maestro-flow 0.5.31 → 0.5.33

package/.agents/skills/team-perf-opt/roles/reviewer/role.md

@@ -0,0 +1,77 @@
+---
+role: reviewer
+prefix: REVIEW
+inner_loop: false
+additional_prefixes: [QUALITY]
+discuss_rounds: [DISCUSS-REVIEW]
+message_types:
+  success: review_complete
+  error: error
+  fix: fix_required
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Optimization Reviewer
+
+Review optimization code changes for correctness, side effects, regression risks, and adherence to best practices. Provide structured verdicts with actionable feedback.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Optimization code changes | From IMPL task artifacts / git diff | Yes |
+| Optimization plan / detail | Varies by mode (see below) | Yes |
+| Benchmark results | Varies by mode (see below) | No |
+| .msg/meta.json | <session>/.msg/meta.json | Yes |
+
+1. Extract session path from task description
+2. **Detect branch/pipeline context** from task description:
+
+| Task Description Field | Value | Context |
+|----------------------|-------|---------|
+| `BranchId: B{NN}` | Present | Fan-out branch -- review only this branch's changes |
+| `PipelineId: {P}` | Present | Independent pipeline -- review pipeline-scoped changes |
+| Neither present | - | Single mode -- review all optimization changes |
+
+3. **Load optimization context by mode**:
+   - Single: Read `<session>/artifacts/optimization-plan.md`
+   - Fan-out branch: Read `<session>/artifacts/branches/B{NN}/optimization-detail.md`
+   - Independent: Read `<session>/artifacts/pipelines/{P}/optimization-plan.md`
+
+4. Load .msg/meta.json for scoped optimizer namespace
+5. Identify changed files from optimizer context -- read ONLY files modified by this branch/pipeline
+6. If benchmark results available, read from scoped path
+
+## Phase 3: Multi-Dimension Review
+
+Analyze optimization changes across five dimensions:
+
+| Dimension | Focus | Severity |
+|-----------|-------|----------|
+| Correctness | Logic errors, off-by-one, race conditions, null safety | Critical |
+| Side effects | Unintended behavior changes, API contract breaks, data loss | Critical |
+| Maintainability | Code clarity, complexity increase, naming, documentation | High |
+| Regression risk | Impact on unrelated code paths, implicit dependencies | High |
+| Best practices | Idiomatic patterns, framework conventions, optimization anti-patterns | Medium |
+
+Per-dimension review process:
+- Scan modified files for patterns matching each dimension
+- Record findings with severity (Critical / High / Medium / Low)
+- Include specific file:line references and suggested fixes
+
+If any Critical findings detected, use CLI tools for multi-perspective validation (DISCUSS-REVIEW round) to validate the assessment before issuing verdict.
+
+## Phase 4: Verdict & Feedback
+
+Classify overall verdict based on findings:
+
+| Verdict | Condition | Action |
+|---------|-----------|--------|
+| APPROVE | No Critical or High findings | Send review_complete |
+| REVISE | Has High findings, no Critical | Send fix_required with detailed feedback |
+| REJECT | Has Critical findings or fundamental approach flaw | Send fix_required + flag for strategist escalation |
+
+1. Write review report to scoped output path (single/fan-out/independent)
+2. Update `<session>/.msg/meta.json` under scoped namespace
+3. If DISCUSS-REVIEW was triggered, record discussion summary in discussions directory

package/.agents/skills/team-perf-opt/roles/strategist/role.md

