pb-spec (longcipher/pb-spec)

pb-spec

https://github.com/longcipher/pb-spec
Admin
pb-spec is a CLI tool that installs AI coding assistant skills into your project, providing a...

Tokens:19,704
Snippets:323
Trust Score:7.5
Update:4 weeks ago
Show doc for...
Context Summary (auto-generated)
Raw
# pb-spec

pb-spec is a Plan-Build Spec toolkit that provides AI coding assistant workflow skills compliant with the Agent Skills Specification. It enables a structured development process where natural-language requirements are transformed into well-architected, TDD/BDD-driven, tested code through a four-stage workflow: `/pb-init` (project initialization), `/pb-plan` (design and task planning), `/pb-refine` (iterative refinement), and `/pb-build` (subagent-driven implementation). The system enforces context-first design, contract-based architecture, and dual-loop verification through logging and health checks.

The pb-spec CLI tool validates plan-build workflow artifacts and enforces code quality standards at different stages of the workflow. It provides a `validate` command with three modes: `--plan` validates spec documents generated by `/pb-plan`, `--build` validates task completion after `/pb-build`, and `--task` performs code quality checks before signaling READY_FOR_EVAL. The scanner component detects TODOs, skipped tests, debug artifacts, and not-implemented code across multiple programming languages including Python, TypeScript, JavaScript, Rust, Go, Java, Ruby, and C/C++.

## Installing pb-spec Skills

Install all pb-spec workflow skills into your project for AI coding assistants.

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

# Or install only specific skills
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-refine
```

Skills are placed in `.agents/skills/` and automatically indexed by compatible AI tools (Cursor, Claude Code, GitHub Copilot, OpenCode, Gemini CLI).

## Installing pb-spec CLI

Install the Python CLI tool for validation and code quality scanning.

```bash
# Install from PyPI
pip install pb-spec

# Or using uv
uv add pb-spec

# Verify installation
pb-spec --version
```

## /pb-init - Project Initialization

Audits the current project and generates or updates `AGENTS.md` with architecture snapshot, project structure, and key files for AI coding agents.

The pb-init agent scans the project root to detect language, framework, and build tools. It generates a directory tree, identifies key files (entry points, configs, tests, CI), captures architecture decisions from existing documentation, and detects active specs. The output is written to `AGENTS.md` using managed markers that preserve user-authored content.

```bash
# In your AI assistant terminal or IDE
/pb-init
```

Example output in `AGENTS.md`:

```markdown
<!-- BEGIN PB-INIT MANAGED BLOCK -->
## pb-init Snapshot

> Auto-generated by pb-init. Last updated: 2026-04-15

### Project Overview

- **Language**: Python
- **Framework**: Click (CLI)
- **Build Tool**: uv
- **Test Command**: `uv run pytest`

### Project Structure

```text
pb-spec/
├── src/pb_spec/
│   ├── cli.py
│   ├── commands/
│   │   └── validate.py
│   └── validation/
│       └── scanner.py
├── tests/
├── features/
└── docs/
```

### Architecture Decision Snapshot

- Established Patterns: Command pattern for CLI
- Dependency Injection Boundaries: Scanner accepts target_files parameter
- Error Handling Conventions: Custom exception hierarchy (ValidationError, SpecNotFoundError)
<!-- END PB-INIT MANAGED BLOCK -->
```

## /pb-plan - Design and Task Planning

Generates complete feature design specifications from natural language requirements including `design.md`, `tasks.md`, and Gherkin scenarios.

The pb-plan agent accepts requirements in any format (rough notes, PRDs, RFC fragments) and produces a structured spec under `specs/<YYYY-MM-DD-NO-feature-name>/`. It analyzes the codebase for existing patterns, records architecture decisions, and creates an ordered task breakdown with BDD/TDD verification requirements.

```bash
# Generate a complete spec from a requirement
/pb-plan Add WebSocket authentication to the API

# The agent creates:
# specs/2026-04-15-01-add-websocket-auth/
# ├── design.md     # Architecture, API contracts, data models
# ├── tasks.md      # Ordered implementation tasks
# └── features/     # Gherkin acceptance scenarios
```

Example `tasks.md` structure:

```markdown
# Add WebSocket Auth — Tasks

### Task 1.1: Implement JWT token validation

