16 KiB
AGENTS.md
Guidance for any coding agent working in this repository.
Keep every rule here harness-agnostic: name the required behaviour, not the tool that provides it (e.g. "spawn a fresh reviewer that did not write the code", not a specific sub-command).
Code Quality & Refactoring Standards
- Zero Patch Stacking: Never apply more than two sequential fixes to the same logic block. If a solution fails twice, scrap the block and rewrite it cleanly.
- Root-Cause Fixes: Fix invalid state at the producer, not via defensive checks at the consumer.
- Architectural Simplicity: Prefer a complete 20-line rewrite over a 5-line band-aid that adds conditional complexity or obscures intent.
- Revert on Flail: If an implementation becomes convoluted to satisfy edge cases, discard the approach and select a simpler design.
What this is
archied is a resident daemon that polls a forge (GitHub, Gitea) for issues assigned/labelled to it, works each one in an isolated git worktree through a routed workflow (bootstrap / implement / TDD / feasibility), and opens pull requests for human review.
See ARCHITECTURE.md for the package map, workflow engine design, task
lifecycle, and key design decisions. Read it before making non-trivial changes.
Key invariants: env-enforced gates, model never runs git, and agent execution
functions as a strict data boundary. Before adding a new plugin engine, satisfy
ARCHITECTURE.md#plugin-engine-rule-strict.
Scope Discipline
docs/architecture/ is authoritative for settled design.
docs/architecture/migration-decisions.md is the open decision register for the
domain migration.
- Settled design exists → Implement it immediately with a diff. Do not produce design prose. If a small detail is missing, ask the maintainer directly.
- No settled design exists (or open in
migration-decisions.md) → Write a decisive, 1-page design doc before coding. Land new capabilities indocs/prds/and migration questions indocs/architecture/migration-decisions.md. Promote todocs/architecture/only after implementation lands. - Strictly Prohibited: Ownership ledgers, field-level inventories, current-state traces, parity matrices for their own sake, and planning/refactor tracking issues.
- Solo Project Context: Prefer the smallest workable change over extensive defensive scaffolding.
Deployment Model
- Systemd is optional:
deployments/holds supported profiles (single-forge-github.toml,multi-forge-github-gitea.toml,local-ollama-standalone.toml,docker-nats-stack.toml,systemd-user-service.md). Never assume a systemd unit exists. - Chat filesystem confinement: Builtin tools default to workspace jail via
SetPathConfinement(!unrestricted). Unrestricted access requires[chat] unrestricted_filesystem = true. - NATS endpoint immutability: The daemon passes agent containers its startup
connection URL (
d.ConnectedNATS.URL). Containers and daemon must resolve this address. Embedded mode binds to the Docker bridge gateway. A SIGHUP reload ofnats.urllogs an error requiring restart to prevent split-brain delivery. - Container pull policy:
containers.pull_policymust be"missing"(default) or"always". Private registries return 401 on"always"because no auth is sent. Refresh explicitly viadocker compose pull agent. - Docker Compose:
docker-compose.ymlcarries optional external NATS and theagentbuild stanza. The agent uses abuildprofile soup -d natsnever starts it as a persistent service. - Config path: Runtime configuration lives at
${XDG_CONFIG_HOME:-~/.config}/archie/config.toml. Nothing in the working tree is load-bearing at runtime.
Release Process
See RELEASING.md. Most sessions touch only archied, making releases
gateway-only (RUNTIME=skip) by default. Skip untouched components
automatically and note it in the handoff.
Build & Test
Commands are defined in Taskfile.yml (requires Go 1.27.0,
Task, gofumpt, golangci-lint, and Node/npm).
task build # build archied and archie-agent binaries into bin/
task test # go test ./... -count=1
task test:ui # dashboard node tests (DOM-building primitives)
task ui # build dashboard into ui/dist (LAW asset)
task fmt # gofumpt -w . && go fix ./...
task vet # go vet ./...
task lint # golangci-lint run ./...
task check # fmt + go fix + proto:lint + proto:check + vet + lint + build + test + test:ui (The Definitive Gate)
task dev # archied live-reload + Vite HMR together on :5173
Single package/test runs:
go test ./internal/domain/workflow/... -run TestName -v -count=1
Repository Hygiene
- Generated assets are LAW: Never modify, revert, or ignore generated files
in
ui/dist/or schema outputs. Incorporate them into relevant commits. - Ignored paths: Never commit build artifacts, binaries (
/bin/,/archied), DB files, working screenshots,.references/, ornode_modules/. - Scratch files: Place scratch files strictly in
/tmpor the harness scratch space. Never put scratch files in the working tree (worktree.CommitAllwill stage them). - Conventional Commits: Scope by package:
feat(webui): ...,fix(build): ...,chore(release): .... - Commit policy: Commit finished, gate-clean changes (
task checkpassing) without asking. Push only when instructed.
Organisation (Strict Domain-Driven Architecture)
docs/architecture/organisation.md is authoritative. Do not follow flat
structures found in legacy packages.
Layers and Ownership
internal/domain/<area>/: Domain logic, entities, state machines, commands, events, and required contracts (interfaces). Never imports infrastructure or app.internal/infrastructure/<service>/: Implementations of domain contracts (persistence, forge clients, external transports, config loading).internal/app/<application>/: Dependency injection, wiring domain to infrastructure, lifecycle management, and shutdown ordering.cmd/<binary>/: CLI flag parsing, OS signal traps, and entry point routing only. No domain wiring.
Invariants
- Dependency Flow:
cmd → app → {domain, infrastructure}, withinfrastructure → domainimplementing contracts. Downward/inward dependencies only. - Cross-Cutting Packages:
logging,events,eventbus,policy,taskstatesit directly underinternal/. They may be imported by any layer, but must import zero internal packages. Noshared/,utils/, orcommon/catch-alls. - File Layout: One file per API concern (
api_tasks.go,api_logs.go). A package owns its on-disk format end-to-end (e.g.internal/loggingdefines and reads its format; transport layers do not parse). - Frontend: Features live in
ui/src/<feature>/with colocated.jsand.css. Extract toui/src/base/only on the second distinct consumer.
Per-Package Invariants & Traps
-
internal/channels/telegram/: -
The long-polling worker must call
dropPendingUpdates(ctx, b)beforeb.Start(ctx)and on/restart. -
Always publish command menus to
default,all_private_chats, andall_group_chatssimultaneously viacommands.goto avoid scope shadowing from legacy registrations. -
ai-sdkStreaming:FullStreamwrites synchronously and MUST be drained completely to prevent producer deadlocks. Do not rely onTextStream(drops deltas). -
NATS Invariants:
-
ARCHIE_TASKSusesjetstream.WorkQueuePolicy. Do not bind overlapping consumer filters; useFetchon existing durables instead of newSubscribecalls. -
RPC and task responses must use core NATS
msg.Respondto write to ephemeral_INBOX.*subjects, noteventbus.Publisher. -
Always flush connections (
nc.Flush()) immediately after registering responders to avoid race conditions on initial requests. -
internal/gateway/Chat Prompt: System prompt<tools>blocks are rendered strictly from the activecore.ToolSet. Never decouple prompt tool definitions from passed runtime tools. -
internal/container/pool.go(WriteTaskJSON): Write task briefs to<worktree>/.git/task.json. Never place them in the worktree root (go-gitAdd{All:true}ignores.gitignoreand leaks root files into branch commits). -
MCP Providers: Daemon registers providers as optional via
providerRegistry.RegisterOptional. Missing or failed providers log warnings and degrade health without terminating the process. -
internal/infrastructure/staterpc/(State Store gRPC contract): Authority isdocs/prds/state-store-contract.md(rev. 2c) -- read it before changing this package or its callers. -
The proto (
proto/state/v1/state.proto, serviceStateStoreService, packagestatev1ininternal/contracts/state/v1/) is one gRPC service fronting every ratified store contract (42 RPCs); the Go consumer facades stay narrow (workflow.Store,store.TaskStore, etc., all ≤8 methods except theTaskStorecomposite) viastaterpc.Client's multiplevar _assertions -- never add a Go interface method without a matching RPC. -
Error sentinels (
store.ErrStaleTransition,ErrBindingNotFound, ...) cross the wire viamapError/unmapErrorinvalues.go, matched on(code, exact canonical message). Changing a canonical message string breakserrors.Ison the client without changing behavior visibly -- treat those message constants as part of the wire contract. -
The State Store is a standalone process (
cmd/archie-state-store, run viaarchied.RunStateStore) -- the daemon and Gateway never ownarchie.dbor serve this service in-process;boot.openStateStoreininternal/app/archied/state_store.gois the only caller ofopenProductionTaskStore. Never add a second listener for the same service, and never reintroduce an in-process serving path in the daemon/Gateway (TestOpenStoresNeverOwnsTaskDBguards this). -
Per-task credentials are scoped, not just authenticated:
daemon. StateStoreGrantIssuer(staterpc.GrantIssuer) registers a fresh task-scoped grant at the remote State Store viaRegisterTaskGrantbeforeContainerPool.Acquireand revokes it viaRevokeTaskGrantonRelease(acquireTaskContainer/processininternal/daemon/daemon.go). Fails closed (parks the task) if a State Store is configured but no issuer is wired -- it must never fall back to forwarding the daemon's own administrative token. Server-side,staterpc.TaskGrants.UnaryInterceptorauthorizes a task-scoped token for onlyUpdate/Transition/InsertEventon its own task ID; every other RPC (includingRegisterTaskGrant/RevokeTaskGrantthemselves and the streaming capture RPCs) requires the administrative token. -
archie-agenthas exactly oneworkflow.Storepath: gRPC viastaterpc.Client(agenttransport/nats.Transport.Store), using theSTATE_STORE_URL/STATE_STORE_TOKENenv the daemon injects. The legacy NATSstorerpctransport is deleted (internal/storerpcno longer exists); do not reintroduce a dual-path selection. -
store.BindingDispatcher.RecordDispatchtakes no*sql.Tx(dropped in.4.2-- it cannot cross a gRPC boundary; production always passednil). Do not reintroduce a transaction parameter on a producer-owned store interface that a remote adapter must also implement. -
internal/forge/webhook/(forge webhook receiver): -
Verify HMAC (
webhookguard.VerifyHMACagainstX-Hub-Signature-256) before parsing the payload, never after -- an unverified body must not reachgithub.ParseWebHook. -
Do not give the webhook-built
workintake.TaskEnvelopea delivery-source- specific idempotency key.IdempotencyKey()is keyed onowner/repo/numberonly so a webhook-delivered issue and a later poll of the same issue dedup against each other viaPublishUnique; adding an event ID or timestamp to the key defeats that and reintroduces poll/webhook double-dispatch. -
Webhook intake refuses to start when
[[identities]]is configured (one receiver, one dispatch config). Do not silently enable it for multi-identity deployments without first building per-identity routing -- seeARCHITECTURE.md's "Webhook intake" section. -
internal/domain/embedding/+internal/infrastructure/embedding/: Embedding client contract + implementation. Config-driven exactly like chat model roles:models.embedding = "provider/model"plus a[providers.*]entry.infrastructure/embedding.Newdegrades to(nil, false)-- never an error -- for a missing role, unknown provider, unsupported class, or unresolved credential; wired as an optional capability inbootstrap.go'ssetupEmbeddings. Only provider classes matchingconfig.Provider's shape are supported (openai, gemini, ollama, cohere, mistral) -- azure needs aDeploymentfield this config type doesn't have. -
internal/domain/sampling/: The curatorSamplerinterface (seedocs/prds/curator-sampler-wave1.md) plus four pure, deterministic strategies (recency, staleness, random, all). No curator consumes aSampleryet --curator.Registraris untouched by this package.
Development Protocol
- Red (Failing Test): Write failing test cases first using table-driven tests against target behaviour. Verify the failure originates from test assertions, not compilation errors.
- Green (Implementation): Implement minimal code to satisfy the failing tests.
- Quality Gate: Run
task check. - Formatting is LAW: Adopt all formatting and simplification changes from
task fmt(gofumpt+go fix) verbatim. Never revert or fight canonical linter/formatter diffs. - No standing adversarial-review pass (for contributors): Do not spawn a
separate fresh-context reviewer pass on every change as a matter of course.
Red-green TDD plus
task checkis the gate; a manual adversarial pass is opt-in per request — ask before running one. This is the rule for a human or agent contributor. Separately, archied runs the same adversarial review automatically on the PRs it opens (gated per repo byrepo.review_enabled) — seedocs/architecture/adversarial-review.md. The two paths are distinct: you run one when asked; archied runs one before it opens a PR. - Linter Guard:
- When using
errorlintfixes, ensure boolean predicates (e.g.exitErr.ExitCode() == 1) are retained alongsideerrors.As. - When extracting loops/conditionals, verify slice mutations and pointer semantics do not duplicate elements.
Issue Tracking (Beads)
All task management is tracked via bd (beads). Do not write local Markdown TODO lists or use non-Beads trackers.
Commands
bd ready # List unclaimed work
bd show <id> # View issue details
bd update <id> --claim # Claim an issue
bd close <id> # Mark issue complete
bd remember # Persist cross-session architectural facts
- Run
bd primeto inspect full engine context. - Use
bd rememberfor knowledge retention. Do not write to rootMEMORY.mdfiles. - Issues live in a local Dolt DB, synced to its own
git+remote viabd dolt push/bd dolt pull..beads/issues.jsonland.beads/interactions.jsonlare local-only export/audit files (.gitignored,export.auto: false) -- nevergit addthem and never create a commit whose only content is beads bookkeeping. Bead state moves through Dolt, not through git commits on this repo.
Session Completion Protocol
-
Log remaining work: File new items via
bdfor identified debt or follow-up tasks. -
Run gate: Verify
task checkpasses completely clean. -
Update tracker: Close finished issues via
bd close <id>. This alone is not commit-worthy -- do not stage or commit.beads/for it. -
Commit: Only for actual code/doc changes, scoped to the files that changed.
git add <scoped-files> git commit -m "feat(scope): description" -
Sync & Push Policy: Do not push to git remotes or run
bd dolt pushunless explicitly instructed. -
Handoff: Report changed files, gate verification results, and active issue states.
Maintaining this file
Keep this file for knowledge useful to almost every future agent session in this project. Do not repeat what the codebase already shows; point to the authoritative file or command instead. Prefer rewriting or pruning existing entries over appending new ones. When updating this file, preserve this bar for all agents and keep entries concise.