diff --git a/.claude/skills/team-command-designer/SKILL.md b/.claude/skills/team-command-designer/SKILL.md new file mode 100644 index 00000000..60034dfb --- /dev/null +++ b/.claude/skills/team-command-designer/SKILL.md @@ -0,0 +1,220 @@ +--- +name: team-command-designer +description: Design and generate team command .md files following established patterns (8 infrastructure patterns + 10 collaboration patterns with convergence control). Triggers on "design team command", "create team role", "new teammate". +allowed-tools: Task, AskUserQuestion, Read, Write, Bash, Glob, Grep +--- + +# Team Command Designer + +Design and generate team command .md files following established patterns extracted from existing team commands (coordinate, plan, execute, test, review). Supports 10 collaboration patterns for diverse team interaction models. + +## Architecture Overview + +``` +Phase 0: Specification Study (Mandatory - read design patterns + collaboration patterns) + | +Phase 1: Requirements Collection -> role-config.json + | +Phase 2: Pattern Analysis -> applicable-patterns.json (infra + collaboration) + | +Phase 3: Command Generation -> {team-name}/{role-name}.md + | +Phase 4: Integration Verification -> integration-report.json + | +Phase 5: Validation -> validation-report.json +``` + +## Key Design Principles + +1. **Pattern Compliance**: All generated commands must follow infrastructure + collaboration patterns +2. **Message Bus Integration**: Every command must include team_msg logging +3. **Task Lifecycle**: Standard TaskList -> TaskGet -> TaskUpdate flow +4. **Complexity-Adaptive**: Support direct execution and sub-agent delegation +5. **Five-Phase Execution**: Each command follows the 5-phase structure +6. **Convergence Control**: Every collaboration pattern has explicit convergence criteria +7. **Feedback Loops**: Every pattern has structured feedback mechanisms +8. **Composable Patterns**: Collaboration patterns can be combined for complex workflows + +--- + +## Mandatory Prerequisites + +> **Do NOT skip**: Before performing any operations, you **must** completely read the following documents. + +### Specification Documents (Required Reading) + +| Document | Purpose | When | +|----------|---------|------| +| [specs/team-design-patterns.md](specs/team-design-patterns.md) | Infrastructure patterns (8) + collaboration pattern index | **Must read before execution** | +| [specs/collaboration-patterns.md](specs/collaboration-patterns.md) | 10 collaboration patterns with convergence/feedback control | **Must read before execution** | +| [specs/quality-standards.md](specs/quality-standards.md) | Quality standards for generated team commands | Must read before generation | + +### Template Files (Must read before generation) + +| Document | Purpose | +|----------|---------| +| [templates/command-template.md](templates/command-template.md) | Team command .md file template with all required sections | + +### Existing Team Commands (Reference) + +| Document | Purpose | +|----------|---------| +| `.claude/commands/team/coordinate.md` | Coordinator pattern - orchestration, team lifecycle | +| `.claude/commands/team/plan.md` | Planner pattern - exploration, plan generation | +| `.claude/commands/team/execute.md` | Executor pattern - implementation, self-validation | +| `.claude/commands/team/test.md` | Tester pattern - adaptive test-fix cycle | +| `.claude/commands/team/review.md` | Reviewer pattern - multi-dimensional review | +| `.claude/commands/team/spec/` | Spec team folder - folder-based team example | + +--- + +## Execution Flow + +``` +Input Parsing: + Parse $ARGUMENTS for role name and capabilities description + +Phase 0: Specification Study (MANDATORY) + -> Refer to: specs/team-design-patterns.md, specs/collaboration-patterns.md, templates/command-template.md + - Read infrastructure patterns (Section A of team-design-patterns.md) + - Read collaboration patterns specification (collaboration-patterns.md) + - Read command template + - Read 1-2 existing team commands most similar to the new role + - Output: Internalized requirements (in-memory) + +Phase 1: Requirements Collection + -> Refer to: phases/01-requirements-collection.md + - Collect team name (folder name) and role name + - Collect responsibilities, communication patterns + - Determine task prefix (e.g., PLAN-*, IMPL-*, ANALYZE-*) + - Select applicable tools and capabilities + - Output: role-config.json (includes team_name, skill_path, output_folder) + +Phase 2: Pattern Analysis + -> Refer to: phases/02-pattern-analysis.md, specs/team-design-patterns.md + - Identify which existing command is most similar + - Select applicable design patterns + - Determine message types needed + - Map phase structure to role responsibilities + - Output: applicable-patterns.json + +Phase 3: Command Generation + -> Refer to: phases/03-command-generation.md, templates/command-template.md + - Apply template with role-specific content + - Generate YAML front matter + - Generate message bus section + - Generate 5-phase execution process + - Generate implementation code + - Generate error handling table + - Output: {team-name}/{role-name}.md + +Phase 4: Integration Verification + -> Refer to: phases/04-integration-verification.md + - Verify consistency with coordinate.md spawn patterns + - Check message type compatibility + - Verify task prefix uniqueness + - Ensure allowed-tools are sufficient + - Output: integration-report.json + +Phase 5: Validation + -> Refer to: phases/05-validation.md, specs/quality-standards.md + - Check all required sections exist + - Verify message bus compliance + - Validate task lifecycle pattern + - Score against quality standards + - Output: validation-report.json + final {team-name}/{role-name}.md +``` + +## Directory Setup + +```javascript +const timestamp = new Date().toISOString().slice(0,19).replace(/[-:T]/g, ''); +const workDir = `.workflow/.scratchpad/team-cmd-${timestamp}`; + +Bash(`mkdir -p "${workDir}"`); +``` + +## Output Structure + +``` +.workflow/.scratchpad/team-cmd-{timestamp}/ +├── role-config.json # Phase 1 output (includes team_name) +├── applicable-patterns.json # Phase 2 output +├── integration-report.json # Phase 4 output +├── validation-report.json # Phase 5 output +└── {role-name}.md # Final generated command + +Final delivery (folder-based): +.claude/commands/team/{team-name}/ +├── {role-name}.md # e.g., coordinator.md, analyst.md +├── ... # Other roles in same team +└── (each team = one folder) + +Skill path mapping: + .claude/commands/team/{team-name}/{role-name}.md → /team:{team-name}:{role-name} + Example: .claude/commands/team/spec/analyst.md → /team:spec:analyst +``` + +--- + +## Reference Documents by Phase + +### Phase 0: Specification Study + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [specs/team-design-patterns.md](specs/team-design-patterns.md) | Team command design patterns | Understand all required patterns **Required Reading** | +| [templates/command-template.md](templates/command-template.md) | Command file template | Understand output structure **Required Reading** | + +### Phase 1: Requirements Collection + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [phases/01-requirements-collection.md](phases/01-requirements-collection.md) | Collection process guide | Execute requirements gathering | +| [specs/team-design-patterns.md](specs/team-design-patterns.md) | Pattern reference | Validate role fits team architecture | + +### Phase 2: Pattern Analysis + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [phases/02-pattern-analysis.md](phases/02-pattern-analysis.md) | Analysis process guide | Execute pattern matching | +| [specs/team-design-patterns.md](specs/team-design-patterns.md) | Full pattern catalog | Select applicable patterns | + +### Phase 3: Command Generation + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [phases/03-command-generation.md](phases/03-command-generation.md) | Generation process guide | Execute command file generation | +| [templates/command-template.md](templates/command-template.md) | Command template | Apply template with role content | + +### Phase 4: Integration Verification + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [phases/04-integration-verification.md](phases/04-integration-verification.md) | Verification process guide | Execute integration checks | + +### Phase 5: Validation + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [phases/05-validation.md](phases/05-validation.md) | Validation process guide | Execute quality checks | +| [specs/quality-standards.md](specs/quality-standards.md) | Quality criteria | Score generated command | + +### Debugging & Troubleshooting + +| Issue | Solution Document | +|-------|------------------| +| Generated command missing message bus | [specs/team-design-patterns.md](specs/team-design-patterns.md) - Pattern 1 | +| Task lifecycle not standard | [specs/team-design-patterns.md](specs/team-design-patterns.md) - Pattern 3 | +| Integration check fails | [phases/04-integration-verification.md](phases/04-integration-verification.md) | +| Quality score below threshold | [specs/quality-standards.md](specs/quality-standards.md) | + +### Reference & Background + +| Document | Purpose | Notes | +|----------|---------|-------| +| `.claude/commands/team/coordinate.md` | Coordinator reference | Spawn patterns, task chain creation | +| `.claude/commands/team/plan.md` | Planner reference | Exploration, plan generation patterns | +| `.claude/commands/team/execute.md` | Executor reference | Implementation, delegation patterns | +| `.claude/commands/team/test.md` | Tester reference | Adaptive fix cycle pattern | +| `.claude/commands/team/review.md` | Reviewer reference | Multi-dimensional review pattern | diff --git a/.claude/skills/team-command-designer/phases/01-requirements-collection.md b/.claude/skills/team-command-designer/phases/01-requirements-collection.md new file mode 100644 index 00000000..2330bf59 --- /dev/null +++ b/.claude/skills/team-command-designer/phases/01-requirements-collection.md @@ -0,0 +1,227 @@ +# Phase 1: Requirements Collection + +Collect team definition, role definition, capabilities, and communication patterns for the new team command. + +## Objective + +- Determine team name (folder name) +- Determine role name and responsibilities +- Define task prefix and communication patterns +- Select required tools and capabilities +- Generate role-config.json + +## Input + +- Dependency: User request (`$ARGUMENTS` or interactive input) +- Specification: `specs/team-design-patterns.md` (read in Phase 0) + +## Execution Steps + +### Step 1: Team & Role Basic Information + +```javascript +const teamInfo = await AskUserQuestion({ + questions: [ + { + question: "What is the team name? (lowercase, used as folder name under .claude/commands/team/{team-name}/)", + header: "Team Name", + multiSelect: false, + options: [ + { label: "Custom team", description: "Enter a custom team name" }, + { label: "spec", description: "Specification documentation team" }, + { label: "security", description: "Security audit and compliance team" }, + { label: "devops", description: "Deployment and operations team" } + ] + }, + { + question: "What is the role name for this teammate? (lowercase, e.g., 'analyzer', 'deployer')", + header: "Role Name", + multiSelect: false, + options: [ + { label: "Custom role", description: "Enter a custom role name" }, + { label: "coordinator", description: "Team coordinator / orchestrator" }, + { label: "analyzer", description: "Code/data analysis specialist" }, + { label: "deployer", description: "Deployment and release management" } + ] + }, + { + question: "What is the primary responsibility type?", + header: "Responsibility", + multiSelect: false, + options: [ + { label: "Read-only analysis", description: "Analyze, review, report (no file modification)" }, + { label: "Code generation", description: "Write/modify code files" }, + { label: "Orchestration", description: "Coordinate sub-tasks and agents" }, + { label: "Validation", description: "Test, verify, audit" } + ] + } + ] +}); +``` + +### Step 2: Task Configuration + +```javascript +const taskConfig = await AskUserQuestion({ + questions: [ + { + question: "What task prefix should this role use? (UPPERCASE, unique, e.g., 'ANALYZE', 'DEPLOY')", + header: "Task Prefix", + multiSelect: false, + options: [ + { label: "Custom prefix", description: "Enter a unique task prefix" }, + { label: "ANALYZE", description: "For analysis tasks (ANALYZE-001)" }, + { label: "DEPLOY", description: "For deployment tasks (DEPLOY-001)" }, + { label: "DOC", description: "For documentation tasks (DOC-001)" } + ] + }, + { + question: "Where does this role fit in the task chain?", + header: "Chain Position", + multiSelect: false, + options: [ + { label: "After PLAN (parallel with IMPL)", description: "Runs alongside implementation" }, + { label: "After IMPL (parallel with TEST/REVIEW)", description: "Post-implementation validation" }, + { label: "After TEST+REVIEW (final stage)", description: "Final processing before completion" }, + { label: "Independent (coordinator-triggered)", description: "No dependency on other tasks" } + ] + } + ] +}); +``` + +### Step 3: Capability Selection + +```javascript +const capabilities = await AskUserQuestion({ + questions: [ + { + question: "What capabilities does this role need?", + header: "Capabilities", + multiSelect: true, + options: [ + { label: "File modification (Write/Edit)", description: "Can create and modify files" }, + { label: "Sub-agent delegation (Task)", description: "Can spawn sub-agents for complex work" }, + { label: "CLI tool invocation", description: "Can invoke ccw cli tools (gemini/qwen/codex)" }, + { label: "User interaction (AskUserQuestion)", description: "Can ask user questions during execution" } + ] + }, + { + question: "Does this role need complexity-adaptive routing?", + header: "Adaptive", + multiSelect: false, + options: [ + { label: "Yes (Recommended)", description: "Low=direct, Medium/High=agent delegation" }, + { label: "No", description: "Always use the same execution path" } + ] + } + ] +}); +``` + +### Step 4: Message Types Definition + +```javascript +// Infer message types from role type +const responsibilityType = roleInfo["Responsibility"] + +const baseMessageTypes = [ + { type: "error", direction: "-> coordinator", trigger: "Blocking error" } +] + +const roleMessageTypes = { + "Read-only analysis": [ + { type: "{role}_result", direction: "-> coordinator", trigger: "Analysis complete" }, + { type: "{role}_progress", direction: "-> coordinator", trigger: "Long analysis progress" } + ], + "Code generation": [ + { type: "{role}_complete", direction: "-> coordinator", trigger: "Generation complete" }, + { type: "{role}_progress", direction: "-> coordinator", trigger: "Batch progress update" } + ], + "Orchestration": [ + { type: "{role}_ready", direction: "-> coordinator", trigger: "Sub-task results ready" }, + { type: "{role}_progress", direction: "-> coordinator", trigger: "Sub-task progress" } + ], + "Validation": [ + { type: "{role}_result", direction: "-> coordinator", trigger: "Validation complete" }, + { type: "fix_required", direction: "-> coordinator", trigger: "Critical issues found" } + ] +} + +const messageTypes = [ + ...baseMessageTypes, + ...(roleMessageTypes[responsibilityType] || []) +] +``` + +### Step 5: Generate Configuration + +```javascript +const teamName = teamInfo["Team Name"] === "Custom team" + ? teamInfo["Team Name_other"] + : teamInfo["Team Name"] + +const roleName = teamInfo["Role Name"] === "Custom role" + ? teamInfo["Role Name_other"] + : teamInfo["Role Name"] + +const taskPrefix = taskConfig["Task Prefix"] === "Custom prefix" + ? taskConfig["Task Prefix_other"] + : taskConfig["Task Prefix"] + +// Build allowed-tools list +const baseTools = ["SendMessage(*)", "TaskUpdate(*)", "TaskList(*)", "TaskGet(*)", "TodoWrite(*)", "Read(*)", "Bash(*)", "Glob(*)", "Grep(*)"] +const selectedCapabilities = capabilities["Capabilities"] || [] + +if (selectedCapabilities.includes("File modification")) { + baseTools.push("Write(*)", "Edit(*)") +} +if (selectedCapabilities.includes("Sub-agent delegation")) { + baseTools.push("Task(*)") +} + +const config = { + team_name: teamName, + role_name: roleName, + display_name: `Team ${teamName} ${roleName}`, + description_cn: `Team ${teamName} ${roleName} - ${teamInfo["Responsibility"]}`, + responsibility_type: responsibilityType, + task_prefix: taskPrefix.toUpperCase(), + chain_position: taskConfig["Chain Position"], + allowed_tools: baseTools, + capabilities: selectedCapabilities, + adaptive_routing: capabilities["Adaptive"].includes("Yes"), + message_types: messageTypes.map(mt => ({ + ...mt, + type: mt.type.replace('{role}', roleName) + })), + cli_integration: selectedCapabilities.includes("CLI tool invocation"), + user_interaction: selectedCapabilities.includes("User interaction"), + // Derived paths + skill_path: `team:${teamName}:${roleName}`, // e.g., team:spec:analyst + output_folder: `.claude/commands/team/${teamName}`, // e.g., .claude/commands/team/spec + output_file: `${roleName}.md` // e.g., analyst.md +} + +Write(`${workDir}/role-config.json`, JSON.stringify(config, null, 2)) +``` + +## Output + +- **File**: `role-config.json` +- **Format**: JSON +- **Location**: `{workDir}/role-config.json` + +## Quality Checklist + +- [ ] Team name is lowercase, valid as folder name +- [ ] Role name is lowercase, unique within the team folder +- [ ] Task prefix is UPPERCASE, unique (not PLAN/IMPL/TEST/REVIEW) +- [ ] Allowed tools include minimum set (SendMessage, TaskUpdate, TaskList, TaskGet) +- [ ] Message types follow naming convention +- [ ] Chain position is clearly defined +- [ ] Derived paths (skill_path, output_folder, output_file) are consistent + +## Next Phase + +-> [Phase 2: Pattern Analysis](02-pattern-analysis.md) diff --git a/.claude/skills/team-command-designer/phases/02-pattern-analysis.md b/.claude/skills/team-command-designer/phases/02-pattern-analysis.md new file mode 100644 index 00000000..f1670b9e --- /dev/null +++ b/.claude/skills/team-command-designer/phases/02-pattern-analysis.md @@ -0,0 +1,266 @@ +# Phase 2: Pattern Analysis + +Identify applicable design patterns from existing team commands for the new role. + +## Objective + +- Find the most similar existing team command +- Select applicable infrastructure patterns (Section A) +- Select applicable collaboration patterns (Section B: CP-1 through CP-10) +- Map role responsibilities to phase structure +- Generate applicable-patterns.json + +## Input + +- Dependency: `role-config.json` (from Phase 1) +- Specification: `specs/team-design-patterns.md` (read in Phase 0) + +## Execution Steps + +### Step 1: Load Configuration + +```javascript +const config = JSON.parse(Read(`${workDir}/role-config.json`)) +``` + +### Step 2: Find Most Similar Existing Command + +```javascript +// Similarity mapping based on responsibility type +const similarityMap = { + "Read-only analysis": { + primary: "review", // Multi-dimensional analysis -> report + secondary: "plan", // Also does exploration + reason: "Both analyze code and report findings with severity classification" + }, + "Code generation": { + primary: "execute", // Code implementation + secondary: "test", // Also modifies code (fixes) + reason: "Both write/modify code files and self-validate" + }, + "Orchestration": { + primary: "plan", // Manages exploration and plan generation + secondary: "coordinate", // High-level orchestration + reason: "Both coordinate multiple sub-tasks and produce structured output" + }, + "Validation": { + primary: "test", // Test execution and fix cycles + secondary: "review", // Verification + reason: "Both validate output quality with structured criteria" + } +} + +const similarity = similarityMap[config.responsibility_type] + +// Read the most similar command for pattern extraction +const primaryRef = Read(`.claude/commands/team/${similarity.primary}.md`) +const secondaryRef = Read(`.claude/commands/team/${similarity.secondary}.md`) +``` + +### Step 3: Select Applicable Patterns + +```javascript +// All commands use these core patterns (mandatory) +const corePatterns = [ + "pattern-1-message-bus", // Always required + "pattern-2-yaml-front-matter", // Always required + "pattern-3-task-lifecycle", // Always required + "pattern-4-five-phase", // Always required + "pattern-6-coordinator-spawn", // Always required + "pattern-7-error-handling" // Always required +] + +// Conditional patterns based on config +const conditionalPatterns = [] + +if (config.adaptive_routing) { + conditionalPatterns.push("pattern-5-complexity-adaptive") +} + +if (config.responsibility_type === "Code generation" || + config.responsibility_type === "Orchestration") { + conditionalPatterns.push("pattern-8-session-files") +} +``` + +### Step 4: Map Phase Structure + +```javascript +// Map 5-phase structure to role-specific content +const phaseMapping = { + "Read-only analysis": { + phase1: "Task Discovery", + phase2: "Context Loading (read changed files, load plan)", + phase3: `${config.role_name}-specific analysis`, + phase4: "Finding Summary (classify severity)", + phase5: "Report to Coordinator" + }, + "Code generation": { + phase1: "Task & Plan Loading", + phase2: "Task Grouping (dependency analysis)", + phase3: "Code Implementation (direct or sub-agent)", + phase4: "Self-Validation (syntax, criteria)", + phase5: "Completion Report" + }, + "Orchestration": { + phase1: "Task Discovery", + phase2: "Context & Complexity Assessment", + phase3: "Orchestrated Execution (parallel sub-agents)", + phase4: "Result Aggregation", + phase5: "Submit for Approval + Loop" + }, + "Validation": { + phase1: "Task Discovery", + phase2: "Framework/Environment Detection", + phase3: "Execution & Fix Cycle", + phase4: "Result Analysis", + phase5: "Report to Coordinator" + } +} + +const phases = phaseMapping[config.responsibility_type] +``` + +### Step 5: Extract Implementation Patterns from Reference + +```javascript +// Extract specific code patterns from the most similar command +function extractPatterns(commandContent) { + const patterns = {} + + // Extract task discovery pattern + const taskDiscovery = commandContent.match( + /\/\/ Find my assigned.*?if \(my\w+Tasks\.length === 0\).*?return/s + ) + if (taskDiscovery) patterns.taskDiscovery = taskDiscovery[0] + + // Extract message bus examples + const msgExamples = commandContent.match( + /mcp__ccw-tools__team_msg\(\{[^}]+\}\)/g + ) + if (msgExamples) patterns.messageExamples = msgExamples + + // Extract error handling table + const errorTable = commandContent.match( + /## Error Handling[\s\S]*?\n\n/ + ) + if (errorTable) patterns.errorHandling = errorTable[0] + + return patterns +} + +const referencePatterns = extractPatterns(primaryRef) +``` + +### Step 6: Select Collaboration Patterns + +```javascript +// Collaboration pattern selection based on role characteristics +function selectCollaborationPatterns(config) { + const patterns = ['CP-1'] // CP-1 Linear Pipeline is always the base + + const responsibilityType = config.responsibility_type + + // Rule-based selection + if (responsibilityType === 'Validation' || responsibilityType === 'Read-only analysis') { + patterns.push('CP-2') // Review-Fix Cycle - natural for validation roles + } + + if (responsibilityType === 'Orchestration') { + patterns.push('CP-3') // Fan-out/Fan-in for orchestration + patterns.push('CP-4') // Consensus Gate for decisions + } + + if (config.adaptive_routing) { + patterns.push('CP-5') // Escalation Chain for when self-repair fails + } + + if (responsibilityType === 'Code generation') { + patterns.push('CP-6') // Incremental Delivery for large implementations + patterns.push('CP-2') // Review-Fix Cycle for code quality + } + + // CP-5 Escalation is always available as a fallback + if (!patterns.includes('CP-5')) { + patterns.push('CP-5') + } + + // CP-10 Post-Mortem is always included at team level + patterns.push('CP-10') + + return [...new Set(patterns)] // Deduplicate +} + +const collaborationPatterns = selectCollaborationPatterns(config) + +// Map collaboration patterns to convergence configurations +const convergenceConfig = collaborationPatterns.map(cp => { + const defaults = { + 'CP-1': { max_iterations: 1, timeout: null, success_gate: 'all_stages_completed' }, + 'CP-2': { max_iterations: 5, timeout: null, success_gate: 'verdict_approve_or_conditional' }, + 'CP-3': { max_iterations: 1, timeout: 300000, success_gate: 'quorum_100_percent' }, + 'CP-4': { max_iterations: 2, timeout: 300000, success_gate: 'quorum_67_percent' }, + 'CP-5': { max_iterations: null, timeout: null, success_gate: 'issue_resolved_at_any_level' }, + 'CP-6': { max_iterations: 3, timeout: null, success_gate: 'all_increments_validated' }, + 'CP-7': { max_iterations: 2, timeout: 600000, success_gate: 'blocker_resolved' }, + 'CP-8': { max_iterations: 2, timeout: 120000, success_gate: 'advice_applied' }, + 'CP-9': { max_iterations: 2, timeout: 300000, success_gate: 'all_sync_points_aligned' }, + 'CP-10': { max_iterations: 1, timeout: 180000, success_gate: 'report_generated' } + } + return { pattern: cp, convergence: defaults[cp] } +}) +``` + +### Step 7: Generate Patterns Document + +```javascript +const applicablePatterns = { + role_name: config.role_name, + similar_to: { + primary: similarity.primary, + secondary: similarity.secondary, + reason: similarity.reason + }, + // Infrastructure patterns + core_patterns: corePatterns, + conditional_patterns: conditionalPatterns, + // Collaboration patterns + collaboration_patterns: collaborationPatterns, + convergence_config: convergenceConfig, + // Phase and reference mapping + phase_structure: phases, + reference_patterns: { + task_discovery: "Adapt from " + similarity.primary + ".md Phase 1", + core_work: "Adapt from " + similarity.primary + ".md Phase 3", + reporting: "Adapt from " + similarity.primary + ".md Phase 5" + }, + message_types: config.message_types, + implementation_hints: { + phase1: `Standard task lifecycle with ${config.task_prefix}-* prefix`, + phase2: phases.phase2, + phase3: phases.phase3, + phase4: phases.phase4, + phase5: `SendMessage to coordinator with ${config.role_name} results` + } +} + +Write(`${workDir}/applicable-patterns.json`, JSON.stringify(applicablePatterns, null, 2)) +``` + +## Output + +- **File**: `applicable-patterns.json` +- **Format**: JSON +- **Location**: `{workDir}/applicable-patterns.json` + +## Quality Checklist + +- [ ] Most similar existing command identified +- [ ] All mandatory patterns included (6 core patterns) +- [ ] Phase structure mapped to role responsibilities +- [ ] Implementation hints are specific and actionable +- [ ] Reference patterns point to concrete sections + +## Next Phase + +-> [Phase 3: Command Generation](03-command-generation.md) diff --git a/.claude/skills/team-command-designer/phases/03-command-generation.md b/.claude/skills/team-command-designer/phases/03-command-generation.md new file mode 100644 index 00000000..25776647 --- /dev/null +++ b/.claude/skills/team-command-designer/phases/03-command-generation.md @@ -0,0 +1,353 @@ +# Phase 3: Command Generation + +Generate the team command .md file using template and pattern analysis results. + +## Objective + +- Apply command template with role-specific content +- Generate complete YAML front matter +- Generate message bus section +- Generate 5-phase implementation with code +- Generate error handling table +- Output final command file + +## Input + +- Dependency: `role-config.json` (Phase 1), `applicable-patterns.json` (Phase 2) +- Template: `templates/command-template.md` + +## Execution Steps + +### Step 1: Load Inputs + +```javascript +const config = JSON.parse(Read(`${workDir}/role-config.json`)) +const patterns = JSON.parse(Read(`${workDir}/applicable-patterns.json`)) +const template = Read(`${skillDir}/templates/command-template.md`) + +// Read most similar command for code reference +// Note: reference may be in a folder (e.g. .claude/commands/team/folder/cmd.md) if config.output_folder is set +const refCommand = Read(`.claude/commands/team/${patterns.similar_to.primary}.md`) +``` + +### Step 2: Generate YAML Front Matter + +```javascript +const frontMatter = `--- +name: ${config.role_name} +description: ${config.description_cn} +argument-hint: "" +allowed-tools: ${config.allowed_tools.join(', ')} +group: team +---` +``` + +### Step 3: Generate Message Bus Section + +```javascript +const messageBusSection = `## Message Bus + +Every SendMessage **before**, must call \`mcp__ccw-tools__team_msg\` to log: + +\`\`\`javascript +mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "${config.role_name}", to: "coordinator", type: "", summary: "" }) +\`\`\` + +### Supported Message Types + +| Type | Direction | Trigger | Description | +|------|-----------|---------|-------------| +${config.message_types.map(mt => + `| \`${mt.type}\` | ${config.role_name} -> coordinator | ${mt.trigger} | ${mt.description || mt.trigger} |` +).join('\n')} + +### Examples + +\`\`\`javascript +${config.message_types.filter(mt => mt.type !== 'error').map(mt => + `// ${mt.trigger} +mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "${config.role_name}", to: "coordinator", type: "${mt.type}", summary: "${mt.trigger}" })` +).join('\n\n')} +\`\`\`` +``` + +### Step 4: Generate Phase Implementations + +```javascript +// Phase 1: Task Discovery (standard for all roles) +const phase1 = `### Phase 1: Task Discovery + +\`\`\`javascript +// Find assigned ${config.task_prefix}-* tasks +const tasks = TaskList() +const myTasks = tasks.filter(t => + t.subject.startsWith('${config.task_prefix}-') && + t.owner === '${config.role_name}' && + t.status === 'pending' && + t.blockedBy.length === 0 +) + +if (myTasks.length === 0) return // idle + +const task = TaskGet({ taskId: myTasks[0].id }) +TaskUpdate({ taskId: task.id, status: 'in_progress' }) +\`\`\`` + +// Phase 2: Context Loading (adapted by responsibility type) +const phase2Templates = { + "Read-only analysis": `### Phase 2: Context Loading + +\`\`\`javascript +// Load plan for criteria reference +const planPathMatch = task.description.match(/\\.workflow\\/\\.team-plan\\/[^\\s]+\\/plan\\.json/) +let plan = null +if (planPathMatch) { + try { plan = JSON.parse(Read(planPathMatch[0])) } catch {} +} + +// Get changed files +const changedFiles = Bash(\`git diff --name-only HEAD~1 2>/dev/null || git diff --name-only --cached\`) + .split('\\n').filter(Boolean) + +// Read file contents for analysis +const fileContents = {} +for (const file of changedFiles.slice(0, 20)) { + try { fileContents[file] = Read(file) } catch {} +} +\`\`\``, + + "Code generation": `### Phase 2: Task & Plan Loading + +\`\`\`javascript +// Extract plan path from task description +const planPathMatch = task.description.match(/\\.workflow\\/\\.team-plan\\/[^\\s]+\\/plan\\.json/) +if (!planPathMatch) { + SendMessage({ type: "message", recipient: "coordinator", + content: \`Cannot find plan.json path in task \${task.subject}\`, + summary: "Plan path not found" }) + return +} + +const plan = JSON.parse(Read(planPathMatch[0])) +// Load task files from .task/ directory +const planTasks = plan.task_ids.map(id => + JSON.parse(Read(\`\${planPathMatch[0].replace('plan.json', '')}.task/\${id}.json\`)) +) +\`\`\``, + + "Orchestration": `### Phase 2: Context & Complexity Assessment + +\`\`\`javascript +// Assess task complexity +function assessComplexity(desc) { + let score = 0 + if (/refactor|architect|restructure|module|system/.test(desc)) score += 2 + if (/multiple|across|cross/.test(desc)) score += 2 + if (/integrate|api|database/.test(desc)) score += 1 + if (/security|performance/.test(desc)) score += 1 + return score >= 4 ? 'High' : score >= 2 ? 'Medium' : 'Low' +} + +const complexity = assessComplexity(task.description) + +// Load related context +const projectTech = Bash(\`test -f .workflow/project-tech.json && cat .workflow/project-tech.json || echo "{}"\`) +\`\`\``, + + "Validation": `### Phase 2: Environment Detection + +\`\`\`javascript +// Detect relevant tools/frameworks +// (customize based on specific validation domain) +const changedFiles = Bash(\`git diff --name-only HEAD~1 2>/dev/null || git diff --name-only --cached\`) + .split('\\n').filter(Boolean) + +// Load context based on validation type +\`\`\`` +} + +const phase2 = phase2Templates[config.responsibility_type] + +// Phase 3: Core Work (role-specific, provides skeleton) +const phase3 = `### Phase 3: ${patterns.phase_structure.phase3} + +\`\`\`javascript +// Core ${config.role_name} logic +// TODO: Implement based on role requirements +// Reference: .claude/commands/team/${patterns.similar_to.primary}.md Phase 3 + +${config.adaptive_routing ? ` +// Complexity-adaptive execution +if (complexity === 'Low') { + // Direct execution +} else { + // Delegate to sub-agent + Task({ + subagent_type: "universal-executor", + run_in_background: false, + description: "${config.role_name} work", + prompt: \` +## Task +\${task.description} + +## MANDATORY FIRST STEPS +1. Read: .workflow/project-tech.json (if exists) +2. Read: .workflow/project-guidelines.json (if exists) + +## Expected Output +\${expectedFormat} +\` + }) +}` : `// Direct execution for all tasks`} +\`\`\`` + +// Phase 4: Validation/Summary +const phase4 = `### Phase 4: ${patterns.phase_structure.phase4} + +\`\`\`javascript +// Validate/summarize results +// TODO: Implement based on role requirements +// Reference: .claude/commands/team/${patterns.similar_to.primary}.md Phase 4 +\`\`\`` + +// Phase 5: Report + Loop (standard for all roles) +const phase5 = `### Phase 5: Report to Coordinator + +\`\`\`javascript +// Log message before SendMessage +mcp__ccw-tools__team_msg({ + operation: "log", team: teamName, + from: "${config.role_name}", to: "coordinator", + type: "${config.message_types[0]?.type || config.role_name + '_complete'}", + summary: \`${config.task_prefix} complete: \${task.subject}\` +}) + +SendMessage({ + type: "message", + recipient: "coordinator", + content: \`## ${config.display_name} Results + +**Task**: \${task.subject} +**Status**: \${resultStatus} + +### Summary +\${resultSummary} + +### Details +\${resultDetails}\`, + summary: \`${config.task_prefix} complete\` +}) + +// Mark task completed +TaskUpdate({ taskId: task.id, status: 'completed' }) + +// Check for next task +const nextTasks = TaskList().filter(t => + t.subject.startsWith('${config.task_prefix}-') && + t.owner === '${config.role_name}' && + t.status === 'pending' && + t.blockedBy.length === 0 +) + +if (nextTasks.length > 0) { + // Continue with next task -> back to Phase 1 +} +\`\`\`` +``` + +### Step 5: Generate Error Handling Table + +```javascript +const errorTable = `## Error Handling + +| Scenario | Resolution | +|----------|------------| +| No ${config.task_prefix}-* tasks available | Idle, wait for coordinator assignment | +| Plan/Context file not found | Notify coordinator, request location | +${config.adaptive_routing ? '| Sub-agent failure | Retry once, then fallback to direct execution |\n' : ''}| Max iterations exceeded | Report to coordinator, suggest intervention | +| Critical issue beyond scope | SendMessage fix_required to coordinator | +| Unexpected error | Log error via team_msg, report to coordinator |` +``` + +### Step 6: Assemble Final Command File + +```javascript +const commandContent = `${frontMatter} + +# Team ${config.display_name} Command (/${config.skill_path}) + +## Overview + +Team ${config.role_name} role command. Operates as a teammate within an Agent Team, responsible for ${config.responsibility_type.toLowerCase()}. + +**Core capabilities:** +- Task discovery from shared team task list (${config.task_prefix}-* tasks) +${patterns.core_patterns.includes('pattern-5-complexity-adaptive') ? '- Complexity-adaptive routing (Low -> direct, Medium/High -> agent)\n' : ''}- ${config.responsibility_type}-specific processing +- Structured result reporting to coordinator + +## Role Definition + +**Name**: \`${config.role_name}\` +**Responsibility**: ${patterns.phase_structure.phase2} -> ${patterns.phase_structure.phase3} -> ${patterns.phase_structure.phase5} +**Communication**: SendMessage to coordinator only + +${messageBusSection} + +## Execution Process + +\`\`\` +Phase 1: Task Discovery + ├─ TaskList to find unblocked ${config.task_prefix}-* tasks + ├─ TaskGet to read full task details + └─ TaskUpdate to mark in_progress + +Phase 2: ${patterns.phase_structure.phase2} + +Phase 3: ${patterns.phase_structure.phase3} + +Phase 4: ${patterns.phase_structure.phase4} + +Phase 5: ${patterns.phase_structure.phase5} + ├─ team_msg log + SendMessage results + ├─ TaskUpdate completed + └─ Check for next ${config.task_prefix}-* task +\`\`\` + +## Implementation + +${phase1} + +${phase2} + +${phase3} + +${phase4} + +${phase5} + +${errorTable} +` + +Write(`${workDir}/${config.role_name}.md`, commandContent) +``` + +## Output + +- **File**: `{role-name}.md` +- **Format**: Markdown +- **Location**: `{workDir}/{role-name}.md` + +## Quality Checklist + +- [ ] YAML front matter includes all required fields +- [ ] `group: team` is present +- [ ] Message bus section has team_msg examples +- [ ] All 5 phases are present with implementation code +- [ ] Task lifecycle follows standard pattern +- [ ] Error handling table is present +- [ ] SendMessage always preceded by team_msg +- [ ] Role communicates only with coordinator + +## Next Phase + +-> [Phase 4: Integration Verification](04-integration-verification.md) diff --git a/.claude/skills/team-command-designer/phases/04-integration-verification.md b/.claude/skills/team-command-designer/phases/04-integration-verification.md new file mode 100644 index 00000000..714f595c --- /dev/null +++ b/.claude/skills/team-command-designer/phases/04-integration-verification.md @@ -0,0 +1,212 @@ +# Phase 4: Integration Verification + +Verify the generated command integrates correctly with the existing team system. + +## Objective + +- Verify consistency with coordinate.md spawn patterns +- Check message type compatibility +- Verify task prefix uniqueness +- Ensure allowed-tools are sufficient +- Generate integration-report.json + +## Input + +- Dependency: `{role-name}.md` (Phase 3), `role-config.json` (Phase 1) +- Reference: `.claude/commands/team/coordinate.md` + +## Execution Steps + +### Step 1: Load Generated Command and Config + +```javascript +const config = JSON.parse(Read(`${workDir}/role-config.json`)) +const generatedCommand = Read(`${workDir}/${config.role_name}.md`) +const coordinateCmd = Read(`.claude/commands/team/coordinate.md`) +``` + +### Step 2: Check Task Prefix Uniqueness + +```javascript +// Extract existing prefixes from coordinate.md +const existingPrefixes = ['PLAN', 'IMPL', 'TEST', 'REVIEW'] + +// Also scan all team command files for prefixes +const teamFiles = Glob('.claude/commands/team/**/*.md') +for (const file of teamFiles) { + const content = Read(file) + const prefixMatch = content.match(/startsWith\('([A-Z]+)-'\)/) + if (prefixMatch && !existingPrefixes.includes(prefixMatch[1])) { + existingPrefixes.push(prefixMatch[1]) + } +} + +const prefixConflict = existingPrefixes.includes(config.task_prefix) + +const prefixCheck = { + status: prefixConflict ? 'FAIL' : 'PASS', + existing: existingPrefixes, + new_prefix: config.task_prefix, + message: prefixConflict + ? `Prefix ${config.task_prefix} conflicts with existing: ${existingPrefixes.join(', ')}` + : `Prefix ${config.task_prefix} is unique` +} +``` + +### Step 3: Verify Spawn Pattern Compatibility + +```javascript +// Check that the generated command can be spawned by coordinate.md +const spawnCheck = { + has_skill_invocation: generatedCommand.includes('Skill(skill="team:'), + has_task_lifecycle: generatedCommand.includes('TaskList') && + generatedCommand.includes('TaskGet') && + generatedCommand.includes('TaskUpdate'), + has_message_bus: generatedCommand.includes('mcp__ccw-tools__team_msg'), + has_send_message: generatedCommand.includes('SendMessage'), + has_group_team: generatedCommand.includes('group: team') +} + +const spawnCompatible = Object.values(spawnCheck).every(v => v) +``` + +### Step 4: Verify Message Type Compatibility + +```javascript +// Extract all message types used in coordinate.md handlers +const coordinateTypes = coordinateCmd.match(/type:\s*["']([^"']+)["']/g) + ?.map(m => m.match(/["']([^"']+)["']/)[1]) || [] + +// Check new message types don't conflict +const msgTypeCheck = { + coordinator_knows: coordinateTypes, + new_types: config.message_types.map(mt => mt.type), + conflicts: config.message_types + .filter(mt => coordinateTypes.includes(mt.type)) + .map(mt => mt.type), + recommendation: "Add new message types to coordinate.md handler table" +} +``` + +### Step 5: Verify Allowed-Tools Sufficiency + +```javascript +const requiredTools = ['SendMessage', 'TaskUpdate', 'TaskList', 'TaskGet'] +const missingTools = requiredTools.filter(tool => + !config.allowed_tools.some(at => at.includes(tool)) +) + +const toolCheck = { + status: missingTools.length === 0 ? 'PASS' : 'FAIL', + required: requiredTools, + configured: config.allowed_tools, + missing: missingTools +} +``` + +### Step 6: Verify Chain Position Integration + +```javascript +// Check coordinate.md has or can add the task chain +const chainCheck = { + position: config.chain_position, + existing_chain: "PLAN-001 -> IMPL-001 -> TEST-001 + REVIEW-001", + integration_needed: true, + suggestion: generateChainSuggestion(config) +} + +function generateChainSuggestion(config) { + const pos = config.chain_position + if (pos.includes("After PLAN")) { + return `PLAN-001 -> IMPL-001 + ${config.task_prefix}-001 -> TEST-001 + REVIEW-001` + } + if (pos.includes("After IMPL")) { + return `PLAN-001 -> IMPL-001 -> TEST-001 + REVIEW-001 + ${config.task_prefix}-001` + } + if (pos.includes("After TEST")) { + return `PLAN-001 -> IMPL-001 -> TEST-001 + REVIEW-001 -> ${config.task_prefix}-001` + } + return `PLAN-001 -> IMPL-001 -> TEST-001 + REVIEW-001 (+ ${config.task_prefix}-001 independent)` +} +``` + +### Step 7: Generate Coordinator Spawn Snippet + +```javascript +// Generate the spawn code that should be added to coordinate.md +const spawnSnippet = `// ${config.display_name} +Task({ + subagent_type: "general-purpose", + team_name: teamName, + name: "${config.role_name}", + prompt: \`You are team "\${teamName}" ${config.role_name.toUpperCase()}. + +When you receive ${config.task_prefix}-* tasks, call Skill(skill="${config.skill_path}") to execute. + +Current requirement: \${taskDescription} +Constraints: \${constraints} + +## Message Bus (Required) +Before each SendMessage, call mcp__ccw-tools__team_msg: +mcp__ccw-tools__team_msg({ operation: "log", team: "\${teamName}", from: "${config.role_name}", to: "coordinator", type: "", summary: "" }) + +Workflow: +1. TaskList -> find ${config.task_prefix}-* tasks assigned to you +2. Skill(skill="${config.skill_path}") to execute +3. team_msg log + SendMessage results to coordinator +4. TaskUpdate completed -> check next task\` +})` +``` + +```javascript +// Skill path: ${config.skill_path} (e.g., team:spec:analyst) +// Folder: ${config.output_folder} (e.g., .claude/commands/team/spec) +``` + +### Step 8: Generate Integration Report + +```javascript +const report = { + role_name: config.role_name, + checks: { + prefix_unique: prefixCheck, + spawn_compatible: { status: spawnCompatible ? 'PASS' : 'FAIL', details: spawnCheck }, + message_types: msgTypeCheck, + tools_sufficient: toolCheck, + chain_integration: chainCheck + }, + overall: (prefixCheck.status === 'PASS' && + spawnCompatible && + toolCheck.status === 'PASS') ? 'PASS' : 'NEEDS_ATTENTION', + destination: `${config.output_folder}/${config.output_file}`, + coordinator_updates: { + spawn_snippet: spawnSnippet, + task_chain: chainCheck.suggestion, + handler_additions: config.message_types.map(mt => ({ + type: mt.type, + action: `Handle ${mt.trigger}` + })) + } +} + +Write(`${workDir}/integration-report.json`, JSON.stringify(report, null, 2)) +``` + +## Output + +- **File**: `integration-report.json` +- **Format**: JSON +- **Location**: `{workDir}/integration-report.json` + +## Quality Checklist + +- [ ] Task prefix does not conflict with existing prefixes +- [ ] Spawn pattern compatible with coordinate.md +- [ ] All required tools are in allowed-tools +- [ ] Message types documented +- [ ] Chain position has integration suggestion +- [ ] Coordinator spawn snippet is ready to copy + +## Next Phase + +-> [Phase 5: Validation](05-validation.md) diff --git a/.claude/skills/team-command-designer/phases/05-validation.md b/.claude/skills/team-command-designer/phases/05-validation.md new file mode 100644 index 00000000..2d39a9ac --- /dev/null +++ b/.claude/skills/team-command-designer/phases/05-validation.md @@ -0,0 +1,254 @@ +# Phase 5: Validation + +Verify completeness and quality of the generated team command. + +## Objective + +- Check all required sections exist +- Verify pattern compliance +- Score against quality standards +- Generate validation report +- Deliver final command file + +## Input + +- Dependency: `{role-name}.md` (Phase 3), `integration-report.json` (Phase 4) +- Specification: `specs/quality-standards.md` + +## Execution Steps + +### Step 1: Load Files + +```javascript +const config = JSON.parse(Read(`${workDir}/role-config.json`)) +const command = Read(`${workDir}/${config.role_name}.md`) +const integration = JSON.parse(Read(`${workDir}/integration-report.json`)) +``` + +### Step 2: Structural Completeness Check + +```javascript +const requiredSections = [ + { name: "YAML Front Matter", pattern: /^---\n[\s\S]+?\n---/ }, + { name: "group: team", pattern: /group:\s*team/ }, + { name: "Overview Section", pattern: /## Overview/ }, + { name: "Role Definition", pattern: /## Role Definition/ }, + { name: "Message Bus Section", pattern: /## .*[Mm]essage.*[Bb]us/ }, + { name: "team_msg Examples", pattern: /mcp__ccw-tools__team_msg/ }, + { name: "Message Types Table", pattern: /\| Type \| Direction/ }, + { name: "Execution Process", pattern: /## Execution Process/ }, + { name: "Phase 1: Task Discovery", pattern: /Phase 1.*Task Discovery/i }, + { name: "TaskList Usage", pattern: /TaskList/ }, + { name: "TaskGet Usage", pattern: /TaskGet/ }, + { name: "TaskUpdate Usage", pattern: /TaskUpdate/ }, + { name: "SendMessage to Coordinator", pattern: /SendMessage.*coordinator/i }, + { name: "Error Handling Table", pattern: /## Error Handling/ }, + { name: "Implementation Section", pattern: /## Implementation/ } +] + +const structureResults = requiredSections.map(section => ({ + section: section.name, + present: section.pattern.test(command), + status: section.pattern.test(command) ? 'PASS' : 'FAIL' +})) + +const structureScore = structureResults.filter(r => r.status === 'PASS').length / + structureResults.length * 100 +``` + +### Step 3: Pattern Compliance Check + +```javascript +const patternChecks = [ + { + name: "Message Bus Before SendMessage", + check: () => { + // Every SendMessage should be preceded by team_msg + const sendMessages = command.match(/SendMessage\(/g)?.length || 0 + const teamMsgs = command.match(/team_msg\(/g)?.length || 0 + return teamMsgs >= sendMessages + }, + severity: "critical" + }, + { + name: "Task Lifecycle Pattern", + check: () => { + return command.includes('TaskList') && + command.includes('TaskGet') && + command.includes("status: 'in_progress'") && + command.includes("status: 'completed'") + }, + severity: "critical" + }, + { + name: "Task Prefix Usage", + check: () => { + return command.includes(`'${config.task_prefix}-'`) + }, + severity: "high" + }, + { + name: "Coordinator-Only Communication", + check: () => { + return command.includes('recipient: "coordinator"') && + !command.includes('recipient: "executor"') && + !command.includes('recipient: "planner"') + }, + severity: "high" + }, + { + name: "Next Task Loop", + check: () => { + return command.includes('Check for next') || + command.includes('back to Phase 1') + }, + severity: "medium" + }, + { + name: "Idle on No Tasks", + check: () => { + return command.includes('idle') || command.includes('return') + }, + severity: "medium" + } +] + +const patternResults = patternChecks.map(pc => ({ + pattern: pc.name, + compliant: pc.check(), + severity: pc.severity, + status: pc.check() ? 'PASS' : 'FAIL' +})) + +const criticalFails = patternResults.filter(r => + r.status === 'FAIL' && r.severity === 'critical' +) +``` + +### Step 4: Quality Scoring + +```javascript +const qualityDimensions = { + completeness: structureScore, + pattern_compliance: patternResults.filter(r => r.status === 'PASS').length / + patternResults.length * 100, + integration: integration.overall === 'PASS' ? 100 : 50, + consistency: checkConsistency(command, config) +} + +function checkConsistency(command, config) { + let score = 100 + // Check role name consistency + if (!command.includes(config.role_name)) score -= 20 + // Check task prefix consistency + if (!command.includes(config.task_prefix)) score -= 20 + // Check front matter matches config + if (!command.includes(`name: ${config.role_name}`)) score -= 20 + // Check group: team + if (!command.includes('group: team')) score -= 20 + return Math.max(0, score) +} + +const overallScore = Object.values(qualityDimensions) + .reduce((a, b) => a + b, 0) / Object.keys(qualityDimensions).length + +const qualityGate = overallScore >= 80 ? 'PASS' : + overallScore >= 60 ? 'REVIEW' : 'FAIL' +``` + +### Step 5: Generate Validation Report + +```javascript +const report = { + role_name: config.role_name, + timestamp: new Date().toISOString(), + scores: { + completeness: qualityDimensions.completeness, + pattern_compliance: qualityDimensions.pattern_compliance, + integration: qualityDimensions.integration, + consistency: qualityDimensions.consistency, + overall: overallScore + }, + quality_gate: qualityGate, + structure_checks: structureResults, + pattern_checks: patternResults, + critical_failures: criticalFails, + recommendations: generateRecommendations(structureResults, patternResults, integration), + delivery: { + source: `${workDir}/${config.role_name}.md`, + destination: `${config.output_folder}/${config.output_file}`, + ready: qualityGate !== 'FAIL' && criticalFails.length === 0 + } +} + +function generateRecommendations(structure, patterns, integration) { + const recs = [] + structure.filter(s => s.status === 'FAIL').forEach(s => { + recs.push(`Add missing section: ${s.section}`) + }) + patterns.filter(p => p.status === 'FAIL').forEach(p => { + recs.push(`Fix pattern violation: ${p.pattern} [${p.severity}]`) + }) + if (integration.overall === 'NEEDS_ATTENTION') { + recs.push('Review integration report for coordinate.md updates') + } + return recs +} + +Write(`${workDir}/validation-report.json`, JSON.stringify(report, null, 2)) +``` + +### Step 6: Deliver Final File + +```javascript +if (report.delivery.ready) { + // Copy to final location + const finalContent = Read(`${workDir}/${config.role_name}.md`) + // Ensure team folder exists + Bash(`mkdir -p "${config.output_folder}"`) + Write(`${config.output_folder}/${config.output_file}`, finalContent) + + // Report success + console.log(`Team command delivered to: ${config.output_folder}/${config.output_file}`) + console.log(`Skill path: /${config.skill_path}`) + console.log(`Quality score: ${overallScore.toFixed(1)}% (${qualityGate})`) + console.log(`Integration: ${integration.overall}`) + + if (report.recommendations.length > 0) { + console.log('\nRecommendations:') + report.recommendations.forEach(r => console.log(` - ${r}`)) + } + + // Remind about coordinate.md updates + console.log('\nNext steps:') + console.log('1. Update coordinate.md to add spawn snippet (see integration-report.json)') + console.log('2. Add new message type handlers to coordinator') + console.log(`3. Test with: /${config.skill_path}`) +} else { + console.log(`Validation FAILED (score: ${overallScore.toFixed(1)}%)`) + console.log('Critical failures:') + criticalFails.forEach(f => console.log(` - ${f.pattern}`)) + console.log('Fix issues and re-run Phase 3-5') +} +``` + +## Output + +- **File**: `validation-report.json` +- **Format**: JSON +- **Location**: `{workDir}/validation-report.json` +- **Delivery**: `.claude/commands/team/{team-name}/{role-name}.md` (if validation passes) + +## Quality Checklist + +- [ ] All 15+ structural checks executed +- [ ] All 6+ pattern compliance checks executed +- [ ] No critical failures remaining +- [ ] Overall score >= 80% (PASS gate) +- [ ] Integration report reviewed +- [ ] Final file delivered to `.claude/commands/team/{team-name}/` +- [ ] Coordinator update instructions provided + +## Completion + +This is the final phase. The generated team command is ready for use. diff --git a/.claude/skills/team-command-designer/specs/collaboration-patterns.md b/.claude/skills/team-command-designer/specs/collaboration-patterns.md new file mode 100644 index 00000000..b59eacb4 --- /dev/null +++ b/.claude/skills/team-command-designer/specs/collaboration-patterns.md @@ -0,0 +1,1341 @@ +# Collaboration Patterns Specification + +> 10 种团队协作模式，每种具备：收敛性、完整流程、反馈控制 + +--- + +## Pattern Standard Structure + +每种协作模式遵循统一规范： + +``` +┌─────────────────────────────────────────┐ +│ Entry Condition (何时启用) │ +├─────────────────────────────────────────┤ +│ Roles Required (需要哪些角色) │ +├─────────────────────────────────────────┤ +│ Workflow (完整执行流程) │ +├─────────────────────────────────────────┤ +│ Convergence (收敛条件) │ +│ ├─ Success Gate (成功判定) │ +│ ├─ Max Iterations (最大迭代) │ +│ └─ Timeout (超时处理) │ +├─────────────────────────────────────────┤ +│ Feedback Loop (反馈控制) │ +│ ├─ Signal (反馈信号) │ +│ ├─ Handler (处理逻辑) │ +│ └─ Correction (纠正动作) │ +├─────────────────────────────────────────┤ +│ Fallback (降级策略) │ +└─────────────────────────────────────────┘ +``` + +--- + +## CP-1: Linear Pipeline (线性流水线) + +### Description + +最基础的协作模式。任务沿固定顺序在角色间传递，每个阶段有明确的入口和出口条件。上一阶段的输出是下一阶段的输入。 + +### Entry Condition + +- 任务具有清晰的阶段划分（规划 → 实现 → 验证） +- 各阶段之间有天然的依赖关系 +- 适用于大多数标准特性开发 + +### Roles Required + +`coordinator` → `planner` → `executor` → `tester` + +### Workflow + +``` + ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ +需求 ──→ │ PLAN │──→ │ IMPL │──→ │ TEST │──→ │ REPORT │ + │ planner │ │ executor │ │ + REVIEW │ │ coord. │ + └────┬─────┘ └────┬─────┘ └─────┬─────┘ └──────────┘ + │ │ │ + ▼ ▼ ▼ + plan.json code changes test results + review findings +``` + +```javascript +// Coordinator creates task chain +TaskCreate({ subject: "PLAN-001", owner: "planner" }) +TaskCreate({ subject: "IMPL-001", owner: "executor", addBlockedBy: [planId] }) +TaskCreate({ subject: "TEST-001", owner: "tester", addBlockedBy: [implId] }) +TaskCreate({ subject: "REVIEW-001", owner: "tester", addBlockedBy: [implId] }) +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | 所有阶段任务状态 = `completed` | +| **Max Iterations** | 每阶段 1 次（若失败触发 Review-Fix Cycle） | +| **Timeout** | 无显式超时，每阶段内部有各自收敛机制 | + +### Feedback Loop + +``` +┌─ Stage Transition Feedback ─────────────────────────┐ +│ │ +│ Plan rejected? → planner revises → resubmit │ +│ Impl has errors? → executor self-validates → fix │ +│ Tests fail? → tester fix cycle → retry │ +│ Review blocks? → create IMPL-fix → executor fixes │ +│ │ +└──────────────────────────────────────────────────────┘ +``` + +**Signal**: 下一阶段的 reject/fail message +**Handler**: Coordinator 路由消息回上一阶段 +**Correction**: 上一阶段 agent 修订并重新提交 + +### Fallback + +- Plan 拒绝 3+ 次 → Coordinator 自行规划 +- Test 达不到 95% 超过 5 次迭代 → 上报用户 +- Review 发现 critical → 创建 IMPL-fix 任务 + +### Implementation Reference + +当前 `coordinate.md` 即采用此模式。 + +--- + +## CP-2: Review-Fix Cycle (审查修复循环) + +### Description + +两个角色之间的迭代改进循环。一个角色产出工作成果，另一个角色审查，发现问题后退回修复，直到达到质量门控。这是软件开发中 code review 的自然映射。 + +### Entry Condition + +- 工作产出需要质量验证（代码实现、计划、文档） +- 存在明确的质量标准（pass rate、severity threshold、acceptance criteria） +- 需要多轮迭代才能达到质量要求 + +### Roles Required + +`producer` (executor/planner) ↔ `reviewer` (tester/reviewer) + +### Workflow + +``` + ┌─────────┐ ┌──────────┐ + │Producer │ │Reviewer │ + │ │──(1)产出───→│ │ + │ │ │ │ + │ │←─(2)反馈────│ │ + │ │ │ │ + │ │──(3)修订───→│ │ + │ │ │ │ + │ ... │ ...循环 │ ... │ + │ │ │ │ + └─────────┘ └──────────┘ + │ │ + ▼ ▼ + final artifact APPROVE verdict +``` + +```javascript +// Coordinator orchestrates review-fix cycle +function reviewFixCycle(producerRole, reviewerRole, maxIterations) { + let iteration = 0 + let verdict = 'PENDING' + + while (iteration < maxIterations && verdict !== 'APPROVE') { + iteration++ + + // Step 1: Producer delivers (or revises) + if (iteration === 1) { + // Wait for initial delivery + // msg type: impl_complete / plan_ready + } else { + // Wait for revision + // msg type: impl_complete (revision) + } + + // Step 2: Reviewer examines + // Creates REVIEW task, waits for review_result + + // Step 3: Check verdict + verdict = reviewResult.data.verdict // APPROVE | CONDITIONAL | BLOCK + + if (verdict === 'BLOCK') { + // Step 4: Create fix task for producer + TaskCreate({ + subject: `IMPL-fix-${iteration}`, + description: `Fix issues: ${reviewResult.data.findings}`, + owner: producerRole + }) + // Send feedback to producer + team_msg({ type: "fix_required", data: { iteration, findings: reviewResult.data.findings } }) + } + } + + return { verdict, iterations: iteration } +} +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | Reviewer verdict = `APPROVE` 或 `CONDITIONAL`（无 critical findings） | +| **Max Iterations** | 5 轮（可配置）。Producer 修复 → Reviewer 再审 = 1 轮 | +| **Timeout** | 单轮超时 = 阶段超时（由各角色内部控制） | + +### Feedback Loop + +``` +Signal: review_result { verdict: "BLOCK", findings: [...] } + ↓ +Handler: Coordinator 解析 findings，按 severity 分类 + ↓ +Correction: 创建 IMPL-fix 任务，附带 findings 明细 + Producer 收到任务 → 读取 findings → 修复 → 重新提交 + ↓ +Loop: Reviewer 再次审查修订后的产出 +``` + +**反馈信号结构**: +```javascript +{ + verdict: "APPROVE" | "CONDITIONAL" | "BLOCK", + findings: { + critical: [{ file, line, description, suggestion }], + high: [...], + medium: [...], + low: [...] + }, + iteration: 2, + delta: "+3 fixed, -1 new issue" // 对比上一轮的变化 +} +``` + +### Fallback + +| Condition | Action | +|-----------|--------| +| 达到 max iterations 仍 BLOCK | 上报用户，附带全部 findings 历史 | +| Reviewer 发现 Producer 无法修复的设计问题 | 升级到 CP-5 Escalation，或回退到 CP-1 重新规划 | +| 连续 2 轮 findings 不减少（无改善） | 中断循环，上报用户请求介入 | + +--- + +## CP-3: Parallel Fan-out/Fan-in (并行扇出扇入) + +### Description + +Coordinator 将同一任务或同一类任务广播给多个 agent 并行执行，收集所有结果后聚合。适用于需要多角度分析、分片处理、或冗余验证的场景。 + +### Entry Condition + +- 任务可分解为独立的并行子任务 +- 需要多角度/多维度分析（如安全 + 性能 + 架构审查） +- 大型任务需要分片并行处理 + +### Roles Required + +`coordinator` → `worker-1, worker-2, ... worker-N` → `coordinator` (aggregation) + +### Workflow + +``` + ┌─ worker-1 ─┐ + │ 角度 A │───┐ + broadcast ├─ worker-2 ─┤ │ aggregate +coord ──────────────┤ 角度 B │───┼──── coord + ├─ worker-3 ─┤ │ + │ 角度 C │───┘ + └────────────┘ +``` + +```javascript +// Phase 1: Fan-out - broadcast tasks +const workerTasks = angles.map((angle, i) => { + const taskId = TaskCreate({ + subject: `ANALYZE-${i+1}: ${angle} analysis`, + description: `Analyze from ${angle} perspective: ${requirement}`, + owner: `worker-${i+1}`, + activeForm: `Analyzing ${angle}` + }) + return taskId +}) + +// Phase 2: Wait for all workers (or quorum + timeout) +function waitForCompletion(taskIds, quorumRatio = 1.0, timeoutMs = 300000) { + const startTime = Date.now() + const quorumCount = Math.ceil(taskIds.length * quorumRatio) + let completedCount = 0 + + while (completedCount < quorumCount) { + if (Date.now() - startTime > timeoutMs) break + const tasks = TaskList() + completedCount = taskIds.filter(id => + tasks.find(t => t.id === id && t.status === 'completed') + ).length + // Wait... + } + + return { completed: completedCount, total: taskIds.length, timedOut: completedCount < quorumCount } +} + +// Phase 3: Fan-in - aggregate results +function aggregateResults(taskIds) { + const results = taskIds.map(id => { + const task = TaskGet({ taskId: id }) + return { angle: task.subject, result: task.metadata?.result } + }) + + // Conflict detection + const conflicts = detectConflicts(results) + + return { + results, + conflicts, + consensus: conflicts.length === 0, + summary: synthesize(results) + } +} +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | 所有 worker 完成（或达到 quorum 比例，默认 100%） | +| **Max Iterations** | 1 轮扇出（若聚合后有冲突，可触发 CP-4 Consensus） | +| **Timeout** | 可配置，默认 5 分钟。超时后用已完成的结果聚合 | + +### Feedback Loop + +``` +Signal: 每个 worker 的 {角度}_result message + ↓ +Handler: Coordinator 收集所有结果 + ↓ +Aggregate: 合并结果 + 冲突检测 + ├─ 无冲突 → 直接合成最终结果 + └─ 有冲突 → 升级到 CP-4 Consensus Gate +``` + +**聚合策略**: +- **Union（并集）**: 合并所有发现（适用于安全审查 - 不遗漏任何 finding） +- **Intersection（交集）**: 只保留多个 worker 共同发现的问题（适用于降噪） +- **Weighted（加权）**: 按 worker 的专业权重合并（适用于多专家评审） + +### Fallback + +| Condition | Action | +|-----------|--------| +| Worker 超时未完成 | 用已完成的 worker 结果聚合，标注缺失角度 | +| Worker 返回错误 | 跳过该 worker，用 N-1 结果聚合 | +| 聚合结果有冲突 | 触发 CP-4 Consensus Gate 解决分歧 | + +--- + +## CP-4: Consensus Gate (共识门控) + +### Description + +在做出重要决策前，要求多个 agent 投票表达意见，只有达到 quorum 才能通过。模拟软件开发中的 Design Review、Architecture Decision Record (ADR) 的决策流程。 + +### Entry Condition + +- 架构决策（选择技术方案 A vs B vs C） +- 安全决策（是否可接受某个风险） +- 影响面大的重构（需要多方确认） +- CP-3 扇出结果有冲突需要裁决 + +### Roles Required + +`proposer` → `voter-1, voter-2, ... voter-N` → `coordinator` (tally) + +### Workflow + +``` + ┌─ voter-1 ─────────────┐ + │ APPROVE + rationale │ + proposal ├─ voter-2 ─────────────┤ tally +proposer ─────────→ │ REJECT + rationale │ ────→ coordinator + ├─ voter-3 ─────────────┤ │ + │ APPROVE + conditions │ ▼ + └───────────────────────┘ decision +``` + +```javascript +// Phase 1: Proposal +const proposal = { + id: `PROPOSAL-${Date.now()}`, + title: "Adopt Strategy Pattern for payment gateway", + options: [ + { id: "A", description: "Strategy Pattern with factory", pros: [...], cons: [...] }, + { id: "B", description: "Plugin architecture", pros: [...], cons: [...] } + ], + context: "Payment module needs multi-gateway support", + deadline: Date.now() + 300000 // 5 min +} + +// Phase 2: Broadcast proposal to voters +voters.forEach(voter => { + SendMessage({ + recipient: voter, + content: `## Proposal: ${proposal.title}\n${JSON.stringify(proposal)}`, + summary: "Vote requested" + }) +}) + +// Phase 3: Collect votes +function collectVotes(proposalId, voterCount, quorum, deadline) { + const votes = [] + while (votes.length < voterCount && Date.now() < deadline) { + // Listen for vote messages + const msgs = team_msg({ operation: "list", type: "vote" }) + const newVotes = msgs.filter(m => + m.data.proposalId === proposalId && !votes.find(v => v.from === m.from) + ) + votes.push(...newVotes) + + // Check quorum + if (votes.length >= quorum) break + } + return votes +} + +// Phase 4: Tally and decide +function tallyVotes(votes, quorumRatio = 0.67) { + const approvals = votes.filter(v => v.data.vote === 'APPROVE') + const rejections = votes.filter(v => v.data.vote === 'REJECT') + const conditions = votes.flatMap(v => v.data.conditions || []) + + const approvalRatio = approvals.length / votes.length + const passed = approvalRatio >= quorumRatio + + return { + passed, + approvalRatio, + approvals: approvals.length, + rejections: rejections.length, + conditions: [...new Set(conditions)], + rationales: votes.map(v => ({ from: v.from, vote: v.data.vote, rationale: v.data.rationale })) + } +} +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | 赞成率 ≥ quorum（默认 2/3）且无 BLOCK 级别反对 | +| **Max Iterations** | 2 轮。第 1 轮未达 quorum → 修订提案 → 第 2 轮重投 | +| **Timeout** | 5 分钟。超时后以已收到的票数计算（≥ quorum 则通过） | + +### Feedback Loop + +``` +Signal: vote { vote: "REJECT", rationale: "...", conditions: [...] } + ↓ +Handler: Coordinator 聚合所有反对意见和附加条件 + ↓ +Correction: ├─ 未达 quorum → Proposer 修订提案，融合反对意见 → 重投 + ├─ 达到 quorum 但有 conditions → 记录 conditions 作为实施约束 + └─ 明确通过 → 执行决策 +``` + +**投票格式**: +```javascript +team_msg({ + type: "vote", + data: { + proposalId: "PROPOSAL-xxx", + vote: "APPROVE" | "REJECT" | "ABSTAIN", + rationale: "选择方案A因为...", // 必须提供理由 + conditions: ["需要增加向后兼容层"], // 可选附加条件 + confidence: 0.85 // 置信度 0-1 + } +}) +``` + +### Fallback + +| Condition | Action | +|-----------|--------| +| 2 轮都未达 quorum | 上报用户裁决 | +| 投票截止但票数不足（< N/2） | 延长截止时间 1 轮 | +| 全员 ABSTAIN | 由 Coordinator 做默认决策并记录 | + +--- + +## CP-5: Escalation Chain (逐级升级) + +### Description + +当 agent 遇到无法自行解决的问题时，逐级升级到更高层级的处理能力。模拟软件开发中的 on-call escalation / tiered support。 + +### Entry Condition + +- Agent 自修复失败（尝试 N 次后仍无法解决） +- 问题超出当前角色能力范围 +- 需要更高权限或更广视角的决策 + +### Roles Required + +`agent` → `specialist` → `coordinator` → `user` + +### Workflow + +``` +Level 0 Level 1 Level 2 Level 3 +┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ +│ Agent │────→│Specialist│────→│Coordinator│───→│ User │ +│ 自修复 │ │ 专家诊断 │ │ 全局视角 │ │ 人工裁决 │ +└──────────┘ └──────────┘ └──────────┘ └──────────┘ + │ │ │ │ + ▼ ▼ ▼ ▼ + retry 2x CLI analysis cross-team fix manual fix +``` + +```javascript +// Escalation state machine +const ESCALATION_LEVELS = [ + { + level: 0, + name: "Self-repair", + handler: "agent", + maxAttempts: 2, + actions: ["Retry with different approach", "Read more context", "Simplify approach"] + }, + { + level: 1, + name: "Specialist diagnosis", + handler: "specialist", + maxAttempts: 1, + actions: ["CLI analysis (gemini/qwen)", "Cross-file dependency trace", "Pattern matching"] + }, + { + level: 2, + name: "Coordinator intervention", + handler: "coordinator", + maxAttempts: 1, + actions: ["Reassign to different agent", "Modify task scope", "Create support task"] + }, + { + level: 3, + name: "User escalation", + handler: "user", + maxAttempts: 1, + actions: ["Present diagnosis chain", "Request manual guidance", "Offer options"] + } +] + +function escalate(issue, currentLevel) { + const nextLevel = ESCALATION_LEVELS[currentLevel + 1] + if (!nextLevel) { + // Already at highest level, wait for user + return { action: "wait", level: currentLevel } + } + + team_msg({ + type: "escalate", + data: { + issue: issue.description, + from_level: currentLevel, + to_level: nextLevel.level, + attempts_at_current: issue.attempts, + diagnosis_chain: issue.diagnosisHistory // 所有层级的诊断记录 + } + }) + + return { action: "escalate", nextHandler: nextLevel.handler, level: nextLevel.level } +} +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | 问题在某个层级被解决（agent 报告 issue resolved） | +| **Max Iterations** | 每个层级有独立的 maxAttempts（L0: 2, L1: 1, L2: 1, L3: 1） | +| **Timeout** | L0-L2 无显式超时；L3 用户层需等待用户响应 | + +### Feedback Loop + +``` +Signal: escalate { issue, from_level, diagnosis_chain } + ↓ +Handler: 上级接收问题 + 下级的全部诊断历史 + ↓ +Diagnosis: 上级基于更广视角/更强能力做出诊断 + ↓ +Response: ├─ 解决方案 → 传回原 agent 执行 + ├─ 重新定义问题 → 修改任务描述，agent 重试 + └─ 无法解决 → 继续升级到下一层 +``` + +**诊断链结构** (每层追加): +```javascript +{ + diagnosisHistory: [ + { level: 0, agent: "executor", attempts: 2, diagnosis: "TypeScript类型不匹配", tried: ["修改类型定义", "添加类型断言"] }, + { level: 1, agent: "specialist", attempts: 1, diagnosis: "循环依赖导致类型无法推断", recommendation: "重构模块边界" }, + // ... 每层追加自己的诊断 + ] +} +``` + +### Fallback + +| Condition | Action | +|-----------|--------| +| L3 用户无响应 | Agent 尝试最保守的方案继续，标记为 WORKAROUND | +| 诊断链显示根本问题（如架构缺陷） | 回退到 CP-1 重新规划 | +| 升级到 L1 后解决 | 将解决方案记录为 pattern，下次 L0 可直接处理 | + +--- + +## CP-6: Incremental Delivery (增量交付) + +### Description + +将大型任务分解为小的增量，每个增量独立交付并验证后再进行下一个。模拟 CI/CD 中的小批量交付和渐进式部署。 + +### Entry Condition + +- 大型特性（影响 > 10 个文件） +- 高风险变更（需要逐步验证） +- 用户要求渐进可见的进度 + +### Roles Required + +`coordinator` → `executor` (increment) → `validator` (per-increment) → `coordinator` (gate) + +### Workflow + +``` + ┌─────────────────────────────────────────────────┐ + │ Increment 1 Increment 2 Increment N │ + │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ + │ │ Implement│ │ Implement│ │ Implement│ │ + │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ + │ ▼ ▼ ▼ │ + │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ + │ │ Validate │ │ Validate │ │ Validate │ │ + │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ + │ ▼ ▼ ▼ │ + │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ + │ │ Gate ✓ │ │ Gate ✓ │ │ Gate ✓ │ │ + │ └──────────┘ └──────────┘ └──────────┘ │ + └─────────────────────────────────────────────────┘ + │ + ▼ + Full validation +``` + +```javascript +// Coordinator splits plan into increments +function createIncrements(plan) { + // Group tasks by dependency layers + const layers = topologicalSort(plan.tasks) + + return layers.map((layer, i) => ({ + id: `INCREMENT-${i+1}`, + tasks: layer, + gate: { + syntax_clean: true, + no_regression: true, // 已有测试不破坏 + increment_tests_pass: true // 增量相关测试通过 + } + })) +} + +// Execute increment cycle +for (const increment of increments) { + // Step 1: Executor implements increment + TaskCreate({ + subject: `IMPL-inc-${increment.id}`, + description: `Implement increment: ${increment.tasks.map(t => t.title).join(', ')}`, + owner: "executor" + }) + + // Step 2: Wait for implementation + // msg: increment_ready + + // Step 3: Validator checks increment gate + const gateResult = validateIncrement(increment) + + // Step 4: Gate decision + if (gateResult.passed) { + team_msg({ type: "increment_ready", data: { increment: increment.id, status: "PASS" } }) + // Continue to next increment + } else { + // Feedback: which gate criteria failed + team_msg({ type: "fix_required", data: { + increment: increment.id, + failed_gates: gateResult.failures, + suggestion: gateResult.fix_suggestion + }}) + // Executor fixes → re-validate (max 3 retries per increment) + } +} + +// Final: full validation after all increments +TaskCreate({ subject: "TEST-final", description: "Full test suite after all increments" }) +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | 所有增量通过各自的 gate + 最终全量验证通过 | +| **Max Iterations** | 每个增量最多 3 次重试，总增量数由 plan 决定 | +| **Timeout** | 单个增量超时 = 增量任务数 × 单任务超时 | + +### Feedback Loop + +``` +Signal: increment gate failure { failed_gates, affected_files } + ↓ +Handler: Coordinator 定位失败的 gate 条件 + ↓ +Correction: ├─ syntax_clean 失败 → Executor 修复语法 + ├─ no_regression 失败 → Executor 修复回归 + 回滚该增量 + └─ increment_tests 失败 → 触发 CP-2 Review-Fix Cycle +``` + +**增量进度追踪**: +```javascript +{ + total_increments: 4, + completed: 2, + current: 3, + progress_percent: 50, + gate_history: [ + { id: "INCREMENT-1", attempts: 1, status: "PASS" }, + { id: "INCREMENT-2", attempts: 2, status: "PASS" }, + { id: "INCREMENT-3", attempts: 1, status: "IN_PROGRESS" } + ] +} +``` + +### Fallback + +| Condition | Action | +|-----------|--------| +| 增量重试 3 次仍失败 | 回滚该增量代码，标记为 blocked，继续下一增量 | +| 超过半数增量被 blocked | 停止交付，上报用户评估是否重新规划 | +| 最终全量验证失败 | 识别失败增量组合，逐个回退定位 | + +--- + +## CP-7: Swarming (群策攻关) + +### Description + +当流水线被一个问题阻塞时，暂停正常工作流，所有可用 agent 集中力量解决该问题。模拟敏捷开发中的 swarming / mob debugging。 + +### Entry Condition + +- 关键任务被阻塞超过阈值时间 +- Agent 自修复和 L1 升级都失败 +- 问题影响多个下游任务 + +### Roles Required + +`coordinator` (发起) → `all available agents` (协同) → `coordinator` (裁决) + +### Workflow + +``` + ┌───────────────────────────────────┐ + │ SWARM MODE ACTIVE │ + │ │ + │ ┌────────┐ ┌────────┐ │ + │ │Agent A │ │Agent B │ │ + │ │诊断视角1│ │诊断视角2│ │ + │ └───┬────┘ └───┬────┘ │ + │ │ │ │ + │ ▼ ▼ │ + │ ┌─────────────────────┐ │ + │ │ Coordinator 汇总 │ │ + │ │ 选择最佳诊断 │ │ + │ └─────────┬───────────┘ │ + │ ▼ │ + │ ┌─────────────────────┐ │ + │ │ 指定 Agent 执行修复 │ │ + │ └─────────────────────┘ │ + │ │ + └───────────────────────────────────┘ + │ + ▼ + Resume normal pipeline +``` + +```javascript +// Coordinator initiates swarm +function initiateSwarm(blockingIssue) { + // Step 1: Pause all non-critical tasks + const activeTasks = TaskList().filter(t => t.status === 'in_progress') + activeTasks.forEach(t => { + TaskUpdate({ taskId: t.id, metadata: { paused_for_swarm: true } }) + }) + + // Step 2: Broadcast swarm request + team_msg({ + type: "swarm_join", + data: { + issue: blockingIssue.description, + affected_tasks: blockingIssue.blockedTasks, + diagnosis_so_far: blockingIssue.diagnosisHistory, + assignment: "All agents: diagnose from your expertise angle" + } + }) + + // Step 3: Each agent analyzes from their perspective + // planner: 架构视角诊断 + // executor: 实现细节诊断 + // tester: 测试/环境视角诊断 + + // Step 4: Collect diagnoses (fan-in) + // Uses CP-3 fan-in aggregation + + // Step 5: Coordinator selects best diagnosis + assigns fix + const bestDiagnosis = selectBestDiagnosis(diagnoses) + const fixer = selectBestFixer(bestDiagnosis, availableAgents) + + TaskCreate({ + subject: `SWARM-FIX: ${blockingIssue.summary}`, + description: `Fix based on swarm diagnosis:\n${bestDiagnosis.detail}`, + owner: fixer + }) + + // Step 6: Verify fix, resume pipeline + // ... wait for fix completion ... + + // Step 7: Resume paused tasks + activeTasks.forEach(t => { + TaskUpdate({ taskId: t.id, metadata: { paused_for_swarm: null } }) + }) +} +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | 阻塞问题解决（相关测试通过 / 错误消失） | +| **Max Iterations** | 2 轮诊断。第 1 轮全员诊断 → 修复 → 若失败 → 第 2 轮聚焦诊断 | +| **Timeout** | 10 分钟。超时后以最佳可用诊断尝试修复 | + +### Feedback Loop + +``` +Signal: 每个 agent 的 swarm_diagnosis { perspective, root_cause, confidence, fix_suggestion } + ↓ +Handler: Coordinator 按 confidence 排序，合并互补的诊断 + ↓ +Selection: 选择 confidence 最高且 fix_suggestion 最具体的方案 + ↓ +Execution: 指定最合适的 agent 执行修复 + ↓ +Verify: 修复后重新运行触发阻塞的场景 + ├─ 通过 → 恢复流水线 + └─ 失败 → 第 2 轮，排除已尝试方案 +``` + +### Fallback + +| Condition | Action | +|-----------|--------| +| 2 轮 swarm 未解决 | 升级到用户（CP-5 L3） | +| 修复引入新问题 | 回滚修复，尝试次优方案 | +| Agent 在 swarm 期间无响应 | 跳过该 agent，用其余 agent 的诊断 | + +--- + +## CP-8: Consulting/Advisory (咨询顾问) + +### Description + +工作中的 agent 暂停当前任务，向拥有特定领域知识的 specialist 请求建议，获得建议后继续工作。不同于升级（CP-5），consulting 不转移问题所有权。 + +### Entry Condition + +- Agent 遇到不熟悉的领域（如安全、性能优化、特定框架用法） +- 需要验证方案的正确性但不需要他人实现 +- 需要领域最佳实践参考 + +### Roles Required + +`requester` (任何工作中的 agent) → `consultant` (specialist agent) → `requester` (继续工作) + +### Workflow + +``` + requester consultant + ┌──────────┐ ┌──────────┐ + │ Working │ │ Idle │ + │ │──(1)请求────→│ │ + │ Paused │ │ 分析中 │ + │ │←─(2)建议────│ │ + │ Resume │ │ Idle │ + │ (应用建议)│ │ │ + └──────────┘ └──────────┘ +``` + +```javascript +// Requester sends consultation request +function requestConsultation(topic, context, urgency = 'normal') { + team_msg({ + type: "consult_request", + from: currentRole, + to: "coordinator", // coordinator routes to appropriate specialist + data: { + topic: topic, // "security", "performance", "database" + question: context.question, // 具体问题 + context: context.codeSnippet, // 相关代码片段 + options: context.options, // 可选方案（如果有） + urgency: urgency // "blocking" | "normal" | "low" + } + }) + // Pause current work, wait for response +} + +// Coordinator routes to specialist +function routeConsultation(request) { + const specialist = selectSpecialist(request.data.topic) + // If no specialist agent exists, use CLI tool as specialist + if (!specialist) { + // Fallback: invoke CLI analysis + Bash(`ccw cli -p "PURPOSE: Expert consultation on ${request.data.topic} +TASK: ${request.data.question} +CONTEXT: ${request.data.context} +EXPECTED: Actionable recommendation with confidence level +" --tool gemini --mode analysis`, { run_in_background: true }) + } +} + +// Consultant provides advice +function provideAdvice(request) { + team_msg({ + type: "consult_response", + from: "consultant", + to: request.from, + data: { + recommendation: "使用 bcrypt 而非 SHA-256 进行密码哈希", + rationale: "bcrypt 内置 salt 和自适应计算成本...", + confidence: 0.95, + references: ["OWASP Password Storage Cheat Sheet"], + caveats: ["需要增加 ~100ms 延迟"], + alternative: "如果延迟敏感，可考虑 Argon2id" + } + }) +} + +// Requester applies advice +function applyAdvice(advice) { + if (advice.data.confidence >= 0.8) { + // Apply recommendation directly + return { action: "apply", recommendation: advice.data.recommendation } + } else { + // Low confidence: request second opinion or escalate + return { action: "second_opinion" } + } +} +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | 咨询回复 confidence ≥ 0.8 且 requester 成功应用建议 | +| **Max Iterations** | 1 次主咨询 + 1 次追问（如果首次回复不够清晰） | +| **Timeout** | blocking: 2 分钟, normal: 5 分钟, low: 无超时 | + +### Feedback Loop + +``` +Signal: consult_response { recommendation, confidence, caveats } + ↓ +Handler: Requester 评估建议的适用性 + ├─ confidence ≥ 0.8 → 直接应用 + ├─ confidence < 0.8 → 追问一轮或请求 second opinion + └─ 与当前方案冲突 → 上报 coordinator 裁决 + ↓ +Correction: Requester 基于建议调整实现方案，继续原任务 +``` + +### Fallback + +| Condition | Action | +|-----------|--------| +| 无可用 specialist | 使用 CLI tool (gemini/qwen) 替代 | +| 咨询超时 | Requester 用自己的最佳判断继续，标注 unverified | +| 建议与当前设计冲突 | 上报 coordinator，触发 CP-4 Consensus | + +--- + +## CP-9: Dual-Track (双轨并行) + +### Description + +两条工作轨道并行推进，在预定义的同步点（checkpoint）对齐。典型应用：设计与实现并行、前端与后端并行、功能开发与测试开发并行。 + +### Entry Condition + +- 任务可分解为两条相对独立的工作流 +- 两条轨道有明确的同步点（interface contract、API spec、schema） +- 并行执行能提升整体效率 + +### Roles Required + +`coordinator` → `track-A` agent + `track-B` agent → `coordinator` (sync) + +### Workflow + +``` + Track A (Design/API) Track B (Implementation) + ┌────────────┐ ┌────────────┐ + │ Phase A-1 │ │ Phase B-1 │ + │ API 设计 │ │ 脚手架搭建 │ + └─────┬──────┘ └─────┬──────┘ + │ │ + ▼ ┌──────────┐ ▼ + ╔═══════════════╗│ SYNC-1 │╔═══════════════╗ + ║ checkpoint 1 ║│ 对齐接口 │║ checkpoint 1 ║ + ╚═══════════════╝└──────────┘╚═══════════════╝ + │ │ + ▼ ▼ + ┌────────────┐ ┌────────────┐ + │ Phase A-2 │ │ Phase B-2 │ + │ 详细设计 │ │ 核心实现 │ + └─────┬──────┘ └─────┬──────┘ + │ │ + ▼ ┌──────────┐ ▼ + ╔═══════════════╗│ SYNC-2 │╔═══════════════╗ + ║ checkpoint 2 ║│ 集成验证 │║ checkpoint 2 ║ + ╚═══════════════╝└──────────┘╚═══════════════╝ +``` + +```javascript +// Coordinator defines sync points +const syncPoints = [ + { + id: "SYNC-1", + name: "Interface Contract", + trackA_deliverable: "API schema / interface definitions", + trackB_deliverable: "Scaffold with interface stubs", + alignment_check: "Both tracks agree on interface signatures" + }, + { + id: "SYNC-2", + name: "Integration Verification", + trackA_deliverable: "Complete design + test specs", + trackB_deliverable: "Core implementation", + alignment_check: "Implementation passes design test specs" + } +] + +// Phase execution with sync barriers +for (const sync of syncPoints) { + // Launch both tracks in parallel + const trackATask = TaskCreate({ + subject: `TRACK-A-${sync.id}: ${sync.trackA_deliverable}`, + owner: "track-a-agent" + }) + const trackBTask = TaskCreate({ + subject: `TRACK-B-${sync.id}: ${sync.trackB_deliverable}`, + owner: "track-b-agent" + }) + + // Wait for both tracks to reach sync point + waitForBoth(trackATask, trackBTask) + + // Sync point: alignment check + const aligned = checkAlignment(sync.alignment_check, trackAResult, trackBResult) + + if (!aligned) { + // Misalignment detected → correction + team_msg({ type: "sync_checkpoint", data: { + sync_id: sync.id, + status: "MISALIGNED", + trackA_state: trackAResult.summary, + trackB_state: trackBResult.summary, + conflicts: aligned.conflicts + }}) + // Coordinator mediates: which track adjusts? + resolveAlignment(aligned.conflicts, trackATask, trackBTask) + } else { + team_msg({ type: "sync_checkpoint", data: { sync_id: sync.id, status: "ALIGNED" } }) + } +} +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | 所有 sync point 对齐 + 最终集成验证通过 | +| **Max Iterations** | 每个 sync point 最多 2 次对齐尝试 | +| **Timeout** | 先到达 sync point 的 track 等待另一个 track，超时 5 分钟 | + +### Feedback Loop + +``` +Signal: sync_checkpoint { status: "MISALIGNED", conflicts } + ↓ +Handler: Coordinator 分析冲突来源 + ├─ Track A 的设计不合理 → 要求 Track A 调整设计 + ├─ Track B 偏离了接口约定 → 要求 Track B 重新对齐 + └─ 双方都有偏差 → 协商折中方案 + ↓ +Correction: 被要求调整的 track agent 收到 fix 描述 + → 调整产出 → 重新到达 sync point +``` + +### Fallback + +| Condition | Action | +|-----------|--------| +| 一条 track 完全阻塞 | 另一条 track 暂停等待，触发 CP-7 Swarming 解决阻塞 | +| Sync 对齐 2 次失败 | 降级为 CP-1 Linear Pipeline（顺序执行） | +| 两条 track 差距过大（一快一慢） | 快 track 预做下一阶段，慢 track 加速 | + +--- + +## CP-10: Post-Mortem (复盘回顾) + +### Description + +任务完成后，对整个执行过程进行结构化回顾，提取经验教训和改进建议。这些知识可以反馈到项目的 CLAUDE.md 或 core memory 中，提升未来任务的执行质量。 + +### Entry Condition + +- 团队完成一个完整任务周期后（所有 task completed） +- 任务执行过程中出现显著问题（多次失败、多次升级） +- 用户主动请求回顾 + +### Roles Required + +`coordinator` (发起 + 汇总) → `all agents` (提供各自视角) → `coordinator` (文档化) + +### Workflow + +``` + ┌──────────────────────────────────────────┐ + │ POST-MORTEM PHASE │ + │ │ + │ 1. Coordinator 收集执行数据 │ + │ ├─ 任务链完成情况 │ + │ ├─ 消息总线历史 │ + │ └─ 迭代/升级/失败记录 │ + │ │ + │ 2. 每个 Agent 提交回顾 │ + │ ├─ Planner: 规划准确度 │ + │ ├─ Executor: 实现障碍 │ + │ └─ Tester: 质量发现 │ + │ │ + │ 3. Coordinator 汇总 │ + │ ├─ 成功因素 │ + │ ├─ 改进点 │ + │ └─ 行动建议 │ + │ │ + │ 4. 输出到 memory / CLAUDE.md │ + └──────────────────────────────────────────┘ +``` + +```javascript +// Coordinator initiates post-mortem +function conductPostMortem(teamName) { + // Step 1: Collect execution data + const messages = team_msg({ operation: "list", team: teamName }) + const tasks = TaskList() + const completedTasks = tasks.filter(t => t.status === 'completed') + const failedTasks = tasks.filter(t => t.status === 'in_progress' && t.metadata?.stuck) + + const executionData = { + total_tasks: tasks.length, + completed: completedTasks.length, + total_messages: messages.length, + escalations: messages.filter(m => m.type === 'escalate').length, + fix_cycles: messages.filter(m => m.type === 'fix_required').length, + errors: messages.filter(m => m.type === 'error').length + } + + // Step 2: Request agent retrospectives (Fan-out) + // Each agent answers: What went well? What was difficult? What should change? + agents.forEach(agent => { + SendMessage({ + recipient: agent.name, + content: `## Post-Mortem Request +请回顾本次任务，回答: +1. **顺利**: 哪些方面执行顺利？ +2. **困难**: 遇到了什么障碍？ +3. **建议**: 下次如何改进？ +4. **模式**: 发现了什么可复用的模式？`, + summary: "Post-mortem request" + }) + }) + + // Step 3: Aggregate findings + // Collect retro_finding messages from all agents + const findings = collectFindings(agents) + + // Step 4: Generate structured post-mortem report + const report = { + team: teamName, + timestamp: new Date().toISOString(), + execution_summary: executionData, + what_went_well: findings.flatMap(f => f.went_well), + what_was_difficult: findings.flatMap(f => f.difficult), + improvement_actions: findings.flatMap(f => f.suggestions), + reusable_patterns: findings.flatMap(f => f.patterns), + recommendations: generateRecommendations(executionData, findings) + } + + // Step 5: Persist learnings + // Option A: Write to session artifacts + Write(`${sessionFolder}/post-mortem.json`, JSON.stringify(report, null, 2)) + + // Option B: Import to core memory (if significant) + if (report.reusable_patterns.length > 0) { + mcp__ccw-tools__core_memory({ + operation: "import", + text: `Team ${teamName} post-mortem: ${report.reusable_patterns.join('; ')}` + }) + } + + return report +} +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | 所有 agent 提交回顾 + 报告生成完毕 | +| **Max Iterations** | 1 轮（回顾是单次活动） | +| **Timeout** | Agent 回顾提交超时 3 分钟，超时则仅用已收到的回顾 | + +### Feedback Loop + +``` +Signal: retro_finding { went_well, difficult, suggestions, patterns } + ↓ +Handler: Coordinator 分类、去重、优先级排序 + ↓ +Output: ├─ 高价值 patterns → 写入 core memory / CLAUDE.md + ├─ 改进建议 → 记录到项目 guidelines + └─ 问题根因 → 作为下次任务的预防措施 +``` + +**学习闭环**: Post-mortem 的输出反馈到未来任务的 Phase 2 Context Loading，实现持续改进。 + +### Fallback + +| Condition | Action | +|-----------|--------| +| Agent 无法提供回顾（已关闭） | 从消息总线历史中提取该 agent 的执行数据 | +| 无显著 findings | 生成最小报告，不写入 core memory | +| 执行数据缺失 | 基于现有数据生成部分报告 | + +--- + +## Pattern Composition (模式组合) + +### 常见组合 + +协作模式可以组合使用，形成更复杂的工作流： + +``` +1. Standard Development (标准开发) + CP-1 (Pipeline) + CP-2 (Review-Fix) + CP-10 (Post-Mortem) + +2. High-Risk Feature (高风险特性) + CP-4 (Consensus on design) → CP-6 (Incremental Delivery) → CP-2 (Review-Fix each increment) + +3. Complex Investigation (复杂问题调查) + CP-3 (Fan-out analysis) → CP-4 (Consensus on diagnosis) → CP-7 (Swarm if needed) + +4. Parallel Development (并行开发) + CP-9 (Dual-Track) + CP-2 (Review-Fix per track) + CP-10 (Post-Mortem) + +5. Expert-Guided Development (专家指导开发) + CP-8 (Consulting for design) → CP-1 (Pipeline implementation) → CP-2 (Review-Fix) +``` + +### 组合规则 + +1. **不可重入**: 同一时间只能有一个 CP-7 (Swarming) 实例 +2. **可嵌套**: CP-6 的每个增量可以内部使用 CP-2 +3. **可升级**: CP-2 内发现无法修复的问题可升级到 CP-5 或 CP-7 +4. **可降级**: CP-9 对齐失败可降级到 CP-1 +5. **CP-10 始终在最后**: Post-mortem 只在团队任务完成后执行 + +### State Machine (模式状态机) + +``` + ┌──────────────────────────────────────────┐ + │ COORDINATOR FSM │ + │ │ + 新需求 ────→ [PLAN] ──→ [EXECUTE] ──→ [VALIDATE] ──→ [DONE] │ + │ │ │ │ │ + │ │ │ │ │ + ▼ ▼ ▼ ▼ │ + CP-4? CP-6? CP-2? CP-10 │ + Consensus Incremental Review-Fix Post- │ + Gate Delivery Cycle Mortem │ + │ │ │ │ + ▼ ▼ ▼ │ + [blocked?] [blocked?] [blocked?] │ + │ │ │ │ + ▼ ▼ ▼ │ + CP-5/CP-7 CP-5/CP-7 CP-5/CP-7 │ + Escalate Escalate Escalate │ + /Swarm /Swarm /Swarm │ + └──────────────────────────────────────────┘ +``` + +--- + +## Coordinator Integration Guide + +### Coordinator 如何选择协作模式 + +```javascript +// In coordinate.md Phase 1 (需求澄清) or Phase 4 (协调主循环) + +function selectCollaborationPattern(context) { + const { taskType, complexity, riskLevel, teamSize, hasExpert } = context + + // Rule-based selection + const patterns = ['CP-1'] // CP-1 is always the base + + if (riskLevel === 'high') patterns.push('CP-4') // Consensus for risky decisions + if (complexity === 'High' && taskType === 'feature') patterns.push('CP-6') // Incremental for large features + if (taskType === 'review' || taskType === 'test') patterns.push('CP-2') // Review-Fix for quality + if (hasExpert && complexity !== 'Low') patterns.push('CP-8') // Consulting for expertise + patterns.push('CP-10') // Post-mortem always included + + return patterns +} +``` + +### Coordinator 消息路由表（含协作模式） + +| 消息类型 | 触发模式 | Coordinator 动作 | +|---------|---------|-----------------| +| `plan_ready` | CP-1 | 审批 plan → 通知 executor | +| `impl_complete` | CP-1/CP-6 | 解锁 TEST/REVIEW 或下一增量 | +| `review_result` (BLOCK) | CP-2 | 创建 fix 任务 → 启动 Review-Fix Cycle | +| `vote` | CP-4 | 收集投票 → 达到 quorum 则执行决策 | +| `escalate` | CP-5 | 路由到上一级处理者 | +| `increment_ready` | CP-6 | 验证增量 gate → 允许或拒绝 | +| `swarm_join` | CP-7 | 暂停其他任务 → 聚合诊断 | +| `consult_request` | CP-8 | 路由到 specialist 或 CLI tool | +| `sync_checkpoint` | CP-9 | 检查两条 track 对齐状态 | +| `retro_finding` | CP-10 | 收集回顾 → 生成报告 | diff --git a/.claude/skills/team-command-designer/specs/quality-standards.md b/.claude/skills/team-command-designer/specs/quality-standards.md new file mode 100644 index 00000000..347403fa --- /dev/null +++ b/.claude/skills/team-command-designer/specs/quality-standards.md @@ -0,0 +1,124 @@ +# Quality Standards for Team Commands + +Quality assessment criteria for generated team command .md files. + +## When to Use + +| Phase | Usage | Section | +|-------|-------|---------| +| Phase 5 | Score generated command | All dimensions | +| Phase 3 | Guide generation quality | Checklist | + +--- + +## Quality Dimensions + +### 1. Completeness (25%) + +| Score | Criteria | +|-------|----------| +| 100% | All 15 required sections present with substantive content | +| 80% | 12+ sections present, minor gaps in non-critical areas | +| 60% | Core sections present (front matter, message bus, 5 phases, error handling) | +| 40% | Missing critical sections | +| 0% | Skeleton only | + +**Required Sections Checklist:** +- [ ] YAML front matter with `group: team` +- [ ] Overview with core capabilities +- [ ] Role Definition (name, responsibility, communication) +- [ ] Message Bus section with team_msg examples +- [ ] Message Types table +- [ ] Execution Process overview diagram +- [ ] Phase 1: Task Discovery implementation +- [ ] Phase 2: Context Loading implementation +- [ ] Phase 3: Core Work implementation +- [ ] Phase 4: Validation/Summary implementation +- [ ] Phase 5: Report + Loop implementation +- [ ] Error Handling table +- [ ] Code examples in all phases + +### 2. Pattern Compliance (25%) + +| Score | Criteria | +|-------|----------| +| 100% | All 8 infrastructure patterns + selected collaboration patterns fully implemented | +| 80% | 6 core infra patterns + at least 1 collaboration pattern with convergence | +| 60% | Minimum 6 infra patterns, collaboration patterns present but incomplete | +| 40% | Missing critical patterns (message bus or task lifecycle) | +| 0% | No pattern compliance | + +**Infrastructure Pattern Checklist:** +- [ ] Pattern 1: Message bus - team_msg before every SendMessage +- [ ] Pattern 2: YAML front matter - all fields present, group: team +- [ ] Pattern 3: Task lifecycle - TaskList/Get/Update flow +- [ ] Pattern 4: Five-phase structure - all 5 phases present +- [ ] Pattern 5: Complexity-adaptive (if applicable) +- [ ] Pattern 6: Coordinator spawn compatible +- [ ] Pattern 7: Error handling table +- [ ] Pattern 8: Session files (if applicable) + +**Collaboration Pattern Checklist:** +- [ ] At least one CP selected (CP-1 minimum) +- [ ] Each selected CP has convergence criteria defined +- [ ] Each selected CP has feedback loop mechanism +- [ ] Each selected CP has timeout/fallback behavior +- [ ] CP-specific message types registered in message bus section +- [ ] Escalation path defined (CP-5) for error scenarios + +### 3. Integration (25%) + +| Score | Criteria | +|-------|----------| +| 100% | All integration checks pass, spawn snippet ready | +| 80% | Minor integration notes, no blocking issues | +| 60% | Some checks need attention but functional | +| 40% | Task prefix conflict or missing critical tools | +| 0% | Incompatible with team system | + +### 4. Consistency (25%) + +| Score | Criteria | +|-------|----------| +| 100% | Role name, task prefix, message types consistent throughout | +| 80% | Minor inconsistencies in non-critical areas | +| 60% | Some mixed terminology but intent clear | +| 40% | Confusing or contradictory content | +| 0% | Internally inconsistent | + +--- + +## Quality Gates + +| Gate | Threshold | Action | +|------|-----------|--------| +| PASS | >= 80% | Deliver to `.claude/commands/team/{team-name}/` | +| REVIEW | 60-79% | Fix recommendations, re-validate | +| FAIL | < 60% | Major rework needed, re-run from Phase 3 | + +--- + +## Issue Classification + +### Errors (Must Fix) + +- Missing YAML front matter +- Missing `group: team` +- No message bus section +- No task lifecycle (TaskList/Get/Update) +- No SendMessage to coordinator +- Task prefix conflicts with existing + +### Warnings (Should Fix) + +- Missing error handling table +- Incomplete Phase implementation (skeleton only) +- Missing team_msg before some SendMessage calls +- No complexity-adaptive routing when role is complex + +### Info (Nice to Have) + +- Code examples could be more detailed +- Additional message type examples +- Session file structure documentation +- CLI integration examples diff --git a/.claude/skills/team-command-designer/specs/team-design-patterns.md b/.claude/skills/team-command-designer/specs/team-design-patterns.md new file mode 100644 index 00000000..e666528f --- /dev/null +++ b/.claude/skills/team-command-designer/specs/team-design-patterns.md @@ -0,0 +1,446 @@ +# Team Command Design Patterns + +> Extracted from 5 production team commands: coordinate, plan, execute, test, review +> Extended with 10 collaboration patterns for diverse team interaction models + +--- + +## Pattern Architecture + +``` +Team Design Patterns +├── Section A: Infrastructure Patterns (8) ← HOW to build a team command +│ ├── Pattern 1: Message Bus Integration +│ ├── Pattern 2: YAML Front Matter +│ ├── Pattern 3: Task Lifecycle +│ ├── Pattern 4: Five-Phase Execution +│ ├── Pattern 5: Complexity-Adaptive Routing +│ ├── Pattern 6: Coordinator Spawn Integration +│ ├── Pattern 7: Error Handling Table +│ └── Pattern 8: Session File Structure +│ +└── Section B: Collaboration Patterns (10) ← HOW agents interact + ├── CP-1: Linear Pipeline (线性流水线) + ├── CP-2: Review-Fix Cycle (审查修复循环) + ├── CP-3: Parallel Fan-out/Fan-in (并行扇出扇入) + ├── CP-4: Consensus Gate (共识门控) + ├── CP-5: Escalation Chain (逐级升级) + ├── CP-6: Incremental Delivery (增量交付) + ├── CP-7: Swarming (群策攻关) + ├── CP-8: Consulting/Advisory (咨询顾问) + ├── CP-9: Dual-Track (双轨并行) + └── CP-10: Post-Mortem (复盘回顾) +``` + +**Section B** collaboration patterns are documented in: [collaboration-patterns.md](collaboration-patterns.md) + +--- + +## When to Use + +| Phase | Usage | Section | +|-------|-------|---------| +| Phase 0 | Understand all patterns before design | All sections | +| Phase 2 | Select applicable infrastructure + collaboration patterns | Pattern catalog | +| Phase 3 | Apply patterns during generation | Implementation details | +| Phase 4 | Verify compliance | Checklists | + +--- + +# Section A: Infrastructure Patterns + +## Pattern 1: Message Bus Integration + +Every teammate must use `mcp__ccw-tools__team_msg` for persistent logging before every `SendMessage`. + +### Structure + +```javascript +// BEFORE every SendMessage, call: +mcp__ccw-tools__team_msg({ + operation: "log", + team: teamName, + from: "", // planner | executor | tester | + to: "coordinator", + type: "", + summary: "", + ref: "", + data: { /* optional structured payload */ } +}) +``` + +### Standard Message Types + +| Type | Direction | Trigger | Payload | +|------|-----------|---------|---------| +| `plan_ready` | planner -> coordinator | Plan generation complete | `{ taskCount, complexity }` | +| `plan_approved` | coordinator -> planner | Plan reviewed | `{ approved: true }` | +| `plan_revision` | planner -> coordinator | Plan modified per feedback | `{ changes }` | +| `task_unblocked` | coordinator -> any | Dependency resolved | `{ taskId }` | +| `impl_complete` | executor -> coordinator | Implementation done | `{ changedFiles, syntaxClean }` | +| `impl_progress` | any -> coordinator | Progress update | `{ batch, total }` | +| `test_result` | tester -> coordinator | Test cycle end | `{ passRate, iterations }` | +| `review_result` | tester -> coordinator | Review done | `{ verdict, findings }` | +| `fix_required` | any -> coordinator | Critical issues | `{ details[] }` | +| `error` | any -> coordinator | Blocking error | `{ message }` | +| `shutdown` | coordinator -> all | Team dissolved | `{}` | + +### Collaboration Pattern Message Types + +| Type | Used By | Direction | Trigger | +|------|---------|-----------|---------| +| `vote` | CP-4 Consensus | any -> coordinator | Agent casts vote on proposal | +| `escalate` | CP-5 Escalation | any -> coordinator | Agent escalates unresolved issue | +| `increment_ready` | CP-6 Incremental | executor -> coordinator | Increment delivered for validation | +| `swarm_join` | CP-7 Swarming | any -> coordinator | Agent joins swarm on blocker | +| `consult_request` | CP-8 Consulting | any -> specialist | Agent requests expert advice | +| `consult_response` | CP-8 Consulting | specialist -> requester | Expert provides advice | +| `sync_checkpoint` | CP-9 Dual-Track | any -> coordinator | Track reaches sync point | +| `retro_finding` | CP-10 Post-Mortem | any -> coordinator | Retrospective insight | + +### Adding New Message Types + +When designing a new role, define role-specific message types following the convention: +- `{action}_ready` - Work product ready for review +- `{action}_complete` - Work phase finished +- `{action}_progress` - Intermediate progress update + +### Message Bus Section Template + +```markdown +## Message Bus + +Every SendMessage **before**, must call `mcp__ccw-tools__team_msg` to log: + +\`\`\`javascript +mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "", to: "coordinator", type: "", summary: "" }) +\`\`\` + +### Supported Message Types + +| Type | Direction | Trigger | Description | +|------|-----------|---------|-------------| +| `` | -> coordinator | | | +``` + +--- + +## Pattern 2: YAML Front Matter + +Every team command file must start with standardized YAML front matter. + +### Structure + +```yaml +--- +name: +description: Team - +argument-hint: "" +allowed-tools: SendMessage(*), TaskUpdate(*), TaskList(*), TaskGet(*), TodoWrite(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), Task(*) +group: team +--- +``` + +### Field Rules + +| Field | Rule | Example | +|-------|------|---------| +| `name` | Lowercase, matches filename | `plan`, `execute`, `test` | +| `description` | `Team -` prefix + Chinese capability list | `Team planner - 多角度代码探索、结构化实现规划` | +| `argument-hint` | Empty string for teammates, has hint for coordinator | `""` | +| `allowed-tools` | Start with `SendMessage(*), TaskUpdate(*), TaskList(*), TaskGet(*)` | See each role | +| `group` | Always `team` | `team` | + +### Minimum Tool Set (All Teammates) + +``` +SendMessage(*), TaskUpdate(*), TaskList(*), TaskGet(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Grep(*) +``` + +### Role-Specific Additional Tools + +| Role Type | Additional Tools | +|-----------|-----------------| +| Read-only (reviewer, analyzer) | None extra | +| Write-capable (executor, fixer) | `Write(*), Edit(*)` | +| Agent-delegating (planner, executor) | `Task(*)` | + +--- + +## Pattern 3: Task Lifecycle + +All teammates follow the same task discovery and lifecycle pattern. + +### Standard Flow + +```javascript +// Step 1: Find my tasks +const tasks = TaskList() +const myTasks = tasks.filter(t => + t.subject.startsWith('-') && // PLAN-*, IMPL-*, TEST-*, REVIEW-* + t.owner === '' && + t.status === 'pending' && + t.blockedBy.length === 0 // Not blocked +) + +// Step 2: No tasks -> idle +if (myTasks.length === 0) return + +// Step 3: Claim task (lowest ID first) +const task = TaskGet({ taskId: myTasks[0].id }) +TaskUpdate({ taskId: task.id, status: 'in_progress' }) + +// Step 4: Execute work +// ... role-specific logic ... + +// Step 5: Complete and loop +TaskUpdate({ taskId: task.id, status: 'completed' }) + +// Step 6: Check for next task +const nextTasks = TaskList().filter(t => + t.subject.startsWith('-') && + t.owner === '' && + t.status === 'pending' && + t.blockedBy.length === 0 +) +if (nextTasks.length > 0) { + // Continue with next task -> back to Step 3 +} +``` + +### Task Prefix Convention + +| Prefix | Role | Example | +|--------|------|---------| +| `PLAN-` | planner | `PLAN-001: Explore and plan implementation` | +| `IMPL-` | executor | `IMPL-001: Implement approved plan` | +| `TEST-` | tester | `TEST-001: Test-fix cycle` | +| `REVIEW-` | tester | `REVIEW-001: Code review and requirement verification` | +| `-` | new role | Must be unique, uppercase, hyphen-suffixed | + +### Task Chain (defined in coordinate.md) + +``` +PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001 + ↑ blockedBy ↑ blockedBy +``` + +--- + +## Pattern 4: Five-Phase Execution Structure + +Every team command follows a consistent 5-phase internal structure. + +### Standard Phases + +| Phase | Purpose | Common Actions | +|-------|---------|----------------| +| Phase 1: Task Discovery | Find and claim assigned tasks | TaskList, TaskGet, TaskUpdate | +| Phase 2: Context Loading | Load necessary context for work | Read plan/config, detect framework | +| Phase 3: Core Work | Execute primary responsibility | Role-specific logic | +| Phase 4: Validation/Summary | Verify work quality | Syntax check, criteria verification | +| Phase 5: Report + Loop | Report to coordinator, check next | SendMessage, TaskUpdate, TaskList | + +### Phase Structure Template + +```markdown +### Phase N: + +\`\`\`javascript +// Implementation code +\`\`\` +``` + +--- + +## Pattern 5: Complexity-Adaptive Routing + +All roles that process varying-difficulty tasks should implement adaptive routing. + +### Decision Logic + +```javascript +function assessComplexity(description) { + let score = 0 + if (/refactor|architect|restructure|module|system/.test(description)) score += 2 + if (/multiple|across|cross/.test(description)) score += 2 + if (/integrate|api|database/.test(description)) score += 1 + if (/security|performance/.test(description)) score += 1 + return score >= 4 ? 'High' : score >= 2 ? 'Medium' : 'Low' +} +``` + +### Routing Table + +| Complexity | Direct Claude | CLI Agent | Sub-agent | +|------------|---------------|-----------|-----------| +| Low | Direct execution | - | - | +| Medium | - | `cli-explore-agent` / `cli-lite-planning-agent` | - | +| High | - | CLI agent | `code-developer` / `universal-executor` | + +### Sub-agent Delegation Pattern + +```javascript +Task({ + subagent_type: "", + run_in_background: false, + description: "", + prompt: ` +## Task Objective +${taskDescription} + +## Output Location +${sessionFolder}/${outputFile} + +## MANDATORY FIRST STEPS +1. Read: .workflow/project-tech.json (if exists) +2. Read: .workflow/project-guidelines.json (if exists) + +## Expected Output +${expectedFormat} +` +}) +``` + +--- + +## Pattern 6: Coordinator Spawn Integration + +New teammates must be spawnable from coordinate.md using standard pattern. + +### Skill Path Format (Folder-Based) + +Team commands use folder-based organization with colon-separated skill paths: + +``` +File location: .claude/commands/team/{team-name}/{role-name}.md +Skill path: team:{team-name}:{role-name} + +Example: + .claude/commands/team/spec/analyst.md → team:spec:analyst + .claude/commands/team/security/scanner.md → team:security:scanner +``` + +### Spawn Template + +```javascript +Task({ + subagent_type: "general-purpose", + team_name: teamName, + name: "", + prompt: `You are team "${teamName}" . + +When you receive -* tasks, call Skill(skill="team:${teamName}:") to execute. + +Current requirement: ${taskDescription} +Constraints: ${constraints} + +## Message Bus (Required) +Before each SendMessage, call mcp__ccw-tools__team_msg: +mcp__ccw-tools__team_msg({ operation: "log", team: "${teamName}", from: "", to: "coordinator", type: "", summary: "" }) + +Workflow: +1. TaskList -> find -* tasks assigned to you +2. Skill(skill="team:${teamName}:") to execute +3. team_msg log + SendMessage results to coordinator +4. TaskUpdate completed -> check next task` +}) +``` + +--- + +## Pattern 7: Error Handling Table + +Every command ends with a standardized error handling table. + +### Template + +```markdown +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| No tasks available | Idle, wait for coordinator assignment | +| Plan/Context file not found | Notify coordinator, request location | +| Sub-agent failure | Retry once, then fallback to direct execution | +| Max iterations exceeded | Report to coordinator, suggest intervention | +| Critical issue beyond scope | SendMessage fix_required to coordinator | +``` + +--- + +## Pattern 8: Session File Structure + +Roles that produce artifacts follow standard session directory patterns. + +### Convention + +``` +.workflow/.team-/{identifier}-{YYYY-MM-DD}/ +├── +├── manifest.json (if multiple outputs) +└── .task/ (if generating task files) + ├── TASK-001.json + └── TASK-002.json +``` + +--- + +# Section B: Collaboration Patterns + +> Complete specification: [collaboration-patterns.md](collaboration-patterns.md) + +## Collaboration Pattern Quick Reference + +Every collaboration pattern has these standard elements: + +| Element | Description | +|---------|-------------| +| **Entry Condition** | When to activate this pattern | +| **Workflow** | Step-by-step execution flow | +| **Convergence Criteria** | How the pattern terminates successfully | +| **Feedback Loop** | How information flows back to enable correction | +| **Timeout/Fallback** | What happens when the pattern doesn't converge | +| **Max Iterations** | Hard limit on cycles (where applicable) | + +### Pattern Selection Guide + +| Scenario | Recommended Pattern | Why | +|----------|-------------------|-----| +| Standard feature development | CP-1: Linear Pipeline | Well-defined sequential stages | +| Code review with fixes needed | CP-2: Review-Fix Cycle | Iterative improvement until quality met | +| Multi-angle analysis needed | CP-3: Fan-out/Fan-in | Parallel exploration, aggregated results | +| Critical decision (architecture, security) | CP-4: Consensus Gate | Multiple perspectives before committing | +| Agent stuck / self-repair failed | CP-5: Escalation Chain | Progressive expertise levels | +| Large feature (many files) | CP-6: Incremental Delivery | Validated increments reduce risk | +| Blocking issue stalls pipeline | CP-7: Swarming | All resources on one problem | +| Domain-specific expertise needed | CP-8: Consulting | Expert advice without role change | +| Design + Implementation parallel | CP-9: Dual-Track | Faster delivery with sync checkpoints | +| Post-completion learning | CP-10: Post-Mortem | Capture insights for future improvement | + +--- + +## Pattern Summary Checklist + +When designing a new team command, verify: + +### Infrastructure Patterns +- [ ] YAML front matter with `group: team` +- [ ] Message bus section with `team_msg` logging +- [ ] Role-specific message types defined +- [ ] Task lifecycle: TaskList -> TaskGet -> TaskUpdate flow +- [ ] Unique task prefix (no collision with existing PLAN/IMPL/TEST/REVIEW, scan `team/**/*.md`) +- [ ] 5-phase execution structure +- [ ] Complexity-adaptive routing (if applicable) +- [ ] Coordinator spawn template integration +- [ ] Error handling table +- [ ] SendMessage communication to coordinator only +- [ ] Session file structure (if producing artifacts) + +### Collaboration Patterns +- [ ] At least one collaboration pattern selected +- [ ] Convergence criteria defined (max iterations / quality gate / timeout) +- [ ] Feedback loop implemented (how results flow back) +- [ ] Timeout/fallback behavior specified +- [ ] Pattern-specific message types registered +- [ ] Coordinator aware of pattern (can route messages accordingly) diff --git a/.claude/skills/team-command-designer/templates/command-template.md b/.claude/skills/team-command-designer/templates/command-template.md new file mode 100644 index 00000000..4c45ed7a --- /dev/null +++ b/.claude/skills/team-command-designer/templates/command-template.md @@ -0,0 +1,219 @@ +# Team Command Template + +Ready-to-use template for generating team command .md files. + +## Purpose + +Provide a complete, fill-in-the-blanks template for generating new team command files that comply with all design patterns. + +## Usage Context + +| Phase | Usage | +|-------|-------| +| Phase 0 | Read to understand output structure | +| Phase 3 | Apply with role-specific content | + +--- + +## Template + +```markdown +--- +name: {{role_name}} +description: Team {{role_name}} - {{description_cn}} +argument-hint: "" +allowed-tools: {{allowed_tools}} +group: team +--- + +# Team {{display_name}} Command (/{{skill_path}}) + +## Overview + +Team {{role_name}} role command. Operates as a teammate within an Agent Team, responsible for {{responsibility_type}}. + +**Core capabilities:** +- Task discovery from shared team task list ({{task_prefix}}-* tasks) +{{#if adaptive_routing}} +- Complexity-adaptive routing (Low -> direct, Medium/High -> agent) +{{/if}} +- {{responsibility_type}}-specific processing +- Structured result reporting to coordinator + +## Role Definition + +**Name**: `{{role_name}}` +**Responsibility**: {{phase2_name}} -> {{phase3_name}} -> Report results +**Communication**: SendMessage to coordinator only + +## Message Bus + +Every SendMessage **before**, must call `mcp__ccw-tools__team_msg` to log: + +\`\`\`javascript +mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "{{role_name}}", to: "coordinator", type: "", summary: "" }) +\`\`\` + +### Supported Message Types + +| Type | Direction | Trigger | Description | +|------|-----------|---------|-------------| +{{#each message_types}} +| `{{this.type}}` | {{../role_name}} -> coordinator | {{this.trigger}} | {{this.description}} | +{{/each}} + +### Examples + +\`\`\`javascript +{{#each message_types}} +// {{this.trigger}} +mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "{{../role_name}}", to: "coordinator", type: "{{this.type}}", summary: "{{this.trigger}}" }) +{{/each}} +\`\`\` + +## Execution Process + +\`\`\` +Phase 1: Task Discovery + |-- TaskList to find unblocked {{task_prefix}}-* tasks + |-- TaskGet to read full task details + \`-- TaskUpdate to mark in_progress + +Phase 2: {{phase2_name}} + +Phase 3: {{phase3_name}} + +Phase 4: {{phase4_name}} + +Phase 5: Report to Coordinator + |-- team_msg log + SendMessage results + |-- TaskUpdate completed + \`-- Check for next {{task_prefix}}-* task +\`\`\` + +## Implementation + +### Phase 1: Task Discovery + +\`\`\`javascript +const tasks = TaskList() +const myTasks = tasks.filter(t => + t.subject.startsWith('{{task_prefix}}-') && + t.owner === '{{role_name}}' && + t.status === 'pending' && + t.blockedBy.length === 0 +) + +if (myTasks.length === 0) return // idle + +const task = TaskGet({ taskId: myTasks[0].id }) +TaskUpdate({ taskId: task.id, status: 'in_progress' }) +\`\`\` + +### Phase 2: {{phase2_name}} + +\`\`\`javascript +// TODO: Implement context loading for {{role_name}} +// Reference: .claude/commands/team/{{reference_command}}.md Phase 2 +\`\`\` + +### Phase 3: {{phase3_name}} + +\`\`\`javascript +// TODO: Implement core {{role_name}} logic +// Reference: .claude/commands/team/{{reference_command}}.md Phase 3 +{{#if adaptive_routing}} + +// Complexity-adaptive execution +if (complexity === 'Low') { + // Direct execution +} else { + // Delegate to sub-agent + Task({ + subagent_type: "universal-executor", + run_in_background: false, + description: "{{role_name}} work", + prompt: `Execute {{role_name}} task: ${task.description}` + }) +} +{{/if}} +\`\`\` + +### Phase 4: {{phase4_name}} + +\`\`\`javascript +// TODO: Implement validation/summary for {{role_name}} +// Reference: .claude/commands/team/{{reference_command}}.md Phase 4 +\`\`\` + +### Phase 5: Report to Coordinator + +\`\`\`javascript +mcp__ccw-tools__team_msg({ + operation: "log", team: teamName, + from: "{{role_name}}", to: "coordinator", + type: "{{primary_message_type}}", + summary: `{{task_prefix}} complete: ${task.subject}` +}) + +SendMessage({ + type: "message", + recipient: "coordinator", + content: `## {{display_name}} Results + +**Task**: ${task.subject} +**Status**: ${resultStatus} + +### Summary +${resultSummary}`, + summary: `{{task_prefix}} complete` +}) + +TaskUpdate({ taskId: task.id, status: 'completed' }) + +const nextTasks = TaskList().filter(t => + t.subject.startsWith('{{task_prefix}}-') && + t.owner === '{{role_name}}' && + t.status === 'pending' && + t.blockedBy.length === 0 +) + +if (nextTasks.length > 0) { + // Continue with next task -> back to Phase 1 +} +\`\`\` + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| No {{task_prefix}}-* tasks available | Idle, wait for coordinator assignment | +| Context/Plan file not found | Notify coordinator, request location | +{{#if adaptive_routing}} +| Sub-agent failure | Retry once, then fallback to direct execution | +{{/if}} +| Critical issue beyond scope | SendMessage fix_required to coordinator | +| Unexpected error | Log error via team_msg, report to coordinator | +``` + +--- + +## Variable Reference + +| Variable | Source | Description | +|----------|--------|-------------| +| `{{team_name}}` | config.team_name | Team folder name (lowercase) | +| `{{role_name}}` | config.role_name | Role identifier (lowercase) | +| `{{skill_path}}` | config.skill_path | Full skill path (e.g., `team:spec:analyst`) | +| `{{display_name}}` | config.display_name | Human-readable role name | +| `{{description_cn}}` | config.description_cn | Chinese description | +| `{{task_prefix}}` | config.task_prefix | Task prefix (UPPERCASE) | +| `{{allowed_tools}}` | config.allowed_tools | Tool list | +| `{{responsibility_type}}` | config.responsibility_type | Role type | +| `{{adaptive_routing}}` | config.adaptive_routing | Boolean | +| `{{message_types}}` | config.message_types | Array of message type objects | +| `{{phase2_name}}` | patterns.phase_structure.phase2 | Phase 2 name | +| `{{phase3_name}}` | patterns.phase_structure.phase3 | Phase 3 name | +| `{{phase4_name}}` | patterns.phase_structure.phase4 | Phase 4 name | +| `{{reference_command}}` | patterns.similar_to.primary | Most similar existing command | +| `{{primary_message_type}}` | config.message_types[0].type | Primary message type |