Files
samandCopilot 64dfad6d53 feat(runs): add typed results and model aliases (#2043)
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>
2026-11-18 23:47:35 +11:00

14 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 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

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.

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.