maestro-flow 0.5.31 → 0.5.33

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

@@ -0,0 +1,173 @@
+---
+name: team-issue
+description: Unified team skill for issue resolution. Uses team-worker agent architecture with role directories for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team issue".
+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__maestro__team_msg(*)
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Team Issue Resolution
+
+Orchestrate issue resolution pipeline: explore context -> plan solution -> review (optional) -> marshal queue -> implement. Supports Quick, Full, and Batch pipelines with review-fix cycle.
+
+## Architecture
+
+```
+invoke_skill(skill="team-issue", args="<issue-ids> [--mode=<mode>]")
+                    |
+         SKILL.md (this file) = Router
+                    |
+     +--------------+--------------+
+     |                             |
+  no --role flag              --role <name>
+     |                             |
+  Coordinator                  Worker
+  roles/coordinator/role.md    roles/<name>/role.md
+     |
+     +-- clarify -> dispatch -> spawn workers -> STOP
+                                    |
+             +-------+-------+-------+-------+
+             v       v       v       v       v
+          [explor] [plann] [review] [integ] [imple]
+```
+
+## Role Registry
+
+| Role | Path | Prefix | Inner Loop |
+|------|------|--------|------------|
+| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
+| explorer | [roles/explorer/role.md](roles/explorer/role.md) | EXPLORE-* | false |
+| planner | [roles/planner/role.md](roles/planner/role.md) | SOLVE-* | false |
+| reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | AUDIT-* | false |
+| integrator | [roles/integrator/role.md](roles/integrator/role.md) | MARSHAL-* | false |
+| implementer | [roles/implementer/role.md](roles/implementer/role.md) | BUILD-* | false |
+
+
+## Pre-load (coordinator, before dispatch)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for module boundaries
+2. **Specs (coding)**: `maestro spec load --category coding` — load coding constraints as shared context
+3. **Specs (debug)**: `maestro spec load --category debug` — load debug constraints as shared context
+4. **Wiki knowledge**: `maestro search "issue resolution fix" --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**: `TISL`
+- **Session path**: `.workflow/.team/TISL-<slug>-<date>/`
+- **Team name**: `issue`
+- **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: "issue",
+  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: issue
+requirement: <task-description>
+inner_loop: 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).`
+})
+```
+
+**Parallel spawn** (Batch mode, N explorer or M implementer instances):
+
+```
+delegate_subagent({
+  subagent_type: "team-worker",
+  name: "<role>-<N>",
+  team_name: "issue",
+  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: issue
+requirement: <task-description>
+agent_name: <role>-<N>
+inner_loop: 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, owner=<role>-<N>) -> role Phase 2-4 -> built-in Phase 5 (report).`
+})
+```
+
+## User Commands
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View execution status graph, no advancement |
+| `resume` / `continue` | Check worker states, advance next step |
+
+## Session Directory
+
+```
+.workflow/.team/TISL-<slug>-<date>/
+├── session.json                    # Session metadata + pipeline + fix_cycles
+├── task-analysis.json              # Coordinator analyze output
+├── .msg/
+│   ├── messages.jsonl              # Message bus log
+│   └── meta.json                   # Session state + cross-role state
+├── wisdom/                         # Cross-task knowledge
+│   ├── learnings.md
+│   ├── decisions.md
+│   ├── conventions.md
+│   └── issues.md
+├── explorations/                   # Explorer output
+│   └── context-<issueId>.json
+├── solutions/                      # Planner output
+│   └── solution-<issueId>.json
+├── audits/                         # Reviewer output
+│   └── audit-report.json
+├── queue/                          # Integrator output (also .workflow/issues/queue/)
+└── builds/                         # Implementer output
+```
+
+## Specs Reference
+
+- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Unknown command | Error with available command list |
+| Role not found | Error with role registry |
+| CLI tool fails | Worker fallback to direct implementation |
+| Fast-advance conflict | Coordinator reconciles on next callback |
+| Completion action fails | Default to Keep Active |
+| Review rejection exceeds 2 rounds | Force convergence to integrator |
+| No issues found for given IDs | Coordinator reports error to user |
+| Deferred BUILD count unknown | Defer to MARSHAL callback |

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

@@ -0,0 +1,64 @@
+# Analyze Task
+
+Parse user issue description -> detect required capabilities -> assess complexity -> select pipeline mode.
+
+**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
+
+## Signal Detection
+
+| Keywords | Capability | Prefix |
+|----------|------------|--------|
+| explore, analyze, context, impact, understand | explorer | EXPLORE |
+| plan, solve, design, solution, approach | planner | SOLVE |
+| review, audit, validate, feasibility | reviewer | AUDIT |
+| marshal, integrate, queue, conflict, order | integrator | MARSHAL |
+| build, implement, execute, code, develop | implementer | BUILD |
+
+## Dependency Graph
+
+Natural ordering tiers:
+- Tier 0: explorer (context analysis — no dependencies)
+- Tier 1: planner (requires explorer output)
+- Tier 2: reviewer (requires planner output, full/batch modes only)
+- Tier 3: integrator (requires reviewer or planner output)
+- Tier 4: implementer (requires integrator output)
+
+## Complexity Scoring
+
+| Factor | Points |
+|--------|--------|
+| Issue count > 2 | +3 |
+| Issue count > 4 | +2 more |
+| Any high-priority issue (priority >= 4) | +2 |
+| Multiple issue types / cross-cutting | +2 |
+| Simple / single issue | -2 |
+
+Results:
+- 0-2: Low -> quick (4 tasks: EXPLORE → SOLVE → MARSHAL → BUILD)
+- 3-4: Medium -> full (5 tasks: EXPLORE → SOLVE → AUDIT → MARSHAL → BUILD)
+- 5+: High -> batch (N+N+1+1+M tasks, parallel exploration and implementation)
+
+## Pipeline Selection
+
+| Complexity | Pipeline | Tasks |
+|------------|----------|-------|
+| Low | quick | EXPLORE → SOLVE → MARSHAL → BUILD |
+| Medium | full | EXPLORE → SOLVE → AUDIT → MARSHAL → BUILD |
+| High | batch | EXPLORE-001..N (parallel) → SOLVE-001..N → AUDIT → MARSHAL → BUILD-001..M (parallel) |
+
+## Output
+
+Write <session>/task-analysis.json:
+```json
+{
+  "task_description": "<original>",
+  "pipeline_type": "<quick|full|batch>",
+  "issue_ids": ["<id1>", "<id2>"],
+  "capabilities": [{ "name": "<cap>", "prefix": "<PREFIX>", "keywords": ["..."] }],
+  "dependency_graph": { "<TASK-ID>": { "role": "<role>", "blockedBy": ["..."], "priority": "P0|P1|P2" } },
+  "roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
+  "complexity": { "score": 0, "level": "Low|Medium|High" },
+  "parallel_explorers": 1,
+  "parallel_builders": 1
+}
+```

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

@@ -0,0 +1,349 @@
+# Dispatch
+
+Create the issue resolution task chain with correct dependencies and structured task descriptions based on selected pipeline mode.
+
+## Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Requirement | From coordinator Phase 1 | Yes |
+| Session folder | From coordinator Phase 2 | Yes |
+| Pipeline mode | From session.json mode | Yes |
+| Issue IDs | From session.json issue_ids | Yes |
+| Execution method | From session.json execution_method | Yes |
+| Code review | From session.json code_review | No |
+
+1. Load requirement, pipeline mode, issue IDs, and execution method from session.json
+2. Determine task chain from pipeline mode
+
+## Task Description Template
+
+Every task description uses structured format:
+
+```
+create_task({
+  subject: "<TASK-ID>",
+  description: "PURPOSE: <what this task achieves> | Success: <completion criteria>
+TASK:
+  - <step 1>
+  - <step 2>
+  - <step 3>
+CONTEXT:
+  - Session: <session-folder>
+  - Issue IDs: <issue-id-list>
+  - Upstream artifacts: <artifact-list>
+EXPECTED: <deliverable path> + <quality criteria>
+CONSTRAINTS: <scope limits>
+---
+InnerLoop: false
+execution_method: <method>
+code_review: <setting>"
+})
+update_task({ taskId: "<TASK-ID>", addBlockedBy: [<dependency-list>], owner: "<role>" })
+```
+
+## Pipeline Router
+
+| Mode | Action |
+|------|--------|
+| quick | Create 4 tasks (EXPLORE → SOLVE → MARSHAL → BUILD) |
+| full | Create 5 tasks (EXPLORE → SOLVE → AUDIT → MARSHAL → BUILD) |
+| batch | Create N+N+1+1+M tasks (EXPLORE-001..N → SOLVE-001..N → AUDIT-001 → MARSHAL-001 → BUILD-001..M) |
+
+---
+
+### Quick Pipeline
+
+**EXPLORE-001** (explorer):
+```
+create_task({
+  subject: "EXPLORE-001",
+  description: "PURPOSE: Analyze issue context and map codebase impact | Success: Context report with relevant files and dependencies
+TASK:
+  - Load issue details via ccw issue status
+  - Explore codebase for relevant files and patterns
+  - Assess complexity and impact scope
+CONTEXT:
+  - Session: <session-folder>
+  - Issue IDs: <issue-id-list>
+EXPECTED: <session>/explorations/context-<issueId>.json with relevant files, dependencies, and impact assessment
+CONSTRAINTS: Exploration and analysis only, no solution design
+---
+InnerLoop: false"
+})
+update_task({ taskId: "EXPLORE-001", owner: "explorer" })
+```
+
+**SOLVE-001** (planner):
+```
+create_task({
+  subject: "SOLVE-001",
+  description: "PURPOSE: Design solution and decompose into implementation tasks | Success: Bound solution with task decomposition
+TASK:
+  - Load explorer context report
+  - Generate solution plan via CLI
+  - Bind solution to issue
+CONTEXT:
+  - Session: <session-folder>
+  - Issue IDs: <issue-id-list>
+  - Upstream artifacts: explorations/context-<issueId>.json
+EXPECTED: <session>/solutions/solution-<issueId>.json with solution plan and task list
+CONSTRAINTS: Solution design only, no code implementation
+---
+InnerLoop: false"
+})
+update_task({ taskId: "SOLVE-001", addBlockedBy: ["EXPLORE-001"], owner: "planner" })
+```
+
+**MARSHAL-001** (integrator):
+```
+create_task({
+  subject: "MARSHAL-001",
+  description: "PURPOSE: Form execution queue with conflict detection and ordering | Success: Execution queue file with resolved conflicts
+TASK:
+  - Verify all issues have bound solutions
+  - Detect file conflicts between solutions
+  - Produce ordered execution queue with DAG-based parallel groups
+CONTEXT:
+  - Session: <session-folder>
+  - Issue IDs: <issue-id-list>
+  - Upstream artifacts: solutions/solution-<issueId>.json
+EXPECTED: .workflow/issues/queue/execution-queue.json with queue, conflicts, parallel groups
+CONSTRAINTS: Queue formation only, no implementation
+---
+InnerLoop: false"
+})
+update_task({ taskId: "MARSHAL-001", addBlockedBy: ["SOLVE-001"], owner: "integrator" })
+```
+
+**BUILD-001** (implementer):
+```
+create_task({
+  subject: "BUILD-001",
+  description: "PURPOSE: Implement solution plan and verify with tests | Success: Code changes committed, tests pass
+TASK:
+  - Load bound solution and explorer context
+  - Route to execution backend (Auto/Codex/Gemini)
+  - Run tests and verify implementation
+  - Commit changes
+CONTEXT:
+  - Session: <session-folder>
+  - Issue IDs: <issue-id-list>
+  - Upstream artifacts: explorations/context-<issueId>.json, solutions/solution-<issueId>.json, queue/execution-queue.json
+EXPECTED: <session>/builds/ with implementation results, tests passing
+CONSTRAINTS: Follow solution plan, no scope creep
+---
+InnerLoop: false
+execution_method: <execution_method>
+code_review: <code_review>"
+})
+update_task({ taskId: "BUILD-001", addBlockedBy: ["MARSHAL-001"], owner: "implementer" })
+```
+
+---
+
+### Full Pipeline
+
+Creates 5 tasks. EXPLORE-001 and SOLVE-001 same as Quick, then AUDIT gate before MARSHAL and BUILD.
+
+**AUDIT-001** (reviewer):
+```
+create_task({
+  subject: "AUDIT-001",
+  description: "PURPOSE: Review solution for technical feasibility, risk, and completeness | Success: Clear verdict (approved/concerns/rejected) with scores
+TASK:
+  - Load explorer context and bound solution
+  - Score across 3 dimensions: technical feasibility (40%), risk (30%), completeness (30%)
+  - Produce verdict: approved (>=80), concerns (60-79), rejected (<60)
+CONTEXT:
+  - Session: <session-folder>
+  - Issue IDs: <issue-id-list>
+  - Upstream artifacts: explorations/context-<issueId>.json, solutions/solution-<issueId>.json
+EXPECTED: <session>/audits/audit-report.json with per-issue scores and overall verdict
+CONSTRAINTS: Review only, do not modify solutions
+---
+InnerLoop: false"
+})
+update_task({ taskId: "AUDIT-001", addBlockedBy: ["SOLVE-001"], owner: "reviewer" })
+```
+
+**MARSHAL-001**: Same as Quick, but `addBlockedBy: ["AUDIT-001"]`.
+
+**BUILD-001**: Same as Quick, `addBlockedBy: ["MARSHAL-001"]`.
+
+---
+
+### Batch Pipeline
+
+Creates tasks in parallel batches. Issue count = N, BUILD tasks = M (from queue parallel groups).
+
+**EXPLORE-001..N** (explorer, parallel):
+
+For each issue in issue_ids (up to 5), create an EXPLORE task with distinct owner:
+
+| Issue Count | Owner Assignment |
+|-------------|-----------------|
+| N = 1 | owner: "explorer" |
+| N > 1 | owner: "explorer-1", "explorer-2", ..., "explorer-N" (max 5) |
+
+```
+create_task({
+  subject: "EXPLORE-<NNN>",
+  description: "PURPOSE: Analyze issue <issueId> context and map codebase impact | Success: Context report for <issueId>
+TASK:
+  - Load issue details for <issueId>
+  - Explore codebase for relevant files
+  - Assess complexity and impact scope
+CONTEXT:
+  - Session: <session-folder>
+  - Issue IDs: <issueId>
+EXPECTED: <session>/explorations/context-<issueId>.json
+CONSTRAINTS: Single issue scope, exploration only
+---
+InnerLoop: false"
+})
+update_task({ taskId: "EXPLORE-<NNN>", owner: "explorer-<N>" })
+```
+
+**SOLVE-001..N** (planner, sequential after all EXPLORE):
+
+```
+create_task({
+  subject: "SOLVE-<NNN>",
+  description: "PURPOSE: Design solution for <issueId> | Success: Bound solution with tasks
+TASK:
+  - Load explorer context for <issueId>
+  - Generate solution plan
+  - Bind solution
+CONTEXT:
+  - Session: <session-folder>
+  - Issue IDs: <issueId>
+  - Upstream artifacts: explorations/context-<issueId>.json
+EXPECTED: <session>/solutions/solution-<issueId>.json
+CONSTRAINTS: Solution design only
+---
+InnerLoop: false"
+})
+update_task({ taskId: "SOLVE-<NNN>", addBlockedBy: ["EXPLORE-001", ..., "EXPLORE-<N>"], owner: "planner" })
+```
+
+**AUDIT-001** (reviewer, batch review):
+```
+create_task({
+  subject: "AUDIT-001",
+  description: "PURPOSE: Batch review all solutions | Success: Verdict for each solution
+TASK:
+  - Load all explorer contexts and bound solutions
+  - Score each solution across 3 dimensions
+  - Produce per-issue verdicts and overall verdict
+CONTEXT:
+  - Session: <session-folder>
+  - Issue IDs: <all-issue-ids>
+  - Upstream artifacts: explorations/*.json, solutions/*.json
+EXPECTED: <session>/audits/audit-report.json with batch results
+CONSTRAINTS: Review only
+---
+InnerLoop: false"
+})
+update_task({ taskId: "AUDIT-001", addBlockedBy: ["SOLVE-001", ..., "SOLVE-<N>"], owner: "reviewer" })
+```
+
+**MARSHAL-001** (integrator): `addBlockedBy: ["AUDIT-001"]`.
+
+**BUILD-001..M** (implementer, DAG parallel):
+
+> Note: In Batch mode, BUILD task count M is not known at dispatch time (depends on MARSHAL queue output). Defer BUILD task creation to handleCallback when MARSHAL completes. Coordinator creates BUILD tasks dynamically after reading execution-queue.json.
+
+When M is known (deferred creation after MARSHAL), assign distinct owners:
+
+| Build Count | Owner Assignment |
+|-------------|-----------------|
+| M <= 2 | owner: "implementer" |
+| M > 2 | owner: "implementer-1", ..., "implementer-M" (max 3) |
+
+```
+create_task({
+  subject: "BUILD-<NNN>",
+  description: "PURPOSE: Implement solution for <issueId> | Success: Code committed, tests pass
+TASK:
+  - Load bound solution and explorer context
+  - Execute implementation via <execution_method>
+  - Run tests, commit
+CONTEXT:
+  - Session: <session-folder>
+  - Issue IDs: <issueId>
+  - Upstream artifacts: explorations/context-<issueId>.json, solutions/solution-<issueId>.json, queue/execution-queue.json
+EXPECTED: <session>/builds/ with results
+CONSTRAINTS: Follow solution plan
+---
+InnerLoop: false
+execution_method: <execution_method>
+code_review: <code_review>"
+})
+update_task({ taskId: "BUILD-<NNN>", addBlockedBy: ["MARSHAL-001"], owner: "implementer-<M>" })
+```
+
+---
+
+### Review-Fix Cycle (Full/Batch modes)
+
+When AUDIT rejects a solution, coordinator creates fix tasks dynamically in handleCallback — NOT at dispatch time.
+
+**SOLVE-fix-001** (planner, revision):
+```
+create_task({
+  subject: "SOLVE-fix-001",
+  description: "PURPOSE: Revise solution addressing reviewer feedback (fix cycle <round>) | Success: Revised solution addressing rejection reasons
+TASK:
+  - Read reviewer feedback from audit report
+  - Design alternative approach addressing concerns
+  - Re-bind revised solution
+CONTEXT:
+  - Session: <session-folder>
+  - Issue IDs: <rejected-issue-ids>
+  - Upstream artifacts: audits/audit-report.json
+  - Reviewer feedback: <rejection-reasons>
+EXPECTED: <session>/solutions/solution-<issueId>.json (revised)
+CONSTRAINTS: Address reviewer concerns specifically
+---
+InnerLoop: false"
+})
+update_task({ taskId: "SOLVE-fix-001", addBlockedBy: ["AUDIT-001"], owner: "planner" })
+```
+
+**AUDIT-002** (reviewer, re-review):
+```
+create_task({
+  subject: "AUDIT-002",
+  description: "PURPOSE: Re-review revised solution (fix cycle <round>) | Success: Verdict on revised solution
+TASK:
+  - Load revised solution
+  - Re-evaluate previously rejected dimensions
+  - Produce updated verdict
+CONTEXT:
+  - Session: <session-folder>
+  - Issue IDs: <rejected-issue-ids>
+  - Upstream artifacts: solutions/solution-<issueId>.json (revised), audits/audit-report.json
+EXPECTED: <session>/audits/audit-report.json (updated)
+CONSTRAINTS: Focus on previously rejected dimensions
+---
+InnerLoop: false"
+})
+update_task({ taskId: "AUDIT-002", addBlockedBy: ["SOLVE-fix-001"], owner: "reviewer" })
+```
+
+## Validation
+
+1. Verify all tasks created with `list_tasks()`
+2. Check dependency chain integrity:
+   - No circular dependencies
+   - All blockedBy references exist
+   - First task(s) have empty blockedBy (EXPLORE tasks)
+3. Log task count and pipeline mode
+4. Verify mode-specific constraints:
+
+| Mode | Constraint |
+|------|-----------|
+| quick | Exactly 4 tasks, no AUDIT |
+| full | Exactly 5 tasks, includes AUDIT |
+| batch | N EXPLORE + N SOLVE + 1 AUDIT + 1 MARSHAL + deferred BUILD |