@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/copilot-pbr/skills/profile/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: profile
+description: "Switch the active model profile. Presets: quality, balanced, budget, adaptive. Supports custom profiles from config.json model_profiles."
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Begin executing Step 0 immediately.**
+
+# /pbr:set-profile — Model Profile Manager
+
+You are running the **profile** skill. Your job is to show the current model profile or switch to a new one by writing model assignments to `.planning/config.json`.
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► MODEL PROFILE                              ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+## Step 1 — Load Config
+
+Read `.planning/config.json`.
+
+If the file does not exist, output:
+
+```
+Error: .planning/config.json not found. Run /pbr:new-project first.
+```
+
+Stop immediately.
+
+## Step 2 — Parse Arguments
+
+Extract the first word from `$ARGUMENTS` as the profile name. Trim whitespace.
+
+- If `$ARGUMENTS` is empty or blank → **show-mode** (go to Step 3).
+- If a profile name is present → **switch-mode** (go to Step 4).
+
+## Step 3 — Show Mode (no argument)
+
+Display the current profile status and available options.
+
+1. Read `config.json` key `model_profile`. If absent, treat as `"balanced"`.
+2. Read `config.json` key `models` (object). If absent, use empty object.
+3. Read `config.json` key `model_profiles` (object, optional custom profiles). If absent, use empty object.
+
+Output the following (fill in actual values):
+
+```
+Active profile: <model_profile value>
+
+Current model assignments:
+  researcher          : <models.researcher or "not set">
+  planner             : <models.planner or "not set">
+  executor            : <models.executor or "not set">
+  verifier            : <models.verifier or "not set">
+  integration_checker : <models.integration_checker or "not set">
+  debugger            : <models.debugger or "not set">
+  mapper              : <models.mapper or "not set">
+  synthesizer         : <models.synthesizer or "not set">
+
+Available presets:
+  quality   — all agents use opus (maximum capability)
+  balanced  — mix of sonnet/inherit/haiku (default)
+  budget    — all agents use haiku (minimum cost)
+  adaptive  — sonnet for planning/verification, inherit/haiku for execution
+```
+
+If `model_profiles` has any keys, also display:
+
+```
+Custom profiles:
+  <profile-name>  — <key count> model overrides
+```
+
+Output: "Run `/pbr:set-profile <name>` to switch profiles."
+
+Stop. Do not write anything.
+
+## Step 4 — Switch Mode (argument provided)
+
+### Step 4a — Validate Profile Name
+
+Built-in preset names: `quality`, `balanced`, `budget`, `adaptive`.
+
+Custom profile names: keys in `config.json model_profiles` (if any).
+
+If the provided name does not match any of the above:
+
+```
+Error: Unknown profile "<name>".
+
+Valid presets: quality, balanced, budget, adaptive
+<list any custom profile names from config.json model_profiles, if any>
+
+Run `/pbr:set-profile` to see the current status.
+```
+
+Stop immediately.
+
+### Step 4b — Resolve Model Values
+
+Use the preset table to resolve model values:
+
+| Agent               | quality | balanced | budget | adaptive |
+|---------------------|---------|----------|--------|----------|
+| researcher          | opus    | sonnet   | haiku  | sonnet   |
+| planner             | opus    | inherit  | haiku  | sonnet   |
+| executor            | opus    | inherit  | haiku  | inherit  |
+| verifier            | opus    | sonnet   | haiku  | sonnet   |
+| integration_checker | sonnet  | sonnet   | haiku  | haiku    |
+| debugger            | opus    | inherit  | haiku  | inherit  |
+| mapper              | sonnet  | sonnet   | haiku  | haiku    |
+| synthesizer         | sonnet  | haiku    | haiku  | haiku    |
+
+For a **custom profile** (name found in `config.json model_profiles`):
+- Start with the `balanced` defaults from the table above.
+- Overlay any keys present in `config.json model_profiles[<name>]`.
+- Any agents not specified in the custom profile use the balanced default.
+
+### Step 4c — Write to config.json
+
+Update `config.json` using the Bash tool with `node -e` inline script:
+
+```bash
+node -e "
+const fs = require('fs');
+const cfg = JSON.parse(fs.readFileSync('.planning/config.json', 'utf8'));
+cfg.model_profile = '<name>';
+cfg.models = cfg.models || {};
+cfg.models.researcher = '<value>';
+cfg.models.planner = '<value>';
+cfg.models.executor = '<value>';
+cfg.models.verifier = '<value>';
+cfg.models.integration_checker = '<value>';
+cfg.models.debugger = '<value>';
+cfg.models.mapper = '<value>';
+cfg.models.synthesizer = '<value>';
+fs.writeFileSync('.planning/config.json', JSON.stringify(cfg, null, 2));
+console.log('OK');
+"
+```
+
+Replace each `<value>` with the resolved model string for that agent. Replace `<name>` with the profile name.
+
+### Step 4d — Confirm
+
+Output:
+
+```
+Active profile set to: <name>
+
+Model assignments updated:
+  researcher          : <value>
+  planner             : <value>
+  executor            : <value>
+  verifier            : <value>
+  integration_checker : <value>
+  debugger            : <value>
+  mapper              : <value>
+  synthesizer         : <value>
+
+Config written to .planning/config.json.
+Run /pbr:set-profile to verify.
+```
+
+Stop. Done.

