@sienklogic/plan-build-run 2.0.0

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

@@ -0,0 +1,362 @@
+---
+name: explore
+description: "Explore ideas, think through approaches, and route insights to the right artifacts."
+allowed-tools: Read, Write, Glob, Grep, Task, AskUserQuestion
+argument-hint: "[topic]"
+---
+
+# /pbr:explore — Idea Exploration
+
+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.
+
+---
+
+## Context Budget
+
+Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+
+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
+
+---
+
+## How /pbr:explore Differs from /pbr:discuss
+
+| | /pbr:discuss | /pbr:explore |
+|---|---|---|
+| Purpose | Make decisions for a phase | Discover what you actually want |
+| Structure | Pre-computed gray areas with options | Open-ended Socratic conversation |
+| Requires | Phase number | Nothing |
+| Output | CONTEXT.md (locked decisions) | Routes to the right artifact |
+| Feels like | Making decisions | Thinking with a partner |
+
+---
+
+## Invocation
+
+- `/pbr:explore` — Open-ended: "I have an idea"
+- `/pbr:explore auth` — Topic-specific exploration
+- `/pbr:explore "should we add caching?"` — Specific question
+
+Parse `$ARGUMENTS` for an optional topic. If provided, use it to seed the opening question. If empty, start fully open-ended.
+
+---
+
+## Pre-Conversation Context Loader
+
+Reference: `skills/shared/context-loader-task.md` for the full briefing Task() pattern.
+
+**Only runs if `.planning/` directory exists.** Fresh explores with no project skip this entirely.
+
+When a project exists, spawn a briefing Task() per the context-loader-task pattern with `skill_purpose` = "exploring new ideas". If a topic was provided, use the topic-scoped variation with that topic.
+
+Use the briefing to inform your conversation — reference existing decisions, avoid re-litigating settled questions, and connect new ideas to the existing project structure.
+
+---
+
+## Conversation Design
+
+The conversation is Socratic, not extractive. You are a thinking partner, not an interviewer.
+
+### Principles
+
+1. **Open with curiosity.** Start with "What are you thinking about?" or "What's on your mind?" — not "Please describe the feature you want."
+
+2. **Follow their energy.** Dig into what excites or concerns them. If they light up about a technical approach, explore it. If they hesitate, probe why.
+
+3. **Surface implications.** "If you go with X, that usually means Y and Z. Is that intentional?" Connect their idea to downstream consequences they may not see yet.
+
+4. **Challenge with alternatives.** "You mentioned X, but have you considered Y?" Don't be adversarial — offer genuine alternatives that might fit better.
+
+5. **Present trade-offs, not options.** "A gives you speed but locks you into a vendor. B is slower but keeps options open." Frame choices as trade-offs with real consequences, not a menu.
+
+6. **Know when to research.** "I'm not sure about the best approach here. Want me to research it?" Don't fake knowledge — admit gaps and offer to investigate.
+
+7. **Don't rush to outputs.** Explore until understanding is genuinely deep. The user will know when they're ready to wrap up.
+
+### Domain-Aware Probing
+
+Reference `skills/shared/domain-probes.md` for technology-specific follow-up questions. When the user mentions a domain (auth, caching, search, etc.), pick the 2-3 most relevant probes from that domain's table. Do NOT run through the table as a checklist.
+
+### Conversation Starters by Invocation
+
+| Invocation | Opening |
+|---|---|
+| `/pbr:explore` | "What are you thinking about?" |
+| `/pbr:explore auth` | "What's your thinking on auth? Are you starting from scratch or rethinking something?" |
+| `/pbr:explore "should we add caching?"` | "Caching for what specifically? What's feeling slow or what do you expect to be slow?" |
+
+---
+
+## Mid-Conversation Research
+
+When a knowledge gap emerges during the conversation — you're unsure about a library, pattern, or approach — surface it explicitly.
+
+**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:
+    - label: "Research now"   description: "Spawn a researcher agent to investigate"
+    - label: "Save for later" description: "Add as a research question for future investigation"
+
+**If research now:**
+
+Display to the user: `◐ Spawning researcher...`
+
+```
+Task({
+  subagent_type: "pbr:researcher",
+  prompt: "<research_assignment>
+    Topic: {specific research question}
+    Output file: .planning/research/{topic-slug}.md
+    Mode: project-research
+
+    Research this specific question: {the question}
+
+    Write findings to the output file.
+  </research_assignment>"
+})
+```
+
+After the researcher completes:
+- Read ONLY the frontmatter and summary section of the research file (not the full document)
+- Incorporate the 2-3 key findings into the conversation
+- Main context gets ~200 tokens of research insight, not the full document
+
+**If save for later:**
+- Note it as a research question to include in output routing
+
+---
+
+## Context Pressure Awareness
+
+After approximately 10 exchanges or when the conversation has been substantial, mention:
+
+"We've been exploring for a while. Want to wrap up with outputs, or keep going?"
+
+Don't force a conclusion — some explorations legitimately need extended conversation. But surface the option so the user can choose.
+
+---
+
+## Output Routing
+
+This is the key innovation of `/pbr:explore`. At conversation end, the agent summarizes key insights and routes them to the right artifacts.
+
+### Step 1: Summarize
+
+Provide a concise summary of the key insights from the conversation:
+- What was the core idea or question?
+- What did we discover or decide?
+- What remains uncertain?
+
+### Step 2: Propose Outputs
+
+Suggest specific outputs with reasoning. Present no more than 4 suggestions — focus on what matters most.
+
+| Output Type | When to Suggest | Where It Goes |
+|---|---|---|
+| Todo | Small, actionable item discovered | `.planning/todos/pending/{id}.md` |
+| Requirement | New project feature identified | Append to `REQUIREMENTS.md` with REQ-ID |
+| 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` |
+| 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` |
+
+**Format for proposals:**
+
+```
+Based on our conversation, here's what I'd suggest capturing:
+
+1. **Todo**: "{title}" — {why this is a todo and not something bigger}
+2. **Seed**: "{title}" — {why this should wait for a trigger condition}
+3. **Research question**: "{question}" — {why we need to investigate this}
+
+Want to adjust, add, or remove any of these?
+```
+
+### Step 3: Confirm
+
+Use the **output-routing** pattern from `skills/shared/gate-prompts.md`:
+  question: "How do you want to handle these proposed outputs?"
+
+Handle responses:
+- "Approve all": Create all suggested artifacts (proceed to Step 4)
+- "Adjust": The user wants to modify proposals. Have a freeform conversation to adjust, then re-present with another AskUserQuestion.
+- "Add more": The user has additional outputs. Gather them conversationally, add to the list, then re-present.
+- "Skip": End the session without creating artifacts. This is fine — sometimes exploring is enough.
+
+Do NOT create any artifacts until the user selects "Approve all" on the final set.
+
+### Step 4: Create Artifacts
+
+**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.
+
+### Step 5: Completion
+
+After creating artifacts (or if user chose "Skip"), display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► EXPLORATION CAPTURED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+{count} artifacts created: {list of artifact types}
+
+───────────────────────────────────────────────────────────────
+
+## ▶ 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`
+
+`{primary command}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/pbr:status` — see project status
+- `/pbr:continue` — execute next logical step
+
+───────────────────────────────────────────────────────────────
+```
+
+---
+
+## Output Formats
+
+### Todo
+
+Write to `.planning/todos/pending/{NNN}-{slug}.md`. Follow the format used by the existing todo skill.
+
+### Requirement
+
+Append to `.planning/REQUIREMENTS.md` with the next available REQ-ID in the appropriate category. If the category doesn't exist, create it.
+
+### Phase Decision
+
+Append to `.planning/phases/{NN}-{slug}/CONTEXT.md`. If CONTEXT.md doesn't exist for that phase, create it with the standard header. Mark the decision as coming from `/pbr:explore`.
+
+### Research Question
+
+Append to `.planning/research/questions.md`. Create the file if it doesn't exist:
+
+```markdown
+# Research Questions
+
+Questions identified during exploration that need deeper investigation.
+
+## Open
+
+- [ ] {Question} — Source: /pbr:explore session ({date})
+
+## Answered
+
+(none yet)
+```
+
+### New Phase
+
+Append to `.planning/ROADMAP.md` following the existing phase format. Assign the next available phase number.
+
+### Note
+
+Write to `.planning/notes/{slug}.md`:
+
+```markdown
+---
+created: {ISO date}
+source: "/pbr:explore session"
+topic: "{topic}"
+---
+# {Title}
+
+{Content from the conversation — key insights, reasoning, context}
+```
+
+### Seed
+
+Write to `.planning/seeds/SEED-{NNN}-{slug}.md`:
+
+```markdown
+---
+id: SEED-{NNN}
+status: dormant
+planted: {ISO date}
+trigger: "{phase-slug}"
+scope_estimate: "small|medium|large"
+source: "/pbr:explore session"
+---
+# {Title}
+
+## Context
+{Why this idea came up}
+
+## Breadcrumbs
+{Related phases, technologies, user preferences}
+```
+
+---
+
+## Git Integration
+
+Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
+
+If `planning.commit_docs: true` in config.json, commit created artifacts:
+
+```
+docs(planning): capture explore session outputs
+```
+
+Stage only the files created during this session. Do not stage unrelated changes.
+
+---
+
+## Error Handling
+
+### Researcher agent fails
+If a mid-conversation researcher Task() fails, display:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+Research agent failed for topic: {topic}.
+
+**To fix:** Continue the conversation without research, or try `/pbr:explore` again with a more specific topic.
+```
+
+### Context loader fails
+If the briefing Task() fails:
+- Display: `⚠ Context loading failed. Proceeding without project context.`
+- Continue with the exploration — the conversation can still be valuable without project context.
+
+---
+
+## 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
+2. **DO NOT** cycle through a checklist of questions
+3. **DO NOT** rush to outputs before understanding is deep
+4. **DO NOT** auto-research without asking (unless config mode is autonomous)
+5. **DO NOT** present more than 4 output suggestions — focus on what matters
+6. **DO NOT** create artifacts the user didn't approve
+7. **DO NOT** re-litigate decisions that are already locked in CONTEXT.md
+8. **DO NOT** force the user to produce outputs — sometimes exploring is enough

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

