@sienklogic/plan-build-run 2.1.0 → 2.1.1

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

@@ -12,9 +12,9 @@ argument-hint: "[topic]"
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► EXPLORING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► EXPLORING                                  ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -23,7 +23,16 @@ 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
 
 ---
 
@@ -33,13 +42,16 @@ Reference: `skills/shared/context-budget.md` for the universal orchestrator rule
 
 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,6 +117,31 @@ 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.
@@ -117,12 +154,31 @@ 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 {resolved_plugin_root}/scripts/pbr-tools.js learnings query --tags "stack,tech" 2>/dev/null
+```
+
+If non-empty JSON array returned:
+
+- Write to temp file: `node {resolved_plugin_root}/scripts/pbr-tools.js learnings query --tags "stack,tech" > /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
     Mode: project-research
@@ -134,7 +190,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)
@@ -178,7 +242,7 @@ Suggest specific outputs with reasoning. Present no more than 4 suggestions —
 | Phase decision | Clarifies an existing phase | Write/append to phase `CONTEXT.md` |
 | Research question | Needs deeper investigation | `.planning/research/questions.md` |
 | New phase | Big enough for its own phase | Append to `ROADMAP.md` |
-| Note | Not actionable yet, worth remembering | `.planning/notes/{slug}.md` |
+| Note | Not actionable yet, worth remembering | `.planning/notes/{YYYY-MM-DD}-{slug}.md` |
 | Quick capture | One-liner idea, no context needed | Suggest `/pbr:note <text>` to the user |
 | Seed | Idea with trigger conditions | `.planning/seeds/SEED-{NNN}-{slug}.md` |
 
@@ -218,36 +282,40 @@ Create only the approved artifacts. A single explore session can produce multipl
 After creating artifacts (or if user chose "Skip"), display:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► EXPLORATION CAPTURED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► EXPLORATION CAPTURED ✓                     ║
+╚══════════════════════════════════════════════════════════════╝
 
 {count} artifacts created: {list of artifact types}
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **{Primary route based on what was created}**
 
 {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}`
-- 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}`
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
-- `/pbr:status` — see project status
+- `/pbr:progress` — see project status
 - `/pbr:continue` — execute next logical step
+- `/pbr:new-milestone` — start a new milestone with new phases
+
 
-───────────────────────────────────────────────────────────────
 ```
 
 ---
@@ -290,7 +358,7 @@ Append to `.planning/ROADMAP.md` following the existing phase format. Assign the
 
 ### Note
 
-Write to `.planning/notes/{NNN}-{slug}.md` where NNN is a zero-padded 3-digit sequential number (001, 002, 003...). Scan `.planning/notes/` for the highest existing number prefix, increment by 1, and zero-pad.
+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).
 
 ```markdown
 ---

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

@@ -1,7 +1,8 @@
 ---
 name: health
 description: "Check planning directory integrity. Find and fix corrupted state."
-allowed-tools: Read, Bash, Glob, Grep
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+argument-hint: "[--repair]"
 ---
 
 **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.**
@@ -11,26 +12,37 @@ allowed-tools: Read, Bash, Glob, Grep
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► HEALTH CHECK
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► HEALTH CHECK                               ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
 
 # /pbr:health — Planning Directory Diagnostics
 
-You are running the **health** skill. Your job is to validate the integrity of the `.planning/` directory, report problems, and suggest targeted fixes. You never auto-repair anything.
+You are running the **health** skill. Your job is to validate the integrity of the `.planning/` directory, report problems, and suggest targeted fixes.
+
+This skill runs **inline**. It is read-only by default, but offers an optional **auto-fix** flow for common corruption patterns (see the Auto-Fix section below).
+
+## References
 
