maestro-flow 0.5.36 → 0.5.37

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

@@ -1,132 +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__maestro__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 |
+# 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__maestro__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 |

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

@@ -8,71 +8,71 @@ message_types:
 ---
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
-
-# Code Fixer
-
-Fix code based on reviewed findings. Load manifest, plan fix groups, apply with rollback-on-failure, verify. Code-generation role -- modifies source files.
-
-## Phase 2: Context & Scope Resolution
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Task description | From task subject/description | Yes |
-| Session path | Extracted from task description | Yes |
-| Fix manifest | <session>/fix/fix-manifest.json | Yes |
-| Review report | <session>/review/review-report.json | Yes |
-| .msg/meta.json | <session>/.msg/meta.json | No |
-
-1. Extract session path, input path from task description
-2. Load manifest (scope, source report path) and review report (findings with enrichment)
-3. Filter fixable findings: severity in scope AND fix_strategy !== 'skip'
-4. If 0 fixable -> report complete immediately
-5. Detect quick path: findings <= 5 AND no cross-file dependencies
-6. Detect verification tools: tsc (tsconfig.json), eslint (package.json), jest (package.json), pytest (pyproject.toml), semgrep (semgrep available)
-7. Load wisdom files from `<session>/wisdom/`
-
-## Phase 3: Plan + Execute
-
-### 3A: Plan Fixes (deterministic, no CLI)
-1. Group findings by primary file
-2. Merge groups with cross-file dependencies (union-find)
-3. Topological sort within each group (respect fix_dependencies, append cycles at end)
-4. Sort groups by max severity (critical first)
-5. Determine execution path: quick_path (<=5 findings, <=1 group) or standard
-6. Write `<session>/fix/fix-plan.json`: `{plan_id, quick_path, groups[{id, files[], findings[], max_severity}], execution_order[], total_findings, total_groups}`
-
-### 3B: Execute Fixes
-**Quick path**: Single code-developer agent for all findings.
-**Standard path**: One code-developer agent per group, in execution_order.
-
-Agent prompt includes: finding list (dependency-sorted), file contents (truncated 8K), critical rules:
-1. Apply each fix using Edit tool in order
-2. After each fix, run related tests
-3. Tests PASS -> finding is "fixed"
-4. Tests FAIL -> `git checkout -- {file}` -> mark "failed" -> continue
-5. No retry on failure. Rollback and move on
-6. If finding depends on previously failed finding -> mark "skipped"
-
-Agent returns JSON: `{results:[{id, status: fixed|failed|skipped, file, error?}]}`
-Fallback: check git diff per file if no structured output.
-
-Write `<session>/fix/execution-results.json`: `{fixed[], failed[], skipped[]}`
-
-## Phase 4: Post-Fix Verification
-
-1. Run available verification tools on modified files:
-
-| Tool | Command | Pass Criteria |
-|------|---------|---------------|
-| tsc | `npx tsc --noEmit` | 0 errors |
-| eslint | `npx eslint <files>` | 0 errors |
-| jest | `npx jest --passWithNoTests` | Tests pass |
-| pytest | `pytest --tb=short` | Tests pass |
-| semgrep | `semgrep --config auto <files> --json` | 0 results |
-
-2. If verification fails critically -> rollback last batch
-3. Write `<session>/fix/verify-results.json`
-4. Generate `<session>/fix/fix-summary.json`: `{fix_id, fix_date, scope, total, fixed, failed, skipped, fix_rate, verification}`
-5. Generate `<session>/fix/fix-summary.md` (human-readable)
-6. Update `<session>/.msg/meta.json` with fix results
-7. Contribute discoveries to `<session>/wisdom/` files
+
+# Code Fixer
+
+Fix code based on reviewed findings. Load manifest, plan fix groups, apply with rollback-on-failure, verify. Code-generation role -- modifies source files.
+
+## Phase 2: Context & Scope Resolution
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| Fix manifest | <session>/fix/fix-manifest.json | Yes |
+| Review report | <session>/review/review-report.json | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | No |
+
+1. Extract session path, input path from task description
+2. Load manifest (scope, source report path) and review report (findings with enrichment)
+3. Filter fixable findings: severity in scope AND fix_strategy !== 'skip'
+4. If 0 fixable -> report complete immediately
+5. Detect quick path: findings <= 5 AND no cross-file dependencies
+6. Detect verification tools: tsc (tsconfig.json), eslint (package.json), jest (package.json), pytest (pyproject.toml), semgrep (semgrep available)
+7. Load wisdom files from `<session>/wisdom/`
+
+## Phase 3: Plan + Execute
+
+### 3A: Plan Fixes (deterministic, no CLI)
+1. Group findings by primary file
+2. Merge groups with cross-file dependencies (union-find)
+3. Topological sort within each group (respect fix_dependencies, append cycles at end)
+4. Sort groups by max severity (critical first)
+5. Determine execution path: quick_path (<=5 findings, <=1 group) or standard
+6. Write `<session>/fix/fix-plan.json`: `{plan_id, quick_path, groups[{id, files[], findings[], max_severity}], execution_order[], total_findings, total_groups}`
+
+### 3B: Execute Fixes
+**Quick path**: Single code-developer agent for all findings.
+**Standard path**: One code-developer agent per group, in execution_order.
+
+Agent prompt includes: finding list (dependency-sorted), file contents (truncated 8K), critical rules:
+1. Apply each fix using Edit tool in order
+2. After each fix, run related tests
+3. Tests PASS -> finding is "fixed"
+4. Tests FAIL -> `git checkout -- {file}` -> mark "failed" -> continue
+5. No retry on failure. Rollback and move on
+6. If finding depends on previously failed finding -> mark "skipped"
+
+Agent returns JSON: `{results:[{id, status: fixed|failed|skipped, file, error?}]}`
+Fallback: check git diff per file if no structured output.
+
+Write `<session>/fix/execution-results.json`: `{fixed[], failed[], skipped[]}`
+
+## Phase 4: Post-Fix Verification
+
+1. Run available verification tools on modified files:
+
+| Tool | Command | Pass Criteria |
+|------|---------|---------------|
+| tsc | `npx tsc --noEmit` | 0 errors |
+| eslint | `npx eslint <files>` | 0 errors |
+| jest | `npx jest --passWithNoTests` | Tests pass |
+| pytest | `pytest --tb=short` | Tests pass |
+| semgrep | `semgrep --config auto <files> --json` | 0 results |
+
+2. If verification fails critically -> rollback last batch
+3. Write `<session>/fix/verify-results.json`
+4. Generate `<session>/fix/fix-summary.json`: `{fix_id, fix_date, scope, total, fixed, failed, skipped, fix_rate, verification}`
+5. Generate `<session>/fix/fix-summary.md` (human-readable)
+6. Update `<session>/.msg/meta.json` with fix results
+7. Contribute discoveries to `<session>/wisdom/` files

