Local Identity OICD bootstrap

AGENTS.md

@@ -0,0 +1,87 @@
+# net-kingdom — Codex Instructions
+
+## Custodian State Hub Integration
+
+This project is tracked as the **netkingdom** domain in the Custodian State Hub.
+Hub topic ID: `a6c6e745-bf54-4465-9340-1534a2be493e`
+
+The State Hub runs locally at http://127.0.0.1:8000. The MCP server (`state-hub`)
+exposes tools for reading and writing state without touching the API directly.
+
+### Session Protocol
+
+**On receiving your first message — before writing any response text — orient
+yourself immediately.** Do not greet, do not ask what to do.
+
+**At the start of every session:**
+1. Read `.custodian-brief.md` — offline-safe orientation that works without MCP.
+2. Call `get_state_summary()` for richer cross-domain context (skip if unreachable).
+   If it fails, the API is likely offline:
+   ```
+   cd ~/the-custodian/state-hub && make api
+   ```
+2. Call `get_next_steps()` — surfaces contextual suggestions from recently resolved
+   decisions and cleared workstream dependencies. Act on these before starting new work.
+3. Check whether this domain has any open workstreams in the summary.
+   - **If workstreams exist:** review blocking decisions before starting work.
+   - **If no workstreams exist:** follow the First Session Protocol below.
+
+**During work:**
+- Use `record_decision()` for any decision that affects direction or dependencies.
+- Use `add_progress_event()` for notable events (milestones, blockers, insights).
+- Use `resolve_decision()` to close a decision once the choice is made — this is one
+  of the two sanctioned write operations in the hub.
+
+> **Design boundary:** The State Hub is a *read model*. Two write operations are
+> permanently sanctioned: **Resolving Decisions** and **Suggesting Next Steps** (v0.2).
+> The bootstrap tools (`create_workstream`, `create_task`, `update_task_status`) are
+> only for First Session Protocol. Formal work structure — requirements, workplans,
+> milestones, tasks — belongs in the domain repo, not managed through the hub.
+
+**At the end of every session:**
+- Call `add_progress_event()` with a summary of what was accomplished or decided.
+  Include `topic_id: a6c6e745-bf54-4465-9340-1534a2be493e` and the relevant `workstream_id`.
+
+### First Session Protocol
+
+Triggered when `get_state_summary()` shows **no workstreams** for the `netkingdom` topic.
+This means the project is registered but work has not yet been structured.
+
+**Step 1 — Understand the project (read, don't write)**
+- `canon/projects/netkingdom/project_charter_v0.1.md` — purpose, scope, success criteria
+- `canon/projects/netkingdom/roadmap_v0.1.md` — planned phases
+- Scan the repo root: README, directory structure, any existing code or docs
+
+**Step 2 — Survey in-progress work**
+- Look for TODOs, open branches, half-finished files, or notes
+- Note what is already done vs. what is clearly started but incomplete
+
+**Step 3 — Propose workstreams to Bernd**
+Based on what you found, propose 1–3 workstreams. Each workstream should be:
+- A coherent strand of work lasting weeks to months (not a single task)
+- Named clearly enough that its scope is obvious
+- Anchored to a phase in the roadmap if possible
+
+Present the proposals and **wait for approval before creating anything**.
+
+**Step 4 — Create and populate (after approval)**
+```
+create_workstream(topic_id="a6c6e745-bf54-4465-9340-1534a2be493e", title="...", owner="...", description="...")
+create_task(workstream_id="<id>", title="...", priority="high|medium|low")
+# repeat for each task in the workstream
+```
+Aim for 3–7 tasks per workstream at this stage. Tasks should be concrete and actionable.
+
+**Step 5 — Record the setup**
+```
+add_progress_event(
+    summary="First session: structured netkingdom work into N workstreams, M tasks",
+    event_type="milestone",
+    topic_id="a6c6e745-bf54-4465-9340-1534a2be493e",
+    detail={"workstreams": [...], "tasks_created": M}
+)
+```
+
+### Quick Reference
+
+See `~/the-custodian/state-hub/mcp_server/TOOLS.md` for a compact tool reference.