VA Auto-Pilot

CLI-first autonomous multi-agent engineering loop — set a goal, the model finds the path.

┌──────────────────────────────────────────────────────┐
│                    Manager Agent                     │
│  Objective → Constraints → Anchors → Perspectives    │
├──────────┬──────────┬──────────┬─────────────────────┤
│ Worker A │ Worker B │ Worker C │  ...parallel tracks  │
│ (impl)   │ (impl)   │ (review) │                     │
├──────────┴──────────┴──────────┴─────────────────────┤
│          CLI Quality Gates (deterministic)            │
│  typecheck · lint · test · review · acceptance        │
├──────────────────────────────────────────────────────┤
│         Pitfall Guide (failure knowledge compounds)   │
└──────────────────────────────────────────────────────┘

Try it now

npx va-auto-pilot init ./auto-pilot-demo --demo
cd ./auto-pilot-demo
npm install
npm run check:demo

Use npx va-auto-pilot init . when adding the loop to an existing repository.

Before dispatching tasks, configure the CLI agent you want to use. The default template is a vendor-neutral placeholder that exits with a clear error; set --agent-template or worker overrides so tasks can actually run.

The Design Bet

Most agent frameworks are built to reduce autonomy: they break tasks into small steps, prescribe exactly what the model should do, and keep the agent close to a human-maintained script.

VA Auto-Pilot makes the opposite bet.

This framework is built for capable coding agents, by design. It sets a goal, states constraints, and specifies acceptance criteria — then lets the agent find the path. There are no step-by-step instructions to follow. There is no role list to pick from. There is only: here is what must be true when you are done.

Long autonomous loops require strong planning, tool-use, and verification behavior. Smaller models can still participate in bounded tracks, but the full loop assumes frontier-grade execution quality.

That is the bet.

Why Frontier Models Need This

2026 frontier coding models bring extraordinary capabilities: autonomous multi-step reasoning, large context windows, and native tool calling. VA Auto-Pilot is designed to amplify these strengths and guard against remaining weaknesses.

Amplifying strengths

Objective-driven delegation — The manager gives goals, constraints, and acceptance criteria. No micromanagement. The model's reasoning ability is fully unleashed.
Parallel autonomous tracks — Frontier models handle complex parallel tool orchestration natively. The framework leans into this instead of serializing everything.
Long-context awareness — Sprint state, pitfall guides, and run journals are designed for models that can hold an entire project in context.

Guarding against weaknesses

Evidence gates prevent hallucination — CLI commands produce objective pass/fail signals that the model cannot argue around. "I think it's done" is not the same as "it is done." The gates catch obvious placeholder cheating and force observable evidence; they do not cryptographically prove that a test is meaningful.
Pitfall compounding prevents repeated mistakes — Unresolved failures are injected into relevant delegations. Rules synthesized from a resolved pitfall enter probation first, so one noisy resolution cannot silently become a permanent hard constraint.
Adversarial review breaks self-validation loops — A fresh-context reviewer sees only the diff, never the intent. This structurally prevents the most common autonomous loop failure: growing confidence in growing errors.

One sentence: Trust the model's reasoning power; use deterministic mechanisms to catch its blind spots.

Relationship to va-agent-protocol

VA Auto-Pilot is a sprint execution engine — it runs the autonomous engineering loop. va-agent-protocol is the universal task protocol — the standardized contract that wraps any CLI agent into a composable unit.

VA Auto-Pilot can run standalone. It can also operate as a reference engine / managed agent for va-agent-protocol. The protocol is the task contract; Auto-Pilot is one execution engine that satisfies it.

The event-driven Colony dispatcher in scripts/lib/colony-bridge.mjs optionally uses va-agent-protocol when it can be resolved — in priority order: the VA_AGENT_PROTOCOL_PATH env var, an installed va-agent-protocol npm package, or a local sibling checkout. Legacy/direct Colony surfaces retain that routing. Orchestrated await-workers currently forces the crash-safe spawn lifecycle so it can persist a real PID/token before GO, own the worker deadline, and recover without duplicate execution; Colony routing is not silently used on that surface.

Long-running orchestration publishes run.json and tracks.json through a durable, hash-checked transaction intent. After a run durably reaches done, recover --apply immediately and idempotently finishes claim release, checkpoint/review cleanup, and active-run removal without waiting for the lease TTL. halted, error, or live/recent worker state never takes this shortcut. Corrupt control files and ambiguous post-GO launches fail closed. Spawn containment covers the launcher/worker process groups and Windows process trees, but a hostile command can deliberately create a new POSIX session (setsid/detached daemon) and escape that best-effort boundary; worker commands must not daemonize.

