@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/cursor-pbr/skills/debug/SKILL.md

@@ -4,14 +4,16 @@ description: "Systematic debugging with hypothesis testing. Persistent across se
 argument-hint: "[issue description]"
 ---
 
+**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 ► DEBUGGING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► DEBUGGING                                  ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -24,6 +26,13 @@ This skill **spawns Task(subagent_type: "pbr:debugger")** for investigation work
 
 ---
 
+## References
+
+- `references/questioning.md` — Investigation questioning patterns: progressive depth, exploratory questions, concrete options (not open-ended)
+- `references/ui-brand.md` — Status symbols, banners, error boxes for issue reporting
+
+---
+
 ## Context Budget
 
 Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
@@ -55,7 +64,7 @@ This handles the case where neither `.planning/` nor `.planning/debug/` exist ye
 
 ### Step 2: Check for Active Debug Sessions
 
-**Load depth profile:** Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` to get `debug.max_hypothesis_rounds`. If the command fails (no config.json or CLI error), default to 5 rounds. Initialize a round counter at 0. This counter increments each time a continuation debugger is spawned.
+**Load depth profile:** Run `node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` to get `debug.max_hypothesis_rounds`. If the command fails (no config.json or CLI error), default to 5 rounds. Initialize a round counter at 0. This counter increments each time a continuation debugger is spawned.
 
 Scan `.planning/debug/` for existing debug files:
 
@@ -65,9 +74,11 @@ Scan `.planning/debug/` for existing debug files:
 ```
 
 Read each file's frontmatter to check status:
-- `status: active` — session is in progress
-- `status: resolved` — session is complete
-- `status: stale` — session was abandoned
+- `status: gathering` — collecting symptoms from user
+- `status: investigating` — testing hypotheses
+- `status: fixing` — applying fix
+- `status: verifying` — confirming fix works
+- `status: resolved` — session complete
 
 **If active sessions found:**
 
@@ -126,7 +137,7 @@ Create `.planning/debug/{NNN}-{slug}.md`:
 ---
 id: "{NNN}"
 title: "{issue title}"
-status: active
+status: gathering
 created: "{ISO date}"
 updated: "{ISO date}"
 severity: "{critical|high|medium|low}"
@@ -176,11 +187,11 @@ category: "{runtime|build|test|config|integration|unknown}"
 
 #### Spawn Debugger
 
-Display to the user: `◐ Spawning debugger...`
+Display to the user: `◆ Spawning debugger...`
 
 Spawn `Task(subagent_type: "pbr:debugger")` with the prompt template.
 
-Read `skills/debug/templates/initial-investigation-prompt.md.tmpl` for the spawn prompt. Fill in the `{NNN}`, `{slug}`, and symptom placeholders with values from the debug file created above.
+Read `${CLAUDE_SKILL_DIR}/templates/initial-investigation-prompt.md.tmpl` for the spawn prompt. Fill in the `{NNN}`, `{slug}`, and symptom placeholders with values from the debug file created above.
 
 ### Step 3b: Resume Flow
 