-This skill runs **inline** and is **read-only** — it never modifies any files.
+- `references/questioning.md` — Questioning philosophy for diagnostic probing
+- `references/ui-brand.md` — Status symbols, banners, checkpoint boxes
+
+## Argument Parsing
+
+Check if the user passed `--repair`:
+- `--repair`: Skip the AskUserQuestion prompt in the Auto-Fix section and automatically apply ALL fixes (equivalent to selecting "Fix all"). Still create backups before any destructive operations.
+- No flag: Use the interactive AskUserQuestion flow as described below (default behavior).
 
 ---
 
 ## How Checks Work
 
-Each check follows the common pattern. Read `skills/health/templates/check-pattern.md.tmpl` for the shared execution flow: target files, validate against rules, classify as PASS/FAIL/WARN/INFO, and record the result with a fix suggestion for any failures.
+Each check follows the common pattern. Read `${CLAUDE_SKILL_DIR}/templates/check-pattern.md.tmpl` for the shared execution flow: target files, validate against rules, classify as PASS/FAIL/WARN/INFO, and record the result with a fix suggestion for any failures.
 
-Read `skills/health/templates/output-format.md.tmpl` for the output format: summary table, status indicators, issues list, optional recent decisions, and final result line.
+Read `${CLAUDE_SKILL_DIR}/templates/output-format.md.tmpl` for the output format: summary table, status indicators, issues list, optional recent decisions, and final result line.
 
 ---
 
@@ -50,11 +62,36 @@ Validate `.planning/` exists with required scaffolding: `STATE.md`, `config.json
 
 No .planning/ directory found.
 
-**To fix:** Run `/pbr:begin` to initialize.
+**To fix:** Run `/pbr:new-project` to initialize.
 ```
 Stop all further checks.
 - PASS: All three required files exist
-- FAIL: List each missing file — "Run `/pbr:begin` to re-initialize, or create the file manually."
+- FAIL: List each missing file — "Run `/pbr:new-project` to re-initialize, or create the file manually."
+
+**Advisory checks — WARN if missing, do not FAIL:**
+
+- `.planning/PROJECT.md`
+  If missing: `⚠ PROJECT.md not found. Run /pbr:new-project to generate it, or create from plugins/pbr/templates/PROJECT.md.tmpl.`
+  If present: Check for `## Context` section (merged from legacy CONTEXT.md). If missing: `⚠ PROJECT.md has no ## Context section. Run /pbr:new-project to regenerate, or add manually.`
+
+- `.planning/REQUIREMENTS.md`
+  If missing: `⚠ REQUIREMENTS.md not found. Run /pbr:new-project to generate it, or create from plugins/pbr/templates/REQUIREMENTS.md.tmpl.`
+
+**Merged state validation:**
+
+- `.planning/STATE.md` ## History section:
+  If STATE.md exists but has no `## History` section: `⚠ STATE.md has no ## History section. History will be tracked once a milestone completes.`
+
+- `.phase-manifest.json` for completed phases:
+  For each phase marked as verified/complete in ROADMAP.md, check if `.planning/phases/{NN}-{slug}/.phase-manifest.json` exists.
+  If missing: `⚠ Phase {N} has no .phase-manifest.json. Undo operations will fall back to git log scanning.`
+
+**Legacy file detection:**
+
+- If `.planning/CONTEXT.md` exists alongside `PROJECT.md` with `## Context` section: `⚠ Legacy CONTEXT.md detected alongside merged PROJECT.md. Run /pbr:new-project to migrate — the legacy file can be removed.`
+- If `.planning/HISTORY.md` exists alongside `STATE.md` with `## History` section: `⚠ Legacy HISTORY.md detected alongside merged STATE.md. Run /pbr:new-project to migrate — the legacy file can be removed.`
+
+These files are generated by /pbr:new-project. Absence is expected on projects created before v2.15.
 
 ### Check 2: Config Validity
 
@@ -80,7 +117,7 @@ Glob all `PLAN*.md` and `SUMMARY*.md` in `.planning/phases/`. Match by plan numb
 
 - PASS: All pairings valid, no orphaned summaries
 - FAIL (orphaned summary): SUMMARY has no matching PLAN — "Verify and remove or re-pair."
