Advance

Spec-driven engineering infrastructure for AI-assisted development.

Project Page · GitHub · Changelog · Setup

[!NOTE]
Advance targets OpenCode.

What Advance is

Advance is an OpenCode plugin that turns AI coding into a governed engineering system.

It combines:

• Spec law — durable capability requirements in .adv/specs/
• 7-gate delivery — proposal → discovery → design → planning → execution → acceptance → release
• Disk-backed persistence — transactional change/task/gate projections that survive process and context loss
• MCP tool surface — structured state mutation and inspection, not hidden chat memory
• Context engineering — one coherent orchestrator, focused sub-agent packets for deep work
• TDD evidence capture — red/green proof recorded on tasks
• Worktree isolation — branch-local specs, shared external change state, safe parallel implementation
• Task checkpoint commits — local rollback/audit commits before task completion
• Review + hardening loops — explicit correctness, security, architecture, test, and slop checks
• Wisdom accumulation — reusable project learnings promoted from completed work
• Runtime guardrails — bash safety, sub-agent nesting limits, cancellation policy, doom-loop detection
• External conformance hooks — optional black-box CI verification for spec drift

The result: AI agents can move fast without losing the engineering contract.

Why it exists

AI coding tools are powerful, but raw chat has weak guarantees:

Advance treats these as infrastructure problems, not prompt problems.

Why Advance is different

Many tools solve one slice of this problem. Some provide durable workflows. Some enforce test commands. Some add memory. Some add review bots. Some add task plans.

Advance is different because it balances all of those parts in one loop.

The efficiency comes from context engineering. The user works with one primary adv agent that carries the full change contract. Deeper work is shed to sequential, bounded sub-agents with their own focused instructions, tool access, and output schemas. The orchestrator keeps the state, gates, user checkpoints, and final decisions.

That is the harness engineering layer: not a bigger prompt, but a stronger operating harness around the agent.

Advance does not claim one mechanism is enough. It makes the mechanisms cooperate:

specs define truth
gates define lifecycle
disk projections preserve state
MCP tools expose state
tasks carry evidence
worktrees isolate change
checkpoints preserve rollback
review/harden catch drift
archive promotes learnings back into law

That combination is the product.

Inspirations and how Advance extends them

Advance is an original implementation, but it is not an isolated idea. It owes a lot to projects that made agentic engineering more structured, durable, and spec-driven.

The pattern is deliberate: take strong primitives from each predecessor, then vertically integrate them into one enforceable agent harness.

Unique technical stack

Advance is intentionally unusual. It is not just commands around an LLM.

This is why Advance is more than durable functions, more than a memory layer, more than a prompt pack, and more than a test wrapper.

Core workflow

Every phase produces artifacts that later phases can verify.

The 7 gates

No gate is a vibe check. Each gate has a contract.

What “done” means

Advance narrows “done” to evidence:

• Agreement exists and acceptance criteria are explicit.
• Design has been validated before implementation.
• Tasks are tracked and blocked dependencies are known.
• TDD evidence exists where applicable.
• Changed work is checkpointed before task completion.
• Review and hardening findings are fixed or classified out of scope.
• Specs are updated when behavior becomes law.
• Wisdom and reflection are recorded for the next change.

Key capabilities

Spec-driven changes

Specs are laws. Proposals and implementations can evolve, but archive validates against the current spec contract. When behavior changes permanently, archive applies spec deltas.

Durable task state

Disk projections track changes, task runs, gates, evidence, and recovery state. If an agent session dies or compacts, the next session resumes from durable files instead of reconstructing intent from chat. Each change projection is updated under a per-change advisory lock with read-latest-inside-lock, atomic temp-write/rename/fsync, in-lock readback, and revision/operation-identity verification.

TDD evidence, not test theater

For implementation tasks, Advance records red and green phases with command, output, test file, and exit code. If TDD is not applicable, the task must say why.

Checkpoint commits

Every /adv-apply task with file changes creates a local checkpoint through adv_task_checkpoint before it is marked done. Checkpoints include change ID, task ID, mode, and verification summary.

Worktree-aware execution

Mutating work runs in per-change worktrees. ADV state is external and shared across worktrees; specs remain git-tracked and branch-local. That gives isolation without losing coordination.

