Stronger planning
Independent architecture and task verifiers check layering, blast radius, reuse, REQ traceability, task order, and TDD closure before implementation.
Progressive Spec-Driven Development
Spec-driven development
// bootstrap any project — new or existing
Spec-driven development
that audits itself.
Spec-driven development means your AI agent builds from a written spec, not a throwaway prompt. Prospec runs that as one governed loop:
story → plan → design → tasks → implement → review → verify → knowledge update → archive
Plus adversarial review, S-to-D quality grades, and project knowledge that compounds on every change.
// install globally, once
$ curl -fsSL https://raw.githubusercontent.com/benwu95/prospec/main/install.sh | bash> powershell -c "irm https://raw.githubusercontent.com/benwu95/prospec/main/install.ps1 | iex"$ prospec quickstart
6,056 total · 6,052 passed · 4 skipped
17 skills
8 enforced principles
read-only MCP server
MIT
Agent-agnostic — works with Claude Code, Codex, Copilot, and Antigravity.
Three pieces: Skills drive judgment inside your agent, AI Knowledge is versioned project memory, and the CLI serves as a background deterministic execution engine.
you ▸ Ask prospec to rate-limit the public API
agent picks up the request and runs prospec-ff …
• scoping & acceptance questions → you answer in plain language
• writes story → plan → tasks; machine gates pass automatically:
implement → prospec-reviewgate ✓
review → prospec-verifygate ✓
verify → GRADE A ✓gate ✓
verify → prospec-knowledge-updatesynced ✓
Tastemaker sign-off → commit + prospec-archive? (Y/n)Y✓ archived
AI Knowledge enriched · specs graduated · lessons harvested
What's new in 2.0
From a guided sequence to a gated, resumable pipeline.
Prospec 2.0 keeps judgment in Skills and makes the CLI responsible for state, evidence, and spec landing.
Gated and resumable
prospec status routes the next station; deterministic commands refuse illegal transitions. Design is conditional and Knowledge Update is a formal station.
A self-correcting quality loop
Drift drafts bounded follow-ups, review loops carry circuit breakers, Verify records provenance, and Archive checks landing fidelity before trust-zone writes.
1.3 → 2.0 upgrade path
- Update the binary or pinned GitHub dependency to 2.0.
- Run
prospec upgrade, then invoke the bareprospec-upgradeSkill with your host's syntax and approve curated-document migrations individually. - Adopt host-aware invocation and the formal
verify → knowledge-update → archivepath; useprospec statusinstead of editing lifecycle metadata. - If the project still relies only on legacy
ai-knowledge/_index.md, preserve its authored content in{base_dir}/index.md; automatic relocation has retired. - Run
prospec check --strict, resolve newly enforced failures, and resume from the station reported by the CLI.
Compatibility: this major release tightens workflow contracts; it does not require rewriting product code or existing Markdown specs.
§01 · The problem
What it fixes, mapped to a command.
AI agents are fast and forgetful. Each row is a real failure mode of agent-driven development, answered by a specific skill or command.
Challenge
The agent doesn't know your codebase.
How Prospec answers
prospec knowledge init + prospec-knowledge-generate auto-scan your project and generate AI-readable module docs.
Challenge
Context windows are finite.
How Prospec answers
Progressive disclosure: load a summary first, details on demand — and the saving is verifiable with the in-repo prospec measure harness, not asserted.
Challenge
Every AI session improvises a different workflow.
How Prospec answers
Structured Skills enforce one loop:
story → plan → design → tasks → implement → review → verify → knowledge update → archive
Challenge
Vendor lock-in to one AI CLI.
How Prospec answers
Works across Claude Code, Codex, Copilot, and Antigravity; knowledge is stored as universal Markdown.
Challenge
Verify passes, but subtle bugs still ship.
How Prospec answers
prospec-review — an independent adversarial reviewer audits the whole diff between implement and verify.
Challenge
Knowledge goes stale the moment it's written.
How Prospec answers
The Archive Entry Gate refuses to close a change until AI Knowledge is updated to match the diff.
Challenge
Lessons don't survive across sessions.
How Prospec answers
prospec-learn promotes recurring fixes — only with human approval — into versioned team rules.
Challenge
There's no bridge from design to code.
How Prospec answers
prospec-design generates visual + interaction specs, with MCP tool integration for Figma / Penpot.
§02 · How it works
One linear flow. Two loops that feed the next change.
Most spec tools stop at spec → plan → tasks → implement. Prospec keeps going — through the stages that actually catch problems and grow your project's memory.
The gold stages — Review · Verify · Knowledge Update · Archive · Learn — turn evidence into project memory. The gold arrows are the loop: each change's results feed into the next. Scroll the diagram sideways on a narrow screen.
Scale-aware: Design is optional for UI work; a user-confirmed quick change skips Plan (story → tasks). Proven backfill follows backfill → Promote → verify → knowledge verify → archive; code review is optional for proven backfill. Forward-change scales keep TDD, adversarial review, and Constitution audits.
1Progressive Disclosure Firstindex first, details on demand
2Spec is Source of Truthdocumented in specs before code
3Zero Startup Cost for Brownfieldno upfront full-codebase docs
4AI Agent Agnosticany AI CLI via Markdown adapters
5User Controls the Rulesthe Constitution is yours; the tool enforces it
6Language Policydocs in your language; code stays English
§03 · The model
Three pieces — judgment in AI, deterministic execution in CLI.
You drive day-to-day work through Skills inside your agent. Under the hood, Skills delegate state transitions, scaffolding, and drift checks to the prospec CLI.
Surface
Skills
Host-aware workflows that run the whole SDD loop inside your AI agent. Describe a change in plain language and Skills can be discovered implicitly; explicit syntax belongs to the host.
runs the workflow
Memory
AI Knowledge
Structured, version-controlled project memory — modules, specs, conventions, lessons. The Skills read it and grow it with each change, so context is progressive rather than dumped.
read & grown every change
Execution
CLI prospec
A deterministic execution engine: prospec status routes lifecycle state, subshell probes handle scaffolding, YAML validation, zero-token drift checks, and mechanical spec sync without LLM formatting errors.
deterministic engine under the hood
§04 · Quickstart
Zero to your first AI-driven change in ~5 minutes.
Prerequisite: an AI coding agent. Standalone binaries do not require Node.js; Node.js ≥ 22.13 applies only to npx, devDependency, and source-development paths.
Install the CLI
Use the one-click standalone installer, download a release binary, or choose the Node.js path for npx/devDependency use.
// Option A1: Standalone Binary (Recommended / macOS & Linux)
$ curl -fsSL https://raw.githubusercontent.com/benwu95/prospec/main/install.sh | bash// Option A2: Standalone Binary (Recommended / Windows)
> powershell -c "irm https://raw.githubusercontent.com/benwu95/prospec/main/install.ps1 | iex"// Option B: Run on demand with npx (Node.js environments)
$ npx github:benwu95/prospec --helpBootstrap your project
One command chains init + agent sync — pick your AI assistants and doc language. Then finish onboarding inside your agent.
$ cd my-project && prospec quickstart▸ prospec-quickstart # use your host's invocation syntaxOn an existing codebase, this reads your modules into AI Knowledge before your first change.
Describe a change — the agent drives the loop
You don't memorize steps. Talk in plain language; the agent runs the gated SDD cascade and pauses for questions, failed gates or circuit breakers, and final Tastemaker sign-off.
▸ Ask prospec to add a dark-mode togglePassing machine gates advance prospec-ff automatically. Individual station Skills still end with a status-aware handoff when you choose to drive the flow manually.
Host-aware invocation
One canonical Skill name, four host conventions.
Every Skill has a bare identity such as prospec-implement. Natural-language triggers can discover it implicitly; when invoking explicitly, use the syntax required by your agent host.
| Host | Explicit syntax | Notes |
|---|---|---|
| Claude Code | /prospec-<name> | Slash command |
| Codex | $prospec-<name> | Skill mention |
| GitHub Copilot | /prospec-<name> | Slash command |
| Antigravity | prospec-<name> | Bare name or Skills browser |
§05 · Verification
Quality you can read off a grade.
Most spec tools stop at the plan. Prospec grades every change across 5+1 dimensions and won't let you commit below the line: grade S or A clears the gate; B or below blocks the commit until the fixes land.
A
Adversarial review, then verify
Critical issues get caught and fixed before they reach you.
prospec-review runs an independent, fresh-context reviewer over the entire diff. Verifier-confirmed, drop-in critical issues are auto-fixed; architectural or ambiguous ones escalate to you. The commit boundary sits after verify hits grade S/A and Knowledge Update runs — review and fixes land in one atomic commit. Prospec prompts; it never auto-commits.
B
Executable Constitution
Your project rules become pass/fail checks, not opinions.
Your project rules carry RFC-2119 severity — → FAIL, → WARN, → advisory. prospec-verify grades against them, so "compliant" is a computed verdict, not an opinion.
C
Deterministic drift gate
Spec, code, and knowledge can't silently drift apart.
prospec check machine-verifies spec ↔ code ↔ knowledge integrity with zero tokens — dangling REQ references, broken links, illegal import direction, stale knowledge. The scaffolded CI workflow enforces it on every PR; an unavailable source degrades to skipped, never a fake PASS.
D
Output Contract + Entry/Exit gates
Each stage proves it passed before the next one runs.
Every workflow Skill self-reports Met N/M | Overall: PASS|WARN|FAIL against objective criteria and checks preconditions before running. WARN/FAIL records persist to a cross-stage quality log, so an earlier stage's concern resurfaces at the next.
§06 · Meets your code where it is
Brownfield-first, and open to any agent.
Backfill existing code into specs
Mature codebases accumulate behavior no spec describes. Backfill is a first-class, two-skill path that reverse-extracts that behavior and graduates it into the spec trust zone (the human-verified spec files that only Archive may write) — without ever writing that trust zone by hand.
- Extract —
prospec-backfill-specreads code, tests, and history; intent it can't infer is marked[NEEDS CLARIFICATION], never fabricated. - Review — you resolve every clarification. The human gate.
- Promote → Verify → Knowledge Sync → Archive — proven backfill skips review provenance; sync only its declared modules, then Archive writes the trust zone.
A read-only MCP server
Expose your project's truth — architecture, specs, dependency direction, promoted playbook, knowledge freshness — to any MCP-capable agent, even one with no Prospec Skills installed.
8 resources knowledge://index · knowledge://module-map · knowledge://playbook · knowledge://health
resources knowledge://module/{name} · knowledge://feature-map · spec://product · spec://feature/{name}
3 tools search_modules · get_dependency_direction · get_spec_requirements
$ claude mcp add proj -- prospec mcp serve --cwd .
§07 · The command index
17 Skills, generated into your repo.
You don't have to run these one by one — describe a change in plain language and the agent drives the loop (or run each step yourself when you want). Day to day you'll mostly reach for explore, implement, review, verify, and archive. They deploy as Markdown adapters for any agent you use — and trigger by plain-language keywords, including your own language.
17 Skills in registry order, presented as Planning 6, Execution 3, Knowledge bootstrap 1, Lifecycle & brownfield 5, and Finishers 2. Expand the full index.
Planning · 6
- prospec-exploreThink-partner for clarifying a requirement
- prospec-new-storyCreate a structured change story
- prospec-planImplementation plan + delta-spec
- prospec-designVisual + interaction specs (generate / extract)
- prospec-tasksOrdered, checkable task list
- prospec-ffStory → plan → tasks in one pass
Execution · 3
- prospec-implementImplement tasks one by one
- prospec-reviewAdversarial review → fix loop
- prospec-verify5+1 audit + quality grade S/A/B/C/D
Knowledge bootstrap · 1
- prospec-knowledge-generateAnalyze project → module docs
Lifecycle & brownfield · 5
- prospec-archiveArchive + spec sync + knowledge gate
- prospec-knowledge-updateIncremental update from delta-spec
- prospec-backfill-specReverse-extract a spec draft from code
- prospec-promote-backfillFormalize a reviewed backfill draft
- prospec-learnPromote recurring lessons → team rules
Periodic finishers · 2
- prospec-quickstartOnboarding finisher (run once)
- prospec-upgradeVersion-upgrade finisher
§08 · Honest boundaries
Questions a careful engineer would ask.
Q1Do I need the CLI running while I work?
No manual CLI execution is needed. Day-to-day SDD work is driven through host-aware Skills in your AI agent. Under the hood, Skills call the
prospec CLI as a deterministic engine for reproducible state mutations, zero-token drift checks, and spec sync.Q2Does it lock me into one AI vendor?
No. Prospec is AI-agent-agnostic.
agent sync writes Claude Code (CLAUDE.md + .claude/skills/) and the agents.md standard for Antigravity / Codex / Copilot (AGENTS.md + .agents/skills/). Knowledge is universal Markdown — switching agents doesn't strand your project's memory.Q3Is the token-saving claim real or marketing?
It's measured, not asserted. Prospec ships a token measurement command (
prospec measure) that parses your local AI CLI session logs to record actual context usage and theoretical baseline savings. The project's rule is explicit: any token figure quoted must come from that harness — estimates are not data.Q4What does it deliberately not do?
The MCP server is read-only (no tool can modify files), serves one project per process, and is stdio-only — HTTP/SSE is intentionally excluded. The drift check is deterministic and never claims to judge semantic spec↔code consistency. Forward changes retain TDD, review, and Constitution audits; proven backfill instead uses a fidelity contract where code review is optional.
Q5Greenfield or brownfield?
Both, with the same bootstrap path. On a new repo, knowledge starts minimal and fills in as you ship. On an existing one,
prospec-quickstart reads your code into AI Knowledge up front, and backfill can reverse-extract specs from undocumented behavior.Q6What's the lineage and license?
MIT-licensed. This project is a fork of ci-yang/prospec, and draws inspiration from OpenSpec, Spec-Kit, cc-sdd, and BMAD. Its own contribution is Skills-driven SDD paired with a deterministic CLI engine, plus AI Knowledge as structured, versioned context engineering.
Get started
Every AI change — reviewed, graded, and archived before it ships.
Install once, bootstrap any project, then describe your first change in plain language.
// install globally, once
$ curl -fsSL https://raw.githubusercontent.com/benwu95/prospec/main/install.sh | bash> powershell -c "irm https://raw.githubusercontent.com/benwu95/prospec/main/install.ps1 | iex"$ cd my-project && prospec quickstart