@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plan-build-run/skills/shared/config-loading.md

@@ -0,0 +1,102 @@
+# Config Loading Pattern
+
+Standard pattern for loading `.planning/config.json` fields at the start of a skill invocation.
+
+> Referenced by: build, plan, review, import, begin, quick, milestone, scan skills
+
+---
+
+## Tooling Shortcut
+
+Instead of reading and parsing STATE.md, ROADMAP.md, and config.json manually, run:
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load
+```
+This returns a JSON object with `config`, `state`, `roadmap`, `current_phase`, and `progress`. Falls back gracefully if the script is missing -- parse files manually in that case.
+
+Additional tooling shortcuts:
+- `plan-index <phase>` -- returns plan inventory (plan_id, wave, depends_on, autonomous, must_haves_count per plan)
+- `phase-info <phase>` -- returns comprehensive phase status (verification, summaries, roadmap_status, filesystem_status, plan_count, completed)
+
+---
+
+## Standard Config Fields
+
+These are the config.json fields commonly read by workflow skills. Each skill reads a subset depending on its needs.
+
+### Core Settings
+```
+depth                 -- quick | standard | comprehensive
+mode                  -- interactive | autonomous
+```
+
+### Feature Flags
+```
+features.research_phase        -- run researcher before planning
+features.plan_checking         -- validate plans via plan-checker agent
+features.goal_verification     -- run verifier after build
+features.inline_verify         -- per-task verification after each executor commit (opt-in)
+features.atomic_commits        -- require atomic commits per task
+features.auto_continue         -- write .auto-next signal on phase completion
+features.auto_advance          -- chain build->review->plan in autonomous mode
+features.integration_verification -- check cross-phase integration
+```
+
+### Gate Flags
+```
+gates.confirm_plan             -- require user approval before building
+gates.confirm_execute          -- require user confirmation before executing build
+gates.confirm_transition       -- require confirmation before advancing to next phase
+```
+
+### Parallelization
+```
+parallelization.enabled        -- whether to run plans in parallel
+parallelization.plan_level     -- parallel at plan level (within a wave)
+parallelization.max_concurrent_agents -- max simultaneous executors
+```
+
+### Planning
+```
+planning.commit_docs           -- commit planning docs after operations
+planning.max_tasks_per_plan    -- maximum tasks in a single plan
+```
+
+### Git
+```
+git.commit_format              -- commit message format
+git.branching         -- none | phase | milestone
+```
+
+### Models
+```
+models.researcher              -- model for researcher agent
+models.planner                 -- model for planner agent
+models.executor                -- model for executor agent
+models.verifier                -- model for verifier agent
+```
+
+---
+
+## Config Field Matrix by Skill
+
+| Field | build | plan | review | import | begin | quick | milestone |
+|-------|-------|------|--------|--------|-------|-------|-----------|
+| depth | | X | | | X | | |
+| mode | X | X | X | | X | | |
+| features.research_phase | | X | | | | | |
+| features.plan_checking | | X | | X | | | |
+| features.goal_verification | X | | X | | | | |
+| features.inline_verify | X | | | | | | |
+| features.atomic_commits | X | | | | | | |
+| features.auto_continue | X | | | | | | |
+| features.auto_advance | X | X | X | | | | |
+| features.integration_verification | | | X | | | | X |
+| gates.confirm_plan | | X | | | | | |
+| gates.confirm_execute | X | | | | | | |
+| gates.confirm_transition | | | X | | | | |
+| parallelization.* | X | | | | | | |
+| planning.commit_docs | X | | | | | X | X |
+| git.commit_format | X | | | | X | X | |
+| git.branching | X | | | | | | |
+| models.* | | X | X | | X | | X |

package/plan-build-run/skills/shared/context-budget.md

@@ -0,0 +1,105 @@
+# Context Budget Rules
+
+Standard rules for keeping orchestrator context lean. Reference this fragment in skills that spawn Task() subagents.
+
+See also: `skills/shared/universal-anti-patterns.md` for the complete set of universal rules (context budget + file reading + behavioral rules).
+
+---
+
+## Universal Rules
+
+Every skill that spawns agents or reads significant content must follow these rules:
+
+1. **Never** read agent definition files (`agents/*.md`) — `subagent_type` auto-loads them
+2. **Never** inline large files into Task() prompts — tell agents to read files from disk instead
+3. **Read depth scales with context window** — check `context_window_tokens` in `.planning/config.json`:
+   - At < 500000 tokens (default 200k): read only frontmatter, status fields, or summaries. Never read full SUMMARY.md, VERIFICATION.md, or RESEARCH.md bodies.
+   - At >= 500000 tokens (1M model): MAY read full subagent output bodies when the content is needed for inline presentation or decision-making. Still avoid unnecessary reads.
+4. **Delegate** heavy work to subagents — the orchestrator routes, it doesn't execute
+5. **Before spawning agents**: If you've already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider running `/pbr:pause` to checkpoint progress." Suggest pause proactively rather than waiting for compaction.
+
+## Read Depth by Context Window
+
+| Context Window | Subagent Output Reading | SUMMARY.md | VERIFICATION.md | PLAN.md (other phases) |
+|---------------|------------------------|------------|-----------------|------------------------|
+| < 500k (200k model) | Frontmatter only | Frontmatter only | Frontmatter only | Current phase only |
+| >= 500k (1M model) | Full body permitted | Full body permitted | Full body permitted | Current phase only |
+
+**How to check:** Read `.planning/config.json` and inspect `context_window_tokens`. If the field is absent, treat as 200k (conservative default).
+
+**Applies to:** build, plan, review skills — any skill that reads back subagent artifacts.
+
+## Context Degradation Awareness
+
+Quality degrades gradually before panic thresholds fire. Watch for these early warning signs:
+
+- **Silent partial completion** — agent claims task is done but implementation is incomplete. Self-check catches file existence but not semantic completeness. Always verify agent output meets the plan's must_haves, not just that files exist.
+- **Increasing vagueness** — agent starts using phrases like "appropriate handling" or "standard patterns" instead of specific code. This indicates context pressure even before budget warnings fire.
+- **Skipped steps** — agent omits protocol steps it would normally follow. If an agent's success criteria has 8 items but it only reports 5, suspect context pressure.
+
+When delegating to agents, the orchestrator cannot verify semantic correctness of agent output — only structural completeness. This is a fundamental limitation. Mitigate with must_haves.truths and spot-check verification.
+
+## State Consolidation Impact
+
+State consolidation (Phase 5) reduces core planning files from 5 to 3:
+- CONTEXT.md is now merged into PROJECT.md ## Context section
+- HISTORY.md is now merged into STATE.md ## History section
+- This reduces per-phase context loading overhead — fewer files to read, same information
+
+**File size estimates (post-consolidation):**
+- PROJECT.md: ~2-4 KB (includes Context section)
+- STATE.md: ~3-6 KB (includes History section)
+- ROADMAP.md: ~3-8 KB (depending on phase count)
+- config.json: ~1-2 KB
+
+**Note:** PROJECT.md is larger now with the merged Context section. Factor this into context budget when loading project state.
+
+## Customization
+
+Skills should add skill-specific rules below the reference line. Common skill-specific additions:
+
+- **build**: "Minimize reading executor output — read only SUMMARY.md frontmatter, not full content"
+- **plan**: "Minimize reading subagent output — read only plan frontmatter for summaries"
+- **review**: "Minimize reading subagent output — read only VERIFICATION.md frontmatter for summaries"
+- **scan**: "Delegate ALL analysis to the 4 parallel codebase-mapper subagents"
+- **quick**: "Never implement the task yourself — ALL code changes go through a spawned executor"
+- **debug**: "Never perform investigation work yourself — delegate ALL analysis to the debugger subagent"
+
+Format in the SKILL.md:
+
+```markdown
+## Context Budget
+
+Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+
+Additionally for this skill:
+- {Skill-specific rule 1}
+- {Skill-specific rule 2}
+```
+
+## Agent Elapsed Time Estimates
+
+When displaying agent spawn lines (e.g., "Spawning researcher..."), append a parenthetical estimate:
+
+| Agent Type | Display Text | Estimate |
+|------------|-------------|----------|
+| researcher | Spawning researcher... | (est. 1-3 min) |
+| planner | Spawning planner... | (est. 2-5 min) |
+| executor | Spawning executor... | (est. 3-8 min) |
+| verifier | Spawning verifier... | (est. 1-2 min) |
+| codebase-mapper | Spawning codebase-mapper... | (est. 1-2 min) |
+| plan-checker | Spawning plan-checker... | (est. 1-2 min) |
+| integration-checker | Spawning integration-checker... | (est. 2-4 min) |
+| debugger | Spawning debugger... | (est. 2-5 min) |
+| general | Spawning agent... | (est. 1-4 min) |
+| audit | Spawning audit... | (est. 2-4 min) |
+
+**Usage**: In any skill that spawns Task() agents, prefix spawn displays with the agent name and append the estimate from this table. Example:
+
+```
+Spawning researcher... (est. 1-3 min)
+Spawning planner... (est. 2-5 min)
+[Wave 1: 3 plans in parallel] Spawning executors... (est. 3-8 min each)
+```
+
+Skills that spawn agents: build, plan, review, debug, scan, milestone, quick.

package/plan-build-run/skills/shared/context-loader-task.md

@@ -0,0 +1,91 @@
+# Context Loader Task Pattern
+
+Standard pattern for spawning a lightweight Task() to build a project briefing before the main skill logic runs. Used by skills that need project context but want to keep the orchestrator lean.
+
+> Referenced by: explore, scan, discuss skills (and any skill that needs a project briefing before interactive work)
+
+---
+
+## When to Use
+
+Use this pattern when:
+- The skill runs mostly inline (conversation, presentation) rather than delegating to agents
+- The skill needs awareness of project state, decisions, and progress
+- Reading all context files directly would consume too much orchestrator context
+
+Do NOT use this pattern when:
+- The skill already uses `pbr-tools.cjs state load` (build, plan, review, import)
+- The skill reads only STATE.md lines 1-20 (continue, status, resume)
+- The skill has no project dependency (note with `--global`)
+
+---
+
+## Pattern: Briefing Task
+
+```
+Task({
+  prompt: "Read the following files and return a ~500 token briefing summarizing the project state, key decisions, and any context relevant to {skill_purpose}:
+    - .planning/STATE.md
+    - .planning/ROADMAP.md
+    - .planning/REQUIREMENTS.md
+    - .planning/PROJECT.md (if exists — project vision, scope, and context)
+    - Any .planning/phases/*/CONTEXT.md files (phase-level locked decisions)
+    - .planning/research/SUMMARY.md (if exists)
+    - .planning/notes/*.md (if notes directory exists — read frontmatter for date/promoted status)
+    - .planning/STATE.md ## History section (scan for decisions relevant to current work only, do NOT summarize all history)
+
+  Return ONLY the briefing text. No preamble, no suggestions."
+})
+```
+
+### CLI Alternative
+
+Alternatively, the skill can call `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load` for structured JSON state instead of spawning a briefing Task. Use the CLI approach when only state data is needed; use the Task approach when project context (decisions, notes, history) is also needed.
+
+### Key Rules
+
+1. **Only runs if `.planning/` directory exists.** Skills invoked on fresh projects with no planning directory skip this entirely.
+2. **Budget: ~500 tokens.** The briefing must be concise. The subagent reads full files in its own context; the orchestrator receives only the summary.
+3. **No suggestions.** The briefing reports state, it does not recommend actions. The skill logic decides what to do.
+4. **Read-only.** The briefing task must not write any files.
+5. **No subagent_type needed.** This is the ONE exception to the "always use `pbr:*` agents" rule. Bare `Task()` without `subagent_type` is intentional here — these are lightweight read-only briefings that don't need agent-specific prompts. Do NOT generalize this pattern to other Task() calls — all research, execution, and analysis Task() calls MUST use `subagent_type: "pbr:{agent}"`.
+
+### Using the Briefing
+
+After the task completes:
+- Use the briefing to inform conversation -- reference existing decisions, avoid re-litigating settled questions
+- Connect new ideas or findings to existing project structure
+- Identify relevant phases, requirements, or decisions without reading the source files yourself
+
+---
+
+## Variation: Topic-Scoped Briefing
+
+When the skill has a specific topic (e.g., `/pbr:explore auth`), scope the briefing:
+
+```
+Task({
+  prompt: "Read the following files and return a ~500 token briefing focused on {topic}:
+    - .planning/STATE.md
+    - .planning/ROADMAP.md
+    - .planning/REQUIREMENTS.md
+    - .planning/PROJECT.md (if exists — project vision, scope, and context)
+    - Any .planning/phases/*/CONTEXT.md files (phase-level locked decisions)
+    - .planning/STATE.md ## History section (scan for decisions relevant to '{topic}' only, do NOT summarize all history)
+
+  Focus on: decisions, requirements, and phase goals related to '{topic}'.
+  Return ONLY the briefing text. No preamble, no suggestions."
+})
+```
+
+---
+
+## Variation: Scan Reconnaissance
+
+For `/pbr:map-codebase`, the pattern adapts to codebase analysis rather than project state:
+
+1. The orchestrator performs a quick inline scan (detect project type, scale, key directories)
+2. Writes the results to `.planning/codebase/RECON.md`
+3. Passes RECON.md content to the spawned analysis agents as baseline context
+
+This is the same principle (build context before main work) but the source is the codebase rather than planning files.

package/plan-build-run/skills/shared/digest-select.md

@@ -0,0 +1,79 @@
+# Digest-Select Pattern
+
+Selective reading depth for prior phase SUMMARY.md files. Saves tokens by reading only what is needed based on the relationship to the current phase.
+
+> Referenced by: plan, build, import skills
+
+---
+
+## Depth Rules
+
+Not all prior phase SUMMARYs need the same level of detail. Use selective depth based on dependency distance:
+
+| Relationship to current phase | Read depth |
+|-------------------------------|------------|
+| Direct dependency (listed in `depends_on` in ROADMAP.md) | Frontmatter + "Key Decisions" section. The subagent reads full bodies from disk in its own context. |
+| 1 phase back from a dependency (transitive) | Frontmatter only (`provides`, `key_files`, `key_decisions`, `patterns`) |
+| 2+ phases back | Skip entirely |
+
+---
+
+## Example
+
+If planning Phase 5 which depends on Phase 4, and Phase 4 depends on Phase 3:
+- Phase 4 SUMMARYs: frontmatter + "Key Decisions" section
+- Phase 3 SUMMARYs: frontmatter only
+- Phases 1-2 SUMMARYs: skip
+
+This saves ~500 tokens per skipped SUMMARY for large projects.
+
+---
+
+## How to Determine Dependency Distance
+
+1. Read ROADMAP.md and find the current phase's `depends_on` list
+2. Those are the **direct dependencies** (distance 1) -- read frontmatter + key decisions
+3. For each direct dependency, find ITS `depends_on` list -- those are **transitive** (distance 2) -- read frontmatter only
+4. Everything else (distance 3+) -- skip
+
+---
+
+## Frontmatter Fields to Extract
+
+When reading frontmatter only (transitive dependencies), extract these fields:
+
+```yaml
+status: complete
+provides:
+  - "user authentication API"
+  - "session management middleware"
+key_files:
+  - src/auth/controller.ts
+  - src/auth/middleware.ts
+key_decisions:
+  - "JWT with refresh tokens"
+  - "bcrypt for password hashing"
+patterns:
+  - "repository pattern for data access"
+  - "middleware chain for auth checks"
+```
+
+These fields give downstream skills enough context to build on prior work without reading the full SUMMARY body.
+
+---
+
+## Skill-Specific Notes
+
+### /pbr:plan-phase
+- Direct dependencies: frontmatter + "Key Decisions" section (planner reads full bodies from disk)
+- Used in Step 2: Load Context
+
+### /pbr:execute-phase
+- Direct dependencies (completed earlier waves): frontmatter only for prior work table
+- Used in Step 6a: Spawn Executors (prior_work section of executor prompt)
+
+### /pbr:import
+- Direct dependencies: full SUMMARY body (needed for conflict detection)
+- Transitive: frontmatter only
+- 2+ back: skip
+- Used in Step 2: Load Full Project Context

package/plan-build-run/skills/shared/domain-probes.md

@@ -0,0 +1,125 @@
+# Domain-Aware Probing Patterns
+
+Shared reference for `/pbr:explore`, `/pbr:new-project`, and `/pbr:discuss-phase`.
+
+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/plan-build-run/skills/shared/error-reporting.md

@@ -0,0 +1,59 @@
+# Error Reporting — Standard Format
+
+Use the branded error box for all blocking errors. Present the box, explain what happened, and give a specific fix action.
+
+## Error Box Format
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+{one-line description of what went wrong}
+
+**To fix:** {specific action the user should take}
+```
+
+## Warning Format (non-blocking)
+
+```
+⚠ {one-line warning}
+  {optional detail or suggestion}
+```
+Continue execution after showing a warning.
+
+## Common Error Patterns
+
+### Phase not found
+Message: "Phase {N} not found in ROADMAP.md."
+Fix: "Run `/pbr:status` to see available phases."
+
+### Missing prerequisites (no REQUIREMENTS.md or ROADMAP.md)
+Message: "Project not initialized. Missing REQUIREMENTS.md or ROADMAP.md."
+Fix: "Run `/pbr:new-project` first."
+
+### No plans found for phase
+Message: "Phase {N} has no plans."
+Fix: "Run `/pbr:plan-phase {N}` first."
+
+### Dependency phase not complete
+Message: "Phase {N} depends on Phase {M}, which is not complete."
+Fix: "Build Phase {M} first with `/pbr:execute-phase {M}`."
+
+### Planner agent failure
+Message: "Planner agent failed for Phase {N}."
+Fix: "Try again with `/pbr:plan-phase {N} --skip-research`. Check `.planning/PROJECT.md` for conflicting constraints."
+
+### Checker loops (3+ iterations without pass)
+Message: "Plan checker failed to pass after 3 revision iterations for Phase {N}."
+Fix: "Review the remaining issues below and decide whether to proceed or revise manually. Run `/pbr:plan-phase {N}` to restart planning from scratch."
+After displaying: present remaining issues and ask user to decide (proceed or intervene).
+
+### Research agent failure
+Display as WARNING (non-blocking): "Research agent failed. Planning without phase-specific research. This may result in less accurate plans."
+Continue to the planning step.
+
+## Usage
+
+In skill files, replace repeated error box content with:
+"Display a branded error box — use the format from `skills/shared/error-reporting.md`, pattern: {pattern name}."