maestro-flow 0.4.9 → 0.4.11

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

@@ -0,0 +1,196 @@
+# Epics & Stories Template (Directory Structure)
+
+Template for generating epic/story breakdown as a directory of individual Epic files in Phase 5.
+
+## Usage Context
+
+| Phase | Usage |
+|-------|-------|
+| Phase 5 (Epics & Stories) | Generate `epics/` directory from requirements decomposition |
+| Output Location | `{workDir}/epics/` |
+
+## Output Structure
+
+```
+{workDir}/epics/
+├── _index.md                      # Overview table + dependency map + MVP scope + execution order
+├── EPIC-001-{slug}.md             # Individual Epic with its Stories
+├── EPIC-002-{slug}.md
+└── ...
+```
+
+---
+
+## Template: _index.md
+
+```markdown
+---
+session_id: {session_id}
+phase: 5
+document_type: epics-index
+status: draft
+generated_at: {timestamp}
+version: 1
+dependencies:
+  - ../spec-config.json
+  - ../product-brief.md
+  - ../requirements/_index.md
+  - ../architecture/_index.md
+---
+
+# Epics & Stories: {product_name}
+
+{executive_summary - overview of epic structure and MVP scope}
+
+## Epic Overview
+
+| Epic ID | Title | Priority | MVP | Stories | Est. Size |
+|---------|-------|----------|-----|---------|-----------|
+| [EPIC-001](EPIC-001-{slug}.md) | {title} | Must | Yes | {n} | {S/M/L/XL} |
+| [EPIC-002](EPIC-002-{slug}.md) | {title} | Must | Yes | {n} | {S/M/L/XL} |
+| [EPIC-003](EPIC-003-{slug}.md) | {title} | Should | No | {n} | {S/M/L/XL} |
+
+## Dependency Map
+
+```mermaid
+graph LR
+    EPIC-001 --> EPIC-002
+    EPIC-001 --> EPIC-003
+    EPIC-002 --> EPIC-004
+    EPIC-003 --> EPIC-005
+```
+
+### Dependency Notes
+{explanation of why these dependencies exist and suggested execution order}
+
+### Recommended Execution Order
+1. [EPIC-{NNN}](EPIC-{NNN}-{slug}.md): {reason - foundational}
+2. [EPIC-{NNN}](EPIC-{NNN}-{slug}.md): {reason - depends on #1}
+3. ...
+
+## MVP Scope
+
+### MVP Epics
+{list of epics included in MVP with justification, linking to each}
+
+### MVP Definition of Done
+- [ ] {MVP completion criterion 1}
+- [ ] {MVP completion criterion 2}
+- [ ] {MVP completion criterion 3}
+
+## Traceability Matrix
+
+| Requirement | Epic | Stories | Architecture |
+|-------------|------|---------|--------------|
+| [REQ-001](../requirements/REQ-001-{slug}.md) | [EPIC-001](EPIC-001-{slug}.md) | STORY-001-001, STORY-001-002 | [ADR-001](../architecture/ADR-001-{slug}.md) |
+| [REQ-002](../requirements/REQ-002-{slug}.md) | [EPIC-001](EPIC-001-{slug}.md) | STORY-001-003 | Component B |
+| [REQ-003](../requirements/REQ-003-{slug}.md) | [EPIC-002](EPIC-002-{slug}.md) | STORY-002-001 | [ADR-002](../architecture/ADR-002-{slug}.md) |
+
+## Estimation Summary
+
+| Size | Meaning | Count |
+|------|---------|-------|
+| S | Small - well-understood, minimal risk | {n} |
+| M | Medium - some complexity, moderate risk | {n} |
+| L | Large - significant complexity, should consider splitting | {n} |
+| XL | Extra Large - high complexity, must split before implementation | {n} |
+
+## Risks & Considerations
+
+| Risk | Affected Epics | Mitigation |
+|------|---------------|------------|
+| {risk description} | [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) | {mitigation} |
+
+## Open Questions
+
+- [ ] {question about scope or implementation 1}
+- [ ] {question about scope or implementation 2}
+
+## References
+
+- Derived from: [Requirements](../requirements/_index.md), [Architecture](../architecture/_index.md)
+- Handoff to: execution workflows (lite-plan, plan, req-plan)
+```
+
+---
+
+## Template: EPIC-NNN-{slug}.md (Individual Epic)
+
+```markdown
+---
+id: EPIC-{NNN}
+priority: {Must|Should|Could}
+mvp: {true|false}
+size: {S|M|L|XL}
+requirements: [REQ-{NNN}]
+architecture: [ADR-{NNN}]
+dependencies: [EPIC-{NNN}]
+status: draft
+---
+
+# EPIC-{NNN}: {epic_title}
+
+**Priority**: {Must|Should|Could}
+**MVP**: {Yes|No}
+**Estimated Size**: {S|M|L|XL}
+
+## Description
+
+{detailed epic description}
+
+## Requirements
+
+- [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md): {title}
+- [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md): {title}
+
+## Architecture
+
+- [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md): {title}
+- Component: {component_name}
+
+## Dependencies
+
+- [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) (blocking): {reason}
+- [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) (soft): {reason}
+
+## Stories
+
+### STORY-{EPIC}-001: {story_title}
+
+**User Story**: As a {persona}, I want to {action} so that {benefit}.
+
+**Acceptance Criteria**:
+- [ ] {criterion 1}
+- [ ] {criterion 2}
+- [ ] {criterion 3}
+
+**Size**: {S|M|L|XL}
+**Traces to**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md)
+
+---
+
+### STORY-{EPIC}-002: {story_title}
+
+**User Story**: As a {persona}, I want to {action} so that {benefit}.
+
+**Acceptance Criteria**:
+- [ ] {criterion 1}
+- [ ] {criterion 2}
+
+**Size**: {S|M|L|XL}
+**Traces to**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md)
+```
+
+---
+
+## 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 |
+| `{EPIC}` | Auto-increment | Epic number (3 digits) |
+| `{NNN}` | Auto-increment | Story/requirement number |
+| `{slug}` | Auto-generated | Kebab-case from epic/story title |
+| `{S\|M\|L\|XL}` | CLI analysis | Relative size estimate |