Context: Add JWT validation middleware for WebSocket connections.
Verification: Run `uv run pytest tests/test_ws_auth.py`.
Scenario Coverage: features/ws-auth.feature — "Valid JWT token connects"
Loop Type: BDD+TDD
Behavioral Contract: Preserve existing HTTP auth behavior.
Simplification Focus: Reuse existing JWT validation logic.
BDD Verification: `uv run behave features/ws-auth.feature`
Advanced Test Verification: N/A — no property tests needed.
Runtime Verification: Check server logs for auth events.
Status: 🔴 TODO
- [ ] Step 1: Write failing BDD scenario
- [ ] Step 2: Write failing unit test
- [ ] Step 3: Implement JWT validation
- [ ] Step 4: Verify all tests pass
```

## /pb-build - Subagent-Driven Implementation

Executes spec-driven implementation using Generator/Evaluator dual-agent loop with BDD+TDD double-loop verification.

The pb-build agent reads `tasks.md`, implements each task sequentially by spawning fresh subagents (Generator persona), and validates work through independent evaluation (Evaluator persona). Tasks are marked done only after the Evaluator outputs PASS. On failure, the system retries up to 3 times before escalating with a Design Change Request.

```bash
# Start implementation from the feature spec
/pb-build add-websocket-auth

# The agent will:
# 1. Resolve specs/2026-04-15-01-add-websocket-auth/
# 2. Validate spec contract (design.md, tasks.md, features/)
# 3. Execute tasks sequentially with TDD loop
# 4. Update tasks.md status after Evaluator PASS
```

Example build output:

```text
[1/4] 🔄 Task 1.1: Implement JWT token validation — in progress...
      BDD OUTER RED: Scenario "Valid JWT token connects" failing
      RED: test_jwt_validation failing
      GREEN: Implementation complete
      BDD OUTER GREEN: Scenario passing
      READY_FOR_EVAL: Task 1.1
      ✅ EVALUATION PASS — Task 1.1
[2/4] 🔄 Task 1.2: Add WebSocket handshake handler — in progress...

📊 pb-build Summary: specs/2026-04-15-01-add-websocket-auth/
Tasks: 4/4 completed | 0 skipped | 0 failed
Files changed:
  - src/ws/auth.py
  - tests/test_ws_auth.py
```

## /pb-refine - Design Iteration

Iteratively refines feature design specs based on user feedback or Design Change Requests from failed builds.

The pb-refine agent reads existing specs and user feedback, then updates `design.md`, `tasks.md`, and feature files with precise edits. It handles standardized build-block packets and DCR packets, preserving completed work while cascading changes through the spec artifacts.

```bash
# Refine based on feedback
/pb-refine add-websocket-auth

# With a Design Change Request from failed build:
# 🔄 Design Change Request — Task 1.1: Implement JWT validation
# Problem: JWT library doesn't support WebSocket context
# Suggested Change: Use custom token extraction from query params
```

Example refinement output:

```text
🔄 Spec refined: specs/2026-04-15-01-add-websocket-auth/

Changes to design.md:
  - Section 4.2: Updated token extraction approach

Changes to tasks.md:
  - Modified: Task 1.1 — Added query param extraction step
  - Reset: Task 1.1 Status from 🔄 DCR to 🔴 TODO

Next steps:
  - Review the updated spec.
  - Run /pb-build add-websocket-auth to continue implementation.
```

## pb-spec validate --plan

Validates spec documents after `/pb-plan` to ensure they meet the contract requirements.

This mode checks that `design.md` contains required sections (full mode: Executive Summary, Requirements & Goals, Architecture Overview, Detailed Design, Verification & Testing Strategy, Implementation Plan; lightweight mode: Architecture Decisions, BDD/TDD Strategy, Verification), validates `tasks.md` task block structure and required fields, and verifies the presence of feature files.

```bash
# Validate spec documents after planning
pb-spec validate --plan

# With custom specs directory
pb-spec validate --plan --specs-dir ./my-specs
```

```python
from pb_spec.commands.validate import validate_plan, get_latest_spec_dir
from pathlib import Path

# Programmatic validation
specs_dir = Path("specs")
latest_spec = get_latest_spec_dir(specs_dir)
result = validate_plan(latest_spec)

if result.is_valid:
    print("Spec validation passed")
else:
    for error in result.errors:
        print(f"Error: {error}")
