Every one of the 1709 tracker issues was created in Gitea and checked field by field against its source record: title, body, state, label set, assignee, comments, dependency edges and epic label. All 1729 beads are closed, citing the issue that carries each one, and .beads is removed. Three differences are deliberate: Gitea truncates titles at 253 characters, so three long titles keep their full text in the issue body; Gitea refuses a mutual dependency, so five symmetric relates-to links exist in one direction; issue 497 carries its fix from e3b1103f.
10 KiB
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.
<temporary - remove on 2026-12-01> 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/<service>/v1, generated into
internal/contracts/<service>/v1, and one binary in cmd/ that parses flags
and calls its composition root in internal/app/<service>.
| 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:
- The maintainer's instruction in this session.
- This file.
- The code as it is in the tree.
- Gitea issues (
tea issues view <n>): the plan for a piece of work. - 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/<service>/v1and 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},infrastructureimplementsdomaininterfaces,domainimports neither.cmd/parses flags and callsapp, nothing else. - Fix invalid state where it is produced, not with checks where it is consumed.
- Log through the service's injected
*slog.Loggerwith the...Contextmethods, so lines carry the OpenTelemetry trace id. Never the globalslog. - 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
<worktree>/.git/task.json, never the worktree root. - NATS: task and RPC replies use
msg.Respond; flush after registering a responder;ARCHIE_TASKSis a work queue, so never bind overlapping consumers. ai-sdkFullStreammust be drained completely.
Build and gate
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 checkgates 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 (Gitea)
Work is tracked as issues on the primary remote, never in Markdown TODO files. GitHub is a read-only mirror; do not open, close or comment there.
tea issues list -r sam/archie --state open --labels priority::critical
tea issues list -r sam/archie --labels epic/<slug> --state open
tea issues view 497
tea issues edit 497 --add-labels status::in_progress --add-assignees sam
tea comment 497 "what changed, and what was run"
tea issues close 497
- An issue is the plan: what is wrong or wanted, and how you know it is done. Keep it to that.
- Labels carry state:
type::,priority::,status::in_progressandstatus::deferred. Open/closed is the issue state, not a label.epic/<slug>says which epic an issue belongs to. - Cite the issue number in commits and comments.
tea issues list --labelssilently ignores an unknown name and returns every issue. Check the count is plausible before trusting a filtered list.- The API caps
limitat 50 regardless of what you pass. - No host names, IPs, paths, PIDs or credentials in an issue: the text outlives the change that wrote it.
- File follow-up work you find as an issue. 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.