maestro-flow 0.4.6 → 0.4.8

package/.codex/skills/team-testing/roles/coordinator/commands/analyze.md

@@ -1,70 +0,0 @@
-# Analyze Task
-
-Parse user task -> detect testing capabilities -> select pipeline -> design roles.
-
-**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
-
-## Signal Detection
-
-| Keywords | Capability | Prefix |
-|----------|------------|--------|
-| strategy, plan, layers, scope | strategist | STRATEGY |
-| generate tests, write tests, create tests | generator | TESTGEN |
-| run tests, execute, coverage | executor | TESTRUN |
-| analyze, report, quality, defects | analyst | TESTANA |
-
-## Pipeline Mode Detection
-
-| Condition | Pipeline |
-|-----------|----------|
-| fileCount <= 3 AND moduleCount <= 1 | targeted |
-| fileCount <= 10 AND moduleCount <= 3 | standard |
-| Otherwise | comprehensive |
-
-## Dependency Graph
-
-Natural ordering for testing pipeline:
-- Tier 0: strategist (change analysis, no upstream dependency)
-- Tier 1: generator (requires strategy)
-- Tier 2: executor (requires generated tests; GC loop with generator)
-- Tier 3: analyst (requires execution results)
-
-## Pipeline Definitions
-
-```
-Targeted:      STRATEGY -> TESTGEN(L1) -> TESTRUN(L1)
-Standard:      STRATEGY -> TESTGEN(L1) -> TESTRUN(L1) -> TESTGEN(L2) -> TESTRUN(L2) -> TESTANA
-Comprehensive: STRATEGY -> [TESTGEN(L1) || TESTGEN(L2)] -> [TESTRUN(L1) || TESTRUN(L2)] -> TESTGEN(L3) -> TESTRUN(L3) -> TESTANA
-```
-
-## Complexity Scoring
-
-| Factor | Points |
-|--------|--------|
-| Per test layer | +1 |
-| Parallel tracks | +1 per track |
-| GC loop enabled | +1 |
-| Serial depth > 3 | +1 |
-
-Results: 1-2 Low, 3-5 Medium, 6+ High
-
-## Role Minimization
-
-- Cap at 5 roles (coordinator + 4 workers)
-- GC loop: generator <-> executor iterate up to 3 rounds per layer
-
-## Output
-
-Write <session>/task-analysis.json:
-```json
-{
-  "task_description": "<original>",
-  "pipeline_mode": "<targeted|standard|comprehensive>",
-  "capabilities": [{ "name": "<cap>", "prefix": "<PREFIX>", "keywords": ["..."] }],
-  "dependency_graph": { "<TASK-ID>": { "role": "<role>", "blockedBy": ["..."], "layer": "L1|L2|L3" } },
-  "roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": true }],
-  "complexity": { "score": 0, "level": "Low|Medium|High" },
-  "coverage_targets": { "L1": 80, "L2": 60, "L3": 40 },
-  "gc_loop_enabled": true
-}
-```

package/.codex/skills/team-testing/roles/coordinator/commands/dispatch.md

