pb-spec — Plan-Build Spec

pb-spec is a set of Agent Skills Specification compliant AI Coding assistant workflow skill packages. It provides a structured process — plan → build → verify — that turns natural-language requirements into well-architected, strictly tested code via TDD + incremental mutation testing.

Design Philosophy

pb-spec implements the Plan-Build pattern: a Planner Agent generates design specs, and a Builder Agent executes code with verification. The core loop is strict TDD (Red → Green → Refactor → Mutate): type contracts and test matrices are the source of truth, and incremental mutation testing proves the tests actually kill bugs — no pseudo-green "step-matched" tests.

Core Principles

Installation

No manual file configuration needed. As long as your AI assistant supports the standard Agent Skills specification (Claude Code, Cursor, GitHub Copilot, OpenCode, etc.), you can install with one command.

Run in your project root:

# Install all pb-spec workflow skills at once
npx skills add longcipher/pb-spec

# Or install only the ones you need
npx skills add longcipher/pb-spec --skill pb-init
npx skills add longcipher/pb-spec --skill pb-plan
npx skills add longcipher/pb-spec --skill pb-build
npx skills add longcipher/pb-spec --skill pb-improve

(After installation, skills will be placed in .agents/skills/ or the compatible local directory for your environment, and automatically indexed by your AI.)

Quick Start

/pb-init            → audit project, write AGENTS.md snapshot
/pb-plan "<req>"    → generate design.md, tasks.md
/pb-build "<feat>"  → execute via Generator/Evaluator with strict TDD + mutation loops
/pb-refine "<feat>" → (optional) iterate specs on Build Blocked / DCR
/pb-improve         → audit codebase, generate prioritized specs

Skills Overview

Core SDD Workflow Skills

Review/Finalization Skills

Meta/Utility Skills

Workflow

/pb-init → /pb-plan → [/pb-refine] → /pb-build
                    ↘
                    /pb-improve → specs/ → /pb-build

Supporting skills activate automatically during the workflow:

• pb-brainstorming — before /pb-plan when requirements are unclear
• pb-code-review — review cycles around /pb-build tasks
• pb-branch-finalization — finalization after /pb-build
• pb-systematic-debugging — when tasks fail repeatedly

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: existing content outside the managed block is preserved verbatim. The snapshot includes an Architecture Decision Snapshot so later agents inherit repo-level conventions.

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

Produces a complete feature spec:

specs/<YYYY-MM-DD-NO-feature-name>/
├── design.md    # Scalable template: 5 required + 5 optional sections
└── tasks.md     # 4-field task blocks with DAG metadata

Key capabilities:

• Type-First: design.md carries a TDD & Mutation Testing Strategy section with type contracts, invariants, boundary conditions, and the TDD test matrix (unit + property tests)
• Scalable design template: 5 required sections (Summary, Approach, Architecture Decisions, TDD & Mutation Testing Strategy, Verification) + 5 optional sections
• RFC 2119 Constraints: §Architectural Constraints section with MUST/SHOULD/MAY keywords — binding for Builder
• 4-field task schema: Context:, Verification:, Status:, Test Coverage:
• DAG-Enabled Tasks: TaskID, DependsOn, Complexity metadata
• Mutation Strategy: every design defines a mutation score target (default ≥ 85%) and tooling (mutmut / cargo-mutants / stryker)

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

Reads user feedback or Design Change Requests and updates design.md and tasks.md. Maintains a revision history and cascades changes without overwriting completed work.

Validates 🛑 Build Blocked and 🔄 Design Change Request packets — each carrying 3 fields: Reason, Requested Change, Impact.

4. /pb-build <feature-name> — Generator/Evaluator Implementation

Implements tasks using a Generator/Evaluator dual-persona workflow with Wave-Based parallel execution (4 Invariants) and Escalation protocol:

Generator (subagent) → READY_FOR_EVAL → Evaluator (independent context) → PASS / FAIL
On PASS  → mark task DONE
On FAIL  → fresh Generator subagent → retry
On 2nd FAIL → Escalate to stronger model for root-cause analysis
On 3rd FAIL → DCR packet to /pb-refine

Key principles: TDD-First (Red → Green → Refactor → Mutate), RFC 2119 constraints BINDING, fresh context per subagent (Evaluator never inherits Generator context), escalation over thrashing, interactive (default) or --auto mode.

5. /pb-improve — Codebase Audit & Plan Generation

Audits any codebase and writes pb-plan-compatible specs for other agents to execute. Never modifies source code — only produces specs under specs/.

/pb-improve                        full audit → prioritized findings → specs
/pb-improve quick                  cheap pass: hotspots, top findings only
/pb-improve deep                   exhaustive: every package, every category
/pb-improve security               focused audit (also: perf, tests, bugs, ...)
/pb-improve branch                 audit only what the current branch changes
/pb-improve next                   feature suggestions — where to take the project
/pb-improve plan <description>     skip the audit, spec one thing
/pb-improve review-spec <feature>  critique and tighten an existing spec
/pb-improve reconcile              refresh the backlog: verify, unblock, retire

Strict TDD + Mutation Testing

The core loop replaces behavior-driven layers with a single, strict, typed pipeline:

specs/design.md (Type Contracts + Test Matrix) → tasks.md → /pb-build (RED → GREEN → REFACTOR → MUTATE)

The Four-Phase Loop

1. RED — Write a failing unit/integration test. For parsers and pure logic, add hypothesis property tests (randomized inputs, invariants). Verify it fails.
2. GREEN — Write the minimum implementation that makes it pass.
3. REFACTOR — Clean up; re-run the full suite.
4. MUTATE — Run incremental mutation testing on the changed files. If any mutant survives, the test suite is not strict enough — strengthen assertions (boundary checks, exact values) until all mutants on changed code are killed.

# The whole gate in one command
pb-spec verify

# Or individually
pb-spec test           # pytest, parallel (-n auto), optional --coverage
pb-spec mutate         # incremental mutation on git-changed files

CLI Commands

4-Field Task Schema

### Task 2.1: "Successful login" — User authenticates

- **TaskID:** `T1` - **DependsOn:** `None` - **Complexity:** `High`
- **Context:** Implement JWT auth guard for login endpoint. Key files: src/auth/jwt.ts, src/routes/login.ts.
- **Verification:** `pytest tests/auth/test_jwt.py -q` exits 0; `pb-spec mutate --against HEAD` score ≥ 85%.
- **Status:** 🔴 TODO
- **Test Coverage:** tests/auth/test_jwt.py::test_valid_token, tests/auth/test_jwt.py::test_expired_token

Build Blocked / DCR Packets

Both 🛑 Build Blocked and 🔄 Design Change Request packets carry 3 fields: Reason (one sentence), Requested Change (one paragraph), Impact (affected task IDs).

Escalation Protocol

Verification

just format && just lint && just type-check && just verify

Supported AI Tools

Compatible with any tool supporting the agentskills.io specification: Cursor, Claude Code, GitHub Copilot / GitHub Spark, OpenCode, Gemini CLI, Codex.

License

Apache-2.0