@@ -0,0 +1,96 @@
+---
+role: strategist
+prefix: STRATEGY
+inner_loop: false
+discuss_rounds: [DISCUSS-OPT]
+message_types:
+  success: strategy_complete
+  error: error
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Optimization Strategist
+
+Analyze bottleneck reports and baseline metrics to design a prioritized optimization plan with concrete strategies, expected improvements, and risk assessments.
+
+## Phase 2: Analysis Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Bottleneck report | <session>/artifacts/bottleneck-report.md | Yes |
+| Baseline metrics | <session>/artifacts/baseline-metrics.json | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | Yes |
+| Wisdom files | <session>/wisdom/patterns.md | No |
+
+1. Extract session path from task description
+2. Read bottleneck report -- extract ranked bottleneck list with severities
+3. Read baseline metrics -- extract current performance numbers
+4. Load .msg/meta.json for profiler findings (project_type, scope)
+5. Assess overall optimization complexity:
+
+| Bottleneck 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 bottleneck, select optimization approach by type:
+
+| Bottleneck Type | Strategies | Risk Level |
+|----------------|-----------|------------|
+| CPU hotspot | Algorithm optimization, memoization, caching, worker threads | Medium |
+| Memory leak/bloat | Pool reuse, lazy initialization, WeakRef, scope cleanup | High |
+| I/O bound | Batching, async pipelines, streaming, connection pooling | Medium |
+| Network latency | Request coalescing, compression, CDN, prefetching | Low |
+| Rendering | Virtualization, memoization, CSS containment, code splitting | Medium |
+| Database | Index optimization, query rewriting, caching layer, denormalization | High |
+
+Prioritize optimizations by impact/effort ratio:
+
+| Priority | Criteria |
+|----------|----------|
+| P0 (Critical) | High impact + Low effort -- quick wins |
+| P1 (High) | High impact + Medium effort |
+| P2 (Medium) | Medium impact + Low effort |
+| P3 (Low) | Low impact or High effort -- defer |
+
+If complexity is High, use CLI tools for multi-perspective analysis (DISCUSS-OPT round) to evaluate trade-offs between competing strategies before finalizing the plan.
+
+Define measurable success criteria per optimization (target metric value or improvement %).
+
+## Phase 4: Plan Output
+
+1. Write optimization plan to `<session>/artifacts/optimization-plan.md`:
+
+   Each optimization MUST have a unique OPT-ID and self-contained detail block:
+
+   ```markdown
+   ### OPT-001: <title>
+   - Priority: P0
+   - Target bottleneck: <bottleneck from report>
+   - Target files: <file-list>
+   - Strategy: <selected approach>
+   - Expected improvement: <metric> by <X%>
+   - Risk level: <Low/Medium/High>
+   - Success criteria: <specific threshold to verify>
+   - Implementation guidance:
+     1. <step 1>
+     2. <step 2>
+     3. <step 3>
+
+   ### OPT-002: <title>
+   ...
+   ```
+
+   Requirements:
+   - Each OPT-ID is sequentially numbered (OPT-001, OPT-002, ...)
+   - Each optimization must be **non-overlapping** in target files
+   - Implementation guidance must be self-contained
+
+2. Update `<session>/.msg/meta.json` under `strategist` namespace:
+   - Read existing -> merge -> write back with optimization metadata
+
+3. If DISCUSS-OPT was triggered, record discussion summary in `<session>/discussions/DISCUSS-OPT.md`

package/.agents/skills/team-perf-opt/specs/pipelines.md

