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 · Give the workflow guide to your AI · Machine-readable script catalog

The progression

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.

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 and task brief. 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:

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

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

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

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, Claude cost accounting, Codex non-interactive execution, Codex authentication. 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. The examples document my system; adapt or install an independently reviewed implementation before running them.

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

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

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.

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 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:

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.”

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.