@sienklogic/plan-build-run 2.21.1 → 2.21.2

package/plugins/pbr/skills/plan/templates/checker-prompt.md.tmpl

@@ -11,11 +11,29 @@ Read and check each of these plan files:
 {For each PLAN.md file in .planning/phases/{NN}-{slug}/:}
 | {plan_id} | {absolute path to PLAN.md} |
 
-Read each plan file using the Read tool. Verify all 7 dimensions against each plan.
+Read each plan file using the Read tool. Verify all 9 dimensions against each plan.
 </plans_to_check>
 
 <!-- Context blocks: Read and fill templates/prompt-partials/phase-project-context.md.tmpl -->
 <!-- Omit <prior_work> -- checker only needs plans and context -->
 
-Run all 7 verification dimensions on these plans. Return your structured report.
+Run all 9 verification dimensions on these plans. Return issues in YAML format under a `## Issues` heading. Each issue must have: dimension, severity, finding, affected_field, suggested_fix.
+
+<plan_depth_check>
+Plan depth mode: {plan_depth from config}
+{If plan_depth is "high-level":}
+ADDITIONAL CHECK — Over-Specification Detection:
+For each task's &lt;action&gt; block, flag as WARNING if it contains:
+- Code keywords: const, let, function, class, interface, type, import, export
+- Fenced code blocks (triple backticks)
+- More than 8 numbered implementation steps
+- Specific library API calls (e.g., X.method(), import X from Y)
+Format: "WARNING: Over-specification in task {id}: &lt;action&gt; contains {pattern}. High-level mode expects deliverable descriptions, not implementation details."
+These are WARNINGs, not BLOCKERs — the planner may have valid reasons for specificity.
+{If plan_depth is "detailed":}
+No over-specification check in detailed mode.
+</plan_depth_check>
+
+If all dimensions pass, return `## CHECK PASSED` with no issues block.
+
 Do NOT write any files. Return your findings as your response text.

package/plugins/pbr/skills/plan/templates/completion-output.md.tmpl

@@ -0,0 +1,27 @@
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PLANNING PHASE {N} ✓                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Phase {N}: {phase-name}** — {plan_count} plans created
+
+Plans:
+{plan_list_lines}
+
+Wave execution:
+{wave_table_lines}
+
+---
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Build Phase {N}** — execute these plans
+
+/pbr:execute-phase {N}
+
+<sub>/clear first → fresh context window</sub>
+
+**Also available:**
+- /pbr:plan-phase {N} --assumptions — review assumptions first
+- /pbr:discuss-phase {N} — talk through details before building

package/plugins/pbr/skills/plan/templates/planner-prompt.md.tmpl

@@ -19,8 +19,24 @@ Research summary available at: {absolute path to research SUMMARY.md}
 Max tasks per plan: {from config.json}
 Parallelization enabled: {from config.json}
 TDD mode: {from config.json}
+Plan depth: {plan_depth from config, default "detailed"}
 </config>
 
+<plan_depth>
+{If plan_depth is "high-level":}
+MODE: HIGH-LEVEL PLANS
+Write plans that describe WHAT to deliver, not HOW to implement.
+- &lt;action&gt; = deliverables, behavioral requirements, integration points, error handling expectations
+- &lt;action&gt; must NOT specify: internal variable names, exact function signatures, line-by-line implementation steps, specific library API calls, code snippets
+- &lt;action&gt; SHOULD specify: module responsibilities, constraints, data flow boundaries
+- &lt;files&gt; = approximate scope (key files or directories), executor determines exact files
+- &lt;verify&gt;, &lt;acceptance_criteria&gt;, &lt;done&gt; = REMAIN FULLY SPECIFIC — these steer the executor
+- must_haves = REMAIN FULLY SPECIFIED — these are the verification contract
+{If plan_depth is "detailed":}
+MODE: DETAILED PLANS (default)
+Write plans with file paths, function names, and exact implementation steps. The executor follows mechanically.
+</plan_depth>
+
 <planning_instructions>
 Create executable plans for this phase following your Standard Planning mode instructions.
 
@@ -28,7 +44,7 @@ Key rules:
 1. Apply goal-backward methodology — derive must-haves first
 2. 2-3 tasks per plan, 5-8 files per plan maximum
 3. Assign wave numbers for parallel execution
