@sienklogic/plan-build-run 2.11.0 → 2.12.1

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}

package/plugins/pbr/skills/shared/progress-display.md

@@ -1,53 +0,0 @@
-# Progress Display Fragment
-
-Standard progress display formats for all skills. Reference `references/ui-formatting.md` for the full brand guide.
-
-## Progress Bar
-
-Always 20 characters wide using `█` (filled) and `░` (empty):
-
-```
-Progress: [████████████░░░░░░░░] 60%
-```
-
-Calculate: `filled = Math.round(percent / 5)`, `empty = 20 - filled`
-
-## Phase Table
-
-Use when displaying multiple phases (status, milestone skills):
-
-```
-| Phase | Name             | Status    | Plans | Progress |
-|-------|------------------|-----------|-------|----------|
-| 01    | Setup            | ✓ complete | 2/2   | 100%     |
-| 02    | Authentication   | ◐ building | 1/3   | 33%      |
-| 03    | Dashboard        | ○ pending  | 0/4   | 0%       |
-```
-
-## Status Indicators
-
-| Symbol | Meaning | When to use |
-|--------|---------|-------------|
-| `✓` | Complete | Phase/plan/task finished |
-| `✗` | Failed | Verification failed |
-| `○` | Pending | Not started |
-| `◐` | In Progress | Currently executing |
-| `?` | Needs Human | Checkpoint requiring user action |
-| `⚠` | Warning | Non-blocking issue |
-| `⊘` | Blocked | Waiting on dependency |
-
-## Wave Progress (build skill)
-
-```
-Wave 1: ✓ Plan 01, ✓ Plan 02
-Wave 2: ◐ Plan 03 (executing)
-Wave 3: ○ Plan 04, ○ Plan 05
-```
-
-## Compact Status Line
-
-For inline status updates:
-
-```
-Phase 3 of 8 (Auth) — building — [████████░░░░░░░░░░░░] 40%
-```

package/plugins/pbr/skills/shared/state-loading.md

