maestro-flow 0.5.31 → 0.5.33

package/.claude/skills/team-planex/roles/coordinator/commands/dispatch.md

@@ -0,0 +1,87 @@
+# Command: dispatch
+
+## Purpose
+
+Create the initial task chain for team-planex pipeline. Creates PLAN-001 for planner. EXEC-* tasks are NOT pre-created — planner creates them at runtime per issue.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Input type | Phase 1 requirements | Yes |
+| Raw input | Phase 1 requirements | Yes |
+| Session folder | Phase 2 session init | Yes |
+| Execution method | Phase 1 requirements | Yes |
+
+## Phase 3: Task Chain Creation
+
+### Task Creation
+
+Create a single PLAN-001 task for the planner:
+
+```
+TaskCreate({
+  subject: "PLAN-001: Requirement decomposition and solution design",
+  description: `Decompose requirements into issues and generate solutions.
+
+Input type: <issues|text|plan>
+Input: <raw-input>
+Session: <session-folder>
+Execution method: <agent|codex|gemini>
+
+## Instructions
+1. Parse input to get issue list
+2. For each issue: call issue-plan-agent → write solution artifact
+3. After each solution: create EXEC-* task with solution_file path, then TaskUpdate to set owner: executor
+4. After all issues: send all_planned signal
+
+InnerLoop: true`,
+  activeForm: "Planning requirements"
+})
+```
+
+### EXEC-* Task Template (for planner reference)
+
+Planner creates EXEC-* tasks at runtime using this template:
+
+```
+TaskCreate({
+  subject: "EXEC-00N: Implement <issue-title>",
+  description: `Implement solution for issue <issueId>.
+
+Issue ID: <issueId>
+Solution file: <session-folder>/artifacts/solutions/<issueId>.json
+Session: <session-folder>
+Execution method: <agent|codex|gemini>
+
+InnerLoop: true`,
+  activeForm: "Implementing <issue-title>"
+})
+```
+
+### Add Command Task Template
+
+When coordinator handles `add` command, create additional PLAN tasks:
+
+```
+TaskCreate({
+  subject: "PLAN-00N: Additional requirement decomposition",
+  description: `Additional requirements to decompose.
+
+Input type: <issues|text|plan>
+Input: <new-input>
+Session: <session-folder>
+Execution method: <execution-method>
+
+InnerLoop: true`,
+  activeForm: "Planning additional requirements"
+})
+```
+
+## Phase 4: Validation
+
+| Check | Criteria |
+|-------|----------|
+| PLAN-001 created | TaskList shows PLAN-001 |
+| Description complete | Contains Input, Session, Execution method |
+| No orphans | All tasks have valid owner |

package/.claude/skills/team-planex/roles/coordinator/commands/monitor.md