[!TIP]
Use worktrees for any agent run that will edit files. Advance materializes or resumes a change/<change-id> worktree, routes mutating tools there, and leaves the main checkout available for review, merge, and release. This pattern is inspired by opencode-worktree, which showed how worktrees make OpenCode agent sessions safer and easier to parallelize. Advance adds gate ownership, shared disk projections, task checkpoints, branch-local specs, and archive finalization.

Bounded autonomy

Advance lets agents work autonomously only inside approved boundaries. It stops for human checkpoints, design conflicts, doom loops, cancellation approval, archive sign-off, and scope drift that changes the agreement.

Accumulated wisdom

Patterns, successes, failures, conventions, and gotchas can be recorded per change and promoted to project-level wisdom. The system gets better as it ships.

External conformance

Optional CI-isolated conformance checks can verify specs from outside the agent’s editable context. Drift blocks archive unless a human explicitly unlocks or overrides.

Prioritizer protocol

When 2+ viable approaches depend on user values, Advance runs the prioritizer before asking. The protocol runs inline by default: it researches tradeoffs, drafts criteria questions, and surfaces a concise choice through the orchestrator. Delegated sub-agents use the same protocol for task-level decisions.

Command + skill architecture

Advance separates workflow ownership from reusable methodology.

• Commands own user entry points, gate transitions, state mutation, and artifacts.
• Skills own reusable guidance and checklists.
• Sub-agents handle bounded research, validation, and implementation work when context can be safely shed.
• The ADV orchestrator keeps sequencing, approvals, and state consistent.

The sub-agent system still exists: adv-engineer implements backend/state/API work, adv-designer is the apply-phase frontend/component specialist (write-only, never review/harden owner), adv-researcher validates architecture/docs/examples, adv-reviewer remediates review/harden findings (with a FRONTEND DESIGN REVIEW SKILL anchor for design-inclusive changes), and explore scans code. They are context-engineering tools, not owners of the lifecycle.

This also enables model comparison: run the same change on two models and compare outputs. Gates, specs, tools, and evidence stay identical; only the reasoning varies.

Command reference

Quick start

Install into OpenCode

curl -fsSL https://github.com/Sharper-Flow/Advance/releases/latest/download/install.sh | bash

That downloads the latest GitHub Release artifact, verifies SHA256SUMS.txt, and syncs the plugin, commands, overlays, bundled agents, and skills into the local OpenCode setup.

For pinned versions and source-checkout maintainer setup, see SETUP.md.

Then, inside an OpenCode project:

/adv-proposal add OAuth login without breaking existing session flows

Advance will move the change through discovery, agreement, design, planning, implementation, review, hardening, and archive.

For setup details and troubleshooting, see SETUP.md.

Develop the plugin

All buildable code lives in plugin/. Run commands from that directory.

cd plugin
pnpm install
pnpm test
pnpm run check
pnpm run build

Requires Node.js 24+ and pnpm 11.9.0. CI runs SDK parity, schema-drift, type, lint, format, unit tests, Bun CLI tests, and build checks on Node 24.x.

Runtime model

OpenCode runs on Bun, while the plugin's build and test tooling runs on Node. No external database, server, worker, CLI service, or runtime environment variables are required.

Mutable state is stored in per-project disk projections under ~/.local/share/opencode/plugins/advance/<projectId>/. A change lives at changes/<changeId>/change.json as {schemaVersion:2,state:{...}}. Different changes do not block one another; writes for the same change serialize through a 15-second advisory file lock with jittered backoff and stale-PID reclaim. Commits use atomic temp-write/rename/fsync, in-lock readback, and revision/operation-identity proofs, failing closed as operator_required on any problem. Epic state uses active-epics/<epicId>/active-projection.json with expected-version optimistic concurrency.

Repository map

plugin/              TypeScript OpenCode plugin implementation
  src/tools/         MCP tool implementations
  src/storage/       disk projections, transactional writes, locks, and state helpers
  src/validator/     spec validation, prep readiness, task classification
  src/events/        terminal UI/status helpers
  src/utils/         project IDs, debug logs, context snapshots, safe helpers
  schemas/           schema anchor stubs; Zod types are authoritative
.adv/specs/          git-tracked capability specs
.opencode/command/   slash-command workflow contracts
.opencode/agents/    bundled/repo-local ADV agents and overlays
skills/              reusable methodology skills
docs/                 gates, checklists, design notes, and specs
scripts/             sync, migration, maintenance, blind-test helpers

Documentation map

License

The package metadata declares the MIT license.