package/.agy/skills/team-lifecycle-v4/templates/product-brief.md

@@ -0,0 +1,133 @@
+# Product Brief Template
+
+Template for generating product brief documents in Phase 2.
+
+## Usage Context
+
+| Phase | Usage |
+|-------|-------|
+| Phase 2 (Product Brief) | Generate product-brief.md from multi-CLI analysis |
+| Output Location | `{workDir}/product-brief.md` |
+
+---
+
+## Template
+
+```markdown
+---
+session_id: {session_id}
+phase: 2
+document_type: product-brief
+status: draft
+generated_at: {timestamp}
+stepsCompleted: []
+version: 1
+dependencies:
+  - spec-config.json
+---
+
+# Product Brief: {product_name}
+
+{executive_summary - 2-3 sentences capturing the essence of the product/feature}
+
+## Vision
+
+{vision_statement - clear, aspirational 1-3 sentence statement of what success looks like}
+
+## Problem Statement
+
+### Current Situation
+{description of the current state and pain points}
+
+### Impact
+{quantified impact of the problem - who is affected, how much, how often}
+
+## Target Users
+
+{for each user persona:}
+
+### {Persona Name}
+- **Role**: {user's role/context}
+- **Needs**: {primary needs related to this product}
+- **Pain Points**: {current frustrations}
+- **Success Criteria**: {what success looks like for this user}
+
+## Goals & Success Metrics
+
+| Goal ID | Goal | Success Metric | Target |
+|---------|------|----------------|--------|
+| G-001 | {goal description} | {measurable metric} | {specific target} |
+| G-002 | {goal description} | {measurable metric} | {specific target} |
+
+## Scope
+
+### In Scope
+- {feature/capability 1}
+- {feature/capability 2}
+- {feature/capability 3}
+
+### Out of Scope
+- {explicitly excluded item 1}
+- {explicitly excluded item 2}
+
+### Assumptions
+- {key assumption 1}
+- {key assumption 2}
+
+## Competitive Landscape
+
+| Aspect | Current State | Proposed Solution | Advantage |
+|--------|--------------|-------------------|-----------|
+| {aspect} | {how it's done now} | {our approach} | {differentiator} |
+
+## Constraints & Dependencies
+
+### Technical Constraints
+- {constraint 1}
+- {constraint 2}
+
+### Business Constraints
+- {constraint 1}
+
+### Dependencies
+- {external dependency 1}
+- {external dependency 2}
+
+## Multi-Perspective Synthesis
+
+### Product Perspective
+{summary of product/market analysis findings}
+
+### Technical Perspective
+{summary of technical feasibility and constraints}
+
+### User Perspective
+{summary of user journey and UX considerations}
+
+### Convergent Themes
+{themes where all perspectives agree}
+
+### Conflicting Views
+{areas where perspectives differ, with notes on resolution approach}
+
+## Open Questions
+
+- [ ] {unresolved question 1}
+- [ ] {unresolved question 2}
+
+## References
+
+- Derived from: [spec-config.json](spec-config.json)
+- Next: [Requirements PRD](requirements.md)
+```
+
+## Variable Descriptions
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `{session_id}` | spec-config.json | Session identifier |
+| `{timestamp}` | Runtime | ISO8601 generation timestamp |
+| `{product_name}` | Seed analysis | Product/feature name |
+| `{executive_summary}` | CLI synthesis | 2-3 sentence summary |
+| `{vision_statement}` | CLI product perspective | Aspirational vision |
+| All `{...}` fields | CLI analysis outputs | Filled from multi-perspective analysis |

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

