prospec1.0.0
GitHub Install
Progressive Spec-Driven Development

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 → tasks → implement → review → verify → 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"
// bootstrap any project — new or existing
$ prospec quickstart
Quickstart in ~5 min View on GitHub
2,090 tests passing 17 skills 6 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.

§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 → tasks → implement → review → verify → 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 · Archive · Learn — are where Prospec goes beyond the category. The gold arrows are the loop: each change's results feed into the next, so the project gets smarter as you ship. Scroll the diagram sideways on a narrow screen.

Scale-aware: not every change earns the full ceremony. A user-confirmed quick change skips Plan entirely (story → tasks), with archive-time backstops so it never becomes a spec-drift hole. TDD, adversarial review, and Constitution audits run at every scale.

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

Slash-command workflows that run the whole SDD loop inside your AI agent. This is what you touch every day — describe a change in plain language and the Skills drive it.

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.

Prerequisites: Node.js ≥ 22.13 and an AI CLI (Claude Code recommended). You install Prospec once — after bootstrap, your agent works from the committed Markdown.

Install the CLI

Download the precompiled binary from Releases, or install via npm/pnpm.

// 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 --help

Bootstrap 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 # inside your AI agent

On 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 SDD loop and pauses only to ask questions and confirm each handoff.

▸ Use prospec to add a dark-mode toggle

Each stage ends with “Run /prospec-<next> now? (Y/n)” — your Y is the trigger, never a silent auto-run.

§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 — 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 — MUST → FAIL, SHOULD → WARN, MAY → 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.

  1. Extract — /prospec-backfill-spec reads code, tests, and history; intent it can't infer is marked [NEEDS CLARIFICATION], never fabricated.
  2. Review — you resolve every clarification. The human gate.
  3. Promote → Verify → Archive — the draft graduates through the same gates as any change; Archive is the sole writer of 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.

knowledge:// index · module · module-map · feature-map · playbook · health spec:// product · feature/<name> tools search_modules · get_dependency_direction
$ 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, grouped by phase: Planning 6, Execution 3, Lifecycle 2, Knowledge 4, Finishers 2. Expand the full index.

Planning · 6

  • /prospec-exploreThink-partner for clarifying a requirement
  • /prospec-new-storyCreate a structured change story
  • /prospec-designVisual + interaction specs (generate / extract)
  • /prospec-planImplementation plan + delta-spec
  • /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

Lifecycle · 2

  • /prospec-archiveArchive + spec sync + knowledge gate
  • /prospec-learnPromote recurring lessons → team rules

Knowledge & brownfield · 4

  • /prospec-knowledge-generateAnalyze project → module docs
  • /prospec-knowledge-updateIncremental update from delta-spec
  • /prospec-backfill-specReverse-extract a spec draft from code
  • /prospec-promote-backfillFormalize a reviewed backfill draft

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 slash-command Skills in your AI Agent. Under the hood, Skills call the prospec CLI as a background deterministic engine to handle byte-reproducible state mutations, zero-token drift checks, and spec sync without formatting errors.
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 benchmark harness (pnpm measure:tokens / prospec measure) that assembles real contexts and records actual provider usage. The project's rule is explicit: any token figure quoted must come from that harness — estimates are not data. Numbers are comparable only within the same provider and repo snapshot.
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 — that stays with the adversarial review. And no scale skips engineering discipline: TDD, review, and Constitution audits run everywhere.
Q5Greenfield or brownfield?
Both, with the same two bootstrap commands. 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 the backfill path can reverse-extract specs from behavior that was never documented.
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
View on GitHub Read the full README