@sienklogic/plan-build-run 2.0.0

package/plugins/pbr/references/continuation-format.md

@@ -0,0 +1,212 @@
+# Continuation Protocol
+
+How to spawn a fresh executor agent to continue from a checkpoint or partial completion.
+
+---
+
+## Why Fresh Agents
+
+When an executor hits a checkpoint, it STOPS and returns. A new, fresh agent must be spawned to continue because:
+1. The checkpoint may require user input that changes the execution path
+2. Context isolation prevents accumulated state from causing issues
+3. Fresh agents have full context budget for remaining work
+
+---
+
+## Lean Continuation State File
+
+Instead of inlining all prior context into the continuation prompt, the build skill writes a compact state file to disk. The continuation executor reads this file + the original PLAN.md, keeping the prompt lean.
+
+### File Location
+
+```
+.planning/phases/{NN}-{slug}/.continuation-state.json
+```
+
+### Schema
+
+```json
+{
+  "plan_id": "02-01",
+  "completed_tasks": [
+    {
+      "id": "02-01-T1",
+      "commit": "abc1234",
+      "files": ["src/auth/discord.ts", "src/auth/types.ts"]
+    },
+    {
+      "id": "02-01-T2",
+      "commit": "def5678",
+      "files": ["src/middleware/auth.ts"]
+    }
+  ],
+  "checkpoint": {
+    "task": "02-01-T3",
+    "type": "human-verify",
+    "resolution": "passed"
+  },
+  "resume_at": "02-01-T3"
+}
+```
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `plan_id` | string | The plan being executed |
+| `completed_tasks` | array | Tasks completed before checkpoint. Each has `id`, `commit` hash, and `files` changed. |
+| `checkpoint` | object | The checkpoint that triggered continuation. `task` = task ID, `type` = checkpoint type, `resolution` = user's response. |
+| `resume_at` | string | Task ID to resume execution from |
+
+### How the Build Skill Uses It
+
+**Writing** (when executor hits a checkpoint):
+1. Executor returns checkpoint info to the build orchestrator
+2. Build orchestrator writes `.continuation-state.json` with completed tasks, checkpoint details, and resume point
+3. Build orchestrator prompts user for checkpoint resolution
+4. Build orchestrator updates `checkpoint.resolution` with user's response
+
+**Reading** (when spawning continuation executor):
+1. Build orchestrator reads `.continuation-state.json` from disk
+2. Build orchestrator reads the original PLAN.md from disk
+3. Build orchestrator constructs a lean continuation prompt referencing both files
+4. Continuation executor reads `.continuation-state.json` itself to verify prior commits
+
+This approach replaces inlining the full completed-tasks table into the prompt, saving significant context budget on plans with many tasks or multiple checkpoints.
+
+---
+
+## Continuation Context Structure
+
+The continuation prompt must include:
+
+### 1. Completed Tasks Table
+
+A table of all tasks completed before the checkpoint, with their commit hashes:
+
+```markdown
+| Task ID | Task Name | Commit | Files Changed | Status |
+|---------|-----------|--------|---------------|--------|
+| 02-01-T1 | Create auth module | abc1234 | src/auth/discord.ts, src/auth/types.ts | complete |
+| 02-01-T2 | Add auth middleware | def5678 | src/middleware/auth.ts | complete |
+| 02-01-T3 | Wire OAuth callback | — | — | checkpoint |
+```
+
+### 2. Resume Task Number
+
+Which task to resume from:
+- If the checkpoint task needs to be RE-EXECUTED with user input: resume at the checkpoint task
+- If the checkpoint task was completed and the next task is blocked: resume at the NEXT task
+
+### 3. User Response
+
+The user's response to the checkpoint:
+- For `decision`: which option they chose
+- For `human-verify`: whether they passed or failed each item
+- For `human-action`: confirmation that the action was taken
+
+---
+
+## Continuation Prompt Template
+
+```
+You are the executor agent. Continue executing a plan from a checkpoint.
+
+<plan>
+[Inline the FULL PLAN.md content — all tasks, not just remaining ones]
+</plan>
+
+<completed_tasks>
+The following tasks have already been completed. DO NOT re-execute them.
+Verify their commits exist before proceeding.
+
+| Task ID | Task Name | Commit | Status |
+|---------|-----------|--------|--------|
+| {id} | {name} | {hash} | complete |
+| {id} | {name} | {hash} | complete |
+| {id} | {name} | — | checkpoint |
+</completed_tasks>
+
+<checkpoint_resolution>
+Checkpoint type: {human-verify | decision | human-action | architectural-change}
+User response: {the user's response to the checkpoint}
+
+{For decision: "User chose Option {X}: {description}"}
+{For human-verify: "User confirmed: {pass/fail per item}"}
+{For human-action: "User confirms action completed: {what they did}"}
+{For architectural-change: "User approved approach: {new approach}"}
+</checkpoint_resolution>
+
+<resume_instructions>
+Resume execution at Task {N}.
+{If checkpoint task should be re-executed: "Re-execute Task {N} with the user's input."}
+{If checkpoint task is done: "Skip Task {N} and continue from Task {N+1}."}
+</resume_instructions>
+
+<project_context>
+[Same project context as original spawn — config, CONTEXT.md, STATE.md]
+</project_context>
+
+<prior_work_this_phase>
+[Include all SUMMARY.md files from other completed plans in this phase]
+</prior_work_this_phase>
+
+Instructions:
+1. Verify completed task commits exist: git log --oneline -n {count}
+2. If commits are missing, STOP and return error
+3. Resume execution at Task {N}
+4. Create atomic commits for each remaining task
+5. Write SUMMARY.md when complete (include ALL tasks — completed and newly executed)
+6. Run self-check
+```
+
+---
+
+## Verification Before Resuming
+
+The continuation agent MUST verify prior work before continuing:
+
+```bash
+# Check that expected commits exist
+git log --oneline -n {expected_commit_count}
+
+# Check that expected files exist
+ls -la {each file from completed tasks}
+```
+
+If verification fails:
+- STOP immediately
+- Report which commits/files are missing
+- DO NOT attempt to re-create them (that's the orchestrator's job)
+
+---
+
+## SUMMARY.md for Continued Plans
+
+The final SUMMARY.md must include ALL tasks — both pre-checkpoint and post-checkpoint:
+
+```markdown
+## Task Results
+
+### Task 1: {name}
+- **Commit**: `{hash}` - {message}
+- **Status**: complete (pre-checkpoint)
+
+### Task 2: {name}
+- **Commit**: `{hash}` - {message}
+- **Status**: complete (pre-checkpoint)
+
+### Task 3: {name} (checkpoint: {type})
+- **Checkpoint resolution**: {user response}
+- **Commit**: `{hash}` - {message}
+- **Status**: complete (post-checkpoint)
+```
+
+---
+
+## Multiple Checkpoints
+
+If a plan has multiple checkpoint tasks:
+- Each checkpoint requires a separate continuation agent spawn
+- The completed_tasks table grows with each continuation
+- Each continuation verifies ALL prior commits, not just the most recent

