bmad-overlay 0.1.1

package/skills/orchestrator-start-run/SKILL.md

@@ -0,0 +1,62 @@
+# orchestrator-start-run
+
+## Purpose
+
+Start or safely resume an orchestration run.
+
+## When To Use
+
+Use this skill when the visible orchestrator needs to:
+
+- start a new run
+- decide whether to reuse an active `run_id`
+- initialize control files
+- establish the first active stage
+
+## Inputs
+
+- user request
+- `docs/index.md` when present
+- `docs/studio/current-stage.yaml` when present
+- `docs/studio/run-manifest.md` when present
+
+## Required Decisions
+
+The skill must decide:
+
+1. reuse current `run_id` or create a new one
+2. what the first active stage is
+3. what `current_council_spec` should be
+4. what `resume_read_order` should be
+
+## Procedure
+
+1. Read the current control files if they exist.
+2. Determine whether an active run is recoverable.
+3. If recoverable and still authoritative, reuse the same `run_id`.
+4. Otherwise create a new `run_id`.
+5. Create `docs/studio/runs/<run_id>/` if needed.
+6. Initialize or refresh:
+   - `docs/studio/current-stage.yaml`
+   - `docs/studio/run-manifest.md`
+7. Set:
+   - `run_id`
+   - `active_run_dir`
+   - `active_stage`
+   - `current_council_spec`
+   - `next_planned_stage`
+   - `allowed_transition_types`
+8. Write initial `resume_read_order`.
+
+## Outputs
+
+- updated `docs/studio/current-stage.yaml`
+- updated `docs/studio/run-manifest.md`
+- active run directory under `docs/studio/runs/<run_id>/`
+
+## Success Criteria
+
+- active run is unambiguous
+- first stage is explicit
+- control files point to the same run
+- the next agent can resume from disk only

package/skills/orchestrator-start-run/bmad-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

package/skills/orchestrator-start-run/workflow.md

@@ -0,0 +1,47 @@
+# Start Run Workflow
+
+## Goal
+
+Initialize or safely resume a run for the overlay orchestrator.
+
+## Role
+
+You are a deterministic run initializer.
+You decide whether to reuse an active `run_id` or create a new one, then you align the control files.
+
+## Inputs
+
+- user request
+- `docs/index.md` when present
+- `docs/studio/current-stage.yaml` when present
+- `docs/studio/run-manifest.md` when present
+
+## Procedure
+
+1. Read current control files if they exist.
+2. Decide whether the active run is still authoritative and recoverable.
+3. If yes, reuse the same `run_id`.
+4. If no, create a new `run_id`.
+5. Ensure `docs/studio/runs/<run_id>/` exists.
+6. Initialize or refresh:
+   - `docs/studio/current-stage.yaml`
+   - `docs/studio/run-manifest.md`
+7. Set:
+   - `run_id`
+   - `active_run_dir`
+   - `active_stage`
+   - `current_council_spec`
+   - `next_planned_stage`
+   - `allowed_transition_types`
+8. Write the initial `resume_read_order`.
+
+## Outputs
+
+- updated `docs/studio/current-stage.yaml`
+- updated `docs/studio/run-manifest.md`
+
+## Success Criteria
+
+- the active run is unambiguous
+- control files point to the same run
+- the next stage is explicit

package/templates/CLAUDE.md

@@ -0,0 +1,51 @@
+# Project Agent Constitution
+
+## Role of the visible agent
+
+You are the single visible orchestrator for this project.
+You may delegate internally, but the user should not need to switch between agents manually.
+
+## Mandatory reading order
+
+Before asking questions or making a plan, read in this order when available:
+
+1. `docs/index.md`
+2. `docs/features/<feature>/index.md`
+3. `docs/features/<feature>/handoff.md`
+4. `docs/features/<feature>/journal.md`
+5. `_bmad-output/project-context.md`
+
+## Interruption policy
+
+Do not interrupt the user for:
+
+- local naming choices
+- file placement choices consistent with the repo
+- minor refactors
+- documentation updates
+- reasonable test additions
+
+Escalate only for:
+
+- product ambiguity
+- conflicting sources of truth
+- architecture changes with broad impact
+- external cost or security risk
+
+## Documentation policy
+
+Before ending substantial work, update:
+
+- the relevant feature `journal.md`
+- the relevant feature `handoff.md`
+- `docs/index.md` if navigation changed
+
+## Source of truth order
+
+If sources conflict, prefer:
+
+1. explicit user instruction
+2. feature-local docs
+3. project-wide docs
+4. `_bmad-output/project-context.md`
+5. codebase conventions inferred from code