@@ -0,0 +1,224 @@
+# Requirements PRD Template (Directory Structure)
+
+Template for generating Product Requirements Document as a directory of individual requirement files in Phase 3.
+
+## Usage Context
+
+| Phase | Usage |
+|-------|-------|
+| Phase 3 (Requirements) | Generate `requirements/` directory from product brief expansion |
+| Output Location | `{workDir}/requirements/` |
+
+## Output Structure
+
+```
+{workDir}/requirements/
+├── _index.md                      # Summary + MoSCoW table + traceability matrix + links
+├── REQ-001-{slug}.md              # Individual functional requirement
+├── REQ-002-{slug}.md
+├── NFR-P-001-{slug}.md            # Non-functional: Performance
+├── NFR-S-001-{slug}.md            # Non-functional: Security
+├── NFR-SC-001-{slug}.md           # Non-functional: Scalability
+├── NFR-U-001-{slug}.md            # Non-functional: Usability
+└── ...
+```
+
+---
+
+## Template: _index.md
+
+```markdown
+---
+session_id: {session_id}
+phase: 3
+document_type: requirements-index
+status: draft
+generated_at: {timestamp}
+version: 1
+dependencies:
+  - ../spec-config.json
+  - ../product-brief.md
+---
+
+# Requirements: {product_name}
+
+{executive_summary - brief overview of what this PRD covers and key decisions}
+
+## Requirement Summary
+
+| Priority | Count | Coverage |
+|----------|-------|----------|
+| Must Have | {n} | {description of must-have scope} |
+| Should Have | {n} | {description of should-have scope} |
+| Could Have | {n} | {description of could-have scope} |
+| Won't Have | {n} | {description of explicitly excluded} |
+
+## Functional Requirements
+
+| ID | Title | Priority | Traces To |
+|----|-------|----------|-----------|
+| [REQ-001](REQ-001-{slug}.md) | {title} | Must | [G-001](../product-brief.md#goals--success-metrics) |
+| [REQ-002](REQ-002-{slug}.md) | {title} | Must | [G-001](../product-brief.md#goals--success-metrics) |
+| [REQ-003](REQ-003-{slug}.md) | {title} | Should | [G-002](../product-brief.md#goals--success-metrics) |
+
+## Non-Functional Requirements
+
+### Performance
+
+| ID | Title | Target |
+|----|-------|--------|
+| [NFR-P-001](NFR-P-001-{slug}.md) | {title} | {target value} |
+
+### Security
+
+| ID | Title | Standard |
+|----|-------|----------|
+| [NFR-S-001](NFR-S-001-{slug}.md) | {title} | {standard/framework} |
+
+### Scalability
+
+| ID | Title | Target |
+|----|-------|--------|
+| [NFR-SC-001](NFR-SC-001-{slug}.md) | {title} | {target value} |
+
+### Usability
+
+| ID | Title | Target |
+|----|-------|--------|
+| [NFR-U-001](NFR-U-001-{slug}.md) | {title} | {target value} |
+
+## Data Requirements
+
+### Data Entities
+
+| Entity | Description | Key Attributes |
+|--------|-------------|----------------|
+| {entity_name} | {description} | {attr1, attr2, attr3} |
+
+### Data Flows
+
+{description of key data flows, optionally with Mermaid diagram}
+
+## Integration Requirements
+
+| System | Direction | Protocol | Data Format | Notes |
+|--------|-----------|----------|-------------|-------|
+| {system_name} | Inbound/Outbound/Both | {REST/gRPC/etc} | {JSON/XML/etc} | {notes} |
+
+## Constraints & Assumptions
+
+### Constraints
+- {technical or business constraint 1}
+- {technical or business constraint 2}
+
+### Assumptions
+- {assumption 1 - must be validated}
+- {assumption 2 - must be validated}
+
+## Priority Rationale
+
+{explanation of MoSCoW prioritization decisions, especially for Should/Could boundaries}
+
+## Traceability Matrix
+
+| Goal | Requirements |
+|------|-------------|
+| G-001 | [REQ-001](REQ-001-{slug}.md), [REQ-002](REQ-002-{slug}.md), [NFR-P-001](NFR-P-001-{slug}.md) |
+| G-002 | [REQ-003](REQ-003-{slug}.md), [NFR-S-001](NFR-S-001-{slug}.md) |
+
+## Open Questions
+
+- [ ] {unresolved question 1}
+- [ ] {unresolved question 2}
+
+## References
+
+- Derived from: [Product Brief](../product-brief.md)
+- Next: [Architecture](../architecture/_index.md)
+```
+
+---
+
+## Template: REQ-NNN-{slug}.md (Individual Functional Requirement)
+
+```markdown
+---
+id: REQ-{NNN}
+type: functional
+priority: {Must|Should|Could|Won't}
+traces_to: [G-{NNN}]
+status: draft
+---
+
+# REQ-{NNN}: {requirement_title}
+
+**Priority**: {Must|Should|Could|Won't}
+
+## Description
+
+{detailed requirement description}
+
+## User Story
+
+As a {persona}, I want to {action} so that {benefit}.
+
+## Acceptance Criteria
+
+- [ ] {specific, testable criterion 1}
+- [ ] {specific, testable criterion 2}
+- [ ] {specific, testable criterion 3}
+
+## Traces
+
+- **Goal**: [G-{NNN}](../product-brief.md#goals--success-metrics)
+- **Architecture**: [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md) (if applicable)
+- **Implemented by**: [EPIC-{NNN}](../epics/EPIC-{NNN}-{slug}.md) (added in Phase 5)
+```
+
+---
+
+## Template: NFR-{type}-NNN-{slug}.md (Individual Non-Functional Requirement)
+
+```markdown
+---
+id: NFR-{type}-{NNN}
+type: non-functional
+category: {Performance|Security|Scalability|Usability}
+priority: {Must|Should|Could}
+status: draft
+---
+
+# NFR-{type}-{NNN}: {requirement_title}
+
+**Category**: {Performance|Security|Scalability|Usability}
+**Priority**: {Must|Should|Could}
+
+## Requirement
+
+{detailed requirement description}
+
+## Metric & Target
+
+| Metric | Target | Measurement Method |
+|--------|--------|--------------------|
+| {metric} | {target value} | {how measured} |
+
+## Traces
+
+- **Goal**: [G-{NNN}](../product-brief.md#goals--success-metrics)
+- **Architecture**: [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md) (if applicable)
+```
+
+---
+
+## 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 | Requirement number (zero-padded 3 digits) |
+| `{slug}` | Auto-generated | Kebab-case from requirement title |
+| `{type}` | Category | P (Performance), S (Security), SC (Scalability), U (Usability) |
+| `{Must\|Should\|Could\|Won't}` | User input / auto | MoSCoW priority tag |