# Output:
# ✅ design.md (lightweight mode) structural checks passed.
# ✅ tasks.md structural checks passed.
# ✅ Found Gherkin .feature files.
# 🎉 All validations passed successfully!
```

## pb-spec validate --build

Validates task completion after `/pb-build` to ensure all tasks are properly done.

This mode verifies that all tasks have status `🟢 DONE`, all step checkboxes are checked (`- [x]`), and performs a deep codebase scan for mocks, TODOs, skipped tests, and debug artifacts. Skipped (`⏭️ SKIPPED`) and obsolete (`⛔ OBSOLETE`) tasks are allowed but warned.

```bash
# Validate build completion
pb-spec validate --build

# Expected output for successful build:
# ✅ All targeted tasks in tasks.md are properly marked as DONE.
# ✅ Codebase scan passed - no issues found.
# 🎉 All validations passed successfully!
```

```python
from pb_spec.commands.validate import validate_build
from pathlib import Path

spec_dir = Path("specs/2026-04-15-01-add-websocket-auth")
result = validate_build(spec_dir)

if not result.is_valid:
    for error in result.errors:
        print(f"Build validation failed: {error}")
# Output examples:
# ❌ Task Unfinished: 1.2: Add WebSocket handler is not marked as DONE.
# ❌ Task '1.1: Implement JWT validation' is marked DONE but has incomplete steps:
#   - [ ] Step 4: Verify all tests pass
```

## pb-spec validate --task

Subagent self-check before signaling READY_FOR_EVAL to ensure code quality.

This mode scans git-modified files (or full codebase in build mode) for code quality issues: TODO/FIXME comments, skipped tests (@pytest.mark.skip, #[ignore], t.Skip()), debug artifacts (console.log, pdb.set_trace, breakpoint()), and NotImplementedError raises. It respects .gitignore and excludes validation infrastructure files.

```bash
# Run subagent self-check
pb-spec validate --task

# Expected output for clean code:
# ℹ️  Running Subagent Task Self-Check (Pre-Eval Validation)...
# ℹ️  Task mode: scanning only 3 git-modified file(s).
# ✅ Codebase scan passed - no issues found.
# ✅ Subagent self-check passed! Code is clean of mocks, skipped tests, and debug artifacts.
# ℹ️  You may now signal READY_FOR_EVAL.
```

```python
from pb_spec.commands.validate import validate_task

# Programmatic task validation
passed = validate_task()

if not passed:
    print("Fix issues before signaling READY_FOR_EVAL")
# Output for issues found:
# ❌ Found 2 TODO/FIXME(s):
#   src/auth.py:42 -> # TODO: Add rate limiting
#   src/ws/handler.py:15 -> # FIXME: Handle reconnection
# ❌ Found 1 skipped test(s):
#   tests/test_auth.py:28 -> @pytest.mark.skip(reason="WIP")
```

## CodeScanner API

Scans codebase for code quality issues including TODOs, skipped tests, debug artifacts, and not-implemented code.

The CodeScanner class provides configurable scanning with support for git-aware file discovery, custom exclusion directories, and targeted file scanning. It returns structured results with issues categorized by type and including file path, line number, and content.

```python
from pb_spec.validation import CodeScanner, IssueType
from pathlib import Path

# Basic scan of current directory
scanner = CodeScanner(root_dir=".")
result = scanner.scan()

if result.has_issues:
    # Get issues by type
    todos = result.issues_by_type(IssueType.TODO)
    for issue in todos:
        print(f"{issue.file_path}:{issue.line_number} - {issue.line_content}")

    skipped = result.issues_by_type(IssueType.SKIPPED_TEST)
    debug = result.issues_by_type(IssueType.DEBUG_ARTIFACT)
    not_impl = result.issues_by_type(IssueType.NOT_IMPLEMENTED)

# Targeted scan of specific files (for --task mode)
modified_files = {Path("src/new_feature.py"), Path("tests/test_new.py")}
scanner = CodeScanner(
    root_dir=".",
    target_files=modified_files,
    check_skipped_tests=True,
    check_not_implemented=True,
    check_todos=True,
    check_debug_artifacts=True,
)
result = scanner.scan()

# Custom configuration
scanner = CodeScanner(
    root_dir="/path/to/project",
    exclude_dirs=frozenset({".git", "node_modules", "vendor"}),
    scan_extensions=frozenset({".py", ".ts", ".go"}),
    check_todos=False,  # Disable TODO detection
)
```

## ValidationResult and Error Handling

Structured validation results and custom exceptions for handling validation failures.

The validation system uses `ValidationResult` dataclass for structured results containing validity status, errors, and warnings. Custom exceptions (`ValidationError`, `SpecNotFoundError`, `FileReadError`, `ContractViolationError`) provide specific error handling for different failure modes.

```python
from pb_spec.commands.validate import (
    ValidationResult,
    ValidationError,
    SpecNotFoundError,
    FileReadError,
    ContractViolationError,
    combine_validation_results,
    get_latest_spec_dir,
)
from pathlib import Path