@@ -1,62 +0,0 @@
-# State Loading Pattern
-
-Standard pattern for loading project state at the start of a skill invocation. Include this fragment in skills that need project context.
-
----
-
-## Minimal State Read (for simple skills)
-
-Use when the skill only needs to know the current position. Skills: status, help, note, todo, pause, config.
-STATE.md is lean — it contains only current-phase context. Historical data lives in HISTORY.md.
-
-```
-1. Read .planning/STATE.md lines 1-20 only
-2. Extract: current phase, plan, status
-3. If STATE.md missing: inform user, suggest /pbr:begin
-```
-
-## Full State Read (for workflow skills)
-
-Use when the skill needs complete project context. Skills: build, plan, review, begin, milestone, continue, resume, debug.
-
-Reading order (always this sequence):
-
-```
-1. Read .planning/STATE.md
-   - Extract: Current Position section (phase, plan, status)
-   - Extract: Blockers/Concerns section (if not "None")
-   - Extract: Session Continuity section (if present)
-
-2. Read .planning/config.json
-   - Extract: depth, mode, features flags
-   - Extract: models configuration
-   - Extract: gates configuration
-
-3. Read .planning/ROADMAP.md (if exists)
-   - Extract: Phase Overview table (current + next 2 phases)
-   - Extract: dependency chain for current phase
-   - Do NOT read full phase details for past phases
-
-4. Read .planning/HISTORY.md (ONLY when cross-phase context is needed)
-   - Do NOT read HISTORY.md for normal build/plan/review operations
-   - Read ONLY when: debugging a regression that may trace to a prior phase,
-     or when a milestone audit needs historical context
-   - Use: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history load`
-   - This returns structured JSON -- do not read the raw file
-```
-
-## Error Handling
-
-| File Missing | Action |
-|-------------|--------|
-| STATE.md | Warn user: "No STATE.md found. Run /pbr:begin to initialize." |
-| config.json | Use defaults (depth: standard, mode: interactive) |
-| ROADMAP.md | Continue without roadmap context (acceptable for quick tasks) |
-| .planning/ dir | Exit: "No .planning directory. This is not a Plan-Build-Run project." |
-
-## What NOT to Read During State Loading
-
-- Full SUMMARY.md bodies from prior phases (read frontmatter only if needed)
-- Agent definition files (agents/*.md) — auto-loaded by subagent_type
-- PLAN.md files from other phases (only current phase plans)
-- .planning/logs/ files (only health skill reads these)

package/plugins/pbr/templates/RESEARCH-SUMMARY.md.tmpl

@@ -1,97 +0,0 @@
-# Research Summary
-
-> Synthesized: {date}
-> Input documents: {count}
-> Sources: {list of document names/paths}
-
-## Executive Summary
-
-{3-5 sentences maximum. What was researched, the single most important conclusion, and the recommended approach. This paragraph should give a planner enough context to start planning without reading further.}
-
-## Recommended Stack
-
-{Only include if project-level synthesis. For phase-level, skip this section.}
-
-| Layer | Choice | Version | Confidence | Alternatives | Source |
-|-------|--------|---------|------------|-------------|--------|
-| Runtime | {Node.js} | {20.x} | HIGH | {Bun, Deno} | {Doc A, Doc B} |
-| Framework | {Next.js} | {14.x} | HIGH | {Remix, Astro} | {Doc A} |
-| Database | {PostgreSQL} | {16.x} | HIGH | {MySQL} | {Doc A, Doc C} |
-| ORM | {Prisma} | {5.x} | MEDIUM | {Drizzle, TypeORM} | {Doc B} |
-| Auth | {NextAuth.js} | {5.x} | MEDIUM | {Clerk, Auth0} | {Doc A} |
-| Hosting | {Vercel} | - | MEDIUM | {AWS, Railway} | {Doc C} |
-| Testing | {Vitest} | {1.x} | HIGH | {Jest} | {Doc B} |
-
-### Stack Rationale
-
-{Brief explanation of why this combination. 2-3 sentences.}
-
-## Architecture Recommendations
-
-{Key architectural decisions informed by research. Use bullet points.}
-
-- **Pattern**: {Recommended pattern with rationale}
-- **Data flow**: {How data should move through the system}
-- **Separation**: {How to organize the code}
-- **State**: {How to manage state}
-
-## Key Patterns
-
-{Patterns to follow during implementation.}
-
-| Pattern | When to Use | Example |
-|---------|------------|---------|
-| {Repository} | {Database access} | {Brief code hint} |
-| {Middleware} | {Auth, logging, validation} | {Brief code hint} |
-| {DTO validation} | {API input/output} | {Zod schemas} |
-
-## Pitfalls & Warnings
-
-{Ranked by severity. These are the things most likely to cause problems.}
-
-| # | Pitfall | Severity | Source | Mitigation |
-|---|---------|----------|--------|------------|
-| 1 | {Most critical pitfall} | CRITICAL | {Doc A} | {How to avoid} |
-| 2 | {Second pitfall} | HIGH | {Doc B, Doc C} | {How to avoid} |
-| 3 | {Third pitfall} | MEDIUM | {Doc A} | {How to avoid} |
-
-## Contradictions Resolved
-
-{Where input documents disagreed and how it was resolved.}
-
-| Topic | Position A | Position B | Resolution | Basis |
-|-------|-----------|-----------|------------|-------|
-| {Database} | PostgreSQL (Doc A, C) | MongoDB (Doc B) | PostgreSQL | Majority + S2 source |
-| {Auth} | JWT (Doc A, B) | Sessions (Doc C) | JWT | Majority + better for API |
-
-{If any contradictions could not be resolved:}
-
-### Unresolved: {Topic}
-
-**Options**: {A} vs {B}
-**Trade-offs**: {A is better for X, B is better for Y}
-**Recommendation**: {best guess} `[NEEDS DECISION]`
-
-## Open Questions
-
-{Things that none of the research documents could definitively answer.}
-
-1. {Question} -- Impact: {what planning/implementation is blocked by this}
-2. {Question} -- Impact: {what planning/implementation is blocked by this}
-
-## Additional Notes
-
-{P3 (Nice to Know) items. Brief bullet points only.}
-
-- {Performance tip from Doc A}
-- {Future consideration from Doc C}
-- {Alternative approach worth noting from Doc B}
-
-## Sources
-
-{Consolidated source list from all input documents.}
-
-| # | Document | Key Contribution | Confidence |
-|---|----------|-----------------|------------|
-| 1 | {path/name} | {what it contributed} | {overall confidence} |
-| 2 | {path/name} | {what it contributed} | {overall confidence} |

package/plugins/pbr/templates/research/ARCHITECTURE.md.tmpl

@@ -1,124 +0,0 @@
-<!-- Source: agents/researcher.md | Purpose: Output format for research project ARCHITECTURE.md -->
-# Architecture Research
-
-**Domain:** {domain}
-**Researched:** {date}
-**Confidence:** {confidence}
-
-## Standard Architecture
-
-### System Overview
-
-```
-{ascii_architecture_diagram}
-```
-
-### Component Responsibilities
-
-| Component | Responsibility | Typical Implementation |
-|-----------|----------------|------------------------|
-| {component} | {responsibility} | {implementation} |
-
-## Recommended Project Structure
-
-```
-src/
-{project_structure}
-```
-
-### Structure Rationale
-
-- **{folder}/:** {rationale}
-
-## Architectural Patterns
-
-### Pattern 1: {pattern_name}
-
-**What:** {description}
-**When to use:** {conditions}
-**Trade-offs:** {pros_and_cons}
-
-**Example:**
-```{language}
-{code_example}
-```
-
-### Pattern 2: {pattern_name}
-
-**What:** {description}
-**When to use:** {conditions}
-**Trade-offs:** {pros_and_cons}
-
-### Pattern 3: {pattern_name}
-
-**What:** {description}
-**When to use:** {conditions}
-**Trade-offs:** {pros_and_cons}
-
-## Data Flow
-
-### Request Flow
-
-```
-{request_flow_diagram}
-```
-
-### State Management
-
-```
-{state_management_diagram}
-```
-
-### Key Data Flows
-
-1. **{flow_name}:** {description}
-2. **{flow_name}:** {description}
-
-## Scaling Considerations
-
-| Scale | Architecture Adjustments |
-|-------|--------------------------|
-| 0-1k users | {approach} |
-| 1k-100k users | {approach} |
-| 100k+ users | {approach} |
-
-### Scaling Priorities
-
-1. **First bottleneck:** {description}
-2. **Second bottleneck:** {description}
-
-## Anti-Patterns
-
-### Anti-Pattern 1: {name}
-
-**What people do:** {mistake}
-**Why it's wrong:** {problem}
-**Do this instead:** {correct_approach}
-
-### Anti-Pattern 2: {name}
-
-**What people do:** {mistake}
-**Why it's wrong:** {problem}
-**Do this instead:** {correct_approach}
-
-## Integration Points
-
-### External Services
-
-| Service | Integration Pattern | Notes |
-|---------|---------------------|-------|
-| {service} | {pattern} | {notes} |
-
-### Internal Boundaries
-
-| Boundary | Communication | Notes |
-|----------|---------------|-------|
-| {boundary} | {communication} | {notes} |
-
-## Sources
-
-- {sources}
-
----
-*Architecture research for: {domain}*
-*Researched: {date}*

package/plugins/pbr/templates/research/STACK.md.tmpl

@@ -1,71 +0,0 @@
-<!-- Source: agents/researcher.md | Purpose: Output format for research project STACK.md (external tech evaluation) -->
-# Stack Research
-
-**Domain:** {domain}
-**Researched:** {date}
-**Confidence:** {confidence}
-
-## Recommended Stack
-
-### Core Technologies
-
-| Technology | Version | Purpose | Why Recommended |
-|------------|---------|---------|-----------------|
-| {technology} | {version} | {purpose} | {rationale} |
-
-### Supporting Libraries
-
-| Library | Version | Purpose | When to Use |
-|---------|---------|---------|-------------|
-| {library} | {version} | {purpose} | {use_case} |
-
-### Development Tools
-
-| Tool | Purpose | Notes |
-|------|---------|-------|
-| {tool} | {purpose} | {notes} |
-
-## Installation
-
-```bash
-# Core
-{core_install_commands}
-
-# Supporting
-{supporting_install_commands}
-
-# Dev dependencies
-{dev_install_commands}
-```
-
-## Alternatives Considered
-
-| Recommended | Alternative | When to Use Alternative |
-|-------------|-------------|-------------------------|
-| {our_choice} | {alternative} | {conditions} |
-
-## What NOT to Use
-
-| Avoid | Why | Use Instead |
-|-------|-----|-------------|
-| {technology} | {problem} | {alternative} |
-
-## Stack Patterns by Variant
-
-**If {condition}:**
-- Use {variation}
-- Because {reason}
-
-## Version Compatibility
-
-| Package A | Compatible With | Notes |
-|-----------|-----------------|-------|
-| {package_a} | {package_b} | {notes} |
-
-## Sources
-
-- {sources}
-
----
-*Stack research for: {domain}*
-*Researched: {date}*