package/templates/analysis-synthesis.md

@@ -0,0 +1,25 @@
+# Analysis Synthesis
+
+## Request Summary
+
+## Problem Statement
+
+## Primary ICP
+
+## Top Pains and Outcomes
+
+## Alternatives Today
+
+## Value Proposition
+
+## V1 Scope Boundary
+
+## Assumptions To Validate
+
+## Feasibility Constraints
+
+## Adversarial Findings
+
+## Council Decision
+
+## Recommended Input To PM Council

package/templates/analyst-seat-output.yaml

@@ -0,0 +1,7 @@
+seat: ""
+focus: ""
+key_findings: []
+risks: []
+assumptions: []
+recommendation: ""
+confidence: "high|medium|low"

package/templates/architecture-handoff.yaml

@@ -0,0 +1,8 @@
+stage: "architecture-council"
+decision: "continue|narrow|reject"
+why: ""
+must_read_next: []
+artifacts_updated: []
+open_questions: []
+blocked_by: []
+recommended_next_stage: "delivery-council|orchestrator"

package/templates/architecture-seat-output.yaml

@@ -0,0 +1,7 @@
+seat: ""
+focus: ""
+key_findings: []
+risks: []
+assumptions: []
+recommendation: ""
+confidence: "high|medium|low"

package/templates/architecture-synthesis.md

@@ -0,0 +1,23 @@
+# Architecture Synthesis
+
+## Request Summary
+
+## Product and Scope Anchors
+
+## Key Technical Decisions
+
+## System Boundaries
+
+## Data and State Decisions
+
+## API and Module Decisions
+
+## Delivery Slices
+
+## Constraints and Risks
+
+## Deferred Decisions
+
+## Council Decision
+
+## Recommended Input To Delivery Council

package/templates/current-stage.yaml

@@ -0,0 +1,26 @@
+active_stage: ""
+active_lead: ""
+parallel_workers: []
+authoritative_synthesis: ""
+authoritative_handoff: ""
+next_stage_blocked_on: []
+stage_status: "idle"
+run_id: ""
+active_run_dir: ""
+current_council_spec: ""
+lead_task_file: ""
+seat_output_files: []
+seat_task_files: []
+required_files_missing: []
+last_completed_stage: ""
+resume_read_order: []
+recommended_next_action: ""
+run_status: "active"
+prior_run_ids: []
+abandon_reason: ""
+transition_reason: ""
+next_planned_stage: ""
+allowed_transition_types: []
+control_last_updated_at: ""
+blocking_reason: ""
+restart_count: 0

package/templates/delivery-seat-output.yaml

@@ -0,0 +1,7 @@
+seat: ""
+focus: ""
+key_findings: []
+risks: []
+assumptions: []
+recommendation: ""
+confidence: "high|medium|low"

package/templates/delivery-synthesis.md

@@ -0,0 +1,27 @@
+# Delivery Synthesis
+
+## Request Summary
+
+## Plan Summary
+
+## Stories
+
+## Dependencies
+
+## Parallelizable Slices
+
+## Serialized Slices
+
+## Write Scopes
+
+## Implemented Slices
+
+## Files Changed
+
+## Tests Added Or Updated
+
+## Known Gaps
+
+## Risks
+
+## QA Handoff

package/templates/docs-index.md

@@ -0,0 +1,19 @@
+# Documentation Index
+
+## Start Here
+
+- `docs/index.md`: global entrypoint
+- `docs/features/`: feature-specific state and handoff
+- `docs/architecture/`: architectural rules and major decisions
+- `_bmad-output/`: BMAD-generated artifacts
+
+## Active Features
+
+- Add one line per feature:
+- `docs/features/<feature>/index.md` - purpose and current status
+
+## Source of Truth
+
+- Product and delivery artifacts: `_bmad-output/planning-artifacts/`
+- Implementation rules: `_bmad-output/project-context.md`
+- Feature continuation state: `docs/features/<feature>/handoff.md`

package/templates/docs-studio-layout.md

