@sienklogic/plan-build-run 2.0.0

package/plugins/pbr/skills/shared/domain-probes.md

@@ -0,0 +1,125 @@
+# Domain-Aware Probing Patterns
+
+Shared reference for `/pbr:explore`, `/pbr:begin`, and `/pbr:discuss`.
+
+When the user mentions a technology area, use these probes to ask insightful follow-up questions. Don't run through them as a checklist — pick the 2-3 most relevant based on context. The goal is to surface hidden assumptions and trade-offs the user may not have considered yet.
+
+---
+
+## Authentication
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "login" or "auth" | OAuth (which providers?), JWT, or session-based? Do you need social login or just email/password? |
+| "users" or "accounts" | MFA required? Password reset flow? Email verification? |
+| "sessions" | Session duration and refresh strategy? Server-side sessions or stateless tokens? |
+| "roles" or "permissions" | RBAC, ABAC, or simple role checks? How many distinct roles? |
+| "API keys" | Key rotation strategy? Scoped permissions per key? Rate limiting per key? |
+
+---
+
+## Real-Time Updates
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "real-time" or "live updates" | WebSockets, SSE, or polling? What specifically needs to be real-time vs. eventual? |
+| "notifications" | Push notifications (browser/mobile), in-app only, or both? Persistence and read receipts? |
+| "collaboration" or "multiplayer" | Conflict resolution strategy? Operational transforms or CRDTs? Expected concurrent users? |
+| "chat" or "messaging" | Message history and search? Typing indicators? Read receipts? |
+| "streaming" | Reconnection strategy? What happens when the connection drops — queue or discard? |
+
+---
+
+## Dashboard
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "dashboard" | What data sources feed it? How many distinct views? |
+| "charts" or "graphs" | Interactive or static? Drill-down capability? Export to CSV/PDF? |
+| "metrics" or "KPIs" | Refresh strategy — real-time, periodic polling, or on-demand? Acceptable staleness? |
+| "admin panel" | Role-based visibility? Which actions beyond viewing (edit, delete, approve)? |
+| "mobile" or "responsive" | Simplified mobile view or full parity? Touch interactions for charts? |
+
+---
+
+## API Design
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "API" | REST, GraphQL, or RPC-style? Internal only or public-facing? |
+| "endpoints" or "routes" | Versioning strategy (URL path, header, query param)? Breaking change policy? |
+| "pagination" | Cursor-based or offset? Expected result set sizes? Stable ordering guarantee? |
+| "rate limiting" | Per-user, per-IP, or per-API-key? Burst allowance? How to communicate limits to clients? |
+| "errors" | Structured error format? Error codes vs. messages? How much detail in production errors? |
+
+---
+
+## Database
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "database" or "storage" | SQL or NoSQL? What drives the choice — relational integrity, flexibility, scale? |
+| "ORM" or "queries" | ORM (which one?) or raw queries? Query builder as middle ground? |
+| "migrations" | Migration tool? Rollback strategy? How do you handle data migrations vs. schema migrations? |
+| "seeding" or "test data" | Seed data for development? Realistic fake data or minimal fixtures? |
+| "scale" or "performance" | Read/write ratio? Read replicas? Connection pooling strategy? |
+
+---
+
+## Search
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "search" | Full-text or exact match? Dedicated search engine (Elasticsearch, Meilisearch) or database-level? |
+| "filtering" or "facets" | Faceted filtering? How many filter dimensions? Combined filters (AND/OR)? |
+| "autocomplete" or "typeahead" | Debounce strategy? Minimum character threshold? Result ranking? |
+| "indexing" | Index size and update frequency? Real-time indexing or batch? Acceptable index lag? |
+| "fuzzy" or "typo tolerance" | Fuzzy matching? Synonym support? Language-specific stemming? |
+
+---
+
+## File Upload/Storage
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "upload" or "file upload" | Local filesystem or cloud (S3, GCS, Azure Blob)? Direct upload or through server? |
+| "images" or "media" | Processing pipeline — resize, compress, thumbnail generation? Format conversion? |
+| "size limits" | Max file size? Max total storage per user? What happens when limits are hit? |
+| "CDN" | CDN for delivery? Cache invalidation for updated files? Signed URLs for access control? |
+| "documents" or "attachments" | Virus scanning? Preview generation? Versioning of uploaded files? |
+
+---
+
+## Caching
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "caching" or "performance" | Where to cache — browser, CDN, application layer, database query cache? |
+| "invalidation" | Invalidation strategy — TTL, event-driven, or manual? Cache-aside vs. write-through? |
+| "stale data" | Acceptable staleness window? Stale-while-revalidate pattern? |
+| "Redis" or "Memcached" | Cache topology — single node or clustered? Persistence needed or pure cache? |
+| "CDN" or "edge" | Edge caching for static assets? Dynamic content at the edge? Cache key strategy? |
+
+---
+
+## Testing
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "testing" or "tests" | Unit, integration, and E2E balance? Where do you invest most testing effort? |
+| "mocking" or "stubs" | Mock external services or use test containers? Database mocking strategy? |
+| "CI" or "pipeline" | Tests in CI? Parallel test execution? Test-on-PR or test-on-push? |
+| "coverage" | Coverage targets? Coverage as gate or advisory? Which metrics (line, branch, function)? |
+| "E2E" or "browser testing" | Playwright, Cypress, or other? Headed vs. headless? Visual regression testing? |
+
+---
+
+## Deployment
+
+| User mentions | Agent probes with domain knowledge |
+|---|---|
+| "deploy" or "hosting" | Container, serverless, or traditional VM/VPS? Managed platform (Vercel, Railway) or self-hosted? |
+| "CI/CD" or "pipeline" | GitHub Actions, GitLab CI, or other? Deploy on merge to main or manual trigger? |
+| "environments" | How many environments (dev, staging, prod)? Environment parity strategy? |
+| "rollback" | Rollback strategy? Blue-green, canary, or instant rollback? Database rollback considerations? |
+| "secrets" or "config" | Secret management — env vars, vault, or platform-native? Per-environment config strategy? |

