@sienklogic/plan-build-run 2.21.1 → 2.21.2

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

@@ -23,23 +23,36 @@ Then proceed to Step 1.
 
 You are running the **explore** skill. Your job is to help the user think through ideas that might become a todo, requirement, phase, decision, or nothing yet. This is Socratic conversation, not requirements gathering. No phase number is needed.
 
-This skill runs **inline** (no Task delegation), with optional Task() spawns for context loading and mid-conversation research.
+This skill runs **inline** (no Task delegation), with optional Task() spawns for context loading, upfront research, and mid-conversation research.
+
+**CRITICAL: Agent type rule** — When spawning ANY research or analysis Task(), ALWAYS use `subagent_type: "pbr:researcher"`. NEVER use `general-purpose`, `Explore`, or other non-PBR agent types. The PreToolUse hook will block non-PBR agents.
+
+---
+
+## References
+
+- `references/questioning.md` — Questioning philosophy, progressive depth layers, Socratic patterns, anti-patterns (checklist walking, corporate speak)
+- `references/ui-brand.md` — Status symbols, banners, checkpoint boxes, progress display
 
 ---
 
 ## Context Budget
 
 Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+Reference: `skills/shared/agent-type-resolution.md` for agent type fallback when spawning Task() subagents.
 
 Additionally for this skill:
 - **Minimize** file reads — this is a thinking skill, not a code analysis skill
-- **Delegate** deep research to a researcher subagent if investigation exceeds 3-4 file reads
+- **Delegate** deep research to a researcher subagent if investigation exceeds the read threshold:
+  - At context_window_tokens < 500000 (200k model): delegate after 3-4 file reads
+  - At context_window_tokens >= 500000 (1M model): delegate after 12 file reads
+  Check `context_window_tokens` in `.planning/config.json` to determine which limit applies.
 
 ---
 
-## How /pbr:explore Differs from /pbr:discuss
+## How /pbr:explore Differs from /pbr:discuss-phase
 
-| | /pbr:discuss | /pbr:explore |
+| | /pbr:discuss-phase | /pbr:explore |
 |---|---|---|
 | Purpose | Make decisions for a phase | Discover what you actually want |
 | Structure | Pre-computed gray areas with options | Open-ended Socratic conversation |
@@ -105,10 +118,36 @@ Reference `skills/shared/domain-probes.md` for technology-specific follow-up que
 
 ---
 
+## Upfront Research Delegation
+
+When the user's initial request is research-heavy (e.g., "explore best practices for X", "research how other projects do Y", "compare approaches to Z"), delegate immediately to `pbr:researcher` agents rather than doing inline research.
+
+**Detection**: If `$ARGUMENTS` contains words like "research", "compare", "explore examples", "best practices", "how do others", or describes gathering external information — this is an upfront research task.
+
+**Pattern**: Spawn one or more `pbr:researcher` agents in parallel, then synthesize their findings inline:
+
+```
+Task({
+  subagent_type: "pbr:researcher",
+  prompt: "<research_assignment>
+    Topic: {specific research question from user's request}
+    Output: Return findings as structured markdown in your response.
+    Mode: external-research
+
+    {detailed research instructions}
+  </research_assignment>"
+})
+```
+
+After researchers complete, synthesize findings inline and continue the Socratic conversation with the user about what was discovered.
+
+---
+
 ## Mid-Conversation Research
 
 When a knowledge gap emerges during the conversation — you're unsure about a library, pattern, or approach — surface it explicitly.
 
+**CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
 **Ask the user** using the **yes-no** pattern from `skills/shared/gate-prompts.md`:
   question: "I'm not sure about the best approach for {topic}. Research it now?"
   options:
@@ -117,14 +156,33 @@ When a knowledge gap emerges during the conversation — you're unsure about a l
 
 **If research now:**
 
-Display to the user: `◐ Spawning researcher...`
+Display to the user: `◆ Spawning researcher...`
+
+**Learnings injection (opt-in):** Check for relevant tech stack learnings:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js learnings query --tags "stack,tech,friction" 2>/dev/null
+```
+
+If non-empty JSON array returned:
+
+- Write to temp file: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js learnings query --tags "stack,tech,friction" > /tmp/pbr-learnings-$$.md`
+- Note path as `{learnings_temp_path}`; add as item 3 in the researcher's `files_to_read` block below
+
+If no learnings or command fails: omit the extra files_to_read entry.
 
 ```
 Task({
   subagent_type: "pbr:researcher",
-  prompt: "<research_assignment>
+  prompt: "<files_to_read>
+    CRITICAL: Read these files BEFORE any other action:
+    1. .planning/CONTEXT.md — locked decisions and constraints (if exists)
+    2. .planning/STATE.md — current project state (if exists)
+    {if learnings_temp_path exists}3. {learnings_temp_path} — cross-project learnings (tech stack patterns from past PBR projects){/if}
+  </files_to_read>
+  <research_assignment>
     Topic: {specific research question}
-    Output file: .planning/research/{topic-slug}.md
+    Output file: .planning/research/{topic-slug}.md (generate topic-slug via: node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js slug-generate "{topic}")
     Mode: project-research
 
     Research this specific question: {the question}
@@ -134,7 +192,15 @@ Task({
 })
 ```
 
