docs(skills): add archie-agent-fleet and re-home the worked example
Project skill for running a bounded agent fleet on this repository. It stays
thin on purpose: the method -- doctrine, pipeline shape, the interview, the
pi-subagents ceilings and traps, scripts/, templates/ -- is the user-scope
high-throughput-programming skill, which is normative for method. This skill
carries only archie's facts and is normative for those.
What it carries: the seven invariants every lane call must repeat (fail-closed
control plane, the webui/workflow deletion gate, single ownership of
<db_path>-tasks.sqlite, no .beads/ commits, generated assets as LAW, scratch in
/tmp because CommitAll stages untracked files, and the cmd -> app -> {domain,
infrastructure} direction); the canonical gate-evidence.sh invocation and why it
must run the module build and the linter, not just a scoped test; the scoped
test-command shape for a lane plus the fact that task check is the serial full
gate the merge train owns; the agent-discovery trap (a lane worktree is a
sibling, so .pi/agents must be symlinked into it or children die with "Unknown
agent: cp-writer"); bd conventions; and that .pi/control-plane-run/ is
disposable run evidence, not documentation.
Also moves the September 2026 control-plane run out of the user-scope skill's
references/worked-example/ and into references/worked-example/ here, so exactly
one copy exists and it is committed. The user-scope skill's References table and
normative-copy paragraph now point at this repository, and note that a run in
another repository uses templates/ plus its own filled-in briefs. The moved
README gains the worktree agent-symlink fix and loses its stale "everything here
is gitignored" claim; its paths to scripts/ and templates/ now name the
user-scope skill explicitly. The scripts warning is unchanged: they are the
snapshot's and must not be copied.
This commit is contained in:
12 files changed
+1090
No files matched your search
@@ -0,0 +1,138 @@
|
||||
---
|
||||
name: archie-agent-fleet
|
||||
description: >-
|
||||
Run a bounded fleet of coding agents across archie-core's backlog without
|
||||
flooding review. Load when fanning work out into parallel lanes, waves,
|
||||
worktrees or subagents on this repository; when a lane worktree dies with the
|
||||
unknown-agent error for `cp-writer`; or when deciding what every lane call must
|
||||
carry, which gate evidence to demand, and how a lane's scoped test command
|
||||
should be shaped here. Carries archie-specific fleet facts only; the method
|
||||
lives in the user-scope high-throughput-programming skill.
|
||||
---
|
||||
|
||||
# Run an agent fleet on archie-core
|
||||
|
||||
This skill carries the facts about *this repository*. It deliberately does not
|
||||
restate the process.
|
||||
|
||||
## Where the method lives
|
||||
|
||||
The how is the user-scope skill `high-throughput-programming` at
|
||||
`~/.agents/skills/high-throughput-programming/`: doctrine, pipeline shape, the
|
||||
interview that scaffolds a run, the pi-subagents ceilings and traps, `scripts/`,
|
||||
`templates/` and `references/`. Read its `INTERVIEW.md` before scaffolding a run;
|
||||
never scaffold one from memory.
|
||||
|
||||
**Precedence.** That skill is normative for method; this one is normative for
|
||||
archie's facts. If they disagree about the process, it wins. If they disagree
|
||||
about this repository — a path, an invariant, a gate — this one wins, because the
|
||||
method skill is repository-agnostic by construction.
|
||||
|
||||
Route runtime facts to `archie-run-and-operate`, toolchain facts to
|
||||
`archie-build-and-env`, and dependency/boundary rules to
|
||||
`archie-architecture-contract`.
|
||||
|
||||
## Invariants every lane call must carry
|
||||
|
||||
State these as facts to each lane, not as advice. Each one has cost a real run.
|
||||
|
||||
| Invariant | Why it matters to a lane |
|
||||
|---|---|
|
||||
| **The control plane fails closed.** A stored resource that will not validate stops `archied` starting, and nothing bypasses the control plane at boot. Resource history is the only in-band remedy, and it needs the State Store up. | A lane touching the boot path, a stored resource kind, or the recovery commands is a risk-routed lane for the operator's eyes, not a gate-and-merge lane. Evidence: `docs/architecture/safe-change-and-recovery.md` ("Database settings: degrade paths and recovery"). |
|
||||
| **`internal/webui` must not reach `internal/domain/workflow`.** Go imports are atomic: one reference relinks the whole daemon runtime into the UI binary. | `cmd/archie-ui/architecture_test.go` measures the linked binary (`go list -deps .`), not the imports, and fails on anything under `internal/domain/workflow`. `internal/domain/workflow/task` is a named `gateExceptions` entry that must stay linked — it carries only contract and view types, and a stale exception fails the test in both directions. |
|
||||
| **The task DB has one owner.** `<db_path>-tasks.sqlite` is served by the standalone `cmd/archie-state-store` process alone. No second listener, no in-process serving path in the daemon or Gateway. | `boot.openStateStore` (`internal/app/archied/state_store.go`) is the only production caller of `openProductionTaskStore`, and it takes an exclusive flock on `<db>.lock` for the process's life — a second State Store on the same file fails there rather than merely being discouraged. Offline maintenance belongs in subcommands of that binary, never a new `cmd/` entry (`docs/architecture/organisation.md#process-boundaries`). |
|
||||
| **Never commit `.beads/`.** Bead state moves through Dolt; `issues.jsonl` and `interactions.jsonl` are local-only. | A lane that stages `.beads/` pollutes its diff. Closing a bead is not commit-worthy on its own. |
|
||||
| **Generated assets are LAW.** `ui/dist/` and the schema outputs (`docs/data/generated/contracts.json`). | Incorporate them into the commit that shifted them. Never revert, regenerate away, or leave them out. |
|
||||
| **Scratch goes to `/tmp` only.** Never the working tree. | `worktree.CommitAll` stages with go-git's `AddWithOptions{All: true}` (`internal/worktree/worktree.go:502`), which does **not** honour `.gitignore`. An untracked scratch file in a lane worktree is swept onto the task branch. The task brief lives in `.git/task.json` for exactly this reason. |
|
||||
| **Dependency direction is `cmd -> app -> {domain, infrastructure}`**, with infrastructure implementing domain contracts. | A lane that needs a new edge says so before writing it. The `internal/{logging,events,eventbus,policy,taskstate}` cross-cutting packages import zero internal packages. Source: `docs/architecture/organisation.md`. |
|
||||
|
||||
## The canonical gate
|
||||
|
||||
```bash
|
||||
~/.agents/skills/high-throughput-programming/scripts/gate-evidence.sh \
|
||||
<worktree> '<scoped test cmd>' <base>
|
||||
```
|
||||
|
||||
Run it on the host, per lane. It executes the scoped tests, then a module-wide
|
||||
build (`go build ./...`) and the linter (`golangci-lint run ./...`), and emits
|
||||
JSON for the harness to use as the child's structured output.
|
||||
|
||||
The two extra checks are required, not optional. `go test ./pkg/...` compiles
|
||||
only that package, so a changed constructor signature or interface passes its own
|
||||
lane and breaks the next package to merge. That shape has bitten twice here: one
|
||||
lane changed a constructor's signature, passed its own gate, and failed three
|
||||
packages the moment it merged; formatting and lint drifted the same way, and only
|
||||
the repository gate saw it. Both failures are paid for inside the lane when the
|
||||
gate runs the build and the linter, and at merge when it does not.
|
||||
|
||||
A copy of the script under `.pi/control-plane-run/` is that run's disposable
|
||||
state and may lag the skill's version. The skill's copy is the one to trust.
|
||||
|
||||
## Shape a lane's test command like this
|
||||
|
||||
Name every package the change can reach, plus `go vet` on the same set:
|
||||
|
||||
```bash
|
||||
go test ./internal/app/controlplane/... ./internal/domain/applystatus/... -count=1 \
|
||||
&& go vet ./internal/app/controlplane/... ./internal/domain/applystatus/...
|
||||
```
|
||||
|
||||
Real examples, from the worked example's `lanes.json`:
|
||||
|
||||
| Lane surface | Scoped command |
|
||||
|---|---|
|
||||
| CLI subcommands and the State Store contract | `go test ./cmd/... ./internal/infrastructure/staterpc/... -count=1 && go vet ./cmd/...` |
|
||||
| Workflow registry and the agent worker | `go test ./internal/domain/workflow/... ./internal/app/agentworker/... -count=1 && go vet ./internal/domain/workflow/...` |
|
||||
| Config decoding and daemon boot | `go test ./internal/infrastructure/configuration/... ./internal/app/archied/... -count=1 && go vet ./internal/infrastructure/configuration/... ./internal/app/archied/...` |
|
||||
|
||||
`task check` is the *serial full gate* — fmt, proto checks, `docs:check`, vet,
|
||||
lint, build, `go test ./...`, the tools tests and the dashboard tests. The merge
|
||||
train owns it. Never run it in a lane, and never two at once: it saturates the
|
||||
host.
|
||||
|
||||
## The agent-discovery trap
|
||||
|
||||
A lane worktree is a **sibling** of the repository (`/work/apps/cp-<lane>`), not a
|
||||
directory inside it. pi discovers project-scope agents under `<cwd>/.pi/agents/`,
|
||||
so a child launched in a lane worktree does not see them and dies with
|
||||
`Unknown agent: cp-writer`.
|
||||
|
||||
Fix it once per worktree:
|
||||
|
||||
```bash
|
||||
mkdir -p /work/apps/cp-<lane>/.pi
|
||||
ln -sfn /work/apps/archie-core/.pi/agents /work/apps/cp-<lane>/.pi/agents
|
||||
```
|
||||
|
||||
`.pi/` is gitignored, so the worktree stays clean and the symlink cannot reach a
|
||||
commit. This costs an hour to rediscover.
|
||||
|
||||
## Tracker conventions
|
||||
|
||||
`bd` is the only tracker; no markdown TODO lists, no local trackers.
|
||||
|
||||
```bash
|
||||
bd show <id> # before working an item — the brief may describe a tree that has moved
|
||||
bd update <id> --claim
|
||||
bd close <id> # after the work lands, not when it commits
|
||||
```
|
||||
|
||||
Bead state moves through Dolt, never through git commits on this repository. The
|
||||
Dolt remote is pushed explicitly (`bd dolt push`) and never assumed to be in sync.
|
||||
|
||||
## Run artifacts are evidence, not documentation
|
||||
|
||||
`.pi/control-plane-run/` holds a run's scaffold, lane plan, prompts, scripts and
|
||||
gate output. It is gitignored and disposable. Treat it as run evidence only: a
|
||||
fact worth keeping goes into this skill, `docs/`, or `ARCHITECTURE.md`, not into a
|
||||
run directory the next clean deletes.
|
||||
|
||||
## Worked example
|
||||
|
||||
`references/worked-example/` is the control-plane backlog run of September 2026,
|
||||
committed verbatim: the filled orchestrator prompt, four lane briefs, three
|
||||
sub-prompts, and the three agent definitions with their project invariants
|
||||
inlined. Read it for the level of detail a good brief carries.
|
||||
|
||||
Its scripts are the snapshot's, not the current ones. The user-scope skill's
|
||||
`scripts/` and `templates/` are normative and win any disagreement.
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Archie Agent Fleet"
|
||||
short_description: "Run bounded agent fleets on archie-core"
|
||||
default_prompt: "Use $archie-agent-fleet to fan work out across lanes on this repository, carrying the fleet invariants, the gate evidence it needs, and the worktree agent-discovery fix."
|
||||
@@ -0,0 +1,467 @@
|
||||
# Mission: clear the archie-core control-plane backlog with a bounded high-throughput fleet
|
||||
|
||||
> **Where this file's paths point.** This is the committed copy of a live run.
|
||||
> Paths under `.pi/control-plane-run/` (sections 6, 9, 10) name that run's own
|
||||
> disposable copies of `wave0.js`, `wave2.js`, `review.js` and
|
||||
> `gate-evidence.sh`; they are gitignored run state and may lag the skill's
|
||||
> normative versions in `~/.agents/skills/high-throughput-programming/`. The
|
||||
> skill is the one to trust. Paths under `/work/apps/archie-core` and
|
||||
> repo-relative source paths are unchanged.
|
||||
|
||||
You are the orchestrator. You do not write production code yourself. You run
|
||||
waves of subagents through the `subagent` tool, verify their work against git
|
||||
evidence rather than their reports, and land finished slices on `main`.
|
||||
|
||||
Repository: `/work/apps/archie-core`, branch `main`, working tree clean at start.
|
||||
Gate: `task check`. Tracker: `bd`. Read `CLAUDE.md` and
|
||||
`docs/architecture/organisation.md` before Wave 1.
|
||||
|
||||
---
|
||||
|
||||
## 1. Hard rules
|
||||
|
||||
1. **One top-level `subagent` call per wave.** Every child launches inside that
|
||||
call's `workflowScript`. Never open a second top-level orchestration while a
|
||||
wave is running.
|
||||
2. **Read-only fans out wide. Writers do not.** Recon and review children are
|
||||
cheap and parallel. Writer children are bounded by file overlap and by this
|
||||
machine (16 cores), not by the spawn budget.
|
||||
3. **At most one `task check` at a time, ever.** It compiles 117 Go packages,
|
||||
runs the full test suite and the Node dashboard tests, and saturates the
|
||||
machine. Writer children run package-scoped tests only. The full gate belongs
|
||||
to the merge train in Wave 4, which is strictly serial.
|
||||
4. **A worker's report is not evidence.** Accept a lane only on: the handoff
|
||||
manifest path, `git -C <worktree> status --short`, `git log --oneline`, and
|
||||
`git diff --stat` against the lane's own base. A bead marked closed with no
|
||||
commits means the work did not happen.
|
||||
5. **No suppression.** Children may not add `//nolint`, `t.Skip`, build tags that
|
||||
exclude a failing test, or delete an assertion to make a gate pass. Say this
|
||||
in every writer and fix task. A child that suppresses gets its lane reverted,
|
||||
not patched.
|
||||
6. **Formatting is law.** Adopt `task fmt` output verbatim. Never revert a
|
||||
linter or formatter diff.
|
||||
7. **Zero patch stacking.** Two failed fixes on the same logic block means the
|
||||
block gets rewritten, not patched a third time. This is a `CLAUDE.md` rule and
|
||||
it applies to children.
|
||||
8. **Do not push.** Commit gate-clean work to `main` in the captain checkout.
|
||||
Sam pushes manually and does not always announce it, so never assume a commit
|
||||
is local or remote without checking `git log origin/main..main`.
|
||||
9. **No `.beads/` commits.** Bead state moves through Dolt. Closing a bead is not
|
||||
commit-worthy on its own.
|
||||
10. **Scratch stays out of the tree.** Children write scratch to `/tmp` only.
|
||||
`.pi/` is gitignored; nothing else you create may land in a commit.
|
||||
11. **Separation of duties.** No agent merges, closes or approves its own work.
|
||||
Writers write, reviewers review, and you alone run the merge train. You do
|
||||
not write production code; if you find yourself editing a lane's files, the
|
||||
lane was scoped wrong.
|
||||
12. **Every wave ends with an adversarial review pass** before the next wave
|
||||
starts. Reviewers are read-only, parallel and cheap; a defect caught at the
|
||||
end of the wave that produced it costs one lane, and the same defect caught
|
||||
three waves later costs the tree.
|
||||
|
||||
---
|
||||
|
||||
## 2. Ground truth: do not spend agents rediscovering this
|
||||
|
||||
This came from the session that just ended. Treat it as fact.
|
||||
|
||||
- `docs/prds/runtime-control-plane.md` is Approved and is the spec. Its resource
|
||||
surface, YAML workflow definitions, identity-backed attribution and audit trail
|
||||
are already built.
|
||||
- **Restore is not its own command.** A revision carries its value, so restoring
|
||||
replays it through the ordinary replace. Do not add a rollback RPC.
|
||||
- **Dashboard writes attribute to `identity.SystemID`.** One shared bearer token,
|
||||
no per-user session. `webAudit` in `internal/webui/api_identities.go` is the
|
||||
only source. Named attribution needs a dashboard login first.
|
||||
- **`internal/webui` must not link the workflow engine.** It decodes definitions
|
||||
with the projection types in `internal/domain/workflow/task`. `cmd/archie-ui`'s
|
||||
deletion gate fails if anything reaches `internal/domain/workflow`.
|
||||
- Shipped defaults ride `ResourceDescriptor.defaults_json`. The API is fixed at
|
||||
four operations, so defaults get no REST route.
|
||||
- `archie-messaging` fails closed when the State Store is unreachable. The
|
||||
database is authoritative for channel settings. File config is not a fallback.
|
||||
- **The control plane fails closed with no way back.** A stored value that will
|
||||
not validate stops `archied` starting. Nothing bypasses the control plane at
|
||||
boot. `docs/architecture/safe-change-and-recovery.md` records this posture.
|
||||
Resource history is the only in-band remedy and needs the State Store up.
|
||||
- **`task check` will not catch a field the server stopped sending.** Optional
|
||||
chaining made a dead dashboard banner typecheck silently; `delivery-snapshot.sh`
|
||||
scanned for a symbol its composition root no longer calls. Both fixed in
|
||||
`85f0fd0b`. When a server-side field is deleted, grep the dashboard and the
|
||||
snapshot scripts by name. Add this to every review task.
|
||||
- **Reload re-reads the database layer and can fail.** `boot.runtimeConfig` is the
|
||||
one layering call; the SIGHUP callback makes the same call over the document it
|
||||
just resolved (`9af013eb`). A new database-owned layer goes in `runtimeConfig`
|
||||
and nowhere else.
|
||||
- **Apply status lives on the State Store contract, not the control plane.**
|
||||
`PutApplyStatus`/`ListApplyStatus` are administrative, keyed on
|
||||
`(process, kind)`, replaced in place, re-stamped every 30s, stale at 90s, and a
|
||||
stale record renders as "Not reporting", never as current. `applystatus.New`
|
||||
refuses a process name `Processes()` does not list.
|
||||
- Five commits are local as of 2026-09-21: `731a9a06`, `1dd0d874`, `d9dd7885`,
|
||||
`9accf112`, `d38e27fd`. `archie-core-pskb` is closed. There is no post-commit
|
||||
hook; `core.hooksPath` is `.beads/hooks` and those are beads shims.
|
||||
|
||||
---
|
||||
|
||||
## 3. The backlog
|
||||
|
||||
Seven ready beads carry the `control-plane` label. Their real shape is what
|
||||
decides the lanes, and it is not the same as their titles.
|
||||
|
||||
| Bead | Title shape | Primary surface |
|
||||
|------|-------------|-----------------|
|
||||
| `archie-core-nwa0` | check a live replacement before switching to it | live apply path + apply-status surface |
|
||||
| `archie-core-fwmp` | let plugins register workflow step types | `workflow.BuiltinStepRegistry()` and all five call sites |
|
||||
| `archie-core-8szi` | registered steps covering the deleted `.archie` gate | `internal/domain/workflow/steps.go`, needs fwmp's answer |
|
||||
| `archie-core-6zw0` | offline backup/restore/validate/rollback for `archie.db` | new `cmd/` binary + state-store infrastructure |
|
||||
| `archie-core-i3qm` | stop TOML blocking State Store startup | `internal/app/archied/control_plane.go`, bootstrap validation |
|
||||
| `archie-core-xrux` | `ApplyOverlayValues` is dead, confirm the file overlay | `internal/infrastructure/configuration/loader.go`, `apply.go` |
|
||||
| `archie-core-eju6` | end-to-end restart test for a database-backed change | test only, proves the whole loop |
|
||||
|
||||
Three couplings you already know about, and Wave 0 exists to find the rest:
|
||||
|
||||
- **fwmp is the shared shape.** It changes the registry every call site hardcodes
|
||||
(`app/agentworker/task_execution.go:319,:335`,
|
||||
`app/controlplane/workflow_definitions.go:26,:33`, `app/controlplane/client.go:41`)
|
||||
and the validating side and the executing side must resolve it identically.
|
||||
8szi has nothing to register against until fwmp lands. These two are never
|
||||
concurrent writers.
|
||||
- **xrux decides i3qm's blast radius.** xrux is an investigation with two
|
||||
opposite outcomes: either the file overlay zeroes omitted map fields, in which
|
||||
case `foldOverrides` moves there and it is a live bug, or it does not, in which
|
||||
case `apply.go`, `apply_test.go` and `Loader.ApplyOverlay` are deleted. Both
|
||||
land in the same package i3qm rewrites. One lane owns both, in that order.
|
||||
`archie-core-xrux` is a trap, not a cleanup. Read the bead before deleting
|
||||
`apply.go`.
|
||||
- **eju6 proves the others.** It goes last, against everything merged.
|
||||
|
||||
---
|
||||
|
||||
## 4. Models: resolve before Wave 0
|
||||
|
||||
Run `subagent({ action: "models" })` first and pick exact `provider/id` strings.
|
||||
Bare ids resolve only when unique. Then print the table you resolved and use it.
|
||||
|
||||
| Tier | Used by | Pick |
|
||||
|------|---------|------|
|
||||
| Fast | recon, inventory, grep-shaped probes | cheapest capable, low or medium thinking. Default `ollama/deepseek-v4.1-flash:cloud`. |
|
||||
| Strong | writers, integrator | best reasoning model authenticated here, high thinking. Prefer a `deepseek-v4-pro` class id if `models` lists one. |
|
||||
| Review | reviewers, oracle | a **different family** from the writer that produced the diff. Model diversity catches different failure modes; it does not rescue an ambiguous prompt. |
|
||||
|
||||
If a tier cannot be resolved, say so and fall back to the session default rather
|
||||
than inventing an id. Provider 429s return from that model; do not kill a rate
|
||||
limited child, it keeps its context and recovers.
|
||||
|
||||
---
|
||||
|
||||
## 5. Concurrency: the numbers that actually bind
|
||||
|
||||
Defaults in this install (`pi-subagents` 0.70.0) are not 64.
|
||||
|
||||
- `globalConcurrencyLimit` defaults to **20** concurrent children per run. Set it
|
||||
explicitly on each top-level call.
|
||||
- `maxSubagentSpawnsPerRun` defaults to **64** cumulative admissions per run
|
||||
tree, never refunded. Retries and fix passes spend it too.
|
||||
- **Each wave is its own top-level run, so each wave gets its own budget.** This
|
||||
is why the mission is split into waves rather than one giant script.
|
||||
- `runs.lanes` is capped at 32 lanes, 16 stages per lane, 64 stages total.
|
||||
|
||||
Per-wave dials:
|
||||
|
||||
| Wave | Shape | `globalConcurrencyLimit` | `maxSubagentSpawnsPerRun` |
|
||||
|------|-------|--------------------------|---------------------------|
|
||||
| 0 recon | `runs.all`, read-only | 32 | 64 |
|
||||
| 0R audit | `review.js`, angles `claims` | 16 | 24 |
|
||||
| 1 shape-first | one writer plus one probe | 2 | 8 |
|
||||
| 1R review | `review.js`, full angle set, one target | 12 | 16 |
|
||||
| 2 writer lanes | `runs.lanes`, one worktree each | 4 | 32 |
|
||||
| 2R review | `review.js`, full angle set, four targets | 24 | 48 |
|
||||
| 3 fix pass | `runs.lanes`, retained writers | 4 | 24 |
|
||||
| 4 merge train | serial, one `task check` at a time | 1 | 8 |
|
||||
| 4R post-merge | `review.js` on merged `main`, angles `boundary`, `deadfield`, `contract` | 8 | 12 |
|
||||
| 5 eju6 | one lane, then its own review | 2 | 12 |
|
||||
|
||||
Do not set a hard `toolBudget` or a tight `usageBudget` on any writer, fix
|
||||
worker, or reviewer with edit authority: the default budget blocks read and
|
||||
search tools rather than mutation tools, which leaves a half-written tree. Bound
|
||||
writers with `timeoutMs` plus `checkpointBeforeDeadlineMs` instead. Hard caps are
|
||||
fine on explicitly read-only children.
|
||||
|
||||
---
|
||||
|
||||
## 5a. The constraint is review, not generation
|
||||
|
||||
Generation is no longer the bottleneck and has not been for a while. The
|
||||
measured evidence is consistent: agent-authored changes take far longer to reach
|
||||
a first review, merge at a lower rate than human-authored ones, and raise more
|
||||
issues per change; one randomized study found experienced developers 19% slower
|
||||
with agent tooling while expecting to be faster. Feature-branch throughput rises
|
||||
while main-branch throughput falls. Adding writer lanes past what review can
|
||||
absorb does not raise throughput, it grows a queue, and queued work ages badly
|
||||
because the tree moves underneath it.
|
||||
|
||||
Act on that as follows.
|
||||
|
||||
- **WIP is capped by review, not by cores.** Four writer lanes exist because
|
||||
four is what the review pass and the merge train can absorb per cycle. Do not
|
||||
raise it to use spare concurrency.
|
||||
- **Put the judgment upstream.** Before a writer starts, its task must carry
|
||||
intent, acceptance criteria and non-goals, so verification has an external
|
||||
reference. "Does this do what it was supposed to do" is checkable; "does this
|
||||
look right" is not, and fluent output passes a read-through scan regardless of
|
||||
whether it is correct.
|
||||
- **Spend the effort on the verifier, not the prompt.** A parallel fleet is only
|
||||
as good as the check that decides whether its output is right. A better test
|
||||
is worth more than a better instruction.
|
||||
- **Every handoff carries evidence.** Intent, non-goals, files touched with a
|
||||
reason each, alternatives rejected, commands actually run with pasted output,
|
||||
the test that would fail first, and known limitations. A report that only
|
||||
describes its own diff is not evidence.
|
||||
- **Deterministic gates run before any reviewer looks.** `gate-evidence.sh` runs
|
||||
the lane's tests on the host and emits JSON that becomes the child's
|
||||
structured output, and it fails the lane on added `//nolint`, `t.Skip`, ignore
|
||||
build tags, removed tests or removed assertions. Gate gaming is cheap to
|
||||
detect and expensive to miss, so detect it mechanically rather than asking a
|
||||
reviewer to notice.
|
||||
- **Keep batches small.** Generation being cheap is a reason for smaller
|
||||
changes, not bigger ones. A lane whose diff passes roughly 400 changed lines
|
||||
gets split at a coherent boundary.
|
||||
- **Route risk, do not review uniformly.** These surfaces get Sam's eyes before
|
||||
merge, named explicitly in your report: the fail-closed boot path
|
||||
(`boot.runtimeConfig`, bootstrap validation), the State Store wire contract and
|
||||
its error sentinels, task-scoped grants and credentials, anything that writes
|
||||
or migrates `archie.db`, and the release or CI surface. Everything else merges
|
||||
on gate plus reviewer verdict, with a sample called out for him to spot-check.
|
||||
- **Watch the right numbers.** Report per wave: reviewer findings raised versus
|
||||
accepted, lanes blocked by gate versus by review, rework passes per lane, and
|
||||
wall-clock from lane start to merged. Lines written and beads closed measure
|
||||
how fast the queue fills.
|
||||
|
||||
---
|
||||
|
||||
## 6. Wave 0: recon fanout (read-only, wide)
|
||||
|
||||
One top-level call, `async: true`, `workflowScriptPath: ".pi/control-plane-run/wave0.js"`.
|
||||
|
||||
Three probes per bead, plus four cross-cutting probes: 25 children, all
|
||||
`cp-recon`, all read-only, all returning structured output. The probe text is composed inside
|
||||
`wave0.js`; do not retype it.
|
||||
|
||||
Per bead:
|
||||
|
||||
- **spec** — extract the exact PRD clauses the bead must satisfy, with line
|
||||
anchors, and the acceptance criteria the gate can actually check.
|
||||
- **blast** — trace every call site, consumer and test of the symbols the bead
|
||||
names. Return package paths and file paths, not prose.
|
||||
- **tests** — inventory the tests that already cover this surface and name the
|
||||
one test that would fail first if the change were wrong.
|
||||
|
||||
Cross-cutting:
|
||||
|
||||
- **overlap** — for all seven beads, the set of packages and files each one must
|
||||
modify, in one table.
|
||||
- **gate-cost** — time `task build` and `go test ./internal/app/controlplane/...`
|
||||
and report wall-clock, so Wave 2 timeouts are measured rather than guessed.
|
||||
- **dead-field** — grep `ui/src/` and `scripts/delivery-snapshot.sh` for every
|
||||
control-plane field name the server sends today, and flag any the server no
|
||||
longer sends. This is the failure class `task check` cannot see.
|
||||
- **contract-pairs** — find every place the validating side (State Store) and
|
||||
the executing side (archie-agent) must agree on the same vocabulary, and name
|
||||
the single test that would tie each pair together.
|
||||
|
||||
Every probe returns `structuredOutput` matching the schema in `wave0.js`. Long
|
||||
findings go to a file via `outputMode: "file-only"`; do not pull transcripts into
|
||||
your context.
|
||||
|
||||
**Do not let a recon child draw the conclusion.** A scout that measures correctly
|
||||
can still land the wrong call, and its write-up reads confident either way. Take
|
||||
their facts, make the call yourself.
|
||||
|
||||
---
|
||||
|
||||
## 7. Checkpoint A: lane plan, then stop
|
||||
|
||||
Build the conflict matrix from the `overlap` probe and the per-bead `blast`
|
||||
results. Two beads may be concurrent writers only if their file sets are
|
||||
disjoint. Directory names are not evidence of disjointness: check the imports.
|
||||
|
||||
Then report to Sam, in under 30 lines:
|
||||
|
||||
- the matrix, as bead by bead package intersections;
|
||||
- the proposed lanes, and which beads you are deliberately serializing;
|
||||
- any bead whose description no longer matches the tree, with the commit that
|
||||
moved underneath it;
|
||||
- the measured gate cost and the timeouts you derived from it;
|
||||
- anything in Wave 0 that contradicts section 2.
|
||||
|
||||
Wait for approval before Wave 1. This is the only mandatory stop.
|
||||
|
||||
---
|
||||
|
||||
## 8. Wave 1: shape-first, serial
|
||||
|
||||
Land the shared shape before anything forks against it. Five workers each adding
|
||||
a field to one struct produced eight cleanup commits on this repo in July; the
|
||||
merge cost scales with shared-file overlap, not worker count.
|
||||
|
||||
Sub-prompts for both children are in `prompts/wave1.md`.
|
||||
|
||||
1. **fwmp** alone: one `cp-writer`, `worktree: true`, red-green, gate
|
||||
`go test ./internal/domain/workflow/... ./internal/app/controlplane/... ./internal/app/agentworker/...`.
|
||||
Requirement: one contract test asserting the validating registry and the
|
||||
executing registry resolve the same step vocabulary. Two sides that each pass
|
||||
their own tests and disagree with each other is the exact failure this bead
|
||||
exists to prevent.
|
||||
2. Merge fwmp through the Wave 4 train immediately, before Wave 2 starts. Wave 2
|
||||
branches from the merged shape.
|
||||
3. **xrux investigation** runs concurrently with fwmp, because it is read-only
|
||||
until it has a verdict: one `cp-recon` writes a characterization test in a
|
||||
scratch worktree that answers the single question, does `Loader.overlayFile`
|
||||
zero omitted fields of a map-valued entry. It returns the verdict and the
|
||||
test, and nothing else. The verdict decides the i3qm lane's stages.
|
||||
|
||||
---
|
||||
|
||||
## 9. Wave 2: bounded writer lanes
|
||||
|
||||
One top-level call, `runs.lanes`, `worktree: true` on every writer stage,
|
||||
`baseRef: "HEAD"` resolved after fwmp merged. Four lanes, concurrency 4.
|
||||
|
||||
| Lane | Beads | Stages |
|
||||
|------|-------|--------|
|
||||
| `live` | nwa0 | red, green, self-gate, challenge |
|
||||
| `recovery` | 6zw0 | red, green, self-gate, challenge |
|
||||
| `steps` | 8szi | red, green, self-gate, challenge |
|
||||
| `config` | xrux then i3qm | verdict-apply, red, green, self-gate, challenge |
|
||||
|
||||
Stage contract, enforced by `wave2.js` and the `cp-writer` agent definition:
|
||||
|
||||
- **red**: write the failing table-driven test first, run it, and paste the
|
||||
failure. Verify the failure comes from an assertion, not a compile error. A
|
||||
test that cannot fail for an interesting reason is noise in the gate.
|
||||
- **green**: minimal implementation that satisfies the failing test.
|
||||
- **self-gate**: a typed `gate` pointed at
|
||||
`.pi/control-plane-run/gate-evidence.sh`, which runs the lane's package-scoped
|
||||
test command on the host and returns JSON that becomes the child's
|
||||
`structuredOutput`: branch, sha, changed files, uncommitted files, test exit
|
||||
and tail, plus the gate-gaming counters. Never `task check`. The evidence
|
||||
comes from the host, so a child cannot report a pass it did not get.
|
||||
- **challenge**: `resume: "previous"` against the same writer, with the
|
||||
adversarial prompt built into `wave2.js`'s challenge stage. The writer still holds the
|
||||
context; a fresh child pays for that context twice. Only resume a child
|
||||
`children.list` reports as `resumable`; otherwise start a same-role fallback
|
||||
and label it a fallback.
|
||||
|
||||
Each lane's writer also returns the evidence handoff in `wave2.js`: intent,
|
||||
non-goals, files with reasons, alternatives rejected, commands run with pasted
|
||||
output, the test that would fail first, and known limitations. A lane whose diff
|
||||
passes roughly 400 changed lines stops at a coherent boundary and reports what
|
||||
remains rather than growing further.
|
||||
|
||||
Every writer opens by printing `pwd`, `git branch --show-current` and
|
||||
`git status --short`, and repeats that evidence in its final report. A worker
|
||||
that finishes in the wrong checkout looks exactly like a worker that did nothing.
|
||||
|
||||
A failed stage blocks only its lane. Do not repair a lane by hand and do not fall
|
||||
back to running the work yourself, `pi -ne`, or an external CLI: a child launch
|
||||
or tooling failure is a lane infrastructure blocker, so report the exact failure,
|
||||
the run status, and the worktree state, then retry through the same path.
|
||||
|
||||
---
|
||||
|
||||
## 10. Review after every wave
|
||||
|
||||
`.pi/control-plane-run/review.js`, read-only `cp-reviewer` children on a
|
||||
different model family from the producer, one child per angle per target. The
|
||||
angles live in that script: `bead`, `invariant`, `contract`, `deadfield`,
|
||||
`boundary`, `operator`, `tests`, `gaming`, `intent`, plus `claims` for auditing
|
||||
recon findings.
|
||||
|
||||
| After | Targets | Angles |
|
||||
|-------|---------|--------|
|
||||
| Wave 0 | the recon findings themselves | `claims` |
|
||||
| Wave 1 | `cp/shape` | full set |
|
||||
| Wave 2 | the four lane branches | full set |
|
||||
| Wave 4 | merged `main` | `boundary`, `deadfield`, `contract` |
|
||||
| Wave 5 | the eju6 branch | `tests`, `operator`, `intent` |
|
||||
|
||||
The Wave 0 audit is the cheapest of these and catches the most: a recon child
|
||||
that measures correctly can still carry a wrong conclusion into your lane plan,
|
||||
and its write-up reads confident either way. Feed the audit the claims your lane
|
||||
plan is about to rest on, and check the load-bearing ones before Checkpoint A,
|
||||
not after.
|
||||
|
||||
Reviewers label findings P0/P1/P2 by evidence, not by severity language, carry
|
||||
`file:line` with a quoted proof, and end with one of `Merge verdict: BLOCK`,
|
||||
`Merge verdict: OK`, `Merge verdict: OK with notes`. Prose is never parsed for
|
||||
control flow: you decide the lane's fate from the findings.
|
||||
|
||||
Fixes go back to that lane's retained writer, batched into one pass, not one
|
||||
child per finding. Resume only a writer `children.list` reports as `resumable`;
|
||||
otherwise start a same-role fallback and label it as a fallback. A second failed
|
||||
fix on the same logic block means the lane is reverted and requeued, not patched
|
||||
again.
|
||||
|
||||
Count the pass as complete only when every angle returned. A missing angle is an
|
||||
unreviewed axis, not a clean one.
|
||||
|
||||
---
|
||||
|
||||
## 11. Wave 4: merge train, strictly serial
|
||||
|
||||
The procedure, with the exact commands, is in `prompts/wave4-merge-train.md`.
|
||||
One branch at a time, in dependency order, in the captain checkout at
|
||||
`/work/apps/archie-core`. Per branch:
|
||||
|
||||
1. `git merge-base --is-ancestor main <branch>`. A stale branch computed its
|
||||
deletions against code that has since changed; rebase or re-derive, never
|
||||
merge it as is.
|
||||
2. Apply the lane's handoff patch.
|
||||
3. `task check`, once, alone. Nothing else runs while it does.
|
||||
4. On failure: one fix pass through the lane's writer with the real output. On a
|
||||
second failure, revert the lane and requeue it; do not stack a third patch.
|
||||
5. Commit with a conventional scope (`feat(controlplane): ...`,
|
||||
`fix(config): ...`). Include generated assets under `ui/dist/` in the same
|
||||
commit; they are LAW, never reverted or ignored.
|
||||
6. `bd close <id>`. Do not stage `.beads/`.
|
||||
7. Verify it landed: `git log --oneline -1`, then
|
||||
`git branch --no-merged main`. Done has three states: no commits, committed
|
||||
and unmerged, merged. Only the third counts.
|
||||
|
||||
Your own edits get the same gate as the children's. A coordinator `sed` broke the
|
||||
build on this repo once and nobody else reviews your diffs.
|
||||
|
||||
---
|
||||
|
||||
## 12. Wave 5: eju6
|
||||
|
||||
Sub-prompt in `prompts/wave5-eju6.md`. Last, against merged `main`. One lane: an end-to-end test that drives a change
|
||||
through the API, restarts a process, and asserts the change survived. Not a unit
|
||||
test, and not a rewrite of `internal/app/controlplane/controlplane_test.go`,
|
||||
which covers seeding and catalog only. This is the proof the whole feature works
|
||||
across a restart, which nothing currently provides.
|
||||
|
||||
If it fails, that is a finding about the feature, not about the test. Report it
|
||||
and stop rather than weakening the assertion.
|
||||
|
||||
---
|
||||
|
||||
## 13. Final report
|
||||
|
||||
- Beads closed, with the commit that closed each one.
|
||||
- Beads deliberately not attempted, and why.
|
||||
- `task check` result on final `main`, quoted, not summarized.
|
||||
- Every branch still unmerged, and whether it holds work.
|
||||
- Commits now local and unpushed (`git log --oneline origin/main..main`), stated
|
||||
as fact without pushing.
|
||||
- Anything you found that contradicts `docs/prds/runtime-control-plane.md` or
|
||||
section 2 of this prompt, filed as a new bead.
|
||||
- New beads for identified debt or follow-ups, filed via `bd`.
|
||||
- The wave metrics: per wave, reviewer findings raised versus accepted, lanes
|
||||
blocked by the gate versus by review, rework passes per lane, and wall-clock
|
||||
from lane start to merged. Say which stage was the constraint in practice and
|
||||
whether it matched the prediction that review would be.
|
||||
- The risk-routed surfaces that changed and need Sam's eyes: the fail-closed
|
||||
boot path, the State Store wire contract and error sentinels, grants and
|
||||
credentials, anything touching `archie.db`, and the release or CI surface.
|
||||
@@ -0,0 +1,43 @@
|
||||
# Worked example: archie-core control plane, September 2026
|
||||
|
||||
A real run, frozen partway through, kept verbatim so the shapes can be read
|
||||
rather than re-derived. It is repository-specific on purpose: the value is in
|
||||
seeing how much project knowledge a good brief carries.
|
||||
|
||||
**Its scripts are the snapshot's, not the current ones.** This directory was
|
||||
captured mid-run, so the scripts in it predate fixes the skill's own lessons
|
||||
describe — the typed-gate boolean trap, the post-fix re-gate and re-review, the
|
||||
P2 handling, the build and lint checks in the gate.
|
||||
`~/.agents/skills/high-throughput-programming/scripts/` and
|
||||
`~/.agents/skills/high-throughput-programming/templates/` are normative; if this
|
||||
directory disagrees with them, they win. Read the briefs, the lane plan and the
|
||||
merge-train procedure here. Do not copy the scripts.
|
||||
|
||||
The method this run followed lives in the user-scope skill
|
||||
`~/.agents/skills/high-throughput-programming/`; it is normative for method. This
|
||||
repository's `archie-agent-fleet` skill is normative for facts about archie-core.
|
||||
A run in another repository uses that skill's `templates/` plus its own filled-in
|
||||
briefs — none of the archie specifics here transfer.
|
||||
|
||||
Seven tracker items, one shared shape, four lanes, a review pass after every
|
||||
wave, a serial merge train.
|
||||
|
||||
| File | Note |
|
||||
|------|------|
|
||||
| `00-orchestrator.md` | The filled orchestrator prompt. Section 2 is the project's ground truth, section 5a the review-is-the-constraint doctrine, section 10 the review cadence. |
|
||||
| `lanes.json` | Lane briefs carrying intent, traps and `file:line` premises. Read one to see the level of detail a brief needs. |
|
||||
| `prompts/wave1.md` | The shared shape, plus an investigation whose verdict gated another lane. |
|
||||
| `prompts/wave4-merge-train.md` | The serial merge procedure with the project's own hazards in it. |
|
||||
| `agents/` | The three agent definitions with project invariants inlined. |
|
||||
|
||||
No scripts are copied here. This run's `wave0.js`, `wave2.js`, `review.js` and
|
||||
`gate-evidence.sh` became `templates/recon.js`, `templates/lanes.js`,
|
||||
`templates/review.js` and `scripts/gate-evidence.sh` in the user-scope skill;
|
||||
those are normative, and this directory's stale copies were deleted so there is
|
||||
exactly one of each to keep current.
|
||||
|
||||
What this run's Wave 0 actually caught, which is the argument for recon before
|
||||
fanout: three of the seven items had premises that no longer matched the tree,
|
||||
including one whose target file did not exist under the name the item used, one
|
||||
whose anchor had moved commits earlier, and one whose scope could not reach the
|
||||
clause it cited. All three would have produced confidently wrong lanes.
|
||||
@@ -0,0 +1,105 @@
|
||||
# Control-plane backlog run: how to drive it
|
||||
|
||||
This is the committed copy of a real run. Its originals lived in
|
||||
`/work/apps/archie-core/.pi/control-plane-run/`, which is gitignored, disposable
|
||||
run state whose live copies may have moved on since. Nothing here is load
|
||||
bearing at runtime.
|
||||
|
||||
The method is not here. The pipeline shape, the concurrency ceilings, the
|
||||
pi-subagents traps, and the `scripts/` and `templates/` this file names all live
|
||||
in the user-scope skill `~/.agents/skills/high-throughput-programming/`, and that
|
||||
skill is normative for method. This copy is normative only for what the run
|
||||
looked like on this repository; the archie-specific facts themselves live in the
|
||||
parent `archie-agent-fleet` skill. A run in another repository uses that skill's
|
||||
`templates/` plus its own filled-in briefs.
|
||||
|
||||
## Files
|
||||
|
||||
| File | What it is |
|
||||
|------|------------|
|
||||
| `00-orchestrator.md` | The prompt you give pi. It owns the waves, the ceilings and the verification rules. |
|
||||
| *(the scripts)* | This run's `wave0.js`, `wave2.js`, `review.js` and `gate-evidence.sh` are **not copied here**: they live on as `templates/recon.js`, `templates/lanes.js`, `templates/review.js` and `scripts/gate-evidence.sh` under `~/.agents/skills/high-throughput-programming/`, which are normative. The snapshot's copies were stale, so they were deleted rather than duplicated. |
|
||||
| `lanes.json` | Lane definitions: worktree paths, branches, beads, scoped test commands, briefs. Fill in the model id. |
|
||||
| `prompts/wave1.md` | fwmp shape-first writer, and the xrux verdict probe. |
|
||||
| `prompts/wave4-merge-train.md` | The serial merge procedure and the landing checks. |
|
||||
| `prompts/wave5-eju6.md` | The end-to-end restart test. |
|
||||
| `agents/cp-recon.md`, `agents/cp-writer.md`, `agents/cp-reviewer.md` | Project-scope agent definitions, as the run used them from `.pi/agents/`; these committed copies sit beside this file. |
|
||||
|
||||
## Start it
|
||||
|
||||
```fish
|
||||
cd /work/apps/archie-core
|
||||
pi "$(cat .pi/control-plane-run/00-orchestrator.md)"
|
||||
```
|
||||
|
||||
The `.pi/control-plane-run/` path is the run's own state directory, not this
|
||||
copy. Interactive is the right mode here: Checkpoint A after Wave 0 is a real
|
||||
stop and wants you in the loop. `/subagents-fleet` opens the live inspector,
|
||||
`/subagents-doctor` checks the install.
|
||||
|
||||
## Before Wave 2
|
||||
|
||||
Create the durable worktrees yourself. Managed `worktree: true` children capture
|
||||
a patch and then remove the worktree, which a resumed challenge stage cannot
|
||||
edit, so the lanes use operator-created worktrees plus per-child `cwd`.
|
||||
|
||||
```fish
|
||||
for lane in live recovery steps config
|
||||
git -C /work/apps/archie-core worktree add ../cp-$lane -b cp/$lane
|
||||
end
|
||||
```
|
||||
|
||||
A lane worktree is a **sibling** of the repository, so `.pi/agents/` inside the
|
||||
repository is not discovered from it. Link it per worktree or the children fail
|
||||
with `Unknown agent: cp-writer`:
|
||||
|
||||
```fish
|
||||
for lane in live recovery steps config
|
||||
mkdir -p /work/apps/cp-$lane/.pi
|
||||
ln -sfn /work/apps/archie-core/.pi/agents /work/apps/cp-$lane/.pi/agents
|
||||
end
|
||||
```
|
||||
|
||||
Then fill `model` in `lanes.json` from what `subagent({ action: "models" })`
|
||||
resolves, and pass it as `args`.
|
||||
|
||||
## Ceilings worth knowing before you tune anything
|
||||
|
||||
This install is `pi-subagents` **0.70.0**, matching your clone except for four
|
||||
doc files. Two 0.69/0.70 features are load bearing here: typed gates
|
||||
(`gate: { command, output: "json" }` turns a host command's JSON stdout into the
|
||||
child's `structuredOutput`) and `allowedAgents`, which can stop a reviewer
|
||||
launching a writer if you want separation of duties enforced rather than
|
||||
instructed.
|
||||
|
||||
- `globalConcurrencyLimit` defaults to **20**, not 64. Set it per top-level call.
|
||||
- `maxSubagentSpawnsPerRun` defaults to **64** cumulative admissions per run
|
||||
tree, never refunded, so retries spend it. Each wave is a separate top-level
|
||||
run precisely so each gets its own budget.
|
||||
- `runs.lanes` caps at 32 lanes, 16 stages per lane, 64 stages total.
|
||||
- `gate` is rejected on a retained `resume` item, which is why the challenge
|
||||
stage runs its tests through `bash` instead.
|
||||
- A typed gate cannot be combined with `outputSchema` on the same child, so the
|
||||
writer stages carry the gate and the reviewers carry the schema.
|
||||
- Host steps have no per-step `cwd`, which is why `gate-evidence.sh` takes the
|
||||
worktree path as its first argument instead of relying on one.
|
||||
|
||||
## Why the fleet is not 64 writers
|
||||
|
||||
64 concurrent children is comfortable for read-only work and pointless for
|
||||
writers here. Two limits bite first:
|
||||
|
||||
1. **Overlap.** Merge cost scales with shared file overlap, not worker count.
|
||||
Seven beads reduce to four genuinely disjoint lanes plus one shared shape
|
||||
that has to land alone first. Five workers each adding a field to one struct
|
||||
cost eight cleanup commits on this repo in July.
|
||||
2. **The machine.** 16 cores, 117 Go packages, and `task check` also runs the
|
||||
dashboard tests. One full gate saturates the host, so the gate is serialized
|
||||
into the merge train and writers run package-scoped tests.
|
||||
|
||||
The throughput comes from recon and review: 25 recon children, then a review
|
||||
pass after every wave at up to 36 children, all read-only, all cheap, all
|
||||
genuinely parallel. The writers stay at four because that is what the
|
||||
repository's coupling and the review pass can absorb. The measured literature is
|
||||
consistent that review, not generation, is where agent-heavy pipelines stall, so
|
||||
spare concurrency goes into checking rather than into more lanes.
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
name: cp-recon
|
||||
description: Read-only recon on archie-core. Traces call sites, extracts spec clauses, inventories tests. Returns citations, never conclusions.
|
||||
tools: read, grep, find, ls, bash
|
||||
excludeTools: write, edit
|
||||
acceptanceRole: read-only
|
||||
completionGuard: false
|
||||
inheritProjectContext: true
|
||||
inheritGlobalContext: false
|
||||
inheritSkills: false
|
||||
thinking: high
|
||||
systemPromptMode: replace
|
||||
---
|
||||
|
||||
You are a read-only investigator in the archie-core Go repository. You measure; you do not decide.
|
||||
|
||||
Rules:
|
||||
|
||||
- Never edit, write, stage, commit, or run anything that mutates the tree. `bash` is for `git log`, `grep`, `go list`, `bd show`, and timing commands only.
|
||||
- Every claim carries `file:line`. A claim without a citation is not a finding, it is a guess.
|
||||
- Report facts. The orchestrator draws the conclusion. Do not recommend a course of action unless you were asked for one, and never close or reopen a bead.
|
||||
- Grep first, then read only the lines that matter. Do not pull whole packages into context.
|
||||
- Directory and bead names are not evidence of coupling. Check the imports.
|
||||
- `ARCHITECTURE.md` and `CLAUDE.md` are stale by construction in this repo. The tree is the only evidence of current state; when a doc and the code disagree, report both and say which file you read.
|
||||
- If your task's premise is false, say so plainly as your first line instead of answering the question you were asked.
|
||||
|
||||
Finish with your structured output. Keep prose under 40 lines; long inventories belong in your output file.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
name: cp-reviewer
|
||||
description: Read-only adversarial reviewer for one archie-core lane and one angle. Evidence-labelled findings and a single merge verdict.
|
||||
tools: read, grep, find, ls, bash
|
||||
excludeTools: write, edit
|
||||
acceptanceRole: read-only
|
||||
completionGuard: false
|
||||
inheritProjectContext: true
|
||||
inheritGlobalContext: false
|
||||
inheritSkills: false
|
||||
thinking: high
|
||||
systemPromptMode: replace
|
||||
---
|
||||
|
||||
You review one lane of archie-core work from one angle. You did not write this code and you do not fix it.
|
||||
|
||||
Start from `git diff main..<branch>` and `git diff --stat main..<branch>`. Review the diff, never the writer's transcript: the transcript costs context and carries almost no signal.
|
||||
|
||||
What you are looking for, in order:
|
||||
|
||||
1. Behaviour the change dropped while keeping the shape. Refactors lose guards. Read every new or changed doc comment: one that describes a silent fallback is usually a confession.
|
||||
2. A claim in the diff that the code does not support.
|
||||
3. A test that restates an assignment or a constant instead of failing for an interesting reason.
|
||||
4. Two sides that must agree and have no test tying them together.
|
||||
|
||||
Rules:
|
||||
|
||||
- Read-only. Do not edit, stage, commit, or fix. Propose the fix in words.
|
||||
- Every finding carries `file:line` and a quoted proof.
|
||||
- Label by evidence, not by how bad it sounds: P0 breaks a user-reachable path or an invariant, P1 is a real defect with a bounded blast radius, P2 is worth fixing but not now.
|
||||
- "No finding" is a valid and useful answer. Do not manufacture findings to look thorough.
|
||||
- `task check` passing is not evidence of correctness: it cannot see a field the server stopped sending, because optional chaining makes a dead dashboard binding typecheck.
|
||||
|
||||
End with exactly one line: `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
name: cp-writer
|
||||
description: Implementation worker for archie-core lanes. Red-green TDD in an isolated worktree, package-scoped gate, no suppression.
|
||||
tools: read, write, edit, grep, find, ls, bash
|
||||
acceptanceRole: writer
|
||||
inheritProjectContext: true
|
||||
inheritGlobalContext: false
|
||||
inheritSkills: false
|
||||
thinking: high
|
||||
timeoutMs: 5400000
|
||||
systemPromptMode: replace
|
||||
---
|
||||
|
||||
You implement one lane of work in the archie-core Go repository, inside your own git worktree.
|
||||
|
||||
Open every run by printing `pwd`, `git branch --show-current` and `git status --short`, and repeat all three in your final report. A worker that finishes in the wrong checkout looks exactly like one that did nothing.
|
||||
|
||||
Method:
|
||||
|
||||
1. Read the bead with `bd show <id>`, then `CLAUDE.md` and `docs/architecture/organisation.md`.
|
||||
2. Red: write the failing table-driven test first. Run it. Paste the failure. Confirm it fails on an assertion, not a compile error. A test that cannot fail for an interesting reason is noise in the gate.
|
||||
3. Green: the minimal implementation that satisfies the test.
|
||||
4. Run your lane's scoped test command. Never run `task check`: it saturates the machine and the merge train owns it.
|
||||
5. Commit on your lane branch with a conventional-commit subject scoped by package (`feat(controlplane): ...`).
|
||||
|
||||
Hard rules:
|
||||
|
||||
- Fix invalid state at the producer, not with a defensive check at the consumer.
|
||||
- Never suppress: no `//nolint`, no `t.Skip`, no build tag that hides a failing test, no deleted assertion. If a lint is wrong, leave it failing and say why.
|
||||
- Adopt `task fmt` output verbatim. Never revert a formatter or linter diff.
|
||||
- Two failed fixes on the same logic block means you rewrite the block, not patch it a third time. Prefer a clean 20-line rewrite over a 5-line band-aid.
|
||||
- Dependency flow is `cmd -> app -> {domain, infrastructure}`, with infrastructure implementing domain contracts. Nothing in `internal/webui` may reach `internal/domain/workflow`.
|
||||
- Do not widen scope. Work not asked for is a finding to report, not work to do.
|
||||
- Do not merge, do not push, do not touch `.beads/`, do not edit the main checkout.
|
||||
- Scratch files live in `/tmp`. Never in the working tree.
|
||||
- If the bead describes a world the tree no longer has, stop and report that instead of implementing it.
|
||||
|
||||
Your final report states: the commit sha, changed files, the scoped test command and its result, what you deliberately did not do, and any residual risk.
|
||||
@@ -0,0 +1,47 @@
|
||||
{
|
||||
"model": "REPLACE_WITH_STRONG_TIER_ID",
|
||||
"timeoutMs": 5400000,
|
||||
"lanes": [
|
||||
{
|
||||
"key": "live",
|
||||
"dir": "/work/apps/cp-live",
|
||||
"branch": "cp/live",
|
||||
"beads": [
|
||||
"archie-core-nwa0"
|
||||
],
|
||||
"test": "go test ./internal/app/controlplane/... ./internal/domain/applystatus/... -count=1 && go vet ./internal/app/controlplane/... ./internal/domain/applystatus/...",
|
||||
"brief": "Wave 0 and its claims audit corrected this bead's premise, and the correction is the work. There is not one live apply path, there are two, and the PRD clause (Archie starts and checks a replacement before switching, and if the check fails the old one keeps running) applies to both. (1) workflow-execution-settings is applied on a watch (internal/app/archied/control_plane.go:94) and reports apply status at :118. (2) personas is also watched and applied live in the same process (internal/app/archied/gateway_runtime.go:37 watch, :79-86 apply) and reports NO apply status at all, so personas is the live-watched kind that widens this bead. Correction to the earlier version of this brief: workflow-definitions is not applied by a daemon watch, but do not read that as \"no watch anywhere\" -- the webui streams it at internal/webui/api_control_plane.go:139, which is a generic SSE passthrough for any kind. That is a read path, not a component-replacement path, so it does not widen nwa0. What the audit also established: the hard-coded nil at control_plane.go:118 is inert (no path in applyWorkflowExecutionSettings can fail), so do not build the bead around \"the report path cannot carry a rejection\"; that framing is wrong. Order of work: add the build-and-probe step to the live apply path, retain the previous component when the check fails, and report the failure through the apply-status surface. Decide explicitly whether personas gets the same treatment in this bead or a follow-up bead; if it is a follow-up, file the bead rather than half-wiring it. Do NOT fix the watch-reconnect defect opportunistically: it is filed separately as archie-core-yrmr, and a defect found by a review pass must not be silently repaired inside another lane. Apply status is on the State Store contract, not the control plane: PutApplyStatus/ListApplyStatus are administrative, keyed on (process, kind), replaced in place, re-stamped every 30s, stale at 90s, and a stale record renders as \"Not reporting\", never as current. applystatus.New refuses a process name Processes() does not list, deliberately: an invented name would read as a process that is not running, which the PRD blesses as legitimate, so the failure would be invisible."
|
||||
},
|
||||
{
|
||||
"key": "recovery",
|
||||
"dir": "/work/apps/cp-recovery",
|
||||
"branch": "cp/recovery",
|
||||
"beads": [
|
||||
"archie-core-6zw0"
|
||||
],
|
||||
"test": "go test ./cmd/... ./internal/infrastructure/staterpc/... -count=1 && go vet ./cmd/...",
|
||||
"brief": "DECIDED: subcommands of cmd/archie-state-store (backup, restore, validate, rollback). Not a new binary. Sam's standing rule, restated 2026-09-21 and now recorded in docs/architecture/organisation.md#process-boundaries: a cmd/ entry is a process boundary, earned only when a surface fails independently of the rest of the fleet or when that process may need to run in more than one location (HA pair, NAT traversal, separate host). Operational commands over a surface an existing binary already owns are subcommands of it. Do not reopen this. Two premise corrections from Wave 0 that change the work. First, the file is <dir>/archie.db-tasks.sqlite (cmd/archie-state-store/main.go:290-292, asserted at main_test.go:435-439), not archie.db, so a command that operates on 'archie.db' by name operates on nothing. Second, part of this already exists in shell: scripts/archie-update-install:189 takes a sqlite3 .backup of the task database and describes it as the watchdog's only route back from a forward schema migration. That makes this bead partly consolidation. The subcommand becomes the one authoritative implementation and the install script calls it, rather than a Go path and a shell path that drift apart. Changing that script is in scope for this lane; the watchdog's refusal semantics (an update that cannot back up must not start) must survive the change unchanged. The command operates on the database file directly with the State Store stopped, refuses to run against a live store, and adds no rollback RPC: a revision carries its value and restoring replays it through the ordinary replace."
|
||||
},
|
||||
{
|
||||
"key": "steps",
|
||||
"dir": "/work/apps/cp-steps",
|
||||
"branch": "cp/steps",
|
||||
"beads": [
|
||||
"archie-core-8szi"
|
||||
],
|
||||
"test": "go test ./internal/domain/workflow/... ./internal/app/agentworker/... -count=1 && go vet ./internal/domain/workflow/...",
|
||||
"brief": "internal/domain/workflow/steps.go:215 and :227 hard-error on legacy .archie/stages/*.go and .archie/gate.go and tell the operator to migrate to a registered YAML workflow step, but BuiltinStepRegistry() only exposes the six shipped workflows' own stages, so there is nothing to migrate to. Identify what the removed hooks actually did and land the equivalent as registered step types. This lane starts only after archie-core-fwmp has merged, and registers against the extension point fwmp created. Do not re-open the registry design."
|
||||
},
|
||||
{
|
||||
"key": "config",
|
||||
"dir": "/work/apps/cp-config",
|
||||
"branch": "cp/config",
|
||||
"beads": [
|
||||
"archie-core-xrux",
|
||||
"archie-core-i3qm"
|
||||
],
|
||||
"test": "go test ./internal/infrastructure/configuration/... ./internal/app/archied/... -count=1 && go vet ./internal/infrastructure/configuration/... ./internal/app/archied/...",
|
||||
"brief": "Two beads in order, one package owner. First archie-core-xrux. The verdict is already measured with evidence (Wave 0R claims audit c6) and it is ZEROES: the -config-overlay file path silently drops every field a partial map-valued entry omits, which is exactly the archie-core-e2e2 hazard, and it is user-reachable because deployments/dev.toml is the documented -config-overlay argument and sets [services.state] target/listen, while the base config.toml is where [services.state].target_token lives -- so the overlay drops the token. The red stage is a committed characterization test through the production entry point (Loader.Resolve / -config-overlay) that loads a config with a populated map-valued entry, overlays a file setting one sibling key, and asserts the omitted keys survive; it fails today. Then move apply.go's foldOverrides (apply.go:60) onto the file overlay path (loader.go:161-194, decode at :176) so it passes. Do NOT delete apply.go, apply_test.go or Loader.ApplyOverlay: the hazard they were written for is live on that path. No dotted-path field merge is wanted beyond this guard, because the control plane replaces whole documents. Then archie-core-i3qm, whose anchor and scope the audit corrected. control_plane.go:13 is a blank line (the doc comment is :14-18); the calls moved to :20 (RuntimeConfig) and :27 (configuration.Validate) in 9accf112. More importantly the PRD clause names State Store startup, and state_store.go:75-104 never calls runtimeConfig: it reaches Loader.finalize via bootstrap.go:263 (the loader.Resolve call site, not finalize itself) and loader.go:341-346, where Validate runs. Scope correction: that file-only Validate runs before loadRuntimeConfig for ALL THREE binaries (main.go:358, gateway.go:61, state_store.go:78), so it is not state-store-specific; and a value that is valid alone but invalid only after the DB merge never blocks the state store at all, because it is imported unvalidated at state_store.go:104 and fails later in the daemon's loadRuntimeConfig (control_plane.go:27). Reduce the bootstrap document to the fields the PRD lists (database path, listen addresses, credentials, TLS, encryption-key references) and stop validating the migrated surface at startup, so a stale TOML value in a database-owned field cannot fail boot. boot.runtimeConfig is the one layering call and the SIGHUP callback makes the same call: if you add a database-owned layer, add it there and nowhere else."
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,72 @@
|
||||
# Wave 1 sub-prompt: shape first
|
||||
|
||||
**One child. fwmp alone.** Nothing else runs until it merges, and Wave 2 branches
|
||||
from the merged shape.
|
||||
|
||||
xrux is no longer a Wave 1 probe. Its verdict is already measured with evidence
|
||||
(Wave 0R claims audit c6) and the answer is **ZEROES**. Re-measuring buys nothing,
|
||||
so the characterization test is folded into the `config` lane's red stage, where
|
||||
it is committed and the evidence lives in the tree rather than in a transcript.
|
||||
See the `config` brief in `lanes.json`.
|
||||
|
||||
---
|
||||
|
||||
## fwmp: the shared shape (cp-writer, worktree `/work/apps/cp-shape`, branch `cp/shape`)
|
||||
|
||||
Gate: `go test ./internal/domain/workflow/... ./internal/app/controlplane/... ./internal/app/agentworker/... -count=1`
|
||||
|
||||
```text
|
||||
Bead archie-core-fwmp. Run `bd show archie-core-fwmp` first.
|
||||
|
||||
docs/prds/runtime-control-plane.md:95 says plugins can add step types. Today every
|
||||
call site hardcodes workflow.BuiltinStepRegistry():
|
||||
internal/app/agentworker/task_execution.go:319 and :335,
|
||||
internal/app/controlplane/workflow_definitions.go:26 and :33, and
|
||||
internal/app/controlplane/client.go:41. The step vocabulary is closed to the six
|
||||
shipped workflows.
|
||||
|
||||
Verified by the Wave 0 claims audit, so treat as fact and do not re-derive:
|
||||
- Those are exactly five non-test call sites, plus five test call sites.
|
||||
- BuiltinStepRegistry() is defined at internal/domain/workflow/definition.go:149 and
|
||||
is built only from legacyBuiltinWorkflows() (definition.go:181).
|
||||
- StepRegistry is a plain `map[string]StepFactory` (definition.go:32). There is no
|
||||
merge/widen function; BuiltinStepRegistry() is itself the only registration site.
|
||||
- All five production call sites pass the identical function, so nothing diverges
|
||||
today. The gap is the absence of a guard, not a live defect.
|
||||
|
||||
Deliver: a registry assembled from the plugin set, resolved identically on both
|
||||
sides.
|
||||
|
||||
The load-bearing constraint is not the extension point, it is agreement. The
|
||||
validating side is the State Store; the executing side is archie-agent. A
|
||||
definition that validates and then fails to compile at run time is the failure
|
||||
this bead exists to prevent, and it is exactly the failure two packages that each
|
||||
pass their own tests produce. No test today ties the two sides: no test file
|
||||
imports both internal/app/controlplane and internal/app/agentworker. Your change
|
||||
is not done until one test asserts that both sides resolve the same step
|
||||
vocabulary from the same plugin set. Write that test first and let it fail for the
|
||||
right reason.
|
||||
|
||||
Do NOT edit internal/domain/workflow/definition_test.go:8
|
||||
TestParseDefinitionRejectsUnsafeDefinitions. The audit established it is not an
|
||||
obstacle: its pin is name-exact ("shell" at :11, implement.prepare's own factory at
|
||||
:12), so a settings-bearing plugin step type under any other name passes it
|
||||
unchanged. Adding a step type is archie-core-8szi's lane, not this one.
|
||||
|
||||
Do NOT fix the workflow-version pin opportunistically. The audit found it is never
|
||||
persisted over gRPC and its digest guard is dead in production; that is filed as
|
||||
archie-core-zf8h and gets its own lane and Sam's eyes. Report it if you touch it,
|
||||
do not repair it here.
|
||||
|
||||
Before adding a plugin engine surface, satisfy
|
||||
ARCHITECTURE.md#plugin-engine-rule-strict.
|
||||
|
||||
This is the shape every other lane branches from, so it lands alone and it lands
|
||||
first. Do not implement any step type; archie-core-8szi does that afterwards
|
||||
against what you build. Do not widen scope to the .archie gate behaviour.
|
||||
|
||||
Working contract: print pwd, git branch --show-current and git status --short
|
||||
before editing and repeat them in your report. Red then green. Package-scoped
|
||||
tests only, never `task check`. No //nolint, no t.Skip, no deleted assertions.
|
||||
Adopt `task fmt` verbatim. Commit on cp/shape with a conventional subject.
|
||||
```
|
||||
+62
@@ -0,0 +1,62 @@
|
||||
# Wave 4: merge train
|
||||
|
||||
Serial. You run this yourself in the captain checkout at
|
||||
`/work/apps/archie-core`. No subagent owns `main`, and only one `task check`
|
||||
exists at a time.
|
||||
|
||||
Order: `cp/shape` (already merged in Wave 1), then `cp/config`, `cp/live`,
|
||||
`cp/recovery`, `cp/steps`. Config goes early because it owns the bootstrap path
|
||||
the others boot through.
|
||||
|
||||
## Per branch
|
||||
|
||||
```bash
|
||||
BR=cp/live
|
||||
|
||||
git -C /work/apps/archie-core status --short # must be clean
|
||||
git merge-base --is-ancestor main $BR && echo "stale: rebase required"
|
||||
git log --oneline main..$BR
|
||||
git diff --stat main..$BR
|
||||
```
|
||||
|
||||
A branch that predates a merge computed its deletions against code that has
|
||||
since changed. On this repo a stale branch's diff deleted 460 lines of
|
||||
`internal/config` that read as tidy relocation and would have reverted another
|
||||
lane's decomposition. Rebase it or re-derive the work. Never merge a diff whose
|
||||
deletions were computed against code that has moved.
|
||||
|
||||
Then:
|
||||
|
||||
1. `git merge --no-ff $BR` (or apply the lane's handoff patch if the lane ran in
|
||||
a managed worktree).
|
||||
2. `task build --force`, then `task check`, once, alone. Nothing else runs on this machine while it does. The force-build is required until archie-core-hhgw lands: `task build`'s sources are Go-only (Taskfile.yml:325), so a ui/dist-only change does not retrigger it and a stale embedded dashboard would ship (Wave 0R audit c10).
|
||||
3. On failure: one fix pass back to that lane's retained writer with the real
|
||||
output pasted in, not a summary. On a second failure, `git reset --hard` the
|
||||
merge, requeue the lane, and move to the next branch. Do not stack a third
|
||||
patch, and do not fix it yourself unless the fix is one line and obvious.
|
||||
4. Commit generated assets in the same commit. `ui/dist/` and schema outputs are
|
||||
LAW: never regenerated away, never reverted, never left out.
|
||||
5. `bd close <id>` for each bead the branch delivered. Do not stage `.beads/`,
|
||||
and never create a commit whose only content is beads bookkeeping.
|
||||
|
||||
## Landing check, every time
|
||||
|
||||
```bash
|
||||
git log --oneline -3
|
||||
git branch --no-merged main
|
||||
git log --oneline origin/main..main
|
||||
```
|
||||
|
||||
Done has three states: no commits, committed and unmerged, merged. Only the
|
||||
third counts. A closed bead is what a worker believed, not what landed.
|
||||
|
||||
## Your own edits
|
||||
|
||||
A coordinator `sed` rename on this repo once produced `&fakeStore{fakeStore{` in
|
||||
six places and broke the build. Your edits get the same gate as the children's,
|
||||
and nobody else reviews them.
|
||||
|
||||
## Do not push
|
||||
|
||||
Sam pushes manually and does not always announce it. Report what is unpushed as
|
||||
fact. If `git log origin/main..main` is long, say how long; do not act on it.
|
||||
@@ -0,0 +1,53 @@
|
||||
# Wave 5: eju6, the end-to-end restart test
|
||||
|
||||
One lane, one `cp-writer`, against merged `main`. This is the only bead that
|
||||
proves the feature rather than adding to it, so it runs last and alone.
|
||||
|
||||
Gate: `cd <worktree> && go test ./internal/app/controlplane/... -count=1`,
|
||||
then `task check` through the merge train as usual.
|
||||
|
||||
```text
|
||||
Bead archie-core-eju6. Run `bd show archie-core-eju6` first.
|
||||
|
||||
docs/prds/runtime-control-plane.md ("First implementation") lists an end-to-end
|
||||
restart test as a deliverable and there is none.
|
||||
internal/app/controlplane/controlplane_test.go covers seeding and catalog only.
|
||||
No test drives a change through the API, restarts a process, and asserts the
|
||||
change survived.
|
||||
|
||||
Deliver that test: a real end-to-end check, not a unit test, and not a rewrite
|
||||
of the existing file.
|
||||
|
||||
It must, in one test:
|
||||
1. write a settings change through the control-plane API, as the dashboard
|
||||
would, attributing to identity.SystemID;
|
||||
2. observe the change land in the audit trail as an ordinary edit;
|
||||
3. restart the process that consumes it;
|
||||
4. assert the process came back on the stored value, not the file value;
|
||||
5. assert the apply-status row for that process reports the version it
|
||||
applied, and that a record older than 90 seconds reads as "not reporting"
|
||||
rather than as current.
|
||||
|
||||
Facts you need and must not re-derive:
|
||||
- boot.runtimeConfig is the single layering call, and the SIGHUP reload makes
|
||||
the same call over the document it just resolved (9af013eb). A reload cannot
|
||||
revert a database-owned setting to its file value, and that is the property
|
||||
under test.
|
||||
- Execution budgets arrive on a watch, not a resource query, so boot records
|
||||
the last settings it applied and the reload re-applies them from there.
|
||||
- PutApplyStatus/ListApplyStatus are administrative on the State Store
|
||||
contract: a task-scoped grant is denied both by the deny-by-default arm of
|
||||
authorizesTaskScopedCall. Your harness needs the administrative token.
|
||||
- Rows are keyed on (process, kind) and replaced in place; every process
|
||||
re-stamps every 30 seconds.
|
||||
- The control plane fails closed: a stored value that will not validate stops
|
||||
archied starting.
|
||||
|
||||
If the test fails, that is a finding about the feature, not about the test.
|
||||
Report the failure with the output and stop. Do not weaken an assertion, do not
|
||||
add a retry loop to paper over a race, and do not mark it t.Skip.
|
||||
|
||||
If a real end-to-end restart cannot be driven in-process, say so explicitly and
|
||||
describe what harness it would need, rather than substituting a unit test that
|
||||
asserts less and claims the bead.
|
||||
```
|
||||
Reference in new issue
Block a user