package/plugins/pbr/skills/shared/error-reporting.md

@@ -0,0 +1,79 @@
+# Error Reporting Fragment
+
+Standard error display formats for all skills. Reference `references/ui-formatting.md` for the full brand guide.
+
+## Recoverable Error
+
+For errors that don't halt the workflow — skill can suggest a fix or retry:
+
+```
+⚠ Warning: {short description}
+
+{1-2 line explanation of what went wrong}
+
+To fix: {actionable instruction}
+```
+
+Example:
+```
+⚠ Warning: STATE.md is 180 lines (limit: 150)
+
+The state file has grown beyond the recommended size, which increases context usage on load.
+
+To fix: Run /pbr:health to compact the Accumulated Context section.
+```
+
+## Fatal Error
+
+For errors that stop execution — skill cannot continue:
+
+```
+✗ Error: {short description}
+
+{1-2 line explanation}
+
+What to try:
+  1. {first suggestion}
+  2. {second suggestion}
+  3. {fallback — often /pbr:health or manual fix}
+```
+
+Example:
+```
+✗ Error: PLAN.md not found for phase 03
+
+No plan files exist in .planning/phases/03-auth/. The executor cannot run without a plan.
+
+What to try:
+  1. Run /pbr:plan 3 to create a plan first
+  2. Check if the phase directory exists: ls .planning/phases/03-*
+  3. Run /pbr:health to check planning directory integrity
+```
+
+## Validation Error
+
+For format or schema validation failures (config, plan format, commit message):
+
+```
+✗ Validation failed: {what was validated}
+
+Issues:
+  - {specific issue 1}
+  - {specific issue 2}
+
+Expected format: {brief format description or example}
+```
+
+## Hook Block Message
+
+For PreToolUse hooks that reject a tool call:
+
+```
+Blocked: {short reason}
+
+{explanation}
+
+{how to fix or alternative approach}
+```
+
+This format is used by validate-commit.js and check-dangerous-commands.js. The `decision: "block"` and `reason` fields in the JSON output follow this pattern.

package/plugins/pbr/skills/shared/gate-prompts.md

