@sienklogic/plan-build-run 2.3.0 → 2.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",

package/plugins/cursor-pbr/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Plan-Build-Run — Structured development workflow for Cursor. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

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

@@ -0,0 +1,67 @@
+---
+name: do
+description: "Route freeform text to the right PBR skill automatically."
+argument-hint: "<freeform description of what you want to do>"
+---
+
+# /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 add` | Needs a full phase with research/plan/build cycle |
+| A review or quality concern about existing work | `/pbr:review` | 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 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 add`**: When routing to plan, check if `.planning/ROADMAP.md` exists first (via Read). If it doesn't, suggest `/pbr:begin` 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.

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

@@ -184,17 +184,38 @@ Todo {NNN} not found in pending todos.
 2. If not found, display the same error block as `done` — suggest `/pbr:todo list`
 3. Read the todo file content (frontmatter + body)
 4. Extract the `title` from frontmatter and the full body (Goal, Scope, Acceptance Criteria sections)
-5. Display branded output:
+
+5. **Assess complexity** to choose the right skill. Evaluate the todo content against these criteria:
+
+| Signal | Route to |
+|--------|----------|
+| Single file change, small fix, simple addition | `/pbr:quick` |
+| Multiple acceptance criteria, multi-file scope, architectural decisions, needs research | `/pbr:plan` (requires an active phase) |
+| Investigation needed, unclear root cause | `/pbr:debug` |
+| Open-ended exploration, no clear deliverable | `/pbr:explore` |
+
+If unsure, ask the user via AskUserQuestion:
+```
+Todo {NNN} could be handled as a quick task or may need full planning.
+
+Which approach?
+- Quick task (/pbr:quick) — single executor, atomic commit
+- Full planning (/pbr:plan) — research, plan, build cycle
+- Debug (/pbr:debug) — systematic investigation
+- Explore (/pbr:explore) — open-ended investigation
+```
+
+6. Display branded output:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  PLAN-BUILD-RUN ► WORKING ON TODO {NNN}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 **Todo {NNN}:** {title}
-
-Launching /pbr:quick with todo context...
+**Routing to:** /pbr:{chosen-skill}
 ```
-6. Invoke the Skill tool: `skill: "pbr:quick"` with `args` set to the todo title followed by the body content. Format the args as:
+
+7. Invoke the chosen skill via the Skill tool, passing the todo title and body as args:
 
 ```
 {title}
@@ -203,7 +224,9 @@ Context from todo {NNN}:
 {body content — Goal, Scope, Acceptance Criteria sections}
 ```
 
