maestro-flow 0.5.31 → 0.5.33

package/.agents/skills/team-roadmap-dev/roles/coordinator/commands/pause.md

@@ -0,0 +1,90 @@
+# Command: pause
+
+Save session state and exit cleanly. Allows resumption later via resume command.
+
+## Purpose
+
+Persist the current execution state (phase, step, pending tasks) to state.md so the session can be resumed from exactly where it stopped. This is the coordinator's mechanism for handling user "Stop" requests at phase boundaries or gap closure gates.
+
+## When to Use
+
+- User selects "Stop" at any interactive gate in monitor.md
+- User requests pause during roadmap discussion
+- External interruption requires graceful shutdown
+
+## Parameters
+
+| Parameter | Source | Description |
+|-----------|--------|-------------|
+| `sessionFolder` | From coordinator | Session artifact directory |
+| `currentPhase` | From monitor loop | Phase number at pause time |
+| `currentStep` | From monitor loop | Step within phase (plan/exec/verify/gap_closure) |
+| `gapIteration` | From monitor loop | Current gap closure iteration (0 = none) |
+
+## Execution Steps
+
+### Step 1: Capture Current State
+
+```javascript
+const state = read_file(`${sessionFolder}/state.md`)
+const timestamp = new Date().toISOString().slice(0, 19)
+
+// Capture pending task states
+const allTasks = list_tasks()
+const pendingTasks = allTasks.filter(t =>
+  t.status === 'pending' || t.status === 'in_progress'
+)
+```
+
+### Step 2: Update state.md with Pause Marker
+
+```javascript
+// Find the current phase status line and update it
+edit_file(`${sessionFolder}/state.md`, {
+  old_string: `- Status: in_progress`,
+  new_string: `- Status: paused
+- Paused At: ${timestamp}
+- Paused Phase: ${currentPhase}
+- Paused Step: ${currentStep}
+- Gap Iteration: ${gapIteration}
+- Pending Tasks: ${pendingTasks.map(t => t.subject).join(', ')}`
+})
+```
+
+### Step 3: Log Pause Event
+
+```javascript
+mcp__maestro__team_msg({
+  operation: "log", session_id: sessionId,
+  from: "coordinator", to: "all",
+  type: "phase_paused",
+  data: { ref: `${sessionFolder}/state.md` }
+})
+```
+
+### Step 4: Report to User
+
+```javascript
+// Output pause summary
+const summary = `[coordinator] Session paused.
+- Phase: ${currentPhase}
+- Step: ${currentStep}
+- Gap Iteration: ${gapIteration}
+- Pending Tasks: ${pendingTasks.length}
+
+To resume: invoke_skill(skill="team-roadmap-dev", args="--resume ${sessionFolder}")
+`
+```
+
+## Output
+
+| Artifact | Path | Description |
+|----------|------|-------------|
+| state.md | `{sessionFolder}/state.md` | Updated with paused status and resume coordinates |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| state.md edit fails | Write full state.md from scratch with pause info |
+| Task list unavailable | Record phase/step only, skip task listing |

package/.agents/skills/team-roadmap-dev/roles/coordinator/commands/resume.md

