Also fix repository-free message.send validation (#2046) and add a single-binary development smoke path (#1977). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
269 lines
14 KiB
Markdown
269 lines
14 KiB
Markdown
# 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 alert, a
|
|
webhook, a schedule, a chat message, an issue) is matched to a workflow, the
|
|
workflow runs an agent whose every action is judged before it runs, 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.
|
|
|
|
## Layout
|
|
|
|
Main is becoming one binary, `archie`. The design is ARCHITECTURE.md in the
|
|
private sam/archie-product repo, and the work is epic #1977. New work goes
|
|
there:
|
|
|
|
- `cmd/archie` parses flags and calls `internal/app/archie`, the composition
|
|
root.
|
|
- Each module is `modules/<name>/`: an API package and an `internal/` directory
|
|
nothing outside the module can import. Modules reach each other only through
|
|
API packages, own their schema and tables, and keep no state only in memory.
|
|
- `internal/platform/` holds the few leaf packages every module may use.
|
|
- The new code never imports the old services' packages (depguard enforces it).
|
|
Old code moves: `git mv` it into the module that owns it, then adapt it.
|
|
While an old service still imports it, copy it instead, name the source
|
|
path in the commit, and delete the old copy with its service.
|
|
MIGRATION.md in sam/archie-product gives every old package a destination and
|
|
a verdict. Writing a replacement from scratch, or deleting an old package,
|
|
needs the maintainer's verdict on its row. Before building anything an old
|
|
package already does, read that package and carry its behaviour.
|
|
|
|
### The services being replaced
|
|
|
|
The six services below are deleted slice by slice as the binary replaces them,
|
|
each only once MIGRATION.md has a verdict for every package it holds. Don't
|
|
add features to them; fix them only when a bug blocks work.
|
|
|
|
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 tables | PostgreSQL |
|
|
| `archie-gateway` | Chat contract; owns the conversation tables | State Store, PostgreSQL |
|
|
| `archied` | Daemon contract; scheduling, workflow runs, task containers | State Store, Gateway, Messaging, NATS |
|
|
| `archie-messaging` | Messaging contract; external channel frontends | State Store, Gateway |
|
|
| `archie-ui` | Dashboard HTTP API (`internal/webui`) and the embedded SPA | State Store, Gateway, Daemon, Messaging |
|
|
| `archie-agent` | The worker inside each task container | NATS |
|
|
|
|
Forge, channel and secret-engine contracts are extension boundaries, not
|
|
services: a core binary starts the extension as a plugin process and dials it.
|
|
`archied` also runs the State Store's backup and restore during a host update.
|
|
|
|
`internal/domain` holds behaviour and interfaces; `internal/infrastructure`
|
|
implements them. Every instruction sent to a model is a file in
|
|
`internal/prompts`, read through that package; never inline a prompt in code.
|
|
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. Gitea issues (`tea issues view <n>`): 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).
|
|
- **Push back when it matters.** If a request competes with something clearly
|
|
more urgent (a bug that loses work, a failure that shows nothing, a security
|
|
gap, a broken setup path), or looks like the wrong call, say so once in a
|
|
sentence or two and suggest whether it belongs in the backlog. Then do what
|
|
was asked: don't repeat the point or hold work back on your own judgement.
|
|
- **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 comes first.** A bug that blocks or loses work goes ahead of new
|
|
features. Fix the cause. When that's a bigger job, unblock with a small change
|
|
first and file the proper fix rather than stopping there.
|
|
- **Cheapest option first.** Before building, consider the smallest change that
|
|
solves the problem, including changing configuration or deleting something.
|
|
A new mechanism (RPC, process, binary, abstraction, config field, tool) is
|
|
fine when it's the right design; say why the smaller option wasn't enough.
|
|
- **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.
|
|
- **Modules own their API and tables.** A module reaches another only through
|
|
its API package, never its tables or `internal/`. The only real process
|
|
boundaries are extensions and the runner. A new command is a subcommand of
|
|
`archie`.
|
|
- **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.
|
|
- Log through the service's injected `*slog.Logger` with the `...Context`
|
|
methods, so lines carry the OpenTelemetry trace id. Never the global `slog`.
|
|
- If a fix fails twice, throw the block away and rewrite it simply.
|
|
- Comments explain why, not what the code already says. No migration
|
|
history, phase names or issue narration in code.
|
|
- Write natural, idiomatic technical English in comments, errors, logs,
|
|
test names, descriptions, prompts and user-facing text. Use conventional
|
|
terminology and normal word order. Avoid invented metaphors, awkward
|
|
possessives, inverted sentences and clever paraphrases. Prefer repeating
|
|
an established term over inventing a synonym.
|
|
- Generated files (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. Prefer making an invalid state unrepresentable to testing
|
|
that it is rejected.
|
|
|
|
How to write one:
|
|
|
|
- **Prove it.** Run the new test against the code before the fix and see it
|
|
fail. A test that passes either way proves nothing: delete it. When a bug
|
|
can't be reproduced deterministically (a race, say), fix it with an API that
|
|
rules it out and don't add a test.
|
|
- **One table per behaviour.** Extend the table instead of adding a second test.
|
|
Name the test after the behaviour, and say in its comment what regression it
|
|
guards.
|
|
- **Same gate as production.** Tests pass golangci-lint, gosec included, with no
|
|
exclusions for test files. Fix what the linter finds. A fixture that has to
|
|
look like a secret (a key the redaction must catch, a URL with a password the
|
|
parser must reject) uses a plainly fake value and a `//nolint:gosec` saying
|
|
what it tests.
|
|
- **Isolated.** Use `t.TempDir()` and `t.Setenv`, never host state. A test that
|
|
commits with git sets `GIT_CONFIG_GLOBAL` to `os.DevNull`. No test opens a
|
|
real database or needs Docker: test SQL semantics at the interceptor or domain
|
|
level with fakes. Files are written `0o600`, or `0o700` for a script.
|
|
- **Shared setup in helpers.** When several tests repeat the same setup, put it
|
|
in a helper in a `_test.go` file, never in production code.
|
|
|
|
## Invariants
|
|
|
|
These protect users. Do not weaken them without the maintainer's say-so.
|
|
|
|
- A crash loses no accepted work, and a restart resumes every run. Work is
|
|
acknowledged only once it is durable. A missing dependency is reported
|
|
unhealthy and retried, never a reason to exit.
|
|
- 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_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`, `task db:generate` and `task openapi:generate` write
|
|
the committed generated output for `proto/`, `internal/infrastructure/postgres/`
|
|
and `api/openapi.yaml`; `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
|
|
every commit as soon as it is made; a local-only commit is not acceptable.
|
|
- 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.
|
|
|
|
```bash
|
|
tea issues list -r sam/archie --state open --labels critical
|
|
tea issues view 497
|
|
tea issues edit 497 --add-labels 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: a type (`bug`, `feature`, `task`, `chore`, `epic`,
|
|
`decision`, `discovery`), a priority (`critical`, `high`, `medium`, `low`), `in-progress`
|
|
and `deferred`. Open/closed is the issue state, not a label.
|
|
- An epic's children are its dependencies: link each one as it is filed (Gitea
|
|
MCP `issue_write` `add_dependency`, the epic `blocked_by` the child), plus any
|
|
real blocker between children. No `epic/<slug>` label; the dependencies are
|
|
the link, and the only place the web UI shows an epic's children.
|
|
- `tea` drops labels on `issues create` and `edit --add-labels`. Label through
|
|
the Gitea MCP connector, by label ID: it resolves names from the first 50
|
|
labels only.
|
|
- Cite the issue number in commits and comments.
|
|
- `tea issues list --labels` silently ignores an unknown name and returns every
|
|
issue. Check the count is plausible before trusting a filtered list.
|
|
- The API caps `limit` at 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.
|