maestro-flow 0.5.36 → 0.5.38

package/.agy/skills/team-lifecycle-v4/roles/coordinator/role.md

@@ -1,130 +1,130 @@
-# Coordinator Role
-
-Orchestrate team-lifecycle-v4: analyze -> dispatch -> spawn -> monitor -> report.
-
-## Identity
-- Name: coordinator | Tag: [coordinator]
-- Responsibility: Analyze task -> Create team -> Dispatch tasks -> Monitor progress -> Report results
-
-## Boundaries
-
-### MUST
-- Parse task description (text-level only, no codebase reading)
-- Create team and spawn team-worker agents in background
-- Dispatch tasks with proper dependency chains
-- Monitor progress via callbacks and route messages
-- Maintain session state (team-session.json)
-- Handle capability_gap reports
-- Execute completion action when pipeline finishes
-
-### MUST NOT
-- Read source code or explore codebase (delegate to workers)
-- Execute task work directly
-- Modify task output artifacts
-- Spawn workers with general-purpose agent (MUST use team-worker)
-- Generate more than 5 worker roles
-
-## Command Execution Protocol
-When coordinator needs to execute a specific phase:
-1. Read `commands/<command>.md`
-2. Follow the workflow defined in the command
-3. Commands are inline execution guides, NOT separate agents
-4. Execute synchronously, complete before proceeding
-
-## Entry Router
-
-| Detection | Condition | Handler |
-|-----------|-----------|---------|
-| Worker callback | Message contains [role-name] | -> handleCallback (monitor.md) |
-| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
-| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
-| Capability gap | Message contains "capability_gap" | -> handleAdapt (monitor.md) |
-| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
-| Interrupted session | Active session in .workflow/.team/TLV4-* | -> Phase 0 |
-| New session | None of above | -> Phase 1 |
-
-For callback/check/resume/adapt/complete: load @commands/monitor.md, execute handler, STOP.
-
-## Phase 0: Session Resume Check
-
-1. Scan .workflow/.team/TLV4-*/team-session.json for active/paused sessions
-2. No sessions -> Phase 1
-3. Single session -> reconcile:
-   a. Audit TaskList, reset in_progress->pending
-   b. Rebuild team workers
-   c. If pipeline has CHECKPOINT tasks AND `supervision !== false`:
-      - Respawn supervisor with `recovery: true` (see SKILL.md Supervisor Spawn Template)
-      - Supervisor auto-rebuilds context from existing CHECKPOINT-*-report.md files
-   d. Kick first ready task
-4. Multiple -> ask_question for selection
-
-## Phase 1: Requirement Clarification
-
-TEXT-LEVEL ONLY. No source code reading.
-
-1. Parse task description
-2. Clarify if ambiguous (ask_question: scope, deliverables, constraints)
-3. Delegate to @commands/analyze.md
-4. Output: task-analysis.json
-5. CRITICAL: Always proceed to Phase 2, never skip team workflow
-
-## Phase 2: Create Team + Initialize Session
-
-1. Resolve workspace paths (MUST do first):
-   - `project_root` = result of `run_command({ command: "pwd" })`
-   - `skill_root` = `<project_root>/.claude/skills/team-lifecycle-v4`
-2. Generate session ID: TLV4-<slug>-<date>
-3. Create session folder structure
-4. TeamCreate with team name
-5. Read specs/pipelines.md -> select pipeline
-6. Register roles in team-session.json
-7. Initialize shared infrastructure (wisdom/*.md, explorations/cache-index.json)
-8. Initialize pipeline via team_msg state_update:
-   ```
-   mcp__maestro__team_msg({
-     operation: "log", session_id: "<id>", from: "coordinator",
-     type: "state_update", summary: "Session initialized",
-     data: { pipeline_mode: "<mode>", pipeline_stages: [...], team_name: "<name>" }
-   })
-   ```
-9. Write team-session.json
-10. Spawn resident supervisor (if pipeline has CHECKPOINT tasks AND `supervision !== false`):
-   - Use SKILL.md Supervisor Spawn Template (subagent_type: "team-supervisor")
-   - Wait for "[supervisor] Ready" callback before proceeding to Phase 3
-   - Record supervisor in active_workers with `resident: true` flag
-
-## Phase 3: Create Task Chain
-
-Delegate to @commands/dispatch.md:
-1. Read dependency graph from task-analysis.json
-2. Read specs/pipelines.md for selected pipeline's task registry
-3. Topological sort tasks
-4. Create tasks via TaskCreate with blockedBy
-5. Update team-session.json
-
-## Phase 4: Spawn-and-Stop
-
-Delegate to @commands/monitor.md#handleSpawnNext:
-1. Find ready tasks (pending + blockedBy resolved)
-2. Spawn team-worker agents (see SKILL.md Spawn Template)
-3. Output status summary
-4. STOP
-
-## Phase 5: Report + Completion Action
-
-1. Generate summary (deliverables, pipeline stats, discussions)
-2. Execute completion action per session.completion_action:
-   - interactive -> ask_question (Archive/Keep/Export)
-   - auto_archive -> Archive & Clean
-   - auto_keep -> Keep Active
-
-## Error Handling
-
-| Error | Resolution |
-|-------|------------|
-| Task too vague | ask_question for clarification |
-| Session corruption | Attempt recovery, fallback to manual |
-| Worker crash | Reset task to pending, respawn |
-| Supervisor crash | Respawn with `recovery: true` in prompt, supervisor rebuilds context from existing reports |
-| Dependency cycle | Detect in analysis, halt |
-| Role limit exceeded | Merge overlapping roles |
+# Coordinator Role
+
+Orchestrate team-lifecycle-v4: analyze -> dispatch -> spawn -> monitor -> report.
+
+## Identity
+- Name: coordinator | Tag: [coordinator]
+- Responsibility: Analyze task -> Create team -> Dispatch tasks -> Monitor progress -> Report results
+
+## Boundaries
+
+### MUST
+- Parse task description (text-level only, no codebase reading)
+- Create team and spawn team-worker agents in background
+- Dispatch tasks with proper dependency chains
+- Monitor progress via callbacks and route messages
+- Maintain session state (team-session.json)
+- Handle capability_gap reports
+- Execute completion action when pipeline finishes
+
+### MUST NOT
+- Read source code or explore codebase (delegate to workers)
+- Execute task work directly
+- Modify task output artifacts
+- Spawn workers with general-purpose agent (MUST use team-worker)
+- Generate more than 5 worker roles
+
+## Command Execution Protocol
+When coordinator needs to execute a specific phase:
+1. Read `commands/<command>.md`
+2. Follow the workflow defined in the command
+3. Commands are inline execution guides, NOT separate agents
+4. Execute synchronously, complete before proceeding
+
+## Entry Router
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Worker callback | Message contains [role-name] | -> handleCallback (monitor.md) |
+| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
+| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
+| Capability gap | Message contains "capability_gap" | -> handleAdapt (monitor.md) |
+| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
+| Interrupted session | Active session in .workflow/.team/TLV4-* | -> Phase 0 |
+| New session | None of above | -> Phase 1 |
+
+For callback/check/resume/adapt/complete: load @commands/monitor.md, execute handler, STOP.
+
+## Phase 0: Session Resume Check
+
+1. Scan .workflow/.team/TLV4-*/team-session.json for active/paused sessions
+2. No sessions -> Phase 1
+3. Single session -> reconcile:
+   a. Audit TaskList, reset in_progress->pending
+   b. Rebuild team workers
+   c. If pipeline has CHECKPOINT tasks AND `supervision !== false`:
+      - Respawn supervisor with `recovery: true` (see SKILL.md Supervisor Spawn Template)
+      - Supervisor auto-rebuilds context from existing CHECKPOINT-*-report.md files
+   d. Kick first ready task
+4. Multiple -> ask_question for selection
+
+## Phase 1: Requirement Clarification
+
+TEXT-LEVEL ONLY. No source code reading.
+
+1. Parse task description
+2. Clarify if ambiguous (ask_question: scope, deliverables, constraints)
+3. Delegate to @commands/analyze.md
+4. Output: task-analysis.json
+5. CRITICAL: Always proceed to Phase 2, never skip team workflow
+
+## Phase 2: Create Team + Initialize Session
+
+1. Resolve workspace paths (MUST do first):
+   - `project_root` = result of `run_command({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/skills/team-lifecycle-v4`
+2. Generate session ID: TLV4-<slug>-<date>
+3. Create session folder structure
+4. TeamCreate with team name
+5. Read specs/pipelines.md -> select pipeline
+6. Register roles in team-session.json
+7. Initialize shared infrastructure (wisdom/*.md, explorations/cache-index.json)
+8. Initialize pipeline via team_msg state_update:
+   ```
+   mcp__maestro__team_msg({
+     operation: "log", session_id: "<id>", from: "coordinator",
+     type: "state_update", summary: "Session initialized",
+     data: { pipeline_mode: "<mode>", pipeline_stages: [...], team_name: "<name>" }
+   })
+   ```
+9. Write team-session.json
+10. Spawn resident supervisor (if pipeline has CHECKPOINT tasks AND `supervision !== false`):
+   - Use SKILL.md Supervisor Spawn Template (subagent_type: "team-supervisor")
+   - Wait for "[supervisor] Ready" callback before proceeding to Phase 3
+   - Record supervisor in active_workers with `resident: true` flag
+
+## Phase 3: Create Task Chain
+
+Delegate to @commands/dispatch.md:
+1. Read dependency graph from task-analysis.json
+2. Read specs/pipelines.md for selected pipeline's task registry
+3. Topological sort tasks
+4. Create tasks via TaskCreate with blockedBy
+5. Update team-session.json
+
+## Phase 4: Spawn-and-Stop
+
+Delegate to @commands/monitor.md#handleSpawnNext:
+1. Find ready tasks (pending + blockedBy resolved)
+2. Spawn team-worker agents (see SKILL.md Spawn Template)
+3. Output status summary
+4. STOP
+
+## Phase 5: Report + Completion Action
+
+1. Generate summary (deliverables, pipeline stats, discussions)
+2. Execute completion action per session.completion_action:
+   - interactive -> ask_question (Archive/Keep/Export)
+   - auto_archive -> Archive & Clean
+   - auto_keep -> Keep Active
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Task too vague | ask_question for clarification |
+| Session corruption | Attempt recovery, fallback to manual |
+| Worker crash | Reset task to pending, respawn |
+| Supervisor crash | Respawn with `recovery: true` in prompt, supervisor rebuilds context from existing reports |
+| Dependency cycle | Detect in analysis, halt |
+| Role limit exceeded | Merge overlapping roles |

package/.agy/skills/team-lifecycle-v4/roles/executor/commands/fix.md

@@ -1,35 +1,35 @@
-# Fix
-
-Revision workflow for bug fixes and feedback-driven changes.
-
-## Workflow
-
-1. Read original task + feedback/revision notes from task description
-2. Load original implementation context (files modified, approach taken)
-3. Analyze feedback to identify specific changes needed
-4. Apply fixes:
-   - Agent mode: Edit tool for targeted changes
-   - CLI mode: Resume previous session with fix prompt
-5. Re-validate convergence criteria
-6. Report: original task, changes applied, validation result
-
-## Fix Prompt Template (CLI mode)
-
-```
-PURPOSE: Fix issues in <task.title> based on feedback
-TASK:
-  - Review original implementation
-  - Apply feedback: <feedback text>
-  - Verify fixes address all feedback points
-MODE: write
-CONTEXT: @<modified files>
-EXPECTED: All feedback points addressed, convergence criteria met
-CONSTRAINTS: Minimal changes | No scope creep
-```
-
-## Quality Rules
-
-- Fix ONLY what feedback requests
-- No refactoring beyond fix scope
-- Verify original convergence criteria still pass
-- Report partial_completion if some feedback unclear
+# Fix
+
+Revision workflow for bug fixes and feedback-driven changes.
+
+## Workflow
+
+1. Read original task + feedback/revision notes from task description
+2. Load original implementation context (files modified, approach taken)
+3. Analyze feedback to identify specific changes needed
+4. Apply fixes:
+   - Agent mode: Edit tool for targeted changes
+   - CLI mode: Resume previous session with fix prompt
+5. Re-validate convergence criteria
+6. Report: original task, changes applied, validation result
+
+## Fix Prompt Template (CLI mode)
+
+```
+PURPOSE: Fix issues in <task.title> based on feedback
+TASK:
+  - Review original implementation
+  - Apply feedback: <feedback text>
+  - Verify fixes address all feedback points
+MODE: write
+CONTEXT: @<modified files>
+EXPECTED: All feedback points addressed, convergence criteria met
+CONSTRAINTS: Minimal changes | No scope creep
+```
+
+## Quality Rules
+
+- Fix ONLY what feedback requests
+- No refactoring beyond fix scope
+- Verify original convergence criteria still pass
+- Report partial_completion if some feedback unclear

package/.agy/skills/team-lifecycle-v4/roles/executor/role.md

@@ -4,61 +4,61 @@ prefix: IMPL
 inner_loop: true
 message_types: 
 ---
-
-# Executor
-
-Code implementation worker with dual execution modes.
-
-## Identity
-- Tag: [executor] | Prefix: IMPL-*
-- Responsibility: Implement code from plan tasks via agent or CLI delegation
-
-## Boundaries
-### MUST
-- Parse task JSON before implementation
-- Execute pre_analysis steps if defined
-- Follow existing code patterns (task.reference)
-- Run convergence check after implementation
-### MUST NOT
-- Skip convergence validation
-- Implement without reading task JSON
-- Introduce breaking changes not in plan
-
-## Phase 2: Parse Task + Resolve Mode
-
-1. Extract from task description: task_file path, session folder, execution mode
-2. Read task JSON (id, title, files[], implementation[], convergence.criteria[])
-3. Resolve execution mode:
-   | Priority | Source |
-   |----------|--------|
-   | 1 | Task description Executor: field |
-   | 2 | task.meta.execution_config.method |
-   | 3 | plan.json recommended_execution |
-   | 4 | Auto: Low → agent, Medium/High → codex |
-4. Execute pre_analysis[] if exists (Read, Bash, Grep, Glob tools)
-
-## Phase 3: Execute Implementation
-
-Route by mode → read commands/<command>.md:
-- agent / gemini / codex / qwen → commands/implement.md
-- Revision task → commands/fix.md
-
-## Phase 4: Self-Validation
-
-| Step | Method | Pass Criteria |
-|------|--------|--------------|
-| Convergence check | Match criteria vs output | All criteria addressed |
-| Syntax check | tsc --noEmit or equivalent | Exit code 0 |
-| Test detection | Find test files for modified files | Tests identified |
-
-Report: task ID, status, mode used, files modified, convergence results.
-
-## Error Handling
-
-| Scenario | Resolution |
-|----------|------------|
-| Agent mode syntax errors | Retry with error context (max 3) |
-| CLI mode failure | Retry or resume with --resume |
-| pre_analysis failure | Follow on_error (fail/continue/skip) |
-| CLI tool unavailable | Fallback: gemini → qwen → codex |
-| Max retries exceeded | Report failure to coordinator |
+
+# Executor
+
+Code implementation worker with dual execution modes.
+
+## Identity
+- Tag: [executor] | Prefix: IMPL-*
+- Responsibility: Implement code from plan tasks via agent or CLI delegation
+
+## Boundaries
+### MUST
+- Parse task JSON before implementation
+- Execute pre_analysis steps if defined
+- Follow existing code patterns (task.reference)
+- Run convergence check after implementation
+### MUST NOT
+- Skip convergence validation
+- Implement without reading task JSON
+- Introduce breaking changes not in plan
+
+## Phase 2: Parse Task + Resolve Mode
+
+1. Extract from task description: task_file path, session folder, execution mode
+2. Read task JSON (id, title, files[], implementation[], convergence.criteria[])
+3. Resolve execution mode:
+   | Priority | Source |
+   |----------|--------|
+   | 1 | Task description Executor: field |
+   | 2 | task.meta.execution_config.method |
+   | 3 | plan.json recommended_execution |
+   | 4 | Auto: Low → agent, Medium/High → codex |
+4. Execute pre_analysis[] if exists (Read, Bash, Grep, Glob tools)
+
+## Phase 3: Execute Implementation
+
+Route by mode → read commands/<command>.md:
+- agent / agy / codex / qwen → commands/implement.md
+- Revision task → commands/fix.md
+
+## Phase 4: Self-Validation
+
+| Step | Method | Pass Criteria |
+|------|--------|--------------|
+| Convergence check | Match criteria vs output | All criteria addressed |
+| Syntax check | tsc --noEmit or equivalent | Exit code 0 |
+| Test detection | Find test files for modified files | Tests identified |
+
+Report: task ID, status, mode used, files modified, convergence results.
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Agent mode syntax errors | Retry with error context (max 3) |
+| CLI mode failure | Retry or resume with --resume |
+| pre_analysis failure | Follow on_error (fail/continue/skip) |
+| CLI tool unavailable | Fallback: agy → qwen → codex |
+| Max retries exceeded | Report failure to coordinator |

package/.agy/skills/team-lifecycle-v4/roles/planner/role.md

@@ -34,7 +34,7 @@ Codebase-informed implementation planning with complexity assessment.
    TASK: • Search for relevant patterns • Identify files to modify • Document integration points
    MODE: analysis
    CONTEXT: @**/*
-   EXPECTED: JSON with: relevant_files[], patterns[], integration_points[], recommendations[]" --tool gemini --mode analysis`, run_in_background: false })
+   EXPECTED: JSON with: relevant_files[], patterns[], integration_points[], recommendations[]" --tool agy --mode analysis`, run_in_background: false })
    ```
 4. Store results in <session>/explorations/
 
@@ -56,7 +56,7 @@ TASK: • Create plan.json overview • Generate TASK-*.json files (2-7 tasks)
 MODE: write
 CONTEXT: @<session>/explorations/*.json
 EXPECTED: Files: plan.json + .task/TASK-*.json
-CONSTRAINTS: 2-7 tasks, include id/title/files[]/convergence.criteria/depends_on" --tool gemini --mode write`, run_in_background: false })
+CONSTRAINTS: 2-7 tasks, include id/title/files[]/convergence.criteria/depends_on" --tool agy --mode write`, run_in_background: false })
 ```
 
 Output files:

package/.agy/skills/team-lifecycle-v4/roles/reviewer/commands/review-code.md

@@ -1,34 +1,34 @@
-# Code Review
-
-4-dimension code review for implementation quality.
-
-## Inputs
-
-- Plan file (plan.json)
-- Git diff or modified files list
-- Test results (if available)
-
-## Dimensions
-
-| Dimension | Critical Issues |
-|-----------|----------------|
-| Quality | Empty catch, any casts, @ts-ignore, console.log |
-| Security | Hardcoded secrets, SQL injection, eval/exec, innerHTML |
-| Architecture | Circular deps, imports >2 levels deep, files >500 lines |
-| Requirements | Missing core functionality, incomplete acceptance criteria |
-
-## Review Process
-
-1. Gather modified files from executor's state (team_msg get_state)
-2. Read each modified file
-3. Score per dimension (0-100%)
-4. Classify issues by severity (Critical/High/Medium/Low)
-5. Generate verdict (BLOCK/CONDITIONAL/APPROVE)
-
-## Output
-
-Write review report to <session>/artifacts/review-report.md:
-- Per-dimension scores
-- Issue list with file:line references
-- Verdict with justification
-- Recommendations (if CONDITIONAL)
+# Code Review
+
+4-dimension code review for implementation quality.
+
+## Inputs
+
+- Plan file (plan.json)
+- Git diff or modified files list
+- Test results (if available)
+
+## Dimensions
+
+| Dimension | Critical Issues |
+|-----------|----------------|
+| Quality | Empty catch, any casts, @ts-ignore, console.log |
+| Security | Hardcoded secrets, SQL injection, eval/exec, innerHTML |
+| Architecture | Circular deps, imports >2 levels deep, files >500 lines |
+| Requirements | Missing core functionality, incomplete acceptance criteria |
+
+## Review Process
+
+1. Gather modified files from executor's state (team_msg get_state)
+2. Read each modified file
+3. Score per dimension (0-100%)
+4. Classify issues by severity (Critical/High/Medium/Low)
+5. Generate verdict (BLOCK/CONDITIONAL/APPROVE)
+
+## Output
+
+Write review report to <session>/artifacts/review-report.md:
+- Per-dimension scores
+- Issue list with file:line references
+- Verdict with justification
+- Recommendations (if CONDITIONAL)

package/.agy/skills/team-lifecycle-v4/roles/reviewer/commands/review-spec.md

@@ -1,44 +1,44 @@
-# Spec Quality Review
-
-5-dimension spec quality gate with discuss protocol.
-
-## Inputs
-
-- All spec docs in <session>/spec/
-- Quality gate config from specs/quality-gates.md
-
-## Dimensions
-
-| Dimension | Weight | Focus |
-|-----------|--------|-------|
-| Completeness | 25% | All sections present with substance |
-| Consistency | 25% | Terminology, format, references uniform |
-| Traceability | 25% | Goals→Reqs→Arch→Stories chain |
-| Depth | 25% | AC testable, ADRs justified, stories estimable |
-
-## Review Process
-
-1. Read all spec documents from <session>/spec/
-2. Load quality gate thresholds from specs/quality-gates.md
-3. Score each dimension
-4. Run cross-document validation
-5. Generate readiness-report.md + blueprint-summary.md
-6. Run DISCUSS-003:
-   - Artifact: <session>/spec/readiness-report.md
-   - Perspectives: product, technical, quality, risk, coverage
-   - Handle verdict per consensus protocol
-   - DISCUSS-003 HIGH always triggers user pause
-
-## Quality Gate
-
-| Gate | Score |
-|------|-------|
-| PASS | >= 80% |
-| REVIEW | 60-79% |
-| FAIL | < 60% |
-
-## Output
-
-Write to <session>/artifacts/:
-- readiness-report.md: Dimension scores, issue list, traceability matrix
-- blueprint-summary.md: Executive summary of all spec docs
+# Spec Quality Review
+
+5-dimension spec quality gate with discuss protocol.
+
+## Inputs
+
+- All spec docs in <session>/spec/
+- Quality gate config from specs/quality-gates.md
+
+## Dimensions
+
+| Dimension | Weight | Focus |
+|-----------|--------|-------|
+| Completeness | 25% | All sections present with substance |
+| Consistency | 25% | Terminology, format, references uniform |
+| Traceability | 25% | Goals→Reqs→Arch→Stories chain |
+| Depth | 25% | AC testable, ADRs justified, stories estimable |
+
+## Review Process
+
+1. Read all spec documents from <session>/spec/
+2. Load quality gate thresholds from specs/quality-gates.md
+3. Score each dimension
+4. Run cross-document validation
+5. Generate readiness-report.md + blueprint-summary.md
+6. Run DISCUSS-003:
+   - Artifact: <session>/spec/readiness-report.md
+   - Perspectives: product, technical, quality, risk, coverage
+   - Handle verdict per consensus protocol
+   - DISCUSS-003 HIGH always triggers user pause
+
+## Quality Gate
+
+| Gate | Score |
+|------|-------|
+| PASS | >= 80% |
+| REVIEW | 60-79% |
+| FAIL | < 60% |
+
+## Output
+
+Write to <session>/artifacts/:
+- readiness-report.md: Dimension scores, issue list, traceability matrix
+- blueprint-summary.md: Executive summary of all spec docs