-4. Every task needs all 5 elements: name, files, action, verify, done
+4. Every task needs all 7 elements (see deep_work_rules below)
 5. Honor all locked decisions from CONTEXT.md
 6. Do NOT include deferred ideas
 7. Write plan files to: .planning/phases/{NN}-{slug}/PLAN-{plan_num}.md
@@ -36,3 +52,29 @@ Key rules:
 
 Use the Write tool to create each plan file.
 </planning_instructions>
+
+<deep_work_rules>
+CRITICAL — These rules are NON-NEGOTIABLE. Plans that violate them will be rejected by the plan-checker.
+
+**Every task MUST include ALL 7 elements — they are NOT optional:**
+
+1. `<name>` — Imperative verb phrase describing the task
+2. `<read_first>` — Files the executor MUST read before editing. Specific paths only, NO globs. At minimum, list the files from `<files>` that already exist on disk.
+3. `<files>` — All files this task creates or modifies (commit scope)
+4. `<action>` — Numbered implementation steps with CONCRETE values. The executor should be able to complete the task from the action text alone, without needing to re-read CONTEXT.md or research docs. Do NOT write vague actions like "align X with Y" or "implement per best practices" — specify exactly what to do.
+5. `<acceptance_criteria>` — Grep-verifiable conditions. Each criterion must be a shell command returning 0 (pass) or non-0 (fail). Example: `grep -q "export class AuthService" src/auth/service.ts`
+6. `<verify>` — Runnable verification command (npm test, tsc --noEmit, curl, etc.)
+7. `<done>` — Observable outcome that proves the task is complete
+
+**Action quality rules:**
+- Actions must include CONCRETE file paths, function names, and values — not references to other documents
+- If the action says "create X", the `<files>` element must list the file being created
+- If the action says "use library Y", specify the import path and API calls
+- The executor has a FRESH context window — it only sees the plan file and files from `<read_first>`. Everything it needs must be IN the plan.
+
+**After writing each plan file**, validate it:
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js verify plan-structure "{plan_path}"
+```
+If `valid: false`, fix the errors before writing the next plan. Do NOT return `## PLANNING COMPLETE` with invalid plans.
+</deep_work_rules>

package/plugins/pbr/skills/plan/templates/revision-prompt.md.tmpl

@@ -1,7 +1,10 @@
 <!-- Source: plan/SKILL.md | Purpose: Prompt template for planner revision mode when checker finds issues -->
+<!-- Depends on: checker-prompt.md.tmpl (YAML issue format) -->
 
 You are the planner agent operating in Revision Mode.
 
+**Iteration context:** This is revision iteration {iteration} of max 3. Previous iteration had {prev_count} issues. You must reduce the issue count or the loop will terminate.
+
 <original_plans>
 Read the current plan files that need revision:
 
@@ -13,11 +16,24 @@ Read the current plan files that need revision:
 Read each plan file using the Read tool before revising.
 </original_plans>
 