@@ -0,0 +1,186 @@
+---
+name: health
+description: "Check planning directory integrity. Find and fix corrupted state."
+allowed-tools: Read, Bash, Glob, Grep
+---
+
+# /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.
+
+This skill runs **inline** and is **read-only** — it never modifies any files.
+
+---
+
+## 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.
+
+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.
+
+---
+
+## Checks
+
+Run all 9 checks in order. Collect results and present them together at the end.
+
+### Check 1: Structure
+
+Validate `.planning/` exists with required scaffolding: `STATE.md`, `config.json`, `ROADMAP.md`.
+
+- If `.planning/` is missing: FAIL the entire health check immediately. Display:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+No .planning/ directory found.
+
+**To fix:** Run `/pbr:begin` 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."
+
+### Check 2: Config Validity
+
+Parse `.planning/config.json` as JSON. Check required fields: `projectName`, `version`. Check recommended fields: `phases`, `currentPhase`.
+
+- PASS: Valid JSON with all required fields
+- FAIL (parse error): Report the parse error message — "Open the file and correct the syntax."
+- FAIL (missing required field): Report which field — "Add the field to config.json."
+- WARN (missing recommended field): Report which field — "This may cause issues with some skills."
+
+### Check 3: Phase Consistency
+
+Compare directories in `.planning/phases/` against phases defined in `ROADMAP.md`.
+
+- PASS: Every directory matches a ROADMAP.md phase; no started phases are missing directories
+- FAIL (orphan directory): Directory exists but not in ROADMAP.md — "Add to ROADMAP.md or remove the directory."
+- FAIL (missing directory): ROADMAP.md lists phase as in-progress but directory missing — "Create the directory or update ROADMAP.md."
+- Note: Future phases without directories are normal (not a failure).
+
+### Check 4: Plan/Summary Pairing
+
+Glob all `PLAN*.md` and `SUMMARY*.md` in `.planning/phases/`. Match by plan number. A PLAN without SUMMARY is normal unless the phase is marked complete.
+
+- 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."
+
+### Check 5: STATE.md Accuracy
+
+Extract current phase, plan identifier, and progress percentage from `STATE.md`. Verify each against the file system.
+
+- PASS: All STATE.md references match the file system
+- FAIL (stale phase): Referenced phase directory does not exist — "Update STATE.md to reflect the actual current phase."
+- FAIL (stale plan): Referenced plan file does not exist — "Update STATE.md to the correct current plan."
+- FAIL (wrong progress): Stated progress does not match actual plan/summary counts — "Update the progress in STATE.md."
+- WARN (no position): No current phase or plan specified — "Fine for new projects but may indicate lost state."
+
+### Check 6: Frontmatter Validity
+
+Glob all `PLAN*.md` and `SUMMARY*.md` in `.planning/phases/`. Each file must start with `---`, have a closing `---`, contain valid YAML, and include required fields: `title`, `status`.
+
+- PASS: All files have valid frontmatter with required fields
+- FAIL (no frontmatter): "Add frontmatter block starting with `---` at the top of the file."
+- FAIL (malformed): Report the YAML error — "Correct the YAML syntax between the `---` delimiters."
+- FAIL (missing field): Report which field — "Add `{field}: {suggested value}` to the frontmatter."
+
+### Check 7: ROADMAP/STATE Sync
+
+Compare ROADMAP.md phase statuses against STATE.md current position. Flag if ROADMAP says a phase is "verified" but STATE says it is "building", or if phases after current are marked complete.
+
+- PASS: ROADMAP and STATE are consistent
+- FAIL (mismatch): Report both statuses — "Update STATE.md to match ROADMAP.md, or vice versa."
+- WARN (drift): Current phase in STATE.md is behind phases marked complete in ROADMAP.md.
+
+### Check 8: Hook Execution Log
+
+Check if `.planning/logs/hooks.jsonl` exists. If so, scan last 20 entries for `result: "error"` or `result: "unlink-failed"`.
+
+- PASS: Log exists with no recent errors
+- WARN (errors found): Report error count and most recent error description — "Hooks may not be firing correctly."
+- INFO (no log): "No hook log found. Normal if no hooks have fired yet."
+
+### Check 9: Config Completeness
+
+Read `.planning/config.json` and check for fields referenced by skills:
+- `features.auto_continue` (build skill, auto-continue.js hook)
+- `features.team_discussions` (config skill)
+- `features.goal_verification` (build, review skills)
+- `features.integration_verification` (review skill)
+- `git.mode` (config skill)
+
+- PASS: All expected fields present
+- WARN (missing fields): Report each missing field and which skill uses it — "Run `/pbr:config` to set all options."
+
+---
+
+## Bonus: Recent Decisions
+
+After all checks, look for `.planning/logs/decisions.jsonl`. If it exists, display the last 5 entries as `- {date}: {summary} (phase {N})`. If it does not exist, skip silently.
+
+---
+
+## Completion
+
+After all checks complete, display the branded result:
+
+**If all checks passed (0 failures):**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► HEALTH CHECK PASSED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+{N} checks passed, {M} warnings
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Continue your workflow** — planning directory is healthy
+
+`/pbr:status`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/pbr:continue` — execute next logical step
+- `/pbr:config` — adjust settings
+
+───────────────────────────────────────────────────────────────
+```
+
+**If failures found:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► HEALTH CHECK FAILED ⚠
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+{N} checks passed, {F} failures, {M} warnings
+
+───────────────────────────────────────────────────────────────
+
+## ▶ 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
+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
+6. **DO NOT** fail silently — every check must produce an explicit PASS, WARN, or FAIL
+7. **DO NOT** suggest running destructive commands — fixes should be safe, targeted edits