-After the researcher completes, display: `✓ Research complete — results in .planning/research/{topic-slug}.md`
+If `{learnings_temp_path}` was produced above, replace `{if...}{/if}` with the actual line. If no learnings were found, omit item 3 entirely.
+
+After the researcher completes, check for completion markers in the Task() output:
+
+- If `## RESEARCH COMPLETE` is present: proceed normally
+- If `## RESEARCH BLOCKED` is present: display the blocker reason and offer to retry:
+  `⚠ Research blocked: {reason}. Try a different angle or continue without research.`
+
+Display: `✓ Research complete — results in .planning/research/{topic-slug}.md`
 
 Then:
 - Read ONLY the frontmatter and summary section of the research file (not the full document)
@@ -196,6 +262,7 @@ Want to adjust, add, or remove any of these?
 
 ### Step 3: Confirm
 
+**CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
 Use the **output-routing** pattern from `skills/shared/gate-prompts.md`:
   question: "How do you want to handle these proposed outputs?"
 
@@ -209,6 +276,8 @@ Do NOT create any artifacts until the user selects "Approve all" on the final se
 
 ### Step 4: Create Artifacts
 
+**CRITICAL (no hook) -- DO NOT SKIP: Create target directories and write artifact files.**
+
 **Directory creation:** Before writing any artifact, ensure the target directory exists. Create `.planning/notes/`, `.planning/seeds/`, `.planning/research/`, or `.planning/todos/pending/` as needed if they don't already exist.
 
 Create only the approved artifacts. A single explore session can produce multiple outputs across different types.
@@ -234,11 +303,11 @@ After creating artifacts (or if user chose "Skip"), display:
 
 {Smart routing — pick the most relevant primary command:}
 - If a todo was created: **Manage tasks** → `/pbr:todo`
-- If a phase decision was captured: **Plan the phase** → `/pbr:plan {N}`
-- If a new phase was added: **Discuss the new phase** → `/pbr:discuss {N}`
-- If research questions were logged: **Plan with research** → `/pbr:plan {N}`
-- If current milestone is complete (STATE.md status is "milestone-complete"): **Start next milestone** → `/pbr:milestone new`
-- Default: **See project status** → `/pbr:status`
+- If a phase decision was captured: **Plan the phase** → `/pbr:plan-phase {N}`
+- If a new phase was added: **Discuss the new phase** → `/pbr:discuss-phase {N}`
+- If research questions were logged: **Plan with research** → `/pbr:plan-phase {N}`
+- If current milestone is complete (STATE.md status is "milestone-complete"): **Start next milestone** → `/pbr:new-milestone`
+- Default: **See project status** → `/pbr:progress`
 
 `{primary command}`
 
@@ -247,9 +316,9 @@ After creating artifacts (or if user chose "Skip"), display:
 
 
 **Also available:**
-- `/pbr:status` — see project status
+- `/pbr:progress` — see project status
 - `/pbr:continue` — execute next logical step
-- `/pbr:milestone new` — start a new milestone with new phases
+- `/pbr:new-milestone` — start a new milestone with new phases
 
 
 ```
@@ -260,7 +329,9 @@ After creating artifacts (or if user chose "Skip"), display:
 
 ### Todo
 
-Write to `.planning/todos/pending/{NNN}-{slug}.md` where NNN is a zero-padded 3-digit sequential number (001, 002, 003...). Scan both `.planning/todos/pending/` and `.planning/todos/done/` for the highest existing number, increment by 1, and zero-pad. Follow the format used by the existing todo skill.
+**CRITICAL: Write the todo file NOW. Do not skip this step.**
+
+Write to `.planning/todos/pending/{NNN}-{slug}.md` where NNN is a zero-padded 3-digit sequential number (001, 002, 003...). Scan both `.planning/todos/pending/` and `.planning/todos/done/` for the highest existing number, increment by 1, and zero-pad. Generate slug via CLI: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js slug-generate "{todo title}"`. Follow the format used by the existing todo skill.
 
 ### Requirement
 