@@ -0,0 +1,137 @@
+# Command: resume
+
+Resume a paused roadmap-dev session from its saved state. Reads pause coordinates from state.md and re-enters the monitor loop at the exact phase and step where execution was paused.
+
+## Purpose
+
+Restore execution context from a paused session and continue the monitor loop. This is the coordinator's mechanism for resuming long-running projects across sessions.
+
+## When to Use
+
+- User invokes `invoke_skill(skill="team-roadmap-dev", args="--resume {sessionFolder}")`
+- Coordinator detects a paused session during init
+
+## Parameters
+
+| Parameter | Source | Description |
+|-----------|--------|-------------|
+| `sessionFolder` | From --resume argument | Session artifact directory to resume |
+
+## Execution Steps
+
+### Step 1: Validate Session State
+
+```javascript
+const stateContent = read_file(`${sessionFolder}/state.md`)
+
+// Check for paused status
+if (!stateContent.includes('Status: paused')) {
+  // Session is not paused — check if it's in_progress or completed
+  if (stateContent.includes('Status: completed')) {
+    // Session already finished
+    return { error: "Session already completed", sessionFolder }
+  }
+  // Not paused, not completed — treat as fresh continue
+}
+
+// Parse resume coordinates
+const pausedPhase = parseInt(stateContent.match(/Paused Phase: (\d+)/)?.[1] || '1')
+const pausedStep = stateContent.match(/Paused Step: (\w+)/)?.[1] || 'plan'
+const gapIteration = parseInt(stateContent.match(/Gap Iteration: (\d+)/)?.[1] || '0')
+```
+
+### Step 2: Load Session Context
+
+```javascript
+const roadmap = read_file(`${sessionFolder}/roadmap.md`)
+const config = JSON.parse(read_file(`${sessionFolder}/config.json`))
+
+// Load project context
+const projectTech = JSON.parse(read_file('.workflow/project-tech.json'))
+```
+
+### Step 3: Update State to In-Progress
+
+```javascript
+const timestamp = new Date().toISOString().slice(0, 19)
+
+edit_file(`${sessionFolder}/state.md`, {
+  old_string: `- Status: paused`,
+  new_string: `- Status: in_progress
+- Resumed At: ${timestamp}
+- Resumed From Phase: ${pausedPhase}, Step: ${pausedStep}`
+})
+```
+
+### Step 4: Log Resume Event
+
+```javascript
+mcp__maestro__team_msg({
+  operation: "log", session_id: sessionId,
+  from: "coordinator", to: "all",
+  type: "phase_started",
+  data: { ref: `${sessionFolder}/state.md` }
+})
+```
+
+### Step 5: Re-enter monitor_process Loop
+
+```javascript
+// Delegate to monitor.md with resume context
+// monitor.md receives:
+//   - startPhase: pausedPhase (instead of 1)
+//   - startStep: pausedStep (plan/exec/verify/gap_closure)
+//   - gapIteration: gapIteration (for gap closure continuity)
+
+read_file("commands/monitor.md")
+// monitor_process will:
+//   1. Skip phases before pausedPhase
+//   2. Within pausedPhase, skip steps before pausedStep
+//   3. Continue normal execution from that point
+```
+
+### Step 6: Determine Resume Entry Point
+
+```javascript
+// Map pausedStep to monitor entry point
+switch (pausedStep) {
+  case 'plan':
+    // Re-dispatch planner for current phase
+    // Check if PLAN task exists and is pending/incomplete
+    break
+
+  case 'exec':
+    // Re-dispatch executor for current phase
+    // Check if EXEC task exists and is pending/incomplete
+    break
+
+  case 'verify':
+    // Re-dispatch verifier for current phase
+    break
+
+  case 'gap_closure':
+    // Re-enter gap closure loop at gapIteration
+    break
+
+  case 'transition':
+    // Phase was complete, proceed to next phase
+    break
+}
+```
+
+## Output
+
+| Artifact | Path | Description |
+|----------|------|-------------|
+| state.md | `{sessionFolder}/state.md` | Updated with resumed status |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Session folder not found | Error with available session list |
+| state.md missing | Error — session may be corrupted |
+| Session not paused | Check if in_progress or completed, handle accordingly |
+| Roadmap.md missing | Error — session artifacts may be incomplete |
+| config.json missing | Use defaults (mode=interactive, depth=standard) |
+| Tasks from prior run still pending | Re-use them, don't create duplicates |

package/.agents/skills/team-roadmap-dev/roles/coordinator/commands/roadmap-discuss.md

