# AGENTS.md Rules for any agent working in this repository. Short on purpose: every rule here changes a decision. If a rule stops changing decisions, delete it. ## What this is **archie-core** is event-driven agentic automation. An event (an issue, PR, webhook, schedule, chat message) is matched to a workflow, the workflow runs an agent or tool in an isolated container, and the result lands somewhere for review or action. A repository is an optional input to a workflow, not the point of the product. A forge is one of many inputs or outputs; core code never assumes one. The goal until 1 December is a production-ready archie-core, including the features the maintainer is still adding. Speak up when a request competes with something more urgent: a bug that loses work, a failure that shows nothing, a security gap, a broken setup path. Give the trade-off in a sentence or two and suggest whether the request belongs in the backlog. Don't hold work back on your own judgement. ## Services and layout Each service is a gRPC contract in `proto//v1`, generated into `internal/contracts//v1`, and one binary in `cmd/` that parses flags and calls its composition root in `internal/app/`. | Binary | Serves | Dials | | --- | --- | --- | | `archie-state-store` | State Store and Control Plane contracts; owns the task and control-plane PostgreSQL tables | PostgreSQL | | `archie-gateway` | Chat, conversation state, task tools | State Store | | `archied` | Scheduling, workflow runs, harness, Daemon contract | State Store, Gateway, Messaging | | `archie-messaging` | External channel frontends | Gateway | | `archie-ui` | Dashboard HTTP API (`internal/webui`) and the embedded SPA | State Store, Gateway, daemon, harness | | `archie-agent` | The worker inside each task container | NATS | `internal/domain` holds behaviour and interfaces; `internal/infrastructure` implements them. Dashboard work follows `ui/CLAUDE.md`. Workflow YAML and its step vocabulary are in `WORKFLOWS.md`; the server catalogue is authoritative. ## Authority When sources disagree, the higher one wins: 1. The maintainer's instruction in this session. 2. This file. 3. The code as it is in the tree. 4. Beads issues (`bd show `): the plan for a piece of work. 5. Everything else (memories, comments, old docs) is a hint. Verify it against the code before acting on it. ## Working with the maintainer - **A clear direction is the go-ahead.** Do it in the same turn. Do not restate the plan, offer options, or ask "shall I proceed?". Stop only for destructive or outward-facing actions (deleting data, pushing, touching a live host). - **Post outside the repo only when told.** Chat, tickets and any external service get a message only on the maintainer's instruction. - **Report, don't narrate.** Final replies say what changed, what was verified, and anything blocked, in a few lines. No preamble, no recap of the request, no closing offers of more help. Leave out what the maintainer can see or infer: a clean tree, unpushed commits, a passing gate (commits imply it), and steps skipped that the task never asked for. Name a skipped step only when the task required it. ## How to decide - **Broken beats new.** A bug that blocks work gets fixed now, with the smallest change that unblocks it. No design docs and no new mechanism. - **Cheapest option first.** Before building, name the smallest change that solves the problem, including changing configuration or deleting something. If your plan adds a new mechanism (RPC, process, binary, abstraction, config field, tool) or grows past about 100 lines, stop and assess whether you're taking the path of least resistance. - **Delete before adding.** Unused code, dead paths, fallbacks nobody takes and features nobody runs get removed, not maintained. Solo project, single user: breaking changes need no compatibility shims. - **Finish before starting.** Prefer completing a half-built feature end to end over starting a new one. - **Services own contracts.** A service is a gRPC contract in `proto//v1` and one binary that serves it. Services reach each other only through those contracts, never through another service's tables or packages. A new command is a subcommand of an existing binary. A new binary exists only for a new service or a real process boundary. - **No compensating tools.** Do not write a linter, checker or generator to enforce something a simpler design would make unnecessary. Fix the design. - **A setting must work end to end.** A config field that parses but has no consumer is a bug. Settings are edited through the control plane (API and dashboard), never by requiring a server login. - **Ask only for real decisions.** Product direction and trade-offs the maintainer owns are questions. Everything with a conventional answer is not: decide, do it, say what you chose. ## Code - Idiomatic Go. Small functions, explicit errors, no package-level mutable state, no god objects. Each feature wires itself; a composition root only calls those constructors in order. - Dependencies point inward: `cmd → app → {domain, infrastructure}`, `infrastructure` implements `domain` interfaces, `domain` imports neither. `cmd/` parses flags and calls `app`, nothing else. - Fix invalid state where it is produced, not with checks where it is consumed. - If a fix fails twice, throw the block away and rewrite it simply. - Comments say why, briefly. No migration history, phase names or issue narration in code. - Generated files (`ui/dist/`, protobuf, sqlc) are regenerated and committed with the change that caused them, never hand-edited. ## Tests The default for a change is no new test. Write one only when: - something actually broke: write the test that reproduces it, see it fail on the assertion, then fix; or - the change alters one of these seams: State Store SQL semantics (transition guards, idempotent dispatch, cancellation), security boundaries (HMAC, grants, path confinement, egress, secrets), the workflow step contract, or the import-boundary rules. A test that exists must catch a real regression, survive refactoring, run fast, and be cheap to keep. Never test wiring, constants, defaults, struct shapes, fakes, or call order. No test opens a real database or needs Docker; test SQL semantics at the interceptor or domain level with fakes. One table-driven test per behaviour; extend the table instead of adding a second test. Prefer making an invalid state unrepresentable to testing that it is rejected. Test helpers live in `_test.go` files only. ## Invariants These protect users. Do not weaken them without the maintainer's say-so. - Failure stays local. Any service may crash, restart or be absent without losing accepted work or taking another service down. Callers retry, degrade and report the dependency as unhealthy; they never exit because a peer is missing, and work is acknowledged only once it is durable. - The model never runs git. Commits and pushes go through the daemon. - The daemon's own credentials never enter an agent container. Containers get task-scoped grants that are revoked when the task ends. - Webhook HMAC is verified before the payload is parsed. - Task briefs go in `/.git/task.json`, never the worktree root. - NATS: task and RPC replies use `msg.Respond`; flush after registering a responder; `ARCHIE_TASKS` is a work queue, so never bind overlapping consumers. - `ai-sdk` `FullStream` must be drained completely. ## Build and gate ```bash task build # binaries into bin/ task test # go test -short ./... task ui # dashboard into ui/dist task check # the gate go test -short ./internal/domain/workflow -run TestName # one test task dev # every service + Vite at http://localhost:5173, from deployments/dev.toml task e2e:up # seeded local stack; task e2e:check -- all runs the browser checks ``` `task proto:generate` and `task db:generate` write the committed generated output for `proto/` and `internal/infrastructure/postgres/`; `task check` runs their check variants and rejects stale output. The e2e stack is not part of the gate. Requires Go 1.27, Task, golangci-lint, Node, pnpm and Docker. Adopt `task fmt` and `go fix` output as-is. - `task check` gates the commit: `task check && git commit ...`. Never claim a gate result you did not just produce on that exact tree; if the gate could not run, say what you did verify. - Commit finished work without asking. Stage only your own paths and commit in the same command. Conventional Commits scoped by package, short messages. Push only when told. - Never commit binaries, build output, scratch files or `.references/`. Scratch goes in `/tmp`. - Runtime config lives at `${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`. Nothing in the working tree is read at runtime. Systemd is optional. - Releases: `RELEASING.md`. ## Issues (beads) Work is tracked in `bd`, never in Markdown TODO files. ```bash bd ready | bd show | bd update --claim | bd close ``` - An issue is the plan: what is wrong or wanted, and how you know it is done. Keep it to that. - Bead state syncs through Dolt (`bd dolt push/pull`, only when told), not git. Never commit `.beads/` exports. - No host names, IPs, paths, PIDs or credentials in any bead: they are published. - File follow-up work you find as a bead. Do not fix it in passing. ## Changing this file A rule is added only after a real failure it would have prevented, and it must say which decision it changes. Remove rules that no longer change decisions. Keep it short enough to read in full every session.