package/plugins/pbr/references/deviation-rules.md

@@ -0,0 +1,112 @@
+# Deviation Rules
+
+When execution doesn't go exactly as planned, these 5 rules govern what the executor can do on its own versus what requires user approval.
+
+---
+
+## Rule 1: Bug Discovered
+
+**Trigger**: Verify command fails due to a bug in the code just written.
+
+**Action**: Auto-fix the bug, re-run verify. If it passes, commit as normal. Note the bug and fix in SUMMARY.md under "Deviations".
+
+**Limit**: 3 fix attempts maximum. After 3 failures, STOP and return error with failing verify output.
+
+**Approval needed**: No
+
+---
+
+## Rule 2: Missing Dependency
+
+**Trigger**: Action or verify fails because a package/dependency is not installed.
+
+**Action**: Auto-install the dependency using the project's package manager. Continue execution.
+
+**Commit**: Include dependency installation in the task's commit (e.g., package.json, package-lock.json changes).
+
+**Limit**: Only install dependencies directly referenced in the plan's `<action>` or clearly required by the code being written. Do NOT install "nice-to-have" packages.
+
+**Approval needed**: No
+
+---
+
+## Rule 3: Critical Gap
+
+**Trigger**: While implementing, a critical gap is noticed that would cause runtime errors — missing error handling, null checks, input validation for security.
+
+**Action**: Add the minimal necessary code. Note it in SUMMARY.md under "Deviations".
+
+**Limit**: This is for preventing crashes and security holes ONLY. Not for adding features, improving UX, or refactoring.
+
+**Examples of valid critical gaps**:
+- Missing null check that would cause runtime crash
+- Unhandled promise rejection
+- SQL injection vulnerability
+- Missing input sanitization
+- Missing error boundary
+
+**Examples that are NOT critical gaps (use Rule 5 instead)**:
+- Better error messages
+- Input validation for UX (e.g., email format)
+- Performance optimization
+- Code organization improvements
+
+**Approval needed**: No
+
+---
+
+## Rule 4: Architectural Change
+
+**Trigger**: The plan's approach won't work as specified. The architecture needs to change. A fundamental assumption was wrong.
+
+**Action**: STOP immediately. Return a checkpoint-style response describing:
+- What the plan says to do
+- Why it won't work
+- What the alternative would be
+- Which tasks are affected
+
+**DO NOT** make architectural changes without approval. DO NOT try to "make it work" with hacks.
+
+**Examples**:
+- Plan says to use library X, but it doesn't support the required feature
+- Plan assumes a REST API, but the service only has GraphQL
+- Plan's database schema won't support the required queries
+- Plan's authentication approach conflicts with the framework
+
+**Approval needed**: YES — full stop, present to user
+
+---
+
+## Rule 5: Scope Creep
+
+**Trigger**: While implementing, something is noticed that would be nice to have, could be improved, or is related but not in the plan.
+
+**Action**: Log it in SUMMARY.md under "Deferred Ideas". DO NOT implement it. Continue with the plan as written.
+
+**Examples**:
+- "This could use caching" -> Deferred
+- "The error messages could be better" -> Deferred
+- "This should have pagination" -> Deferred
+- "The existing code has a bug unrelated to this plan" -> Deferred (unless it blocks the plan)
+- "This API should have rate limiting" -> Deferred
+- "The UI could use loading states" -> Deferred
+
+**Approval needed**: No (just log and continue)
+
+---
+
+## Decision Tree
+
+```
+Execution deviates from plan
+  |
+  ├─ Code bug? ──────────────── Rule 1: Auto-fix (3 attempts)
+  |
+  ├─ Missing package? ──────── Rule 2: Auto-install
+  |
+  ├─ Security/crash risk? ──── Rule 3: Minimal fix + note
+  |
+  ├─ Architecture wrong? ───── Rule 4: STOP + checkpoint
+  |
+  └─ Nice to have? ─────────── Rule 5: Log + continue
+```

