A shared, resumable development workflow for AI coding agents
Project-local specs, rules, and change history · Skills guide judgment · the CLI executes deterministic steps
繁體中文 • Quickstart • Why Prospec? • Documentation • How It Works • CLI Reference
This project is a fork of ci-yang/prospec
Prospec combines Project + Specification. It gives developers and AI coding agents a shared workflow grounded in files inside the project. Specs describe expected behavior; the Constitution, conventions, and module knowledge record project rules and things an agent needs to know before changing code. In-progress change files capture the request, plan, and tasks. When work pauses, prospec status reports the current station, next Skill, and blocking gates, so another agent working in the same project can resume from the recorded state.
You work through host-aware Skills inside your agent (Claude Code, Antigravity, Copilot, Codex). Each station has instructions for the judgment it needs — interviews, prose, reviews, and verdicts — while the required standalone prospec CLI handles deterministic scaffolding, status transitions, structured records, checks, grading, and spec sync. The standard path is story → plan → design → tasks → implement → knowledge-update → review → verify → archive; Design is conditional on UI scope, and change scale can shorten the path.
Three pieces work together:
You ⇄ AI agent
│
├─ Skills .......... run the workflow: story → plan → design → tasks →
│ implement → knowledge-update → 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? Teams and solo developers who use AI coding agents and want work to remain understandable across sessions or agents, in a new project (greenfield) or an existing codebase (brownfield).
Review uses eight shared lenses: correctness, security and spec-architecture run every round; five conditional lenses follow the diff. Security details load on demand for applicable risk surfaces. Review skills installed in your environment that match the diff add their criteria under prospec's own contract and project conventions, and a performance trade-off accepted without production data volume is asked for that data. prospec learn yield groups known aliases and protects must-run lenses from yield-based retirement; see the CLI reference for evidence thresholds and declaration behavior.
| Challenge | How Prospec helps |
|---|---|
| AI doesn't know your codebase | prospec knowledge init + prospec-knowledge-generate auto-scan and generate AI-readable docs |
| A new agent cannot tell where work stopped | Project-local change artifacts preserve the current work; prospec status names the next station and its blocking gates |
| Context window limits | Progressive disclosure: load a summary first, details on demand; verify the impact on your own sessions with prospec measure |
| Inconsistent AI workflows | Structured Skills enforce story → plan → design → tasks → implement → knowledge-update → review → verify → archive with explicit conditional branches |
| 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 | Sync Knowledge before final review/tests/verify; verify adopts repository-wide Knowledge health, the S/A prompt confirms validated inputs, and archive re-confirms synchronization |
| 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 — see AI Skills and the Workflow and the CLI Reference.
From zero to your first AI-driven change in about five minutes.
- An AI CLI (one or more): Claude Code (recommended), Codex CLI, GitHub Copilot CLI, or Antigravity CLI
- Node.js >= 22.13.0 — only for the npm/npx or source-development paths; the standalone binary below needs none.
Option A: Standalone Binary (Recommended & No Node.js Required)
For macOS and Linux, run the one-click installer script (installs to ~/.prospec/bin and configures PATH):
curl -fsSL https://raw.githubusercontent.com/benwu95/prospec/main/install.sh | bashFor Windows, run the one-click PowerShell installer script:
powershell -c "irm https://raw.githubusercontent.com/benwu95/prospec/main/install.ps1 | iex"Version pinning, manual binary downloads, and the devDependency / npx options are in Getting Started.
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 + Skillsprospec 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.
prospec-<name> is the canonical Skill identity. The spelling used to invoke a Skill manually belongs to the host, not to the Skill name:
| Host | Explicit invocation |
|---|---|
| Claude Code | /prospec-<name> |
| Codex | $prospec-<name> |
| GitHub Copilot | /prospec-<name> |
| Antigravity | Mention the bare Skill name or select it from the Skills browser: prospec-<name> |
Use these forms only for explicit invocation. Skill descriptions and triggers still enable implicit discovery, so no workflow becomes manual-only.
You don't have to remember the steps — describe the change in plain language and the agent drives the gated SDD cascade, pausing for scoping questions, a failed gate or circuit breaker, and final Tastemaker sign-off:
🤖 Run inside your AI Agent chat:
You ▸ Ask 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
• as machine gates pass, continues autonomously:
implement → knowledge update ✓ → review → verify → GRADE A
→ Tastemaker sign-off (you inspect the diff + evidence)
→ you approve the commit and archive ✓
The cascade pauses only for clarification, a failed gate or circuit breaker, a plan sign-off where one applies, and final Tastemaker sign-off, and it never commits, pushes, or archives without your explicit approval. The pause rules are in AI Skills and the Workflow; driving each station yourself, and the full greenfield and brownfield walkthroughs, are in Getting Started. Direct CLI creation requires an explicit scope declaration: prospec change story <name> --related-module <module> (repeatable), or prospec change story <name> --no-related-modules after determining none apply. Skills judge this scope before scaffolding and reconcile it once the proposal is concrete. Correct legacy or inaccurate scope through prospec change related-modules; CLI Reference documents the breaking changes and migration.
In worktree mode, active changes stay in the source .prospec/changes/; complete archive/abandoned bundles live in the corresponding main worktree project’s .prospec/archive/ and .prospec/abandoned/. Read actual locations with prospec history paths --json; preview existing local history with prospec history import --from <project-root> --dry-run. Edit the returned archivePath summary and run prospec archive finalize <name> --bundle <archiveIdentity> in the source before removing that worktree. Retention is not Git backup or work restoration.
Guides and reference material beyond the first change live in docs/, grouped by what you are trying to do:
- Getting Started — every installation option, greenfield and brownfield bootstrap, and driving each station yourself.
- How It Works — how Skills, AI Knowledge and the CLI divide the work, what is enforced and by what, and the core principles.
- AI Skills and the Workflow — the Skill catalog, quality gates, right-sized process, sourced premises and cascade pauses.
- Guides — Upgrading Prospec (including what changed in 2.0), Backfill, and Customizing Module READMEs.
- CLI Reference — commands, generated layout and architecture; see the Configuration Reference for configuration fields.
Contributions are welcome — see CONTRIBUTING.md for development setup, testing, and the SDD workflow this repository uses on itself.
MIT License - see LICENSE for details.
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.
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.
Made with care for the AI-powered development community