@@ -0,0 +1,65 @@
+# Pipeline Definitions — Team Performance Optimization
+
+## Pipeline Modes
+
+### Single Mode (Linear with Review-Fix Cycle)
+
+```
+Stage 1           Stage 2           Stage 3           Stage 4
+PROFILE-001  -->  STRATEGY-001 -->  IMPL-001   --> BENCH-001
+[profiler]        [strategist]      [optimizer]    [benchmarker]
+                                        ^               |
+                                        +<--FIX-001---->+
+                                        |          REVIEW-001
+                                        +<-------->  [reviewer]
+                                  (max 3 iterations)
+```
+
+### Fan-out Mode (Shared stages 1-2, parallel branches 3-4)
+
+```
+Stage 1           Stage 2         CP-2.5          Stage 3+4 (per branch)
+PROFILE-001 --> STRATEGY-001 --+-> IMPL-B01 --> BENCH-B01 + REVIEW-B01 (fix cycle)
+                               +-> IMPL-B02 --> BENCH-B02 + REVIEW-B02 (fix cycle)
+                               +-> IMPL-B0N --> BENCH-B0N + REVIEW-B0N (fix cycle)
+                                                          |
+                                                     AGGREGATE -> Phase 5
+```
+
+### Independent Mode (M fully independent pipelines)
+
+```
+Pipeline A: PROFILE-A01 --> STRATEGY-A01 --> IMPL-A01 --> BENCH-A01 + REVIEW-A01
+Pipeline B: PROFILE-B01 --> STRATEGY-B01 --> IMPL-B01 --> BENCH-B01 + REVIEW-B01
+                                                          |
+                                                     AGGREGATE -> Phase 5
+```
+
+## Task Metadata Registry (Single Mode)
+
+| Task ID | Role | Phase | Dependencies | Description |
+|---------|------|-------|-------------|-------------|
+| PROFILE-001 | profiler | Stage 1 | (none) | Profile application, identify bottlenecks |
+| STRATEGY-001 | strategist | Stage 2 | PROFILE-001 | Design optimization plan from bottleneck report |
+| IMPL-001 | optimizer | Stage 3 | STRATEGY-001 | Implement highest-priority optimizations |
+| BENCH-001 | benchmarker | Stage 4 | IMPL-001 | Run benchmarks, compare vs baseline |
+| REVIEW-001 | reviewer | Stage 4 | IMPL-001 | Review optimization code for correctness |
+| FIX-001 | optimizer | Stage 3 (cycle) | REVIEW-001 or BENCH-001 | Fix issues found in review/benchmark |
+
+## Checkpoints
+
+| Checkpoint | Trigger | Behavior |
+|------------|---------|----------|
+| CP-1 | PROFILE-001 complete | User reviews bottleneck report, can refine scope |
+| CP-2 | STRATEGY-001 complete | User reviews optimization plan, can adjust priorities |
+| CP-2.5 | STRATEGY-001 complete (auto/fan-out) | Auto-create N branch tasks, spawn all IMPL-B* in parallel |
+| CP-3 | REVIEW/BENCH fail | Auto-create FIX task for that branch only (max 3x per branch) |
+| CP-4 | All tasks/branches complete | Aggregate results, interactive completion action |
+
+## Task Naming Rules
+
+| Mode | Stage 3 | Stage 4 | Fix | Retry |
+|------|---------|---------|-----|-------|
+| Single | IMPL-001 | BENCH-001, REVIEW-001 | FIX-001 | BENCH-001-R1, REVIEW-001-R1 |
+| Fan-out | IMPL-B01 | BENCH-B01, REVIEW-B01 | FIX-B01-1 | BENCH-B01-R1, REVIEW-B01-R1 |
+| Independent | IMPL-A01 | BENCH-A01, REVIEW-A01 | FIX-A01-1 | BENCH-A01-R1, REVIEW-A01-R1 |

package/.agents/skills/team-perf-opt/specs/team-config.json

