diff --git a/.claude/skills/team-command-designer/SKILL.md b/.claude/skills/team-command-designer/SKILL.md deleted file mode 100644 index 60034dfb..00000000 --- a/.claude/skills/team-command-designer/SKILL.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -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 deleted file mode 100644 index 2330bf59..00000000 --- a/.claude/skills/team-command-designer/phases/01-requirements-collection.md +++ /dev/null @@ -1,227 +0,0 @@ -# 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 deleted file mode 100644 index f1670b9e..00000000 --- a/.claude/skills/team-command-designer/phases/02-pattern-analysis.md +++ /dev/null @@ -1,266 +0,0 @@ -# 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 deleted file mode 100644 index 3cefd770..00000000 --- a/.claude/skills/team-command-designer/phases/03-command-generation.md +++ /dev/null @@ -1,364 +0,0 @@ -# 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')} -\`\`\` - -### CLI 回退 - -当 \`mcp__ccw-tools__team_msg\` MCP 不可用时，使用 \`ccw team\` CLI 作为等效回退： - -\\\`\\\`\\\`javascript -// 回退: 将 MCP 调用替换为 Bash CLI（参数一一对应） -Bash(\\\`ccw team log --team "\${teamName}" --from "${config.role_name}" --to "coordinator" --type "${config.message_types[0]?.type || 'result'}" --summary "<摘要>" --json\\\`) -\\\`\\\`\\\` - -**参数映射**: \`team_msg(params)\` → \`ccw team log --team --from ${config.role_name} --to coordinator --type --summary "" [--ref ] [--data ''] [--json]\`` -``` - -### 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 deleted file mode 100644 index 714f595c..00000000 --- a/.claude/skills/team-command-designer/phases/04-integration-verification.md +++ /dev/null @@ -1,212 +0,0 @@ -# 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 deleted file mode 100644 index 85e6d975..00000000 --- a/.claude/skills/team-command-designer/phases/05-validation.md +++ /dev/null @@ -1,264 +0,0 @@ -# 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: "CLI Fallback Section", pattern: /CLI 回退|CLI Fallback/ }, - { name: "ccw team CLI Example", pattern: /ccw team log/ }, - { 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" - }, - { - name: "CLI Fallback Present", - check: () => { - return (command.includes('CLI 回退') || command.includes('CLI Fallback')) && - command.includes('ccw team log') - }, - severity: "high" - } -] - -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 deleted file mode 100644 index b59eacb4..00000000 --- a/.claude/skills/team-command-designer/specs/collaboration-patterns.md +++ /dev/null @@ -1,1341 +0,0 @@ -# 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 deleted file mode 100644 index e75a188f..00000000 --- a/.claude/skills/team-command-designer/specs/quality-standards.md +++ /dev/null @@ -1,126 +0,0 @@ -# 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 1b: CLI fallback - `ccw team` CLI fallback section with parameter mapping -- [ ] 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 -- Missing CLI fallback section (`### CLI 回退` with `ccw team` examples) -- 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 deleted file mode 100644 index e51d4785..00000000 --- a/.claude/skills/team-command-designer/specs/team-design-patterns.md +++ /dev/null @@ -1,472 +0,0 @@ -# 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 - -### CLI Fallback - -When `mcp__ccw-tools__team_msg` MCP is unavailable, use `ccw team` CLI as equivalent fallback: - -```javascript -// Fallback: Replace MCP call with Bash CLI (parameters map 1:1) -Bash(`ccw team log --team "${teamName}" --from "" --to "coordinator" --type "" --summary "" [--ref ] [--data ''] --json`) -``` - -**Parameter mapping**: `team_msg(params)` → `ccw team --team [--from/--to/--type/--summary/--ref/--data/--id/--last] [--json]` - -**Coordinator** uses all 4 operations: `log`, `list`, `status`, `read` -**Teammates** primarily use: `log` - -### Message Bus Section Template - -```markdown -## 消息总线 - -每次 SendMessage **前**，必须调用 `mcp__ccw-tools__team_msg` 记录消息： - -\`\`\`javascript -mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "", to: "coordinator", type: "", summary: "" }) -\`\`\` - -### 支持的 Message Types - -| Type | 方向 | 触发时机 | 说明 | -|------|------|----------|------| -| `` | → coordinator | | | - -### CLI 回退 - -当 `mcp__ccw-tools__team_msg` MCP 不可用时，使用 `ccw team` CLI 作为等效回退： - -\`\`\`javascript -// 回退: 将 MCP 调用替换为 Bash CLI（参数一一对应） -Bash(\`ccw team log --team "${teamName}" --from "" --to "coordinator" --type "" --summary "" --json\`) -\`\`\` - -**参数映射**: `team_msg(params)` → `ccw team log --team --from --to coordinator --type --summary "" [--ref ] [--data ''] [--json]` -``` - ---- - -## 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 -- [ ] CLI fallback section with `ccw team` CLI examples and parameter mapping -- [ ] 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 deleted file mode 100644 index a43a7525..00000000 --- a/.claude/skills/team-command-designer/templates/command-template.md +++ /dev/null @@ -1,230 +0,0 @@ -# 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}} -\`\`\` - -### CLI 回退 - -当 `mcp__ccw-tools__team_msg` MCP 不可用时，使用 `ccw team` CLI 作为等效回退： - -\`\`\`javascript -// 回退: 将 MCP 调用替换为 Bash CLI（参数一一对应） -Bash(\`ccw team log --team "${teamName}" --from "{{role_name}}" --to "coordinator" --type "{{primary_message_type}}" --summary "<摘要>" --json\`) -\`\`\` - -**参数映射**: `team_msg(params)` → `ccw team log --team --from {{role_name}} --to coordinator --type --summary "" [--ref ] [--data ''] [--json]` - -## 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 | diff --git a/.claude/skills/team-planex/SKILL.md b/.claude/skills/team-planex/SKILL.md new file mode 100644 index 00000000..5d3f13ad --- /dev/null +++ b/.claude/skills/team-planex/SKILL.md @@ -0,0 +1,264 @@ +--- +name: team-planex +description: Unified team skill for plan-and-execute pipeline. 2-member team (planner + executor) with wave pipeline for concurrent planning and execution. All roles invoke this skill with --role arg. Triggers on "team planex". +allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*) +--- + +# Team PlanEx + +2 成员边规划边执行团队。通过 Wave Pipeline（波次流水线）实现 planner 和 executor 并行工作：planner 完成一个 wave 的 queue 后立即创建 EXEC-* 任务，同时进入下一 wave 规划。所有成员通过 `--role=xxx` 路由。 + +## Architecture Overview + +``` +┌──────────────────────────────────────────────┐ +│ Skill(skill="team-planex", args="--role=xxx") │ +└────────────────┬─────────────────────────────┘ + │ Role Router + ┌───────┴───────┐ + ↓ ↓ + ┌─────────┐ ┌──────────┐ + │ planner │ │ executor │ + │ PLAN-* │ │ EXEC-* │ + └─────────┘ └──────────┘ +``` + +**设计原则**: 只有 2 个角色，没有独立 coordinator。SKILL.md 入口承担轻量编排（创建团队、派发初始任务链），然后 planner 担任 lead 角色持续推进。 + +## Role Router + +### Input Parsing + +```javascript +const args = "$ARGUMENTS" +const roleMatch = args.match(/--role[=\s]+(\w+)/) + +if (!roleMatch) { + // No --role: orchestration mode (lightweight coordinator) + // → See "Orchestration Mode" section below +} + +const role = roleMatch[1] +const teamName = args.match(/--team[=\s]+([\w-]+)/)?.[1] || "planex" +``` + +### Role Dispatch + +```javascript +const VALID_ROLES = { + "planner": { file: "roles/planner.md", prefix: "PLAN" }, + "executor": { file: "roles/executor.md", prefix: "EXEC" } +} + +if (!VALID_ROLES[role]) { + throw new Error(`Unknown role: ${role}. Available: ${Object.keys(VALID_ROLES).join(', ')}`) +} + +// Read and execute role-specific logic +Read(VALID_ROLES[role].file) +// → Execute the 5-phase process defined in that file +``` + +### Available Roles + +| Role | Task Prefix | Responsibility | Reuses Agent | Role File | +|------|-------------|----------------|--------------|-----------| +| `planner` | PLAN-* | 需求拆解 → issue 创建 → 方案设计 → 队列编排 → EXEC 任务派发 | issue-plan-agent, issue-queue-agent | [roles/planner.md](roles/planner.md) | +| `executor` | EXEC-* | 加载 solution → 代码实现 → 测试 → 提交 | code-developer | [roles/executor.md](roles/executor.md) | + +## Input Types + +支持 3 种输入方式（通过 args 传入 planner）： + +| 输入类型 | 格式 | 示例 | +|----------|------|------| +| Issue IDs | 直接传入 ID | `--role=planner ISS-20260215-001 ISS-20260215-002` | +| 需求文本 | `--text '...'` | `--role=planner --text '实现用户认证模块'` | +| Plan 文件 | `--plan path` | `--role=planner --plan plan/2026-02-15-auth.md` | + +## Shared Infrastructure + +### Role Isolation Rules + +#### Output Tagging（强制） + +```javascript +SendMessage({ content: `## [${role}] ...`, summary: `[${role}] ...` }) +mcp__ccw-tools__team_msg({ summary: `[${role}] ...` }) +``` + +#### Planner 边界 + +| 允许 | 禁止 | +|------|------| +| 需求拆解 (issue 创建) | ❌ 直接编写/修改代码 | +| 方案设计 (issue-plan-agent) | ❌ 调用 code-developer | +| 队列编排 (issue-queue-agent) | ❌ 运行测试 | +| 创建 EXEC-* 任务 | ❌ git commit | +| 监控进度 (消息总线) | | + +#### Executor 边界 + +| 允许 | 禁止 | +|------|------| +| 处理 EXEC-* 前缀的任务 | ❌ 创建 issue | +| 调用 code-developer 实现 | ❌ 修改 solution/queue | +| 运行测试验证 | ❌ 为 planner 创建 PLAN-* 任务 | +| git commit 提交 | ❌ 直接与用户交互 (AskUserQuestion) | +| SendMessage 给 planner | | + +### Team Configuration + +```javascript +const TEAM_CONFIG = { + name: "planex", + sessionDir: ".workflow/.team/PEX-{slug}-{date}/", + msgDir: ".workflow/.team-msg/planex/", + issueDataDir: ".workflow/issues/" +} +``` + +### Message Bus + +```javascript +mcp__ccw-tools__team_msg({ + operation: "log", + team: teamName, + from: role, + to: role === "planner" ? "executor" : "planner", + type: "", + summary: `[${role}] `, + ref: "" +}) +``` + +**Message types by role**: + +| Role | Types | +|------|-------| +| planner | `wave_ready`, `queue_ready`, `all_planned`, `error` | +| executor | `impl_complete`, `impl_failed`, `wave_done`, `error` | + +### CLI Fallback + +```javascript +Bash(`ccw team log --team "${teamName}" --from "${role}" --to "${role === 'planner' ? 'executor' : 'planner'}" --type "" --summary "" --json`) +``` + +### Task Lifecycle (Both Roles) + +```javascript +const tasks = TaskList() +const myTasks = tasks.filter(t => + t.subject.startsWith(`${VALID_ROLES[role].prefix}-`) && + t.owner === role && + 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-4: Role-specific (see roles/{role}.md) +// Phase 5: Report + Loop +``` + +## Wave Pipeline + +``` +Wave 1: planner 创建 issues + 规划 solutions + 形成 queue + ↓ (queue ready → 创建 EXEC-* 任务) +Wave 1 执行: executor 开始实现 ←→ planner 继续规划 Wave 2 + ↓ +Wave 2 执行: executor 实现 Wave 2 ←→ planner 规划 Wave 3 + ... +Final: planner 发送 all_planned → executor 完成剩余 EXEC-* → 结束 +``` + +**波次规则**: +- planner 每完成一个 wave 的 queue 后，立即创建 EXEC-* 任务供 executor 消费 +- planner 不等待 executor 完成当前 wave，直接进入下一 wave +- executor 持续轮询并消费可用的 EXEC-* 任务 +- 当 planner 发送 `all_planned` 消息后，executor 完成所有剩余任务即可结束 + +## Orchestration Mode + +当不带 `--role` 调用时，SKILL.md 进入轻量编排模式： + +```javascript +// 1. 创建团队 +TeamCreate({ team_name: teamName }) + +// 2. 解析输入参数 +const issueIds = args.match(/ISS-\d{8}-\d{6}/g) || [] +const textMatch = args.match(/--text\s+['"]([^'"]+)['"]/) +const planMatch = args.match(/--plan\s+(\S+)/) + +let plannerInput = args // 透传给 planner + +// 3. 创建初始 PLAN-* 任务 +TaskCreate({ + subject: "PLAN-001: 初始规划", + description: `规划任务。输入: ${plannerInput}`, + activeForm: "规划中", + owner: "planner" +}) + +// 4. Spawn planner agent +Task({ + subagent_type: "general-purpose", + team_name: teamName, + name: "planner", + prompt: `你是 team "${teamName}" 的 PLANNER。 +当你收到 PLAN-* 任务时，调用 Skill(skill="team-planex", args="--role=planner") 执行。 +当前输入: ${plannerInput} + +## 角色准则（强制） +- 你只能处理 PLAN-* 前缀的任务 +- 所有输出必须带 [planner] 标识前缀 +- 完成每个 wave 后立即创建 EXEC-* 任务供 executor 消费 + +## 消息总线（必须） +每次 SendMessage 前，先调用 mcp__ccw-tools__team_msg 记录。 + +工作流程: +1. TaskList → 找到 PLAN-* 任务 +2. Skill(skill="team-planex", args="--role=planner") 执行 +3. team_msg log + SendMessage +4. TaskUpdate completed → 检查下一个任务` +}) + +// 5. Spawn executor agent +Task({ + subagent_type: "general-purpose", + team_name: teamName, + name: "executor", + prompt: `你是 team "${teamName}" 的 EXECUTOR。 +当你收到 EXEC-* 任务时，调用 Skill(skill="team-planex", args="--role=executor") 执行。 + +## 角色准则（强制） +- 你只能处理 EXEC-* 前缀的任务 +- 所有输出必须带 [executor] 标识前缀 +- 每个 solution 完成后通知 planner + +## 消息总线（必须） +每次 SendMessage 前，先调用 mcp__ccw-tools__team_msg 记录。 + +工作流程: +1. TaskList → 找到 EXEC-* 任务（等待 planner 创建） +2. Skill(skill="team-planex", args="--role=executor") 执行 +3. team_msg log + SendMessage +4. TaskUpdate completed → 检查下一个任务` +}) +``` + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Unknown --role value | Error with available role list | +| Missing --role arg | Enter orchestration mode | +| Role file not found | Error with expected path (roles/{name}.md) | +| Planner wave failure | Retry once, then report error and halt pipeline | +| Executor impl failure | Report to planner, continue with next EXEC-* task | +| No EXEC-* tasks yet | Executor idles, polls for new tasks | +| Pipeline stall | Planner monitors — if executor blocked > 2 tasks, escalate to user | diff --git a/ccw/frontend/settings-full-page.png b/ccw/frontend/settings-full-page.png new file mode 100644 index 00000000..d635f03e Binary files /dev/null and b/ccw/frontend/settings-full-page.png differ diff --git a/ccw/frontend/src/components/a2ui/A2UIPopupCard.tsx b/ccw/frontend/src/components/a2ui/A2UIPopupCard.tsx index bb333ccb..18073ef8 100644 --- a/ccw/frontend/src/components/a2ui/A2UIPopupCard.tsx +++ b/ccw/frontend/src/components/a2ui/A2UIPopupCard.tsx @@ -5,7 +5,7 @@ // Used for displayMode: 'popup' surfaces (e.g., ask_question) // Supports markdown content parsing and multi-page navigation -import { useState, useCallback, useMemo } from 'react'; +import { useState, useCallback, useMemo, useEffect } from 'react'; import { useIntl } from 'react-intl'; import ReactMarkdown from 'react-markdown'; import remarkGfm from 'remark-gfm'; @@ -167,6 +167,23 @@ function SinglePagePopup({ surface, onClose }: A2UIPopupCardProps) { const questionId = (surface.initialState as any)?.questionId as string | undefined; + // Countdown timer for auto-selection + const timeoutAt = (surface.initialState as any)?.timeoutAt as string | undefined; + const defaultLabel = (surface.initialState as any)?.defaultValue as string | undefined; + const [remaining, setRemaining] = useState(null); + + useEffect(() => { + if (!timeoutAt || !defaultLabel) return; + const target = new Date(timeoutAt).getTime(); + const tick = () => { + const secs = Math.max(0, Math.ceil((target - Date.now()) / 1000)); + setRemaining(secs); + }; + tick(); + const id = setInterval(tick, 1000); + return () => clearInterval(id); + }, [timeoutAt, defaultLabel]); + // Extract title, message, and description from surface components const titleComponent = surface.components.find( (c) => c.id === 'title' && 'Text' in (c.component as any) @@ -351,6 +368,15 @@ function SinglePagePopup({ surface, onClose }: A2UIPopupCardProps) { )} + {/* Countdown for auto-selection */} + {remaining !== null && defaultLabel && ( +
+ {remaining > 0 + ? `${remaining}s 后将自动选择「${defaultLabel}」` + : `即将自动选择「${defaultLabel}」`} +
+ )} + {/* Footer - Action buttons */} {actionButtons.length > 0 && ( @@ -383,6 +409,22 @@ function MultiPagePopup({ surface, onClose }: A2UIPopupCardProps) { const [currentPage, setCurrentPage] = useState(0); + // Countdown timer for auto-selection + const timeoutAt = (state as any)?.timeoutAt as string | undefined; + const [remaining, setRemaining] = useState(null); + + useEffect(() => { + if (!timeoutAt) return; + const target = new Date(timeoutAt).getTime(); + const tick = () => { + const secs = Math.max(0, Math.ceil((target - Date.now()) / 1000)); + setRemaining(secs); + }; + tick(); + const id = setInterval(tick, 1000); + return () => clearInterval(id); + }, [timeoutAt]); + // "Other" per-page state const [otherSelectedPages, setOtherSelectedPages] = useState>(new Set()); const [otherTexts, setOtherTexts] = useState>(new Map()); @@ -613,6 +655,15 @@ function MultiPagePopup({ surface, onClose }: A2UIPopupCardProps) { ))} + {/* Countdown for auto-selection */} + {remaining !== null && ( +
+ {remaining > 0 + ? `${remaining}s 后将自动提交默认选项` + : '即将自动提交默认选项'} +
+ )} + {/* Footer - Navigation buttons */}
diff --git a/ccw/frontend/src/packages/a2ui-runtime/core/A2UITypes.ts b/ccw/frontend/src/packages/a2ui-runtime/core/A2UITypes.ts index ba1fbc1f..5067bc51 100644 --- a/ccw/frontend/src/packages/a2ui-runtime/core/A2UITypes.ts +++ b/ccw/frontend/src/packages/a2ui-runtime/core/A2UITypes.ts @@ -127,6 +127,7 @@ export const RadioGroupComponentSchema = z.object({ label: TextContentSchema, value: z.string(), description: TextContentSchema.optional(), + isDefault: z.boolean().optional(), })), selectedValue: TextContentSchema.optional(), onChange: ActionSchema, diff --git a/ccw/frontend/src/packages/a2ui-runtime/renderer/components/A2UIRadioGroup.tsx b/ccw/frontend/src/packages/a2ui-runtime/renderer/components/A2UIRadioGroup.tsx index c2b062a5..deab8fb9 100644 --- a/ccw/frontend/src/packages/a2ui-runtime/renderer/components/A2UIRadioGroup.tsx +++ b/ccw/frontend/src/packages/a2ui-runtime/renderer/components/A2UIRadioGroup.tsx @@ -43,7 +43,9 @@ export const A2UIRadioGroup: ComponentRenderer = ({ component, onAction, resolve return ( {radioConfig.options.map((option, idx) => { - const labelText = resolveTextContent(option.label, resolveBinding); + const rawLabel = resolveTextContent(option.label, resolveBinding); + const labelText = rawLabel.replace(/\s*\(Recommended\)\s*/i, ''); + const isDefault = (option as any).isDefault === true || /\(Recommended\)/i.test(rawLabel); const descriptionText = option.description ? resolveTextContent(option.description, resolveBinding) : undefined; @@ -61,6 +63,11 @@ export const A2UIRadioGroup: ComponentRenderer = ({ component, onAction, resolve className="text-sm font-medium leading-none cursor-pointer" > {labelText} + {isDefault && ( + + 推荐 + + )} {descriptionText && ( diff --git a/ccw/src/tools/ask-question.ts b/ccw/src/tools/ask-question.ts index 669f253f..41350f12 100644 --- a/ccw/src/tools/ask-question.ts +++ b/ccw/src/tools/ask-question.ts @@ -751,6 +751,7 @@ Type inference: options + multiSelect=true → multi-select; options + multiSele properties: { label: { type: 'string', description: 'Display text, also used as value' }, description: { type: 'string', description: 'Option description' }, + isDefault: { type: 'boolean', description: 'Mark as default/recommended option' }, }, required: ['label'], }, @@ -830,6 +831,7 @@ interface PageMeta { function generateMultiQuestionSurface( questions: SimpleQuestion[], surfaceId: string, + timeoutMs: number, ): { surfaceUpdate: { surfaceId: string; @@ -997,6 +999,7 @@ function generateMultiQuestionSurface( questionType: 'multi-question', pages, totalPages: questions.length, + timeoutAt: new Date(Date.now() + timeoutMs).toISOString(), }, displayMode: 'popup', }, @@ -1055,7 +1058,7 @@ async function executeSimpleFormat( const compositeId = `multi-${Date.now()}`; const surfaceId = `question-${compositeId}`; - const { surfaceUpdate, pages } = generateMultiQuestionSurface(questions, surfaceId); + const { surfaceUpdate, pages } = generateMultiQuestionSurface(questions, surfaceId, timeout ?? DEFAULT_TIMEOUT_MS); // Create promise for the composite answer const resultPromise = new Promise((resolve, reject) => { diff --git a/codex-lens/src/codexlens/parsers/astgrep_processor.py b/codex-lens/src/codexlens/parsers/astgrep_processor.py index e0358743..4eb21423 100644 --- a/codex-lens/src/codexlens/parsers/astgrep_processor.py +++ b/codex-lens/src/codexlens/parsers/astgrep_processor.py @@ -324,6 +324,15 @@ class AstGrepPythonProcessor(BaseAstGrepProcessor): for node in from_matches: module = self._get_match(node, "MODULE") names = self._get_match(node, "NAMES") + # Prefer parsing from full node text to handle multiple imports + # (ast-grep-py capture may only include the first name). + try: + node_text = self._binding._get_node_text(node) if self._binding else "" + except Exception: + node_text = "" + parsed_names = self._extract_import_names_from_text(node_text) if node_text else "" + if parsed_names: + names = parsed_names start_line, end_line = self._get_line_range(node) if module: all_matches.append((start_line, end_line, "from_import", f"{module}:{names}", node)) @@ -478,29 +487,46 @@ class AstGrepPythonProcessor(BaseAstGrepProcessor): module = parts[0] names = parts[1] if len(parts) > 1 else "" - # Record the import relationship - relationships.append(CodeRelationship( - source_symbol=get_current_scope(), - target_symbol=module, - relationship_type=RelationshipType.IMPORTS, - source_file=source_file, - target_file=None, - source_line=start_line, - )) + names = (names or "").strip() + if names.startswith("(") and names.endswith(")"): + names = names[1:-1].strip() - # Add aliases for imported names + # Record IMPORTS edges for the imported names (module.symbol), and + # update aliases for call/usage resolution. if names and names != "*": for name in names.split(","): name = name.strip() - # Handle "name as alias" syntax + if not name or name == "*": + continue + if " as " in name: - as_parts = name.split(" as ") + as_parts = name.split(" as ", 1) original = as_parts[0].strip() alias = as_parts[1].strip() + if not original: + continue + target = f"{module}.{original}" if module else original if alias: - update_aliases({alias: f"{module}.{original}"}) - elif name: - update_aliases({name: f"{module}.{name}"}) + update_aliases({alias: target}) + relationships.append(CodeRelationship( + source_symbol=get_current_scope(), + target_symbol=target, + relationship_type=RelationshipType.IMPORTS, + source_file=source_file, + target_file=None, + source_line=start_line, + )) + else: + target = f"{module}.{name}" if module else name + update_aliases({name: target}) + relationships.append(CodeRelationship( + source_symbol=get_current_scope(), + target_symbol=target, + relationship_type=RelationshipType.IMPORTS, + source_file=source_file, + target_file=None, + source_line=start_line, + )) elif match_type == "call": # Resolve alias for call target diff --git a/codex-lens/src/codexlens/parsers/treesitter_parser.py b/codex-lens/src/codexlens/parsers/treesitter_parser.py index 019b6189..70ab91f9 100644 --- a/codex-lens/src/codexlens/parsers/treesitter_parser.py +++ b/codex-lens/src/codexlens/parsers/treesitter_parser.py @@ -595,7 +595,7 @@ class TreeSitterSymbolParser: targets: List[str] = [] if node.type == "import_statement": - for child in node.children: + for i, child in enumerate(node.children): if child.type == "aliased_import": name_node = child.child_by_field_name("name") alias_node = child.child_by_field_name("alias") @@ -632,7 +632,7 @@ class TreeSitterSymbolParser: if module_node is not None: module_name = self._node_text(source_bytes, module_node).strip() - for child in node.children: + for i, child in enumerate(node.children): if child.type == "aliased_import": name_node = child.child_by_field_name("name") alias_node = child.child_by_field_name("alias") @@ -650,7 +650,18 @@ class TreeSitterSymbolParser: if bound_name: aliases[bound_name] = target targets.append(target) - elif child.type == "identifier": + elif child.type == "dotted_name" and node.field_name_for_child(i) == "name": + # tree-sitter-python represents `from X import A, B, C` as + # multiple dotted_name nodes (field: "name"). + imported_name = self._node_text(source_bytes, child).strip() + if not imported_name: + continue + target = ( + f"{module_name}.{imported_name}" if module_name else imported_name + ) + aliases[imported_name] = target + targets.append(target) + elif child.type == "identifier" and node.field_name_for_child(i) == "name": imported_name = self._node_text(source_bytes, child).strip() if not imported_name or imported_name in {"from", "import", "*"}: continue