From b036df7cd8b8e9e87e686a0d85d9ec79a6e4b8d8 Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 8 Jul 2026 15:01:51 +0200 Subject: [PATCH] Track .claude/rules agent instructions (fix gitignore) Allow version-controlled agent rule files under .claude/rules/ while keeping machine-local Claude Code state ignored. Aligns with state-hub gitignore pattern. --- .claude/rules/agents.md | 20 ++++++ .claude/rules/architecture.md | 8 +++ .claude/rules/credential-routing.md | 50 +++++++++++++++ .claude/rules/first-session.md | 42 +++++++++++++ .claude/rules/repo-boundary.md | 8 +++ .claude/rules/repo-identity.md | 5 ++ .claude/rules/session-protocol.md | 92 ++++++++++++++++++++++++++++ .claude/rules/stack-and-commands.md | 19 ++++++ .claude/rules/workplan-convention.md | 55 +++++++++++++++++ .gitignore | 6 +- 10 files changed, 303 insertions(+), 2 deletions(-) create mode 100644 .claude/rules/agents.md create mode 100644 .claude/rules/architecture.md create mode 100644 .claude/rules/credential-routing.md create mode 100644 .claude/rules/first-session.md create mode 100644 .claude/rules/repo-boundary.md create mode 100644 .claude/rules/repo-identity.md create mode 100644 .claude/rules/session-protocol.md create mode 100644 .claude/rules/stack-and-commands.md create mode 100644 .claude/rules/workplan-convention.md diff --git a/.claude/rules/agents.md b/.claude/rules/agents.md new file mode 100644 index 0000000..0e8a5d9 --- /dev/null +++ b/.claude/rules/agents.md @@ -0,0 +1,20 @@ +## Kaizen Agents + +Specialized agent personas available on demand via the state-hub MCP. + +**Discover:** `list_kaizen_agents()` — returns all agents with name, description, category +**Load:** `get_kaizen_agent("tdd-workflow")` — returns full instructions; read and follow them + +Common agents: + +| Agent | Category | When to use | +|-------|----------|-------------| +| `tdd-workflow` | testing | Step-by-step TDD8 workflow for any feature | +| `code-refactoring` | quality | Code quality analysis and safe refactoring | +| `test-maintenance` | testing | Diagnose and fix failing tests | +| `requirements-engineering` | process | Prevent interface/mock mismatches upfront | +| `keepaTodofile` | process | Maintain TODO.md during work | +| `project-management` | process | Track status, determine next steps | +| `datamodel-optimization` | quality | Optimize dataclasses and data structures | + +All 17 agents: call `list_kaizen_agents()` for the full list. diff --git a/.claude/rules/architecture.md b/.claude/rules/architecture.md new file mode 100644 index 0000000..7c2a645 --- /dev/null +++ b/.claude/rules/architecture.md @@ -0,0 +1,8 @@ +## Architecture + + + +## Quick Reference + +`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference diff --git a/.claude/rules/credential-routing.md b/.claude/rules/credential-routing.md new file mode 100644 index 0000000..d91d6c8 --- /dev/null +++ b/.claude/rules/credential-routing.md @@ -0,0 +1,50 @@ +# Credential and access routing + +**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect** +for inference. Run this check **before** requesting secrets, API keys, SSH access, +login tokens, or database passwords — in any repo, not only `ops-warden`. + +ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every +other credential need belongs to another subsystem. **Do not** message +`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key. + +### Lookup (do this first) + +```bash +warden route find "" --json +warden route show --json +``` + +Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`). + +| Agent runtime | How to orient | +| --- | --- | +| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=marki-docx` is for coordination, not secret vending | +| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workplans; **still** use `warden route` for credential ownership | +| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` | + +### Quick routing table + +| I need… | Owner | ops-warden executes? | +| --- | --- | --- | +| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` | +| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only | +| Login / OIDC / MFA | key-cape / Keycloak | No — route only | +| Authorization decision | flex-auth | No — route only | +| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` | +| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only | + +### Anti-patterns (do not do these) + +- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc. +- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist +- Pasting secrets into Git, State Hub, workplans, logs, or chat + +### Other capabilities (reuse-surface) + +Non-credential capabilities are usually discovered through **reuse-surface** federation +(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in +every repo's agent instructions because it is high-frequency, high-risk, and easy to +get wrong. + +**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml` \ No newline at end of file diff --git a/.claude/rules/first-session.md b/.claude/rules/first-session.md new file mode 100644 index 0000000..661dd6f --- /dev/null +++ b/.claude/rules/first-session.md @@ -0,0 +1,42 @@ +## First Session Protocol + +Triggered when `get_domain_summary("communication")` shows **no workplans**. +The project is registered but work has not yet been structured. + +**Step 1 — Read, don't write** +- `~/the-custodian/canon/projects/communication/project_charter_v0.1.md` — purpose, scope +- `~/the-custodian/canon/projects/communication/roadmap_v0.1.md` — planned phases +- Scan repo root: README, directory structure, existing code or docs + +**Step 2 — Survey in-progress work** +Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete. + +**Step 3 — Propose workplans to Bernd** +Propose 1–3 workplans — each a coherent strand, weeks to months, anchored to a +roadmap phase. **Wait for approval before creating.** + +**Step 4 — Write the workplan file; fix-consistency registers it (ADR-001)** +``` +workplans/MRKD-WP-NNNN-.md ← write this, commit it +``` +Then register by running the consistency check — do **not** call +`create_workplan`/`create_task` yourself; manual registration duplicates what +C-06 creates from the file: +```bash +statehub fix-consistency --repo marki-docx +``` +C-06 creates the hub workplan + tasks and writes `state_hub_workstream_id` +(legacy frontmatter name — holds the workplan UUID) and `state_hub_task_id` +back into the file. + +**Step 5 — Record the setup** +``` +add_progress_event( + summary="First session: structured communication into N workplans, M tasks", + event_type="milestone", + topic_id="36c7421b-c537-4723-bf75-42a3ebc6a1dc", + detail={"workplans": [...], "tasks_created": M} +) +``` + + diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md new file mode 100644 index 0000000..d169383 --- /dev/null +++ b/.claude/rules/repo-boundary.md @@ -0,0 +1,8 @@ +## Repo boundary + +This repo owns **marki-docx** only. It does not own: + + diff --git a/.claude/rules/repo-identity.md b/.claude/rules/repo-identity.md new file mode 100644 index 0000000..de8add5 --- /dev/null +++ b/.claude/rules/repo-identity.md @@ -0,0 +1,5 @@ +**Purpose:** Markdown ↔ DOCX round-trip editing system. CLI + REST + MCP interfaces for controlled editorial workflows where Markdown is canonical and Word is the editorial projection. + +**Domain:** communication +**Repo slug:** marki-docx +**Topic ID:** 36c7421b-c537-4723-bf75-42a3ebc6a1dc diff --git a/.claude/rules/session-protocol.md b/.claude/rules/session-protocol.md new file mode 100644 index 0000000..037abcb --- /dev/null +++ b/.claude/rules/session-protocol.md @@ -0,0 +1,92 @@ +## Session Protocol + +Dev Hub (State Hub API): http://127.0.0.1:8000 +MCP server name in `~/.claude.json`: `dev-hub` + +**Step 1 — Orient** + +Read the offline-safe brief first — it works without a live hub connection: +```bash +cat .custodian-brief.md +``` +Then call the MCP tool for richer cross-domain context when MCP tools are exposed: +``` +get_domain_summary("communication") +``` +If MCP tools are unavailable in the current agent session, use the REST API: +```bash +curl -s "http://127.0.0.1:8000/state/summary" | python3 -m json.tool +``` +If the hub is offline: `cd ~/state-hub && make api` + +**Step 2 — Check inbox** +With MCP tools: +``` +get_messages(to_agent="marki-docx", unread_only=True) +``` +Mark read with `mark_message_read(message_id)`. Reply or act on coordination +requests before proceeding. + +Without MCP tools: +```bash +curl -s "http://127.0.0.1:8000/messages/?to_agent=marki-docx&unread_only=true" \ + | python3 -m json.tool +curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ + -H "Content-Type: application/json" -d '{}' +``` + +**Step 3 — Scan workplans** +```bash +ls workplans/ +``` +For each file with `status: ready`, `active`, or `blocked`, note pending +`wait`/`todo`/`progress` tasks. + +**Step 4 — Present brief** + +1. **Active workplans** for `communication` — title, task counts, blocking decisions +2. **Pending tasks** from `workplans/` + any `[repo:marki-docx]` hub tasks +3. **Goal guidance** — if `goal_guidance` in summary: + - `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"* + - `alignment_warnings`: flag if active work is not aligned with current goal +4. **Suggested next action** — highest-priority open item +5. **SBOM status** — flag if `last_sbom_at` is unset for this repo + +If no workplans: follow First Session Protocol (`first-session.md`). + +**During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()` + +> State Hub is a *read model*. **Never register workplans or tasks by hand** +> (`create_workplan`, `create_task`) — write the workplan file in `workplans/` +> and run `fix-consistency`; C-06 registers the workplan and tasks and writes +> IDs back into the file. Manual registration creates duplicates when +> fix-consistency runs. Work structure belongs in repo files (ADR-001). +> +> Legacy: `create_workstream` and `/workstreams/` remain as metered aliases — +> see `workplan-convention.md` (compatibility footnote). + +**Session close:** +With MCP tools: +``` +add_progress_event(summary="...", topic_id="36c7421b-c537-4723-bf75-42a3ebc6a1dc", workplan_id="") +``` +Without MCP tools: +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{"topic_id":"36c7421b-c537-4723-bf75-42a3ebc6a1dc","workplan_id":"","event_type":"note","summary":"what changed","author":"codex"}' +``` +If workplan files were modified, ensure the local copy is up to date first, +then sync from the repo checkout: +```bash +git pull --ff-only +statehub fix-consistency +``` +For repos where implementation runs on a remote machine (e.g. CoulombCore), +use the pull-before-fix mode from any shell with the State Hub CLI: +```bash +statehub fix-consistency --repo marki-docx --remote +``` +**C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback +will sync the file to match DB. **C-16** (repo behind remote) blocks all writes +until you pull — intentional to prevent clobbering remote progress. diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md new file mode 100644 index 0000000..dc53ac6 --- /dev/null +++ b/.claude/rules/stack-and-commands.md @@ -0,0 +1,19 @@ +## Stack + + +- **Language:** +- **Key deps:** + +## Dev Commands + +```bash +# TODO: Fill in the standard commands for this repo + +# Install dependencies + +# Run tests + +# Lint / type check + +# Build / package (if applicable) +``` diff --git a/.claude/rules/workplan-convention.md b/.claude/rules/workplan-convention.md new file mode 100644 index 0000000..b7eec0c --- /dev/null +++ b/.claude/rules/workplan-convention.md @@ -0,0 +1,55 @@ +## Workplan Convention (ADR-001) + +File location: `workplans/MRKD-WP-NNNN-.md` +ID prefix: `MRKD-WP-` + +Work items originate as files in this repo **before** being registered in the hub. + +Canonical workplan frontmatter statuses are: +`proposed`, `ready`, `active`, `blocked`, `backlog`, `finished`, `archived`. +Use `proposed` for a newly drafted plan, `ready` after review against current +repo state, and `finished` when implementation is complete. `stalled` and +`needs_review` are derived health labels, not stored statuses. + +Closed workplans may be moved to `workplans/archived/` with a completion-date +prefix: `YYMMDD-MRKD-WP-NNNN-.md`. The frontmatter id remains +unchanged; the prefix is only for quick visual reference. + +Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**: +`workplans/ADHOC-YYYY-MM-DD.md`, workplan slug `adhoc-YYYY-MM-DD`, and task ids +`ADHOC-YYYY-MM-DD-T01`, `T02`, etc. Use adhocs only for low-risk work completed +directly. Promote anything requiring analysis, design, approval, dependencies, or +multiple planned phases into a normal workplan. + +Ecosystem todos from other agents arrive as `[repo:marki-docx]` hub tasks — +visible at session start. Pick one up by creating the workplan file, committing, +and running `statehub fix-consistency` — C-06 registers the workplan in the hub. +Never register by hand with `create_workplan` (legacy MCP alias: `create_workstream`). + +Task blocks use this shape: + +```task +id: MRKD-WP-NNNN-T01 +status: wait | todo | progress | done | cancel +priority: high | medium | low +state_hub_task_id: "" # written by fix-consistency — do not edit +``` + +Status progression is `todo` → `progress` → `done`; use `wait` for waiting or +blocked work and `cancel` for stopped work. + +Workplan frontmatter carries `state_hub_workstream_id` — a legacy field name +kept for compatibility; it holds the hub workplan UUID and is written by +fix-consistency. Do not edit or rename it. + +### Legacy terminology (compatibility footnote) + +**Workplan** is the fleet term — see +`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`. +**Workstream** is legacy only: some API routes (`/workstreams/`), params +(`workstream_id`), MCP aliases (`create_workstream`), and the frontmatter field +above remain until `STATE-WP-0069` retires them via legacy-meter. Treat those +identifiers as workplan IDs. Prefer `GET /workplans/` and `workplan_id` in new +examples and scripts. + + diff --git a/.gitignore b/.gitignore index 5dd1cb4..306f17d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,7 @@ -# Claude Code local state -.claude/ +# Claude Code local state (track shared rules; ignore machine-specific files) +.claude/* +!.claude/rules/ +!.claude/rules/*.md # Ralph workplan plugin (local tooling, not project source) ralph-workplan/