@@ -294,7 +365,9 @@ Append to `.planning/ROADMAP.md` following the existing phase format. Assign the
 
 ### Note
 
-Write to `.planning/notes/{YYYY-MM-DD}-{slug}.md` where the date prefix is today's date in ISO format. Scan `.planning/notes/` to avoid filename collisions — if a file with the same date and slug exists, append `-2` (or increment).
+**CRITICAL: Write the note file NOW. Do not skip this step.**
+
+Write to `.planning/notes/{YYYY-MM-DD}-{slug}.md` where the date prefix is today's date in ISO format. Generate slug via CLI: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js slug-generate "{note title}"`. Scan `.planning/notes/` to avoid filename collisions — if a file with the same date and slug exists, append `-2` (or increment).
 
 ```markdown
 ---
@@ -309,7 +382,9 @@ topic: "{topic}"
 
 ### Seed
 
-Write to `.planning/seeds/SEED-{NNN}-{slug}.md` where NNN is a zero-padded 3-digit sequential number (001, 002, 003...). Scan `.planning/seeds/` for the highest existing SEED number, increment by 1, and zero-pad.
+**CRITICAL: Write the seed file NOW. Do not skip this step.**
+
+Write to `.planning/seeds/SEED-{NNN}-{slug}.md` where NNN is a zero-padded 3-digit sequential number (001, 002, 003...). Scan `.planning/seeds/` for the highest existing SEED number, increment by 1, and zero-pad. Generate slug via CLI: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js slug-generate "{seed title}"`.
 
 ```markdown
 ---
@@ -347,6 +422,8 @@ Stage only the files created during this session. Do not stage unrelated changes
 
 ## Error Handling
 
+Reference: `skills/shared/error-reporting.md` for branded error output patterns.
+
 ### Researcher agent fails
 If a mid-conversation researcher Task() fails, display:
 ```
@@ -368,8 +445,6 @@ If the briefing Task() fails:
 
 ## Anti-Patterns
 
-Reference: `skills/shared/universal-anti-patterns.md` for rules that apply to ALL skills.
-
 Additionally for this skill:
 
 1. **DO NOT** act like an interviewer — be a thinking partner

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

