state-hub/AGENTS.md

AGENTS.md

This repository is the standalone home for the Custodian State Hub service.

Session Start

1. Read this file and SCOPE.md.
2. Read .custodian-brief.md if present.
3. If the State Hub API is reachable, query the local hub for orientation:
   • GET http://127.0.0.1:8000/state/summary
   • GET http://127.0.0.1:8000/messages/?to_agent=hub&unread_only=true
4. Mark relevant inbox messages read after acting on them.
5. Check git status --short before editing.

If the API is not reachable, continue from local files. The repo must remain usable offline.

Repository Boundary

State Hub owns:

• FastAPI app, models, schemas, routers, migrations
• MCP server and tool reference
• Observable dashboard
• consistency, registration, SBOM, token, image, and repo-sync scripts
• task-flow engine and flow definitions
• State Hub operational docs, tests, policies, prompts, and infra

The Custodian governance repo owns:

• canon, constitution, values, memory, and broad cross-domain governance
• bridge workplans that coordinate extraction from the old embedded layout

Do not write governance canon directly from this repo.

Build And Test

After the implementation move, the expected command surface is:

make install
make db
make migrate
make test
make api
make mcp-http
make dashboard
make dashboard-check

When API routers, models, migrations, or consistency logic change, run the relevant tests before closing the session. Prefer make test when the database test prerequisites are available. make test includes an Observable dashboard build smoke check so dashboard startup regressions are not missed.

Workplans

Use workplans/ for State Hub-local workplans. New workplans should use:

SHUB-WP-0001

For migrated Custodian-hosted plans, preserve existing state_hub_workstream_id and task IDs when safe. Never call create_workstream() or create_task() manually for a file-backed workplan before the file exists in this repo.

Session Close

1. Add a progress event through State Hub if the API is reachable.
2. Run consistency sync for this repo once it is registered.
3. Record any decisions that change repo ownership, state model, API contracts, or deployment topology.
4. Leave the worktree clear or explicitly report remaining uncommitted changes.