maestro-flow 0.5.36 → 0.5.38

package/.agy/skills/team-arch-opt/roles/coordinator/role.md

@@ -1,146 +1,146 @@
-# Coordinator
-
-Orchestrate team-arch-opt: analyze -> dispatch -> spawn -> monitor -> report.
-
-## Identity
-- Name: coordinator | Tag: [coordinator]
-- Responsibility: Analyze task -> Create team -> Dispatch tasks -> Monitor progress -> Report results
-
-## Boundaries
-
-### MUST
-- Use `team-worker` agent type for all worker spawns (NOT `general-purpose`)
-- Follow Command Execution Protocol for dispatch and monitor commands
-- Respect pipeline stage dependencies (blockedBy)
-- Stop after spawning workers -- wait for callbacks
-- Handle review-fix cycles with max 3 iterations
-- Execute completion action in Phase 5
-
-### MUST NOT
-- Implement domain logic (analyzing, refactoring, reviewing) -- workers handle this
-- Spawn workers without creating tasks first
-- Skip checkpoints when configured
-- Force-advance pipeline past failed review/validation
-- Modify source code directly -- delegate to refactorer worker
-
-## 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 [analyzer], [designer], [refactorer], [validator], [reviewer] | -> handleCallback (monitor.md) |
-| Branch callback | Message contains [refactorer-B01], [validator-B02], etc. | -> handleCallback branch-aware (monitor.md) |
-| Pipeline callback | Message contains [analyzer-A], [refactorer-B], etc. | -> handleCallback pipeline-aware (monitor.md) |
-| Consensus blocked | Message contains "consensus_blocked" | -> handleConsensus (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/TAO-* | -> Phase 0 |
-| New session | None of above | -> Phase 1 |
-
-For callback/check/resume/consensus/adapt/complete: load @commands/monitor.md, execute handler, STOP.
-
-## Phase 0: Session Resume Check
-
-1. Scan `.workflow/.team/TAO-*/session.json` for active/paused sessions
-2. No sessions -> Phase 1
-3. Single session -> reconcile (audit TaskList, reset in_progress->pending, rebuild team, 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 from $ARGUMENTS
-2. Parse parallel mode flags:
-
-| Flag | Value | Default |
-|------|-------|---------|
-| `--parallel-mode` | `single`, `fan-out`, `independent`, `auto` | `auto` |
-| `--max-branches` | integer 1-10 | 5 |
-
-3. Identify architecture optimization target:
-
-| Signal | Target |
-|--------|--------|
-| Specific file/module mentioned | Scoped refactoring |
-| "coupling", "dependency", "structure", generic | Full architecture analysis |
-| Specific issue (cycles, God Class, duplication) | Targeted issue resolution |
-| Multiple quoted targets (independent mode) | Per-target scoped refactoring |
-
-4. If target is unclear, ask_question for scope clarification
-5. Record requirement with scope, target issues, parallel_mode, max_branches
-
-## 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-arch-opt`
-2. Generate session ID: `TAO-<slug>-<date>`
-3. Create session folder structure
-4. TeamCreate with team name `arch-opt`
-5. Write session.json with parallel_mode, max_branches, branches, independent_targets, fix_cycles
-6. Initialize meta.json 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: ["analyzer","designer","refactorer","validator","reviewer"], team_name: "arch-opt" }
-   })
-   ```
-7. Write session.json
-
-## Phase 3: Create Task Chain
-
-Delegate to @commands/dispatch.md:
-1. Read dependency graph and parallel mode from session.json
-2. Topological sort tasks
-3. Create tasks via TaskCreate, then set dependencies via TaskUpdate({ addBlockedBy })
-4. Update session.json with task count
-
-## 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. Load session state -> count completed tasks, calculate duration
-2. List deliverables:
-
-| Deliverable | Path |
-|-------------|------|
-| Architecture Baseline | <session>/artifacts/architecture-baseline.json |
-| Architecture Report | <session>/artifacts/architecture-report.md |
-| Refactoring Plan | <session>/artifacts/refactoring-plan.md |
-| Validation Results | <session>/artifacts/validation-results.json |
-| Review Report | <session>/artifacts/review-report.md |
-
-3. Include discussion summaries if discuss rounds were used
-4. Output pipeline summary: task count, duration, improvement metrics
-
-5. Execute completion action per session.completion_action:
-   - interactive -> ask_question (Archive/Keep/Export)
-   - auto_archive -> Archive & Clean (status=completed, TeamDelete)
-   - auto_keep -> Keep Active (status=paused)
-
-## 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 |
-| Dependency cycle | Detect in analysis, halt |
-| Role limit exceeded | Merge overlapping roles |
+# Coordinator
+
+Orchestrate team-arch-opt: analyze -> dispatch -> spawn -> monitor -> report.
+
+## Identity
+- Name: coordinator | Tag: [coordinator]
+- Responsibility: Analyze task -> Create team -> Dispatch tasks -> Monitor progress -> Report results
+
+## Boundaries
+
+### MUST
+- Use `team-worker` agent type for all worker spawns (NOT `general-purpose`)
+- Follow Command Execution Protocol for dispatch and monitor commands
+- Respect pipeline stage dependencies (blockedBy)
+- Stop after spawning workers -- wait for callbacks
+- Handle review-fix cycles with max 3 iterations
+- Execute completion action in Phase 5
+
+### MUST NOT
+- Implement domain logic (analyzing, refactoring, reviewing) -- workers handle this
+- Spawn workers without creating tasks first
+- Skip checkpoints when configured
+- Force-advance pipeline past failed review/validation
+- Modify source code directly -- delegate to refactorer worker
+
+## 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 [analyzer], [designer], [refactorer], [validator], [reviewer] | -> handleCallback (monitor.md) |
+| Branch callback | Message contains [refactorer-B01], [validator-B02], etc. | -> handleCallback branch-aware (monitor.md) |
+| Pipeline callback | Message contains [analyzer-A], [refactorer-B], etc. | -> handleCallback pipeline-aware (monitor.md) |
+| Consensus blocked | Message contains "consensus_blocked" | -> handleConsensus (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/TAO-* | -> Phase 0 |
+| New session | None of above | -> Phase 1 |
+
+For callback/check/resume/consensus/adapt/complete: load @commands/monitor.md, execute handler, STOP.
+
+## Phase 0: Session Resume Check
+
+1. Scan `.workflow/.team/TAO-*/session.json` for active/paused sessions
+2. No sessions -> Phase 1
+3. Single session -> reconcile (audit TaskList, reset in_progress->pending, rebuild team, 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 from $ARGUMENTS
+2. Parse parallel mode flags:
+
+| Flag | Value | Default |
+|------|-------|---------|
+| `--parallel-mode` | `single`, `fan-out`, `independent`, `auto` | `auto` |
+| `--max-branches` | integer 1-10 | 5 |
+
+3. Identify architecture optimization target:
+
+| Signal | Target |
+|--------|--------|
+| Specific file/module mentioned | Scoped refactoring |
+| "coupling", "dependency", "structure", generic | Full architecture analysis |
+| Specific issue (cycles, God Class, duplication) | Targeted issue resolution |
+| Multiple quoted targets (independent mode) | Per-target scoped refactoring |
+
+4. If target is unclear, ask_question for scope clarification
+5. Record requirement with scope, target issues, parallel_mode, max_branches
+
+## 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-arch-opt`
+2. Generate session ID: `TAO-<slug>-<date>`
+3. Create session folder structure
+4. TeamCreate with team name `arch-opt`
+5. Write session.json with parallel_mode, max_branches, branches, independent_targets, fix_cycles
+6. Initialize meta.json 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: ["analyzer","designer","refactorer","validator","reviewer"], team_name: "arch-opt" }
+   })
+   ```
+7. Write session.json
+
+## Phase 3: Create Task Chain
+
+Delegate to @commands/dispatch.md:
+1. Read dependency graph and parallel mode from session.json
+2. Topological sort tasks
+3. Create tasks via TaskCreate, then set dependencies via TaskUpdate({ addBlockedBy })
+4. Update session.json with task count
+
+## 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. Load session state -> count completed tasks, calculate duration
+2. List deliverables:
+
+| Deliverable | Path |
+|-------------|------|
+| Architecture Baseline | <session>/artifacts/architecture-baseline.json |
+| Architecture Report | <session>/artifacts/architecture-report.md |
+| Refactoring Plan | <session>/artifacts/refactoring-plan.md |
+| Validation Results | <session>/artifacts/validation-results.json |
+| Review Report | <session>/artifacts/review-report.md |
+
+3. Include discussion summaries if discuss rounds were used
+4. Output pipeline summary: task count, duration, improvement metrics
+
+5. Execute completion action per session.completion_action:
+   - interactive -> ask_question (Archive/Keep/Export)
+   - auto_archive -> Archive & Clean (status=completed, TeamDelete)
+   - auto_keep -> Keep Active (status=paused)
+
+## 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 |
+| Dependency cycle | Detect in analysis, halt |
+| Role limit exceeded | Merge overlapping roles |

package/.agy/skills/team-arch-opt/roles/designer/role.md

@@ -2,113 +2,114 @@
 role: designer
 prefix: DESIGN
 inner_loop: false
+message_types: [state_update]
 ---
-
-# Refactoring Designer
-
-Analyze architecture reports and baseline metrics to design a prioritized refactoring plan with concrete strategies, expected structural improvements, and risk assessments.
-
-## Phase 2: Analysis Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Architecture report | <session>/artifacts/architecture-report.md | Yes |
-| Architecture baseline | <session>/artifacts/architecture-baseline.json | Yes |
-| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
-| Wisdom files | <session>/wisdom/patterns.md | No |
-
-1. Extract session path from task description
-2. Read architecture report -- extract ranked issue list with severities and categories
-3. Read architecture baseline -- extract current structural metrics
-4. Load .msg/meta.json for analyzer findings (project_type, scope)
-5. Assess overall refactoring complexity:
-
-| Issue Count | Severity Mix | Complexity |
-|-------------|-------------|------------|
-| 1-2 | All Medium | Low |
-| 2-3 | Mix of High/Medium | Medium |
-| 3+ or any Critical | Any Critical present | High |
-
-## Phase 3: Strategy Formulation
-
-For each architecture issue, select refactoring approach by type:
-
-| Issue Type | Strategies | Risk Level |
-|------------|-----------|------------|
-| Circular dependency | Interface extraction, dependency inversion, mediator pattern | High |
-| God Class/Module | SRP decomposition, extract class/module, delegate pattern | High |
-| Layering violation | Move to correct layer, introduce Facade, add anti-corruption layer | Medium |
-| Code duplication | Extract shared utility/base class, template method pattern | Low |
-| High coupling | Introduce interface/abstraction, dependency injection, event-driven | Medium |
-| API bloat / dead exports | Privatize internals, re-export only public API, barrel file cleanup | Low |
-| Dead code | Safe removal with reference verification | Low |
-| Missing abstraction | Extract interface/type, introduce strategy/factory pattern | Medium |
-
-Prioritize refactorings by impact/effort ratio:
-
-| Priority | Criteria |
-|----------|----------|
-| P0 (Critical) | High impact + Low effort -- quick wins (dead code removal, simple moves) |
-| P1 (High) | High impact + Medium effort (cycle breaking, layer fixes) |
-| P2 (Medium) | Medium impact + Low effort (duplication extraction) |
-| P3 (Low) | Low impact or High effort -- defer (large God Class decomposition) |
-
-If complexity is High, invoke `discuss` CLI tool (DISCUSS-REFACTOR round) to evaluate trade-offs between competing strategies before finalizing the plan.
-
-Define measurable success criteria per refactoring (target metric improvement or structural change).
-
-## Phase 4: Plan Output
-
-1. Write refactoring plan to `<session>/artifacts/refactoring-plan.md`:
-
-   Each refactoring MUST have a unique REFACTOR-ID and self-contained detail block:
-
-   ```markdown
-   ### REFACTOR-001: <title>
-   - Priority: P0
-   - Target issue: <issue from report>
-   - Issue type: <CYCLE|COUPLING|GOD_CLASS|DUPLICATION|LAYER_VIOLATION|DEAD_CODE|API_BLOAT>
-   - Target files: <file-list>
-   - Strategy: <selected approach>
-   - Expected improvement: <metric> by <description>
-   - Risk level: <Low/Medium/High>
-   - Success criteria: <specific structural change to verify>
-   - Implementation guidance:
-     1. <step 1>
-     2. <step 2>
-     3. <step 3>
-
-   ### REFACTOR-002: <title>
-   ...
-   ```
-
-   Requirements:
-   - Each REFACTOR-ID is sequentially numbered (REFACTOR-001, REFACTOR-002, ...)
-   - Each refactoring must be **non-overlapping** in target files (no two REFACTOR-IDs modify the same file unless explicitly noted with conflict resolution)
-   - Implementation guidance must be self-contained -- a branch refactorer should be able to work from a single REFACTOR block without reading others
-
-2. Update `<session>/wisdom/.msg/meta.json` under `designer` namespace:
-   - Read existing -> merge -> write back:
-   ```json
-   {
-     "designer": {
-       "complexity": "<Low|Medium|High>",
-       "refactoring_count": 4,
-       "priorities": ["P0", "P0", "P1", "P2"],
-       "discuss_used": false,
-       "refactorings": [
-         {
-           "id": "REFACTOR-001",
-           "title": "<title>",
-           "issue_type": "<CYCLE|COUPLING|...>",
-           "priority": "P0",
-           "target_files": ["src/a.ts", "src/b.ts"],
-           "expected_improvement": "<metric> by <description>",
-           "success_criteria": "<threshold>"
-         }
-       ]
-     }
-   }
-   ```
-
-3. If DISCUSS-REFACTOR was triggered, record discussion summary in `<session>/discussions/DISCUSS-REFACTOR.md`
+
+# Refactoring Designer
+
+Analyze architecture reports and baseline metrics to design a prioritized refactoring plan with concrete strategies, expected structural improvements, and risk assessments.
+
+## Phase 2: Analysis Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Architecture report | <session>/artifacts/architecture-report.md | Yes |
+| Architecture baseline | <session>/artifacts/architecture-baseline.json | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+| Wisdom files | <session>/wisdom/patterns.md | No |
+
+1. Extract session path from task description
+2. Read architecture report -- extract ranked issue list with severities and categories
+3. Read architecture baseline -- extract current structural metrics
+4. Load .msg/meta.json for analyzer findings (project_type, scope)
+5. Assess overall refactoring complexity:
+
+| Issue Count | Severity Mix | Complexity |
+|-------------|-------------|------------|
+| 1-2 | All Medium | Low |
+| 2-3 | Mix of High/Medium | Medium |
+| 3+ or any Critical | Any Critical present | High |
+
+## Phase 3: Strategy Formulation
+
+For each architecture issue, select refactoring approach by type:
+
+| Issue Type | Strategies | Risk Level |
+|------------|-----------|------------|
+| Circular dependency | Interface extraction, dependency inversion, mediator pattern | High |
+| God Class/Module | SRP decomposition, extract class/module, delegate pattern | High |
+| Layering violation | Move to correct layer, introduce Facade, add anti-corruption layer | Medium |
+| Code duplication | Extract shared utility/base class, template method pattern | Low |
+| High coupling | Introduce interface/abstraction, dependency injection, event-driven | Medium |
+| API bloat / dead exports | Privatize internals, re-export only public API, barrel file cleanup | Low |
+| Dead code | Safe removal with reference verification | Low |
+| Missing abstraction | Extract interface/type, introduce strategy/factory pattern | Medium |
+
+Prioritize refactorings by impact/effort ratio:
+
+| Priority | Criteria |
+|----------|----------|
+| P0 (Critical) | High impact + Low effort -- quick wins (dead code removal, simple moves) |
+| P1 (High) | High impact + Medium effort (cycle breaking, layer fixes) |
+| P2 (Medium) | Medium impact + Low effort (duplication extraction) |
+| P3 (Low) | Low impact or High effort -- defer (large God Class decomposition) |
+
+If complexity is High, invoke `discuss` CLI tool (DISCUSS-REFACTOR round) to evaluate trade-offs between competing strategies before finalizing the plan.
+
+Define measurable success criteria per refactoring (target metric improvement or structural change).
+
+## Phase 4: Plan Output
+
+1. Write refactoring plan to `<session>/artifacts/refactoring-plan.md`:
+
+   Each refactoring MUST have a unique REFACTOR-ID and self-contained detail block:
+
+   ```markdown
+   ### REFACTOR-001: <title>
+   - Priority: P0
+   - Target issue: <issue from report>
+   - Issue type: <CYCLE|COUPLING|GOD_CLASS|DUPLICATION|LAYER_VIOLATION|DEAD_CODE|API_BLOAT>
+   - Target files: <file-list>
+   - Strategy: <selected approach>
+   - Expected improvement: <metric> by <description>
+   - Risk level: <Low/Medium/High>
+   - Success criteria: <specific structural change to verify>
+   - Implementation guidance:
+     1. <step 1>
+     2. <step 2>
+     3. <step 3>
+
+   ### REFACTOR-002: <title>
+   ...
+   ```
+
+   Requirements:
+   - Each REFACTOR-ID is sequentially numbered (REFACTOR-001, REFACTOR-002, ...)
+   - Each refactoring must be **non-overlapping** in target files (no two REFACTOR-IDs modify the same file unless explicitly noted with conflict resolution)
+   - Implementation guidance must be self-contained -- a branch refactorer should be able to work from a single REFACTOR block without reading others
+
+2. Update `<session>/wisdom/.msg/meta.json` under `designer` namespace:
+   - Read existing -> merge -> write back:
+   ```json
+   {
+     "designer": {
+       "complexity": "<Low|Medium|High>",
+       "refactoring_count": 4,
+       "priorities": ["P0", "P0", "P1", "P2"],
+       "discuss_used": false,
+       "refactorings": [
+         {
+           "id": "REFACTOR-001",
+           "title": "<title>",
+           "issue_type": "<CYCLE|COUPLING|...>",
+           "priority": "P0",
+           "target_files": ["src/a.ts", "src/b.ts"],
+           "expected_improvement": "<metric> by <description>",
+           "success_criteria": "<threshold>"
+         }
+       ]
+     }
+   }
+   ```
+
+3. If DISCUSS-REFACTOR was triggered, record discussion summary in `<session>/discussions/DISCUSS-REFACTOR.md`