feat: add spec team commands with structured discussion rounds

Design 5 team commands based on spec-generator skill workflow, introducing multi-perspective discussion rounds between each phase: - spec-coordinate: workflow orchestration + discussion management - spec-analyst: seed analysis + codebase exploration (RESEARCH-*) - spec-writer: 4-type document generation (DRAFT-*) - spec-reviewer: 4-dimension quality scoring (QUALITY-*) - spec-discuss: multi-perspective critique + consensus building (DISCUSS-*)
2026-02-14 02:42:04 +08:00 · 2026-02-13 10:52:19 +08:00
parent e485f1d69b
commit 0b67cd4bf4
5 changed files with 2088 additions and 0 deletions
--- a/.claude/commands/team/spec-analyst.md
+++ b/.claude/commands/team/spec-analyst.md
@@ -0,0 +1,310 @@
+---
+name: spec-analyst
+description: Team spec analyst - 种子分析、代码库探索、上下文收集、多维度研究
+argument-hint: ""
+allowed-tools: SendMessage(*), TaskUpdate(*), TaskList(*), TaskGet(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Grep(*), Task(*)
+group: team
+---
+
+# Team Spec Analyst Command (/team:spec-analyst)
+
+## Overview
+
+Team spec-analyst role command. Operates as a teammate within a Spec Team, responsible for discovery, codebase exploration, and multi-dimensional context gathering. Maps to spec-generator Phase 1 (Discovery).
+
+**Core capabilities:**
+- Task discovery from shared team task list (RESEARCH-* tasks)
+- Seed analysis: problem statement, users, domain, constraints extraction
+- Codebase exploration: existing patterns, architecture, tech stack detection
+- Multi-dimensional research: 3-5 exploration dimensions with complexity assessment
+- Structured context output for downstream discussion and drafting
+
+## Role Definition
+
+**Name**: `spec-analyst`
+**Responsibility**: Seed Analysis → Codebase Exploration → Context Packaging → Report
+**Communication**: SendMessage to coordinator only
+
+## 消息总线
+
+每次 SendMessage **前**，必须调用 `mcp__ccw-tools__team_msg` 记录消息：
+
+```javascript
+mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "spec-analyst", to: "coordinator", type: "<type>", summary: "<摘要>", ref: "<文件路径>" })
+```
+
+### 支持的 Message Types
+
+| Type | 方向 | 触发时机 | 说明 |
+|------|------|----------|------|
+| `research_ready` | spec-analyst → coordinator | 研究完成 | 附带 discovery-context.json 路径和维度摘要 |
+| `research_progress` | spec-analyst → coordinator | 长时间研究进展 | 阶段性进展更新 |
+| `error` | spec-analyst → coordinator | 遇到不可恢复错误 | 代码库访问失败、CLI 超时等 |
+
+### 调用示例
+
+```javascript
+// 研究就绪
+mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "spec-analyst", to: "coordinator", type: "research_ready", summary: "研究完成: 5个探索维度, 检测到React+Node技术栈", ref: ".workflow/.spec-team/session/discovery-context.json" })
+
+// 进展更新
+mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "spec-analyst", to: "coordinator", type: "research_progress", summary: "种子分析完成, 开始代码库探索 (2/3)" })
+
+// 错误上报
+mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "spec-analyst", to: "coordinator", type: "error", summary: "代码库探索失败: 项目根目录无法识别" })
+```
+
+## Execution Process
+
+```
+Phase 1: Task Discovery
+   ├─ TaskList to find unblocked RESEARCH-* tasks
+   ├─ TaskGet to read full task details
+   └─ TaskUpdate to mark in_progress
+
+Phase 2: Seed Analysis
+   ├─ Parse topic/idea from task description
+   ├─ Extract: problem statement, target users, domain, constraints
+   ├─ Identify 3-5 exploration dimensions
+   └─ Assess complexity (simple/moderate/complex)
+
+Phase 3: Codebase Exploration (conditional)
+   ├─ Detect project presence (package.json, Cargo.toml, etc.)
+   ├─ Explore architecture patterns and conventions
+   ├─ Map technology stack and dependencies
+   └─ Identify integration constraints
+
+Phase 4: Context Packaging
+   ├─ Generate spec-config.json (session state)
+   ├─ Generate discovery-context.json (research results)
+   └─ Validate output completeness
+
+Phase 5: Report to Coordinator
+   ├─ team_msg log + SendMessage research summary
+   ├─ TaskUpdate completed
+   └─ Check for next RESEARCH-* task
+```
+
+## Implementation
+
+### Phase 1: Task Discovery
+
+```javascript
+// Find assigned RESEARCH-* tasks
+const tasks = TaskList()
+const myTasks = tasks.filter(t =>
+  t.subject.startsWith('RESEARCH-') &&
+  t.owner === 'spec-analyst' &&
+  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: Seed Analysis
+
+```javascript
+// Extract session folder from task description
+const sessionMatch = task.description.match(/Session:\s*(.+)/)
+const sessionFolder = sessionMatch ? sessionMatch[1].trim() : '.workflow/.spec-team/default'
+
+// Parse topic from task description
+const topicLines = task.description.split('\n').filter(l => !l.startsWith('Session:') && !l.startsWith('输出:') && l.trim())
+const topic = topicLines[0] || task.subject.replace('RESEARCH-001: ', '')
+
+// Use Gemini CLI for seed analysis
+Bash({
+  command: `ccw cli -p "PURPOSE: Analyze the following topic/idea and extract structured seed information for specification generation.
+TASK:
+• Extract problem statement (what problem does this solve)
+• Identify target users and their pain points
+• Determine domain and industry context
+• List constraints and assumptions
+• Identify 3-5 exploration dimensions for deeper research
+• Assess complexity (simple/moderate/complex)
+
+TOPIC: ${topic}
+
+MODE: analysis
+CONTEXT: @**/*
+EXPECTED: JSON output with fields: problem_statement, target_users[], domain, constraints[], exploration_dimensions[], complexity_assessment
+CONSTRAINTS: Output as valid JSON" --tool gemini --mode analysis --rule analysis-analyze-technical-document`,
+  run_in_background: true
+})
+// Wait for CLI result
+
+// Parse Gemini analysis result
+const seedAnalysis = parseCLIResult(geminiOutput)
+```
+
+### Phase 3: Codebase Exploration (conditional)
+
+```javascript
+// Check if there's an existing codebase to explore
+const hasProject = Bash(`test -f package.json || test -f Cargo.toml || test -f pyproject.toml || test -f go.mod; echo $?`)
+
+if (hasProject === '0') {
+  // Progress update
+  mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "spec-analyst", to: "coordinator", type: "research_progress", summary: "种子分析完成, 开始代码库探索" })
+
+  // Explore codebase using ACE search
+  const archSearch = mcp__ace-tool__search_context({
+    project_root_path: projectRoot,
+    query: `Architecture patterns, main modules, entry points for: ${topic}`
+  })
+
+  // Detect tech stack
+  const techStack = {
+    languages: [],
+    frameworks: [],
+    databases: [],
+    infrastructure: []
+  }
+
+  // Scan package files for dependencies
+  const pkgJson = Read('package.json') // if exists
+  // Parse and categorize dependencies
+
+  // Explore existing patterns
+  const patterns = mcp__ace-tool__search_context({
+    project_root_path: projectRoot,
+    query: `Similar features, existing conventions, coding patterns related to: ${topic}`
+  })
+
+  // Integration constraints
+  const integrationPoints = mcp__ace-tool__search_context({
+    project_root_path: projectRoot,
+    query: `API endpoints, service boundaries, module interfaces that ${topic} would integrate with`
+  })
+
+  var codebaseContext = {
+    tech_stack: techStack,
+    architecture_patterns: archSearch,
+    existing_conventions: patterns,
+    integration_points: integrationPoints,
+    constraints_from_codebase: []
+  }
+} else {
+  var codebaseContext = null
+}
+```
+
+### Phase 4: Context Packaging
+
+```javascript
+// Generate spec-config.json
+const specConfig = {
+  session_id: `SPEC-${topicSlug}-${dateStr}`,
+  topic: topic,
+  status: "research_complete",
+  complexity: seedAnalysis.complexity_assessment || "moderate",
+  phases_completed: ["discovery"],
+  created_at: new Date().toISOString(),
+  session_folder: sessionFolder,
+  discussion_depth: task.description.match(/讨论深度:\s*(.+)/)?.[1] || "standard"
+}
+Write(`${sessionFolder}/spec-config.json`, JSON.stringify(specConfig, null, 2))
+
+// Generate discovery-context.json
+const discoveryContext = {
+  session_id: specConfig.session_id,
+  phase: 1,
+  document_type: "discovery-context",
+  status: "complete",
+  generated_at: new Date().toISOString(),
+  seed_analysis: {
+    problem_statement: seedAnalysis.problem_statement,
+    target_users: seedAnalysis.target_users,
+    domain: seedAnalysis.domain,
+    constraints: seedAnalysis.constraints,
+    exploration_dimensions: seedAnalysis.exploration_dimensions,
+    complexity: seedAnalysis.complexity_assessment
+  },
+  codebase_context: codebaseContext,
+  recommendations: {
+    focus_areas: seedAnalysis.exploration_dimensions?.slice(0, 3) || [],
+    risks: [],
+    open_questions: []
+  }
+}
+Write(`${sessionFolder}/discovery-context.json`, JSON.stringify(discoveryContext, null, 2))
+```
+
+### Phase 5: Report to Coordinator
+
+```javascript
+const dimensionCount = discoveryContext.seed_analysis.exploration_dimensions?.length || 0
+const hasCodebase = codebaseContext !== null
+
+// Log before SendMessage
+mcp__ccw-tools__team_msg({
+  operation: "log", team: teamName,
+  from: "spec-analyst", to: "coordinator",
+  type: "research_ready",
+  summary: `研究完成: ${dimensionCount}个探索维度, ${hasCodebase ? '有' : '无'}代码库上下文, 复杂度=${specConfig.complexity}`,
+  ref: `${sessionFolder}/discovery-context.json`
+})
+
+SendMessage({
+  type: "message",
+  recipient: "coordinator",
+  content: `## 研究分析结果
+
+**Task**: ${task.subject}
+**复杂度**: ${specConfig.complexity}
+**代码库**: ${hasCodebase ? '已检测到现有项目' : '全新项目（无现有代码）'}
+
+### 问题陈述
+${discoveryContext.seed_analysis.problem_statement}
+
+### 目标用户
+${(discoveryContext.seed_analysis.target_users || []).map(u => `- ${u}`).join('\n')}
+
+### 探索维度
+${(discoveryContext.seed_analysis.exploration_dimensions || []).map((d, i) => `${i+1}. ${d}`).join('\n')}
+
+### 约束条件
+${(discoveryContext.seed_analysis.constraints || []).map(c => `- ${c}`).join('\n')}
+
+${hasCodebase ? `### 代码库上下文
+- 技术栈: ${JSON.stringify(codebaseContext.tech_stack)}
+- 集成点: ${codebaseContext.integration_points?.length || 0}个` : ''}
+
+### 输出位置
+- Config: ${sessionFolder}/spec-config.json
+- Context: ${sessionFolder}/discovery-context.json
+
+研究已就绪，可进入讨论轮次 DISCUSS-001。`,
+  summary: `研究就绪: ${dimensionCount}维度, ${specConfig.complexity}`
+})
+
+// Mark task completed
+TaskUpdate({ taskId: task.id, status: 'completed' })
+
+// Check for next RESEARCH task
+const nextTasks = TaskList().filter(t =>
+  t.subject.startsWith('RESEARCH-') &&
+  t.owner === 'spec-analyst' &&
+  t.status === 'pending' &&
+  t.blockedBy.length === 0
+)
+
+if (nextTasks.length > 0) {
+  // Continue with next task -> back to Phase 1
+}
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| No RESEARCH-* tasks available | Idle, wait for coordinator assignment |
+| Gemini CLI analysis failure | Fallback to direct Claude analysis without CLI |
+| Codebase detection failed | Continue as new project (no codebase context) |
+| Session folder cannot be created | Notify coordinator, request alternative path |
+| Topic too vague for analysis | Report to coordinator with clarification questions |
+| Unexpected error | Log error via team_msg, report to coordinator |