generated from coulomb/repo-seed
73 lines
2.1 KiB
Markdown
73 lines
2.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
make install
|
|
make db
|
|
make migrate
|
|
make test
|
|
make api
|
|
make mcp-http
|
|
make dashboard
|
|
```
|
|
|
|
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.
|
|
|
|
## Workplans
|
|
|
|
Use `workplans/` for State Hub-local workplans. New workplans should use:
|
|
|
|
```text
|
|
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.
|