pd

name	pd
description	Bomb-proof development pipeline: brainstorm → spec → plan → code → test → review. Master orchestrator for software projects.
version	1.1.0
license	MIT
metadata	{"hermes":{"tags":["project-development","pipeline","orchestration","bomb-proof","workflow"],"related_skills":["writing-plans","test-driven-development","requesting-code-review","subagent-driven-development","debugging-discipline","spike"]}}
argument-hint	What feature or project needs the full pipeline?

Project Development (PD) — Bomb-Proof Pipeline

Leading word: bomb-proof — same as writing-plans. A plan so thorough no implementer has to guess. Phases gate on completion criteria; each phase proves readiness for the next.

Overview

PD is the master orchestrator for software development. It guides you through a complete pipeline from idea to code review, ensuring quality at every step.

Inspired by: brainstorming, planning, verification patterns + Context Rot, Wave-Based Execution, STATE.md persistence Adapted for: Hermes Agent + OpenCode + Claude Code

Multi-platform reference: See references/multi-platform-skill-development.md for sync scripts, attribution patterns, and repo structure.

CLI tool reference: See references/cli-tool-architecture.md for CLI commands, config, hooks, and testing patterns.

🚨 BLOCKER — DO NOT CODE FIRST

Before writing ANY code, you MUST complete:

1. Brainstorming (understand the problem)
2. Planning (define the approach)
3. Create .spec/ structure

There are NO exceptions. Even "simple" tasks need a brief design.

CLI Commands

The PD CLI manages state and validates progress. Use it to track your workflow:

# Initialize a new feature
pd init <feature-name>

# Check current status
pd status

# Validate progress
pd validate
pd validate --deep    # Content validation (checks SPEC/PLAN/VERIFICATION)

# Create checkpoint
pd checkpoint --note "Completed Phase 2"

# Verify before completing
pd verify

# Advance to next phase
pd advance
pd advance --dry-run   # Preview without changing state
pd advance --force     # Skip validation

# Mark task as complete
pd complete-task "Implemented user model"

# List all features
pd list

# Delete/archive a feature
pd delete <feature-name> --archive

# Show checkpoint timeline
pd history

# Generate progress report
pd report

# Show changes since last checkpoint
pd diff

# Generate shell completions
pd completion bash   # or zsh, fish

Global Flags

-f, --feature    # Target specific feature (default: most recent)
--json           # JSON output for all commands
--dry-run        # Preview without changing state
--force          # Skip confirmations and validation
--no-color       # Disable colored output

State is persisted in .spec/<feature>/STATE.json + STATE.md — the CLI reads and updates both files.

The Prime Directive

NO SPECIFICATION + PLAN, NO CODE

If you haven't completed brainstorming and planning, you cannot write code.

When NOT to Use (Skip the pipeline if:)

Task fits in one short prompt, completed in one turn without clarification. Variable rename, typo fix, missing import, simple bug with obvious cause.

Rule of thumb: Needs research? Files you haven't read? Decisions unsettled? Use the pipeline. Otherwise, skip.

When to Use

• Starting a new project or feature
• User says: "quero criar", "vamos implementar", "nova feature"
• Coding task needing planning before implementation
• Multi-file features, cross-cutting refactors, work spanning hours/sessions

Context Rot

Problem: As the context window fills, quality degrades silently. The model starts contradicting earlier decisions, code style drifts, plans ignore requirements.

Why it happens: Transformer attention weights relevance across a finite window. As noise accumulates, signal-to-noise degrades.

Symptoms:

• Model contradicts earlier decisions
• Code style drifts from conventions
• Plans ignore clearly stated requirements
• Hallucinated file names or function signatures

Solution: Fresh-context subagents for heavy work.

Context Rules

Task Size	Context Strategy
<5 tasks	Sequential in main context
5-10 tasks	Parallel subagents, fresh context each
>10 tasks	Wave-based execution (see below)
Cross-session	STATE.md persists context

The Orchestrator Principle

The main session (orchestrator) should:

• Never touch source files directly — delegate to subagents
• Stay lean — only spawn agents, collect results, update state
• Grow slowly — context window should be predictable

Each subagent should:

• Start fresh — clean context window
• Receive exactly what it needs — project summary, phase context, specific task
• Terminate when done — report results back to orchestrator

Wave-Based Execution