MCP and A2A are complementary connection layers. VA Auto-Pilot sits above connection and messaging: it governs how long-running engineering work is decomposed, executed, reviewed, recovered, and accepted.

Harness + Loop Engineering

In current industry language, VA Auto-Pilot is a Loop Engineering system built on a Harness Engineering reliability layer.

Harness: constraints, skills, CLI tools, quality gates, adversarial review, pitfall memory, and deterministic feedback around the model.
Loop: sprint state, manager/worker dispatch, plan review, parallel tracks, recovery strategy, auto-commit, and next-cycle selection.

The loop keeps work moving. The harness prevents that motion from amplifying mistakes.

Core Intellectual Contributions

1. Perspectives emerge from constraints and anchors — never from role lists

Most multi-agent review frameworks prescribe perspectives: "security reviewer," "QA engineer," "architecture reviewer." The problem is that generic roles expose generic failure modes. Real failure modes are specific to the change.

VA Auto-Pilot uses a different model. Before any review, the manager identifies:

Constraints: what hard boundaries govern this change?
Anchors: what invariants must hold after this change?

Given those real constraints and anchors, the question becomes: which expert views would expose the most critical failure modes for this specific change? The perspectives emerge from the analysis — they are never assigned from a fixed list.

2. CLI-first is a correctness guarantee, not a style preference

Quality gates run via deterministic CLI commands. npm run check:all either passes or it does not. The model cannot declare success or argue its way through a failing gate.

This creates an objective synchronization point that separates "I think it's done" from "it is done." The gate itself can still be gamed by a sufficiently cooperative agent, so the framework also compounds pitfalls and runs adversarial review to raise the cost of cheating.

3. The manager delegates — it never implements

The manager agent's value is knowing what needs to be true, not how to make it true. Implementation is always delegated to sub-agents with full context: objective, constraints, hard limits, and completion gate.

4. Strategic decomposition before tactical execution

High-level goals are not decomposed by a human into tasks. The framework runs a parallel dimension scan: each sub-agent audits one axis of the problem independently, with no cross-contamination between dimensions.

5. Adversarial post-sprint review as a first-class gate

Every sprint ends with a fresh-context adversarial reviewer who has seen only the diff — not what was intended, not what was discussed. Their job is to find what the sprint team was blind to.

6. Failure knowledge compounds

The pitfall guide captures structured failure metadata — not just error strings, but hypotheses and missing context. Relevant unresolved pitfalls become hard constraints; rules learned from resolved pitfalls enter probation and require evidence-backed promotion. Active learned rules lose confidence over their configured half-life, effective feedback refreshes them, ineffective feedback retires them, and declared conflicts quarantine both otherwise-injectable relevant rules. The system compounds validated knowledge without turning every historical failure into permanent prompt debt.

7. The tool reports on itself

Pitfalls compound knowledge about the project's failures; meta-problems close the loop on the tool's failures. When a gate cannot express a project's stack, the orchestration state machine misbehaves, or protocol text misleads an agent, the agent records a structured meta-problem (category, severity, expected-vs-actual, command/exit-code/output evidence) into the project's local .va-auto-pilot/meta-problems.json — the protocol makes this recording mandatory before the cycle ends. Records never leave the project's disk. Running va-auto-pilot meta report --project <path> against an adopted project prints a stdout-only improvement report mapped to candidate areas of this repository, so real-world friction flows back into the backlog instead of evaporating at sprint end.

When to Use VA Auto-Pilot

Use it when:

You have access to frontier coding model capability
Your goal is complex enough that a human would need to decompose it before executing
You need guaranteed quality gates, not best-effort review
You want an execution loop that gets better as models improve

Do not use it when:

You cannot provide an agent with strong planning, tool-use, and verification behavior
You want to control every implementation step
Your task is small and bounded — a single well-written prompt is faster
You want minimal ceremony — this framework has protocol; the value is in the guarantees

Quick Start

# Install globally
npm i -g va-auto-pilot

# Or run directly with npx
npx va-auto-pilot init .

Bootstrap from GitHub (no npm dependency):

tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/Vadaski/va-auto-pilot "$tmp/va-auto-pilot"
node "$tmp/va-auto-pilot/bin/va-auto-pilot.mjs" init .
rm -rf "$tmp"

Try the default human workflow:

