@sienklogic/plan-build-run 2.0.0 → 2.0.1

package/plugins/pbr/references/agent-interactions.md

@@ -1,134 +1,134 @@
-# Agent Interaction Map
-
-This document shows how Plan-Build-Run agents communicate through files on disk. Agents never message each other directly -- they read and write shared files in `.planning/`.
-
-## Interaction Graph
-
-```
-                    User / Orchestrator
-                     |           ^
-                     v           |
-              +--------------+   |
-              |  researcher  |---+---> planner
-              +--------------+         |    ^
-                     |                 v    |
-              +--------------+   +--------------+
-              | synthesizer  |   | plan-checker |
-              +--------------+   +--------------+
-                                       |
-                                       v
-                                 +-----------+
-                                 |  executor  |
-                                 +-----------+
-                                       |
-                                       v
-                                 +-----------+
-                                 |  verifier  |----> planner (gap closure)
-                                 +-----------+
-                                       |
-                                       v
-                              +--------------------+
-                              | integration-checker|
-                              +--------------------+
-```
-
-## Per-Agent Interaction Details
-
-### researcher
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | User/Orchestrator | Research topics, CONTEXT.md constraints, phase goals |
-| Produces for | planner | Research documents with technology details and recommendations |
-| Produces for | synthesizer | Research documents to be combined |
-| Produces for | User | Direct reading for decision-making |
-
-### synthesizer
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | researcher | Research documents to synthesize |
-| Receives from | Orchestrator | Paths to research documents, synthesis request |
-| Produces for | planner | SUMMARY.md as consolidated research input for planning |
-| Produces for | User | High-level project/phase research overview |
-
-### planner
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | researcher | Research documents with technology details and recommendations |
-| Receives from | plan-checker | Issue reports requiring plan revision |
-| Receives from | verifier | VERIFICATION.md reports requiring gap closure plans |
-| Receives from | User/Orchestrator | Phase goals, CONTEXT.md, planning requests |
-| Produces for | plan-checker | Plan files for quality verification |
-| Produces for | executor | Plan files for execution |
-| Produces for | verifier | Must-have definitions for verification (embedded in plan frontmatter) |
-
-### plan-checker
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Plan files to check, phase context |
-| Receives from | planner | Newly created or revised plan files |
-| Produces for | planner | Issue reports for revision |
-| Produces for | Orchestrator/User | Pass/fail decision on plan quality |
-
-### executor
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator | Plan files to execute, continuation instructions |
-| Receives from | planner | The plans themselves (indirectly, via files) |
-| Produces for | verifier | SUMMARY.md for verification, committed code for inspection |
-| Produces for | Orchestrator | Checkpoint responses, completion status |
-| Produces for | planner | Deferred ideas (in SUMMARY.md) for future planning |
-
-### verifier
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator | Phase to verify, timing trigger |
-| Receives from | executor | Completed work (via codebase and SUMMARY.md) |
-| Receives from | Previous VERIFICATION.md | Gaps to re-check (in re-verification mode) |
-| Produces for | planner | Gap list for gap-closure planning (via VERIFICATION.md) |
-| Produces for | Orchestrator | Phase status (passed/gaps_found/human_needed) |
-| Produces for | User | Human verification items with specific test instructions |
-
-### integration-checker
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator | Phases to check, trigger event (milestone/review) |
-| Receives from | verifier | Phase-level verification reports (for context on per-phase status) |
-| Produces for | planner | Integration gap list for cross-phase fix plans |
-| Produces for | Orchestrator | Integration status for milestone decisions |
-| Produces for | User | Integration health overview and security issues |
-
-### debugger
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Bug reports, symptoms, reproduction steps |
-| Receives from | executor | Errors encountered during execution (via checkpoint responses) |
-| Receives from | verifier | Issues discovered during verification |
-| Produces for | Orchestrator/User | Root cause analysis, fix commits, checkpoint requests |
-| Produces for | planner | Findings requiring architectural changes |
-| Produces for | executor | Simple fix instructions for executor to apply |
-
-### codebase-mapper
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Focus area to analyze, project path |
-| Receives from | researcher | May be invoked alongside researcher for new projects |
-| Produces for | planner | STACK.md, ARCHITECTURE.md, STRUCTURE.md for informed planning |
-| Produces for | executor | CONVENTIONS.md for code style, TESTING.md for test patterns |
-| Produces for | verifier | All documents as reference for what "correct" looks like |
-| Produces for | User | Direct reading for project understanding |
-
-### general
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Ad-hoc task instructions |
-| Produces for | Orchestrator/User | Task output (files, formatting, config changes) |
+# Agent Interaction Map
+
+This document shows how Plan-Build-Run agents communicate through files on disk. Agents never message each other directly -- they read and write shared files in `.planning/`.
+
+## Interaction Graph
+
+```
+                    User / Orchestrator
+                     |           ^
+                     v           |
+              +--------------+   |
+              |  researcher  |---+---> planner
+              +--------------+         |    ^
+                     |                 v    |
+              +--------------+   +--------------+
+              | synthesizer  |   | plan-checker |
+              +--------------+   +--------------+
+                                       |
+                                       v
+                                 +-----------+
+                                 |  executor  |
+                                 +-----------+
+                                       |
+                                       v
+                                 +-----------+
+                                 |  verifier  |----> planner (gap closure)
+                                 +-----------+
+                                       |
+                                       v
+                              +--------------------+
+                              | integration-checker|
+                              +--------------------+
+```
+
+## Per-Agent Interaction Details
+
+### researcher
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | User/Orchestrator | Research topics, CONTEXT.md constraints, phase goals |
+| Produces for | planner | Research documents with technology details and recommendations |
+| Produces for | synthesizer | Research documents to be combined |
+| Produces for | User | Direct reading for decision-making |
+
+### synthesizer
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | researcher | Research documents to synthesize |
+| Receives from | Orchestrator | Paths to research documents, synthesis request |
+| Produces for | planner | SUMMARY.md as consolidated research input for planning |
+| Produces for | User | High-level project/phase research overview |
+
+### planner
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | researcher | Research documents with technology details and recommendations |
+| Receives from | plan-checker | Issue reports requiring plan revision |
+| Receives from | verifier | VERIFICATION.md reports requiring gap closure plans |
+| Receives from | User/Orchestrator | Phase goals, CONTEXT.md, planning requests |
+| Produces for | plan-checker | Plan files for quality verification |
+| Produces for | executor | Plan files for execution |
+| Produces for | verifier | Must-have definitions for verification (embedded in plan frontmatter) |
+
+### plan-checker
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | Orchestrator/User | Plan files to check, phase context |
+| Receives from | planner | Newly created or revised plan files |
+| Produces for | planner | Issue reports for revision |
+| Produces for | Orchestrator/User | Pass/fail decision on plan quality |
+
+### executor
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | Orchestrator | Plan files to execute, continuation instructions |
+| Receives from | planner | The plans themselves (indirectly, via files) |
+| Produces for | verifier | SUMMARY.md for verification, committed code for inspection |
+| Produces for | Orchestrator | Checkpoint responses, completion status |
+| Produces for | planner | Deferred ideas (in SUMMARY.md) for future planning |
+
+### verifier
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | Orchestrator | Phase to verify, timing trigger |
+| Receives from | executor | Completed work (via codebase and SUMMARY.md) |
+| Receives from | Previous VERIFICATION.md | Gaps to re-check (in re-verification mode) |
+| Produces for | planner | Gap list for gap-closure planning (via VERIFICATION.md) |
+| Produces for | Orchestrator | Phase status (passed/gaps_found/human_needed) |
+| Produces for | User | Human verification items with specific test instructions |
+
+### integration-checker
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | Orchestrator | Phases to check, trigger event (milestone/review) |
+| Receives from | verifier | Phase-level verification reports (for context on per-phase status) |
+| Produces for | planner | Integration gap list for cross-phase fix plans |
+| Produces for | Orchestrator | Integration status for milestone decisions |
+| Produces for | User | Integration health overview and security issues |
+
+### debugger
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | Orchestrator/User | Bug reports, symptoms, reproduction steps |
+| Receives from | executor | Errors encountered during execution (via checkpoint responses) |
+| Receives from | verifier | Issues discovered during verification |
+| Produces for | Orchestrator/User | Root cause analysis, fix commits, checkpoint requests |
+| Produces for | planner | Findings requiring architectural changes |
+| Produces for | executor | Simple fix instructions for executor to apply |
+
+### codebase-mapper
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | Orchestrator/User | Focus area to analyze, project path |
+| Receives from | researcher | May be invoked alongside researcher for new projects |
+| Produces for | planner | STACK.md, ARCHITECTURE.md, STRUCTURE.md for informed planning |
+| Produces for | executor | CONVENTIONS.md for code style, TESTING.md for test patterns |
+| Produces for | verifier | All documents as reference for what "correct" looks like |
+| Produces for | User | Direct reading for project understanding |
+
+### general
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | Orchestrator/User | Ad-hoc task instructions |
+| Produces for | Orchestrator/User | Task output (files, formatting, config changes) |