For complex features with >10 tasks, organize into waves:

Wave Structure

Wave 1 (Foundation):
├── Task 1: Setup infrastructure
├── Task 2: Create models
└── Task 3: Define interfaces

Wave 2 (Core - parallel):
├── Task 4: Backend endpoint A (depends: Wave 1)
├── Task 5: Backend endpoint B (depends: Wave 1)
└── Task 6: Frontend component (depends: Wave 1)

Wave 3 (Integration - parallel):
├── Task 7: Integration tests (depends: Wave 2)
└── Task 8: API tests (depends: Wave 2)

Wave 4 (Verification):
└── Task 9: Full verification (depends: Wave 3)

Wave Rules

1. Tasks in same wave — must be independent (non-overlapping file paths)
2. Waves execute sequentially — Wave 2 starts after Wave 1 completes
3. Parallel within wave — use delegate_task for tasks in same wave
4. Fresh context each — each subagent gets clean context

Multi-Agent Orchestration Patterns

Agent Roles

Role	Purpose	When to Use
Orchestrator	Coordinates agents, manages state	Main session
Worker	Executes specific tasks	Parallel execution
Reviewer	Validates work	Quality checks
Specialist	Domain expertise	Complex problems

Agent Collaboration Patterns

Pattern 1: Supervisor-Worker

Orchestrator
├── Worker A (task 1)
├── Worker B (task 2)
└── Worker C (task 3)

Use when: Tasks are independent, can run in parallel.

# Supervisor-worker pattern
delegate_task(
    tasks=[
        {"goal": "Implement auth module", "toolsets": ["terminal", "file"]},
        {"goal": "Implement API routes", "toolsets": ["terminal", "file"]},
        {"goal": "Write tests", "toolsets": ["terminal", "file"]}
    ]
)

Pattern 2: Pipeline

Agent A ──► Agent B ──► Agent C ──► Result

Use when: Output of one agent feeds into next.

# Pipeline pattern
result_a = delegate_task("Research requirements")
result_b = delegate_task(f"Design based on: {result_a}")
result_c = delegate_task(f"Implement based on: {result_b}")

Pattern 3: Review Loop

Worker ──► Reviewer ──► Fix ──► Reviewer ──► Done

Use when: Quality is critical, need validation.

# Review loop pattern
work = delegate_task("Implement feature")
review = delegate_task(f"Review this code:\n{work}")

if review.contains_issues:
    fixes = delegate_task(f"Fix issues:\n{review.issues}")
    final_review = delegate_task(f"Verify fixes:\n{fixes}")

Pattern 4: Swarm (Specialist)

Orchestrator
├── Python Expert
├── TypeScript Expert
└── DevOps Expert

Use when: Different domains need specialized knowledge.

# Swarm pattern
delegate_task(
    tasks=[
        {"goal": "Optimize Python backend", "toolsets": ["terminal", "file"]},
        {"goal": "Refactor React components", "toolsets": ["terminal", "file"]},
        {"goal": "Setup CI/CD pipeline", "toolsets": ["terminal", "file"]}
    ],
    role="orchestrator"
)

Agent Policies

Control what agents can do:

# Agent policy examples
policies:
  # Safety
  approve_shell:
    type: function
    handler: ask_before_shell_commands
  
  # Cost control
  budget:
    type: function
    handler: max_cost_usd
    params:
      limit: 5.00
  
  # Tool limits
  tool_calls:
    type: function
    handler: max_tool_calls
    params:
      limit: 50

Agent Communication

Via Context Passing

# Pass context between agents
agent_a_result = delegate_task("Analyze codebase")
agent_b_result = delegate_task(
    f"Based on this analysis:\n{agent_a_result}\n\nImplement improvements"
)

Via Shared State Files

# Agents read/write to shared files
delegate_task("Write analysis to /tmp/analysis.md")
delegate_task("Read /tmp/analysis.md and implement recommendations")

Agent Quality Gates

Before claiming completion, agents must verify:

# Quality gate checklist
quality_checklist = """
- [ ] Code compiles/runs
- [ ] Tests pass
- [ ] No lint errors
- [ ] Follows style guide
- [ ] Meets requirements
"""

Anti-Patterns in Multi-Agent