@@ -0,0 +1,94 @@
+---
+name: fast
+description: "Execute a trivial task inline without subagent overhead. No planning, no research — just do it and commit."
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+argument-hint: "<task description>"
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it.**
+
+# /pbr:fast — Inline Trivial Task Execution
+
+Execute a trivial task directly in the current context. No subagents, no PLAN.md, no research. For tasks like: fix a typo, update a config value, add a missing import, rename a variable, add a .gitignore entry, bump a version.
+
+Use `/pbr:quick` for anything needing multi-step planning, research, or verification.
+
+## Step 0 — Banner
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► FAST                                       ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+## Step 1 — Parse Task
+
+If `$ARGUMENTS` is empty, ask: "What's the quick fix? (one sentence)"
+
+Store as the task description.
+
+## Step 2 — Scope Check
+
+A task is trivial if it needs:
+- 3 or fewer file edits
+- No new dependencies or architecture changes
+- No research needed
+
+If the task seems non-trivial, say:
+
+```
+This looks like it needs planning. Use /pbr:quick instead:
+  /pbr:quick "{task description}"
+```
+
+And stop.
+
+## Step 3 — Execute Inline
+
+Do the work directly:
+
+1. Read the relevant file(s)
+2. Make the change(s) using Edit or Write
+3. Verify the change works (run existing tests if applicable)
+
+**No PLAN.md. No Task() spawn. Just do it.**
+
+## Step 4 — Commit
+
+Stage specific files (NEVER `git add .`) and commit:
+
+```bash
+git add {specific files}
+git commit -m "{type}(fast): {concise description}"
+```
+
+Use conventional commit types: fix, feat, docs, chore, refactor as appropriate.
+
+## Step 5 — Log to Quick Tasks
+
+If `.planning/quick/` exists, create a minimal tracking entry:
+
+1. Find next NNN: scan `.planning/quick/` for highest existing number + 1
+2. Create `.planning/quick/{NNN}-fast-{slug}/PLAN.md` with a one-line plan
+3. Create `.planning/quick/{NNN}-fast-{slug}/SUMMARY.md` with the commit hash and description
+
+This ensures fast tasks appear in state tracking alongside quick tasks.
+
+## Step 6 — Report
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  FAST ✓                                                      ║
+╚══════════════════════════════════════════════════════════════╝
+
+{commit hash} — {commit message}
+Files: {changed files}
+```
+
+## Anti-Patterns
+
+1. DO NOT spawn a Task() — fast mode is inline only
+2. DO NOT create elaborate plans — this is for trivial changes
+3. DO NOT use `git add .` — stage specific files
+4. DO NOT use fast mode for multi-file refactors — suggest `/pbr:quick`
+5. DO NOT skip the commit — every change gets committed

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

@@ -0,0 +1,144 @@
+---
+name: forensics
+description: "Post-mortem investigation for failed or stuck workflows. Analyzes git history and planning artifacts."
+allowed-tools: Read, Bash, Glob, Grep, Write, AskUserQuestion
+argument-hint: "[description of what went wrong]"
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it.**
+
+# /pbr:forensics — Post-Mortem Investigation
+
+Read-only investigation for failed or stuck workflows. Analyzes git history, `.planning/` artifacts, and file system state to detect anomalies. Writes a diagnostic report. Does NOT modify project files.
+
+## Step 0 — Banner
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► FORENSICS                                  ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+## Step 1 — Get Problem Description
+
+If `$ARGUMENTS` is empty, ask: "What went wrong? Describe the issue — e.g., 'autonomous mode got stuck on phase 3', 'execute-phase failed silently', 'commits seem wrong'."
+
+## Step 2 — Gather Evidence
+
+Collect data from all available sources. Missing sources are fine — adapt.
+
+### 2a. Git History
+
+```bash
+git log --oneline -30
+git log --format="%H %ai %s" -30
+git log --name-only --format="" -20 | sort | uniq -c | sort -rn | head -20
+git status --short
+git diff --stat
+```
+
+Record: commit timeline, most-edited files, uncommitted changes.
+
+### 2b. Planning State
+
+Read if they exist: STATE.md, ROADMAP.md, config.json. Extract current phase, last session, blockers.
+
+### 2c. Phase Artifacts
+
+For each phase in `.planning/phases/*/`, check which artifacts exist vs expected (PLAN, SUMMARY, VERIFICATION, CONTEXT, RESEARCH).
+
+### 2d. Worktree State
+
+```bash
+git worktree list
+```
+
+Check for orphaned worktrees from crashed agents.
+
+## Step 3 — Detect Anomalies
+
+### Stuck Loop Detection
+Same file in 3+ consecutive commits within a short time window. HIGH confidence if commit messages are similar.
+
+### Missing Artifact Detection
+Phase appears complete (has commits, past in roadmap) but lacks PLAN, SUMMARY, or VERIFICATION.
+
+### Abandoned Work Detection
+Large gap between last commit and now, with STATE.md showing mid-execution.
+
+### Crash/Interruption Detection
+Uncommitted changes + STATE.md active + orphaned worktrees.
+
+### Scope Drift Detection
+Recent commits touch files outside current phase's expected scope (from PLAN.md).
+
+### Test Regression Detection
+Commit messages containing "fix test", "revert", or re-commits of test files.
+
+## Step 4 — Generate Report
+
+```bash
+mkdir -p .planning/forensics
+```
+
+Write to `.planning/forensics/report-{YYYYMMDD-HHMMSS}.md`:
+
+```markdown
+# Forensic Report
+
+**Generated:** {ISO timestamp}
+**Problem:** {user's description}
+
+## Evidence Summary
+
+### Git Activity
+- **Last commit:** {date} — "{message}"
+- **Commits (last 30):** {count}
+- **Uncommitted changes:** {yes/no}
+- **Active worktrees:** {count}
+
+### Planning State
+- **Current phase:** {N} — {name} ({status})
+- **Last session:** {date}
+- **Blockers:** {list or "none"}
+
+### Artifact Completeness
+| Phase | PLAN | SUMMARY | VERIFICATION | Status |
+|-------|------|---------|-------------|--------|
+| {N} | {Y/N} | {Y/N} | {Y/N} | {complete/incomplete} |
+
+## Anomalies Detected
+
+### {Anomaly Name}
+**Confidence:** {HIGH/MEDIUM/LOW}
+**Evidence:** {specific data points}
+**Impact:** {what this caused}
+**Recommendation:** {what to do}
+
+## Recommendations
+
+1. {Prioritized action items}
+```
+
+## Step 5 — Present Findings
+
+Display a summary of findings inline, point to the full report on disk:
+
+```
+Report: .planning/forensics/report-{timestamp}.md
+
+Anomalies found: {count}
+  - {anomaly 1}: {brief}
+  - {anomaly 2}: {brief}
+
+Recommended: {top action item}
+```
+
+Optionally offer to create a GitHub issue with the findings.
+
+## Anti-Patterns
+
+1. DO NOT modify project files — forensics is read-only
+2. DO NOT spawn subagents — run everything inline
+3. DO NOT guess — base all findings on evidence
+4. DO NOT report anomalies without evidence and confidence levels