maestro-flow 0.5.31 → 0.5.33

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

@@ -0,0 +1,162 @@
+---
+name: team-designer
+description: Meta-skill for generating team skills following the v4 architecture pattern. Produces complete skill packages with SKILL.md router, coordinator, worker roles, specs, and templates. Triggers on "team-designer", "design team".
+allowed-tools: 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 Skill Designer
+
+Generate complete team skills following the team-lifecycle-v4 architecture: SKILL.md as universal router, coordinator with beat model, worker roles with optional commands/, shared specs, and templates.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Team Skill Designer (SKILL.md)                                  │
+│  → Orchestrator: gather requirements, generate files, validate   │
+└───────────────────────────┬──────────────────────────────────────┘
+                            │
+    ┌───────────┬───────────┼───────────┬───────────┐
+    ↓           ↓           ↓           ↓
+┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
+│ Phase 1 │ │ Phase 2 │ │ Phase 3 │ │ Phase 4 │
+│ Require │ │ Scaffold│ │ Content │ │ Valid   │
+│ Analysis│ │  Gen    │ │  Gen    │ │ & Report│
+└─────────┘ └─────────┘ └─────────┘ └─────────┘
+     ↓           ↓           ↓           ↓
+  teamConfig  SKILL.md    roles/      Validated
+              + dirs     specs/       skill pkg
+                         templates/
+```
+
+## Key Design Principles
+
+1. **v4 Architecture Compliance**: Generated skills follow team-lifecycle-v4 pattern — SKILL.md = pure router, beat model = coordinator-only, unified structure (roles/ + specs/ + templates/)
+2. **Golden Sample Reference**: Uses `team-lifecycle-v4` as reference implementation at `~  or <project>/.claude/skills/team-lifecycle-v4/`
+3. **Intelligent Commands Distribution**: Auto-determines which roles need `commands/` (2+ commands) vs inline logic (1 command)
+4. **team-worker Compatibility**: Role.md files include correct YAML frontmatter for team-worker agent parsing
+
+## Pre-load (before execution)
+
+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. **Wiki knowledge**: `maestro search "skill design team architecture" --json` — top 5 entries as prior context
+4. All optional — proceed without if unavailable
+
+## Execution Flow
+
+```
+Input Parsing:
+   └─ Parse user requirements (skill name, roles, pipelines, domain)
+
+Phase 1: Requirements Analysis
+   └─ Ref: phases/01-requirements-analysis.md
+      ├─ Tasks: Detect input → Gather roles → Define pipelines → Build teamConfig
+      └─ Output: teamConfig
+
+Phase 2: Scaffold Generation
+   └─ Ref: phases/02-scaffold-generation.md
+      ├─ Tasks: Create dirs → Generate SKILL.md router → Verify
+      └─ Output: SKILL.md + directory structure
+
+Phase 3: Content Generation
+   └─ Ref: phases/03-content-generation.md
+      ├─ Tasks: Coordinator → Workers → Specs → Templates
+      └─ Output: roles/**/*.md, specs/*.md, templates/*.md
+
+Phase 4: Validation
+   └─ Ref: phases/04-validation.md
+      └─ Output: Validation report (PASS/REVIEW/FAIL)
+
+Return:
+   └─ Summary with skill location and usage instructions
+```
+
+**Phase Reference Documents** (read on-demand when phase executes):
+
+| Phase | Document | Purpose |
+|-------|----------|---------|
+| 1 | [phases/01-requirements-analysis.md](phases/01-requirements-analysis.md) | Gather team skill requirements, build teamConfig |
+| 2 | [phases/02-scaffold-generation.md](phases/02-scaffold-generation.md) | Generate SKILL.md router and directory structure |
+| 3 | [phases/03-content-generation.md](phases/03-content-generation.md) | Generate coordinator, workers, specs, templates |
+| 4 | [phases/04-validation.md](phases/04-validation.md) | Validate structure, references, and consistency |
+
+## Golden Sample
+
+Generated skills follow the architecture of `~  or <project>/.claude/skills/team-lifecycle-v4/`:
+
+```
+.claude/skills/<skill-name>/
+├── SKILL.md                              # Universal router (all roles read)
+├── roles/
+│   ├── coordinator/
+│   │   ├── role.md                       # Orchestrator + beat model + entry router
+│   │   └── commands/
+│   │       ├── analyze.md                # Task analysis
+│   │       ├── dispatch.md               # Task chain creation
+│   │       └── monitor.md                # Beat control + callbacks
+│   ├── <inline-worker>/
+│   │   └── role.md                       # Phase 2-4 embedded (simple role)
+│   └── <command-worker>/
+│       ├── role.md                       # Phase 2-4 dispatcher
+│       └── commands/
+│           ├── <cmd-1>.md
+│           └── <cmd-2>.md
+├── specs/
+│   ├── pipelines.md                      # Pipeline definitions + task registry
+│   └── <domain-specs>.md                 # Domain-specific specifications
+└── templates/                            # Optional document templates
+```
+
+## Data Flow
+
+```
+User Input (skill name, roles, pipelines)
+    ↓
+Phase 1: Requirements Analysis
+    ↓ Output: teamConfig
+    ↓
+Phase 2: Scaffold Generation
+    ↓ Input: teamConfig
+    ↓ Output: SKILL.md + skillDir
+    ↓
+Phase 3: Content Generation
+    ↓ Input: teamConfig + skillDir
+    ↓ Output: roles/, specs/, templates/
+    ↓
+Phase 4: Validation
+    ↓ Input: teamConfig + all files
+    ↓ Output: validation report
+    ↓
+Return summary to user
+```
+
+## Core Rules
+
+1. **Start Immediately**: First action is Phase 1 execution
+2. **Parse Every Output**: Extract teamConfig from Phase 1 for subsequent phases
+3. **Auto-Continue**: After each phase, automatically execute next phase
+4. **Progressive Phase Loading**: Read phase docs ONLY when that phase is about to execute
+5. **Golden Sample Fidelity**: Generated files must match team-lifecycle-v4 patterns
+6. **DO NOT STOP**: Continuous workflow until all 4 phases complete
+
+## Input Processing
+
+Convert user input to structured format:
+
+```
+SKILL_NAME: [kebab-case name, e.g., team-code-review]
+DOMAIN: [what this team does, e.g., "multi-stage code review with security analysis"]
+ROLES: [worker roles beyond coordinator, e.g., "analyst, reviewer, security-expert"]
+PIPELINES: [pipeline types and flows, e.g., "review-only: SCAN-001 → REVIEW-001 → REPORT-001"]
+SESSION_PREFIX: [3-4 char, e.g., TCR]
+```
+
+## Error Handling
+
+- **Invalid role name**: Must be lowercase alphanumeric with hyphens, max 20 chars
+- **Circular dependencies**: Detect and report in pipeline validation
+- **Missing golden sample**: Fall back to embedded templates in phase files
+- **Directory conflict**: Warn if skill directory already exists, ask user to confirm overwrite

package/.agents/skills/team-designer/phases/01-requirements-analysis.md

@@ -0,0 +1,265 @@
+# Phase 1: Requirements Analysis
+
+Gather team skill requirements from user input and build the `teamConfig` data structure that drives all subsequent phases.
+
+## Objective
+
+- Parse user input (text description, reference skill, or interactive)
+- Determine roles, pipelines, specs, templates
+- Auto-decide commands distribution (inline vs commands/ folder)
+- Build comprehensive `teamConfig` object
+- Confirm with user before proceeding
+
+## Step 1.1: Detect Input Source
+
+```javascript
+function detectInputSource(userInput) {
+  // Source A: Reference to existing skill
+  if (userInput.includes('based on') || userInput.includes('参考') || userInput.includes('like')) {
+    return { type: 'reference', refSkill: extractSkillName(userInput) };
+  }
+  // Source B: Structured input with roles/pipelines
+  if (userInput.includes('ROLES:') || userInput.includes('PIPELINES:')) {
+    return { type: 'structured', data: parseStructuredInput(userInput) };
+  }
+  // Source C: Natural language description
+  return { type: 'natural', description: userInput };
+}
+```
+
+**For reference source**: Read the referenced skill's SKILL.md and role files to extract structure.
+
+**For natural language**: Use ask_user to gather missing details interactively.
+
+## Step 1.2: Gather Core Identity
+
+```javascript
+const coreIdentity = ask_user({
+  questions: [
+    {
+      question: "团队技能名称？(kebab-case, e.g., team-code-review)",
+      header: "Skill Name",
+      multiSelect: false,
+      options: [
+        { label: suggestedName, description: "Auto-suggested from description" },
+        { label: "Custom", description: "Enter custom name" }
+      ]
+    },
+    {
+      question: "会话前缀？(3-4字符用于任务ID, e.g., TCR)",
+      header: "Prefix",
+      multiSelect: false,
+      options: [
+        { label: suggestedPrefix, description: "Auto-suggested" },
+        { label: "Custom", description: "Enter custom prefix" }
+      ]
+    }
+  ]
+});
+```
+
+If user provided clear name/prefix in input, skip this step.
+
+## Step 1.3: Determine Roles
+
+### Role Discovery from Domain
+
+Analyze domain description to identify required roles:
+
+```javascript
+function discoverRoles(domain) {
+  const rolePatterns = {
+    'analyst': ['分析', 'analyze', 'research', 'explore', 'investigate', 'scan'],
+    'planner': ['规划', 'plan', 'design', 'architect', 'decompose'],
+    'writer': ['文档', 'write', 'document', 'draft', 'spec', 'report'],
+    'executor': ['实现', 'implement', 'execute', 'build', 'code', 'develop'],
+    'tester': ['测试', 'test', 'verify', 'validate', 'qa'],
+    'reviewer': ['审查', 'review', 'quality', 'check', 'audit', 'inspect'],
+    'security-expert': ['安全', 'security', 'vulnerability', 'penetration'],
+    'performance-optimizer': ['性能', 'performance', 'optimize', 'benchmark'],
+    'data-engineer': ['数据', 'data', 'pipeline', 'etl', 'migration'],
+    'devops-engineer': ['部署', 'devops', 'deploy', 'ci/cd', 'infrastructure'],
+  };
+
+  const matched = [];
+  for (const [role, keywords] of Object.entries(rolePatterns)) {
+    if (keywords.some(kw => domain.toLowerCase().includes(kw))) {
+      matched.push(role);
+    }
+  }
+  return matched;
+}
+```
+
+### Role Configuration
+
+For each discovered role, determine:
+
+```javascript
+function configureRole(roleName) {
+  return {
+    name: roleName,
+    prefix: determinePrefix(roleName),
+    inner_loop: determineInnerLoop(roleName),
+    hasCommands: false,  // determined in Step 1.5
+    commands: [],
+    message_types: determineMessageTypes(roleName),
+    path: `roles/${roleName}/role.md`
+  };
+}
+
+// Standard prefix mapping
+const prefixMap = {
+  'analyst': 'RESEARCH',
+  'writer': 'DRAFT',
+  'planner': 'PLAN',
+  'executor': 'IMPL',
+  'tester': 'TEST',
+  'reviewer': 'REVIEW',
+  // Dynamic roles use uppercase role name
+};
+
+// Inner loop: roles that process multiple tasks sequentially
+const innerLoopRoles = ['executor', 'writer', 'planner'];
+
+// Message types the role handles
+const messageMap = {
+  'analyst': ['state_update'],
+  'writer': ['state_update', 'discuss_response'],
+  'planner': ['state_update'],
+  'executor': ['state_update', 'revision_request'],
+  'tester': ['state_update'],
+  'reviewer': ['state_update', 'discuss_request'],
+};
+```
+
+## Step 1.4: Define Pipelines
+
+### Pipeline Types from Role Combination
+
+```javascript
+function definePipelines(roles, domain) {
+  const has = name => roles.some(r => r.name === name);
+
+  // Full lifecycle: analyst → writer → planner → executor → tester → reviewer
+  if (has('analyst') && has('writer') && has('planner') && has('executor'))
+    return [{ name: 'full-lifecycle', tasks: buildFullLifecycleTasks(roles) }];
+
+  // Spec-only: analyst → writer → reviewer
+  if (has('analyst') && has('writer') && !has('executor'))
+    return [{ name: 'spec-only', tasks: buildSpecOnlyTasks(roles) }];
+
+  // Impl-only: planner → executor → tester → reviewer
+  if (has('planner') && has('executor') && !has('analyst'))
+    return [{ name: 'impl-only', tasks: buildImplOnlyTasks(roles) }];
+
+  // Custom: user-defined
+  return [{ name: 'custom', tasks: buildCustomTasks(roles, domain) }];
+}
+```
+
+### Task Schema
+
+```javascript
+const taskSchema = {
+  id: 'PREFIX-NNN',       // e.g., RESEARCH-001
+  role: 'analyst',        // which role executes
+  name: 'Seed Analysis',  // human-readable name
+  dependsOn: [],          // task IDs that must complete first
+  isCheckpoint: false,    // true for quality gates
+  isConditional: false,   // true for routing decisions
+  description: '...'
+};
+```
+
+## Step 1.5: Determine Commands Distribution
+
+**Rule**: 1 action → inline in role.md. 2+ distinct actions → commands/ folder.
+
+```javascript
+function determineCommandsDistribution(roles) {
+  // Coordinator: always has commands/
+  // coordinator.commands = ['analyze', 'dispatch', 'monitor']
+
+  // Standard multi-action roles:
+  // executor → implement + fix → commands/
+  // reviewer (if both code & spec review) → review-code + review-spec → commands/
+  // All others → typically inline
+
+  for (const role of roles) {
+    const actions = countDistinctActions(role);
+    if (actions.length >= 2) {
+      role.hasCommands = true;
+      role.commands = actions.map(a => a.name);
+    }
+  }
+}
+```
+
+## Step 1.6: Determine Specs and Templates
+
+```javascript
+// Specs: always include pipelines, add domain-specific
+const specs = ['pipelines'];
+if (hasQualityGates) specs.push('quality-gates');
+if (hasKnowledgeTransfer) specs.push('knowledge-transfer');
+
+// Templates: only if writer role exists
+const templates = [];
+if (has('writer')) {
+  // Detect from domain keywords
+  if (domain.includes('product')) templates.push('product-brief');
+  if (domain.includes('requirement')) templates.push('requirements');
+  if (domain.includes('architecture')) templates.push('architecture');
+  if (domain.includes('epic')) templates.push('epics');
+}
+```
+
+## Step 1.7: Build teamConfig
+
+```javascript
+const teamConfig = {
+  skillName: string,          // e.g., "team-code-review"
+  sessionPrefix: string,      // e.g., "TCR"
+  domain: string,             // domain description
+  title: string,              // e.g., "Code Review Team"
+  roles: Array<RoleConfig>,   // includes coordinator
+  pipelines: Array<Pipeline>,
+  specs: Array<string>,       // filenames without .md
+  templates: Array<string>,   // filenames without .md
+  conditionalRouting: boolean,
+  dynamicSpecialists: Array<string>,
+};
+```
+
+## Step 1.8: Confirm with User
+
+```
+╔══════════════════════════════════════════╗
+║  Team Skill Configuration Summary        ║
+╠══════════════════════════════════════════╣
+
+Skill Name:     ${skillName}
+Session Prefix: ${sessionPrefix}
+Domain:         ${domain}
+
+Roles (N):
+  ├─ coordinator (commands: analyze, dispatch, monitor)
+  ├─ role-a [PREFIX-*] (inline) 🔄
+  └─ role-b [PREFIX-*] (commands: cmd1, cmd2)
+
+Pipelines:
+  └─ pipeline-name: TASK-001 → TASK-002 → TASK-003
+
+Specs: pipelines, quality-gates
+Templates: (none)
+
+╚══════════════════════════════════════════╝
+```
+
+Use ask_user to confirm or allow modifications.
+
+## Output
+
+- **Variable**: `teamConfig` — complete configuration for all subsequent phases
+- **Next**: Phase 2 - Scaffold Generation

package/.agents/skills/team-designer/phases/02-scaffold-generation.md

@@ -0,0 +1,236 @@
+# Phase 2: Scaffold Generation
+
+Generate the SKILL.md universal router and create the directory structure for the team skill.
+
+## Objective
+
+- Create directory structure (roles/, specs/, templates/)
+- Generate SKILL.md as universal router following v4 pattern
+- SKILL.md must NOT contain beat model, pipeline details, or role Phase 2-4 logic
+
+## Step 2.1: Create Directory Structure
+
+```bash
+skillDir=".claude/skills/${teamConfig.skillName}"
+mkdir -p "${skillDir}"
+
+# Create role directories
+for role in teamConfig.roles:
+  mkdir -p "${skillDir}/roles/${role.name}"
+  if role.hasCommands:
+    mkdir -p "${skillDir}/roles/${role.name}/commands"
+
+# Create specs directory
+mkdir -p "${skillDir}/specs"
+
+# Create templates directory (if needed)
+if teamConfig.templates.length > 0:
+  mkdir -p "${skillDir}/templates"
+```
+
+## Step 2.2: Generate SKILL.md
+
+The SKILL.md follows a strict template. Every generated SKILL.md contains these sections in order:
+
+### Section 1: Frontmatter
+
+```yaml
+---
+name: ${teamConfig.skillName}
+description: "${teamConfig.domain}. Triggers on ${teamConfig.skillName}."
+allowed-tools: create_team(*), delete_team(*), send_message(*), create_task(*), update_task(*), list_tasks(*), get_task(*), delegate_subagent(*), ask_user(*), read_file(*), write_file(*), edit_file(*), shell(*), find_files(*), search(*)
+---
+```
+
+### Section 2: Title + Architecture Diagram
+
+```markdown
+# ${Title}
+
+${One-line description}
+
+## Architecture
+
+\```
+invoke_skill(skill="${teamConfig.skillName}", args="task description")
+                    |
+         SKILL.md (this file) = Router
+                    |
+     +--------------+--------------+
+     |                             |
+  no --role flag              --role <name>
+     |                             |
+  Coordinator                  Worker
+  roles/coordinator/role.md    roles/<name>/role.md
+     |
+     +-- analyze → dispatch → spawn workers → STOP
+                                    |
+                    +-------+-------+-------+
+                    v       v       v       v
+                 [team-worker agents, each loads roles/<role>/role.md]
+\```
+```
+
+### Section 3: Role Registry
+
+```markdown
+## Role Registry
+
+| Role | Path | Prefix | Inner Loop |
+|------|------|--------|------------|
+| coordinator | roles/coordinator/role.md | — | — |
+${teamConfig.roles.filter(r => r.name !== 'coordinator').map(r =>
+  `| ${r.name} | ${r.path} | ${r.prefix}-* | ${r.inner_loop} |`
+).join('\n')}
+```
+
+### Section 4: Role Router
+
+```markdown
+## Role Router
+
+Parse `$ARGUMENTS`:
+- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
+- No `--role` → Read `roles/coordinator/role.md`, execute entry router
+```
+
+### Section 5: Shared Constants
+
+```markdown
+## Shared Constants
+
+- **Session prefix**: `${teamConfig.sessionPrefix}`
+- **Session path**: `.workflow/.team/${teamConfig.sessionPrefix}-<slug>-<date>/`
+- **CLI tools**: `maestro delegate --mode analysis` (read-only), `maestro delegate --mode write` (modifications)
+- **Message bus**: `mcp__maestro__team_msg(session_id=<session-id>, ...)`
+```
+
+### Section 6: Worker Spawn Template
+
+```markdown
+## Worker Spawn Template
+
+Coordinator spawns workers using this template:
+
+\```
+delegate_subagent({
+  subagent_type: "team-worker",
+  description: "Spawn <role> worker",
+  team_name: <team-name>,
+  name: "<role>",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: <role>
+role_spec: .claude/skills/${teamConfig.skillName}/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: <team-name>
+requirement: <task-description>
+inner_loop: <true|false>
+
+Read role_spec file to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
+})
+\```
+```
+
+### Section 7: User Commands
+
+```markdown
+## User Commands
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View execution status graph |
+| `resume` / `continue` | Advance to next step |
+| `revise <TASK-ID> [feedback]` | Revise specific task |
+| `feedback <text>` | Inject feedback for revision |
+| `recheck` | Re-run quality check |
+| `improve [dimension]` | Auto-improve weakest dimension |
+```
+
+### Section 8: Completion Action
+
+```markdown
+## Completion Action
+
+When pipeline completes, coordinator presents:
+
+\```
+ask_user({
+  questions: [{
+    question: "Pipeline complete. What would you like to do?",
+    header: "Completion",
+    multiSelect: false,
+    options: [
+      { label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" },
+      { label: "Keep Active", description: "Keep session for follow-up work" },
+      { label: "Export Results", description: "Export deliverables to target directory" }
+    ]
+  }]
+})
+\```
+```
+
+### Section 9: Specs Reference
+
+```markdown
+## Specs Reference
+
+${teamConfig.specs.map(s =>
+  `- [specs/${s}.md](specs/${s}.md) — ${specDescription(s)}`
+).join('\n')}
+```
+
+### Section 10: Session Directory
+
+```markdown
+## Session Directory
+
+\```
+.workflow/.team/${teamConfig.sessionPrefix}-<slug>-<date>/
+├── team-session.json           # Session state + role registry
+├── spec/                       # Spec phase outputs
+├── plan/                       # Implementation plan + TASK-*.json
+├── artifacts/                  # All deliverables
+├── wisdom/                     # Cross-task knowledge
+├── explorations/               # Shared explore cache
+├── discussions/                # Discuss round records
+└── .msg/                       # Team message bus
+\```
+```
+
+### Section 11: Error Handling
+
+```markdown
+## 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 |
+```
+
+## Step 2.3: Assemble and Write
+
+Assemble all sections into a single SKILL.md file and write to `${skillDir}/SKILL.md`.
+
+**Quality Rules**:
+1. SKILL.md must NOT contain beat model (ONE_STEP_PER_INVOCATION, spawn-and-stop)
+2. SKILL.md must NOT contain pipeline task details (task IDs, dependencies)
+3. SKILL.md must NOT contain role Phase 2-4 logic
+4. SKILL.md MUST contain role registry table with correct paths
+5. SKILL.md MUST contain worker spawn template with correct `role_spec` paths
+
+## Output
+
+- **File**: `.claude/skills/${teamConfig.skillName}/SKILL.md`
+- **Variable**: `skillDir` (path to skill root directory)
+- **Next**: Phase 3 - Content Generation
+
+## Next Phase
+
+Return to orchestrator, then auto-continue to [Phase 3: Content Generation](03-content-generation.md).