# Prospec

> Progressive Spec-Driven Development (SDD) toolkit for AI coding agents — Claude Code, Copilot, Codex. Slash-command Skills + structured AI Knowledge + MCP server; Progressive Disclosure cuts 70–80% tokens. Brownfield & greenfield.

- **Type:** MCP server
- **Install:** `agentstack add mcp-benwu95-prospec`
- **Verified:** Pending review
- **Seller:** [benwu95](https://agentstack.voostack.com/s/benwu95)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [benwu95](https://github.com/benwu95)
- **Source:** https://github.com/benwu95/prospec
- **Website:** https://benwu95.github.io/prospec/

## Install

```sh
agentstack add mcp-benwu95-prospec
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/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](https://docs.anthropic.com/claude/docs/claude-code) (recommended), [Codex CLI](https://developers.openai.com/codex/cli), [GitHub Copilot CLI](https://docs.github.com/copilot/github-copilot-in-the-cli), or [Antigravity CLI](https://antigravity.google/)

### 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:
```bash
curl -fsSL https://raw.githubusercontent.com/benwu95/prospec/main/install.sh | bash
```

For Windows, run the one-click PowerShell installer script:
```powershell
powershell -c "irm https://raw.githubusercontent.com/benwu95/prospec/main/install.ps1 | iex"
```

Alternatively, download the precompiled binary manually from the [GitHub Releases](https://github.com/benwu95/prospec/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:
```bash
npx github:benwu95/prospec 
```

**Option C: Pin as devDependency (Node.js projects)**
Install as a local project dependency:
```bash
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:

```bash
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:

```text
🤖 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:

```text
🤖 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:

```text
🤖 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:

```bash
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:

```bash
# `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:

```bash
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:

```bash
# `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).

```mermaid
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](https://github.com/benwu95)
- **Source:** [benwu95/prospec](https://github.com/benwu95/prospec)
- **License:** MIT
- **Homepage:** https://benwu95.github.io/prospec/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-benwu95-prospec
- Seller: https://agentstack.voostack.com/s/benwu95
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.