# Combining multiple validation results
result1 = ValidationResult(is_valid=True, warnings=["Minor issue"])
result2 = ValidationResult(is_valid=False, errors=["Missing section"])
combined = combine_validation_results(result1, result2)
print(f"Combined valid: {combined.is_valid}")  # False
print(f"Errors: {combined.errors}")  # ['Missing section']
print(f"Warnings: {combined.warnings}")  # ['Minor issue']

# Error handling
try:
    spec_dir = get_latest_spec_dir(Path("specs"))
except SpecNotFoundError as e:
    print(f"No specs found: {e}")
    # "Directory 'specs/' not found. Run /pb-plan first."

# Custom validation logic
def validate_custom_spec(spec_dir: Path) -> ValidationResult:
    errors = []
    warnings = []

    design_file = spec_dir / "design.md"
    if not design_file.exists():
        errors.append("Missing design.md")

    tasks_file = spec_dir / "tasks.md"
    if tasks_file.exists():
        content = tasks_file.read_text()
        if "🔴 TODO" in content:
            warnings.append("Incomplete tasks found")

    return ValidationResult(
        is_valid=len(errors) == 0,
        errors=errors,
        warnings=warnings,
    )
```

## Running Tests and Quality Checks

Commands for running the pb-spec test suite and quality checks.

The project uses pytest for unit tests, behave for BDD tests, ruff for linting, and ty for type checking. The Justfile provides convenient commands for common development tasks.

```bash
# Run unit tests
uv run pytest -q

# Run BDD tests
uv run behave features/

# Run linting
uv run ruff check .

# Run type checking
uv run ty check

# Format code
uv run ruff format .

# Using Justfile commands
just test       # Run unit tests
just bdd        # Run BDD tests
just lint       # Run linting
just format     # Format code
just test-all   # Run full test suite
```

```python
# Example test using the validation API
import pytest
from pathlib import Path
from pb_spec.commands.validate import validate_plan, ValidationResult

def test_valid_spec_passes(tmp_path: Path):
    """Test that a valid spec passes validation."""
    spec_dir = tmp_path / "specs" / "2026-04-15-test-feature"
    spec_dir.mkdir(parents=True)

    # Create minimal valid design.md (lightweight mode)
    (spec_dir / "design.md").write_text(
        "## Architecture Decisions\nUse Python\n"
        "## BDD/TDD Strategy\nUse pytest\n"
        "## Verification\nRun tests\n"
    )

    # Create valid tasks.md
    (spec_dir / "tasks.md").write_text(
        "### Task 1.1: Test\n"
        "Context: Test context\n"
        "Verification: pytest\n"
        "Scenario Coverage: test.feature\n"
        "Loop Type: TDD-only\n"
        "Behavioral Contract: N/A\n"
        "Simplification Focus: N/A\n"
        "BDD Verification: N/A\n"
        "Advanced Test Verification: N/A\n"
        "Runtime Verification: N/A\n"
        "Status: 🔴 TODO\n"
        "- [ ] Step 1\n"
    )

    result = validate_plan(spec_dir)
    assert result.is_valid is True
```

pb-spec is designed for AI-assisted development workflows where structured planning precedes implementation. The primary use case is enabling AI coding assistants to generate well-architected code through a disciplined process: initialize project context with `/pb-init`, plan features with `/pb-plan`, optionally refine designs with `/pb-refine`, and implement with `/pb-build`. The validation CLI serves as a quality gate at each stage, ensuring specs meet contract requirements and code remains clean of common issues.

Integration follows the Agent Skills Specification, making pb-spec compatible with Cursor, Claude Code, GitHub Copilot, OpenCode, and other tools that support `.agents/skills/` or `agentskills.io`. For programmatic use, the Python package exposes `CodeScanner` for custom code analysis, `ValidationResult` for structured validation outcomes, and individual validation functions (`validate_plan`, `validate_build`, `validate_task`) that can be integrated into CI/CD pipelines or custom tooling. The modular design allows using just the validation CLI without the full skill workflow, or embedding specific validators into existing development processes.