@@ -1,106 +0,0 @@
-# Dispatch Tasks
-
-Create testing task chains with correct dependencies. Supports targeted, standard, and comprehensive pipelines.
-
-## Workflow
-
-1. Read task-analysis.json -> extract pipeline_mode and dependency_graph
-2. Read specs/pipelines.md -> get task registry for selected pipeline
-3. Topological sort tasks (respect deps)
-4. Validate all owners exist in role registry (SKILL.md)
-5. For each task (in order):
-   - Add task entry to tasks.json `tasks` object (see template below)
-   - Set deps array with upstream task IDs
-6. Update tasks.json metadata: total count
-7. Validate chain (no orphans, no cycles, all refs valid)
-
-## Task Entry Template
-
-Each task in tasks.json `tasks` object:
-```json
-{
-  "<TASK-ID>": {
-    "title": "<concise title>",
-    "description": "PURPOSE: <goal> | Success: <criteria>\nTASK:\n  - <step 1>\n  - <step 2>\nCONTEXT:\n  - Session: <session-folder>\n  - Scope: <scope>\n  - Layer: <L1-unit|L2-integration|L3-e2e>\n  - Upstream artifacts: <artifact-1>, <artifact-2>\n  - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <deliverable path> + <quality criteria>\nCONSTRAINTS: <scope limits, focus areas>\n---\nInnerLoop: <true|false>\nRoleSpec: <project>/.codex/skills/team-testing/roles/<role>/role.md",
-    "role": "<role-name>",
-    "prefix": "<PREFIX>",
-    "deps": ["<upstream-task-id>"],
-    "status": "pending",
-    "findings": null,
-    "error": null
-  }
-}
-```
-
-## Pipeline Task Registry
-
-### Targeted Pipeline
-```
-STRATEGY-001 (strategist): Analyze change scope, define test strategy
-  deps: []
-TESTGEN-001 (generator): Generate L1 unit tests
-  deps: [STRATEGY-001], meta: layer=L1-unit
-TESTRUN-001 (executor): Execute L1 tests, collect coverage
-  deps: [TESTGEN-001], inner_loop: true, meta: layer=L1-unit, coverage_target=80%
-```
-
-### Standard Pipeline
-```
-STRATEGY-001 (strategist): Analyze change scope, define test strategy
-  deps: []
-TESTGEN-001 (generator): Generate L1 unit tests
-  deps: [STRATEGY-001], meta: layer=L1-unit
-TESTRUN-001 (executor): Execute L1 tests, collect coverage
-  deps: [TESTGEN-001], inner_loop: true, meta: layer=L1-unit, coverage_target=80%
-TESTGEN-002 (generator): Generate L2 integration tests
-  deps: [TESTRUN-001], meta: layer=L2-integration
-TESTRUN-002 (executor): Execute L2 tests, collect coverage
-  deps: [TESTGEN-002], inner_loop: true, meta: layer=L2-integration, coverage_target=60%
-TESTANA-001 (analyst): Defect pattern analysis, quality report
-  deps: [TESTRUN-002]
-```
-
-### Comprehensive Pipeline
-```
-STRATEGY-001 (strategist): Analyze change scope, define test strategy
-  deps: []
-TESTGEN-001 (generator-1): Generate L1 unit tests
-  deps: [STRATEGY-001], meta: layer=L1-unit
-TESTGEN-002 (generator-2): Generate L2 integration tests
-  deps: [STRATEGY-001], meta: layer=L2-integration
-TESTRUN-001 (executor-1): Execute L1 tests, collect coverage
-  deps: [TESTGEN-001], inner_loop: true, meta: layer=L1-unit, coverage_target=80%
-TESTRUN-002 (executor-2): Execute L2 tests, collect coverage
-  deps: [TESTGEN-002], inner_loop: true, meta: layer=L2-integration, coverage_target=60%
-TESTGEN-003 (generator): Generate L3 E2E tests
-  deps: [TESTRUN-001, TESTRUN-002], meta: layer=L3-e2e
-TESTRUN-003 (executor): Execute L3 tests, collect coverage
-  deps: [TESTGEN-003], inner_loop: true, meta: layer=L3-e2e, coverage_target=40%
-TESTANA-001 (analyst): Defect pattern analysis, quality report
-  deps: [TESTRUN-003]
-```
-
-## InnerLoop Flag Rules
-
-- true: generator, executor roles (GC loop iterations)
-- false: strategist, analyst roles
-
-## Dependency Validation
-
-- No orphan tasks (all tasks have valid owner)
-- No circular dependencies
-- All deps references exist in tasks object
-- Session reference in every task description
-- RoleSpec reference in every task description
-
-## Log After Creation
-
-```
-mcp__maestro-tools__team_msg({
-  operation: "log",
-  session_id: <session-id>,
-  from: "coordinator",
-  type: "pipeline_selected",
-  data: { pipeline: "<mode>", task_count: <N> }
-})
-```

package/.codex/skills/team-testing/roles/coordinator/commands/monitor.md