-This hands off execution to `/pbr:quick`, which will spawn an executor agent, make atomic commits, and track the work. When quick completes, remind the user:
+For `/pbr:plan`, if no phase exists for this work yet, suggest the user run `/pbr:plan add` first to create one, then re-run `/pbr:todo work {NNN}`.
+
+8. When the skill completes, remind the user:
 
 ```
 ───────────────────────────────────────────────────────────────

package/plugins/pbr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Plan-Build-Run — Structured development workflow for Claude Code. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/pbr/scripts/validate-skill-args.js

@@ -7,8 +7,8 @@
  *   - /pbr:plan — blocks freeform text arguments that don't match
  *     valid patterns (phase number, subcommand, flags).
  *
- * This provides structural enforcement that catches cases where the
- * LLM ignores the prompt-based freeform text guard in SKILL.md.
+ * When freeform text is detected, analyzes it to suggest the most
+ * appropriate skill (quick, debug, explore, todo, plan).
  *
  * Exit codes:
  *   0 = allowed (valid args or non-plan skill)
@@ -29,6 +29,47 @@ const { logHook } = require('./hook-logger');
  */
 const PLAN_VALID_PATTERN = /^\s*$|^\s*\d+(\.\d+)?\s*(--(?:skip-research|assumptions|gaps|teams)\s*)*$|^\s*(?:add|check)\s*$|^\s*(?:insert|remove)\s+\d+(\.\d+)?\s*$/i;
 
+/**
+ * Keyword patterns for routing freeform text to the right skill.
+ * Order matters — first match wins.
+ */
+const ROUTE_PATTERNS = [
+  {
+    pattern: /\b(bugs?|fix(es|ing)?|errors?|crash(es|ing)?|fails?|failing|broken|issues?|debug(ging)?|diagnos(e|ing)|stack\s*trace|exceptions?|regress(ion|ing)?)\b/i,
+    skill: '/pbr:debug',
+    reason: 'Looks like a bug or debugging task'
+  },
+  {
+    pattern: /\b(explore|research|understand|how does|what is|analy[zs]e|evaluate|compare|pros and cons|trade-?offs?|approach(es)?)\b/i,
+    skill: '/pbr:explore',
+    reason: 'Looks like exploration or research'
+  },
+  {
+    pattern: /\b(refactor|redesign|architect|migrate|restructure|overhaul|rewrite|multi-?phase|complex|system|infrastructure)\b/i,
+    skill: '/pbr:plan add',
+    reason: 'Looks like a complex task that needs full planning'
+  },
+  {
+    // Default: anything actionable goes to quick
+    pattern: /./,
+    skill: '/pbr:quick',
+    reason: 'Looks like a straightforward task'
+  }
+];
+
+/**
+ * Suggest the best skill for freeform text.
+ * Returns { skill, reason }.
+ */
+function suggestSkill(text) {
+  for (const route of ROUTE_PATTERNS) {
+    if (route.pattern.test(text)) {
+      return { skill: route.skill, reason: route.reason };
+    }
+  }
+  return { skill: '/pbr:quick', reason: 'Default routing' };
+}
+
 /**
  * Check whether a Skill tool call has valid arguments.
  * Returns null if valid, or { output, exitCode } if blocked.
@@ -48,11 +89,14 @@ function checkSkillArgs(data) {
     return null;
   }
 
-  // Freeform text detected — block
+  // Freeform text detected — suggest the right skill
+  const suggestion = suggestSkill(args);
+
   logHook('validate-skill-args', 'PreToolUse', 'blocked', {
     skill,
     args: args.substring(0, 100),
-    reason: 'freeform-text'
+    reason: 'freeform-text',
+    suggested: suggestion.skill
   });
 
   return {
@@ -62,17 +106,17 @@ function checkSkillArgs(data) {
         '',
         'The arguments "' + args.substring(0, 80) + (args.length > 80 ? '...' : '') + '" do not match any valid pattern.',
         '',
-        'Valid usage:',
+        'Valid /pbr:plan usage:',
         '  /pbr:plan <N>              Plan phase N',
         '  /pbr:plan <N> --gaps       Create gap-closure plans',
         '  /pbr:plan add              Add a new phase',
         '  /pbr:plan insert <N>       Insert a phase at position N',
         '  /pbr:plan remove <N>       Remove phase N',
         '',
-        'For freeform tasks, use:',
-        '  /pbr:todo add <description>   Capture as a todo',
-        '  /pbr:quick <description>      Execute immediately',
-        '  /pbr:explore <topic>          Investigate an idea'
+        'Suggested skill for this text:',
+        '  ' + suggestion.skill + ' — ' + suggestion.reason,
+        '',
+        'Or use /pbr:do to auto-route freeform text to the right skill.'
       ].join('\n')
     },
     exitCode: 2
@@ -102,5 +146,5 @@ function main() {
   });
 }
 
-module.exports = { checkSkillArgs, PLAN_VALID_PATTERN };
+module.exports = { checkSkillArgs, suggestSkill, PLAN_VALID_PATTERN, ROUTE_PATTERNS };
 if (require.main === module || process.argv[1] === __filename) { main(); }

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

@@ -0,0 +1,70 @@
+---
+name: do
+description: "Route freeform text to the right PBR skill automatically."
+allowed-tools: Read, Skill, AskUserQuestion
+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 add` | Needs a full phase with research/plan/build cycle |
+| A review or quality concern about existing work | `/pbr:review` | 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 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 add`**: When routing to plan, check if `.planning/ROADMAP.md` exists first (via Read). If it doesn't, suggest `/pbr:begin` 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.

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

@@ -1,7 +1,7 @@
 ---
 name: todo
 description: "File-based persistent todos. Add, list, complete — survives sessions."
-allowed-tools: Read, Write, Bash, Glob, Grep, Skill
+allowed-tools: Read, Write, Bash, Glob, Grep, Skill, AskUserQuestion
 argument-hint: "add <description> | list [theme] | done <NNN> | work <NNN>"
 ---
 
@@ -187,17 +187,38 @@ Todo {NNN} not found in pending todos.
 2. If not found, display the same error block as `done` — suggest `/pbr:todo list`
 3. Read the todo file content (frontmatter + body)
 4. Extract the `title` from frontmatter and the full body (Goal, Scope, Acceptance Criteria sections)
-5. Display branded output:
+
+5. **Assess complexity** to choose the right skill. Evaluate the todo content against these criteria:
+
+| Signal | Route to |
+|--------|----------|
+| Single file change, small fix, simple addition | `/pbr:quick` |
+| Multiple acceptance criteria, multi-file scope, architectural decisions, needs research | `/pbr:plan` (requires an active phase) |
+| Investigation needed, unclear root cause | `/pbr:debug` |
+| Open-ended exploration, no clear deliverable | `/pbr:explore` |
+
+If unsure, ask the user via AskUserQuestion:
+```
+Todo {NNN} could be handled as a quick task or may need full planning.
+
+Which approach?
+- Quick task (/pbr:quick) — single executor, atomic commit
+- Full planning (/pbr:plan) — research, plan, build cycle
+- Debug (/pbr:debug) — systematic investigation
+- Explore (/pbr:explore) — open-ended investigation
+```
+
+6. Display branded output:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  PLAN-BUILD-RUN ► WORKING ON TODO {NNN}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 **Todo {NNN}:** {title}
-
-Launching /pbr:quick with todo context...
+**Routing to:** /pbr:{chosen-skill}
 ```
-6. Invoke the Skill tool: `skill: "pbr:quick"` with `args` set to the todo title followed by the body content. Format the args as:
+
+7. Invoke the chosen skill via the Skill tool, passing the todo title and body as args:
 
 ```
 {title}
@@ -206,7 +227,9 @@ Context from todo {NNN}:
 {body content — Goal, Scope, Acceptance Criteria sections}
 ```
 
-This hands off execution to `/pbr:quick`, which will spawn an executor agent, make atomic commits, and track the work. When quick completes, remind the user:
+For `/pbr:plan`, if no phase exists for this work yet, suggest the user run `/pbr:plan add` first to create one, then re-run `/pbr:todo work {NNN}`.
+
+8. When the skill completes, remind the user:
 
 ```
 ───────────────────────────────────────────────────────────────