@sienklogic/plan-build-run 2.54.0 → 2.56.0

package/plugins/codex-pbr/skills/shared/context-budget.md

@@ -0,0 +1,77 @@
+# Context Budget Rules
+
+Standard rules for keeping orchestrator context lean. Reference this fragment in skills that spawn Task() agents.
+
+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. **Minimize** reading subagent output into main context — read only frontmatter, not full content
+4. **Delegate** heavy work to agents — 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.
+
+## 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.
+
+## 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 agents"
+- **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/plugins/codex-pbr/skills/shared/context-loader-task.md

@@ -0,0 +1,86 @@
+# 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.js 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/CONTEXT.md
+    - Any .planning/phases/*/CONTEXT.md files
+    - .planning/research/SUMMARY.md (if exists)
+    - .planning/notes/*.md (if notes directory exists — read frontmatter for date/promoted status)
+    - .planning/HISTORY.md (if exists — scan for decisions relevant to current work only, do NOT summarize all history)
+
+  Return ONLY the briefing text. No preamble, no suggestions."
+})
+```
+
+### 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.
+
+### 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/CONTEXT.md
+    - Any .planning/phases/*/CONTEXT.md files
+    - .planning/HISTORY.md (if exists — 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-scan`, 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/plugins/codex-pbr/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
+- Direct dependencies: frontmatter + "Key Decisions" section (planner reads full bodies from disk)
+- Used in Step 2: Load Context
+
+### $pbr-build
+- 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/plugins/codex-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/codex-pbr/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-begin` first."
+
+### No plans found for phase
+Message: "Phase {N} has no plans."
+Fix: "Run `$pbr-plan {N}` first."
+
+### Dependency phase not complete
+Message: "Phase {N} depends on Phase {M}, which is not complete."
+Fix: "Build Phase {M} first with `$pbr-build {M}`."
+
+### Planner agent failure
+Message: "Planner agent failed for Phase {N}."
+Fix: "Try again with `$pbr-plan {N} --skip-research`. Check `.planning/CONTEXT.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 {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}."