-<checker_feedback>
-[Inline the checker's issue report]
-</checker_feedback>
+<checker_issues>
+The issues below are in YAML format. Each has: dimension, severity, finding, affected_field, suggested_fix. Address ALL BLOCKER issues. Address WARNING issues where feasible.
+
+```yaml
+{YAML issues block from plan-checker output — passed verbatim}
+```
+</checker_issues>
 
 <revision_instructions>
-Revise the plans to address all BLOCKER and WARNING issues. Follow your Revision Mode instructions.
-Preserve task IDs that don't need changes. Write updated plan files to the same paths.
+Revise the plans to address all BLOCKER and WARNING issues listed above.
+
+For each issue:
+- **BLOCKER**: Make the required change. These block execution.
+- **WARNING**: Address or explain why it is acceptable. Add a comment in the plan if deferring.
+
+Rules:
+- Preserve task IDs that don't need changes
+- Do NOT introduce new issues while fixing existing ones
+- Preserve all content not flagged by the checker
+- Write updated plan files to the same paths
 </revision_instructions>

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

@@ -0,0 +1,185 @@
+---
+name: profile
+description: "Switch the active model profile. Presets: quality, balanced, budget, adaptive. Supports custom profiles from config.json model_profiles."
+allowed-tools: Read, Write, Bash, AskUserQuestion
+argument-hint: "[quality|balanced|budget|adaptive|<custom>]"
+---
+
+**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`.
+
+Reference: `@references/model-profile-resolution.md` for profile resolution logic and precedence rules.
+
+## 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.
+```
+
+### Commit Changes
+
+Reference: `skills/shared/commit-planning-docs.md` for the commit pattern.
+
+If `planning.commit_docs` is true in config.json, commit config.json:
+
+```text
+docs(profile): switch to {profile_name} model profile
+```
+
+Stop. Done.

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

@@ -0,0 +1,227 @@
+---
+name: profile-user
+description: "Analyze Claude Code session history to generate a developer behavioral profile across 8 dimensions."
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+argument-hint: "[--sessions N]"
+---
+
+**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 tokens. Begin executing Step 0 immediately.**
+
+## Step 0 -- Banner
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► USER PROFILE                              ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+# /pbr:profile-user -- Developer Behavioral Profiling
+
+You are running the **profile-user** skill. Your job is to analyze the user's Claude Code session history across 8 behavioral dimensions and generate a `.planning/USER-PROFILE.md` file with actionable insights. If insufficient session data exists, fall back to a short interactive questionnaire.
+
+---
+
+## Step 1 -- Config Gate
+
+Check if the developer profiling feature is enabled:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config get developer_profile.enabled
+```
+
+- If the result is `false`, empty, or the key is missing: tell the user to enable it first with `/pbr:config set developer_profile.enabled true` and **STOP**.
+- If `true`: proceed to Step 2.
+
+---
+
+## Step 2 -- Locate Session Logs
+
+Find the Claude Code session log directory for this project:
+
+```bash
+# List ~/.claude/projects/ to find the encoded project path
+ls -la ~/.claude/projects/
+```
+
+The directory name is the project root path with path separators replaced by `-`. For example, `D:\Repos\plan-build-run` becomes something like `D--Repos-plan-build-run` or `D-Repos-plan-build-run`.
+
+Once found, list JSONL files sorted by modification time:
+
+```bash
+ls -lt ~/.claude/projects/{encoded-path}/*.jsonl 2>/dev/null | head -20
+```
+
+Count the files that are larger than 1KB:
+
+```bash
+find ~/.claude/projects/{encoded-path}/ -name "*.jsonl" -size +1k 2>/dev/null | wc -l
+```
+
+---
+
+## Step 3 -- Analysis or Fallback Decision
+
+- If **>= 3** session JSONL files found (each > 1KB): proceed to **Step 4** (session analysis mode).
+- If **< 3** usable session files: proceed to **Step 5** (questionnaire fallback).
+
+---
+
+## Step 4 -- Session Analysis Mode
+
+Read the **5 most recent** session JSONL files. For each file, parse the JSON lines and extract behavioral signals.
+
+### What to look for
+
+For each session, scan `type: "human"` messages (user inputs) and `type: "assistant"` messages (responses) to detect patterns:
+
+1. **Communication style** -- Are user messages terse (1-2 words, commands) or detailed (paragraphs with context)? Do they use technical jargon freely?
+2. **Decision speed** -- When presented with options or checkpoints, how quickly does the user respond? Do they accept suggestions or counter-propose alternatives?
+3. **Debugging approach** -- When errors occur, does the user provide stack traces, ask for root cause analysis, or direct Claude to specific files?
+4. **UX philosophy** -- Does the user focus on functionality first, or request UI polish, formatting, and user-facing details early?
+5. **Code style** -- Does the user request tests, mention linting, prefer functional vs OOP patterns, ask for type safety?
+6. **Review thoroughness** -- Does the user examine diffs carefully, request changes, or approve quickly?
+7. **Risk tolerance** -- Does the user approve force operations, skip verification steps, use `--auto` flags?
+8. **Domain expertise** -- What technologies, frameworks, and languages appear most frequently?
+
+### Scoring
+
+Score each dimension on a 3-point scale:
+
+| Dimension | Low | Medium | High |
+|-----------|-----|--------|------|
+| Communication style | terse | balanced | detailed |
+| Decision speed | fast | measured | deliberate |
+| Debugging approach | delegation | intuitive | systematic |
+| UX philosophy | function-first | balanced | polish-first |
+| Code style | pragmatic | balanced | perfectionist |
+| Review thoroughness | light | standard | deep |
+| Risk tolerance | conservative | moderate | adventurous |
+| Domain expertise | (list top 3-5 domains) | | |
+
+After scoring, proceed to **Step 6**.
+
+---
+
+## Step 5 -- Questionnaire Fallback
+
+When insufficient session data is available, use `AskUserQuestion` to ask these 4 questions **one at a time**:
+
+**Question 1:**
+> How do you prefer Claude to communicate?
+> (a) Brief and direct
+> (b) Balanced -- concise but with enough context
+> (c) Detailed with thorough explanations
+
+**Question 2:**
+> When you encounter a bug, do you prefer to:
+> (a) Get a fix immediately -- just make it work
+> (b) Understand the root cause first, then fix
+> (c) Have Claude investigate and report back before changing anything
+
+**Question 3:**
+> How important is code quality vs shipping speed?
+> (a) Ship fast, refactor later
+> (b) Balance both -- good enough quality, reasonable speed
+> (c) Quality first, take the time needed
+
+**Question 4:**
+> What is your primary domain? (e.g., backend, frontend, DevOps, data, mobile, full-stack)
+
+### Mapping answers to dimensions
+
+| Answer | Dimension mappings |
+|--------|-------------------|
+| Q1=a | communication_style: terse, review_thoroughness: light |
+| Q1=b | communication_style: balanced, review_thoroughness: standard |
+| Q1=c | communication_style: detailed, review_thoroughness: deep |
+| Q2=a | debugging_approach: delegation, decision_speed: fast |
+| Q2=b | debugging_approach: systematic, decision_speed: measured |
+| Q2=c | debugging_approach: systematic, decision_speed: deliberate |
+| Q3=a | code_style: pragmatic, risk_tolerance: adventurous, ux_philosophy: function-first |
+| Q3=b | code_style: balanced, risk_tolerance: moderate, ux_philosophy: balanced |
+| Q3=c | code_style: perfectionist, risk_tolerance: conservative, ux_philosophy: balanced |
+| Q4 | domain_expertise: [user's answer] |
+
+After mapping, proceed to **Step 6**.
+
+---
+
+## Step 6 -- Generate USER-PROFILE.md
+
+**CRITICAL: Write USER-PROFILE.md NOW. Do not skip this step.**
+
+Write `.planning/USER-PROFILE.md` with the following structure:
+
+```yaml
+---
+generated: "{ISO date from node -e 'console.log(new Date().toISOString())'}"
+source: "session-analysis" or "questionnaire"
+sessions_analyzed: {N, or 0 for questionnaire}
+dimensions:
+  communication_style: "{terse|balanced|detailed}"
+  decision_speed: "{fast|measured|deliberate}"
+  debugging_approach: "{delegation|intuitive|systematic}"
+  ux_philosophy: "{function-first|balanced|polish-first}"
+  code_style: "{pragmatic|balanced|perfectionist}"
+  review_thoroughness: "{light|standard|deep}"
+  risk_tolerance: "{conservative|moderate|adventurous}"
+  domain_expertise: ["{domain1}", "{domain2}"]
+---
+```
+
+After the frontmatter, write a **body section** with 1-2 sentences per dimension explaining:
+- What was observed (or what the user selected)
+- How this should affect agent behavior
+
+Example body format:
+
+```markdown
+## Communication Style: balanced
+
+You communicate with a mix of brief directives and contextual detail. Agents should
+match this style -- provide enough explanation to be useful but avoid over-explaining
+concepts you clearly understand.
+
+## Decision Speed: measured
+
+You take time to evaluate options before committing. Agents should present choices
+clearly and wait for your input rather than assuming a default.
+
+(... one section per dimension ...)
+```
+
+---
+
+Reference: `skills/shared/commit-planning-docs.md` -- if `planning.commit_docs` is true, commit USER-PROFILE.md.
+
+---
+
+## Step 7 -- Summary Output
+
+After writing `USER-PROFILE.md`, display a summary table:
+
+```
+Profile generated: .planning/USER-PROFILE.md
+Source: {session-analysis|questionnaire}
+
+| Dimension            | Value          |
+|----------------------|----------------|
+| Communication style  | {value}        |
+| Decision speed       | {value}        |
+| Debugging approach   | {value}        |
+| UX philosophy        | {value}        |
+| Code style           | {value}        |
+| Review thoroughness  | {value}        |
+| Risk tolerance       | {value}        |
+| Domain expertise     | {domains}      |
+
+Run /pbr:profile-user again at any time to regenerate your profile
+with updated session data.
+```
+
+If `developer_profile.inject_prompts` is enabled in config, also note:
+> Profile dimensions will be injected into agent prompts for personalized communication.