Plan before implementation
Independent architecture and task verifiers check layering, blast radius, reuse, REQ traceability, task order, and TDD closure before implementation.
Project + Specification
A shared workflow.
// bootstrap any git repository — new or existing
A shared workflow.
For AI coding agents.
Project-local specs, rules, and change history keep work resumable across agents and sessions.
story → plan → tasks → implement → knowledge update → review → verify → archive
Every station has instructions. prospec status names the next Skill and blocking gates when work changes hands.
// 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
9,477 total tests
16 skills
configurable Constitution
read-only MCP server
MIT
Agent-agnostic — works with Claude Code, Codex, Copilot, and Antigravity.
Three pieces: Skills guide decisions at each station, AI Knowledge preserves project context, and the CLI handles deterministic state changes, checks, and spec sync.
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-knowledge-updatesynced ✓
synced inputs → prospec-reviewgate ✓
tests recorded once → prospec-verifygate ✓
final verify → GRADE A ✓gate ✓
Tastemaker sign-off → commit + prospec-archive? (Y/n)Y✓ archived
AI Knowledge enriched · specs graduated · lessons harvested
Workflow capabilities
Project context that carries work forward.
Skills guide planning and review. The CLI records state and checks gates so the next agent can resume from project-local evidence.
Gated and resumable
prospec status routes the next station; deterministic commands refuse illegal transitions. Knowledge Update is a formal station.
Review with recorded evidence
Drift drafts bounded follow-ups, review loops carry circuit breakers, Verify records provenance, and Archive checks landing fidelity before trust-zone writes.
Updating an existing setup? See the upgrade guide.
§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
Load the knowledge index first, then the module summaries and source needed for the current task.
Challenge
Every AI session improvises a different workflow.
How Prospec answers
Structured Skills enforce one loop:
story → plan → tasks → implement → knowledge update → 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
A proposal's ## Design Source names where the UI comes from; tasks add visual regression tests and verify grades the implementation against that source.
§02 · How it works
One linear flow. Two loops that feed the next change.
A change moves through documented stations. Its specs, rules, and progress stay in the project, so the next agent can read the context and continue from the station prospec status reports.
The gold stages — Knowledge Update · Review · Verify · 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: a quick change skips Plan (story → tasks), whether selected autonomously in Draft-First, confirmed in interactive mode, or assigned by auto-draft. Proven backfill follows backfill → Promote → Knowledge Sync → final Verify → archive; code review is optional for proven backfill. Forward-change scales keep TDD, adversarial review, and Constitution audits. Knowledge Update runs before review, so the recorded review and test evidence already covers it.
1Knowledge on Demandindex first, details as needed
2Spec is Source of Truthdocumented in specs before code
3Start from Existing Codeno pre-existing specs required
4AI Agent Agnosticany AI CLI via Markdown adapters
5User Controls the Rulesdefine the Constitution used by checks and reviews
6Language Policyconfigure change-artifact and trust-zone languages separately
§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; CLI commands scaffold files, validate YAML, check structural drift, and sync specs without calling an LLM.
deterministic engine under the hood
§04 · Quickstart
From your project to your first AI-driven change.
Use an AI coding agent with the standalone CLI. Standalone binaries do not require Node.js.
Install the CLI
Use the standalone installer below or download a binary from GitHub Releases.
// Standalone binary — macOS & Linux
$ curl -fsSL https://raw.githubusercontent.com/benwu95/prospec/main/install.sh | bash// Standalone binary — Windows
> powershell -c "irm https://raw.githubusercontent.com/benwu95/prospec/main/install.ps1 | iex"Bootstrap your project
Inside a git repository (git init a new project), one command chains init + agent sync — pick your AI assistants and doc language. Use git add to stage source files before generating Knowledge, 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, final Tastemaker sign-off, and a plan sign-off when you opt in or the AI proposed the problem.
▸ 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.
Prospec grades each change across 5+1 dimensions. Grade S or A clears the workflow's commit handoff; B or below sends the agent back to fix the change. You remain in control of the actual commit.
A
Adversarial review, then verify
An independent reviewer looks for issues before final verification.
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. Complete Knowledge Update and validate the resulting inputs before the grade S/A commit handoff. Prospec prompts; it never auto-commits.
B
Constitution-guided audits
Project rules guide both automated checks and agent judgment.
Your project rules carry RFC-2119 severity — violations → FAIL, violations → WARN, → advisory. prospec-verify combines CLI evidence with agent judgment for rules that require interpretation.
C
Deterministic drift gate
Detect structural drift and missing validation evidence.
prospec check checks REQ references, links, import direction, and knowledge coverage, freshness, and validation records. Semantic consistency still requires review. Opt in to PR checks with prospec check --init-ci: --strict blocks on FAIL; WARN and skipped do not block.
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 → Knowledge Sync → final Verify → Archive — proven backfill skips review provenance; sync the modules
prospec knowledge update --changereports ∪metadata.related_modulesand stamp them before final validation. S/A confirms the prepared inputs; later input edits require renewed validation before 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
16 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.
16 Skills in registry order, presented as Planning 5, Execution 3, Knowledge bootstrap 1, Lifecycle & brownfield 5, and Finishers 2. Expand the full index.
Planning · 5
- prospec-exploreThink-partner for clarifying a requirement
- prospec-new-storyCreate a structured change story
- 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
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 persistent daemon is needed. Keep the
prospec CLI installed; Skills in your AI agent call it when needed to record state, check gates, and sync specs.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.Q3How does work resume across sessions or agents?
Specs, project rules, AI Knowledge, and change records stay in your repository. The next agent reads those artifacts and runs
prospec status to identify the current station, next Skill, and blocking gates. This resumes the recorded workflow; it does not restore the previous conversation.Q4What does it deliberately not do?
The MCP server is read-only (no tool can modify files; computing knowledge freshness lets git run the project's clean filters and config-defined hooks against temporary index copies), 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
Keep AI-assisted work traceable, verifiable, and resumable.
Install once, bootstrap any git repository, 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