@sienklogic/plan-build-run 2.12.0 → 2.12.1

package/plugins/pbr/skills/begin/templates/STATE.md.tmpl

@@ -1,7 +1,6 @@
 ---
 version: 2
 current_phase: 1
-total_phases: {total}
 phase_slug: "{phase_1_slug}"
 phase_name: "{Phase 1 name}"
 status: "ready_to_plan"
@@ -9,7 +8,7 @@ progress_percent: 0
 plans_total: 0
 plans_complete: 0
 last_activity: "{date}"
-last_command: "/pbr:begin"
+last_command: "/pbr:new-project"
 blockers: []
 active_checkpoint: null
 ---

package/plugins/pbr/skills/begin/templates/config.json.tmpl

@@ -1,64 +1,451 @@
 {
+  "_guide_meta": [
+    "schema_version: config schema version for migration detection",
+    "version: planning format version (v2 is current)"
+  ],
+  "schema_version": 3,
   "version": 2,
+  "_guide_core": [
+    "ceremony_level: auto|low|medium|high — override risk-based ceremony (auto = classifier decides)",
+    "context_strategy: aggressive|balanced|conservative — how aggressively PBR manages context budget",
+    "depth: quick|standard|comprehensive — thoroughness of research, planning, and verification",
+    "mode: interactive|autonomous — interactive pauses at gates, autonomous runs hands-free"
+  ],
+  "ceremony_level": "auto",
   "context_strategy": "aggressive",
-  "mode": "interactive",
   "depth": "standard",
+  "mode": "interactive",
+  "_guide_context_window": [
+    "agent_checkpoint_pct: 40-80 — context % where agents checkpoint and return",
+    "context_window_tokens: 100k-2M — your model's context size, scales all thresholds",
+    "orchestrator_budget_pct: 15-50 — % of context reserved for orchestrator (higher = more inline work)",
+    "session_cycling: tmux|compact-first|compact|manual — what happens when phase limit is reached",
+    "session_phase_limit: 0-20 — max phases per session before auto-pause (0 = disabled)",
+    "skip_rag_max_lines: projects under this LOC can load entire codebase into context",
+    "",
+    "--- 1M CONTEXT (Opus 4.6) RECOMMENDED VALUES ---",
+    "context_window_tokens: 1000000",
+    "agent_checkpoint_pct: 70  (default 50 for 200k models)",
+    "orchestrator_budget_pct: 35  (default 25 for 200k models)",
+    "session_phase_limit: 10  (default 3 for 200k, scales: 3@200k, 6@500k, 10@1M)",
+    "session_cycling: compact-first  (try /compact before cycling sessions)",
+    "context_budget.threshold_curve: adaptive  (shifts warnings up: 60/75/85 vs 50/70/85)",
+    "workflow.inline_context_cap_pct: 50  (500k tokens before forcing subagent delegation)",
+    "workflow.inline_max_files: 10, inline_max_lines: 100, inline_max_tasks: 3",
+    "workflow.max_phases_in_context: 6  (hold 6 phase plans simultaneously)",
+    "debug.max_hypothesis_rounds: 8  (longer investigation chains)"
+  ],
+  "agent_checkpoint_pct": 50,
+  "context_window_tokens": 200000,
+  "orchestrator_budget_pct": 25,
+  "session_cycling": "compact",
+  "session_phase_limit": 3,
+  "skip_rag_max_lines": 50000,
+  "_guide_autonomy": [
+    "autonomy.level: supervised|guided|collaborative|adaptive — progressive autonomy control",
+    "gates.confirm_*: pause for user confirmation (all false in autonomous mode)",
+    "gates.auto_checkpoints: auto-resolve checkpoint:human-verify tasks during build",
+    "gates.checkpoint_auto_resolve: none|verify-only|verify-and-decision|all",
+    "safety.always_confirm_destructive: always ask before destructive git ops",
+    "safety.always_confirm_external_services: always ask before calling external APIs",
+    "safety.enforce_phase_boundaries: prevent agents from working outside assigned phase"
+  ],
+  "autonomy": {
+    "level": "supervised"
+  },
+  "gates": {
+    "auto_checkpoints": false,
+    "checkpoint_auto_resolve": "none",
+    "confirm_commit_docs": false,
+    "confirm_deferred": false,
+    "confirm_execute": false,
+    "confirm_plan": true,
+    "confirm_project": true,
+    "confirm_research": false,
+    "confirm_roadmap": true,
+    "confirm_seeds": false,
+    "confirm_transition": true,
+    "issues_review": false
+  },
+  "safety": {
+    "always_confirm_destructive": true,
+    "always_confirm_external_services": true,
+    "enforce_phase_boundaries": true
+  },
+  "_guide_features": [
+    "--- CORE WORKFLOW ---",
+    "atomic_commits: one commit per task (not batched)",
+    "context_isolation: heavy work delegated to subagents to protect main context",
+    "session_persistence: persist state across sessions via STATE.md",
+    "structured_planning: use phased planning with ROADMAP + plan files",
+    "",
+    "--- RESEARCH & PLANNING ---",
+    "machine_executable_plans: programmatic task execution from parsed plans",
+    "plan_checking: validate plans via plan-checker agent before execution",
+    "pre_research: speculatively research upcoming phases at 70%+ completion",
+    "research_phase: run researcher agent before planning",
+    "reverse_spec: generate specs from existing code",
+    "spec_diffing: semantic diff when plans change",
+    "",
+    "--- EXECUTION ---",
+    "inline_simple_tasks: simple tasks (<N files, <N lines) run inline without subagent",
+    "post_hoc_artifacts: auto-generate SUMMARY.md from git history after execution",
+    "tdd_mode: red-green-refactor (3 commits per task instead of 1)",
+    "zero_friction_quick: skip pre-execution ceremony for quick tasks",
+    "",
+    "--- VERIFICATION ---",
+    "agent_feedback_loop: verification results feed back into executor prompts",
+    "confidence_calibration: confidence scores based on historical agent accuracy",
+    "goal_verification: run verifier agent after builds to check goals met",
+    "graduated_verification: trust-based verification depth (light/standard/thorough)",
+    "inline_verify: per-task verification after each commit (+10-20s per plan)",
+    "integration_verification: cross-phase integration checks",
+    "multi_layer_validation: parallel BugBot-style review passes",
+    "self_verification: executor self-checks before presenting output",
+    "trust_tracking: trust scores per agent type and task category",
+    "",
+    "--- AUTOMATION ---",
+    "auto_advance: chain build, review, plan automatically (requires autonomous mode)",
+    "auto_continue: write .auto-next signal on phase completion for chaining",
+    "",
+    "--- CONTEXT & SESSION ---",
+    "context_quality_scoring: track signal-to-noise ratio in context",
+    "enhanced_session_start: structured context injection at session start (~500 tokens)",
+    "extended_context: aggressive 1M optimizations (higher concurrency, team review, parallel scan)",
+    "mental_model_snapshots: capture working context at session end for instant resume",
+    "multi_phase_awareness: hold multiple phase plans simultaneously in context",
+    "rich_agent_prompts: enrich agent prompts with full project context",
+    "session_metrics: show metrics dashboard at session end",
+    "skip_rag: load entire codebase for small projects (under skip_rag_max_lines)",
+    "status_line: show PBR status bar in session UI",
+    "",
+    "--- KNOWLEDGE & INTELLIGENCE ---",
+    "adaptive_ceremony: risk-based ceremony adjustment per task",
+    "convention_memory: auto-detect and store project conventions",
+    "decision_journal: record WHY decisions were made in .planning/decisions/",
+    "dependency_break_detection: warn when upstream changes invalidate downstream plans",
+    "living_requirements: auto-update requirement status as phases complete",
+    "natural_language_routing: intent detection in /pbr:do",
+    "negative_knowledge: track what failed and why in .planning/negative-knowledge/",
+    "pattern_routing: file modification patterns trigger specialized agents",
+    "smart_next_task: dependency graph analysis for auto-continue suggestions",
+    "tech_debt_surfacing: surface tech debt in status dashboard",
+    "",
+    "--- QUALITY & SECURITY ---",
+    "architecture_graph: live module dependency tracking",
+    "architecture_guard: warn on dependency violations",
+    "predictive_impact: impact analysis using architecture graph",
+    "regression_prevention: smart test selection from changed files",
+    "security_scanning: OWASP-style scanning of changed files during build",
+    "",
+    "--- UI & VISUALIZATION ---",
+    "contextual_help: activity-specific suggestions based on current state",
+    "progress_visualization: phase dependency graph and timeline in dashboard",
+    "",
+    "--- TEAMS (disabled by default) ---",
+    "agent_teams: parallel worktree-based agent teams",
+    "competing_hypotheses: multiple approaches for complex problems",
+    "dynamic_teams: dynamic team composition per task",
+    "team_discussions: multi-perspective planning discussions",
+    "team_onboarding: generate onboarding guide from project docs"
+  ],
   "features": {
-    "structured_planning": true,
+    "adaptive_ceremony": true,
+    "agent_feedback_loop": true,
+    "agent_teams": false,
+    "architecture_graph": true,
+    "architecture_guard": true,
+    "atomic_commits": true,
+    "auto_advance": false,
+    "auto_continue": false,
+    "competing_hypotheses": false,
+    "confidence_calibration": true,
+    "context_isolation": true,
+    "context_quality_scoring": true,
+    "contextual_help": true,
+    "convention_memory": true,
+    "decision_journal": true,
+    "dependency_break_detection": true,
+    "dynamic_teams": false,
+    "enhanced_session_start": true,
+    "extended_context": false,
     "goal_verification": true,
+    "graduated_verification": true,
+    "inline_simple_tasks": true,
+    "inline_verify": false,
     "integration_verification": true,
-    "context_isolation": true,
-    "atomic_commits": true,
-    "session_persistence": true,
-    "research_phase": true,
+    "living_requirements": true,
+    "machine_executable_plans": false,
+    "mental_model_snapshots": true,
+    "multi_layer_validation": false,
+    "multi_phase_awareness": true,
+    "natural_language_routing": true,
+    "negative_knowledge": true,
+    "pattern_routing": true,
     "plan_checking": true,
-    "tdd_mode": false,
+    "post_hoc_artifacts": true,
+    "pre_research": true,
+    "predictive_impact": true,
+    "progress_visualization": true,
+    "regression_prevention": true,
+    "research_phase": true,
+    "reverse_spec": false,
+    "rich_agent_prompts": true,
+    "security_scanning": true,
+    "self_verification": true,
+    "session_metrics": true,
+    "session_persistence": true,
+    "skip_rag": false,
+    "smart_next_task": true,
+    "spec_diffing": true,
     "status_line": true,
-    "auto_continue": false,
-    "auto_advance": false,
+    "structured_planning": true,
+    "tdd_mode": false,
     "team_discussions": false,
-    "inline_verify": false
+    "team_onboarding": false,
+    "tech_debt_surfacing": true,
+    "trust_tracking": true,
+    "zero_friction_quick": true
   },
+  "_guide_models": [
+    "Per-agent model: sonnet|opus|haiku|inherit",
+    "complexity_map: auto-select model by task difficulty",
+    "model_profiles: custom named presets (e.g. 'budget' using haiku everywhere)"
+  ],
   "models": {
-    "researcher": "sonnet",
-    "planner": "inherit",
-    "executor": "inherit",
-    "verifier": "sonnet",
-    "integration_checker": "sonnet",
+    "complexity_map": {
+      "complex": "inherit",
+      "medium": "sonnet",
+      "simple": "haiku"
+    },
     "debugger": "inherit",
+    "executor": "sonnet",
+    "integration_checker": "sonnet",
     "mapper": "sonnet",
-    "synthesizer": "sonnet"
+    "planner": "sonnet",
+    "researcher": "sonnet",
+    "synthesizer": "haiku",
+    "verifier": "sonnet"
   },
+  "model_profiles": {},
+  "_guide_parallelization": [
+    "enabled: allow parallel plan execution within a wave",
+    "max_concurrent_agents: 1-10 — max simultaneous executor subagents",
+    "min_plans_for_parallel: minimum plans in a wave to trigger parallel execution",
+    "plan_level: parallelize at plan level (multiple plans in same wave)",
+    "task_level: parallelize at task level within a plan (not currently used)",
+    "use_teams: use Agent Teams for coordination (discussion only, never execution)",
+    "teams.*: roles and coordination strategy for team discussions"
+  ],
   "parallelization": {
-    "enabled": true,
-    "plan_level": true,
-    "task_level": false,
+    "enabled": false,
     "max_concurrent_agents": 3,
     "min_plans_for_parallel": 2,
+    "plan_level": false,
+    "task_level": false,
     "use_teams": false
   },
-  "planning": {
-    "commit_docs": true,
-    "max_tasks_per_plan": 3,
-    "search_gitignored": false
+  "teams": {
+    "coordination": "file-based",
+    "planning_roles": [
+      "architect",
+      "security-reviewer",
+      "test-designer"
+    ],
+    "review_roles": [
+      "functional-reviewer",
+      "security-auditor",
+      "performance-analyst"
+    ],
+    "synthesis_model": "sonnet"
+  },
+  "_guide_workflow": [
+    "autonomous: enable /pbr:autonomous for hands-free multi-phase execution",
+    "enforce_pbr_skills: advisory|block|off — PBR workflow compliance enforcement",
+    "inline_context_cap_pct: context % above which always spawn subagent",
+    "inline_execution: trivial plans execute inline without subagent",
+    "inline_max_files: max files for inline execution eligibility",
+    "inline_max_lines: max estimated lines of change for inline execution",
+    "inline_max_tasks: max tasks for inline execution eligibility",
+    "max_phases_in_context: max phase plans held simultaneously by orchestrator",
+    "phase_boundary_clear: recommend|enforce|off — /clear at phase boundaries",
+    "phase_replay: failed verification triggers replay with enriched context",
+    "speculative_planning: plan phase N+1 while executor runs phase N"
+  ],
+  "workflow": {
+    "autonomous": false,
+    "enforce_pbr_skills": "advisory",
+    "inline_context_cap_pct": 40,
+    "inline_execution": false,
+    "inline_max_files": 5,
+    "inline_max_lines": 50,
+    "inline_max_tasks": 2,
+    "max_phases_in_context": 3,
+    "phase_boundary_clear": "off",
+    "phase_replay": false,
+    "speculative_planning": false
+  },
+  "_guide_git": [
+    "git.auto_pr: create GitHub PR after successful phase verification",
+    "git.branching: none|phase|milestone|disabled — branching strategy",
+    "git.commit_format: commit message template with {type}, {phase}, {plan}, {description}",
+    "git.mode: enabled|disabled — disabled skips all git operations",
+    "ci.gate_enabled: block wave advancement until CI passes",
+    "ci.wait_timeout_seconds: max seconds to wait for CI completion",
+    "planning.commit_docs: commit SUMMARY/VERIFICATION after builds",
+    "planning.max_tasks_per_plan: 1-10 — keeps plans focused and atomic",
+    "planning.multi_phase: enable --through flag for multi-phase planning",
+    "planning.search_gitignored: include gitignored files in codebase scanning"
+  ],
+  "ci": {
+    "gate_enabled": false,
+    "wait_timeout_seconds": 120
   },
   "git": {
+    "auto_pr": false,
     "branching": "none",
     "commit_format": "{type}({phase}-{plan}): {description}",
-    "phase_branch_template": "plan-build-run/phase-{phase}-{slug}",
-    "milestone_branch_template": "plan-build-run/{milestone}-{slug}",
-    "mode": "enabled"
+    "milestone_branch_template": "pbr/{milestone}-{slug}",
+    "mode": "enabled",
+    "phase_branch_template": "pbr/phase-{phase}-{slug}"
   },
-  "gates": {
-    "confirm_project": true,
-    "confirm_roadmap": true,
-    "confirm_plan": true,
-    "confirm_execute": false,
-    "confirm_transition": true,
-    "issues_review": true
+  "planning": {
+    "commit_docs": false,
+    "max_tasks_per_plan": 3,
+    "multi_phase": false,
+    "search_gitignored": false
   },
-  "safety": {
-    "always_confirm_destructive": true,
-    "always_confirm_external_services": true
+  "_guide_verification": [
+    "validation_passes: which review passes run with multi_layer_validation",
+    "  options: correctness, security, performance, style, tests, accessibility, docs, deps",
+    "verification.confidence_gate: skip verification if executor reports 100% completion + tests pass",
+    "verification.confidence_threshold: 0.5-1.0 — minimum confidence to skip verification"
+  ],
+  "validation_passes": [
+    "correctness",
+    "security"
+  ],
+  "verification": {
+    "confidence_gate": false,
+    "confidence_threshold": 1
+  },
+  "_guide_context_budget": [
+    "context_budget.threshold_curve: linear|adaptive — warning threshold scaling",
+    "  linear = fixed 50/70/85%, adaptive = shifts up for 1M context (60/75/85%)",
+    "context_ledger.enabled: track what files are in context and when they go stale",
+    "context_ledger.stale_after_minutes: 5-1440 — minutes before a read is considered stale"
+  ],
+  "context_budget": {
+    "threshold_curve": "linear"
+  },
+  "context_ledger": {
+    "enabled": false,
+    "stale_after_minutes": 60
+  },
+  "_guide_hooks": [
+    "hook_server.enabled: route hooks through persistent HTTP server (faster than per-hook processes)",
+    "hook_server.port: TCP port for hook server (localhost only)",
+    "hooks.autoFormat: run auto-formatting after file writes",
+    "hooks.blockDocSprawl: block creation of excessive documentation files",
+    "hooks.compactThreshold: 10-200 — context % at which to suggest compaction",
+    "hooks.detectConsoleLogs: warn when console.log statements are added",
+    "hooks.typeCheck: run type checking after file writes"
+  ],
+  "hook_server": {
+    "enabled": false,
+    "event_log": true,
+    "port": 19836
+  },
+  "hooks": {
+    "autoFormat": false,
+    "blockDocSprawl": true,
+    "compactThreshold": 50,
+    "detectConsoleLogs": true,
+    "typeCheck": false
+  },
+  "_guide_intelligence": [
+    "intel.enabled: persistent codebase intelligence (architecture maps, file graph)",
+    "intel.auto_update: PostToolUse hooks queue intel updates on code changes",
+    "intel.inject_on_start: inject architecture summary into session context at start",
+    "learnings.enabled: cross-phase knowledge transfer via LEARNINGS.md",
+    "learnings.read_depth: 1-20 — how many prior phases' learnings the planner reads",
+    "learnings.cross_project_knowledge: copy learnings to ~/.claude/pbr-knowledge/ for reuse"
+  ],
+  "intel": {
+    "auto_update": false,
+    "enabled": false,
+    "inject_on_start": false
+  },
+  "learnings": {
+    "cross_project_knowledge": false,
+    "enabled": false,
+    "read_depth": 3
+  },
+  "_guide_tools": [
+    "dashboard: web UI for browsing .planning/ state (default port 3141)",
+    "debug.max_hypothesis_rounds: 1-20 — max hypothesis cycles for /pbr:debug",
+    "depth_profiles: override built-in quick/standard/comprehensive defaults",
+    "developer_profile: behavioral profiling from session history + prompt injection",
+    "local_llm: offload classification tasks to local Ollama instance",
+    "prd.auto_extract: skip confirmation gate during PRD import",
+    "spinner_tips: custom messages shown during agent execution",
+    "status_line: status bar appearance (sections, branding, context bar)",
+    "timeouts: task/build/verify timeout limits in milliseconds",
+    "ui.enabled: enable UI design pipeline (/pbr:ui-phase, /pbr:ui-review)",
+    "worktree.sparse_paths: glob patterns for sparse checkout in agent worktrees"
+  ],
+  "dashboard": {
+    "auto_launch": false,
+    "port": 3141
+  },
+  "debug": {
+    "max_hypothesis_rounds": 5
+  },
+  "depth_profiles": {},
+  "developer_profile": {
+    "enabled": false,
+    "inject_prompts": false
+  },
+  "local_llm": {
+    "enabled": false
+  },
+  "prd": {
+    "auto_extract": false
+  },
+  "spinner_tips": {
+    "exclude_defaults": false,
+    "tips": []
+  },
+  "status_line": {
+    "brand_text": "PBR",
+    "context_bar": {
+      "chars": {
+        "empty": "░",
+        "filled": "█"
+      },
+      "thresholds": {
+        "green": 50,
+        "yellow": 75
+      },
+      "width": 20
+    },
+    "max_status_length": 80,
+    "sections": [
+      "phase",
+      "plan",
+      "status",
+      "context"
+    ]
+  },
+  "timeouts": {
+    "build_max_ms": 600000,
+    "task_default_ms": 300000,
+    "verify_max_ms": 300000
+  },
+  "ui": {
+    "enabled": false
+  },
+  "worktree": {
+    "sparse_paths": []
   }
 }

package/plugins/pbr/skills/begin/templates/researcher-prompt.md.tmpl

@@ -1,5 +1,21 @@
 <!-- Source: begin/SKILL.md | Purpose: Prompt template for spawning researcher agents during project initialization -->
 
+<downstream_consumer>
+Your output will be consumed by:
+- **Synthesizer agent:** Reads all research files to produce SUMMARY.md. Needs: structured findings with confidence levels, source attributions, clear recommendations. Missing confidence levels prevent the synthesizer from assessing reliability.
+- **Planner agent:** Uses synthesized research for phase planning. Needs: technology recommendations, architecture patterns, and pitfall warnings to shape plan verification steps.
+- **Dashboard ResearchTab:** Displays research confidence and coverage. Needs: frontmatter with confidence and coverage fields.
+</downstream_consumer>
+
+<quality_gates>
+Before completing your output, verify:
+- [ ] Every finding has a confidence level (HIGH/MEDIUM/LOW)
+- [ ] Every recommendation cites at least one source
+- [ ] Coverage assessment table is filled in (COMPLETE/PARTIAL/INSUFFICIENT)
+- [ ] Gaps are explicitly listed, not hidden behind confident language
+- [ ] Output file matches the research output template format
+</quality_gates>
+
 <project_context>
 Project: {project name from questioning}
 Description: {2-3 sentence description from questioning}
@@ -16,4 +32,16 @@ Research these specific questions:
 {topic-specific questions - see below}
 </research_assignment>
 
+<output_contract>
+Your output MUST follow the template at `{resolved_plugin_root}/templates/research-outputs/{TOPIC}.md.tmpl` where {TOPIC} is one of: STACK, FEATURES, ARCHITECTURE, PITFALLS.
+
+Your output MUST include YAML frontmatter with the following required fields:
+- `confidence`: HIGH | MEDIUM | LOW (overall confidence in findings)
+- `sources_checked`: integer (number of sources consulted)
+
+Write your output to `.planning/research/{TOPIC}.md`. Do NOT commit the file -- the synthesizer will commit all research files together after producing SUMMARY.md.
+</output_contract>
+
 Write your findings to the output file using the Project Research output format from your agent definition. Use the Write tool to create the file.
+
+When complete, end your output with `## RESEARCH COMPLETE` if successful, or `## RESEARCH BLOCKED` with a reason if unable to complete.

package/plugins/pbr/skills/begin/templates/roadmap-prompt.md.tmpl

@@ -1,5 +1,23 @@
 <!-- Source: begin/SKILL.md | Purpose: Prompt template for spawning the planner agent in roadmap mode -->
 
+<downstream_consumer>
+Your output will be consumed by:
+- **Planner agent:** Reads roadmap to create phase plans. Needs: phase goals, dependencies, requirement mappings.
+- **Build agent:** Reads current phase definition. Needs: clear success criteria and deliverables.
+- **Status skill:** Reads progress table. Needs: consistent progress table format matching phase count.
+- **check-plan-format.js and check-roadmap-sync.js:** Parse roadmap structure. Needs: `## Milestone:` and `### Phase NN:` headings in exact format.
+</downstream_consumer>
+
+<quality_gates>
+Before completing your output, verify:
+- [ ] Every phase has Goal, Requirements, Success Criteria, Provides, and Depends on fields
+- [ ] Dependencies form a DAG (no circular dependencies)
+- [ ] Requirement IDs map to entries in REQUIREMENTS.md
+- [ ] Progress table row count matches phase count and includes Milestone column
+- [ ] Milestone sections use exact `## Milestone:` heading format
+- [ ] A `## Milestones` index section exists near the top of the roadmap
+</quality_gates>
+
 <project_context>
 Project: {project name}
 Description: {description}
@@ -20,12 +38,17 @@ Phase count guidelines based on depth:
 
 Each phase should:
 1. Have a clear, achievable goal
-2. Map to specific REQ-IDs
-3. Build on prior phases logically
-4. Be independently verifiable
+2. Include **Requirements:** listing mapped REQ-IDs
+3. Include **Success Criteria:** with verifiable conditions
+4. Build on prior phases logically
+5. Be independently verifiable
 
 **Milestone structure:** Wrap all phases in a `## Milestone:` section. For comprehensive-depth projects with 8+ phases, consider splitting into multiple milestones at natural delivery boundaries. Use the milestone section format from the roadmap template (`## Milestone: {name}` with `**Goal:**` and `**Phases:** start - end`).
 
+**Milestone index:** Include a `## Milestones` index section near the top of the roadmap (after the title) listing each milestone with version, name, status, and date columns.
+
+**Progress table:** Include a Milestone column in the progress table so each phase row shows which milestone it belongs to.
+
 Write the roadmap to .planning/ROADMAP.md using the roadmap format from your agent definition.
 </roadmap_instructions>
 

package/plugins/pbr/skills/begin/templates/synthesis-prompt.md.tmpl

@@ -1,16 +1,44 @@
 <!-- Source: begin/SKILL.md | Purpose: Prompt template for spawning the synthesis agent after research completes -->
 
+<downstream_consumer>
+Your output will be consumed by:
+- **Planner agent (primary consumer):** Reads SUMMARY.md for all planning decisions. Needs: stack recommendation, architecture recommendation, key risks, feature priorities. If synthesis omits a dimension, the planner makes decisions without that research.
+- **Begin skill:** Presents synthesis to user for approval before roadmap creation. Needs: executive summary and consolidated recommendations.
+- **Dashboard ResearchTab:** Displays synthesis with confidence levels. Needs: confidence assessment table and research coverage fields.
+</downstream_consumer>
+
+<quality_gates>
+Before completing your output, verify:
+- [ ] All available research dimensions referenced (Stack, Features, Architecture, Pitfalls)
+- [ ] Confidence gaps noted for any missing dimensions
+- [ ] Executive summary is under 200 words
+- [ ] Recommendations are prescriptive ("Use X") not exploratory ("Consider X or Y")
+- [ ] Partial failure handled -- missing dimensions noted explicitly, not silently omitted
+</quality_gates>
+
 <research_documents>
-Read the following research documents and synthesize them:
-{List all .planning/research/*.md files that were created}
+Read ALL .md files in the `.planning/research/` directory (excluding SUMMARY.md). These are your research inputs. Discover files dynamically at runtime -- do not rely on a hardcoded list.
 </research_documents>
 
+<partial_failure_handling>
+Some research dimensions may be missing. For each of the 4 dimensions (Stack, Features, Architecture, Pitfalls):
+- If the corresponding file exists: synthesize its findings
+- If the file is missing: mark the dimension as MISSING in the Research Coverage table and LOW confidence in the Confidence Assessment table
+- Never fail or block due to missing input files. Produce SUMMARY.md with whatever inputs are available.
+</partial_failure_handling>
+
 <synthesis_instructions>
-1. Read all research documents
+1. Read all research documents found in `.planning/research/` (excluding SUMMARY.md)
 2. Identify consensus findings
-3. Resolve contradictions (higher source level wins)
+3. Resolve contradictions (higher source level wins per S0-S6 hierarchy)
 4. Produce a unified summary with clear recommendations
-5. Write the synthesis to .planning/research/SUMMARY.md using the Synthesis output format
+5. Your output MUST follow the template at `{resolved_plugin_root}/templates/research-outputs/SUMMARY.md.tmpl`
+6. Your output MUST include a **Research Coverage** table showing COMPLETE/PARTIAL/MISSING per dimension
+7. Your output MUST include a **Confidence Assessment** table showing confidence levels per dimension
+8. Write the synthesis to .planning/research/SUMMARY.md using the Synthesis output format
+9. After writing SUMMARY.md, commit ALL files in `.planning/research/` together with message: `docs(research): complete research synthesis`
 </synthesis_instructions>
 
 Write the synthesis to .planning/research/SUMMARY.md using the Write tool.
+
+When complete, end your output with `## SYNTHESIS COMPLETE` if successful, or `## SYNTHESIS BLOCKED` with a reason if unable to complete.