maestro-flow 0.4.9 → 0.4.11

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

@@ -0,0 +1,149 @@
+---
+name: team-review
+description: "Unified team skill for code review. 3-role pipeline: scanner, reviewer, fixer. Triggers on team-review."
+allowed-tools: team_create(*), team_delete(*), send_message(*), task_create(*), task_update(*), task_list(*), task_get(*), agent(*), ask_user_question(*), read(*), write(*), edit(*), bash(*), glob(*), grep(*), mcp__ace-tool__search_context(*), mcp__ccw-tools__team_msg(*)
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Team Review
+
+Orchestrate multi-agent code review: scanner -> reviewer -> fixer. Toolchain + LLM scan, deep analysis with root cause enrichment, and automated fix with rollback-on-failure.
+
+## Architecture
+
+```
+invoke_skill(skill="team-review", 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
+                [scan]  [review]  [fix]
+                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) | — | — |
+| scanner | [roles/scanner/role.md](roles/scanner/role.md) | SCAN-* | false |
+| reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | REV-* | false |
+| fixer | [roles/fixer/role.md](roles/fixer/role.md) | FIX-* | true |
+
+## 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**: `RV`
+- **Session path**: `.workflow/.team/RV-<slug>-<date>/`
+- **Team name**: `review`
+- **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:
+
+```
+delegate_subagent({
+  subagent_type: "team-worker",
+  description: "Spawn <role> worker",
+  team_name: "review",
+  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: review
+requirement: <task-description>
+inner_loop: <true|false>
+
+## 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 pipeline status graph |
+| `resume` / `continue` | Advance to next step |
+| `--full` | Enable scan + review + fix pipeline |
+| `--fix` | Fix-only mode (skip scan/review) |
+| `-q` / `--quick` | Quick scan only |
+| `--dimensions=sec,cor,prf,mnt` | Custom dimensions |
+| `-y` / `--yes` | Skip confirmations |
+
+## Completion Action
+
+When pipeline completes, coordinator presents:
+
+```
+ask_user({
+  questions: [{
+    question: "Review 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/RV-<slug>-<date>/
+├── .msg/messages.jsonl     # Team message bus
+├── .msg/meta.json          # Session state + cross-role state
+├── wisdom/                 # Cross-task knowledge
+├── scan/                   # Scanner output
+├── review/                 # Reviewer output
+└── fix/                    # Fixer output
+```
+
+## Specs Reference
+
+- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
+- [specs/dimensions.md](specs/dimensions.md) — Review dimension definitions (SEC/COR/PRF/MNT)
+- [specs/finding-schema.json](specs/finding-schema.json) — Finding data schema
+- [specs/team-config.json](specs/team-config.json) — Team configuration
+
+## 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 |
+| Scanner finds 0 findings | Report clean, skip review + fix |
+| User declines fix | Delete FIX tasks, complete with review-only results |
+| Fast-advance conflict | Coordinator reconciles on next callback |
+| Completion action fails | Default to Keep Active |

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

@@ -0,0 +1,71 @@
+# Analyze Task
+
+Parse user task -> detect review capabilities -> build dependency graph -> design pipeline.
+
+**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
+
+## Signal Detection
+
+| Keywords | Capability | Prefix |
+|----------|------------|--------|
+| scan, lint, static analysis, toolchain | scanner | SCAN |
+| review, analyze, audit, findings | reviewer | REV |
+| fix, repair, remediate, patch | fixer | FIX |
+
+## Pipeline Mode Detection
+
+| Condition | Mode |
+|-----------|------|
+| Flag `--fix` | fix-only |
+| Flag `--full` | full |
+| Flag `-q` or `--quick` | quick |
+| (none) | default |
+
+## Dependency Graph
+
+Natural ordering for review pipeline:
+- Tier 0: scanner (toolchain + semantic scan, no upstream dependency)
+- Tier 1: reviewer (deep analysis, requires scan findings)
+- Tier 2: fixer (apply fixes, requires reviewed findings + user confirm)
+
+## Pipeline Definitions
+
+```
+quick:    SCAN(quick=true)
+default:  SCAN -> REV
+full:     SCAN -> REV -> [user confirm] -> FIX
+fix-only: FIX
+```
+
+## Complexity Scoring
+
+| Factor | Points |
+|--------|--------|
+| Per capability | +1 |
+| Large target scope (>20 files) | +2 |
+| Multiple dimensions | +1 |
+| Fix phase included | +1 |
+
+Results: 1-2 Low, 3-4 Medium, 5+ High
+
+## Role Minimization
+
+- Cap at 4 roles (coordinator + 3 workers)
+- Sequential pipeline: scanner -> reviewer -> fixer
+
+## Output
+
+Write <session>/task-analysis.json:
+```json
+{
+  "task_description": "<original>",
+  "pipeline_mode": "<quick|default|full|fix-only>",
+  "target": "<path>",
+  "dimensions": ["sec", "cor", "prf", "mnt"],
+  "auto_confirm": false,
+  "capabilities": [{ "name": "<cap>", "prefix": "<PREFIX>" }],
+  "dependency_graph": { "<TASK-ID>": { "role": "<role>", "blockedBy": ["..."] } },
+  "roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
+  "complexity": { "score": 0, "level": "Low|Medium|High" }
+}
+```

package/.agents/skills/team-review/roles/coordinator/commands/dispatch.md

@@ -0,0 +1,91 @@
+# Dispatch Tasks
+
+Create task chains from pipeline mode with proper blockedBy relationships.
+
+## Workflow
+
+1. Read task-analysis.json -> extract pipeline_mode and parameters
+2. Read specs/pipelines.md -> get task registry for selected pipeline
+3. Topological sort tasks (respect blockedBy)
+4. Validate all owners exist in role registry (SKILL.md)
+5. For each task (in order):
+   - create_task with structured description (see template below)
+   - update_task with blockedBy + owner assignment
+6. Update session meta.json with pipeline.tasks_total
+7. Validate chain (no orphans, no cycles, all refs valid)
+
+## Task Description Template
+
+```
+PURPOSE: <goal> | Success: <criteria>
+TASK:
+  - <step 1>
+  - <step 2>
+CONTEXT:
+  - Session: <session-folder>
+  - Target: <target>
+  - Dimensions: <dimensions>
+  - Upstream artifacts: <list>
+EXPECTED: <artifact path> + <quality criteria>
+CONSTRAINTS: <scope limits>
+---
+InnerLoop: <true|false>
+RoleSpec: ~  or <project>/.claude/skills/team-review/roles/<role>/role.md
+```
+
+## Pipeline Task Registry
+
+### default Mode
+```
+SCAN-001 (scanner): Multi-dimension code scan
+  blockedBy: [], meta: target=<target>, dimensions=<dims>
+REV-001 (reviewer): Deep finding analysis and review
+  blockedBy: [SCAN-001]
+```
+
+### full Mode
+```
+SCAN-001 (scanner): Multi-dimension code scan
+  blockedBy: [], meta: target=<target>, dimensions=<dims>
+REV-001 (reviewer): Deep finding analysis and review
+  blockedBy: [SCAN-001]
+FIX-001 (fixer): Plan and execute fixes
+  blockedBy: [REV-001]
+```
+
+### fix-only Mode
+```
+FIX-001 (fixer): Execute fixes from manifest
+  blockedBy: [], meta: input=<fix-manifest>
+```
+
+### quick Mode
+```
+SCAN-001 (scanner): Quick scan (fast mode)
+  blockedBy: [], meta: target=<target>, quick=true
+```
+
+## InnerLoop Flag Rules
+
+- true: fixer role (iterative fix cycles)
+- false: scanner, reviewer roles
+
+## Dependency Validation
+
+- No orphan tasks (all tasks have valid owner)
+- No circular dependencies
+- All blockedBy references exist
+- Session reference in every task description
+- RoleSpec reference in every task description
+
+## Log After Creation
+
+```
+mcp__ccw-tools__team_msg({
+  operation: "log",
+  session_id: <session-id>,
+  from: "coordinator",
+  type: "dispatch_ready",
+  data: { pipeline: "<mode>", task_count: <N>, target: "<target>" }
+})
+```

package/.agents/skills/team-review/roles/coordinator/commands/monitor.md

@@ -0,0 +1,224 @@
+# monitor_process Pipeline
+
+Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
+
+## Constants
+
+- SPAWN_MODE: background
+- ONE_STEP_PER_INVOCATION: true
+- FAST_ADVANCE_AWARE: true
+- WORKER_AGENT: team-worker
+
+## Handler Router
+
+| Source | Handler |
+|--------|---------|
+| Message contains [scanner], [reviewer], [fixer] | handleCallback |
+| "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 |
+|--------|------|-----------|------------|
+| SCAN-* | scanner | `~  or <project>/.claude/skills/team-review/roles/scanner/role.md` | false |
+| REV-* | reviewer | `~  or <project>/.claude/skills/team-review/roles/reviewer/role.md` | false |
+| FIX-* | fixer | `~  or <project>/.claude/skills/team-review/roles/fixer/role.md` | true |
+
+## handleCallback
+
+Worker completed. Verify completion, check pipeline conditions, advance.
+
+1. Parse message to identify role and task ID:
+
+| Message Pattern | Role Detection |
+|----------------|---------------|
+| `[scanner]` or task ID `SCAN-*` | scanner |
+| `[reviewer]` or task ID `REV-*` | reviewer |
+| `[fixer]` or task ID `FIX-*` | fixer |
+
+2. Check if progress update (inner loop) or final completion
+3. Progress -> update session state, STOP
+4. Completion -> mark task done via update_task(status="completed"), remove from active_workers
+5. Check for checkpoints:
+   - scanner completes -> read meta.json for findings_count:
+     - findings_count === 0 -> delete remaining REV-*/FIX-* tasks -> handleComplete
+     - findings_count > 0 -> proceed to handleSpawnNext
+   - reviewer completes AND pipeline_mode === 'full':
+     - autoYes flag set -> write fix-manifest.json, set fix_scope='all' -> handleSpawnNext
+     - NO autoYes -> ask_user:
+       ```
+       question: "<N> findings reviewed. Proceed with fix?"
+       options:
+         - "Fix all": set fix_scope='all'
+         - "Fix critical/high only": set fix_scope='critical,high'
+         - "Skip fix": delete FIX-* tasks -> handleComplete
+       ```
+       Write fix_scope to meta.json, write fix-manifest.json, -> handleSpawnNext
+   - fixer completes -> handleSpawnNext (checks for completion naturally)
+
+6. -> handleSpawnNext
+
+## handleCheck
+
+Read-only status report, then STOP.
+
+**Worker Progress** (from message bus):
+
+Before generating status output, read worker milestones:
+
+```javascript
+const progressMsgs = mcp__ccw-tools__team_msg({
+  operation: "list", session_id: sessionId, type: "progress", last: 50
+})
+const blockerMsgs = mcp__ccw-tools__team_msg({
+  operation: "list", session_id: sessionId, type: "blocker", last: 10
+})
+
+// Aggregate latest milestone per task
+const taskProgress = {}
+for (const msg of (progressMsgs.result?.messages || [])) {
+  const tid = msg.data?.task_id
+  if (tid && (!taskProgress[tid] || msg.ts > taskProgress[tid].ts)) {
+    taskProgress[tid] = { phase: msg.data.phase, pct: msg.data.progress_pct, ts: msg.ts }
+  }
+}
+```
+
+Include in status output:
+- Per-worker latest milestone (phase + progress_pct) next to task status
+- Active blockers section (if any blockerMsgs found)
+
+Output:
+```
+[coordinator] Review Pipeline Status
+[coordinator] Mode: <pipeline_mode>
+[coordinator] Progress: <completed>/<total> (<percent>%)
+
+[coordinator] Pipeline Graph:
+  SCAN-001: <done|run|wait|deleted> <summary>
+  REV-001:  <done|run|wait|deleted> <summary>
+  FIX-001:  <done|run|wait|deleted> <summary>
+
+  done=completed  >>>=running  o=pending  x=deleted
+
+[coordinator] Active Workers: <list with elapsed time>
+[coordinator] Ready to spawn: <subjects>
+[coordinator] Commands: 'resume' to advance | 'check' to refresh
+```
+
+Then STOP.
+
+## handleResume
+
+1. No active workers -> handleSpawnNext
+2. Has active -> check each status
+   - completed -> mark done via update_task
+   - in_progress -> still running
+   - other -> worker failure -> reset to pending
+3. Some completed -> handleSpawnNext
+4. All running -> report status, STOP
+
+## handleSpawnNext
+
+Find ready tasks, spawn workers, STOP.
+
+1. Collect from list_tasks():
+   - completedSubjects: status = completed
+   - inProgressSubjects: status = in_progress
+   - deletedSubjects: status = deleted
+   - readySubjects: status = pending AND all blockedBy in completedSubjects
+
+2. No ready + work in progress -> report waiting, STOP
+3. No ready + nothing in progress -> handleComplete
+4. Has ready -> take first ready task:
+   a. Determine role from prefix (use Role-Worker Map)
+   b. update_task -> in_progress
+   c. team_msg log -> task_unblocked
+   d. Spawn team-worker:
+
+```
+delegate_subagent({
+  subagent_type: "team-worker",
+  description: "Spawn <role> worker for <subject>",
+  team_name: "review",
+  name: "<role>",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: <role>
+role_spec: ~  or <project>/.claude/skills/team-review/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: review
+requirement: <task-description>
+inner_loop: <true|false>
+
+## Current Task
+- Task ID: <task-id>
+- Task: <subject>
+
+## 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 to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
+})
+```
+
+   e. Add to active_workers
+5. Update session meta.json, output summary, STOP
+
+## handleComplete
+
+Pipeline done. Generate report and completion action.
+
+1. All tasks completed or deleted (no pending, no in_progress)
+2. Read final session state from meta.json
+3. Generate pipeline summary: mode, target, findings_count, stages_completed, fix results (if applicable), deliverable paths
+4. Update session: pipeline_status='complete', completed_at=<timestamp>
+5. Read session.completion_action:
+   - interactive -> ask_user (Archive/Keep/Export)
+   - auto_archive -> Archive & Clean (status=completed, delete_team)
+   - auto_keep -> Keep Active (status=paused)
+
+## handleAdapt
+
+Capability gap reported mid-pipeline.
+
+1. Parse gap description
+2. Check if existing role covers it -> redirect
+3. Role count < 4 -> generate dynamic role-spec in <session>/role-specs/
+4. Create new task, spawn worker
+5. Role count >= 4 -> merge or pause
+
+## Fast-Advance Reconciliation
+
+On every coordinator wake:
+1. Read team_msg entries with type="fast_advance"
+2. Sync active_workers with spawned successors
+3. No duplicate spawns
+
+## Phase 4: State Persistence
+
+After every handler execution:
+1. Reconcile active_workers with actual list_tasks states
+2. Remove entries for completed/deleted tasks
+3. Write updated meta.json
+4. STOP (wait for next callback)
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Session file not found | Error, suggest re-initialization |
+| Worker callback from unknown role | Log info, scan for other completions |
+| 0 findings after scan | Delete remaining stages, complete pipeline |
+| User declines fix | Delete FIX-* tasks, complete with review-only results |
+| Pipeline stall | Check blockedBy chains, report to user |
+| Worker failure | Reset task to pending, respawn on next resume |

package/.agents/skills/team-review/roles/coordinator/role.md

@@ -0,0 +1,132 @@
+# Coordinator Role
+
+Orchestrate team-review: parse target -> detect mode -> dispatch task chain -> monitor -> report.
+
+## Identity
+- Name: coordinator | Tag: [coordinator]
+- Responsibility: Target parsing, mode detection, task creation/dispatch, stage monitoring, result aggregation
+
+## Boundaries
+
+### MUST
+- All output prefixed with `[coordinator]`
+- Parse task description and detect pipeline mode
+- Create team and spawn team-worker agents in background
+- Dispatch task chain with proper dependencies
+- monitor_process progress via callbacks and route messages
+- Maintain session state
+- Execute completion action when pipeline finishes
+
+### MUST NOT
+- Run analysis tools directly (semgrep, eslint, tsc, etc.)
+- Modify source code files
+- Perform code review or scanning directly
+- Bypass worker roles
+- Spawn workers with general-purpose agent (MUST use team-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 [scanner], [reviewer], [fixer] | -> 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/RV-* | -> 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/RV-*/.msg/meta.json for active/paused sessions
+2. No sessions -> Phase 1
+3. Single session -> reconcile (audit list_tasks, reset in_progress->pending, rebuild team, kick first ready task)
+4. Multiple -> ask_user for selection
+
+## Phase 1: Requirement Clarification
+
+TEXT-LEVEL ONLY. No source code reading.
+
+1. Parse arguments for explicit settings:
+
+| Flag | Mode | Description |
+|------|------|-------------|
+| `--fix` | fix-only | Skip scan/review, go directly to fixer |
+| `--full` | full | scan + review + fix pipeline |
+| `-q` / `--quick` | quick | Quick scan only, no review/fix |
+| (none) | default | scan + review pipeline |
+
+2. Extract parameters: target, dimensions, auto-confirm flag
+3. Clarify if ambiguous (ask_user for target path)
+4. Delegate to @commands/analyze.md
+5. Output: task-analysis.json
+6. 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 `shell({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/skills/team-review`
+2. Generate session ID: RV-<slug>-<date>
+3. Create session folder structure (scan/, review/, fix/, wisdom/)
+4. create_team with team name "review"
+5. Read specs/pipelines.md -> select pipeline based on mode
+6. Initialize pipeline via team_msg state_update:
+   ```
+   mcp__ccw-tools__team_msg({
+     operation: "log", session_id: "<id>", from: "coordinator",
+     type: "state_update", summary: "Session initialized",
+     data: {
+       pipeline_mode: "<default|full|fix-only|quick>",
+       pipeline_stages: ["scanner", "reviewer", "fixer"],
+       team_name: "review",
+       target: "<target>",
+       dimensions: "<dimensions>",
+       auto_confirm: "<auto_confirm>"
+     }
+   })
+   ```
+7. Write session meta.json
+
+## Phase 3: Create Task Chain
+
+Delegate to @commands/dispatch.md:
+1. Read specs/pipelines.md for selected pipeline's task registry
+2. Create tasks via create_task with blockedBy
+3. Update session meta.json with pipeline.tasks_total
+
+## 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 (mode, target, findings_total, by_severity, fix_rate if applicable)
+2. Execute completion action per session.completion_action:
+   - interactive -> ask_user (Archive/Keep/Export)
+   - auto_archive -> Archive & Clean
+   - auto_keep -> Keep Active
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Task too vague | ask_user for clarification |
+| Session corruption | Attempt recovery, fallback to manual |
+| Worker crash | Reset task to pending, respawn |
+| Scanner finds 0 findings | Report clean, skip review + fix stages |
+| Fix verification fails | Log warning, report partial results |
+| Target path invalid | ask_user for corrected path |