pb-spec — Plan-Build Spec

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.

Features

• 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

Installation

# Recommended
uv tool install pb-spec

# Alternative
pipx install pb-spec

Quick Start

# 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

Supported AI Tools

AI Tool	Target Directory	File Format
Claude Code	.claude/skills/pb-<name>/SKILL.md	YAML frontmatter + Markdown
VS Code Copilot	.github/prompts/pb-<name>.prompt.md	Markdown (no frontmatter)
OpenCode	.opencode/skills/pb-<name>/SKILL.md	YAML frontmatter + Markdown

CLI Reference

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).

Workflow

four agent skills that chain together:

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

1. /pb-init — Project Initialization

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.

2. /pb-plan <requirement> — Design & Task Planning

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)

3. /pb-refine <feature-name> — Design Iteration (Optional)

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.

4. /pb-build <feature-name> — Subagent-Driven Implementation

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.

Skills Overview

Skill	Trigger	Output	Description
pb-init	/pb-init	AGENTS.md	Detect stack, scan structure, generate project context
pb-plan	/pb-plan <requirement>	specs/<name>/design.md + tasks.md	Design proposal + ordered task breakdown
pb-refine	/pb-refine <feature>	Revised spec files	Apply feedback or Design Change Requests
pb-build	/pb-build <feature-name>	Code + tests	TDD implementation via subagents

Development

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

License

Apache-2.0 © 2025 Bob Liu