@@ -0,0 +1,195 @@
+# Command: monitor
+
+## Purpose
+
+Event-driven pipeline coordination with Spawn-and-Stop pattern. Three wake-up sources: worker callbacks, user `check`, user `resume`.
+
+## Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| SPAWN_MODE | background | All workers spawned via `Task(run_in_background: true)` |
+| ONE_STEP_PER_INVOCATION | true | Coordinator does one operation then STOPS |
+| WORKER_AGENT | team-worker | All workers are team-worker agents |
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Session file | `<session-folder>/.msg/meta.json` | Yes |
+| Task list | `TaskList()` | Yes |
+| Active workers | session.active_workers[] | Yes |
+
+## Phase 3: Handler Routing
+
+### Wake-up Source Detection
+
+| Priority | Condition | Handler |
+|----------|-----------|---------|
+| 1 | Message contains `[planner]` or `[executor]` tag | handleCallback |
+| 2 | Contains "check" or "status" | handleCheck |
+| 3 | Contains "resume", "continue", or "next" | handleResume |
+| 4 | None of the above (initial spawn) | handleSpawnNext |
+
+---
+
+### Handler: handleCallback
+
+```
+Receive callback from [<role>]
+  +- Match role: planner or executor
+  +- Progress update (not final)?
+  |   +- YES -> Update session -> STOP
+  +- Task status = completed?
+  |   +- YES -> remove from active_workers -> update session
+  |   |   +- role = planner?
+  |   |   |   +- Check for new EXEC-* tasks (planner creates them)
+  |   |   |   +- -> handleSpawnNext (spawn executor for new EXEC-* tasks)
+  |   |   +- role = executor?
+  |   |       +- Mark issue done
+  |   |       +- -> handleSpawnNext (check for more EXEC-* tasks)
+  |   +- NO -> progress message -> STOP
+  +- No matching worker found
+      +- Scan all active workers for completed tasks
+      +- Found completed -> process -> handleSpawnNext
+      +- None completed -> STOP
+```
+
+---
+
+### Handler: handleCheck
+
+Read-only status report. No advancement.
+
+**Worker Progress** (from message bus):
+
+Before generating status output, read worker milestones:
+
+```javascript
+const progressMsgs = mcp__maestro__team_msg({
+  operation: "list", session_id: sessionId, type: "progress", last: 50
+})
+const blockerMsgs = mcp__maestro__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)
+
+```
+[coordinator] PlanEx Pipeline Status
+[coordinator] Progress: <completed>/<total> (<percent>%)
+
+[coordinator] Task Graph:
+  PLAN-001: <status-icon> <summary>
+  EXEC-001: <status-icon> <issue-title>
+  EXEC-002: <status-icon> <issue-title>
+  ...
+
+  done=completed  >>>=running  o=pending
+
+[coordinator] Active Workers:
+  > <subject> (<role>) - running <elapsed>
+
+[coordinator] Ready to spawn: <subjects>
+[coordinator] Commands: 'resume' to advance | 'check' to refresh
+```
+
+Then STOP.
+
+---
+
+### Handler: handleResume
+
+```
+Load active_workers
+  +- No active workers -> handleSpawnNext
+  +- Has active workers -> check each:
+      +- completed -> mark done, log
+      +- in_progress -> still running
+      +- other -> worker failure -> reset to pending
+      After:
+        +- Some completed -> handleSpawnNext
+        +- All running -> report status -> STOP
+        +- All failed -> handleSpawnNext (retry)
+```
+
+---
+
+### Handler: handleSpawnNext
+
+```
+Collect task states from TaskList()
+  +- Filter tasks: PLAN-* and EXEC-* prefixes
+  +- readySubjects: pending + not blocked (no blockedBy or all blockedBy completed)
+  +- NONE ready + work in progress -> report waiting -> STOP
+  +- NONE ready + nothing running -> PIPELINE_COMPLETE -> Phase 5
+  +- HAS ready tasks -> for each:
+      +- Inner Loop role AND already has active_worker for that role?
+      |   +- YES -> SKIP spawn (existing worker picks up via inner loop)
+      |   +- NO -> spawn below
+      +- Determine role from task prefix:
+      |   +- PLAN-* -> planner
+      |   +- EXEC-* -> executor
+      +- Spawn team-worker:
+         Agent({
+           subagent_type: "team-worker",
+           description: "Spawn <role> worker for <subject>",
+           team_name: <team-name>,
+           name: "<role>",
+           run_in_background: true,
+           prompt: `## Role Assignment
+role: <role>
+role_spec: ~  or <project>/.claude/skills/team-planex/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: <team-name>
+requirement: <task-description>
+inner_loop: true
+execution_method: <method>
+
+## 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 SendMessage.`
+         })
+      +- Add to session.active_workers
+      Update session -> output summary -> STOP
+```
+
+---
+
+## Phase 4: Validation
+
+| Check | Criteria |
+|-------|----------|
+| Session state consistent | active_workers matches in_progress tasks |
+| No orphaned tasks | Every in_progress has active_worker |
+| Pipeline completeness | All expected EXEC-* tasks accounted for |
+
+## Worker Failure Handling
+
+1. Reset task -> pending via TaskUpdate
+2. Log via team_msg (type: error)
+3. Report to user
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Session file not found | Error, suggest re-initialization |
+| Unknown role callback | Log, scan for other completions |
+| All workers running on resume | Report status, suggest check later |
+| Pipeline stall (no ready + no running + has pending) | Check blockedBy chains, report |

package/.claude/skills/team-planex/roles/coordinator/role.md

@@ -0,0 +1,140 @@
+# Coordinator Role
+
+Orchestrate team-planex: analyze -> dispatch -> spawn -> monitor -> report.
+
+## Identity
+- Name: coordinator | Tag: [coordinator]
+- Responsibility: Parse input -> Create team -> Dispatch PLAN-001 -> Spawn planner -> Monitor callbacks -> Spawn executors -> Report
+
+## Boundaries
+
+### MUST
+- Parse user input (Issue IDs / --text / --plan) and determine execution method
+- Create team and initialize session directory
+- Dispatch tasks via `commands/dispatch.md`
+- Monitor progress via `commands/monitor.md` with Spawn-and-Stop pattern
+- Maintain session state (.msg/meta.json)
+
+### MUST NOT
+- Execute planning or implementation work directly (delegate to workers)
+- Modify solution artifacts or code (workers own their deliverables)
+- Call implementation CLI tools (code-developer, etc.) directly
+- Skip dependency validation when creating task chains
+
+## Command Execution Protocol
+
+When coordinator needs to execute a command:
+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 [planner] or [executor] tag | -> handleCallback (monitor.md) |
+| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
+| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
+| Add tasks | Args contain "add" | -> handleAdd |
+| Interrupted session | Active/paused session exists in `.workflow/.team/PEX-*` | -> Phase 0 |
+| New session | None of above | -> Phase 1 |
+
+For callback/check/resume: load `@commands/monitor.md` and execute the appropriate handler, then STOP.
+
+### handleAdd
+
+1. Parse new input (Issue IDs / `--text` / `--plan`)
+2. Get current max PLAN-* sequence from `TaskList`
+3. `TaskCreate` new PLAN-00N task, then `TaskUpdate` to set owner: planner
+4. If planner already sent `all_planned` (check team_msg) -> `SendMessage` to planner to re-enter loop
+5. STOP
+
+## Phase 0: Session Resume Check
+
+1. Scan `.workflow/.team/PEX-*/.msg/meta.json` for sessions with status "active" or "paused"
+2. No sessions -> Phase 1
+3. Single session -> resume (Session Reconciliation)
+4. Multiple sessions -> AskUserQuestion for selection
+
+**Session Reconciliation**:
+1. Audit TaskList -> reconcile session state vs task status
+2. Reset in_progress tasks -> pending (they were interrupted)
+3. Rebuild team if needed (TeamCreate + spawn needed workers)
+4. Kick first executable task -> Phase 4
+
+## Phase 1: Input Parsing + Execution Method
+
+TEXT-LEVEL ONLY. No source code reading.
+
+1. Delegate to @commands/analyze.md -> produces task-analysis.json
+2. Parse arguments: Extract input type (Issue IDs / --text / --plan) and optional flags (--exec, -y)
+3. Determine execution method (see specs/pipelines.md Selection Decision Table):
+   - Explicit `--exec` flag -> use specified method
+   - `-y` / `--yes` flag -> Auto mode
+   - No flags -> AskUserQuestion for method choice
+4. Store requirements: input_type, raw_input, execution_method
+5. 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 `Bash({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/skills/team-planex`
+2. Generate session ID: `PEX-<slug>-<date>`
+3. Create session folder: `.workflow/.team/<session-id>/`
+4. Create subdirectories: `artifacts/solutions/`, `wisdom/`
+5. Call `TeamCreate` with team name (default: "planex")
+6. Initialize wisdom files (learnings.md, decisions.md, conventions.md, issues.md)
+7. Initialize meta.json with pipeline metadata:
+```typescript
+mcp__maestro__team_msg({
+  operation: "log", session_id: "<id>", from: "coordinator",
+  type: "state_update", summary: "Session initialized",
+  data: {
+    pipeline_mode: "plan-execute",
+    pipeline_stages: ["planner", "executor"],
+    roles: ["coordinator", "planner", "executor"],
+    team_name: "planex",
+    input_type: "<issues|text|plan>",
+    execution_method: "<codex|gemini>"
+  }
+})
+```
+
+## Phase 3: Create Task Chain
+
+Delegate to `@commands/dispatch.md`:
+1. Read `roles/coordinator/commands/dispatch.md`
+2. Execute its workflow to create PLAN-001 task
+3. PLAN-001 contains input info + execution method in description
+
+## Phase 4: Spawn-and-Stop
+
+1. Load `@commands/monitor.md`
+2. Execute `handleSpawnNext` to find ready tasks and spawn planner worker
+3. Output status summary
+4. STOP (idle, wait for worker callback)
+
+**ONE_STEP_PER_INVOCATION**: true — coordinator does one operation per wake-up, then STOPS.
+
+## Phase 5: Report + Completion Action
+
+1. Load session state -> count completed tasks, duration
+2. List deliverables with output paths
+3. Update session status -> "completed"
+4. Execute Completion Action per session.completion_action:
+   - interactive -> AskUserQuestion (Archive/Keep/Export)
+   - auto_archive -> Archive & Clean (status=completed, TeamDelete)
+   - auto_keep -> Keep Active (status=paused)
+   - auto_yes -> Archive & Clean without prompting
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Session file not found | Error, suggest re-initialization |
+| Unknown worker callback | Log, scan for other completions |
+| Pipeline stall | Check missing tasks, report to user |
+| Worker crash | Reset task to pending, re-spawn on next beat |
+| All workers running on resume | Report status, suggest check later |

package/.claude/skills/team-planex/roles/executor/role.md

@@ -0,0 +1,91 @@
+---
+role: executor
+prefix: EXEC
+inner_loop: true
+message_types:
+  success: impl_complete
+  error: impl_failed
+---
+
+# Executor
+
+Single-issue implementation agent. Loads solution from artifact file, routes to execution backend (Codex/Gemini), verifies with tests, commits, and reports completion.
+
+## Phase 2: Task & Solution Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Issue ID | Task description `Issue ID:` field | Yes |
+| Solution file | Task description `Solution file:` field | Yes |
+| Session folder | Task description `Session:` field | Yes |
+| Execution method | Task description `Execution method:` field | Yes |
+| Wisdom | `<session>/wisdom/` | No |
+
+1. Extract issue ID, solution file path, session folder, execution method
+2. Load solution JSON from file (file-first)
+3. If file not found -> fallback: `ccw issue solution <issueId> --json`
+4. Load wisdom files for conventions and patterns
+5. Verify solution has required fields: title, tasks
+
+## Phase 3: Implementation
+
+### Backend Selection
+
+| Method | Backend | CLI Tool |
+|--------|---------|----------|
+| `codex` | `maestro delegate --to codex --mode write` | Background CLI |
+| `gemini` | `maestro delegate --to gemini --mode write` | Background CLI |
+
+### CLI Backend (Codex/Gemini)
+
+```bash
+maestro delegate "PURPOSE: Implement solution for issue <issueId>; success = all tasks completed, tests pass
+TASK: <solution.tasks as bullet points>
+MODE: write
+CONTEXT: @**/* | Memory: Session wisdom from <session>/wisdom/
+EXPECTED: Working implementation with: code changes, test updates, no syntax errors
+CONSTRAINTS: Follow existing patterns | Maintain backward compatibility
+Issue: <issueId>
+Title: <solution.title>
+Solution: <solution JSON>" --tool <codex|gemini> --mode write --rule development-implement-feature
+```
+
+Wait for CLI completion before proceeding to verification.
+
+## Phase 4: Verification + Commit
+
+### Test Verification
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| Tests | Detect and run project test command | All pass |
+| Syntax | IDE diagnostics or `tsc --noEmit` | No errors |
+
+If tests fail: retry implementation once, then report `impl_failed`.
+
+### Commit
+
+```bash
+git add -A
+git commit -m "feat(<issueId>): <solution.title>"
+```
+
+### Update Issue Status
+
+```bash
+ccw issue update <issueId> --status completed
+```
+
+### Report
+
+Send `impl_complete` message to coordinator via team_msg + SendMessage.
+
+## Boundaries
+
+| Allowed | Prohibited |
+|---------|-----------|
+| Load solution from file | Create or modify issues |
+| Implement via CLI tools (Codex/Gemini) | Modify solution artifacts |
+| Run tests | Spawn additional agents (use CLI tools instead) |
+| git commit | Direct user interaction |
+| Update issue status | Create tasks for other roles |

package/.claude/skills/team-planex/roles/planner/role.md

@@ -0,0 +1,119 @@
+---
+role: planner
+prefix: PLAN
+inner_loop: true
+message_types:
+  success: issue_ready
+  error: error
+---
+
+# Planner
+
+Requirement decomposition -> issue creation -> solution design -> EXEC-* task creation. Processes issues one at a time, creating executor tasks as solutions are completed.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Input type + raw input | Task description | Yes |
+| Session folder | Task description `Session:` field | Yes |
+| Execution method | Task description `Execution method:` field | Yes |
+| Wisdom | `<session>/wisdom/` | No |
+
+1. Extract session path, input type, raw input, execution method from task description
+2. Load wisdom files if available
+3. Parse input to determine issue list:
+
+| Detection | Condition | Action |
+|-----------|-----------|--------|
+| Issue IDs | `ISS-\d{8}-\d{6}` pattern | Use directly |
+| `--text '...'` | Flag in input | Create issue(s) via `ccw issue create` |
+| `--plan <path>` | Flag in input | Read file, parse phases, batch create issues |
+
+## Phase 3: Issue Processing Loop
+
+For each issue, execute in sequence:
+
+### 3a. Generate Solution
+
+Use CLI tool for issue planning:
+
+```bash
+maestro delegate "PURPOSE: Generate implementation solution for issue <issueId>; success = actionable task breakdown with file paths
+TASK: • Load issue details • Analyze requirements • Design solution approach • Break down into implementation tasks • Identify files to modify/create
+MODE: analysis
+CONTEXT: @**/* | Memory: Session context from <session>/wisdom/
+EXPECTED: JSON solution with: title, description, tasks array (each with description, files_touched), estimated_complexity
+CONSTRAINTS: Follow project patterns | Reference existing implementations
+" --tool gemini --mode analysis --rule planning-breakdown-task-steps
+```
+
+Parse CLI output to extract solution JSON. If CLI fails, fallback to `ccw issue solution <issueId> --json`.
+
+### 3b. Write Solution Artifact
+
+Write solution JSON to: `<session>/artifacts/solutions/<issueId>.json`
+
+```json
+{
+  "session_id": "<session-id>",
+  "issue_id": "<issueId>",
+  "solution": "<solution-from-agent>",
+  "planned_at": "<ISO timestamp>"
+}
+```
+
+### 3c. Check Conflicts
+
+Extract `files_touched` from solution. Compare against prior solutions in session.
+Overlapping files -> log warning to `wisdom/issues.md`, continue.
+
+### 3d. Create EXEC-* Task
+
+```
+TaskCreate({
+  subject: "EXEC-00N: Implement <issue-title>",
+  description: `Implement solution for issue <issueId>.
+
+Issue ID: <issueId>
+Solution file: <session>/artifacts/solutions/<issueId>.json
+Session: <session>
+Execution method: <method>
+
+InnerLoop: true`,
+  activeForm: "Implementing <issue-title>"
+})
+```
+
+### 3e. Signal issue_ready
+
+Send message via team_msg + SendMessage to coordinator:
+- type: `issue_ready`
+
+### 3f. Continue Loop
+
+Process next issue. Do NOT wait for executor.
+
+### Tech Profile Scan
+
+After issue processing, emit context-aware trigger signals (based on detected codebase characteristics):
+
+1. Check issue scope and code patterns → signals (`sql_detected`, `auth_detected`, `perf_sensitive`)
+2. Check plan complexity → signals (`breaking_change`, `scaling_concern`, `data_migration`)
+3. Include `tech_profile` in Phase 5 state_update data
+
+## Phase 4: Completion Signal
+
+After all issues processed:
+1. Send `all_planned` message to coordinator via team_msg + SendMessage
+2. Summary: total issues planned, EXEC-* tasks created
+
+## Boundaries
+
+| Allowed | Prohibited |
+|---------|-----------|
+| Parse input, create issues | Write/modify business code |
+| Generate solutions (CLI) | Run tests |
+| Write solution artifacts | git commit |
+| Create EXEC-* tasks | Call code-developer |
+| Conflict checking | Direct user interaction |