va-auto-pilot init ./auto-pilot-demo --demo
cd ./auto-pilot-demo
va-auto-pilot goal --text "Ship this project to a releasable state"
va-auto-pilot plan-from-goal --json
va-auto-pilot plan-from-goal --apply --json
va-auto-pilot cockpit

To actually dispatch tasks, configure an agent. Examples:

# Claude Code
va-auto-pilot run . --agent-template 'claude -p --output-format text "Implement task {taskId} in this project"'

# Codex CLI
va-auto-pilot run . --agent-template 'codex exec --full-auto -C . "Implement task {taskId}"'

# Kimi CLI
va-auto-pilot run . --agent-template 'kimi -w . --quiet -p "Implement task {taskId}"'

The cockpit is the daily control surface. It keeps human attention on whether the goal is still right, whether risk is acceptable, and whether the evidence is trustworthy. Sprint state, run journals, pitfalls, quality gates, and orchestration phases remain auditable internals for the agent. For the active run, cockpit validates task evidence manifests, artifact size/hash identity, event-log bindings, required gate outcomes, and declared review counts when present before presenting structured proof. Journal summaries are fallback context only when no bundle exists; gate trust is compressed into evidence-risk signals. Agents can maintain stale placeholder gates with va-auto-pilot gates audit and va-auto-pilot gates maintain --apply. The explicit goal path is goal -> plan-from-goal -> candidate backlog -> orchestrate plan -> review-plan; orchestrate plan also consumes unchecked objective intent automatically.

Orchestrated mode treats approval as a concrete integrity boundary. Plan review must end with an explicit PLAN REVIEW STATUS: PASS|FAIL marker (with structured findings before it when applicable); review waivers require a reason. Commit approval is bound to the selected tasks, approved file set (or isolated-worktree commits), evidence references, and the current integration HEAD. If any of that context changes, the run returns to approval instead of committing stale or unrelated work. Run and task IDs are restricted to path-safe identifiers, concurrent human-board/state updates are locked and atomic, and init/upgrade refuse symlinked scaffold destinations.

Default cockpit output starts with the decisions a human needs:

Goal Cockpit
Objective: Ship this project to a releasable state (human goal; needs-human-intent-processing)
Progress: NEEDS MANAGER ACTION - New human intent must be incorporated before worker dispatch. (dispatch blocked)
Risk: MEDIUM - NO_ACTIVE_RUN: No active orchestration run exists.
Evidence trust: TRUSTED - Required evidence gates are configured and no evidence risk signals are active.
Evidence: collecting
  Gate trust: configured
  Recent completions: none
  Recent failures: none
  Known unresolved problems: none
  Recovery: recoverable
  Approval freshness: current
  Commit readiness: not-ready - No completed worker results are waiting to commit.
Approval: No human approval needed now. Manager action required: New human intent must be incorporated before worker dispatch.
Manager next:
1. Generate candidate backlog: node scripts/auto-pilot.mjs plan-from-goal --json - Turn unchecked goal intent into an explicit candidate backlog.
2. Apply candidate backlog: node scripts/auto-pilot.mjs plan-from-goal --apply --json - Persist candidate backlog items into sprint state and mark intent handled.

Use va-auto-pilot cockpit --json when a manager agent or debugger needs the machine-readable audit surface and executable nextCommands.

Managed DocStore

