@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/codex-pbr/skills/health/SKILL.md

@@ -0,0 +1,330 @@
+---
+name: health
+description: "Check planning directory integrity. Find and fix corrupted state."
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► HEALTH CHECK                               ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+# $pbr-health — Planning Directory Diagnostics
+
+You are running the **health** skill. Your job is to validate the integrity of the `.planning/` directory, report problems, and suggest targeted fixes.
+
+This skill runs **inline**. It is read-only by default, but offers an optional **auto-fix** flow for common corruption patterns (see the Auto-Fix section below).
+
+## References
+
+- `references/questioning.md` — Questioning philosophy for diagnostic probing
+- `references/ui-brand.md` — Status symbols, banners, checkpoint boxes
+
+## Argument Parsing
+
+Check if the user passed `--repair`:
+- `--repair`: Skip the AskUserQuestion prompt in the Auto-Fix section and automatically apply ALL fixes (equivalent to selecting "Fix all"). Still create backups before any destructive operations.
+- No flag: Use the interactive AskUserQuestion flow as described below (default behavior).
+
+---
+
+## How Checks Work
+
+Each check follows the common pattern. Read `${CLAUDE_SKILL_DIR}/templates/check-pattern.md.tmpl` for the shared execution flow: target files, validate against rules, classify as PASS/FAIL/WARN/INFO, and record the result with a fix suggestion for any failures.
+
+Read `${CLAUDE_SKILL_DIR}/templates/output-format.md.tmpl` for the output format: summary table, status indicators, issues list, optional recent decisions, and final result line.
+
+---
+
+## Checks
+
+Run all 10 checks in order. Collect results and present them together at the end.
+
+### Check 1: Structure
+
+Validate `.planning/` exists with required scaffolding: `STATE.md`, `config.json`, `ROADMAP.md`.
+
+- If `.planning/` is missing: FAIL the entire health check immediately. Display:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+No .planning/ directory found.
+
+**To fix:** Run `$pbr-new-project` to initialize.
+```
+Stop all further checks.
+- PASS: All three required files exist
+- FAIL: List each missing file — "Run `$pbr-new-project` to re-initialize, or create the file manually."
+
+**Advisory checks — WARN if missing, do not FAIL:**
+
+- `.planning/PROJECT.md`
+  If missing: `⚠ PROJECT.md not found. Run $pbr-new-project to generate it, or create from plugins/pbr/templates/PROJECT.md.tmpl.`
+  If present: Check for `## Context` section (merged from legacy CONTEXT.md). If missing: `⚠ PROJECT.md has no ## Context section. Run $pbr-new-project to regenerate, or add manually.`
+
+- `.planning/REQUIREMENTS.md`
+  If missing: `⚠ REQUIREMENTS.md not found. Run $pbr-new-project to generate it, or create from plugins/pbr/templates/REQUIREMENTS.md.tmpl.`
+
+**Merged state validation:**
+
+- `.planning/STATE.md` ## History section:
+  If STATE.md exists but has no `## History` section: `⚠ STATE.md has no ## History section. History will be tracked once a milestone completes.`
+
+- `.phase-manifest.json` for completed phases:
+  For each phase marked as verified/complete in ROADMAP.md, check if `.planning/phases/{NN}-{slug}/.phase-manifest.json` exists.
+  If missing: `⚠ Phase {N} has no .phase-manifest.json. Undo operations will fall back to git log scanning.`
+
+**Legacy file detection:**
+
+- If `.planning/CONTEXT.md` exists alongside `PROJECT.md` with `## Context` section: `⚠ Legacy CONTEXT.md detected alongside merged PROJECT.md. Run $pbr-new-project to migrate — the legacy file can be removed.`
+- If `.planning/HISTORY.md` exists alongside `STATE.md` with `## History` section: `⚠ Legacy HISTORY.md detected alongside merged STATE.md. Run $pbr-new-project to migrate — the legacy file can be removed.`
+
+These files are generated by $pbr-new-project. Absence is expected on projects created before v2.15.
+
+### Check 2: Config Validity
+
+Parse `.planning/config.json` as JSON. Check required fields: `version`, `depth`. Check recommended fields: `features`, `models`.
+
+- PASS: Valid JSON with all required fields
+- FAIL (parse error): Report the parse error message — "Open the file and correct the syntax."
+- FAIL (missing required field): Report which field — "Add the field to config.json."
+- WARN (missing recommended field): Report which field — "This may cause issues with some skills."
+
+### Check 3: Phase Consistency
+
+Compare directories in `.planning/phases/` against phases defined in `ROADMAP.md`.
+
+- PASS: Every directory matches a ROADMAP.md phase; no started phases are missing directories
+- FAIL (orphan directory): Directory exists but not in ROADMAP.md — "Add to ROADMAP.md or remove the directory."
+- FAIL (missing directory): ROADMAP.md lists phase as in-progress but directory missing — "Create the directory or update ROADMAP.md."
+- Note: Future phases without directories are normal (not a failure).
+
+### Check 4: Plan/Summary Pairing
+
+Glob all `PLAN*.md` and `SUMMARY*.md` in `.planning/phases/`. Match by plan number. A PLAN without SUMMARY is normal unless the phase is marked complete.
+
+- PASS: All pairings valid, no orphaned summaries
+- FAIL (orphaned summary): SUMMARY has no matching PLAN — "Verify and remove or re-pair."
+- WARN (missing summary in complete phase): Phase marked complete but plan has no SUMMARY — "Execute with `$pbr-execute-phase` or mark phase incomplete."
+
+### Check 5: STATE.md Accuracy
+
+Extract current phase, plan identifier, and progress percentage from `STATE.md`. Verify each against the file system.
+
+- PASS: All STATE.md references match the file system
+- FAIL (stale phase): Referenced phase directory does not exist — "Update STATE.md to reflect the actual current phase."
+- FAIL (stale plan): Referenced plan file does not exist — "Update STATE.md to the correct current plan."
+- FAIL (wrong progress): Stated progress does not match actual plan/summary counts — "Update the progress in STATE.md."
+- WARN (no position): No current phase or plan specified — "Fine for new projects but may indicate lost state."
+
+### Check 6: Frontmatter Validity
+
+Glob all `PLAN*.md` and `SUMMARY*.md` in `.planning/phases/`. Each file must start with `---`, have a closing `---`, contain valid YAML, and include required fields: `title`, `status`.
+
+- PASS: All files have valid frontmatter with required fields
+- FAIL (no frontmatter): "Add frontmatter block starting with `---` at the top of the file."
+- FAIL (malformed): Report the YAML error — "Correct the YAML syntax between the `---` delimiters."
+- FAIL (missing field): Report which field — "Add `{field}: {suggested value}` to the frontmatter."
+
+### Check 7: ROADMAP/STATE Sync
+
+Compare ROADMAP.md phase statuses against STATE.md current position. Flag if ROADMAP says a phase is "verified" but STATE says it is "building", or if phases after current are marked complete.
+
+- PASS: ROADMAP and STATE are consistent
+- FAIL (mismatch): Report both statuses — "Update STATE.md to match ROADMAP.md, or vice versa."
+- WARN (drift): Current phase in STATE.md is behind phases marked complete in ROADMAP.md.
+
+### Check 8: Hook Execution Log
+
+Check if `.planning/logs/hooks.jsonl` exists. Also check the legacy path `.planning/.hook-log` (the logger migrates this automatically, but it may still exist if hooks haven't fired since the migration was added). Use whichever file exists (prefer `hooks.jsonl`). If found, scan last 20 entries for `decision: "error"` or `decision: "unlink-failed"`.
+
+- PASS: Log exists with no recent errors
+- WARN (errors found): Report error count and most recent error description — "Hooks may not be firing correctly."
+- INFO (no log): "No hook log found. Normal if no hooks have fired yet."
+
+### Check 9: Config Completeness
+
+Read `.planning/config.json` and check for fields referenced by skills:
+- `features.auto_continue` (build skill, auto-continue.js hook)
+- `features.team_discussions` (config skill)
+- `features.goal_verification` (build, review skills)
+- `features.integration_verification` (review skill)
+- `git.mode` (config skill)
+- `planning.commit_docs` (import, discuss, quick skills) — must be a boolean; validate that the value is strictly `true` or `false`, not a string or number
+
+- PASS: All expected fields present with correct types
+- WARN (missing fields): Report each missing field and which skill uses it — "Run `$pbr-settings` to set all options."
+
+### Check 10: Orphaned Crash Recovery & Lock Files
+
+The executor creates `.PROGRESS-{plan_id}` files as crash recovery breadcrumbs during builds and deletes them after `SUMMARY.md` is written. Similarly, `.checkpoint-manifest.json` files track checkpoint state during execution. If the executor crashes mid-build, these files remain and could confuse future runs.
+
+Glob for `.planning/phases/**/.PROGRESS-*` and `.planning/phases/**/.checkpoint-manifest.json`.
+
+- PASS: No orphaned files found
+- WARN (orphaned progress files): List each file with its parent phase directory:
+  ```
+  Orphaned progress files detected:
+  - .planning/phases/02-auth/.PROGRESS-02-01 (executor may have crashed)
+  ```
+  Fix suggestion: "These are crash recovery breadcrumbs from interrupted builds. Safe to delete if no `$pbr-execute-phase` is currently running. Remove with `rm <path>`."
+- WARN (orphaned checkpoint manifests): List each file:
+  ```
+  Orphaned checkpoint manifests detected:
+  - .planning/phases/02-auth/.checkpoint-manifest.json (stale build checkpoint)
+  ```
+  Fix suggestion: "Checkpoint manifests are leftover from interrupted builds. Safe to delete if no `$pbr-execute-phase` is currently running. Remove with `rm <path>`."
+
+Also check for `.planning/.active-skill`:
+
+- If the file does not exist: no action needed (PASS for this sub-check)
+- If the file exists, check its age by comparing the file modification time to the current time:
+  - If older than 1 hour: WARN with fix suggestion: "Stale .active-skill lock file detected (set {age} ago). No PBR skill appears to be running. Safe to delete with `rm .planning/.active-skill`."
+  - If younger than 1 hour: INFO: "Active skill lock exists ({content}). A PBR skill may be running."
+
+---
+
+## Auto-Fix for Common Corruption Patterns
+
+After running all 10 checks and collecting results, if any of the following auto-fixable issues were found, offer to fix them.
+
+### Auto-Fixable Patterns
+
+| Pattern | Detection | Fix Action |
+|---------|-----------|------------|
+| Missing STATE.md frontmatter | Check 5 finds STATE.md without `---` block | Regenerate frontmatter from ROADMAP.md phase data (current_phase, phase_slug, status) |
+| STATE.md phase_slug mismatch | Check 5/7 finds phase_slug doesn't match current phase directory name | Correct phase_slug to match the actual directory name in `.planning/phases/` |
+| Missing config.json | Check 1/2 finds no `.planning/config.json` | Create with default config template (same as `$pbr-setup` defaults) |
+| Orphaned .active-skill file | Check 10 or general scan finds `.planning/.active-skill` older than 1 hour | Delete the stale `.active-skill` file |
+| Empty phases directory | Check 3 finds `.planning/phases/` missing | Create the directory: `mkdir -p .planning/phases` |
+| STATE.md over 150 lines | Check 5 finds STATE.md exceeds 150 lines | Compact the `## Accumulated Context` section, keeping only the last 3 entries |
+
+### Auto-Fix Flow
+
+After displaying health check results, if any auto-fixable issues were detected:
+
+**CRITICAL — Before ANY auto-fix that modifies or regenerates STATE.md (frontmatter regeneration, phase_slug correction, or line compaction), you MUST create a timestamped backup first. DO NOT SKIP THIS STEP.**
+
+```
+mkdir -p .planning/backups
+cp .planning/STATE.md .planning/backups/STATE-$(date +%Y%m%dT%H%M%S).md
+```
+
+This ensures the user can recover the original STATE.md if the fix produces incorrect results.
+
+1. Count the auto-fixable issues.
+
+   **If `--repair` flag was passed**: Skip the question and go directly to "Fix all" (step 2). Display: "Auto-repair mode: applying {N} fixes..."
+
+   **Otherwise**: Present the choice:
+
+   Use AskUserQuestion:
+     question: "Found {N} auto-fixable issues. How should we handle them?"
+     header: "Fix?"
+     options:
+       - label: "Fix all"       description: "Apply all {N} fixes automatically"
+       - label: "Review each"   description: "Show each fix and confirm individually"
+       - label: "Skip"          description: "Do nothing — just report"
+
+2. If "Fix all" (or `--repair`): Apply all fixes in order, then display a summary:
+   ```
+   Auto-fix results:
+   - Fixed: {description of fix 1}
+   - Fixed: {description of fix 2}
+   ...
+   ```
+
+3. If "Review each": For each fixable issue, display:
+   ```
+   Issue: {description}
+   Fix: {what will be done}
+   ```
+   Then ask via AskUserQuestion (yes/no): "Apply this fix?"
+   - If yes: apply and display `- Fixed: {description}`
+   - If no: skip and display `- Skipped: {description}`
+
+4. If "Skip": Do nothing, continue to the rest of the output.
+
+---
+
+## Bonus: Recent Decisions
+
+After all checks, look for `.planning/logs/decisions.jsonl`. If it exists, display the last 5 entries as `- {date}: {summary} (phase {N})`. If it does not exist, skip silently.
+
+---
+
+## Completion
+
+After all checks complete, display the branded result:
+
+**If all checks passed (0 failures):**
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► HEALTH CHECK PASSED ✓                      ║
+╚══════════════════════════════════════════════════════════════╝
+
+{N} checks passed, {M} warnings
+
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Continue your workflow** — planning directory is healthy
+
+`$pbr-progress`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `$pbr-continue` — execute next logical step
+- `$pbr-settings` — adjust settings
+
+
+```
+
+**If failures found:**
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► HEALTH CHECK FAILED ⚠                      ║
+╚══════════════════════════════════════════════════════════════╝
+
+{N} checks passed, {F} failures, {M} warnings
+
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Fix the failures** listed above, then re-run
+
+`$pbr-health`
+
+
+```
+
+---
+
+## Anti-Patterns
+
+1. **DO NOT** modify files without user consent — auto-fix requires explicit user approval via AskUserQuestion
+2. **DO NOT** auto-repair anything silently — always present fixes and let the user decide
+3. **DO NOT** skip checks that depend on missing files — report the dependency failure and continue
+4. **DO NOT** treat warnings as failures in the summary count — only count FAIL items
+5. **DO NOT** read full plan/summary contents — frontmatter and existence checks are sufficient
+6. **DO NOT** fail silently — every check must produce an explicit PASS, WARN, or FAIL
+7. **DO NOT** suggest running destructive commands — fixes should be safe, targeted edits

package/plugins/codex-pbr/skills/help/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: help
+description: "Command reference and workflow guide for Plan-Build-Run."
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► COMMAND REFERENCE                          ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+# $pbr-help — Plan-Build-Run Command Reference
+
+## Contextual Help
+
+If `$ARGUMENTS` contains a command name (e.g., `plan`, `build`, `review`, `config`, `quick`), show detailed help for just that command instead of the full reference. Match the argument against the command tables below and display only the matching section with its subcommands and flags. If the argument doesn't match any command, show the full reference.
+
+Examples:
+- `$pbr-help plan` → Show only the plan command and its flags (--assumptions, --skip-research, --gaps, add, insert, remove)
+- `$pbr-help build` → Show only the build command and its flags (--gaps-only, --team)
+- `$pbr-help` → Show the full reference below
+
+## Full Reference
+
+Display the following reference to the user:
+
+---
+
+## Plan-Build-Run Commands
+
+### Core Workflow (the main loop)
+
+| Command | Description | Cost |
+|---------|-------------|------|
+| `$pbr-new-project` | Start a new project. Deep questioning, research, requirements, roadmap. | High (4-6 agents) |
+| `$pbr-plan-phase <N>` | Plan a phase. Research, create plans, verify before building. | Medium (2-3 agents) |
+| `$pbr-execute-phase <N>` | Build a phase. Execute plans in parallel waves, verify results. | High (2-4 agents) |
+| `$pbr-verify-work <N>` | Review what was built. Automated verification + walkthrough with you. | Low (1 agent) |
+| `$pbr-test <N>` | Generate tests for completed phase code. Detects framework automatically. | Medium (1-3 agents) |
+
+### Planning & Discovery
+
+| Command | Description |
+|---------|-------------|
+| `$pbr-explore [topic]` | Explore ideas, think through approaches. No phase number needed. |
+| `$pbr-discuss-phase <N>` | Talk through a phase before planning. Captures decisions. |
+| `$pbr-plan-phase <N> --assumptions` | Surface Claude's assumptions before planning. Zero cost. |
+| `$pbr-plan-phase <N> --skip-research` | Plan without research phase. Faster. |
+| `$pbr-plan-phase <N> --gaps` | Create gap-closure plans from verification failures. |
+| `$pbr-plan-phase add` | Append a new phase to the roadmap. |
+| `$pbr-plan-phase insert <N>` | Insert a phase using decimal numbering. |
+| `$pbr-plan-phase remove <N>` | Remove a future phase and renumber. |
+
+### Execution
+
+| Command | Description |
+|---------|-------------|
+| `$pbr-execute-phase <N>` | Execute all plans in a phase. |
+| `$pbr-execute-phase <N> --gaps-only` | Execute only gap-closure plans. |
+| `$pbr-execute-phase <N> --team` | Use Agent Teams for complex inter-agent coordination. |
+| `$pbr-quick` | Quick ad-hoc task with atomic commit. Low cost. |
+| `$pbr-continue` | Execute the next logical step automatically. No prompts. |
+
+### Verification & Debugging
+
+| Command | Description |
+|---------|-------------|
+| `$pbr-verify-work <N>` | Verify phase + conversational UAT. |
+| `$pbr-verify-work <N> --auto-fix` | Auto-diagnose and fix verification failures. |
+| `$pbr-test <N>` | Generate tests for completed phase code. Detects framework, targets key files. |
+| `$pbr-debug` | Systematic debugging with hypothesis testing. |
+| `$pbr-map-codebase` | Analyze existing codebase (brownfield). |
+
+### Session Management
+
+| Command | Description |
+|---------|-------------|
+| `$pbr-progress` | Where am I? Shows progress and suggests next action. |
+| `$pbr-health` | Check planning directory integrity. Find and fix corrupted state. |
+| `$pbr-pause-work` | Save session state for later. |
+| `$pbr-pause-work --checkpoint` | Save with a named checkpoint for easier resumption. |
+| `$pbr-resume-work` | Pick up where you left off. |
+
+### Project Management
+
+| Command | Description |
+|---------|-------------|
+| `$pbr-new-milestone` | Start a new milestone cycle. |
+| `$pbr-complete-milestone` | Archive completed milestone. |
+| `$pbr-milestone preview` | Dry-run of complete — show what would happen. |
+| `$pbr-audit-milestone` | Verify milestone completion. |
+| `$pbr-plan-milestone-gaps` | Create phases to close audit gaps. |
+| `$pbr-add-todo\|list\|done` | Persistent file-based todos. |
+| `$pbr-todo work <NNN>` | Work on a specific todo by ID. |
+| `$pbr-note <text>\|list\|promote` | Zero-friction idea capture. Quick notes that persist across sessions. |
+| `$pbr-note --global` | Save note to global notes directory (shared across projects). |
+| `$pbr-settings session_phase_limit <N>` | Set max phases per session before auto-pause (0 = disabled, default 3). |
+| `$pbr-settings` | Configure workflow settings. |
+| `$pbr-import <N>` | Import external plans (design docs, RFCs) into PBR format. |
+| `$pbr-import --from <path>` | Import from a specific file path. |
+| `$pbr-import --skip-checker` | Skip plan-checker validation on import. |
+| `$pbr-setup` | Interactive onboarding wizard for new projects. |
+
+### Analysis & Utilities
+
+| Command | Description |
+|---------|-------------|
+| `$pbr-audit` | Review past sessions for PBR workflow compliance and UX quality. |
+| `$pbr-audit --today` | Audit today's sessions (default). |
+| `$pbr-audit --from DATE --to DATE` | Audit a specific date range. |
+| `$pbr-audit --mode compliance\|ux` | Run compliance-only or UX-only audit. |
+| `$pbr-do <description>` | Route freeform text to the right PBR skill automatically. |
+| `$pbr-dashboard` | Launch the web dashboard for the current project. |
+| `$pbr-dashboard --port <N>` | Launch dashboard on a specific port. |
+| `$pbr-statusline` | Install or configure the PBR status line in Claude Code. |
+
+## Choose Your Command
+
+Not sure which command to use? Follow this guide:
+
+| I want to... | Command |
+|--------------|---------|
+| Start a new project | `$pbr-new-project` |
+| Fix a bug or investigate an error | `$pbr-debug` |
+| Think through an idea or approach | `$pbr-explore` |
+| Do a small task (≤3 files) | `$pbr-quick` |
+| Plan a complex change (4+ files) | `$pbr-plan-phase <N>` |
+| See where I am and what's next | `$pbr-progress` |
+| Auto-execute the next step | `$pbr-continue` |
+| Describe something and let PBR route it | `$pbr-do <description>` |
+| Lock decisions for a specific phase | `$pbr-discuss-phase <N>` |
+| Check project health | `$pbr-health` |
+
+## Typical Workflow
+
+```
+$pbr-new-project              ← Start project, define requirements, create roadmap
+$pbr-discuss-phase 1          ← (optional) Talk through phase details
+$pbr-plan-phase 1             ← Plan the first phase
+$pbr-execute-phase 1            ← Build it
+$pbr-verify-work 1           ← Verify it works
+$pbr-plan-phase 2             ← Plan the next phase
+...                     ← Repeat plan → build → review
+$pbr-complete-milestone ← Archive when done
+```
+
+**Shortcut**: After `$pbr-new-project`, run `$pbr-continue` repeatedly — it auto-advances through plan → build → review → next phase, stopping at milestones and errors.
+
+## status vs continue vs do
+
+| | `$pbr-progress` | `$pbr-continue` | `$pbr-do <text>` |
+|-|---------------|-----------------|-------------------|
+| **Purpose** | Dashboard — show progress, suggest next | Auto-execute the next logical step | Route freeform text to a skill |
+| **Reads state?** | Yes (full scan) | Yes (minimal) | No |
+| **Modifies files?** | Never | Yes (via delegation) | Depends on routed skill |
+| **Asks questions?** | If multiple options | Never — fully automatic | Only if ambiguous |
+| **Use when...** | You want to see where you are before deciding | You trust PBR to pick and run the next step | You'd rather describe a task in plain English |
+| **Hard stops** | N/A | Milestones, checkpoints, errors, verification gaps, session phase limit | N/A |
+
+## Quick Reference
+
+- **Context strategy**: `aggressive` (delegate everything) | `balanced` | `minimal` (run inline)
+- **Depth**: `quick` (skip research, ~50% cheaper) | `standard` | `comprehensive` (~2x cost)
+- **State files**: `.planning/STATE.md` (position), `.planning/ROADMAP.md` (phases), `.planning/config.json` (settings)
+- **Configure**: `$pbr-settings` to change depth, models, gates, parallelization
+- **List agents**: Run `claude agents` in your terminal to see all registered PBR agents and verify loading
+- **Tip**: Use `$pbr-quick` for creative/visual work where structured planning adds overhead without benefit.
+- **PR hygiene**: When creating PRs from a Plan-Build-Run project, `.planning/` commits can be filtered using phase branching (`git.branching: phase`) which squash-merges code-only changes to main.
+- **Session cycling**: After `session_phase_limit` phases (default 3), PBR auto-pauses and resumes with a fresh context. In TMUX, this is seamless. Configure via `$pbr-settings session_phase_limit <N>`.
+- **Seeds**: `$pbr-explore` can create seed files (`.planning/seeds/`) with trigger conditions. Seeds auto-inject into planning when their trigger phase is reached.
+
+## Behavioral Contexts
+
+Plan-Build-Run includes three behavioral contexts in `contexts/` that adjust how Claude operates:
+
+- **dev** — Active development: write code first, low verbosity, medium risk tolerance
+- **research** — Exploration mode: read widely, no code writing, high verbosity, evidence-based
+- **review** — Code review: read thoroughly, prioritize by severity, report don't fix
+
+Skills automatically activate the appropriate context: `$pbr-execute-phase` uses dev context, `$pbr-discuss-phase` uses research context, `$pbr-verify-work` uses review context.
+
+## When to Use Quick vs Plan+Build
+
+| Use `$pbr-quick` when... | Use `$pbr-plan-phase` + `$pbr-execute-phase` when... |
+|--------------------------|----------------------------------------|
+| Change touches ≤3 files | Change touches 4+ files |
+| ≤100 lines of code | 100+ lines of code |
+| Single subsystem | Multiple subsystems or cross-cutting |
+| No architectural decisions | Requires design choices |
+| Bug fix, small feature, docs | New feature, refactor, migration |
+
+## Setup vs Begin
+
+- **`$pbr-new-project`** — Use this to start a new project. It handles everything: questioning, research, requirements, roadmap, AND config initialization. This is the standard entry point.
+- **`$pbr-setup`** — Use this only to reconfigure an existing project's settings (model profiles, gates, depth, parallelization) without re-running the full begin flow.
+
+If you're unsure, start with `$pbr-new-project`. It will detect existing config and offer to reuse or overwrite.
+
+## Team Discussions
+
+The `features.team_discussions` config flag (and `$pbr-execute-phase --team`) enables **Agent Teams** for complex builds. When enabled, executor agents can coordinate with each other during parallel wave execution — sharing context about what they've built, resolving interface conflicts, and avoiding duplicate work. Best for phases where multiple plans have shared dependencies. Configure via `$pbr-settings`.
+
+## Getting Started
+
+```
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+- `$pbr-new-project` — start a new project
+- `$pbr-progress` — check current project status
+- `$pbr-settings` — configure workflow settings
+- `$pbr-help <command>` — detailed help for a specific command
+
+
+```
+
+## Getting Help
+
+- GitHub Issues: https://github.com/SienkLogic/plan-build-run/issues
+- README: https://github.com/SienkLogic/plan-build-run