@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/references/ui-formatting.md

@@ -1,444 +0,0 @@
-# Plan-Build-Run UI Brand & Formatting Reference
-
-Consistent output formatting for all Plan-Build-Run skills. Every skill that produces user-facing output should follow these patterns.
-
-## Stage Banners
-
-Use for major workflow transitions. Always use `PLAN-BUILD-RUN` prefix.
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► {STAGE NAME}                              ║
-╚══════════════════════════════════════════════════════════════╝
-```
-
-**Stage names (uppercase):**
-- `QUESTIONING`
-- `RESEARCHING`
-- `DEFINING REQUIREMENTS`
-- `CREATING ROADMAP`
-- `PLANNING PHASE {N}`
-- `EXECUTING WAVE {N}`
-- `VERIFYING`
-- `PHASE {N} COMPLETE ✓`
-- `MILESTONE COMPLETE`
-- `SCANNING CODEBASE`
-- `DEBUGGING`
-
----
-
-## Invocation Banners
-
-**Every skill MUST display a branded banner as its very first output, BEFORE any file reads, state loading, or processing.** This is the user's immediate confirmation that their command was received.
-
-Format:
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► {SKILL NAME}                              ║
-╚══════════════════════════════════════════════════════════════╝
-```
-
-**Skill names (uppercase):**
-- `STARTING PROJECT` (begin)
-- `PLANNING PHASE {N}` (plan)
-- `BUILDING PHASE {N}` (build)
-- `REVIEWING PHASE {N}` (review)
-- `QUICK TASK` (quick)
-- `NEXT STEP` (continue)
-- `PROJECT STATUS` (status)
-- `RESUMING SESSION` (resume)
-- `PAUSING SESSION` (pause)
-- `HEALTH CHECK` (health)
-- `SETUP` (setup)
-- `CONFIGURATION` (config)
-- `COMMAND REFERENCE` (help)
-- `DISCUSSION` (discuss)
-- `EXPLORING` (explore)
-- `NOTE` (note)
-- `TODO` (todo)
-- `DEBUGGING` (debug)
-- `SCANNING CODEBASE` (scan)
-- `MILESTONE` (milestone)
-- `IMPORTING PLAN` (import)
-
-**Rules:**
-1. The banner MUST be output BEFORE any tool calls (Read, Glob, Bash, Task)
-2. The banner MUST be the first text the user sees
-3. After the banner, optionally show a 1-line context summary (e.g., "Phase 3 of 7 — API Layer")
-4. Then proceed to Step 1 (state loading, argument parsing, etc.)
-
----
-
-## Headers
-
-Use these patterns for consistent visual hierarchy within sections:
-
-```
-## Phase 3: Authentication        <- Phase-level header
-### Plan 01: Database Schema      <- Plan-level header
-#### Task 1: Create User Table    <- Task-level header
-```
-
----
-
-## Status Indicators
-
-| Status | Indicator | Usage |
-|--------|-----------|-------|
-| Complete | `✓` | Completed items, passed checks |
-| Failed | `✗` | Failed verification, missing items |
-| Pending | `○` | Not yet started |
-| In Progress | `◐` | Currently executing |
-| Needs Human | `?` | Requires human verification |
-| Warning | `⚠` | Warnings, non-blocking issues |
-| Blocked | `⊘` | Blocked by dependency |
-| Auto-approved | `⚡` | Automatically approved (gates) |
-
----
-
-## Progress Display
-
-**Phase/milestone level:**
-```
-Progress: ████████░░ 80%
-```
-
-**Phase progress (detailed):**
-```
-Phase 3 of 5: Authentication
-Progress: [████████░░░░░░░░░░░░] 40%
-Plans: 2/5 complete
-```
-
-**Build progress (wave tracking):**
-```
-Wave 1: ✓ Plan 01, ✓ Plan 02
-Wave 2: ◐ Plan 03 (executing)
-Wave 3: ○ Plan 04
-```
-
-**Task level:**
-```
-Tasks: 2/4 complete
-```
-
----
-
-## Spawning Indicators
-
-Show when agents are being launched:
-
-```
-◐ Spawning executor...
-
-◐ Spawning 4 executors in parallel...
-  → Plan 01: Database Schema
-  → Plan 02: Auth Service
-  → Plan 03: API Routes
-  → Plan 04: Test Suite
-
-✓ Plan 01 complete (2m 14s)
-```
-
-For research agents:
-```
-◐ Spawning 4 researchers in parallel...
-  → Stack research
-  → Features research
-  → Architecture research
-  → Pitfalls research
-
-✓ Researcher complete: STACK.md written
-```
-
----
-
-## Checkpoint Boxes
-
-User action required. Use double-line box drawing, 62-character inner width.
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  CHECKPOINT: {Type}                                          ║
-╚══════════════════════════════════════════════════════════════╝
-
-{Content}
-
-→ {ACTION PROMPT}
-```
-
-**Types:**
-- `CHECKPOINT: Verification Required` → `→ Type "approved" or describe issues`
-- `CHECKPOINT: Decision Required` → `→ Select: option-a / option-b`
-- `CHECKPOINT: Action Required` → `→ Type "done" when complete`
-
----
-
-## AskUserQuestion Patterns
-
-Structured prompts for user decision points. All gate checks use AskUserQuestion instead of
-plain-text "Type approved" prompts. See `skills/shared/gate-prompts.md` for the full
-pattern catalog (21 named AskUserQuestion patterns).
-
-### Structure
-
-```
-AskUserQuestion:
-  question: "{contextual question}"
-  header: "{max 12 chars}"
-  options:
-    - label: "{Option 1}"  description: "{What happens}"
-    - label: "{Option 2}"  description: "{What happens}"
-  multiSelect: false
-```
-
-### Rules
-
-- **Max 4 options** per call. Split into 2-step flow if more are needed.
-- **Header max 12 characters.** Single word preferred (e.g., "Approve?", "Confirm", "Scope").
-- **multiSelect: false** always. Plan-Build-Run gates require single selection.
-- **Handle "Other"**: Users may type freeform text instead of selecting. Skills must handle this gracefully.
-- **Orchestrator only**: AskUserQuestion cannot be called from subagents.
-
-### Common Patterns
-
-**Approval gate** (approve-revise-abort):
-```
-question: "Approve these plans?"
-header: "Approve?"
-options:
-  - label: "Approve"          description: "Proceed with execution"
-  - label: "Request changes"  description: "Discuss adjustments before proceeding"
-  - label: "Abort"            description: "Cancel this operation"
-```
-
-**Simple confirmation** (yes-no):
-```
-question: "Re-plan this phase with gap context?"
-header: "Confirm"
-options:
-  - label: "Yes"  description: "Create gap-closure plans"
-  - label: "No"   description: "Skip re-planning"
-```
-
-**Category selection** (settings-category-select):
-```
-question: "What would you like to configure?"
-header: "Configure"
-options:
-  - label: "Depth"          description: "quick/standard/comprehensive"
-  - label: "Model profile"  description: "quality/balanced/budget/adaptive"
-  - label: "Features"       description: "Toggle workflow features and gates"
-  - label: "Git settings"   description: "branching strategy, commit mode"
-```
-
-**Dynamic routing** (action-routing):
-```
-question: "What would you like to do next?"
-header: "Next Step"
-options:
-  - label: "/pbr:build 3"    description: "Execute phase 3 plans"
-  - label: "/pbr:review 2"   description: "Verify phase 2 results"
-  - label: "Something else"  description: "Enter a different command"
-```
-
-### When NOT to Use
-
-Do not use AskUserQuestion for:
-- Freeform text input (symptom descriptions, task descriptions, open questions)
-- Socratic discussion (explore, discuss follow-ups)
-- Situations with unbounded response space
-
-Use plain conversational prompts for these cases instead.
-
----
-
-## Next Up Block
-
-Always present at end of major completions (phase complete, milestone complete, project init).
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
-╚══════════════════════════════════════════════════════════════╝
-
-**{Identifier}: {Name}** — {one-line description}
-
-`{copy-paste command}`
-
-<sub>`/clear` first → fresh context window</sub>
-```
-
-**Also available:**
-- `/pbr:alternative-1` — description
-- `/pbr:alternative-2` — description
-
-**Shorter routing (for minor completions):**
-```
-What's next?
-→ /pbr:plan 4 — plan the next phase
-→ /pbr:review 3 — review what was just built
-→ /pbr:status — see full project status
-```
-
----
-
-## Error Box
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  ERROR                                                       ║
-╚══════════════════════════════════════════════════════════════╝
-
-{Error description}
-
-**To fix:** {Resolution steps}
-```
-
----
-
-## Tables
-
-Use tables for structured data:
-
-```markdown
-| Phase | Status | Plans | Progress |
-|-------|--------|-------|----------|
-| 1. Foundation | ✓ Complete | 3/3 | 100% |
-| 2. Database | ✓ Complete | 2/2 | 100% |
-| 3. Auth | ◐ Building | 1/3 | 33% |
-| 4. Frontend | ○ Pending | 0/4 | 0% |
-```
-
----
-
-## Cost/Token Warnings
-
-```
-⚠ Budget check: This operation will spawn 4 agents (~400k tokens)
-  Estimated: ~20% of 5-hour window
-  Continue? [/pbr:config to adjust depth first]
-```
-
----
-
-## Completion Summary Templates
-
-### Phase Complete
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓                      ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Phase {N}: {Name}**
-
-{X} plans executed
-Goal verified ✓
-
-╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Phase {N+1}: {Name}** — {Goal from ROADMAP.md}
-
-/pbr:discuss {N+1} — gather context and clarify approach
-
-<sub>/clear first → fresh context window</sub>
-
-**Also available:**
-- /pbr:plan {N+1} — skip discussion, plan directly
-- /pbr:review {N} — manual acceptance testing before continuing
-```
-
-### Milestone Complete
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► MILESTONE COMPLETE                         ║
-╚══════════════════════════════════════════════════════════════╝
-
-**{version}**
-
-{N} phases completed
-All phase goals verified ✓
-
-╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Audit milestone** — verify requirements, cross-phase integration, E2E flows
-
-/pbr:milestone audit
-
-<sub>/clear first → fresh context window</sub>
-
-**Also available:**
-- /pbr:review — manual acceptance testing
-- /pbr:milestone complete — archive milestone after audit passes
-```
-
-### Gaps Found
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠                    ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Phase {N}: {Name}**
-
-Score: {X}/{Y} must-haves verified
-Report: .planning/phases/{phase_dir}/VERIFICATION.md
-
-### What's Missing
-
-{Extract gap summaries from VERIFICATION.md}
-
-╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Plan gap closure** — create additional plans to complete the phase
-
-/pbr:plan {N} --gaps
-
-<sub>/clear first → fresh context window</sub>
-
-**Also available:**
-- cat .planning/phases/{phase_dir}/VERIFICATION.md — see full report
-- /pbr:review {N} — manual testing before planning
-```
-
----
-
-## Session Banners
-
-Use for session lifecycle transitions (pause/resume):
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► SESSION RESTORED ✓                         ║
-╚══════════════════════════════════════════════════════════════╝
-
-Position: Phase {N} — {phase name}, Plan {M}
-Paused: {ISO datetime}
-Duration: {time since pause}
-
-{Summary of where work left off}
-```
-
-Other session banners: `SESSION SAVED ✓` (pause), `RESUMING SESSION` (resume start).
-
----
-
-## Anti-Patterns
-
-Do NOT:
-- Use varying box/banner widths — always 62-character inner width
-- Use `━━━` heavy bars or `───` thin dividers for banners/sections — use `╔═╗║╚═╝` boxes
-- Mix banner styles (`===`, `---`, `***`) with double-line boxes
-- Skip `PLAN-BUILD-RUN ►` prefix in stage banners
-- Use random emoji (only for milestone complete, `✓` for phase complete)
-- Skip the "Next Up" block after major completions
-- Reference non-Plan-Build-Run commands (always use `/pbr:*` commands)
-- Use non-Plan-Build-Run branding in banners

package/plugins/pbr/scripts/validate-plugin-structure.js

@@ -1,183 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Validates the Plan-Build-Run plugin structure:
- * - Every skill directory has SKILL.md
- * - Every agent file has valid YAML frontmatter (name, description)
- * - hooks.json references existing scripts
- * - No broken relative links in markdown files
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const ROOT = path.resolve(__dirname, '..');
-let errors = 0;
-let warnings = 0;
-
-function error(msg) {
-  console.error(`ERROR: ${msg}`);
-  errors++;
-}
-
-function warn(msg) {
-  console.warn(`WARN: ${msg}`);
-  warnings++;
-}
-
-function info(msg) {
-  console.log(`OK: ${msg}`);
-}
-
-// 1. Check plugin.json exists
-const pluginJsonPath = path.join(ROOT, '.claude-plugin', 'plugin.json');
-if (!fs.existsSync(pluginJsonPath)) {
-  error('.claude-plugin/plugin.json missing');
-} else {
-  try {
-    const plugin = JSON.parse(fs.readFileSync(pluginJsonPath, 'utf8'));
-    if (!plugin.name) error('plugin.json missing "name" field');
-    if (!plugin.version) error('plugin.json missing "version" field');
-    if (!plugin.description) error('plugin.json missing "description" field');
-    info(`Plugin: ${plugin.name} v${plugin.version}`);
-  } catch (e) {
-    error(`plugin.json is not valid JSON: ${e.message}`);
-  }
-}
-
-// 2. Check every skill directory has SKILL.md
-const skillsDir = path.join(ROOT, 'skills');
-if (fs.existsSync(skillsDir)) {
-  const skillDirs = fs.readdirSync(skillsDir, { withFileTypes: true })
-    .filter(d => d.isDirectory() && d.name !== 'shared');
-
-  for (const dir of skillDirs) {
-    const skillMd = path.join(skillsDir, dir.name, 'SKILL.md');
-    if (!fs.existsSync(skillMd)) {
-      error(`skills/${dir.name}/ missing SKILL.md`);
-    } else {
-      const content = fs.readFileSync(skillMd, 'utf8');
-      if (!content.startsWith('---')) {
-        error(`skills/${dir.name}/SKILL.md missing YAML frontmatter`);
-      } else {
-        const frontmatter = content.split('---')[1];
-        if (!frontmatter.includes('name:')) {
-          error(`skills/${dir.name}/SKILL.md frontmatter missing "name" field`);
-        }
-        if (!frontmatter.includes('description:')) {
-          error(`skills/${dir.name}/SKILL.md frontmatter missing "description" field`);
-        }
-      }
-      // Check: skills with Task in allowed-tools must have Context Budget section
-      const frontmatterBlock = content.split('---')[1] || '';
-      const hasTaskTool = /allowed-tools:.*Task/.test(frontmatterBlock);
-      if (hasTaskTool && !content.includes('## Context Budget')) {
-        warn(`skills/${dir.name}/SKILL.md has Task in allowed-tools but no "## Context Budget" section`);
-      }
-
-      info(`Skill: /pbr:${dir.name}`);
-    }
-  }
-} else {
-  error('skills/ directory missing');
-}
-
-// 3. Check every agent file has valid frontmatter
-const agentsDir = path.join(ROOT, 'agents');
-if (fs.existsSync(agentsDir)) {
-  const agentFiles = fs.readdirSync(agentsDir)
-    .filter(f => f.endsWith('.md'));
-
-  for (const file of agentFiles) {
-    const content = fs.readFileSync(path.join(agentsDir, file), 'utf8');
-    if (!content.startsWith('---')) {
-      error(`agents/${file} missing YAML frontmatter`);
-    } else {
-      const frontmatter = content.split('---')[1];
-      if (!frontmatter.includes('name:')) {
-        error(`agents/${file} frontmatter missing "name" field`);
-      }
-      if (!frontmatter.includes('description:')) {
-        error(`agents/${file} frontmatter missing "description" field`);
-      }
-      const nameMatch = frontmatter.match(/name:\s*(.+)/);
-      info(`Agent: ${nameMatch ? nameMatch[1].trim() : file}`);
-    }
-  }
-} else {
-  error('agents/ directory missing');
-}
-
-// 4. Check context files have valid structure
-const contextsDir = path.join(ROOT, 'contexts');
-if (fs.existsSync(contextsDir)) {
-  const contextFiles = fs.readdirSync(contextsDir)
-    .filter(f => f.endsWith('.md'));
-
-  for (const file of contextFiles) {
-    const content = fs.readFileSync(path.join(contextsDir, file), 'utf8');
-    if (!content.startsWith('#')) {
-      warn(`contexts/${file} should start with a heading`);
-    }
-    const name = file.replace('.md', '');
-    info(`Context: ${name}`);
-  }
-} else {
-  warn('contexts/ directory not found (contexts are optional)');
-}
-
-// 5. Check hooks.json references existing scripts
-const hooksJsonPath = path.join(ROOT, 'hooks', 'hooks.json');
-if (fs.existsSync(hooksJsonPath)) {
-  try {
-    const hooksFile = JSON.parse(fs.readFileSync(hooksJsonPath, 'utf8'));
-
-    // Plugin hooks format: { hooks: { EventName: [ { matcher?, hooks: [ { type, command } ] } ] } }
-    const hooksObj = hooksFile.hooks || {};
-    for (const eventName of Object.keys(hooksObj)) {
-      const matcherGroups = hooksObj[eventName];
-      if (!Array.isArray(matcherGroups)) continue;
-      for (const group of matcherGroups) {
-        const handlers = group.hooks || [];
-        for (const handler of handlers) {
-          if (handler.command) {
-            const cmd = handler.command.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, ROOT);
-            // Handle run-hook.js bootstrap pattern: command ends with "run-hook.js\" scriptName.js"
-            const runHookMatch = cmd.match(/run-hook\.js[^"]*\)?\)?"?\s+(\S+\.js)/);
-            if (runHookMatch) {
-              // Script is dispatched via run-hook.js — look in scripts/ dir
-              const scriptName = runHookMatch[1];
-              const resolvedPath = path.join(ROOT, 'scripts', scriptName);
-              if (!fs.existsSync(resolvedPath)) {
-                error(`hooks.json references missing script: ${scriptName}`);
-              }
-            } else {
-              const parts = cmd.split(' ');
-              const scriptPart = parts.find(p => p.endsWith('.js'));
-              if (scriptPart) {
-                const scriptPath = scriptPart.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, ROOT);
-                const resolvedPath = path.isAbsolute(scriptPath) ? scriptPath : path.join(ROOT, scriptPath);
-                if (!fs.existsSync(resolvedPath)) {
-                  error(`hooks.json references missing script: ${scriptPart}`);
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-    info('hooks.json validated');
-  } catch (e) {
-    error(`hooks.json is not valid JSON: ${e.message}`);
-  }
-} else {
-  warn('hooks/hooks.json not found (hooks are optional)');
-}
-
-// 6. Summary
-console.log('\n---');
-console.log(`Validation complete: ${errors} errors, ${warnings} warnings`);
-
-if (errors > 0) {
-  process.exit(1);
-}

package/plugins/pbr/skills/milestone/templates/audit-report.md.tmpl

@@ -1,48 +0,0 @@
-# Template: Milestone Audit Report
-# Used by: milestone/SKILL.md (audit subcommand, Step 5)
-# Variables: {version}, {status}, {date}, {phase entries}, {integration results}, {requirements}, {tech debt}
-
----
-milestone: "{version}"
-status: "{passed | gaps_found | tech_debt}"
-date: "{ISO date}"
----
-
-# Milestone Audit: {version}
-
-## Overall Status: {PASSED / GAPS FOUND / TECH DEBT}
-
-## Phase Verification Summary
-
-| Phase | Verified | Gaps | Integration |
-|-------|----------|------|-------------|
-| {N}. {name} | {yes/no} | {count} | {ok/issues} |
-
-## Integration Check Results
-
-### Dependency Graph
-{Mermaid or ASCII representation of phase dependencies}
-
-### Integration Issues
-{List of integration problems found, or "None"}
-
-- **{Issue}**: {description}
-  - Affected phases: {list}
-  - Severity: {critical/high/medium/low}
-  - Suggested fix: {brief suggestion}
-
-## Requirements Coverage
-
-| Requirement | Status | Verified By |
-|-------------|--------|-------------|
-| {req} | {covered/uncovered} | {phase/plan or "N/A"} |
-
-## Tech Debt Identified
-
-{Issues that don't block the milestone but should be addressed}
-
-- {debt item}: {description}
-
-## Recommendations
-
-{Summary of what needs to be done, if anything}