pb-spec 0.1.0

Plan-Build Spec (pb-spec): A CLI tool for managing AI coding assistant skills

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

• 3 agent skills: pb-init, pb-plan, pb-build — covering project analysis, design planning, 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-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

pb-spec provides three agent skills that chain together:

/pb-init → /pb-plan → /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 so that subsequent agents have full project context.

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 with acceptance criteria

3. /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) with self-review before completion.

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