@@ -0,0 +1,388 @@
+# Gate Prompt Patterns
+
+> Referenced by: plan, build, import, scan, review, milestone, config, status, resume, quick, begin, discuss, explore, debug skills
+> Purpose: Reusable AskUserQuestion patterns for structured gate checks
+
+These patterns provide consistent, structured prompts for user decision points. Skills reference these patterns by name to ensure all gate checks use the same format.
+
+## Rules
+
+- `header` must be max 12 characters
+- `multiSelect` is always `false` for gate checks
+- Always handle the "Other" case (user typed a freeform response instead of selecting)
+
+---
+
+## Pattern: approve-revise-abort
+
+3-option gate for plan approval, gap-closure approval.
+
+```
+Use AskUserQuestion:
+  question: "Approve these {noun}?"
+  header: "Approve?"
+  options:
+    - label: "Approve"          description: "Proceed with {action}"
+    - label: "Request changes"  description: "Discuss adjustments before proceeding"
+    - label: "Abort"            description: "Cancel this operation"
+  multiSelect: false
+```
+
+---
+
+## Pattern: yes-no
+
+Simple 2-option confirmation for re-planning, rebuild, replace plans, commit.
+
+```
+Use AskUserQuestion:
+  question: "{Specific question about the action}"
+  header: "Confirm"
+  options:
+    - label: "Yes"  description: "{What happens if yes}"
+    - label: "No"   description: "{What happens if no}"
+  multiSelect: false
+```
+
+---
+
+## Pattern: stale-continue
+
+2-option refresh gate for staleness warnings, timestamp freshness.
+
+```
+Use AskUserQuestion:
+  question: "{Artifact} may be outdated. Refresh or continue?"
+  header: "Stale"
+  options:
+    - label: "Refresh"          description: "Update before proceeding (recommended)"
+    - label: "Continue anyway"  description: "Proceed with current version"
+  multiSelect: false
+```
+
+---
+
+## Pattern: yes-no-pick
+
+3-option selection for seed selection, item inclusion.
+
+```
+Use AskUserQuestion:
+  question: "Include {items} in planning?"
+  header: "Include?"
+  options:
+    - label: "Yes, all"     description: "Include all matching items"
+    - label: "Let me pick"  description: "Choose which items to include"
+    - label: "No"           description: "Proceed without these items"
+  multiSelect: false
+```
+
+---
+
+## Pattern: multi-option-failure
+
+4-option failure handler for build failures.
+
+```
+Use AskUserQuestion:
+  question: "Plan {id} failed. How should we proceed?"
+  header: "Failed"
+  options:
+    - label: "Retry"     description: "Re-run this plan's executor"
+    - label: "Skip"      description: "Mark as skipped, continue to next wave"
+    - label: "Rollback"  description: "Undo commits, revert to last good state"
+    - label: "Abort"     description: "Stop the entire build"
+  multiSelect: false
+```
+
+---
+
+## Pattern: multi-option-escalation
+
+4-option escalation for review escalation (max AskUserQuestion supports).
+
+```
+Use AskUserQuestion:
+  question: "Phase {N} has failed verification {attempt} times. How should we proceed?"
+  header: "Escalate"
+  options:
+    - label: "Accept gaps"  description: "Mark as complete-with-gaps and move on"
+    - label: "Re-plan"      description: "Go back to /pbr:plan with gap context"
+    - label: "Debug"        description: "Spawn /pbr:debug to investigate root causes"
+    - label: "Retry"        description: "Try one more verification cycle"
+  multiSelect: false
+```
+
+Note: AskUserQuestion supports max 4 options. The original review escalation had 5 options (accept-gaps/re-plan/debug/override/retry). The "override" option is folded into the post-selection flow: if user selects "Accept gaps", offer a follow-up AskUserQuestion asking whether to accept all gaps or pick specific ones (the "override" behavior).
+
+---
+
+## Pattern: multi-option-gaps
+
+4-option gap handler for review gaps-found.
+
+```
+Use AskUserQuestion:
+  question: "{count} verification gaps need attention. How should we proceed?"
+  header: "Gaps"
+  options:
+    - label: "Auto-fix"  description: "Diagnose root causes and create fix plans (recommended)"
+    - label: "Override"   description: "Accept specific gaps as false positives"
+    - label: "Manual"     description: "I'll fix these myself"
+    - label: "Skip"       description: "Save results for later"
+  multiSelect: false
+```
+
+---
+
+## Pattern: multi-option-priority
+
+4-option priority selection for milestone gap priority.
+
+```
+Use AskUserQuestion:
+  question: "Which gaps should we address?"
+  header: "Priority"
+  options:
+    - label: "Must-fix only"   description: "Address critical/high gaps only"
+    - label: "Must + should"   description: "Address critical, high, and medium gaps"
+    - label: "Everything"      description: "Address all gaps including low priority"
+    - label: "Let me pick"     description: "Choose specific gaps to address"
+  multiSelect: false
+```
+
+---
+
+## Pattern: settings-category-select
+
+4-option menu for configuration category selection (config skill).
+
+```
+Use AskUserQuestion:
+  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"
+  multiSelect: false
+```
+
+Note: Original 7 categories condensed to 4. "Models" (per-agent) merged into "Model profile". "Gates" and "Parallelization" merged into "Features". After selection, show a category-specific follow-up AskUserQuestion.
+
+---
+
+## Pattern: toggle-confirm
+
+2-option confirmation for enabling/disabling boolean features (config skill).
+
+```
+Use AskUserQuestion:
+  question: "Enable {feature_name}?"
+  header: "Toggle"
+  options:
+    - label: "Enable"   description: "Turn this feature on"
+    - label: "Disable"  description: "Turn this feature off"
+  multiSelect: false
+```
+
+---
+
+## Pattern: model-profile-select
+
+4-option selection for model profile presets (config skill).
+
+```
+Use AskUserQuestion:
+  question: "Select model profile"
+  header: "Profile"
+  options:
+    - label: "Quality"    description: "opus for all agents (highest cost)"
+    - label: "Balanced"   description: "sonnet/inherit mix (default)"
+    - label: "Budget"     description: "haiku for all agents (lowest cost)"
+    - label: "Adaptive"   description: "sonnet planning, haiku execution"
+  multiSelect: false
+```
+
+---
+
+## Pattern: action-routing
+
+Up to 4 suggested next actions with selection (status, resume skills).
+
+```
+Use AskUserQuestion:
+  question: "What would you like to do next?"
+  header: "Next Step"
+  options:
+    - label: "{primary action}"   description: "{explanation}"
+    - label: "{alternative 1}"    description: "{explanation}"
+    - label: "{alternative 2}"    description: "{explanation}"
+    - label: "Something else"     description: "Enter a different command"
+  multiSelect: false
+```
+
+Note: Dynamically generate options from workflow state. The "Something else" option allows freeform input. Build 1-3 real options + always include "Something else" as the last option. If only 1 real option exists, use the yes-no pattern instead.
+
+---
+
+## Pattern: pause-point-select
+
+Select from multiple resume points (resume skill).
+
+```
+Use AskUserQuestion:
+  question: "Found multiple pause points. Which would you like to resume?"
+  header: "Resume"
+  options:
+    - label: "Phase {A}"  description: "Paused {date}"
+    - label: "Phase {B}"  description: "Paused {date}"
+    - label: "Phase {C}"  description: "Paused {date}"
+    - label: "Phase {D}"  description: "Paused {date}"
+  multiSelect: false
+```
+
+Note: If more than 4 pause points exist, show the 4 most recent. The oldest option becomes "Show earlier" which re-prompts with the next batch.
+
+---
+
+## Pattern: scope-confirm
+
+3-option confirmation for quick task scope validation (quick skill).
+
+```
+Use AskUserQuestion:
+  question: "This task looks complex. Proceed as quick task or use full planning?"
+  header: "Scope"
+  options:
+    - label: "Quick task"  description: "Execute as lightweight task"
+    - label: "Full plan"   description: "Switch to /pbr:plan for proper planning"
+    - label: "Revise"      description: "Let me rewrite the task description"
+  multiSelect: false
+```
+
+---
+
+## Pattern: depth-select
+
+3-option depth selection for begin skill workflow preferences.
+
+```
+Use AskUserQuestion:
+  question: "How thorough should planning be?"
+  header: "Depth"
+  options:
+    - label: "Quick"           description: "3-5 phases, skip research, ~50% cheaper"
+    - label: "Standard"        description: "5-8 phases with research (default)"
+    - label: "Comprehensive"   description: "8-12 phases, deep research, ~2x cost"
+  multiSelect: false
+```
+
+---
+
+## Pattern: git-strategy-select
+
+3-option git branching strategy for begin skill.
+
+```
+Use AskUserQuestion:
+  question: "Git branching strategy?"
+  header: "Git"
+  options:
+    - label: "None"                description: "Commit to current branch (default)"
+    - label: "Phase branches"      description: "Create a branch per phase"
+    - label: "Milestone branches"  description: "Create a branch per milestone"
+  multiSelect: false
+```
+
+---
+
+## Pattern: context-handling
+
+3-option handler for existing CONTEXT.md in discuss skill.
+
+```
+Use AskUserQuestion:
+  question: "Phase {N} already has a CONTEXT.md. How should we handle it?"
+  header: "Context"
+  options:
+    - label: "Overwrite"  description: "Replace with new decisions"
+    - label: "Append"     description: "Add new decisions below existing ones"
+    - label: "Cancel"     description: "Keep existing and stop"
+  multiSelect: false
+```
+
+---
+
+## Pattern: gray-area-option
+
+Dynamic template for presenting gray area choices in discuss skill.
+
+```
+Use AskUserQuestion:
+  question: "{Gray area title}"
+  header: "Decision"
+  options:
+    - label: "{Option 1}"        description: "{Concrete approach 1}"
+    - label: "{Option 2}"        description: "{Concrete approach 2}"
+    - label: "Let Claude decide"  description: "Mark as Claude's Discretion"
+  multiSelect: false
+```
+
+Note: Options are generated at runtime based on phase analysis. The pattern defines the structure; the skill fills in options per gray area. Always include "Let Claude decide" as the last option. If more than 4 options are identified, split into a 2-step flow (AskUserQuestion supports max 4 options).
+
+---
+
+## Pattern: output-routing
+
+4-option confirmation for explore skill output proposals.
+
+```
+Use AskUserQuestion:
+  question: "How do you want to handle these proposed outputs?"
+  header: "Outputs"
+  options:
+    - label: "Approve all"  description: "Create all suggested artifacts"
+    - label: "Adjust"       description: "Modify the proposals before creating"
+    - label: "Add more"     description: "I have additional outputs to capture"
+    - label: "Skip"         description: "Don't create any artifacts from this session"
+  multiSelect: false
+```
+
+---
+
+## Pattern: debug-session-select
+
+Dynamic template for debug session selection.
+
+```
+Use AskUserQuestion:
+  question: "Found active debug sessions. Which would you like?"
+  header: "Debug"
+  options:
+    - label: "#{NNN}: {title}"  description: "Started {date}, last: {hypothesis}"
+    - label: "#{NNN}: {title}"  description: "Started {date}, last: {hypothesis}"
+    - label: "#{NNN}: {title}"  description: "Started {date}, last: {hypothesis}"
+    - label: "New session"      description: "Start a fresh debug investigation"
+  multiSelect: false
+```
+
+Note: Options are generated at runtime from active debug sessions. If more than 3 active sessions exist, show the 3 most recent plus "New session" (max 4 options). Older sessions can be accessed by running `/pbr:debug` with the session number.
+
+---
+
+## Pattern: debug-checkpoint
+
+3-option checkpoint response during debug investigation.
+
+```
+Use AskUserQuestion:
+  question: "Investigation has reached a checkpoint. How should we proceed?"
+  header: "Continue?"
+  options:
+    - label: "Continue"       description: "Keep investigating with current findings"
+    - label: "More info"      description: "I have additional context to share"
+    - label: "New approach"   description: "Try a different investigation angle"
+  multiSelect: false
+```

