Prospec

What is Prospec?

Prospec is a CLI-first 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), and every deterministic operation those Skills perform — scaffolding, status transitions, quality-log writes, spec sync, grading — is executed by the prospec CLI (a required, standalone executable), so the same repo state always produces the same bytes. Skills keep the judgment: interviews, prose, reviews, verdicts. The payoff: your agent follows a consistent story → plan → tasks → implement → review → verify → archive workflow, grounded in structured, version-controlled project knowledge, with the nondeterministic LLM kept out of the bookkeeping.

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) ... executes every deterministic step:  scaffolds, status
                          transitions, quality-log writes, drift checks, grading, spec sync

• Skills run the workflow's JUDGMENT inside your agent — interviews, prose, reviews, verdicts — the day-to-day surface.
• AI Knowledge is progressive project memory the Skills read and grow with each change.
• CLI is a required standalone executable IN the runtime loop: every deterministic operation the Skills need — bootstrap, scaffolds, lifecycle transitions, structured records, drift checks, grading, archive sync — runs as code, byte-reproducibly.

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?

Each row maps to a Skill or command below — see AI Skills and 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 <command>

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.

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

# `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]
                                 #   path-scoped Language Policy rule is seeded into
                                 #   CONSTITUTION.md — the trust zone, 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)

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

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

your-project/
├── .prospec.yaml              # Prospec config
├── CLAUDE.md                  # Claude Code config (Layer 0, <100 lines)
├── AGENTS.md                  # Antigravity / Codex / Copilot config (agents.md standard)
├── {base_dir}/
│   ├── README.md              # Short Prospec intro for this project's readers
│   ├── CONSTITUTION.md        # Project rules (user-defined)
│   ├── index.md               # AI Entry Point & Module index (Markdown table)
│   ├── specs/
│   │   ├── product.md         # Product Spec (PRD entry point)
│   │   └── features/          # Living Feature Specs (accumulated)
│   └── ai-knowledge/
│       ├── _conventions.md    # Project conventions
│       ├── _playbook.md       # Team lessons promoted by /prospec-learn (human-gated)
│       ├── _lessons-ledger.md # Accumulating lessons ledger, auto-fed at Archive (version-controlled)
│       ├── raw-scan.md        # Auto-generated project scan data
│       ├── module-map.yaml    # Module dependencies
│       ├── feature-map.yaml   # Feature→module index (optional; bootstrapped at Archive)
│       └── modules/
│           └── {module}/
│               └── README.md  # Module-specific docs
├── .prospec/                  # Change management (not committed)
│   ├── changes/
│   │   └── {change-name}/
│   │       ├── proposal.md        # User Story + acceptance criteria
│   │       ├── design-spec.md     # Visual spec (optional, UI changes)
│   │       ├── interaction-spec.md # Interaction spec (optional)
│   │       ├── plan.md            # Implementation plan
│   │       ├── tasks.md           # Task breakdown (checkbox format)
│   │       ├── delta-spec.md      # Patch Spec (ADDED/MODIFIED/REMOVED)
│   │       └── metadata.yaml      # Change lifecycle metadata
│   └── archive/               # Archived completed changes
├── .claude/skills/            # Skills for Claude Code (one dir per skill)
│   ├── prospec-explore/
│   ├── prospec-new-story/
│   ├── prospec-design/
│   ├── prospec-plan/
│   ├── prospec-tasks/
│   ├── prospec-ff/
│   ├── prospec-implement/
│   ├── prospec-review/
│   ├── prospec-verify/
│   ├── prospec-archive/
│   ├── prospec-learn/
│   ├── prospec-knowledge-generate/
│   ├── prospec-knowledge-update/
│   ├── prospec-backfill-spec/
│   ├── prospec-promote-backfill/
│   ├── prospec-quickstart/       # one-time onboarding finisher (on disk, excluded from entry config)
│   └── prospec-upgrade/          # version-upgrade finisher (on disk, excluded from entry config)
└── .agents/skills/            # Same skills, agents.md format (Antigravity / Codex / Copilot)
    └── prospec-*/

