claude-code-workflow 7.2.28 → 7.2.30

package/.claude/skills/ccw-chain/phases/spec-generator/phases/01-5-requirement-clarification.md

@@ -0,0 +1,404 @@
+# Phase 1.5: Requirement Expansion & Clarification
+
+在进入正式文档生成前，通过多轮交互讨论对原始需求进行深度挖掘、扩展和确认。
+
+## Objective
+
+- 识别原始需求中的模糊点、遗漏和潜在风险
+- 通过 CLI 辅助分析需求完整性，生成深度探测问题
+- 支持多轮交互讨论，逐步细化需求
+- 生成经用户确认的 `refined-requirements.json` 作为后续阶段的高质量输入
+
+## Input
+
+- Dependency: `{workDir}/spec-config.json` (Phase 1 output)
+- Optional: `{workDir}/discovery-context.json` (codebase context)
+
+## Execution Steps
+
+### Step 1: Load Phase 1 Context
+
+```javascript
+const specConfig = JSON.parse(Read(`${workDir}/spec-config.json`));
+const { seed_analysis, seed_input, focus_areas, has_codebase, depth } = specConfig;
+
+let discoveryContext = null;
+if (has_codebase) {
+  try {
+    discoveryContext = JSON.parse(Read(`${workDir}/discovery-context.json`));
+  } catch (e) { /* proceed without */ }
+}
+```
+
+### Step 2: CLI Gap Analysis & Question Generation
+
+调用 Gemini CLI 分析原始需求的完整性，识别模糊点并生成探测问题。
+
+```javascript
+Bash({
+  command: `ccw cli -p "PURPOSE: 深度分析用户的初始需求，识别模糊点、遗漏和需要澄清的领域。
+Success: 生成 3-5 个高质量的探测问题，覆盖功能范围、边界条件、非功能性需求、用户场景等维度。
+
+ORIGINAL SEED INPUT:
+${seed_input}
+
+SEED ANALYSIS:
+${JSON.stringify(seed_analysis, null, 2)}
+
+FOCUS AREAS: ${focus_areas.join(', ')}
+${discoveryContext ? `
+CODEBASE CONTEXT:
+- Existing patterns: ${discoveryContext.existing_patterns?.slice(0,5).join(', ') || 'none'}
+- Tech stack: ${JSON.stringify(discoveryContext.tech_stack || {})}
+` : ''}
+
+TASK:
+1. 评估当前需求描述的完整性（1-10 分，列出缺失维度）
+2. 识别 3-5 个关键模糊区域，每个区域包含：
+   - 模糊点描述（为什么不清楚）
+   - 1-2 个开放式探测问题
+   - 1-2 个扩展建议（基于领域最佳实践）
+3. 检查以下维度是否有遗漏：
+   - 功能范围边界（什么在范围内/外？）
+   - 核心用户场景和流程
+   - 非功能性需求（性能、安全、可用性、可扩展性）
+   - 集成点和外部依赖
+   - 数据模型和存储需求
+   - 错误处理和异常场景
+4. 基于领域经验提供需求扩展建议
+
+MODE: analysis
+EXPECTED: JSON output:
+{
+  \"completeness_score\": 7,
+  \"missing_dimensions\": [\"Performance requirements\", \"Error handling\"],
+  \"clarification_areas\": [
+    {
+      \"area\": \"Scope boundary\",
+      \"rationale\": \"Input does not clarify...\",
+      \"questions\": [\"Question 1?\", \"Question 2?\"],
+      \"suggestions\": [\"Suggestion 1\", \"Suggestion 2\"]
+    }
+  ],
+  \"expansion_recommendations\": [
+    {
+      \"category\": \"Non-functional\",
+      \"recommendation\": \"Consider adding...\",
+      \"priority\": \"high|medium|low\"
+    }
+  ]
+}
+CONSTRAINTS: 问题必须是开放式的，建议必须具体可执行，使用用户输入的语言
+" --tool gemini --mode analysis`,
+  run_in_background: true
+});
+// Wait for CLI result before continuing
+```
+
+解析 CLI 输出为结构化数据：
+```javascript
+const gapAnalysis = {
+  completeness_score: 0,
+  missing_dimensions: [],
+  clarification_areas: [],
+  expansion_recommendations: []
+};
+// Parse from CLI output
+```
+
+### Step 3: Interactive Discussion Loop
+
+核心多轮交互循环。每轮：展示分析结果 → 用户回应 → 更新需求状态 → 判断是否继续。
+
+```javascript
+// Initialize requirement state
+let requirementState = {
+  problem_statement: seed_analysis.problem_statement,
+  target_users: seed_analysis.target_users,
+  domain: seed_analysis.domain,
+  constraints: seed_analysis.constraints,
+  confirmed_features: [],
+  non_functional_requirements: [],
+  boundary_conditions: [],
+  integration_points: [],
+  key_assumptions: [],
+  discussion_rounds: 0
+};
+
+let discussionLog = [];
+let userSatisfied = false;
+
+// === Round 1: Present gap analysis results ===
+// Display completeness_score, clarification_areas, expansion_recommendations
+// Then ask user to respond
+
+while (!userSatisfied && requirementState.discussion_rounds < 5) {
+  requirementState.discussion_rounds++;
+
+  if (requirementState.discussion_rounds === 1) {
+    // --- First round: present initial gap analysis ---
+    // Format questions and suggestions from gapAnalysis for display
+    // Present as a structured summary to the user
+
+    AskUserQuestion({
+      questions: [
+        {
+          question: buildDiscussionPrompt(gapAnalysis, requirementState),
+          header: "Req Expand",
+          multiSelect: false,
+          options: [
+            { label: "I'll answer", description: "I have answers/feedback to provide (type in 'Other')" },
+            { label: "Accept all suggestions", description: "Accept all expansion recommendations as-is" },
+            { label: "Skip to generation", description: "Requirements are clear enough, proceed directly" }
+          ]
+        }
+      ]
+    });
+  } else {
+    // --- Subsequent rounds: refine based on user feedback ---
+    // Call CLI with accumulated context for follow-up analysis
+    Bash({
+      command: `ccw cli -p "PURPOSE: 基于用户最新回应，更新需求理解，识别剩余模糊点。
+
+CURRENT REQUIREMENT STATE:
+${JSON.stringify(requirementState, null, 2)}
+
+DISCUSSION HISTORY:
+${JSON.stringify(discussionLog, null, 2)}
+
+USER'S LATEST RESPONSE:
+${lastUserResponse}
+
+TASK:
+1. 将用户回应整合到需求状态中
+2. 识别 1-3 个仍需澄清或可扩展的领域
+3. 生成后续问题（如有必要）
+4. 如果需求已充分，输出最终需求摘要
+
+MODE: analysis
+EXPECTED: JSON output:
+{
+  \"updated_fields\": { /* fields to merge into requirementState */ },
+  \"status\": \"need_more_discussion\" | \"ready_for_confirmation\",
+  \"follow_up\": {
+    \"remaining_areas\": [{\"area\": \"...\", \"questions\": [\"...\"]}],
+    \"summary\": \"...\"
+  }
+}
+CONSTRAINTS: 避免重复已回答的问题，聚焦未覆盖的领域
+" --tool gemini --mode analysis`,
+      run_in_background: true
+    });
+    // Wait for CLI result, parse and continue
+
+    // If status === "ready_for_confirmation", break to confirmation step
+    // If status === "need_more_discussion", present follow-up questions
+
+    AskUserQuestion({
+      questions: [
+        {
+          question: buildFollowUpPrompt(followUpAnalysis, requirementState),
+          header: "Follow-up",
+          multiSelect: false,
+          options: [
+            { label: "I'll answer", description: "I have more feedback (type in 'Other')" },
+            { label: "Looks good", description: "Requirements are sufficiently clear now" },
+            { label: "Accept suggestions", description: "Accept remaining suggestions" }
+          ]
+        }
+      ]
+    });
+  }
+
+  // Process user response
+  // - "Skip to generation" / "Looks good" → userSatisfied = true
+  // - "Accept all suggestions" → merge suggestions into requirementState, userSatisfied = true
+  // - "I'll answer" (with Other text) → record in discussionLog, continue loop
+  // - User selects Other with custom text → parse and record
+
+  discussionLog.push({
+    round: requirementState.discussion_rounds,
+    agent_prompt: currentPrompt,
+    user_response: userResponse,
+    timestamp: new Date().toISOString()
+  });
+}
+```
+
+#### Helper: Build Discussion Prompt
+
+```javascript
+function buildDiscussionPrompt(gapAnalysis, state) {
+  let prompt = `## Requirement Analysis Results\n\n`;
+  prompt += `**Completeness Score**: ${gapAnalysis.completeness_score}/10\n`;
+
+  if (gapAnalysis.missing_dimensions.length > 0) {
+    prompt += `**Missing Dimensions**: ${gapAnalysis.missing_dimensions.join(', ')}\n\n`;
+  }
+
+  prompt += `### Key Questions\n\n`;
+  gapAnalysis.clarification_areas.forEach((area, i) => {
+    prompt += `**${i+1}. ${area.area}**\n`;
+    prompt += `  ${area.rationale}\n`;
+    area.questions.forEach(q => { prompt += `  - ${q}\n`; });
+    if (area.suggestions.length > 0) {
+      prompt += `  Suggestions: ${area.suggestions.join('; ')}\n`;
+    }
+    prompt += `\n`;
+  });
+
+  if (gapAnalysis.expansion_recommendations.length > 0) {
+    prompt += `### Expansion Recommendations\n\n`;
+    gapAnalysis.expansion_recommendations.forEach(rec => {
+      prompt += `- [${rec.priority}] **${rec.category}**: ${rec.recommendation}\n`;
+    });
+  }
+
+  prompt += `\nPlease answer the questions above, or choose an option below.`;
+  return prompt;
+}
+```
+
+### Step 4: Auto Mode Handling
+
+```javascript
+if (autoMode) {
+  // Skip interactive discussion
+  // CLI generates default requirement expansion based on seed_analysis
+  Bash({
+    command: `ccw cli -p "PURPOSE: 基于种子分析自动生成需求扩展，无需用户交互。
+
+SEED ANALYSIS:
+${JSON.stringify(seed_analysis, null, 2)}
+
+SEED INPUT: ${seed_input}
+DEPTH: ${depth}
+${discoveryContext ? `CODEBASE: ${JSON.stringify(discoveryContext.tech_stack || {})}` : ''}
+
+TASK:
+1. 基于领域最佳实践，自动扩展功能需求清单
+2. 推断合理的非功能性需求
+3. 识别明显的边界条件
+4. 列出关键假设
+
+MODE: analysis
+EXPECTED: JSON output matching refined-requirements.json schema
+CONSTRAINTS: 保守推断，只添加高置信度的扩展
+" --tool gemini --mode analysis`,
+    run_in_background: true
+  });
+  // Parse output directly into refined-requirements.json
+}
+```
+
+### Step 5: Generate Requirement Confirmation Summary
+
+在写入文件前，向用户展示最终的需求确认摘要（非 auto mode）。
+
+```javascript
+if (!autoMode) {
+  // Build confirmation summary from requirementState
+  const summary = buildConfirmationSummary(requirementState);
+
+  AskUserQuestion({
+    questions: [
+      {
+        question: `## Requirement Confirmation\n\n${summary}\n\nConfirm and proceed to specification generation?`,
+        header: "Confirm",
+        multiSelect: false,
+        options: [
+          { label: "Confirm & proceed", description: "Requirements confirmed, start spec generation" },
+          { label: "Need adjustments", description: "Go back and refine further" }
+        ]
+      }
+    ]
+  });
+
+  // If "Need adjustments" → loop back to Step 3
+  // If "Confirm & proceed" → continue to Step 6
+}
+```
+
+### Step 6: Write refined-requirements.json
+
+```javascript
+const refinedRequirements = {
+  session_id: specConfig.session_id,
+  phase: "1.5",
+  generated_at: new Date().toISOString(),
+  source: autoMode ? "auto-expansion" : "interactive-discussion",
+  discussion_rounds: requirementState.discussion_rounds,
+
+  // Core requirement content
+  clarified_problem_statement: requirementState.problem_statement,
+  confirmed_target_users: requirementState.target_users.map(u =>
+    typeof u === 'string' ? { name: u, needs: [], pain_points: [] } : u
+  ),
+  confirmed_domain: requirementState.domain,
+
+  confirmed_features: requirementState.confirmed_features.map(f => ({
+    name: f.name,
+    description: f.description,
+    acceptance_criteria: f.acceptance_criteria || [],
+    edge_cases: f.edge_cases || [],
+    priority: f.priority || "unset"
+  })),
+
+  non_functional_requirements: requirementState.non_functional_requirements.map(nfr => ({
+    type: nfr.type,    // Performance, Security, Usability, Scalability, etc.
+    details: nfr.details,
+    measurable_criteria: nfr.measurable_criteria || ""
+  })),
+
+  boundary_conditions: {
+    in_scope: requirementState.boundary_conditions.filter(b => b.scope === 'in'),
+    out_of_scope: requirementState.boundary_conditions.filter(b => b.scope === 'out'),
+    constraints: requirementState.constraints
+  },
+
+  integration_points: requirementState.integration_points,
+  key_assumptions: requirementState.key_assumptions,
+
+  // Traceability
+  discussion_log: autoMode ? [] : discussionLog
+};
+
+Write(`${workDir}/refined-requirements.json`, JSON.stringify(refinedRequirements, null, 2));
+```
+
+### Step 7: Update spec-config.json
+
+```javascript
+specConfig.refined_requirements_file = "refined-requirements.json";
+specConfig.phasesCompleted.push({
+  phase: 1.5,
+  name: "requirement-clarification",
+  output_file: "refined-requirements.json",
+  discussion_rounds: requirementState.discussion_rounds,
+  completed_at: new Date().toISOString()
+});
+
+Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));
+```
+
+## Output
+
+- **File**: `refined-requirements.json`
+- **Format**: JSON
+- **Updated**: `spec-config.json` (added `refined_requirements_file` field and phase 1.5 to `phasesCompleted`)
+
+## Quality Checklist
+
+- [ ] Problem statement refined (>= 30 characters, more specific than seed)
+- [ ] At least 2 confirmed features with descriptions
+- [ ] At least 1 non-functional requirement identified
+- [ ] Boundary conditions defined (in-scope + out-of-scope)
+- [ ] Key assumptions listed (>= 1)
+- [ ] Discussion rounds recorded (>= 1 in interactive mode)
+- [ ] User explicitly confirmed requirements (non-auto mode)
+- [ ] `refined-requirements.json` written with valid JSON
+- [ ] `spec-config.json` updated with phase 1.5 completion
+
+## Next Phase
+
+Proceed to [Phase 2: Product Brief](02-product-brief.md). Phase 2 should load `refined-requirements.json` as primary input instead of relying solely on `spec-config.json.seed_analysis`.

package/.claude/skills/ccw-chain/phases/spec-generator/phases/01-discovery.md

@@ -0,0 +1,257 @@
+# Phase 1: Discovery
+
+Parse input, analyze the seed idea, optionally explore codebase, establish session configuration.
+
+## Objective
+
+- Generate session ID and create output directory
+- Parse user input (text description or file reference)
+- Analyze seed via Gemini CLI to extract problem space dimensions
+- Conditionally explore codebase for existing patterns and constraints
+- Gather user preferences (depth, focus areas) via interactive confirmation
+- Write `spec-config.json` as the session state file
+
+## Input
+
+- Dependency: `$ARGUMENTS` (user input from command)
+- Flags: `-y` (auto mode), `-c` (continue mode)
+
+## Execution Steps
+
+### Step 1: Session Initialization
+
+```javascript
+// Parse arguments
+const args = $ARGUMENTS;
+const autoMode = args.includes('-y') || args.includes('--yes');
+const continueMode = args.includes('-c') || args.includes('--continue');
+
+// Extract the idea/topic (remove flags)
+const idea = args.replace(/(-y|--yes|-c|--continue)\s*/g, '').trim();
+
+// Generate session ID
+const slug = idea.toLowerCase()
+  .replace(/[^a-z0-9\u4e00-\u9fff]+/g, '-')
+  .replace(/^-|-$/g, '')
+  .slice(0, 40);
+const date = new Date().toISOString().slice(0, 10);
+const sessionId = `SPEC-${slug}-${date}`;
+const workDir = `.workflow/.spec/${sessionId}`;
+
+// Check for continue mode
+if (continueMode) {
+  // Find existing session
+  const existingSessions = Glob('.workflow/.spec/SPEC-*/spec-config.json');
+  // If slug matches an existing session, load it and resume
+  // Read spec-config.json, find first incomplete phase, jump to that phase
+  return; // Resume logic handled by orchestrator
+}
+
+// Create output directory
+Bash(`mkdir -p "${workDir}"`);
+```
+
+### Step 2: Input Parsing
+
+```javascript
+// Determine input type
+if (idea.startsWith('@') || idea.endsWith('.md') || idea.endsWith('.txt')) {
+  // File reference - read and extract content
+  const filePath = idea.replace(/^@/, '');
+  const fileContent = Read(filePath);
+  // Use file content as the seed
+  inputType = 'file';
+  seedInput = fileContent;
+} else {
+  // Direct text description
+  inputType = 'text';
+  seedInput = idea;
+}
+```
+
+### Step 3: Seed Analysis via Gemini CLI
+
+```javascript
+Bash({
+  command: `ccw cli -p "PURPOSE: Analyze this seed idea/requirement to extract structured problem space dimensions.
+Success: Clear problem statement, target users, domain identification, 3-5 exploration dimensions.
+
+SEED INPUT:
+${seedInput}
+
+TASK:
+- Extract a clear problem statement (what problem does this solve?)
+- Identify target users (who benefits?)
+- Determine the domain (technical, business, consumer, etc.)
+- List constraints (budget, time, technical, regulatory)
+- Generate 3-5 exploration dimensions (key areas to investigate)
+- Assess complexity: simple (1-2 components), moderate (3-5 components), complex (6+ components)
+
+MODE: analysis
+EXPECTED: JSON output with fields: problem_statement, target_users[], domain, constraints[], dimensions[], complexity
+CONSTRAINTS: Be specific and actionable, not vague
+" --tool gemini --mode analysis`,
+  run_in_background: true
+});
+// Wait for CLI result before continuing
+```
+
+Parse the CLI output into structured `seedAnalysis`:
+```javascript
+const seedAnalysis = {
+  problem_statement: "...",
+  target_users: ["..."],
+  domain: "...",
+  constraints: ["..."],
+  dimensions: ["..."]
+};
+const complexity = "moderate"; // from CLI output
+```
+
+### Step 4: Codebase Exploration (Conditional)
+
+```javascript
+// Detect if running inside a project with code
+const hasCodebase = Glob('**/*.{ts,js,py,java,go,rs}').length > 0
+  || Glob('package.json').length > 0
+  || Glob('Cargo.toml').length > 0;
+
+if (hasCodebase) {
+  Agent({
+    subagent_type: "cli-explore-agent",
+    run_in_background: false,
+    description: `Explore codebase for spec: ${slug}`,
+    prompt: `
+## Spec Generator Context
+Topic: ${seedInput}
+Dimensions: ${seedAnalysis.dimensions.join(', ')}
+Session: ${workDir}
+
+## MANDATORY FIRST STEPS
+1. Search for code related to topic keywords
+2. Read project config files (package.json, pyproject.toml, etc.) if they exist
+
+## Exploration Focus
+- Identify existing implementations related to the topic
+- Find patterns that could inform architecture decisions
+- Map current architecture constraints
+- Locate integration points and dependencies
+
+## Output
+Write findings to: ${workDir}/discovery-context.json
+
+Schema:
+{
+  "relevant_files": [{"path": "...", "relevance": "high|medium|low", "rationale": "..."}],
+  "existing_patterns": ["pattern descriptions"],
+  "architecture_constraints": ["constraint descriptions"],
+  "integration_points": ["integration point descriptions"],
+  "tech_stack": {"languages": [], "frameworks": [], "databases": []},
+  "_metadata": { "exploration_type": "spec-discovery", "timestamp": "ISO8601" }
+}
+`
+  });
+}
+```
+
+### Step 5: User Confirmation (Interactive)
+
+```javascript
+if (!autoMode) {
+  // Confirm problem statement and select depth
+  AskUserQuestion({
+    questions: [
+      {
+        question: `Problem statement: "${seedAnalysis.problem_statement}" - Is this accurate?`,
+        header: "Problem",
+        multiSelect: false,
+        options: [
+          { label: "Accurate", description: "Proceed with this problem statement" },
+          { label: "Needs adjustment", description: "I'll refine the problem statement" }
+        ]
+      },
+      {
+        question: "What specification depth do you need?",
+        header: "Depth",
+        multiSelect: false,
+        options: [
+          { label: "Light", description: "Quick overview - key decisions only" },
+          { label: "Standard (Recommended)", description: "Balanced detail for most projects" },
+          { label: "Comprehensive", description: "Maximum detail for complex/critical projects" }
+        ]
+      },
+      {
+        question: "Which areas should we focus on?",
+        header: "Focus",
+        multiSelect: true,
+        options: seedAnalysis.dimensions.map(d => ({ label: d, description: `Explore ${d} in depth` }))
+      },
+      {
+        question: "What type of specification is this?",
+        header: "Spec Type",
+        multiSelect: false,
+        options: [
+          { label: "Service (Recommended)", description: "Long-running service with lifecycle, state machine, observability" },
+          { label: "API", description: "REST/GraphQL API with endpoints, auth, rate limiting" },
+          { label: "Library/SDK", description: "Reusable package with public API surface, examples" },
+          { label: "Platform", description: "Multi-component system, uses Service profile" }
+        ]
+      }
+    ]
+  });
+} else {
+  // Auto mode defaults
+  depth = "standard";
+  focusAreas = seedAnalysis.dimensions;
+  specType = "service"; // default for auto mode
+}
+```
+
+### Step 6: Write spec-config.json
+
+```javascript
+const specConfig = {
+  session_id: sessionId,
+  seed_input: seedInput,
+  input_type: inputType,
+  timestamp: new Date().toISOString(),
+  mode: autoMode ? "auto" : "interactive",
+  complexity: complexity,
+  depth: depth,
+  focus_areas: focusAreas,
+  seed_analysis: seedAnalysis,
+  has_codebase: hasCodebase,
+  spec_type: specType, // "service" | "api" | "library" | "platform"
+  iteration_count: 0,
+  iteration_history: [],
+  phasesCompleted: [
+    {
+      phase: 1,
+      name: "discovery",
+      output_file: "spec-config.json",
+      completed_at: new Date().toISOString()
+    }
+  ]
+};
+
+Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));
+```
+
+## Output
+
+- **File**: `spec-config.json`
+- **File**: `discovery-context.json` (optional, if codebase detected)
+- **Format**: JSON
+
+## Quality Checklist
+
+- [ ] Session ID matches `SPEC-{slug}-{date}` format
+- [ ] Problem statement exists and is >= 20 characters
+- [ ] Target users identified (>= 1)
+- [ ] 3-5 exploration dimensions generated
+- [ ] spec-config.json written with all required fields
+- [ ] Output directory created
+
+## Next Phase
+
+Proceed to [Phase 2: Product Brief](02-product-brief.md) with the generated spec-config.json.