package/plugins/pbr/skills/health/templates/check-pattern.md.tmpl

@@ -0,0 +1,30 @@
+# Health Check Execution Pattern
+
+Each of the 9 checks follows this common pattern. The check-specific details (what to read, what to validate, what constitutes PASS/FAIL) are defined in SKILL.md — this template describes only the shared execution flow.
+
+## Pattern
+
+```
+For check {check_number} ({check_name}):
+
+1. READ — Read the target file(s): {target_files}
+2. VALIDATE — Apply the check-specific rules: {validation_rules}
+3. CLASSIFY — Determine result:
+   - PASS: Validation succeeded, no issues found
+   - FAIL: A required condition is violated (counts toward issue total)
+   - WARN: A recommended condition is violated (does NOT count toward issue total)
+   - INFO: Informational note, not a problem
+4. RECORD — Store the result with:
+   - Status: [PASS], [FAIL], [WARN], or [INFO]
+   - Check name (short label)
+   - One-line summary of finding
+   - For FAIL/WARN: the specific file, the problem, and a concrete fix suggestion
+```
+
+## Rules
+
+- Every check MUST produce exactly one status line (PASS, FAIL, WARN, or INFO)
+- FAIL results MUST include: file path, problem description, and fix suggestion
+- Multiple failures within a single check produce multiple entries in the "Issues Found" section
+- Checks never auto-repair — they report only
+- If a check depends on a prior check's file (e.g., Check 2 needs config.json which Check 1 validates exists), and that file is missing, report the dependency failure and move on

