maestro-flow 0.5.31 → 0.5.33

package/.agents/skills/team-issue/roles/planner/role.md

@@ -0,0 +1,83 @@
+---
+role: planner
+prefix: SOLVE
+inner_loop: false
+additional_prefixes: [SOLVE-fix]
+message_types: [solution_ready, multi_solution, error]
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Issue Planner
+
+Design solutions and decompose into implementation tasks. Uses CLI tools for ACE exploration and solution generation. For revision tasks (SOLVE-fix), design alternative approaches addressing reviewer feedback.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Issue ID | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes |
+| Explorer context | `<session>/explorations/context-<issueId>.json` | No |
+| Review feedback | Task description (for SOLVE-fix tasks) | No |
+| wisdom meta | <session>/wisdom/.msg/meta.json | No |
+
+1. Extract issue ID from task description via regex: `(?:GH-\d+|ISS-\d{8}-\d{6})`
+2. If no issue ID found -> report error, STOP
+3. Load explorer context report (if available):
+
+```
+read_file("<session>/explorations/context-<issueId>.json")
+```
+
+4. Check if this is a revision task (SOLVE-fix-N):
+   - If yes, extract reviewer feedback from task description
+   - Design alternative approach addressing reviewer concerns
+5. Load wisdom files for accumulated codebase knowledge
+
+## Phase 3: Solution Generation via CLI
+
+**CLI invocation**:
+
+```
+shell("maestro delegate \\\"
+PURPOSE: Design solution for issue <issueId> and decompose into implementation tasks; success = solution bound to issue with task breakdown
+
+TASK: • Load issue details from ccw issue status • Analyze explorer context • Design solution approach • Break down into implementation tasks • Generate solution JSON • Bind solution to issue
+
+MODE: analysis
+
+CONTEXT: @**/* | Memory: Issue <issueId> - <issue.title> (Priority: <issue.priority>)
+Explorer findings: <explorerContext.key_findings>
+Relevant files: <explorerContext.relevant_files>
+Complexity: <explorerContext.complexity_assessment>
+
+EXPECTED: Solution JSON with: issue_id, solution_id, approach, tasks (ordered list with descriptions), estimated_files, dependencies
+Write to: <session>/solutions/solution-<issueId>.json
+Then bind: ccw issue bind <issueId> <solution_id>
+
+CONSTRAINTS: Follow existing patterns | Minimal changes | Address reviewer feedback if SOLVE-fix task
+\" --tool gemini --mode analysis", { run_in_background: false })
+```
+
+**Expected CLI output**: Solution file path and binding confirmation
+
+**Parse result**:
+
+```
+read_file("<session>/solutions/solution-<issueId>.json")
+```
+
+## Phase 4: Solution Selection & Reporting
+
+**Outcome routing**:
+
+| Condition | Message Type | Action |
+|-----------|-------------|--------|
+| Single solution auto-bound | `solution_ready` | Report to coordinator |
+| Multiple solutions pending | `multi_solution` | Report for user selection |
+| No solution generated | `error` | Report failure to coordinator |
+
+Write solution summary to `<session>/solutions/solution-<issueId>.json`.
+
+Update `<session>/wisdom/.msg/meta.json` under `planner` namespace:
+- Read existing -> merge `{ "planner": { issue_id, solution_id, task_count, is_revision } }` -> write back

package/.agents/skills/team-issue/roles/reviewer/role.md