@@ -0,0 +1,287 @@
+# Command: roadmap-discuss
+
+Interactive roadmap discussion with the user. This is the KEY coordinator command -- no work begins until the roadmap is agreed upon.
+
+## Purpose
+
+Discuss project roadmap with the user using project-tech.json + specs/*.md as context. Elicit phases, requirements, success criteria, and execution preferences. Produces `roadmap.md` and `config.json` as session artifacts.
+
+## When to Use
+
+- Phase 2 of coordinator lifecycle (after init prerequisites, before dispatch)
+- Called exactly once per session (re-entry updates existing roadmap)
+
+## Strategy
+
+Direct interaction via ask_user. No delegation to workers or CLI tools. Coordinator handles this entirely.
+
+## Parameters
+
+| Parameter | Source | Description |
+|-----------|--------|-------------|
+| `sessionFolder` | From coordinator Phase 1 | Session artifact directory |
+| `taskDescription` | From coordinator Phase 1 | User's original task description |
+| `projectTech` | Loaded in Phase 1 | Parsed project-tech.json |
+| `projectGuidelines` | Loaded in Phase 1 | Parsed specs/*.md (nullable) |
+| `autoYes` | From -y/--yes flag | Skip interactive prompts, use defaults |
+
+## Execution Steps
+
+### Step 1: Load Project Context
+
+```javascript
+// Already loaded by coordinator Phase 1, but verify availability
+const projectTech = JSON.parse(read_file('.workflow/project-tech.json'))
+let projectGuidelines = null
+try {
+  projectGuidelines = JSON.parse(read_file('.workflow/specs/*.md'))
+} catch {}
+```
+
+### Step 2: Present Project Overview to User
+
+```javascript
+// Summarize what we know about the project
+const overview = `[coordinator] Project context loaded.
+- Project: ${projectTech.project_name}
+- Tech Stack: ${projectTech.tech_stack?.join(', ')}
+- Task: ${taskDescription}
+${projectGuidelines ? `- Guidelines: ${projectGuidelines.conventions?.length || 0} conventions loaded` : '- Guidelines: not configured'}`
+
+// Display overview (via direct output, not ask_user)
+```
+
+### Step 3: Confirm Project Goal and Scope
+
+```javascript
+// Skip if taskDescription is already detailed enough, or autoYes
+if (!autoYes && !taskDescription) {
+  ask_user({
+    questions: [{
+      question: "What is the project goal and scope for this session?",
+      header: "Goal",
+      multiSelect: false,
+      options: [] // Free-form text input
+    }]
+  })
+}
+// Store response as `projectGoal`
+const projectGoal = taskDescription || userResponse
+```
+
+### Step 4: Ask Execution Mode
+
+```javascript
+if (!autoYes) {
+  ask_user({
+    questions: [{
+      question: "How should phase transitions be handled?",
+      header: "Execution Mode",
+      multiSelect: false,
+      options: [
+        { label: "interactive", description: "Ask for confirmation at each phase transition" },
+        { label: "yolo", description: "Auto-execute all phases without stopping" },
+        { label: "custom", description: "Choose which gates require confirmation" }
+      ]
+    }]
+  })
+} else {
+  mode = "yolo"
+}
+
+// If "custom" selected, follow up with gate selection:
+if (mode === "custom") {
+  ask_user({
+    questions: [{
+      question: "Which gates should require confirmation?",
+      header: "Custom Gates",
+      multiSelect: true,
+      options: [
+        { label: "plan_check", description: "Review plan before execution" },
+        { label: "verifier", description: "Review verification results before next phase" },
+        { label: "gap_closure", description: "Confirm gap closure before re-execution" }
+      ]
+    }]
+  })
+}
+```
+
+### Step 5: Ask Analysis Depth
+
+```javascript
+if (!autoYes) {
+  ask_user({
+    questions: [{
+      question: "How thorough should the analysis be?",
+      header: "Analysis Depth",
+      multiSelect: false,
+      options: [
+        { label: "quick", description: "Fast scan, minimal context gathering (small tasks)" },
+        { label: "standard", description: "Balanced analysis with key context (default)" },
+        { label: "comprehensive", description: "Deep analysis, full codebase exploration (large refactors)" }
+      ]
+    }]
+  })
+} else {
+  depth = "standard"
+}
+```
+
+### Step 6: Analyze Codebase and Generate Phased Roadmap
+
+```javascript
+// Use Gemini CLI (or CLI exploration tool) to analyze the codebase
+// and generate a phased breakdown based on goal + project context
+shell({
+  command: `maestro delegate "PURPOSE: Analyze codebase and generate phased execution roadmap for: ${projectGoal}
+TASK: \
+  - Scan project structure and identify affected modules \
+  - Break goal into sequential phases (max 5) \
+  - Each phase: goal, requirements (REQ-IDs), success criteria (2-5 testable behaviors) \
+  - Order phases by dependency (foundational first)
+MODE: analysis
+CONTEXT: @**/* | Memory: Tech stack: ${projectTech.tech_stack?.join(', ')}
+EXPECTED: Phased roadmap in markdown with REQ-IDs and testable success criteria
+CONSTRAINTS: Max 5 phases | Each phase independently verifiable | No implementation details" \
+  --tool gemini --mode analysis --rule planning-breakdown-task-steps`,
+  run_in_background: false,
+  timeout: 300000
+})
+
+// Parse the CLI output into structured phases
+```
+
+### Step 7: Present Roadmap Draft for Confirmation
+
+```javascript
+// Display the generated roadmap to user
+// Output the roadmap content directly, then ask for adjustments
+
+ask_user({
+  questions: [{
+    question: "Review the roadmap above. Any adjustments needed?",
+    header: "Roadmap Review",
+    multiSelect: false,
+    options: [
+      { label: "Looks good, proceed", description: "Accept roadmap as-is" },
+      { label: "Adjust phases", description: "I want to modify the phase breakdown" },
+      { label: "Add requirements", description: "I want to add missing requirements" },
+      { label: "Change scope", description: "Narrow or expand the scope" }
+    ]
+  }]
+})
+
+// If user requests adjustments, incorporate feedback and re-present
+// Loop until user confirms "Looks good, proceed"
+```
+
+### Step 8: Generate Session Artifacts
+
+#### roadmap.md
+
+```javascript
+write_file(`${sessionFolder}/roadmap.md`, roadmapContent)
+```
+
+**roadmap.md format**:
+
+```markdown
+# Roadmap: {projectGoal}
+
+Generated: {date}
+Session: {sessionFolder}
+Depth: {depth}
+
+## Phase 1: {phase title}
+
+**Goal**: {one-line goal}
+
+**Requirements**:
+- REQ-101: {requirement description}
+- REQ-102: {requirement description}
+
+**Success Criteria**:
+- [ ] {testable behavior 1}
+- [ ] {testable behavior 2}
+- [ ] {testable behavior 3}
+
+**Plan Count**: TBD
+
+---
+
+## Phase 2: {phase title}
+
+**Goal**: {one-line goal}
+
+**Requirements**:
+- REQ-201: {requirement description}
+
+**Success Criteria**:
+- [ ] {testable behavior 1}
+- [ ] {testable behavior 2}
+
+**Plan Count**: TBD
+
+---
+
+(... additional phases ...)
+```
+
+**REQ-ID Convention**: `REQ-{phase}{seq}` (e.g., REQ-101 = Phase 1, requirement 1)
+
+#### config.json
+
+```javascript
+write_file(`${sessionFolder}/config.json`, JSON.stringify({
+  mode: mode,           // "interactive" | "yolo" | "custom"
+  depth: depth,         // "quick" | "standard" | "comprehensive"
+  auto_advance: mode === "yolo",
+  gates: {
+    plan_check: mode === "interactive" || (mode === "custom" && customGates.includes("plan_check")),
+    verifier: mode === "interactive" || (mode === "custom" && customGates.includes("verifier")),
+    gap_closure: mode === "interactive" || (mode === "custom" && customGates.includes("gap_closure"))
+  }
+}, null, 2))
+```
+
+**config.json format**:
+
+```json
+{
+  "mode": "interactive",
+  "depth": "standard",
+  "auto_advance": false,
+  "gates": {
+    "plan_check": true,
+    "verifier": true,
+    "gap_closure": true
+  }
+}
+```
+
+### Step 9: Update state.md
+
+```javascript
+// Transition Phase 0 → Phase 1
+edit_file(`${sessionFolder}/state.md`, {
+  old_string: "- Phase: 0 (Roadmap Discussion)\n- Status: initializing",
+  new_string: `- Phase: 1\n- Status: ready_to_dispatch\n- Roadmap: confirmed (${phaseCount} phases)\n- Mode: ${mode}\n- Depth: ${depth}`
+})
+```
+
+## Output
+
+| Artifact | Path | Description |
+|----------|------|-------------|
+| roadmap.md | `{sessionFolder}/roadmap.md` | Phased plan with REQ-IDs and success criteria |
+| config.json | `{sessionFolder}/config.json` | Execution preferences |
+| state.md | `{sessionFolder}/state.md` | Updated with phase transition |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| User provides no goal | Re-prompt with examples |
+| CLI analysis fails | Retry with simpler prompt, or ask user to describe phases manually |
+| User keeps adjusting roadmap | Max 5 adjustment rounds, then proceed with latest version |
+| autoYes flag set | Skip all ask_user calls, use defaults: mode=yolo, depth=standard |