@@ -0,0 +1,88 @@
+# docs/studio Layout
+
+## Purpose
+
+Define the canonical file layout for a full overlay run.
+
+## Global Control Files
+
+- `docs/studio/current-stage.yaml`
+- `docs/studio/run-manifest.md`
+
+## Run ID Strategy
+
+Every orchestration run gets a unique `run_id`.
+
+Recommended layout:
+
+- `docs/studio/runs/<run_id>/`
+
+Control files stay at the root of `docs/studio/`, but they point to the active run directory.
+
+## Stage Files
+
+### Analyst Council
+
+- `docs/studio/runs/<run_id>/analysis-market-analyst.yaml`
+- `docs/studio/runs/<run_id>/analysis-user-problem-analyst.yaml`
+- `docs/studio/runs/<run_id>/analysis-feasibility-analyst.yaml`
+- `docs/studio/runs/<run_id>/analysis-adversarial-analyst.yaml`
+- `docs/studio/runs/<run_id>/analysis-synthesis.md`
+- `docs/studio/runs/<run_id>/analysis-handoff.yaml`
+
+### PM Council
+
+- `docs/studio/runs/<run_id>/pm-mvp-pm.yaml`
+- `docs/studio/runs/<run_id>/pm-growth-pm.yaml`
+- `docs/studio/runs/<run_id>/pm-risk-pm.yaml`
+- `docs/studio/runs/<run_id>/pm-ux-pm.yaml`
+- `docs/studio/runs/<run_id>/pm-synthesis.md`
+- `docs/studio/runs/<run_id>/pm-handoff.yaml`
+
+### Architecture Council
+
+- `docs/studio/runs/<run_id>/architecture-application-architect.yaml`
+- `docs/studio/runs/<run_id>/architecture-data-architect.yaml`
+- `docs/studio/runs/<run_id>/architecture-delivery-architect.yaml`
+- `docs/studio/runs/<run_id>/architecture-constraint-reviewer.yaml`
+- `docs/studio/runs/<run_id>/architecture-synthesis.md`
+- `docs/studio/runs/<run_id>/architecture-handoff.yaml`
+
+### Delivery Council
+
+- `docs/studio/runs/<run_id>/delivery-story-planner.yaml`
+- `docs/studio/runs/<run_id>/delivery-dependency-planner.yaml`
+- `docs/studio/runs/<run_id>/delivery-dev-representative.yaml`
+- `docs/studio/runs/<run_id>/delivery-frontend-dev.yaml`
+- `docs/studio/runs/<run_id>/delivery-backend-dev.yaml`
+- `docs/studio/runs/<run_id>/delivery-data-dev.yaml`
+- `docs/studio/runs/<run_id>/delivery-integration-dev.yaml`
+- `docs/studio/runs/<run_id>/delivery-quick-fix-dev.yaml`
+- `docs/studio/runs/<run_id>/delivery-plan.md`
+- `docs/studio/runs/<run_id>/delivery-synthesis.md`
+- `docs/studio/runs/<run_id>/delivery-handoff.yaml`
+
+### QA / Review Council
+
+- `docs/studio/runs/<run_id>/qa-review-qa-engineer.yaml`
+- `docs/studio/runs/<run_id>/qa-review-edge-case-reviewer.yaml`
+- `docs/studio/runs/<run_id>/qa-review-docs-continuity-reviewer.yaml`
+- `docs/studio/runs/<run_id>/qa-review-release-gatekeeper.yaml`
+- `docs/studio/runs/<run_id>/qa-review-summary.md`
+- `docs/studio/runs/<run_id>/qa-review-findings.yaml`
+- `docs/studio/runs/<run_id>/qa-review-handoff.yaml`
+
+## Naming Rules
+
+- stage prefix first: `analysis`, `pm`, `architecture`, `delivery`, `qa-review`
+- seat file second: `<stage>-<seat>.yaml`
+- authoritative lead outputs use fixed names:
+  - `<stage>-synthesis.md`
+  - `<stage>-handoff.yaml`
+- summary-only review stage may use `qa-review-summary.md`
+- all stage artifacts are namespaced under `runs/<run_id>/`
+
+## Persistence Rule
+
+These files are durable working memory for the overlay.
+They should be readable enough for a later agent to resume work without chat history.

package/templates/feature-index.md

@@ -0,0 +1,21 @@
+# Feature Index Template
+
+## Summary
+
+- Feature name:
+- Owner:
+- Status:
+
+## Read In Order
+
+1. `index.md`
+2. `handoff.md`
+3. `journal.md`
+
+## Relevant Code
+
+- `path/to/file`
+
+## Relevant Decisions
+
+- Link or summarize major decisions here

package/templates/intake-request.yaml

