@sienklogic/plan-build-run 2.0.0 → 2.0.1

package/plugins/pbr/skills/setup/SKILL.md

@@ -1,227 +1,253 @@
----
-name: setup
-description: "Onboarding wizard. Initialize project, select models, verify setup."
-allowed-tools: Read, Write, Bash, Glob, AskUserQuestion
----
-
-# /pbr:setup — Plan-Build-Run Setup Wizard
-
-You are running the **setup** skill. This is an interactive onboarding wizard that guides users through Plan-Build-Run project setup. Use AskUserQuestion at each step for clear choices.
-
----
-
-## Step 1: Detect Project State
-
-Check if `.planning/` directory exists in the current working directory.
-
-**If `.planning/` exists**:
-- Read `.planning/config.json` to check current settings
-- Tell the user: "Existing Plan-Build-Run project detected. This wizard will review your configuration."
-- Skip to Step 3 (model selection)
-
-**If `.planning/` does NOT exist**:
-- Ask the user:
-
-```
-AskUserQuestion:
-  question: "No Plan-Build-Run project found. Would you like to initialize one?"
-  header: "Initialize"
-  options:
-    - label: "Yes, initialize here"
-      description: "Creates .planning/ directory with default config, STATE.md, and ROADMAP.md"
-    - label: "No, just exploring"
-      description: "Exit the wizard — you can run /pbr:begin later for full project setup"
-```
-
-If "No", display: "Run `/pbr:begin` when you're ready to start a project. It includes deep requirements gathering and roadmap creation." Then stop.
-
-If "Yes", create the minimal `.planning/` structure:
-
-```bash
-mkdir -p .planning/phases .planning/todos/pending .planning/todos/done .planning/logs .planning/research
-```
-
-Create `.planning/config.json` with defaults:
-```json
-{
-  "version": 2,
-  "depth": "standard",
-  "mode": "guided",
-  "features": {
-    "structured_planning": true,
-    "goal_verification": true,
-    "integration_verification": false,
-    "context_isolation": true,
-    "atomic_commits": true,
-    "session_persistence": true,
-    "research_phase": true,
-    "plan_checking": true,
-    "tdd_mode": false,
-    "status_line": true,
-    "auto_continue": false,
-    "auto_advance": false,
-    "team_discussions": false,
-    "inline_verify": false
-  },
-  "models": {
-    "executor": "sonnet",
-    "researcher": "sonnet",
-    "planner": "sonnet",
-    "verifier": "sonnet",
-    "synthesizer": "haiku"
-  },
-  "parallelization": {
-    "max_concurrent_agents": 3,
-    "allow_parallel_plans": true
-  },
-  "planning": {
-    "max_plans_per_phase": 4,
-    "min_must_haves": 3
-  },
-  "git": {
-    "auto_commit": true,
-    "commit_format": "conventional",
-    "branching_strategy": "none"
-  },
-  "gates": {
-    "verification": true,
-    "review": true,
-    "plan_approval": false,
-    "pre_build_checklist": false
-  },
-  "safety": {
-    "block_sensitive_files": true,
-    "require_tests": false
-  },
-  "hooks": {}
-}
-```
-
-Create `.planning/STATE.md`:
-```markdown
----
-version: 2
-current_phase: 0
-total_phases: 0
-status: "initialized"
-progress_percent: 0
-last_activity: "{today's date}"
-last_command: "/pbr:setup"
-blockers: []
----
-# Project State
-
-## Current Position
-Phase: 0 of 0
-Status: initialized
-
-Plan-Build-Run project initialized via /pbr:setup. Run /pbr:begin to start requirements gathering and roadmap creation.
-```
-
----
-
-## Step 2: Project Type (new projects only)
-
-```
-AskUserQuestion:
-  question: "What kind of project is this?"
-  header: "Project type"
-  options:
-    - label: "Greenfield"
-      description: "Starting from scratch — full planning cycle recommended"
-    - label: "Existing codebase"
-      description: "Adding Plan-Build-Run to an existing project — run /pbr:scan first"
-    - label: "Prototype/experiment"
-      description: "Quick iteration — lighter workflow with fewer gates"
-```
-
-Based on selection:
-- **Greenfield**: Keep defaults (full gates, structured planning)
-- **Existing codebase**: Suggest running `/pbr:scan` after setup to map the codebase
-- **Prototype**: Set `depth: "quick"`, disable `gates.verification`, disable `gates.review`, set `features.research_phase: false`
-
-Update config.json with any changes.
-
----
-
-## Step 3: Model Selection
-
-```
-AskUserQuestion:
-  question: "Which model profile should Plan-Build-Run use for agents?"
-  header: "Models"
-  options:
-    - label: "Balanced (Recommended)"
-      description: "Sonnet for most agents, Haiku for synthesizer. Good quality/cost tradeoff."
-    - label: "Quality"
-      description: "Opus for executor and planner, Sonnet for others. Best results, highest cost."
-    - label: "Budget"
-      description: "Haiku for most agents. Fastest and cheapest, but lower quality."
-```
-
-Apply the selected profile to `config.json`:
-- **Balanced**: executor=sonnet, researcher=sonnet, planner=sonnet, verifier=sonnet, synthesizer=haiku
-- **Quality**: executor=opus, researcher=sonnet, planner=opus, verifier=sonnet, synthesizer=sonnet
-- **Budget**: executor=haiku, researcher=haiku, planner=sonnet, verifier=haiku, synthesizer=haiku
-
----
-
-## Step 4: Workflow Preferences
-
-```
-AskUserQuestion:
-  question: "Which workflow features do you want enabled?"
-  header: "Features"
-  multiSelect: true
-  options:
-    - label: "Auto-continue"
-      description: "Automatically chain commands (build → review → next phase) without prompting"
-    - label: "TDD mode"
-      description: "Write tests before implementation in executor agents"
-    - label: "Strict gates"
-      description: "Require verification AND review to pass before advancing phases"
-    - label: "Git branching"
-      description: "Create a branch per phase for cleaner PR history"
-```
-
-Apply selections:
-- **Auto-continue**: Set `features.auto_continue: true`
-- **TDD mode**: Set `features.tdd_mode: true`
-- **Strict gates**: Set `gates.verification: true`, `gates.review: true`, `gates.plan_approval: true`
-- **Git branching**: Set `git.branching_strategy: "phase"`
-
----
-
-## Step 5: Verification
-
-Run a quick health check:
-
-1. Verify `.planning/config.json` is valid JSON
-2. Verify `.planning/STATE.md` exists and is parseable
-3. Verify hook scripts are accessible: `node ${CLAUDE_PLUGIN_ROOT}/scripts/progress-tracker.js` from the project directory
-4. Check that `npm test` works (if package.json exists)
-
-Display results:
-
-```
-Setup Complete!
-
-Project: {cwd basename}
-Model profile: {balanced/quality/budget}
-Depth: {quick/standard/comprehensive}
-Features: {list of enabled non-default features}
-
-Next steps:
-  /pbr:begin  — Full project setup with requirements and roadmap
-  /pbr:scan   — Analyze existing codebase (if adding to existing project)
-  /pbr:help   — Command reference
-  /pbr:config — Fine-tune individual settings
-```
-
----
-
-## Error Handling
-
-- If `.planning/` creation fails (permissions): Tell user to create it manually and retry
-- If config.json write fails: Display the JSON content and ask user to save it manually
-- If health check fails: Display specific failure and suggest `/pbr:health` for diagnostics
+---
+name: setup
+description: "Onboarding wizard. Initialize project, select models, verify setup."
+allowed-tools: Read, Write, Bash, Glob, AskUserQuestion
+---
+
+**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 ► SETUP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then proceed to Step 1.
+
+# /pbr:setup — Plan-Build-Run Setup Wizard
+
+You are running the **setup** skill. This is an interactive onboarding wizard that guides users through Plan-Build-Run project setup. Use AskUserQuestion at each step for clear choices.
+
+---
+
+## Step 1: Detect Project State
+
+Check if `.planning/` directory exists in the current working directory.
+
+**If `.planning/` exists**:
+- Read `.planning/config.json` to check current settings
+- Tell the user: "Existing Plan-Build-Run project detected. This wizard will review your configuration."
+- Skip to Step 3 (model selection)
+
+**If `.planning/` does NOT exist**:
+- Ask the user:
+
+```
+AskUserQuestion:
+  question: "No Plan-Build-Run project found. Would you like to initialize one?"
+  header: "Initialize"
+  options:
+    - label: "Yes, initialize here"
+      description: "Creates .planning/ directory with default config, STATE.md, and ROADMAP.md"
+    - label: "No, just exploring"
+      description: "Exit the wizard — you can run /pbr:begin later for full project setup"
+```
+
+If "No", display: "Run `/pbr:begin` when you're ready to start a project. It includes deep requirements gathering and roadmap creation." Then stop.
+
+If "Yes", create the minimal `.planning/` structure:
+
+```bash
+mkdir -p .planning/phases .planning/todos/pending .planning/todos/done .planning/logs .planning/research
+```
+
+Create `.planning/config.json` with defaults:
+```json
+{
+  "version": 2,
+  "context_strategy": "aggressive",
+  "mode": "interactive",
+  "depth": "standard",
+  "features": {
+    "structured_planning": true,
+    "goal_verification": true,
+    "integration_verification": true,
+    "context_isolation": true,
+    "atomic_commits": true,
+    "session_persistence": true,
+    "research_phase": true,
+    "plan_checking": true,
+    "tdd_mode": false,
+    "status_line": true,
+    "auto_continue": false,
+    "auto_advance": false,
+    "team_discussions": false,
+    "inline_verify": false
+  },
+  "models": {
+    "researcher": "sonnet",
+    "planner": "inherit",
+    "executor": "inherit",
+    "verifier": "sonnet",
+    "integration_checker": "sonnet",
+    "debugger": "inherit",
+    "mapper": "sonnet",
+    "synthesizer": "sonnet"
+  },
+  "parallelization": {
+    "enabled": true,
+    "plan_level": true,
+    "task_level": false,
+    "max_concurrent_agents": 3,
+    "min_plans_for_parallel": 2,
+    "use_teams": false
+  },
+  "planning": {
+    "commit_docs": true,
+    "max_tasks_per_plan": 3,
+    "search_gitignored": false
+  },
+  "git": {
+    "branching": "none",
+    "commit_format": "{type}({phase}-{plan}): {description}",
+    "phase_branch_template": "plan-build-run/phase-{phase}-{slug}",
+    "milestone_branch_template": "plan-build-run/{milestone}-{slug}",
+    "mode": "enabled"
+  },
+  "gates": {
+    "confirm_project": true,
+    "confirm_roadmap": true,
+    "confirm_plan": true,
+    "confirm_execute": false,
+    "confirm_transition": true,
+    "issues_review": true
+  },
+  "safety": {
+    "always_confirm_destructive": true,
+    "always_confirm_external_services": true
+  }
+}
+```
+
+Create `.planning/STATE.md`:
+```markdown
+---
+version: 2
+current_phase: 0
+total_phases: 0
+status: "initialized"
+progress_percent: 0
+last_activity: "{today's date}"
+last_command: "/pbr:setup"
+blockers: []
+---
+# Project State
+
+## Current Position
+Phase: 0 of 0
+Status: initialized
+
+Plan-Build-Run project initialized via /pbr:setup. Run /pbr:begin to start requirements gathering and roadmap creation.
+```
+
+---
+
+## Step 2: Project Type (new projects only)
+
+```
+AskUserQuestion:
+  question: "What kind of project is this?"
+  header: "Project type"
+  options:
+    - label: "Greenfield"
+      description: "Starting from scratch — full planning cycle recommended"
+    - label: "Existing codebase"
+      description: "Adding Plan-Build-Run to an existing project — run /pbr:scan first"
+    - label: "Prototype/experiment"
+      description: "Quick iteration — lighter workflow with fewer gates"
+```
+
+Based on selection:
+- **Greenfield**: Keep defaults (full gates, structured planning)
+- **Existing codebase**: Suggest running `/pbr:scan` after setup to map the codebase
+- **Prototype**: Set `depth: "quick"`, disable `gates.verification`, disable `gates.review`, set `features.research_phase: false`
+
+Update config.json with any changes.
+
+---
+
+## Step 3: Model Selection
+
+```
+AskUserQuestion:
+  question: "Which model profile should Plan-Build-Run use for agents?"
+  header: "Models"
+  options:
+    - label: "Balanced (Recommended)"
+      description: "Sonnet for most agents, Haiku for synthesizer. Good quality/cost tradeoff."
+    - label: "Quality"
+      description: "Opus for executor and planner, Sonnet for others. Best results, highest cost."
+    - label: "Budget"
+      description: "Haiku for most agents. Fastest and cheapest, but lower quality."
+```
+
+Apply the selected profile to `config.json`:
+- **Balanced**: executor=sonnet, researcher=sonnet, planner=sonnet, verifier=sonnet, synthesizer=haiku
+- **Quality**: executor=opus, researcher=sonnet, planner=opus, verifier=sonnet, synthesizer=sonnet
+- **Budget**: executor=haiku, researcher=haiku, planner=sonnet, verifier=haiku, synthesizer=haiku
+
+---
+
+## Step 4: Workflow Preferences
+
+```
+AskUserQuestion:
+  question: "Which workflow features do you want enabled?"
+  header: "Features"
+  multiSelect: true
+  options:
+    - label: "Auto-continue"
+      description: "Automatically chain commands (build → review → next phase) without prompting"
+    - label: "TDD mode"
+      description: "Write tests before implementation in executor agents"
+    - label: "Strict gates"
+      description: "Require verification AND review to pass before advancing phases"
+    - label: "Git branching"
+      description: "Create a branch per phase for cleaner PR history"
+```
+
+Apply selections:
+- **Auto-continue**: Set `features.auto_continue: true`
+- **TDD mode**: Set `features.tdd_mode: true`
+- **Strict gates**: Set `gates.verification: true`, `gates.review: true`, `gates.plan_approval: true`
+- **Git branching**: Set `git.branching: "phase"`
+
+---
+
+## Step 5: Verification
+
+Run a quick health check:
+
+1. Verify `.planning/config.json` is valid JSON
+2. Verify `.planning/STATE.md` exists and is parseable
+3. Verify hook scripts are accessible: `node ${CLAUDE_PLUGIN_ROOT}/scripts/progress-tracker.js` from the project directory
+4. Check that `npm test` works (if package.json exists)
+
+Display results:
+
+```
+Setup Complete!
+
+Project: {cwd basename}
+Model profile: {balanced/quality/budget}
+Depth: {quick/standard/comprehensive}
+Features: {list of enabled non-default features}
+
+Next steps:
+  /pbr:begin  — Full project setup with requirements and roadmap
+  /pbr:scan   — Analyze existing codebase (if adding to existing project)
+  /pbr:help   — Command reference
+  /pbr:config — Fine-tune individual settings
+```
+
+---
+
+## Error Handling
+
+- If `.planning/` creation fails (permissions): Tell user to create it manually and retry
+- If config.json write fails: Display the JSON content and ask user to save it manually
+- If health check fails: Display specific failure and suggest `/pbr:health` for diagnostics