@@ -0,0 +1,246 @@
+{
+  "version": "5.0.0",
+  "team_name": "perf-opt",
+  "team_display_name": "Performance Optimization",
+  "skill_name": "team-perf-opt",
+  "skill_path": "~  or <project>/.claude/skills/team-perf-opt/",
+  "worker_agent": "team-worker",
+  "pipeline_type": "Linear with Review-Fix Cycle (Parallel-Capable)",
+  "completion_action": "interactive",
+  "has_inline_discuss": true,
+  "has_shared_explore": true,
+  "has_checkpoint_feedback": true,
+  "has_session_resume": true,
+
+  "roles": [
+    {
+      "name": "coordinator",
+      "type": "orchestrator",
+      "description": "Orchestrates performance optimization pipeline, manages task chains, handles review-fix cycles",
+      "spec_path": "roles/coordinator/role.md",
+      "tools": ["Task", "TaskCreate", "TaskList", "TaskGet", "TaskUpdate", "TeamCreate", "TeamDelete", "SendMessage", "AskUserQuestion", "Read", "Write", "Bash", "Glob", "Grep"]
+    },
+    {
+      "name": "profiler",
+      "type": "orchestration",
+      "description": "Profiles application performance, identifies CPU/memory/IO/network/rendering bottlenecks",
+      "role_spec": "roles/profiler/role.md",
+      "inner_loop": false,
+      "frontmatter": {
+        "prefix": "PROFILE",
+        "inner_loop": false,
+        "additional_prefixes": [],
+        "discuss_rounds": [],
+        "delegates_to": [],
+        "message_types": {
+          "success": "profile_complete",
+          "error": "error"
+        }
+      },
+      "weight": 1,
+      "tools": ["Read", "Bash", "Glob", "Grep", "Task"]
+    },
+    {
+      "name": "strategist",
+      "type": "orchestration",
+      "description": "Analyzes bottleneck reports, designs prioritized optimization plans with concrete strategies",
+      "role_spec": "roles/strategist/role.md",
+      "inner_loop": false,
+      "frontmatter": {
+        "prefix": "STRATEGY",
+        "inner_loop": false,
+        "additional_prefixes": [],
+        "discuss_rounds": ["DISCUSS-OPT"],
+        "delegates_to": [],
+        "message_types": {
+          "success": "strategy_complete",
+          "error": "error"
+        }
+      },
+      "weight": 2,
+      "tools": ["Read", "Bash", "Glob", "Grep", "Task"]
+    },
+    {
+      "name": "optimizer",
+      "type": "code_generation",
+      "description": "Implements optimization changes following the strategy plan",
+      "role_spec": "roles/optimizer/role.md",
+      "inner_loop": "dynamic",
+      "frontmatter": {
+        "prefix": "IMPL",
+        "inner_loop": "dynamic",
+        "additional_prefixes": ["FIX"],
+        "discuss_rounds": [],
+        "delegates_to": [],
+        "message_types": {
+          "success": "impl_complete",
+          "error": "error",
+          "fix": "fix_required"
+        }
+      },
+      "weight": 3,
+      "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Task"]
+    },
+    {
+      "name": "benchmarker",
+      "type": "validation",
+      "description": "Runs benchmarks, compares before/after metrics, validates performance improvements",
+      "role_spec": "roles/benchmarker/role.md",
+      "inner_loop": false,
+      "frontmatter": {
+        "prefix": "BENCH",
+        "inner_loop": false,
+        "additional_prefixes": [],
+        "discuss_rounds": [],
+        "delegates_to": [],
+        "message_types": {
+          "success": "bench_complete",
+          "error": "error",
+          "fix": "fix_required"
+        }
+      },
+      "weight": 4,
+      "tools": ["Read", "Bash", "Glob", "Grep", "Task"]
+    },
+    {
+      "name": "reviewer",
+      "type": "read_only_analysis",
+      "description": "Reviews optimization code for correctness, side effects, and regression risks",
+      "role_spec": "roles/reviewer/role.md",
+      "inner_loop": false,
+      "frontmatter": {
+        "prefix": "REVIEW",
+        "inner_loop": false,
+        "additional_prefixes": ["QUALITY"],
+        "discuss_rounds": ["DISCUSS-REVIEW"],
+        "delegates_to": [],
+        "message_types": {
+          "success": "review_complete",
+          "error": "error",
+          "fix": "fix_required"
+        }
+      },
+      "weight": 4,
+      "tools": ["Read", "Bash", "Glob", "Grep", "Task"]
+    }
+  ],
+
+  "parallel_config": {
+    "modes": ["single", "fan-out", "independent", "auto"],
+    "default_mode": "auto",
+    "max_branches": 5,
+    "auto_mode_rules": {
+      "single": "optimization_count <= 2",
+      "fan-out": "optimization_count >= 3"
+    }
+  },
+
+  "pipeline": {
+    "stages": [
+      {
+        "stage": 1,
+        "name": "Performance Profiling",
+        "roles": ["profiler"],
+        "blockedBy": [],
+        "fast_advance": true
+      },
+      {
+        "stage": 2,
+        "name": "Optimization Strategy",
+        "roles": ["strategist"],
+        "blockedBy": ["PROFILE"],
+        "fast_advance": true
+      },
+      {
+        "stage": 3,
+        "name": "Code Optimization",
+        "roles": ["optimizer"],
+        "blockedBy": ["STRATEGY"],
+        "fast_advance": false
+      },
+      {
+        "stage": 4,
+        "name": "Benchmark & Review",
+        "roles": ["benchmarker", "reviewer"],
+        "blockedBy": ["IMPL"],
+        "fast_advance": false,
+        "parallel": true,
+        "review_fix_cycle": {
+          "trigger": "REVIEW or BENCH finds issues",
+          "target_stage": 3,
+          "max_iterations": 3
+        }
+      }
+    ],
+    "parallel_pipelines": {
+      "fan-out": {
+        "shared_stages": [1, 2],
+        "branch_stages": [3, 4],
+        "branch_prefix": "B",
+        "review_fix_cycle": {
+          "scope": "per_branch",
+          "max_iterations": 3
+        }
+      },
+      "independent": {
+        "pipeline_prefix_chars": "ABCDEFGHIJ",
+        "review_fix_cycle": {
+          "scope": "per_pipeline",
+          "max_iterations": 3
+        }
+      }
+    },
+    "diagram": "See pipeline-diagram section"
+  },
+
+  "shared_resources": [
+    {
+      "name": "Performance Baseline",
+      "path": "<session>/artifacts/baseline-metrics.json",
+      "usage": "Before-optimization metrics for comparison",
+      "scope": "shared (fan-out) / per-pipeline (independent)"
+    },
+    {
+      "name": "Bottleneck Report",
+      "path": "<session>/artifacts/bottleneck-report.md",
+      "usage": "Profiler output consumed by strategist",
+      "scope": "shared (fan-out) / per-pipeline (independent)"
+    },
+    {
+      "name": "Optimization Plan",
+      "path": "<session>/artifacts/optimization-plan.md",
+      "usage": "Strategist output consumed by optimizer",
+      "scope": "shared (fan-out) / per-pipeline (independent)"
+    },
+    {
+      "name": "Benchmark Results",
+      "path": "<session>/artifacts/benchmark-results.json",
+      "usage": "Benchmarker output consumed by reviewer",
+      "scope": "per-branch (fan-out) / per-pipeline (independent)"
+    }
+  ],
+
+  "shared_memory_namespacing": {
+    "single": {
+      "profiler": "profiler",
+      "strategist": "strategist",
+      "optimizer": "optimizer",
+      "benchmarker": "benchmarker",
+      "reviewer": "reviewer"
+    },
+    "fan-out": {
+      "profiler": "profiler",
+      "strategist": "strategist",
+      "optimizer": "optimizer.B{NN}",
+      "benchmarker": "benchmarker.B{NN}",
+      "reviewer": "reviewer.B{NN}"
+    },
+    "independent": {
+      "profiler": "profiler.{P}",
+      "strategist": "strategist.{P}",
+      "optimizer": "optimizer.{P}",
+      "benchmarker": "benchmarker.{P}",
+      "reviewer": "reviewer.{P}"
+    }
+  }
+}