-- WARN (missing summary in complete phase): Phase marked complete but plan has no SUMMARY — "Execute with `/pbr:build` or mark phase incomplete."
+- WARN (missing summary in complete phase): Phase marked complete but plan has no SUMMARY — "Execute with `/pbr:execute-phase` or mark phase incomplete."
 
 ### Check 5: STATE.md Accuracy
 
@@ -128,9 +165,9 @@ Read `.planning/config.json` and check for fields referenced by skills:
 - `planning.commit_docs` (import, discuss, quick skills) — must be a boolean; validate that the value is strictly `true` or `false`, not a string or number
 
 - PASS: All expected fields present with correct types
-- WARN (missing fields): Report each missing field and which skill uses it — "Run `/pbr:config` to set all options."
+- WARN (missing fields): Report each missing field and which skill uses it — "Run `/pbr:settings` to set all options."
 
-### Check 10: Orphaned Crash Recovery Files
+### Check 10: Orphaned Crash Recovery & Lock Files
 
 The executor creates `.PROGRESS-{plan_id}` files as crash recovery breadcrumbs during builds and deletes them after `SUMMARY.md` is written. Similarly, `.checkpoint-manifest.json` files track checkpoint state during execution. If the executor crashes mid-build, these files remain and could confuse future runs.
 
@@ -142,13 +179,83 @@ Glob for `.planning/phases/**/.PROGRESS-*` and `.planning/phases/**/.checkpoint-
   Orphaned progress files detected:
   - .planning/phases/02-auth/.PROGRESS-02-01 (executor may have crashed)
   ```
-  Fix suggestion: "These are crash recovery breadcrumbs from interrupted builds. Safe to delete if no `/pbr:build` is currently running. Remove with `rm <path>`."
+  Fix suggestion: "These are crash recovery breadcrumbs from interrupted builds. Safe to delete if no `/pbr:execute-phase` is currently running. Remove with `rm <path>`."
 - WARN (orphaned checkpoint manifests): List each file:
   ```
   Orphaned checkpoint manifests detected:
   - .planning/phases/02-auth/.checkpoint-manifest.json (stale build checkpoint)
   ```