VA Auto-Pilot can manage design, decision, and process documents through ManagedDocStore. When a repo tracks .docstore/*, use the DocStore CLI for writes instead of editing managed artifacts by hand.

Init / repair

node ./scripts/doc-store-cli.mjs init
node ./scripts/doc-store-cli.mjs init --force --mode=mixed --managed-roots=.docstore/designs,.docstore/decisions,.docstore/process

init is safe to rerun. On a healthy store it falls through to doctor.
Use --force when you intentionally change mode or managedRoots. Existing journal state, archive artifacts, and registered extensions are retained.
If doctor reports pending journal recovery or config/index drift, repair through init or the ManagedDocStore APIs instead of hand-editing .docstore/INDEX.json.

Adopt legacy docs

node ./scripts/doc-store-cli.mjs adopt docs/designs/doc-store-api-draft.md --kind=design --title="DocStore API Draft"

adopt moves an existing file into .docstore/ and prefers git mv so history stays attached when the repo supports it.
Outside a git worktree it falls back to a normal move, so local sandboxes and tests still work.

Install hook

node ./scripts/doc-store-cli.mjs install-hook
node ./scripts/doc-store-cli.mjs uninstall-hook

install-hook is idempotent.
uninstall-hook is safe to rerun; if a preserved hook exists it is restored, otherwise the command exits cleanly.
If .git/hooks/pre-commit already exists, DocStore preserves it as pre-commit.doc-store-prev and chains to it before running enforce-staged.

Modes

legacy — permissive rollout mode; managed-path enforcement is off.
mixed — legacy paths stay editable, but configured .docstore/* roots must be written through DocStore.
managed — configured managed roots are strict; manual adds, edits, or deletes are rejected unless the staged INDEX.json change matches the artifact change.
Change mode or managedRoots through doc-store-cli init --force ... so config and index stay in sync.

This repository currently uses mixed mode with .docstore/designs, .docstore/decisions, and .docstore/process as managed roots.

Goal-First Delegation

The correct way to use this framework is to give it a goal, not a plan.

$va-auto-pilot

Objective:
Ship onboarding v2 with measurable activation lift.

Constraints:
- Keep architecture boundaries unchanged.
- No security regressions.
- Keep critical path latency under 300ms.

Acceptance:
- typecheck, lint, tests pass
- configured review gate reports no blocking findings
- acceptance flow MUST 100%, SHOULD >= 80%

No list of files. No sequence of steps. No prescribed approach. You define the destination and the constraints. That is the entire contract.

Concurrency Model

One primary task per cycle, zero or more independent tracks in parallel
Synchronization at mandatory quality gates
State promotion blocked until required gates pass
Default path is model-native parallel tool orchestration
Replace review-agent with your configured reviewer command or wrapper (the example below is a placeholder)

Humans normally see this through the default cockpit output. Manager agents and debuggers can use cockpit --json; the planner and board commands below are internal/debug surfaces:

node scripts/sprint-board.mjs plan --json --max-parallel 3 > .va-auto-pilot/parallel-plan.json
npm run check:all && review-agent review --uncommitted && npm run validate:distribution

Distribution

# npm
npm i -g va-auto-pilot

# Generic CLI agent path
npx va-auto-pilot init .
npm install

# Then capture the goal and inspect the human-facing cockpit
node scripts/auto-pilot.mjs goal --text "Ship a reliable release"
node scripts/auto-pilot.mjs cockpit

# A capable CLI agent can then run the governed loop internally.
# The line below is a natural-language prompt you paste into your agent,
# not a shell command:
# $va-auto-pilot run one full loop in this repo with highest standards; keep humans on goal, risk, and evidence

# Agent integration example: Claude Code command
mkdir -p .claude/commands
curl -fsSL https://raw.githubusercontent.com/Vadaski/va-auto-pilot/main/skills/va-auto-pilot/claude-command.md \
  -o .claude/commands/va-auto-pilot.md

Roadmap

v0.3

Persistence — SQLite-backed sprint state and pitfall storage
Push-based async — replace polling with event-driven worker notifications
Web Dashboard — real-time sprint visualization

Future

REST / gRPC adapter for non-CLI integrations
Multi-language SDK (Python, Go)
Distributed orchestration across machines

See the next-gen Harness + Loop roadmap: docs/operations/next-gen-harness-loop-roadmap.md

Documentation

Protocol: docs/operations/va-auto-pilot-protocol.md
Public narrative spec: docs/operations/public-narrative-spec.md
Open-source readiness checklist: docs/operations/open-source-readiness-checklist.md
Fault-injection soak: docs/operations/fault-injection-soak.md
Next-gen roadmap: docs/operations/next-gen-harness-loop-roadmap.md
Start prompt: docs/operations/start-va-auto-pilot-prompt.md
Distribution: docs/operations/distribute-skill.md
Vision article: docs/human-on-the-loop.md
Ralph comparison: docs/comparisons/va-auto-pilot-vs-ralph.en.md

Website

website/ is a standalone static site with bilingual switch (EN / 中文), interactive state machine, animated execution demo, and SEO + OG metadata.

cd website && python3 -m http.server 4173

Verification

npm run check:all
npm run check:fault-injection
npm run validate:distribution

Credits

Created by Vadaski. Developed with assistance from frontier coding agents and dogfooded through VA Auto-Pilot's own engineering loop.

Acknowledgements: Vera project

License

MIT

Name		Name	Last commit message	Last commit date
.docstore		.docstore
.github/workflows		.github/workflows
.va-auto-pilot		.va-auto-pilot
bin		bin
docs		docs
e2e		e2e
schemas		schemas
scripts		scripts
skills		skills
templates		templates
test-flows		test-flows
tests		tests
website		website
.gitignore		.gitignore
.npmignore		.npmignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
README.zh.md		README.zh.md
SECURITY.md		SECURITY.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation