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.

🧠 Design Philosophy

pb-spec follows a harness-first philosophy: reliability comes from process design, explicit checks, and recoverability, not from assuming one-shot model correctness.

Best-Practice Alignment

Source	Core Idea	How pb-spec Applies It
RPI Strategy	Separate research, planning, and implementation	/pb-init + /pb-plan precede /pb-build
Plan-and-Solve Prompting	Plan first to reduce missing-step errors	design.md + tasks.md are mandatory artifacts
ReAct	Interleave reasoning and actions with environment feedback	/pb-build executes task-by-task with test/tool feedback loops
Reflexion	Learn from failure signals via iterative retries	Retry/skip/abort and DCR flow in pb-build
Effective Harnesses for Long-Running Agents	Grounding, context hygiene, recovery, observability	State checks, minimal context handoff, task-local rollback guidance
Building Effective Agents	Prefer simple composable workflows over framework complexity	Small adapter-based CLI + explicit workflow prompts
Stop Using /init for AGENTS.md	Keep AGENTS.md focused and maintainable	/pb-init updates a managed snapshot block in AGENTS.md while preserving all user-authored constraints outside that block

Practical Principles in pb-spec

• Context Before Code: /pb-init and /pb-plan establish project and requirement context before implementation starts.
• Verification by Design: Planning requires explicit verification commands so completion is measurable.
• Strict TDD Execution: /pb-build enforces Red → Green → Refactor with per-task status tracking.
• Safe Failure Recovery: Failed attempts use scoped recovery guidance to avoid polluting unrelated workspace state.
• Composable Architecture: Platform differences stay in adapters; workflow semantics stay in shared templates.

Features

• 4 agent skills: pb-init, pb-plan, pb-refine, pb-build — covering project analysis, design planning, iterative refinement, and TDD implementation
• 5 platforms: Claude Code, VS Code Copilot, OpenCode, Gemini CLI, Codex
• 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/prompts for your AI tool
cd my-project
pb-spec init --ai claude       # or: copilot, opencode, gemini, codex, all
pb-spec init --ai all -g       # install globally to each agent's home/config dir

# 2. Open the project in your AI coding assistant and use the installed commands/prompts:
#    /pb-init                          → Audit repo, append/update a managed AGENTS.md snapshot block (non-destructive)
#    /pb-plan Add WebSocket auth       → Generate specs/YYYY-MM-DD-01-add-websocket-auth/
#    /pb-refine add-websocket-auth     → (Optional) Refine design based on feedback
#    /pb-build add-websocket-auth      → Implement tasks via TDD subagents
#
#    Note for Codex: prompts are loaded from .codex/prompts and typically run via /prompts:<name>.

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
Gemini CLI	.gemini/commands/pb-<name>.toml	TOML (description + prompt)
Codex	.codex/prompts/pb-<name>.md	YAML frontmatter + Markdown

CLI Reference

pb-spec init --ai <platform> [-g, --global] [--force]

Install skill files into the current project, or into global agent config directories with -g.

• --ai — Target platform: claude, copilot, opencode, gemini, codex, or all
• -g, --global — Install into each AI tool's home/config directory (instead of current project)
• --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 — AGENTS.md Snapshot & Safe Merge

Audits your project and writes a pb-init snapshot into AGENTS.md using managed markers:

• <!-- BEGIN PB-INIT MANAGED BLOCK -->
• <!-- END PB-INIT MANAGED BLOCK -->

Merge behavior is non-destructive:

• If markers exist, only that managed block is replaced.
• If markers do not exist, the managed block is appended.
• All existing content outside the managed block is preserved verbatim.

This design avoids relying on any fixed AGENTS.md section layout and protects user-maintained constraints across re-runs.

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

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

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

The spec directory follows the naming format YYYY-MM-DD-NO-feature-name (e.g., 2026-02-15-01-add-websocket-auth). The feature-name part must be unique across all specs. During planning, AGENTS.md is treated as read-only policy context (free-form, no fixed layout assumptions).

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. AGENTS.md remains read-only in this phase.

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

Reads specs/<YYYY-MM-DD-NO-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. Only the <feature-name> part is needed when invoking — the agent resolves the full directory automatically. AGENTS.md is read-only unless the user explicitly requests an AGENTS.md change.

Skills Overview

Skill	Trigger	Output	Description
pb-init	/pb-init	AGENTS.md	Audit repo and safely update/append a managed snapshot block without rewriting user-authored constraints
pb-plan	/pb-plan <requirement>	specs/<YYYY-MM-DD-NO-feature-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

Design Philosophy: Agent Harness

pb-spec's prompt design is inspired by Anthropic's research on Effective Harnesses for Long-Running Agents. The core idea: place AI agents inside a strict, observable, recoverable execution environment — a "harness" — rather than relying on the agent's autonomous judgment alone.

Key Harness Principles

Principle	How pb-spec Implements It
State Grounding	Subagents must verify workspace state (ls, find, read_file) before writing any code — preventing path hallucination
Error Quoting	Subagents must quote specific error messages before attempting fixes — preventing blind debugging
Context Hygiene	Orchestrator passes only minimal, relevant context to each subagent — preventing context window pollution
Recovery Loop	Failed tasks use pre-task snapshots + file-scoped recovery (git restore + task-local cleanup), and avoid workspace-wide restore in dirty trees
Verification Harness	Design docs define explicit verification commands at planning time — subagents execute, not invent, verification
Agent Rules	AGENTS.md is treated as free-form policy context: pb-init manages only its marker block; pb-plan/pb-refine/pb-build read it without rewriting

Where Each Principle Lives

• Worker (Implementer): implementer_prompt.md enforces grounding-first workflow and error quoting
• Architect (Planner): design_template.md includes Critical Path Verification table
• Orchestrator (Builder): pb-build SKILL enforces context hygiene and task-local recovery with safe rollback rules
• Foundation (Init): pb-init updates only the managed marker block in AGENTS.md, preserving all external user-authored constraints

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