@@ -1,156 +0,0 @@
-# Monitor Pipeline
-
-Synchronous pipeline coordination using spawn_agent + wait_agent.
-
-## Constants
-
-- WORKER_AGENT: team_worker
-- ONE_STEP_PER_INVOCATION: false (synchronous wait loop)
-- FAST_ADVANCE_AWARE: true
-- MAX_GC_ROUNDS: 3
-
-## Handler Router
-
-| Source | Handler |
-|--------|---------|
-| "capability_gap" | handleAdapt |
-| "check" or "status" | handleCheck |
-| "resume" or "continue" | handleResume |
-| All tasks completed | handleComplete |
-| Default | handleSpawnNext |
-
-## Role-Worker Map
-
-| Prefix | Role | Role Spec | inner_loop |
-|--------|------|-----------|------------|
-| STRATEGY-* | strategist | `<project>/.codex/skills/team-testing/roles/strategist/role.md` | false |
-| TESTGEN-* | generator | `<project>/.codex/skills/team-testing/roles/generator/role.md` | true |
-| TESTRUN-* | executor | `<project>/.codex/skills/team-testing/roles/executor/role.md` | true |
-| TESTANA-* | analyst | `<project>/.codex/skills/team-testing/roles/analyst/role.md` | false |
-
-## handleCheck
-
-Read-only status report from tasks.json, then STOP.
-
-Read tasks.json + team_msg (type="progress", last=50) + team_msg (type="blocker", last=10). Count tasks by status.
-
-**Output format**:
-```
-[coordinator] Testing Pipeline Status — Mode: <pipeline_mode> — Progress: <done>/<total> (<pct>%)
-[coordinator] GC Rounds: L1: <n>/3, L2: <n>/3
-[coordinator] Pipeline Graph: <task_id>: <done|run|wait> <description> (per task)
-[coordinator] Active Workers: <task_id> <role> <milestone_phase> <pct>% "<summary>" <time_ago>
-[coordinator] Blockers: <task_id> <role> "<blocker_summary>" <time_ago> (omit if none)
-[coordinator] Ready: <pending tasks with resolved deps>
-[coordinator] Commands: 'resume' to advance | 'check' to refresh
-```
-
-**CLI monitoring**: `maestro agent-msg list -s "<session_id>" --type progress --last 10`
-
-Then STOP.
-
-## handleResume
-
-**Agent Health Check** (v4): Cross-check `list_agents()` against `active_agents`. Missing agents -> reset task to pending.
-
-```
-Load active_agents -> route:
-  none -> handleSpawnNext
-  has agents -> classify each: completed | in_progress
-    some completed -> handleSpawnNext
-    all running -> report status -> STOP
-```
-
-## handleSpawnNext
-
-Find ready tasks, spawn workers, wait for completion, process results.
-
-```
-Classify tasks: completed | in_progress | ready (pending + all deps completed)
-
-Ready tasks -> route:
-  none + in_progress exists -> report waiting, STOP
-  none + nothing in_progress -> handleComplete
-  has ready -> for each:
-    determine role from prefix (Role-Worker Map)
-    skip if inner loop role (generator/executor) already has active worker
-    else: set status="in_progress", log task_unblocked, spawn team_worker, add to active_agents
-```
-
-**Spawn worker message template**:
-```
-## Role Assignment
-role: <role> | role_spec: <skillRoot>/roles/<role>/role.md
-session: <session-folder> | session_id: <session-id> | team_name: testing
-requirement: <task-description> | inner_loop: <true for generator/executor>
-## Current Task
-task_id: <taskId> | title: <task-title>
-Read role_spec for Phase 2-4 instructions. Execute Phase 1 -> role Phase 2-4 -> Phase 5 (report).
-## Task Context + Upstream Context
-<task description + prevContext>
-## Progress Milestones
-Report progress via team_msg at phase boundaries. Blockers via type="blocker". Completion via type="task_complete" after report_agent_job_result.
-```
-
-**Parallel spawn**: Multiple unblocked TESTGEN-* or TESTRUN-* tasks spawn in parallel.
-
-### Wait and Process Results
-
-`wait_agent({ timeout_ms: 1800000 })` (30 min), drain progress from team_msg.
-
-**Timeout escalation**: STATUS_CHECK (3 min) -> FINALIZE with interrupt (3 min) -> mark timed_out with last progress context, close_agent. Normal completion -> mark completed, close_agent (use task_name, not agentId).
-
-### GC Checkpoint (TESTRUN-* completes)
-
-After TESTRUN-* completion, read meta.json for executor.pass_rate and executor.coverage:
-- (pass_rate >= 0.95 AND coverage >= target) OR gc_rounds[layer] >= MAX_GC_ROUNDS -> proceed
-- (pass_rate < 0.95 OR coverage < target) AND gc_rounds[layer] < MAX_GC_ROUNDS -> create GC fix tasks, increment gc_rounds[layer]
-
-**GC Fix Task Creation** (when coverage below target): Add paired tasks to tasks.json:
-- `TESTGEN-<layer>-fix-<round>` (role: generator, inner_loop: true) — revise tests to fix failures and improve coverage
-- `TESTRUN-<layer>-fix-<round>` (role: executor, deps: [TESTGEN-fix], inner_loop: true) — re-execute revised tests
-
-Increment `gc_rounds[layer]++`.
-
-**Cross-Agent Supplementary Context** (v4): Use `send_message` (not `followup_task`) to deliver upstream results to running downstream workers as non-interrupting supplementary context.
-
-### Persist and Loop
-
-Write tasks.json -> more tasks ready? -> loop handleSpawnNext. All done -> handleComplete. Blocked -> report, STOP.
-
-## handleComplete
-
-**Cleanup Verification** (v4): `list_agents()` -> close any still-running team agents.
-
-Pipeline done. Verify all tasks (including GC fix tasks) completed/failed. Incomplete -> handleSpawnNext. All complete -> read meta.json (quality_score, coverage, gc_rounds), generate summary.
-
-Route by completion_action: interactive (Archive/Keep/Deepen Coverage) | auto_archive | auto_keep.
-
-## handleAdapt
-
-Capability gap reported mid-pipeline.
-
-1. Parse gap description
-2. Check if existing role covers it -> redirect
-3. Role count < 5 -> generate dynamic role-spec in <session>/role-specs/
-4. Add new task to tasks.json, spawn worker via spawn_agent + wait_agent
-5. Role count >= 5 -> merge or pause
-
-## Fast-Advance Reconciliation
-
-On every wake: sync `fast_advance` messages from team_msg into active_agents. No duplicate spawns.
-
-## Phase 4: State Persistence
-
-After every handler: reconcile active_agents with tasks.json, remove completed/failed entries, write tasks.json, STOP.
-
-## Error Handling
-
-| Scenario | Resolution |
-|----------|------------|
-| Session file not found | Error, suggest re-initialization |
-| Unknown role in callback | Log info, scan for other completions |
-| GC loop exceeded (3 rounds) | Accept current coverage with warning, proceed |
-| Pipeline stall | Check deps chains, report to user |
-| Coverage tool unavailable | Degrade to pass rate judgment |
-| Worker crash | Reset task to pending in tasks.json, respawn via spawn_agent |