How it works

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

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 + _playbook<br/>team rules accumulate")]

    KU --> AK[("AI Knowledge<br/>more complete every change")]
    A -- Spec Sync --> FS[("Feature Specs<br/>graduate at archive")]

    AK -.-> NEXT["next change starts from a<br/>richer, 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.

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 — change artifacts in the language you choose at prospec init (default: English); the trust zone (AI Knowledge base, Feature Specs, Constitution), 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[("existing<br/>brownfield code")] --> BF([Backfill]) -- "draft + human review" --> PR([Promote]) -- "scale: backfill<br/>(no plan/tasks)" --> V([Verify]) -- "spec-fidelity → S/A" --> A([Archive])

    A -- Spec Sync --> FS[("Feature Specs<br/>graduate 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 relaxation when a backfill-draft.md proves provenance — so a faithful draft reaches S/A instead of being blocked by debt it merely documents, and the marker can't bypass quality gates for new code.
5. Archive — /prospec-archive graduates the requirements into prospec/specs/features/{slug}.md. That is the only step that writes the trust zone.

Upgrading Prospec

When a new prospec version ships, re-run the install to pull the latest (it's an unpublished GitHub fork, so this re-clones + rebuilds the current commit):

npm install -g github:benwu95/prospec     # or: pnpm add -g github:benwu95/prospec
# pinned per-project devDependency: npm install -D github:benwu95/prospec

Then bring an existing project up to date in two steps — a deterministic CLI step, then a consent-gated AI step:

prospec upgrade                  # CLI (zero-LLM): record the new version, re-sync agents + create any missing init docs

🤖 Run inside your AI Agent chat:
/prospec-upgrade                 # in your AI agent: enrich created docs + migrate drifted init-doc formats + localize new-skill triggers (asks before each change)

• prospec upgrade (CLI) records the running prospec version in .prospec.yaml version (merged in place, so your comments and formatting survive), re-runs agent sync so your per-agent config and Skills match the new templates, refreshes the deterministic raw-scan.md to the new version's scanner, and prints a migration report (version delta; a docs inventory listing every doc prospec init creates as present or missing — derived from the same registry init itself uses, so it can never miss a file; then either a nudge to set an artifact_language when the project never chose one — e.g. a project scaffolded by a pre-feature CLI — or any newly-added skills missing native-language triggers). On an interactive terminal it prompts you to fill each nudge (like prospec init); piped/CI runs — and the /prospec-upgrade skill — pass --no-interactive and just get the report. It back-fills any missing init-created doc, rendering it from the same template prospec init uses (skip-if-exists) — so a doc a newer prospec added lands without re-running prospec init (which is blocked once .prospec.yaml exists) — but it never overwrites or reformats an existing doc: CONSTITUTION.md, _conventions.md, prospec/index.md, the canonical convention docs, and module READMEs stay byte-for-byte (migrating an existing doc's format is the skill's job; the only other ai-knowledge/ write is the always-regenerable raw-scan.md).
• /prospec-upgrade (Skill) finishes the judgment work the CLI can't do safely: it works through the report's docs inventory — comparing each present doc to its latest template and offering to update any whose format has drifted, enriching the docs the CLI just back-filled that need more than a baseline (e.g. index.md's real module table, or migrating a legacy _index.md's curated columns), and, as a safety net, offering to create any doc still marked missing (a back-fill that failed) — asking for your confirmation per file (it never overwrites your authored content). It then localizes triggers for any newly-added skills into your artifact_language (filling only the missing ones) and re-runs agent sync.

.prospec.yaml version is the prospec version the project last upgraded to (a legacy version: "1.0" is treated as stale and bumped on first prospec upgrade). Need to (re-)localize triggers after adding a skill? Just re-run prospec agent sync — it names any skill missing a skill_triggers entry, so you fill only the gap. You never need to delete .prospec.yaml.

AI Skills

Prospec generates 17 Skills — 15 guide AI through the full SDD lifecycle, plus two periodic finishers: /prospec-quickstart (onboarding) and /prospec-upgrade (version upgrade):

Periodic finishers — /prospec-quickstart (run once after prospec quickstart) and /prospec-upgrade (run after prospec upgrade on a version bump) finish the judgment steps the CLI cannot do deterministically. Both are deployed as Skills on disk but kept out of the always-loaded entry config, so they add no recurring token cost.

Quality Gates & Self-Improvement

Beyond the linear flow, every workflow Skill carries built-in quality machinery:

• Output Contract — each Skill self-reports Met N/M | Overall: PASS|WARN|FAIL against objective criteria, so you don't hand-check artifacts.
• Entry / Exit gates — a Skill checks preconditions before running (Entry) and Constitution compliance after (Exit); WARN/FAIL records persist to a cross-stage quality_log so an earlier stage's concern surfaces at the next.
• Skill instruction quality — per-phase gate checklists (finer-grained than the skill-level Entry/Exit gates); a status-aware next-step handoff at the end of each linear-flow Skill (plan→tasks→implement→review→verify→archive) (Run <next-step> now? (Y/n) — your Y is the trigger, never a silent auto-run); new-session detection of in-progress changes to resume; /prospec-implement re-anchors Progress X/Y | Goal | Next after each task; and /prospec-explore / /prospec-knowledge-generate warn when the Constitution is still substantively empty (its gates would otherwise be no-ops).
• Executable Constitution — rules carry RFC-2119 severity (MUST→FAIL / SHOULD→WARN / MAY→advisory); /prospec-verify grades against them.
• Deterministic drift gate — prospec check machine-verifies spec ↔ code ↔ knowledge referential integrity with zero tokens; /prospec-verify consumes its report at dev time and the scaffolded CI workflow enforces it on every PR. With an optional feature-map.yaml (feature→module index, bootstrapped at archive) it adds two governance checks: REQ-prefix legality (WARN) and the feature→module edge (FAIL).
• Adversarial review — /prospec-review sits between implement and verify: an independent fresh-context reviewer audits the whole change diff; only verifier-confirmed, drop-in criticals are auto-fixed, the rest escalate to you. The commit boundary is after verify reaches grade S/A, so implement + review + verify fixes land in one atomic commit (prospec prompts; it never auto-commits).
• Feedback promotion — every Archive auto-harvests a change's recurring lessons into a version-controlled ledger (_lessons-ledger.md); /prospec-learn then scores them with an explicit reproducible rule (frequency + impact modules) and — only with explicit human approval — promotes them into the team _playbook.md or the Constitution. Before each collection it sweeps both files for entries the project has outgrown — a rule some gate now enforces, one whose subject is gone, or one that contradicts the Constitution — and surfaces each with its evidence for human retirement; expiry retires in place (a ledger row keeps every counter, a playbook id is never reused), so the audit trail survives the cleanup.

Right-Sized Process (Scale)

Not every change deserves the full ceremony. At story time, /prospec-new-story (or /prospec-ff) assesses complexity against explicit criteria and proposes a scale — you confirm before it is written to metadata.yaml:

Two honest backstops keep quick from becoming a spec-drift hole: a change expected to touch spec-covered behavior is vetoed out of quick at assessment time, and the /prospec-archive Entry Gate re-checks the actual diff — spec impact blocks archiving until a minimal Spec Impact section is added, and the knowledge-sync gate derives affected modules from diff paths instead of the absent delta-spec. Engineering discipline is not scaled down: TDD, adversarial review, and Constitution audits run at every scale.

Tasks also carry a kind marker ([M] manual, [V] verification, unmarked = code): completion rates count code tasks only, so an unchecked "run this command manually" reminder never blocks or distorts a gate.

CLI Commands

Infrastructure Commands

Agent config layout — agent sync writes each detected agent's entry config + Skills:

• Claude Code → CLAUDE.md + .claude/skills/
• Antigravity / Codex / GitHub Copilot → AGENTS.md + .agents/skills/ (the shared agents.md open standard; written once even when several are enabled)

Skills whose workflow depends on the harness — today /prospec-review and /prospec-verify — state what it can do (can_spawn_subagent / can_worktree / can_background) instead of asking the agent to guess at runtime. Because one .agents/skills/ copy serves several agents, it states the intersection of their capabilities, never promising something one of them lacks.

Your edits are safe: entry configs carry prospec:auto / prospec:user blocks. agent sync (and init for AGENTS.md) refresh only the auto block and preserve whatever you write in the user block; a pre-existing hand-written CLAUDE.md / AGENTS.md is migrated into the user block on first sync rather than clobbered.

Upgrading from an older Prospec? After re-syncing, remove the now-unused GEMINI.md, .gemini/skills/, .codex/skills/, .github/copilot-instructions.md, and .github/instructions/.

Project-scan language support

prospec knowledge init (incl. --raw-scan-only) detects the following into raw-scan.md. Detection is deterministic (no LLM, no network) and best-effort; coverage differs by section:

¹ Java dependencies are read from Maven pom.xml only — the Gradle Groovy/Kotlin DSL is not statically parsed. ² Ruby dependencies are not parsed (Gemfile is a Ruby DSL). ³ C vs C++ is inferred from source-file extensions; set tech_stack in .prospec.yaml to override. ⁴ C/C++ dependencies are read from declarative manifests only — CMakeLists.txt and conanfile.py are imperative and not parsed. ⁵ Swift dependencies are not parsed (Package.swift is imperative Swift). Any unrecognized language still appears in the Directory Tree and File Stats sections — and, because an unlisted extension counts as source, its code directories stay OUT of Directories Without Source Files.

Directories the scan cannot classify as code. raw-scan.md also carries a Directories Without Source Files section: each topmost directory in which no file counts as source — the module detector requires a file to carry an extension AND for that extension not to be on its non-source denylist, so a directory whose only content is extensionless files (a bin/ of scripts) lands here too. Root-level files belong to no directory and are never listed. It is a scan fact, not a detection verdict: a curated module-map.yaml (which detection always prefers) or the no-module fallback can still make such a directory a module. The section is the evidence /prospec-knowledge-generate weighs when deciding whether one of them — a manifests/ of Kubernetes YAML, a chapters/ of LaTeX — is really this project's substance and belongs in module-map.yaml.

A language outside this table? It still scans — the Directory Tree and File Stats sections are always populated, and /prospec-knowledge-generate reads the source directly. The Tech Stack line falls back to unknown; declare it authoritatively in .prospec.yaml tech_stack (free-form — it overrides auto-detection and is reported with Source: config):

tech_stack:
  language: zig
  package_manager: zig build

Entry Points, Dependencies, and Config Files have no per-language override — they stay empty for an unrecognized language until detection patterns are added (the scan never invents them).

Change Management Commands

| prospec change scale <quick\|standard\|full\|backfill> [--change <name>] | Write the user-confirmed complexity scale (comment-preserving in-place edit) | | prospec change status <to> [--change <name>] | Forward-only lifecycle transition; a backward/invalid jump is refused with the legal targets listed | | prospec change log --skill <station> --result <PASS\|WARN\|FAIL> [--warning <w>...] [--grade <g>] [--dimension n=r...] [--criticals-found <n>] ... | Append one structured quality_log entry (canonical key order, escaping by construction) | | prospec change progress [--complete <task>] [--change <name>] | Code-task progress (X/Y, [M]/[V] excluded) + next task; --complete flips exactly one checkbox | | prospec review merge --findings <file> [--change <name>] | Merge one review round's findings JSON into the cumulative review.md table (identity-keyed, severity max, carry-forward) and report the round's structured counts | | prospec verify record --dimension <name>=<result>... [--warning <w>...] | Compute the S/A/B/C/D grade — machine dimensions self-sourced from the prospec-report.json drift report (whose test-provenance check carries the recorded test run), judgment dimensions from the flags — record the structured quality_log entry, and advance status: verified on S/A | | prospec learn upsert --lesson <file> [--today <date>] | Keyed idempotent lessons-ledger upsert + the explicit freq≥3 ∧ modules≥2 scoring rule (auditable detail) + playbook TTL scan | | prospec validate <kind> [target] [--change <name>] | Machine verdicts for artifact structure: slug / promote-scaffold (complete) and backfill-draft / design-spec (structural subset — sections, headers, NC locations); FAIL exits 1 |

Note: These commands ARE the workflow's deterministic layer (issue #107 restored the cli-first posture): the Skills (/prospec-new-story, /prospec-ff, …) call them for every scaffold, transition, and record instead of hand-writing artifacts, and each Skill STOPs when the CLI is missing or older than its probe floor. They remain equally available for manual or scripted use.

MCP Server

A read-only, stdio MCP server that exposes the project's truth — architecture, specs, dependency direction, promoted playbook, and knowledge freshness — to any MCP-capable agent, even one without Prospec Skills installed.

Resources (re-read from disk on every request — clients always see current file state):

Tools: search_modules (which module owns a concept — normalized term-OR match over the curated index columns, so drift checker finds drift-checker) and get_dependency_direction (may from import to? — answered from module-map depends_on, or the Constitution chain when no map exists; the answer states which source it used).

Registering — point your agent's MCP config at prospec mcp serve --cwd <project-root>. --cwd pins the project so the server resolves its .prospec.yaml no matter where the agent was launched — which also lets one agent register several projects at once. Assumes the recommended global install (prospec on PATH).

Claude Code:

claude mcp add project-name -- prospec mcp serve --cwd /path/to/project

Other agents — the same command in the agent's JSON MCP config:

{
  "mcpServers": {
    "project-name": {
      "command": "prospec",
      "args": ["mcp", "serve", "--cwd", "/path/to/project"]
    }
  }
}

To serve several projects from any directory, register one entry per project — each with a unique name and its own --cwd (Claude Code: add -s user so it's available everywhere):

claude mcp add -s user prospec-a -- prospec mcp serve --cwd /path/to/A
claude mcp add -s user prospec-b -- prospec mcp serve --cwd /path/to/B

Pinned prospec as a devDependency rather than installed globally? Route through npx: prefix the Claude Code command (… -- npx prospec mcp serve --cwd /path/to/project), or in JSON set "command": "npx" with "prospec" as the first arg (["prospec", "mcp", "serve", "--cwd", "/path/to/project"]).

Honest boundaries: the server is read-only (no tool or resource can modify files), serves one project per process (the root given by --cwd), and is a pure add-on — no Skill or CLI command depends on it, so everything works unchanged when it is not running. Transport is stdio only; HTTP/SSE is deliberately not included in this version.

# .prospec.yaml
knowledge:
  token_budget:
    l1_per_file: 1800       # max tokens per L1 file (index.md + each core convention)
    l2_per_module: 1000     # max tokens per module file (README and each sub-module)
    readme_max_lines: 100   # max lines per module file

Configuration

Prospec can be configured via a .prospec.yaml file in the project root. This is the primary way to customize how AI Knowledge is generated and how the workflow operates.

Key configurations you can tweak:

• artifact_language: Sets the language for change artifacts under .prospec/changes/ and their archived summaries (e.g. Traditional Chinese (Taiwan)). The trust zone — the AI Knowledge base, specs/features/, specs/product.md, index.md, README.md, CONSTITUTION.md — plus code, identifiers, technical terms, and git commit messages are always kept in English. prospec init seeds a path-scoped Language Policy rule into CONSTITUTION.md from these same paths, so the rule and your agent's entry config (CLAUDE.md/AGENTS.md) always state one scope.
• exclude: Glob patterns for directories to exclude from AI knowledge scanning. Defaults include node_modules, .git, and common build directories.
• agents: Specifies which AI agent configs to generate (claude, antigravity, codex, copilot).
• tech_stack: Overrides auto-detected tech stack (e.g., language: zig, package_manager: zig build).
• knowledge.strategy: Determines how the project is split into modules during knowledge generation (auto, architecture, domain, package).
• knowledge.token_budget: Controls token/line size limits for L1 and L2 knowledge files.
• knowledge.additional_core_conventions: Prospec's knowledge system loads _conventions.md (and CONSTITUTION.md) by default when the Agent starts. If you have other globally shared convention files (e.g., API guidelines, security rules) that you want to be pre-loaded as Core Conventions, you can list them here. These paths are relative to the ai-knowledge/ directory.
• skill_triggers: Allows customizing the activation keywords for specific AI Skills to match your native language.

Example .prospec.yaml (for the full annotated reference of every field, run prospec config example):

version: "1.0"
project:
  name: my-project
tech_stack:
  language: typescript
  package_manager: pnpm
paths:
  base_dir: prospec
artifact_language: Traditional Chinese (Taiwan)
exclude:
  - "*.env*"
  - "node_modules"
agents:
  - claude
  - antigravity
knowledge:
  base_path: prospec/ai-knowledge
  strategy: domain
  token_budget:
    l1_per_file: 1800
    l2_per_module: 1000
    readme_max_lines: 100
  additional_core_conventions:
    - my-custom-api-rules.md
skill_triggers:
  prospec-explore:
    - explore
    - 探索

Architecture

Prospec uses Pragmatic Layered Architecture for CLI development best practices:

src/
├── cli/          — Commander.js commands + formatters
├── services/     — Business logic (14 services)
├── lib/          — Pure utility functions (config, fs, logger, etc.)
├── types/        — Zod schemas + TypeScript types
└── templates/    — Handlebars templates (66 .hbs files)
    └── skills/   — 17 Skill templates + 19 reference templates

Tech Stack

• CLI Framework: Commander.js 14 + @inquirer/prompts 8
• Validation: Zod 4
• Templating: Handlebars 4.7
• File Scanning: fast-glob 3.3
• YAML: eemeli/yaml 2.x (preserves comments)
• Testing: Vitest 4.0 + memfs
• TypeScript: 5.9

Testing

# Run all tests (3120 tests)
pnpm test

# Watch mode
pnpm run test:watch

# Type check
pnpm run typecheck

# Lint
pnpm run lint

Test Coverage: 3120 tests across 4 categories:

• Unit tests (types + lib + services + cli): 2232 tests
• Contract tests (CLI output + Skill format): 777 tests
• Integration tests: 45 tests
• E2E tests: 66 tests

The suite includes a real init + agent sync generation contract (tests/integration/skill-contract.test.ts) asserting agent-specific reference paths, no dangling references, canonical convention docs, base_dir-relative spec paths, and .agents convergence.

Keeping factual counts in sync — the test totals and .hbs inventory quoted across the READMEs and prospec/index.md are machine-generated from a single source (vitest + the filesystem), not hand-edited:

# Rewrite every count in place to match the current suite/filesystem
pnpm counts

# Dry-run: report drift and exit 1 if any count is stale
pnpm counts:check

CI's test job runs the read-only form with --from, pointed at the JSON report pnpm run test:coverage writes in the step before it — so the gate costs no second suite run, and a stale count fails the PR. --from is read-only by construction: the rewrite mode refuses it, because nothing can tell a just-written report from yesterday's.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development uses pnpm (Node 22.13+, pnpm 11+).

# Clone and install
git clone https://github.com/benwu95/prospec.git
cd prospec
pnpm install

# Run in dev mode
pnpm run dev

# Build
pnpm run build

# Test
pnpm test

# First time: install deps, build, then register the bin globally
pnpm install && pnpm run build && pnpm add -g .

# After making changes, just rebuild — the global bin picks up the new dist/
pnpm run build

# Remove it when finished
pnpm uninstall -g prospec

License

MIT License - see LICENSE for details.

Acknowledgments

Prospec is a fork of ci-yang/prospec by Ci Yang — the upstream project this codebase originates from.

Beyond that lineage, Prospec draws inspiration from:

• OpenSpec — Delta Specs, Fast-Forward, Archive
• Spec-Kit — Constitution validation
• cc-sdd — Steering analysis, template customization
• BMAD — Analyst role (prospec-explore)

Prospec's unique contribution: cli-first SDD with judgment-only Skills — the CLI executes every deterministic operation (scaffolds, transitions, grading, spec sync) so it is reproducible and token-free, while Skills run the judgment inside your AI agent. Plus AI Knowledge as Context Engineering — structured, versioned, progressive project memory for AI agents.

See Also

prospec-verify and prospec-review adapt engineering heuristics (failure-recovery triage, and security / performance / maintainability lens criteria) from addyosmani/agent-skills (MIT) — vendored into prospec's own self-contained reference templates, so no plugin install is required for prospec to work. If you want the fuller standalone treatment, that plugin is worth a look as optional further reading: marketplace addy-agent-skills, plugin agent-skills (invocable as agent-skills:*). Attribution: see THIRD-PARTY-NOTICES.

Links

• AI Knowledge Index
• Feature Specs