maestro-flow 0.4.9 → 0.4.11

package/.agy/skills/team-lifecycle-v4/specs/knowledge-transfer.md

@@ -0,0 +1,114 @@
+# Knowledge Transfer Protocols
+
+## 1. Transfer Channels
+
+| Channel | Method | Producer | Consumer |
+|---------|--------|----------|----------|
+| Artifacts | Files in `<session>/artifacts/` | Task executor | Next task in pipeline |
+| State Updates | `team_msg(type="state_update")` | Task executor | Coordinator + downstream |
+| Wisdom | Append to `<session>/wisdom/*.md` | Any role | All roles |
+| Context Accumulator | In-memory aggregation | Inner loop only | Current task |
+| Exploration Cache | `<session>/explorations/` | Analyst / researcher | All roles |
+
+## 2. Context Loading Protocol (Before Task Execution)
+
+Every role MUST load context in this order before starting work.
+
+| Step | Action | Required |
+|------|--------|----------|
+| 1 | `team_msg(operation="get_state", role=<upstream>)` | Yes |
+| 2 | Read artifact files from upstream state's `ref` paths | Yes |
+| 3 | Read `<session>/wisdom/*.md` if exists | Yes |
+| 4 | Check `<session>/explorations/cache-index.json` before new exploration | If exploring |
+
+**Loading rules**:
+- Never skip step 1 -- state contains key decisions and findings
+- If `ref` path in state does not exist, log warning and continue
+- Wisdom files are append-only -- read all entries, newest last
+
+## 3. Context Publishing Protocol (After Task Completion)
+
+| Step | Action | Required |
+|------|--------|----------|
+| 1 | Write deliverable to `<session>/artifacts/<task-id>-<name>.md` | Yes |
+| 2 | Send `team_msg(type="state_update")` with payload (see schema below) | Yes |
+| 3 | Append wisdom entries for learnings, decisions, issues found | If applicable |
+
+## 4. State Update Schema
+
+Sent via `team_msg(type="state_update")` on task completion.
+
+```json
+{
+  "status": "task_complete",
+  "task_id": "<TASK-NNN>",
+  "ref": "<session>/artifacts/<filename>",
+  "key_findings": [
+    "Finding 1",
+    "Finding 2"
+  ],
+  "decisions": [
+    "Decision with rationale"
+  ],
+  "files_modified": [
+    "path/to/file.ts"
+  ],
+  "verification": "self-validated | peer-reviewed | tested",
+  "tech_profile": "<optional, from Phase 2-4 if codebase signals detected>"
+}
+```
+
+**Field rules**:
+- `ref`: Always an artifact path, never inline content
+- `key_findings`: Max 5 items, each under 100 chars
+- `decisions`: Include rationale, not just the choice
+- `files_modified`: Only for implementation tasks
+- `verification`: One of `self-validated`, `peer-reviewed`, `tested`
+- `tech_profile`: Optional. Codebase signals for context-aware specialist injection. Schema: `{ signals: string[], evidence: { signal: filePaths[] }, confidence: "high|medium|low" }`
+
+**Supervisor-specific extensions** (CHECKPOINT tasks only):
+
+```json
+{
+  "supervision_verdict": "pass | warn | block",
+  "supervision_score": 0.85,
+  "risks_logged": 0,
+  "blocks_detected": 0
+}
+```
+
+- `supervision_verdict`: Required for CHECKPOINT tasks. Determines pipeline progression.
+- `supervision_score`: Float 0.0-1.0. Aggregate of individual check scores.
+- `risks_logged`: Count of risks written to wisdom/issues.md.
+- `blocks_detected`: Count of blocking issues found. >0 implies verdict=block.
+
+## 5. Exploration Cache Protocol
+
+Prevents redundant research across tasks and discussion rounds.
+
+| Step | Action |
+|------|--------|
+| 1 | Read `<session>/explorations/cache-index.json` |
+| 2 | If angle already explored, read cached result from `explore-<angle>.json` |
+| 3 | If not cached, perform exploration |
+| 4 | Write result to `<session>/explorations/explore-<angle>.json` |
+| 5 | Update `cache-index.json` with new entry |
+
+**cache-index.json format**:
+```json
+{
+  "entries": [
+    {
+      "angle": "competitor-analysis",
+      "file": "explore-competitor-analysis.json",
+      "created_by": "RESEARCH-001",
+      "timestamp": "2026-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+**Rules**:
+- Cache key is the exploration `angle` (normalized to kebab-case)
+- Cache entries never expire within a session
+- Any role can read cached explorations; only the creator updates them

package/.agy/skills/team-lifecycle-v4/specs/pipelines.md

@@ -0,0 +1,140 @@
+# Pipeline Definitions
+
+## 1. Pipeline Selection Criteria
+
+| Keywords | Pipeline |
+|----------|----------|
+| spec, design, document, requirements | `spec-only` |
+| implement, build, fix, code | `impl-only` |
+| full, lifecycle, end-to-end | `full-lifecycle` |
+| frontend, UI, react, vue | `fe-only` or `fullstack` |
+| Ambiguous / unclear | ask_question |
+
+## 2. Spec-Only Pipeline
+
+**6 tasks + 2 optional checkpoints, 3 discussion rounds**
+
+```
+RESEARCH-001(+D1) -> DRAFT-001 -> DRAFT-002(+D2) -> [CHECKPOINT-001] -> DRAFT-003 -> DRAFT-004 -> [CHECKPOINT-002] -> QUALITY-001(+D3)
+```
+
+| Task | Role | Description | Discuss |
+|------|------|-------------|---------|
+| RESEARCH-001 | analyst | Research domain, competitors, constraints | D1: scope alignment |
+| DRAFT-001 | writer | Product brief, self-validate | - |
+| DRAFT-002 | writer | Requirements PRD | D2: requirements review |
+| CHECKPOINT-001 | supervisor | Brief↔PRD consistency, terminology alignment | - |
+| DRAFT-003 | writer | Architecture design, self-validate | - |
+| DRAFT-004 | writer | Epics & stories, self-validate | - |
+| CHECKPOINT-002 | supervisor | Full spec consistency (4 docs), quality trend | - |
+| QUALITY-001 | reviewer | Quality gate scoring | D3: readiness decision |
+
+**Checkpoint**: After QUALITY-001 -- pause for user approval before any implementation.
+
+**Supervision opt-out**: Set `supervision: false` in team-session.json to skip CHECKPOINT tasks.
+
+## 3. Impl-Only Pipeline
+
+**4 tasks + 1 optional checkpoint, 0 discussion rounds**
+
+```
+PLAN-001 -> [CHECKPOINT-003] -> IMPL-001 -> TEST-001 + REVIEW-001
+```
+
+| Task | Role | Description |
+|------|------|-------------|
+| PLAN-001 | planner | Break down into implementation steps, assess complexity |
+| CHECKPOINT-003 | supervisor | Plan↔input alignment, complexity sanity check |
+| IMPL-001 | implementer | Execute implementation plan |
+| TEST-001 | tester | Validate against acceptance criteria |
+| REVIEW-001 | reviewer | Code review |
+
+TEST-001 and REVIEW-001 run in parallel after IMPL-001 completes.
+
+**Supervision opt-out**: Set `supervision: false` in team-session.json to skip CHECKPOINT tasks.
+
+## 4. Full-Lifecycle Pipeline
+
+**10 tasks + 3 optional checkpoints = spec-only (6+2) + impl (4+1)**
+
+```
+[Spec pipeline with CHECKPOINT-001/002] -> PLAN-001(blockedBy: QUALITY-001) -> [CHECKPOINT-003] -> IMPL-001 -> TEST-001 + REVIEW-001
+```
+
+PLAN-001 is blocked until QUALITY-001 passes and user approves the checkpoint.
+
+**Supervision opt-out**: Set `supervision: false` in team-session.json to skip all CHECKPOINT tasks.
+
+## 5. Frontend Pipelines
+
+| Pipeline | Description |
+|----------|-------------|
+| `fe-only` | Frontend implementation only: PLAN-001 -> IMPL-001 (fe-implementer) -> TEST-001 + REVIEW-001 |
+| `fullstack` | Backend + frontend: PLAN-001 -> IMPL-001 (backend) + IMPL-002 (frontend) -> TEST-001 + REVIEW-001 |
+| `full-lifecycle-fe` | Full spec pipeline -> fullstack impl pipeline |
+
+## 6. Conditional Routing
+
+PLAN-001 outputs a complexity assessment that determines the impl topology.
+
+| Complexity | Modules | Route |
+|------------|---------|-------|
+| Low | 1-2 | PLAN-001 -> IMPL-001 -> TEST + REVIEW |
+| Medium | 3-4 | PLAN-001 -> ORCH-001 -> IMPL-{1..N} (parallel) -> TEST + REVIEW |
+| High | 5+ | PLAN-001 -> ARCH-001 -> ORCH-001 -> IMPL-{1..N} -> TEST + REVIEW |
+
+- **ORCH-001** (orchestrator): Coordinates parallel IMPL tasks, manages dependencies
+- **ARCH-001** (architect): Detailed architecture decisions before orchestration
+
+## 7. Task Metadata Registry
+
+| Task ID | Role | Phase | Depends On | Discuss | Priority |
+|---------|------|-------|------------|---------|----------|
+| RESEARCH-001 | analyst | research | - | D1 | P0 |
+| DRAFT-001 | writer | product-brief | RESEARCH-001 | - | P0 |
+| DRAFT-002 | writer | requirements | DRAFT-001 | D2 | P0 |
+| DRAFT-003 | writer | architecture | DRAFT-002 | - | P0 |
+| DRAFT-004 | writer | epics | DRAFT-003 | - | P0 |
+| QUALITY-001 | reviewer | readiness | CHECKPOINT-002 (or DRAFT-004) | D3 | P0 |
+| CHECKPOINT-001 | supervisor | checkpoint | DRAFT-002 | - | P1 |
+| CHECKPOINT-002 | supervisor | checkpoint | DRAFT-004 | - | P1 |
+| CHECKPOINT-003 | supervisor | checkpoint | PLAN-001 | - | P1 |
+| PLAN-001 | planner | planning | QUALITY-001 (or user input) | - | P0 |
+| ARCH-001 | architect | arch-detail | PLAN-001 | - | P1 |
+| ORCH-001 | orchestrator | orchestration | PLAN-001 or ARCH-001 | - | P1 |
+| IMPL-001 | implementer | implementation | PLAN-001 or ORCH-001 | - | P0 |
+| IMPL-{N} | implementer | implementation | ORCH-001 | - | P0 |
+| TEST-001 | tester | validation | IMPL-* | - | P0 |
+| REVIEW-001 | reviewer | review | IMPL-* | - | P0 |
+
+## 8. Context-Aware Specialist Injection
+
+Specialists are injected based on **codebase signals** detected by explorer/analyst/planner workers, not keyword matching. The coordinator evaluates signals emitted in worker state updates against a trigger matrix to determine when specialist roles are needed.
+
+### Signal Flow
+
+```
+analyst (RESEARCH-001) emits tech_profile in state_update
+  → coordinator evaluateSpecialistInjection (in handleCallback)
+  → signal combination matches trigger matrix
+  → P0: TaskCreate blocking downstream | P1: TaskCreate parallel with REVIEW/TEST
+```
+
+### Common Trigger Examples
+
+| Signal Combination | Specialist | Priority |
+|-------------------|-----------|----------|
+| `sql_detected` + `auth_detected` | security-expert (SECURITY-*) | P0 |
+| `perf_sensitive` + `scaling_concern` | performance-optimizer (PERF-*) | P0 |
+| `ml_detected` | ml-engineer (ML-*) | P0 |
+| `data_migration` | data-engineer (DATA-*) | P0 |
+| `devops_detected` + CI config changes | devops-engineer (DEVOPS-*) | P1 |
+
+
+
+### Injection Rules
+
+- Specialist tasks inherit session context and wisdom
+- They publish state_update on completion like any other task
+- P0 specialists block downstream tasks; P1 run in parallel
+- Same specialist is only injected once per session (dedup)

package/.agy/skills/team-lifecycle-v4/specs/quality-gates.md

@@ -0,0 +1,130 @@
+# Quality Gates
+
+## 1. Quality Thresholds
+
+| Result | Score | Action |
+|--------|-------|--------|
+| Pass | >= 80% | Proceed to next phase |
+| Review | 60-79% | Revise flagged items, re-evaluate |
+| Fail | < 60% | Return to producer for rework |
+
+## 2. Scoring Dimensions
+
+| Dimension | Weight | Criteria |
+|-----------|--------|----------|
+| Completeness | 25% | All required sections present with substantive content |
+| Consistency | 25% | Terminology, formatting, cross-references are uniform |
+| Traceability | 25% | Clear chain: Goals -> Requirements -> Architecture -> Stories |
+| Depth | 25% | ACs are testable, ADRs justified, stories estimable |
+
+**Score** = weighted average of all dimensions (0-100 per dimension).
+
+## 3. Per-Phase Quality Gates
+
+### Phase 2: Product Brief
+
+| Check | Pass Criteria |
+|-------|---------------|
+| Vision statement | Clear, one-paragraph, measurable outcome |
+| Problem definition | Specific pain points with evidence |
+| Target users | Defined personas or segments |
+| Success goals | Quantifiable metrics (KPIs) |
+| Success metrics | Measurement method specified |
+
+### Phase 3: Requirements PRD
+
+| Check | Pass Criteria |
+|-------|---------------|
+| Functional requirements | Each has unique ID (FR-NNN) |
+| Acceptance criteria | Testable given/when/then format |
+| Prioritization | MoSCoW applied to all requirements |
+| User stories | Format: As a [role], I want [goal], so that [benefit] |
+| Non-functional reqs | Performance, security, scalability addressed |
+
+### Phase 4: Architecture
+
+| Check | Pass Criteria |
+|-------|---------------|
+| Component diagram | All major components identified with boundaries |
+| Tech stack | Each choice justified against alternatives |
+| ADRs | At least 1 ADR per major decision, with status |
+| Data model | Entities, relationships, key fields defined |
+| Integration points | APIs, protocols, data formats specified |
+
+### Phase 5: Epics & Stories
+
+| Check | Pass Criteria |
+|-------|---------------|
+| Epic count | 2-8 epics (too few = too broad, too many = too granular) |
+| MVP subset | Clearly marked MVP epics/stories |
+| Stories per epic | 3-12 stories each |
+| Story format | Title, description, ACs, estimate present |
+
+### Phase 6: Readiness Gate
+
+| Check | Pass Criteria |
+|-------|---------------|
+| All docs exist | Brief, PRD, Architecture, Epics all present |
+| Cross-refs valid | All document references resolve correctly |
+| Overall score | >= 60% across all dimensions |
+| No P0 issues | Zero Error-class issues outstanding |
+
+## 4. Cross-Document Validation
+
+| Source | Target | Validation |
+|--------|--------|------------|
+| Brief goals | PRD requirements | Every goal has >= 1 requirement |
+| PRD requirements | Architecture components | Every requirement maps to a component |
+| PRD requirements | Epic stories | Every requirement covered by >= 1 story |
+| Architecture components | Epic stories | Every component has implementation stories |
+| Brief success metrics | Epic ACs | Metrics traceable to acceptance criteria |
+
+## 5. Code Review Dimensions
+
+For REVIEW-* tasks during implementation phases.
+
+### Quality
+
+| Check | Severity |
+|-------|----------|
+| Empty catch blocks | Error |
+| `as any` type casts | Warning |
+| `@ts-ignore` / `@ts-expect-error` | Warning |
+| `console.log` in production code | Warning |
+| Unused imports/variables | Info |
+
+### Security
+
+| Check | Severity |
+|-------|----------|
+| Hardcoded secrets/credentials | Error |
+| SQL injection vectors | Error |
+| `eval()` or `Function()` usage | Error |
+| `innerHTML` assignment | Warning |
+| Missing input validation | Warning |
+
+### Architecture
+
+| Check | Severity |
+|-------|----------|
+| Circular dependencies | Error |
+| Deep cross-boundary imports (3+ levels) | Warning |
+| Files > 500 lines | Warning |
+| Functions > 50 lines | Info |
+
+### Requirements Coverage
+
+| Check | Severity |
+|-------|----------|
+| Core functionality implemented | Error if missing |
+| Acceptance criteria covered | Error if missing |
+| Edge cases handled | Warning |
+| Error states handled | Warning |
+
+## 6. Issue Classification
+
+| Class | Label | Action |
+|-------|-------|--------|
+| Error | Must fix | Blocks progression, must resolve before proceeding |
+| Warning | Should fix | Should resolve, can proceed with justification |
+| Info | Nice to have | Optional improvement, log for future |

package/.agy/skills/team-lifecycle-v4/templates/architecture.md

@@ -0,0 +1,254 @@
+# Architecture Document Template (Directory Structure)
+
+Template for generating architecture decision documents as a directory of individual ADR files in Phase 4.
+
+## Usage Context
+
+| Phase | Usage |
+|-------|-------|
+| Phase 4 (Architecture) | Generate `architecture/` directory from requirements analysis |
+| Output Location | `{workDir}/architecture/` |
+
+## Output Structure
+
+```
+{workDir}/architecture/
+├── _index.md                      # Overview, components, tech stack, data model, security
+├── ADR-001-{slug}.md              # Individual Architecture Decision Record
+├── ADR-002-{slug}.md
+└── ...
+```
+
+---
+
+## Template: _index.md
+
+```markdown
+---
+session_id: {session_id}
+phase: 4
+document_type: architecture-index
+status: draft
+generated_at: {timestamp}
+version: 1
+dependencies:
+  - ../spec-config.json
+  - ../product-brief.md
+  - ../requirements/_index.md
+---
+
+# Architecture: {product_name}
+
+{executive_summary - high-level architecture approach and key decisions}
+
+## System Overview
+
+### Architecture Style
+{description of chosen architecture style: microservices, monolith, serverless, etc.}
+
+### System Context Diagram
+
+```mermaid
+C4Context
+    title System Context Diagram
+    Person(user, "User", "Primary user")
+    System(system, "{product_name}", "Core system")
+    System_Ext(ext1, "{external_system}", "{description}")
+    Rel(user, system, "Uses")
+    Rel(system, ext1, "Integrates with")
+```
+
+## Component Architecture
+
+### Component Diagram
+
+```mermaid
+graph TD
+    subgraph "{product_name}"
+        A[Component A] --> B[Component B]
+        B --> C[Component C]
+        A --> D[Component D]
+    end
+    B --> E[External Service]
+```
+
+### Component Descriptions
+
+| Component | Responsibility | Technology | Dependencies |
+|-----------|---------------|------------|--------------|
+| {component_name} | {what it does} | {tech stack} | {depends on} |
+
+## Technology Stack
+
+### Core Technologies
+
+| Layer | Technology | Version | Rationale |
+|-------|-----------|---------|-----------|
+| Frontend | {technology} | {version} | {why chosen} |
+| Backend | {technology} | {version} | {why chosen} |
+| Database | {technology} | {version} | {why chosen} |
+| Infrastructure | {technology} | {version} | {why chosen} |
+
+### Key Libraries & Frameworks
+
+| Library | Purpose | License |
+|---------|---------|---------|
+| {library_name} | {purpose} | {license} |
+
+## Architecture Decision Records
+
+| ADR | Title | Status | Key Choice |
+|-----|-------|--------|------------|
+| [ADR-001](ADR-001-{slug}.md) | {title} | Accepted | {one-line summary} |
+| [ADR-002](ADR-002-{slug}.md) | {title} | Accepted | {one-line summary} |
+| [ADR-003](ADR-003-{slug}.md) | {title} | Proposed | {one-line summary} |
+
+## Data Architecture
+
+### Data Model
+
+```mermaid
+erDiagram
+    ENTITY_A ||--o{ ENTITY_B : "has many"
+    ENTITY_A {
+        string id PK
+        string name
+        datetime created_at
+    }
+    ENTITY_B {
+        string id PK
+        string entity_a_id FK
+        string value
+    }
+```
+
+### Data Storage Strategy
+
+| Data Type | Storage | Retention | Backup |
+|-----------|---------|-----------|--------|
+| {type} | {storage solution} | {retention policy} | {backup strategy} |
+
+## API Design
+
+### API Overview
+
+| Endpoint | Method | Purpose | Auth |
+|----------|--------|---------|------|
+| {/api/resource} | {GET/POST/etc} | {purpose} | {auth type} |
+
+## Security Architecture
+
+### Security Controls
+
+| Control | Implementation | Requirement |
+|---------|---------------|-------------|
+| Authentication | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) |
+| Authorization | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) |
+| Data Protection | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) |
+
+## Infrastructure & Deployment
+
+### Deployment Architecture
+
+{description of deployment model: containers, serverless, VMs, etc.}
+
+### Environment Strategy
+
+| Environment | Purpose | Configuration |
+|-------------|---------|---------------|
+| Development | Local development | {config} |
+| Staging | Pre-production testing | {config} |
+| Production | Live system | {config} |
+
+## Codebase Integration
+
+{if has_codebase is true:}
+
+### Existing Code Mapping
+
+| New Component | Existing Module | Integration Type | Notes |
+|--------------|----------------|------------------|-------|
+| {component} | {existing module path} | Extend/Replace/New | {notes} |
+
+### Migration Notes
+{any migration considerations for existing code}
+
+## Quality Attributes
+
+| Attribute | Target | Measurement | ADR Reference |
+|-----------|--------|-------------|---------------|
+| Performance | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) |
+| Scalability | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) |
+| Reliability | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) |
+
+## Risks & Mitigations
+
+| Risk | Impact | Probability | Mitigation |
+|------|--------|-------------|------------|
+| {risk} | High/Medium/Low | High/Medium/Low | {mitigation approach} |
+
+## Open Questions
+
+- [ ] {architectural question 1}
+- [ ] {architectural question 2}
+
+## References
+
+- Derived from: [Requirements](../requirements/_index.md), [Product Brief](../product-brief.md)
+- Next: [Epics & Stories](../epics/_index.md)
+```
+
+---
+
+## Template: ADR-NNN-{slug}.md (Individual Architecture Decision Record)
+
+```markdown
+---
+id: ADR-{NNN}
+status: Accepted
+traces_to: [{REQ-NNN}, {NFR-X-NNN}]
+date: {timestamp}
+---
+
+# ADR-{NNN}: {decision_title}
+
+## Context
+
+{what is the situation that motivates this decision}
+
+## Decision
+
+{what is the chosen approach}
+
+## Alternatives Considered
+
+| Option | Pros | Cons |
+|--------|------|------|
+| {option_1 - chosen} | {pros} | {cons} |
+| {option_2} | {pros} | {cons} |
+| {option_3} | {pros} | {cons} |
+
+## Consequences
+
+- **Positive**: {positive outcomes}
+- **Negative**: {tradeoffs accepted}
+- **Risks**: {risks to monitor}
+
+## Traces
+
+- **Requirements**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md), [NFR-X-{NNN}](../requirements/NFR-X-{NNN}-{slug}.md)
+- **Implemented by**: [EPIC-{NNN}](../epics/EPIC-{NNN}-{slug}.md) (added in Phase 5)
+```
+
+---
+
+## Variable Descriptions
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `{session_id}` | spec-config.json | Session identifier |
+| `{timestamp}` | Runtime | ISO8601 generation timestamp |
+| `{product_name}` | product-brief.md | Product/feature name |
+| `{NNN}` | Auto-increment | ADR/requirement number |
+| `{slug}` | Auto-generated | Kebab-case from decision title |
+| `{has_codebase}` | spec-config.json | Whether existing codebase exists |