@@ -0,0 +1,88 @@
+---
+role: reviewer
+prefix: AUDIT
+inner_loop: false
+message_types: [approved, concerns, rejected, error]
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Issue Reviewer
+
+Review solution plans for technical feasibility, risk, and completeness. Quality gate role between plan and execute phases. Provides clear verdicts: approved, rejected, or concerns.
+
+## Phase 2: Context & Solution Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Issue IDs | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes |
+| Explorer context | `<session>/explorations/context-<issueId>.json` | No |
+| Bound solution | `ccw issue solutions <id> --json` | Yes |
+| wisdom meta | <session>/wisdom/.msg/meta.json | No |
+
+1. Extract issue IDs from task description via regex
+2. Load explorer context reports for each issue
+3. Load bound solutions for each issue:
+
+```
+shell("ccw issue solutions <issueId> --json")
+```
+
+## Phase 3: Multi-Dimensional Review
+
+Review each solution across three weighted dimensions:
+
+**Technical Feasibility (40%)**:
+
+| Criterion | Check |
+|-----------|-------|
+| File Coverage | Solution covers all affected files from explorer context |
+| Dependency Awareness | Considers dependency cascade effects |
+| API Compatibility | Maintains backward compatibility |
+| Pattern Conformance | Follows existing code patterns (ACE semantic validation) |
+
+**Risk Assessment (30%)**:
+
+| Criterion | Check |
+|-----------|-------|
+| Scope Creep | Solution stays within issue boundary (task_count <= 10) |
+| Breaking Changes | No destructive modifications |
+| Side Effects | No unforeseen side effects |
+| Rollback Path | Can rollback if issues occur |
+
+**Completeness (30%)**:
+
+| Criterion | Check |
+|-----------|-------|
+| All Tasks Defined | Task decomposition is complete (count > 0) |
+| Test Coverage | Includes test plan |
+| Edge Cases | Considers boundary conditions |
+
+**Score calculation**:
+
+```
+total_score = round(
+  technical_feasibility.score * 0.4 +
+  risk_assessment.score * 0.3 +
+  completeness.score * 0.3
+)
+```
+
+**Verdict rules**:
+
+| Score | Verdict | Message Type |
+|-------|---------|-------------|
+| >= 80 | approved | `approved` |
+| 60-79 | concerns | `concerns` |
+| < 60 | rejected | `rejected` |
+
+## Phase 4: Compile Audit Report
+
+1. Write audit report to `<session>/audits/audit-report.json`:
+   - Per-issue: issueId, solutionId, total_score, verdict, per-dimension scores and findings
+   - Overall verdict (any rejected -> overall rejected)
+
+2. Update `<session>/wisdom/.msg/meta.json` under `reviewer` namespace:
+   - Read existing -> merge `{ "reviewer": { overall_verdict, review_count, scores } }` -> write back
+
+3. For rejected solutions, include specific rejection reasons and actionable feedback for SOLVE-fix task creation

package/.agents/skills/team-issue/specs/pipelines.md

