net-kingdom/AGENTS.md

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
   

3. Call get_next_steps() — surfaces contextual suggestions from recently resolved decisions and cleared workstream dependencies. Act on these before starting new work.
4. 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.