Pattern	Problem
Too many agents	Coordination overhead
No clear roles	Confusion, duplication
Blocking dependencies	Sequential bottleneck
No quality gates	Low-quality output
Ignoring cost	Budget overruns

Parallel Execution with delegate_task

# Example: Wave 2 (Backend + Frontend in parallel)
delegate_task(
    tasks=[
        {
            "goal": "Implement backend endpoint A",
            "context": "Load clean-code skill. Follow .spec/01-feature/backend/task-04.md. Fresh context: read SPEC.md, PLAN.md, models from Wave 1.",
            "toolsets": ["terminal", "file"]
        },
        {
            "goal": "Implement backend endpoint B", 
            "context": "Load clean-code skill. Follow .spec/01-feature/backend/task-05.md. Fresh context: read SPEC.md, PLAN.md, models from Wave 1.",
            "toolsets": ["terminal", "file"]
        },
        {
            "goal": "Implement frontend component",
            "context": "Load clean-code skill. Follow .spec/01-feature/frontend/task-06.md. Fresh context: read SPEC.md, PLAN.md, interfaces from Wave 1.",
            "toolsets": ["terminal", "file"]
        }
    ]
)

Rationalization Detection

These thoughts mean STOP — you're rationalizing:

Thought	Reality
"This is just a simple question"	Questions are tasks. Check for skills.
"I need more context first"	Skill check comes BEFORE clarifying questions.
"Let me explore the codebase first"	Skills tell you HOW to explore. Check first.
"I can check git/files quickly"	Files lack conversation context. Check for skills.
"Let me gather information first"	Skills tell you HOW to gather information.
"This doesn't need a formal skill"	If a skill exists, use it.
"I remember this skill"	Skills evolve. Read current version.
"This doesn't count as a task"	Action = task. Check for skills.
"The skill is overkill"	Simple things become complex. Use it.
"I'll just do this one thing first"	Check BEFORE doing anything.
"This feels productive"	Undisciplined action wastes time. Skills prevent this.
"I know what that means"	Knowing the concept ≠ using the skill. Invoke it.

Skill Priority

When multiple skills could apply, use this order:

1. Process skills first (pd, brainstorming, debugging) — determine HOW to approach
2. Implementation skills second (clean-code, ddd-development) — guide execution

Examples:

• "Let's build X" → PD first, then clean-code + ddd-development
• "Fix this bug" → systematic-debugging first, then pd if needed
• "Write tests" → test-driven-development first

Skill Types

Type	Examples	Behavior
Rigid	TDD, debugging, verification	Follow exactly. Don't adapt away discipline.
Flexible	clean-code, ddd-development	Adapt principles to context.

The skill itself tells you which.

---

Phase 0: Worktree (Optional but Recommended)

Goal: Isolate feature work in a git worktree to avoid conflicts.

When to Use

• Feature will take >30 min
• Multiple features in parallel
• Risky changes that might break main

Worktree Setup

# Create worktree for feature
git worktree add ../feature-name feature/01-user-auth

# Work in isolated directory
cd ../feature-name

# When done, merge and cleanup
git checkout main
git merge feature/01-user-auth
git worktree remove ../feature-name

Worktree Rules

1. One worktree per feature — don't mix features
2. Branch naming: feature/XX-name
3. Commit frequently — keep worktree up to date
4. Merge when done — cleanup worktrees after merge

---

Pipeline Phases

┌─────────────────────────────────────────────────────────────┐
│  PHASE 0: WORKTREE (opcional)                               │
│  Output: git worktree isolado para a feature                │
├─────────────────────────────────────────────────────────────┤
│  PHASE 1: BRAINSTORMING                                     │
│  Output: .spec/XX-feature/SPEC.md                           │
├─────────────────────────────────────────────────────────────┤
│  PHASE 2: PLANNING                                          │
│  Output: .spec/XX-feature/PLAN.md                           │
├─────────────────────────────────────────────────────────────┤
│  PHASE 3: STRUCTURE                                         │
│  Output: .spec/XX-feature/{backend,frontend,tests}/         │
├─────────────────────────────────────────────────────────────┤
│  PHASE 4: CODING (paralelo ou sequencial)                   │
│  Output: Implementation following PLAN.md                   │
├─────────────────────────────────────────────────────────────┤
│  PHASE 5: TESTING                                           │
│  Output: Tests in .spec/XX-feature/tests/                   │
├─────────────────────────────────────────────────────────────┤
│  PHASE 6: REVIEW                                            │
│  Output: .spec/XX-feature/CHECKPOINT.md                     │
├─────────────────────────────────────────────────────────────┤
│  PHASE 7: MERGE (cleanup do worktree)                       │
│  Output: Feature merged, worktree removido                  │
└─────────────────────────────────────────────────────────────┘

