docs(development): checklists for every kind of change
docs/development/ holds one page per kind of change (settings, State Store and persistence, task lifecycle, workflows and steps, event automation, dashboard, agent execution and containers, processes and wiring, merging work), each naming every layer the change must reach and pointing at the document that owns the design. The docs build puts them in the development set; docs/index.md and CLAUDE.md link them. Also adds the container-profile case to the validator agreement test, the check the profiles work skipped.
This commit is contained in:
1 parent
4046766abe
commit
4fe3bc13ee
17 files changed
+569
-3
No files matched your search
@@ -102,6 +102,66 @@
|
||||
"section": "Architecture",
|
||||
"body": "# Safe Change and Recovery\n\n**Status:** Requirements approved; mechanics are under design. Database-backed settings are implemented through the control plane (2026-09): see the degrade/recovery section below, which records a gap rather than a solution. The full runtime-supervision protocol (bounded observation, versioned audit trail) remains under design.\n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is built and improved by agents as well as humans. The architecture MUST\nmake a change easy to locate, understand, test, audit, extend, and reverse\nwithout requiring its author to understand unrelated parts of the application.\n\nSeparation of concerns is therefore an operational safety boundary, not only a\ncode-organisation preference.\n\n## Required outcomes\n\n- An agent can improve a focused feature without receiving authority over\n unrelated domains.\n- Every event, function, action, setting, and policy has an identifiable owner\n and provenance.\n- Source and runtime changes pass deterministic checks outside the actor making\n the change.\n- A rejected or unhealthy candidate cannot replace the last known working\n version.\n- Invalid user configuration does not terminate an otherwise healthy\n application.\n- Configuration and service failures are observable, attributed, and eligible\n for bounded remediation or rollback.\n- The application continues serving unaffected capabilities when one\n capability is misconfigured or unhealthy.\n- Recovery failure is reported and contained rather than hidden in an\n unbounded retry loop.\n\n## Source changes\n\nAgent-authored source changes occur through the task-execution boundary in an\nisolated workspace. The agent does not directly mutate the running\ninstallation.\n\nPromotion is controlled by deterministic repository-owned policy, including\ntests, generated-reference drift checks, protected paths, change scope, and\nother required gates. The actor proposing a change cannot waive these checks.\n\nRepository and domain separation SHOULD allow a task to load and modify only\nthe governing requirements and code for its declared scope.\n\n## Runtime changes\n\nConfiguration and other runtime changes are proposed as candidates rather than\nmutating the active state in place.\n\nThe affected domain owns:\n\n- the command describing the semantic change;\n- validation of its typed settings;\n- health signals that demonstrate correct operation;\n- domain-specific remediation and rollback consequences.\n\nShared policy supplies consistent evaluation, evidence, and audit mechanics.\nIdentity supplies actor attribution. Infrastructure supplies external\nconfiguration storage, service control, and other operational adapters.\n\n## Runtime change protocol\n\nLast-known-good preservation and candidate promotion are the universal runtime\nchange protocol.\n\n1. An identity proposes an immutable candidate version.\n2. Infrastructure parses it without changing active state.\n3. Each affected domain validates its typed settings.\n4. Shared policy evaluates cross-cutting constraints.\n5. Each affected capability prepares the candidate without destroying its\n active instance.\n6. Capability-specific health checks prove the candidate works.\n7. Runtime supervision atomically promotes the candidate.\n8. A bounded observation period watches for delayed failure.\n9. Failure restores the last-known-good version and records the reason,\n evidence, actor, and involved versions.\n10. Repeated remediation failure stops retrying, isolates the capability, and\n reports the fault.\n\nThe affected domain owns the semantic change command, typed validation, health\nsignals, and remediation consequences. Shared runtime supervision owns the\npromotion transaction. Infrastructure performs storage and service-control\noperations.\n\nThe protocol's exact Go contracts, storage model, atomicity boundary, and\nobservation rules require a focused runtime-supervision design pass.\n\n## Failure isolation\n\nInvalid input MUST leave the active valid configuration unchanged and produce a\ndiagnostic record.\n\nA capability that cannot start or reload SHOULD fail independently where its\nabsence does not violate a declared application invariant. Unaffected\ncapabilities continue operating.\n\nRemediation MUST be bounded, observable, and policy-driven. Recovery MUST NOT\nsilently oscillate between versions or retry forever.\n\n## Database settings: degrade paths and recovery (2026-09)\n\nThe control plane owns runtime-tunable settings and stores them in the State\nStore's PostgreSQL database.\nThis replaced a dashboard overlay store that degraded to file config on any\nfailure and had three documented ways back. The replacement has none, and the\nposture is the opposite: **the daemon fails closed.**\n\n### Degrade paths\n\n| Failure | Boot behaviour | Where the operator sees it |\n| --- | -Line truncated
|
||||
},
|
||||
{
|
||||
"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"
|
||||
},
|
||||
{
|
||||
"url": "/dev/development/agent-execution-and-containers/",
|
||||
"title": "Agent execution and containers",
|
||||
"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"
|
||||
},
|
||||
{
|
||||
"url": "/dev/development/config-settings/",
|
||||
"title": "Configuration 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"
|
||||
},
|
||||
{
|
||||
"url": "/dev/development/dashboard/",
|
||||
"title": "Dashboard",
|
||||
"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"
|
||||
},
|
||||
{
|
||||
"url": "/dev/development/event-automation/",
|
||||
"title": "Event automation",
|
||||
"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"
|
||||
},
|
||||
{
|
||||
"url": "/dev/development/merging-work/",
|
||||
"title": "Merging work",
|
||||
"section": "Development",
|
||||
"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/",
|
||||
"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"
|
||||
},
|
||||
{
|
||||
"url": "/dev/development/state-store-and-persistence/",
|
||||
"title": "State Store and persistence",
|
||||
"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"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/01-project-management/",
|
||||
"title": "Architecture Decision Index",
|
||||
@@ -528,6 +588,48 @@
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Development guides",
|
||||
"url": "/dev/development/",
|
||||
"items": [
|
||||
{
|
||||
"title": "Agent execution and containers",
|
||||
"url": "/dev/development/agent-execution-and-containers/"
|
||||
},
|
||||
{
|
||||
"title": "Configuration settings",
|
||||
"url": "/dev/development/config-settings/"
|
||||
},
|
||||
{
|
||||
"title": "Dashboard",
|
||||
"url": "/dev/development/dashboard/"
|
||||
},
|
||||
{
|
||||
"title": "Event automation",
|
||||
"url": "/dev/development/event-automation/"
|
||||
},
|
||||
{
|
||||
"title": "Merging work",
|
||||
"url": "/dev/development/merging-work/"
|
||||
},
|
||||
{
|
||||
"title": "Processes and wiring",
|
||||
"url": "/dev/development/processes-and-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": "PRDs",
|
||||
"items": [
|
||||
|
||||
@@ -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\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 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"
|
||||
},
|
||||
{
|
||||
"url": "/docs/guides/first-playbook/",
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
# Agent execution and containers
|
||||
|
||||
Authority: `docs/architecture/agent-system.md` (execution boundary, the model
|
||||
never runs git) and the Deployment Model section of `CLAUDE.md`.
|
||||
|
||||
The daemon prepares a workspace, starts one container per task from a profile's
|
||||
image, and hands the whole task to `archie-agent` over NATS in one
|
||||
`taskrun.Request`. The agent reaches the State Store, forge and worktree push
|
||||
only through the daemon's RPC servers, using task-scoped credentials.
|
||||
|
||||
## Giving the agent something new
|
||||
|
||||
- **Data about the task** goes in `taskrun.Request` or the task brief
|
||||
(`container.TaskPayload`), never in an environment variable. Add a test that
|
||||
the request carries it (`TestRunViaAgentSendsMCPServers` is the pattern).
|
||||
- **A credential** is scoped to the task and revoked when it ends, like the
|
||||
State Store grant and the worktree publication grant. The daemon's own
|
||||
administrative token never enters a container.
|
||||
- **A tool** reaches the agent through the central registry, MCP, a repository
|
||||
script or a skill plugin. A profile's `tools` list filters those; ai-sdk
|
||||
agentloop's built-in file tools are outside it. A tool that must stay inside
|
||||
the workspace uses the agent loop's confinement, not its own path handling.
|
||||
|
||||
## Changing the agent image or a profile image
|
||||
|
||||
1. The agent image is `Dockerfile`; example profile images live in
|
||||
`examples/profiles/`, each with a build-only service in
|
||||
`docker-compose.yml` (`profiles: ["build"]`, so `up -d` never starts it).
|
||||
2. Anything the agent runs must be in the image. The container gets no
|
||||
package manager at run time beyond what the image ships.
|
||||
3. A locally built image needs `containers.pull_policy = "missing"`;
|
||||
`"always"` tries to pull it and fails.
|
||||
4. Profiles are configured under `[containers.profiles.<name>]` and resolved
|
||||
by the daemon before the container starts (`pinTaskProfile`). An unknown
|
||||
profile parks the task; it never falls back to the default image.
|
||||
|
||||
## Changing how a task runs
|
||||
|
||||
- Workspace preparation happens in the daemon (`prepareWorkspace`) before the
|
||||
container starts, because the container binds the directory. Clones need the
|
||||
daemon's forge credential; the agent never clones.
|
||||
- A task with no repository gets `worktree.Manager.ScratchDir`, which is
|
||||
removed when the task ends.
|
||||
- The agent runs as root in the container. Anything it writes into the
|
||||
bind-mounted workspace is handed back to the daemon's UID
|
||||
(`restoreWorktreeOwnership`); a new write path must stay inside that
|
||||
workspace.
|
||||
- NATS rules are in `CLAUDE.md`: task responses use `msg.Respond`, a responder
|
||||
is flushed after it registers, and `ARCHIE_TASKS` is a work queue.
|
||||
@@ -0,0 +1,58 @@
|
||||
# Configuration settings
|
||||
|
||||
Authority: `docs/architecture/configuration.md`. The wiring matrix, the
|
||||
decoded-but-unwired ledger and the three shapes an unwired field takes are in
|
||||
`.agents/skills/archie-config-and-flags`.
|
||||
|
||||
A field that parses is not a field that works. Before adding one, name the code
|
||||
that reads it and the path the value takes to get there.
|
||||
|
||||
## Decide what kind of setting it is
|
||||
|
||||
- **Bootstrap-only** (read once at process start: `database_url`, `state_dir`,
|
||||
`work_dir`). It stays in the file, is checked by `validateBootstrap` in
|
||||
`internal/infrastructure/configuration/validate.go`, and the runtime overlay
|
||||
refuses changes to it.
|
||||
- **Database-owned** (repository policies, scheduling, tools, plugins,
|
||||
channels, containers). The file only seeds it. Once the State Store holds the
|
||||
control-plane resource, the stored document is layered over the file
|
||||
(`controlplane.Client.RuntimeConfig`) and the file key stops mattering. It is
|
||||
checked by `validateDatabaseOwned` and by the resource's validator.
|
||||
- **Worker-carried.** A value the agent container needs travels in
|
||||
`config.TaskConfig` (`Config.ForTask`) or on `taskrun.Request`. Never pass it
|
||||
as an environment variable the daemon did not already define, and never carry
|
||||
a secret this way.
|
||||
|
||||
## Adding a database-owned field
|
||||
|
||||
1. Add it to the struct the resource's `Document` names in
|
||||
`internal/app/controlplane/operational_settings.go`. The resource's JSON
|
||||
schema and the dashboard's Advanced settings editor are generated from that
|
||||
type, so no UI work is needed for the editor itself.
|
||||
2. Stored documents use Go field names as keys (`Image`, `MaxConcurrency`).
|
||||
Give the field no `json` tag unless its neighbours have one.
|
||||
3. A map or a nested struct needs its layering checked. `json.Unmarshal`
|
||||
merges into an existing map, so a stored map would add to the file's rather
|
||||
than replace it. A field the stored document omits keeps the file's value
|
||||
(a document stored before the field existed). Add a case to
|
||||
`internal/app/controlplane/runtime_config_test.go` for both.
|
||||
4. Validate it in one function both sides call, and add a case to
|
||||
`TestResourceValidatorsRejectWhatEffectiveValidationRejects` in
|
||||
`validators_agree_test.go`, so the file and the resource cannot disagree.
|
||||
5. Decide whether it reloads: it does only if every consumer re-reads it from
|
||||
`config.Holder`. The allowlist is `internal/app/archied/reload.go`; anything
|
||||
not on it requires a restart.
|
||||
6. If the settings page shows it as a plain field, add it to
|
||||
`internal/webui/config_schema.go` and the view in `api_config.go`.
|
||||
|
||||
## Every new field
|
||||
|
||||
- Test through the layering: build the effective config the way boot does,
|
||||
not by setting the field on the consumer.
|
||||
- Add a commented example to `config.example.toml`. Touch `deployments/*.toml`
|
||||
only when a profile there needs a value different from the default.
|
||||
- Update the wiring matrix in `.agents/skills/archie-config-and-flags`.
|
||||
- Secrets are `SecretRef`s resolved through the secret registry. Never inspect
|
||||
a resolved value, even in a test.
|
||||
- Reject a configuration that sets a field with no consumer rather than
|
||||
accepting and ignoring it (per-identity `forge.intake` is the precedent).
|
||||
@@ -0,0 +1,37 @@
|
||||
# Dashboard
|
||||
|
||||
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
|
||||
should look.
|
||||
|
||||
## Adding or changing a feature
|
||||
|
||||
1. The feature lives in `ui/src/<feature>/`. Move a helper to `ui/src/base/`
|
||||
only when a second feature needs it.
|
||||
2. Keep wire shapes, draft state and payload building in a plain `.ts` module
|
||||
beside the components (`ui/src/bindings/binding-draft.ts` is the pattern),
|
||||
and test it in `ui/test/*.test.ts`. Components stay thin.
|
||||
3. Every mutation goes through `api.*` in `ui/src/lib/api`, which sends the
|
||||
CSRF and Content-Type headers the server's mutation guard requires. A bare
|
||||
`fetch` is refused.
|
||||
4. A value the server also describes (task statuses, actions, workflow inputs)
|
||||
comes from the server. Keep a local default only so the first render works,
|
||||
and keep it in step (`ui/src/lib/task-meta.ts`).
|
||||
5. Run `task ui`, `task test:ui` and `cd ui && npm run typecheck`. Commit the
|
||||
regenerated `ui/dist/`; the Go binaries embed it.
|
||||
|
||||
## Adding an API route
|
||||
|
||||
1. The handler goes in the `internal/webui/api_<concern>.go` file for its
|
||||
concern. Check the request fully on the server; the UI's checks are only a
|
||||
convenience.
|
||||
2. A mutation calls `authorizeTaskMutation` first.
|
||||
3. A route whose store is not configured answers 503, and
|
||||
`internal/app/archieui/degraded_routes_test.go` pins what each route
|
||||
returns without its contract. Add the route there.
|
||||
4. The dashboard runs in its own process (`archie-ui`) and must not link the
|
||||
daemon or the workflow engine (`cmd/archie-ui/architecture_test.go`). Reach
|
||||
stored data through `storecontract` interfaces wired in
|
||||
`internal/app/archieui/compose.go`.
|
||||
5. Settings that live in a control-plane resource need no new route: the
|
||||
Advanced settings page edits every resource from its generated schema.
|
||||
@@ -0,0 +1,44 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,42 @@
|
||||
# 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.
|
||||
|
||||
| Changing | Guide |
|
||||
| --- | --- |
|
||||
| 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) |
|
||||
|
||||
## Every change
|
||||
|
||||
- Write the failing test first for anything with logic, branching or a
|
||||
contract, and check it fails on an assertion, not a compile error.
|
||||
- Test through the path production uses. A test that sets a value directly on
|
||||
the consumer proves nothing about the layers that normally deliver it.
|
||||
- Run `task check` and let its exit status decide the commit:
|
||||
`task check && git commit ...`. `task test` passes `-short`, which skips the
|
||||
process and Postgres tests, so run `go test -count=1 ./cmd/... ./internal/...`
|
||||
too when a change crosses a process or the database.
|
||||
- Regenerate, never hand-edit, generated output: `task proto:generate`,
|
||||
`go -C tools tool sqlc generate -f $PWD/internal/infrastructure/postgres/sqlc.yaml`,
|
||||
`task ui`, `task docs:artifact`. `task proto:check` compares against the git
|
||||
index, so stage regenerated contracts before running it.
|
||||
- Stage by path, or read `git status` before `git add -A`. Tests that start
|
||||
embedded NATS or write logs must use `t.TempDir()`; anything they leave in the
|
||||
tree gets committed. `task check` also adds linter-tool lines to `go.sum`
|
||||
(bead 1e37); restore `go.sum` before committing unless you changed a
|
||||
dependency.
|
||||
- A change to `docs/prds/` or `docs/architecture/` carries the regenerated
|
||||
`docs/data/generated/dev-docs.json`, and PRD edits follow
|
||||
`docs/prds/RULES.md` and pass `task docs:prds`.
|
||||
@@ -0,0 +1,29 @@
|
||||
# Merging work
|
||||
|
||||
Parallel lanes (see `.agents/skills/archie-agent-fleet`) merge into an
|
||||
integration branch before `main`. Each merge is a change in its own right and
|
||||
passes the same gate.
|
||||
|
||||
## Resolving conflicts
|
||||
|
||||
- **Generated files** (`*.pb.go`, `postgresdb/*.go`, `ui/dist/`,
|
||||
`docs/data/generated/*.json`): take either side, then regenerate. Never merge
|
||||
them by hand.
|
||||
- **One side deletes a file, the other edits it**: the deletion wins when the
|
||||
deleting lane replaced the thing the file served. Move the other side's
|
||||
change onto its replacement.
|
||||
- **One side changes how code is built (a new store, renamed packages), the
|
||||
other what it does**: take the behaviour side's version and reapply the
|
||||
mechanical change to it. That is usually cleaner than merging line by line.
|
||||
- **Error sentinels** are rows in `wireErrors`, not switch cases.
|
||||
|
||||
## After resolving
|
||||
|
||||
1. Search for leftovers of anything the other side removed: the old package
|
||||
path, the old type, and comments describing the old behaviour.
|
||||
2. Tests written against one side's semantics may pass there and fail after
|
||||
the merge. A test that used to pass on the old store may be asserting a rule
|
||||
the other side deliberately changed. Fix the test's setup to the merged
|
||||
rule; do not loosen the rule to the test.
|
||||
3. Run the full suite without `-short`, then `task check`, then commit. Check
|
||||
`git status` for files a test wrote into the tree before staging.
|
||||
@@ -0,0 +1,48 @@
|
||||
# Processes and wiring
|
||||
|
||||
Authority: `docs/architecture/organisation.md` (layers, process boundaries),
|
||||
`docs/architecture/dependencies-and-contracts.md` (dependency direction, wire
|
||||
contracts) and `docs/architecture/plugins-and-extensions.md` (the plugin engine
|
||||
rule).
|
||||
|
||||
## Placing new code
|
||||
|
||||
- Domain logic, entities and the interfaces it needs go in
|
||||
`internal/domain/<area>/`, which imports no infrastructure or app package.
|
||||
- Implementations of those interfaces go in `internal/infrastructure/<service>/`.
|
||||
- Construction and wiring go in `internal/app/<application>/`; `cmd/` only
|
||||
parses flags and calls it.
|
||||
- `logging`, `events`, `eventbus`, `policy` and `taskstate` import no internal
|
||||
package. There is no `shared/`, `utils/` or `common/` package.
|
||||
- A behaviour has one authoritative path. Before adding a second way to do
|
||||
something, remove or redirect the first.
|
||||
|
||||
## Adding a capability to a process
|
||||
|
||||
1. Decide which process owns it. A new binary is justified only when the
|
||||
surface must fail, scale or run somewhere independently.
|
||||
2. Wire it at that process's composition root. An optional capability
|
||||
degrades: a missing provider logs a warning and marks health degraded
|
||||
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)).
|
||||
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,
|
||||
not the test.
|
||||
|
||||
## Adding a plugin engine
|
||||
|
||||
Satisfy every invariant in "Plugin engine rule (strict)" in
|
||||
`plugins-and-extensions.md`: typed domain contract, an owning manager,
|
||||
lifecycle and health, narrow host access, and an explicit trust boundary.
|
||||
`internal/plugin/architecture_test.go` checks the parts that can be checked.
|
||||
|
||||
## Adding a channel or a NATS subject
|
||||
|
||||
- Channel rules (Telegram's pending-update drop, command scopes) are in
|
||||
`CLAUDE.md` under Per-Package Invariants.
|
||||
- A subject is part of the wire contract. Its payload type belongs to the
|
||||
domain that defines its meaning, and the transport code lives in
|
||||
infrastructure.
|
||||
@@ -0,0 +1,57 @@
|
||||
# State Store and persistence
|
||||
|
||||
Authority: `docs/prds/state-store-contract.md` and the State Store section of
|
||||
`CLAUDE.md`. All persistence is PostgreSQL behind the standalone State Store
|
||||
process; nothing else opens the database.
|
||||
|
||||
## Adding a column
|
||||
|
||||
1. Write the next migration in `internal/infrastructure/postgres/migrations/`
|
||||
(`00NN_name.sql`, goose Up and Down). Give the column a `NOT NULL DEFAULT`
|
||||
that is correct for existing rows.
|
||||
2. Update the queries in `internal/infrastructure/postgres/queries/` and
|
||||
regenerate with sqlc. A query that lists columns (`ListTaskSummaries`, the
|
||||
binding selects) does not pick the new one up; `SELECT *` queries do.
|
||||
3. Map it in the store (`taskFromRow`, `bindingValue` and friends). If the
|
||||
column holds encoded data, the package that owns the type owns the encoding
|
||||
(`task.EncodeInputs`), and the store and the wire both use it.
|
||||
4. Add the column to `newColumns` in
|
||||
`internal/infrastructure/legacyimport/load.go` if legacy data has no value
|
||||
for it. The importer refuses a target column it cannot fill otherwise.
|
||||
5. Carry it over the wire (next section) if any process other than the State
|
||||
Store reads it.
|
||||
|
||||
## Adding a field to a wire message
|
||||
|
||||
1. Add it to `proto/state/v1/state.proto` with a new field number. Never reuse
|
||||
a number; retire one with `deprecated = true`.
|
||||
2. `task proto:generate`, then map it both ways in
|
||||
`internal/infrastructure/staterpc/values.go`.
|
||||
3. `TestTaskProtoCarriesEveryDomainField` fills every `task.Task` field and
|
||||
fails on one the mapping forgets. If it cannot fill the field's kind, extend
|
||||
it. Other messages have no such test, so add a round trip to
|
||||
`conformance_test.go`.
|
||||
|
||||
## Adding an RPC or a store method
|
||||
|
||||
1. Put the Go method on the narrow consumer interface in
|
||||
`internal/domain/storecontract` (keep each at eight methods or fewer) and add
|
||||
the matching RPC. A Go method without an RPC does not cross the process.
|
||||
2. Implement it in the Postgres store, in `staterpc.Client` (with its `var _`
|
||||
assertion) and in `staterpc.server`. A missing dependency answers
|
||||
`codes.Unavailable`, never a fabricated default.
|
||||
3. Wire the dependency in every composition that serves or consumes it:
|
||||
`stateStoreDeps` in `internal/app/archied/state_store.go`, the daemon's
|
||||
assertions in `bootstrap.go`, and `internal/app/archieui/compose.go` for the
|
||||
dashboard process.
|
||||
4. Task-scoped tokens may call only `Update`, `Transition` and `InsertEvent` on
|
||||
their own task (`staterpc.TaskGrants`). A new RPC is admin-only unless it is
|
||||
added there deliberately.
|
||||
5. Add it to `conformance_test.go`, which runs every surface over a real gRPC
|
||||
connection.
|
||||
|
||||
## Adding an error sentinel
|
||||
|
||||
Add the sentinel to `storecontract`, a row to `wireErrors` in `values.go`, and
|
||||
a case to `error_test.go`. The canonical message is part of the wire contract:
|
||||
changing it breaks `errors.Is` on the client silently.
|
||||
@@ -0,0 +1,40 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,41 @@
|
||||
# Workflows and steps
|
||||
|
||||
Authority: `docs/architecture/agent-system.md` for the lifecycle,
|
||||
`docs/prds/event-automation.md` for inputs, repository modes and profiles.
|
||||
|
||||
Workflow definitions are YAML stored as a control-plane resource. The State
|
||||
Store validates them and the agent compiles them, each against the step
|
||||
vocabulary it registers, so both must see the same step types.
|
||||
|
||||
## Adding a step type
|
||||
|
||||
1. Write the factory in `internal/domain/workflow` as a `StepType`. It decodes
|
||||
and validates its settings and returns an error for anything it cannot
|
||||
honour. The factory runs when a definition is saved and again when it is
|
||||
compiled, so a bad definition is refused on save.
|
||||
2. Register it through a provider in
|
||||
`internal/infrastructure/workflowsteps/workflowsteps.go`. That one list is
|
||||
what every process registers, which is how the validating and executing
|
||||
sides agree.
|
||||
3. An agent-driven step builds on `AgentStage`; do not start a second path to
|
||||
the agent runner.
|
||||
4. A step that needs no repository goes in `repoFreeStepTypes` in
|
||||
`definition.go`, or workflows declaring `repository: none` or `optional`
|
||||
cannot use it. A step that needs one may assume `tc.Dir` holds a worktree
|
||||
only when the workflow's repository is `required`.
|
||||
5. A step that ends the workflow sets `tc.Outcome`. A workflow that runs out of
|
||||
steps without an outcome is parked as a definition bug.
|
||||
6. Add a parse test (settings accepted and refused) and a run test with fake
|
||||
`Trees` and agent runner.
|
||||
|
||||
## Changing the definition format
|
||||
|
||||
- The fields a caller needs without the engine (inputs, repository, profile)
|
||||
live in `task.WorkflowInterface`, because the dashboard process must not
|
||||
import the workflow engine (`cmd/archie-ui/architecture_test.go`). Anything a
|
||||
binding or the dashboard checks goes there.
|
||||
- The YAML decoder rejects unknown keys. Existing stored definitions must keep
|
||||
parsing, so a new key is optional with a default that preserves today's
|
||||
behaviour.
|
||||
- Examples in `examples/workflows/` are parsed against the registered
|
||||
vocabulary by `TestExampleWorkflowsParse`. Add one for a new capability.
|
||||
@@ -20,6 +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.
|
||||
|
||||
## What runs where
|
||||
|
||||
|
||||
Reference in new issue
Block a user