# How I run an agentic engineering team

My working reference: planning skills, parallel sessions, messaging, scripts and provider adapters. October 14, 2026. This describes my current implementation and what readers can copy; it is still evolving.

[Back to the playbook](https://hamedtaheri.com/playbook/v0.2.0/index.html) · [Give the workflow guide to your AI](https://hamedtaheri.com/playbook/v0.2.0/agent/workflows.md) · [Machine-readable script catalog](https://hamedtaheri.com/playbook/v0.2.0/reference/script-catalog.json)

## The progression

| Stage | How I work | What coordinates it |
|---|---|---|
| Detailed planning | Explore options, settle a specification, then write an implementation plan with exact files, dependencies and checks | Planning skills and a human who accepts the decisions |
| Parallel interactive sessions | Independent deliverables in separate worktrees; sessions exchange focused updates and request decisions | Accepted plan, task ownership, messages and durable handoffs |
| Scripted headless sessions | Fresh bounded workers and reviewers, selected provider, recorded outcomes, capped fix loops | Deterministic scripts, ledgers, environment checks and a human decisions inbox |

These modes coexist. I still use interactive sessions for design, investigation and decisions. Ready execution work can move through scripts without a long model conversation routing every step.

![Parallel sessions sharing focused messages around an accepted plan](https://hamedtaheri.com/playbook/v0.2.0/figures/parallel-sessions-modern.png)

*Conceptual illustration generated for this draft. It does not encode a measured productivity result.*

## 1. Spec first, implementation plan second

I used design and planning skills to turn a broad goal into a contract several sessions could follow. The specification covers observable behavior, non-goals, accepted product decisions, exact interfaces/schema, compatibility and failure cases. The implementation plan turns that contract into reviewable parts: named files, dependency order, verification commands, required environments and review points.

For example, define a notification contract before splitting schema, API, SDK and documentation work. A session writing an SDK cannot safely infer a response shape from “the API session is handling that.” Put the exact agreed shape in the spec and link its revision. An interface change needs an update to dependent lanes.

Sensitive or multi-surface tasks retain **Invariants** and a **Test matrix**. A prepared brief has six fields: outcome, acceptance, spec/plan reference at revision, files/interfaces, verification and branch/base. Small tasks can use a small brief. Complexity determines how much detail must survive compression.

Use the [implementation-plan template](https://hamedtaheri.com/playbook/v0.2.0/templates/implementation-plan.md) and [task brief](https://hamedtaheri.com/playbook/v0.2.0/templates/task-brief.md). Planning skills belong where design judgment is needed. The lean worker receives the resulting contract, without repeating every planning step or inheriting unrelated tools. Put binding project constraints into the worker's explicit inputs before reducing discovery.

## 2. Parallel sessions and messaging

I assign each interactive lane a coherent deliverable, known owner, worktree, starting revision, test environment and stop conditions. A dependency graph decides what can start together. Shared tables, migrations, mutable test databases, ports and Git metadata can constrain concurrency even when the prompts look independent.

Messages are short coordination events: a dependency is ready, a contract changed, a check failed, or a decision is required. They include the task key, revision, evidence and requested action. The receiving session checks the current task and relevant source before acting. The message does not silently reassign work, approve a release or overwrite a newer decision.

An example using the [message template](https://hamedtaheri.com/playbook/v0.2.0/templates/session-message.md):

```text
Task: notification-sdk; revision: accepted-contract-revision
Update: the API lane now returns retryAfterSeconds on rate-limit responses.
Evidence: contract document + reviewed PR revision.
Requested action: update the SDK's accepted response mapping and its tests.
Owner/scope: keep your existing lane; flag any acceptance change for review.
```

This is a pattern, not a transport installed by the kit. Use the messaging tool available in your environment and the user's authorization. Record the accepted interface change in the spec/decision; retain completion evidence in the task. A handoff captures where work stopped. Neither requires dumping a raw transcript into every session.

The newer lean workers do not autonomously message all other sessions or write team memory. Their reports and handoffs return to the coordinating layer. `run-queue` updates selected task records; `run-plan` maintains local execution state and a decisions inbox. Session messaging and scripted orchestration solve related problems through different mechanisms.

## 3. The headless pipeline

```text
Human + planning session → accepted spec / implementation plan
review-spec → current-content gate → prep-brief → run-task
  → deterministic/environment verification → review-pr
  → bounded fix or human escalation → exact-head landing checks
  → separately authorized integration and release
```

![Scripted task flow with worker stations, verification, review and decisions](https://hamedtaheri.com/playbook/v0.2.0/figures/scripted-pipeline-modern.png)

*Conceptual illustration. The routing script itself does not need a model session; its workers and reviewers do.*

`pipeline` handles one task. `run-queue` handles tasks selected on a board. `run-plan` handles a dependency graph of parts. Each uses the smaller commands below. Reports and machine outcomes replace repeated “what should we do next?” exchanges for decisions already encoded in the workflow.

The main outputs sit under `.claude/ai-pilot/`: preparation, worker, review and specification ledgers; per-task pipeline results; queue summaries; plan state and escalations; landing reports; a decisions inbox. Keep these private. Public evidence should use redacted aggregates and explicit scope.

## 4. Provider and subscription routing

| Route | Headless harness | Authentication and accounting | Control in this implementation |
|---|---|---|---|
| `anthropic:MODEL` or unprefixed model | `claude -p` | Existing Claude Code login can use subscription access; an API-key configuration can bill separately. CLI dollars are client-side estimates | Worker stage budget plus attempt/recovery reserve; pipeline checks between stages |
| `codex:MODEL` or `codex:` | `codex exec` | ChatGPT login for subscription access, or API auth when configured. Recorded value is API-equivalent or unknown, not a subscription invoice | Read/write sandbox, timeouts, stage-boundary budget checks; no live Claude-style dollar cap |
| `deepseek:MODEL` | `claude -p` against the configured Anthropic-compatible endpoint | `DEEPSEEK_API_KEY`; API billing. Uses configured model prices when present | CLI cap uses an assumed price basis; known models above that basis are refused |
| `openrouter:MODEL` | Same Claude CLI harness, different endpoint | `OPENROUTER_API_KEY`; API billing. Catalog prices are cached for up to 24 hours | Same price-basis check; compatibility must be probed for the selected model/version |

The prefix selects the adapter. It is not a guarantee that any model works with the harness. Pin a tested model ID and record the CLI version, authentication mode, endpoint, rate source/date and usage completeness. Do not treat subscription access as unlimited capacity or an API-equivalent dollar figure as an actual saving.

The Codex adapter can require subscription login with `AI_PILOT_CODEX_SUBSCRIPTION_ONLY=1`, forcing the OpenAI provider and clearing selected API credentials and endpoint overrides from the child environment. `AI_PILOT_CODEX_USAGE_LEDGER` records observed token totals. `AI_PILOT_CODEX_COORDINATOR_PUBLISH=1` keeps the write worker off network publication: it writes `.ai-pilot-ready.md`; a separately authorized coordinator verifies and publishes. The pipeline does not automatically perform that publication, and a run without a PR may stop for preparation or human handling.

Codex read stages default to 10 minutes and write stages to 30. The product supports non-interactive resume, but **this ephemeral adapter does not implement recovery resume**. Claude tool allowlists and the Read hook do not carry over to Codex. Its native sandbox and explicit worker instructions govern those boundaries.

For the API routes, the key is available in the child process environment; isolation remains necessary. Model-driven PR test execution is disabled for these routes and for Codex. A separately configured verification stage supplies test evidence. A read-only model review alone does not prove runtime behavior.

Product references, checked October 14: [Claude non-interactive CLI](https://code.claude.com/docs/en/headless), [Claude cost accounting](https://code.claude.com/docs/en/costs), [Codex non-interactive execution](https://developers.openai.com/codex/noninteractive), [Codex authentication](https://developers.openai.com/codex/auth). Claude's newer `--bare` mode does not use subscription OAuth; it is not interchangeable with this runner's explicit lean settings. The script behaviors below come from the pinned source snapshot, rather than product-wide guarantees.

## 5. Command reference: prepare and execute

Paths below are relative to the implementation repository and start with `scripts/ai-pilot/`. **These runner scripts aren't publicly available yet and aren't in the starter kit. If you'd like to see them, [just ask](https://calendar.app.google/UVoMSwMPxo1ypDkH9).** The examples document my system; adapt or install an independently reviewed implementation before running them.

| Script | Inputs and main options | What it does and leaves behind |
|---|---|---|
| `review-spec.mjs` | Repeated `--spec FILE`, required `--base BRANCH`; `--model`, `--budget`, `--dry-run`, `--force` | Checks source facts and asks a fresh reviewer for READY, FIX SPEC, SPLIT or NEEDS HUMAN. Caches by spec basename/content hash; writes `spec-reviews/*.md` and `spec-reviews.jsonl` on review |
| `spec-gate.mjs` | `accept --spec FILE --by IDENTITY`; optional `--pilot-dir` | Records ACCEPTED for a reviewed spec's coordinator patch. Requires the specific patch marker and a prior matching prefix review. Any later content edit invalidates the gate; it does not substitute for human acceptance of product decisions |
| `prep-brief.mjs` | `--task KEY --spec FILE --base BRANCH`; `--notes`, `--out`, `--model`, `--budget`, `--keep` | Fetches the base, uses a detached worktree and lean read-only model to write a six-field brief or NOT READY. Writes `prep.jsonl`. **No standalone `--dry-run` option** in this snapshot |
| `run-task.mjs` | `--task KEY --brief FILE --base BRANCH`; `--model`, `--soft`, `--hard`, `--recovery`, `--reserve`, `--from`, `--new-attempt`, `--dry-run`, `--full`, `--mcp-config` | Validates budget and repeat-attempt policy, creates an isolated `pilot/KEY` worktree, starts one worker, records attempts in `ledger.jsonl`. Claude can run one handoff-only recovery; Codex cannot. Authorized normal worker publication opens a draft PR on its task branch |
| `pipeline.mjs` | `--task KEY --base BRANCH`, either `--spec` or `--brief`; `--max-usd`, `--model`, `--review-model`, `--max-fix-rounds`, `--verify-cmd`, `--dry-run` | Chains prep, worker, verification and review. Reserves the remaining estimated budget before starting each stage. Writes `pipelines/KEY.json` and `pipelines.jsonl`; returns a machine outcome. Does not merge the task PR into its base |
| `run-queue.mjs` | `--queue FILE`; `--parallel`, `--stagger`, `--claim-wait`, `--owner`, `--dry-run` | Re-reads selected backlog tasks, checks exact spec content and environment, claims by write/wait/re-read, launches pipelines and writes outcomes while the lease is still its own. Leaves `queue/RUN/summary.{md,json}` and child logs. `--no-spec-gate` exists but weakens the readiness check |
| `run-plan.mjs` | `--plan FILE`; `--parallel` 1–4, `--cap`, repeated `--coordinator`, `--resume`, `--dry-run`, `--apply`, `--auto-fix` | Orders parts by dependencies, checks spec/spend gates, runs pipeline, deep review and landing. Saves `plans/NAME/state.json`, `ESCALATIONS.md`, `run.log`, `notify.log` and decisions. Resume requires the same plan hash and fix mode |

Queue claims are **not atomic** in this implementation, although the memory backend supports `expectedVersion` and the queue could use it: re-reading after a timed wait reduces some conflicts but cannot prove exclusive execution across coordinators. The portable kit's local conditional-update demonstration is a different implementation. Qualify your backend's concurrency contract before adopting the queue across multiple coordinators.

## 6. Review, repair and landing

| Script | Inputs and main options | Behavior and output |
|---|---|---|
| `review-pr.mjs` | `--pr N`; `--acceptance FILE`, `--model`, `--budget`, `--max-diff-lines`, `--deep`, `--sha`, `--verify-file`, `--dry-run`, `--force`, `--keep` | Collects PR metadata, diff, CI and threads before a fresh model review. Pins the head; emits MERGE, MERGE AFTER or DO NOT MERGE and conditions. Writes `reviews/N-SHA.md` and `reviews.jsonl`. Ordinary reviews can omit oversized diff chunks; deep review inspects wider feature/invariant scope |
| `ext-review.mjs` | Imported reviewer adapter; pipeline `--ext-review codex-github`, `--ext-rounds`, `--ext-flow v2` | Requests/polls GitHub Codex review for the exact SHA, parses severity and deduplicates findings. The module itself has no local model call; external review consumes its service allowance and fix/review stages consume theirs. Requesting review can mark a draft ready and post a review-request comment |
| `make-fix-brief.mjs` | `--pr N --report FILE --head pilot/KEY`; `--task-key`, `--verify`, `--out-dir` | Converts BLOCKING and fix conditions into `inbox/fixspecs/KEY-fixN.md`. Keeps report text fenced as untrusted data. Writes a fix specification; does not run or approve it |
| `land-pr.mjs` | `--pr N --into BRANCH`; `--apply`, `--try-tsc`, `--keep-worktree`; optional task/status preconditions | Checks PR, exact-head deep review, merge conflicts, typecheck policy, tests, real Postgres, structured conditions and drift. Appends `landings.jsonl`; prints BLOCKED, READY or LANDED. Dry-run landing still performs checks and local worktree/test operations |
| `merge-train.mjs` | `--into BRANCH`, `--prs 1,2` or `--from-ledger`; `--max-prs`, `--max-minutes`, `--apply`, `--dry-run` | Sorts/deduplicates PRs and serially calls `land-pr`. Holds high-risk paths. Leaves `merge-train.jsonl` and `.log`; the train does not bypass the landing gate |

The v2 review flow gathers a deep review and external review, merges findings, performs one full fix and confirms on the new head. A second fix is limited to new findings in a different area; recurring issues in the same area escalate to `needs_design`. Unresolved `NOT_FIXED` items remain visible. This is a bounded repair policy, not a claim that two reviews discover every bug.

`MERGE AFTER` includes a structured `CONDITIONS:` JSON array. Only allowlisted test, drift and named Postgres-suite commands can be executed by the landing gate. Human conditions block; fix conditions require repair. Review prose is not arbitrary shell authority.

The pinned landing implementation allows `--apply` only into its approved integration branch `10th-oct`; adoption needs a deliberately chosen equivalent. It blocks protected targets and does not deploy. TypeScript changes under `src/` currently stop for human handling unless `--try-tsc` opts into the scoped check; package/tsconfig changes also block. Scoped checking has known coverage and resource limits. A READY result means the implemented checks passed or were explicitly skipped, not that a complete build or production smoke test ran. The source GUARDRAILS and landing implementation contain different build instructions; resolve that locally before using the gate as acceptance authority.

`pipeline --merge-fix`, its external fix flow, and `run-plan --auto-fix` can merge a reviewed fix PR into its task's `pilot/*` branch. **Omitting `--apply` does not disable those fix-branch merges.** Task integration remains a separate landing step. `run-plan` dependants wait for prerequisites to be landed, so without application they can stay pending even when earlier parts are ready.

## 7. Accounting and the human inbox

| Script | Usage | Result |
|---|---|---|
| `spend.mjs` | `--since DATE`, `--session ID`, repeated `--coordinator ID`, `--projects-dir DIR`, `--cap USD`, `--json` | Totals recorded stage ledgers and selected Claude helper/coordinator usage. A cap breach exits 3; a missing selected coordinator transcript also blocks a cap check. Without coordinator IDs, those sessions are not counted. This is scoped accounting, not a complete bill |
| `codex-spend.mjs` | Repeated `--ledger FILE` / `--rollout FILE`; `--pricing-model`, `--speed` | Reads selected local usage metadata, deduplicates attempts and reports API-equivalent estimates. Missing rates or incomplete usage can leave totals unknown; `actualUsd` stays null. It makes no model call and prints no message text |
| `decisions.mjs` | `add --task KEY --question TEXT`, optional options/recommendation/link; `list --json`; `answer ID TEXT`; `--file` | Maintains `inbox/DECISIONS-PENDING.md` with Open and Answered sections. Uses temporary write + rename. An answer records the human's decision; it does not automatically grant a run new permissions. Single-file replacement is not a distributed writer lock |
| `probe-providers.mjs` | `--provider openrouter`, `deepseek` or `all`; optional `--model` | Sends tiny real model requests for configured providers, nominal $0.05 stage caps. **Paid maintenance probe**, especially after CLI upgrades; not an offline compatibility test |

Measure cost per accepted deliverable across preparation, execution, coordinator, reviews, repairs and verification infrastructure. Keep failed attempts. A missing valuation should remain unknown rather than becoming zero. Reprice from underlying token counts when rates change; the scripts' bundled price constants are not an evergreen price feed.

## 8. Every supporting script and configuration

These modules support the commands above; they are not separate worker roles to launch.

| File | Responsibility |
|---|---|
| `entry-args.mjs` | Side-effect-free parsers for run-task/prep; require an explicit permitted base and reject unknown flags |
| `budget.mjs` | Attempt/overshoot/recovery arithmetic, result classification, repeat-attempt rules, lean settings, context ranges and worker/recovery prompts/tool lists |
| `stage.mjs` | Shared process runner and provider dispatch; streams Claude events, deduplicates usage counters, measures context/tools, creates/removes detached worktrees and links build artifacts |
| `codex-stage.mjs` | Native Codex arguments, prompts, sandbox/auth environment, timeouts, JSON event parsing, readiness artifacts and optional usage ledger; no recovery resume |
| `providers.mjs` | Prefix parsing, provider endpoints/key mapping, price lookup, token/cost conversion and CLI price-basis checks; OpenRouter catalog caching is an I/O operation |
| `codex-cost.mjs` | Codex pricing and usage validation, deduplication, selected rollout metadata and completeness-aware summaries; separates equivalent value from actual charges |
| `readonly.mjs` | Prep/review prompts, read-only tool lists, credential scrubbing, sensitive-path selection, spec facts, diff packing and verdict helpers |
| `pipeline-lib.mjs` | Routing/outcomes, stage budgets, environment profile checks/verification facts, fix briefs, deep/external findings, spec sensitivity and human-gate rules |
| `run-queue-lib.mjs` | Queue validation, task-key normalization, claim fields, human-gate parsing, outcome-to-status fields and summary formatting |
| `land-pr-lib.mjs` | Landing arguments, exact-head review selection, test mapping/base-failure comparison, typecheck parsing, Postgres/drift selection and report formatting |
| `merge-train-lib.mjs` | Train arguments, risk tiers, PR ordering, current-head deep-review selection and agreement between exit/summary/landing record |
| `review-conditions.mjs` | Strict CONDITIONS parsing and command allowlist; malformed/unmatched/fix/human conditions cannot be silently accepted |
| `fetch-lock.mjs` | Exclusive local lock file around shared Git fetch, timeout and stale-lock policy. It protects fetch operations, not all Git operations or task ownership |
| `team-memory.mjs` | Config lookup and task-record count/update/note requests. It implements the queue's REST calls, not atomic compare-and-swap claims or session-to-session messaging |
| `read-guard.mjs` | Claude Read hook: requires bounded reads for large files, up to 150 lines. Applies to that tool, not every way to read a file; parse/read errors can allow the operation |
| `hooks/guard-review-subagents.mjs` | Claude Agent/Task hook: rejects recognized review calls without an eligible small-model choice and explicit dollar budget. Has exemptions and fails open on malformed input; it is not a general spending cap |

Also present: `README.md` (operations), `GUARDRAILS.md` (project rules and incidents), `prices.example.json` (rate configuration), `env-profiles.example.json` (environment check/setup/ready/verify patterns), `land-pr.pg-suites.json` (test-suite/path mappings), and `examples/plan.example.json` with `examples/specs/part-a.md` and `part-b.md`. Environment profile commands can create resources or call live services; inspect their actual commands and payer before use. Two landing runs can collide on a suite's hard-coded container/port, so serialize those checks.

The [catalog](https://hamedtaheri.com/playbook/v0.2.0/reference/script-catalog.json) lists every one of the 32 JavaScript files in this snapshot, their categories, roles and source hashes. Test files are outside this operational catalog; their existence is not evidence that this publication ran a live pipeline.

## 9. A first adoption sequence

1. Write one accepted spec and implementation plan. Prepare a worker card containing the project's actual restrictions and commands. Map ownership, messages and handoffs to your environment.
2. Pick one compatible provider/auth mode; pin CLI/model and pricing metadata. Isolate worktree, test data and credentials. Set an authorized whole-run budget including the coordinator.
3. Inspect a complete dry-run plan. Run one bounded task after execution is authorized, read its verification and exact-head review, then inspect landing checks. Increase concurrency after verifying resource isolation and acceptance.
4. Record accepted output, quality/repair outcomes, human effort, API-equivalent usage and actual charges independently. Compare like-for-like work before claiming an improvement.

Examples for an installation of the implementation, with existing example files and an explicitly chosen non-protected base:

```sh
node scripts/ai-pilot/pipeline.mjs --task demo-a --base integration-demo --spec specs/demo-a.md --max-usd 3 --dry-run
node scripts/ai-pilot/run-task.mjs --task demo-a --base integration-demo --brief briefs/demo-a.md --hard 3 --dry-run
node scripts/ai-pilot/run-plan.mjs --plan plans/demo.json --parallel 2 --cap 5 --dry-run
node scripts/ai-pilot/decisions.mjs list --json
```

These examples omit paid execution and application flags. A **full dry run** is not the same as a **dry-run landing**. Without `--dry-run`, run-plan runs paid stages even without `--apply`. Queue dry runs still check the remote board, execute declared environment readiness checks and write local summary files. Spec-review dry runs create their local reports directory. PR-review and landing dry runs can fetch/create probes or execute checks. Inspect the pinned implementation before treating a flag as “no side effects.”

## 10. What changed after this snapshot

The scripts above are the October 14 snapshot. These practices were added in the second half of October. They are described here, not shipped.

### Rules that came from incidents

Each started as a mistake that cost money or shipped a bug. They are written once and shared by every agent tool we use, Claude Code and Codex alike, in a repository file and a team-memory playbook kept in sync.

- **One cap covers everything.** A session's dollar cap includes preparation, workers, reviews, fix rounds, subagents and the coordinator. A script totals all of it before every wave, and no wave starts that the remainder can't fund.
- **Reviews never run as in-session subagents.** Each review is one capped headless process. The [$17.30 spec review](https://hamedtaheri.com/playbook/v0.2.0/playbook.md#4-manage-usage-and-cost) is why; a hook enforces it.
- **Size the task to the worker.** A worker has a soft budget of about $2. Tasks with more than six to eight new files came back with no code, so work is split into parts of about 500 changed lines or fewer, each stacked on the previous one's branch.
- **Paste shared contracts.** When two tasks touch the same table, interface or wire format, each spec carries the exact definition. "Created by task X" is not enough (the [import failure](https://hamedtaheri.com/playbook/v0.2.0/playbook.md#a-task-walkthrough-from-my-own-experience) is the example).
- **A thin review is not verification.** A review that made one or two tool calls on a change with new SQL, auth, billing or two-store writes counts as unverified. Before merging, someone runs the build, the touched tests in a clean environment, and each new query once against a real database with the real schema.
- **Check red against the base.** A failing test counts against a change only if it passes on the base. Known failures on the base are listed, so nobody "fixes" them inside an unrelated PR.
- **Route, don't work.** A coordinator fix that takes more than about five calls costs more than a worker run. Write a brief instead.
- **Drive, don't patch.** A session driving the queue runs commands and reads short output. It never patches the runner mid-run (it writes a note and ends), never routes around a refusal, never merges directly (landing goes through the landing script) and never files board tasks; a proposed split stays a proposal.

### Questions and decisions

By late October my answers lived in a flat rulings file that sessions appended to. It grew to about 150 entries in two days, with numbers reused by different sessions, and nothing could find an old answer except reading the whole file. Now the open question and the answer are separate records:

| Situation | Record |
|---|---|
| A question only a person can answer, not answered yet | An **inquiry** directed to that person; the waiting task is blocked by it |
| An offer the person can accept or reject | An inquiry of kind proposal; it becomes a task only after it is accepted |
| An answer a later session would otherwise ask again, or undo | A **decision**, linked to the inquiry it resolves and the tasks it applies to |
| Approval of one action, "this time only" | A one-line note on the task, not a decision |
| A tactical choice nobody will ask about again | Nothing; the PR description is enough |
| A later answer that disagrees with an accepted decision | A new decision that supersedes it; the old one is never edited |

Sessions find decisions by search, so a decision states the general rule, not the conversation. "Public API fixes may change responses only for invalid input" can be found again; "Yes (Recommended)" cannot. Each decision carries a reuse level: a **standing rule** applies every time and needs the person to have said "always" or "from now on", and gets a review date; a **precedent** is a strong default for similar cases; a **one-off** covers this case only.

At pickup, a script lists the open questions on the task, the accepted decisions that apply and the closest precedents. Accepted decisions are final. Before opening a new question, the agent searches for a precedent and asks "same answer as this one?" instead of starting fresh. Headless workers never ask; they leave the inquiry open and the task waits. Moving the old rulings over taught me not to flood memory: one decision per ruling would have buried the rules that matter under one-time landing approvals, so only standing rules and product calls became decisions.

Work that needs a human action other than a PR review moves to a waiting state with three fields: the kind of need (decision, approval, verify, wait or proposal), a self-contained ask (the exact question, or the exact command with preflight, verification and rollback) and what resumes once it is answered. Runners claim only backlog work, so a parked task is never picked up by a worker; a human session works through them. A prod-touching brief must declare its human gate, or explicitly declare none, or the pipeline stops before the worker.

### Security audits and UI tests

In October I started a security audit and hardening of our backend, work I never had room for before. Pinned third-party security review skills run as capped, read-only headless sessions; nothing is installed in the product repository; a dry run shows the job list and the worst-case cost before I approve a ceiling. Findings come back as a triage table. Each confirmed row is checked against the code before it becomes a task, and rows that need cloud or configuration access become verification tasks for a person. A lighter pass runs on each release diff. The audit is not finished, and I don't publish its findings.

Agents also test the product through its interface: the local UI in a real browser, signed in to a test account whose credentials live outside every repository and are never printed. They touch only throwaway items they created. A bug in the change under test is fixed there with a failing test first; other bugs are reported; feature ideas become proposals for me.

### Claims

The plan runner gained the queue's opt-in claim with a read-back, and the backend now has a compare-and-swap test on the record version, but no claim uses that check yet. One coordinator runs at a time.

## Source and limits

This reference is based on the implementation snapshot at commit `48d788a0be3f0a94384ceb9c5939ad484db45e99`, selected from the local `origin/10th-oct` ref on October 14. The catalog preserves file hashes. Branches and scripts continue to change; these descriptions are versioned observations. No paid worker, provider probe, external review, task-board write, merge or deployment was performed to produce this reference. Existing output/cost figures belong to their separately scoped evidence cohorts.

The generated illustrations are conceptual. The portable memory kit, workflow templates and AI guide are available now; publishing sanitized runner source and a hosted contribution channel remains separate future work.