diff --git a/CLAUDE.md b/CLAUDE.md
index 4601f281a..268c79971 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -5,15 +5,16 @@ here changes a decision. If a rule stops changing decisions, delete it.
## What this is
-**archie-core** is event-driven agentic automation. An event (a forge issue,
-a webhook capture, a schedule, a chat message) is matched to a workflow,
-the workflow runs an agent in an isolated container, and the result lands
-somewhere a human reviews it. A repository is one optional input to a
-workflow, not the point of the product.
+**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.
-The product is unfinished. Many features are half-built, and the codebase
-carries far more code, binaries, docs and tooling than it delivers. The job
-right now is to finish features and shrink the codebase, not to extend it.
+ The product is
+unfinished. Many features are half-built, and the codebase carries far more
+code, binaries, docs and tooling than it delivers. The job right now is to
+finish features and shrink the codebase, not to extend it.
## Authority
@@ -23,49 +24,44 @@ When sources disagree, the higher one wins:
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.
-
-There are no PRDs, architecture docs or repo skills. Old ones live outside
-the repo and are not guidance. Do not recreate them.
+5. Everything else (memories, comments, old docs) is a hint. Verify it against
+ the code before acting on it.
## How to decide
-- **Broken beats new.** A bug that blocks work gets fixed now, with the
- smallest change that unblocks it. No design doc, no new mechanism.
-- **Cheapest option first.** Before building anything, 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 present the cheap option to the maintainer first.
-- **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.
-- **No new binaries.** A new command is a subcommand of an existing binary.
- A binary exists only for a real process boundary (separate deploy,
- scaling, security or failure domain).
+- **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.
+- **No new binaries.** A new command is a subcommand of an existing binary. A
+ binary exists only for a real process boundary (separate deploy, scaling,
+ security or failure domain).
- **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.
+ 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. `internal/app/archied/bootstrap.go` is the
- counter-example: never add to it. New wiring belongs to the feature that
- needs it.
+ 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.
+- 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.
@@ -76,19 +72,18 @@ the repo and are not guidance. Do not recreate them.
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.
+- 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. 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.
+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. 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
@@ -113,17 +108,17 @@ task ui # dashboard into ui/dist
task check # the gate
```
-Requires Go 1.27, Task, golangci-lint, Node/npm and Docker.
-Adopt `task fmt` and `go fix` output as-is.
+Requires Go 1.27, Task, golangci-lint, Node/npm 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`.
+- `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`.
@@ -136,16 +131,16 @@ Work is tracked in `bd`, never in Markdown TODO files.
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.
+- 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.
+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.