package/.agents/skills/team-planex/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: team-planex
+description: Unified team skill for plan-and-execute pipeline. Pure router — coordinator always. Beat model is coordinator-only in monitor.md. Triggers on "team planex".
+allowed-tools: agent(*), task_create(*), task_list(*), task_get(*), task_update(*), team_create(*), team_delete(*), send_message(*), ask_user_question(*), read(*), write(*), edit(*), bash(*), glob(*), grep(*), mcp__maestro__team_msg(*)
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Team PlanEx
+
+Unified team skill: plan-and-execute pipeline for issue-based development. Built on **team-worker agent architecture** — coordinator orchestrates, workers are team-worker agents loading role-specific instructions from `roles/<role>/role.md`.
+
+## Architecture
+
+```
+invoke_skill(skill="team-planex", 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
+               [planner]                       [executor]
+         (team-worker agent,            (team-worker agent,
+          loads roles/planner/role.md)   loads roles/executor/role.md)
+```
+
+## Role Registry
+
+| Role | Path | Prefix | Inner Loop |
+|------|------|--------|------------|
+| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
+| planner | [roles/planner/role.md](roles/planner/role.md) | PLAN-* | true |
+| executor | [roles/executor/role.md](roles/executor/role.md) | EXEC-* | true |
+
+
+## Pre-load (coordinator, before dispatch)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for module boundaries
+2. **Specs (arch)**: `maestro spec load --category arch` — load arch constraints as shared context
+3. **Specs (coding)**: `maestro spec load --category coding` — load coding constraints as shared context
+4. **Wiki knowledge**: `maestro search "plan execute implementation" --json` — top 5 entries as prior context
+5. All optional — proceed without if unavailable
+## 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**: `PEX`
+- **Session path**: `.workflow/.team/PEX-<slug>-<date>/`
+- **CLI tools**: `maestro delegate --mode analysis` (read-only), `maestro delegate --mode write` (modifications)
+- **Message bus**: `mcp__maestro__team_msg(session_id=<session-id>, ...)`
+
+## Worker Spawn Template
+
+Coordinator spawns workers using this template:
+
+```
+delegate_subagent({
+  subagent_type: "team-worker",
+  description: "Spawn <role> worker",
+  team_name: "planex",
+  name: "<role>",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: <role>
+role_spec: <skill_root>/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: planex
+requirement: <task-description>
+inner_loop: <true|false>
+execution_method: <codex|gemini>
+
+## Progress Milestones
+session_id: <session-id>
+Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
+Report blockers immediately via team_msg type="blocker".
+Report completion via team_msg type="task_complete" after final send_message.
+
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
+})
+```
+
+## User Commands
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View execution status graph |
+| `resume` / `continue` | Advance to next step |
+| `add <issue-ids or --text '...' or --plan path>` | Append new tasks to planner queue |
+
+## Session Directory
+
+```
+.workflow/.team/PEX-<slug>-<YYYY-MM-DD>/
+├── .msg/
+│   ├── messages.jsonl          # Message bus log
+│   └── meta.json               # Session state
+├── task-analysis.json          # Coordinator analyze output
+├── artifacts/
+│   └── solutions/              # Planner solution output per issue
+│       ├── <issueId-1>.json
+│       └── <issueId-N>.json
+└── wisdom/                     # Cross-task knowledge
+    ├── learnings.md
+    ├── decisions.md
+    ├── conventions.md
+    └── issues.md
+```
+
+## Specs Reference
+
+- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions, task metadata registry, execution method selection
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Unknown command | Error with available command list |
+| Role not found | Error with role registry |
+| Role spec file not found | Error with expected path (roles/<name>/role.md) |
+| team-worker agent unavailable | Error: requires .claude/agents/team-worker.md |
+| Planner issue planning failure | Retry once, then skip to next issue |
+| Executor impl failure | Report to coordinator, continue with next EXEC-* task |
+| Pipeline stall | Coordinator monitors, escalate to user |
+| Worker no response | Report waiting task, suggest user `resume` |