package/plugins/pbr/references/git-integration.md

@@ -0,0 +1,226 @@
+# Git Integration Reference
+
+Plan-Build-Run's commit conventions, commit points, branching strategy, and hook scripts.
+
+---
+
+## Commit Message Format
+
+```
+{type}({phase}-{plan}): {description}
+```
+
+### Components
+
+| Part | Description | Example |
+|------|-------------|---------|
+| `{type}` | Conventional commit type | `feat`, `fix`, `test` |
+| `{phase}` | Phase number (zero-padded) | `02` |
+| `{plan}` | Plan number | `01` |
+| `{description}` | Imperative, lowercase description | `implement discord oauth client` |
+
+The format is configurable via `config.json` at `git.commit_format`. The default is `{type}({phase}-{plan}): {description}`.
+
+### Full Example
+```
+feat(02-01): implement discord oauth client
+```
+
+---
+
+## Commit Types
+
+| Type | When to Use | Example |
+|------|------------|---------|
+| `feat` | New feature or functionality | `feat(02-01): implement discord oauth client` |
+| `fix` | Bug fix (including during execution) | `fix(02-01): handle null user profile from discord api` |
+| `refactor` | Code restructuring, no behavior change | `refactor(02-01): extract token validation into helper` |
+| `test` | Adding or modifying tests | `test(02-01): add failing tests for discord oauth flow` |
+| `docs` | Documentation changes | `docs(03-02): add api endpoint documentation` |
+| `chore` | Build config, dependencies, tooling | `chore(01-01): configure typescript and eslint` |
+| `style` | Formatting, whitespace (no logic change) | `style(02-01): fix import ordering` |
+
+---
+
+## Special Commit Scopes
+
+Beyond the standard `{phase}-{plan}` scope, Plan-Build-Run recognizes these additional patterns:
+
+| Pattern | When Used | Example |
+|---------|-----------|---------|
+| `{type}(quick-{NNN})` | Quick-task commits via `/pbr:quick` | `feat(quick-001): add health endpoint` |
+| `docs(planning)` | Planning document commits | `docs(planning): add phase 3 plans` |
+| `wip: {desc}` or `wip({area}): {desc}` | Work-in-progress (use sparingly) | `wip(auth): partial oauth implementation` |
+| Merge commits | Git merge operations | `Merge branch 'plan-build-run/phase-02-auth'` |
+
+---
+
+## Commit Body (Optional)
+
+For commits that need explanation, add a body after a blank line:
+
+```
+feat(02-01): implement discord oauth client
+
+- Uses discord-oauth2 library for token exchange
+- Stores tokens in httpOnly cookies for security
+- Supports identify and email OAuth scopes
+
+Deviation: Added null check for user.email (Rule 3 -- critical gap)
+```
+
+---
+
+## Commit Points
+
+Plan-Build-Run defines strict rules about WHEN commits happen:
+
+### One Task = One Commit
+
+Each successfully completed plan task gets exactly one atomic commit. No more, no less.
+
+### TDD Tasks = Three Commits
+
+TDD tasks (`tdd="true"`) produce exactly 3 commits following Red-Green-Refactor:
+
+```
+test(02-01): RED - add failing tests for auth middleware
+feat(02-01): GREEN - implement auth middleware to pass tests
+refactor(02-01): REFACTOR - extract token verification helper
+```
+
+### Commit Preconditions
+
+A commit is created only when:
+1. All `<action>` steps in the task are complete
+2. All `<verify>` commands pass with exit code 0
+3. Only files listed in the task's `<files>` element are staged (plus deviation-required files)
+
+### Deviation Commits
+
+When an executor applies a deviation rule during a task, the deviation is included in the same task commit (not a separate commit):
+
+```
+# Rule 1 auto-fix: rolled into the task's commit
+# Rule 2 auto-install: package.json/lock added to same commit
+# Rule 3 critical gap: null check added in same commit
+```
+
+---
+
+## Atomic Commit Rules
+
+1. **One task = one commit** (TDD tasks get 3)
+2. **Commit only after verify passes** -- never commit broken code
+3. **Stage only files listed in `<files>`** plus any deviation-required files
+4. **Never use `git add .` or `git add -A`** -- stage specific files
+5. **Include all files from the task** -- do not leave modified files unstaged
+6. **Commit message must describe what was done** -- not just the task name
+7. **Use the configured commit format** -- from `config.json` `git.commit_format`
+
+---
+
+## Staging Examples
+
+```bash
+# Standard task
+git add src/auth/discord.ts src/auth/types.ts
+git commit -m "feat(02-01): implement Discord OAuth client with token exchange"
+
+# Task that also installed a dependency (Rule 2)
+git add src/auth/discord.ts src/auth/types.ts package.json package-lock.json
+git commit -m "feat(02-01): implement Discord OAuth client with token exchange"
+
+# TDD RED
+git add tests/auth/discord.test.ts
+git commit -m "test(02-01): add failing tests for Discord OAuth flow"
+```
+
+---
+
+## Git Retry Logic
+
+If `git commit` fails with a lock error (`fatal: Unable to create ... .git/index.lock`):
+1. Wait 2 seconds
+2. Retry the commit
+3. Maximum 3 attempts
+4. If still failing after 3 attempts, report the error and stop
+
+This commonly occurs when parallel executors compete for the git index lock.
+
+---
+
+## Branching Strategy
+
+Configured via `config.json` at `git.branching`:
+
+| Strategy | Behavior |
+|----------|----------|
+| `none` | All commits go directly to the current branch (default) |
+| `phase` | Each phase gets its own branch: `plan-build-run/phase-{NN}-{slug}`. Squash-merged to main on completion. |
+| `milestone` | Each milestone gets a branch: `plan-build-run/{milestone}-{slug}`. Merged on milestone completion. |
+| `disabled` | No git operations at all. No commits, no branching. Useful for prototyping or non-git projects. |
+
+### Phase Branching Flow
+
+When `git.branching` is `phase`:
+1. Build orchestrator creates branch: `git checkout -b plan-build-run/phase-{NN}-{slug}`
+2. All executor commits go to the phase branch
+3. After all plans complete and verification passes, orchestrator asks user to confirm squash merge
+4. If confirmed: `git checkout main && git merge --squash plan-build-run/phase-{NN}-{slug}`
+5. Phase branch is deleted after merge
+
+Branch name templates are configured in `config.json`:
+- `git.phase_branch_template`: Default `plan-build-run/phase-{phase}-{slug}`
+- `git.milestone_branch_template`: Default `plan-build-run/{milestone}-{slug}`
+
+### Git Mode
+
+The `git.mode` field controls whether git integration is active:
+
+| Mode | Behavior |
+|------|----------|
+| `enabled` | Normal operation -- commits, branching, hooks all active (default) |
+| `disabled` | No git commands are run. No commits, no branching. Useful for non-git projects. |
+
+---
+
+## Hook Scripts
+
+Plan-Build-Run uses Claude Code hooks (defined in `hooks/hooks.json`) to enforce conventions and track progress during execution. All hooks log via `hook-logger.js` to `.planning/.hook-log` (JSONL format, max 200 entries).
+
+### Hook Summary
+
+| Hook Event | Script | Purpose |
+|------------|--------|---------|
+| `SessionStart` | `progress-tracker.js` | Displays current project progress on session start |
+| `PostToolUse` (Write/Edit) | `check-plan-format.js` | Validates plan file YAML frontmatter after writes |
+| `PostToolUse` (Write/Edit) | `check-roadmap-sync.js` | Ensures ROADMAP.md stays in sync with phase changes |
+| `PreToolUse` (Bash) | `validate-commit.js` | Validates commit message format before `git commit` runs |
+| `PreCompact` | `context-budget-check.js` | Warns about context budget before compaction |
+| `Stop` | `auto-continue.js` | Handles auto-continuation signal when session ends |
+| `SubagentStart` | `log-subagent.js start` | Logs subagent spawn events |
+| `SubagentStop` | `log-subagent.js stop` | Logs subagent completion events |
+| `SessionEnd` | `session-cleanup.js` | Cleans up temporary state on session end |
+
+### validate-commit.js Details
+
+The commit validation hook (`PreToolUse` on Bash commands) enforces the commit format:
+- Checks that `git commit -m "..."` messages match the pattern: `{type}({scope}): {description}`
+- Valid types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `wip`
+- Allows merge commits (starting with "Merge")
+- Allows quick-task, planning, and WIP scope patterns
+- Blocks commits with sensitive file patterns (`.env`, `.key`, `.pem`, credentials) unless they match safe patterns (`.example`, `.template`, `.sample`, test directories)
+- Exit code 2 blocks the commit; exit code 0 allows it
+
+---
+
+## Planning Doc Commits
+
+When `config.json` has `planning.commit_docs: true`, the build orchestrator commits planning artifacts (SUMMARY.md, VERIFICATION.md) after all plans in a phase complete:
+
+```
+docs({phase}): add build summaries and verification
+```
+
+This keeps the planning trail in version control alongside the code it describes.

