Prospec

Prospec

[](LICENSE) [](https://www.typescriptlang.org/) [](tests/) [](https://nodejs.org/) [](https://pnpm.io/)

Progressive Spec-Driven Development (SDD) toolkit for AI coding agents

Slash-command Skills · structured AI Knowledge · MCP server — for Claude Code, Copilot, Codex

[繁體中文](./README.zh-TW.md) • [Quickstart](#quickstart) • [Why Prospec?](#why-prospec) • [How it works](#how-it-works)

This project is a fork of ci-yang/prospec

---

What is Prospec?

Prospec is a Skills-driven Spec-Driven Development (SDD) toolkit for AI coding agents. You drive day-to-day work through slash-command Skills inside your agent (Claude Code, Antigravity, Copilot, Codex); a thin CLI only bootstraps the project and regenerates Skills/Knowledge. The payoff: your agent follows a consistent story → plan → tasks → implement → review → verify → archive workflow, grounded in structured, version-controlled project knowledge.

Three pieces work together:

  You ⇄ AI agent
     │
     ├─ Skills .......... run the workflow:  story → plan → tasks →
     │                    implement → review → verify → archive
     │                        ▲
     │                        │ read & grow
     ├─ AI Knowledge .... structured project memory (modules, specs, lessons)
     │                        ▲
     │                        │ generated / regenerated by
     └─ CLI (prospec) ... bootstrap only:  init, agent sync, knowledge init / re-scan structure

• Skills run the workflow inside your agent — the day-to-day surface.
• AI Knowledge is progressive project memory the Skills read and grow with each change.
• CLI is a one-time/occasional tool: it scaffolds the project and regenerates Skills + Knowledge — it is not in the runtime loop.

Who is it for? Developers using an AI coding agent who want repeatable, reviewable workflows on a new project (greenfield) or an existing codebase (brownfield).

Why Prospec?

| Challenge | How Prospec helps | |-----------|-------------------| | AI doesn't know your codebase | prospec knowledge init + /prospec-knowledge-generate auto-scan and generate AI-readable docs | | Context window limits | Progressive disclosure: load a summary first, details on-demand (70%+ token saving vs full-dump) | | Inconsistent AI workflows | Structured Skills enforce story → plan → tasks → implement → review → verify → archive | | Vendor lock-in | Works with 4+ AI CLIs; knowledge stored as universal Markdown | | No design-to-code bridge | /prospec-design generates visual + interaction specs with MCP tool integration | | Knowledge becomes stale | The verify S/A commit prompt folds a Knowledge Update into the feature commit; the archive Entry Gate re-confirms it as a backstop | | Verify passes but subtle bugs ship | /prospec-review — independent adversarial review between implement and verify | | Lessons don't persist across sessions | /prospec-learn — recurring fixes promote (human-gated) into versioned team rules |

> Each row maps to a Skill or command below — see [AI Skills](#ai-skills) and [CLI Commands](#cli-commands).

---

Quickstart

From zero to your first AI-driven change in about five minutes.

Prerequisites

• Node.js >= 22.13.0
• An AI CLI (one or more): Claude Code (recommended), Codex CLI, GitHub Copilot CLI, or Antigravity CLI

1. Install

Prospec is a bootstrap/update CLI — once prospec quickstart has run (it chains init + agent sync), your agent works from the committed Skills and Knowledge (Markdown); the binary isn't needed again until you regenerate.

Option A: Standalone Binary (Recommended & No Node.js Required) For macOS and Linux, run the one-click installer script:

curl -fsSL https://raw.githubusercontent.com/benwu95/prospec/main/install.sh | bash

For Windows, run the one-click PowerShell installer script:

powershell -c "irm https://raw.githubusercontent.com/benwu95/prospec/main/install.ps1 | iex"

Alternatively, download the precompiled binary manually from the GitHub Releases page:

• Linux (x64): prospec-linux-x64.tar.gz
• macOS (Apple Silicon): prospec-macos-arm64.tar.gz
• macOS (Intel): prospec-macos-x64.tar.gz
• Windows (x64): prospec-windows-x64.zip

(For manual installation, extract the prospec or prospec.exe file from the archive and move it to your executable PATH).

Option B: Run on demand with npx (Node.js environments) Run without installing globally:

npx github:benwu95/prospec 

Option C: Pin as devDependency (Node.js projects) Install as a local project dependency:

npm install -D github:benwu95/prospec     # or: pnpm add -D github:benwu95/prospec

> [!WARNING] > We do NOT recommend installing globally via npm install -g as global compiling of unpublished forks can fail depending on your local Node/compile environment.

2. Bootstrap your project

One command does the deterministic setup — it chains init + agent sync, skipping any step already done:

cd my-project                 # a new or existing project

prospec quickstart            # → select AI assistants, choose doc language; creates .prospec.yaml + per-agent config + Skills

prospec quickstart runs agent sync, which writes Claude Code → CLAUDE.md + .claude/skills/; Antigravity / Codex / Copilot → AGENTS.md + .agents/skills/. Then finish onboarding inside your AI agent:

🤖 Run inside your AI Agent chat:
/prospec-quickstart           # localize skill triggers, re-sync config, generate AI Knowledge

This one-time finisher is re-runnable and self-terminating; on an existing codebase it reads your modules into AI Knowledge so the agent understands them before your first change.

3. Run your first change (inside your AI agent)

You don't have to remember the steps — describe the change in plain language and the agent drives the SDD loop, pausing only to ask you questions and to confirm each handoff:

🤖 Run inside your AI Agent chat:
You ▸ Use prospec to add a dark-mode toggle

The agent picks up the request and runs /prospec-ff:
  • asks a few scoping / acceptance questions — you answer in plain language
  • writes story → plan → tasks, then hands off at each stage:

  "Run /prospec-implement now? (Y/n)"             → Y
  implement → "Run /prospec-review now? (Y/n)"    → Y
  review    → "Run /prospec-verify now? (Y/n)"    → Y
  verify reaches grade A → prompts you to commit  → Y
         → "Run /prospec-archive now? (Y/n)"      → Y   ✓ archived

Every stage ends by telling you what's next and waiting for your Y — answer n to stop and the suggestion stays, so you can resume later without tracking where you left off. /prospec-verify is the commit boundary: at grade S/A it prompts you to commit (it never commits for you), then offers to archive.

Prefer to drive each step yourself? Run them explicitly:

🤖 Run inside your AI Agent chat:
/prospec-explore                   # (optional) clarify the requirement first
/prospec-new-story add-my-feature  # capture it as a structured story
/prospec-design                    # (optional) UI / interaction specs
/prospec-plan                      # design the implementation (a `quick`-scale change skips this)
/prospec-tasks                     # break the plan into an ordered task checklist
#   ↑ collapse story → plan → tasks in one pass with: /prospec-ff add-my-feature
/prospec-implement                 # implement task-by-task (no commit yet)
/prospec-review                    # adversarial review → fix loop
/prospec-verify                    # validate; prompts you to commit at grade S/A
/prospec-archive                   # archive + sync specs & knowledge
/prospec-learn                     # (periodic) promote recurring lessons → team rules

That's the full SDD loop. Because /prospec-quickstart already seeded AI Knowledge, the agent starts from an understanding of your modules. The full greenfield & brownfield walkthroughs below break down every step prospec quickstart automates.

Greenfield vs. brownfield bootstrap — what the two commands expand to

Greenfield (new projects)

prospec quickstart → /prospec-quickstart is the whole bootstrap:

mkdir my-project && cd my-project
prospec quickstart --name my-project   # init + agent sync (interactive assistant + language selection)
# then, inside your AI agent:
/prospec-quickstart                     # localize triggers · re-sync · generate AI Knowledge

Those two commands expand to:

# `prospec quickstart` runs:
prospec init --name my-project   # → select AI assistants (interactive checkbox)
                                 # → choose the doc language (default: English, or
                                 #   --language "Traditional Chinese (Taiwan)"); a [MUST]
                                 #   Language Policy rule is seeded into CONSTITUTION.md —
                                 #   code and git commit messages stay in English
                                 # → creates .prospec.yaml + directory structure
prospec agent sync               # → per-agent config + Skills (Claude Code → CLAUDE.md +
                                 #   .claude/skills/; Antigravity / Codex / Copilot →
                                 #   AGENTS.md + .agents/skills/)

# `/prospec-quickstart` then, inside your AI agent:
#   • non-English doc language? proposes native trigger words for `skill_triggers`
#     in .prospec.yaml and re-runs agent sync once you confirm — skills then match
#     requests phrased in your language
#   • prospec knowledge init → /prospec-knowledge-generate (seeds AI Knowledge)

On a fresh repo, /prospec-knowledge-generate produces a minimal Knowledge base that fills in as you ship changes. Then run your first change exactly as in step 3 above.

Brownfield (existing projects)

same two commands; /prospec-quickstart reads your existing code into AI Knowledge:

cd existing-project
prospec quickstart                      # auto-detects tech stack; runs init + agent sync
# then, inside your AI agent:
/prospec-quickstart                     # localize triggers · re-sync · knowledge init · /prospec-knowledge-generate

Those two commands expand to:

# `prospec quickstart` runs:
prospec init          # → auto-detect tech stack; select AI assistants; choose doc
                      #   language (default: English; --language to skip the prompt)
prospec agent sync    # → per-agent config + Skills

# `/prospec-quickstart` then, inside your AI agent:
prospec knowledge init       # → generates raw-scan.md + empty skeletons (prospec/index.md, _conventions.md, module-map.yaml)
/prospec-knowledge-generate  # → AI reads raw-scan.md, decides module partitioning,
                             #   creates modules/*/README.md + fills prospec/index.md

Here knowledge init reads your existing code, so /prospec-knowledge-generate produces a rich Knowledge base up front. Then run your first change exactly as in step 3 above — the develop loop is identical to greenfield.

knowledge init captures how your code is structured, but brownfield modules usually still lack a Feature Spec describing what they do. Closing that WHAT-layer gap is its own first-class flow — see [Backfill: document existing code into the trust zone](#backfill-document-existing-code-into-the-trust-zone) below. It is not part of bootstrap, so run it whenever you choose.

Directory layout after completing the Quickstart (prospec quickstart + /prospec-quickstart)

your-project/
├── .prospec.yaml              # Prospec config
├── CLAUDE.md                  # Claude Code config (Layer 0, 

---

## How it works

Prospec runs one linear flow, wrapped in two feedback loops that make it **compound** rather than merely repeat.

```mermaid
flowchart TD
    E([Explore]) --> S([Story]) --> D(["Design (optional)"]) --> P([Plan]) --> T([Tasks]) --> I([Implement]) --> R([Review]) --> V([Verify]) --> KU([Knowledge Update]) -- Entry Gate --> A([Archive]) -- periodic --> L([Learn])

    V -. quality_log .-> L
    R -. findings .-> L
    L -- human-approved --> RULES[("Constitution + _playbookteam rules accumulate")]

    KU --> AK[("AI Knowledgemore complete every change")]
    A -- Spec Sync --> FS[("Feature Specsgraduate at archive")]

    AK -.-> NEXT["next change starts from aricher, smarter baseline"]
    FS -.-> NEXT
    RULES -.-> NEXT
    NEXT -. context .-> P

    classDef asset fill:#eef7ff,stroke:#2b6cb0,stroke-width:2px;
    classDef gain fill:#e9f9ee,stroke:#2f855a,stroke-width:2px;
    class AK,FS,RULES asset;
    class NEXT gain;

Every Archive enriches AI Knowledge (more complete with each change), and recurring lessons — review findings, the cross-stage quality_log, session corrections — promote, only with human approval, into an accumulating body of team rules (Constitution + _playbook). So the next change doesn't start from scratch; it starts from a richer, smarter baseline.

The flow is also scale-aware: a user-confirmed quick change skips the Plan stage entirely (story → tasks), with archive-time backstops — see [Right-Sized Process](#right-sized-process-scale).

Core principles

Prospec enforces 6 principles over the assets it injects into your project — the generated Skills, configs, and directory structure:

1. Progressive Disclosure First — never load all info at once; index → details
2. Spec is Source of Truth — changes documented in specs before code
3. Zero Startup Cost for Brownfield — no need to document the entire codebase upfront
4. AI Agent Agnostic — works with any AI CLI via Markdown adapters
5. User Controls the Rules — Constitution is user-defined, the tool enforces
6. Language Policy — AI-generated docs in the language you choose at prospec init (default: English); code, technical terms, and git commit messages always in English

---

Backfill: document existing code into the trust zone

Brownfield projects accumulate behavior that no Feature Spec describes. Backfill is a first-class, two-skill path that reverse-extracts that behavior from the code and graduates it into the spec trust zone (prospec/specs/features/) — and it never writes the trust zone by hand (archive stays the sole writer).

flowchart TD
    CODE[("existingbrownfield code")] --> BF([Backfill]) -- "draft + human review" --> PR([Promote]) -- "scale: backfill(no plan/tasks)" --> V([Verify]) -- "spec-fidelity → S/A" --> A([Archive])

    A -- Spec Sync --> FS[("Feature Specsgraduate into trust zone")]

    classDef asset fill:#eef7ff,stroke:#2b6cb0,stroke-width:2px;
    class CODE,FS asset;

1. Extract — /prospec-backfill-spec reads the code (and tests, git history, docs) and stages a route-compatible backfill-draft.md; intent it cannot infer from code is marked [NEEDS CLARIFICATION], never fabricated.
2. Review — resolve every [NEEDS CLARIFICATION] (the So that value, target role, ambiguous AC) and confirm the candidate feature slug. This is the human gate.
3. Promote — /prospec-promote-backfill turns the reviewed draft into the change scaffold (proposal + delta-spec + metadata) marked scale: backfill, status: implemented. backfill is a light scale like quick — no hollow plan.md/tasks.md, because the code already exists.
4. Verify — /prospec-verify grades spec-fidelity (each REQ's file:line must resolve), records pre-existing code-quality gaps (e.g. untested brownfield code) as informational tech debt, and only applies that

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: benwu95
• Source: benwu95/prospec
• License: MIT
• Homepage: https://benwu95.github.io/prospec/

Install and usage instructions live in the source repository linked above.