From fd7f25866a94897acfdefaafc83a9d8336c1081b Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 18 May 2026 16:55:53 +0200 Subject: [PATCH] Refresh agent instruction files --- .claude/rules/agents.md | 20 ++++ .claude/rules/architecture.md | 8 ++ .claude/rules/first-session.md | 38 ++++++ .claude/rules/repo-boundary.md | 8 ++ .claude/rules/repo-identity.md | 5 + .claude/rules/session-protocol.md | 84 +++++++++++++ .claude/rules/stack-and-commands.md | 19 +++ .claude/rules/workplan-convention.md | 28 +++++ AGENTS.md | 172 ++++++++++++--------------- CLAUDE.md | 97 ++------------- 10 files changed, 299 insertions(+), 180 deletions(-) create mode 100644 .claude/rules/agents.md create mode 100644 .claude/rules/architecture.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/first-session.md b/.claude/rules/first-session.md new file mode 100644 index 0000000..6416e2a --- /dev/null +++ b/.claude/rules/first-session.md @@ -0,0 +1,38 @@ +## First Session Protocol + +Triggered when `get_domain_summary("capabilities")` shows **no workstreams**. +The project is registered but work has not yet been structured. + +**Step 1 — Read, don't write** +- `~/the-custodian/canon/projects/capabilities/project_charter_v0.1.md` — purpose, scope +- `~/the-custodian/canon/projects/capabilities/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 workstreams to Bernd** +Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to a +roadmap phase. **Wait for approval before creating.** + +**Step 4 — Create workplan file first, then DB record (ADR-001)** +``` +workplans/repo-scoping-WP-NNNN-.md ← write this first +``` +Then register in the hub: +``` +create_workstream(topic_id="64418556-3206-457a-ba29-6884b5b12cf3", title="...", owner="...", description="...") +create_task(workstream_id="", title="...", priority="high|medium|low") +``` + +**Step 5 — Record the setup** +``` +add_progress_event( + summary="First session: structured capabilities into N workstreams, M tasks", + event_type="milestone", + topic_id="64418556-3206-457a-ba29-6884b5b12cf3", + detail={"workstreams": [...], "tasks_created": M} +) +``` + + diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md new file mode 100644 index 0000000..c5b1e17 --- /dev/null +++ b/.claude/rules/repo-boundary.md @@ -0,0 +1,8 @@ +## Repo boundary + +This repo owns **repo-scoping** 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..501b3b6 --- /dev/null +++ b/.claude/rules/repo-identity.md @@ -0,0 +1,5 @@ +**Purpose:** repo-scoping - (fill in purpose) + +**Domain:** capabilities +**Repo slug:** repo-scoping +**Topic ID:** 64418556-3206-457a-ba29-6884b5b12cf3 diff --git a/.claude/rules/session-protocol.md b/.claude/rules/session-protocol.md new file mode 100644 index 0000000..4fee6b6 --- /dev/null +++ b/.claude/rules/session-protocol.md @@ -0,0 +1,84 @@ +## Session Protocol + +State Hub: http://127.0.0.1:8000 + +**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("capabilities") +``` +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="repo-scoping", 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=repo-scoping&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 +`todo`/`in_progress` tasks. + +**Step 4 — Present brief** + +1. **Active workstreams** for `capabilities` — title, task counts, blocking decisions +2. **Pending tasks** from `workplans/` + any `[repo:repo-scoping]` 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 workstreams: follow First Session Protocol (`first-session.md`). + +**During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()` + +> State Hub is a *read model*. Bootstrap tools (`create_workstream`, `create_task`) +> are First Session Protocol only. Work structure belongs in repo files (ADR-001). + +**Session close:** +With MCP tools: +``` +add_progress_event(summary="...", topic_id="64418556-3206-457a-ba29-6884b5b12cf3", workstream_id="") +``` +Without MCP tools: +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{"topic_id":"64418556-3206-457a-ba29-6884b5b12cf3","workstream_id":"","event_type":"note","summary":"what changed","author":"codex"}' +``` +If workplan files were modified, ensure the local copy is up to date first: +```bash +git -C pull --ff-only +cd ~/state-hub && make fix-consistency REPO=repo-scoping +``` +For repos where implementation runs on a remote machine (e.g. CoulombCore), +use the combined target which pulls before fixing: +```bash +cd ~/state-hub && make fix-consistency-remote REPO=repo-scoping +``` +**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..b9bcc72 --- /dev/null +++ b/.claude/rules/workplan-convention.md @@ -0,0 +1,28 @@ +## Workplan Convention (ADR-001) + +File location: `workplans/repo-scoping-WP-NNNN-.md` +ID prefix: `REPO-WP` + +Work items originate as files in this repo **before** being registered in the hub. + +Canonical workplan/workstream 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-repo-scoping-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`, workstream 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:repo-scoping]` hub tasks — +visible at session start. Pick one up by creating the workplan file, then registering +the workstream. + + diff --git a/AGENTS.md b/AGENTS.md index c41d6cf..ab293c4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,46 +2,44 @@ ## Repo Identity -**Purpose:** Repository Scoping — turns Git repositories into reviewable, -source-linked maps of `Ability → Capability → Feature → Evidence`. Deterministic -scanners establish observed facts; LLM-assisted extractors propose interpreted -claims; humans or trusted agents approve registry truth. +**Purpose:** repo-scoping - (fill in purpose) -**Domain:** capabilities -**Repo slug:** repo-scoping -**Topic ID:** `64418556-3206-457a-ba29-6884b5b12cf3` -**Workplan prefix:** `RREG-WP-` +**Domain:** capabilities +**Repo slug:** repo-scoping +**Topic ID:** `64418556-3206-457a-ba29-6884b5b12cf3` +**Workplan prefix:** `REPO-WP-` --- ## State Hub Integration -The Custodian State Hub tracks work across all domains. It runs at -`http://127.0.0.1:8000` (local) or `http://127.0.0.1:18000` when accessed from -a remote machine via tunnel. +The Custodian State Hub tracks work across all domains. Interact via HTTP REST — +there is no MCP server for Codex agents. -Interact via HTTP — there is no MCP integration for Codex agents. +| Context | URL | +|---------|-----| +| Local workstation | `http://127.0.0.1:8000` | +| Remote via tunnel | `http://127.0.0.1:18000` | ### Orient at session start ```bash -# Domain workstreams +# Offline brief — works without hub connection +cat .custodian-brief.md + +# Active workstreams for this domain curl -s "http://127.0.0.1:8000/workstreams/?topic_id=64418556-3206-457a-ba29-6884b5b12cf3&status=active" \ | python3 -m json.tool -# Open tasks for this repo (once workstreams are registered) -curl -s "http://127.0.0.1:8000/tasks/?status=todo" | python3 -m json.tool - # Check inbox curl -s "http://127.0.0.1:8000/messages/?to_agent=repo-scoping&unread_only=true" \ | python3 -m json.tool ``` -Also read `workplans/` directly — the files are the source of truth: - +Mark a message read: ```bash -ls workplans/ -grep -h "^status:" workplans/RREG-WP-*.md +curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ + -H "Content-Type: application/json" -d '{}' ``` ### Log progress (required at session close) @@ -50,27 +48,31 @@ grep -h "^status:" workplans/RREG-WP-*.md curl -s -X POST http://127.0.0.1:8000/progress/ \ -H "Content-Type: application/json" \ -d '{ - "summary": "describe what was done", + "summary": "what was done", "event_type": "note", - "author": "codex" + "author": "codex", + "workstream_id": "", + "task_id": "" }' ``` -Include `"workstream_id": ""` and `"task_id": ""` when known. +Omit `workstream_id` / `task_id` when not applicable. -### Mark a message read - -```bash -curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ - -H "Content-Type: application/json" -d '{}' -``` - -### Update task status (after workstreams are synced) +### Update task status ```bash curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ -H "Content-Type: application/json" \ -d '{"status": "in_progress"}' +# values: todo | in_progress | done | blocked +``` + +### Flag a task for human review + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"needs_human": true, "intervention_note": "reason"}' ``` --- @@ -78,99 +80,83 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ ## Session Protocol **Start:** -1. `ls workplans/` — note active workplans and their open tasks -2. Check inbox via `GET /messages/?to_agent=repo-scoping&unread_only=true` -3. Check for human-flagged tasks: `GET /tasks/?needs_human=true` +1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe) +2. Check inbox: `GET /messages/?to_agent=repo-scoping&unread_only=true`; mark read +3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks +4. Check blocked tasks: `GET /tasks/?needs_human=true` **During work:** -- Update task status in the workplan file as tasks progress -- For significant decisions, record them: `POST /decisions/` +- Update task statuses in workplan files as tasks progress +- Record significant decisions via `POST /decisions/` **Close:** -1. Update task statuses in workplan files to match progress -2. Call `POST /progress/` with a summary of what was done -3. If workplan files changed, sync them to the hub DB: - -```bash -curl -s -X POST "http://127.0.0.1:8000/repos/repo-scoping/sync" | python3 -m json.tool -``` - -This runs the ADR-001 consistency check with `--fix` and returns a JSON report. -A `"result": "warn"` with only C-17 is normal (unpushed commits); no action needed. -A `"result": "fail"` means file/DB drift that could not be auto-fixed — read the issues list. +1. Update workplan file task statuses to reflect progress +2. Log: `POST /progress/` with a summary of what changed +3. Note for the custodian operator: after workplan file changes, run from + `~/state-hub`: + ```bash + make fix-consistency REPO=repo-scoping + ``` + This syncs task status from files into the hub DB. --- ## Workplan Convention (ADR-001) -Work items originate as files in this repo, not in the hub. The hub is a -read/cache/index layer. +Work items originate as files in this repo — not in the hub. The hub is a +read/cache/index layer that rebuilds from files. -**File location:** `workplans/RREG-WP-NNNN-.md` +**File location:** `workplans/REPO-WP-NNNN-.md` + +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-REPO-WP-NNNN-.md`. The `YYMMDD` prefix is +the completion/archive date; the frontmatter `id` does not change. + +**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use +`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use +this only for low-risk work completed directly; create a normal workplan for +anything needing analysis, design, approval, dependencies, or multiple phases. **Frontmatter:** ```yaml --- -id: RREG-WP-NNNN +id: REPO-WP-NNNN type: workplan title: "..." domain: capabilities repo: repo-scoping -status: active | done +status: proposed | ready | active | blocked | backlog | finished | archived owner: codex -topic_slug: foerster-capabilities +topic_slug: ... created: "YYYY-MM-DD" updated: "YYYY-MM-DD" -state_hub_workstream_id: "" # populated by fix-consistency +state_hub_workstream_id: "" # written by fix-consistency — do not edit --- ``` -**Task blocks** (one per `##` section): +Use `proposed` for a new draft, `ready` after review against current repo +state, and `finished` after implementation. `stalled` and `needs_review` are +derived health labels, not frontmatter statuses. -```markdown +**Task block format** (one per `##` section): + +``` ## Task Title -\`\`\`task -id: RREG-WP-NNNN-T01 +` ` `task +id: REPO-WP-NNNN-T01 status: todo | in_progress | done | blocked priority: high | medium | low -\`\`\` +state_hub_task_id: "" # written by fix-consistency — do not edit +` ` ` -Task description. +Task description text. ``` -**Status values:** `todo` → `in_progress` → `done` (or `blocked`) +Status progression: `todo` → `in_progress` → `done` (or `blocked`) ---- - -## Stack and Commands - -**Runtime:** Python 3.x, FastAPI, SQLite (dev) / PostgreSQL (prod) -**Package manager:** pip / uv - -```bash -# Install -pip install -e ".[dev]" - -# Run dev server -uvicorn repo_scoping.web_api.app:app --reload - -# Run tests -pytest tests/ -pytest tests/ -k "e2e" - -# Check API health -curl http://127.0.0.1:8001/health -``` - ---- - -## Repo Boundary - -This repo owns: repository ingestion, deterministic scanning, LLM-assisted candidate -extraction, review/approval workflow, registry query and search. - -It does NOT own: the Custodian State Hub, other domain repos, deployment infrastructure. - -Coordination with other domains goes through the State Hub message inbox. +To create a new workplan: +1. Write the file following the format above +2. Notify the custodian operator to run `make fix-consistency REPO=repo-scoping` + (or send a message to the hub agent via `POST /messages/`) diff --git a/CLAUDE.md b/CLAUDE.md index f54d6be..5c3469e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,88 +1,11 @@ -# CLAUDE.md +# repo-scoping — Claude Code Instructions -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Commands - -```bash -# Install -pip install -e ".[dev]" - -# Run dev server (port 8001) -uvicorn repo_scoping.web_api.app:app --reload --port 8001 - -# Run tests -pytest -pytest -k "test_scanner" # filter by keyword -pytest tests/test_web_api.py # single file - -# Health check -curl http://127.0.0.1:8001/health -``` - -## Architecture - -The service maps Git repositories to reviewable scope maps using a fixed hierarchy: - -``` -Scope → Ability → Capability → Feature → Evidence → ObservedFact -``` - -**Data flow for an analysis run:** - -1. `POST /repos/{id}/analysis-runs` triggers the pipeline in `RegistryService.run_analysis()` -2. `GitIngestionService` clones or resolves the repo path -3. `RepositoryMetadataExtractor` reads pyproject.toml / package.json / README -4. `DeterministicScanner` produces `ObservedFact` objects (files, languages, manifests, APIs, etc.) -5. `ContentExtractor` chunks files into searchable segments -6. `CandidateGraphGenerator` builds a draft ability→capability→feature→evidence tree from facts -7. Optionally, `LLMCandidateExtractor` proposes additional candidates (requires `REPO_SCOPING_LLM_ENABLED=true`) -8. Candidates are stored; humans or agents review them via `POST .../candidate-graph/approve` -9. Approved characteristics feed `ScopeGenerator` to produce `SCOPE.md` - -**Key source locations:** - -| Component | Path | -|-----------|------| -| FastAPI routes + DI | `src/repo_scoping/web_api/app.py` | -| Orchestration | `src/repo_scoping/core/service.py` | -| Frozen dataclasses | `src/repo_scoping/core/models.py` | -| Deterministic scanner | `src/repo_scoping/repo_scanning/scanner.py` | -| Candidate graph builder | `src/repo_scoping/candidate_graph/generator.py` | -| SQLite store | `src/repo_scoping/storage/sqlite.py` | -| Schema migration | `migrations/0001_initial.sql` | - -**Storage:** SQLite at `var/repo-scoping.sqlite3` (auto-created). Schema migrations run at startup. Dynamic columns are added to support evidence relationships, classification, and expectation gaps. - -**LLM extraction** is optional and disabled by default. Enable with `REPO_SCOPING_LLM_ENABLED=true` plus `REPO_SCOPING_LLM_PROVIDER` and `REPO_SCOPING_LLM_MODEL`. The `llm-connect` sibling package provides the adapter abstraction. - -**Semantic search** uses `HashingEmbeddingProvider` by default — deterministic, no external service required. - -## Environment Variables - -| Variable | Default | Purpose | -|----------|---------|---------| -| `REPO_SCOPING_DATABASE_PATH` | `var/repo-scoping.sqlite3` | SQLite file | -| `REPO_SCOPING_CHECKOUT_ROOT` | `var/checkouts` | Git clone cache | -| `REPO_SCOPING_LLM_ENABLED` | `true` | Enable LLM extraction | -| `REPO_SCOPING_LLM_PROVIDER` | — | e.g. `gemini`, `anthropic` | -| `REPO_SCOPING_LLM_MODEL` | — | e.g. `gemini-2.5-flash` | -| `REPO_SCOPING_STATE_HUB_BASE_URL` | `http://127.0.0.1:8000` | State Hub for coordination | - -## State Hub & Workplans - -Active work is tracked in `workplans/RREG-WP-*.md` — these files are the source of truth (ADR-001). The Custodian State Hub caches this state; workplan files take precedence. - -Session protocol (see `AGENTS.md` for full curl examples): -- **Start:** check `workplans/` status headers and State Hub inbox -- **Close:** update task statuses in workplan files, then `POST /progress/` and sync via `POST /repos/repo-scoping/sync` - -Workplan sync warns on C-17 (unpushed commits) — that's normal. A `"result": "fail"` needs investigation. - -## Docs - -Design decisions and terminology live in `docs/`: -- `docs/terminology.md` — characteristic model definitions -- `docs/scope-md-spec.md` — SCOPE.md format -- `docs/characteristic-evidence-model.md` — evidence target kinds -- `docs/classification-strategy.md` — how characteristics are classified +@SCOPE.md +@.claude/rules/repo-identity.md +@.claude/rules/session-protocol.md +@.claude/rules/first-session.md +@.claude/rules/workplan-convention.md +@.claude/rules/stack-and-commands.md +@.claude/rules/architecture.md +@.claude/rules/repo-boundary.md +@.claude/rules/agents.md