---

Phase 1: Brainstorming

Goal: Understand the problem, explore approaches, get user approval.

Checklist

1. Explore project context — check existing code, docs, recent commits
2. Ask clarifying questions — one at a time, understand purpose/constraints
3. Propose 2-3 approaches — with trade-offs and recommendation
4. Present design — get user approval
5. Write SPEC.md — save to .spec/XX-feature/SPEC.md
6. User reviews spec — confirm before proceeding

SPEC.md Template

# [Feature Name] — Specification

**Date:** YYYY-MM-DD
**Status:** `draft` | `approved` | `implemented`

## Problem Statement
[What problem does this solve?]

## Requirements
- [ ] Requirement 1
- [ ] Requirement 2

## Proposed Approaches

### Approach A: [Name]
- Pros: ...
- Cons: ...

### Approach B: [Name]
- Pros: ...
- Cons: ...

## Recommended Approach
[Which one and why]

## Success Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Constraints
- Technical constraints
- Business constraints
- Timeline constraints

---

Phase 2: Planning

Goal: Break the design into bite-sized tasks (2-5 min each).

Checklist

1. Map file structure — which files to create/modify
2. Define tasks — each task is one action (2-5 min)
3. Order tasks — dependencies, TDD order
4. Write PLAN.md — save to .spec/XX-feature/PLAN.md

PLAN.md Template

# [Feature Name] — Implementation Plan

**Goal:** [One sentence]
**Architecture:** [2-3 sentences]
**Tech Stack:** [Key technologies]

## File Structure

feature/ ├── backend/ │ ├── models.py │ └── endpoints.py ├── frontend/ │ └── components/ └── tests/ ├── unit/ └── integration/

## Tasks

### Backend
- [ ] 1. Create User model (models.py)
- [ ] 2. Write failing test for create_user
- [ ] 3. Implement create_user endpoint
- [ ] 4. Write failing test for validate_email
- [ ] 5. Implement email validation

### Frontend
- [ ] 6. Create LoginForm component
- [ ] 7. Write failing test for form validation
- [ ] 8. Implement form validation

### Tests
- [ ] 9. Write unit tests for model
- [ ] 10. Write integration tests for API
- [ ] 11. Ensure all tests pass

## Estimated Time
- Backend: ~30 min
- Frontend: ~20 min
- Tests: ~15 min
- Total: ~65 min

---

Phase 3: Structure

Goal: Create the .spec/ directory structure with STATE.md as the spine.

STATE.md — Project Memory

STATE.md is the navigation layer that carries context across sessions. It records exactly where the project is in the pipeline.

Every workflow reads STATE.md first, writes back when done.

Note: The CLI maintains a dual backend — STATE.json (structured, used by the CLI for reliable parsing) alongside STATE.md (human-readable). On first load of existing features, auto-migrates from STATE.md → STATE.json.

Directory Layout

.spec/
├── README.md                              # Project overview
├── STATE.md                               # Project memory (spine)
├── .templates/
│   ├── TASK.md
│   ├── CHECKPOINT.md
│   └── STATUS.md
│
├── 01-feature-name/
│   ├── SPEC.md                            # From Phase 1 (Brainstorm)
│   ├── PLAN.md                            # From Phase 2 (Planning)
│   ├── CONTEXT.md                         # Implementation decisions
│   ├── RESEARCH.md                        # Domain research (if needed)
│   ├── VERIFICATION.md                    # Verification results
│   │
│   ├── backend/
│   │   ├── README.md                      # Backend index
│   │   ├── 01-create-model.md
│   │   ├── 02-create-endpoint.md
│   │   └── STATUS.md
│   │
│   ├── frontend/
│   │   ├── README.md
│   │   ├── 01-login-form.md
│   │   └── STATUS.md
│   │
│   ├── tests/
│   │   ├── README.md
│   │   ├── 01-unit-tests.md
│   │   ├── 02-integration-tests.md
│   │   └── STATUS.md
│   │
│   └── CHECKPOINT.md