package/plugins/pbr/references/integration-patterns.md

@@ -0,0 +1,117 @@
+# Integration Patterns Reference
+
+Technology-specific grep/search patterns and E2E flow templates for integration-checker.
+
+## E2E Flow Templates
+
+### Authentication Flow
+
+| Step | Check |
+|------|-------|
+| 1. Login form exists | Component with email/password fields or OAuth button |
+| 2. Form submits to auth endpoint | onSubmit calls auth API or redirects to OAuth |
+| 3. Backend validates credentials | Route handler with validation logic |
+| 4. Token/session created | JWT generation or session creation |
+| 5. Token stored client-side | Cookie set or localStorage/state |
+| 6. Requests include auth | Auth header or cookie sent with API calls |
+| 7. Protected routes accessible | Auth middleware passes with valid token |
+| 8. Invalid auth redirects | 401 or redirect when no/invalid token |
+
+### Data Display Flow
+
+| Step | Check |
+|------|-------|
+| 1. Page/component renders | Component file with JSX/HTML |
+| 2. Component requests data | useEffect/useSWR/useQuery with API call |
+| 3. API route handles request | Route handler exists for endpoint |
+| 4. Handler queries data source | Database query or service call |
+| 5. Data returned | res.json() or return with data |
+| 6. Component renders data | Data mapped to JSX elements |
+| 7. Loading state handled | Loading indicator while fetching |
+| 8. Error state handled | Error message on failure |
+
+### Form Submission Flow
+
+| Step | Check |
+|------|-------|
+| 1. Form component exists | Form element with inputs |
+| 2. Client-side validation | Schema or manual checks |
+| 3. Submit calls API | fetch/axios with form data |
+| 4. Server validates input | Input validation in handler |
+| 5. Server processes request | Business logic (CRUD) |
+| 6. Database mutation | Write operation |
+| 7. Success response | Response with success status |
+| 8. UI reflects success | Toast/redirect/state update |
+| 9. Error handling | Server errors shown in form |
+
+### CRUD Flow (per entity)
+
+| Step | Check |
+|------|-------|
+| 1. List view | Component renders list |
+| 2. Create form | Component with creation UI |
+| 3. Create API | POST route with handler |
+| 4. Read/detail API | GET route with handler |
+| 5. Update form | Component with edit UI |
+| 6. Update API | PUT/PATCH route with handler |
+| 7. Delete action | Delete button/handler |
+| 8. Delete API | DELETE route with handler |
+| 9. Frontend calls all CRUD | All operations invoked from UI |
+| 10. Auth on all ops | All operations require auth (if applicable) |
+
+## Technology-Specific Search Patterns
+
+### React / Next.js
+
+```bash
+# Component imports and usage
+grep -rn "import.*{Component}" src/ --include="*.tsx"
+grep -rn "<{Component}" src/ --include="*.tsx"
+
+# Context providers (must wrap the app)
+grep -rn "Provider" src/app/layout.tsx src/pages/_app.tsx 2>/dev/null
+
+# Client vs Server components (Next.js)
+grep -rn "'use client'\|\"use client\"" src/ --include="*.tsx"
+
+# Next.js API routes (App Router)
+find src/app/api -name "route.ts" 2>/dev/null
+
+# Next.js middleware
+find src -name "middleware.ts" -maxdepth 2 2>/dev/null
+
+# Data fetching hooks
+grep -rn "useSWR\|useQuery\|useMutation\|getServerSideProps\|getStaticProps" src/ --include="*.tsx" --include="*.ts"
+```
+
+### Express / Node.js API
+
+```bash
+# Route registration on main app
+grep -rn "app\.use\|router\.use" src/ --include="*.ts" --include="*.js"
+
+# Middleware chain order (important for auth)
+grep -rn "\.use(" src/app.ts src/server.ts src/index.ts 2>/dev/null
+
+# Error handling middleware (must be last)
+grep -rn "err.*req.*res.*next\|ErrorHandler\|errorMiddleware" src/ --include="*.ts" --include="*.js"
+
+# Database connection used in routes
+grep -rn "db\.\|prisma\.\|knex\.\|mongoose\.\|sequelize\." src/ --include="*.ts" --include="*.js" | grep -v "node_modules"
+```
+
+### Python (Django / Flask / FastAPI)
+
+```bash
+# URL patterns
+grep -rn "urlpatterns\|path(\|route(" */urls.py **/urls.py 2>/dev/null
+
+# View imports
+grep -rn "from.*views.*import\|from.*api.*import" */urls.py **/urls.py 2>/dev/null
+
+# Middleware registration
+grep -rn "MIDDLEWARE" */settings.py 2>/dev/null
+
+# Model imports in views
+grep -rn "from.*models.*import" */views.py **/views.py 2>/dev/null
+```