@sienklogic/plan-build-run 2.11.0 → 2.12.1

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

@@ -1,113 +0,0 @@
-<!-- canonical: ../../pbr/references/deviation-rules.md -->
-# 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/cursor-pbr/references/git-integration.md

@@ -1,227 +0,0 @@
-<!-- canonical: ../../pbr/references/git-integration.md -->
-# 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/cursor-pbr/references/integration-patterns.md

@@ -1,118 +0,0 @@
-<!-- canonical: ../../pbr/references/integration-patterns.md -->
-# 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
-```

package/plugins/cursor-pbr/references/model-profiles.md

@@ -1,100 +0,0 @@
-<!-- canonical: ../../pbr/references/model-profiles.md -->
-# Model Profiles Reference
-
-How Plan-Build-Run maps agents to models and how to configure model selection.
-
----
-
-## Agent-to-Model Mapping
-
-Each Plan-Build-Run agent has a default model specified in its agent definition frontmatter (`model:` field). These defaults are overridden by the `models` section of `config.json`.
-
-### Default Agent Models
-
-| Agent | Default Model | Rationale |
-|-------|---------------|-----------|
-| `researcher` | `sonnet` | Research requires strong reasoning for source evaluation and synthesis |
-| `planner` | `inherit` | Planning is complex; inherits the session's primary model |
-| `executor` | `inherit` | Execution needs the full capability of the session model |
-| `verifier` | `sonnet` | Verification needs solid reasoning but not the heaviest model |
-| `integration-checker` | `sonnet` | Cross-phase analysis requires strong pattern matching |
-| `plan-checker` | `sonnet` | Plan quality analysis needs good analytical capability |
-| `debugger` | `inherit` | Debugging is complex; inherits session model |
-| `codebase-mapper` | `sonnet` | Codebase analysis requires thorough reasoning |
-| `synthesizer` | `haiku` | Synthesis is mechanical combination; speed over depth |
-| `general` | `inherit` | Lightweight utility; inherits session model |
-
-The `inherit` value means the agent uses whatever model the parent session is running (typically the user's configured Claude model).
-
----
-
-## Model Profile Presets
-
-The `/pbr:config model-profile {preset}` command sets all agent models at once using a preset:
-
-| Profile | Researcher | Planner | Executor | Verifier | Int-Checker | Debugger | Mapper | Synthesizer |
-|---------|-----------|---------|----------|----------|-------------|----------|--------|-------------|
-| `quality` | opus | opus | opus | opus | sonnet | opus | sonnet | sonnet |
-| `balanced` | sonnet | inherit | inherit | sonnet | sonnet | inherit | sonnet | haiku |
-| `budget` | haiku | haiku | haiku | haiku | haiku | haiku | haiku | haiku |
-| `adaptive` | sonnet | sonnet | inherit | sonnet | haiku | inherit | haiku | haiku |
-
-### Preset Descriptions
-
-- **quality**: Maximum capability across all agents. Best results but highest token cost. Use for critical projects or complex architectures.
-- **balanced**: The default preset. Front-loads intelligence in research and verification, inherits session model for planning and execution. Good general-purpose choice.
-- **budget**: All agents use haiku. Fastest and cheapest, but reduced quality for complex reasoning tasks. Suitable for well-defined, mechanical work.
-- **adaptive**: Front-loads intelligence in research and planning (where decisions matter most), uses lighter models for mechanical execution and verification. Good cost-quality tradeoff.
-
----
-
-## Configuring Models
-
-### Per-Agent Configuration
-
-Set an individual agent's model via `/pbr:config`:
-
-```
-/pbr:config model executor sonnet
-/pbr:config model verifier opus
-```
-
-Or edit `config.json` directly:
-
-```json
-{
-  "models": {
-    "researcher": "sonnet",
-    "planner": "inherit",
-    "executor": "inherit",
-    "verifier": "sonnet",
-    "integration_checker": "sonnet",
-    "debugger": "inherit",
-    "mapper": "sonnet",
-    "synthesizer": "haiku"
-  }
-}
-```
-
-### Valid Model Values
-
-| Value | Meaning |
-|-------|---------|
-| `sonnet` | Claude Sonnet (4.5/4.6) -- balanced speed and capability |
-| `opus` | Claude Opus (4.6) -- highest capability, slower |
-| `haiku` | Claude Haiku (4.5) -- fastest, lower capability |
-| `inherit` | Use the session's primary model (whatever the user is running) |
-
-Note: Claude Code 2.1.45+ supports Sonnet 4.6. Model values are abstract names — Claude Code resolves them to the latest available version.
-
----
-
-## Model Selection in Skill Orchestration
-
-Skills that spawn subagents use the `model` parameter in `Task()` calls. Some skills hardcode a lighter model for specific tasks:
-
-- **Build skill**: Spawns inline verifiers with `model: "haiku"` for quick spot-checks
-- **Build skill**: Spawns codebase mapper updates with `model: "haiku"` for incremental map refreshes
-- **Plan skill**: Uses the configured `planner` model for main planning work
-
-The `subagent_type` parameter automatically loads the agent definition, and the model from `config.json` takes precedence over the agent's default `model:` frontmatter field.

package/plugins/cursor-pbr/references/model-selection.md

@@ -1,32 +0,0 @@
-<!-- canonical: ../../pbr/references/model-selection.md -->
-# Model Selection Reference
-
-Plan-Build-Run uses adaptive model selection to balance cost and capability.
-
-## How It Works
-
-1. The planner annotates each task with `complexity="simple|medium|complex"`
-2. The build skill maps complexity to a model via `config.models.complexity_map`
-3. The executor agent is spawned with the selected model
-
-## Default Mapping
-
-| Complexity | Model | Rationale |
-|-----------|-------|-----------|
-| simple | haiku | Fast, cheap — sufficient for mechanical changes |
-| medium | sonnet | Good balance for standard feature work |
-| complex | inherit | Uses session model — typically Opus for critical work |
-
-## Override Mechanisms
-
-1. **Per-task override**: Add `model="sonnet"` attribute to task XML in PLAN.md
-2. **Config override**: Set `models.complexity_map` in config.json to change defaults
-3. **Agent-level override**: Set `models.executor` in config.json to force a single model for all executor spawns (disables adaptive selection)
-
-## Heuristics
-
-The planner uses these signals to determine complexity:
-- File count and types
-- Task name keywords
-- Dependency count
-- Whether the task introduces new patterns vs. follows established ones