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.
43 lines
2.5 KiB
Markdown
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`.
|