@@ -0,0 +1,124 @@
+# Pipeline Definitions — team-issue
+
+## Available Pipelines
+
+### Quick Pipeline (4 beats, strictly serial)
+
+```
+EXPLORE-001 → SOLVE-001 → MARSHAL-001 → BUILD-001
+[explorer]    [planner]   [integrator]  [implementer]
+```
+
+Use when: 1-2 simple issues, no high-priority (priority < 4).
+
+### Full Pipeline (5 beats, with review gate)
+
+```
+EXPLORE-001 → SOLVE-001 → AUDIT-001 ─┬─(approved/concerns)→ MARSHAL-001 → BUILD-001
+[explorer]    [planner]   [reviewer]  │
+                                      └─(rejected, round<2)→ SOLVE-fix-001 → AUDIT-002 → MARSHAL-001 → BUILD-001
+```
+
+Use when: 1-4 issues with high-priority, or 3-4 issues regardless of priority.
+
+### Batch Pipeline (parallel windows)
+
+```
+[EXPLORE-001..N](parallel, max 5) → [SOLVE-001..N](sequential) → AUDIT-001 → MARSHAL-001 → [BUILD-001..M](parallel, max 3, deferred)
+```
+
+Use when: 5+ issues.
+
+Note: BUILD tasks are created dynamically after MARSHAL completes and execution-queue.json is available.
+
+## Task Metadata Registry
+
+| Task ID | Role | Phase | Dependencies | Description |
+|---------|------|-------|-------------|-------------|
+| EXPLORE-001 | explorer | explore | (none) | Context analysis and impact assessment |
+| EXPLORE-002..N | explorer | explore | (none) | Parallel exploration (Batch mode only, max 5) |
+| SOLVE-001 | planner | plan | EXPLORE-001 (or all EXPLORE-*) | Solution design and task decomposition |
+| SOLVE-002..N | planner | plan | all EXPLORE-* | Parallel solution design (Batch mode only) |
+| AUDIT-001 | reviewer | review | SOLVE-001 (or all SOLVE-*) | Technical feasibility and risk review (Full/Batch) |
+| SOLVE-fix-001 | planner | fix | AUDIT-001 | Revised solution addressing reviewer feedback |
+| AUDIT-002 | reviewer | re-review | SOLVE-fix-001 | Re-review of revised solution |
+| MARSHAL-001 | integrator | integrate | AUDIT-001 (or last SOLVE-* in quick) | Conflict detection and queue orchestration |
+| BUILD-001 | implementer | implement | MARSHAL-001 | Code implementation and result submission |
+| BUILD-002..M | implementer | implement | MARSHAL-001 | Parallel implementation (Batch, deferred creation) |
+
+## Mode Auto-Detection
+
+| Condition | Mode |
+|-----------|------|
+| User specifies `--mode=<M>` | Use specified mode |
+| Issue count <= 2 AND no high-priority (priority < 4) | `quick` |
+| Issue count <= 2 AND has high-priority (priority >= 4) | `full` |
+| 3-4 issues | `full` |
+| Issue count >= 5 | `batch` |
+
+## Checkpoints
+
+| Trigger | Location | Behavior |
+|---------|----------|----------|
+| Review gate | After AUDIT-* | approved/concerns → MARSHAL; rejected → SOLVE-fix (max 2 rounds) |
+| Review loop limit | fix_cycles >= 2 | Force proceed to MARSHAL with warnings |
+| Deferred BUILD creation | After MARSHAL-* (batch) | Read execution-queue.json, create BUILD tasks |
+| Pipeline stall | No ready + no running | Check missing tasks, report to user |
+
+## Completion Conditions
+
+| Mode | Completion Condition |
+|------|---------------------|
+| quick | All 4 tasks completed |
+| full | All 5 tasks (+ any fix cycle tasks) completed |
+| batch | All N EXPLORE + N SOLVE + 1 AUDIT + 1 MARSHAL + M BUILD (+ any fix cycle tasks) completed |
+
+## Parallel Spawn Rules
+
+| Pipeline | Stage | Max Parallel |
+|----------|-------|-------------|
+| Batch | EXPLORE-001..N | min(N, 5) |
+| Batch | BUILD-001..M | min(M, 3) |
+| All | All other stages | 1 |
+
+## Shared State (meta.json)
+
+| Role | State Key |
+|------|-----------| 
+| explorer | `explorer` (issue_id, complexity, impact_scope, file_count) |
+| planner | `planner` (issue_id, solution_id, task_count, is_revision) |
+| reviewer | `reviewer` (overall_verdict, review_count, scores) |
+| integrator | `integrator` (queue_size, parallel_groups, conflict_count) |
+| implementer | `implementer` (issue_id, executor, test_status, review_status) |
+
+## Message Types
+
+| Role | Types |
+|------|-------|
+| coordinator | `pipeline_selected`, `review_result`, `fix_required`, `task_unblocked`, `error`, `shutdown` |
+| explorer | `context_ready`, `error` |
+| planner | `solution_ready`, `multi_solution`, `error` |
+| reviewer | `approved`, `concerns`, `rejected`, `error` |
+| integrator | `queue_ready`, `conflict_found`, `error` |
+| implementer | `impl_complete`, `impl_failed`, `error` |
+
+## Review-Fix Cycle
+
+```
+AUDIT verdict: rejected
+    │
+    ├─ fix_cycles < 2 → create SOLVE-fix-<N> + AUDIT-<N+1> → spawn planner → wait
+    │                       ↑
+    │                   (repeat if rejected again)
+    │
+    └─ fix_cycles >= 2 → force proceed to MARSHAL with rejection warning logged
+```
+
+## Deferred BUILD Creation (Batch Mode)
+
+BUILD tasks are not created during initial dispatch. After MARSHAL-001 completes:
+1. Read `.workflow/issues/queue/execution-queue.json`
+2. Parse `parallel_groups` to determine M
+3. Create BUILD-001..M tasks with `addBlockedBy: ["MARSHAL-001"]`
+4. Assign owners: M <= 2 → "implementer"; M > 2 → "implementer-1".."implementer-M" (max 3)
+5. Spawn implementer workers via handleSpawnNext

