Files
archie/docs/development/index.md
T
sam c971348a86 docs(development): organise the guides by area
One page per area: frontend UI, agent, workflows, daemon (task lifecycle and
event automation together), State Store, control plane and settings, and
processes and wiring, with merging work kept separate.
2026-09-24 21:05:29 +10:00

43 lines
2.5 KiB
Markdown

# Development guides
Checklists for changing Archie, one page per area. Each names every place a
change must reach, so a feature that works in one layer does not silently stop
at the next. A change that spans areas starts on the page for the area it
begins in, which points to the others. The pages point at the documents that
own the design (`docs/architecture/`, the PRDs, `CLAUDE.md`) rather than
restating them.
| Area | Covers |
| --- | --- |
| [Frontend UI](frontend-ui.md) | Anything under `ui/`, and the dashboard's API routes |
| [Agent](agent.md) | The agent container, its image, profiles, tools and workspace |
| [Workflows](workflows.md) | Workflow definitions and step types |
| [Daemon](daemon.md) | Task statuses, fields and the brief; sources, event types, mappings and bindings |
| [State Store](state-store.md) | Stored fields, tables, RPCs and errors |
| [Control plane and settings](control-plane.md) | Settings in `config.toml` or the dashboard |
| [Processes and wiring](wiring.md) | Where code goes, processes, plugin engines, channels, NATS subjects |
| [Merging work](merging-work.md) | Merging a lane or a branch |
## Every change
- Write the failing test first for anything with logic, branching or a
contract, and check it fails on an assertion, not a compile error.
- Test through the path production uses. A test that sets a value directly on
the consumer proves nothing about the layers that normally deliver it.
- Run `task check` and let its exit status decide the commit:
`task check && git commit ...`. `task test` passes `-short`, which skips the
process and Postgres tests, so run `go test -count=1 ./cmd/... ./internal/...`
too when a change crosses a process or the database.
- Regenerate, never hand-edit, generated output: `task proto:generate`,
`go -C tools tool sqlc generate -f $PWD/internal/infrastructure/postgres/sqlc.yaml`,
`task ui`, `task docs:artifact`. `task proto:check` compares against the git
index, so stage regenerated contracts before running it.
- Stage by path, or read `git status` before `git add -A`. Tests that start
embedded NATS or write logs must use `t.TempDir()`; anything they leave in the
tree gets committed. `task check` also adds linter-tool lines to `go.sum`
(bead 1e37); restore `go.sum` before committing unless you changed a
dependency.
- A change to `docs/prds/` or `docs/architecture/` carries the regenerated
`docs/data/generated/dev-docs.json`, and PRD edits follow
`docs/prds/RULES.md` and pass `task docs:prds`.