@@ -0,0 +1,12 @@
+request:
+  name: ""
+  goal: ""
+  mode_hint: "quick"
+  domain: ""
+  audience: ""
+  stack: ""
+  constraints: []
+  integrations: []
+  risks: []
+  success_metrics: []
+  out_of_scope: []

package/templates/pm-handoff.yaml

@@ -0,0 +1,11 @@
+stage: "pm-council"
+decision: "continue|narrow|reject"
+why: ""
+must_read_next:
+  - "docs/studio/pm-synthesis.md"
+artifacts_updated:
+  - "docs/studio/pm-synthesis.md"
+  - "docs/studio/pm-handoff.yaml"
+open_questions: []
+blocked_by: []
+recommended_next_stage: "architecture-council|orchestrator"

package/templates/pm-seat-output.yaml

@@ -0,0 +1,7 @@
+seat: ""
+focus: ""
+key_findings: []
+risks: []
+assumptions: []
+recommendation: ""
+confidence: "high|medium|low"

package/templates/pm-synthesis.md

@@ -0,0 +1,25 @@
+# PM Synthesis
+
+## Request Summary
+
+## Product Goal
+
+## Target User
+
+## Desired Outcomes
+
+## MVP Boundary
+
+## In Scope
+
+## Out of Scope
+
+## Success Metrics
+
+## Activation and Retention Considerations
+
+## Product Risks
+
+## Deferred Decisions
+
+## Recommended Input To Architecture Council

package/templates/qa-review-findings.yaml

@@ -0,0 +1,7 @@
+seat: ""
+focus: ""
+status: "pass|warn|fail"
+key_findings: []
+blocking_findings: []
+follow_up: []
+confidence: "high|medium|low"

package/templates/qa-review-handoff.yaml

@@ -0,0 +1,10 @@
+stage: "qa-review-council"
+decision: "pass|warn|fail"
+why: ""
+blocking_issues: []
+non_blocking_issues: []
+test_status: "passed|partial|not_run|failed"
+doc_continuity_status: "clean|warn|broken"
+must_read_next: []
+artifacts_updated: []
+recommended_next_stage: "orchestrator|implementation|release-closeout"

package/templates/qa-review-seat-output.yaml

@@ -0,0 +1,7 @@
+seat: ""
+focus: ""
+status: "pass|warn|fail"
+key_findings: []
+blocking_findings: []
+follow_up: []
+confidence: "high|medium|low"

package/templates/qa-review-summary.md

@@ -0,0 +1,21 @@
+# QA Review Summary
+
+## Review Summary
+
+## Scope Reviewed
+
+## Test Status
+
+## Functional Findings
+
+## Edge-Case Findings
+
+## Documentation Continuity Findings
+
+## Blocking Issues
+
+## Non-Blocking Issues
+
+## Release Recommendation
+
+## Next Action

package/templates/run-manifest.md

@@ -0,0 +1,46 @@
+# Run Manifest
+
+## Purpose
+
+Track the artifact set for one active orchestration run.
+
+## Run Metadata
+
+- `run_id`:
+- `created_at`:
+- `status`: `active|closed|abandoned`
+- `active_stage`:
+- `last_completed_stage`:
+- `next_planned_stage`:
+- `run_dir`: `docs/studio/runs/<run_id>/`
+- `parent_run_id`:
+- `closure_reason`:
+- `abandon_reason`:
+- `last_updated_at`:
+- `transition_reason`:
+
+## Active Artifacts
+
+- `docs/studio/current-stage.yaml`
+- stage-specific seat outputs
+- stage synthesis
+- stage handoff
+
+## Reading Order For Resume
+
+1. `docs/studio/current-stage.yaml`
+2. current stage handoff or latest completed handoff
+3. current stage synthesis or latest completed synthesis
+4. current stage seat outputs
+
+## Lifecycle Notes
+
+- create a new run for a new orchestration or a hard restart
+- reuse a run only when continuing the same active thread
+- close a run when the orchestration loop is complete
+- abandon a run when it is superseded or no longer safely resumable
+
+## Runtime Notes
+
+- update `run-manifest.md` before `current-stage.yaml`
+- treat `current-stage.yaml` as the last authoritative pointer

package/templates/stage-handoff.yaml

@@ -0,0 +1,8 @@
+stage: ""
+decision: ""
+why: ""
+must_read_next: []
+artifacts_updated: []
+open_questions: []
+blocked_by: []
+recommended_next_stage: ""