From c43a72ef46adc10e7f10beca5923c5e1fcee7f64 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Wed, 3 Dec 2025 22:45:04 +0800 Subject: [PATCH] release: v5.9.8 - Brainstorm workflow improvements and documentation updates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Changes - Simplify analysis output strategy to optional modular structure - Update synthesis/artifacts documentation to use AskUserQuestion tool - Add modular output strategy for brainstorm analysis - Simplify clarification deduplication in lite-plan - Add "Fix, Don't Hide" section to CLAUDE.md guidelines - Simplify project.json schema by removing unused fields - Update session ID format in lite-fix/lite-plan workflows - Add development index to project JSON schema 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .claude/agents/conceptual-planning-agent.md | 54 +- .claude/agents/context-search-agent.md | 7 +- .../commands/workflow/brainstorm/artifacts.md | 770 +++++++----------- .../workflow/brainstorm/auto-parallel.md | 51 +- .../commands/workflow/brainstorm/synthesis.md | 586 ++++++------- .claude/commands/workflow/init.md | 34 +- .claude/commands/workflow/lite-execute.md | 52 ++ .claude/commands/workflow/lite-fix.md | 8 +- .claude/commands/workflow/lite-plan.md | 51 +- .claude/commands/workflow/status.md | 5 - .../commands/workflow/tools/context-gather.md | 4 +- .../workflow/tools/task-generate-agent.md | 2 +- .../workflow/tools/task-generate-tdd.md | 8 +- .../workflow/tools/test-task-generate.md | 2 +- .../reference/commands/workflow/init.md | 32 +- .../reference/commands/workflow/status.md | 5 - .../schemas/project-json-schema.json | 152 +--- CLAUDE.md | 17 +- 18 files changed, 713 insertions(+), 1127 deletions(-) diff --git a/.claude/agents/conceptual-planning-agent.md b/.claude/agents/conceptual-planning-agent.md index cf67e937..a49debd9 100644 --- a/.claude/agents/conceptual-planning-agent.md +++ b/.claude/agents/conceptual-planning-agent.md @@ -119,17 +119,6 @@ This agent processes **simplified inline [FLOW_CONTROL]** format from brainstorm - No dependency management - Used for temporary context preparation -### NOT Handled by This Agent - -**JSON format** (used by code-developer, test-fix-agent): -```json -"flow_control": { - "pre_analysis": [...], - "implementation_approach": [...] -} -``` - -This complete JSON format is stored in `.task/IMPL-*.json` files and handled by implementation agents, not conceptual-planning-agent. ### Role-Specific Analysis Dimensions @@ -146,14 +135,14 @@ This complete JSON format is stored in `.task/IMPL-*.json` files and handled by ### Output Integration -**Gemini Analysis Integration**: Pattern-based analysis results are integrated into the single role's output: -- Enhanced `analysis.md` with codebase insights and architectural patterns +**Gemini Analysis Integration**: Pattern-based analysis results are integrated into role output documents: +- Enhanced analysis documents with codebase insights and architectural patterns - Role-specific technical recommendations based on existing conventions - Pattern-based best practices from actual code examination - Realistic feasibility assessments based on current implementation **Codex Analysis Integration**: Autonomous analysis results provide comprehensive insights: -- Enhanced `analysis.md` with autonomous development recommendations +- Enhanced analysis documents with autonomous development recommendations - Role-specific strategy based on intelligent system understanding - Autonomous development approaches and implementation guidance - Self-guided optimization and integration recommendations @@ -229,26 +218,23 @@ Generate documents according to loaded role template specifications: **Output Location**: `.workflow/WFS-[session]/.brainstorming/[assigned-role]/` -**Required Files**: -- **analysis.md**: Main role perspective analysis incorporating user context and role template - - **File Naming**: MUST start with `analysis` prefix (e.g., `analysis.md`, `analysis-1.md`, `analysis-2.md`) +**Output Files**: +- **analysis.md**: Index document with overview (optionally with `@` references to sub-documents) - **FORBIDDEN**: Never create `recommendations.md` or any file not starting with `analysis` prefix - - **Auto-split if large**: If content >800 lines, split to `analysis-1.md`, `analysis-2.md` (max 3 files: analysis.md, analysis-1.md, analysis-2.md) - - **Content**: Includes both analysis AND recommendations sections within analysis files -- **[role-deliverables]/**: Directory for specialized role outputs as defined in planning role template (optional) +- **analysis-{slug}.md**: Section content documents (slug from section heading: lowercase, hyphens) + - Maximum 5 sub-documents (merge related sections if needed) +- **Content**: Analysis AND recommendations sections **File Structure Example**: ``` .workflow/WFS-[session]/.brainstorming/system-architect/ -├── analysis.md # Main system architecture analysis with recommendations -├── analysis-1.md # (Optional) Continuation if content >800 lines -└── deliverables/ # (Optional) Additional role-specific outputs - ├── technical-architecture.md # System design specifications - ├── technology-stack.md # Technology selection rationale - └── scalability-plan.md # Scaling strategy +├── analysis.md # Index with overview + @references +├── analysis-architecture-assessment.md # Section content +├── analysis-technology-evaluation.md # Section content +├── analysis-integration-strategy.md # Section content +└── analysis-recommendations.md # Section content (max 5 sub-docs total) -NOTE: ALL brainstorming output files MUST start with 'analysis' prefix -FORBIDDEN: recommendations.md, recommendations-*.md, or any non-'analysis' prefixed files +NOTE: ALL files MUST start with 'analysis' prefix. Max 5 sub-documents. ``` ## Role-Specific Planning Process @@ -268,14 +254,10 @@ FORBIDDEN: recommendations.md, recommendations-*.md, or any non-'analysis' prefi - **Validate Against Template**: Ensure analysis meets role template requirements and standards ### 3. Brainstorming Documentation Phase -- **Create analysis.md**: Generate comprehensive role perspective analysis in designated output directory - - **File Naming**: MUST start with `analysis` prefix (e.g., `analysis.md`, `analysis-1.md`, `analysis-2.md`) - - **FORBIDDEN**: Never create `recommendations.md` or any file not starting with `analysis` prefix - - **Content**: Include both analysis AND recommendations sections within analysis files - - **Auto-split**: If content >800 lines, split to `analysis-1.md`, `analysis-2.md` (max 3 files total) -- **Generate Role Deliverables**: Create specialized outputs as defined in planning role template (optional) +- **Create analysis.md**: Main document with overview (optionally with `@` references) +- **Create sub-documents**: `analysis-{slug}.md` for major sections (max 5) - **Validate Output Structure**: Ensure all files saved to correct `.brainstorming/[role]/` directory -- **Naming Validation**: Verify NO files with `recommendations` prefix exist +- **Naming Validation**: Verify ALL files start with `analysis` prefix - **Quality Review**: Ensure outputs meet role template standards and user requirements ## Role-Specific Analysis Framework @@ -324,5 +306,3 @@ When analysis is complete, ensure: - **Relevance**: Directly addresses user's specified requirements - **Actionability**: Provides concrete next steps and recommendations -### Windows Path Format Guidelines -- **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users` diff --git a/.claude/agents/context-search-agent.md b/.claude/agents/context-search-agent.md index 9f050aa3..4ee0b624 100644 --- a/.claude/agents/context-search-agent.md +++ b/.claude/agents/context-search-agent.md @@ -449,7 +449,12 @@ Calculate risk level based on: { "path": "system-architect/analysis.md", "type": "primary", - "content": "# System Architecture Analysis\n\n## Overview\n..." + "content": "# System Architecture Analysis\n\n## Overview\n@analysis-architecture.md\n@analysis-recommendations.md" + }, + { + "path": "system-architect/analysis-architecture.md", + "type": "supplementary", + "content": "# Architecture Assessment\n\n..." } ] } diff --git a/.claude/commands/workflow/brainstorm/artifacts.md b/.claude/commands/workflow/brainstorm/artifacts.md index 102a849c..b95249e8 100644 --- a/.claude/commands/workflow/brainstorm/artifacts.md +++ b/.claude/commands/workflow/brainstorm/artifacts.md @@ -2,452 +2,359 @@ name: artifacts description: Interactive clarification generating confirmed guidance specification through role-based analysis and synthesis argument-hint: "topic or challenge description [--count N]" -allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*) +allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), AskUserQuestion(*) --- ## Overview -Six-phase workflow: **Automatic project context collection** → Extract topic challenges → Select roles → Generate task-specific questions → Detect conflicts → Generate confirmed guidance (declarative statements only). +Seven-phase workflow: **Context collection** → **Topic analysis** → **Role selection** → **Role questions** → **Conflict resolution** → **Final check** → **Generate specification** + +All user interactions use AskUserQuestion tool (max 4 questions per call, multi-round). **Input**: `"GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]` -**Output**: `.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md` (CONFIRMED/SELECTED format) -**Core Principle**: Questions dynamically generated from project context + topic keywords/challenges, NOT from generic templates +**Output**: `.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md` +**Core Principle**: Questions dynamically generated from project context + topic keywords, NOT generic templates **Parameters**: - `topic` (required): Topic or challenge description (structured format recommended) -- `--count N` (optional): Number of roles user WANTS to select (system will recommend N+2 options for user to choose from, default: 3) +- `--count N` (optional): Number of roles to select (system recommends N+2 options, default: 3) + +--- + +## Quick Reference + +### Phase Summary + +| Phase | Goal | AskUserQuestion | Storage | +|-------|------|-----------------|---------| +| 0 | Context collection | - | context-package.json | +| 1 | Topic analysis | 2-4 questions | intent_context | +| 2 | Role selection | 1 multi-select | selected_roles | +| 3 | Role questions | 3-4 per role | role_decisions[role] | +| 4 | Conflict resolution | max 4 per round | cross_role_decisions | +| 4.5 | Final check | progressive rounds | additional_decisions | +| 5 | Generate spec | - | guidance-specification.md | + +### AskUserQuestion Pattern + +```javascript +// Single-select (Phase 1, 3, 4) +AskUserQuestion({ + questions: [ + { + question: "{问题文本}", + header: "{短标签}", // max 12 chars + multiSelect: false, + options: [ + { label: "{选项}", description: "{说明和影响}" }, + { label: "{选项}", description: "{说明和影响}" }, + { label: "{选项}", description: "{说明和影响}" } + ] + } + // ... max 4 questions per call + ] +}) + +// Multi-select (Phase 2) +AskUserQuestion({ + questions: [{ + question: "请选择 {count} 个角色", + header: "角色选择", + multiSelect: true, + options: [/* max 4 options per call */] + }] +}) +``` + +### Multi-Round Execution + +```javascript +const BATCH_SIZE = 4; +for (let i = 0; i < allQuestions.length; i += BATCH_SIZE) { + const batch = allQuestions.slice(i, i + BATCH_SIZE); + AskUserQuestion({ questions: batch }); + // Store responses before next round +} +``` + +--- ## Task Tracking -**⚠️ TodoWrite Rule**: EXTEND auto-parallel's task list (NOT replace/overwrite) +**TodoWrite Rule**: EXTEND auto-parallel's task list (NOT replace/overwrite) **When called from auto-parallel**: -- Find the artifacts parent task: "Execute artifacts command for interactive framework generation" -- Mark parent task as "in_progress" -- APPEND artifacts sub-tasks AFTER the parent task (Phase 0-5) -- Mark each sub-task as it completes -- When Phase 5 completes, mark parent task as "completed" -- **PRESERVE all other auto-parallel tasks** (role agents, synthesis) +- Find artifacts parent task → Mark "in_progress" +- APPEND sub-tasks (Phase 0-5) → Mark each as completes +- When Phase 5 completes → Mark parent "completed" +- PRESERVE all other auto-parallel tasks **Standalone Mode**: ```json [ - {"content": "Initialize session (.workflow/active/ session check, parse --count parameter)", "status": "pending", "activeForm": "Initializing"}, - {"content": "Phase 0: Automatic project context collection (call context-gather)", "status": "pending", "activeForm": "Phase 0 context collection"}, - {"content": "Phase 1: Extract challenges, output 2-4 task-specific questions, wait for user input", "status": "pending", "activeForm": "Phase 1 topic analysis"}, - {"content": "Phase 2: Recommend count+2 roles, output role selection, wait for user input", "status": "pending", "activeForm": "Phase 2 role selection"}, - {"content": "Phase 3: Generate 3-4 questions per role, output and wait for answers (max 10 per round)", "status": "pending", "activeForm": "Phase 3 role questions"}, - {"content": "Phase 4: Detect conflicts, output clarifications, wait for answers (max 10 per round)", "status": "pending", "activeForm": "Phase 4 conflict resolution"}, - {"content": "Phase 5: Transform Q&A to declarative statements, write guidance-specification.md", "status": "pending", "activeForm": "Phase 5 document generation"} + {"content": "Initialize session", "status": "pending", "activeForm": "Initializing"}, + {"content": "Phase 0: Context collection", "status": "pending", "activeForm": "Phase 0"}, + {"content": "Phase 1: Topic analysis (2-4 questions)", "status": "pending", "activeForm": "Phase 1"}, + {"content": "Phase 2: Role selection", "status": "pending", "activeForm": "Phase 2"}, + {"content": "Phase 3: Role questions (per role)", "status": "pending", "activeForm": "Phase 3"}, + {"content": "Phase 4: Conflict resolution", "status": "pending", "activeForm": "Phase 4"}, + {"content": "Phase 4.5: Final clarification", "status": "pending", "activeForm": "Phase 4.5"}, + {"content": "Phase 5: Generate specification", "status": "pending", "activeForm": "Phase 5"} ] ``` -## User Interaction Protocol - -### Question Output Format - -All questions output as structured text (detailed format with descriptions): - -```markdown -【问题{N} - {短标签}】{问题文本} -a) {选项标签} - 说明：{选项说明和影响} -b) {选项标签} - 说明：{选项说明和影响} -c) {选项标签} - 说明：{选项说明和影响} - -请回答：{N}a 或 {N}b 或 {N}c -``` - -**Multi-select format** (Phase 2 role selection): -```markdown -【角色选择】请选择 {count} 个角色参与头脑风暴分析 - -a) {role-name} ({中文名}) - 推荐理由：{基于topic的相关性说明} -b) {role-name} ({中文名}) - 推荐理由：{基于topic的相关性说明} -... - -支持格式： -- 分别选择：2a 2c 2d (选择第2题的a、c、d选项) -- 合并语法：2acd (选择a、c、d) -- 逗号分隔：2a,c,d - -请输入选择： -``` - -### Input Parsing Rules - -**Supported formats** (intelligent parsing): - -1. **Space-separated**: `1a 2b 3c` → Q1:a, Q2:b, Q3:c -2. **Comma-separated**: `1a,2b,3c` → Q1:a, Q2:b, Q3:c -3. **Multi-select combined**: `2abc` → Q2: options a,b,c -4. **Multi-select spaces**: `2 a b c` → Q2: options a,b,c -5. **Multi-select comma**: `2a,b,c` → Q2: options a,b,c -6. **Natural language**: `问题1选a` → 1a (fallback parsing) - -**Parsing algorithm**: -- Extract question numbers and option letters -- Validate question numbers match output -- Validate option letters exist for each question -- If ambiguous/invalid, output example format and request re-input - -**Error handling** (lenient): -- Recognize common variations automatically -- If parsing fails, show example and wait for clarification -- Support re-input without penalty - -### Batching Strategy - -**Batch limits**: -- **Default**: Maximum 10 questions per round -- **Phase 2 (role selection)**: Display all recommended roles at once (count+2 roles) -- **Auto-split**: If questions > 10, split into multiple rounds with clear round indicators - -**Round indicators**: -```markdown -===== 第 1 轮问题 (共2轮) ===== -【问题1 - ...】... -【问题2 - ...】... -... -【问题10 - ...】... - -请回答 (格式: 1a 2b ... 10c)： -``` - -### Interaction Flow - -**Standard flow**: -1. Output questions in formatted text -2. Output expected input format example -3. Wait for user input -4. Parse input with intelligent matching -5. If parsing succeeds → Store answers and continue -6. If parsing fails → Show error, example, and wait for re-input - -**No question/option limits**: Text-based interaction removes previous 4-question and 4-option restrictions +--- ## Execution Phases ### Session Management + - Check `.workflow/active/` for existing sessions -- Multiple sessions → Prompt selection | Single → Use it | None → Create `WFS-[topic-slug]` -- Parse `--count N` parameter from user input (default: 3 if not specified) -- Store decisions in `workflow-session.json` including count parameter +- Multiple → Prompt selection | Single → Use it | None → Create `WFS-[topic-slug]` +- Parse `--count N` parameter (default: 3) +- Store decisions in `workflow-session.json` -### Phase 0: Automatic Project Context Collection +### Phase 0: Context Collection -**Goal**: Gather project architecture, documentation, and relevant code context BEFORE user interaction +**Goal**: Gather project context BEFORE user interaction -**Detection Mechanism** (execute first): -```javascript -// Check if context-package already exists -const contextPackagePath = `.workflow/active/WFS-{session-id}/.process/context-package.json`; +**Steps**: +1. Check if `context-package.json` exists → Skip if valid +2. Invoke `context-search-agent` (BRAINSTORM MODE - lightweight) +3. Output: `.workflow/active/WFS-{session-id}/.process/context-package.json` -if (file_exists(contextPackagePath)) { - // Validate package - const package = Read(contextPackagePath); - if (package.metadata.session_id === session_id) { - console.log("✅ Valid context-package found, skipping Phase 0"); - return; // Skip to Phase 1 - } -} -``` - -**Implementation**: Invoke `context-search-agent` only if package doesn't exist +**Graceful Degradation**: If agent fails, continue to Phase 1 without context ```javascript Task( subagent_type="context-search-agent", description="Gather project context for brainstorm", prompt=` -You are executing as context-search-agent (.claude/agents/context-search-agent.md). +Execute context-search-agent in BRAINSTORM MODE (Phase 1-2 only). -## Execution Mode -**BRAINSTORM MODE** (Lightweight) - Phase 1-2 only (skip deep analysis) +Session: ${session_id} +Task: ${task_description} +Output: .workflow/${session_id}/.process/context-package.json -## Session Information -- **Session ID**: ${session_id} -- **Task Description**: ${task_description} -- **Output Path**: .workflow/${session_id}/.process/context-package.json - -## Mission -Execute complete context-search-agent workflow for implementation planning: - -### Phase 1: Initialization & Pre-Analysis -1. **Detection**: Check for existing context-package (early exit if valid) -2. **Foundation**: Initialize code-index, get project structure, load docs -3. **Analysis**: Extract keywords, determine scope, classify complexity - -### Phase 2: Multi-Source Context Discovery -Execute all 3 discovery tracks: -- **Track 1**: Reference documentation (CLAUDE.md, architecture docs) -- **Track 2**: Web examples (use Exa MCP for unfamiliar tech/APIs) -- **Track 3**: Codebase analysis (5-layer discovery: files, content, patterns, deps, config/tests) - -### Phase 3: Synthesis, Assessment & Packaging -1. Apply relevance scoring and build dependency graph -2. Synthesize 3-source data (docs > code > web) -3. Integrate brainstorm artifacts (if .brainstorming/ exists, read content) -4. Perform conflict detection with risk assessment -5. Generate and validate context-package.json - -## Output Requirements -Complete context-package.json with: -- **metadata**: task_description, keywords, complexity, tech_stack, session_id -- **project_context**: architecture_patterns, coding_conventions, tech_stack -- **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores -- **dependencies**: {internal[], external[]} with dependency graph -- **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content -- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy} - -## Quality Validation -Before completion verify: -- [ ] Valid JSON format with all required fields -- [ ] File relevance accuracy >80% -- [ ] Dependency graph complete (max 2 transitive levels) -- [ ] Conflict risk level calculated correctly -- [ ] No sensitive data exposed -- [ ] Total files ≤50 (prioritize high-relevance) - -Execute autonomously following agent documentation. -Report completion with statistics. +Required fields: metadata, project_context, assets, dependencies, conflict_detection ` ) ``` -**Graceful Degradation**: -- If agent fails: Log warning, continue to Phase 1 without project context -- If package invalid: Re-run context-search-agent +### Phase 1: Topic Analysis -### Phase 1: Topic Analysis & Intent Classification - -**Goal**: Extract keywords/challenges to drive all subsequent question generation, **enriched by Phase 0 project context** +**Goal**: Extract keywords/challenges enriched by Phase 0 context **Steps**: -1. **Load Phase 0 context** (if available): - - Read `.workflow/active/WFS-{session-id}/.process/context-package.json` - - Extract: tech_stack, existing modules, conflict_risk, relevant files +1. Load Phase 0 context (tech_stack, modules, conflict_risk) +2. Deep topic analysis (entities, challenges, constraints, metrics) +3. Generate 2-4 context-aware probing questions +4. AskUserQuestion → Store to `session.intent_context` -2. **Deep topic analysis** (context-aware): - - Extract technical entities from topic + existing codebase - - Identify core challenges considering existing architecture - - Consider constraints (timeline/budget/compliance) - - Define success metrics based on current project state - -3. **Generate 2-4 context-aware probing questions**: - - Reference existing tech stack in questions - - Consider integration with existing modules - - Address identified conflict risks from Phase 0 - - Target root challenges and trade-off priorities - -4. **User interaction**: Output questions using text format (see User Interaction Protocol), wait for user input - -5. **Parse user answers**: Use intelligent parsing to extract answers from user input (support multiple formats) - -6. **Storage**: Store answers to `session.intent_context` with `{extracted_keywords, identified_challenges, user_answers, project_context_used}` - -**Example Output**: -```markdown -===== Phase 1: 项目意图分析 ===== - -【问题1 - 核心挑战】实时协作平台的主要技术挑战？ -a) 实时数据同步 - 说明：100+用户同时在线，状态同步复杂度高 -b) 可扩展性架构 - 说明：用户规模增长时的系统扩展能力 -c) 冲突解决机制 - 说明：多用户同时编辑的冲突处理策略 - -【问题2 - 优先级】MVP阶段最关注的指标？ -a) 功能完整性 - 说明：实现所有核心功能 -b) 用户体验 - 说明：流畅的交互体验和响应速度 -c) 系统稳定性 - 说明：高可用性和数据一致性 - -请回答 (格式: 1a 2b)： +**Example**: +```javascript +AskUserQuestion({ + questions: [ + { + question: "实时协作平台的主要技术挑战？", + header: "核心挑战", + multiSelect: false, + options: [ + { label: "实时数据同步", description: "100+用户同时在线，状态同步复杂度高" }, + { label: "可扩展性架构", description: "用户规模增长时的系统扩展能力" }, + { label: "冲突解决机制", description: "多用户同时编辑的冲突处理策略" } + ] + }, + { + question: "MVP阶段最关注的指标？", + header: "优先级", + multiSelect: false, + options: [ + { label: "功能完整性", description: "实现所有核心功能" }, + { label: "用户体验", description: "流畅的交互体验和响应速度" }, + { label: "系统稳定性", description: "高可用性和数据一致性" } + ] + } + ] +}) ``` -**User input examples**: -- `1a 2c` → Q1:a, Q2:c -- `1a,2c` → Q1:a, Q2:c - **⚠️ CRITICAL**: Questions MUST reference topic keywords. Generic "Project type?" violates dynamic generation. ### Phase 2: Role Selection -**⚠️ CRITICAL**: User MUST interact to select roles. NEVER auto-select without user confirmation. +**Goal**: User selects roles from intelligent recommendations -**Available Roles**: -- data-architect (数据架构师) -- product-manager (产品经理) -- product-owner (产品负责人) -- scrum-master (敏捷教练) -- subject-matter-expert (领域专家) -- system-architect (系统架构师) -- test-strategist (测试策略师) -- ui-designer (UI 设计师) -- ux-expert (UX 专家) +**Available Roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert **Steps**: -1. **Intelligent role recommendation** (AI analysis): - - Analyze Phase 1 extracted keywords and challenges - - Use AI reasoning to determine most relevant roles for the specific topic - - Recommend count+2 roles (e.g., if user wants 3 roles, recommend 5 options) - - Provide clear rationale for each recommended role based on topic context +1. Analyze Phase 1 keywords → Recommend count+2 roles with rationale +2. AskUserQuestion (multiSelect=true) → Store to `session.selected_roles` +3. If count+2 > 4, split into multiple rounds -2. **User selection** (text interaction): - - Output all recommended roles at once (no batching needed for count+2 roles) - - Display roles with labels and relevance rationale - - Wait for user input in multi-select format - - Parse user input (support multiple formats) - - **Storage**: Store selections to `session.selected_roles` - -**Example Output**: -```markdown -===== Phase 2: 角色选择 ===== - -【角色选择】请选择 3 个角色参与头脑风暴分析 - -a) system-architect (系统架构师) - 推荐理由：实时同步架构设计和技术选型的核心角色 -b) ui-designer (UI设计师) - 推荐理由：协作界面用户体验和实时状态展示 -c) product-manager (产品经理) - 推荐理由：功能优先级和MVP范围决策 -d) data-architect (数据架构师) - 推荐理由：数据同步模型和存储方案设计 -e) ux-expert (UX专家) - 推荐理由：多用户协作交互流程优化 - -支持格式： -- 分别选择：2a 2c 2d (选择a、c、d) -- 合并语法：2acd (选择a、c、d) -- 逗号分隔：2a,c,d (选择a、c、d) - -请输入选择： +**Example**: +```javascript +AskUserQuestion({ + questions: [{ + question: "请选择 3 个角色参与头脑风暴分析", + header: "角色选择", + multiSelect: true, + options: [ + { label: "system-architect", description: "实时同步架构设计和技术选型" }, + { label: "ui-designer", description: "协作界面用户体验和状态展示" }, + { label: "product-manager", description: "功能优先级和MVP范围决策" }, + { label: "data-architect", description: "数据同步模型和存储方案设计" } + ] + }] +}) ``` -**User input examples**: -- `2acd` → Roles: a, c, d (system-architect, product-manager, data-architect) -- `2a 2c 2d` → Same result -- `2a,c,d` → Same result +**⚠️ CRITICAL**: User MUST interact. NEVER auto-select without confirmation. -**Role Recommendation Rules**: -- NO hardcoded keyword-to-role mappings -- Use intelligent analysis of topic, challenges, and requirements -- Consider role synergies and coverage gaps -- Explain WHY each role is relevant to THIS specific topic -- Default recommendation: count+2 roles for user to choose from - -### Phase 3: Role-Specific Questions (Dynamic Generation) +### Phase 3: Role-Specific Questions **Goal**: Generate deep questions mapping role expertise to Phase 1 challenges **Algorithm**: -``` -FOR each selected role: - 1. Map Phase 1 challenges to role domain: - - "real-time sync" + system-architect → State management pattern - - "100 users" + system-architect → Communication protocol - - "low latency" + system-architect → Conflict resolution +1. FOR each selected role: + - Map Phase 1 challenges to role domain + - Generate 3-4 questions (implementation depth, trade-offs, edge cases) + - AskUserQuestion per role → Store to `session.role_decisions[role]` +2. Process roles sequentially (one at a time for clarity) +3. If role needs > 4 questions, split into multiple rounds - 2. Generate 3-4 questions per role probing implementation depth, trade-offs, edge cases: - Q: "How handle real-time state sync for 100+ users?" (explores approach) - Q: "How resolve conflicts when 2 users edit simultaneously?" (explores edge case) - Options: [Event Sourcing/Centralized/CRDT] (concrete, explain trade-offs for THIS use case) - - 3. Output questions in text format per role: - - Display all questions for current role (3-4 questions, no 10-question limit) - - Questions in Chinese (用中文提问) - - Wait for user input - - Parse answers using intelligent parsing - - Store answers to session.role_decisions[role] +**Example** (system-architect): +```javascript +AskUserQuestion({ + questions: [ + { + question: "100+ 用户实时状态同步方案？", + header: "状态同步", + multiSelect: false, + options: [ + { label: "Event Sourcing", description: "完整事件历史，支持回溯，存储成本高" }, + { label: "集中式状态管理", description: "实现简单，单点瓶颈风险" }, + { label: "CRDT", description: "去中心化，自动合并，学习曲线陡" } + ] + }, + { + question: "两个用户同时编辑冲突如何解决？", + header: "冲突解决", + multiSelect: false, + options: [ + { label: "自动合并", description: "用户无感知，可能产生意外结果" }, + { label: "手动解决", description: "用户控制，增加交互复杂度" }, + { label: "版本控制", description: "保留历史，需要分支管理" } + ] + } + ] +}) ``` -**Batching Strategy**: -- Each role outputs all its questions at once (typically 3-4 questions) -- No need to split per role (within 10-question batch limit) -- Multiple roles processed sequentially (one role at a time for clarity) +### Phase 4: Conflict Resolution -**Output Format**: Follow standard format from "User Interaction Protocol" section (single-choice question format) - -**Example Topic-Specific Questions** (system-architect role for "real-time collaboration platform"): -- "100+ 用户实时状态同步方案?" → Options: Event Sourcing / 集中式状态管理 / CRDT -- "两个用户同时编辑冲突如何解决?" → Options: 自动合并 / 手动解决 / 版本控制 -- "低延迟通信协议选择?" → Options: WebSocket / SSE / 轮询 -- "系统扩展性架构方案?" → Options: 微服务 / 单体+缓存 / Serverless - -**Quality Requirements**: See "Question Generation Guidelines" section for detailed rules - -### Phase 4: Cross-Role Clarification (Conflict Detection) - -**Goal**: Resolve ACTUAL conflicts from Phase 3 answers, not pre-defined relationships +**Goal**: Resolve ACTUAL conflicts from Phase 3 answers **Algorithm**: -``` 1. Analyze Phase 3 answers for conflicts: - - Contradictory choices: product-manager "fast iteration" vs system-architect "complex Event Sourcing" - - Missing integration: ui-designer "Optimistic updates" but system-architect didn't address conflict handling - - Implicit dependencies: ui-designer "Live cursors" but no auth approach defined - -2. FOR each detected conflict: - Generate clarification questions referencing SPECIFIC Phase 3 choices - -3. Output clarification questions in text format: - - Batch conflicts into rounds (max 10 questions per round) - - Display questions with context from Phase 3 answers - - Questions in Chinese (用中文提问) - - Wait for user input - - Parse answers using intelligent parsing - - Store answers to session.cross_role_decisions - + - Contradictory choices (e.g., "fast iteration" vs "complex Event Sourcing") + - Missing integration (e.g., "Optimistic updates" but no conflict handling) + - Implicit dependencies (e.g., "Live cursors" but no auth defined) +2. Generate clarification questions referencing SPECIFIC Phase 3 choices +3. AskUserQuestion (max 4 per call, multi-round) → Store to `session.cross_role_decisions` 4. If NO conflicts: Skip Phase 4 (inform user: "未检测到跨角色冲突，跳过Phase 4") + +**Example**: +```javascript +AskUserQuestion({ + questions: [{ + question: "CRDT 与 UI 回滚期望冲突，如何解决？\n背景：system-architect选择CRDT，ui-designer期望回滚UI", + header: "架构冲突", + multiSelect: false, + options: [ + { label: "采用 CRDT", description: "保持去中心化，调整UI期望" }, + { label: "显示合并界面", description: "增加用户交互，展示冲突详情" }, + { label: "切换到 OT", description: "支持回滚，增加服务器复杂度" } + ] + }] +}) ``` -**Batching Strategy**: -- Maximum 10 clarification questions per round -- If conflicts > 10, split into multiple rounds -- Prioritize most critical conflicts first +### Phase 4.5: Final Clarification -**Output Format**: Follow standard format from "User Interaction Protocol" section (single-choice question format with background context) - -**Example Conflict Detection** (from Phase 3 answers): -- **Architecture Conflict**: "CRDT 与 UI 回滚期望冲突，如何解决?" - - Background: system-architect chose CRDT, ui-designer expects rollback UI - - Options: 采用 CRDT / 显示合并界面 / 切换到 OT -- **Integration Gap**: "实时光标功能缺少身份认证方案" - - Background: ui-designer chose live cursors, no auth defined - - Options: OAuth 2.0 / JWT Token / Session-based - -**Quality Requirements**: See "Question Generation Guidelines" section for conflict-specific rules - -### Phase 5: Generate Guidance Specification +**Purpose**: Ensure no important points missed before generating specification **Steps**: -1. Load all decisions: `intent_context` + `selected_roles` + `role_decisions` + `cross_role_decisions` -2. Transform Q&A pairs to declarative: Questions → Headers, Answers → CONFIRMED/SELECTED statements -3. Generate guidance-specification.md (template below) - **PRIMARY OUTPUT FILE** -4. Update workflow-session.json with **METADATA ONLY**: - - session_id (e.g., "WFS-topic-slug") - - selected_roles[] (array of role names, e.g., ["system-architect", "ui-designer", "product-manager"]) - - topic (original user input string) - - timestamp (ISO-8601 format) - - phase_completed: "artifacts" - - count_parameter (number from --count flag) -5. Validate: No interrogative sentences in .md file, all decisions traceable, no content duplication in .json +1. Ask initial check: + ```javascript + AskUserQuestion({ + questions: [{ + question: "在生成最终规范之前，是否有前面未澄清的重点需要补充？", + header: "补充确认", + multiSelect: false, + options: [ + { label: "无需补充", description: "前面的讨论已经足够完整" }, + { label: "需要补充", description: "还有重要内容需要澄清" } + ] + }] + }) + ``` +2. If "需要补充": + - Analyze user's additional points + - Generate progressive questions (not role-bound, interconnected) + - AskUserQuestion (max 4 per round) → Store to `session.additional_decisions` + - Repeat until user confirms completion +3. If "无需补充": Proceed to Phase 5 -**⚠️ CRITICAL OUTPUT SEPARATION**: -- **guidance-specification.md**: Full guidance content (decisions, rationale, integration points) -- **workflow-session.json**: Session metadata ONLY (no guidance content, no decisions, no Q&A pairs) -- **NO content duplication**: Guidance stays in .md, metadata stays in .json +**Progressive Pattern**: Questions interconnected, each round informs next, continue until resolved. -## Output Document Template +### Phase 5: Generate Specification + +**Steps**: +1. Load all decisions: `intent_context` + `selected_roles` + `role_decisions` + `cross_role_decisions` + `additional_decisions` +2. Transform Q&A to declarative: Questions → Headers, Answers → CONFIRMED/SELECTED statements +3. Generate `guidance-specification.md` +4. Update `workflow-session.json` (metadata only) +5. Validate: No interrogative sentences, all decisions traceable + +--- + +## Question Guidelines + +### Core Principle + +**Target**: 开发者（理解技术但需要从用户需求出发） + +**Question Structure**: `[业务场景/需求前提] + [技术关注点]` +**Option Structure**: `标签：[技术方案] + 说明：[业务影响] + [技术权衡]` + +### Quality Rules + +**MUST Include**: +- ✅ All questions in Chinese (用中文提问) +- ✅ 业务场景作为问题前提 +- ✅ 技术选项的业务影响说明 +- ✅ 量化指标和约束条件 + +**MUST Avoid**: +- ❌ 纯技术选型无业务上下文 +- ❌ 过度抽象的用户体验问题 +- ❌ 脱离话题的通用架构问题 + +### Phase-Specific Requirements + +| Phase | Focus | Key Requirements | +|-------|-------|------------------| +| 1 | 意图理解 | Reference topic keywords, 用户场景、业务约束、优先级 | +| 2 | 角色推荐 | Intelligent analysis (NOT keyword mapping), explain relevance | +| 3 | 角色问题 | Reference Phase 1 keywords, concrete options with trade-offs | +| 4 | 冲突解决 | Reference SPECIFIC Phase 3 choices, explain impact on both roles | + +--- + +## Output & Governance + +### Output Template **File**: `.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md` @@ -478,9 +385,9 @@ FOR each selected role: ## Next Steps **⚠️ Automatic Continuation** (when called from auto-parallel): -- auto-parallel will assign agents to generate role-specific analysis documents -- Each selected role gets dedicated conceptual-planning-agent -- Agents read this guidance-specification.md for framework context +- auto-parallel assigns agents for role-specific analysis +- Each selected role gets conceptual-planning-agent +- Agents read this guidance-specification.md for context ## Appendix: Decision Tracking | Decision ID | Category | Question | Selected | Phase | Rationale | @@ -490,95 +397,19 @@ FOR each selected role: | D-003+ | [Role] | [Q] | [A] | 3 | [Why] | ``` -## Question Generation Guidelines - -### Core Principle: Developer-Facing Questions with User Context - -**Target Audience**: 开发者（理解技术但需要从用户需求出发） - -**Generation Philosophy**: -1. **Phase 1**: 用户场景、业务约束、优先级（建立上下文） -2. **Phase 2**: 基于话题分析的智能角色推荐（非关键词映射） -3. **Phase 3**: 业务需求 + 技术选型（需求驱动的技术决策） -4. **Phase 4**: 技术冲突的业务权衡（帮助开发者理解影响） - -### Universal Quality Rules - -**Question Structure** (all phases): -``` -[业务场景/需求前提] + [技术关注点] -``` - -**Option Structure** (all phases): -``` -标签：[技术方案简称] + (业务特征) -说明：[业务影响] + [技术权衡] -``` - -**MUST Include** (all phases): -- ✅ All questions in Chinese (用中文提问) -- ✅ 业务场景作为问题前提 -- ✅ 技术选项的业务影响说明 -- ✅ 量化指标和约束条件 - -**MUST Avoid** (all phases): -- ❌ 纯技术选型无业务上下文 -- ❌ 过度抽象的用户体验问题 -- ❌ 脱离话题的通用架构问题 - -### Phase-Specific Requirements - -**Phase 1 Requirements**: -- Questions MUST reference topic keywords (NOT generic "Project type?") -- Focus: 用户使用场景（谁用？怎么用？多频繁？）、业务约束（预算、时间、团队、合规） -- Success metrics: 性能指标、用户体验目标 -- Priority ranking: MVP vs 长期规划 - -**Phase 3 Requirements**: -- Questions MUST reference Phase 1 keywords (e.g., "real-time", "100 users") -- Options MUST be concrete approaches with relevance to topic -- Each option includes trade-offs specific to this use case -- Include 业务需求驱动的技术问题、量化指标（并发数、延迟、可用性） - -**Phase 4 Requirements**: -- Questions MUST reference SPECIFIC Phase 3 choices in background context -- Options address the detected conflict directly -- Each option explains impact on both conflicting roles -- NEVER use static "Cross-Role Matrix" - ALWAYS analyze actual Phase 3 answers -- Focus: 技术冲突的业务权衡、帮助开发者理解不同选择的影响 - -## Validation Checklist - -Generated guidance-specification.md MUST: -- ✅ No interrogative sentences (use CONFIRMED/SELECTED) -- ✅ Every decision traceable to user answer -- ✅ Cross-role conflicts resolved or documented -- ✅ Next steps concrete and specific -- ✅ All Phase 1-4 decisions in session metadata - -## Update Mechanism +### File Structure ``` -IF guidance-specification.md EXISTS: - Prompt: "Regenerate completely / Update sections / Cancel" -ELSE: - Run full Phase 1-5 flow +.workflow/active/WFS-[topic]/ +├── workflow-session.json # Metadata ONLY +├── .process/ +│ └── context-package.json # Phase 0 output +└── .brainstorming/ + └── guidance-specification.md # Full guidance content ``` -## Governance Rules +### Session Metadata -**Output Requirements**: -- All decisions MUST use CONFIRMED/SELECTED (NO "?" in decision sections) -- Every decision MUST trace to user answer -- Conflicts MUST be resolved (not marked "TBD") -- Next steps MUST be actionable -- Topic preserved as authoritative reference in session - -**CRITICAL**: Guidance is single source of truth for downstream phases. Ambiguity violates governance. - -## Storage Validation - -**workflow-session.json** (metadata only): ```json { "session_id": "WFS-{topic-slug}", @@ -591,14 +422,31 @@ ELSE: } ``` -**⚠️ Rule**: Session JSON stores ONLY metadata (session_id, selected_roles[], topic, timestamps). All guidance content goes to guidance-specification.md. +**⚠️ Rule**: Session JSON stores ONLY metadata. All guidance content goes to guidance-specification.md. -## File Structure +### Validation Checklist + +- ✅ No interrogative sentences (use CONFIRMED/SELECTED) +- ✅ Every decision traceable to user answer +- ✅ Cross-role conflicts resolved or documented +- ✅ Next steps concrete and specific +- ✅ No content duplication between .json and .md + +### Update Mechanism ``` -.workflow/active/WFS-[topic]/ -├── workflow-session.json # Session metadata ONLY -└── .brainstorming/ - └── guidance-specification.md # Full guidance content +IF guidance-specification.md EXISTS: + Prompt: "Regenerate completely / Update sections / Cancel" +ELSE: + Run full Phase 0-5 flow ``` +### Governance Rules + +- All decisions MUST use CONFIRMED/SELECTED (NO "?" in decision sections) +- Every decision MUST trace to user answer +- Conflicts MUST be resolved (not marked "TBD") +- Next steps MUST be actionable +- Topic preserved as authoritative reference + +**CRITICAL**: Guidance is single source of truth for downstream phases. Ambiguity violates governance. diff --git a/.claude/commands/workflow/brainstorm/auto-parallel.md b/.claude/commands/workflow/brainstorm/auto-parallel.md index 235a3dae..57006069 100644 --- a/.claude/commands/workflow/brainstorm/auto-parallel.md +++ b/.claude/commands/workflow/brainstorm/auto-parallel.md @@ -141,26 +141,10 @@ OUTPUT_LOCATION: .workflow/active/WFS-{session}/.brainstorming/{role}/ TOPIC: {user-provided-topic} ## Flow Control Steps -1. **load_topic_framework** - - Action: Load structured topic discussion framework - - Command: Read(.workflow/active/WFS-{session}/.brainstorming/guidance-specification.md) - - Output: topic_framework_content - -2. **load_role_template** - - Action: Load {role-name} planning template - - Command: Read(~/.claude/workflows/cli-templates/planning-roles/{role}.md) - - Output: role_template_guidelines - -3. **load_session_metadata** - - Action: Load session metadata and original user intent - - Command: Read(.workflow/active/WFS-{session}/workflow-session.json) - - Output: session_context (contains original user prompt as PRIMARY reference) - -4. **load_style_skill** (ONLY for ui-designer role when style_skill_package exists) - - Action: Load style SKILL package for design system reference - - Command: Read(.claude/skills/style-{style_skill_package}/SKILL.md) AND Read(.workflow/reference_style/{style_skill_package}/design-tokens.json) - - Output: style_skill_content, design_tokens - - Usage: Apply design tokens in ui-designer analysis and artifacts +1. load_topic_framework → .workflow/active/WFS-{session}/.brainstorming/guidance-specification.md +2. load_role_template → ~/.claude/workflows/cli-templates/planning-roles/{role}.md +3. load_session_metadata → .workflow/active/WFS-{session}/workflow-session.json +4. load_style_skill (ui-designer only, if style_skill_package) → .claude/skills/style-{style_skill_package}/ ## Analysis Requirements **Primary Reference**: Original user prompt from workflow-session.json is authoritative @@ -170,13 +154,9 @@ TOPIC: {user-provided-topic} **Template Integration**: Apply role template guidelines within framework structure ## Expected Deliverables -1. **analysis.md**: Comprehensive {role-name} analysis addressing all framework discussion points - - **File Naming**: MUST start with `analysis` prefix (e.g., `analysis.md`, `analysis-1.md`, `analysis-2.md`) - - **FORBIDDEN**: Never use `recommendations.md` or any filename not starting with `analysis` - - **Auto-split if large**: If content >800 lines, split to `analysis-1.md`, `analysis-2.md` (max 3 files: analysis.md, analysis-1.md, analysis-2.md) - - **Content**: Includes both analysis AND recommendations sections within analysis files -2. **Framework Reference**: Include @../guidance-specification.md reference in analysis -3. **User Intent Alignment**: Validate analysis aligns with original user objectives from session_context +1. **analysis.md** (optionally with analysis-{slug}.md sub-documents) +2. **Framework Reference**: @../guidance-specification.md +3. **User Intent Alignment**: Validate against session_context ## Completion Criteria - Address each discussion point from guidance-specification.md with {role-name} expertise @@ -199,10 +179,10 @@ TOPIC: {user-provided-topic} - guidance-specification.md path **Validation**: -- Each role creates `.workflow/active/WFS-{topic}/.brainstorming/{role}/analysis.md` (primary file) -- If content is large (>800 lines), may split to `analysis-1.md`, `analysis-2.md` (max 3 files total) -- **File naming pattern**: ALL files MUST start with `analysis` prefix (use `analysis*.md` for globbing) -- **FORBIDDEN naming**: No `recommendations.md`, `recommendations-*.md`, or any non-`analysis` prefixed files +- Each role creates `.workflow/active/WFS-{topic}/.brainstorming/{role}/analysis.md` +- Optionally with `analysis-{slug}.md` sub-documents (max 5) +- **File pattern**: `analysis*.md` for globbing +- **FORBIDDEN**: `recommendations.md` or any non-`analysis` prefixed files - All N role analyses completed **TodoWrite Update (Phase 2 agents dispatched - tasks attached in parallel)**: @@ -453,12 +433,9 @@ CONTEXT_VARS: ├── workflow-session.json # Session metadata ONLY └── .brainstorming/ ├── guidance-specification.md # Framework (Phase 1) - ├── {role-1}/ - │ └── analysis.md # Role analysis (Phase 2) - ├── {role-2}/ - │ └── analysis.md - ├── {role-N}/ - │ └── analysis.md + ├── {role}/ + │ ├── analysis.md # Main document (with optional @references) + │ └── analysis-{slug}.md # Section documents (max 5) └── synthesis-specification.md # Integration (Phase 3) ``` diff --git a/.claude/commands/workflow/brainstorm/synthesis.md b/.claude/commands/workflow/brainstorm/synthesis.md index ca5ed597..93c00de6 100644 --- a/.claude/commands/workflow/brainstorm/synthesis.md +++ b/.claude/commands/workflow/brainstorm/synthesis.md @@ -2,325 +2,318 @@ name: synthesis description: Clarify and refine role analyses through intelligent Q&A and targeted updates with synthesis agent argument-hint: "[optional: --session session-id]" -allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*), Edit(*), Glob(*) +allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*), Edit(*), Glob(*), AskUserQuestion(*) --- ## Overview -Three-phase workflow to eliminate ambiguities and enhance conceptual depth in role analyses: +Six-phase workflow to eliminate ambiguities and enhance conceptual depth in role analyses: -**Phase 1-2 (Main Flow)**: Session detection → File discovery → Path preparation +**Phase 1-2**: Session detection → File discovery → Path preparation +**Phase 3A**: Cross-role analysis agent → Generate recommendations +**Phase 4**: User selects enhancements → User answers clarifications (via AskUserQuestion) +**Phase 5**: Parallel update agents (one per role) +**Phase 6**: Context package update → Metadata update → Completion report -**Phase 3A (Analysis Agent)**: Cross-role analysis → Generate recommendations - -**Phase 4 (Main Flow)**: User selects enhancements → User answers clarifications → Build update plan - -**Phase 5 (Parallel Update Agents)**: Each agent updates ONE role document → Parallel execution - -**Phase 6 (Main Flow)**: Metadata update → Completion report - -**Key Features**: -- Multi-agent architecture (analysis agent + parallel update agents) -- Clear separation: Agent analysis vs Main flow interaction -- Parallel document updates (one agent per role) -- User intent alignment validation +All user interactions use AskUserQuestion tool (max 4 questions per call, multi-round). **Document Flow**: - Input: `[role]/analysis*.md`, `guidance-specification.md`, session metadata - Output: Updated `[role]/analysis*.md` with Enhancements + Clarifications sections +--- + +## Quick Reference + +### Phase Summary + +| Phase | Goal | Executor | Output | +|-------|------|----------|--------| +| 1 | Session detection | Main flow | session_id, brainstorm_dir | +| 2 | File discovery | Main flow | role_analysis_paths | +| 3A | Cross-role analysis | Agent | enhancement_recommendations | +| 4 | User interaction | Main flow + AskUserQuestion | update_plan | +| 5 | Document updates | Parallel agents | Updated analysis*.md | +| 6 | Finalization | Main flow | context-package.json, report | + +### AskUserQuestion Pattern + +```javascript +// Enhancement selection (multi-select) +AskUserQuestion({ + questions: [{ + question: "请选择要应用的改进建议", + header: "改进选择", + multiSelect: true, + options: [ + { label: "EP-001: API Contract", description: "添加详细的请求/响应 schema 定义" }, + { label: "EP-002: User Intent", description: "明确用户需求优先级和验收标准" } + ] + }] +}) + +// Clarification questions (single-select, multi-round) +AskUserQuestion({ + questions: [ + { + question: "MVP 阶段的核心目标是什么？", + header: "用户意图", + multiSelect: false, + options: [ + { label: "快速验证", description: "最小功能集，快速上线获取反馈" }, + { label: "技术壁垒", description: "完善架构，为长期发展打基础" }, + { label: "功能完整", description: "覆盖所有规划功能，延迟上线" } + ] + } + ] +}) +``` + +--- + ## Task Tracking ```json [ - {"content": "Detect session and validate analyses", "status": "in_progress", "activeForm": "Detecting session"}, + {"content": "Detect session and validate analyses", "status": "pending", "activeForm": "Detecting session"}, {"content": "Discover role analysis file paths", "status": "pending", "activeForm": "Discovering paths"}, - {"content": "Execute analysis agent (cross-role analysis)", "status": "pending", "activeForm": "Executing analysis agent"}, - {"content": "Present enhancements for user selection", "status": "pending", "activeForm": "Presenting enhancements"}, - {"content": "Generate and present clarification questions", "status": "pending", "activeForm": "Clarifying with user"}, - {"content": "Build update plan from user input", "status": "pending", "activeForm": "Building update plan"}, - {"content": "Execute parallel update agents (one per role)", "status": "pending", "activeForm": "Updating documents in parallel"}, - {"content": "Update session metadata and generate report", "status": "pending", "activeForm": "Finalizing session"} + {"content": "Execute analysis agent (cross-role analysis)", "status": "pending", "activeForm": "Executing analysis"}, + {"content": "Present enhancements via AskUserQuestion", "status": "pending", "activeForm": "Selecting enhancements"}, + {"content": "Clarification questions via AskUserQuestion", "status": "pending", "activeForm": "Clarifying"}, + {"content": "Execute parallel update agents", "status": "pending", "activeForm": "Updating documents"}, + {"content": "Update context package and metadata", "status": "pending", "activeForm": "Finalizing"} ] ``` +--- + ## Execution Phases ### Phase 1: Discovery & Validation -1. **Detect Session**: Use `--session` parameter or find `.workflow/active/WFS-*` directories +1. **Detect Session**: Use `--session` parameter or find `.workflow/active/WFS-*` 2. **Validate Files**: - `guidance-specification.md` (optional, warn if missing) - `*/analysis*.md` (required, error if empty) -3. **Load User Intent**: Extract from `workflow-session.json` (project/description field) +3. **Load User Intent**: Extract from `workflow-session.json` ### Phase 2: Role Discovery & Path Preparation **Main flow prepares file paths for Agent**: 1. **Discover Analysis Files**: - - Glob(.workflow/active/WFS-{session}/.brainstorming/*/analysis*.md) - - Supports: analysis.md, analysis-1.md, analysis-2.md, analysis-3.md - - Validate: At least one file exists (error if empty) + - Glob: `.workflow/active/WFS-{session}/.brainstorming/*/analysis*.md` + - Supports: analysis.md + analysis-{slug}.md (max 5) 2. **Extract Role Information**: - - `role_analysis_paths`: Relative paths from brainstorm_dir - - `participating_roles`: Role names extracted from directory paths + - `role_analysis_paths`: Relative paths + - `participating_roles`: Role names from directories -3. **Pass to Agent** (Phase 3): - - `session_id` - - `brainstorm_dir`: .workflow/active/WFS-{session}/.brainstorming/ - - `role_analysis_paths`: ["product-manager/analysis.md", "system-architect/analysis-1.md", ...] - - `participating_roles`: ["product-manager", "system-architect", ...] - -**Main Flow Responsibility**: File discovery and path preparation only (NO file content reading) +3. **Pass to Agent**: session_id, brainstorm_dir, role_analysis_paths, participating_roles ### Phase 3A: Analysis & Enhancement Agent -**First agent call**: Cross-role analysis and generate enhancement recommendations +**Agent executes cross-role analysis**: -```bash -Task(conceptual-planning-agent): " +```javascript +Task(conceptual-planning-agent, ` ## Agent Mission -Analyze role documents, identify conflicts/gaps, and generate enhancement recommendations +Analyze role documents, identify conflicts/gaps, generate enhancement recommendations -## Input from Main Flow -- brainstorm_dir: {brainstorm_dir} -- role_analysis_paths: {role_analysis_paths} -- participating_roles: {participating_roles} +## Input +- brainstorm_dir: ${brainstorm_dir} +- role_analysis_paths: ${role_analysis_paths} +- participating_roles: ${participating_roles} -## Execution Instructions -[FLOW_CONTROL] +## Flow Control Steps +1. load_session_metadata → Read workflow-session.json +2. load_role_analyses → Read all analysis files +3. cross_role_analysis → Identify consensus, conflicts, gaps, ambiguities +4. generate_recommendations → Format as EP-001, EP-002, ... -### Flow Control Steps -**AGENT RESPONSIBILITY**: Execute these analysis steps sequentially with context accumulation: - -1. **load_session_metadata** - - Action: Load original user intent as primary reference - - Command: Read({brainstorm_dir}/../workflow-session.json) - - Output: original_user_intent (from project/description field) - -2. **load_role_analyses** - - Action: Load all role analysis documents - - Command: For each path in role_analysis_paths: Read({brainstorm_dir}/{path}) - - Output: role_analyses_content_map = {role_name: content} - -3. **cross_role_analysis** - - Action: Identify consensus themes, conflicts, gaps, underspecified areas - - Output: consensus_themes, conflicting_views, gaps_list, ambiguities - -4. **generate_recommendations** - - Action: Convert cross-role analysis findings into structured enhancement recommendations - - Format: EP-001, EP-002, ... (sequential numbering) - - Fields: id, title, affected_roles, category, current_state, enhancement, rationale, priority - - Taxonomy: Map to 9 categories (User Intent, Requirements, Architecture, UX, Feasibility, Risk, Process, Decisions, Terminology) - - Output: enhancement_recommendations (JSON array) - -### Output to Main Flow -Return JSON array: +## Output Format [ { - \"id\": \"EP-001\", - \"title\": \"API Contract Specification\", - \"affected_roles\": [\"system-architect\", \"api-designer\"], - \"category\": \"Architecture\", - \"current_state\": \"High-level API descriptions\", - \"enhancement\": \"Add detailed contract definitions with request/response schemas\", - \"rationale\": \"Enables precise implementation and testing\", - \"priority\": \"High\" - }, - ... + "id": "EP-001", + "title": "API Contract Specification", + "affected_roles": ["system-architect", "api-designer"], + "category": "Architecture", + "current_state": "High-level API descriptions", + "enhancement": "Add detailed contract definitions", + "rationale": "Enables precise implementation", + "priority": "High" + } ] - -" +`) ``` -### Phase 4: Main Flow User Interaction +### Phase 4: User Interaction -**Main flow handles all user interaction via text output**: +**All interactions via AskUserQuestion (Chinese questions)** -**⚠️ CRITICAL**: ALL questions MUST use Chinese (所有问题必须用中文) for better user understanding +#### Step 1: Enhancement Selection -1. **Present Enhancement Options** (multi-select): -```markdown -===== Enhancement 选择 ===== +```javascript +// If enhancements > 4, split into multiple rounds +const enhancements = [...]; // from Phase 3A +const BATCH_SIZE = 4; -请选择要应用的改进建议（可多选）： +for (let i = 0; i < enhancements.length; i += BATCH_SIZE) { + const batch = enhancements.slice(i, i + BATCH_SIZE); -a) EP-001: API Contract Specification - 影响角色：system-architect, api-designer - 说明：添加详细的请求/响应 schema 定义 + AskUserQuestion({ + questions: [{ + question: `请选择要应用的改进建议 (第${Math.floor(i/BATCH_SIZE)+1}轮)`, + header: "改进选择", + multiSelect: true, + options: batch.map(ep => ({ + label: `${ep.id}: ${ep.title}`, + description: `影响: ${ep.affected_roles.join(', ')} | ${ep.enhancement}` + })) + }] + }) -b) EP-002: User Intent Validation - 影响角色：product-manager, ux-expert - 说明：明确用户需求优先级和验收标准 + // Store selections before next round +} -c) EP-003: Error Handling Strategy - 影响角色：system-architect - 说明：统一异常处理和降级方案 - -支持格式：1abc 或 1a 1b 1c 或 1a,b,c -请输入选择（可跳过输入 skip）： +// User can also skip: provide "跳过" option ``` -2. **Generate Clarification Questions** (based on analysis agent output): - - ✅ **ALL questions in Chinese (所有问题必须用中文)** - - Use 9-category taxonomy scan results - - Prioritize most critical questions (no hard limit) - - Each with 2-4 options + descriptions +#### Step 2: Clarification Questions -3. **Interactive Clarification Loop** (max 10 questions per round): -```markdown -===== Clarification 问题 (第 1/2 轮) ===== +```javascript +// Generate questions based on 9-category taxonomy scan +// Categories: User Intent, Requirements, Architecture, UX, Feasibility, Risk, Process, Decisions, Terminology -【问题1 - 用户意图】MVP 阶段的核心目标是什么？ -a) 快速验证市场需求 - 说明：最小功能集，快速上线获取反馈 -b) 建立技术壁垒 - 说明：完善架构，为长期发展打基础 -c) 实现功能完整性 - 说明：覆盖所有规划功能，延迟上线 +const clarifications = [...]; // from analysis +const BATCH_SIZE = 4; -【问题2 - 架构决策】技术栈选择的优先考虑因素？ -a) 团队熟悉度 - 说明：使用现有技术栈，降低学习成本 -b) 技术先进性 - 说明：采用新技术，提升竞争力 -c) 生态成熟度 - 说明：选择成熟方案，保证稳定性 +for (let i = 0; i < clarifications.length; i += BATCH_SIZE) { + const batch = clarifications.slice(i, i + BATCH_SIZE); + const currentRound = Math.floor(i / BATCH_SIZE) + 1; + const totalRounds = Math.ceil(clarifications.length / BATCH_SIZE); -...（最多10个问题） + AskUserQuestion({ + questions: batch.map(q => ({ + question: q.question, + header: q.category.substring(0, 12), + multiSelect: false, + options: q.options.map(opt => ({ + label: opt.label, + description: opt.description + })) + })) + }) -请回答 (格式: 1a 2b 3c...)： + // Store answers before next round +} ``` -Wait for user input → Parse all answers in batch → Continue to next round if needed +### Question Guidelines -4. **Build Update Plan**: -``` +**Target**: 开发者（理解技术但需要从用户需求出发） + +**Question Structure**: `[跨角色分析发现] + [需要澄清的决策点]` +**Option Structure**: `标签：[具体方案] + 说明：[业务影响] + [技术权衡]` + +**9-Category Taxonomy**: + +| Category | Focus | Example Question Pattern | +|----------|-------|--------------------------| +| User Intent | 用户目标 | "MVP阶段核心目标？" + 验证/壁垒/完整性 | +| Requirements | 需求细化 | "功能优先级如何排序？" + 核心/增强/可选 | +| Architecture | 架构决策 | "技术栈选择考量？" + 熟悉度/先进性/成熟度 | +| UX | 用户体验 | "交互复杂度取舍？" + 简洁/丰富/渐进 | +| Feasibility | 可行性 | "资源约束下的范围？" + 最小/标准/完整 | +| Risk | 风险管理 | "风险容忍度？" + 保守/平衡/激进 | +| Process | 流程规范 | "迭代节奏？" + 快速/稳定/灵活 | +| Decisions | 决策确认 | "冲突解决方案？" + 方案A/方案B/折中 | +| Terminology | 术语统一 | "统一使用哪个术语？" + 术语A/术语B | + +**Quality Rules**: + +**MUST Include**: +- ✅ All questions in Chinese (用中文提问) +- ✅ 基于跨角色分析的具体发现 +- ✅ 选项包含业务影响说明 +- ✅ 解决实际的模糊点或冲突 + +**MUST Avoid**: +- ❌ 与角色分析无关的通用问题 +- ❌ 重复已在 artifacts 阶段确认的内容 +- ❌ 过于细节的实现级问题 + +#### Step 3: Build Update Plan + +```javascript update_plan = { "role1": { - "enhancements": [EP-001, EP-003], + "enhancements": ["EP-001", "EP-003"], "clarifications": [ - {"question": "...", "answer": "...", "category": "..."}, - ... + {"question": "...", "answer": "...", "category": "..."} ] }, "role2": { - "enhancements": [EP-002], + "enhancements": ["EP-002"], "clarifications": [...] - }, - ... + } } ``` ### Phase 5: Parallel Document Update Agents -**Parallel agent calls** (one per role needing updates): +**Execute in parallel** (one agent per role): -```bash -# Execute in parallel using single message with multiple Task calls - -Task(conceptual-planning-agent): " +```javascript +// Single message with multiple Task calls for parallelism +Task(conceptual-planning-agent, ` ## Agent Mission -Apply user-confirmed enhancements and clarifications to {role1} analysis document +Apply enhancements and clarifications to ${role} analysis -## Agent Intent -- **Goal**: Integrate synthesis results into role-specific analysis -- **Scope**: Update ONLY {role1}/analysis.md (isolated, no cross-role dependencies) -- **Constraints**: Preserve original insights, add refinements without deletion +## Input +- role: ${role} +- analysis_path: ${brainstorm_dir}/${role}/analysis.md +- enhancements: ${role_enhancements} +- clarifications: ${role_clarifications} +- original_user_intent: ${intent} -## Input from Main Flow -- role: {role1} -- analysis_path: {brainstorm_dir}/{role1}/analysis.md -- enhancements: [EP-001, EP-003] (user-selected improvements) -- clarifications: [{question, answer, category}, ...] (user-confirmed answers) -- original_user_intent: {from session metadata} +## Flow Control Steps +1. load_current_analysis → Read analysis file +2. add_clarifications_section → Insert Q&A section +3. apply_enhancements → Integrate into relevant sections +4. resolve_contradictions → Remove conflicts +5. enforce_terminology → Align terminology +6. validate_intent → Verify alignment with user intent +7. write_updated_file → Save changes -## Execution Instructions -[FLOW_CONTROL] - -### Flow Control Steps -**AGENT RESPONSIBILITY**: Execute these update steps sequentially: - -1. **load_current_analysis** - - Action: Load existing role analysis document - - Command: Read({brainstorm_dir}/{role1}/analysis.md) - - Output: current_analysis_content - -2. **add_clarifications_section** - - Action: Insert Clarifications section with Q&A - - Format: \"## Clarifications\\n### Session {date}\\n- **Q**: {question} (Category: {category})\\n **A**: {answer}\" - - Output: analysis_with_clarifications - -3. **apply_enhancements** - - Action: Integrate EP-001, EP-003 into relevant sections - - Strategy: Locate section by category (Architecture → Architecture section, UX → User Experience section) - - Output: analysis_with_enhancements - -4. **resolve_contradictions** - - Action: Remove conflicts between original content and clarifications/enhancements - - Output: contradiction_free_analysis - -5. **enforce_terminology_consistency** - - Action: Align all terminology with user-confirmed choices from clarifications - - Output: terminology_consistent_analysis - -6. **validate_user_intent_alignment** - - Action: Verify all updates support original_user_intent - - Output: validated_analysis - -7. **write_updated_file** - - Action: Save final analysis document - - Command: Write({brainstorm_dir}/{role1}/analysis.md, validated_analysis) - - Output: File update confirmation - -### Output -Updated {role1}/analysis.md with Clarifications section + enhanced content -") - -Task(conceptual-planning-agent): " -## Agent Mission -Apply user-confirmed enhancements and clarifications to {role2} analysis document - -## Agent Intent -- **Goal**: Integrate synthesis results into role-specific analysis -- **Scope**: Update ONLY {role2}/analysis.md (isolated, no cross-role dependencies) -- **Constraints**: Preserve original insights, add refinements without deletion - -## Input from Main Flow -- role: {role2} -- analysis_path: {brainstorm_dir}/{role2}/analysis.md -- enhancements: [EP-002] (user-selected improvements) -- clarifications: [{question, answer, category}, ...] (user-confirmed answers) -- original_user_intent: {from session metadata} - -## Execution Instructions -[FLOW_CONTROL] - -### Flow Control Steps -**AGENT RESPONSIBILITY**: Execute same 7 update steps as {role1} agent (load → clarifications → enhancements → contradictions → terminology → validation → write) - -### Output -Updated {role2}/analysis.md with Clarifications section + enhanced content -") - -# ... repeat for each role in update_plan +## Output +Updated ${role}/analysis.md +`) ``` **Agent Characteristics**: -- **Intent**: Integrate user-confirmed synthesis results (NOT generate new analysis) -- **Isolation**: Each agent updates exactly ONE role (parallel execution safe) -- **Context**: Minimal - receives only role-specific enhancements + clarifications -- **Dependencies**: Zero cross-agent dependencies (full parallelism) +- **Isolation**: Each agent updates exactly ONE role (parallel safe) +- **Dependencies**: Zero cross-agent dependencies - **Validation**: All updates must align with original_user_intent -### Phase 6: Completion & Metadata Update +### Phase 6: Finalization -**Main flow finalizes**: +#### Step 1: Update Context Package + +```javascript +// Sync updated analyses to context-package.json +const context_pkg = Read(".workflow/active/WFS-{session}/.process/context-package.json") + +// Update guidance-specification if exists +// Update synthesis-specification if exists +// Re-read all role analysis files +// Update metadata timestamps + +Write(context_pkg_path, JSON.stringify(context_pkg)) +``` + +#### Step 2: Update Session Metadata -1. Wait for all parallel agents to complete -2. Update workflow-session.json: ```json { "phases": { @@ -330,15 +323,13 @@ Updated {role2}/analysis.md with Clarifications section + enhanced content "completed_at": "timestamp", "participating_roles": [...], "clarification_results": { - "enhancements_applied": ["EP-001", "EP-002", ...], + "enhancements_applied": ["EP-001", "EP-002"], "questions_asked": 3, - "categories_clarified": ["Architecture", "UX", ...], - "roles_updated": ["role1", "role2", ...], - "outstanding_items": [] + "categories_clarified": ["Architecture", "UX"], + "roles_updated": ["role1", "role2"] }, "quality_metrics": { "user_intent_alignment": "validated", - "requirement_coverage": "comprehensive", "ambiguity_resolution": "complete", "terminology_consistency": "enforced" } @@ -347,7 +338,8 @@ Updated {role2}/analysis.md with Clarifications section + enhanced content } ``` -3. Generate completion report (show to user): +#### Step 3: Completion Report + ```markdown ## ✅ Clarification Complete @@ -359,9 +351,11 @@ Updated {role2}/analysis.md with Clarifications section + enhanced content ✅ PROCEED: `/workflow:plan --session WFS-{session-id}` ``` +--- + ## Output -**Location**: `.workflow/active/WFS-{session}/.brainstorming/[role]/analysis*.md` (in-place updates) +**Location**: `.workflow/active/WFS-{session}/.brainstorming/[role]/analysis*.md` **Updated Structure**: ```markdown @@ -381,116 +375,24 @@ Updated {role2}/analysis.md with Clarifications section + enhanced content - Ambiguities resolved, placeholders removed - Consistent terminology -### Phase 6: Update Context Package - -**Purpose**: Sync updated role analyses to context-package.json to avoid stale cache - -**Operations**: -```bash -context_pkg_path = ".workflow/active/WFS-{session}/.process/context-package.json" - -# 1. Read existing package -context_pkg = Read(context_pkg_path) - -# 2. Re-read brainstorm artifacts (now with synthesis enhancements) -brainstorm_dir = ".workflow/active/WFS-{session}/.brainstorming" - -# 2.1 Update guidance-specification if exists -IF exists({brainstorm_dir}/guidance-specification.md): - context_pkg.brainstorm_artifacts.guidance_specification.content = Read({brainstorm_dir}/guidance-specification.md) - context_pkg.brainstorm_artifacts.guidance_specification.updated_at = NOW() - -# 2.2 Update synthesis-specification if exists -IF exists({brainstorm_dir}/synthesis-specification.md): - IF context_pkg.brainstorm_artifacts.synthesis_output: - context_pkg.brainstorm_artifacts.synthesis_output.content = Read({brainstorm_dir}/synthesis-specification.md) - context_pkg.brainstorm_artifacts.synthesis_output.updated_at = NOW() - -# 2.3 Re-read all role analysis files -role_analysis_files = Glob({brainstorm_dir}/*/analysis*.md) -context_pkg.brainstorm_artifacts.role_analyses = [] - -FOR file IN role_analysis_files: - role_name = extract_role_from_path(file) # e.g., "ui-designer" - relative_path = file.replace({brainstorm_dir}/, "") - - context_pkg.brainstorm_artifacts.role_analyses.push({ - "role": role_name, - "files": [{ - "path": relative_path, - "type": "primary", - "content": Read(file), - "updated_at": NOW() - }] - }) - -# 3. Update metadata -context_pkg.metadata.updated_at = NOW() -context_pkg.metadata.synthesis_timestamp = NOW() - -# 4. Write back -Write(context_pkg_path, JSON.stringify(context_pkg, indent=2)) - -REPORT: "✅ Updated context-package.json with synthesis results" -``` - -**TodoWrite Update**: -```json -{"content": "Update context package with synthesis results", "status": "completed", "activeForm": "Updating context package"} -``` - -## Session Metadata - -Update `workflow-session.json`: - -```json -{ - "phases": { - "BRAINSTORM": { - "status": "clarification_completed", - "clarification_completed": true, - "completed_at": "timestamp", - "participating_roles": ["product-manager", "system-architect", ...], - "clarification_results": { - "questions_asked": 3, - "categories_clarified": ["Architecture & Design", ...], - "roles_updated": ["system-architect", "ui-designer", ...], - "outstanding_items": [] - }, - "quality_metrics": { - "user_intent_alignment": "validated", - "requirement_coverage": "comprehensive", - "ambiguity_resolution": "complete", - "terminology_consistency": "enforced", - "decision_transparency": "documented" - } - } - } -} -``` +--- ## Quality Checklist **Content**: -- All role analyses loaded/analyzed -- Cross-role analysis (consensus, conflicts, gaps) -- 9-category ambiguity scan -- Questions prioritized -- Clarifications documented +- ✅ All role analyses loaded/analyzed +- ✅ Cross-role analysis (consensus, conflicts, gaps) +- ✅ 9-category ambiguity scan +- ✅ Questions prioritized **Analysis**: -- User intent validated -- Cross-role synthesis complete -- Ambiguities resolved -- Correct roles updated -- Terminology consistent -- Contradictions removed +- ✅ User intent validated +- ✅ Cross-role synthesis complete +- ✅ Ambiguities resolved +- ✅ Terminology consistent **Documents**: -- Clarifications section formatted -- Sections reflect answers -- No placeholders (TODO/TBD) -- Valid Markdown -- Cross-references maintained - - +- ✅ Clarifications section formatted +- ✅ Sections reflect answers +- ✅ No placeholders (TODO/TBD) +- ✅ Valid Markdown diff --git a/.claude/commands/workflow/init.md b/.claude/commands/workflow/init.md index 9c81c132..e5e00756 100644 --- a/.claude/commands/workflow/init.md +++ b/.claude/commands/workflow/init.md @@ -98,10 +98,10 @@ Analyze project for workflow initialization and generate .workflow/project.json. Generate complete project.json with: - project_name: ${projectName} - initialized_at: current ISO timestamp -- overview: {description, technology_stack, architecture, key_components, entry_points, metrics} +- overview: {description, technology_stack, architecture, key_components} - features: ${regenerate ? 'preserve from backup' : '[] (empty)'} +- development_index: ${regenerate ? 'preserve from backup' : '{feature: [], enhancement: [], bugfix: [], refactor: [], docs: []}'} - statistics: ${regenerate ? 'preserve from backup' : '{total_features: 0, total_sessions: 0, last_updated}'} -- memory_resources: {skills, documentation, module_docs, gaps, last_scanned} - _metadata: {initialized_by: "cli-explore-agent", analysis_timestamp, analysis_mode} ## Analysis Requirements @@ -118,28 +118,11 @@ Generate complete project.json with: - Patterns: singleton, factory, repository - Key components: 5-10 modules {name, path, description, importance} -**Metrics**: -- total_files: Source files (exclude tests/configs) -- lines_of_code: Use find + wc -l -- module_count: Use ~/.claude/scripts/get_modules_by_depth.sh -- complexity: low | medium | high - -**Entry Points**: -- main: index.ts, main.py, main.go -- cli_commands: package.json scripts, Makefile targets -- api_endpoints: HTTP/REST routes (if applicable) - -**Memory Resources**: -- skills: Scan .claude/skills/ → [{name, type, path}] -- documentation: Scan .workflow/docs/ → [{name, path, has_readme, has_architecture}] -- module_docs: Find **/CLAUDE.md (exclude node_modules, .git) -- gaps: Identify missing resources - ## Execution 1. Structural scan: get_modules_by_depth.sh, find, wc -l 2. Semantic analysis: Gemini for patterns/architecture 3. Synthesis: Merge findings -4. ${regenerate ? 'Merge with preserved features/statistics from .workflow/project.json.backup' : ''} +4. ${regenerate ? 'Merge with preserved features/development_index/statistics from .workflow/project.json.backup' : ''} 5. Write JSON: Write('.workflow/project.json', jsonContent) 6. Report: Return brief completion summary @@ -168,17 +151,6 @@ Frameworks: ${projectJson.overview.technology_stack.frameworks.join(', ')} Style: ${projectJson.overview.architecture.style} Components: ${projectJson.overview.key_components.length} core modules -### Metrics -Files: ${projectJson.overview.metrics.total_files} -LOC: ${projectJson.overview.metrics.lines_of_code} -Complexity: ${projectJson.overview.metrics.complexity} - -### Memory Resources -SKILL Packages: ${projectJson.memory_resources.skills.length} -Documentation: ${projectJson.memory_resources.documentation.length} -Module Docs: ${projectJson.memory_resources.module_docs.length} -Gaps: ${projectJson.memory_resources.gaps.join(', ') || 'none'} - --- Project state: .workflow/project.json ${regenerate ? 'Backup: .workflow/project.json.backup' : ''} diff --git a/.claude/commands/workflow/lite-execute.md b/.claude/commands/workflow/lite-execute.md index 863ae2c3..21f46ec2 100644 --- a/.claude/commands/workflow/lite-execute.md +++ b/.claude/commands/workflow/lite-execute.md @@ -556,6 +556,58 @@ codex --full-auto exec "[Verify plan acceptance criteria at ${plan.json}]" --ski - `@{plan.json}` → `@${executionContext.session.artifacts.plan}` - `[@{exploration.json}]` → exploration files from artifacts (if exists) +### Step 6: Update Development Index + +**Trigger**: After all executions complete (regardless of code review) + +**Skip Condition**: Skip if `.workflow/project.json` does not exist + +**Operations**: +```javascript +const projectJsonPath = '.workflow/project.json' +if (!fileExists(projectJsonPath)) return // Silent skip + +const projectJson = JSON.parse(Read(projectJsonPath)) + +// Initialize if needed +if (!projectJson.development_index) { + projectJson.development_index = { feature: [], enhancement: [], bugfix: [], refactor: [], docs: [] } +} + +// Detect category from keywords +function detectCategory(text) { + text = text.toLowerCase() + if (/\b(fix|bug|error|issue|crash)\b/.test(text)) return 'bugfix' + if (/\b(refactor|cleanup|reorganize)\b/.test(text)) return 'refactor' + if (/\b(doc|readme|comment)\b/.test(text)) return 'docs' + if (/\b(add|new|create|implement)\b/.test(text)) return 'feature' + return 'enhancement' +} + +// Detect sub_feature from task file paths +function detectSubFeature(tasks) { + const dirs = tasks.map(t => t.file?.split('/').slice(-2, -1)[0]).filter(Boolean) + const counts = dirs.reduce((a, d) => { a[d] = (a[d] || 0) + 1; return a }, {}) + return Object.entries(counts).sort((a, b) => b[1] - a[1])[0]?.[0] || 'general' +} + +const category = detectCategory(`${planObject.summary} ${planObject.approach}`) +const entry = { + title: planObject.summary.slice(0, 60), + sub_feature: detectSubFeature(planObject.tasks), + date: new Date().toISOString().split('T')[0], + description: planObject.approach.slice(0, 100), + status: previousExecutionResults.every(r => r.status === 'completed') ? 'completed' : 'partial', + session_id: executionContext?.session?.id || null +} + +projectJson.development_index[category].push(entry) +projectJson.statistics.last_updated = new Date().toISOString() +Write(projectJsonPath, JSON.stringify(projectJson, null, 2)) + +console.log(`✓ Development index: [${category}] ${entry.title}`) +``` + ## Best Practices **Input Modes**: In-memory (lite-plan), prompt (standalone), file (JSON/text) diff --git a/.claude/commands/workflow/lite-fix.md b/.claude/commands/workflow/lite-fix.md index 832529ed..92883f35 100644 --- a/.claude/commands/workflow/lite-fix.md +++ b/.claude/commands/workflow/lite-fix.md @@ -77,11 +77,9 @@ Phase 5: Dispatch const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() const bugSlug = bug_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40) -const timestamp = getUtc8ISOString().replace(/[:.]/g, '-') -const shortTimestamp = timestamp.substring(0, 19).replace('T', '-') // Format: 2025-11-29-14-30-25 +const dateStr = getUtc8ISOString().substring(0, 10) // Format: 2025-11-29 -// ⚠️ CRITICAL: sessionId MUST include both slug AND timestamp -const sessionId = `${bugSlug}-${shortTimestamp}` // e.g., "user-avatar-upload-fails-2025-11-29-14-30-25" +const sessionId = `${bugSlug}-${dateStr}` // e.g., "user-avatar-upload-fails-2025-11-29" const sessionFolder = `.workflow/.lite-fix/${sessionId}` bash(`mkdir -p ${sessionFolder} && test -d ${sessionFolder} && echo "SUCCESS: ${sessionFolder}" || echo "FAILED: ${sessionFolder}"`) @@ -589,7 +587,7 @@ SlashCommand(command="/workflow:lite-execute --in-memory --mode bugfix") ## Session Folder Structure ``` -.workflow/.lite-fix/{bug-slug}-{timestamp}/ +.workflow/.lite-fix/{bug-slug}-{YYYY-MM-DD}/ |- diagnosis-{angle1}.json # Diagnosis angle 1 |- diagnosis-{angle2}.json # Diagnosis angle 2 |- diagnosis-{angle3}.json # Diagnosis angle 3 (if applicable) diff --git a/.claude/commands/workflow/lite-plan.md b/.claude/commands/workflow/lite-plan.md index 52b6cb07..9c7978fc 100644 --- a/.claude/commands/workflow/lite-plan.md +++ b/.claude/commands/workflow/lite-plan.md @@ -77,11 +77,9 @@ Phase 5: Dispatch const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() const taskSlug = task_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40) -const timestamp = getUtc8ISOString().replace(/[:.]/g, '-') -const shortTimestamp = timestamp.substring(0, 19).replace('T', '-') // Format: 2025-11-29-14-30-25 +const dateStr = getUtc8ISOString().substring(0, 10) // Format: 2025-11-29 -// ⚠️ CRITICAL: sessionId MUST include both slug AND timestamp -const sessionId = `${taskSlug}-${shortTimestamp}` // e.g., "implement-jwt-refresh-2025-11-29-14-30-25" +const sessionId = `${taskSlug}-${dateStr}` // e.g., "implement-jwt-refresh-2025-11-29" const sessionFolder = `.workflow/.lite-plan/${sessionId}` bash(`mkdir -p ${sessionFolder} && test -d ${sessionFolder} && echo "SUCCESS: ${sessionFolder}" || echo "FAILED: ${sessionFolder}"`) @@ -306,28 +304,22 @@ explorations.forEach(exp => { } }) -// Deduplicate by question similarity -function deduplicateClarifications(clarifications) { - const unique = [] - clarifications.forEach(c => { - const isDuplicate = unique.some(u => - u.question.toLowerCase() === c.question.toLowerCase() - ) - if (!isDuplicate) unique.push(c) - }) - return unique -} - -const uniqueClarifications = deduplicateClarifications(allClarifications) +// Deduplicate exact same questions only +const seen = new Set() +const dedupedClarifications = allClarifications.filter(c => { + const key = c.question.toLowerCase() + if (seen.has(key)) return false + seen.add(key) + return true +}) // Multi-round clarification: batch questions (max 4 per round) -// ⚠️ MUST execute ALL rounds until uniqueClarifications exhausted -if (uniqueClarifications.length > 0) { +if (dedupedClarifications.length > 0) { const BATCH_SIZE = 4 - const totalRounds = Math.ceil(uniqueClarifications.length / BATCH_SIZE) + const totalRounds = Math.ceil(dedupedClarifications.length / BATCH_SIZE) - for (let i = 0; i < uniqueClarifications.length; i += BATCH_SIZE) { - const batch = uniqueClarifications.slice(i, i + BATCH_SIZE) + for (let i = 0; i < dedupedClarifications.length; i += BATCH_SIZE) { + const batch = dedupedClarifications.slice(i, i + BATCH_SIZE) const currentRound = Math.floor(i / BATCH_SIZE) + 1 console.log(`### Clarification Round ${currentRound}/${totalRounds}`) @@ -335,15 +327,12 @@ if (uniqueClarifications.length > 0) { AskUserQuestion({ questions: batch.map(need => ({ question: `[${need.source_angle}] ${need.question}\n\nContext: ${need.context}`, - header: need.source_angle, + header: need.source_angle.substring(0, 12), multiSelect: false, - options: need.options.map((opt, index) => { - const isRecommended = need.recommended === index - return { - label: isRecommended ? `${opt} ★` : opt, - description: isRecommended ? `Use ${opt} approach (Recommended)` : `Use ${opt} approach` - } - }) + options: need.options.map((opt, index) => ({ + label: need.recommended === index ? `${opt} ★` : opt, + description: need.recommended === index ? `Recommended` : `Use ${opt}` + })) })) }) @@ -573,7 +562,7 @@ SlashCommand(command="/workflow:lite-execute --in-memory") ## Session Folder Structure ``` -.workflow/.lite-plan/{task-slug}-{timestamp}/ +.workflow/.lite-plan/{task-slug}-{YYYY-MM-DD}/ ├── exploration-{angle1}.json # Exploration angle 1 ├── exploration-{angle2}.json # Exploration angle 2 ├── exploration-{angle3}.json # Exploration angle 3 (if applicable) diff --git a/.claude/commands/workflow/status.md b/.claude/commands/workflow/status.md index 06a70c00..c5adec27 100644 --- a/.claude/commands/workflow/status.md +++ b/.claude/commands/workflow/status.md @@ -113,11 +113,6 @@ Patterns: ${overview.architecture.patterns.join(', ')} **Key Components** (${overview.key_components.length}): ${overview.key_components.map(c => `- ${c.name} (${c.path})\n ${c.description}`).join('\n')} -**Metrics**: -- Files: ${overview.metrics.total_files} -- Lines of Code: ${overview.metrics.lines_of_code} -- Complexity: ${overview.metrics.complexity} - --- ` : ''} diff --git a/.claude/commands/workflow/tools/context-gather.md b/.claude/commands/workflow/tools/context-gather.md index b4cd5c3f..46d8ea82 100644 --- a/.claude/commands/workflow/tools/context-gather.md +++ b/.claude/commands/workflow/tools/context-gather.md @@ -251,7 +251,7 @@ Execute all discovery tracks: ### Phase 3: Synthesis, Assessment & Packaging 1. Apply relevance scoring and build dependency graph 2. **Synthesize 4-source data**: Merge findings from all sources (archive > docs > code > web). **Prioritize the context from `project.json`** for architecture and tech stack unless code analysis reveals it's outdated. -3. **Populate `project_context`**: Directly use the `overview` from `project.json` to fill the `project_context` section of the output `context-package.json`. Include technology_stack, architecture, key_components, and entry_points. +3. **Populate `project_context`**: Directly use the `overview` from `project.json` to fill the `project_context` section of the output `context-package.json`. Include description, technology_stack, architecture, and key_components. 4. Integrate brainstorm artifacts (if .brainstorming/ exists, read content) 5. Perform conflict detection with risk assessment 6. **Inject historical conflicts** from archive analysis into conflict_detection @@ -260,7 +260,7 @@ Execute all discovery tracks: ## Output Requirements Complete context-package.json with: - **metadata**: task_description, keywords, complexity, tech_stack, session_id -- **project_context**: architecture_patterns, coding_conventions, tech_stack (sourced from `project.json` overview) +- **project_context**: description, technology_stack, architecture, key_components (sourced from `project.json` overview) - **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores - **dependencies**: {internal[], external[]} with dependency graph - **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content diff --git a/.claude/commands/workflow/tools/task-generate-agent.md b/.claude/commands/workflow/tools/task-generate-agent.md index 2590abbd..94cff40d 100644 --- a/.claude/commands/workflow/tools/task-generate-agent.md +++ b/.claude/commands/workflow/tools/task-generate-agent.md @@ -132,7 +132,7 @@ Determine CLI tool usage per-step based on user's task description: ## QUALITY STANDARDS Hard Constraints: - - Task count <= 12 (hard limit - request re-scope if exceeded) + - Task count <= 18 (hard limit - request re-scope if exceeded) - All requirements quantified (explicit counts and enumerated lists) - Acceptance criteria measurable (include verification commands) - Artifact references mapped from context package diff --git a/.claude/commands/workflow/tools/task-generate-tdd.md b/.claude/commands/workflow/tools/task-generate-tdd.md index 9bd76d75..e1fe947c 100644 --- a/.claude/commands/workflow/tools/task-generate-tdd.md +++ b/.claude/commands/workflow/tools/task-generate-tdd.md @@ -42,10 +42,10 @@ Autonomous TDD task JSON and IMPL_PLAN.md generation using action-planning-agent - Different tech stacks or domains within feature ### Task Limits -- **Maximum 10 tasks** (hard limit for TDD workflows) +- **Maximum 18 tasks** (hard limit for TDD workflows) - **Feature-based**: Complete functional units with internal TDD cycles - **Hierarchy**: Flat (≤5 simple features) | Two-level (6-10 for complex features with sub-features) -- **Re-scope**: If >10 tasks needed, break project into multiple TDD workflow sessions +- **Re-scope**: If >18 tasks needed, break project into multiple TDD workflow sessions ### TDD Cycle Mapping - **Old approach**: 1 feature = 3 tasks (TEST-N.M, IMPL-N.M, REFACTOR-N.M) @@ -249,7 +249,7 @@ Refer to: @.claude/agents/action-planning-agent.md for: - Each task executes Red-Green-Refactor phases sequentially - Task count = Feature count (typically 5 features = 5 tasks) - Subtasks only when complexity >2500 lines or >6 files per cycle -- **Maximum 10 tasks** (hard limit for TDD workflows) +- **Maximum 18 tasks** (hard limit for TDD workflows) #### TDD Cycle Mapping - **Simple features**: IMPL-N with internal Red-Green-Refactor phases @@ -318,7 +318,7 @@ Refer to: @.claude/agents/action-planning-agent.md for: **Quality Gates** (Full checklist in action-planning-agent.md): - ✓ Quantification requirements enforced (explicit counts, measurable acceptance, exact targets) -- ✓ Task count ≤10 (hard limit) +- ✓ Task count ≤18 (hard limit) - ✓ Each task has meta.tdd_workflow: true - ✓ Each task has exactly 3 implementation steps with tdd_phase field - ✓ Green phase includes test-fix cycle logic diff --git a/.claude/commands/workflow/tools/test-task-generate.md b/.claude/commands/workflow/tools/test-task-generate.md index 47607d1d..060eacdd 100644 --- a/.claude/commands/workflow/tools/test-task-generate.md +++ b/.claude/commands/workflow/tools/test-task-generate.md @@ -212,7 +212,7 @@ PRIMARY requirements source - extract and map to task JSONs: ## QUALITY STANDARDS Hard Constraints: - - Task count: minimum 2, maximum 12 + - Task count: minimum 2, maximum 18 - All requirements quantified from TEST_ANALYSIS_RESULTS.md - Test framework matches existing project framework - flow_control includes reusable_test_tools and test_commands from project diff --git a/.claude/skills/command-guide/reference/commands/workflow/init.md b/.claude/skills/command-guide/reference/commands/workflow/init.md index 9c81c132..f2609bc8 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/init.md +++ b/.claude/skills/command-guide/reference/commands/workflow/init.md @@ -98,10 +98,10 @@ Analyze project for workflow initialization and generate .workflow/project.json. Generate complete project.json with: - project_name: ${projectName} - initialized_at: current ISO timestamp -- overview: {description, technology_stack, architecture, key_components, entry_points, metrics} +- overview: {description, technology_stack, architecture, key_components} - features: ${regenerate ? 'preserve from backup' : '[] (empty)'} +- development_index: ${regenerate ? 'preserve from backup' : '{feature: [], enhancement: [], bugfix: [], refactor: [], docs: []}'} - statistics: ${regenerate ? 'preserve from backup' : '{total_features: 0, total_sessions: 0, last_updated}'} -- memory_resources: {skills, documentation, module_docs, gaps, last_scanned} - _metadata: {initialized_by: "cli-explore-agent", analysis_timestamp, analysis_mode} ## Analysis Requirements @@ -118,23 +118,6 @@ Generate complete project.json with: - Patterns: singleton, factory, repository - Key components: 5-10 modules {name, path, description, importance} -**Metrics**: -- total_files: Source files (exclude tests/configs) -- lines_of_code: Use find + wc -l -- module_count: Use ~/.claude/scripts/get_modules_by_depth.sh -- complexity: low | medium | high - -**Entry Points**: -- main: index.ts, main.py, main.go -- cli_commands: package.json scripts, Makefile targets -- api_endpoints: HTTP/REST routes (if applicable) - -**Memory Resources**: -- skills: Scan .claude/skills/ → [{name, type, path}] -- documentation: Scan .workflow/docs/ → [{name, path, has_readme, has_architecture}] -- module_docs: Find **/CLAUDE.md (exclude node_modules, .git) -- gaps: Identify missing resources - ## Execution 1. Structural scan: get_modules_by_depth.sh, find, wc -l 2. Semantic analysis: Gemini for patterns/architecture @@ -168,17 +151,6 @@ Frameworks: ${projectJson.overview.technology_stack.frameworks.join(', ')} Style: ${projectJson.overview.architecture.style} Components: ${projectJson.overview.key_components.length} core modules -### Metrics -Files: ${projectJson.overview.metrics.total_files} -LOC: ${projectJson.overview.metrics.lines_of_code} -Complexity: ${projectJson.overview.metrics.complexity} - -### Memory Resources -SKILL Packages: ${projectJson.memory_resources.skills.length} -Documentation: ${projectJson.memory_resources.documentation.length} -Module Docs: ${projectJson.memory_resources.module_docs.length} -Gaps: ${projectJson.memory_resources.gaps.join(', ') || 'none'} - --- Project state: .workflow/project.json ${regenerate ? 'Backup: .workflow/project.json.backup' : ''} diff --git a/.claude/skills/command-guide/reference/commands/workflow/status.md b/.claude/skills/command-guide/reference/commands/workflow/status.md index 06a70c00..c5adec27 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/status.md +++ b/.claude/skills/command-guide/reference/commands/workflow/status.md @@ -113,11 +113,6 @@ Patterns: ${overview.architecture.patterns.join(', ')} **Key Components** (${overview.key_components.length}): ${overview.key_components.map(c => `- ${c.name} (${c.path})\n ${c.description}`).join('\n')} -**Metrics**: -- Files: ${overview.metrics.total_files} -- Lines of Code: ${overview.metrics.lines_of_code} -- Complexity: ${overview.metrics.complexity} - --- ` : ''} diff --git a/.claude/workflows/cli-templates/schemas/project-json-schema.json b/.claude/workflows/cli-templates/schemas/project-json-schema.json index a4de1144..70cbd25e 100644 --- a/.claude/workflows/cli-templates/schemas/project-json-schema.json +++ b/.claude/workflows/cli-templates/schemas/project-json-schema.json @@ -9,7 +9,6 @@ "overview", "features", "statistics", - "memory_resources", "_metadata" ], "properties": { @@ -28,9 +27,7 @@ "description", "technology_stack", "architecture", - "key_components", - "entry_points", - "metrics" + "key_components" ], "properties": { "description": { @@ -125,49 +122,6 @@ } }, "description": "5-10 core modules/components" - }, - "entry_points": { - "type": "object", - "required": ["main", "cli_commands", "api_endpoints"], - "properties": { - "main": { - "type": "string", - "description": "Primary application entry point (index.ts, main.py, etc.)" - }, - "cli_commands": { - "type": "array", - "items": {"type": "string"}, - "description": "Available CLI commands (npm start, make build, etc.)" - }, - "api_endpoints": { - "type": "array", - "items": {"type": "string"}, - "description": "HTTP/REST/GraphQL endpoints (if applicable)" - } - } - }, - "metrics": { - "type": "object", - "required": ["total_files", "lines_of_code", "module_count", "complexity"], - "properties": { - "total_files": { - "type": "integer", - "description": "Total source code files" - }, - "lines_of_code": { - "type": "integer", - "description": "Estimated total lines of code" - }, - "module_count": { - "type": "integer", - "description": "Number of top-level modules/packages" - }, - "complexity": { - "type": "string", - "enum": ["low", "medium", "high"], - "description": "Overall project complexity rating" - } - } } } }, @@ -199,6 +153,17 @@ }, "description": "Completed workflow features (populated by /workflow:session:complete)" }, + "development_index": { + "type": "object", + "description": "Categorized development history (lite-plan/lite-execute)", + "properties": { + "feature": { "type": "array", "items": { "$ref": "#/$defs/devIndexEntry" } }, + "enhancement": { "type": "array", "items": { "$ref": "#/$defs/devIndexEntry" } }, + "bugfix": { "type": "array", "items": { "$ref": "#/$defs/devIndexEntry" } }, + "refactor": { "type": "array", "items": { "$ref": "#/$defs/devIndexEntry" } }, + "docs": { "type": "array", "items": { "$ref": "#/$defs/devIndexEntry" } } + } + }, "statistics": { "type": "object", "required": ["total_features", "total_sessions", "last_updated"], @@ -218,85 +183,6 @@ } } }, - "memory_resources": { - "type": "object", - "required": ["skills", "documentation", "module_docs", "gaps", "last_scanned"], - "properties": { - "skills": { - "type": "array", - "items": { - "type": "object", - "required": ["name", "type", "path"], - "properties": { - "name": { - "type": "string", - "description": "SKILL package name" - }, - "type": { - "type": "string", - "enum": ["workflow_progress", "project_docs", "tech_stacks", "codemap", "style"], - "description": "SKILL package type" - }, - "path": { - "type": "string", - "description": "Relative path to SKILL package directory" - } - } - }, - "description": "SKILL packages generated by /memory:* commands" - }, - "documentation": { - "type": "array", - "items": { - "type": "object", - "required": ["name", "path", "has_readme", "has_architecture"], - "properties": { - "name": { - "type": "string", - "description": "Documentation project name" - }, - "path": { - "type": "string", - "description": "Path to documentation directory" - }, - "has_readme": { - "type": "boolean", - "description": "README.md exists" - }, - "has_architecture": { - "type": "boolean", - "description": "ARCHITECTURE.md exists" - } - } - }, - "description": "Documentation generated by /memory:docs" - }, - "module_docs": { - "type": "array", - "items": {"type": "string"}, - "description": "Paths to CLAUDE.md files generated by /memory:update-*" - }, - "gaps": { - "type": "array", - "items": { - "type": "string", - "enum": [ - "project_skill", - "documentation", - "tech_stack", - "workflow_history", - "module_docs_low_coverage" - ] - }, - "description": "Missing memory resources" - }, - "last_scanned": { - "type": "string", - "format": "date-time", - "description": "ISO 8601 timestamp of last memory scan" - } - } - }, "_metadata": { "type": "object", "required": ["initialized_by", "analysis_timestamp", "analysis_mode"], @@ -317,5 +203,19 @@ } } } + }, + "$defs": { + "devIndexEntry": { + "type": "object", + "required": ["title", "sub_feature", "date", "description", "status"], + "properties": { + "title": { "type": "string", "maxLength": 60 }, + "sub_feature": { "type": "string", "description": "Module/component area" }, + "date": { "type": "string", "format": "date" }, + "description": { "type": "string", "maxLength": 100 }, + "status": { "type": "string", "enum": ["completed", "partial"] }, + "session_id": { "type": "string", "description": "lite-plan session ID" } + } + } } } diff --git a/CLAUDE.md b/CLAUDE.md index dbac4313..5c6a5014 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -29,8 +29,7 @@ For all CLI tool usage, command syntax, and integration guidelines: - **Clear intent over clever code** - Be boring and obvious - **Follow existing code style** - Match import patterns, naming conventions, and formatting of existing codebase - **Minimize changes** - Only modify what's directly required; avoid refactoring, adding features, or "improving" code beyond the request -- **No unsolicited reports** - Task summaries can be performed internally, but NEVER generate additional reports, documentation files, or summary files without explicit user permission -- **Minimal documentation output** - Avoid unnecessary documentation. If required, save to .workflow/.scratchpad/ +- **No unsolicited documentation** - NEVER generate reports, documentation files, or summaries without explicit user request. If required, save to .workflow/.scratchpad/ ### Simplicity Means @@ -55,11 +54,15 @@ For all CLI tool usage, command syntax, and integration guidelines: - Use project's formatter/linter settings - Don't introduce new tools without strong justification -## Important Reminders + +### Fix, Don't Hide + +- **Solve problems, don't silence symptoms** - Skipped tests, `@ts-ignore`, empty catch, `as any`, excessive timeouts = hiding bugs, not fixing them **NEVER**: - Make assumptions - verify with existing code - Generate reports, summaries, or documentation files without explicit user request +- Use suppression mechanisms (`skip`, `ignore`, `disable`) without fixing root cause **ALWAYS**: - Plan complex tasks thoroughly before implementation @@ -74,11 +77,9 @@ For all CLI tool usage, command syntax, and integration guidelines: ## Platform-Specific Guidelines ### Windows Path Format Guidelines -- always use complete absolute Windows paths with drive letters and backslashes for ALL file operations -- **MCP Tools**: Use double backslash `D:\\path\\file.txt` (MCP doesn't support POSIX `/d/path`) -- **Bash Commands**: Use forward slash `D:/path/file.txt` or POSIX `/d/path/file.txt` -- **Relative Paths**: No conversion needed `./src`, `../config` -- **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users` +- **MCP Tools**: Double backslash `D:\\path\\file.txt` +- **Bash Commands**: Forward slash `D:/path/file.txt` or `/d/path/file.txt` +- **Relative Paths**: Universal (works in both) #### **Content Uniqueness Rules**