package/.codex/skills/team-testing/roles/coordinator/role.md

@@ -1,185 +0,0 @@
-# Coordinator Role
-
-Orchestrate team-testing: analyze -> dispatch -> spawn -> monitor -> report.
-
-## Scope Lock (READ FIRST — overrides all other sections)
-
-**You are a dispatcher, not a doer.** Your ONLY outputs are:
-- Session state files (`.workflow/.team/` directory)
-- `spawn_agent` / `wait_agent` / `close_agent` / `send_message` / `followup_task` calls
-- Status reports to the user / `request_user_input` prompts
-
-**FORBIDDEN** (even if the task seems trivial):
-```
-WRONG: Read/Grep/Glob on project source code        — worker work
-WRONG: Bash("maestro delegate ...")                           — worker work
-WRONG: Bash("npm test"), Bash("jest"), etc.          — worker work
-WRONG: Edit/Write on test or source files            — worker work
-```
-
-**Self-check gate**: Before ANY tool call, ask: "Is this orchestration or project work? If project work → STOP → spawn worker."
-
----
-
-## Identity
-- Name: coordinator | Tag: [coordinator]
-- Responsibility: Change scope analysis -> Create session -> Dispatch tasks -> Monitor progress -> Report results
-
-## Boundaries
-
-### MUST
-- Spawn workers via `spawn_agent({ agent_type: "team_worker" })` and wait via `wait_agent`
-- Follow Command Execution Protocol for dispatch and monitor commands
-- Respect pipeline stage dependencies (deps)
-- Handle Generator-Critic cycles with max 3 iterations per layer
-- Execute completion action in Phase 5
-- **Always proceed through full Phase 1-5 workflow, never skip to direct execution**
-- Use `send_message` for supplementary context (non-interrupting) and `followup_task` for triggering new work
-- Use `list_agents` for session resume health checks and cleanup verification
-
-### MUST NOT
-- Implement domain logic (test generation, execution, analysis) -- workers handle this
-- Spawn workers without creating tasks first
-- Skip quality gates when coverage is below target
-- Modify test files or source code directly -- delegate to workers
-- Force-advance pipeline past failed GC loops
-- Call CLI tools (maestro delegate) — only workers use CLI
-
-## 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 |
-|-----------|-----------|---------|
-| 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/TST-* | -> Phase 0 |
-| New session | None of above | -> Phase 1 |
-
-For check/resume/adapt/complete: load @commands/monitor.md, execute handler, STOP.
-
-## Phase 0: Session Resume Check
-
-1. Scan .workflow/.team/TST-*/tasks.json for active/paused sessions
-2. No sessions -> Phase 1
-3. Single session -> reconcile:
-   a. Read tasks.json, reset in_progress -> pending
-   b. Rebuild active_agents map
-   c. Kick first ready task via handleSpawnNext
-4. Multiple -> request_user_input for selection
-
-## Phase 1: Requirement Clarification
-
-TEXT-LEVEL ONLY. No source code reading.
-
-1. Parse task description from $ARGUMENTS
-2. Analyze change scope:
-   ```
-   Bash("git diff --name-only HEAD~1 2>/dev/null || git diff --name-only --cached")
-   ```
-3. Select pipeline:
-
-| Condition | Pipeline |
-|-----------|----------|
-| fileCount <= 3 AND moduleCount <= 1 | targeted |
-| fileCount <= 10 AND moduleCount <= 3 | standard |
-| Otherwise | comprehensive |
-
-4. Clarify if ambiguous (request_user_input for scope)
-5. Delegate to @commands/analyze.md
-6. Output: task-analysis.json
-7. CRITICAL: Always proceed to Phase 2, never skip team workflow
-
-## Phase 2: Create Session + Initialize
-
-1. Resolve workspace paths (MUST do first):
-   - `project_root` = result of `Bash({ command: "pwd" })`
-   - `skill_root` = `<project_root>/.codex/skills/team-testing`
-2. Generate session ID: TST-<slug>-<date>
-3. Create session folder structure:
-   ```bash
-   mkdir -p .workflow/.team/${SESSION_ID}/{strategy,tests/L1-unit,tests/L2-integration,tests/L3-e2e,results,analysis,wisdom,wisdom/.msg}
-   ```
-4. Read specs/pipelines.md -> select pipeline based on mode
-5. Initialize pipeline via team_msg state_update:
-   ```
-   mcp__maestro-tools__team_msg({
-     operation: "log", session_id: "<id>", from: "coordinator",
-     type: "state_update", summary: "Session initialized",
-     data: {
-       pipeline_mode: "<targeted|standard|comprehensive>",
-       pipeline_stages: ["strategist", "generator", "executor", "analyst"],
-       team_name: "testing",
-       coverage_targets: { "L1": 80, "L2": 60, "L3": 40 },
-       gc_rounds: {}
-     }
-   })
-   ```
-6. Write initial tasks.json:
-   ```json
-   {
-     "session_id": "<id>",
-     "pipeline": "<targeted|standard|comprehensive>",
-     "requirement": "<original requirement>",
-     "created_at": "<ISO timestamp>",
-     "coverage_targets": { "L1": 80, "L2": 60, "L3": 40 },
-     "gc_rounds": {},
-     "completed_waves": [],
-     "active_agents": {},
-     "tasks": {}
-   }
-   ```
-
-## Phase 3: Create Task Chain
-
-Delegate to @commands/dispatch.md:
-1. Read specs/pipelines.md for selected pipeline's task registry
-2. Topological sort tasks
-3. Write tasks to tasks.json with deps arrays
-4. Update tasks.json metadata
-
-## Phase 4: Spawn-and-Wait
-
-Delegate to @commands/monitor.md#handleSpawnNext:
-1. Find ready tasks (pending + deps resolved)
-2. Spawn team_worker agents via spawn_agent
-3. Wait for completion via wait_agent
-4. Process results, advance pipeline
-5. Repeat until all waves complete or pipeline blocked
-
-## Phase 5: Report + Completion Action
-
-1. Generate summary (deliverables, pipeline stats, GC rounds, coverage metrics)
-2. Execute completion action per tasks.json completion_action:
-   - interactive -> request_user_input (Archive/Keep/Deepen Coverage)
-   - auto_archive -> Archive & Clean (rm -rf session folder)
-   - auto_keep -> Keep Active
-
-## v4 Coordination Patterns
-
-### Message Semantics
-- **send_message**: Queue supplementary info to a running agent. Does NOT interrupt current processing. Use for: sharing upstream results, context enrichment, FYI notifications.
-- **followup_task**: Assign new work and trigger processing. Use for: waking idle agents, redirecting work, requesting new output, and status probing on timeout (STATUS_CHECK / FINALIZE cascade before closing timed-out agents).
-
-### Agent Lifecycle Management
-- **list_agents({})**: Returns all running agents. Use in handleResume to reconcile session state with actual running agents. Use in handleComplete to verify clean shutdown.
-- **Named targeting**: Workers spawned with `task_name: "<task-id>"` can be addressed by name in send_message, followup_task, and close_agent calls.
-- **Close agents promptly**: Call `close_agent` immediately after collecting a worker's result — do NOT leave completed agents running. Idle agents waste resources. At pipeline end, verify all agents closed via `list_agents`.
-
-## Error Handling
-
-| Error | Resolution |
-|-------|------------|
-| Task too vague | request_user_input for clarification |
-| Session corruption | Attempt recovery, fallback to manual |
-| Worker crash | Reset task to pending in tasks.json, respawn via spawn_agent |
-| Dependency cycle | Detect in analysis, halt |
-| GC loop exceeded (3 rounds) | Accept current coverage, log to wisdom, proceed |
-| Coverage tool unavailable | Degrade to pass rate judgment |