package/plugins/copilot-pbr/skills/quick/SKILL.md

@@ -0,0 +1,437 @@
+---
+name: quick
+description: "Execute an ad-hoc task with atomic commits. Skips full plan/review."
+---
+
+**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.**
+
+# /pbr:quick — Quick Ad-Hoc Task Execution
+
+You are running the **quick** skill. Your job is to execute a small, self-contained task outside the normal plan/build/review cycle. Quick tasks get their own tracking, atomic commits, and state integration, but skip the overhead of full planning.
+
+This skill **spawns a single Task(subagent_type: "pbr:executor")** for execution.
+
+---
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► QUICK TASK                                 ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+## References
+
+- `references/questioning.md` — Questioning philosophy and progressive depth patterns
+- `references/ui-brand.md` — Status symbols, banners, checkpoint boxes, progress display
+
+## Context Budget
+
+Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+
+Additionally for this skill:
+- **Never** implement the task yourself — you are a router, not a builder. ALL code changes go through a spawned `Task(subagent_type: "pbr:executor")`
+- **Never** skip creating `.planning/quick/{NNN}-{slug}/` and writing PLAN.md — even trivial tasks need tracking artifacts
+- **Minimize** reading executor output into main context — read only SUMMARY.md frontmatter
+
+## Composable Flags
+
+Parse `$ARGUMENTS` for optional flags before extracting the task description:
+
+- **`--discuss`**: Include a brief discussion step before building. When passed, after Step 3 (Validate Scope), ask 2-3 clarifying questions about the approach before generating the plan. This adds a lightweight discussion without the full `/pbr:discuss-phase` overhead.
+- **`--full`**: Run the complete begin-plan-build chain. When passed, instead of the quick task flow, chain directly: `Skill({ skill: "pbr:plan", args: "" })` with the task description carried over. This escalates to the full pipeline including research.
+
+Strip these flags from `$ARGUMENTS` before using the remainder as the task description.
+
+**Flag combinations:**
+- `--discuss` alone: Quick task with brief discussion step
+- `--full` alone: Escalate to full pipeline
+- `--discuss --full`: Escalate to full pipeline (--full takes precedence)
+- No flags: Standard quick task flow
+
+## Core Principle
+
+**Quick tasks are for small, well-defined work.** If the user describes something that would take more than 3-5 tasks or touches multiple subsystems, suggest using the full plan/build cycle instead.
+
+---
+
+## Flow
+
+### Step 1: Check Project Context
+
+**Init-first pattern**: When spawning agents, pass the output of `node plugins/pbr/scripts/pbr-tools.js init quick "{description}"` as context rather than having the agent read multiple files separately. This reduces file reads and prevents context-loading failures.
+
+1. Check if `.planning/` directory exists
+   - If yes: read config.json for settings
+   - If no: create **both** `.planning/` and `.planning/quick/` directories, then warn "No Plan-Build-Run project found. This will create a standalone quick task. Consider running `/pbr:new-project` first for full project tracking."
+
+2. If `.planning/` exists but `.planning/quick/` does not: create `.planning/quick/` now. **Every quick task gets tracked in `.planning/quick/` — this directory MUST exist before Step 4.**
+
+3. **After** confirming both directories exist, write `.planning/.active-skill` with the content `quick` (single word, no newline). This registers you with the workflow enforcement hook — it will block source code writes until PLAN.md exists.
+
+4. Check if ROADMAP.md exists
+   - If yes: note the current phase context (quick tasks may relate to the active phase)
+   - If no: proceed without phase context
+
+### Step 2: Get Task Description
+
+If `$ARGUMENTS` is provided and non-empty:
+- Use `$ARGUMENTS` as the task description
+
+If `$ARGUMENTS` is empty:
+- Ask the user: "What do you need done? Describe the task in a sentence or two."
+  This is a freeform text prompt — do NOT use AskUserQuestion here. Task descriptions require arbitrary text input, not option selection.
+
+### Step 3: Validate Scope
+
+Analyze the task description. If it appears to involve:
+- More than ~5 files
+- Multiple independent subsystems
+- Significant architectural decisions
+- Complex multi-step workflows
+
+Then use the **scope-confirm** pattern (see `skills/shared/gate-prompts.md`):
+
+Use AskUserQuestion:
+  question: "This task looks complex. Quick tasks work best for bug fixes, small features, config changes, and single-module refactors. How would you like to proceed?"
+  header: "Scope"
+  options:
+    - label: "Quick task"  description: "Execute as lightweight task"
+    - label: "Full plan"   description: "Switch to /pbr:plan-phase for proper planning"
+    - label: "Revise"      description: "Let me rewrite the task description"
+  multiSelect: false
+
+If user selects "Quick task": continue to Step 4.
+If user selects "Full plan": clean up `.active-skill` if it exists, then chain directly: `Skill({ skill: "pbr:plan", args: "" })`. The user's task description carries over in conversation context — the plan skill will pick it up.
+If user selects "Revise": go back to Step 2 to get a new task description.
+If user types something else (freeform): interpret their response and proceed accordingly.
+
+### Step 4: Generate Slug and Task Number
+
+**CRITICAL (no hook): You MUST complete Steps 4, 5, and 6 before any executor is spawned. If you skip these steps, the quick task will have no tracking artifacts and no PLAN.md for the executor to follow. This is the #1 failure mode of this skill.**
+
+**Generate slug:**
+- Take the first 4-5 meaningful words from the description
+- Lowercase, hyphen-separated
+- Remove articles (a, an, the) and prepositions
+- Example: "Fix auth bug in login flow" -> "fix-auth-bug-login"
+
+**Find next task number:**
+1. Scan `.planning/quick/` directory for existing quick task directories
+2. Extract the NNN prefix from directory names (pattern: `{NNN}-{slug}/`)
+3. Next number = highest existing NNN + 1
+4. If no existing tasks: start at 001
+5. Zero-pad to 3 digits
+
+### Step 5: Create Quick Task Directory
+
+**STOP — Use the Write or Bash tool RIGHT NOW to create this directory. Do not skip this step.**
+
+Create: `.planning/quick/{NNN}-{slug}/`
+
+Verify the directory exists with `ls .planning/quick/{NNN}-{slug}/` before proceeding. If the directory doesn't exist, you have a bug — go back and create it.
+
+### Step 6: Create Minimal PLAN.md
+
+Write `.planning/quick/{NNN}-{slug}/PLAN.md`:
+
+Read `references/plan-format.md` for the plan file format. Fill in all `{variable}` placeholders with actual task data from the user's description and project context.
+
+**Plan generation rules:**
+- Break the task into 1-3 tasks maximum (prefer fewer)
+- Each task should be atomic (one commit per task)
+- Infer file paths from the description and project context
+- Include concrete verification commands
+- If verification is unclear, use `echo "Manual verification needed"` and add a note
+
+**For multi-task quick tasks**, add sequential tasks:
+
+```markdown
+<task name="{task 1}" type="auto">
+...
+</task>
+
+<task name="{task 2}" type="auto">
+...
+</task>
+```
+
+**PLANNING GATE — verify before spawning executor:**
+
+Before proceeding to Step 7, confirm these exist on disk:
+1. `.planning/quick/{NNN}-{slug}/` directory exists
+2. `.planning/quick/{NNN}-{slug}/PLAN.md` exists, is non-empty, and contains at least one `<task>` block
+
+If either check fails, you have skipped steps. Go back and complete Steps 4-6. Do NOT proceed to spawning an executor.
+
+### Step 6b: Local LLM Task Validation (optional, advisory)
+
+If `config.local_llm.enabled` is `true`, run a quick scope validation before spawning:
+
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js llm classify PLAN ".planning/quick/{NNN}-{slug}/PLAN.md"
+```
+
+- If classification is `"stub"` with confidence >= 0.7: warn `"⚠ Plan looks like a stub — executor may struggle. Consider adding more detail to task descriptions."`
+- If the command fails or returns null: skip silently (local LLM unavailable)
+- This is advisory only — never block on the result
+
+### Step 7: Spawn Executor
+
+**Pre-spawn check** — Verify `.planning/quick/{NNN}-{slug}/PLAN.md` exists and contains at least one `<task>` block. If missing, STOP and complete Steps 4-6 first.
+
+Display to the user: `◆ Spawning executor...`
+
+Spawn a `Task(subagent_type: "pbr:executor")` with the following prompt:
+
+> **Completion markers**: After executor completes, check for `## PLAN COMPLETE` or `## PLAN FAILED`. Route accordingly.
+
+```
+You are executor. Execute the following quick task plan.
+
+<files_to_read>
+CRITICAL (no hook): Read these files BEFORE any other action:
+1. .planning/quick/{NNN}-{slug}/PLAN.md — the quick task plan with task details
+2. .planning/STATE.md — current project state and progress (if exists)
+</files_to_read>
+
+Plan file: .planning/quick/{NNN}-{slug}/PLAN.md
+Phase: quick
+Plan ID: {NNN}
+
+Read the plan file and execute all tasks sequentially. Follow all executor protocols:
+- Atomic commits per task
+- Commit format: fix(quick-{NNN}): {description} (or feat/refactor/test as appropriate)
+- Run verify commands
+- Create SUMMARY.md at .planning/quick/{NNN}-{slug}/SUMMARY.md
+
+Execute now.
+```
+
+### Step 8: Read Results
+
+After the executor completes:
+1. Read `.planning/quick/{NNN}-{slug}/SUMMARY.md`
+2. Check the status field:
+   - `completed` — task succeeded
+   - `partial` — some tasks completed, others failed
+   - `failed` — task failed entirely
+
+### Step 8b: Spot-Check Executor Output
+
+CRITICAL (no hook): Verify executor output before proceeding.
+
+1. **SUMMARY.md exists**: Check `.planning/quick/{NNN}-{slug}/SUMMARY.md` exists
+2. **Key files exist**: Verify first 2 files from SUMMARY.md `key_files` frontmatter exist on disk
+3. **Commits present**: Run `git log --oneline -5` and verify at least one commit matches the task scope
+4. **Self-check status**: Look for `## Self-Check: FAILED` in SUMMARY.md — if present, warn the user
+
+If ANY spot-check fails, present the user with options: **Retry** / **Continue anyway** / **Abort**
+
+### Step 9: Update STATE.md
+
+If STATE.md exists, update the Quick Tasks section.
+
+**If the section doesn't exist, create it:**
+
+```markdown
+### Quick Tasks
+
+| # | Description | Status | Commit |
+|---|-------------|--------|--------|
+```
+
+**Add the new entry:**
+
+```markdown
+| {NNN} | {description} | {status indicator} | {commit hash or "N/A"} |
+```
+
+Status indicators:
+- Completed: checkmark
+- Partial: warning indicator
+- Failed: X indicator
+
+### Step 10: Clean Up Active Skill
+
+Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.
+
+### Step 11: Commit Planning Docs
+
+Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
+
+If `planning.commit_docs: true` in config.json:
+- Stage the quick task directory files (PLAN.md, SUMMARY.md)
+- Stage STATE.md changes
+- Commit: `docs(planning): quick task {NNN} - {slug}`
+
+### Step 11b: Check Pending Todos
+
+After completing work, check if any pending todos are now satisfied:
+
+1. Check if `.planning/todos/pending/` exists and contains files
+2. If no pending todos: skip to Step 12
+3. If pending todos exist:
+   a. Read the title and description from each pending todo's YAML frontmatter
+   b. Compare each todo against the work just completed (the task description, files changed, commits made)
+   c. If a todo is **clearly satisfied** by the work (the todo's goal matches what was built):
+      - Move it: read the file, update `status: done`, add `completed: {YYYY-MM-DD}`, write to `.planning/todos/done/{filename}`, delete from `pending/` via Bash `rm`
+      - Display: `✓ Auto-closed todo {NNN}: {title} (satisfied by quick task {NNN})`
+   d. If a todo is **partially related** but not fully satisfied: do NOT close it, but mention it:
+      - Display: `ℹ Related pending todo {NNN}: {title} — may be partially addressed`
+   e. If a todo is unrelated: skip silently
+
+**Important:** Only auto-close todos where the match is unambiguous. When in doubt, leave it open — false closures are worse than missed closures.
+
+### Step 12: Report Results
+
+**Artifact check** — Before reporting, verify all required artifacts exist:
+1. `.planning/quick/{NNN}-{slug}/PLAN.md` exists
+2. `.planning/quick/{NNN}-{slug}/SUMMARY.md` exists and is non-empty
+3. STATE.md contains a quick task entry for {NNN} (if STATE.md exists)
+
+If SUMMARY.md is missing: the executor may have failed — re-read executor output and report the failure.
+If STATE.md entry is missing: write it now (Step 9 was skipped).
+
+Display results to the user with branded output:
+
+**If completed:**
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► QUICK TASK COMPLETE ✓                      ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Quick Task {NNN}:** {description}
+Commit: {hash} — {commit message}
+Files: {list of files changed}
+
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Continue your workflow** — task complete
+
+`/pbr:progress`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `/pbr:continue` — execute next logical step
+- `/pbr:check-todos` — see pending todos
+
+
+```
+
+**If partial:**
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► QUICK TASK {NNN} PARTIAL ⚠                ║
+╚══════════════════════════════════════════════════════════════╝
+
+Completed: {N} of {M} tasks
+Failed task: {task name} — {failure reason}
+
+→ Re-run with `/pbr:quick` to retry
+→ `/pbr:debug` to investigate the failure
+```
+
+**If failed:**
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+Quick Task {NNN} failed: {failure details}
+
+**To fix:** {what to try next}
+```
+
+---
+
+## Quick Task Plan Generation
+
+### Inferring File Paths
+
+When the user describes a task, infer file paths from:
+1. The project structure (use Glob to find existing files matching keywords)
+2. The tech stack (from prior SUMMARY.md files or package.json/requirements.txt)
+3. Naming conventions in the codebase
+4. Explicit file mentions in the description
+
+### Inferring Verification
+
+Choose verification based on context:
+
+| Context | Verification Command |
+|---------|---------------------|
+| TypeScript project | `npx tsc --noEmit` |
+| Has test files | `npm test` or `pytest` |
+| Has ESLint | `npx eslint {files}` |
+| Python project | `python -c "import {module}"` |
+| Config change | `cat {file}` to verify content |
+| Script | Run the script with safe args |
+| Unknown | `echo "Manual verification needed"` |
+
+### Commit Type Selection
+
+| Task Nature | Commit Type |
+|-------------|-------------|
+| Bug fix | `fix` |
+| New feature/functionality | `feat` |
+| Code restructuring | `refactor` |
+| Adding tests | `test` |
+| Config/tooling changes | `chore` |
+| Documentation | `docs` |
+
+---
+
+## Edge Cases
+
+### No `.planning/` directory
+- Create `.planning/quick/` directory
+- Proceed without STATE.md integration
+- Warn user about limited tracking
+
+### Executor fails entirely
+- Delete `.planning/.active-skill` before reporting the error
+- Read error output
+- Present to user with suggestion
+- Do NOT auto-retry — let the user decide
+
+### Task description is too vague
+- Ask clarifying questions as plain text prompts (do NOT use AskUserQuestion — these require freeform text answers):
+  - "Which file(s) need to change?"
+  - "What should the end result look like?"
+  - "Is there a specific error to fix?"
+
+### User provides a file path in the description
+- Use it directly in the plan
+- Read the file first to understand its context
+- Tailor the plan to the specific file
+
+---
+
+## Anti-Patterns
+
+**These are the most common failure modes. If you violate any of these, the skill has not executed correctly.**
+
+1. **DO NOT** implement the task yourself — you MUST spawn a `Task(subagent_type: "pbr:executor")`. This is the single most important rule.
+2. **DO NOT** skip creating `.planning/quick/{NNN}-{slug}/` — every quick task gets a tracking directory
+3. **DO NOT** skip writing PLAN.md — the executor needs a plan file to follow
+4. **DO NOT** create elaborate multi-wave plans — quick tasks should be 1-3 tasks max
+5. **DO NOT** spawn multiple executors — one executor for the whole quick task
+6. **DO NOT** skip the SUMMARY.md — even quick tasks need documentation
+7. **DO NOT** use `git add .` — stage specific files only
+8. **DO NOT** skip verification — every task needs a verify step
+9. **DO NOT** create a quick task for something that needs planning — suggest `/pbr:plan-phase`
+10. **DO NOT** modify STATE.md if it doesn't exist (other than warning)
+11. **DO NOT** break the numbering sequence — always find the next number