Files
archie/docs/development/index.md
T
sam 82bef76caf docs(development): task check writes no module file on a consistent tree
The index page warned that task check adds linter-tool lines to go.sum
(bead 1e37) and told contributors to restore the file before committing.
Measured at HEAD c6623d53 on a copy of go.sum, with the originals restored
after every step, that is not what the gate does: go fix ./..., golangci-lint
fmt, go vet ./..., golangci-lint run ./... (root and tools), go build ./cmd/...,
go test -short ./..., the docsgen and docsite checks and
go -C tools test -mod=readonly ./... left go.mod, go.sum, tools/go.mod and
tools/go.sum byte-identical, with GOFLAGS unset and again with
GOFLAGS=-mod=mod. golangci-lint cannot write its own lines into go.sum either:
it is in no require or tool directive, go mod tidy -diff is empty, and the
committed go.sum carries none of its dependencies.

What the page should say is the rule the measurements show. A stale go.mod or
go.sum fails the gate (missing go.sum entry, updates to go.mod needed) instead
of being repaired, because every Go step runs under the toolchain's readonly
default and the tools steps pass -mod=readonly. Only a global
GOFLAGS=-mod=mod in go env re-enables the repair, which is why the flag is
spelled out on the go -C tools steps; when go.sum does go dirty, go mod tidy
and its own commit are the fix.

The regenerated docs/data/generated/dev-docs.json rides along, as the page
requires: docsite check failed on the edited page first (stale dev-docs.json)
and passes after task docs:artifact.
2026-09-30 11:38:57 +10:00

3.5 KiB

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 Anything under ui/, and the dashboard's API routes
Agent The agent container, its image, profiles, tools and workspace
Workflows Workflow definitions and step types
Daemon Task statuses, fields and the brief; sources, event types, mappings and bindings
State Store Stored fields, tables, RPCs and errors
Control plane and settings Settings in config.toml or the dashboard
Processes and wiring Where code goes, processes, plugin engines, channels, NATS subjects
Merging work 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 writes no module file on a consistent tree, root or tools/ (verified at HEAD with GOFLAGS unset and with -mod=mod): a stale go.mod or go.sum fails it, with missing go.sum entry or updates to go.mod needed, rather than being repaired. Only a global GOFLAGS=-mod=mod in go env re-enables that repair, which is why the go -C tools steps pass -mod=readonly; if go.sum goes dirty, run go mod tidy and commit the result on its own.
  • A change to docs/prds/, docs/architecture/ or docs/development/ carries the regenerated docs/data/generated/dev-docs.json: run task docs:artifact (not task docs:check, which checks contracts only). PRD edits also follow docs/prds/RULES.md and pass task docs:prds.