bmad-overlay 0.1.1

package/workflows/councils/analyst-council.md

@@ -0,0 +1,229 @@
+# Council Spec: Analyst Council
+
+## Purpose
+
+Convert a vague or partially defined product request into an analysis synthesis that a PM council can use without rereading raw discovery.
+
+## Entry Conditions
+
+Run when:
+
+- the request is net-new
+- the product framing is weak
+- the ICP is unclear
+- the value proposition is still fuzzy
+- the orchestrator confidence is not high
+
+## Inputs
+
+### Required
+
+- orchestrator intake brief
+
+### Optional but preferred
+
+- `docs/index.md`
+- existing feature docs
+- `product-brief.md`
+- `PRD.md`
+- existing research docs
+- `_bmad-output/project-context.md`
+
+## Seats
+
+### Lead Analyst
+
+Owns convergence and synthesis.
+
+Prompt contract:
+
+- read the orchestrator intake first
+- read any existing authoritative docs before reacting
+- identify the key tensions between the other seats
+- force a single recommendation, not a vague summary
+- write the final synthesis and handoff
+
+Must produce:
+
+- council synthesis
+- council handoff
+
+### Market Analyst
+
+Owns competitors, substitutes, positioning, monetization clues.
+
+Prompt contract:
+
+- analyze the market category
+- identify substitutes even if direct competitors are unknown
+- infer where willingness to pay might exist
+- avoid pretending certainty when evidence is weak
+
+Must produce:
+
+- alternatives today
+- positioning notes
+- market risks
+
+### User Problem Analyst
+
+Owns ICP, JTBD, pain points, outcomes, value proposition clues.
+
+Prompt contract:
+
+- define the most likely first user
+- identify the concrete pain they experience today
+- translate that pain into desired outcomes
+- prefer one primary ICP over a broad list
+
+Must produce:
+
+- primary ICP
+- top pains
+- desired outcomes
+- early value proposition framing
+
+### Feasibility Analyst
+
+Owns technical, data, workflow, and operational constraints.
+
+Prompt contract:
+
+- identify hidden complexity
+- detect integration or data dependencies
+- call out operational realities that may change MVP shape
+- bias toward constraints that affect scope immediately
+
+Must produce:
+
+- feasibility constraints
+- implementation complexity notes
+- operational risks
+
+### Adversarial Analyst
+
+Owns failure analysis, weak assumptions, fake differentiation, and false demand.
+
+Prompt contract:
+
+- attack the strongest assumption, not the weakest one
+- challenge fake novelty and vanity scope
+- identify why the product may not be compelling enough
+- keep criticism actionable
+
+Must produce:
+
+- adversarial findings
+- weak assumptions
+- reasons to narrow or reject
+
+## Output Files
+
+- `docs/studio/runs/<run_id>/analysis-synthesis.md`
+- `docs/studio/runs/<run_id>/analysis-handoff.yaml`
+- `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`
+
+These are overlay-owned artifacts and are intentionally kept under `docs/studio/runs/<run_id>/`.
+
+## Per-Seat Output Contract
+
+Each seat should return a concise structured note:
+
+```yaml
+seat: ""
+focus: ""
+key_findings: []
+risks: []
+assumptions: []
+recommendation: ""
+confidence: "high|medium|low"
+```
+
+These seat outputs are persistent files in `docs/studio/runs/<run_id>/`, not ephemeral intermediate results.
+
+## Lead Analyst Synthesis Contract
+
+The Lead Analyst must produce one synthesis document with these sections:
+
+1. Request Summary
+2. Problem Statement
+3. Primary ICP
+4. Top Pains and Outcomes
+5. Alternatives Today
+6. Value Proposition
+7. V1 Scope Boundary
+8. Assumptions To Validate
+9. Feasibility Constraints
+10. Adversarial Findings
+11. Council Decision
+12. Recommended Input To PM Council
+
+## Lead Analyst Writing Rules
+
+- do not dump all seat notes verbatim
+- resolve contradictions explicitly
+- if confidence is low, say why
+- convert analysis into PM-ready framing
+- name what is still unknown, but do not block for trivia
+
+## Handoff To PM Council
+
+The analyst handoff must answer these PM-facing questions:
+
+- what exact product opportunity should PM shape?
+- who is the first user and why them?
+- what should PM keep out of MVP?
+- what assumptions must PM preserve or validate?
+- what major risks should influence prioritization?
+
+## PM Handoff Contract
+
+Suggested structure:
+
+```yaml
+stage: "analyst-council"
+decision: "continue|narrow|reject"
+why: ""
+must_read_next:
+  - "docs/studio/runs/<run_id>/analysis-synthesis.md"
+artifacts_updated:
+  - "docs/studio/runs/<run_id>/analysis-synthesis.md"
+  - "docs/studio/runs/<run_id>/analysis-handoff.yaml"
+open_questions: []
+blocked_by: []
+recommended_next_stage: "pm-council|orchestrator"
+```
+
+## Minimum Required Synthesis
+
+- problem statement
+- primary ICP
+- top pains
+- value proposition
+- V1 scope boundary
+- assumptions to validate
+- continue/narrow/reject decision
+
+## Escalation Threshold
+
+Escalate only for:
+
+- multiple equally plausible product directions
+- no inferable ICP
+- conflict with existing authoritative docs
+- external business decision required
+
+## Next Consumer
+
+- `PM Council`
+
+## Suggested Execution Order
+
+1. Market Analyst
+2. User Problem Analyst
+3. Feasibility Analyst
+4. Adversarial Analyst
+5. Lead Analyst synthesis