-  Fix suggestion: "Checkpoint manifests are leftover from interrupted builds. Safe to delete if no `/pbr:build` is currently running. Remove with `rm <path>`."
+  Fix suggestion: "Checkpoint manifests are leftover from interrupted builds. Safe to delete if no `/pbr:execute-phase` is currently running. Remove with `rm <path>`."
+
+Also check for `.planning/.active-skill`:
+
+- If the file does not exist: no action needed (PASS for this sub-check)
+- If the file exists, check its age by comparing the file modification time to the current time:
+  - If older than 1 hour: WARN with fix suggestion: "Stale .active-skill lock file detected (set {age} ago). No PBR skill appears to be running. Safe to delete with `rm .planning/.active-skill`."
+  - If younger than 1 hour: INFO: "Active skill lock exists ({content}). A PBR skill may be running."
+
+---
+
+## Auto-Fix for Common Corruption Patterns
+
+After running all 10 checks and collecting results, if any of the following auto-fixable issues were found, offer to fix them.
+
+### Auto-Fixable Patterns
+
+| Pattern | Detection | Fix Action |
+|---------|-----------|------------|
+| Missing STATE.md frontmatter | Check 5 finds STATE.md without `---` block | Regenerate frontmatter from ROADMAP.md phase data (current_phase, phase_slug, status) |
+| STATE.md phase_slug mismatch | Check 5/7 finds phase_slug doesn't match current phase directory name | Correct phase_slug to match the actual directory name in `.planning/phases/` |
+| Missing config.json | Check 1/2 finds no `.planning/config.json` | Create with default config template (same as `/pbr:setup` defaults) |
+| Orphaned .active-skill file | Check 10 or general scan finds `.planning/.active-skill` older than 1 hour | Delete the stale `.active-skill` file |
+| Empty phases directory | Check 3 finds `.planning/phases/` missing | Create the directory: `mkdir -p .planning/phases` |
+| STATE.md over 150 lines | Check 5 finds STATE.md exceeds 150 lines | Compact the `## Accumulated Context` section, keeping only the last 3 entries |
+
+### Auto-Fix Flow
+
+After displaying health check results, if any auto-fixable issues were detected:
+
+**CRITICAL — Before ANY auto-fix that modifies or regenerates STATE.md (frontmatter regeneration, phase_slug correction, or line compaction), you MUST create a timestamped backup first. DO NOT SKIP THIS STEP.**
+
+```
+mkdir -p .planning/backups
+cp .planning/STATE.md .planning/backups/STATE-$(date +%Y%m%dT%H%M%S).md
+```
+
+This ensures the user can recover the original STATE.md if the fix produces incorrect results.
+
+1. Count the auto-fixable issues.
+
+   **If `--repair` flag was passed**: Skip the question and go directly to "Fix all" (step 2). Display: "Auto-repair mode: applying {N} fixes..."
+
+   **Otherwise**: Present the choice:
+
+   Use AskUserQuestion:
+     question: "Found {N} auto-fixable issues. How should we handle them?"
+     header: "Fix?"
+     options:
+       - label: "Fix all"       description: "Apply all {N} fixes automatically"
+       - label: "Review each"   description: "Show each fix and confirm individually"
+       - label: "Skip"          description: "Do nothing — just report"
+
+2. If "Fix all" (or `--repair`): Apply all fixes in order, then display a summary:
+   ```
+   Auto-fix results:
+   - Fixed: {description of fix 1}
+   - Fixed: {description of fix 2}
+   ...
+   ```
+
+3. If "Review each": For each fixable issue, display:
+   ```
+   Issue: {description}
+   Fix: {what will be done}
+   ```
+   Then ask via AskUserQuestion (yes/no): "Apply this fix?"
+   - If yes: apply and display `- Fixed: {description}`
+   - If no: skip and display `- Skipped: {description}`
+
+4. If "Skip": Do nothing, continue to the rest of the output.
 
 ---
 
@@ -164,56 +271,60 @@ After all checks complete, display the branded result:
 
 **If all checks passed (0 failures):**
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► HEALTH CHECK PASSED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► HEALTH CHECK PASSED ✓                      ║
+╚══════════════════════════════════════════════════════════════╝
 
 {N} checks passed, {M} warnings
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Continue your workflow** — planning directory is healthy
 
-`/pbr:status`
+`/pbr:progress`
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:continue` — execute next logical step
-- `/pbr:config` — adjust settings
+- `/pbr:settings` — adjust settings
+
 
-───────────────────────────────────────────────────────────────
 ```
 
 **If failures found:**
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► HEALTH CHECK FAILED ⚠
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► HEALTH CHECK FAILED ⚠                      ║
+╚══════════════════════════════════════════════════════════════╝
 
 {N} checks passed, {F} failures, {M} warnings
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Fix the failures** listed above, then re-run
 
 `/pbr:health`
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ---
 
 ## Anti-Patterns
 
-1. **DO NOT** modify any files — this is strictly read-only
-2. **DO NOT** auto-repair anything — present fixes and let the user decide
+1. **DO NOT** modify files without user consent — auto-fix requires explicit user approval via AskUserQuestion
+2. **DO NOT** auto-repair anything silently — always present fixes and let the user decide
 3. **DO NOT** skip checks that depend on missing files — report the dependency failure and continue
 4. **DO NOT** treat warnings as failures in the summary count — only count FAIL items
 5. **DO NOT** read full plan/summary contents — frontmatter and existence checks are sufficient