@@ -200,15 +211,26 @@ Last state:
 Continuing investigation...
 ```
 
-4. **Increment the round counter** (resuming counts as a new round). Display to the user: `◐ Spawning debugger (resuming session #{NNN}, round {N})...`
+4. **Increment the round counter** (resuming counts as a new round). Display to the user: `◆ Spawning debugger (resuming session #{NNN}, round {N})...`
 
    Spawn `Task(subagent_type: "pbr:debugger")` with the continuation prompt template.
 
-   Read `skills/debug/templates/continuation-prompt.md.tmpl` for the spawn prompt. Fill in the `{NNN}`, `{slug}`, and `{paste investigation log...}` placeholders with data from the debug file.
+   Read `${CLAUDE_SKILL_DIR}/templates/continuation-prompt.md.tmpl` for the spawn prompt. Fill in the `{NNN}`, `{slug}`, and `{paste investigation log...}` placeholders with data from the debug file.
 
 ### Step 4: Handle Debugger Results
 
-When the debugger agent completes, display: `✓ Debug session complete — {N} hypotheses tested` (read the hypothesis count from the debug file's Hypotheses table).
+When the debugger agent completes, first check for completion markers in the Task() output before routing:
+
+| Marker in Task() Output | Route To |
+|--------------------------|----------|
+| `## DEBUG COMPLETE` | ROOT CAUSE FOUND + FIX path |
+| `## ROOT CAUSE FOUND` | ROOT CAUSE FOUND (no fix) path |
+| `## DEBUG SESSION PAUSED` | CHECKPOINT path |
+| No marker found | INCONCLUSIVE path |
+
+**Spot-check:** Before routing, verify `.planning/debug/{NNN}-{slug}.md` exists and was recently updated (modified timestamp is newer than the Task() spawn time). If the debug file was not updated, warn: `⚠ Debug file not updated by agent — results may be incomplete.`
+
+Display: `✓ Debug session complete — {N} hypotheses tested` (read the hypothesis count from the debug file's Hypotheses table).
 
 The debugger returns one of four outcomes:
 
@@ -230,32 +252,34 @@ Actions:
 3. Report to user with branded output:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► BUG RESOLVED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► BUG RESOLVED ✓                             ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Session #{NNN}:** {title}
 **Root cause:** {cause}
 **Fix:** {description}
 **Commit:** {hash}
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Continue your workflow** — the bug is fixed
 
-`/pbr:status`
+`/pbr:progress`
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:continue` — execute next logical step
-- `/pbr:review {N}` — verify the current phase
+- `/pbr:verify-work {N}` — verify the current phase
+
 
-───────────────────────────────────────────────────────────────
 ```
 
 #### ROOT CAUSE FOUND (no fix)
@@ -275,9 +299,11 @@ Actions:
 2. Suggest next steps to user:
 
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Apply the fix** — root cause identified, fix needed
 
@@ -285,13 +311,13 @@ Actions:
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
-- `/pbr:plan` — for complex fixes that need planning
-- `/pbr:status` — see project status
+- `/pbr:plan-phase` — for complex fixes that need planning
+- `/pbr:progress` — see project status
+
 
-───────────────────────────────────────────────────────────────
 ```
 
 #### CHECKPOINT
@@ -312,7 +338,7 @@ Actions:
    question: "Investigation has reached a checkpoint. How should we proceed?"
 
 Handle responses:
-- "Continue": **Increment the round counter** (e.g., round 1 becomes round 2). Then display `◐ Spawning debugger (continuing investigation, round {N})...` and spawn another `Task(subagent_type: "pbr:debugger")` with updated context from the debug file
+- "Continue": **Increment the round counter** (e.g., round 1 becomes round 2). Then display `◆ Spawning debugger (continuing investigation, round {N})...` and spawn another `Task(subagent_type: "pbr:debugger")` with updated context from the debug file
 - "More info": **Increment the round counter.** Ask the user freeform what additional context they have, then update the debug file and spawn another debugger
 - "New approach": **Increment the round counter.** Ask the user freeform what alternative angle to try, then update hypotheses and spawn another debugger
 
@@ -401,7 +427,7 @@ Use AskUserQuestion:
     - label: "Escalate"  description: "Save context for manual debugging"
 
 - If "Extend": double the limit and continue
-- If "Wrap up": update debug file status to `stale`, record all findings, suggest next steps
+- If "Wrap up": update debug file `status: resolved` with `resolution: abandoned`, record all findings, suggest next steps
 - If "Escalate": write a detailed handoff document to the debug file with all hypotheses, evidence, and suggested manual investigation steps
 
 ---
@@ -411,15 +437,15 @@ Use AskUserQuestion:
 ### Lifecycle
 
 ```
-active → resolved     (root cause found and fixed)
-active → stale        (abandoned — no updates for 7+ days)
-active → active       (resumed after pause)
+gathering → investigating → fixing → verifying → resolved
+(any non-resolved) → resolved  (with resolution: abandoned, if 7+ days stale)
+(any non-resolved) → (same)    (resumed after pause)
 ```
 
 ### Staleness Detection
 
 When scanning for active sessions, check the `updated` date. If more than 7 days old:
-- Mark as `stale` in status
+- Set `status: resolved` with `resolution: abandoned` in frontmatter
 - Still offer to resume, but warn: "This session is {N} days old. Context may have changed."
 
 ### Cleanup

package/plugins/cursor-pbr/skills/discuss/SKILL.md

@@ -1,22 +1,26 @@
 ---
 name: discuss
 description: "Talk through a phase before planning. Identifies gray areas and captures your decisions."
-argument-hint: "<phase-number>"
+argument-hint: "<phase-number> | --project"
 ---
 
+**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 ► DISCUSSION
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► DISCUSSION                                 ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
 
-# /pbr:discuss — Pre-Planning Discussion
+# /pbr:discuss-phase — Pre-Planning Discussion
+
+**References:** `@references/questioning.md`, `@references/ui-brand.md`
 
 You are running the **discuss** skill. Your job is to help the user think through a phase BEFORE planning begins. You identify gray areas where the user's preference matters, ask structured questions, and capture every decision in a CONTEXT.md file that the planner must honor.
 
@@ -24,6 +28,22 @@ This skill runs **inline** (no Task delegation).
 
 ---
 
+## Multi-Session Sync
+
+Before any phase-modifying operations (writing CONTEXT.md, updating STATE.md), acquire a claim:
+
+```
+acquireClaim(phaseDir, sessionId)
+```
+
+If the claim fails (another session owns this phase), display: "Another session owns this phase. Use `/pbr:progress` to see active claims."
+
+On completion or error (including all exit paths), release the claim:
+
+```
+releaseClaim(phaseDir, sessionId)
+```
+
 ## Core Principle
 
 **Decisions made here are LOCKED.** The planner cannot override them, even if research suggests a different approach. The planner must implement the locked decision and may note the discrepancy, but must follow the user's choice exactly.
@@ -34,12 +54,15 @@ This skill runs **inline** (no Task delegation).
 
 ### Step 1: Parse Phase Number and Check for Existing Plans
 
-Parse `$ARGUMENTS` to get the phase number.
+Parse `$ARGUMENTS`:
+- If argument is `--project`: enter PROJECT mode (see Step 1-project below). Skip Steps 2-8.
+- If argument is a phase number: enter PHASE mode (existing flow — continue with Step 1 as-is).
+- If no argument: existing logic applies (read STATE.md for current phase).
 
-**Validation:**
+**Validation (PHASE mode):**
 - Must be a valid phase number (integer or decimal like `3.1`)
 - If no argument provided, read STATE.md to get the current phase
-- If no current phase and no argument: "Which phase do you want to discuss? Run `/pbr:status` to see available phases."
+- If no current phase and no argument: "Which phase do you want to discuss? Run `/pbr:progress` to see available phases."
 
 **Phase directory resolution:**
 1. List directories in `.planning/phases/`
@@ -53,15 +76,66 @@ Parse `$ARGUMENTS` to get the phase number.
 
 Phase {N} not found.
 
-**To fix:** Run `/pbr:status` to see available phases.
+**To fix:** Run `/pbr:progress` to see available phases.
 ```
 
 **Check for existing plans** (after resolving the phase directory):
 1. Check for `PLAN.md` or `PLAN-*.md` files in the phase directory
 2. If plan files exist:
-   - Warn: "Phase {N} already has plans. Decisions from this discussion won't retroactively change them. Consider re-planning with `/pbr:plan {N}` after."
+   - Warn: "Phase {N} already has plans. Decisions from this discussion won't retroactively change them. Consider re-planning with `/pbr:plan-phase {N}` after."
    - This is a **warning only** — do not block the discussion
 
+### Step 1-project: Project Discussion Mode (--project)
+
+When invoked with `--project`, discuss project-level cross-cutting decisions.
+This mode writes to `.planning/PROJECT.md` ## Context section (project-level), NOT a phase directory.
+
+**Check for existing project context:**
+1. Read `.planning/PROJECT.md` and check if it has a `## Context` section.
+2. If it has a ## Context section, ask the user (using the context-handling pattern from
+   `skills/shared/gate-prompts.md`):
+   question: "PROJECT.md already has a ## Context section. How should we handle it?"
+   options: Overwrite | Append | Cancel
+3. If Cancel: stop and display the existing PROJECT.md path.
+4. **Backwards compat:** If `.planning/CONTEXT.md` exists (legacy), read it as the existing context source for Append mode, then write merged result to PROJECT.md ## Context.
+
+**Load project context:**
+- Read `.planning/PROJECT.md` (if exists) — project vision, scope, and context (## Context section)
+- Read `.planning/REQUIREMENTS.md` (if exists) — requirements for constraint awareness
+- **Backwards compat:** If PROJECT.md has no ## Context but `.planning/CONTEXT.md` exists, read from the legacy file
+
+**Run gray areas for project-level decisions (Steps 2.5-5 pattern):**
+- Identify 3-4 cross-cutting architectural decisions across ALL phases
+- Focus on: technology stack choices, infrastructure, security posture,
+  observability approach, deployment strategy, data storage decisions
+- Follow the same Steps 3-5 pattern (gray areas → options → follow-ups)
+
+**Write project context to PROJECT.md:**
+1. Read `${CLAUDE_SKILL_DIR}/templates/project-CONTEXT.md.tmpl`
+2. Fill in from discussion decisions:
+   - Locked Decisions table: all decisions the user made (not "Let Claude decide")
+   - User Constraints: budget, team, timeline, hosting from the conversation
+   - Deferred Ideas: anything explicitly ruled out for this project
+   - Claude's Discretion: decisions marked "Let Claude decide"
+3. If Append mode: merge new decisions with existing PROJECT.md ## Context content
+4. Write to `.planning/PROJECT.md` under the `## Context` section with subsections:
+   - `### Locked Decisions`
+   - `### User Constraints`
+   - `### Deferred Ideas`
+
+**Update STATE.md pointer:**
+Add under Accumulated Context:
+```
+Project context: .planning/PROJECT.md ## Context ({N} locked decisions, {N} deferred, {N} discretion)
+```
+
+**After writing:** Auto-sync to CLAUDE.md is handled by the post-write-dispatch hook.
+Display: `✓ Project context written to PROJECT.md — locked decisions will auto-sync to CLAUDE.md`
+
+Skip to Cleanup step. Do NOT run Steps 2-8 of the phase flow.
+
+---
+
 ### Step 2: Load Phase Context
 
 Read the following files to understand what this phase needs to accomplish:
@@ -79,7 +153,7 @@ Read the following files to understand what this phase needs to accomplish:
    - What patterns have been established (`patterns` field)
    - What decisions were already made (`key_decisions` field)
 
-3. **REQUIREMENTS.md** (if exists) — Read project requirements relevant to this phase
+3. **REQUIREMENTS.md** (if exists) — Read project requirements relevant to this phase. **CRITICAL**: After reading, display to the user which specific requirements map to this phase. Flag any requirements that could constrain decisions. If the user's discussion decisions later contradict a stated requirement, surface the contradiction immediately — don't wait until planning.
 
 4. **CONTEXT.md** (if exists in the phase directory) — Check if a prior discussion already happened
    - If CONTEXT.md exists, inform the user and use the **context-handling** pattern from `skills/shared/gate-prompts.md`:
@@ -113,7 +187,7 @@ Before jumping into specific gray areas, give the user space to share their ment
 
 Analyze the phase goal, requirements, and what's already built. Identify **3-4 gray areas** where the user's preference matters. Gray areas fall into these categories:
 
-Read `skills/discuss/templates/decision-categories.md` for the category reference table.
+Read `${CLAUDE_SKILL_DIR}/templates/decision-categories.md` for the category reference table.
 
 **How to identify gray areas:**
 1. Look at the phase requirements — where are there multiple valid approaches?
@@ -150,17 +224,23 @@ If more than 3 concrete options exist for a gray area, present only the top 3 pl
 
 For each gray area where the user made a decision (not "Let Claude decide"), ask **4 follow-up questions** to fully capture their intent.
 
+**CRITICAL — STOP: Do NOT skip ANY of the 4 follow-up areas below. All 4 MUST be asked for each gray area where the user made a decision.**
+
 **Follow-up question types:**
 
+**CRITICAL — STOP: Do NOT skip this follow-up area.**
 1. **Scope boundary**: "Should {feature} also handle {edge case}?"
    Use the **yes-no** pattern — this is a binary decision.
 
+**CRITICAL — STOP: Do NOT skip this follow-up area.**
 2. **Quality level**: "How polished should this be?"
    Do NOT use AskUserQuestion — this is freeform. Let the user describe their quality expectations in their own words.
 
+**CRITICAL — STOP: Do NOT skip this follow-up area.**
 3. **Integration**: "How should this interact with {existing component}?"
    Do NOT use AskUserQuestion — this is freeform. The answer depends on the specific component and context.
 
+**CRITICAL — STOP: Do NOT skip this follow-up area.**
 4. **Future-proofing**: "Should we design this to support {potential future need}, or keep it simple?"
    Use the **yes-no** pattern:
      question: "Design {feature} to support {future need}, or keep it simple for now?"
@@ -174,6 +254,8 @@ For each gray area where the user made a decision (not "Let Claude decide"), ask
 - If the user gives a short answer, capture it as-is
 - If the user says "you decide" on a follow-up, move that specific sub-decision to Claude's Discretion
 
+**Completion check:** After all follow-up questions for all gray areas, verify that all 4 follow-up areas produced output for each decided gray area. If any area was missed, go back and ask it before proceeding to Step 6.
+
 ### Step 6: Capture Deferred Ideas
 
 During the conversation, the user may mention ideas they want but not in this phase. Track these separately:
@@ -181,6 +263,23 @@ During the conversation, the user may mention ideas they want but not in this ph
 - Ideas that are out of scope for this phase based on ROADMAP.md
 - Ideas the user considered but rejected
 
+### Step 6.5: Decision Gate (inline)
+
+Before creating the CONTEXT.md artifact, confirm readiness with the user per `@references/questioning.md` decision gate pattern:
+
+```
+AskUserQuestion:
+  question: "I think I have a clear picture of your decisions for this phase. Ready to capture them in CONTEXT.md?"
+  header: "Ready?"
+  options:
+    - label: "Yes, proceed"    description: "Write CONTEXT.md with captured decisions"
+    - label: "Keep exploring"  description: "I want to share more or discuss further"
+```
+
+If "Keep exploring" -- ask what they want to add or identify gaps and probe naturally. Loop until "Yes, proceed" is selected.
+
+**Freeform rule:** If the user selects "Keep exploring" and responds with freeform text (not selecting an option), switch to plain text conversation per `@references/questioning.md` freeform rule. Do NOT present another AskUserQuestion until you have processed their freeform response.
+
 ### Step 7: Write CONTEXT.md
 
 Write the CONTEXT.md file to the phase directory:
@@ -189,7 +288,7 @@ Write the CONTEXT.md file to the phase directory:
 
 **Content:**
 
-Read `skills/discuss/templates/CONTEXT.md.tmpl` for the template structure.
+Read `${CLAUDE_SKILL_DIR}/templates/CONTEXT.md.tmpl` for the template structure.
 
 **Placeholders to fill:**
 - `{N}` -- the phase number
@@ -211,38 +310,34 @@ Add under the `### Decisions` subsection:
 Phase {N} discussion: .planning/phases/{NN}-{slug}/CONTEXT.md ({count} locked, {count} deferred, {count} discretion)
 ```
 
-This creates a pointer so `/pbr:resume` and `progress-tracker.js` know that phase-specific decisions exist and where to find them.
+This creates a pointer so `/pbr:resume-work` and `progress-tracker.js` know that phase-specific decisions exist and where to find them.
 
 ### Step 8: Confirm and Route
 
-After writing CONTEXT.md, display branded output:
+After writing CONTEXT.md, display branded output per `@references/ui-brand.md`:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► DISCUSSION CAPTURED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► DISCUSSION CAPTURED ✓                      ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {name}**
 
-Decisions: {count} locked, {count} deferred, {count} discretion
-
-───────────────────────────────────────────────────────────────
+✓ Decisions: {count} locked, {count} deferred, {count} discretion
 
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Plan this phase** — your decisions will be honored
 
-`/pbr:plan {N}`
+`/pbr:plan-phase {N}`
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
-
 **Also available:**
-- `/pbr:status` — see project status
+- `/pbr:progress` — see project status
 - `/pbr:explore` — explore ideas further
-
-───────────────────────────────────────────────────────────────
 ```
 
 ---
@@ -303,7 +398,7 @@ These come from:
 
 ### User wants to discuss multiple phases
 - Handle one at a time
-- After completing one, suggest: "Want to discuss Phase {N+1} too? Run `/pbr:discuss {N+1}`."
+- After completing one, suggest: "Want to discuss Phase {N+1} too? Run `/pbr:discuss-phase {N+1}`."
 
 ### User disagrees with all options
 - Ask: "What would you prefer instead?" — this is freeform text, do NOT use AskUserQuestion.
@@ -319,7 +414,7 @@ These come from:
 
 ## State Integration
 
-This skill updates STATE.md's Accumulated Context section with a pointer to the phase CONTEXT.md file. It does NOT change the project position (current phase/plan). STATE.md position is updated when `/pbr:plan` runs.
+This skill updates STATE.md's Accumulated Context section with a pointer to the phase CONTEXT.md file. It does NOT change the project position (current phase/plan). STATE.md position is updated when `/pbr:plan-phase` runs.
 
 ---
 

package/plugins/cursor-pbr/skills/do/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: do
+description: "Route freeform text to the right PBR skill automatically."
+argument-hint: "<freeform description of what you want to do>"
+---
+
+**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 ~3,000 tokens. Begin executing Step 1 immediately.**
+
+# /pbr:do — Freeform Task Router
+
+You are running the **do** skill. Your job is to analyze freeform text from the user and route it to the most appropriate PBR skill. You are a dispatcher, not an executor — you never do the work yourself.
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► ROUTING                                    ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+## Step 1 — Validate Input
+
+If `$ARGUMENTS` is empty, ask the user what they want to do via AskUserQuestion:
+```
+What would you like to do? Describe the task, bug, or idea and I'll route it to the right skill.
+```
+
+## Step 2 — Analyze and Route
+
+Evaluate `$ARGUMENTS` against these routing criteria. Apply the **first matching** rule:
+
+| If the text describes... | Route to | Why |
+|--------------------------|----------|-----|
+| A bug, error, crash, failure, or something broken | `/pbr:debug` | Needs systematic investigation |
+| Exploration, research, comparison, or "how does X work" | `/pbr:explore` | Open-ended investigation |
+| A complex task: refactoring, migration, multi-file architecture, system redesign | `/pbr:plan-phase add` | Needs a full phase with research/plan/build cycle |
+| A review or quality concern about existing work | `/pbr:verify-work` | Needs verification against plan |
+| A note, idea, or "remember to..." | `/pbr:note` | Capture for later |
+| A specific, actionable task (add feature, fix typo, update config, write test) | `/pbr:quick` | Self-contained, single executor |
+
+**Ambiguity handling**: If the text could reasonably match multiple routes, ask the user via AskUserQuestion with the top 2-3 options. For example:
+
+```
+"Refactor the authentication system" could be:
+- /pbr:plan-phase add — Full planning cycle (recommended for multi-file refactors)
+- /pbr:quick — Quick execution (if scope is small and clear)
+```
+
+## Step 3 — Confirm and Dispatch
+
+Display the routing decision:
+
+```
+**Input:** {first 80 chars of arguments}
+**Routing to:** {chosen skill}
+**Reason:** {one-line explanation}
+```
+
+Then invoke the chosen skill via the Skill tool, passing `$ARGUMENTS` as the args.
+
+**Special case for `/pbr:plan-phase add`**: When routing to plan, check if `.planning/ROADMAP.md` exists first (via Read). If it doesn't, suggest `/pbr:new-project` instead — the user needs to set up the project before they can add phases.
+
+## Step 4 — No Follow-Up
+
+After invoking the skill, your job is done. The dispatched skill handles everything from here (execution, commits, state updates). Do not add any additional output after the Skill tool call.