package/workflows/councils/architecture-council.md

@@ -0,0 +1,240 @@
+# Council Spec: Architecture Council
+
+## Purpose
+
+Translate a PM-ready product plan into implementation strategy, system boundaries, technical decisions, and delivery constraints that the Delivery Council can execute without reopening product discovery.
+
+## Entry Conditions
+
+Run when:
+
+- a product brief or PRD exists
+- the MVP scope is stable enough to design against
+- the implementation path needs explicit technical decisions
+- the request is not just a trivial copy change or content tweak
+- the orchestrator confidence is not low on product framing
+
+## Skip Conditions
+
+The orchestrator may skip or shorten the Architecture Council when all of the following are true:
+
+- the change is fully bounded and uses an already established pattern
+- no new system boundary, data model, or integration is introduced
+- the Delivery Council can implement from existing project context and stories
+- the request is clearly a minor follow-up to an already-approved slice
+
+If skipped, the orchestrator must record a short rationale in the handoff path and point to the authoritative architecture source already in force.
+
+## Inputs
+
+### Required
+
+- PM council synthesis
+- orchestrator intake brief
+
+### Optional but preferred
+
+- `docs/index.md`
+- feature-local docs
+- `_bmad-output/project-context.md`
+- `_bmad-output/planning-artifacts/product-brief.md`
+- `_bmad-output/planning-artifacts/PRD.md`
+- any existing architecture docs
+- any existing stories or epic breakdowns
+
+## Seats
+
+### Lead Architect
+
+Owns convergence and the final architecture synthesis.
+
+Prompt contract:
+
+- read PM synthesis before forming any architectural position
+- identify the minimum safe implementation shape
+- resolve contradictions between seats explicitly
+- turn architecture choices into deployable constraints
+- write the final synthesis and handoff
+
+Must produce:
+
+- architecture synthesis
+- architecture handoff
+
+### Application Architect
+
+Owns application boundaries, API shape, module structure, and service seams.
+
+Prompt contract:
+
+- identify the simplest app structure that preserves clarity
+- define boundaries that keep implementation from becoming tangled
+- call out API and module decisions that developers must follow
+- avoid over-architecting if a monolith suffices
+
+Must produce:
+
+- application structure notes
+- API and boundary risks
+- module boundary recommendations
+
+### Data Architect
+
+Owns schema, persistence, tenancy, state, migration, and reporting concerns.
+
+Prompt contract:
+
+- identify the minimal durable data model
+- call out migration and tenancy implications
+- flag places where data shape will constrain delivery
+- keep schema decisions explicit and avoid ambiguity
+
+Must produce:
+
+- data model notes
+- persistence risks
+- migration concerns
+
+### Delivery Architect
+
+Owns decomposition into implementation slices and sequencing for execution.
+
+Prompt contract:
+
+- break architecture into buildable slices
+- identify dependencies between slices
+- protect the Delivery Council from vague scope
+- prefer slices that can be implemented and tested independently
+
+Must produce:
+
+- delivery slices
+- sequencing notes
+- dependency map
+
+### Constraint Reviewer
+
+Owns hidden coupling, scaling traps, edge cases, and feasibility friction.
+
+Prompt contract:
+
+- attack assumptions that would leak into implementation
+- identify risks that only appear under load or with real users
+- challenge architecture choices that create avoidable fragility
+- keep feedback actionable and scoped
+
+Must produce:
+
+- constraint risks
+- edge cases
+- rejection or caution notes
+
+## Output Files
+
+- `docs/studio/runs/<run_id>/architecture-synthesis.md`
+- `docs/studio/runs/<run_id>/architecture-handoff.yaml`
+- `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`
+
+These are overlay-owned artifacts and are intentionally kept in `docs/studio/runs/<run_id>/`.
+
+## Per-Seat Output Contract
+
+Each seat should return a concise structured note:
+
+```yaml
+seat: ""
+focus: ""
+key_findings: []
+risks: []
+assumptions: []
+recommendation: ""
+confidence: "high|medium|low"
+```
+
+These seat outputs are persistent files in `docs/studio/runs/<run_id>/`, not ephemeral intermediate results.
+
+## Lead Architect Synthesis Contract
+
+The Lead Architect must produce one synthesis document with these sections:
+
+1. Request Summary
+2. Product and Scope Anchors
+3. Key Technical Decisions
+4. System Boundaries
+5. Data and State Decisions
+6. API and Module Decisions
+7. Delivery Slices
+8. Constraints and Risks
+9. Deferred Decisions
+10. Council Decision
+11. Recommended Input To Delivery Council
+
+## Lead Architect Writing Rules
+
+- do not restate PM content unless it affects implementation
+- make decisions explicit and citable
+- prefer boring, safe patterns when they fit
+- identify what must stay stable for the Delivery Council
+- do not introduce unnecessary abstraction
+
+## Handoff To Delivery Council
+
+The architecture handoff must answer these delivery-facing questions:
+
+- what implementation slices should be built first?
+- what boundaries must developers not cross?
+- what data or API decisions are locked?
+- what risks should shape ordering and tests?
+- what should the Delivery Council treat as non-negotiable?
+
+## Delivery Handoff Contract
+
+Suggested structure:
+
+```yaml
+stage: "architecture-council"
+decision: "continue|narrow|reject"
+why: ""
+must_read_next:
+  - "docs/studio/runs/<run_id>/architecture-synthesis.md"
+artifacts_updated:
+  - "docs/studio/runs/<run_id>/architecture-synthesis.md"
+  - "docs/studio/runs/<run_id>/architecture-handoff.yaml"
+open_questions: []
+blocked_by: []
+recommended_next_stage: "delivery-council|orchestrator"
+```
+
+## Minimum Required Synthesis
+
+- product and scope anchors
+- key technical decisions
+- system boundaries
+- data and state decisions
+- delivery slices
+- constraints and risks
+- continue/narrow/reject decision
+
+## Escalation Threshold
+
+Escalate only for:
+
+- product scope that is still unstable enough to invalidate architecture
+- architectural directions that are materially incompatible
+- missing critical information that cannot be inferred from docs or code
+- external infrastructure, security, or cost decisions that require the user
+
+## Next Consumer
+
+- `Delivery Council`
+
+## Suggested Execution Order
+
+1. Application Architect
+2. Data Architect
+3. Delivery Architect
+4. Constraint Reviewer
+5. Lead Architect synthesis