STATE.md Template

# Project State

**Last Updated:** YYYY-MM-DD HH:MM
**Current Phase:** [phase number/name]
**Status:** `planning` | `executing` | `verifying` | `complete`

## Current Milestone
[Milestone name and goal]

## Active Phase
- **Phase:** [number]
- **Goal:** [one sentence]
- **Status:** [current status]

## Progress
| Phase | Status | Plans | Tasks Done |
|-------|--------|-------|------------|
| 1. Feature A | complete | 3/3 | 12/12 |
| 2. Feature B | executing | 2/4 | 8/15 |
| 3. Feature C | pending | 0/0 | 0/0 |

## Decisions
- [Decision 1]
- [Decision 2]

## Blockers
- [Blocker 1]

## Metrics
- Total tasks: X
- Completed: Y
- Coverage: Z%

CONTEXT.md Template

# Implementation Context

**Phase:** [number]
**Date:** YYYY-MM-DD

## Decisions
- **Library:** [choice] — because [reason]
- **Pattern:** [choice] — because [reason]
- **Error handling:** [strategy]

## Constraints
- Must use [technology]
- Cannot modify [file]
- Performance target: [metric]

## Edge Cases
- [Edge case 1]: [how to handle]
- [Edge case 2]: [how to handle]

## References
- [Link to docs]
- [Link to examples]

Task File Format

# [Task Name]

**Status:** `pending` | `in_progress` | `done` | `blocked`
**Depends:** #task-anterior
**Estimated:** 2-5 min

## Objective
[What this task does]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Implementation Notes
[Details about how to implement]

---

Phase 4: Coding (Executing Plans)

Goal: Implement tasks following the PLAN.md. Can run sequentially or in parallel.

The Process

Step 1: Load and Review Plan

1. Read PLAN.md file
2. Review critically — identify any questions or concerns
3. If concerns: Raise them before starting
4. If no concerns: Create todo list and proceed

Step 2: Execute Tasks

For each task:

1. Mark as in_progress
2. Follow each step exactly (plan has bite-sized steps)
3. Run verifications as specified
4. Mark as done

Step 3: Complete Development

After all tasks complete and verified:

• Run Phase 6 (Review & Verification)
• Create CHECKPOINT.md

When to Stop and Ask for Help

STOP executing immediately when:

• Hit a blocker (missing dependency, test fails, instruction unclear)
• Plan has critical gaps preventing starting
• You don't understand an instruction
• Verification fails repeatedly

Ask for clarification rather than guessing.

When to Revisit Earlier Steps

Return to Planning when:

• Partner updates the plan based on your feedback
• Fundamental approach needs rethinking

Don't force through blockers — stop and ask.

Sequential vs Parallel

Scenario	Mode	How
Simple feature (<5 tasks)	Sequential	One task at a time
Complex feature (>5 tasks)	Parallel	delegate_task for independent tasks
Backend + Frontend independent	Parallel	Split into subagents
TDD (test first)	Sequential	Write test → implement → repeat

Parallel Execution with delegate_task

# Example: Backend + Frontend in parallel
delegate_task(
    tasks=[
        {
            "goal": "Implement backend endpoints following PLAN.md backend section",
            "context": "Load clean-code skill. Follow .spec/01-feature/backend/ tasks.",
            "toolsets": ["terminal", "file"]
        },
        {
            "goal": "Implement frontend components following PLAN.md frontend section", 
            "context": "Load clean-code skill. Follow .spec/01-feature/frontend/ tasks.",
            "toolsets": ["terminal", "file"]
        }
    ]
)

Parallel Rules

1. Independent tasks only — don't parallelize tasks with dependencies
2. Separate file paths — backend/ and frontend/ can be parallel
3. Tests always last — after implementation is complete
4. Review is sequential — one review at a time

Coding Checklist

