@sienklogic/plan-build-run 2.21.1 → 2.21.2

package/plugins/copilot-pbr/skills/shared/context-loader-task.md

@@ -1,87 +0,0 @@
-<!-- canonical: ../../../pbr/skills/shared/context-loader-task.md -->
-# 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/copilot-pbr/skills/shared/digest-select.md

@@ -1,80 +0,0 @@
-<!-- canonical: ../../../pbr/skills/shared/digest-select.md -->
-# 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/copilot-pbr/skills/shared/domain-probes.md

@@ -1,126 +0,0 @@
-<!-- canonical: ../../../pbr/skills/shared/domain-probes.md -->
-# 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/copilot-pbr/skills/shared/error-recovery-strategies.md

@@ -1,51 +0,0 @@
-# Error Recovery Strategies Fragment
-
-Standard recovery patterns for skills and agents when operations fail. Reference `error-reporting.md` for display formats.
-
-## Strategy 1: Retry with Backoff
-
-For transient failures (file locks, network timeouts, tool failures):
-
-1. Wait briefly, then retry the same operation (max 2 retries)
-2. If still failing after retries, fall through to Strategy 2
-
-Use for: git operations, file writes blocked by antivirus, API calls.
-
-## Strategy 2: Degrade Gracefully
-
-When a non-critical step fails, skip it and continue:
-
-1. Log a warning using the recoverable error format
-2. Note the skipped step in SUMMARY.md `deferred` field
-3. Continue with remaining work
-
-Use for: optional validations, dashboard launch, hook logger writes, note/todo updates.
-
-## Strategy 3: Escalate to User
-
-When a critical step fails and no automated fix exists:
-
-1. Display the fatal error format with actionable suggestions
-2. Do NOT attempt workarounds that could corrupt state
-3. Suggest `/pbr:health` as the first diagnostic step
-4. If in an agent context, return the error in the agent's output so the orchestrator can relay it
-
-Use for: STATE.md corruption, missing phase directories, config parse failures, git conflicts.
-
-## Strategy 4: Checkpoint and Abort
-
-When a multi-step operation partially fails:
-
-1. Commit any completed work (don't lose progress)
-2. Update STATE.md with accurate status (not the target status)
-3. Write a `.continue-here.md` breadcrumb if mid-phase
-4. Report what completed and what remains
-
-Use for: build phase with mixed plan results, verification with partial failures.
-
-## Anti-Patterns
-
-- **Never silently swallow errors** in catch blocks — at minimum call `logHook()` with the error message
-- **Never retry destructive operations** (deletes, force-pushes, state resets)
-- **Never auto-fix by deleting user artifacts** — only delete PBR internal state files (.active-skill, .context-tracker, .auto-next)
-- **Never continue building after STATE.md write failure** — state integrity is non-negotiable

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

@@ -1,81 +0,0 @@
-# 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.
-
-Block reasons should always include a "To fix:" line with actionable guidance so the user or agent knows how to resolve the block.