package/plugins/pbr/skills/shared/commit-planning-docs.md

@@ -1,35 +1,35 @@
-# Commit Planning Docs Pattern
-
-Standard pattern for committing planning artifacts to git. Reference this fragment in skills that create or modify `.planning/` files.
-
----
-
-## Pattern
-
-```
-If `planning.commit_docs: true` in config.json:
-1. Stage the relevant .planning/ files for this skill's output
-2. Commit with format: `docs({scope}): {description}`
-3. Use the appropriate scope from the skill's commit conventions
-
-If `planning.commit_docs: false` or config.json missing:
-- Skip the commit step
-```
-
-## Commit Messages by Skill
-
-| Skill | Commit message format |
-|-------|----------------------|
-| build | `docs({phase}): add build summaries and verification` |
-| plan | `docs({phase}): add phase plans` |
-| review | `docs({phase}): add verification report` |
-| begin | `chore: initialize plan-build-run project planning` |
-| import | `docs({phase}): import external plans` |
-| quick | `docs(planning): quick task {NNN} - {slug}` |
-| scan | `docs(planning): initial codebase analysis` |
-| explore | `docs(planning): capture explore session outputs` |
-| debug | `docs(planning): open/resolve debug session {NNN}` |
-| discuss | `docs(planning): capture phase {N} discussion decisions` |
-| pause | `docs(planning): checkpoint phase {N} progress` |
-| todo | `docs(planning): add/complete todo {NNN}` |
-| milestone | `docs(planning): start/complete/audit milestone` |
+# Commit Planning Docs Pattern
+
+Standard pattern for committing planning artifacts to git. Reference this fragment in skills that create or modify `.planning/` files.
+
+---
+
+## Pattern
+
+```
+If `planning.commit_docs: true` in config.json:
+1. Stage the relevant .planning/ files for this skill's output
+2. Commit with the format from the **Commit Messages by Skill** table below (most use `docs({scope}):` but some skills like pause use `wip(planning):`)
+3. Use the appropriate scope from the skill's commit conventions
+
+If `planning.commit_docs: false` or config.json missing:
+- Skip the commit step
+```
+
+## Commit Messages by Skill
+
+| Skill | Commit message format |
+|-------|----------------------|
+| build | `docs({phase}): add build summaries and verification` |
+| plan | `docs({phase}): add phase plans` |
+| review | `docs({phase}): add verification report` |
+| begin | `chore: initialize plan-build-run project planning` |
+| import | `docs({phase}): import external plans` |
+| quick | `docs(planning): quick task {NNN} - {slug}` |
+| scan | `docs(planning): initial codebase analysis` |
+| explore | `docs(planning): capture explore session outputs` |
+| debug | `docs(planning): open/resolve debug session {NNN}` |
+| discuss | `docs(planning): capture phase {N} discussion decisions` |
+| pause | `wip(planning): save session state — phase {N} plan {M}` |
+| todo | `docs(planning): add/complete todo {NNN}` |
+| milestone | `docs(planning): start/complete/audit milestone` |