maestro-flow 0.5.31 → 0.5.33

package/.agents/skills/team-designer/phases/03-content-generation.md

@@ -0,0 +1,330 @@
+# Phase 3: Content Generation
+
+Generate all role files, specs, and templates based on `teamConfig` and the generated SKILL.md.
+
+## Objective
+
+- Generate coordinator role.md + commands/ (analyze, dispatch, monitor)
+- Generate each worker role.md (inline or with commands/)
+- Generate specs/ files (pipelines.md + domain specs)
+- Generate templates/ if needed
+- Follow team-lifecycle-v4 golden sample patterns
+
+## Golden Sample Reference
+
+Read the golden sample at `~  or <project>/.claude/skills/team-lifecycle-v4/` for each file type before generating. This ensures pattern fidelity.
+
+## Step 3.1: Generate Coordinator
+
+The coordinator is the most complex role. It always has 3 commands.
+
+### coordinator/role.md
+
+```markdown
+---
+role: coordinator
+---
+
+# Coordinator — ${teamConfig.title}
+
+## Identity
+
+You are the coordinator for ${teamConfig.title}. You orchestrate the ${teamConfig.domain} pipeline by analyzing requirements, dispatching tasks, and monitoring worker progress.
+
+## Boundaries
+
+- **DO**: Analyze, dispatch, monitor, reconcile, report
+- **DO NOT**: Implement domain work directly — delegate to workers
+
+## Command Execution Protocol
+
+Read command file → Execute ALL steps sequentially → Return to entry router.
+Commands: `commands/analyze.md`, `commands/dispatch.md`, `commands/monitor.md`.
+
+## Entry Router
+
+On each invocation, detect current state and route:
+
+| Condition | Handler |
+|-----------|---------|
+| First invocation (no session) | → Phase 1: Requirement Clarification |
+| Session exists, no team | → Phase 2: Team Setup |
+| Team exists, no tasks | → Phase 3: Dispatch (analyze.md → dispatch.md) |
+| Tasks exist, none started | → Phase 4: Spawn First (monitor.md → handleSpawnNext) |
+| Callback received | → monitor.md → handleCallback |
+| User says "check"/"status" | → monitor.md → handleCheck |
+| User says "resume"/"continue" | → monitor.md → handleResume |
+| All tasks completed | → Phase 5: Report & Completion |
+
+## Phase 0: Session Resume
+
+If `.workflow/.team/${teamConfig.sessionPrefix}-*/team-session.json` exists:
+- Load session state, verify team, reconcile task status
+- Route to appropriate handler based on current state
+
+## Phase 1: Requirement Clarification
+
+- Parse user's task description at TEXT LEVEL
+- Use ask_user if requirements are ambiguous
+- Execute `commands/analyze.md` for signal detection + complexity scoring
+
+## Phase 2: Team Setup
+
+- create_team with session ID: `${teamConfig.sessionPrefix}-<slug>-<date>`
+- Initialize team_msg message bus
+- Create session directory structure
+
+## Phase 3: Dispatch
+
+- Execute `commands/dispatch.md`
+- Creates create_task calls, then sets dependencies via update_task({ addBlockedBy })
+
+## Phase 4: Spawn & monitor_process
+
+- Execute `commands/monitor.md` → handleSpawnNext
+- Spawn ready workers as team-worker agents
+- **STOP after spawning** — wait for callback
+
+## Phase 5: Report & Completion
+
+- Aggregate all task artifacts
+- Present completion action to user
+```
+
+### coordinator/commands/analyze.md
+
+Template based on golden sample — includes:
+- Signal detection (keywords → capabilities)
+- Dependency graph construction (tiers)
+- Complexity scoring (1-3 Low, 4-6 Medium, 7+ High)
+- Role minimization (cap at 5)
+- Output: task-analysis.json
+
+```markdown
+# Command: Analyze
+
+## Signal Detection
+
+Scan requirement text for capability signals:
+${teamConfig.roles.filter(r => r.name !== 'coordinator').map(r =>
+  `- **${r.name}**: [domain-specific keywords]`
+).join('\n')}
+
+## Dependency Graph
+
+Build 4-tier dependency graph:
+- Tier 0: Independent tasks (can run in parallel)
+- Tier 1: Depends on Tier 0
+- Tier 2: Depends on Tier 1
+- Tier 3: Depends on Tier 2
+
+## Complexity Scoring
+
+| Score | Level | Strategy |
+|-------|-------|----------|
+| 1-3 | Low | Direct implementation, skip deep planning |
+| 4-6 | Medium | Standard pipeline with planning |
+| 7+ | High | Full spec → plan → implement cycle |
+
+## Output
+
+Write `task-analysis.json` to session directory:
+\```json
+{
+  "signals": [...],
+  "roles_needed": [...],
+  "dependency_tiers": [...],
+  "complexity": { "score": N, "level": "Low|Medium|High" },
+  "pipeline": "${teamConfig.pipelines[0].name}"
+}
+\```
+```
+
+### coordinator/commands/dispatch.md
+
+Template — includes:
+- Topological sort from dependency graph
+- create_task + update_task({ addBlockedBy }) for dependencies
+- Task description template (PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS)
+
+### coordinator/commands/monitor.md
+
+Template — includes:
+- Beat model constants (ONE_STEP_PER_INVOCATION, SPAWN_MODE: spawn-and-stop)
+- 6 handlers: handleCallback, handleCheck, handleResume, handleSpawnNext, handleComplete, handleAdapt
+- Checkpoint detection for quality gates
+- Fast-advance reconciliation
+
+**Critical**: This is the ONLY file that contains beat model logic.
+
+## Step 3.2: Generate Worker Roles
+
+For each worker role in `teamConfig.roles`:
+
+### Inline Role Template (no commands/)
+
+```markdown
+---
+role: ${role.name}
+prefix: ${role.prefix}
+inner_loop: ${role.inner_loop}
+message_types: [${role.message_types.join(', ')}]
+---
+
+# ${capitalize(role.name)} — ${teamConfig.title}
+
+## Identity
+
+You are the ${role.name} for ${teamConfig.title}.
+Task prefix: `${role.prefix}-*`
+
+## Phase 2: Context Loading
+
+- Read task description from get_task
+- Load relevant session artifacts from session directory
+- Load specs from `specs/` as needed
+
+## Phase 3: Domain Execution
+
+[Domain-specific execution logic for this role]
+
+### Execution Steps
+
+1. [Step 1 based on role's domain]
+2. [Step 2]
+3. [Step 3]
+
+### Tools Available
+
+- CLI tools: `maestro delegate --mode analysis|write`
+- Direct tools: Read, Write, Edit, Bash, Grep, Glob
+- Message bus: `mcp__maestro__team_msg`
+- **Cannot use delegate_subagent()** — workers must use CLI or direct tools
+
+## Phase 4: Output & Report
+
+- Write artifacts to session directory
+- Log state_update via team_msg
+- Publish wisdom if cross-task knowledge discovered
+```
+
+### Command-Based Role Template (has commands/)
+
+```markdown
+---
+role: ${role.name}
+prefix: ${role.prefix}
+inner_loop: ${role.inner_loop}
+message_types: [${role.message_types.join(', ')}]
+---
+
+# ${capitalize(role.name)} — ${teamConfig.title}
+
+## Identity
+
+You are the ${role.name} for ${teamConfig.title}.
+Task prefix: `${role.prefix}-*`
+
+## Phase 2: Context Loading
+
+Load task description, detect mode/command.
+
+## Phase 3: Command Router
+
+| Condition | Command |
+|-----------|---------|
+${role.commands.map(cmd =>
+  `| [condition for ${cmd}] | → commands/${cmd}.md |`
+).join('\n')}
+
+Read command file → Execute ALL steps → Return to Phase 4.
+
+## Phase 4: Output & Report
+
+Write artifacts, log state_update.
+```
+
+Then generate each `commands/<cmd>.md` with domain-specific logic.
+
+## Step 3.3: Generate Specs
+
+### specs/pipelines.md
+
+```markdown
+# Pipeline Definitions
+
+## Available Pipelines
+
+${teamConfig.pipelines.map(p => `
+### ${p.name}
+
+| Task ID | Role | Name | Depends On | Checkpoint |
+|---------|------|------|------------|------------|
+${p.tasks.map(t =>
+  `| ${t.id} | ${t.role} | ${t.name} | ${t.dependsOn.join(', ') || '—'} | ${t.isCheckpoint ? '✓' : '—'} |`
+).join('\n')}
+`).join('\n')}
+
+## Task Metadata Registry
+
+Standard task description template:
+
+\```
+PURPOSE: [goal]
+TASK: [steps]
+CONTEXT: [session artifacts + specs]
+EXPECTED: [deliverable format]
+CONSTRAINTS: [scope limits]
+\```
+
+## Conditional Routing
+
+${teamConfig.conditionalRouting ? `
+PLAN-001 complexity assessment routes to:
+- Low (1-3): Direct implementation
+- Medium (4-6): Standard planning
+- High (7+): Full spec → plan → implement
+` : 'No conditional routing in this pipeline.'}
+
+## Dynamic Specialist Injection
+
+${teamConfig.dynamicSpecialists.length > 0 ?
+  teamConfig.dynamicSpecialists.map(s => `- ${s}: Injected when domain keywords detected`).join('\n') :
+  'No dynamic specialists configured.'
+}
+```
+
+### Additional Specs
+
+For each additional spec in `teamConfig.specs` (beyond pipelines), generate domain-appropriate content:
+
+- **quality-gates.md**: Thresholds (Pass≥80%, Review 60-79%, Fail<60%), scoring dimensions, per-phase gates
+- **knowledge-transfer.md**: 5 transfer channels, Phase 2 loading protocol, Phase 4 publishing protocol
+
+## Step 3.4: Generate Templates
+
+For each template in `teamConfig.templates`:
+
+1. Check if golden sample has matching template at `~  or <project>/.claude/skills/team-lifecycle-v4/templates/`
+2. If exists: copy and adapt for new domain
+3. If not: generate domain-appropriate template structure
+
+## Step 3.5: Generation Order
+
+Execute in this order (respects dependencies):
+
+1. **specs/** — needed by roles for reference
+2. **coordinator/** — role.md + commands/ (3 files)
+3. **workers/** — each role.md (+ optional commands/)
+4. **templates/** — independent, generate last
+
+For each file:
+1. Read golden sample equivalent (if exists)
+2. Adapt content for current teamConfig
+3. Write file
+4. Verify file exists
+
+## Output
+
+- **Files**: All role.md, commands/*.md, specs/*.md, templates/*.md
+- **Next**: Phase 4 - Validation

package/.agents/skills/team-designer/phases/04-validation.md

@@ -0,0 +1,329 @@
+# Phase 4: Validation
+
+Validate the generated team skill package for structural completeness, reference integrity, role consistency, and team-worker compatibility.
+
+## Objective
+
+- Verify all required files exist
+- Validate SKILL.md role registry matches actual role files
+- Check role.md frontmatter format for team-worker compatibility
+- Verify pipeline task references match existing roles
+- Report validation results
+
+## Step 4.1: Structural Validation
+
+```javascript
+function validateStructure(teamConfig) {
+  const skillDir = `.claude/skills/${teamConfig.skillName}`;
+  const results = { errors: [], warnings: [], info: [] };
+
+  // Check SKILL.md exists
+  if (!fileExists(`${skillDir}/SKILL.md`)) {
+    results.errors.push('SKILL.md not found');
+  }
+
+  // Check coordinator structure
+  if (!fileExists(`${skillDir}/roles/coordinator/role.md`)) {
+    results.errors.push('Coordinator role.md not found');
+  }
+  for (const cmd of ['analyze', 'dispatch', 'monitor']) {
+    if (!fileExists(`${skillDir}/roles/coordinator/commands/${cmd}.md`)) {
+      results.errors.push(`Coordinator command ${cmd}.md not found`);
+    }
+  }
+
+  // Check worker roles
+  for (const role of teamConfig.roles.filter(r => r.name !== 'coordinator')) {
+    if (!fileExists(`${skillDir}/roles/${role.name}/role.md`)) {
+      results.errors.push(`Worker role.md not found: ${role.name}`);
+    }
+    if (role.hasCommands) {
+      for (const cmd of role.commands) {
+        if (!fileExists(`${skillDir}/roles/${role.name}/commands/${cmd}.md`)) {
+          results.errors.push(`Worker command not found: ${role.name}/commands/${cmd}.md`);
+        }
+      }
+    }
+  }
+
+  // Check specs
+  if (!fileExists(`${skillDir}/specs/pipelines.md`)) {
+    results.errors.push('specs/pipelines.md not found');
+  }
+
+  return results;
+}
+```
+
+## Step 4.2: SKILL.md Content Validation
+
+```javascript
+function validateSkillMd(teamConfig) {
+  const skillDir = `.claude/skills/${teamConfig.skillName}`;
+  const results = { errors: [], warnings: [], info: [] };
+  const skillMd = read_file(`${skillDir}/SKILL.md`);
+
+  // Required sections
+  const requiredSections = [
+    'Role Registry', 'Role Router', 'Shared Constants',
+    'Worker Spawn Template', 'User Commands', 'Session Directory'
+  ];
+  for (const section of requiredSections) {
+    if (!skillMd.includes(section)) {
+      results.errors.push(`SKILL.md missing section: ${section}`);
+    }
+  }
+
+  // Verify role registry completeness
+  for (const role of teamConfig.roles) {
+    if (!skillMd.includes(role.path || `roles/${role.name}/role.md`)) {
+      results.errors.push(`Role registry missing path for: ${role.name}`);
+    }
+  }
+
+  // Verify session prefix
+  if (!skillMd.includes(teamConfig.sessionPrefix)) {
+    results.warnings.push(`Session prefix ${teamConfig.sessionPrefix} not found in SKILL.md`);
+  }
+
+  // Verify NO beat model content in SKILL.md
+  const beatModelPatterns = [
+    'ONE_STEP_PER_INVOCATION',
+    'spawn-and-stop',
+    'SPAWN_MODE',
+    'handleCallback',
+    'handleSpawnNext'
+  ];
+  for (const pattern of beatModelPatterns) {
+    if (skillMd.includes(pattern)) {
+      results.errors.push(`SKILL.md contains beat model content: ${pattern} (should be in coordinator only)`);
+    }
+  }
+
+  return results;
+}
+```
+
+## Step 4.3: Role Frontmatter Validation
+
+Verify role.md files have correct YAML frontmatter for team-worker agent compatibility:
+
+```javascript
+function validateRoleFrontmatter(teamConfig) {
+  const skillDir = `.claude/skills/${teamConfig.skillName}`;
+  const results = { errors: [], warnings: [], info: [] };
+
+  for (const role of teamConfig.roles.filter(r => r.name !== 'coordinator')) {
+    const roleMd = read_file(`${skillDir}/roles/${role.name}/role.md`);
+
+    // Check frontmatter exists
+    if (!roleMd.startsWith('---')) {
+      results.errors.push(`${role.name}/role.md missing YAML frontmatter`);
+      continue;
+    }
+
+    // Extract frontmatter
+    const fmMatch = roleMd.match(/^---\n([\s\S]*?)\n---/);
+    if (!fmMatch) {
+      results.errors.push(`${role.name}/role.md malformed frontmatter`);
+      continue;
+    }
+
+    const fm = fmMatch[1];
+
+    // Required fields
+    if (!fm.includes(`role: ${role.name}`)) {
+      results.errors.push(`${role.name}/role.md frontmatter missing 'role: ${role.name}'`);
+    }
+    if (!fm.includes(`prefix: ${role.prefix}`)) {
+      results.errors.push(`${role.name}/role.md frontmatter missing 'prefix: ${role.prefix}'`);
+    }
+    if (!fm.includes(`inner_loop: ${role.inner_loop}`)) {
+      results.warnings.push(`${role.name}/role.md frontmatter missing 'inner_loop: ${role.inner_loop}'`);
+    }
+    if (!fm.includes('message_types:')) {
+      results.warnings.push(`${role.name}/role.md frontmatter missing 'message_types'`);
+    }
+  }
+
+  return results;
+}
+```
+
+## Step 4.4: Pipeline Consistency
+
+```javascript
+function validatePipelines(teamConfig) {
+  const skillDir = `.claude/skills/${teamConfig.skillName}`;
+  const results = { errors: [], warnings: [], info: [] };
+
+  // Check every role referenced in pipelines exists
+  const definedRoles = new Set(teamConfig.roles.map(r => r.name));
+
+  for (const pipeline of teamConfig.pipelines) {
+    for (const task of pipeline.tasks) {
+      if (!definedRoles.has(task.role)) {
+        results.errors.push(
+          `Pipeline '${pipeline.name}' task ${task.id} references undefined role: ${task.role}`
+        );
+      }
+    }
+
+    // Check for circular dependencies
+    const visited = new Set();
+    const stack = new Set();
+    for (const task of pipeline.tasks) {
+      if (hasCycle(task, pipeline.tasks, visited, stack)) {
+        results.errors.push(`Pipeline '${pipeline.name}' has circular dependency involving ${task.id}`);
+      }
+    }
+  }
+
+  // Verify specs/pipelines.md contains all pipelines
+  const pipelinesMd = read_file(`${skillDir}/specs/pipelines.md`);
+  for (const pipeline of teamConfig.pipelines) {
+    if (!pipelinesMd.includes(pipeline.name)) {
+      results.warnings.push(`specs/pipelines.md missing pipeline: ${pipeline.name}`);
+    }
+  }
+
+  return results;
+}
+```
+
+## Step 4.5: Commands Distribution Validation
+
+```javascript
+function validateCommandsDistribution(teamConfig) {
+  const skillDir = `.claude/skills/${teamConfig.skillName}`;
+  const results = { errors: [], warnings: [], info: [] };
+
+  for (const role of teamConfig.roles.filter(r => r.name !== 'coordinator')) {
+    if (role.hasCommands) {
+      // Verify commands/ directory exists and has files
+      const cmdDir = `${skillDir}/roles/${role.name}/commands`;
+      if (role.commands.length < 2) {
+        results.warnings.push(
+          `${role.name} has commands/ but only ${role.commands.length} command(s) — consider inline`
+        );
+      }
+      // Verify role.md references commands
+      const roleMd = read_file(`${skillDir}/roles/${role.name}/role.md`);
+      for (const cmd of role.commands) {
+        if (!roleMd.includes(`commands/${cmd}.md`)) {
+          results.warnings.push(
+            `${role.name}/role.md doesn't reference commands/${cmd}.md`
+          );
+        }
+      }
+    } else {
+      // Verify no commands/ directory exists
+      const cmdDir = `${skillDir}/roles/${role.name}/commands`;
+      if (directoryExists(cmdDir)) {
+        results.warnings.push(
+          `${role.name} is inline but has commands/ directory`
+        );
+      }
+    }
+  }
+
+  return results;
+}
+```
+
+## Step 4.6: Aggregate Results and Report
+
+```javascript
+function generateValidationReport(teamConfig) {
+  const structural = validateStructure(teamConfig);
+  const skillMd = validateSkillMd(teamConfig);
+  const frontmatter = validateRoleFrontmatter(teamConfig);
+  const pipelines = validatePipelines(teamConfig);
+  const commands = validateCommandsDistribution(teamConfig);
+
+  const allErrors = [
+    ...structural.errors, ...skillMd.errors,
+    ...frontmatter.errors, ...pipelines.errors, ...commands.errors
+  ];
+  const allWarnings = [
+    ...structural.warnings, ...skillMd.warnings,
+    ...frontmatter.warnings, ...pipelines.warnings, ...commands.warnings
+  ];
+
+  const gate = allErrors.length === 0 ? 'PASS' :
+               allErrors.length <= 2 ? 'REVIEW' : 'FAIL';
+
+  const skillDir = `.claude/skills/${teamConfig.skillName}`;
+
+  console.log(`
+╔══════════════════════════════════════╗
+║   Team Skill Validation Report       ║
+╠══════════════════════════════════════╣
+║  Skill: ${teamConfig.skillName.padEnd(28)}║
+║  Gate:  ${gate.padEnd(28)}║
+╚══════════════════════════════════════╝
+
+Structure:
+  ${skillDir}/
+  ├── SKILL.md                                    ✓
+  ├── roles/
+  │   ├── coordinator/
+  │   │   ├── role.md                             ✓
+  │   │   └── commands/ (analyze, dispatch, monitor)
+${teamConfig.roles.filter(r => r.name !== 'coordinator').map(r => {
+  const structure = r.hasCommands
+    ? `  │   ├── ${r.name}/ (role.md + commands/)`
+    : `  │   ├── ${r.name}/role.md`;
+  return `${structure.padEnd(50)}✓`;
+}).join('\n')}
+  ├── specs/
+  │   └── pipelines.md                            ✓
+  └── templates/                                  ${teamConfig.templates.length > 0 ? '✓' : '(empty)'}
+
+${allErrors.length > 0 ? `Errors (${allErrors.length}):\n${allErrors.map(e => `  ✗ ${e}`).join('\n')}` : 'Errors: None ✓'}
+
+${allWarnings.length > 0 ? `Warnings (${allWarnings.length}):\n${allWarnings.map(w => `  ⚠ ${w}`).join('\n')}` : 'Warnings: None ✓'}
+
+Usage:
+  invoke_skill(skill="${teamConfig.skillName}", args="<task description>")
+  `);
+
+  return { gate, errors: allErrors, warnings: allWarnings };
+}
+```
+
+## Step 4.7: Error Recovery
+
+```javascript
+if (report.gate === 'FAIL') {
+  const recovery = ask_user({
+    questions: [{
+      question: `Validation found ${report.errors.length} errors. How to proceed?`,
+      header: "Recovery",
+      multiSelect: false,
+      options: [
+        { label: "Auto-fix", description: "Attempt automatic fixes (missing files, frontmatter)" },
+        { label: "Regenerate", description: "Re-run Phase 3 with fixes" },
+        { label: "Accept as-is", description: "Manual fix later" }
+      ]
+    }]
+  });
+}
+```
+
+## Output
+
+- **Report**: Validation results with quality gate (PASS/REVIEW/FAIL)
+- **Completion**: Team skill package ready at `.claude/skills/${teamConfig.skillName}/`
+
+## Completion
+
+Team Skill Designer has completed. The generated team skill is ready for use.
+
+```
+Next Steps:
+  1. Review SKILL.md router for correctness
+  2. Review each role.md for domain accuracy
+  3. Test: invoke_skill(skill="${teamConfig.skillName}", args="<test task>")
+  4. Iterate based on execution results
+```

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

@@ -1,7 +1,7 @@
 ---
 name: team-executor
 description: Lightweight session execution skill. Resumes existing team-coordinate sessions for pure execution via team-worker agents. No analysis, no role generation -- only loads and executes. Session path required. Triggers on "Team Executor".
-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__ccw-tools__team_msg(*)
+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. -->