pb-spec is a CLI tool that installs AI coding assistant skills into your project. It provides a structured workflow — init → plan → build — that turns natural-language requirements into implemented, tested code through AI agent prompts.

• 4 agent skills: pb-init, pb-plan, pb-refine, pb-build — covering project analysis, design planning, iterative refinement, and TDD implementation
• 3 platforms: Claude Code, VS Code Copilot, OpenCode
• Zero config: run pb-spec init and start using AI prompts immediately
• Idempotent: safe to re-run; use --force to overwrite existing files
• Built with: Python 3.12+, click, uv

# Recommended
uv tool install pb-spec

# Alternative
pipx install pb-spec

# 1. Install skills for your AI tool
cd my-project
pb-spec init --ai claude       # or: copilot, opencode, all

# 2. Open the project in your AI coding assistant and use the skills:
#    /pb-init                          → Generate AGENTS.md project context
#    /pb-plan Add WebSocket auth       → Generate design.md + tasks.md
#    /pb-refine add-websocket-auth     → (Optional) Refine design based on feedback
#    /pb-build add-websocket-auth      → Implement tasks via TDD subagents

pb-spec init --ai <platform> [--force]

Install skill files into the current project.

• --ai — Target platform: claude, copilot, opencode, or all
• --force — Overwrite existing files

pb-spec version

Print the installed pb-spec version.

pb-spec update

Update pb-spec to the latest version (requires uv).

four agent skills that chain together:

/pb-init → /pb-plan → [/pb-refine] → /pb-build

Analyzes your project and generates an AGENTS.md file at the project root. This file captures the tech stack, directory structure, conventions, and testing patterns. Preserves user-added context so manual notes aren't lost on re-runs.

Takes a natural-language requirement and produces a complete feature spec:

specs/<feature-name>/
├── design.md    # Architecture, API contracts, data models
└── tasks.md     # Ordered implementation tasks (logical units of work)

Reads user feedback or Design Change Requests (from failed builds) and intelligently updates design.md and tasks.md. It maintains a revision history and cascades design changes to the task list without overwriting completed work.

Reads specs/<feature-name>/tasks.md and implements each task sequentially. Every task is executed by a fresh subagent following strict TDD (Red → Green → Refactor). Supports Design Change Requests if the planned design proves infeasible during implementation.

# Clone
git clone https://github.com/longcipher/pb-spec.git
cd pb-spec

# Install dependencies
uv sync --group dev

# Run tests
uv run pytest -v

# Install locally for testing
uv pip install -e .

Apache-2.0 © 2025 Bob Liu