package/.agents/skills/team-planex/roles/coordinator/commands/analyze.md

@@ -0,0 +1,52 @@
+# Analyze Task
+
+Parse plan-and-execute input -> detect input type -> determine execution method -> assess scope.
+
+**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
+
+## Signal Detection
+
+| Input Pattern | Type | Action |
+|--------------|------|--------|
+| `ISS-\d{8}-\d{6}` pattern | Issue IDs | Use directly |
+| `--text '...'` flag | Text requirement | Create issues via CLI |
+| `--plan <path>` flag | Plan file | Read file, parse phases |
+
+## Execution Method Selection
+
+| Condition | Execution Method |
+|-----------|-----------------|
+| `--exec=codex` specified | Codex |
+| `--exec=gemini` specified | Gemini |
+| `-y` or `--yes` flag present | Auto (default Gemini) |
+| No flags (interactive) | ask_user -> user choice |
+| Auto + task_count <= 3 | Gemini |
+| Auto + task_count > 3 | Codex |
+
+## Scope Assessment
+
+| Factor | Complexity |
+|--------|------------|
+| Issue count 1-3 | Low |
+| Issue count 4-10 | Medium |
+| Issue count > 10 | High |
+| Cross-cutting concern | +1 level |
+
+## Output
+
+Write <session>/task-analysis.json:
+```json
+{
+  "task_description": "<original>",
+  "input_type": "<issues|text|plan>",
+  "raw_input": "<original input>",
+  "execution_method": "<codex|gemini>",
+  "issue_count_estimate": 0,
+  "complexity": { "score": 0, "level": "Low|Medium|High" },
+  "pipeline_type": "plan-execute",
+  "roles": [
+    { "name": "planner", "prefix": "PLAN", "inner_loop": true },
+    { "name": "executor", "prefix": "EXEC", "inner_loop": true }
+  ]
+}
+```