diff --git a/.claude/rules/architecture.md b/.claude/rules/architecture.md index 4f6c74c..7c2a645 100644 --- a/.claude/rules/architecture.md +++ b/.claude/rules/architecture.md @@ -5,4 +5,4 @@ ## Quick Reference -`~/the-custodian/state-hub/mcp_server/TOOLS.md` — MCP tool reference +`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference diff --git a/.claude/rules/first-session.md b/.claude/rules/first-session.md index 2513b6f..94b9dc7 100644 --- a/.claude/rules/first-session.md +++ b/.claude/rules/first-session.md @@ -21,7 +21,7 @@ workplans/ihp-railiance-probe-WP-NNNN-.md ← write this first ``` Then register in the hub: ``` -create_workstream(topic_id="(none)", title="...", owner="...", description="...") +create_workstream(topic_id="595afc64-bd28-47bf-aafb-ba230b28371b", title="...", owner="...", description="...") create_task(workstream_id="", title="...", priority="high|medium|low") ``` @@ -30,7 +30,7 @@ create_task(workstream_id="", title="...", priority="high|medium|low") add_progress_event( summary="First session: structured stack into N workstreams, M tasks", event_type="milestone", - topic_id="(none)", + topic_id="595afc64-bd28-47bf-aafb-ba230b28371b", detail={"workstreams": [...], "tasks_created": M} ) ``` diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md index f0ab07a..f92d3d8 100644 --- a/.claude/rules/repo-boundary.md +++ b/.claude/rules/repo-boundary.md @@ -4,5 +4,5 @@ This repo owns **ihp-railiance-probe** only. It does not own: diff --git a/.claude/rules/repo-identity.md b/.claude/rules/repo-identity.md index 5dcb307..5c7f5cd 100644 --- a/.claude/rules/repo-identity.md +++ b/.claude/rules/repo-identity.md @@ -1,6 +1,5 @@ -**Purpose:** ihp-railiance-probe — (fill in purpose) +**Purpose:** ihp-railiance-probe - (fill in purpose) **Domain:** stack **Repo slug:** ihp-railiance-probe -**Topic slug:** stack **Topic ID:** 595afc64-bd28-47bf-aafb-ba230b28371b diff --git a/.claude/rules/session-protocol.md b/.claude/rules/session-protocol.md index 5c3dd6d..5569fe2 100644 --- a/.claude/rules/session-protocol.md +++ b/.claude/rules/session-protocol.md @@ -8,24 +8,38 @@ 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 (skip if unreachable): +Then call the MCP tool for richer cross-domain context when MCP tools are exposed: ``` get_domain_summary("stack") ``` -If the hub is offline: `cd ~/the-custodian/state-hub && make api` +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="ihp-railiance-probe", 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=ihp-railiance-probe&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: active`, note pending `todo`/`in_progress` tasks. +For each file with `status: ready`, `active`, or `blocked`, note pending +`todo`/`in_progress` tasks. **Step 4 — Present brief** @@ -45,18 +59,25 @@ If no workstreams: follow First Session Protocol (`first-session.md`). > are First Session Protocol only. Work structure belongs in repo files (ADR-001). **Session close:** +With MCP tools: ``` -add_progress_event(summary="...", topic_id="(none)", workstream_id="") +add_progress_event(summary="...", topic_id="595afc64-bd28-47bf-aafb-ba230b28371b", 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":"595afc64-bd28-47bf-aafb-ba230b28371b","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 ~/the-custodian/state-hub && make fix-consistency REPO=ihp-railiance-probe +cd ~/state-hub && make fix-consistency REPO=ihp-railiance-probe ``` For repos where implementation runs on a remote machine (e.g. CoulombCore), use the combined target which pulls before fixing: ```bash -cd ~/the-custodian/state-hub && make fix-consistency-remote REPO=ihp-railiance-probe +cd ~/state-hub && make fix-consistency-remote REPO=ihp-railiance-probe ``` **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 diff --git a/.claude/rules/workplan-convention.md b/.claude/rules/workplan-convention.md index 12a60e3..8c1e10d 100644 --- a/.claude/rules/workplan-convention.md +++ b/.claude/rules/workplan-convention.md @@ -5,6 +5,12 @@ ID prefix: `IHP-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-ihp-railiance-probe-WP-NNNN-.md`. The frontmatter id remains unchanged; the prefix is only for quick visual reference. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..14e1d70 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,162 @@ +# ihp-railiance-probe — Agent Instructions + +## Repo Identity + +**Purpose:** ihp-railiance-probe - (fill in purpose) + +**Domain:** stack +**Repo slug:** ihp-railiance-probe +**Topic ID:** `595afc64-bd28-47bf-aafb-ba230b28371b` +**Workplan prefix:** `IHP-WP-` + +--- + +## State Hub Integration + +The Custodian State Hub tracks work across all domains. Interact via HTTP REST — +there is no MCP server 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 +# 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=595afc64-bd28-47bf-aafb-ba230b28371b&status=active" \ + | python3 -m json.tool + +# Check inbox +curl -s "http://127.0.0.1:8000/messages/?to_agent=ihp-railiance-probe&unread_only=true" \ + | python3 -m json.tool +``` + +Mark a message read: +```bash +curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ + -H "Content-Type: application/json" -d '{}' +``` + +### Log progress (required at session close) + +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{ + "summary": "what was done", + "event_type": "note", + "author": "codex", + "workstream_id": "", + "task_id": "" + }' +``` + +Omit `workstream_id` / `task_id` when not applicable. + +### 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"}' +``` + +--- + +## Session Protocol + +**Start:** +1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe) +2. Check inbox: `GET /messages/?to_agent=ihp-railiance-probe&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 statuses in workplan files as tasks progress +- Record significant decisions via `POST /decisions/` + +**Close:** +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=ihp-railiance-probe + ``` + 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 that rebuilds from files. + +**File location:** `workplans/IHP-WP-NNNN-.md` + +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-IHP-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: IHP-WP-NNNN +type: workplan +title: "..." +domain: stack +repo: ihp-railiance-probe +status: proposed | ready | active | blocked | backlog | finished | archived +owner: codex +topic_slug: ... +created: "YYYY-MM-DD" +updated: "YYYY-MM-DD" +state_hub_workstream_id: "" # written by fix-consistency — do not edit +--- +``` + +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. + +**Task block format** (one per `##` section): + +``` +## Task Title + +` ` `task +id: IHP-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 text. +``` + +Status progression: `todo` → `in_progress` → `done` (or `blocked`) + +To create a new workplan: +1. Write the file following the format above +2. Notify the custodian operator to run `make fix-consistency REPO=ihp-railiance-probe` + (or send a message to the hub agent via `POST /messages/`)