package/plugins/pbr/skills/shared/phase-argument-parsing.md

@@ -0,0 +1,45 @@
+# Phase Argument Parsing
+
+How skills parse and validate phase number arguments from `$ARGUMENTS`.
+
+## Parsing Rules
+
+1. **Integer phases**: `3` → Phase 3 (standard phase)
+2. **Decimal phases**: `3.1` → Phase 3.1 (inserted phase)
+3. **Zero-padded**: `03` → Phase 3 (strip leading zeros for display, keep for file paths)
+4. **No argument**: Use current phase from STATE.md
+
+## Normalization
+
+```
+Input       → Normalized  → Directory Name
+"3"         → 3           → 03-{slug}
+"03"        → 3           → 03-{slug}
+"3.1"       → 3.1         → 03.1-{slug}
+""          → (current)   → (read from STATE.md)
+```
+
+## Validation
+
+1. Phase number must be numeric (integer or decimal with one decimal place)
+2. Phase must exist in ROADMAP.md (or be a valid target for insert/add)
+3. Phase must be in the expected state for the operation:
+   - `/pbr:plan N` — phase must not already have plans (unless re-planning)
+   - `/pbr:build N` — phase must have plans
+   - `/pbr:review N` — phase must have been built (SUMMARY.md files exist)
+
+## Finding Phase Directory
+
+```
+Given phase number N:
+1. List directories in .planning/phases/
+2. Find directory matching pattern: {NN}-* or {N.M}-*
+3. If not found, check ROADMAP.md for phase name
+4. If still not found, error: "Phase N not found"
+```
+
+## Error Messages
+
+- No argument and no current phase: "Which phase? Specify a number or run /pbr:status to see where you are."
+- Phase not found: "Phase {N} not found in .planning/phases/. Run /pbr:status to see available phases."
+- Wrong state: "Phase {N} hasn't been planned yet. Run /pbr:plan {N} first."

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

@@ -0,0 +1,53 @@
+# 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%
+```