generated from coulomb/repo-seed
Refresh agent instruction templates
This commit is contained in:
204
AGENTS.md
204
AGENTS.md
@@ -1,74 +1,162 @@
|
||||
# AGENTS.md
|
||||
# State Hub — Agent Instructions
|
||||
|
||||
This repository is the standalone home for the Custodian State Hub service.
|
||||
## Repo Identity
|
||||
|
||||
## Session Start
|
||||
**Purpose:** Standalone State Hub service repository extracted from the-custodian/state-hub. Owns the FastAPI API, MCP server, dashboard, migrations, consistency tooling, and operational docs.
|
||||
|
||||
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.
|
||||
**Domain:** custodian
|
||||
**Repo slug:** state-hub
|
||||
**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a`
|
||||
**Workplan prefix:** `STATE-WP-`
|
||||
|
||||
If the API is not reachable, continue from local files. The repo must remain
|
||||
usable offline.
|
||||
---
|
||||
|
||||
## Repository Boundary
|
||||
## State Hub Integration
|
||||
|
||||
State Hub owns:
|
||||
The Custodian State Hub tracks work across all domains. Interact via HTTP REST —
|
||||
there is no MCP server for Codex agents.
|
||||
|
||||
- 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
|
||||
| Context | URL |
|
||||
|---------|-----|
|
||||
| Local workstation | `http://127.0.0.1:8000` |
|
||||
| Remote via tunnel | `http://127.0.0.1:18000` |
|
||||
|
||||
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:
|
||||
### Orient at session start
|
||||
|
||||
```bash
|
||||
make install
|
||||
make db
|
||||
make migrate
|
||||
make test
|
||||
make api
|
||||
make mcp-http
|
||||
make dashboard
|
||||
make dashboard-check
|
||||
# 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=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \
|
||||
| python3 -m json.tool
|
||||
|
||||
# Check inbox
|
||||
curl -s "http://127.0.0.1:8000/messages/?to_agent=state-hub&unread_only=true" \
|
||||
| python3 -m json.tool
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```text
|
||||
SHUB-WP-0001
|
||||
Mark a message read:
|
||||
```bash
|
||||
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
|
||||
-H "Content-Type: application/json" -d '{}'
|
||||
```
|
||||
|
||||
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.
|
||||
### Log progress (required at session close)
|
||||
|
||||
## 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": "<uuid>",
|
||||
"task_id": "<uuid>"
|
||||
}'
|
||||
```
|
||||
|
||||
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.
|
||||
Omit `workstream_id` / `task_id` when not applicable.
|
||||
|
||||
### Update task status
|
||||
|
||||
```bash
|
||||
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
|
||||
-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/<task_id>" \
|
||||
-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=state-hub&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=state-hub
|
||||
```
|
||||
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/STATE-WP-NNNN-<slug>.md`
|
||||
|
||||
**Archived location:** finished workplans may move to
|
||||
`workplans/archived/YYMMDD-STATE-WP-NNNN-<slug>.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: STATE-WP-NNNN
|
||||
type: workplan
|
||||
title: "..."
|
||||
domain: custodian
|
||||
repo: state-hub
|
||||
status: proposed | ready | active | blocked | backlog | finished | archived
|
||||
owner: codex
|
||||
topic_slug: ...
|
||||
created: "YYYY-MM-DD"
|
||||
updated: "YYYY-MM-DD"
|
||||
state_hub_workstream_id: "<uuid>" # 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: STATE-WP-NNNN-T01
|
||||
status: todo | in_progress | done | blocked
|
||||
priority: high | medium | low
|
||||
state_hub_task_id: "<uuid>" # 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=state-hub`
|
||||
(or send a message to the hub agent via `POST /messages/`)
|
||||
|
||||
Reference in New Issue
Block a user