package/.agents/skills/team-review/specs/dimensions.md

@@ -1,82 +1,82 @@
-# Review Dimensions (4-Dimension System)
-
-## Security (SEC)
-
-Vulnerabilities, attack surfaces, and data protection issues.
-
-**Categories**: injection, authentication, authorization, data-exposure, encryption, input-validation, access-control
-
-**Tool Support**: Semgrep (`--config auto`), npm audit, tsc strict mode
-**LLM Focus**: Business logic vulnerabilities, privilege escalation paths, sensitive data flows
-
-**Severity Mapping**:
-- Critical: RCE, SQL injection, auth bypass, data breach
-- High: XSS, CSRF, insecure deserialization, weak crypto
-- Medium: Missing input validation, overly permissive CORS
-- Low: Informational headers, minor config issues
-
----
-
-## Correctness (COR)
-
-Bugs, logic errors, and type safety issues.
-
-**Categories**: bug, error-handling, edge-case, type-safety, race-condition, null-reference
-
-**Tool Support**: tsc `--noEmit`, ESLint error-level rules
-**LLM Focus**: Logic errors, unhandled exception paths, state management bugs, race conditions
-
-**Severity Mapping**:
-- Critical: Data corruption, crash in production path
-- High: Incorrect business logic, unhandled error in common path
-- Medium: Edge case not handled, missing null check
-- Low: Minor type inconsistency, unused variable
-
----
-
-## Performance (PRF)
-
-Inefficiencies, resource waste, and scalability issues.
-
-**Categories**: n-plus-one, memory-leak, blocking-operation, complexity, resource-usage, caching
-
-**Tool Support**: None (LLM-only dimension)
-**LLM Focus**: Algorithm complexity, N+1 queries, unnecessary sync operations, memory leaks, missing caching
-
-**Severity Mapping**:
-- Critical: Memory leak in long-running process, O(n³) on user data
-- High: N+1 query in hot path, blocking I/O in async context
-- Medium: Suboptimal algorithm, missing obvious cache
-- Low: Minor inefficiency, premature optimization opportunity
-
----
-
-## Maintainability (MNT)
-
-Code quality, readability, and structural health.
-
-**Categories**: code-smell, naming, complexity, duplication, dead-code, pattern-violation, coupling
-
-**Tool Support**: ESLint warning-level rules, complexity metrics
-**LLM Focus**: Architectural coupling, abstraction leaks, project convention violations
-
-**Severity Mapping**:
-- High: God class, circular dependency, copy-paste across modules
-- Medium: Long method, magic numbers, unclear naming
-- Low: Minor style inconsistency, commented-out code
-- Info: Pattern observation, refactoring suggestion
-
----
-
-## Why 4 Dimensions (Not 7)
-
-The original review-cycle used 7 dimensions with significant overlap:
-
-| Original | Problem | Merged Into |
-|----------|---------|-------------|
-| Quality | Overlaps Maintainability + Best-Practices | **Maintainability** |
-| Best-Practices | Overlaps Quality + Maintainability | **Maintainability** |
-| Architecture | Overlaps Maintainability (coupling/layering) | **Maintainability** (structure) + **Security** (security architecture) |
-| Action-Items | Not a dimension — it's a report format | Standard field on every finding |
-
-4 dimensions = clear ownership, no overlap, each maps to distinct tooling.
+# Review Dimensions (4-Dimension System)
+
+## Security (SEC)
+
+Vulnerabilities, attack surfaces, and data protection issues.
+
+**Categories**: injection, authentication, authorization, data-exposure, encryption, input-validation, access-control
+
+**Tool Support**: Semgrep (`--config auto`), npm audit, tsc strict mode
+**LLM Focus**: Business logic vulnerabilities, privilege escalation paths, sensitive data flows
+
+**Severity Mapping**:
+- Critical: RCE, SQL injection, auth bypass, data breach
+- High: XSS, CSRF, insecure deserialization, weak crypto
+- Medium: Missing input validation, overly permissive CORS
+- Low: Informational headers, minor config issues
+
+---
+
+## Correctness (COR)
+
+Bugs, logic errors, and type safety issues.
+
+**Categories**: bug, error-handling, edge-case, type-safety, race-condition, null-reference
+
+**Tool Support**: tsc `--noEmit`, ESLint error-level rules
+**LLM Focus**: Logic errors, unhandled exception paths, state management bugs, race conditions
+
+**Severity Mapping**:
+- Critical: Data corruption, crash in production path
+- High: Incorrect business logic, unhandled error in common path
+- Medium: Edge case not handled, missing null check
+- Low: Minor type inconsistency, unused variable
+
+---
+
+## Performance (PRF)
+
+Inefficiencies, resource waste, and scalability issues.
+
+**Categories**: n-plus-one, memory-leak, blocking-operation, complexity, resource-usage, caching
+
+**Tool Support**: None (LLM-only dimension)
+**LLM Focus**: Algorithm complexity, N+1 queries, unnecessary sync operations, memory leaks, missing caching
+
+**Severity Mapping**:
+- Critical: Memory leak in long-running process, O(n³) on user data
+- High: N+1 query in hot path, blocking I/O in async context
+- Medium: Suboptimal algorithm, missing obvious cache
+- Low: Minor inefficiency, premature optimization opportunity
+
+---
+
+## Maintainability (MNT)
+
+Code quality, readability, and structural health.
+
+**Categories**: code-smell, naming, complexity, duplication, dead-code, pattern-violation, coupling
+
+**Tool Support**: ESLint warning-level rules, complexity metrics
+**LLM Focus**: Architectural coupling, abstraction leaks, project convention violations
+
+**Severity Mapping**:
+- High: God class, circular dependency, copy-paste across modules
+- Medium: Long method, magic numbers, unclear naming
+- Low: Minor style inconsistency, commented-out code
+- Info: Pattern observation, refactoring suggestion
+
+---
+
+## Why 4 Dimensions (Not 7)
+
+The original review-cycle used 7 dimensions with significant overlap:
+
+| Original | Problem | Merged Into |
+|----------|---------|-------------|
+| Quality | Overlaps Maintainability + Best-Practices | **Maintainability** |
+| Best-Practices | Overlaps Quality + Maintainability | **Maintainability** |
+| Architecture | Overlaps Maintainability (coupling/layering) | **Maintainability** (structure) + **Security** (security architecture) |
+| Action-Items | Not a dimension — it's a report format | Standard field on every finding |
+
+4 dimensions = clear ownership, no overlap, each maps to distinct tooling.