package/.agy/skills/team-quality-assurance/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: team-quality-assurance
+description: Unified team skill for quality assurance. Full closed-loop QA combining issue discovery and software testing. Triggers on "team quality-assurance", "team qa".
+allowed-tools:
+  - ask_question
+  - define_subagent
+  - grep_search
+  - invoke_subagent
+  - manage_subagents
+  - replace_file_content
+  - run_command
+  - send_message
+  - view_file
+  - write_to_file
+agy-subagents:
+  - team-worker
+---
+
+## Sub-Agent Registration (Antigravity)
+
+Before any `invoke_subagent` call below, register each sub-agent type once per session by reading the system_prompt from `<agy-agents-dir>/<name>.md` and passing it to `define_subagent`. The `<agy-agents-dir>` is:
+- global install: `~/.gemini/antigravity-cli/agents/`
+- workspace install: `<project>/.agents/agents/`
+
+- `define_subagent(name="team-worker", description="<from agents/team-worker.md frontmatter>", system_prompt=<contents of agents/team-worker.md body>, enable_write_tools=true, enable_mcp_tools=true, enable_subagent_tools=false)`
+
+**ConversationId tracking**: `invoke_subagent` returns a ConversationId per spawned instance. Subsequent `send_message(Recipient=<ConversationId>, Message=...)` calls require that ConversationId — never use the role name as the recipient.
+
+---
+
+# Team Quality Assurance
+
+Orchestrate multi-agent QA: scout -> strategist -> generator -> executor -> analyst. Supports discovery, testing, and full closed-loop modes with parallel generation and GC loops.
+
+## Architecture
+
+```
+view_file(AbsolutePath="<agy-skills-dir>/team-quality-assurance/SKILL.md") + execute inline (args: "task description")
+                    |
+         SKILL.md (this file) = Router
+                    |
+     +--------------+--------------+
+     |                             |
+  no --role flag              --role <name>
+     |                             |
+  Coordinator                  Worker
+  roles/coordinator/role.md    roles/<name>/role.md
+     |
+     +-- analyze -> dispatch -> spawn workers -> STOP
+                                    |
+                    +-------+-------+-------+-------+-------+
+                    v       v       v       v       v
+                 [scout] [strat] [gen] [exec] [analyst]
+                 team-worker agents, each loads roles/<role>/role.md
+```
+
+## Role Registry
+
+| Role | Path | Prefix | Inner Loop |
+|------|------|--------|------------|
+| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
+| scout | [roles/scout/role.md](roles/scout/role.md) | SCOUT-* | false |
+| strategist | [roles/strategist/role.md](roles/strategist/role.md) | QASTRAT-* | false |
+| generator | [roles/generator/role.md](roles/generator/role.md) | QAGEN-* | false |
+| executor | [roles/executor/role.md](roles/executor/role.md) | QARUN-* | true |
+| analyst | [roles/analyst/role.md](roles/analyst/role.md) | QAANA-* | false |
+
+## Role Router
+
+Parse `$ARGUMENTS`:
+- Has `--role <name>` -> Read `roles/<name>/role.md`, execute Phase 2-4
+- No `--role` -> `@roles/coordinator/role.md`, execute entry router
+
+## Shared Constants
+
+- **Session prefix**: `QA`
+- **Session path**: `.workflow/.team/QA-<slug>-<date>/`
+- **Team name**: `quality-assurance`
+- **CLI tools**: `maestro delegate --mode analysis` (read-only), `maestro delegate --mode write` (modifications)
+- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
+
+## Worker Spawn Template
+
+Coordinator spawns workers using this template:
+
+```
+invoke_subagent([{ TypeName: "team-worker", Role: "<role>", Prompt: "<Prompt>", Workspace: "inherit" }])
+```
+
+## User Commands
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View pipeline status graph |
+| `resume` / `continue` | Advance to next step |
+| `--mode=discovery` | Force discovery mode |
+| `--mode=testing` | Force testing mode |
+| `--mode=full` | Force full QA mode |
+
+## Completion Action
+
+When pipeline completes, coordinator presents:
+
+```
+ask_question({
+  questions: [{
+    question: "Quality Assurance pipeline complete. What would you like to do?",
+    header: "Completion",
+    multiSelect: false,
+    options: [
+      { label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" },
+      { label: "Keep Active", description: "Keep session for follow-up work" },
+      { label: "Export Results", description: "Export deliverables to target directory" }
+    ]
+  }]
+})
+```
+
+## Session Directory
+
+```
+.workflow/.team/QA-<slug>-<date>/
+├── .msg/messages.jsonl     # Team message bus
+├── .msg/meta.json          # Session state + shared memory
+├── wisdom/                 # Cross-task knowledge
+├── scan/                   # Scout output
+├── strategy/               # Strategist output
+├── tests/                  # Generator output (L1/, L2/, L3/)
+├── results/                # Executor output
+└── analysis/               # Analyst output
+```
+
+## Specs Reference
+
+- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
+- [specs/team-config.json](specs/team-config.json) — Team configuration and shared memory schema
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Unknown --role value | Error with available role list |
+| Role not found | Error with expected path (roles/<name>/role.md) |
+| CLI tool fails | Worker fallback to direct implementation |
+| Scout finds no issues | Report clean scan, skip to testing mode |
+| GC loop exceeded | Accept current coverage with warning |
+| Fast-advance conflict | Coordinator reconciles on next callback |
+| Completion action fails | Default to Keep Active |