package/.agents/skills/team-issue/specs/team-config.json

@@ -0,0 +1,70 @@
+{
+  "team_name": "issue",
+  "team_display_name": "Issue Resolution",
+  "description": "Unified team skill for issue processing pipeline (plan → queue → execute). Issue creation handled by issue-discover, CRUD by issue-manage.",
+  "version": "1.0.0",
+
+  "roles": {
+    "coordinator": {
+      "task_prefix": null,
+      "responsibility": "Pipeline orchestration, mode selection, task chain creation, progress monitoring",
+      "message_types": ["task_assigned", "pipeline_update", "escalation", "shutdown", "error"]
+    },
+    "explorer": {
+      "task_prefix": "EXPLORE",
+      "responsibility": "Issue context analysis, codebase exploration, dependency identification, impact assessment",
+      "message_types": ["context_ready", "impact_assessed", "error"],
+      "reuses_agent": "cli-explore-agent"
+    },
+    "planner": {
+      "task_prefix": "SOLVE",
+      "responsibility": "Solution design, task decomposition via issue-plan-agent",
+      "message_types": ["solution_ready", "multi_solution", "error"],
+      "reuses_agent": "issue-plan-agent"
+    },
+    "reviewer": {
+      "task_prefix": "AUDIT",
+      "responsibility": "Solution review, technical feasibility validation, risk assessment",
+      "message_types": ["approved", "rejected", "concerns", "error"],
+      "reuses_agent": null
+    },
+    "integrator": {
+      "task_prefix": "MARSHAL",
+      "responsibility": "Queue formation, conflict detection, execution order optimization via issue-queue-agent",
+      "message_types": ["queue_ready", "conflict_found", "error"],
+      "reuses_agent": "issue-queue-agent"
+    },
+    "implementer": {
+      "task_prefix": "BUILD",
+      "responsibility": "Code implementation, test verification, result submission via code-developer",
+      "message_types": ["impl_complete", "impl_failed", "error"],
+      "reuses_agent": "code-developer"
+    }
+  },
+
+  "pipelines": {
+    "quick": {
+      "description": "Simple issues, skip review",
+      "task_chain": ["EXPLORE-001", "SOLVE-001", "MARSHAL-001", "BUILD-001"]
+    },
+    "full": {
+      "description": "Complex issues, with CP-2 review cycle (max 2 rounds)",
+      "task_chain": ["EXPLORE-001", "SOLVE-001", "AUDIT-001", "MARSHAL-001", "BUILD-001"]
+    },
+    "batch": {
+      "description": "Batch processing 5-100 issues with parallel exploration and execution",
+      "task_chain": "EXPLORE-001..N(batch≤5) → SOLVE-001..N(batch≤3) → AUDIT-001 → MARSHAL-001 → BUILD-001..M(DAG parallel)"
+    }
+  },
+
+  "collaboration_patterns": ["CP-1", "CP-2", "CP-3", "CP-5"],
+
+  "session_dirs": {
+    "base": ".workflow/.team-plan/issue/",
+    "context": ".workflow/.team-plan/issue/context-{issueId}.json",
+    "audit": ".workflow/.team-plan/issue/audit-report.json",
+    "queue": ".workflow/issues/queue/execution-queue.json",
+    "solutions": ".workflow/issues/solutions/",
+    "messages": ".workflow/.team-msg/issue/"
+  }
+}