• Load clean-code skill
• Load ddd-development skill (if modeling domain)
• Review PLAN.md critically before starting
• Follow task order from PLAN.md
• Update task status in .spec/
• Run verifications after each task
• Commit after each task or logical unit
• Stop and ask if blocked (don't guess)

---

Phase 5: Testing & Debugging

Goal: Write tests using TDD, debug systematically when failures occur.

TDD Rules

1. Load test-driven-development skill — follow RED-GREEN-REFACTOR
2. Write tests in .spec/XX-feature/tests/
3. Track test status

Bug-Driven Coverage (from ai-regression-testing)

Don't aim for 100% coverage. Test where bugs were found:

Bug in /api/users/profile  → Write test for profile API
Bug in /api/pets           → Write test for pets API
No bug in /api/bookings    → Don't write test (yet)

AI repeats the same mistake category. Once tested, that regression cannot happen again.

Response Shape Contracts (from ai-regression-testing)

Define required fields contract per endpoint. Test ALL return the fields:

// Contract: every GET /users/me MUST return these fields
const REQUIRED_FIELDS = ['id', 'name', 'email', 'avatarUrl']

describe('GET /users/me', () => {
  it('returns all required fields', async () => {
    const res = await api.get('/users/me')
    for (const field of REQUIRED_FIELDS) {
      expect(res.body).toHaveProperty(field)
    }
  })
})

Data Query Completeness (from ai-regression-testing)

Regression: AI added field to response schema but forgot to include it in the data query:

it('response includes newly added field', async () => {
  const res = await api.get('/items')
  const items = res.body

  for (const item of items) {
    expect(item).toHaveProperty('newField')  // ← often forgotten in query
  }
})

Optimistic Update Rollback (from ai-regression-testing)

// regression: optimistic update without rollback
it('restores previous state on API failure', async () => {
  const previousState = getState()

  await triggerAction('invalid-id')  // fails

  // State should be restored to previous
  expect(getState()).toEqual(previousState)
})

Key Anti-Patterns to Scan For (from ai-regression-testing)

1. State mutation before API response — setState(data) then await api.post(...). If API fails, state is wrong.
2. as any / @ts-ignore in new code — check that they're justified, not laziness.
3. SELECT * changed — if schema changed, did query update too?
4. Error handling gaps — .catch(() => {}) or missing rollback paths.

Systematic Debugging

Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Phase 1: Root Cause Investigation

BEFORE attempting ANY fix:

1. Read Error Messages Carefully

   • Don't skip past errors or warnings
   • They often contain the exact solution
   • Read stack traces completely
   • Note line numbers, file paths, error codes

2. Reproduce Consistently

   • Can you trigger it reliably?
   • What are the exact steps?
   • Does it happen every time?
   • If not reproducible → gather more data, don't guess

3. Check Recent Changes

   • What changed that could cause this?
   • Git diff, recent commits
   • New dependencies, config changes
   • Environmental differences

4. Gather Evidence in Multi-Component Systems

   For EACH component boundary:
     - Log what data enters component
     - Log what data exits component
     - Verify environment/config propagation
     - Check state at each layer
   
   Run once to gather evidence showing WHERE it breaks
   THEN analyze evidence to identify failing component
   THEN investigate that specific component
   

Phase 2: Hypothesis Formation

Based on evidence from Phase 1:

1. List possible root causes
2. Rank by likelihood
3. Design test for most likely cause

Phase 3: Fix Implementation

1. Implement minimal fix for root cause
2. Don't refactor during debugging
3. Keep changes focused

Phase 4: Verification

1. Run original failing test — must pass
2. Run full test suite — no regressions
3. Commit fix

When to Use Debugging

Use for ANY technical issue:

• Test failures
• Bugs in production
• Unexpected behavior
• Performance problems
• Build failures
• Integration issues

Use this ESPECIALLY when:

• Under time pressure (emergencies make guessing tempting)
• "Just one quick fix" seems obvious
• You've already tried multiple fixes
• Previous fix didn't work
• You don't fully understand the issue

Don't skip when:

• Issue seems simple (simple bugs have root causes too)
• You're in a hurry (rushing guarantees rework)
• Manager wants it fixed NOW (systematic is faster than thrashing)

Testing Checklist

• Load test-driven-development skill
• Write unit tests
• Write integration tests
• Define Response Shape Contracts
• Test Data Query Completeness
• Test Optimistic Update Rollback
• Scan for anti-patterns
• All tests passing
• If tests fail: Load systematic-debugging skill
• Follow Root Cause Investigation before fixing

---

Phase 6: Review & Validation

Goal: Verify what was BUILT matches what was PLANNED and DECIDED.

Evidence-Based Completion

NO COMPLETION CLAIMS WITHOUT FRESH EVIDENCE

If you haven't run the verification command in this message, you cannot claim it passes.

Validation ≠ Testing

Testing checks: "Does the code work?" Validation checks: "Did we build the right thing?"

Validation checks:

1. Requirement coverage — were all REQ-IDs addressed?
2. Decision coverage — were CONTEXT.md decisions implemented?
3. Phase goal alignment — does built = planned = decided?

Quality Gate

BEFORE claiming any status or expressing satisfaction:

1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
   - If NO: State actual status with evidence
   - If YES: State claim WITH evidence
5. ONLY THEN: Make the claim

Skip any step = lying, not verifying

Verification Checklist

• Requirement coverage — read SPEC.md, verify each requirement
• Decision coverage — read CONTEXT.md, verify each decision
• Tests passing — run test command, see output
• Linter clean — run linter, see output
• Build succeeds — run build, see output
• No regressions — git diff, verify changes
• VERIFICATION.md created — document findings

Verification Template

# Verification Report

**Phase:** [number]
**Date:** YYYY-MM-DD
**Status:** `pass` | `fail` | `partial`

## Requirement Coverage
| REQ-ID | Description | Status | Evidence |
|--------|-------------|--------|----------|
| REQ-001 | User can login | ✅ | test output |
| REQ-002 | Password validation | ✅ | test output |
| REQ-003 | OAuth support | ❌ | not implemented |

## Decision Coverage
| Decision | Implemented | Evidence |
|----------|-------------|----------|
| Use bcrypt for hashing | ✅ | lib/auth.py:45 |
| JWT expiration: 24h | ✅ | config.py:12 |

## Test Results
```bash
[command output here]

Linter Results

[command output here]

Build Results

[command output here]

Gaps Found

• Gap 1: [description]
• Gap 2: [description]

Fix Plans

• Fix plan 1: [description]

### Common Verification Failures

| Claim | Requires | Not Sufficient |
|-------|----------|----------------|
| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
| Requirements met | Line-by-line checklist | Tests passing |

### Warning Signs — Validation

- Using "should", "probably", "seems to"
- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!")
- About to commit/push/PR without verification
- Trusting agent success reports
- Relying on partial verification
- Thinking "just this once"

### Rationalization Prevention

| Excuse | Reality |
|--------|---------|
| "Should work now" | RUN the verification |
| "I'm confident" | Confidence ≠ evidence |
| "Just this once" | No exceptions |
| "Linter passed" | Linter ≠ compiler |
| "Agent said success" | Verify independently |
| "I'm tired" | Exhaustion ≠ excuse |
| "Partial check is enough" | Partial proves nothing |

### Rules

1. **Load `requesting-code-review` skill** — pre-commit verification
2. **Run ALL verification commands** — don't skip
3. **Check requirements AND decisions** — not just tests
4. **Create VERIFICATION.md** — document findings with evidence
5. **Create CHECKPOINT.md** — final summary
6. **Update STATE.md** — mark phase complete

---

## Phase 7: Merge & Cleanup

**Goal:** Merge feature branch, cleanup worktree, update docs.

### Merge Checklist

- [ ] All tests passing
- [ ] Code review approved
- [ ] No conflicts with main
- [ ] Documentation updated
- [ ] `.spec/` archived (move to `.spec/archive/`)

### Worktree Cleanup

```bash
# If using worktree
cd /main/repo
git checkout main
git merge feature/XX-name
git branch -d feature/XX-name
git worktree remove ../feature-name

Archive .spec/

# Archive completed feature
mkdir -p .spec/archive
mv .spec/01-feature-name .spec/archive/01-feature-name-$(date +%Y%m%d)

---

---

Planning Templates & References

Implementation Plan Templates

Two plan formats supported — see references/create-implementation-plan.md:

Format	When to Use	Structure
ISIS (PLAN.md + checkpoints)	Features in Hermes/ISIS ecosystem	plans/<feature>/PLAN.md
nexus-vellum (plan.md + checkpoints.md)	Projects with own plan format	plans/active/<feature>/plan.md

Bite-Sized Task Writing

Detailed guidance on task granularity (2-5 min each), plan document structure, and TDD-oriented planning — see references/writing-plans.md.

Routing to Sub-Skills

Phase	Skill to Load	When
Worktree	using-git-worktrees (if available)	Creating isolated worktree
Brainstorming	—	Start of any feature
Planning	writing-plans	Creating PLAN.md
Coding	clean-code + executing-plans	Writing code
Domain Modeling	ddd-development	Designing entities/VOs
Testing	test-driven-development	Writing tests
Debugging	systematic-debugging	Tests failing
Review	requesting-code-review	Before commit
API Design	api-design	Designing endpoints, REST patterns
Database	database-patterns	Migrations, indexing, queries
Security	security-checklist	Auth, OWASP, secrets
Monitoring	monitoring-observability	Logging, metrics, alerts
Deployment	deployment-patterns	CI/CD, feature flags
Performance	performance-patterns	Caching, profiling
Documentation	documentation-patterns	READMEs, ADRs, API docs
Recipes	recipes	Step-by-step combining skills
Parallel	delegate_task	Backend + Frontend simultaneously

---

Example: Full Pipeline

User: "Quero criar um sistema de login"

PD Phase 1 (Brainstorming):
  → Pergunta: "Email/senha? OAuth? MFA?"
  → Propõe 2 abordagens
  → Usuário aprova
  → Salva .spec/01-login/SPEC.md

PD Phase 2 (Planning):
  → Quebra em tasks de 2-5 min
  → Salva .spec/01-login/PLAN.md

PD Phase 3 (Structure):
  → Cria .spec/01-login/{backend,frontend,tests}/

PD Phase 4 (Coding):
  → Carrega clean-code
  → Implementa tasks
  → Atualiza status

PD Phase 5 (Testing):
  → Carrega test-driven-development
  → Escreve testes
  → Debuga se necessário

PD Phase 6 (Review):
  → Carrega requesting-code-review
  → Cria CHECKPOINT.md
  → Commit

---

Common Pitfalls

1. Skipping brainstorming. Even "simple" tasks need design. The spec can be short, but it MUST exist.

2. Tasks too large. Each task should be 2-5 minutes. If it's bigger, split it.

3. Not updating status. Keep .spec/ in sync with reality.

4. Forgetting to commit. Commit after each task or logical unit.

5. Mixing phases. Don't code before planning is complete.

6. STATE.md format mismatch. The parser must handle both ## Phase: 1 and ## Phase\\n1 formats. Always verify STATE.md is readable after generation. See references/cli-tool-architecture.md for details.

7. CI validation requires "When to Use" on ALL skills. When building or modifying skills, every SKILL.md MUST have a ## When to Use section. CI validation will fail without it. Check all skills before pushing: grep -L "When to Use" skills/*/SKILL.md.

8. argparse global flags don't inherit to subparsers. When building Python CLIs with argparse, flags defined on the main parser are NOT available in subcommand parsers. Use parents=[global_parent] when creating subparsers:

   global_parent = argparse.ArgumentParser(add_help=False)
   global_parent.add_argument("--json", action="store_true")
   parser = argparse.ArgumentParser(parents=[global_parent])
   subparsers = parser.add_subparsers(dest="command")
   sub = subparsers.add_parser("status", parents=[global_parent])  # MUST include parent
   

   Without parents=, the subparser rejects the flag with "unrecognized arguments".

9. Subagent timeout leaves dirty state. When a subagent times out (600s default), it may have partially modified files or changed the working directory. After a timeout: (a) check which files were modified, (b) verify the working directory is valid, (c) handle remaining work manually or dispatch a new subagent. The terminal tool can break if the CWD was changed to a deleted temp directory — use execute_code with explicit os.chdir() as a workaround.

10. pytest capsys captures ALL stdout. When testing CLI output, earlier commands (init, checkpoint) print messages that mix with the command under test. For JSON output tests, use a helper that extracts the FIRST valid JSON block from captured output, not the entire string:

    def extract_json(captured_out):
        lines = captured_out.strip().split("\n")
        for i, line in enumerate(lines):
            if line.strip().startswith("{") or line.strip().startswith("["):
                return json.loads("\n".join(lines[i:]))
        return None
    

Verification Checklist

• SPEC.md exists and is approved
• PLAN.md exists with bite-sized tasks
• .spec/ structure created
• All tasks have status tracking
• Code follows clean-code principles
• Tests follow test-driven-development
• CHECKPOINT.md created
• All changes committed
• STATE.json exists and is valid