@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/codex-pbr/skills/discuss/SKILL.md

@@ -0,0 +1,438 @@
+---
+name: discuss
+description: "Talk through a phase before planning. Identifies gray areas and captures your decisions."
+---
+
+**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.**
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► DISCUSSION                                 ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+# $pbr-discuss-phase — Pre-Planning Discussion
+
+**References:** `@references/questioning.md`, `@references/ui-brand.md`
+
+You are running the **discuss** skill. Your job is to help the user think through a phase BEFORE planning begins. You identify gray areas where the user's preference matters, ask structured questions, and capture every decision in a CONTEXT.md file that the planner must honor.
+
+This skill runs **inline** (no Task delegation).
+
+---
+
+## Multi-Session Sync
+
+Before any phase-modifying operations (writing CONTEXT.md, updating STATE.md), acquire a claim:
+
+```
+acquireClaim(phaseDir, sessionId)
+```
+
+If the claim fails (another session owns this phase), display: "Another session owns this phase. Use `$pbr-progress` to see active claims."
+
+On completion or error (including all exit paths), release the claim:
+
+```
+releaseClaim(phaseDir, sessionId)
+```
+
+## Core Principle
+
+**Decisions made here are LOCKED.** The planner cannot override them, even if research suggests a different approach. The planner must implement the locked decision and may note the discrepancy, but must follow the user's choice exactly.
+
+---
+
+## Flow
+
+### Step 1: Parse Phase Number and Check for Existing Plans
+
+Parse `$ARGUMENTS`:
+- If argument is `--project`: enter PROJECT mode (see Step 1-project below). Skip Steps 2-8.
+- If argument is a phase number: enter PHASE mode (existing flow — continue with Step 1 as-is).
+- If no argument: existing logic applies (read STATE.md for current phase).
+
+**Validation (PHASE mode):**
+- Must be a valid phase number (integer or decimal like `3.1`)
+- If no argument provided, read STATE.md to get the current phase
+- If no current phase and no argument: "Which phase do you want to discuss? Run `$pbr-progress` to see available phases."
+
+**Phase directory resolution:**
+1. List directories in `.planning/phases/`
+2. Find directory matching pattern `{NN}-*` where NN matches the phase number
+3. If not found, check ROADMAP.md for the phase name
+4. If still not found, display:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+Phase {N} not found.
+
+**To fix:** Run `$pbr-progress` to see available phases.
+```
+
+**Check for existing plans** (after resolving the phase directory):
+1. Check for `PLAN.md` or `PLAN-*.md` files in the phase directory
+2. If plan files exist:
+   - Warn: "Phase {N} already has plans. Decisions from this discussion won't retroactively change them. Consider re-planning with `$pbr-plan-phase {N}` after."
+   - This is a **warning only** — do not block the discussion
+
+### Step 1-project: Project Discussion Mode (--project)
+
+When invoked with `--project`, discuss project-level cross-cutting decisions.
+This mode writes to `.planning/PROJECT.md` ## Context section (project-level), NOT a phase directory.
+
+**Check for existing project context:**
+1. Read `.planning/PROJECT.md` and check if it has a `## Context` section.
+2. If it has a ## Context section, ask the user (using the context-handling pattern from
+   `skills/shared/gate-prompts.md`):
+   question: "PROJECT.md already has a ## Context section. How should we handle it?"
+   options: Overwrite | Append | Cancel
+3. If Cancel: stop and display the existing PROJECT.md path.
+4. **Backwards compat:** If `.planning/CONTEXT.md` exists (legacy), read it as the existing context source for Append mode, then write merged result to PROJECT.md ## Context.
+
+**Load project context:**
+- Read `.planning/PROJECT.md` (if exists) — project vision, scope, and context (## Context section)
+- Read `.planning/REQUIREMENTS.md` (if exists) — requirements for constraint awareness
+- **Backwards compat:** If PROJECT.md has no ## Context but `.planning/CONTEXT.md` exists, read from the legacy file
+
+**Run gray areas for project-level decisions (Steps 2.5-5 pattern):**
+- Identify 3-4 cross-cutting architectural decisions across ALL phases
+- Focus on: technology stack choices, infrastructure, security posture,
+  observability approach, deployment strategy, data storage decisions
+- Follow the same Steps 3-5 pattern (gray areas → options → follow-ups)
+
+**Write project context to PROJECT.md:**
+1. Read `${CLAUDE_SKILL_DIR}/templates/project-CONTEXT.md.tmpl`
+2. Fill in from discussion decisions:
+   - Locked Decisions table: all decisions the user made (not "Let Claude decide")
+   - User Constraints: budget, team, timeline, hosting from the conversation
+   - Deferred Ideas: anything explicitly ruled out for this project
+   - Claude's Discretion: decisions marked "Let Claude decide"
+3. If Append mode: merge new decisions with existing PROJECT.md ## Context content
+4. Write to `.planning/PROJECT.md` under the `## Context` section with subsections:
+   - `### Locked Decisions`
+   - `### User Constraints`
+   - `### Deferred Ideas`
+
+**Update STATE.md pointer:**
+Add under Accumulated Context:
+```
+Project context: .planning/PROJECT.md ## Context ({N} locked decisions, {N} deferred, {N} discretion)
+```
+
+**After writing:** Auto-sync to CLAUDE.md is handled by the post-write-dispatch hook.
+Display: `✓ Project context written to PROJECT.md — locked decisions will auto-sync to CLAUDE.md`
+
+Skip to Cleanup step. Do NOT run Steps 2-8 of the phase flow.
+
+---
+
+### Step 2: Load Phase Context
+
+Read the following files to understand what this phase needs to accomplish:
+
+1. **ROADMAP.md** — Find the phase entry. Extract:
+   - Phase name and description
+   - Goal / objective
+   - Requirements to satisfy
+   - Success criteria
+   - Dependencies on prior phases
+
+2. **Prior SUMMARY.md files** — Scan `.planning/phases/` for phases with lower numbers that have SUMMARY.md files. Read their frontmatter to understand:
+   - What's already been built (`provides` field)
+   - What technologies are in use (`tech_stack` field)
+   - What patterns have been established (`patterns` field)
+   - What decisions were already made (`key_decisions` field)
+
+3. **REQUIREMENTS.md** (if exists) — Read project requirements relevant to this phase. **CRITICAL**: After reading, display to the user which specific requirements map to this phase. Flag any requirements that could constrain decisions. If the user's discussion decisions later contradict a stated requirement, surface the contradiction immediately — don't wait until planning.
+
+4. **CONTEXT.md** (if exists in the phase directory) — Check if a prior discussion already happened
+   - If CONTEXT.md exists, inform the user and use the **context-handling** pattern from `skills/shared/gate-prompts.md`:
+     question: "Phase {N} already has a CONTEXT.md from a prior discussion. How should we handle it?"
+
+   Handle responses:
+   - "Overwrite": Replace CONTEXT.md entirely with new decisions
+   - "Append": Add new decisions below existing ones, marked as "Amendment ({date})"
+   - "Cancel": Stop the discussion, keep existing CONTEXT.md
+
+### Step 2.5: Open Exploration Phase
+
+Before jumping into specific gray areas, give the user space to share their mental model unprompted.
+
+1. **Present the phase goal** (from ROADMAP.md) and ask an open question:
+   - "Before we get into specifics — what's your mental model of how this phase should work? What excites you about it? What concerns you?"
+
+2. **Follow the user's response with 2-3 domain-aware follow-ups** from `skills/shared/domain-probes.md`:
+   - Match what the user mentioned to the relevant domain tables
+   - Pick the 2-3 most insightful probes based on what they said, not a generic checklist
+   - Ask them conversationally, not as a numbered list
+
+3. **Surface implications** from what the user shared:
+   - "You mentioned X — that usually means we'd need Y. Is that part of your vision?"
+   - Connect their ideas to concrete technical or design consequences
+   - Flag anything that would affect scope, complexity, or dependencies
+
+4. **Let the conversation reveal gray areas naturally.** The user's responses here often surface the real gray areas better than top-down analysis. Carry any themes, concerns, or preferences forward into Step 3.
+
+### Step 3: Identify Gray Areas
+
+Analyze the phase goal, requirements, and what's already built. Identify **3-4 gray areas** where the user's preference matters. Gray areas fall into these categories:
+
+Read `${CLAUDE_SKILL_DIR}/templates/decision-categories.md` for the category reference table.
+
+**How to identify gray areas:**
+1. Look at the phase requirements — where are there multiple valid approaches?
+2. Look at prior phase decisions — where might this phase need to diverge?
+3. Look at the success criteria — what's ambiguous about how to satisfy them?
+4. Consider the user's likely pain points — what would they want a say in?
+
+**Important:** Do NOT identify gray areas that are purely implementation details (e.g., variable naming, file organization). Focus on areas that affect user experience, system behavior, or long-term maintainability.
+
+### Step 4: Present Gray Areas
+
+Present each gray area to the user using the **gray-area-option** pattern from `skills/shared/gate-prompts.md`. For each gray area:
+
+Use AskUserQuestion:
+  question: "Gray Area {N}: {Title} — {Why this matters}"
+  header: "Decision"
+  options: (generate 2-4 concrete options from analysis, each with pros/cons in the description)
+    - label: "{Option A}"       description: "{Pros: ..., Cons: ...}"
+    - label: "{Option B}"       description: "{Pros: ..., Cons: ...}"
+    - ...up to 4 options total, with "Let Claude decide" always as the last option
+    - label: "Let Claude decide" description: "Mark as Claude's Discretion"
+  multiSelect: false
+
+If more than 3 concrete options exist for a gray area, present only the top 3 plus "Let Claude decide" (max 4 total). Mention the omitted option(s) in the question text.
+
+**Rules for presenting options:**
+- Each option must be concrete and implementable
+- Include honest pros/cons (don't bias toward one option)
+- "Let Claude decide" should always be available as a choice
+- If the user gives a preference not in the options, accept it
+- If the user says "I don't care", mark it as Claude's Discretion
+
+### Step 5: Deep-Dive Each Selected Area
+
+For each gray area where the user made a decision (not "Let Claude decide"), ask **4 follow-up questions** to fully capture their intent.
+
+**CRITICAL — STOP: Do NOT skip ANY of the 4 follow-up areas below. All 4 MUST be asked for each gray area where the user made a decision.**
+
+**Follow-up question types:**
+
+**CRITICAL — STOP: Do NOT skip this follow-up area.**
+1. **Scope boundary**: "Should {feature} also handle {edge case}?"
+   Use the **yes-no** pattern — this is a binary decision.
+
+**CRITICAL — STOP: Do NOT skip this follow-up area.**
+2. **Quality level**: "How polished should this be?"
+   Do NOT use AskUserQuestion — this is freeform. Let the user describe their quality expectations in their own words.
+
+**CRITICAL — STOP: Do NOT skip this follow-up area.**
+3. **Integration**: "How should this interact with {existing component}?"
+   Do NOT use AskUserQuestion — this is freeform. The answer depends on the specific component and context.
+
+**CRITICAL — STOP: Do NOT skip this follow-up area.**
+4. **Future-proofing**: "Should we design this to support {potential future need}, or keep it simple?"
+   Use the **yes-no** pattern:
+     question: "Design {feature} to support {future need}, or keep it simple for now?"
+     options:
+       - label: "Future-proof"  description: "Add extensibility for {future need}"
+       - label: "Keep simple"   description: "Build only what's needed now"
+
+**Rules for follow-ups:**
+- Ask all 4 questions for each area
+- Record exact answers (don't paraphrase)
+- If the user gives a short answer, capture it as-is
+- If the user says "you decide" on a follow-up, move that specific sub-decision to Claude's Discretion
+
+**Completion check:** After all follow-up questions for all gray areas, verify that all 4 follow-up areas produced output for each decided gray area. If any area was missed, go back and ask it before proceeding to Step 6.
+
+### Step 6: Capture Deferred Ideas
+
+During the conversation, the user may mention ideas they want but not in this phase. Track these separately:
+- Ideas explicitly deferred by the user ("let's do that later")
+- Ideas that are out of scope for this phase based on ROADMAP.md
+- Ideas the user considered but rejected
+
+### Step 6.5: Decision Gate (inline)
+
+Before creating the CONTEXT.md artifact, confirm readiness with the user per `@references/questioning.md` decision gate pattern:
+
+```
+AskUserQuestion:
+  question: "I think I have a clear picture of your decisions for this phase. Ready to capture them in CONTEXT.md?"
+  header: "Ready?"
+  options:
+    - label: "Yes, proceed"    description: "Write CONTEXT.md with captured decisions"
+    - label: "Keep exploring"  description: "I want to share more or discuss further"
+```
+
+If "Keep exploring" -- ask what they want to add or identify gaps and probe naturally. Loop until "Yes, proceed" is selected.
+
+**Freeform rule:** If the user selects "Keep exploring" and responds with freeform text (not selecting an option), switch to plain text conversation per `@references/questioning.md` freeform rule. Do NOT present another AskUserQuestion until you have processed their freeform response.
+
+### Step 7: Write CONTEXT.md
+
+Write the CONTEXT.md file to the phase directory:
+
+**Path:** `.planning/phases/{NN}-{phase-name}/CONTEXT.md`
+
+**Content:**
+
+Read `${CLAUDE_SKILL_DIR}/templates/CONTEXT.md.tmpl` for the template structure.
+
+**Placeholders to fill:**
+- `{N}` -- the phase number
+- `{ISO date}` -- today's date in ISO format
+- `{Decision title}` / `{User's exact choice and reasoning}` -- from Step 4-5 decisions
+- `{Idea}` / `{Why deferred}` -- from Step 6 deferred ideas
+- `{Area}` / `{What Claude can choose}` -- items marked "Let Claude decide"
+- `{2-3 sentences}` -- user's vision summary from the conversation
+- `{Concern}` / `{Context}` -- concerns raised during discussion
+
+**Decision Summary generation:** The `## Decision Summary` section at the top of CONTEXT.md is a compact digest (~300 tokens) of all decisions. For each locked decision, write only the title and the user's choice in one phrase (no scope/quality/integration details). List deferred and discretion items as comma-separated titles only. This summary is injected into agent prompts by the plan skill -- keep it concise.
+
+### Step 7.5: Update STATE.md Pointer
+
+Update `.planning/STATE.md`'s `## Accumulated Context` section to add a reference to the new CONTEXT.md:
+
+Add under the `### Decisions` subsection:
+```
+Phase {N} discussion: .planning/phases/{NN}-{slug}/CONTEXT.md ({count} locked, {count} deferred, {count} discretion)
+```
+
+This creates a pointer so `$pbr-resume-work` and `progress-tracker.js` know that phase-specific decisions exist and where to find them.
+
+### Step 8: Confirm and Route
+
+After writing CONTEXT.md, display branded output per `@references/ui-brand.md`:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► DISCUSSION CAPTURED ✓                      ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Phase {N}: {name}**
+
+✓ Decisions: {count} locked, {count} deferred, {count} discretion
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Plan this phase** — your decisions will be honored
+
+`$pbr-plan-phase {N}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+**Also available:**
+- `$pbr-progress` — see project status
+- `$pbr-explore` — explore ideas further
+```
+
+---
+
+## Decision Categories Reference
+
+### LOCKED Decisions
+
+These come from:
+- User selecting a specific option (not "Let Claude decide")
+- User answering follow-up questions with specific preferences
+- User volunteering a strong opinion during discussion
+
+**The planner MUST:**
+- Implement exactly as the user specified
+- Not modify, optimize, or "improve" the decision
+- Note in the plan if research suggests a different approach
+- Still follow the locked decision regardless
+
+### DEFERRED Ideas
+
+These come from:
+- User explicitly saying "not now" or "later"
+- Ideas that are out of scope per ROADMAP.md
+- User rejecting an option but saying it's a good idea for later
+
+**The planner MUST NOT:**
+- Include deferred ideas in the plan
+- Sneak deferred ideas in as "nice to have" tasks
+- Combine deferred ideas with in-scope work
+
+### CLAUDE'S DISCRETION
+
+These come from:
+- User selecting "Let Claude decide"
+- User saying "I don't care" or "whatever you think"
+- Follow-up questions answered with "you decide"
+
+**The planner MAY:**
+- Choose any reasonable approach
+- Use research results to inform the choice
+- Change their mind during planning if they learn something new
+- Must document their choice and rationale in the plan
+
+---
+
+## Edge Cases
+
+### Phase already has CONTEXT.md
+- Use the **context-handling** pattern from `skills/shared/gate-prompts.md` (same as Step 2)
+- If "Overwrite": replace entirely
+- If "Append": add new decisions below existing ones, marking them as "Amendment"
+- If "Cancel": stop the discussion, keep existing CONTEXT.md
+
+### Phase already has plans
+- Handled by Step 1 — warn but do not block
+- See Step 1 "Check for existing plans" for the exact warning message
+
+### User wants to discuss multiple phases
+- Handle one at a time
+- After completing one, suggest: "Want to discuss Phase {N+1} too? Run `$pbr-discuss-phase {N+1}`."
+
+### User disagrees with all options
+- Ask: "What would you prefer instead?" — this is freeform text, do NOT use AskUserQuestion.
+- Accept any answer and lock it as a decision.
+- The options were suggestions, not constraints
+
+### User wants to skip follow-ups
+- If user says "that's enough" or "skip the details", respect that
+- Write what you have — partial follow-ups are fine
+- Mark missing follow-up areas as Claude's Discretion
+
+---
+
+## State Integration
+
+This skill updates STATE.md's Accumulated Context section with a pointer to the phase CONTEXT.md file. It does NOT change the project position (current phase/plan). STATE.md position is updated when `$pbr-plan-phase` runs.
+
+---
+
+## Git Integration
+
+Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
+
+If `planning.commit_docs: true` in config.json:
+- Commit CONTEXT.md: `docs(planning): capture phase {N} discussion decisions`
+
+---
+
+## Anti-Patterns
+
+1. **DO NOT** bias the user toward a particular option
+2. **DO NOT** skip the follow-up questions (unless the user asks to skip)
+3. **DO NOT** paraphrase the user's decisions — capture them verbatim
+4. **DO NOT** add your own opinions to LOCKED decisions
+5. **DO NOT** mark something as Claude's Discretion unless the user explicitly chose that
+6. **DO NOT** include implementation details in CONTEXT.md — it captures WHAT, not HOW
+7. **DO NOT** skip the deferred ideas section — this prevents scope creep later
+8. **DO NOT** present more than 4 options per gray area — decision fatigue is real

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

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