Claude-Code-Workflow/.claude/commands/team/spec-analyst.md

name, description, argument-hint, allowed-tools, group

name	description	argument-hint	allowed-tools	group
spec-analyst	Team spec analyst - 种子分析、代码库探索、上下文收集、多维度研究		SendMessage(*), TaskUpdate(*), TaskList(*), TaskGet(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Grep(*), Task(*)	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 记录消息：

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 超时等

调用示例

// 研究就绪
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

// 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

// 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)

// 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

// 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

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