@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plugins/pbr/references/archive/checkpoints.md

@@ -0,0 +1,189 @@
+# Checkpoints Reference
+
+How Plan-Build-Run uses checkpoint tasks to pause execution and involve the human.
+
+---
+
+## What Are Checkpoints?
+
+Checkpoints are special task types that cause the executor agent to **stop execution** and return control to the orchestrator (or the human). They exist because some tasks require human judgment, manual action, or verification that cannot be automated.
+
+Checkpoints are defined in plan task XML via the `type` attribute. When the executor encounters a checkpoint task, it follows a specific protocol depending on the checkpoint type.
+
+---
+
+## Checkpoint Types
+
+Plan-Build-Run supports three checkpoint types:
+
+### checkpoint:human-verify
+
+**Purpose**: The executor has completed work, but a human needs to visually inspect or manually test the result before proceeding.
+
+**Executor behavior**:
+1. Execute the task's `<action>` steps normally
+2. Commit the changes
+3. **STOP execution**
+4. Return a structured `CHECKPOINT: HUMAN-VERIFY` response containing:
+   - What was done (summary of action taken)
+   - What to verify (from the task's `<done>` condition)
+   - How to verify (instructions derived from `<verify>`)
+   - Completed tasks table
+   - Remaining tasks list
+
+**Use when**: The result requires subjective judgment (UI looks correct, behavior feels right, output makes sense) that automated verification cannot cover.
+
+**Example scenario**: A template was created and needs visual review in the browser, or an API integration needs manual testing with real credentials.
+
+### checkpoint:decision
+
+**Purpose**: The plan reaches a point where a human decision is needed before the executor can continue. The task is NOT executed — execution pauses before the task starts.
+
+**Executor behavior**:
+1. **STOP before executing the task**
+2. Return a structured `CHECKPOINT: DECISION` response containing:
+   - The decision that needs to be made (from `<action>`)
+   - Available options
+   - Context to help the human decide
+   - Completed tasks table
+
+**Use when**: The plan has a fork point where different approaches are possible and the right choice depends on human preference, business context, or information the planner could not determine.
+
+**Example scenario**: Choosing between two authentication providers, deciding whether to use a specific third-party library or build in-house.
+
+### checkpoint:human-action
+
+**Purpose**: The task requires something the executor cannot do — a manual step that involves the human interacting with external systems, creating accounts, or performing physical actions.
+
+**Executor behavior**:
+1. **STOP before executing the task**
+2. Return a structured `CHECKPOINT: HUMAN-ACTION` response containing:
+   - What the human needs to do (from `<action>`)
+   - Step-by-step instructions
+   - Prompt to tell the executor when done
+   - Completed tasks table
+
+**Use when**: External setup is required — creating API keys, configuring DNS, setting up OAuth applications, or any action that requires credentials or permissions the agent does not have.
+
+**Example scenario**: The human needs to create a Discord application in the Developer Portal and paste the client ID and secret into `.env`.
+
+---
+
+## Checkpoint in Plan Format
+
+Checkpoints are declared in the task's `type` attribute in the plan XML:
+
+```xml
+<task id="02-01-T3" type="checkpoint:human-verify" tdd="false">
+  <name>Verify OAuth login flow in browser</name>
+  <files>...</files>
+  <action>...</action>
+  <verify>Open browser to localhost:3000/auth/login and complete the flow</verify>
+  <done>User can log in via Discord OAuth and see their profile</done>
+</task>
+```
+
+Valid checkpoint type values:
+- `checkpoint:human-verify`
+- `checkpoint:decision`
+- `checkpoint:human-action`
+
+Non-checkpoint task types use `type="auto"`.
+
+---
+
+## Autonomous vs Non-Autonomous Plans
+
+The plan frontmatter field `autonomous: true|false` indicates whether a plan contains checkpoint tasks:
+
+| Value | Meaning |
+|-------|---------|
+| `autonomous: true` | No checkpoint tasks. The executor can complete all tasks without human intervention. |
+| `autonomous: false` | Contains at least one checkpoint task. Execution will pause at some point. |
+
+The build orchestrator uses this field to determine execution strategy:
+- Autonomous plans can be executed in parallel with other autonomous plans in the same wave
+- Non-autonomous plans may block the wave while waiting for human input
+- The orchestrator tracks checkpoint state in `.checkpoint-manifest.json`
+
+---
+
+## Continuation Protocol
+
+After a checkpoint is resolved (human provides their answer, completes their action, or confirms verification), the orchestrator spawns a **fresh continuation executor** to resume from where the checkpoint paused.
+
+The continuation executor receives:
+1. The full plan content
+2. A table of completed tasks with their commit hashes
+3. The checkpoint resolution (what the human decided or confirmed)
+4. The task number to resume from
+5. The same project context as the original executor
+
+**Key rules for continuation**:
+- The continuation executor does NOT re-execute completed tasks
+- It reads the partial SUMMARY.md if one exists
+- It verifies prior commits exist via `git log`
+- It resumes from the next uncompleted task after the checkpoint
+
+---
+
+## Authentication Gate (Implicit Checkpoint)
+
+The executor also supports an implicit checkpoint for authentication failures. If the executor encounters an authentication error (missing API key, expired token, invalid credentials) during any task, it immediately stops and returns a `CHECKPOINT: AUTH-GATE` response.
+
+This is not declared in the plan — it triggers automatically when an auth error is detected. The response includes:
+- Which task was blocked
+- What credential is needed
+- Where to configure it
+- The actual error message
+
+---
+
+## Architectural Deviation (Implicit Checkpoint)
+
+Similarly, if the executor discovers that the plan's approach cannot work (API changed, framework limitation, dependency conflict), it stops with a `CHECKPOINT: ARCHITECTURAL-DEVIATION` response. This follows Deviation Rule 4 from the executor's deviation handling protocol.
+
+---
+
+## Best Practices for Planners
+
+When creating plans that include checkpoints:
+
+1. **Minimize checkpoint tasks** — each one pauses execution and requires human attention
+2. **Place checkpoints at natural boundaries** — after a feature is complete, not in the middle of wiring
+3. **Group manual actions** — combine related human actions into a single checkpoint rather than multiple stops
+4. **Provide clear instructions** — the `<action>` and `<verify>` elements should give the human everything they need
+5. **Consider autonomous alternatives** — if a task CAN be verified automatically, prefer `type="auto"` with a robust `<verify>` command
+6. **Set `autonomous: false`** in the plan frontmatter when any task is a checkpoint
+
+---
+
+## Automation-First Philosophy
+
+### 5 Golden Rules
+1. If Claude CAN run it, Claude MUST run it
+2. If Claude CAN verify it, Claude MUST verify it
+3. Only checkpoint for things requiring human senses or credentials
+4. Group manual actions to minimize checkpoint count
+5. Never ask the user to do something automatable
+
+### Automatable Quick Reference
+
+| Action | Automatable? | Notes |
+|--------|-------------|-------|
+| Run tests | YES | `npm test`, `pytest`, etc. |
+| Start dev server | YES | `npm run dev` (check port) |
+| Check environment variables | YES | `env \| grep KEY` |
+| Build project | YES | `npm run build` |
+| Run linting | YES | `npm run lint` |
+| Database migrations | YES | CLI commands |
+| Click email verification link | NO | Requires browser + inbox |
+| 3DS payment verification | NO | Requires card + phone |
+| OAuth consent screen | NO | Requires browser interaction |
+| Hardware token/YubiKey | NO | Physical device |
+
+### Anti-Patterns
+- Asking user to "start the dev server" — just run it
+- Asking user to "check if tests pass" — run `npm test`
+- Saying "please verify the output" without running verification commands first
+- Creating a checkpoint for `mkdir` or `npm install`

package/plugins/pbr/references/archive/context-quality-tiers.md

@@ -0,0 +1,45 @@
+# Context Quality Tiers
+
+Behavioral guidance for agents based on context window utilization.
+
+## Tier Definitions
+
+| Tier | Context Used | Quality | Guidance |
+|------|-------------|---------|----------|
+| PEAK | 0-30% | Full capacity | Explore freely, read broadly, take time to understand |
+| GOOD | 30-50% | High capacity | Be selective with reads, skip non-essential exploration |
+| DEGRADING | 50-70% | Declining capacity | Write incrementally, finish current task, skip nice-to-haves |
+| POOR | 70%+ | Critical | Finish current task IMMEDIATELY and return. No new reads. |
+
+## Behavioral Rules Per Tier
+
+### PEAK (0-30%)
+- Read all relevant files before making changes
+- Explore adjacent code for patterns and conventions
+- Write comprehensive commit messages
+- Full self-check protocols
+
+### GOOD (30-50%)
+- Read only files directly relevant to current task
+- Skip exploratory reads of "nice to have" context
+- Standard commit messages
+- Standard self-check
+
+### DEGRADING (50-70%)
+- Write changes incrementally (don't accumulate large diffs)
+- Skip optional verification steps
+- Brief commit messages
+- Abbreviated self-check (key_files only)
+
+### POOR (70%+)
+- STOP exploring. Finish the current task only.
+- Write SUMMARY.md immediately if executor
+- Return completion marker immediately
+- Do NOT start new tasks or reads
+
+## Agent-Specific Overrides
+
+- **Researcher**: At DEGRADING, write findings immediately rather than accumulating
+- **Executor**: At DEGRADING, complete current task then return CHECKPOINT
+- **Verifier**: At DEGRADING, check existence only (skip substantiveness/wiring layers)
+- **Planner**: At GOOD, reduce task detail level; at DEGRADING, finish current plan file only

package/plugins/pbr/references/archive/pbr-rules.md

@@ -0,0 +1,194 @@
+# Plan-Build-Run Rules
+
+Authoritative rules for all Plan-Build-Run skills, agents, hooks, and workflows.
+Condensed from the 3,100-line `docs/DEVELOPMENT-GUIDE.md`. When in doubt, these rules govern.
+
+---
+
+## Philosophy
+
+1. **Context is precious.** The orchestrator stays lean (~15% usage). Delegate heavy work to subagents.
+2. **State lives on disk.** Skills and agents communicate through `.planning/` files, not messages.
+3. **Agents are black boxes.** Clear input/output contracts. Agents never read other agent definitions.
+4. **Gates provide safety.** Users control pace via config toggles. Never skip a gate.
+5. **One task, one commit.** Atomic commits for clean history and easy rollback.
+6. **Cross-platform always.** `path.join()`, CommonJS, test on Windows/macOS/Linux.
+7. **Test everything.** 70% coverage minimum. All 9 CI matrix combinations must pass.
+8. **PLAN-BUILD-RUN branding only.** Always use `PLAN-BUILD-RUN ►` prefix in banners.
+
+---
+
+## Context Budget
+
+9. Target 15% orchestrator context usage. Warn user at 30%.
+10. **Never** read agent definitions (`agents/*.md`) in the orchestrator — `subagent_type` auto-loads them.
+11. **Never** inline large files into `Task()` prompts — tell agents to read files from disk.
+12. **Never** read full subagent output — read frontmatter only (first 10-20 lines).
+13. Read STATE.md and config.json fully. Read ROADMAP.md by section. Read PLAN.md/SUMMARY.md/VERIFICATION.md frontmatter only.
+14. Use the `limit` parameter on Read to restrict line counts.
+15. Proactively suggest `/pbr:pause-work` when context gets heavy — before compaction, not after.
+15b. **After compaction or context recovery**, always read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
+
+---
+
+## State Management
+
+16. STATE.md is the **single source of truth** for current position.
+17. **Never** infer current phase from directory listings, git log, or conversation history.
+18. Always read STATE.md before making state-dependent decisions.
+19. Update STATE.md at: begin, plan, build, review, pause, continue, milestone.
+20. **Never** commit STATE.md mid-skill — hooks handle session persistence.
+21. Agents write artifacts (SUMMARY.md, VERIFICATION.md). Only the orchestrator writes STATE.md.
+22. Every ROADMAP.md phase must have a matching `.planning/phases/` directory, and vice versa.
+23. config.json is validated against `scripts/config-schema.json` on load.
+
+---
+
+## Agent Spawning
+
+24. Always use `subagent_type: "pbr:{name}"` to spawn agents.
+25. Pass file paths to agents, not file contents.
+26. Agents never read other agent definition files.
+27. Each agent gets a fresh 200k token context window — let them do the heavy reading.
+
+---
+
+## User Interaction Patterns
+
+28. Use `AskUserQuestion` for all structured gate checks — never plain-text "Type approved" prompts.
+29. AskUserQuestion is an orchestrator-only tool. It **cannot** be called from subagents (Task contexts).
+30. Max 4 options per AskUserQuestion call. If more options exist, split into a 2-step flow.
+31. `header` field must be max 12 characters. Keep it a single word when possible.
+32. `multiSelect` is always `false` for Plan-Build-Run gate checks.
+33. Always handle the "Other" case — users may type freeform text instead of selecting an option.
+34. Reuse patterns from `skills/shared/gate-prompts.md` by name. Do not reinvent prompts inline.
+35. Do **not** use AskUserQuestion for freeform text input (symptom gathering, Socratic discussion, open-ended questions). Use plain conversation for those.
+36. Skills that do not require user interaction (continue, health, help, pause) intentionally omit AskUserQuestion from allowed-tools.
+
+---
+
+## Skill Authoring
+
+37. Every SKILL.md starts with YAML frontmatter: `name`, `description`, `allowed-tools`, `argument-hint`.
+38. Skills that spawn agents **must** have a `## Context Budget` section.
+39. Mark each step as `(inline)` or `(delegate)` — inline for light work, delegate for analysis.
+40. Reference templates and references by filename — never inline them.
+41. Gate checks: read config toggle → display summary → ask user → proceed/abort/revise.
+42. Use branded UI elements from `references/ui-brand.md`.
+
+---
+
+## Agent Authoring
+
+43. Every agent file starts with YAML frontmatter: `name`, `description`, `model`, `memory`, `tools`.
+44. Agent name matches the agent file name (no prefix needed).
+45. `tools` array: only include tools the agent actually uses.
+46. Agents write artifacts to disk. They never modify STATE.md or ROADMAP.md.
+47. Agent definitions are self-contained — no cross-agent references.
+
+---
+
+## Hook Development
+
+48. All hooks use **CommonJS** (`require`), never ES modules (`import`).
+49. All hooks call `logHook()` from `hook-logger.js`. No silent exits.
+50. Exit codes: `0` = allow/success, `2` = block (PreToolUse only), other = error (logged, non-blocking).
+51. Hooks receive JSON on stdin, write JSON to stdout.
+52. Fail gracefully: wrap in try/catch, exit 0 on parse errors.
+53. Every hook in `hooks.json` must have a `statusMessage` field (gerund form: "Validating...", keep short).
+54. Windows file deletion: use 3-attempt retry loop to handle AV/indexer locks.
+55. Every hook script must have a corresponding `tests/{name}.test.js`.
+
+---
+
+## Commits
+
+56. Format: `{type}({scope}): {description}`.
+57. Valid types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `wip`.
+58. Valid scopes: a short descriptive word for what changed (e.g., `auth`, `executor`, `config`), `quick-{NNN}`, `planning`, or `{NN}-{MM}` (phase-plan, legacy).
+59. **Never** use `git add .` or `git add -A` — stage specific files only.
+60. Blocked files: `.env` (not `.env.example`), `*.key`, `*.pem`, `*.pfx`, `*.p12`, `*credential*`, `*secret*` (unless in `tests/` or `*.example`).
+61. TDD tasks: exactly 3 commits — RED (test), GREEN (feat), REFACTOR.
+62. Executors: one atomic commit per task.
+
+---
+
+## Templates
+
+63. Default syntax: `{variable}` placeholders for string substitution.
+64. Only use EJS (`<%= %>`, `<% %>`) when loops or conditionals are genuinely needed.
+65. Template files use `.tmpl` extension. Name matches the output file (e.g., `SUMMARY.md.tmpl` → `SUMMARY.md`).
+66. Templates live in `templates/` (global), `templates/codebase/` (scan), `templates/research/` (research), or `skills/{name}/templates/` (skill-specific).
+
+---
+
+## File Naming
+
+67. Skills: `plugins/pbr/skills/{skill-name}/SKILL.md` — lowercase hyphenated dir, uppercase `SKILL.md`.
+68. Agents: `plugins/pbr/agents/{name}.md` — agent name matches file name.
+69. Scripts: `plugins/pbr/scripts/{name}.js` — lowercase, hyphenated, CommonJS.
+70. References: `plugins/pbr/references/{name}.md` — lowercase, hyphenated.
+71. Tests: `tests/{script-name}.test.js` — mirrors the script name.
+
+---
+
+## Testing
+
+72. Test files mirror script names: `scripts/foo.js` → `tests/foo.test.js`.
+73. Use the fixture project at `tests/fixtures/fake-project/` for integration tests.
+74. Hook tests: use stdin/stdout protocol with `execSync()`, timeout 5000ms, run in temp dir.
+75. Coverage target: 70% branches/functions/lines/statements.
+76. CI matrix: Node 18/20/22 × ubuntu/macos/windows. All 9 must pass.
+77. Local pre-push: `npm run lint && npm test && npm run validate`.
+
+---
+
+## Cross-Platform
+
+78. **Never** hardcode `/` or `\` — always `path.join()`.
+79. Use `\n` in string literals — Node.js and Git normalize line endings.
+80. In `hooks.json`, use `${CLAUDE_PLUGIN_ROOT}` — Claude Code expands this internally on all platforms.
+81. **Never** use `$CLAUDE_PLUGIN_ROOT` (shell expansion is platform-dependent).
+82. **Never** rely on execute bits — always invoke via `node script.js`.
+
+---
+
+## Dependencies & Gates
+
+83. Check all `depends_on` plans have SUMMARY.md files before executing.
+84. Checkpoint tasks (`checkpoint:human-verify`) require STOP — write partial SUMMARY.md, return metadata.
+85. Respect all `gates.confirm_*` config toggles. Never auto-proceed when a gate is enabled.
+
+---
+
+## Logging
+
+86. Hook scripts → `logHook()` (writes to `logs/hooks.jsonl`, max 200 entries).
+87. Workflow milestones → `logEvent()` (writes to `logs/events.jsonl`, max 1,000 entries).
+88. Rule of thumb: inside a hook? `logHook()`. Tracking a high-level event? `logEvent()`.
+
+---
+
+## Gotchas
+
+89. JSDoc `*/` in glob patterns closes Babel comments early — use `//` line comments instead.
+90. Regex anchors: use `\b` word boundaries, not `^` anchors (misses chained commands like `cd && git commit`).
+91. Windows cwd locking in tests: use `cwd` option in `execSync()` instead of `process.chdir()`.
+92. PLAN.md frontmatter must include all required fields: `phase`, `plan`, `type`, `wave`, `depends_on`, `files_modified`, `autonomous`, `must_haves`.
+
+---
+
+## Quick Reference: Never Do This
+
+| # | Anti-Pattern | Impact |
+|---|-------------|--------|
+| 1 | Read agent definitions in orchestrator | Context balloons 15% → 88% |
+| 2 | Inline large files into Task() prompts | Wasted orchestrator context |
+| 3 | Read full subagent output | Context bloat |
+| 4 | Use non-Plan-Build-Run branding | User confusion |
+| 5 | Hardcode path separators | Cross-platform breakage |
+| 6 | Use ES modules in hooks | Hook fails to load |
+| 7 | Skip hook logging | Silent failures |
+| 8 | Modify STATE.md in agents | Race conditions, corruption |
+| 9 | Use `git add .` | Sensitive data leaks |
+| 10 | Skip tests for new scripts | CI failures, regressions |