package/plugins/pbr/skills/health/templates/output-format.md.tmpl

@@ -0,0 +1,63 @@
+# Health Check Output Format
+
+Present results as a single report after all checks complete.
+
+## Summary Table
+
+```
+Planning Health Check
+=====================
+
+[PASS]  Structure           .planning/ exists, all required files present
+[FAIL]  Config              config.json missing required field `projectName`
+[PASS]  Phase consistency   Directories match ROADMAP.md phases
+[PASS]  Plan/Summary        All pairings valid
+[FAIL]  STATE.md accuracy   Phase reference is stale
+[PASS]  Frontmatter         All PLAN/SUMMARY files have valid frontmatter
+[PASS]  ROADMAP/STATE sync  ROADMAP and STATE phase statuses are consistent
+[PASS]  Hook log            No recent hook errors
+[PASS]  Config completeness All expected fields present
+```
+
+## Status Indicators
+
+| Indicator | Meaning | Counts as Issue? |
+|-----------|---------|-----------------|
+| `[PASS]`  | Check passed, no problems | No |
+| `[FAIL]`  | Required condition violated | **Yes** |
+| `[WARN]`  | Recommended condition violated | No |
+| `[INFO]`  | Informational note | No |
+
+## Issues Section
+
+Only shown when at least one FAIL exists:
+
+```
+Issues Found: {count}
+---------------
+
+1. {problem description}
+   File: {file path}
+   Fix:  {concrete fix suggestion}
+
+2. {problem description}
+   File: {file path}
+   Fix:  {concrete fix suggestion}
+```
+
+## Recent Decisions (Bonus)
+
+If `.planning/logs/decisions.jsonl` exists, show the last 5 entries:
+
+```
+Recent Decisions:
+- {date}: {summary} (phase {N})
+- {date}: {summary} (phase {N})
+```
+
+If the file does not exist, skip silently.
+
+## Final Line
+
+- With issues: `Result: {N} issues found. Review and apply fixes manually.`
+- All passed: `Result: All checks passed. Planning directory is healthy.`