docs(development): organise the guides by area

One page per area: frontend UI, agent, workflows, daemon (task lifecycle and
event automation together), State Store, control plane and settings, and
processes and wiring, with merging work kept separate.
This commit is contained in:
sam committed 2026-09-24 21:05:29 +10:00
1 parent 4fe3bc13ee
commit 173e059bc8
14 files changed
+157 -160

No files matched your search

+3 -2
View File
@@ -33,8 +33,9 @@ git, and agent execution functions as a strict data boundary. Before adding a ne
plugin engine, satisfy
`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`.
Before changing a subsystem, read its checklist in `docs/development/`: each
page names every layer that kind of change must reach.
Before changing an area (frontend UI, agent, workflows, daemon, State Store,
control plane), read its page in `docs/development/`: it names every layer the
change must reach.
## Scope Discipline
+39 -49
View File
@@ -106,31 +106,31 @@
"url": "/dev/development/",
"title": "Development guides",
"section": "Development",
"body": "# Development guides\n\nChecklists for changing Archie. Each page covers one kind of change and names\nevery place that change must reach, so a feature that works in one layer does\nnot silently stop at the next. The pages point at the documents that own the\ndesign (`docs/architecture/`, the PRDs, `CLAUDE.md`) rather than restating\nthem.\n\n| Changing | Guide |\n| --- | --- |\n| A setting in `config.toml` or the dashboard | [Configuration settings](/dev/development/config-settings/) |\n| A stored field, table, RPC or error | [State Store and persistence](/dev/development/state-store-and-persistence/) |\n| Task statuses, fields or the task brief | [Task lifecycle](/dev/development/task-lifecycle/) |\n| Workflow definitions or step types | [Workflows and steps](/dev/development/workflows-and-steps/) |\n| Sources, event types, mappings or bindings | [Event automation](/dev/development/event-automation/) |\n| Anything under `ui/` | [Dashboard](/dev/development/dashboard/) |\n| The agent container, its image or its tools | [Agent execution and containers](/dev/development/agent-execution-and-containers/) |\n| A process, plugin engine, channel or NATS subject | [Processes and wiring](/dev/development/processes-and-wiring/) |\n| Merging a lane or a branch | [Merging work](/dev/development/merging-work/) |\n\n## Every change\n\n- Write the failing test first for anything with logic, branching or a\n contract, and check it fails on an assertion, not a compile error.\n- Test through the path production uses. A test that sets a value directly on\n the consumer proves nothing about the layers that normally deliver it.\n- Run `task check` and let its exit status decide the commit:\n `task check \u0026\u0026 git commit ...`. `task test` passes `-short`, which skips the\n process and Postgres tests, so run `go test -count=1 ./cmd/... ./internal/...`\n too when a change crosses a process or the database.\n- Regenerate, never hand-edit, generated output: `task proto:generate`,\n `go -C tools tool sqlc generate -f $PWD/internal/infrastructure/postgres/sqlc.yaml`,\n `task ui`, `task docs:artifact`. `task proto:check` compares against the git\n index, so stage regenerated contracts before running it.\n- Stage by path, or read `git status` before `git add -A`. Tests that start\n embedded NATS or write logs must use `t.TempDir()`; anything they leave in the\n tree gets committed. `task check` also adds linter-tool lines to `go.sum`\n (bead 1e37); restore `go.sum` before committing unless you changed a\n dependency.\n- A change to `docs/prds/` or `docs/architecture/` carries the regenerated\n `docs/data/generated/dev-docs.json`, and PRD edits follow\n `docs/prds/RULES.md` and pass `task docs:prds`.\n"
"body": "# Development guides\n\nChecklists for changing Archie, one page per area. Each names every place a\nchange must reach, so a feature that works in one layer does not silently stop\nat the next. A change that spans areas starts on the page for the area it\nbegins in, which points to the others. The pages point at the documents that\nown the design (`docs/architecture/`, the PRDs, `CLAUDE.md`) rather than\nrestating them.\n\n| Area | Covers |\n| --- | --- |\n| [Frontend UI](/dev/development/frontend-ui/) | Anything under `ui/`, and the dashboard's API routes |\n| [Agent](/dev/development/agent/) | The agent container, its image, profiles, tools and workspace |\n| [Workflows](/dev/development/workflows/) | Workflow definitions and step types |\n| [Daemon](/dev/development/daemon/) | Task statuses, fields and the brief; sources, event types, mappings and bindings |\n| [State Store](/dev/development/state-store/) | Stored fields, tables, RPCs and errors |\n| [Control plane and settings](/dev/development/control-plane/) | Settings in `config.toml` or the dashboard |\n| [Processes and wiring](/dev/development/wiring/) | Where code goes, processes, plugin engines, channels, NATS subjects |\n| [Merging work](/dev/development/merging-work/) | Merging a lane or a branch |\n\n## Every change\n\n- Write the failing test first for anything with logic, branching or a\n contract, and check it fails on an assertion, not a compile error.\n- Test through the path production uses. A test that sets a value directly on\n the consumer proves nothing about the layers that normally deliver it.\n- Run `task check` and let its exit status decide the commit:\n `task check \u0026\u0026 git commit ...`. `task test` passes `-short`, which skips the\n process and Postgres tests, so run `go test -count=1 ./cmd/... ./internal/...`\n too when a change crosses a process or the database.\n- Regenerate, never hand-edit, generated output: `task proto:generate`,\n `go -C tools tool sqlc generate -f $PWD/internal/infrastructure/postgres/sqlc.yaml`,\n `task ui`, `task docs:artifact`. `task proto:check` compares against the git\n index, so stage regenerated contracts before running it.\n- Stage by path, or read `git status` before `git add -A`. Tests that start\n embedded NATS or write logs must use `t.TempDir()`; anything they leave in the\n tree gets committed. `task check` also adds linter-tool lines to `go.sum`\n (bead 1e37); restore `go.sum` before committing unless you changed a\n dependency.\n- A change to `docs/prds/` or `docs/architecture/` carries the regenerated\n `docs/data/generated/dev-docs.json`, and PRD edits follow\n `docs/prds/RULES.md` and pass `task docs:prds`.\n"
},
{
"url": "/dev/development/agent-execution-and-containers/",
"title": "Agent execution and containers",
"url": "/dev/development/agent/",
"title": "Agent",
"section": "Development",
"body": "# Agent execution and containers\n\nAuthority: `docs/architecture/agent-system.md` (execution boundary, the model\nnever runs git) and the Deployment Model section of `CLAUDE.md`.\n\nThe daemon prepares a workspace, starts one container per task from a profile's\nimage, and hands the whole task to `archie-agent` over NATS in one\n`taskrun.Request`. The agent reaches the State Store, forge and worktree push\nonly through the daemon's RPC servers, using task-scoped credentials.\n\n## Giving the agent something new\n\n- **Data about the task** goes in `taskrun.Request` or the task brief\n (`container.TaskPayload`), never in an environment variable. Add a test that\n the request carries it (`TestRunViaAgentSendsMCPServers` is the pattern).\n- **A credential** is scoped to the task and revoked when it ends, like the\n State Store grant and the worktree publication grant. The daemon's own\n administrative token never enters a container.\n- **A tool** reaches the agent through the central registry, MCP, a repository\n script or a skill plugin. A profile's `tools` list filters those; ai-sdk\n agentloop's built-in file tools are outside it. A tool that must stay inside\n the workspace uses the agent loop's confinement, not its own path handling.\n\n## Changing the agent image or a profile image\n\n1. The agent image is `Dockerfile`; example profile images live in\n `examples/profiles/`, each with a build-only service in\n `docker-compose.yml` (`profiles: [\"build\"]`, so `up -d` never starts it).\n2. Anything the agent runs must be in the image. The container gets no\n package manager at run time beyond what the image ships.\n3. A locally built image needs `containers.pull_policy = \"missing\"`;\n `\"always\"` tries to pull it and fails.\n4. Profiles are configured under `[containers.profiles.\u003cname\u003e]` and resolved\n by the daemon before the container starts (`pinTaskProfile`). An unknown\n profile parks the task; it never falls back to the default image.\n\n## Changing how a task runs\n\n- Workspace preparation happens in the daemon (`prepareWorkspace`) before the\n container starts, because the container binds the directory. Clones need the\n daemon's forge credential; the agent never clones.\n- A task with no repository gets `worktree.Manager.ScratchDir`, which is\n removed when the task ends.\n- The agent runs as root in the container. Anything it writes into the\n bind-mounted workspace is handed back to the daemon's UID\n (`restoreWorktreeOwnership`); a new write path must stay inside that\n workspace.\n- NATS rules are in `CLAUDE.md`: task responses use `msg.Respond`, a responder\n is flushed after it registers, and `ARCHIE_TASKS` is a work queue.\n"
"body": "# Agent\n\nAuthority: `docs/architecture/agent-system.md` (execution boundary, the model\nnever runs git) and the Deployment Model section of `CLAUDE.md`.\n\nThe daemon prepares a workspace, starts one container per task from a profile's\nimage, and hands the whole task to `archie-agent` over NATS in one\n`taskrun.Request`. The agent reaches the State Store, forge and worktree push\nonly through the daemon's RPC servers, using task-scoped credentials.\n\n## Giving the agent something new\n\n- **Data about the task** goes in `taskrun.Request` or the task brief\n (`container.TaskPayload`), never in an environment variable. Add a test that\n the request carries it (`TestRunViaAgentSendsMCPServers` is the pattern).\n- **A credential** is scoped to the task and revoked when it ends, like the\n State Store grant and the worktree publication grant. The daemon's own\n administrative token never enters a container.\n- **A tool** reaches the agent through the central registry, MCP, a repository\n script or a skill plugin. A profile's `tools` list filters those; ai-sdk\n agentloop's built-in file tools are outside it. A tool that must stay inside\n the workspace uses the agent loop's confinement, not its own path handling.\n\n## Changing the agent image or a profile image\n\n1. The agent image is `Dockerfile`; example profile images live in\n `examples/profiles/`, each with a build-only service in\n `docker-compose.yml` (`profiles: [\"build\"]`, so `up -d` never starts it).\n2. Anything the agent runs must be in the image. The container gets no\n package manager at run time beyond what the image ships.\n3. A locally built image needs `containers.pull_policy = \"missing\"`;\n `\"always\"` tries to pull it and fails.\n4. Profiles are configured under `[containers.profiles.\u003cname\u003e]` and resolved\n by the daemon before the container starts (`pinTaskProfile`). An unknown\n profile parks the task; it never falls back to the default image.\n\n## Changing how a task runs\n\n- Workspace preparation happens in the daemon (`prepareWorkspace`) before the\n container starts, because the container binds the directory. Clones need the\n daemon's forge credential; the agent never clones.\n- A task with no repository gets `worktree.Manager.ScratchDir`, which is\n removed when the task ends.\n- The agent runs as root in the container. Anything it writes into the\n bind-mounted workspace is handed back to the daemon's UID\n (`restoreWorktreeOwnership`); a new write path must stay inside that\n workspace.\n- NATS rules are in `CLAUDE.md`: task responses use `msg.Respond`, a responder\n is flushed after it registers, and `ARCHIE_TASKS` is a work queue.\n"
},
{
"url": "/dev/development/config-settings/",
"title": "Configuration settings",
"url": "/dev/development/control-plane/",
"title": "Control plane and settings",
"section": "Development",
"body": "# Configuration settings\n\nAuthority: `docs/architecture/configuration.md`. The wiring matrix, the\ndecoded-but-unwired ledger and the three shapes an unwired field takes are in\n`.agents/skills/archie-config-and-flags`.\n\nA field that parses is not a field that works. Before adding one, name the code\nthat reads it and the path the value takes to get there.\n\n## Decide what kind of setting it is\n\n- **Bootstrap-only** (read once at process start: `database_url`, `state_dir`,\n `work_dir`). It stays in the file, is checked by `validateBootstrap` in\n `internal/infrastructure/configuration/validate.go`, and the runtime overlay\n refuses changes to it.\n- **Database-owned** (repository policies, scheduling, tools, plugins,\n channels, containers). The file only seeds it. Once the State Store holds the\n control-plane resource, the stored document is layered over the file\n (`controlplane.Client.RuntimeConfig`) and the file key stops mattering. It is\n checked by `validateDatabaseOwned` and by the resource's validator.\n- **Worker-carried.** A value the agent container needs travels in\n `config.TaskConfig` (`Config.ForTask`) or on `taskrun.Request`. Never pass it\n as an environment variable the daemon did not already define, and never carry\n a secret this way.\n\n## Adding a database-owned field\n\n1. Add it to the struct the resource's `Document` names in\n `internal/app/controlplane/operational_settings.go`. The resource's JSON\n schema and the dashboard's Advanced settings editor are generated from that\n type, so no UI work is needed for the editor itself.\n2. Stored documents use Go field names as keys (`Image`, `MaxConcurrency`).\n Give the field no `json` tag unless its neighbours have one.\n3. A map or a nested struct needs its layering checked. `json.Unmarshal`\n merges into an existing map, so a stored map would add to the file's rather\n than replace it. A field the stored document omits keeps the file's value\n (a document stored before the field existed). Add a case to\n `internal/app/controlplane/runtime_config_test.go` for both.\n4. Validate it in one function both sides call, and add a case to\n `TestResourceValidatorsRejectWhatEffectiveValidationRejects` in\n `validators_agree_test.go`, so the file and the resource cannot disagree.\n5. Decide whether it reloads: it does only if every consumer re-reads it from\n `config.Holder`. The allowlist is `internal/app/archied/reload.go`; anything\n not on it requires a restart.\n6. If the settings page shows it as a plain field, add it to\n `internal/webui/config_schema.go` and the view in `api_config.go`.\n\n## Every new field\n\n- Test through the layering: build the effective config the way boot does,\n not by setting the field on the consumer.\n- Add a commented example to `config.example.toml`. Touch `deployments/*.toml`\n only when a profile there needs a value different from the default.\n- Update the wiring matrix in `.agents/skills/archie-config-and-flags`.\n- Secrets are `SecretRef`s resolved through the secret registry. Never inspect\n a resolved value, even in a test.\n- Reject a configuration that sets a field with no consumer rather than\n accepting and ignoring it (per-identity `forge.intake` is the precedent).\n"
"body": "# Control plane and settings\n\nAuthority: `docs/architecture/configuration.md`. The wiring matrix, the\ndecoded-but-unwired ledger and the three shapes an unwired field takes are in\n`.agents/skills/archie-config-and-flags`.\n\nA field that parses is not a field that works. Before adding one, name the code\nthat reads it and the path the value takes to get there.\n\n## Decide what kind of setting it is\n\n- **Bootstrap-only** (read once at process start: `database_url`, `state_dir`,\n `work_dir`). It stays in the file, is checked by `validateBootstrap` in\n `internal/infrastructure/configuration/validate.go`, and the runtime overlay\n refuses changes to it.\n- **Database-owned** (repository policies, scheduling, tools, plugins,\n channels, containers). The file only seeds it. Once the State Store holds the\n control-plane resource, the stored document is layered over the file\n (`controlplane.Client.RuntimeConfig`) and the file key stops mattering. It is\n checked by `validateDatabaseOwned` and by the resource's validator.\n- **Worker-carried.** A value the agent container needs travels in\n `config.TaskConfig` (`Config.ForTask`) or on `taskrun.Request`. Never pass it\n as an environment variable the daemon did not already define, and never carry\n a secret this way.\n\n## Adding a database-owned field\n\n1. Add it to the struct the resource's `Document` names in\n `internal/app/controlplane/operational_settings.go`. The resource's JSON\n schema and the dashboard's Advanced settings editor are generated from that\n type, so no UI work is needed for the editor itself.\n2. Stored documents use Go field names as keys (`Image`, `MaxConcurrency`).\n Give the field no `json` tag unless its neighbours have one.\n3. A map or a nested struct needs its layering checked. `json.Unmarshal`\n merges into an existing map, so a stored map would add to the file's rather\n than replace it. A field the stored document omits keeps the file's value\n (a document stored before the field existed). Add a case to\n `internal/app/controlplane/runtime_config_test.go` for both.\n4. Validate it in one function both sides call, and add a case to\n `TestResourceValidatorsRejectWhatEffectiveValidationRejects` in\n `validators_agree_test.go`, so the file and the resource cannot disagree.\n5. Decide whether it reloads: it does only if every consumer re-reads it from\n `config.Holder`. The allowlist is `internal/app/archied/reload.go`; anything\n not on it requires a restart.\n6. If the settings page shows it as a plain field, add it to\n `internal/webui/config_schema.go` and the view in `api_config.go`.\n\n## Every new field\n\n- Test through the layering: build the effective config the way boot does,\n not by setting the field on the consumer.\n- Add a commented example to `config.example.toml`. Touch `deployments/*.toml`\n only when a profile there needs a value different from the default.\n- Update the wiring matrix in `.agents/skills/archie-config-and-flags`.\n- Secrets are `SecretRef`s resolved through the secret registry. Never inspect\n a resolved value, even in a test.\n- Reject a configuration that sets a field with no consumer rather than\n accepting and ignoring it (per-identity `forge.intake` is the precedent).\n"
},
{
"url": "/dev/development/dashboard/",
"title": "Dashboard",
"url": "/dev/development/daemon/",
"title": "Daemon",
"section": "Development",
"body": "# Dashboard\n\nAuthority: `.agents/skills/archie-web-ui` (stack facts, design-system rules,\ntone and accessibility). This page covers what a change must reach, not how it\nshould look.\n\n## Adding or changing a feature\n\n1. The feature lives in `ui/src/\u003cfeature\u003e/`. Move a helper to `ui/src/base/`\n only when a second feature needs it.\n2. Keep wire shapes, draft state and payload building in a plain `.ts` module\n beside the components (`ui/src/bindings/binding-draft.ts` is the pattern),\n and test it in `ui/test/*.test.ts`. Components stay thin.\n3. Every mutation goes through `api.*` in `ui/src/lib/api`, which sends the\n CSRF and Content-Type headers the server's mutation guard requires. A bare\n `fetch` is refused.\n4. A value the server also describes (task statuses, actions, workflow inputs)\n comes from the server. Keep a local default only so the first render works,\n and keep it in step (`ui/src/lib/task-meta.ts`).\n5. Run `task ui`, `task test:ui` and `cd ui \u0026\u0026 npm run typecheck`. Commit the\n regenerated `ui/dist/`; the Go binaries embed it.\n\n## Adding an API route\n\n1. The handler goes in the `internal/webui/api_\u003cconcern\u003e.go` file for its\n concern. Check the request fully on the server; the UI's checks are only a\n convenience.\n2. A mutation calls `authorizeTaskMutation` first.\n3. A route whose store is not configured answers 503, and\n `internal/app/archieui/degraded_routes_test.go` pins what each route\n returns without its contract. Add the route there.\n4. The dashboard runs in its own process (`archie-ui`) and must not link the\n daemon or the workflow engine (`cmd/archie-ui/architecture_test.go`). Reach\n stored data through `storecontract` interfaces wired in\n `internal/app/archieui/compose.go`.\n5. Settings that live in a control-plane resource need no new route: the\n Advanced settings page edits every resource from its generated schema.\n"
"body": "# Daemon\n\nThe daemon claims and runs tasks, and turns captured events into tasks through\nbindings. This page covers both.\n\n## Task lifecycle\n\nAuthority: `docs/architecture/agent-system.md`. The status vocabulary lives in\n`internal/taskstate`, which imports no internal package.\n\n### Adding a status\n\n1. Add the constant to `internal/taskstate/taskstate.go` and place it in\n `Terminal`, `Actions` and `Statuses`. Its value is stored, so renaming it\n later is a migration.\n2. Alias it in `internal/domain/workflow/task/task.go` and\n `internal/domain/workflow/task_aliases.go`.\n3. Add it to the default catalog in `ui/src/lib/task-meta.ts`. The server\n catalog replaces the defaults when it loads, but the defaults render first.\n4. Find every hand-written status list in SQL:\n `grep -rn \"'merged'\" internal/infrastructure/postgres/queries`.\n `ClearTerminalTasks` must match `taskstate.Terminal`, which\n `TestClearTerminalTasksMatchesTaskstate` enforces. The stats queries count\n outcomes by name; decide whether the new status counts.\n5. Extend the table in `taskstate_test.go`.\n\n### Adding a task field\n\nFollow [State Store](/dev/development/state-store/) for the\ncolumn and the wire. Then decide who writes it: `UpdateTask` writes a fixed\ncolumn set, so a field set at enqueue needs its own statement (as\n`StampTaskBinding` does for binding provenance and inputs).\n\n### Changing what the agent receives\n\n- The task brief is `container.TaskPayload`, written to\n `\u003cworkspace\u003e/.git/task.json` by `WriteTaskJSON`. Never write it to the\n workspace root: the commit stage stages everything there.\n- The run request is `taskrun.Request`. `Validate` rejects a request that\n cannot run; a new requirement goes there.\n- Parking always carries a class (`taskstate.ParkTransient`,\n `ParkNeedsHuman`, `ParkTerminal`) chosen by the code that parks. Pick the one\n that says what an operator must do.\n- A task with no repository (`Task.HasRepository`) runs in a scratch workspace\n with no worktree grant. Code that assumes an owner and repo must check first.\n\n## Event automation\n\nAuthority: `docs/prds/event-automation.md` (the model: source, event type,\nmapping, binding, workflow, profile) and `docs/architecture/bindings.md`\n(threat model).\n\n### Where each check lives\n\nA binding is checked twice, and a new rule usually belongs in both places:\n\n- **On save**, in `checkedBinding` (`internal/webui/api_binding.go`), so the\n operator sees the problem while editing. It calls the domain checks\n `binding.Validate`, `binding.CompileFilter` and `Binding.CheckWorkflow`.\n- **At dispatch**, in `dispatchOneBinding` and `resolveBindingTarget`\n (`internal/daemon`), because the workflow or mapping may have changed since\n the save. A refusal is recorded with `recordDispatchFailure` and starts no\n task.\n\nPut the rule itself in `internal/domain/binding` or\n`internal/domain/workflow/task` and call it from both, rather than writing it\ntwice.\n\n### Adding a binding field\n\n1. Domain type and `Validate` in `internal/domain/binding`.\n2. Column, queries, store mapping, wire field, `newColumns`\n ([State Store](/dev/development/state-store/)).\n3. The request type and `checkedBinding` in `api_binding.go`.\n4. The draft, payload and editor in `ui/src/bindings/`\n ([Frontend UI](/dev/development/frontend-ui/)).\n5. Its effect at dispatch, with a case in\n `internal/daemon/dispatch_inputs_test.go` or `dispatch_bindings_test.go`.\n\n### Rules that must hold\n\n- Signing belongs to the source. Intake verifies the HMAC against the source's\n secret before the payload is parsed.\n- An event must be identified as an event type before anything dispatches it,\n and a binding applies only to its mapping's event type. Dispatch test\n fixtures therefore create an event type before inserting captures.\n- The dispatch ledger is claimed before the task is enqueued (at most once).\n- Anything an event supplies that selects what the agent acts on, such as a\n repository, must be checked against configuration. An event never widens\n what an agent can reach.\n"
},
{
"url": "/dev/development/event-automation/",
"title": "Event automation",
"url": "/dev/development/frontend-ui/",
"title": "Frontend UI",
"section": "Development",
"body": "# Event automation\n\nAuthority: `docs/prds/event-automation.md` (the model: source, event type,\nmapping, binding, workflow, profile) and `docs/architecture/bindings.md`\n(threat model).\n\n## Where each check lives\n\nA binding is checked twice, and a new rule usually belongs in both places:\n\n- **On save**, in `checkedBinding` (`internal/webui/api_binding.go`), so the\n operator sees the problem while editing. It calls the domain checks\n `binding.Validate`, `binding.CompileFilter` and `Binding.CheckWorkflow`.\n- **At dispatch**, in `dispatchOneBinding` and `resolveBindingTarget`\n (`internal/daemon`), because the workflow or mapping may have changed since\n the save. A refusal is recorded with `recordDispatchFailure` and starts no\n task.\n\nPut the rule itself in `internal/domain/binding` or\n`internal/domain/workflow/task` and call it from both, rather than writing it\ntwice.\n\n## Adding a binding field\n\n1. Domain type and `Validate` in `internal/domain/binding`.\n2. Column, queries, store mapping, wire field, `newColumns`\n ([State Store and persistence](/dev/development/state-store-and-persistence/)).\n3. The request type and `checkedBinding` in `api_binding.go`.\n4. The draft, payload and editor in `ui/src/bindings/`\n ([Dashboard](/dev/development/dashboard/)).\n5. Its effect at dispatch, with a case in\n `internal/daemon/dispatch_inputs_test.go` or `dispatch_bindings_test.go`.\n\n## Rules that must hold\n\n- Signing belongs to the source. Intake verifies the HMAC against the source's\n secret before the payload is parsed.\n- An event must be identified as an event type before anything dispatches it,\n and a binding applies only to its mapping's event type. Dispatch test\n fixtures therefore create an event type before inserting captures.\n- The dispatch ledger is claimed before the task is enqueued (at most once).\n- Anything an event supplies that selects what the agent acts on, such as a\n repository, must be checked against configuration. An event never widens\n what an agent can reach.\n"
"body": "# Frontend UI\n\nAuthority: `.agents/skills/archie-web-ui` (stack facts, design-system rules,\ntone and accessibility). This page covers what a change must reach, not how it\nshould look.\n\n## Adding or changing a feature\n\n1. The feature lives in `ui/src/\u003cfeature\u003e/`. Move a helper to `ui/src/base/`\n only when a second feature needs it.\n2. Keep wire shapes, draft state and payload building in a plain `.ts` module\n beside the components (`ui/src/bindings/binding-draft.ts` is the pattern),\n and test it in `ui/test/*.test.ts`. Components stay thin.\n3. Every mutation goes through `api.*` in `ui/src/lib/api`, which sends the\n CSRF and Content-Type headers the server's mutation guard requires. A bare\n `fetch` is refused.\n4. A value the server also describes (task statuses, actions, workflow inputs)\n comes from the server. Keep a local default only so the first render works,\n and keep it in step (`ui/src/lib/task-meta.ts`).\n5. Run `task ui`, `task test:ui` and `cd ui \u0026\u0026 npm run typecheck`. Commit the\n regenerated `ui/dist/`; the Go binaries embed it.\n\n## Adding an API route\n\n1. The handler goes in the `internal/webui/api_\u003cconcern\u003e.go` file for its\n concern. Check the request fully on the server; the UI's checks are only a\n convenience.\n2. A mutation calls `authorizeTaskMutation` first.\n3. A route whose store is not configured answers 503, and\n `internal/app/archieui/degraded_routes_test.go` pins what each route\n returns without its contract. Add the route there.\n4. The dashboard runs in its own process (`archie-ui`) and must not link the\n daemon or the workflow engine (`cmd/archie-ui/architecture_test.go`). Reach\n stored data through `storecontract` interfaces wired in\n `internal/app/archieui/compose.go`.\n5. Settings that live in a control-plane resource need no new route: the\n Advanced settings page edits every resource from its generated schema.\n"
},
{
"url": "/dev/development/merging-work/",
@@ -139,28 +139,22 @@
"body": "# Merging work\n\nParallel lanes (see `.agents/skills/archie-agent-fleet`) merge into an\nintegration branch before `main`. Each merge is a change in its own right and\npasses the same gate.\n\n## Resolving conflicts\n\n- **Generated files** (`*.pb.go`, `postgresdb/*.go`, `ui/dist/`,\n `docs/data/generated/*.json`): take either side, then regenerate. Never merge\n them by hand.\n- **One side deletes a file, the other edits it**: the deletion wins when the\n deleting lane replaced the thing the file served. Move the other side's\n change onto its replacement.\n- **One side changes how code is built (a new store, renamed packages), the\n other what it does**: take the behaviour side's version and reapply the\n mechanical change to it. That is usually cleaner than merging line by line.\n- **Error sentinels** are rows in `wireErrors`, not switch cases.\n\n## After resolving\n\n1. Search for leftovers of anything the other side removed: the old package\n path, the old type, and comments describing the old behaviour.\n2. Tests written against one side's semantics may pass there and fail after\n the merge. A test that used to pass on the old store may be asserting a rule\n the other side deliberately changed. Fix the test's setup to the merged\n rule; do not loosen the rule to the test.\n3. Run the full suite without `-short`, then `task check`, then commit. Check\n `git status` for files a test wrote into the tree before staging.\n"
},
{
"url": "/dev/development/processes-and-wiring/",
"url": "/dev/development/state-store/",
"title": "State Store",
"section": "Development",
"body": "# State Store\n\nAuthority: `docs/prds/state-store-contract.md` and the State Store section of\n`CLAUDE.md`. All persistence is PostgreSQL behind the standalone State Store\nprocess; nothing else opens the database.\n\n## Adding a column\n\n1. Write the next migration in `internal/infrastructure/postgres/migrations/`\n (`00NN_name.sql`, goose Up and Down). Give the column a `NOT NULL DEFAULT`\n that is correct for existing rows.\n2. Update the queries in `internal/infrastructure/postgres/queries/` and\n regenerate with sqlc. A query that lists columns (`ListTaskSummaries`, the\n binding selects) does not pick the new one up; `SELECT *` queries do.\n3. Map it in the store (`taskFromRow`, `bindingValue` and friends). If the\n column holds encoded data, the package that owns the type owns the encoding\n (`task.EncodeInputs`), and the store and the wire both use it.\n4. Add the column to `newColumns` in\n `internal/infrastructure/legacyimport/load.go` if legacy data has no value\n for it. The importer refuses a target column it cannot fill otherwise.\n5. Carry it over the wire (next section) if any process other than the State\n Store reads it.\n\n## Adding a field to a wire message\n\n1. Add it to `proto/state/v1/state.proto` with a new field number. Never reuse\n a number; retire one with `deprecated = true`.\n2. `task proto:generate`, then map it both ways in\n `internal/infrastructure/staterpc/values.go`.\n3. `TestTaskProtoCarriesEveryDomainField` fills every `task.Task` field and\n fails on one the mapping forgets. If it cannot fill the field's kind, extend\n it. Other messages have no such test, so add a round trip to\n `conformance_test.go`.\n\n## Adding an RPC or a store method\n\n1. Put the Go method on the narrow consumer interface in\n `internal/domain/storecontract` (keep each at eight methods or fewer) and add\n the matching RPC. A Go method without an RPC does not cross the process.\n2. Implement it in the Postgres store, in `staterpc.Client` (with its `var _`\n assertion) and in `staterpc.server`. A missing dependency answers\n `codes.Unavailable`, never a fabricated default.\n3. Wire the dependency in every composition that serves or consumes it:\n `stateStoreDeps` in `internal/app/archied/state_store.go`, the daemon's\n assertions in `bootstrap.go`, and `internal/app/archieui/compose.go` for the\n dashboard process.\n4. Task-scoped tokens may call only `Update`, `Transition` and `InsertEvent` on\n their own task (`staterpc.TaskGrants`). A new RPC is admin-only unless it is\n added there deliberately.\n5. Add it to `conformance_test.go`, which runs every surface over a real gRPC\n connection.\n\n## Adding an error sentinel\n\nAdd the sentinel to `storecontract`, a row to `wireErrors` in `values.go`, and\na case to `error_test.go`. The canonical message is part of the wire contract:\nchanging it breaks `errors.Is` on the client silently.\n"
},
{
"url": "/dev/development/wiring/",
"title": "Processes and wiring",
"section": "Development",
"body": "# Processes and wiring\n\nAuthority: `docs/architecture/organisation.md` (layers, process boundaries),\n`docs/architecture/dependencies-and-contracts.md` (dependency direction, wire\ncontracts) and `docs/architecture/plugins-and-extensions.md` (the plugin engine\nrule).\n\n## Placing new code\n\n- Domain logic, entities and the interfaces it needs go in\n `internal/domain/\u003carea\u003e/`, which imports no infrastructure or app package.\n- Implementations of those interfaces go in `internal/infrastructure/\u003cservice\u003e/`.\n- Construction and wiring go in `internal/app/\u003capplication\u003e/`; `cmd/` only\n parses flags and calls it.\n- `logging`, `events`, `eventbus`, `policy` and `taskstate` import no internal\n package. There is no `shared/`, `utils/` or `common/` package.\n- A behaviour has one authoritative path. Before adding a second way to do\n something, remove or redirect the first.\n\n## Adding a capability to a process\n\n1. Decide which process owns it. A new binary is justified only when the\n surface must fail, scale or run somewhere independently.\n2. Wire it at that process's composition root. An optional capability\n degrades: a missing provider logs a warning and marks health degraded\n rather than stopping the process (MCP providers are the model).\n3. Every process that reaches the capability through the State Store gets it\n through a `storecontract` interface asserted on the client\n ([State Store and persistence](/dev/development/state-store-and-persistence/)).\n4. The architecture tests (`cmd/archie-ui/architecture_test.go`,\n `cmd/archie-messaging/architecture_test.go`, `TestOpenStoresNeverOwnsTaskDB`)\n pin what each binary may link. A failure there means the placement is wrong,\n not the test.\n\n## Adding a plugin engine\n\nSatisfy every invariant in \"Plugin engine rule (strict)\" in\n`plugins-and-extensions.md`: typed domain contract, an owning manager,\nlifecycle and health, narrow host access, and an explicit trust boundary.\n`internal/plugin/architecture_test.go` checks the parts that can be checked.\n\n## Adding a channel or a NATS subject\n\n- Channel rules (Telegram's pending-update drop, command scopes) are in\n `CLAUDE.md` under Per-Package Invariants.\n- A subject is part of the wire contract. Its payload type belongs to the\n domain that defines its meaning, and the transport code lives in\n infrastructure.\n"
"body": "# Processes and wiring\n\nAuthority: `docs/architecture/organisation.md` (layers, process boundaries),\n`docs/architecture/dependencies-and-contracts.md` (dependency direction, wire\ncontracts) and `docs/architecture/plugins-and-extensions.md` (the plugin engine\nrule).\n\n## Placing new code\n\n- Domain logic, entities and the interfaces it needs go in\n `internal/domain/\u003carea\u003e/`, which imports no infrastructure or app package.\n- Implementations of those interfaces go in `internal/infrastructure/\u003cservice\u003e/`.\n- Construction and wiring go in `internal/app/\u003capplication\u003e/`; `cmd/` only\n parses flags and calls it.\n- `logging`, `events`, `eventbus`, `policy` and `taskstate` import no internal\n package. There is no `shared/`, `utils/` or `common/` package.\n- A behaviour has one authoritative path. Before adding a second way to do\n something, remove or redirect the first.\n\n## Adding a capability to a process\n\n1. Decide which process owns it. A new binary is justified only when the\n surface must fail, scale or run somewhere independently.\n2. Wire it at that process's composition root. An optional capability\n degrades: a missing provider logs a warning and marks health degraded\n rather than stopping the process (MCP providers are the model).\n3. Every process that reaches the capability through the State Store gets it\n through a `storecontract` interface asserted on the client\n ([State Store](/dev/development/state-store/)).\n4. The architecture tests (`cmd/archie-ui/architecture_test.go`,\n `cmd/archie-messaging/architecture_test.go`, `TestOpenStoresNeverOwnsTaskDB`)\n pin what each binary may link. A failure there means the placement is wrong,\n not the test.\n\n## Adding a plugin engine\n\nSatisfy every invariant in \"Plugin engine rule (strict)\" in\n`plugins-and-extensions.md`: typed domain contract, an owning manager,\nlifecycle and health, narrow host access, and an explicit trust boundary.\n`internal/plugin/architecture_test.go` checks the parts that can be checked.\n\n## Adding a channel or a NATS subject\n\n- Channel rules (Telegram's pending-update drop, command scopes) are in\n `CLAUDE.md` under Per-Package Invariants.\n- A subject is part of the wire contract. Its payload type belongs to the\n domain that defines its meaning, and the transport code lives in\n infrastructure.\n"
},
{
"url": "/dev/development/state-store-and-persistence/",
"title": "State Store and persistence",
"url": "/dev/development/workflows/",
"title": "Workflows",
"section": "Development",
"body": "# State Store and persistence\n\nAuthority: `docs/prds/state-store-contract.md` and the State Store section of\n`CLAUDE.md`. All persistence is PostgreSQL behind the standalone State Store\nprocess; nothing else opens the database.\n\n## Adding a column\n\n1. Write the next migration in `internal/infrastructure/postgres/migrations/`\n (`00NN_name.sql`, goose Up and Down). Give the column a `NOT NULL DEFAULT`\n that is correct for existing rows.\n2. Update the queries in `internal/infrastructure/postgres/queries/` and\n regenerate with sqlc. A query that lists columns (`ListTaskSummaries`, the\n binding selects) does not pick the new one up; `SELECT *` queries do.\n3. Map it in the store (`taskFromRow`, `bindingValue` and friends). If the\n column holds encoded data, the package that owns the type owns the encoding\n (`task.EncodeInputs`), and the store and the wire both use it.\n4. Add the column to `newColumns` in\n `internal/infrastructure/legacyimport/load.go` if legacy data has no value\n for it. The importer refuses a target column it cannot fill otherwise.\n5. Carry it over the wire (next section) if any process other than the State\n Store reads it.\n\n## Adding a field to a wire message\n\n1. Add it to `proto/state/v1/state.proto` with a new field number. Never reuse\n a number; retire one with `deprecated = true`.\n2. `task proto:generate`, then map it both ways in\n `internal/infrastructure/staterpc/values.go`.\n3. `TestTaskProtoCarriesEveryDomainField` fills every `task.Task` field and\n fails on one the mapping forgets. If it cannot fill the field's kind, extend\n it. Other messages have no such test, so add a round trip to\n `conformance_test.go`.\n\n## Adding an RPC or a store method\n\n1. Put the Go method on the narrow consumer interface in\n `internal/domain/storecontract` (keep each at eight methods or fewer) and add\n the matching RPC. A Go method without an RPC does not cross the process.\n2. Implement it in the Postgres store, in `staterpc.Client` (with its `var _`\n assertion) and in `staterpc.server`. A missing dependency answers\n `codes.Unavailable`, never a fabricated default.\n3. Wire the dependency in every composition that serves or consumes it:\n `stateStoreDeps` in `internal/app/archied/state_store.go`, the daemon's\n assertions in `bootstrap.go`, and `internal/app/archieui/compose.go` for the\n dashboard process.\n4. Task-scoped tokens may call only `Update`, `Transition` and `InsertEvent` on\n their own task (`staterpc.TaskGrants`). A new RPC is admin-only unless it is\n added there deliberately.\n5. Add it to `conformance_test.go`, which runs every surface over a real gRPC\n connection.\n\n## Adding an error sentinel\n\nAdd the sentinel to `storecontract`, a row to `wireErrors` in `values.go`, and\na case to `error_test.go`. The canonical message is part of the wire contract:\nchanging it breaks `errors.Is` on the client silently.\n"
},
{
"url": "/dev/development/task-lifecycle/",
"title": "Task lifecycle",
"section": "Development",
"body": "# Task lifecycle\n\nAuthority: `docs/architecture/agent-system.md`. The status vocabulary lives in\n`internal/taskstate`, which imports no internal package.\n\n## Adding a status\n\n1. Add the constant to `internal/taskstate/taskstate.go` and place it in\n `Terminal`, `Actions` and `Statuses`. Its value is stored, so renaming it\n later is a migration.\n2. Alias it in `internal/domain/workflow/task/task.go` and\n `internal/domain/workflow/task_aliases.go`.\n3. Add it to the default catalog in `ui/src/lib/task-meta.ts`. The server\n catalog replaces the defaults when it loads, but the defaults render first.\n4. Find every hand-written status list in SQL:\n `grep -rn \"'merged'\" internal/infrastructure/postgres/queries`.\n `ClearTerminalTasks` must match `taskstate.Terminal`, which\n `TestClearTerminalTasksMatchesTaskstate` enforces. The stats queries count\n outcomes by name; decide whether the new status counts.\n5. Extend the table in `taskstate_test.go`.\n\n## Adding a task field\n\nFollow [State Store and persistence](/dev/development/state-store-and-persistence/) for the\ncolumn and the wire. Then decide who writes it: `UpdateTask` writes a fixed\ncolumn set, so a field set at enqueue needs its own statement (as\n`StampTaskBinding` does for binding provenance and inputs).\n\n## Changing what the agent receives\n\n- The task brief is `container.TaskPayload`, written to\n `\u003cworkspace\u003e/.git/task.json` by `WriteTaskJSON`. Never write it to the\n workspace root: the commit stage stages everything there.\n- The run request is `taskrun.Request`. `Validate` rejects a request that\n cannot run; a new requirement goes there.\n- Parking always carries a class (`taskstate.ParkTransient`,\n `ParkNeedsHuman`, `ParkTerminal`) chosen by the code that parks. Pick the one\n that says what an operator must do.\n- A task with no repository (`Task.HasRepository`) runs in a scratch workspace\n with no worktree grant. Code that assumes an owner and repo must check first.\n"
},
{
"url": "/dev/development/workflows-and-steps/",
"title": "Workflows and steps",
"section": "Development",
"body": "# Workflows and steps\n\nAuthority: `docs/architecture/agent-system.md` for the lifecycle,\n`docs/prds/event-automation.md` for inputs, repository modes and profiles.\n\nWorkflow definitions are YAML stored as a control-plane resource. The State\nStore validates them and the agent compiles them, each against the step\nvocabulary it registers, so both must see the same step types.\n\n## Adding a step type\n\n1. Write the factory in `internal/domain/workflow` as a `StepType`. It decodes\n and validates its settings and returns an error for anything it cannot\n honour. The factory runs when a definition is saved and again when it is\n compiled, so a bad definition is refused on save.\n2. Register it through a provider in\n `internal/infrastructure/workflowsteps/workflowsteps.go`. That one list is\n what every process registers, which is how the validating and executing\n sides agree.\n3. An agent-driven step builds on `AgentStage`; do not start a second path to\n the agent runner.\n4. A step that needs no repository goes in `repoFreeStepTypes` in\n `definition.go`, or workflows declaring `repository: none` or `optional`\n cannot use it. A step that needs one may assume `tc.Dir` holds a worktree\n only when the workflow's repository is `required`.\n5. A step that ends the workflow sets `tc.Outcome`. A workflow that runs out of\n steps without an outcome is parked as a definition bug.\n6. Add a parse test (settings accepted and refused) and a run test with fake\n `Trees` and agent runner.\n\n## Changing the definition format\n\n- The fields a caller needs without the engine (inputs, repository, profile)\n live in `task.WorkflowInterface`, because the dashboard process must not\n import the workflow engine (`cmd/archie-ui/architecture_test.go`). Anything a\n binding or the dashboard checks goes there.\n- The YAML decoder rejects unknown keys. Existing stored definitions must keep\n parsing, so a new key is optional with a default that preserves today's\n behaviour.\n- Examples in `examples/workflows/` are parsed against the registered\n vocabulary by `TestExampleWorkflowsParse`. Add one for a new capability.\n"
"body": "# Workflows\n\nAuthority: `docs/architecture/agent-system.md` for the lifecycle,\n`docs/prds/event-automation.md` for inputs, repository modes and profiles.\n\nWorkflow definitions are YAML stored as a control-plane resource. The State\nStore validates them and the agent compiles them, each against the step\nvocabulary it registers, so both must see the same step types.\n\n## Adding a step type\n\n1. Write the factory in `internal/domain/workflow` as a `StepType`. It decodes\n and validates its settings and returns an error for anything it cannot\n honour. The factory runs when a definition is saved and again when it is\n compiled, so a bad definition is refused on save.\n2. Register it through a provider in\n `internal/infrastructure/workflowsteps/workflowsteps.go`. That one list is\n what every process registers, which is how the validating and executing\n sides agree.\n3. An agent-driven step builds on `AgentStage`; do not start a second path to\n the agent runner.\n4. A step that needs no repository goes in `repoFreeStepTypes` in\n `definition.go`, or workflows declaring `repository: none` or `optional`\n cannot use it. A step that needs one may assume `tc.Dir` holds a worktree\n only when the workflow's repository is `required`.\n5. A step that ends the workflow sets `tc.Outcome`. A workflow that runs out of\n steps without an outcome is parked as a definition bug.\n6. Add a parse test (settings accepted and refused) and a run test with fake\n `Trees` and agent runner.\n\n## Changing the definition format\n\n- The fields a caller needs without the engine (inputs, repository, profile)\n live in `task.WorkflowInterface`, because the dashboard process must not\n import the workflow engine (`cmd/archie-ui/architecture_test.go`). Anything a\n binding or the dashboard checks goes there.\n- The YAML decoder rejects unknown keys. Existing stored definitions must keep\n parsing, so a new key is optional with a default that preserves today's\n behaviour.\n- Examples in `examples/workflows/` are parsed against the registered\n vocabulary by `TestExampleWorkflowsParse`. Add one for a new capability.\n"
},
{
"url": "/dev/prds/01-project-management/",
@@ -593,40 +587,36 @@
"url": "/dev/development/",
"items": [
{
"title": "Agent execution and containers",
"url": "/dev/development/agent-execution-and-containers/"
"title": "Agent",
"url": "/dev/development/agent/"
},
{
"title": "Configuration settings",
"url": "/dev/development/config-settings/"
"title": "Control plane and settings",
"url": "/dev/development/control-plane/"
},
{
"title": "Dashboard",
"url": "/dev/development/dashboard/"
"title": "Daemon",
"url": "/dev/development/daemon/"
},
{
"title": "Event automation",
"url": "/dev/development/event-automation/"
"title": "Frontend UI",
"url": "/dev/development/frontend-ui/"
},
{
"title": "Merging work",
"url": "/dev/development/merging-work/"
},
{
"title": "State Store",
"url": "/dev/development/state-store/"
},
{
"title": "Processes and wiring",
"url": "/dev/development/processes-and-wiring/"
"url": "/dev/development/wiring/"
},
{
"title": "State Store and persistence",
"url": "/dev/development/state-store-and-persistence/"
},
{
"title": "Task lifecycle",
"url": "/dev/development/task-lifecycle/"
},
{
"title": "Workflows and steps",
"url": "/dev/development/workflows-and-steps/"
"title": "Workflows",
"url": "/dev/development/workflows/"
}
]
},
+1 -1
View File
@@ -4,7 +4,7 @@
"url": "/docs/",
"title": "Archie",
"section": "",
"body": "# Archie\n\nEvent Driven Agentic Automation.\n\nArchie is an agent platform that reacts to events. A forge issue, a signed\nwebhook from any app you run, a message in a chat channel: each arrives as an\nevent, a playbook decides what a matching event sets off, and the work happens\nin an isolated git worktree. GitHub and Gitea issues were the first case. A\nforge is now one event source among several, and a pull request one outcome\namong several.\n\nNothing about that path is wired to a particular forge, channel, or sender.\nSources, the fields they carry, and the workflows they reach are configuration\nyou add without touching code or restarting anything.\n\n## Start here\n\n- [First playbook](/docs/guides/first-playbook/) points an external app's webhook\n at archie, maps the fields of a real payload, and binds them to a workflow.\n- [Architecture](/dev/architecture/) is the authority for settled design:\n the domain boundaries, the workflow engine, the task lifecycle, and the\n invariants that hold the whole thing together.\n- [Development guides](/dev/development/) list everything a change of each\n kind must reach: settings, persistence, tasks, workflows, bindings, the\n dashboard, containers and process wiring.\n\n## What runs where\n\nA deployment is a set of services, each owning one typed contract. The Gateway\nserves conversation turns and sessions, the Messaging Service runs the\nchannels, the State Store owns the database outright, the dashboard is its own\nprocess, and `archied` admits work and drives each task through its workflow.\ngRPC carries the synchronous calls between them; NATS carries asynchronous\nfan-out. Agents execute in containers that receive a task-scoped credential,\nissued per task and revoked when the worktree is handed back.\n\nConfiguration lives at `${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`.\nNothing in a working tree is load-bearing at runtime.\n\n## A note on these docs\n\nThis site is generated from the `docs/` directory of the\n[archie-core repository](https://github.com/samcharles93/archie-core) on every\nchange to `main`. The repository is the source; this site is a view of it. If\nthe two ever disagree, the repository is right.\n"
"body": "# Archie\n\nEvent Driven Agentic Automation.\n\nArchie is an agent platform that reacts to events. A forge issue, a signed\nwebhook from any app you run, a message in a chat channel: each arrives as an\nevent, a playbook decides what a matching event sets off, and the work happens\nin an isolated git worktree. GitHub and Gitea issues were the first case. A\nforge is now one event source among several, and a pull request one outcome\namong several.\n\nNothing about that path is wired to a particular forge, channel, or sender.\nSources, the fields they carry, and the workflows they reach are configuration\nyou add without touching code or restarting anything.\n\n## Start here\n\n- [First playbook](/docs/guides/first-playbook/) points an external app's webhook\n at archie, maps the fields of a real payload, and binds them to a workflow.\n- [Architecture](/dev/architecture/) is the authority for settled design:\n the domain boundaries, the workflow engine, the task lifecycle, and the\n invariants that hold the whole thing together.\n- [Development guides](/dev/development/) list, area by area (frontend UI,\n agent, workflows, daemon, State Store, control plane), everything a change\n must reach.\n\n## What runs where\n\nA deployment is a set of services, each owning one typed contract. The Gateway\nserves conversation turns and sessions, the Messaging Service runs the\nchannels, the State Store owns the database outright, the dashboard is its own\nprocess, and `archied` admits work and drives each task through its workflow.\ngRPC carries the synchronous calls between them; NATS carries asynchronous\nfan-out. Agents execute in containers that receive a task-scoped credential,\nissued per task and revoked when the worktree is handed back.\n\nConfiguration lives at `${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`.\nNothing in a working tree is load-bearing at runtime.\n\n## A note on these docs\n\nThis site is generated from the `docs/` directory of the\n[archie-core repository](https://github.com/samcharles93/archie-core) on every\nchange to `main`. The repository is the source; this site is a view of it. If\nthe two ever disagree, the repository is right.\n"
},
{
"url": "/docs/guides/first-playbook/",
@@ -1,4 +1,4 @@
# Agent execution and containers
# Agent
Authority: `docs/architecture/agent-system.md` (execution boundary, the model
never runs git) and the Deployment Model section of `CLAUDE.md`.
@@ -1,4 +1,4 @@
# Configuration settings
# Control plane and settings
Authority: `docs/architecture/configuration.md`. The wiring matrix, the
decoded-but-unwired ledger and the three shapes an unwired field takes are in
+90
View File
@@ -0,0 +1,90 @@
# Daemon
The daemon claims and runs tasks, and turns captured events into tasks through
bindings. This page covers both.
## Task lifecycle
Authority: `docs/architecture/agent-system.md`. The status vocabulary lives in
`internal/taskstate`, which imports no internal package.
### Adding a status
1. Add the constant to `internal/taskstate/taskstate.go` and place it in
`Terminal`, `Actions` and `Statuses`. Its value is stored, so renaming it
later is a migration.
2. Alias it in `internal/domain/workflow/task/task.go` and
`internal/domain/workflow/task_aliases.go`.
3. Add it to the default catalog in `ui/src/lib/task-meta.ts`. The server
catalog replaces the defaults when it loads, but the defaults render first.
4. Find every hand-written status list in SQL:
`grep -rn "'merged'" internal/infrastructure/postgres/queries`.
`ClearTerminalTasks` must match `taskstate.Terminal`, which
`TestClearTerminalTasksMatchesTaskstate` enforces. The stats queries count
outcomes by name; decide whether the new status counts.
5. Extend the table in `taskstate_test.go`.
### Adding a task field
Follow [State Store](state-store.md) for the
column and the wire. Then decide who writes it: `UpdateTask` writes a fixed
column set, so a field set at enqueue needs its own statement (as
`StampTaskBinding` does for binding provenance and inputs).
### Changing what the agent receives
- The task brief is `container.TaskPayload`, written to
`<workspace>/.git/task.json` by `WriteTaskJSON`. Never write it to the
workspace root: the commit stage stages everything there.
- The run request is `taskrun.Request`. `Validate` rejects a request that
cannot run; a new requirement goes there.
- Parking always carries a class (`taskstate.ParkTransient`,
`ParkNeedsHuman`, `ParkTerminal`) chosen by the code that parks. Pick the one
that says what an operator must do.
- A task with no repository (`Task.HasRepository`) runs in a scratch workspace
with no worktree grant. Code that assumes an owner and repo must check first.
## Event automation
Authority: `docs/prds/event-automation.md` (the model: source, event type,
mapping, binding, workflow, profile) and `docs/architecture/bindings.md`
(threat model).
### Where each check lives
A binding is checked twice, and a new rule usually belongs in both places:
- **On save**, in `checkedBinding` (`internal/webui/api_binding.go`), so the
operator sees the problem while editing. It calls the domain checks
`binding.Validate`, `binding.CompileFilter` and `Binding.CheckWorkflow`.
- **At dispatch**, in `dispatchOneBinding` and `resolveBindingTarget`
(`internal/daemon`), because the workflow or mapping may have changed since
the save. A refusal is recorded with `recordDispatchFailure` and starts no
task.
Put the rule itself in `internal/domain/binding` or
`internal/domain/workflow/task` and call it from both, rather than writing it
twice.
### Adding a binding field
1. Domain type and `Validate` in `internal/domain/binding`.
2. Column, queries, store mapping, wire field, `newColumns`
([State Store](state-store.md)).
3. The request type and `checkedBinding` in `api_binding.go`.
4. The draft, payload and editor in `ui/src/bindings/`
([Frontend UI](frontend-ui.md)).
5. Its effect at dispatch, with a case in
`internal/daemon/dispatch_inputs_test.go` or `dispatch_bindings_test.go`.
### Rules that must hold
- Signing belongs to the source. Intake verifies the HMAC against the source's
secret before the payload is parsed.
- An event must be identified as an event type before anything dispatches it,
and a binding applies only to its mapping's event type. Dispatch test
fixtures therefore create an event type before inserting captures.
- The dispatch ledger is claimed before the task is enqueued (at most once).
- Anything an event supplies that selects what the agent acts on, such as a
repository, must be checked against configuration. An event never widens
what an agent can reach.
-44
View File
@@ -1,44 +0,0 @@
# Event automation
Authority: `docs/prds/event-automation.md` (the model: source, event type,
mapping, binding, workflow, profile) and `docs/architecture/bindings.md`
(threat model).
## Where each check lives
A binding is checked twice, and a new rule usually belongs in both places:
- **On save**, in `checkedBinding` (`internal/webui/api_binding.go`), so the
operator sees the problem while editing. It calls the domain checks
`binding.Validate`, `binding.CompileFilter` and `Binding.CheckWorkflow`.
- **At dispatch**, in `dispatchOneBinding` and `resolveBindingTarget`
(`internal/daemon`), because the workflow or mapping may have changed since
the save. A refusal is recorded with `recordDispatchFailure` and starts no
task.
Put the rule itself in `internal/domain/binding` or
`internal/domain/workflow/task` and call it from both, rather than writing it
twice.
## Adding a binding field
1. Domain type and `Validate` in `internal/domain/binding`.
2. Column, queries, store mapping, wire field, `newColumns`
([State Store and persistence](state-store-and-persistence.md)).
3. The request type and `checkedBinding` in `api_binding.go`.
4. The draft, payload and editor in `ui/src/bindings/`
([Dashboard](dashboard.md)).
5. Its effect at dispatch, with a case in
`internal/daemon/dispatch_inputs_test.go` or `dispatch_bindings_test.go`.
## Rules that must hold
- Signing belongs to the source. Intake verifies the HMAC against the source's
secret before the payload is parsed.
- An event must be identified as an event type before anything dispatches it,
and a binding applies only to its mapping's event type. Dispatch test
fixtures therefore create an event type before inserting captures.
- The dispatch ledger is claimed before the task is enqueued (at most once).
- Anything an event supplies that selects what the agent acts on, such as a
repository, must be checked against configuration. An event never widens
what an agent can reach.
@@ -1,4 +1,4 @@
# Dashboard
# Frontend UI
Authority: `.agents/skills/archie-web-ui` (stack facts, design-system rules,
tone and accessibility). This page covers what a change must reach, not how it
+15 -15
View File
@@ -1,22 +1,22 @@
# Development guides
Checklists for changing Archie. Each page covers one kind of change and names
every place that change must reach, so a feature that works in one layer does
not silently stop at the next. The pages point at the documents that own the
design (`docs/architecture/`, the PRDs, `CLAUDE.md`) rather than restating
them.
Checklists for changing Archie, one page per area. Each names every place a
change must reach, so a feature that works in one layer does not silently stop
at the next. A change that spans areas starts on the page for the area it
begins in, which points to the others. The pages point at the documents that
own the design (`docs/architecture/`, the PRDs, `CLAUDE.md`) rather than
restating them.
| Changing | Guide |
| Area | Covers |
| --- | --- |
| A setting in `config.toml` or the dashboard | [Configuration settings](config-settings.md) |
| A stored field, table, RPC or error | [State Store and persistence](state-store-and-persistence.md) |
| Task statuses, fields or the task brief | [Task lifecycle](task-lifecycle.md) |
| Workflow definitions or step types | [Workflows and steps](workflows-and-steps.md) |
| Sources, event types, mappings or bindings | [Event automation](event-automation.md) |
| Anything under `ui/` | [Dashboard](dashboard.md) |
| The agent container, its image or its tools | [Agent execution and containers](agent-execution-and-containers.md) |
| A process, plugin engine, channel or NATS subject | [Processes and wiring](processes-and-wiring.md) |
| Merging a lane or a branch | [Merging work](merging-work.md) |
| [Frontend UI](frontend-ui.md) | Anything under `ui/`, and the dashboard's API routes |
| [Agent](agent.md) | The agent container, its image, profiles, tools and workspace |
| [Workflows](workflows.md) | Workflow definitions and step types |
| [Daemon](daemon.md) | Task statuses, fields and the brief; sources, event types, mappings and bindings |
| [State Store](state-store.md) | Stored fields, tables, RPCs and errors |
| [Control plane and settings](control-plane.md) | Settings in `config.toml` or the dashboard |
| [Processes and wiring](wiring.md) | Where code goes, processes, plugin engines, channels, NATS subjects |
| [Merging work](merging-work.md) | Merging a lane or a branch |
## Every change
@@ -1,4 +1,4 @@
# State Store and persistence
# State Store
Authority: `docs/prds/state-store-contract.md` and the State Store section of
`CLAUDE.md`. All persistence is PostgreSQL behind the standalone State Store
-40
View File
@@ -1,40 +0,0 @@
# Task lifecycle
Authority: `docs/architecture/agent-system.md`. The status vocabulary lives in
`internal/taskstate`, which imports no internal package.
## Adding a status
1. Add the constant to `internal/taskstate/taskstate.go` and place it in
`Terminal`, `Actions` and `Statuses`. Its value is stored, so renaming it
later is a migration.
2. Alias it in `internal/domain/workflow/task/task.go` and
`internal/domain/workflow/task_aliases.go`.
3. Add it to the default catalog in `ui/src/lib/task-meta.ts`. The server
catalog replaces the defaults when it loads, but the defaults render first.
4. Find every hand-written status list in SQL:
`grep -rn "'merged'" internal/infrastructure/postgres/queries`.
`ClearTerminalTasks` must match `taskstate.Terminal`, which
`TestClearTerminalTasksMatchesTaskstate` enforces. The stats queries count
outcomes by name; decide whether the new status counts.
5. Extend the table in `taskstate_test.go`.
## Adding a task field
Follow [State Store and persistence](state-store-and-persistence.md) for the
column and the wire. Then decide who writes it: `UpdateTask` writes a fixed
column set, so a field set at enqueue needs its own statement (as
`StampTaskBinding` does for binding provenance and inputs).
## Changing what the agent receives
- The task brief is `container.TaskPayload`, written to
`<workspace>/.git/task.json` by `WriteTaskJSON`. Never write it to the
workspace root: the commit stage stages everything there.
- The run request is `taskrun.Request`. `Validate` rejects a request that
cannot run; a new requirement goes there.
- Parking always carries a class (`taskstate.ParkTransient`,
`ParkNeedsHuman`, `ParkTerminal`) chosen by the code that parks. Pick the one
that says what an operator must do.
- A task with no repository (`Task.HasRepository`) runs in a scratch workspace
with no worktree grant. Code that assumes an owner and repo must check first.
@@ -26,7 +26,7 @@ rule).
rather than stopping the process (MCP providers are the model).
3. Every process that reaches the capability through the State Store gets it
through a `storecontract` interface asserted on the client
([State Store and persistence](state-store-and-persistence.md)).
([State Store](state-store.md)).
4. The architecture tests (`cmd/archie-ui/architecture_test.go`,
`cmd/archie-messaging/architecture_test.go`, `TestOpenStoresNeverOwnsTaskDB`)
pin what each binary may link. A failure there means the placement is wrong,
@@ -1,4 +1,4 @@
# Workflows and steps
# Workflows
Authority: `docs/architecture/agent-system.md` for the lifecycle,
`docs/prds/event-automation.md` for inputs, repository modes and profiles.
+3 -3
View File
@@ -20,9 +20,9 @@ you add without touching code or restarting anything.
- [Architecture](architecture/index.md) is the authority for settled design:
the domain boundaries, the workflow engine, the task lifecycle, and the
invariants that hold the whole thing together.
- [Development guides](development/index.md) list everything a change of each
kind must reach: settings, persistence, tasks, workflows, bindings, the
dashboard, containers and process wiring.
- [Development guides](development/index.md) list, area by area (frontend UI,
agent, workflows, daemon, State Store, control plane), everything a change
must reach.
## What runs where