package/plugins/pbr/references/agent-teams.md

@@ -1,54 +1,54 @@
-# Agent Teams Reference
-
-Agent Teams enable parallel specialist perspectives for critical phases. Teams are off by default.
-
-## Activation
-
-- **Global**: Set `parallelization.use_teams: true` in `.planning/config.json`
-- **Per-invocation**: Use `--teams` flag on `/pbr:plan`, `/pbr:review`, or `/pbr:build --team`
-- Per-invocation flag takes precedence over global config
-
-## Planning Teams
-
-When `/pbr:plan <N> --teams` is invoked, three specialist agents run in parallel:
-
-| Role | Agent | Focus | Output File |
-|------|-------|-------|-------------|
-| Architect | planner | Structure, dependencies, wave ordering, file boundaries | `.planning/phases/{NN}/team/architect-PLAN.md` |
-| Security Reviewer | planner | Auth, input validation, secrets handling, permission checks | `.planning/phases/{NN}/team/security-PLAN.md` |
-| Test Designer | planner | Test strategy, coverage targets, edge cases, TDD candidates | `.planning/phases/{NN}/team/test-PLAN.md` |
-
-All three use the `planner` agent with different prompts. The orchestrator includes the role and focus in the Task() spawn prompt.
-
-After all three complete, the synthesizer agent reads all team outputs and produces the final unified PLAN.md files.
-
-## Review Teams
-
-When `/pbr:review <N>` runs with teams enabled, three review agents run in parallel:
-
-| Role | Agent | Focus | Output File |
-|------|-------|-------|-------------|
-| Functional Reviewer | verifier | Must-haves met, code correctness, completeness | `.planning/phases/{NN}/team/functional-VERIFY.md` |
-| Security Auditor | verifier | Vulnerabilities, auth bypass, injection, secrets exposure | `.planning/phases/{NN}/team/security-VERIFY.md` |
-| Performance Analyst | verifier | N+1 queries, memory leaks, bundle size, unnecessary re-renders | `.planning/phases/{NN}/team/performance-VERIFY.md` |
-
-All three use the `verifier` agent with different prompts. The synthesizer combines them into a unified VERIFICATION.md.
-
-## File-Based Coordination
-
-Team members write to separate files in a `team/` subdirectory. This avoids file conflicts:
-```
-.planning/phases/{NN}-{slug}/
-  team/
-    architect-PLAN.md
-    security-PLAN.md
-    test-PLAN.md
-```
-
-The synthesizer reads all files in `team/` and produces the final artifact. The `team/` directory is kept for audit purposes but is not read by subsequent skills.
-
-## When to Use Teams
-
-- **Recommended**: Security-critical phases, architectural phases, public API design
-- **Not recommended**: Simple refactors, documentation, configuration changes
-- **Cost consideration**: Teams triple the agent spawns. Use only when the additional perspectives justify the cost.
+# Agent Teams Reference
+
+Agent Teams enable parallel specialist perspectives for critical phases. Teams are off by default.
+
+## Activation
+
+- **Global**: Set `parallelization.use_teams: true` in `.planning/config.json`
+- **Per-invocation**: Use `--teams` flag on `/pbr:plan`, `/pbr:review`, or `/pbr:build --team`
+- Per-invocation flag takes precedence over global config
+
+## Planning Teams
+
+When `/pbr:plan <N> --teams` is invoked, three specialist agents run in parallel:
+
+| Role | Agent | Focus | Output File |
+|------|-------|-------|-------------|
+| Architect | planner | Structure, dependencies, wave ordering, file boundaries | `.planning/phases/{NN}/team/architect-PLAN.md` |
+| Security Reviewer | planner | Auth, input validation, secrets handling, permission checks | `.planning/phases/{NN}/team/security-PLAN.md` |
+| Test Designer | planner | Test strategy, coverage targets, edge cases, TDD candidates | `.planning/phases/{NN}/team/test-PLAN.md` |
+
+All three use the `planner` agent with different prompts. The orchestrator includes the role and focus in the Task() spawn prompt.
+
+After all three complete, the synthesizer agent reads all team outputs and produces the final unified PLAN.md files.
+
+## Review Teams
+
+When `/pbr:review <N>` runs with teams enabled, three review agents run in parallel:
+
+| Role | Agent | Focus | Output File |
+|------|-------|-------|-------------|
+| Functional Reviewer | verifier | Must-haves met, code correctness, completeness | `.planning/phases/{NN}/team/functional-VERIFY.md` |
+| Security Auditor | verifier | Vulnerabilities, auth bypass, injection, secrets exposure | `.planning/phases/{NN}/team/security-VERIFY.md` |
+| Performance Analyst | verifier | N+1 queries, memory leaks, bundle size, unnecessary re-renders | `.planning/phases/{NN}/team/performance-VERIFY.md` |
+
+All three use the `verifier` agent with different prompts. The synthesizer combines them into a unified VERIFICATION.md.
+
+## File-Based Coordination
+
+Team members write to separate files in a `team/` subdirectory. This avoids file conflicts:
+```
+.planning/phases/{NN}-{slug}/
+  team/
+    architect-PLAN.md
+    security-PLAN.md
+    test-PLAN.md
+```
+
+The synthesizer reads all files in `team/` and produces the final artifact. The `team/` directory is kept for audit purposes but is not read by subsequent skills.
+
+## When to Use Teams
+
+- **Recommended**: Security-critical phases, architectural phases, public API design
+- **Not recommended**: Simple refactors, documentation, configuration changes
+- **Cost consideration**: Teams triple the agent spawns. Use only when the additional perspectives justify the cost.