# templates/mas-blueprint.md

## MAS Blueprint — Complete Specification Template (v2.4)

### 0. Metadata
- **Blueprint ID / Name:** 
- **Version:** 2.4 | **Status:** Draft / In Review / Approved
- **Date:** 
- **Primary Stakeholders:** 

### 1. Problem Framing & Success Criteria
**Restated Objective (concise):**

**Quantified Success Metrics:**

| Metric | Target | Measurement Method | Notes |
|--------|--------|--------------------|-------|

**Explicit Non-Goals & Out-of-Scope:**

### 2. Architectural Justification
**Single-Agent Sufficiency Analysis:**
[Why a single agent is or is not sufficient]

**Recommendation & Rationale:**

### 3. Selected Topology & Rationale
**Topology Name:** (e.g., Hierarchical Supervisor with Specialist Workers + Critic Ensemble)

**Mermaid Architecture Diagram:**
```mermaid
graph TD
    User[User / Trigger] --> O[Orchestrator / Supervisor]
    O --> R1[Research Lead]
    O --> R2[Data Analyst]
    R1 & R2 --> C[Critic / Verifier]
    C --> S[Synthesizer]
    S --> O
```

**High-Level Data & Control Flow:**

### 4. Agent Role Specifications

#### Agent: `role_name_snake_case`
**Mission (one sentence):**
**Specialization & Reasoning Style:**
**Primary Tools & Knowledge Sources:**
**Input Contract:**
**Output Contract:**
**Upstream Sources & Downstream Consumers:**
**Self-Verification Questions:**
**Common Failure Modes & Recovery / Escalation:**
**Token & Latency Budget (per invocation):**

(Repeat full card for every agent: orchestrator, specialists, critics, synthesizer, meta-roles, etc.)

### 5. Coordination, State & Memory
**Orchestration Engine & Justification:**
**State Schema (core entities & persistence):**
**Handoff Protocol & Message Contracts:**
**Shared vs Private Memory Strategy:**
**Conflict Resolution & Consensus Mechanism:**

### 6. Observability, Logging & Tracing
**Required Events & Attributes:**
**Correlation ID & Trace Propagation:**
**Dashboards, Metrics & Alerting Thresholds:**
**Replay & Debugging Capabilities:**

### 7. Evaluation Harness
**Offline Evaluation Strategy (datasets, judges, metrics):**
**Online / Shadow Evaluation:**
**Human Feedback Integration & Preference Collection:**
**Regression & Drift Detection:**
**Continuous Improvement Loop:**

### 8. Risk Register

| Risk ID | Description | Likelihood | Impact | Mitigation | Owner |
|---------|-------------|------------|--------|------------|-------|

### 9. Cost & Performance Model
**Steady-State Estimate (per task):**
**Worst-Case / Retry Storm Estimate:**
**Scaling Levers & Cost Controls:**

### 10. Phased Implementation & Rollout
**Phase 0 — Design, Simulation & Offline Eval** (duration & deliverables)
**Phase 1 — Core Happy Path with Human-in-the-Loop**
**Phase 2 — Expanded Autonomy + Shadow Mode**
**Phase 3 — Production Hardening, SLOs & Cost Optimization**
**Phase 4 — Evolution & New Capability Onboarding**

### 11. Governance, Versioning & Evolution
**Prompt / Graph / Tool Registry Strategy:**
**Model Upgrade Process:**
**How New Agents or Topologies Are Introduced Safely:**

### 12. Appendices
- Glossary of terms
- Key references and patterns
- Open questions & decisions deferred to implementation team

---
This template guarantees every blueprint is reviewable, implementable in multiple frameworks, and production-ready.