diff --git a/.claude/active_memory_config.json b/.claude/active_memory_config.json deleted file mode 100644 index f1b9cd57..00000000 --- a/.claude/active_memory_config.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "interval": "manual", - "tool": "gemini" -} \ No newline at end of file diff --git a/.claude/commands/enhance-prompt.md b/.claude/commands/enhance-prompt.md deleted file mode 100644 index 768563c7..00000000 --- a/.claude/commands/enhance-prompt.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -name: enhance-prompt -description: Enhanced prompt transformation using session memory and intent analysis with --enhance flag detection -argument-hint: "user input to enhance" ---- - -## Overview - -Systematically enhances user prompts by leveraging session memory context and intent analysis, translating ambiguous requests into actionable specifications. - -## Core Protocol - -**Enhancement Pipeline:** -`Intent Translation` → `Context Integration` → `Structured Output` - -**Context Sources:** -- Session memory (conversation history, previous analysis) -- Implicit technical requirements -- User intent patterns - -## Enhancement Rules - -### Intent Translation - -| User Says | Translate To | Focus | -|-----------|--------------|-------| -| "fix" | Debug and resolve | Root cause → preserve behavior | -| "improve" | Enhance/optimize | Performance/readability | -| "add" | Implement feature | Integration + edge cases | -| "refactor" | Restructure quality | Maintain behavior | -| "update" | Modernize | Version compatibility | - -### Context Integration Strategy - -**Session Memory:** -- Reference recent conversation context -- Reuse previously identified patterns -- Build on established understanding -- Infer technical requirements from discussion - -**Example:** -```bash -# User: "add login" -# Session Memory: Previous auth discussion, JWT mentioned -# Inferred: JWT-based auth, integrate with existing session management -# Action: Implement JWT authentication with session persistence -``` - -## Output Structure - -```bash -INTENT: [Clear technical goal] -CONTEXT: [Session memory + codebase patterns] -ACTION: [Specific implementation steps] -ATTENTION: [Critical constraints] -``` - -### Output Examples - -**Example 1:** -```bash -# Input: "fix login button" -INTENT: Debug non-functional login button -CONTEXT: From session - OAuth flow discussed, known state issue -ACTION: Check event binding → verify state updates → test auth flow -ATTENTION: Preserve existing OAuth integration -``` - -**Example 2:** -```bash -# Input: "refactor payment code" -INTENT: Restructure payment module for maintainability -CONTEXT: Session memory - PCI compliance requirements, Stripe integration patterns -ACTION: Extract reusable validators → isolate payment gateway logic → maintain adapter pattern -ATTENTION: Zero behavior change, maintain PCI compliance, full test coverage -``` - -## Enhancement Triggers - -- Ambiguous language: "fix", "improve", "clean up" -- Vague requests requiring clarification -- Complex technical requirements -- Architecture changes -- Critical systems: auth, payment, security -- Multi-step refactoring - -## Key Principles - -1. **Session Memory First**: Leverage conversation context and established understanding -2. **Context Reuse**: Build on previous discussions and decisions -3. **Clear Output**: Structured, actionable specifications -4. **Intent Clarification**: Transform vague requests into specific technical goals -5. **Avoid Duplication**: Reference existing context, don't repeat \ No newline at end of file diff --git a/.claude/commands/memory/code-map-memory.md b/.claude/commands/memory/code-map-memory.md deleted file mode 100644 index 0f88d4cb..00000000 --- a/.claude/commands/memory/code-map-memory.md +++ /dev/null @@ -1,687 +0,0 @@ ---- -name: code-map-memory -description: 3-phase orchestrator: parse feature keyword → cli-explore-agent analyzes (Deep Scan dual-source) → orchestrator generates Mermaid docs + SKILL package (skips phase 2 if exists) -argument-hint: "\"feature-keyword\" [--regenerate] [--tool ]" -allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*), Task(*) ---- - -# Code Flow Mapping Generator - -## Overview - -**Pure Orchestrator with Agent Delegation**: Prepares context paths and delegates code flow analysis to specialized cli-explore-agent. Orchestrator transforms agent's JSON analysis into Mermaid documentation. - -**Auto-Continue Workflow**: Runs fully autonomously once triggered. Each phase completes and automatically triggers the next phase. - -**Execution Paths**: -- **Full Path**: All 3 phases (no existing codemap OR `--regenerate` specified) -- **Skip Path**: Phase 1 → Phase 3 (existing codemap found AND no `--regenerate` flag) -- **Phase 3 Always Executes**: SKILL index is always generated or updated - -**Agent Responsibility** (cli-explore-agent): -- Deep code flow analysis using dual-source strategy (Bash + Gemini CLI) -- Returns structured JSON with architecture, functions, data flow, conditionals, patterns -- NO file writing - analysis only - -**Orchestrator Responsibility**: -- Provides feature keyword and analysis scope to agent -- Transforms agent's JSON into Mermaid-enriched markdown documentation -- Writes all files (5 docs + metadata.json + SKILL.md) - -## Core Rules - -1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution -2. **Feature-Specific SKILL**: Each feature creates independent `.claude/skills/codemap-{feature}/` package -3. **Specialized Agent**: Phase 2a uses cli-explore-agent for professional code analysis (Deep Scan mode) -4. **Orchestrator Documentation**: Phase 2b transforms agent JSON into Mermaid markdown files -5. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase -6. **No User Prompts**: Never ask user questions or wait for input between phases -7. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase -8. **Multi-Level Detail**: Generate 4 levels: architecture → function → data → conditional - ---- - -## 3-Phase Execution - -### Phase 1: Parse Feature Keyword & Check Existing - -**Goal**: Normalize feature keyword, check existing codemap, prepare for analysis - -**Step 1: Parse Feature Keyword** -```bash -# Get feature keyword from argument -FEATURE_KEYWORD="$1" - -# Normalize: lowercase, spaces to hyphens -normalized_feature=$(echo "$FEATURE_KEYWORD" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr '_' '-') - -# Example: "User Authentication" → "user-authentication" -# Example: "支付处理" → "支付处理" (keep non-ASCII) -``` - -**Step 2: Set Tool Preference** -```bash -# Default to gemini unless --tool specified -TOOL="${tool_flag:-gemini}" -``` - -**Step 3: Check Existing Codemap** -```bash -# Define codemap directory -CODEMAP_DIR=".claude/skills/codemap-${normalized_feature}" - -# Check if codemap exists -bash(test -d "$CODEMAP_DIR" && echo "exists" || echo "not_exists") - -# Count existing files -bash(find "$CODEMAP_DIR" -name "*.md" 2>/dev/null | wc -l || echo 0) -``` - -**Step 4: Skip Decision** -```javascript -if (existing_files > 0 && !regenerate_flag) { - SKIP_GENERATION = true - message = "Codemap already exists, skipping Phase 2. Use --regenerate to force regeneration." -} else if (regenerate_flag) { - bash(rm -rf "$CODEMAP_DIR") - SKIP_GENERATION = false - message = "Regenerating codemap from scratch." -} else { - SKIP_GENERATION = false - message = "No existing codemap found, generating new code flow analysis." -} -``` - -**Output Variables**: -- `FEATURE_KEYWORD`: Original feature keyword -- `normalized_feature`: Normalized feature name for directory -- `CODEMAP_DIR`: `.claude/skills/codemap-{feature}` -- `TOOL`: CLI tool to use (gemini or qwen) -- `SKIP_GENERATION`: Boolean - whether to skip Phase 2 - -**TodoWrite**: -- If skipping: Mark phase 1 completed, phase 2 completed, phase 3 in_progress -- If not skipping: Mark phase 1 completed, phase 2 in_progress - ---- - -### Phase 2: Code Flow Analysis & Documentation Generation - -**Skip Condition**: Skipped if `SKIP_GENERATION = true` - -**Goal**: Use cli-explore-agent for professional code analysis, then orchestrator generates Mermaid documentation - -**Architecture**: Phase 2a (Agent Analysis) → Phase 2b (Orchestrator Documentation) - ---- - -#### Phase 2a: cli-explore-agent Analysis - -**Purpose**: Leverage specialized cli-explore-agent for deep code flow analysis - -**Agent Task Specification**: - -``` -Task( - subagent_type: "cli-explore-agent", - description: "Analyze code flow: {FEATURE_KEYWORD}", - prompt: " -Perform Deep Scan analysis for feature: {FEATURE_KEYWORD} - -**Analysis Mode**: deep-scan (Dual-source: Bash structural scan + Gemini semantic analysis) - -**Analysis Objectives**: -1. **Module Architecture**: Identify high-level module organization, interactions, and entry points -2. **Function Call Chains**: Trace execution paths, call sequences, and parameter flows -3. **Data Transformations**: Map data structure changes and transformation stages -4. **Conditional Paths**: Document decision trees, branches, and error handling strategies -5. **Design Patterns**: Discover architectural patterns and extract design intent - -**Scope**: -- Feature: {FEATURE_KEYWORD} -- CLI Tool: {TOOL} (gemini-2.5-pro or qwen coder-model) -- File Discovery: MCP Code Index (preferred) + rg fallback -- Target: 5-15 most relevant files - -**MANDATORY FIRST STEP**: -Read: ~/.claude/workflows/cli-templates/schemas/codemap-json-schema.json - -**Output**: Return JSON following schema exactly. NO FILE WRITING - return JSON analysis only. - -**Critical Requirements**: -- Use Deep Scan mode: Bash (Phase 1 - precise locations) + Gemini CLI (Phase 2 - semantic understanding) + Synthesis (Phase 3 - merge with attribution) -- Focus exclusively on {FEATURE_KEYWORD} feature flow -- Include file:line references for ALL findings -- Extract design intent from code structure and comments -- NO FILE WRITING - return JSON analysis only -- Handle tool failures gracefully (Gemini → Qwen fallback, MCP → rg fallback) - " -) -``` - -**Agent Output**: JSON analysis result with architecture, functions, data flow, conditionals, and patterns - ---- - -#### Phase 2b: Orchestrator Documentation Generation - -**Purpose**: Transform cli-explore-agent JSON into Mermaid-enriched documentation - -**Input**: Agent's JSON analysis result - -**Process**: - -1. **Parse Agent Analysis**: - ```javascript - const analysis = JSON.parse(agentResult) - const { feature, files_analyzed, architecture, function_calls, data_flow, conditional_logic, design_patterns } = analysis - ``` - -2. **Generate Mermaid Diagrams from Structured Data**: - - **a) architecture-flow.md** (~3K tokens): - ```javascript - // Convert architecture.modules + architecture.interactions → Mermaid graph TD - const architectureMermaid = ` - graph TD - ${architecture.modules.map(m => ` ${m.name}[${m.name}]`).join('\n')} - ${architecture.interactions.map(i => ` ${i.from} -->|${i.type}| ${i.to}`).join('\n')} - ` - - Write({ - file_path: `${CODEMAP_DIR}/architecture-flow.md`, - content: `--- -feature: ${feature} -level: architecture -detail: high-level module interactions ---- -# Architecture Flow: ${feature} - -## Overview -${architecture.overview} - -## Module Architecture -${architecture.modules.map(m => `### ${m.name}\n- **File**: ${m.file}\n- **Role**: ${m.responsibility}\n- **Dependencies**: ${m.dependencies.join(', ')}`).join('\n\n')} - -## Flow Diagram -\`\`\`mermaid -${architectureMermaid} -\`\`\` - -## Key Interactions -${architecture.interactions.map(i => `- **${i.from} → ${i.to}**: ${i.description}`).join('\n')} - -## Entry Points -${architecture.entry_points.map(e => `- **${e.function}** (${e.file}): ${e.description}`).join('\n')} -` - }) - ``` - - **b) function-calls.md** (~5K tokens): - ```javascript - // Convert function_calls.sequences → Mermaid sequenceDiagram - const sequenceMermaid = ` - sequenceDiagram - ${function_calls.sequences.map(s => ` ${s.from}->>${s.to}: ${s.method}`).join('\n')} - ` - - Write({ - file_path: `${CODEMAP_DIR}/function-calls.md`, - content: `--- -feature: ${feature} -level: function -detail: function-level call sequences ---- -# Function Call Chains: ${feature} - -## Call Sequence Diagram -\`\`\`mermaid -${sequenceMermaid} -\`\`\` - -## Detailed Call Chains -${function_calls.call_chains.map(chain => ` -### Chain ${chain.chain_id}: ${chain.description} -${chain.sequence.map(fn => `- **${fn.function}** (${fn.file})\n - Calls: ${fn.calls.join(', ')}`).join('\n')} -`).join('\n')} - -## Parameters & Returns -${function_calls.sequences.map(s => `- **${s.method}** → Returns: ${s.returns || 'void'}`).join('\n')} -` - }) - ``` - - **c) data-flow.md** (~4K tokens): - ```javascript - // Convert data_flow.transformations → Mermaid flowchart LR - const dataFlowMermaid = ` - flowchart LR - ${data_flow.transformations.map((t, i) => ` Stage${i}[${t.from}] -->|${t.transformer}| Stage${i+1}[${t.to}]`).join('\n')} - ` - - Write({ - file_path: `${CODEMAP_DIR}/data-flow.md`, - content: `--- -feature: ${feature} -level: data -detail: data structure transformations ---- -# Data Flow: ${feature} - -## Data Transformation Diagram -\`\`\`mermaid -${dataFlowMermaid} -\`\`\` - -## Data Structures -${data_flow.structures.map(s => `### ${s.name} (${s.stage})\n\`\`\`json\n${JSON.stringify(s.shape, null, 2)}\n\`\`\``).join('\n\n')} - -## Transformations -${data_flow.transformations.map(t => `- **${t.from} → ${t.to}** via \`${t.transformer}\` (${t.file})`).join('\n')} -` - }) - ``` - - **d) conditional-paths.md** (~4K tokens): - ```javascript - // Convert conditional_logic.branches → Mermaid flowchart TD - const conditionalMermaid = ` - flowchart TD - Start[Entry Point] - ${conditional_logic.branches.map((b, i) => ` - Start --> Check${i}{${b.condition}} - Check${i} -->|Yes| Path${i}A[${b.true_path}] - Check${i} -->|No| Path${i}B[${b.false_path}] - `).join('\n')} - ` - - Write({ - file_path: `${CODEMAP_DIR}/conditional-paths.md`, - content: `--- -feature: ${feature} -level: conditional -detail: decision trees and error paths ---- -# Conditional Paths: ${feature} - -## Decision Tree -\`\`\`mermaid -${conditionalMermaid} -\`\`\` - -## Branch Conditions -${conditional_logic.branches.map(b => `- **${b.condition}** (${b.file})\n - True: ${b.true_path}\n - False: ${b.false_path}`).join('\n')} - -## Error Handling -${conditional_logic.error_handling.map(e => `- **${e.error_type}**: Handler \`${e.handler}\` (${e.file}) - Recovery: ${e.recovery}`).join('\n')} -` - }) - ``` - - **e) complete-flow.md** (~8K tokens): - ```javascript - // Integrate all Mermaid diagrams - Write({ - file_path: `${CODEMAP_DIR}/complete-flow.md`, - content: `--- -feature: ${feature} -level: complete -detail: integrated multi-level view ---- -# Complete Flow: ${feature} - -## Integrated Flow Diagram -\`\`\`mermaid -graph TB - subgraph Architecture - ${architecture.modules.map(m => ` ${m.name}[${m.name}]`).join('\n')} - end - - subgraph "Function Calls" - ${function_calls.call_chains[0]?.sequence.map(fn => ` ${fn.function}`).join('\n') || ''} - end - - subgraph "Data Flow" - ${data_flow.structures.map(s => ` ${s.name}[${s.name}]`).join('\n')} - end -\`\`\` - -## Complete Trace -[Comprehensive end-to-end documentation combining all analysis layers] - -## Design Patterns Identified -${design_patterns.map(p => `- **${p.pattern}** in ${p.location}: ${p.description}`).join('\n')} - -## Recommendations -${analysis.recommendations.map(r => `- ${r}`).join('\n')} - -## Cross-References -- [Architecture Flow](./architecture-flow.md) - High-level module structure -- [Function Calls](./function-calls.md) - Detailed call chains -- [Data Flow](./data-flow.md) - Data transformation stages -- [Conditional Paths](./conditional-paths.md) - Decision trees and error handling -` - }) - ``` - -3. **Write metadata.json**: - ```javascript - Write({ - file_path: `${CODEMAP_DIR}/metadata.json`, - content: JSON.stringify({ - feature: feature, - normalized_name: normalized_feature, - generated_at: new Date().toISOString(), - tool_used: analysis.analysis_metadata.tool_used, - files_analyzed: files_analyzed.map(f => f.file), - analysis_summary: { - total_files: files_analyzed.length, - modules_traced: architecture.modules.length, - functions_traced: function_calls.call_chains.reduce((sum, c) => sum + c.sequence.length, 0), - patterns_discovered: design_patterns.length - } - }, null, 2) - }) - ``` - -4. **Report Phase 2 Completion**: - ``` - Phase 2 Complete: Code flow analysis and documentation generated - - - Agent Analysis: cli-explore-agent with {TOOL} - - Files Analyzed: {count} - - Documentation Generated: 5 markdown files + metadata.json - - Location: {CODEMAP_DIR} - ``` - -**Completion Criteria**: -- cli-explore-agent task completed successfully with JSON result -- 5 documentation files written with valid Mermaid diagrams -- metadata.json written with analysis summary -- All files properly formatted and cross-referenced - -**TodoWrite**: Mark phase 2 completed, phase 3 in_progress - ---- - -### Phase 3: Generate SKILL.md Index - -**Note**: This phase **ALWAYS executes** - generates or updates the SKILL index. - -**Goal**: Read generated flow documentation and create SKILL.md index with progressive loading - -**Steps**: - -1. **Verify Generated Files**: - ```bash - bash(find "{CODEMAP_DIR}" -name "*.md" -type f | sort) - ``` - -2. **Read metadata.json**: - ```javascript - Read({CODEMAP_DIR}/metadata.json) - // Extract: feature, normalized_name, files_analyzed, analysis_summary - ``` - -3. **Read File Headers** (optional, first 30 lines): - ```javascript - Read({CODEMAP_DIR}/architecture-flow.md, limit: 30) - Read({CODEMAP_DIR}/function-calls.md, limit: 30) - // Extract overview and diagram counts - ``` - -4. **Generate SKILL.md Index**: - - Template structure: - ```yaml - --- - name: codemap-{normalized_feature} - description: Code flow mapping for {FEATURE_KEYWORD} feature (located at {project_path}). Load this SKILL when analyzing, tracing, or understanding {FEATURE_KEYWORD} execution flow, especially when no relevant context exists in memory. - version: 1.0.0 - generated_at: {ISO_TIMESTAMP} - --- - # Code Flow Map: {FEATURE_KEYWORD} - - ## Feature: `{FEATURE_KEYWORD}` - - **Analysis Date**: {DATE} - **Tool Used**: {TOOL} - **Files Analyzed**: {COUNT} - - ## Progressive Loading - - ### Level 0: Quick Overview (~2K tokens) - - [Architecture Flow](./architecture-flow.md) - High-level module interactions - - ### Level 1: Core Flows (~10K tokens) - - [Architecture Flow](./architecture-flow.md) - Module architecture - - [Function Calls](./function-calls.md) - Function call chains - - ### Level 2: Complete Analysis (~20K tokens) - - [Architecture Flow](./architecture-flow.md) - - [Function Calls](./function-calls.md) - - [Data Flow](./data-flow.md) - Data transformations - - ### Level 3: Deep Dive (~30K tokens) - - [Architecture Flow](./architecture-flow.md) - - [Function Calls](./function-calls.md) - - [Data Flow](./data-flow.md) - - [Conditional Paths](./conditional-paths.md) - Branches and error handling - - [Complete Flow](./complete-flow.md) - Integrated comprehensive view - - ## Usage - - Load this SKILL package when: - - Analyzing {FEATURE_KEYWORD} implementation - - Tracing execution flow for debugging - - Understanding code dependencies - - Planning refactoring or enhancements - - ## Analysis Summary - - - **Modules Traced**: {modules_traced} - - **Functions Traced**: {functions_traced} - - **Files Analyzed**: {total_files} - - ## Mermaid Diagrams Included - - - Architecture flow diagram (graph TD) - - Function call sequence diagram (sequenceDiagram) - - Data transformation flowchart (flowchart LR) - - Conditional decision tree (flowchart TD) - - Complete integrated diagram (graph TB) - ``` - -5. **Write SKILL.md**: - ```javascript - Write({ - file_path: `{CODEMAP_DIR}/SKILL.md`, - content: generatedIndexMarkdown - }) - ``` - -**Completion Criteria**: -- SKILL.md index written -- All documentation files verified -- Progressive loading levels (0-3) properly structured -- Mermaid diagram references included - -**TodoWrite**: Mark phase 3 completed - -**Final Report**: -``` -Code Flow Mapping Complete - -Feature: {FEATURE_KEYWORD} -Location: .claude/skills/codemap-{normalized_feature}/ - -Files Generated: -- SKILL.md (index) -- architecture-flow.md (with Mermaid diagram) -- function-calls.md (with Mermaid sequence diagram) -- data-flow.md (with Mermaid flowchart) -- conditional-paths.md (with Mermaid decision tree) -- complete-flow.md (with integrated Mermaid diagram) -- metadata.json - -Analysis: -- Files analyzed: {count} -- Modules traced: {count} -- Functions traced: {count} - -Usage: Skill(command: "codemap-{normalized_feature}") -``` - ---- - -## Implementation Details - -### TodoWrite Patterns - -**Initialization** (Before Phase 1): -```javascript -TodoWrite({todos: [ - {"content": "Parse feature keyword and check existing", "status": "in_progress", "activeForm": "Parsing feature keyword"}, - {"content": "Agent analyzes code flow and generates files", "status": "pending", "activeForm": "Analyzing code flow"}, - {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL index"} -]}) -``` - -**Full Path** (SKIP_GENERATION = false): -```javascript -// After Phase 1 -TodoWrite({todos: [ - {"content": "Parse feature keyword and check existing", "status": "completed", ...}, - {"content": "Agent analyzes code flow and generates files", "status": "in_progress", ...}, - {"content": "Generate SKILL.md index", "status": "pending", ...} -]}) - -// After Phase 2 -TodoWrite({todos: [ - {"content": "Parse feature keyword and check existing", "status": "completed", ...}, - {"content": "Agent analyzes code flow and generates files", "status": "completed", ...}, - {"content": "Generate SKILL.md index", "status": "in_progress", ...} -]}) - -// After Phase 3 -TodoWrite({todos: [ - {"content": "Parse feature keyword and check existing", "status": "completed", ...}, - {"content": "Agent analyzes code flow and generates files", "status": "completed", ...}, - {"content": "Generate SKILL.md index", "status": "completed", ...} -]}) -``` - -**Skip Path** (SKIP_GENERATION = true): -```javascript -// After Phase 1 (skip Phase 2) -TodoWrite({todos: [ - {"content": "Parse feature keyword and check existing", "status": "completed", ...}, - {"content": "Agent analyzes code flow and generates files", "status": "completed", ...}, // Skipped - {"content": "Generate SKILL.md index", "status": "in_progress", ...} -]}) -``` - -### Execution Flow - -**Full Path**: -``` -User → TodoWrite Init → Phase 1 (parse) → Phase 2 (agent analyzes) → Phase 3 (write index) → Report -``` - -**Skip Path**: -``` -User → TodoWrite Init → Phase 1 (detect existing) → Phase 3 (update index) → Report -``` - -### Error Handling - -**Phase 1 Errors**: -- Empty feature keyword: Report error, ask user to provide feature description -- Invalid characters: Normalize and continue - -**Phase 2 Errors (Agent)**: -- Agent task fails: Retry once, report if fails again -- No files discovered: Warn user, ask for more specific feature keyword -- CLI failures: Agent handles internally with retries -- Invalid Mermaid syntax: Agent validates before writing - -**Phase 3 Errors**: -- Write failures: Report which files failed -- Missing files: Note in SKILL.md, suggest regeneration - ---- - -## Parameters - -```bash -/memory:code-map-memory "feature-keyword" [--regenerate] [--tool ] -``` - -**Arguments**: -- **"feature-keyword"**: Feature or flow to analyze (required) - - Examples: `"user authentication"`, `"payment processing"`, `"数据导入流程"` - - Can be English, Chinese, or mixed - - Spaces and underscores normalized to hyphens -- **--regenerate**: Force regenerate existing codemap (deletes and recreates) -- **--tool**: CLI tool for analysis (default: gemini) - - `gemini`: Comprehensive flow analysis with gemini-2.5-pro - - `qwen`: Alternative with coder-model - ---- - -## Examples - -**Generated File Structure** (for all examples): -``` -.claude/skills/codemap-{feature}/ -├── SKILL.md # Index (Phase 3) -├── architecture-flow.md # Agent (Phase 2) - High-level flow -├── function-calls.md # Agent (Phase 2) - Function chains -├── data-flow.md # Agent (Phase 2) - Data transformations -├── conditional-paths.md # Agent (Phase 2) - Branches & errors -├── complete-flow.md # Agent (Phase 2) - Integrated view -└── metadata.json # Agent (Phase 2) -``` - -### Example 1: User Authentication Flow - -```bash -/memory:code-map-memory "user authentication" -``` - -**Workflow**: -1. Phase 1: Normalizes to "user-authentication", checks existing codemap -2. Phase 2: Agent discovers auth-related files, executes CLI analysis, generates 5 flow docs with Mermaid -3. Phase 3: Generates SKILL.md index with progressive loading - -**Output**: `.claude/skills/codemap-user-authentication/` with 6 files + metadata - - -### Example 3: Regenerate with Qwen - -```bash -/memory:code-map-memory "payment processing" --regenerate --tool qwen -``` - -**Workflow**: -1. Phase 1: Deletes existing codemap due to --regenerate -2. Phase 2: Agent uses qwen with coder-model for fresh analysis -3. Phase 3: Generates updated SKILL.md - ---- - - -## Architecture - -``` -code-map-memory (orchestrator) - ├─ Phase 1: Parse & Check (bash commands, skip decision) - ├─ Phase 2: Code Analysis & Documentation (skippable) - │ ├─ Phase 2a: cli-explore-agent Analysis - │ │ └─ Deep Scan: Bash structural + Gemini semantic → JSON - │ └─ Phase 2b: Orchestrator Documentation - │ └─ Transform JSON → 5 Mermaid markdown files + metadata.json - └─ Phase 3: Write SKILL.md (index generation, always runs) - -Output: .claude/skills/codemap-{feature}/ -``` diff --git a/.claude/commands/memory/docs.md b/.claude/commands/memory/docs.md deleted file mode 100644 index b7ca1798..00000000 --- a/.claude/commands/memory/docs.md +++ /dev/null @@ -1,615 +0,0 @@ ---- -name: docs -description: Plan documentation workflow with dynamic grouping (≤10 docs/task), generates IMPL tasks for parallel module trees, README, ARCHITECTURE, and HTTP API docs -argument-hint: "[path] [--tool ] [--mode ] [--cli-execute]" ---- - -# Documentation Workflow (/memory:docs) - -## Overview -Lightweight planner that analyzes project structure, decomposes documentation work into tasks, and generates execution plans. Does NOT generate documentation content itself - delegates to doc-generator agent. - -**Execution Strategy**: -- **Dynamic Task Grouping**: Level 1 tasks grouped by top-level directories with document count limit - - **Primary constraint**: Each task generates ≤10 documents (API.md + README.md count) - - **Optimization goal**: Prefer grouping 2 top-level directories per task for context sharing - - **Conflict resolution**: If 2 dirs exceed 10 docs, reduce to 1 dir/task; if 1 dir exceeds 10 docs, split by subdirectories - - **Context benefit**: Same-task directories analyzed together via single Gemini call -- **Parallel Execution**: Multiple Level 1 tasks execute concurrently for faster completion -- **Pre-computed Analysis**: Phase 2 performs unified analysis once, stored in `.process/` for reuse -- **Efficient Data Loading**: All existing docs loaded once in Phase 2, shared across tasks - -**Path Mirroring**: Documentation structure mirrors source code under `.workflow/docs/{project_name}/` -- Example: `my_app/src/core/` → `.workflow/docs/my_app/src/core/API.md` - -**Two Execution Modes**: -- **Default (Agent Mode)**: CLI analyzes in `pre_analysis` (MODE=analysis), agent writes docs -- **--cli-execute (CLI Mode)**: CLI generates docs in `implementation_approach` (MODE=write), agent executes CLI commands - -## Path Mirroring Strategy - -**Principle**: Documentation structure **mirrors** source code structure under project-specific directory. - -| Source Path | Project Name | Documentation Path | -|------------|--------------|-------------------| -| `my_app/src/core/` | `my_app` | `.workflow/docs/my_app/src/core/API.md` | -| `my_app/src/modules/auth/` | `my_app` | `.workflow/docs/my_app/src/modules/auth/API.md` | -| `another_project/lib/utils/` | `another_project` | `.workflow/docs/another_project/lib/utils/API.md` | - - -## Parameters - -```bash -/memory:docs [path] [--tool ] [--mode ] [--cli-execute] -``` - -- **path**: Source directory to analyze (default: current directory) - - Specifies the source code directory to be documented - - Documentation is generated in a separate `.workflow/docs/{project_name}/` directory at the workspace root, **not** within the source `path` itself - - The source path's structure is mirrored within the project-specific documentation folder - - Example: analyzing `src/modules` produces documentation at `.workflow/docs/{project_name}/src/modules/` -- **--mode**: Documentation generation mode (default: full) - - `full`: Complete documentation (modules + README + ARCHITECTURE + EXAMPLES + HTTP API) - - `partial`: Module documentation only (API.md + README.md) -- **--tool**: CLI tool selection (default: gemini) - - `gemini`: Comprehensive documentation, pattern recognition - - `qwen`: Architecture analysis, system design focus - - `codex`: Implementation validation, code quality -- **--cli-execute**: Enable CLI-based documentation generation (optional) - -## Planning Workflow - -### Phase 1: Initialize Session - -```bash -# Get target path, project name, and root -bash(pwd && basename "$(pwd)" && git rev-parse --show-toplevel 2>/dev/null || pwd && date +%Y%m%d-%H%M%S) -``` - -```javascript -// Create docs session (type: docs) -SlashCommand(command="/workflow:session:start --type docs --new \"{project_name}-docs-{timestamp}\"") -// Parse output to get sessionId -``` - -```bash -# Update workflow-session.json with docs-specific fields -bash(jq '. + {"target_path":"{target_path}","project_root":"{project_root}","project_name":"{project_name}","mode":"full","tool":"gemini","cli_execute":false}' .workflow/active/{sessionId}/workflow-session.json > tmp.json && mv tmp.json .workflow/active/{sessionId}/workflow-session.json) -``` - -### Phase 2: Analyze Structure - -**Smart filter**: Auto-detect and skip tests/build/config/vendor based on project tech stack. - -**Commands** (collect data with simple bash): - -```bash -# 1. Run folder analysis -bash(ccw tool exec get_modules_by_depth '{}' | ccw tool exec classify_folders '{}') - -# 2. Get top-level directories (first 2 path levels) -bash(ccw tool exec get_modules_by_depth '{}' | ccw tool exec classify_folders '{}' | awk -F'|' '{print $1}' | sed 's|^\./||' | awk -F'/' '{if(NF>=2) print $1"/"$2; else if(NF==1) print $1}' | sort -u) - -# 3. Find existing docs (if directory exists) -bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${project_name} -type f -name "*.md" ! -path "*/README.md" ! -path "*/ARCHITECTURE.md" ! -path "*/EXAMPLES.md" ! -path "*/api/*" 2>/dev/null; fi) - -# 4. Read existing docs content (if files exist) -bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${project_name} -type f -name "*.md" ! -path "*/README.md" ! -path "*/ARCHITECTURE.md" ! -path "*/EXAMPLES.md" ! -path "*/api/*" 2>/dev/null | xargs cat 2>/dev/null; fi) -``` - -**Data Processing**: Parse bash outputs, calculate statistics, use **Write tool** to create `${session_dir}/.process/doc-planning-data.json` with structure: - -```json -{ - "metadata": { - "generated_at": "2025-11-03T16:57:30.469669", - "project_name": "project_name", - "project_root": "/path/to/project" - }, - "folder_analysis": [ - {"path": "./src/core", "type": "code", "code_count": 5, "dirs_count": 2} - ], - "top_level_dirs": ["src/modules", "lib/core"], - "existing_docs": { - "file_list": [".workflow/docs/project/src/core/API.md"], - "content": "... existing docs content ..." - }, - "unified_analysis": [], - "statistics": { - "total": 15, - "code": 8, - "navigation": 7, - "top_level": 3 - } -} -``` - -**Then** use **Edit tool** to update `workflow-session.json` adding analysis field. - -**Output**: Single `doc-planning-data.json` with all analysis data (no temp files or Python scripts). - -**Auto-skipped**: Tests (`**/test/**`, `**/*.test.*`), Build (`**/node_modules/**`, `**/dist/**`), Config (root-level files), Vendor directories. - -### Phase 3: Detect Update Mode - -**Commands**: - -```bash -# Count existing docs from doc-planning-data.json -bash(cat .workflow/active/WFS-docs-{timestamp}/.process/doc-planning-data.json | jq '.existing_docs.file_list | length') -``` - -**Data Processing**: Use count result, then use **Edit tool** to update `workflow-session.json`: -- Add `"update_mode": "update"` if count > 0, else `"create"` -- Add `"existing_docs": ` - -### Phase 4: Decompose Tasks - -**Task Hierarchy** (Dynamic based on document count): - -``` -Small Projects (total ≤10 docs): - Level 1: IMPL-001 (all directories in single task, shared context) - Level 2: IMPL-002 (README, full mode only) - Level 3: IMPL-003 (ARCHITECTURE+EXAMPLES), IMPL-004 (HTTP API, optional) - -Medium Projects (Example: 7 top-level dirs, 18 total docs): - Step 1: Count docs per top-level dir - ├─ dir1: 3 docs, dir2: 4 docs → Group 1 (7 docs) - ├─ dir3: 5 docs, dir4: 3 docs → Group 2 (8 docs) - ├─ dir5: 2 docs → Group 3 (2 docs, can add more) - - Step 2: Create tasks with ≤10 docs constraint - Level 1: IMPL-001 to IMPL-003 (parallel groups) - ├─ IMPL-001: Group 1 (dir1 + dir2, 7 docs, shared context) - ├─ IMPL-002: Group 2 (dir3 + dir4, 8 docs, shared context) - └─ IMPL-003: Group 3 (remaining dirs, ≤10 docs) - Level 2: IMPL-004 (README, depends on Level 1, full mode only) - Level 3: IMPL-005 (ARCHITECTURE+EXAMPLES), IMPL-006 (HTTP API, optional) - -Large Projects (single dir >10 docs): - Step 1: Detect oversized directory - └─ src/modules/: 15 subdirs → 30 docs (exceeds limit) - - Step 2: Split by subdirectories - Level 1: IMPL-001 to IMPL-003 (split oversized dir) - ├─ IMPL-001: src/modules/ subdirs 1-5 (10 docs) - ├─ IMPL-002: src/modules/ subdirs 6-10 (10 docs) - └─ IMPL-003: src/modules/ subdirs 11-15 (10 docs) -``` - -**Grouping Algorithm**: -1. Count total docs for each top-level directory -2. Try grouping 2 directories (optimization for context sharing) -3. If group exceeds 10 docs, split to 1 dir/task -4. If single dir exceeds 10 docs, split by subdirectories -5. Create parallel Level 1 tasks with ≤10 docs each - - -**Commands**: - -```bash -# 1. Get top-level directories from doc-planning-data.json -bash(cat .workflow/active/WFS-docs-{timestamp}/.process/doc-planning-data.json | jq -r '.top_level_dirs[]') - -# 2. Get mode from workflow-session.json -bash(cat .workflow/active/WFS-docs-{timestamp}/workflow-session.json | jq -r '.mode // "full"') - -# 3. Check for HTTP API -bash(grep -r "router\.|@Get\|@Post" src/ 2>/dev/null && echo "API_FOUND" || echo "NO_API") -``` - -**Data Processing**: -1. Count documents for each top-level directory (from folder_analysis): - - Code folders: 2 docs each (API.md + README.md) - - Navigation folders: 1 doc each (README.md only) -2. Apply grouping algorithm with ≤10 docs constraint: - - Try grouping 2 directories, calculate total docs - - If total ≤10 docs: create group - - If total >10 docs: split to 1 dir/group or subdivide - - If single dir >10 docs: split by subdirectories -3. Use **Edit tool** to update `doc-planning-data.json` adding groups field: - ```json - "groups": { - "count": 3, - "assignments": [ - {"group_id": "001", "directories": ["src/modules", "src/utils"], "doc_count": 5}, - {"group_id": "002", "directories": ["lib/core"], "doc_count": 6}, - {"group_id": "003", "directories": ["lib/helpers"], "doc_count": 3} - ] - } - ``` - -**Task ID Calculation**: -```bash -group_count=$(jq '.groups.count' .workflow/active/WFS-docs-{timestamp}/.process/doc-planning-data.json) -readme_id=$((group_count + 1)) # Next ID after groups -arch_id=$((group_count + 2)) -api_id=$((group_count + 3)) -``` - -### Phase 5: Generate Task JSONs - -**CLI Strategy**: - -| Mode | cli_execute | Placement | CLI MODE | Approval Flag | Agent Role | -|------|-------------|-----------|----------|---------------|------------| -| **Agent** | false | pre_analysis | analysis | (none) | Generate docs in implementation_approach | -| **CLI** | true | implementation_approach | write | --mode write | Execute CLI commands, validate output | - -**Command Patterns**: -- Gemini/Qwen: `ccw cli -p "..." --tool gemini --mode analysis --cd dir` -- CLI Mode: `ccw cli -p "..." --tool gemini --mode write --cd dir` -- Codex: `ccw cli -p "..." --tool codex --mode write --cd dir` - -**Generation Process**: -1. Read configuration values (tool, cli_execute, mode) from workflow-session.json -2. Read group assignments from doc-planning-data.json -3. Generate Level 1 tasks (IMPL-001 to IMPL-N, one per group) -4. Generate Level 2+ tasks if mode=full (README, ARCHITECTURE, HTTP API) - -## Task Templates - -### Level 1: Module Trees Group Task (Unified) - -**Execution Model**: Each task processes assigned directory group (max 2 directories) using pre-analyzed data from Phase 2. - -```json -{ - "id": "IMPL-${group_number}", - "title": "Document Module Trees Group ${group_number}", - "status": "pending", - "meta": { - "type": "docs-tree-group", - "agent": "@doc-generator", - "tool": "gemini", - "cli_execute": false, - "group_number": "${group_number}", - "total_groups": "${total_groups}" - }, - "context": { - "requirements": [ - "Process directories from group ${group_number} in doc-planning-data.json", - "Generate docs to .workflow/docs/${project_name}/ (mirrored structure)", - "Code folders: API.md + README.md; Navigation folders: README.md only", - "Use pre-analyzed data from Phase 2 (no redundant analysis)" - ], - "focus_paths": ["${group_dirs_from_json}"], - "precomputed_data": { - "phase2_analysis": "${session_dir}/.process/doc-planning-data.json" - } - }, - "flow_control": { - "pre_analysis": [ - { - "step": "load_precomputed_data", - "action": "Load Phase 2 analysis and extract group directories", - "commands": [ - "bash(cat ${session_dir}/.process/doc-planning-data.json)", - "bash(jq '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories' ${session_dir}/.process/doc-planning-data.json)" - ], - "output_to": "phase2_context", - "note": "Single JSON file contains all Phase 2 analysis results" - } - ], - "implementation_approach": [ - { - "step": 1, - "title": "Generate documentation for assigned directory group", - "description": "Process directories in Group ${group_number} using pre-analyzed data", - "modification_points": [ - "Read group directories from [phase2_context].groups.assignments[${group_number}].directories", - "For each directory: parse folder types from folder_analysis, parse structure from unified_analysis", - "Map source_path to .workflow/docs/${project_name}/{path}", - "Generate API.md for code folders, README.md for all folders", - "Preserve user modifications from [phase2_context].existing_docs.content" - ], - "logic_flow": [ - "phase2 = parse([phase2_context])", - "dirs = phase2.groups.assignments[${group_number}].directories", - "for dir in dirs:", - " folder_info = find(dir, phase2.folder_analysis)", - " outline = find(dir, phase2.unified_analysis)", - " if folder_info.type == 'code': generate API.md + README.md", - " elif folder_info.type == 'navigation': generate README.md only", - " write to .workflow/docs/${project_name}/{dir}/" - ], - "depends_on": [], - "output": "group_module_docs" - } - ], - "target_files": [ - ".workflow/docs/${project_name}/*/API.md", - ".workflow/docs/${project_name}/*/README.md" - ] - } -} -``` - -**CLI Execute Mode Note**: When `cli_execute=true`, add Step 2 in `implementation_approach`: -```json -{ - "step": 2, - "title": "Batch generate documentation via CLI", - "command": "ccw cli -p 'PURPOSE: Generate module docs\\nTASK: Create documentation\\nMODE: write\\nCONTEXT: @**/* [phase2_context]\\nEXPECTED: API.md and README.md\\nRULES: Mirror structure' --tool gemini --mode write --cd ${dirs_from_group}", - "depends_on": [1], - "output": "generated_docs" -} -``` - -### Level 2: Project README Task - -**Task ID**: `IMPL-${readme_id}` (where `readme_id = group_count + 1`) -**Dependencies**: Depends on all Level 1 tasks completing. - -```json -{ - "id": "IMPL-${readme_id}", - "title": "Generate Project README", - "status": "pending", - "depends_on": ["IMPL-001", "...", "IMPL-${group_count}"], - "meta": {"type": "docs", "agent": "@doc-generator", "tool": "gemini", "cli_execute": false}, - "flow_control": { - "pre_analysis": [ - { - "step": "load_existing_readme", - "command": "bash(cat .workflow/docs/${project_name}/README.md 2>/dev/null || echo 'No existing README')", - "output_to": "existing_readme" - }, - { - "step": "load_module_docs", - "command": "bash(find .workflow/docs/${project_name} -type f -name '*.md' ! -path '.workflow/docs/${project_name}/README.md' ! -path '.workflow/docs/${project_name}/ARCHITECTURE.md' ! -path '.workflow/docs/${project_name}/EXAMPLES.md' ! -path '.workflow/docs/${project_name}/api/*' | xargs cat)", - "output_to": "all_module_docs" - }, - { - "step": "analyze_project", - "command": "bash(ccw cli -p \"PURPOSE: Analyze project structure\\nTASK: Extract overview from modules\\nMODE: analysis\\nCONTEXT: [all_module_docs]\\nEXPECTED: Project outline\" --tool gemini --mode analysis)", - "output_to": "project_outline" - } - ], - "implementation_approach": [ - { - "step": 1, - "title": "Generate project README", - "description": "Generate project README with navigation links while preserving user modifications", - "modification_points": [ - "Parse [project_outline] and [all_module_docs]", - "Generate README structure with navigation links", - "Preserve [existing_readme] user modifications" - ], - "logic_flow": ["Parse data", "Generate README with navigation", "Preserve modifications"], - "depends_on": [], - "output": "project_readme" - } - ], - "target_files": [".workflow/docs/${project_name}/README.md"] - } -} -``` - -### Level 3: Architecture & Examples Documentation Task - -**Task ID**: `IMPL-${arch_id}` (where `arch_id = group_count + 2`) -**Dependencies**: Depends on Level 2 (Project README). - -```json -{ - "id": "IMPL-${arch_id}", - "title": "Generate Architecture & Examples Documentation", - "status": "pending", - "depends_on": ["IMPL-${readme_id}"], - "meta": {"type": "docs", "agent": "@doc-generator", "tool": "gemini", "cli_execute": false}, - "flow_control": { - "pre_analysis": [ - {"step": "load_existing_docs", "command": "bash(cat .workflow/docs/${project_name}/{ARCHITECTURE,EXAMPLES}.md 2>/dev/null || echo 'No existing docs')", "output_to": "existing_arch_examples"}, - {"step": "load_all_docs", "command": "bash(cat .workflow/docs/${project_name}/README.md && find .workflow/docs/${project_name} -type f -name '*.md' ! -path '*/README.md' ! -path '*/ARCHITECTURE.md' ! -path '*/EXAMPLES.md' ! -path '*/api/*' | xargs cat)", "output_to": "all_docs"}, - {"step": "analyze_architecture", "command": "bash(ccw cli -p \"PURPOSE: Analyze system architecture\\nTASK: Synthesize architectural overview and examples\\nMODE: analysis\\nCONTEXT: [all_docs]\\nEXPECTED: Architecture + Examples outline\" --tool gemini --mode analysis)", "output_to": "arch_examples_outline"} - ], - "implementation_approach": [ - { - "step": 1, - "title": "Generate architecture and examples documentation", - "modification_points": [ - "Parse [arch_examples_outline] and [all_docs]", - "Generate ARCHITECTURE.md (system design, patterns)", - "Generate EXAMPLES.md (code snippets, usage)", - "Preserve [existing_arch_examples] modifications" - ], - "depends_on": [], - "output": "arch_examples_docs" - } - ], - "target_files": [".workflow/docs/${project_name}/ARCHITECTURE.md", ".workflow/docs/${project_name}/EXAMPLES.md"] - } -} -``` - -### Level 4: HTTP API Documentation Task (Optional) - -**Task ID**: `IMPL-${api_id}` (where `api_id = group_count + 3`) -**Dependencies**: Depends on Level 3. - -```json -{ - "id": "IMPL-${api_id}", - "title": "Generate HTTP API Documentation", - "status": "pending", - "depends_on": ["IMPL-${arch_id}"], - "meta": {"type": "docs", "agent": "@doc-generator", "tool": "gemini", "cli_execute": false}, - "flow_control": { - "pre_analysis": [ - {"step": "discover_api", "command": "bash(rg 'router\\.| @(Get|Post)' -g '*.{ts,js}')", "output_to": "endpoint_discovery"}, - {"step": "load_existing_api", "command": "bash(cat .workflow/docs/${project_name}/api/README.md 2>/dev/null || echo 'No existing API docs')", "output_to": "existing_api_docs"}, - {"step": "analyze_api", "command": "bash(ccw cli -p \"PURPOSE: Document HTTP API\\nTASK: Analyze endpoints\\nMODE: analysis\\nCONTEXT: @src/api/**/* [endpoint_discovery]\\nEXPECTED: API outline\" --tool gemini --mode analysis)", "output_to": "api_outline"} - ], - "implementation_approach": [ - { - "step": 1, - "title": "Generate HTTP API documentation", - "modification_points": [ - "Parse [api_outline] and [endpoint_discovery]", - "Document endpoints, request/response formats", - "Preserve [existing_api_docs] modifications" - ], - "depends_on": [], - "output": "api_docs" - } - ], - "target_files": [".workflow/docs/${project_name}/api/README.md"] - } -} -``` - -## Session Structure - -**Unified Structure** (single JSON replaces multiple text files): - -``` -.workflow/active/ -└── WFS-docs-{timestamp}/ - ├── workflow-session.json # Session metadata - ├── IMPL_PLAN.md - ├── TODO_LIST.md - ├── .process/ - │ └── doc-planning-data.json # All Phase 2 analysis data (replaces 7+ files) - └── .task/ - ├── IMPL-001.json # Small: all modules | Large: group 1 - ├── IMPL-00N.json # (Large only: groups 2-N) - ├── IMPL-{N+1}.json # README (full mode) - ├── IMPL-{N+2}.json # ARCHITECTURE+EXAMPLES (full mode) - └── IMPL-{N+3}.json # HTTP API (optional) -``` - -**doc-planning-data.json Structure**: -```json -{ - "metadata": { - "generated_at": "2025-11-03T16:41:06+08:00", - "project_name": "Claude_dms3", - "project_root": "/d/Claude_dms3" - }, - "folder_analysis": [ - {"path": "./src/core", "type": "code", "code_count": 5, "dirs_count": 2}, - {"path": "./src/utils", "type": "navigation", "code_count": 0, "dirs_count": 4} - ], - "top_level_dirs": ["src/modules", "src/utils", "lib/core"], - "existing_docs": { - "file_list": [".workflow/docs/project/src/core/API.md"], - "content": "... concatenated existing docs ..." - }, - "unified_analysis": [ - {"module_path": "./src/core", "outline_summary": "Core functionality"} - ], - "groups": { - "count": 4, - "assignments": [ - {"group_id": "001", "directories": ["src/modules", "src/utils"], "doc_count": 6}, - {"group_id": "002", "directories": ["lib/core", "lib/helpers"], "doc_count": 7} - ] - }, - "statistics": { - "total": 15, - "code": 8, - "navigation": 7, - "top_level": 3 - } -} -``` - -**Workflow Session Structure** (workflow-session.json): -```json -{ - "session_id": "WFS-docs-{timestamp}", - "project": "{project_name} documentation", - "status": "planning", - "timestamp": "2024-01-20T14:30:22+08:00", - "path": ".", - "target_path": "/path/to/project", - "project_root": "/path/to/project", - "project_name": "{project_name}", - "mode": "full", - "tool": "gemini", - "cli_execute": false, - "update_mode": "update", - "existing_docs": 5, - "analysis": { - "total": "15", - "code": "8", - "navigation": "7", - "top_level": "3" - } -} -``` - -## Generated Documentation - -**Structure mirrors project source directories under project-specific folder**: - -``` -.workflow/docs/ -└── {project_name}/ # Project-specific root - ├── src/ # Mirrors src/ directory - │ ├── modules/ - │ │ ├── README.md # Navigation - │ │ ├── auth/ - │ │ │ ├── API.md # API signatures - │ │ │ ├── README.md # Module docs - │ │ │ └── middleware/ - │ │ │ ├── API.md - │ │ │ └── README.md - │ │ └── api/ - │ │ ├── API.md - │ │ └── README.md - │ └── utils/ - │ └── README.md - ├── lib/ # Mirrors lib/ directory - │ └── core/ - │ ├── API.md - │ └── README.md - ├── README.md # Project root - ├── ARCHITECTURE.md # System design - ├── EXAMPLES.md # Usage examples - └── api/ # Optional - └── README.md # HTTP API reference -``` - -## Execution Commands - -```bash -# Execute entire workflow (auto-discovers active session) -/workflow:execute - -# Or specify session -/workflow:execute --resume-session="WFS-docs-yyyymmdd-hhmmss" - -# Individual task execution -/task:execute IMPL-001 -``` - -## Template Reference - -**Available Templates** (`~/.claude/workflows/cli-templates/prompts/documentation/`): -- `api.txt`: Code API (Part A) + HTTP API (Part B) -- `module-readme.txt`: Module purpose, usage, dependencies -- `folder-navigation.txt`: Navigation README for folders with subdirectories -- `project-readme.txt`: Project overview, getting started, navigation -- `project-architecture.txt`: System structure, module map, design patterns -- `project-examples.txt`: End-to-end usage examples - -## Execution Mode Summary - -| Mode | CLI Placement | CLI MODE | Approval Flag | Agent Role | -|------|---------------|----------|---------------|------------| -| **Agent (default)** | pre_analysis | analysis | (none) | Generates documentation content | -| **CLI (--cli-execute)** | implementation_approach | write | --mode write | Executes CLI commands, validates output | - -**Execution Flow**: -- **Phase 2**: Unified analysis once, results in `.process/` -- **Phase 4**: Dynamic grouping (max 2 dirs per group) -- **Level 1**: Parallel processing for module tree groups -- **Level 2+**: Sequential execution for project-level docs - -## Related Commands -- `/workflow:execute` - Execute documentation tasks -- `/workflow:status` - View task progress -- `/workflow:session:complete` - Mark session complete diff --git a/.claude/commands/memory/load-skill-memory.md b/.claude/commands/memory/load-skill-memory.md deleted file mode 100644 index 5d2e24ce..00000000 --- a/.claude/commands/memory/load-skill-memory.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -name: load-skill-memory -description: Activate SKILL package (auto-detect from paths/keywords or manual) and intelligently load documentation based on task intent keywords -argument-hint: "[skill_name] \"task intent description\"" -allowed-tools: Bash(*), Read(*), Skill(*) ---- - -# Memory Load SKILL Command (/memory:load-skill-memory) - -## 1. Overview - -The `memory:load-skill-memory` command **activates SKILL package** (auto-detect from task or manual specification) and intelligently loads documentation based on user's task intent. The system automatically determines which documentation files to read based on the intent description. - -**Core Philosophy**: -- **Flexible Activation**: Auto-detect skill from task description/paths, or user explicitly specifies -- **Intent-Driven Loading**: System analyzes task intent to determine documentation scope -- **Intelligent Selection**: Automatically chooses appropriate documentation level and modules -- **Direct Context Loading**: Loads selected documentation into conversation memory - -**When to Use**: -- Manually activate a known SKILL package for a specific task -- Load SKILL context when system hasn't auto-triggered it -- Force reload SKILL documentation with specific intent focus - -**Note**: Normal SKILL activation happens automatically via description triggers or path mentions (system extracts skill name from file paths for intelligent triggering). Use this command only when manual activation is needed. - -## 2. Parameters - -- `[skill_name]` (Optional): Name of SKILL package to activate - - If omitted: System auto-detects from task description or file paths - - If specified: Direct activation of named SKILL package - - Example: `my_project`, `api_service` - - Must match directory name under `.claude/skills/` - -- `"task intent description"` (Required): Description of what you want to do - - Used for both: auto-detection (if skill_name omitted) and documentation scope selection - - **Analysis tasks**: "分析builder pattern实现", "理解参数系统架构" - - **Modification tasks**: "修改workflow逻辑", "增强thermal template功能" - - **Learning tasks**: "学习接口设计模式", "了解测试框架使用" - - **With paths**: "修改D:\projects\my_project\src\auth.py的认证逻辑" (auto-extracts `my_project`) - -## 3. Execution Flow - -### Step 1: Determine SKILL Name (if not provided) - -**Auto-Detection Strategy** (when skill_name parameter is omitted): -1. **Path Extraction**: Scan task description for file paths - - Extract potential project names from path segments - - Example: `"修改D:\projects\my_project\src\auth.py"` → extracts `my_project` -2. **Keyword Matching**: Match task keywords against SKILL descriptions - - Search for project-specific terms, domain keywords -3. **Validation**: Check if extracted name matches `.claude/skills/{skill_name}/` - -**Result**: Either uses provided skill_name or auto-detected name for activation - -### Step 2: Activate SKILL and Analyze Intent - -**Activate SKILL Package**: -```javascript -Skill(command: "${skill_name}") // Uses provided or auto-detected name -``` - -**What Happens After Activation**: -1. If SKILL exists in memory: System reads `.claude/skills/${skill_name}/SKILL.md` -2. If SKILL not found in memory: Error - SKILL package doesn't exist -3. SKILL description triggers are loaded into memory -4. Progressive loading mechanism becomes available -5. Documentation structure is now accessible - -**Intent Analysis**: -Based on task intent description, system determines: -- **Action type**: analyzing, modifying, learning -- **Scope**: specific module, architecture overview, complete system -- **Depth**: quick reference, detailed API, full documentation - -### Step 3: Intelligent Documentation Loading - -**Loading Strategy**: - -The system automatically selects documentation based on intent keywords: - -1. **Quick Understanding** ("了解", "快速理解", "什么是"): - - Load: Level 0 (README.md only, ~2K tokens) - - Use case: Quick overview of capabilities - -2. **Specific Module Analysis** ("分析XXX模块", "理解XXX实现"): - - Load: Module-specific README.md + API.md (~5K tokens) - - Use case: Deep dive into specific component - -3. **Architecture Review** ("架构", "设计模式", "整体结构"): - - Load: README.md + ARCHITECTURE.md (~10K tokens) - - Use case: System design understanding - -4. **Implementation/Modification** ("修改", "增强", "实现"): - - Load: Relevant module docs + EXAMPLES.md (~15K tokens) - - Use case: Code modification with examples - -5. **Comprehensive Learning** ("学习", "完整了解", "深入理解"): - - Load: Level 3 (All documentation, ~40K tokens) - - Use case: Complete system mastery - -**Documentation Loaded into Memory**: -After loading, the selected documentation content is available in conversation memory for subsequent operations. - -## 4. Usage Examples - -### Example 1: Manual Specification - -**User Command**: -```bash -/memory:load-skill-memory my_project "修改认证模块增加OAuth支持" -``` - -**Execution**: -```javascript -// Step 1: Use provided skill_name -skill_name = "my_project" // Directly from parameter - -// Step 2: Activate SKILL -Skill(command: "my_project") - -// Step 3: Intent Analysis -Keywords: ["修改", "认证模块", "增加", "OAuth"] -Action: modifying (implementation) -Scope: auth module + examples - -// Load documentation based on intent -Read(.workflow/docs/my_project/auth/README.md) -Read(.workflow/docs/my_project/auth/API.md) -Read(.workflow/docs/my_project/EXAMPLES.md) -``` - -### Example 2: Auto-Detection from Path - -**User Command**: -```bash -/memory:load-skill-memory "修改D:\projects\my_project\src\services\api.py的接口逻辑" -``` - -**Execution**: -```javascript -// Step 1: Auto-detect skill_name from path -Path detected: "D:\projects\my_project\src\services\api.py" -Extracted: "my_project" -Validated: .claude/skills/my_project/ exists ✓ -skill_name = "my_project" - -// Step 2: Activate SKILL -Skill(command: "my_project") - -// Step 3: Intent Analysis -Keywords: ["修改", "services", "接口逻辑"] -Action: modifying (implementation) -Scope: services module + examples - -// Load documentation based on intent -Read(.workflow/docs/my_project/services/README.md) -Read(.workflow/docs/my_project/services/API.md) -Read(.workflow/docs/my_project/EXAMPLES.md) -``` - -## 5. Intent Keyword Mapping - -**Quick Reference**: -- **Triggers**: "了解", "快速", "什么是", "简介" -- **Loads**: README.md only (~2K) - -**Module-Specific**: -- **Triggers**: "XXX模块", "XXX组件", "分析XXX" -- **Loads**: Module README + API (~5K) - -**Architecture**: -- **Triggers**: "架构", "设计", "整体结构", "系统设计" -- **Loads**: README + ARCHITECTURE (~10K) - -**Implementation**: -- **Triggers**: "修改", "增强", "实现", "开发", "集成" -- **Loads**: Relevant module + EXAMPLES (~15K) - -**Comprehensive**: -- **Triggers**: "完整", "深入", "全面", "学习整个" -- **Loads**: All documentation (~40K) diff --git a/.claude/commands/memory/skill-memory.md b/.claude/commands/memory/skill-memory.md deleted file mode 100644 index 22b399f8..00000000 --- a/.claude/commands/memory/skill-memory.md +++ /dev/null @@ -1,525 +0,0 @@ ---- -name: skill-memory -description: 4-phase autonomous orchestrator: check docs → /memory:docs planning → /workflow:execute → generate SKILL.md with progressive loading index (skips phases 2-3 if docs exist) -argument-hint: "[path] [--tool ] [--regenerate] [--mode ] [--cli-execute]" -allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*) ---- - -# Memory SKILL Package Generator - -## Orchestrator Role - -**Pure Orchestrator**: Execute documentation generation workflow, then generate SKILL.md index. Does NOT create task JSON files. - -**Auto-Continue Workflow**: This command runs **fully autonomously** once triggered. Each phase completes and automatically triggers the next phase without user interaction. - -**Execution Paths**: -- **Full Path**: All 4 phases (no existing docs OR `--regenerate` specified) -- **Skip Path**: Phase 1 → Phase 4 (existing docs found AND no `--regenerate` flag) -- **Phase 4 Always Executes**: SKILL.md index is never skipped, always generated or updated - -## Core Rules - -1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution -2. **No Task JSON**: This command does not create task JSON files - delegates to /memory:docs -3. **Parse Every Output**: Extract required data from each command output (session_id, task_count, file paths) -4. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase -5. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase -6. **Direct Generation**: Phase 4 directly generates SKILL.md using Write tool -7. **No Manual Steps**: User should never be prompted for decisions between phases - ---- - -## 4-Phase Execution - -### Phase 1: Prepare Arguments - -**Goal**: Parse command arguments and check existing documentation - -**Step 1: Get Target Path and Project Name** -```bash -# Get current directory (or use provided path) -bash(pwd) - -# Get project name from directory -bash(basename "$(pwd)") - -# Get project root -bash(git rev-parse --show-toplevel 2>/dev/null || pwd) -``` - -**Output**: -- `target_path`: `/d/my_project` -- `project_name`: `my_project` -- `project_root`: `/d/my_project` - -**Step 2: Set Default Parameters** -```bash -# Default values (use these unless user specifies otherwise): -# - tool: "gemini" -# - mode: "full" -# - regenerate: false (no --regenerate flag) -# - cli_execute: false (no --cli-execute flag) -``` - -**Step 3: Check Existing Documentation** -```bash -# Check if docs directory exists -bash(test -d .workflow/docs/my_project && echo "exists" || echo "not_exists") - -# Count existing documentation files -bash(find .workflow/docs/my_project -name "*.md" 2>/dev/null | wc -l || echo 0) -``` - -**Output**: -- `docs_exists`: `exists` or `not_exists` -- `existing_docs`: `5` (or `0` if no docs) - -**Step 4: Determine Execution Path** - -**Decision Logic**: -```javascript -if (existing_docs > 0 && !regenerate_flag) { - // Documentation exists and no regenerate flag - SKIP_DOCS_GENERATION = true - message = "Documentation already exists, skipping Phase 2 and Phase 3. Use --regenerate to force regeneration." -} else if (regenerate_flag) { - // Force regeneration: delete existing docs - bash(rm -rf .workflow/docs/my_project 2>/dev/null || true) - SKIP_DOCS_GENERATION = false - message = "Regenerating documentation from scratch." -} else { - // No existing docs - SKIP_DOCS_GENERATION = false - message = "No existing documentation found, generating new documentation." -} -``` - -**Summary Variables**: -- `PROJECT_NAME`: `my_project` -- `TARGET_PATH`: `/d/my_project` -- `DOCS_PATH`: `.workflow/docs/my_project` -- `TOOL`: `gemini` (default) or user-specified -- `MODE`: `full` (default) or user-specified -- `CLI_EXECUTE`: `false` (default) or `true` if --cli-execute flag -- `REGENERATE`: `false` (default) or `true` if --regenerate flag -- `EXISTING_DOCS`: Count of existing documentation files -- `SKIP_DOCS_GENERATION`: `true` if skipping Phase 2/3, `false` otherwise - -**Completion & TodoWrite**: -- If `SKIP_DOCS_GENERATION = true`: Mark phase 1 completed, phase 2&3 completed (skipped), phase 4 in_progress -- If `SKIP_DOCS_GENERATION = false`: Mark phase 1 completed, phase 2 in_progress - -**Next Action**: -- If skipping: Display skip message → Jump to Phase 4 (SKILL.md generation) -- If not skipping: Display preparation results → Continue to Phase 2 (documentation planning) - ---- - -### Phase 2: Call /memory:docs - -**Skip Condition**: This phase is **skipped if SKIP_DOCS_GENERATION = true** (documentation already exists without --regenerate flag) - -**Goal**: Trigger documentation generation workflow - -**Command**: -```bash -SlashCommand(command="/memory:docs [targetPath] --tool [tool] --mode [mode] [--cli-execute]") -``` - -**Example**: -```bash -/memory:docs /d/my_app --tool gemini --mode full -/memory:docs /d/my_app --tool gemini --mode full --cli-execute -``` - -**Note**: The `--regenerate` flag is handled in Phase 1 by deleting existing documentation. This command always calls `/memory:docs` without the regenerate flag, relying on docs.md's built-in update detection. - -**Parse Output**: -- Extract session ID: `WFS-docs-[timestamp]` (store as `docsSessionId`) -- Extract task count (store as `taskCount`) - -**Completion Criteria**: -- `/memory:docs` command executed successfully -- Session ID extracted and stored -- Task count retrieved -- Task files created in `.workflow/[docsSessionId]/.task/` -- workflow-session.json exists - -**TodoWrite**: Mark phase 2 completed, phase 3 in_progress - -**Next Action**: Display docs planning results (session ID, task count) → Auto-continue to Phase 3 - ---- - -### Phase 3: Execute Documentation Generation - -**Skip Condition**: This phase is **skipped if SKIP_DOCS_GENERATION = true** (documentation already exists without --regenerate flag) - -**Goal**: Execute documentation generation tasks - -**Command**: -```bash -SlashCommand(command="/workflow:execute") -``` - -**Note**: `/workflow:execute` automatically discovers active session from Phase 2 - -**Completion Criteria**: -- `/workflow:execute` command executed successfully -- Documentation files generated in `.workflow/docs/[projectName]/` -- All tasks marked as completed in session -- At minimum: module documentation files exist (API.md and/or README.md) -- For full mode: Project README, ARCHITECTURE, EXAMPLES files generated - -**TodoWrite**: Mark phase 3 completed, phase 4 in_progress - -**Next Action**: Display execution results (file count, module count) → Auto-continue to Phase 4 - ---- - -### Phase 4: Generate SKILL.md Index - -**Note**: This phase is **NEVER skipped** - it always executes to generate or update the SKILL index. - -**Step 1: Read Key Files** (Use Read tool) -- `.workflow/docs/{project_name}/README.md` (required) -- `.workflow/docs/{project_name}/ARCHITECTURE.md` (optional) - -**Step 2: Discover Structure** -```bash -bash(find .workflow/docs/{project_name} -name "*.md" | sed 's|.workflow/docs/{project_name}/||' | awk -F'/' '{if(NF>=2) print $1"/"$2}' | sort -u) -``` - -**Step 3: Generate Intelligent Description** - -Extract from README + structure: Function (capabilities), Modules (names), Keywords (API/CLI/auth/etc.) - -**Format**: `{Project} {core capabilities} (located at {project_path}). Load this SKILL when analyzing, modifying, or learning about {domain_description} or files under this path, especially when no relevant context exists in memory.` - -**Key Elements**: -- **Path Reference**: Use `TARGET_PATH` from Phase 1 for precise location identification -- **Domain Description**: Extract human-readable domain/feature area from README (e.g., "workflow management", "thermal modeling") -- **Trigger Optimization**: Include project path, emphasize "especially when no relevant context exists in memory" -- **Action Coverage**: analyzing (分析), modifying (修改), learning (了解) - -**Example**: "Workflow orchestration system with CLI tools and documentation generation (located at /d/Claude_dms3). Load this SKILL when analyzing, modifying, or learning about workflow management or files under this path, especially when no relevant context exists in memory." - -**Step 4: Write SKILL.md** (Use Write tool) -```bash -bash(mkdir -p .claude/skills/{project_name}) -``` - -`.claude/skills/{project_name}/SKILL.md`: -```yaml ---- -name: {project_name} -description: {intelligent description from Step 3} -version: 1.0.0 ---- -# {Project Name} SKILL Package - -## Documentation: `../../../.workflow/docs/{project_name}/` - -## Progressive Loading -### Level 0: Quick Start (~2K) -- [README](../../../.workflow/docs/{project_name}/README.md) -### Level 1: Core Modules (~8K) -{Module READMEs} -### Level 2: Complete (~25K) -All modules + [Architecture](../../../.workflow/docs/{project_name}/ARCHITECTURE.md) -### Level 3: Deep Dive (~40K) -Everything + [Examples](../../../.workflow/docs/{project_name}/EXAMPLES.md) -``` - -**Completion Criteria**: -- SKILL.md file created at `.claude/skills/{project_name}/SKILL.md` -- Intelligent description generated from documentation -- Progressive loading levels (0-3) properly structured -- Module index includes all documented modules -- All file references use relative paths - -**TodoWrite**: Mark phase 4 completed - -**Final Action**: Report completion summary to user - -**Return to User**: -``` -SKILL Package Generation Complete - -Project: {project_name} -Documentation: .workflow/docs/{project_name}/ ({doc_count} files) -SKILL Index: .claude/skills/{project_name}/SKILL.md - -Generated: -- {task_count} documentation tasks completed -- SKILL.md with progressive loading (4 levels) -- Module index with {module_count} modules - -Usage: -- Load Level 0: Quick project overview (~2K tokens) -- Load Level 1: Core modules (~8K tokens) -- Load Level 2: Complete docs (~25K tokens) -- Load Level 3: Everything (~40K tokens) -``` - ---- - -## Implementation Details - -### Critical Rules - -1. **No User Prompts Between Phases**: Never ask user questions or wait for input between phases -2. **Immediate Phase Transition**: After TodoWrite update, immediately execute next phase command -3. **Status-Driven Execution**: Check TodoList status after each phase: - - If next task is "pending" → Mark it "in_progress" and execute - - If all tasks are "completed" → Report final summary -4. **Phase Completion Pattern**: - ``` - Phase N completes → Update TodoWrite (N=completed, N+1=in_progress) → Execute Phase N+1 - ``` - -### TodoWrite Patterns - -#### Initialization (Before Phase 1) - -**FIRST ACTION**: Create TodoList with all 4 phases -```javascript -TodoWrite({todos: [ - {"content": "Parse arguments and prepare", "status": "in_progress", "activeForm": "Parsing arguments"}, - {"content": "Call /memory:docs to plan documentation", "status": "pending", "activeForm": "Calling /memory:docs"}, - {"content": "Execute documentation generation", "status": "pending", "activeForm": "Executing documentation"}, - {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL.md"} -]}) -``` - -**SECOND ACTION**: Execute Phase 1 immediately - -#### Full Path (SKIP_DOCS_GENERATION = false) - -**After Phase 1**: -```javascript -TodoWrite({todos: [ - {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"}, - {"content": "Call /memory:docs to plan documentation", "status": "in_progress", "activeForm": "Calling /memory:docs"}, - {"content": "Execute documentation generation", "status": "pending", "activeForm": "Executing documentation"}, - {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL.md"} -]}) -// Auto-continue to Phase 2 -``` - -**After Phase 2**: -```javascript -TodoWrite({todos: [ - {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"}, - {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"}, - {"content": "Execute documentation generation", "status": "in_progress", "activeForm": "Executing documentation"}, - {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL.md"} -]}) -// Auto-continue to Phase 3 -``` - -**After Phase 3**: -```javascript -TodoWrite({todos: [ - {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"}, - {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"}, - {"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"}, - {"content": "Generate SKILL.md index", "status": "in_progress", "activeForm": "Generating SKILL.md"} -]}) -// Auto-continue to Phase 4 -``` - -**After Phase 4**: -```javascript -TodoWrite({todos: [ - {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"}, - {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"}, - {"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"}, - {"content": "Generate SKILL.md index", "status": "completed", "activeForm": "Generating SKILL.md"} -]}) -// Report completion summary to user -``` - -#### Skip Path (SKIP_DOCS_GENERATION = true) - -**After Phase 1** (detects existing docs, skips Phase 2 & 3): -```javascript -TodoWrite({todos: [ - {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"}, - {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"}, - {"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"}, - {"content": "Generate SKILL.md index", "status": "in_progress", "activeForm": "Generating SKILL.md"} -]}) -// Display skip message: "Documentation already exists, skipping Phase 2 and Phase 3. Use --regenerate to force regeneration." -// Jump directly to Phase 4 -``` - -**After Phase 4**: -```javascript -TodoWrite({todos: [ - {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"}, - {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"}, - {"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"}, - {"content": "Generate SKILL.md index", "status": "completed", "activeForm": "Generating SKILL.md"} -]}) -// Report completion summary to user -``` - -### Execution Flow Diagrams - -#### Full Path Flow -``` -User triggers command - ↓ -[TodoWrite] Initialize 4 phases (Phase 1 = in_progress) - ↓ -[Execute] Phase 1: Parse arguments - ↓ -[TodoWrite] Phase 1 = completed, Phase 2 = in_progress - ↓ -[Execute] Phase 2: Call /memory:docs - ↓ -[TodoWrite] Phase 2 = completed, Phase 3 = in_progress - ↓ -[Execute] Phase 3: Call /workflow:execute - ↓ -[TodoWrite] Phase 3 = completed, Phase 4 = in_progress - ↓ -[Execute] Phase 4: Generate SKILL.md - ↓ -[TodoWrite] Phase 4 = completed - ↓ -[Report] Display completion summary -``` - -#### Skip Path Flow -``` -User triggers command - ↓ -[TodoWrite] Initialize 4 phases (Phase 1 = in_progress) - ↓ -[Execute] Phase 1: Parse arguments, detect existing docs - ↓ -[TodoWrite] Phase 1 = completed, Phase 2&3 = completed (skipped), Phase 4 = in_progress - ↓ -[Display] Skip message: "Documentation already exists, skipping Phase 2 and Phase 3" - ↓ -[Execute] Phase 4: Generate SKILL.md (always runs) - ↓ -[TodoWrite] Phase 4 = completed - ↓ -[Report] Display completion summary -``` - -### Error Handling - -- If any phase fails, mark it as "in_progress" (not completed) -- Report error details to user -- Do NOT auto-continue to next phase on failure - ---- - -## Parameters - -```bash -/memory:skill-memory [path] [--tool ] [--regenerate] [--mode ] [--cli-execute] -``` - -- **path**: Target directory (default: current directory) -- **--tool**: CLI tool for documentation (default: gemini) - - `gemini`: Comprehensive documentation - - `qwen`: Architecture analysis - - `codex`: Implementation validation -- **--regenerate**: Force regenerate all documentation - - When enabled: Deletes existing `.workflow/docs/{project_name}/` before regeneration - - Ensures fresh documentation from source code -- **--mode**: Documentation mode (default: full) - - `full`: Complete docs (modules + README + ARCHITECTURE + EXAMPLES) - - `partial`: Module docs only -- **--cli-execute**: Enable CLI-based documentation generation (optional) - - When enabled: CLI generates docs directly in implementation_approach - - When disabled (default): Agent generates documentation content - ---- - -## Examples - -### Example 1: Generate SKILL Package (Default) - -```bash -/memory:skill-memory -``` - -**Workflow**: -1. Phase 1: Detects current directory, checks existing docs -2. Phase 2: Calls `/memory:docs . --tool gemini --mode full` (Agent Mode) -3. Phase 3: Executes documentation generation via `/workflow:execute` -4. Phase 4: Generates SKILL.md at `.claude/skills/{project_name}/SKILL.md` - -### Example 2: Regenerate with Qwen - -```bash -/memory:skill-memory /d/my_app --tool qwen --regenerate -``` - -**Workflow**: -1. Phase 1: Parses target path, detects regenerate flag, deletes existing docs -2. Phase 2: Calls `/memory:docs /d/my_app --tool qwen --mode full` -3. Phase 3: Executes documentation regeneration -4. Phase 4: Generates updated SKILL.md - -### Example 3: Partial Mode (Modules Only) - -```bash -/memory:skill-memory --mode partial -``` - -**Workflow**: -1. Phase 1: Detects partial mode -2. Phase 2: Calls `/memory:docs . --tool gemini --mode partial` (Agent Mode) -3. Phase 3: Executes module documentation only -4. Phase 4: Generates SKILL.md with module-only index - -### Example 4: CLI Execute Mode - -```bash -/memory:skill-memory --cli-execute -``` - -**Workflow**: -1. Phase 1: Detects CLI execute mode -2. Phase 2: Calls `/memory:docs . --tool gemini --mode full --cli-execute` (CLI Mode) -3. Phase 3: Executes CLI-based documentation generation -4. Phase 4: Generates SKILL.md at `.claude/skills/{project_name}/SKILL.md` - -### Example 5: Skip Path (Existing Docs) - -```bash -/memory:skill-memory -``` - -**Scenario**: Documentation already exists in `.workflow/docs/{project_name}/` - -**Workflow**: -1. Phase 1: Detects existing docs (5 files), sets SKIP_DOCS_GENERATION = true -2. Display: "Documentation already exists, skipping Phase 2 and Phase 3. Use --regenerate to force regeneration." -3. Phase 4: Generates or updates SKILL.md index only (~5-10x faster) - ---- - - - -## Architecture - -``` -skill-memory (orchestrator) - ├─ Phase 1: Prepare (bash commands, skip decision) - ├─ Phase 2: /memory:docs (task planning, skippable) - ├─ Phase 3: /workflow:execute (task execution, skippable) - └─ Phase 4: Write SKILL.md (direct file generation, always runs) - -No task JSON created by this command -All documentation tasks managed by /memory:docs -Smart skip logic: 5-10x faster when docs exist -``` diff --git a/.claude/commands/memory/swagger-docs.md b/.claude/commands/memory/swagger-docs.md deleted file mode 100644 index 6cc3ffb6..00000000 --- a/.claude/commands/memory/swagger-docs.md +++ /dev/null @@ -1,773 +0,0 @@ ---- -name: swagger-docs -description: Generate complete Swagger/OpenAPI documentation following RESTful standards with global security, API details, error codes, and validation tests -argument-hint: "[path] [--tool ] [--format ] [--version ] [--lang ]" ---- - -# Swagger API Documentation Workflow (/memory:swagger-docs) - -## Overview - -Professional Swagger/OpenAPI documentation generator that strictly follows RESTful API design standards to produce enterprise-grade API documentation. - -**Core Features**: -- **RESTful Standards**: Strict adherence to REST architecture and HTTP semantics -- **Global Security**: Unified Authorization Token validation mechanism -- **Complete API Docs**: Descriptions, methods, URLs, parameters for each endpoint -- **Organized Structure**: Clear directory hierarchy by business domain -- **Detailed Fields**: Type, required, example, description for each field -- **Error Code Standards**: Unified error response format and code definitions -- **Validation Tests**: Boundary conditions and exception handling tests - -**Output Structure** (--lang zh): -``` -.workflow/docs/{project_name}/api/ -├── swagger.yaml # Main OpenAPI spec file -├── 概述/ -│ ├── README.md # API overview -│ ├── 认证说明.md # Authentication guide -│ ├── 错误码规范.md # Error code definitions -│ └── 版本历史.md # Version history -├── 用户模块/ # Grouped by business domain -│ ├── 用户认证.md -│ ├── 用户管理.md -│ └── 权限控制.md -├── 业务模块/ -│ └── ... -└── 测试报告/ - ├── 接口测试.md # API test results - └── 边界测试.md # Boundary condition tests -``` - -**Output Structure** (--lang en): -``` -.workflow/docs/{project_name}/api/ -├── swagger.yaml # Main OpenAPI spec file -├── overview/ -│ ├── README.md # API overview -│ ├── authentication.md # Authentication guide -│ ├── error-codes.md # Error code definitions -│ └── changelog.md # Version history -├── users/ # Grouped by business domain -│ ├── authentication.md -│ ├── management.md -│ └── permissions.md -├── orders/ -│ └── ... -└── test-reports/ - ├── api-tests.md # API test results - └── boundary-tests.md # Boundary condition tests -``` - -## Parameters - -```bash -/memory:swagger-docs [path] [--tool ] [--format ] [--version ] [--lang ] -``` - -- **path**: API source code directory (default: current directory) -- **--tool**: CLI tool selection (default: gemini) - - `gemini`: Comprehensive analysis, pattern recognition - - `qwen`: Architecture analysis, system design - - `codex`: Implementation validation, code quality -- **--format**: OpenAPI spec format (default: yaml) - - `yaml`: YAML format (recommended, better readability) - - `json`: JSON format -- **--version**: OpenAPI version (default: v3.0) - - `v3.0`: OpenAPI 3.0.x - - `v3.1`: OpenAPI 3.1.0 (supports JSON Schema 2020-12) -- **--lang**: Documentation language (default: zh) - - `zh`: Chinese documentation with Chinese directory names - - `en`: English documentation with English directory names - -## Planning Workflow - -### Phase 1: Initialize Session - -```bash -# Get project info -bash(pwd && basename "$(pwd)" && git rev-parse --show-toplevel 2>/dev/null || pwd && date +%Y%m%d-%H%M%S) -``` - -```javascript -// Create swagger-docs session -SlashCommand(command="/workflow:session:start --type swagger-docs --new \"{project_name}-swagger-{timestamp}\"") -// Parse output to get sessionId -``` - -```bash -# Update workflow-session.json -bash(jq '. + {"target_path":"{target_path}","project_root":"{project_root}","project_name":"{project_name}","format":"yaml","openapi_version":"3.0.3","lang":"{lang}","tool":"gemini"}' .workflow/active/{sessionId}/workflow-session.json > tmp.json && mv tmp.json .workflow/active/{sessionId}/workflow-session.json) -``` - -### Phase 2: Scan API Endpoints - -**Discovery Patterns**: Auto-detect framework signatures and API definition styles. - -**Supported Frameworks**: -| Framework | Detection Pattern | Example | -|-----------|-------------------|---------| -| Express.js | `router.get/post/put/delete` | `router.get('/users/:id')` | -| Fastify | `fastify.route`, `@Route` | `fastify.get('/api/users')` | -| NestJS | `@Controller`, `@Get/@Post` | `@Get('users/:id')` | -| Koa | `router.get`, `ctx.body` | `router.get('/users')` | -| Hono | `app.get/post`, `c.json` | `app.get('/users/:id')` | -| FastAPI | `@app.get`, `@router.post` | `@app.get("/users/{id}")` | -| Flask | `@app.route`, `@bp.route` | `@app.route('/users')` | -| Spring | `@GetMapping`, `@PostMapping` | `@GetMapping("/users/{id}")` | -| Go Gin | `r.GET`, `r.POST` | `r.GET("/users/:id")` | -| Go Chi | `r.Get`, `r.Post` | `r.Get("/users/{id}")` | - -**Commands**: - -```bash -# 1. Detect API framework type -bash( - if rg -q "@Controller|@Get|@Post|@Put|@Delete" --type ts 2>/dev/null; then echo "NESTJS"; - elif rg -q "router\.(get|post|put|delete|patch)" --type ts --type js 2>/dev/null; then echo "EXPRESS"; - elif rg -q "fastify\.(get|post|route)" --type ts --type js 2>/dev/null; then echo "FASTIFY"; - elif rg -q "@app\.(get|post|put|delete)" --type py 2>/dev/null; then echo "FASTAPI"; - elif rg -q "@GetMapping|@PostMapping|@RequestMapping" --type java 2>/dev/null; then echo "SPRING"; - elif rg -q 'r\.(GET|POST|PUT|DELETE)' --type go 2>/dev/null; then echo "GO_GIN"; - else echo "UNKNOWN"; fi -) - -# 2. Scan all API endpoint definitions -bash(rg -n "(router|app|fastify)\.(get|post|put|delete|patch)|@(Get|Post|Put|Delete|Patch|Controller|RequestMapping)" --type ts --type js --type py --type java --type go -g '!*.test.*' -g '!*.spec.*' -g '!node_modules/**' 2>/dev/null | head -200) - -# 3. Extract route paths -bash(rg -o "['\"](/api)?/[a-zA-Z0-9/:_-]+['\"]" --type ts --type js --type py -g '!*.test.*' 2>/dev/null | sort -u | head -100) - -# 4. Detect existing OpenAPI/Swagger files -bash(find . -type f \( -name "swagger.yaml" -o -name "swagger.json" -o -name "openapi.yaml" -o -name "openapi.json" \) ! -path "*/node_modules/*" 2>/dev/null) - -# 5. Extract DTO/Schema definitions -bash(rg -n "export (interface|type|class).*Dto|@ApiProperty|class.*Schema" --type ts -g '!*.test.*' 2>/dev/null | head -100) -``` - -**Data Processing**: Parse outputs, use **Write tool** to create `${session_dir}/.process/swagger-planning-data.json`: - -```json -{ - "metadata": { - "generated_at": "2025-01-01T12:00:00+08:00", - "project_name": "project_name", - "project_root": "/path/to/project", - "openapi_version": "3.0.3", - "format": "yaml", - "lang": "zh" - }, - "framework": { - "type": "NESTJS", - "detected_patterns": ["@Controller", "@Get", "@Post"], - "base_path": "/api/v1" - }, - "endpoints": [ - { - "file": "src/modules/users/users.controller.ts", - "line": 25, - "method": "GET", - "path": "/api/v1/users/:id", - "handler": "getUser", - "controller": "UsersController" - } - ], - "existing_specs": { - "found": false, - "files": [] - }, - "dto_schemas": [ - { - "name": "CreateUserDto", - "file": "src/modules/users/dto/create-user.dto.ts", - "properties": ["email", "password", "name"] - } - ], - "statistics": { - "total_endpoints": 45, - "by_method": {"GET": 20, "POST": 15, "PUT": 5, "DELETE": 5}, - "by_module": {"users": 12, "auth": 8, "orders": 15, "products": 10} - } -} -``` - -### Phase 3: Analyze API Structure - -**Commands**: - -```bash -# 1. Analyze controller/route file structure -bash(cat ${session_dir}/.process/swagger-planning-data.json | jq -r '.endpoints[].file' | sort -u | head -20) - -# 2. Extract request/response types -bash(for f in $(jq -r '.dto_schemas[].file' ${session_dir}/.process/swagger-planning-data.json | head -20); do echo "=== $f ===" && cat "$f" 2>/dev/null; done) - -# 3. Analyze authentication middleware -bash(rg -n "auth|guard|middleware|jwt|bearer|token" -i --type ts --type js -g '!*.test.*' -g '!node_modules/**' 2>/dev/null | head -50) - -# 4. Detect error handling patterns -bash(rg -n "HttpException|BadRequest|Unauthorized|Forbidden|NotFound|throw new" --type ts --type js -g '!*.test.*' 2>/dev/null | head -50) -``` - -**Deep Analysis via Gemini CLI**: - -```bash -ccw cli -p " -PURPOSE: Analyze API structure and generate OpenAPI specification outline for comprehensive documentation -TASK: -• Parse all API endpoints and identify business module boundaries -• Extract request parameters, request bodies, and response formats -• Identify authentication mechanisms and security requirements -• Discover error handling patterns and error codes -• Map endpoints to logical module groups -MODE: analysis -CONTEXT: @src/**/*.controller.ts @src/**/*.routes.ts @src/**/*.dto.ts @src/**/middleware/**/* -EXPECTED: JSON format API structure analysis report with modules, endpoints, security schemes, and error codes -CONSTRAINTS: Strict RESTful standards | Identify all public endpoints | Document output language: {lang} -" --tool gemini --mode analysis --rule analysis-code-patterns --cd {project_root} -``` - -**Update swagger-planning-data.json** with analysis results: - -```json -{ - "api_structure": { - "modules": [ - { - "name": "Users", - "name_zh": "用户模块", - "base_path": "/api/v1/users", - "endpoints": [ - { - "path": "/api/v1/users", - "method": "GET", - "operation_id": "listUsers", - "summary": "List all users", - "summary_zh": "获取用户列表", - "description": "Paginated list of system users with filtering by status and role", - "description_zh": "分页获取系统用户列表，支持按状态、角色筛选", - "tags": ["User Management"], - "tags_zh": ["用户管理"], - "security": ["bearerAuth"], - "parameters": { - "query": ["page", "limit", "status", "role"] - }, - "responses": { - "200": "UserListResponse", - "401": "UnauthorizedError", - "403": "ForbiddenError" - } - } - ] - } - ], - "security_schemes": { - "bearerAuth": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "JWT", - "description": "JWT Token authentication. Add Authorization: Bearer to request header" - } - }, - "error_codes": [ - {"code": "AUTH_001", "status": 401, "message": "Invalid or expired token", "message_zh": "Token 无效或已过期"}, - {"code": "AUTH_002", "status": 401, "message": "Authentication required", "message_zh": "未提供认证信息"}, - {"code": "AUTH_003", "status": 403, "message": "Insufficient permissions", "message_zh": "权限不足"} - ] - } -} -``` - -### Phase 4: Task Decomposition - -**Task Hierarchy**: - -``` -Level 1: Infrastructure Tasks (Parallel) - ├─ IMPL-001: Generate main OpenAPI spec file (swagger.yaml) - ├─ IMPL-002: Generate global security config and auth documentation - └─ IMPL-003: Generate unified error code specification - -Level 2: Module Documentation Tasks (Parallel, by business module) - ├─ IMPL-004: Users module API documentation - ├─ IMPL-005: Auth module API documentation - ├─ IMPL-006: Business module N API documentation - └─ ... - -Level 3: Aggregation Tasks (Depends on Level 1-2) - ├─ IMPL-N+1: Generate API overview and navigation - └─ IMPL-N+2: Generate version history and changelog - -Level 4: Validation Tasks (Depends on Level 1-3) - ├─ IMPL-N+3: API endpoint validation tests - └─ IMPL-N+4: Boundary condition tests -``` - -**Grouping Strategy**: -1. Group by business module (users, orders, products, etc.) -2. Maximum 10 endpoints per task -3. Large modules (>10 endpoints) split by submodules - -**Commands**: - -```bash -# 1. Count endpoints by module -bash(cat ${session_dir}/.process/swagger-planning-data.json | jq '.statistics.by_module') - -# 2. Calculate task groupings -bash(cat ${session_dir}/.process/swagger-planning-data.json | jq -r '.api_structure.modules[] | "\(.name):\(.endpoints | length)"') -``` - -**Data Processing**: Use **Edit tool** to update `swagger-planning-data.json` with task groups: - -```json -{ - "task_groups": { - "level1_count": 3, - "level2_count": 5, - "total_count": 12, - "assignments": [ - {"task_id": "IMPL-001", "level": 1, "type": "openapi-spec", "title": "Generate OpenAPI main spec file"}, - {"task_id": "IMPL-002", "level": 1, "type": "security", "title": "Generate global security config"}, - {"task_id": "IMPL-003", "level": 1, "type": "error-codes", "title": "Generate error code specification"}, - {"task_id": "IMPL-004", "level": 2, "type": "module-doc", "module": "users", "endpoint_count": 12}, - {"task_id": "IMPL-005", "level": 2, "type": "module-doc", "module": "auth", "endpoint_count": 8} - ] - } -} -``` - -### Phase 5: Generate Task JSONs - -**Generation Process**: -1. Read configuration values from workflow-session.json -2. Read task groups from swagger-planning-data.json -3. Generate Level 1 tasks (infrastructure) -4. Generate Level 2 tasks (by module) -5. Generate Level 3-4 tasks (aggregation and validation) - -## Task Templates - -### Level 1-1: OpenAPI Main Spec File - -```json -{ - "id": "IMPL-001", - "title": "Generate OpenAPI main specification file", - "status": "pending", - "meta": { - "type": "swagger-openapi-spec", - "agent": "@doc-generator", - "tool": "gemini", - "priority": "critical" - }, - "context": { - "requirements": [ - "Generate OpenAPI 3.0.3 compliant swagger.yaml", - "Include complete info, servers, tags, paths, components definitions", - "Follow RESTful design standards, use {lang} for descriptions" - ], - "precomputed_data": { - "planning_data": "${session_dir}/.process/swagger-planning-data.json" - } - }, - "flow_control": { - "pre_analysis": [ - { - "step": "load_analysis_data", - "action": "Load API analysis data", - "commands": [ - "bash(cat ${session_dir}/.process/swagger-planning-data.json)" - ], - "output_to": "api_analysis" - } - ], - "implementation_approach": [ - { - "step": 1, - "title": "Generate OpenAPI spec file", - "description": "Create complete swagger.yaml specification file", - "cli_prompt": "PURPOSE: Generate OpenAPI 3.0.3 specification file from analyzed API structure\nTASK:\n• Define openapi version: 3.0.3\n• Define info: title, description, version, contact, license\n• Define servers: development, staging, production environments\n• Define tags: organized by business modules\n• Define paths: all API endpoints with complete specifications\n• Define components: schemas, securitySchemes, parameters, responses\nMODE: write\nCONTEXT: @[api_analysis]\nEXPECTED: Complete swagger.yaml file following OpenAPI 3.0.3 specification\nCONSTRAINTS: Use {lang} for all descriptions | Strict RESTful standards\n--rule documentation-swagger-api", - "output": "swagger.yaml" - } - ], - "target_files": [ - ".workflow/docs/${project_name}/api/swagger.yaml" - ] - } -} -``` - -### Level 1-2: Global Security Configuration - -```json -{ - "id": "IMPL-002", - "title": "Generate global security configuration and authentication guide", - "status": "pending", - "meta": { - "type": "swagger-security", - "agent": "@doc-generator", - "tool": "gemini" - }, - "context": { - "requirements": [ - "Document Authorization header format in detail", - "Describe token acquisition, refresh, and expiration mechanisms", - "List permission requirements for each endpoint" - ] - }, - "flow_control": { - "pre_analysis": [ - { - "step": "analyze_auth", - "command": "bash(rg -n 'auth|guard|jwt|bearer' -i --type ts -g '!*.test.*' 2>/dev/null | head -50)", - "output_to": "auth_patterns" - } - ], - "implementation_approach": [ - { - "step": 1, - "title": "Generate authentication documentation", - "cli_prompt": "PURPOSE: Generate comprehensive authentication documentation for API security\nTASK:\n• Document authentication mechanism: JWT Bearer Token\n• Explain header format: Authorization: Bearer \n• Describe token lifecycle: acquisition, refresh, expiration handling\n• Define permission levels: public, user, admin, super_admin\n• Document authentication failure responses: 401/403 error handling\nMODE: write\nCONTEXT: @[auth_patterns] @src/**/auth/**/* @src/**/guard/**/*\nEXPECTED: Complete authentication guide in {lang}\nCONSTRAINTS: Include code examples | Clear step-by-step instructions\n--rule development-feature", - "output": "{auth_doc_name}" - } - ], - "target_files": [ - ".workflow/docs/${project_name}/api/{overview_dir}/{auth_doc_name}" - ] - } -} -``` - -### Level 1-3: Unified Error Code Specification - -```json -{ - "id": "IMPL-003", - "title": "Generate unified error code specification", - "status": "pending", - "meta": { - "type": "swagger-error-codes", - "agent": "@doc-generator", - "tool": "gemini" - }, - "context": { - "requirements": [ - "Define unified error response format", - "Create categorized error code system (auth, business, system)", - "Provide detailed description and examples for each error code" - ] - }, - "flow_control": { - "implementation_approach": [ - { - "step": 1, - "title": "Generate error code specification document", - "cli_prompt": "PURPOSE: Generate comprehensive error code specification for consistent API error handling\nTASK:\n• Define error response format: {code, message, details, timestamp}\n• Document authentication errors (AUTH_xxx): 401/403 series\n• Document parameter errors (PARAM_xxx): 400 series\n• Document business errors (BIZ_xxx): business logic errors\n• Document system errors (SYS_xxx): 500 series\n• For each error code: HTTP status, error message, possible causes, resolution suggestions\nMODE: write\nCONTEXT: @src/**/*.exception.ts @src/**/*.filter.ts\nEXPECTED: Complete error code specification in {lang} with tables and examples\nCONSTRAINTS: Include response examples | Clear categorization\n--rule development-feature", - "output": "{error_doc_name}" - } - ], - "target_files": [ - ".workflow/docs/${project_name}/api/{overview_dir}/{error_doc_name}" - ] - } -} -``` - -### Level 2: Module API Documentation (Template) - -```json -{ - "id": "IMPL-${module_task_id}", - "title": "Generate ${module_name} API documentation", - "status": "pending", - "depends_on": ["IMPL-001", "IMPL-002", "IMPL-003"], - "meta": { - "type": "swagger-module-doc", - "agent": "@doc-generator", - "tool": "gemini", - "module": "${module_name}", - "endpoint_count": "${endpoint_count}" - }, - "context": { - "requirements": [ - "Complete documentation for all endpoints in this module", - "Each endpoint: description, method, URL, parameters, responses", - "Include success and failure response examples", - "Mark API version and last update time" - ], - "focus_paths": ["${module_source_paths}"] - }, - "flow_control": { - "pre_analysis": [ - { - "step": "load_module_endpoints", - "action": "Load module endpoint information", - "commands": [ - "bash(cat ${session_dir}/.process/swagger-planning-data.json | jq '.api_structure.modules[] | select(.name == \"${module_name}\")')" - ], - "output_to": "module_endpoints" - }, - { - "step": "read_source_files", - "action": "Read module source files", - "commands": [ - "bash(cat ${module_source_files})" - ], - "output_to": "source_code" - } - ], - "implementation_approach": [ - { - "step": 1, - "title": "Generate module API documentation", - "description": "Generate complete API documentation for ${module_name}", - "cli_prompt": "PURPOSE: Generate complete RESTful API documentation for ${module_name} module\nTASK:\n• Create module overview: purpose, use cases, prerequisites\n• Generate endpoint index: grouped by functionality\n• For each endpoint document:\n - Functional description: purpose and business context\n - Request method: GET/POST/PUT/DELETE\n - URL path: complete API path\n - Request headers: Authorization and other required headers\n - Path parameters: {id} and other path variables\n - Query parameters: pagination, filters, etc.\n - Request body: JSON Schema format\n - Response body: success and error responses\n - Field description table: type, required, example, description\n• Add usage examples: cURL, JavaScript, Python\n• Add version info: v1.0.0, last updated date\nMODE: write\nCONTEXT: @[module_endpoints] @[source_code]\nEXPECTED: Complete module API documentation in {lang} with all endpoints fully documented\nCONSTRAINTS: RESTful standards | Include all response codes\n--rule documentation-swagger-api", - "output": "${module_doc_name}" - } - ], - "target_files": [ - ".workflow/docs/${project_name}/api/${module_dir}/${module_doc_name}" - ] - } -} -``` - -### Level 3: API Overview and Navigation - -```json -{ - "id": "IMPL-${overview_task_id}", - "title": "Generate API overview and navigation", - "status": "pending", - "depends_on": ["IMPL-001", "...", "IMPL-${last_module_task_id}"], - "meta": { - "type": "swagger-overview", - "agent": "@doc-generator", - "tool": "gemini" - }, - "flow_control": { - "pre_analysis": [ - { - "step": "load_all_docs", - "command": "bash(find .workflow/docs/${project_name}/api -type f -name '*.md' ! -path '*/{overview_dir}/*' | xargs cat)", - "output_to": "all_module_docs" - } - ], - "implementation_approach": [ - { - "step": 1, - "title": "Generate API overview", - "cli_prompt": "PURPOSE: Generate API overview document with navigation and quick start guide\nTASK:\n• Create introduction: system features, tech stack, version\n• Write quick start guide: authentication, first request example\n• Build module navigation: categorized links to all modules\n• Document environment configuration: development, staging, production\n• List SDKs and tools: client libraries, Postman collection\nMODE: write\nCONTEXT: @[all_module_docs] @.workflow/docs/${project_name}/api/swagger.yaml\nEXPECTED: Complete API overview in {lang} with navigation links\nCONSTRAINTS: Clear structure | Quick start focus\n--rule development-feature", - "output": "README.md" - } - ], - "target_files": [ - ".workflow/docs/${project_name}/api/{overview_dir}/README.md" - ] - } -} -``` - -### Level 4: Validation Tasks - -```json -{ - "id": "IMPL-${test_task_id}", - "title": "API endpoint validation tests", - "status": "pending", - "depends_on": ["IMPL-${overview_task_id}"], - "meta": { - "type": "swagger-validation", - "agent": "@test-fix-agent", - "tool": "codex" - }, - "context": { - "requirements": [ - "Validate accessibility of all endpoints", - "Test various boundary conditions", - "Verify exception handling" - ] - }, - "flow_control": { - "pre_analysis": [ - { - "step": "load_swagger_spec", - "command": "bash(cat .workflow/docs/${project_name}/api/swagger.yaml)", - "output_to": "swagger_spec" - } - ], - "implementation_approach": [ - { - "step": 1, - "title": "Generate test report", - "cli_prompt": "PURPOSE: Generate comprehensive API test validation report\nTASK:\n• Document test environment configuration\n• Calculate endpoint coverage statistics\n• Report test results: pass/fail counts\n• Document boundary tests: parameter limits, null values, special characters\n• Document exception tests: auth failures, permission denied, resource not found\n• List issues found with recommendations\nMODE: write\nCONTEXT: @[swagger_spec]\nEXPECTED: Complete test report in {lang} with detailed results\nCONSTRAINTS: Include test cases | Clear pass/fail status\n--rule development-tests", - "output": "{test_doc_name}" - } - ], - "target_files": [ - ".workflow/docs/${project_name}/api/{test_dir}/{test_doc_name}" - ] - } -} -``` - -## Language-Specific Directory Mapping - -| Component | --lang zh | --lang en | -|-----------|-----------|-----------| -| Overview dir | 概述 | overview | -| Auth doc | 认证说明.md | authentication.md | -| Error doc | 错误码规范.md | error-codes.md | -| Changelog | 版本历史.md | changelog.md | -| Users module | 用户模块 | users | -| Orders module | 订单模块 | orders | -| Products module | 商品模块 | products | -| Test dir | 测试报告 | test-reports | -| API test doc | 接口测试.md | api-tests.md | -| Boundary test doc | 边界测试.md | boundary-tests.md | - -## API Documentation Template - -### Single Endpoint Format - -Each endpoint must include: - -```markdown -### Get User Details - -**Description**: Retrieve detailed user information by ID, including profile and permissions. - -**Endpoint Info**: - -| Property | Value | -|----------|-------| -| Method | GET | -| URL | `/api/v1/users/{id}` | -| Version | v1.0.0 | -| Updated | 2025-01-01 | -| Auth | Bearer Token | -| Permission | user / admin | - -**Request Headers**: - -| Field | Type | Required | Example | Description | -|-------|------|----------|---------|-------------| -| Authorization | string | Yes | `Bearer eyJhbGc...` | JWT Token | -| Content-Type | string | No | `application/json` | Request content type | - -**Path Parameters**: - -| Field | Type | Required | Example | Description | -|-------|------|----------|---------|-------------| -| id | string | Yes | `usr_123456` | Unique user identifier | - -**Query Parameters**: - -| Field | Type | Required | Default | Example | Description | -|-------|------|----------|---------|---------|-------------| -| include | string | No | - | `roles,permissions` | Related data to include | - -**Success Response** (200 OK): - -```json -{ - "code": 0, - "message": "success", - "data": { - "id": "usr_123456", - "email": "user@example.com", - "name": "John Doe", - "status": "active", - "roles": ["user"], - "created_at": "2025-01-01T00:00:00Z", - "updated_at": "2025-01-01T00:00:00Z" - }, - "timestamp": "2025-01-01T12:00:00Z" -} -``` - -**Response Fields**: - -| Field | Type | Description | -|-------|------|-------------| -| code | integer | Business status code, 0 = success | -| message | string | Response message | -| data.id | string | Unique user identifier | -| data.email | string | User email address | -| data.name | string | User display name | -| data.status | string | User status: active/inactive/suspended | -| data.roles | array | User role list | -| data.created_at | string | Creation timestamp (ISO 8601) | -| data.updated_at | string | Last update timestamp (ISO 8601) | - -**Error Responses**: - -| Status | Code | Message | Possible Cause | -|--------|------|---------|----------------| -| 401 | AUTH_001 | Invalid or expired token | Token format error or expired | -| 403 | AUTH_003 | Insufficient permissions | No access to this user info | -| 404 | USER_001 | User not found | User ID doesn't exist or deleted | - -**Examples**: - -```bash -# cURL -curl -X GET "https://api.example.com/api/v1/users/usr_123456" \ - -H "Authorization: Bearer eyJhbGc..." \ - -H "Content-Type: application/json" -``` - -```javascript -// JavaScript (fetch) -const response = await fetch('https://api.example.com/api/v1/users/usr_123456', { - method: 'GET', - headers: { - 'Authorization': 'Bearer eyJhbGc...', - 'Content-Type': 'application/json' - } -}); -const data = await response.json(); -``` -``` - -## Session Structure - -``` -.workflow/active/ -└── WFS-swagger-{timestamp}/ - ├── workflow-session.json - ├── IMPL_PLAN.md - ├── TODO_LIST.md - ├── .process/ - │ └── swagger-planning-data.json - └── .task/ - ├── IMPL-001.json # OpenAPI spec - ├── IMPL-002.json # Security config - ├── IMPL-003.json # Error codes - ├── IMPL-004.json # Module 1 API - ├── ... - ├── IMPL-N+1.json # API overview - └── IMPL-N+2.json # Validation tests -``` - -## Execution Commands - -```bash -# Execute entire workflow -/workflow:execute - -# Specify session -/workflow:execute --resume-session="WFS-swagger-yyyymmdd-hhmmss" - -# Single task execution -/task:execute IMPL-001 -``` - -## Related Commands - -- `/workflow:execute` - Execute documentation tasks -- `/workflow:status` - View task progress -- `/workflow:session:complete` - Mark session complete -- `/memory:docs` - General documentation workflow diff --git a/.claude/commands/memory/tech-research-rules.md b/.claude/commands/memory/tech-research-rules.md deleted file mode 100644 index 285f4f2a..00000000 --- a/.claude/commands/memory/tech-research-rules.md +++ /dev/null @@ -1,310 +0,0 @@ ---- -name: tech-research-rules -description: "3-phase orchestrator: extract tech stack → Exa research → generate path-conditional rules (auto-loaded by Claude Code)" -argument-hint: "[session-id | tech-stack-name] [--regenerate] [--tool ]" -allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*), Task(*) ---- - -# Tech Stack Rules Generator - -## Overview - -**Purpose**: Generate multi-layered, path-conditional rules that Claude Code automatically loads based on file context. - -**Output Structure**: -``` -.claude/rules/tech/{tech-stack}/ -├── core.md # paths: **/*.{ext} - Core principles -├── patterns.md # paths: src/**/*.{ext} - Implementation patterns -├── testing.md # paths: **/*.{test,spec}.{ext} - Testing rules -├── config.md # paths: *.config.* - Configuration rules -├── api.md # paths: **/api/**/* - API rules (backend only) -├── components.md # paths: **/components/**/* - Component rules (frontend only) -└── metadata.json # Generation metadata -``` - -**Templates Location**: `~/.claude/workflows/cli-templates/prompts/rules/` - ---- - -## Core Rules - -1. **Start Immediately**: First action is TodoWrite initialization -2. **Path-Conditional Output**: Every rule file includes `paths` frontmatter -3. **Template-Driven**: Agent reads templates before generating content -4. **Agent Produces Files**: Agent writes all rule files directly -5. **No Manual Loading**: Rules auto-activate when Claude works with matching files - ---- - -## 3-Phase Execution - -### Phase 1: Prepare Context & Detect Tech Stack - -**Goal**: Detect input mode, extract tech stack info, determine file extensions - -**Input Mode Detection**: -```bash -input="$1" - -if [[ "$input" == WFS-* ]]; then - MODE="session" - SESSION_ID="$input" - # Read workflow-session.json to extract tech stack -else - MODE="direct" - TECH_STACK_NAME="$input" -fi -``` - -**Tech Stack Analysis**: -```javascript -// Decompose composite tech stacks -// "typescript-react-nextjs" → ["typescript", "react", "nextjs"] - -const TECH_EXTENSIONS = { - "typescript": "{ts,tsx}", - "javascript": "{js,jsx}", - "python": "py", - "rust": "rs", - "go": "go", - "java": "java", - "csharp": "cs", - "ruby": "rb", - "php": "php" -}; - -const FRAMEWORK_TYPE = { - "react": "frontend", - "vue": "frontend", - "angular": "frontend", - "nextjs": "fullstack", - "nuxt": "fullstack", - "fastapi": "backend", - "express": "backend", - "django": "backend", - "rails": "backend" -}; -``` - -**Check Existing Rules**: -```bash -normalized_name=$(echo "$TECH_STACK_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-') -rules_dir=".claude/rules/tech/${normalized_name}" -existing_count=$(find "${rules_dir}" -name "*.md" 2>/dev/null | wc -l || echo 0) -``` - -**Skip Decision**: -- If `existing_count > 0` AND no `--regenerate` → `SKIP_GENERATION = true` -- If `--regenerate` → Delete existing and regenerate - -**Output Variables**: -- `TECH_STACK_NAME`: Normalized name -- `PRIMARY_LANG`: Primary language -- `FILE_EXT`: File extension pattern -- `FRAMEWORK_TYPE`: frontend | backend | fullstack | library -- `COMPONENTS`: Array of tech components -- `SKIP_GENERATION`: Boolean - -**TodoWrite**: Mark phase 1 completed - ---- - -### Phase 2: Agent Produces Path-Conditional Rules - -**Skip Condition**: Skipped if `SKIP_GENERATION = true` - -**Goal**: Delegate to agent for Exa research and rule file generation - -**Template Files**: -``` -~/.claude/workflows/cli-templates/prompts/rules/ -├── tech-rules-agent-prompt.txt # Agent instructions -├── rule-core.txt # Core principles template -├── rule-patterns.txt # Implementation patterns template -├── rule-testing.txt # Testing rules template -├── rule-config.txt # Configuration rules template -├── rule-api.txt # API rules template (backend) -└── rule-components.txt # Component rules template (frontend) -``` - -**Agent Task**: - -```javascript -Task({ - subagent_type: "general-purpose", - description: `Generate tech stack rules: ${TECH_STACK_NAME}`, - prompt: ` -You are generating path-conditional rules for Claude Code. - -## Context -- Tech Stack: ${TECH_STACK_NAME} -- Primary Language: ${PRIMARY_LANG} -- File Extensions: ${FILE_EXT} -- Framework Type: ${FRAMEWORK_TYPE} -- Components: ${JSON.stringify(COMPONENTS)} -- Output Directory: .claude/rules/tech/${TECH_STACK_NAME}/ - -## Instructions - -Read the agent prompt template for detailed instructions. -Use --rule rules-tech-rules-agent-prompt to load the template automatically. - -## Execution Steps - -1. Execute Exa research queries (see agent prompt) -2. Read each rule template -3. Generate rule files following template structure -4. Write files to output directory -5. Write metadata.json -6. Report completion - -## Variable Substitutions - -Replace in templates: -- {TECH_STACK_NAME} → ${TECH_STACK_NAME} -- {PRIMARY_LANG} → ${PRIMARY_LANG} -- {FILE_EXT} → ${FILE_EXT} -- {FRAMEWORK_TYPE} → ${FRAMEWORK_TYPE} -` -}) -``` - -**Completion Criteria**: -- 4-6 rule files written with proper `paths` frontmatter -- metadata.json written -- Agent reports files created - -**TodoWrite**: Mark phase 2 completed - ---- - -### Phase 3: Verify & Report - -**Goal**: Verify generated files and provide usage summary - -**Steps**: - -1. **Verify Files**: - ```bash - find ".claude/rules/tech/${TECH_STACK_NAME}" -name "*.md" -type f - ``` - -2. **Validate Frontmatter**: - ```bash - head -5 ".claude/rules/tech/${TECH_STACK_NAME}/core.md" - ``` - -3. **Read Metadata**: - ```javascript - Read(`.claude/rules/tech/${TECH_STACK_NAME}/metadata.json`) - ``` - -4. **Generate Summary Report**: - ``` - Tech Stack Rules Generated - - Tech Stack: {TECH_STACK_NAME} - Location: .claude/rules/tech/{TECH_STACK_NAME}/ - - Files Created: - ├── core.md → paths: **/*.{ext} - ├── patterns.md → paths: src/**/*.{ext} - ├── testing.md → paths: **/*.{test,spec}.{ext} - ├── config.md → paths: *.config.* - ├── api.md → paths: **/api/**/* (if backend) - └── components.md → paths: **/components/**/* (if frontend) - - Auto-Loading: - - Rules apply automatically when editing matching files - - No manual loading required - - Example Activation: - - Edit src/components/Button.tsx → core.md + patterns.md + components.md - - Edit tests/api.test.ts → core.md + testing.md - - Edit package.json → config.md - ``` - -**TodoWrite**: Mark phase 3 completed - ---- - -## Path Pattern Reference - -| Pattern | Matches | -|---------|---------| -| `**/*.ts` | All .ts files | -| `src/**/*` | All files under src/ | -| `*.config.*` | Config files in root | -| `**/*.{ts,tsx}` | .ts and .tsx files | - -| Tech Stack | Core Pattern | Test Pattern | -|------------|--------------|--------------| -| TypeScript | `**/*.{ts,tsx}` | `**/*.{test,spec}.{ts,tsx}` | -| Python | `**/*.py` | `**/test_*.py, **/*_test.py` | -| Rust | `**/*.rs` | `**/tests/**/*.rs` | -| Go | `**/*.go` | `**/*_test.go` | - ---- - -## Parameters - -```bash -/memory:tech-research [session-id | "tech-stack-name"] [--regenerate] -``` - -**Arguments**: -- **session-id**: `WFS-*` format - Extract from workflow session -- **tech-stack-name**: Direct input - `"typescript"`, `"typescript-react"` -- **--regenerate**: Force regenerate existing rules - ---- - -## Examples - -### Single Language - -```bash -/memory:tech-research "typescript" -``` - -**Output**: `.claude/rules/tech/typescript/` with 4 rule files - -### Frontend Stack - -```bash -/memory:tech-research "typescript-react" -``` - -**Output**: `.claude/rules/tech/typescript-react/` with 5 rule files (includes components.md) - -### Backend Stack - -```bash -/memory:tech-research "python-fastapi" -``` - -**Output**: `.claude/rules/tech/python-fastapi/` with 5 rule files (includes api.md) - -### From Session - -```bash -/memory:tech-research WFS-user-auth-20251104 -``` - -**Workflow**: Extract tech stack from session → Generate rules - ---- - -## Comparison: Rules vs SKILL - -| Aspect | SKILL Memory | Rules | -|--------|--------------|-------| -| Loading | Manual: `Skill("tech")` | Automatic by path | -| Scope | All files when loaded | Only matching files | -| Granularity | Monolithic packages | Per-file-type | -| Context | Full package | Only relevant rules | - -**When to Use**: -- **Rules**: Tech stack conventions per file type -- **SKILL**: Reference docs, APIs, examples for manual lookup diff --git a/.claude/commands/memory/tips.md b/.claude/commands/memory/tips.md new file mode 100644 index 00000000..52082a81 --- /dev/null +++ b/.claude/commands/memory/tips.md @@ -0,0 +1,332 @@ +--- +name: tips +description: Quick note-taking command to capture ideas, snippets, reminders, and insights for later reference +argument-hint: " [--tag ] [--context ]" +allowed-tools: mcp__ccw-tools__core_memory(*), Read(*) +examples: + - /memory:tips "Remember to use Redis for rate limiting" + - /memory:tips "Auth pattern: JWT with refresh tokens" --tag architecture,auth + - /memory:tips "Bug: memory leak in WebSocket handler after 24h" --context websocket-service + - /memory:tips "Performance: lazy loading reduced bundle by 40%" --tag performance +--- + +# Memory Tips Command (/memory:tips) + +## 1. Overview + +The `memory:tips` command provides **quick note-taking** for capturing: +- Quick ideas and insights +- Code snippets and patterns +- Reminders and follow-ups +- Bug notes and debugging hints +- Performance observations +- Architecture decisions +- Library/tool recommendations + +**Core Philosophy**: +- **Speed First**: Minimal friction for capturing thoughts +- **Searchable**: Tagged for easy retrieval +- **Context-Aware**: Optional context linking +- **Lightweight**: No complex session analysis + +## 2. Parameters + +- `` (Required): The tip/note content to save +- `--tag ` (Optional): Comma-separated tags for categorization +- `--context ` (Optional): Related context (file, module, feature) + +**Examples**: +```bash +/memory:tips "Use Zod for runtime validation - better DX than class-validator" +/memory:tips "Redis connection pool: max 10, min 2" --tag config,redis +/memory:tips "Fix needed: race condition in payment processor" --tag bug,payment --context src/payments +``` + +## 3. Structured Output Format + +```markdown +## Tip ID +TIP-YYYYMMDD-HHMMSS + +## Timestamp +YYYY-MM-DD HH:MM:SS + +## Project Root +[Absolute path to project root, e.g., D:\Claude_dms3] + +## Content +[The tip/note content exactly as provided] + +## Tags +[Comma-separated tags, or (none)] + +## Context +[Optional context linking - file, module, or feature reference] + +## Session Link +[WFS-ID if workflow session active, otherwise (none)] + +## Auto-Detected Context +[Files/topics from current conversation if relevant] +``` + +## 4. Field Definitions + +| Field | Purpose | Example | +|-------|---------|---------| +| **Tip ID** | Unique identifier with timestamp | TIP-20260128-143052 | +| **Timestamp** | When tip was created | 2026-01-28 14:30:52 | +| **Project Root** | Current project path | D:\Claude_dms3 | +| **Content** | The actual tip/note | "Use Redis for rate limiting" | +| **Tags** | Categorization labels | architecture, auth, performance | +| **Context** | Related code/feature | src/auth/**, payment-module | +| **Session Link** | Link to workflow session | WFS-auth-20260128 | +| **Auto-Detected Context** | Files from conversation | src/api/handler.ts | + +## 5. Execution Flow + +### Step 1: Parse Arguments + +```javascript +const parseTipsCommand = (input) => { + // Extract note content (everything before flags) + const contentMatch = input.match(/^"([^"]+)"|^([^\s-]+)/); + const content = contentMatch ? (contentMatch[1] || contentMatch[2]) : ''; + + // Extract tags + const tagsMatch = input.match(/--tag\s+([^\s-]+)/); + const tags = tagsMatch ? tagsMatch[1].split(',').map(t => t.trim()) : []; + + // Extract context + const contextMatch = input.match(/--context\s+([^\s-]+)/); + const context = contextMatch ? contextMatch[1] : ''; + + return { content, tags, context }; +}; +``` + +### Step 2: Gather Context + +```javascript +const gatherTipContext = async () => { + // Get project root + const projectRoot = process.cwd(); // or detect from environment + + // Get current session if active + const manifest = await mcp__ccw-tools__session_manager({ + operation: "list", + location: "active" + }); + const sessionId = manifest.sessions?.[0]?.id || null; + + // Auto-detect files from recent conversation + const recentFiles = extractRecentFilesFromConversation(); // Last 5 messages + + return { + projectRoot, + sessionId, + autoDetectedContext: recentFiles + }; +}; +``` + +### Step 3: Generate Structured Text + +```javascript +const generateTipText = (parsed, context) => { + const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 19); + const tipId = `TIP-${new Date().toISOString().slice(0,10).replace(/-/g, '')}-${new Date().toTimeString().slice(0,8).replace(/:/g, '')}`; + + return `## Tip ID +${tipId} + +## Timestamp +${timestamp} + +## Project Root +${context.projectRoot} + +## Content +${parsed.content} + +## Tags +${parsed.tags.length > 0 ? parsed.tags.join(', ') : '(none)'} + +## Context +${parsed.context || '(none)'} + +## Session Link +${context.sessionId || '(none)'} + +## Auto-Detected Context +${context.autoDetectedContext.length > 0 + ? context.autoDetectedContext.map(f => `- ${f}`).join('\n') + : '(none)'}`; +}; +``` + +### Step 4: Save to Core Memory + +```javascript +mcp__ccw-tools__core_memory({ + operation: "import", + text: structuredText +}) +``` + +**Response Format**: +```json +{ + "operation": "import", + "id": "CMEM-YYYYMMDD-HHMMSS", + "message": "Created memory: CMEM-YYYYMMDD-HHMMSS" +} +``` + +### Step 5: Confirm to User + +``` +✓ Tip saved successfully + + ID: CMEM-YYYYMMDD-HHMMSS + Tags: architecture, auth + Context: src/auth/** + + To retrieve: /memory:search "auth patterns" + Or via MCP: core_memory(operation="search", query="auth") +``` + +## 6. Tag Categories (Suggested) + +**Technical**: +- `architecture` - Design decisions and patterns +- `performance` - Optimization insights +- `security` - Security considerations +- `bug` - Bug notes and fixes +- `config` - Configuration settings +- `api` - API design patterns + +**Development**: +- `testing` - Test strategies and patterns +- `debugging` - Debugging techniques +- `refactoring` - Refactoring notes +- `documentation` - Doc improvements + +**Domain Specific**: +- `auth` - Authentication/authorization +- `database` - Database patterns +- `frontend` - UI/UX patterns +- `backend` - Backend logic +- `devops` - Infrastructure and deployment + +**Organizational**: +- `reminder` - Follow-up items +- `research` - Research findings +- `idea` - Feature ideas +- `review` - Code review notes + +## 7. Search Integration + +Tips can be retrieved using: + +```bash +# Via command (if /memory:search exists) +/memory:search "rate limiting" + +# Via MCP tool +mcp__ccw-tools__core_memory({ + operation: "search", + query: "rate limiting", + source_type: "core_memory", + top_k: 10 +}) + +# Via CLI +ccw core-memory search --query "rate limiting" --top-k 10 +``` + +## 8. Quality Checklist + +Before saving: +- [ ] Content is clear and actionable +- [ ] Tags are relevant and consistent +- [ ] Context provides enough reference +- [ ] Auto-detected context is accurate +- [ ] Project root is absolute path +- [ ] Timestamp is properly formatted + +## 9. Best Practices + +### Good Tips Examples + +✅ **Specific and Actionable**: +``` +"Use connection pooling for Redis: { max: 10, min: 2, acquireTimeoutMillis: 30000 }" +--tag config,redis +``` + +✅ **With Context**: +``` +"Auth middleware must validate both access and refresh tokens" +--tag security,auth --context src/middleware/auth.ts +``` + +✅ **Problem + Solution**: +``` +"Memory leak fixed by unsubscribing event listeners in componentWillUnmount" +--tag bug,react --context src/components/Chat.tsx +``` + +### Poor Tips Examples + +❌ **Too Vague**: +``` +"Fix the bug" --tag bug +``` + +❌ **Too Long** (use /memory:compact instead): +``` +"Here's the complete implementation plan for the entire auth system... [3 paragraphs]" +``` + +❌ **No Context**: +``` +"Remember to update this later" +``` + +## 10. Use Cases + +### During Development +```bash +/memory:tips "JWT secret must be 256-bit minimum" --tag security,auth +/memory:tips "Use debounce (300ms) for search input" --tag performance,ux +``` + +### After Bug Fixes +```bash +/memory:tips "Race condition in payment: lock with Redis SETNX" --tag bug,payment +``` + +### Code Review Insights +```bash +/memory:tips "Prefer early returns over nested ifs" --tag style,readability +``` + +### Architecture Decisions +```bash +/memory:tips "Chose PostgreSQL over MongoDB for ACID compliance" --tag architecture,database +``` + +### Library Recommendations +```bash +/memory:tips "Zod > Yup for TypeScript validation - better type inference" --tag library,typescript +``` + +## 11. Notes + +- **Frequency**: Use liberally - capture all valuable insights +- **Retrieval**: Search by tags, content, or context +- **Lifecycle**: Tips persist across sessions +- **Organization**: Tags enable filtering and categorization +- **Integration**: Can reference tips in later workflows +- **Lightweight**: No complex session analysis required diff --git a/.claude/commands/memory/workflow-skill-memory.md b/.claude/commands/memory/workflow-skill-memory.md deleted file mode 100644 index ac483717..00000000 --- a/.claude/commands/memory/workflow-skill-memory.md +++ /dev/null @@ -1,517 +0,0 @@ ---- -name: workflow-skill-memory -description: Process WFS-* archived sessions using universal-executor agents with Gemini analysis to generate workflow-progress SKILL package (sessions-timeline, lessons, conflicts) -argument-hint: "session | all" -allowed-tools: Task(*), TodoWrite(*), Bash(*), Read(*), Write(*) ---- - -# Workflow SKILL Memory Generator - -## Overview - -Generate SKILL package from archived workflow sessions using agent-driven analysis. Supports single-session incremental updates or parallel processing of all sessions. - -**Scope**: Only processes WFS-* workflow sessions. Other session types (e.g., doc sessions) are automatically ignored. - -## Usage - -```bash -/memory:workflow-skill-memory session WFS- # Process single WFS session -/memory:workflow-skill-memory all # Process all WFS sessions in parallel -``` - -## Execution Modes - -### Mode 1: Single Session (`session `) - -**Purpose**: Incremental update - process one archived session and merge into existing SKILL package - -**Workflow**: -1. **Validate session**: Check if session exists in `.workflow/.archives/{session-id}/` -2. **Invoke agent**: Call `universal-executor` to analyze session and update SKILL documents -3. **Agent tasks**: - - Read session data from `.workflow/.archives/{session-id}/` - - Extract lessons, conflicts, and outcomes - - Use Gemini for intelligent aggregation (optional) - - Update or create SKILL documents using templates - - Regenerate SKILL.md index - -**Command Example**: -```bash -/memory:workflow-skill-memory session WFS-user-auth -``` - -**Expected Output**: -``` -Session WFS-user-auth processed -Updated: -- sessions-timeline.md (1 session added) -- lessons-learned.md (3 lessons merged) -- conflict-patterns.md (1 conflict added) -- SKILL.md (index regenerated) -``` - ---- - -### Mode 2: All Sessions (`all`) - -**Purpose**: Full regeneration - process all archived sessions in parallel for complete SKILL package - -**Workflow**: -1. **List sessions**: Read manifest.json to get all archived session IDs -2. **Parallel invocation**: Launch multiple `universal-executor` agents in parallel (one per session) -3. **Agent coordination**: - - Each agent processes one session independently - - Agents use Gemini for analysis - - Agents collect data into JSON (no direct file writes) - - Final aggregator agent merges results and generates SKILL documents - -**Command Example**: -```bash -/memory:workflow-skill-memory all -``` - -**Expected Output**: -``` -All sessions processed in parallel -Sessions: 8 total -Updated: -- sessions-timeline.md (8 sessions) -- lessons-learned.md (24 lessons aggregated) -- conflict-patterns.md (12 conflicts documented) -- SKILL.md (index regenerated) -``` - ---- - -## Implementation Flow - -### Phase 1: Validation and Setup - -**Step 1.1: Parse Command Arguments** - -Extract mode and session ID: -```javascript -if (args === "all") { - mode = "all" -} else if (args.startsWith("session ")) { - mode = "session" - session_id = args.replace("session ", "").trim() -} else { - ERROR = "Invalid arguments. Usage: session | all" - EXIT -} -``` - -**Step 1.2: Validate Archive Directory** -```bash -bash(test -d .workflow/.archives && echo "exists" || echo "missing") -``` - -If missing, report error and exit. - -**Step 1.3: Mode-Specific Validation** - -**Single Session Mode**: -```bash -# Validate session ID format (must start with WFS-) -if [[ ! "$session_id" =~ ^WFS- ]]; then - ERROR = "Invalid session ID format. Only WFS-* sessions are supported" - EXIT -fi - -# Check if session exists -bash(test -d .workflow/.archives/{session_id} && echo "exists" || echo "missing") -``` - -If missing, report error: "Session {session_id} not found in archives" - -**All Sessions Mode**: -```bash -# Read manifest and filter only WFS- sessions -bash(cat .workflow/.archives/manifest.json | jq -r '.archives[].session_id | select(startswith("WFS-"))') -``` - -Store filtered session IDs in array. Ignore doc sessions and other non-WFS sessions. - -**Step 1.4: TodoWrite Initialization** - -**Single Session Mode**: -```javascript -TodoWrite({todos: [ - {"content": "Validate session existence", "status": "completed", "activeForm": "Validating session"}, - {"content": "Invoke agent to process session", "status": "in_progress", "activeForm": "Invoking agent"}, - {"content": "Verify SKILL package updated", "status": "pending", "activeForm": "Verifying update"} -]}) -``` - -**All Sessions Mode**: -```javascript -TodoWrite({todos: [ - {"content": "Read manifest and list sessions", "status": "completed", "activeForm": "Reading manifest"}, - {"content": "Invoke agents in parallel", "status": "in_progress", "activeForm": "Invoking agents"}, - {"content": "Verify SKILL package regenerated", "status": "pending", "activeForm": "Verifying regeneration"} -]}) -``` - ---- - -### Phase 2: Agent Invocation - -#### Single Session Mode - Agent Task - -Invoke `universal-executor` with session-specific task: - -**Agent Prompt Structure**: -``` -Task: Process Workflow Session for SKILL Package - -Context: -- Session ID: {session_id} -- Session Path: .workflow/.archives/{session_id}/ -- Mode: Incremental update - -Objectives: - -1. Read session data: - - workflow-session.json (metadata) - - IMPL_PLAN.md (implementation summary) - - TODO_LIST.md (if exists) - - manifest.json entry for lessons - -2. Extract key information: - - Description, tags, metrics - - Lessons (successes, challenges, watch_patterns) - - Context package path (reference only) - - Key outcomes from IMPL_PLAN - -3. Use Gemini for aggregation (optional): - Command pattern: - ccw cli -p " - PURPOSE: Extract lessons and conflicts from workflow session - TASK: - • Analyze IMPL_PLAN and lessons from manifest - • Identify success patterns and challenges - • Extract conflict patterns with resolutions - • Categorize by functional domain - MODE: analysis - CONTEXT: @IMPL_PLAN.md @workflow-session.json - EXPECTED: Structured lessons and conflicts in JSON format - RULES: Template reference from skill-aggregation.txt - " --tool gemini --mode analysis --cd .workflow/.archives/{session_id} - -3.5. **Generate SKILL.md Description** (CRITICAL for auto-loading): - - Read skill-index.txt template Section: "Description Field Generation" - - Execute command to get project root: - ```bash - git rev-parse --show-toplevel # Example output: /d/Claude_dms3 - ``` - - Apply description format: - ``` - Progressive workflow development history (located at {project_root}). - Load this SKILL when continuing development, analyzing past implementations, - or learning from workflow history, especially when no relevant context exists in memory. - ``` - - **Validation**: - - [ ] Path uses forward slashes (not backslashes) - - [ ] All three use cases present - - [ ] Trigger optimization phrase included - - [ ] Path is absolute (starts with / or drive letter) - -4. Read templates for formatting guidance: - - ~/.claude/workflows/cli-templates/prompts/workflow/skill-sessions-timeline.txt - - ~/.claude/workflows/cli-templates/prompts/workflow/skill-lessons-learned.txt - - ~/.claude/workflows/cli-templates/prompts/workflow/skill-conflict-patterns.txt - - ~/.claude/workflows/cli-templates/prompts/workflow/skill-index.txt - - **CRITICAL**: From skill-index.txt, read these sections: - - "Description Field Generation" - Rules for generating description - - "Variable Substitution Guide" - All required variables - - "Generation Instructions" - Step-by-step generation process - - "Validation Checklist" - Final validation steps - -5. Update SKILL documents: - - sessions-timeline.md: Append new session, update domain grouping - - lessons-learned.md: Merge lessons into categories, update frequencies - - conflict-patterns.md: Add conflicts, update recurring pattern frequencies - - SKILL.md: Regenerate index with updated counts - - **For SKILL.md generation**: - - Follow "Generation Instructions" from skill-index.txt (Steps 1-7) - - Use git command for project_root: `git rev-parse --show-toplevel` - - Apply "Description Field Generation" rules - - Validate using "Validation Checklist" - - Increment version (patch level) - -6. Return result JSON: - { - "status": "success", - "session_id": "{session_id}", - "updates": { - "sessions_added": 1, - "lessons_merged": count, - "conflicts_added": count - } - } -``` - ---- - -#### All Sessions Mode - Parallel Agent Tasks - -**Step 2.1: Launch parallel session analyzers** - -Invoke multiple agents in parallel (one message with multiple Task calls): - -**Per-Session Agent Prompt**: -``` -Task: Extract Session Data for SKILL Package - -Context: -- Session ID: {session_id} -- Mode: Parallel analysis (no direct file writes) - -Objectives: - -1. Read session data (same as single mode) - -2. Extract key information (same as single mode) - -3. Use Gemini for analysis (same as single mode) - -4. Return structured data JSON: - { - "status": "success", - "session_id": "{session_id}", - "data": { - "metadata": { - "description": "...", - "archived_at": "...", - "tags": [...], - "metrics": {...} - }, - "lessons": { - "successes": [...], - "challenges": [...], - "watch_patterns": [...] - }, - "conflicts": [ - { - "type": "architecture|dependencies|testing|performance", - "pattern": "...", - "resolution": "...", - "code_impact": [...] - } - ], - "impl_summary": "First 200 chars of IMPL_PLAN", - "context_package_path": "..." - } - } -``` - -**Step 2.2: Aggregate results** - -After all session agents complete, invoke aggregator agent: - -**Aggregator Agent Prompt**: -``` -Task: Aggregate Session Results and Generate SKILL Package - -Context: -- Mode: Full regeneration -- Input: JSON results from {session_count} session agents - -Objectives: - -1. Aggregate all session data: - - Collect metadata from all sessions - - Merge lessons by category - - Group conflicts by type - - Sort sessions by date - -2. Use Gemini for final aggregation: - ccw cli -p " - PURPOSE: Aggregate lessons and conflicts from all workflow sessions - TASK: - • Group successes by functional domain - • Categorize challenges by severity (HIGH/MEDIUM/LOW) - • Identify recurring conflict patterns - • Calculate frequencies and prioritize - MODE: analysis - CONTEXT: [Provide aggregated JSON data] - EXPECTED: Final aggregated structure for SKILL documents - RULES: Template reference from skill-aggregation.txt - " --tool gemini --mode analysis - -3. Read templates for formatting (same 4 templates as single mode) - -4. Generate all SKILL documents: - - sessions-timeline.md (all sessions, sorted by date) - - lessons-learned.md (aggregated lessons with frequencies) - - conflict-patterns.md (recurring patterns with resolutions) - - SKILL.md (index with progressive loading) - -5. Write files to .claude/skills/workflow-progress/ - -6. Return result JSON: - { - "status": "success", - "sessions_processed": count, - "files_generated": ["SKILL.md", "sessions-timeline.md", ...], - "summary": { - "total_sessions": count, - "functional_domains": [...], - "date_range": "...", - "lessons_count": count, - "conflicts_count": count - } - } -``` - ---- - -### Phase 3: Verification - -**Step 3.1: Check SKILL Package Files** -```bash -bash(ls -lh .claude/skills/workflow-progress/) -``` - -Verify all 4 files exist: -- SKILL.md -- sessions-timeline.md -- lessons-learned.md -- conflict-patterns.md - -**Step 3.2: TodoWrite Completion** - -Mark all tasks as completed. - -**Step 3.3: Display Summary** - -**Single Session Mode**: -``` -Session {session_id} processed successfully - -Updated: -- sessions-timeline.md -- lessons-learned.md -- conflict-patterns.md -- SKILL.md - -SKILL Location: .claude/skills/workflow-progress/SKILL.md -``` - -**All Sessions Mode**: -``` -All sessions processed in parallel - -Sessions: {count} total -Functional Domains: {domain_list} -Date Range: {earliest} - {latest} - -Generated: -- sessions-timeline.md ({count} sessions) -- lessons-learned.md ({lessons_count} lessons) -- conflict-patterns.md ({conflicts_count} conflicts) -- SKILL.md (4-level progressive loading) - -SKILL Location: .claude/skills/workflow-progress/SKILL.md - -Usage: -- Level 0: Quick refresh (~2K tokens) -- Level 1: Recent history (~8K tokens) -- Level 2: Complete analysis (~25K tokens) -- Level 3: Deep dive (~40K tokens) -``` - ---- - -## Agent Guidelines - -### Agent Capabilities - -**universal-executor agents can**: -- Read files from `.workflow/.archives/` -- Execute bash commands -- Call Gemini CLI for intelligent analysis -- Read template files for formatting guidance -- Write SKILL package files (single mode) or return JSON (parallel mode) -- Return structured results - -### Gemini Usage Pattern - -**When to use Gemini**: -- Aggregating lessons from multiple sources -- Identifying recurring patterns -- Classifying conflicts by type and severity -- Extracting structured data from IMPL_PLAN - -**Fallback Strategy**: If Gemini fails or times out, use direct file parsing with structured extraction logic. - ---- - -## Template System - -### Template Files - -All templates located in: `~/.claude/workflows/cli-templates/prompts/workflow/` - -1. **skill-sessions-timeline.txt**: Format for sessions-timeline.md -2. **skill-lessons-learned.txt**: Format for lessons-learned.md -3. **skill-conflict-patterns.txt**: Format for conflict-patterns.md -4. **skill-index.txt**: Format for SKILL.md index -5. **skill-aggregation.txt**: Rules for Gemini aggregation (existing) - -### Template Usage in Agent - -**Agents read templates to understand**: -- File structure and markdown format -- Data sources (which files to read) -- Update strategy (incremental vs full) -- Formatting rules and conventions -- Aggregation logic (for Gemini) - -**Templates are NOT shown in this command documentation** - agents read them directly as needed. - ---- - -## Error Handling - -### Validation Errors -- **No archives directory**: "Error: No workflow archives found at .workflow/.archives/" -- **Invalid session ID format**: "Error: Invalid session ID format. Only WFS-* sessions are supported" -- **Session not found**: "Error: Session {session_id} not found in archives" -- **No WFS sessions in manifest**: "Error: No WFS-* workflow sessions found in manifest.json" - -### Agent Errors -- If agent fails, report error message from agent result -- If Gemini times out, agents use fallback direct parsing -- If template read fails, agents use inline format - -### Recovery -- Single session mode: Can be retried without affecting other sessions -- All sessions mode: If one agent fails, others continue; retry failed sessions individually - - - -## Integration - -### Called by `/workflow:session:complete` - -Automatically invoked after session archival: -```bash -SlashCommand(command="/memory:workflow-skill-memory session {session_id}") -``` - -### Manual Invocation - -Users can manually process sessions: -```bash -/memory:workflow-skill-memory session WFS-custom-feature # Single session -/memory:workflow-skill-memory all # Full regeneration -``` diff --git a/.claude/commands/task/breakdown.md b/.claude/commands/task/breakdown.md deleted file mode 100644 index e0412201..00000000 --- a/.claude/commands/task/breakdown.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -name: breakdown -description: Decompose complex task into subtasks with dependency mapping, creates child task JSONs with parent references and execution order -argument-hint: "[-y|--yes] task-id" ---- - -## Auto Mode - -When `--yes` or `-y`: Auto-confirm breakdown, use recommended subtask structure. - -# Task Breakdown Command (/task:breakdown) - -## Overview -Breaks down complex tasks into executable subtasks with context inheritance and agent assignment. - -## Core Principles -**File Cohesion:** Related files must stay in same task -**10-Task Limit:** Total tasks cannot exceed 10 (triggers re-scoping) - -## Core Features - -**CRITICAL**: Manual breakdown with safety controls to prevent file conflicts and task limit violations. - -### Breakdown Process -1. **Session Check**: Verify active session contains parent task -2. **Task Validation**: Ensure parent is `pending` status -3. **10-Task Limit Check**: Verify breakdown won't exceed total limit -4. **Manual Decomposition**: User defines subtasks with validation -5. **File Conflict Detection**: Warn if same files appear in multiple subtasks -6. **Similar Function Warning**: Alert if subtasks have overlapping functionality -7. **Context Distribution**: Inherit parent requirements and scope -8. **Agent Assignment**: Auto-assign agents based on subtask type -9. **TODO_LIST Update**: Regenerate TODO_LIST.md with new structure - -### Breakdown Rules -- Only `pending` tasks can be broken down -- **Manual breakdown only**: Automated breakdown disabled to prevent violations -- Parent becomes `container` status (not executable) -- Subtasks use format: IMPL-N.M (max 2 levels) -- Context flows from parent to subtasks -- All relationships tracked in JSON -- **10-task limit enforced**: Breakdown rejected if total would exceed 10 tasks -- **File cohesion preserved**: Same files cannot be split across subtasks - -## Usage - -### Basic Breakdown -```bash -/task:breakdown impl-1 -``` - -Interactive process: -``` -Task: Build authentication module -Current total tasks: 6/10 - -MANUAL BREAKDOWN REQUIRED -Define subtasks manually (remaining capacity: 4 tasks): - -1. Enter subtask title: User authentication core - Focus files: models/User.js, routes/auth.js, middleware/auth.js - -2. Enter subtask title: OAuth integration - Focus files: services/OAuthService.js, routes/oauth.js - -FILE CONFLICT DETECTED: - - routes/auth.js appears in multiple subtasks - - Recommendation: Merge related authentication routes - -SIMILAR FUNCTIONALITY WARNING: - - "User authentication" and "OAuth integration" both handle auth - - Consider combining into single task - -# Use AskUserQuestion for confirmation -AskUserQuestion({ - questions: [{ - question: "File conflicts and/or similar functionality detected. How do you want to proceed?", - header: "Confirm", - options: [ - { label: "Proceed with breakdown", description: "Accept the risks and create the subtasks as defined." }, - { label: "Restart breakdown", description: "Discard current subtasks and start over." }, - { label: "Cancel breakdown", description: "Abort the operation and leave the parent task as is." } - ], - multiSelect: false - }] -}) - -User selected: "Proceed with breakdown" - -Task IMPL-1 broken down: -IMPL-1: Build authentication module (container) - ├── IMPL-1.1: User authentication core -> @code-developer - └── IMPL-1.2: OAuth integration -> @code-developer - -Files updated: .task/IMPL-1.json + 2 subtask files + TODO_LIST.md -``` - -## Decomposition Logic - -### Agent Assignment -- **Design/Planning** → `@planning-agent` -- **Implementation** → `@code-developer` -- **Testing** → `@code-developer` (type: "test-gen") -- **Test Validation** → `@test-fix-agent` (type: "test-fix") -- **Review** → `@universal-executor` (optional) - -### Context Inheritance -- Subtasks inherit parent requirements -- Scope refined for specific subtask -- Implementation details distributed appropriately - -## Safety Controls - -### File Conflict Detection -**Validates file cohesion across subtasks:** -- Scans `focus_paths` in all subtasks -- Warns if same file appears in multiple subtasks -- Suggests merging subtasks with overlapping files -- Blocks breakdown if critical conflicts detected - -### Similar Functionality Detection -**Prevents functional overlap:** -- Analyzes subtask titles for similar keywords -- Warns about potential functional redundancy -- Suggests consolidation of related functionality -- Examples: "user auth" + "login system" → merge recommendation - -### 10-Task Limit Enforcement -**Hard limit compliance:** -- Counts current total tasks in session -- Calculates breakdown impact on total -- Rejects breakdown if would exceed 10 tasks -- Suggests re-scoping if limit reached - -### Manual Control Requirements -**User-driven breakdown only:** -- No automatic subtask generation -- User must define each subtask title and scope -- Real-time validation during input -- Confirmation required before execution - -## Implementation Details - -- Complete task JSON schema -- Implementation field structure -- Context inheritance rules -- Agent assignment logic - -## Validation - -### Pre-breakdown Checks -1. Active session exists -2. Task found in session -3. Task status is `pending` -4. Not already broken down -5. **10-task limit compliance**: Total tasks + new subtasks ≤ 10 -6. **Manual mode enabled**: No automatic breakdown allowed - -### Post-breakdown Actions -1. Update parent to `container` status -2. Create subtask JSON files -3. Update parent subtasks list -4. Update session stats -5. **Regenerate TODO_LIST.md** with new hierarchy -6. Validate file paths in focus_paths -7. Update session task count - -## Examples - -### Basic Breakdown -```bash -/task:breakdown impl-1 - -impl-1: Build authentication (container) - ├── impl-1.1: Design schema -> @planning-agent - ├── impl-1.2: Implement logic + tests -> @code-developer - └── impl-1.3: Execute & fix tests -> @test-fix-agent -``` - -## Error Handling - -```bash -# Task not found -Task IMPL-5 not found - -# Already broken down -Task IMPL-1 already has subtasks - -# Wrong status -Cannot breakdown completed task IMPL-2 - -# 10-task limit exceeded -Breakdown would exceed 10-task limit (current: 8, proposed: 4) -Suggestion: Re-scope project into smaller iterations - -# File conflicts detected -File conflict: routes/auth.js appears in IMPL-1.1 and IMPL-1.2 -Recommendation: Merge subtasks or redistribute files - -# Similar functionality warning -Similar functions detected: "user login" and "authentication" -Consider consolidating related functionality - -# Manual breakdown required -Automatic breakdown disabled. Use manual breakdown process. -``` - -**System ensures**: Manual breakdown control with file cohesion enforcement, similar functionality detection, and 10-task limit compliance \ No newline at end of file diff --git a/.claude/commands/task/create.md b/.claude/commands/task/create.md deleted file mode 100644 index 02b70cd9..00000000 --- a/.claude/commands/task/create.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -name: create -description: Generate task JSON from natural language description with automatic file pattern detection, scope inference, and dependency analysis -argument-hint: "\"task title\"" ---- - -# Task Create Command (/task:create) - -## Overview -Creates new implementation tasks with automatic context awareness and ID generation. - -## Core Principles -**Task System:** @~/.claude/workflows/task-core.md - -## Core Features - -### Automatic Behaviors -- **ID Generation**: Auto-generates IMPL-N format (max 2 levels) -- **Context Inheritance**: Inherits from active workflow session -- **JSON Creation**: Creates task JSON in active session -- **Status Setting**: Initial status = "pending" -- **Agent Assignment**: Suggests agent based on task type -- **Session Integration**: Updates workflow session stats - -### Context Awareness -- Validates active workflow session exists -- Avoids duplicate task IDs -- Inherits session requirements and scope -- Suggests task relationships - -## Usage - -### Basic Creation -```bash -/task:create "Build authentication module" -``` - -Output: -``` -Task created: IMPL-1 -Title: Build authentication module -Type: feature -Agent: code-developer -Status: pending -``` - -### Task Types -- `feature` - New functionality (default) -- `bugfix` - Bug fixes -- `refactor` - Code improvements -- `test` - Test implementation -- `docs` - Documentation - -## Task Creation Process - -1. **Session Validation**: Check active workflow session -2. **ID Generation**: Auto-increment IMPL-N -3. **Context Inheritance**: Load workflow context -4. **Implementation Setup**: Initialize implementation field -5. **Agent Assignment**: Select appropriate agent -6. **File Creation**: Save JSON to .task/ directory -7. **Session Update**: Update workflow stats - -**Task Schema**: See @~/.claude/workflows/task-core.md for complete JSON structure - -## Implementation Field Setup - -### Auto-Population Strategy -- **Detailed info**: Extract from task description and scope -- **Missing info**: Mark `pre_analysis` as multi-step array format for later pre-analysis -- **Basic structure**: Initialize with standard template - -### Analysis Triggers -When implementation details incomplete: -```bash -Task requires analysis for implementation details -Suggest running: gemini analysis for file locations and dependencies -``` - -## File Management - -### JSON Task File -- **Location**: `.task/IMPL-[N].json` in active session -- **Content**: Complete task with implementation field -- **Updates**: Session stats only - -### Simple Process -1. Validate session and inputs -2. Generate task JSON -3. Update session stats -4. Notify completion - -## Context Inheritance - -Tasks inherit from: -1. **Active Session** - Requirements and scope from workflow-session.json -2. **Planning Document** - Context from IMPL_PLAN.md -3. **Parent Task** - For subtasks (IMPL-N.M format) - -## Agent Assignment - -Based on task type and title keywords: -- **Build/Implement** → @code-developer -- **Design/Plan** → @planning-agent -- **Test Generation** → @code-developer (type: "test-gen") -- **Test Execution/Fix** → @test-fix-agent (type: "test-fix") -- **Review/Audit** → @universal-executor (optional, only when explicitly requested) - -## Validation Rules - -1. **Session Check** - Active workflow session required -2. **Duplicate Check** - Avoid similar task titles -3. **ID Uniqueness** - Auto-increment task IDs -4. **Schema Validation** - Ensure proper JSON structure - -## Error Handling - -```bash -# No workflow session -No active workflow found -Use: /workflow init "project name" - -# Duplicate task -Similar task exists: IMPL-3 -Continue anyway? (y/n) - -# Max depth exceeded -Cannot create IMPL-1.2.1 (max 2 levels) -Use: IMPL-2 for new main task -``` - -## Examples - -### Feature Task -```bash -/task:create "Implement user authentication" - -Created IMPL-1: Implement user authentication -Type: feature -Agent: code-developer -Status: pending -``` - -### Bug Fix -```bash -/task:create "Fix login validation bug" --type=bugfix - -Created IMPL-2: Fix login validation bug -Type: bugfix -Agent: code-developer -Status: pending -``` \ No newline at end of file diff --git a/.claude/commands/task/execute.md b/.claude/commands/task/execute.md deleted file mode 100644 index 607c556f..00000000 --- a/.claude/commands/task/execute.md +++ /dev/null @@ -1,270 +0,0 @@ ---- -name: execute -description: Execute task JSON using appropriate agent (@doc-generator/@implementation-agent/@test-agent) with pre-analysis context loading and status tracking -argument-hint: "task-id" ---- - -## Command Overview: /task:execute - -**Purpose**: Executes tasks using intelligent agent selection, context preparation, and progress tracking. - - -## Execution Modes - -- **auto (Default)** - - Fully autonomous execution with automatic agent selection. - - Provides progress updates at each checkpoint. - - Automatically completes the task when done. -- **guided** - - Executes step-by-step, requiring user confirmation at each checkpoint. - - Allows for dynamic adjustments and manual review during the process. -- **review** - - Optional manual review using `@universal-executor`. - - Used only when explicitly requested by user. - -## Agent Selection Logic - -The system determines the appropriate agent for a task using the following logic. - -```pseudo -FUNCTION select_agent(task, agent_override): - // A manual override always takes precedence. - // Corresponds to the --agent= flag. - IF agent_override IS NOT NULL: - RETURN agent_override - - // If no override, select based on keywords in the task title. - ELSE: - CASE task.title: - WHEN CONTAINS "Build API", "Implement": - RETURN "@code-developer" - WHEN CONTAINS "Design schema", "Plan": - RETURN "@planning-agent" - WHEN CONTAINS "Write tests", "Generate tests": - RETURN "@code-developer" // type: test-gen - WHEN CONTAINS "Execute tests", "Fix tests", "Validate": - RETURN "@test-fix-agent" // type: test-fix - WHEN CONTAINS "Review code": - RETURN "@universal-executor" // Optional manual review - DEFAULT: - RETURN "@code-developer" // Default agent - END CASE -END FUNCTION -``` - -## Core Execution Protocol - -`Pre-Execution` -> `Execution` -> `Post-Execution` - -### Pre-Execution Protocol - -`Validate Task & Dependencies` **->** `Prepare Execution Context` **->** `Coordinate with TodoWrite` - -- **Validation**: Checks for the task's JSON file in `.task/` and resolves its dependencies. -- **Context Preparation**: Loads task and workflow context, preparing it for the selected agent. -- **Session Context Injection**: Provides workflow directory paths to agents for TODO_LIST.md and summary management. -- **TodoWrite Coordination**: Generates execution Todos and checkpoints, syncing with `TODO_LIST.md`. - -### Post-Execution Protocol - -`Update Task Status` **->** `Generate Summary` **->** `Save Artifacts` **->** `Sync All Progress` **->** `Validate File Integrity` - -- Updates status in the task's JSON file and `TODO_LIST.md`. -- Creates a summary in `.summaries/`. -- Stores outputs and syncs progress across the entire workflow session. - -### Task & Subtask Execution Logic - -This logic defines how single, multiple, or parent tasks are handled. - -```pseudo -FUNCTION execute_task_command(task_id, mode, parallel_flag): - // Handle parent tasks by executing their subtasks. - IF is_parent_task(task_id): - subtasks = get_subtasks(task_id) - EXECUTE_SUBTASK_BATCH(subtasks, mode) - - // Handle wildcard execution (e.g., IMPL-001.*) - ELSE IF task_id CONTAINS "*": - subtasks = find_matching_tasks(task_id) - IF parallel_flag IS true: - EXECUTE_IN_PARALLEL(subtasks) - ELSE: - FOR each subtask in subtasks: - EXECUTE_SINGLE_TASK(subtask, mode) - - // Default case for a single task ID. - ELSE: - EXECUTE_SINGLE_TASK(task_id, mode) -END FUNCTION -``` - -### Error Handling & Recovery Logic - -```pseudo -FUNCTION pre_execution_check(task): - // Ensure dependencies are met before starting. - IF task.dependencies ARE NOT MET: - LOG_ERROR("Cannot execute " + task.id) - LOG_INFO("Blocked by: " + unmet_dependencies) - HALT_EXECUTION() - -FUNCTION on_execution_failure(checkpoint): - // Provide user with recovery options upon failure. - LOG_WARNING("Execution failed at checkpoint " + checkpoint) - PRESENT_OPTIONS([ - "Retry from checkpoint", - "Retry from beginning", - "Switch to guided mode", - "Abort execution" - ]) - AWAIT user_input - // System performs the selected action. -END FUNCTION -``` - - -### Simplified Context Structure (JSON) - -This is the simplified data structure loaded to provide context for task execution. - -```json -{ - "task": { - "id": "IMPL-1", - "title": "Build authentication module", - "type": "feature", - "status": "active", - "agent": "code-developer", - "context": { - "requirements": ["JWT authentication", "OAuth2 support"], - "scope": ["src/auth/*", "tests/auth/*"], - "acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"], - "inherited_from": "WFS-user-auth" - }, - "relations": { - "parent": null, - "subtasks": ["IMPL-1.1", "IMPL-1.2"], - "dependencies": ["IMPL-0"] - }, - "implementation": { - "files": [ - { - "path": "src/auth/login.ts", - "location": { - "function": "authenticateUser", - "lines": "25-65", - "description": "Main authentication logic" - }, - "original_code": "// Code snippet extracted via gemini analysis", - "modifications": { - "current_state": "Basic password authentication only", - "proposed_changes": [ - "Add JWT token generation", - "Implement OAuth2 callback handling", - "Add multi-factor authentication support" - ], - "logic_flow": [ - "validateCredentials() ───► checkUserExists()", - "◊─── if password ───► generateJWT() ───► return token", - "◊─── if OAuth ───► validateOAuthCode() ───► exchangeForToken()", - "◊─── if MFA ───► sendMFACode() ───► awaitVerification()" - ], - "reason": "Support modern authentication standards and security requirements", - "expected_outcome": "Comprehensive authentication system supporting multiple methods" - } - } - ], - "context_notes": { - "dependencies": ["jsonwebtoken", "passport", "speakeasy"], - "affected_modules": ["user-session", "auth-middleware", "api-routes"], - "risks": [ - "Breaking changes to existing login endpoints", - "Token storage and rotation complexity", - "OAuth provider configuration dependencies" - ], - "performance_considerations": "JWT validation adds ~10ms per request, OAuth callbacks may timeout", - "error_handling": "Ensure sensitive authentication errors don't leak user enumeration data" - }, - "pre_analysis": [ - { - "action": "analyze patterns", - "template": "~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt", - "method": "gemini" - } - ] - } - }, - "workflow": { - "session": "WFS-user-auth", - "phase": "IMPLEMENT", - "session_context": { - "workflow_directory": ".workflow/active/WFS-user-auth/", - "todo_list_location": ".workflow/active/WFS-user-auth/TODO_LIST.md", - "summaries_directory": ".workflow/active/WFS-user-auth/.summaries/", - "task_json_location": ".workflow/active/WFS-user-auth/.task/" - } - }, - "execution": { - "agent": "code-developer", - "mode": "auto", - "attempts": 0 - } -} -``` - -### Agent-Specific Context - -Different agents receive context tailored to their function, including implementation details: - -**`@code-developer`**: -- Complete implementation.files array with file paths and locations -- original_code snippets and proposed_changes for precise modifications -- logic_flow diagrams for understanding data flow -- Dependencies and affected modules for integration planning -- Performance and error handling considerations - -**`@planning-agent`**: -- High-level requirements, constraints, success criteria -- Implementation risks and mitigation strategies -- Architecture implications from implementation.context_notes - -**`@test-fix-agent`**: -- Test files to execute from task.context.focus_paths -- Source files to fix from implementation.files[].path -- Expected behaviors from implementation.modifications.logic_flow -- Error conditions to validate from implementation.context_notes.error_handling -- Performance requirements from implementation.context_notes.performance_considerations - -**`@universal-executor`**: -- Used for optional manual reviews when explicitly requested -- Code quality standards and implementation patterns -- Security considerations from implementation.context_notes.risks -- Dependency validation from implementation.context_notes.dependencies -- Architecture compliance checks - -### Simplified File Output - -- **Task JSON File (`.task/.json`)**: Updated with status and last attempt time only. -- **Session File (`workflow-session.json`)**: Updated task stats (completed count). -- **Summary File**: Generated in `.summaries/` upon completion (optional). - -### Simplified Summary Template - -Optional summary file generated at `.summaries/IMPL-[task-id]-summary.md`. - -```markdown -# Task Summary: IMPL-1 Build Authentication Module - -## What Was Done -- Created src/auth/login.ts with JWT validation -- Added tests in tests/auth.test.ts - -## Execution Results -- **Agent**: code-developer -- **Status**: completed - -## Files Modified -- `src/auth/login.ts` (created) -- `tests/auth.test.ts` (created) -``` diff --git a/.claude/commands/task/replan.md b/.claude/commands/task/replan.md deleted file mode 100644 index 2223a3a7..00000000 --- a/.claude/commands/task/replan.md +++ /dev/null @@ -1,441 +0,0 @@ ---- -name: replan -description: Update task JSON with new requirements or batch-update multiple tasks from verification report, tracks changes in task-changes.json -argument-hint: "[-y|--yes] task-id [\"text\"|file.md] | --batch [verification-report.md]" -allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*) ---- - -## Auto Mode - -When `--yes` or `-y`: Auto-confirm updates, use recommended changes. - -# Task Replan Command (/task:replan) - -> **⚠️ DEPRECATION NOTICE**: This command is maintained for backward compatibility. For new workflows, use `/workflow:replan` which provides: -> - Session-level replanning with comprehensive artifact updates -> - Interactive boundary clarification -> - Updates to IMPL_PLAN.md, TODO_LIST.md, and session metadata -> - Better integration with workflow sessions -> -> **Migration**: Replace `/task:replan IMPL-1 "changes"` with `/workflow:replan IMPL-1 "changes"` - -## Overview -Replans individual tasks or batch processes multiple tasks with change tracking and backup management. - -**Modes**: -- **Single Task Mode**: Replan one task with specific changes -- **Batch Mode**: Process multiple tasks from action-plan verification report - -## Key Features -- **Single/Batch Operations**: Single task or multiple tasks from verification report -- **Multiple Input Sources**: Text, files, or verification report -- **Backup Management**: Automatic backup of previous versions -- **Change Documentation**: Track all modifications -- **Progress Tracking**: TodoWrite integration for batch operations - -**CRITICAL**: Validates active session before replanning - -## Operation Modes - -### Single Task Mode - -#### Direct Text (Default) -```bash -/task:replan IMPL-1 "Add OAuth2 authentication support" -``` - -#### File-based Input -```bash -/task:replan IMPL-1 updated-specs.md -``` -Supports: .md, .txt, .json, .yaml - -#### Interactive Mode -```bash -/task:replan IMPL-1 --interactive -``` -Guided step-by-step modification process with validation - -### Batch Mode - -#### From Verification Report -```bash -/task:replan --batch ACTION_PLAN_VERIFICATION.md -``` - -**Workflow**: -1. Parse verification report to extract replan recommendations -2. Create TodoWrite task list for all modifications -3. Process each task sequentially with confirmation -4. Track progress and generate summary report - -**Auto-detection**: If input file contains "Action Plan Verification Report" header, automatically enters batch mode - -## Replanning Process - -### Single Task Process - -1. **Load & Validate**: Read task JSON and validate session -2. **Parse Input**: Process changes from input source -3. **Create Backup**: Save previous version to backup folder -4. **Update Task**: Modify JSON structure and relationships -5. **Save Changes**: Write updated task and increment version -6. **Update Session**: Reflect changes in workflow stats - -### Batch Process - -1. **Parse Verification Report**: Extract all replan recommendations -2. **Initialize TodoWrite**: Create task list for tracking -3. **For Each Task**: - - Mark todo as in_progress - - Load and validate task JSON - - Create backup - - Apply recommended changes - - Save updated task - - Mark todo as completed -4. **Generate Summary**: Report all changes and backup locations - -## Backup Management - -### Backup Tracking -Tasks maintain backup history: -```json -{ - "id": "IMPL-1", - "version": "1.2", - "replan_history": [ - { - "version": "1.2", - "reason": "Add OAuth2 support", - "input_source": "direct_text", - "backup_location": ".task/backup/IMPL-1-v1.1.json", - "timestamp": "2025-10-17T10:30:00Z" - } - ] -} -``` - -**Complete schema**: See @~/.claude/workflows/task-core.md - -### File Structure -``` -.task/ -├── IMPL-1.json # Current version -├── backup/ -│ ├── IMPL-1-v1.0.json # Original version -│ ├── IMPL-1-v1.1.json # Previous backup -│ └── IMPL-1-v1.2.json # Latest backup -└── [new subtasks as needed] -``` - -**Backup Naming**: `{task-id}-v{version}.json` - -## Implementation Updates - -### Change Detection -Tracks modifications to: -- Files in implementation.files array -- Dependencies and affected modules -- Risk assessments and performance notes -- Logic flows and code locations - -### Analysis Triggers -May require gemini re-analysis when: -- New files need code extraction -- Function locations change -- Dependencies require re-evaluation - -## Document Updates - -### Planning Document -May update IMPL_PLAN.md sections when task structure changes significantly - -### TODO List Sync -If TODO_LIST.md exists, synchronizes: -- New subtasks (with [ ] checkbox) -- Modified tasks (marked as updated) -- Removed subtasks (deleted from list) - -## Change Documentation - -### Change Summary -Generates brief change log with: -- Version increment (1.1 → 1.2) -- Input source and reason -- Key modifications made -- Files updated/created -- Backup location - -## Session Updates - -Updates workflow-session.json with: -- Modified task tracking -- Task count changes (if subtasks added/removed) -- Last modification timestamps - -## Rollback Support - -```bash -/task:replan IMPL-1 --rollback v1.1 - -Rollback to version 1.1: -- Restore task from backup/.../IMPL-1-v1.1.json -- Remove new subtasks if any -- Update session stats - -# Use AskUserQuestion for confirmation -AskUserQuestion({ - questions: [{ - question: "Are you sure you want to roll back this task to a previous version?", - header: "Confirm", - options: [ - { label: "Yes, rollback", description: "Restore the task from the selected backup." }, - { label: "No, cancel", description: "Keep the current version of the task." } - ], - multiSelect: false - }] -}) - -User selected: "Yes, rollback" - -Task rolled back to version 1.1 -``` - -## Batch Processing with TodoWrite - -### Progress Tracking -When processing multiple tasks, automatically creates TodoWrite task list: - -```markdown -**Batch Replan Progress**: -- [x] IMPL-002: Add FR-12 draft saving acceptance criteria -- [x] IMPL-003: Add FR-14 history tracking acceptance criteria -- [ ] IMPL-004: Add FR-09 response surface explicit coverage -- [ ] IMPL-008: Add NFR performance validation steps -``` - -### Batch Report -After completion, generates summary: -```markdown -## Batch Replan Summary - -**Total Tasks**: 4 -**Successful**: 3 -**Failed**: 1 -**Skipped**: 0 - -### Changes Made -- IMPL-002 v1.0 → v1.1: Added FR-12 acceptance criteria -- IMPL-003 v1.0 → v1.1: Added FR-14 acceptance criteria -- IMPL-004 v1.0 → v1.1: Added FR-09 explicit coverage - -### Backups Created -- .task/backup/IMPL-002-v1.0.json -- .task/backup/IMPL-003-v1.0.json -- .task/backup/IMPL-004-v1.0.json - -### Errors -- IMPL-008: File not found (task may have been renamed) -``` - -## Examples - -### Single Task - Text Input -```bash -/task:replan IMPL-1 "Add OAuth2 authentication support" - -Processing changes... -Proposed updates: -+ Add OAuth2 integration -+ Update authentication flow - -# Use AskUserQuestion for confirmation -AskUserQuestion({ - questions: [{ - question: "Do you want to apply these changes to the task?", - header: "Apply", - options: [ - { label: "Yes, apply", description: "Create new version with these changes." }, - { label: "No, cancel", description: "Discard changes and keep current version." } - ], - multiSelect: false - }] -}) - -User selected: "Yes, apply" - -Version 1.2 created -Context updated -Backup saved to .task/backup/IMPL-1-v1.1.json -``` - -### Single Task - File Input -```bash -/task:replan IMPL-2 requirements.md - -Loading requirements.md... -Applying specification changes... - -Task updated with new requirements -Version 1.1 created -Backup saved to .task/backup/IMPL-2-v1.0.json -``` - -### Batch Mode - From Verification Report -```bash -/task:replan --batch .workflow/active/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md - -Parsing verification report... -Found 4 tasks requiring replanning: -- IMPL-002: Add FR-12 draft saving acceptance criteria -- IMPL-003: Add FR-14 history tracking acceptance criteria -- IMPL-004: Add FR-09 response surface explicit coverage -- IMPL-008: Add NFR performance validation steps - -Creating task tracking list... - -Processing IMPL-002... -Backup created: .task/backup/IMPL-002-v1.0.json -Updated to v1.1 - -Processing IMPL-003... -Backup created: .task/backup/IMPL-003-v1.0.json -Updated to v1.1 - -Processing IMPL-004... -Backup created: .task/backup/IMPL-004-v1.0.json -Updated to v1.1 - -Processing IMPL-008... -Backup created: .task/backup/IMPL-008-v1.0.json -Updated to v1.1 - -Batch replan completed: 4/4 successful -Summary report saved -``` - -### Batch Mode - Auto-detection -```bash -# If file contains "Action Plan Verification Report", auto-enters batch mode -/task:replan ACTION_PLAN_VERIFICATION.md - -Detected verification report format -Entering batch mode... -[same as above] -``` - -## Error Handling - -### Single Task Errors -```bash -# Task not found -Task IMPL-5 not found -Check task ID with /workflow:status - -# Task completed -Task IMPL-1 is completed (cannot replan) -Create new task for additional work - -# File not found -File requirements.md not found -Check file path - -# No input provided -Please specify changes needed -Provide text, file, or verification report -``` - -### Batch Mode Errors -```bash -# Invalid verification report -File does not contain valid verification report format -Check report structure or use single task mode - -# Partial failures -Batch completed with errors: 3/4 successful -Review error details in summary report - -# No replan recommendations found -Verification report contains no replan recommendations -Check report content or use /workflow:plan-verify first -``` - -## Batch Mode Integration - -### Input Format Expectations -Batch mode parses verification reports looking for: - -1. **Required Actions Section**: Commands like `/task:replan IMPL-X "changes"` -2. **Findings Table**: Task IDs with recommendations -3. **Next Actions Section**: Specific replan commands - -**Example Patterns**: -```markdown -#### 1. HIGH Priority - Address FR Coverage Gaps -/task:replan IMPL-004 " -Add explicit acceptance criteria: -- FR-09: Response surface 3D visualization -" - -#### 2. MEDIUM Priority - Enhance NFR Coverage -/task:replan IMPL-008 " -Add performance testing: -- NFR-01: Load test API endpoints -" -``` - -### Extraction Logic -1. Scan for `/task:replan` commands in report -2. Extract task ID and change description -3. Group by priority (HIGH, MEDIUM, LOW) -4. Process in priority order with TodoWrite tracking - -### Confirmation Behavior -- **Default**: Confirm each task before applying -- **With `--auto-confirm`**: Apply all changes without prompting - ```bash - /task:replan --batch report.md --auto-confirm - ``` - -## Implementation Details - -### Backup Management -```typescript -// Backup file naming convention -const backupPath = `.task/backup/${taskId}-v${previousVersion}.json`; - -// Backup metadata in task JSON -{ - "replan_history": [ - { - "version": "1.2", - "timestamp": "2025-10-17T10:30:00Z", - "reason": "Add FR-09 explicit coverage", - "input_source": "batch_verification_report", - "backup_location": ".task/backup/IMPL-004-v1.1.json" - } - ] -} -``` - -### TodoWrite Integration -```typescript -// Initialize tracking for batch mode -TodoWrite({ - todos: taskList.map(task => ({ - content: `${task.id}: ${task.changeDescription}`, - status: "pending", - activeForm: `Replanning ${task.id}` - })) -}); - -// Update progress during processing -TodoWrite({ - todos: updateTaskStatus(taskId, "in_progress") -}); - -// Mark completed -TodoWrite({ - todos: updateTaskStatus(taskId, "completed") -}); -``` \ No newline at end of file diff --git a/.claude/commands/version.md b/.claude/commands/version.md deleted file mode 100644 index e6382674..00000000 --- a/.claude/commands/version.md +++ /dev/null @@ -1,254 +0,0 @@ ---- -name: version -description: Display Claude Code version information and check for updates -allowed-tools: Bash(*) ---- - -# Version Command (/version) - -## Purpose -Display local and global installation versions, check for the latest updates from GitHub, and provide upgrade recommendations. - -## Execution Flow -1. **Local Version Check**: Read version information from `./.claude/version.json` if it exists. -2. **Global Version Check**: Read version information from `~/.claude/version.json` if it exists. -3. **Fetch Remote Versions**: Use GitHub API to get the latest stable release tag and the latest commit hash from the main branch. -4. **Compare & Suggest**: Compare installed versions with the latest remote versions and provide upgrade suggestions if applicable. - -## Step 1: Check Local Version - -### Check if local version.json exists -```bash -bash(test -f ./.claude/version.json && echo "found" || echo "not_found") -``` - -### Read local version (if exists) -```bash -bash(cat ./.claude/version.json) -``` - -### Extract version with jq (preferred) -```bash -bash(cat ./.claude/version.json | grep -o '"version": *"[^"]*"' | cut -d'"' -f4) -``` - -### Extract installation date -```bash -bash(cat ./.claude/version.json | grep -o '"installation_date_utc": *"[^"]*"' | cut -d'"' -f4) -``` - -**Output Format**: -``` -Local Version: 3.2.1 -Installed: 2025-10-03T12:00:00Z -``` - -## Step 2: Check Global Version - -### Check if global version.json exists -```bash -bash(test -f ~/.claude/version.json && echo "found" || echo "not_found") -``` - -### Read global version -```bash -bash(cat ~/.claude/version.json) -``` - -### Extract version -```bash -bash(cat ~/.claude/version.json | grep -o '"version": *"[^"]*"' | cut -d'"' -f4) -``` - -### Extract installation date -```bash -bash(cat ~/.claude/version.json | grep -o '"installation_date_utc": *"[^"]*"' | cut -d'"' -f4) -``` - -**Output Format**: -``` -Global Version: 3.2.1 -Installed: 2025-10-03T12:00:00Z -``` - -## Step 3: Fetch Latest Stable Release - -### Call GitHub API for latest release (with timeout) -```bash -bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/releases/latest" 2>/dev/null, timeout: 30000) -``` - -### Extract tag name (version) -```bash -bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/releases/latest" 2>/dev/null | grep -o '"tag_name": *"[^"]*"' | head -1 | cut -d'"' -f4, timeout: 30000) -``` - -### Extract release name -```bash -bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/releases/latest" 2>/dev/null | grep -o '"name": *"[^"]*"' | head -1 | cut -d'"' -f4, timeout: 30000) -``` - -### Extract published date -```bash -bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/releases/latest" 2>/dev/null | grep -o '"published_at": *"[^"]*"' | cut -d'"' -f4, timeout: 30000) -``` - -**Output Format**: -``` -Latest Stable: v3.2.2 -Release: v3.2.2: Independent Test-Gen Workflow with Cross-Session Context -Published: 2025-10-03T04:10:08Z -``` - -## Step 4: Fetch Latest Main Branch - -### Call GitHub API for latest commit on main (with timeout) -```bash -bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/main" 2>/dev/null, timeout: 30000) -``` - -### Extract commit SHA (short) -```bash -bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/main" 2>/dev/null | grep -o '"sha": *"[^"]*"' | head -1 | cut -d'"' -f4 | cut -c1-7, timeout: 30000) -``` - -### Extract commit message (first line only) -```bash -bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/main" 2>/dev/null | grep '"message":' | cut -d'"' -f4 | cut -d'\' -f1, timeout: 30000) -``` - -### Extract commit date -```bash -bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/main" 2>/dev/null | grep -o '"date": *"[^"]*"' | head -1 | cut -d'"' -f4, timeout: 30000) -``` - -**Output Format**: -``` -Latest Dev: a03415b -Message: feat: Add version tracking and upgrade check system -Date: 2025-10-03T04:46:44Z -``` - -## Step 5: Compare Versions and Suggest Upgrade - -### Normalize versions (remove 'v' prefix) -```bash -bash(echo "v3.2.1" | sed 's/^v//') -``` - -### Compare two versions -```bash -bash(printf "%s\n%s" "3.2.1" "3.2.2" | sort -V | tail -n 1) -``` - -### Check if versions are equal -```bash -# If equal: Up to date -# If remote newer: Upgrade available -# If local newer: Development version -``` - -**Output Scenarios**: - -**Scenario 1: Up to date** -``` -You are on the latest stable version (3.2.1) -``` - -**Scenario 2: Upgrade available** -``` -A newer stable version is available: v3.2.2 -Your version: 3.2.1 - -To upgrade: -PowerShell: iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -Bash: bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh) -``` - -**Scenario 3: Development version** -``` -You are running a development version (3.4.0-dev) -This is newer than the latest stable release (v3.3.0) -``` - -## Simple Bash Commands - -### Basic Operations -```bash -# Check local version file -bash(test -f ./.claude/version.json && cat ./.claude/version.json) - -# Check global version file -bash(test -f ~/.claude/version.json && cat ~/.claude/version.json) - -# Extract version from JSON -bash(cat version.json | grep -o '"version": *"[^"]*"' | cut -d'"' -f4) - -# Extract date from JSON -bash(cat version.json | grep -o '"installation_date_utc": *"[^"]*"' | cut -d'"' -f4) - -# Fetch latest release (with timeout) -bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/releases/latest" 2>/dev/null, timeout: 30000) - -# Extract tag name -bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/releases/latest" 2>/dev/null | grep -o '"tag_name": *"[^"]*"' | cut -d'"' -f4, timeout: 30000) - -# Extract release name -bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/releases/latest" 2>/dev/null | grep -o '"name": *"[^"]*"' | head -1 | cut -d'"' -f4, timeout: 30000) - -# Fetch latest commit (with timeout) -bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/main" 2>/dev/null, timeout: 30000) - -# Extract commit SHA -bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/main" 2>/dev/null | grep -o '"sha": *"[^"]*"' | head -1 | cut -d'"' -f4 | cut -c1-7, timeout: 30000) - -# Extract commit message (first line) -bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/main" 2>/dev/null | grep '"message":' | cut -d'"' -f4 | cut -d'\' -f1, timeout: 30000) - -# Compare versions -bash(printf "%s\n%s" "3.2.1" "3.2.2" | sort -V | tail -n 1) - -# Remove 'v' prefix -bash(echo "v3.2.1" | sed 's/^v//') -``` - -## Error Handling - -### No installation found -``` -WARNING: Claude Code Workflow not installed -Install using: -PowerShell: iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1) -``` - -### Network error -``` -ERROR: Could not fetch latest version from GitHub -Check your network connection -``` - -### Invalid version.json -``` -ERROR: version.json is invalid or corrupted -``` - -## Design Notes - -- Uses simple, direct bash commands instead of complex functions -- Each step is independent and can be executed separately -- Fallback to grep/sed for JSON parsing (no jq dependency required) -- Network calls use curl with error suppression and 30-second timeout -- Version comparison uses `sort -V` for accurate semantic versioning -- Use `/commits/main` API instead of `/branches/main` for more reliable commit info -- Extract first line of commit message using `cut -d'\' -f1` to handle JSON escape sequences - -## API Endpoints - -### GitHub API Used -- **Latest Release**: `https://api.github.com/repos/catlog22/Claude-Code-Workflow/releases/latest` - - Fields: `tag_name`, `name`, `published_at` -- **Latest Commit**: `https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/main` - - Fields: `sha`, `commit.message`, `commit.author.date` - -### Timeout Configuration -All network calls should use `timeout: 30000` (30 seconds) to handle slow connections. diff --git a/.claude/commands/workflow/brainstorm/api-designer.md b/.claude/commands/workflow/brainstorm/api-designer.md deleted file mode 100644 index f260e95b..00000000 --- a/.claude/commands/workflow/brainstorm/api-designer.md +++ /dev/null @@ -1,587 +0,0 @@ ---- -name: api-designer -description: Generate or update api-designer/analysis.md addressing guidance-specification discussion points for API design perspective -argument-hint: "optional topic - uses existing framework if available" -allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) ---- - -## 🔌 **API Designer Analysis Generator** - -### Purpose -**Specialized command for generating api-designer/analysis.md** that addresses guidance-specification.md discussion points from backend API design perspective. Creates or updates role-specific analysis with framework references. - -### Core Function -- **Framework-based Analysis**: Address each discussion point in guidance-specification.md -- **API Design Focus**: RESTful/GraphQL API design, endpoint structure, and contract definition -- **Update Mechanism**: Create new or update existing analysis.md -- **Agent Delegation**: Use conceptual-planning-agent for analysis generation - -### Analysis Scope -- **API Architecture**: RESTful/GraphQL design patterns and best practices -- **Endpoint Design**: Resource modeling, URL structure, and HTTP method selection -- **Data Contracts**: Request/response schemas, validation rules, and data transformation -- **API Documentation**: OpenAPI/Swagger specifications and developer experience - -### Role Boundaries & Responsibilities - -#### **What This Role OWNS (API Contract Within Architectural Framework)** -- **API Contract Definition**: Specific endpoint paths, HTTP methods, and status codes -- **Resource Modeling**: Mapping domain entities to RESTful resources or GraphQL types -- **Request/Response Schemas**: Detailed data contracts, validation rules, and error formats -- **API Versioning Strategy**: Version management, deprecation policies, and migration paths -- **Developer Experience**: API documentation (OpenAPI/Swagger), code examples, and SDKs - -#### **What This Role DOES NOT Own (Defers to Other Roles)** -- **System Architecture Decisions**: Microservices vs monolithic, overall communication patterns → Defers to **System Architect** -- **Canonical Data Model**: Underlying data schemas and entity relationships → Defers to **Data Architect** -- **UI/Frontend Integration**: How clients consume the API → Defers to **UI Designer** - -#### **Handoff Points** -- **FROM System Architect**: Receives architectural constraints (REST vs GraphQL, sync vs async) that define the design space -- **FROM Data Architect**: Receives canonical data model and translates it into public API data contracts (as projection/view) -- **TO Frontend Teams**: Provides complete API specifications, documentation, and integration guides - -## ⚙️ **Execution Protocol** - -### Phase 1: Session & Framework Detection -```bash -# Check active session and framework -CHECK: find .workflow/active/ -name "WFS-*" -type d -IF active_session EXISTS: - session_id = get_active_session() - brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/ - - CHECK: brainstorm_dir/guidance-specification.md - IF EXISTS: - framework_mode = true - load_framework = true - ELSE: - IF topic_provided: - framework_mode = false # Create analysis without framework - ELSE: - ERROR: "No framework found and no topic provided" -``` - -### Phase 2: Analysis Mode Detection -```bash -# Check existing analysis -CHECK: brainstorm_dir/api-designer/analysis.md -IF EXISTS: - SHOW existing analysis summary - ASK: "Analysis exists. Do you want to:" - OPTIONS: - 1. "Update with new insights" → Update existing - 2. "Replace completely" → Generate new - 3. "Cancel" → Exit without changes -ELSE: - CREATE new analysis -``` - -### Phase 3: Agent Task Generation -**Framework-Based Analysis** (when guidance-specification.md exists): -```bash -Task(subagent_type="conceptual-planning-agent", - run_in_background=false, - prompt="Generate API designer analysis addressing topic framework - - ## Framework Integration Required - **MANDATORY**: Load and address guidance-specification.md discussion points - **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md - **Output Location**: {session.brainstorm_dir}/api-designer/analysis.md - - ## Analysis Requirements - 1. **Load Topic Framework**: Read guidance-specification.md completely - 2. **Address Each Discussion Point**: Respond to all 5 framework sections from API design perspective - 3. **Include Framework Reference**: Start analysis.md with @../guidance-specification.md - 4. **API Design Focus**: Emphasize endpoint structure, data contracts, versioning strategies - 5. **Structured Response**: Use framework structure for analysis organization - - ## Framework Sections to Address - - Core Requirements (from API design perspective) - - Technical Considerations (detailed API architecture analysis) - - User Experience Factors (developer experience and API usability) - - Implementation Challenges (API design risks and solutions) - - Success Metrics (API performance metrics and adoption tracking) - - ## Output Structure Required - ```markdown - # API Designer Analysis: [Topic] - - **Framework Reference**: @../guidance-specification.md - **Role Focus**: Backend API Design and Contract Definition - - ## Core Requirements Analysis - [Address framework requirements from API design perspective] - - ## Technical Considerations - [Detailed API architecture and endpoint design analysis] - - ## Developer Experience Factors - [API usability, documentation, and integration ease] - - ## Implementation Challenges - [API design risks and mitigation strategies] - - ## Success Metrics - [API performance metrics, adoption rates, and developer satisfaction] - - ## API Design-Specific Recommendations - [Detailed API design recommendations and best practices] - ```", - description="Generate API designer framework-based analysis") -``` - -### Phase 4: Update Mechanism -**Analysis Update Process**: -```bash -# For existing analysis updates -IF update_mode = "incremental": - Task(subagent_type="conceptual-planning-agent", - run_in_background=false, - prompt="Update existing API designer analysis - - ## Current Analysis Context - **Existing Analysis**: @{session.brainstorm_dir}/api-designer/analysis.md - **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md - - ## Update Requirements - 1. **Preserve Structure**: Maintain existing analysis structure - 2. **Add New Insights**: Integrate new API design insights and recommendations - 3. **Framework Alignment**: Ensure continued alignment with topic framework - 4. **API Updates**: Add new endpoint patterns, versioning strategies, documentation improvements - 5. **Maintain References**: Keep @../guidance-specification.md reference - - ## Update Instructions - - Read existing analysis completely - - Identify areas for enhancement or new insights - - Add API design depth while preserving original structure - - Update recommendations with new API design patterns and approaches - - Maintain framework discussion point addressing", - description="Update API designer analysis incrementally") -``` - -## Document Structure - -### Output Files -``` -.workflow/active/WFS-[topic]/.brainstorming/ -├── guidance-specification.md # Input: Framework (if exists) -└── api-designer/ - └── analysis.md # ★ OUTPUT: Framework-based analysis -``` - -### Analysis Structure -**Required Elements**: -- **Framework Reference**: @../guidance-specification.md (if framework exists) -- **Role Focus**: Backend API Design and Contract Definition perspective -- **5 Framework Sections**: Address each framework discussion point -- **API Design Recommendations**: Endpoint-specific insights and solutions - -## ⚡ **Two-Step Execution Flow** - -### ⚠️ Session Management - FIRST STEP -Session detection and selection: -```bash -# Check for active sessions -active_sessions=$(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null) -if [ multiple_sessions ]; then - prompt_user_to_select_session() -else - use_existing_or_create_new() -fi -``` - -### Step 1: Context Gathering Phase -**API Designer Perspective Questioning** - -Before agent assignment, gather comprehensive API design context: - -#### 📋 Role-Specific Questions -1. **API Type & Architecture** - - RESTful, GraphQL, or hybrid API approach? - - Synchronous vs asynchronous communication patterns? - - Real-time requirements (WebSocket, Server-Sent Events)? - -2. **Resource Modeling & Endpoints** - - What are the core domain resources/entities? - - Expected CRUD operations for each resource? - - Complex query requirements (filtering, sorting, pagination)? - -3. **Data Contracts & Validation** - - Request/response data format requirements (JSON, XML, Protocol Buffers)? - - Input validation and sanitization requirements? - - Data transformation and mapping needs? - -4. **API Management & Governance** - - API versioning strategy requirements? - - Authentication and authorization mechanisms? - - Rate limiting and throttling requirements? - - API documentation and developer portal needs? - -5. **Integration & Compatibility** - - Client platforms consuming the API (web, mobile, third-party)? - - Backward compatibility requirements? - - External API integrations needed? - -#### Context Validation -- **Minimum Response**: Each answer must be ≥50 characters -- **Re-prompting**: Insufficient detail triggers follow-up questions -- **Context Storage**: Save responses to `.brainstorming/api-designer-context.md` - -### Step 2: Agent Assignment with Flow Control -**Dedicated Agent Execution** - -```bash -Task(conceptual-planning-agent): " -[FLOW_CONTROL] - -Execute dedicated api-designer conceptual analysis for: {topic} - -ASSIGNED_ROLE: api-designer -OUTPUT_LOCATION: .brainstorming/api-designer/ -USER_CONTEXT: {validated_responses_from_context_gathering} - -Flow Control Steps: -[ - { - \"step\": \"load_role_template\", - \"action\": \"Load api-designer planning template\", - \"command\": \"bash($(cat ~/.claude/workflows/cli-templates/planning-roles/api-designer.md))\", - \"output_to\": \"role_template\" - } -] - -Conceptual Analysis Requirements: -- Apply api-designer perspective to topic analysis -- Focus on endpoint design, data contracts, and API governance -- Use loaded role template framework for analysis structure -- Generate role-specific deliverables in designated output location -- Address all user context from questioning phase - -Deliverables: -- analysis.md: Main API design analysis -- api-specification.md: Detailed endpoint specifications -- data-contracts.md: Request/response schemas and validation rules -- api-documentation.md: API documentation strategy and templates - -Embody api-designer role expertise for comprehensive conceptual planning." -``` - -### Progress Tracking -TodoWrite tracking for two-step process: -```json -[ - {"content": "Gather API designer context through role-specific questioning", "status": "in_progress", "activeForm": "Gathering context"}, - {"content": "Validate context responses and save to api-designer-context.md", "status": "pending", "activeForm": "Validating context"}, - {"content": "Load api-designer planning template via flow control", "status": "pending", "activeForm": "Loading template"}, - {"content": "Execute dedicated conceptual-planning-agent for api-designer role", "status": "pending", "activeForm": "Executing agent"} -] -``` - -## 📊 **Output Specification** - -### Output Location -``` -.workflow/active/WFS-{topic-slug}/.brainstorming/api-designer/ -├── analysis.md # Primary API design analysis -├── api-specification.md # Detailed endpoint specifications (OpenAPI/Swagger) -├── data-contracts.md # Request/response schemas and validation rules -├── versioning-strategy.md # API versioning and backward compatibility plan -└── developer-guide.md # API usage documentation and integration examples -``` - -### Document Templates - -#### analysis.md Structure -```markdown -# API Design Analysis: {Topic} -*Generated: {timestamp}* - -## Executive Summary -[Key API design findings and recommendations overview] - -## API Architecture Overview -### API Type Selection (REST/GraphQL/Hybrid) -### Communication Patterns -### Authentication & Authorization Strategy - -## Resource Modeling -### Core Domain Resources -### Resource Relationships -### URL Structure and Naming Conventions - -## Endpoint Design -### Resource Endpoints -- GET /api/v1/resources -- POST /api/v1/resources -- GET /api/v1/resources/{id} -- PUT /api/v1/resources/{id} -- DELETE /api/v1/resources/{id} - -### Query Parameters -- Filtering: ?filter[field]=value -- Sorting: ?sort=field,-field2 -- Pagination: ?page=1&limit=20 - -### HTTP Methods and Status Codes -- Success responses (2xx) -- Client errors (4xx) -- Server errors (5xx) - -## Data Contracts -### Request Schemas -[JSON Schema or OpenAPI definitions] - -### Response Schemas -[JSON Schema or OpenAPI definitions] - -### Validation Rules -- Required fields -- Data types and formats -- Business logic constraints - -## API Versioning Strategy -### Versioning Approach (URL/Header/Accept) -### Version Lifecycle Management -### Deprecation Policy -### Migration Paths - -## Security & Governance -### Authentication Mechanisms -- OAuth 2.0 / JWT / API Keys -### Authorization Patterns -- RBAC / ABAC / Resource-based -### Rate Limiting & Throttling -### CORS and Security Headers - -## Error Handling -### Standard Error Response Format -```json -{ - "error": { - "code": "ERROR_CODE", - "message": "Human-readable error message", - "details": [], - "trace_id": "uuid" - } -} -``` - -### Error Code Taxonomy -### Validation Error Responses - -## API Documentation -### OpenAPI/Swagger Specification -### Developer Portal Requirements -### Code Examples and SDKs -### Changelog and Migration Guides - -## Performance Optimization -### Response Caching Strategies -### Compression (gzip, brotli) -### Field Selection (sparse fieldsets) -### Bulk Operations and Batch Endpoints - -## Monitoring & Observability -### API Metrics -- Request count, latency, error rates -- Endpoint usage analytics -### Logging Strategy -### Distributed Tracing - -## Developer Experience -### API Usability Assessment -### Integration Complexity -### SDK and Client Library Needs -### Sandbox and Testing Environments -``` - -#### api-specification.md Structure -```markdown -# API Specification: {Topic} -*OpenAPI 3.0 Specification* - -## API Information -- **Title**: {API Name} -- **Version**: 1.0.0 -- **Base URL**: https://api.example.com/v1 -- **Contact**: api-team@example.com - -## Endpoints - -### Users API - -#### GET /users -**Description**: Retrieve a list of users - -**Parameters**: -- `page` (query, integer): Page number (default: 1) -- `limit` (query, integer): Items per page (default: 20, max: 100) -- `sort` (query, string): Sort field (e.g., "created_at", "-updated_at") -- `filter[status]` (query, string): Filter by user status - -**Response 200**: -```json -{ - "data": [ - { - "id": "uuid", - "username": "string", - "email": "string", - "created_at": "2025-10-15T00:00:00Z" - } - ], - "meta": { - "page": 1, - "limit": 20, - "total": 100 - }, - "links": { - "self": "/users?page=1", - "next": "/users?page=2", - "prev": null - } -} -``` - -#### POST /users -**Description**: Create a new user - -**Request Body**: -```json -{ - "username": "string (required, 3-50 chars)", - "email": "string (required, valid email)", - "password": "string (required, min 8 chars)", - "profile": { - "first_name": "string (optional)", - "last_name": "string (optional)" - } -} -``` - -**Response 201**: -```json -{ - "data": { - "id": "uuid", - "username": "string", - "email": "string", - "created_at": "2025-10-15T00:00:00Z" - } -} -``` - -**Response 400** (Validation Error): -```json -{ - "error": { - "code": "VALIDATION_ERROR", - "message": "Request validation failed", - "details": [ - { - "field": "email", - "message": "Invalid email format" - } - ] - } -} -``` - -[Continue for all endpoints...] - -## Authentication - -### OAuth 2.0 Flow -1. Client requests authorization -2. User grants permission -3. Client receives access token -4. Client uses token in requests - -**Header Format**: -``` -Authorization: Bearer {access_token} -``` - -## Rate Limiting - -**Headers**: -- `X-RateLimit-Limit`: 1000 -- `X-RateLimit-Remaining`: 999 -- `X-RateLimit-Reset`: 1634270400 - -**Response 429** (Too Many Requests): -```json -{ - "error": { - "code": "RATE_LIMIT_EXCEEDED", - "message": "API rate limit exceeded", - "retry_after": 3600 - } -} -``` -``` - -## 🔄 **Session Integration** - -### Status Synchronization -Upon completion, update `workflow-session.json`: -```json -{ - "phases": { - "BRAINSTORM": { - "api_designer": { - "status": "completed", - "completed_at": "timestamp", - "output_directory": ".workflow/active/WFS-{topic}/.brainstorming/api-designer/", - "key_insights": ["endpoint_design", "versioning_strategy", "data_contracts"] - } - } - } -} -``` - -### Cross-Role Collaboration -API designer perspective provides: -- **API Contract Specifications** → Frontend Developer -- **Data Schema Requirements** → Data Architect -- **Security Requirements** → Security Expert -- **Integration Endpoints** → System Architect -- **Performance Constraints** → DevOps Engineer - -## ✅ **Quality Assurance** - -### Required Analysis Elements -- [ ] Complete endpoint inventory with HTTP methods and paths -- [ ] Detailed request/response schemas with validation rules -- [ ] Clear versioning strategy and backward compatibility plan -- [ ] Comprehensive error handling and status code usage -- [ ] API documentation strategy (OpenAPI/Swagger) - -### API Design Principles -- [ ] **Consistency**: Uniform naming conventions and patterns across all endpoints -- [ ] **Simplicity**: Intuitive resource modeling and URL structures -- [ ] **Flexibility**: Support for filtering, sorting, pagination, and field selection -- [ ] **Security**: Proper authentication, authorization, and input validation -- [ ] **Performance**: Caching strategies, compression, and efficient data structures - -### Developer Experience Validation -- [ ] API is self-documenting with clear endpoint descriptions -- [ ] Error messages are actionable and helpful for debugging -- [ ] Response formats are consistent and predictable -- [ ] Code examples and integration guides are provided -- [ ] Sandbox environment available for testing - -### Technical Completeness -- [ ] **Resource Modeling**: All domain entities mapped to API resources -- [ ] **CRUD Coverage**: Complete create, read, update, delete operations -- [ ] **Query Capabilities**: Advanced filtering, sorting, and search functionality -- [ ] **Versioning**: Clear version management and migration paths -- [ ] **Monitoring**: API metrics, logging, and tracing strategies defined - -### Integration Readiness -- [ ] **Client Compatibility**: API works with all target client platforms -- [ ] **External Integration**: Third-party API dependencies identified -- [ ] **Backward Compatibility**: Changes don't break existing clients -- [ ] **Migration Path**: Clear upgrade paths for API consumers -- [ ] **SDK Support**: Client libraries and code generation considered diff --git a/.claude/commands/workflow/brainstorm/auto-parallel.md b/.claude/commands/workflow/brainstorm/auto-parallel.md index e84437c4..4f687571 100644 --- a/.claude/commands/workflow/brainstorm/auto-parallel.md +++ b/.claude/commands/workflow/brainstorm/auto-parallel.md @@ -132,55 +132,30 @@ SlashCommand(command="/workflow:brainstorm:artifacts \"{topic}\" --count {N}") ### Phase 2: Parallel Role Analysis Execution -**For Each Selected Role**: +**For Each Selected Role** (unified role-analysis command): ```bash -Task(conceptual-planning-agent): " -[FLOW_CONTROL] - -Execute {role-name} analysis for existing topic framework - -## Context Loading -ASSIGNED_ROLE: {role-name} -OUTPUT_LOCATION: .workflow/active/WFS-{session}/.brainstorming/{role}/ -TOPIC: {user-provided-topic} - -## Flow Control Steps -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 -**Framework Source**: Address all discussion points in guidance-specification.md from {role-name} perspective -**Role Focus**: {role-name} domain expertise aligned with user intent -**Structured Approach**: Create analysis.md addressing framework discussion points -**Template Integration**: Apply role template guidelines within framework structure - -## Expected Deliverables -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 -- Provide actionable recommendations from {role-name} perspective within analysis files -- All output files MUST start with `analysis` prefix (no recommendations.md or other naming) -- Reference framework document using @ notation for integration -- Update workflow-session.json with completion status -" +SlashCommand(command="/workflow:brainstorm:role-analysis {role-name} --session {session-id} --skip-questions") ``` -**Parallel Execute**: -- Launch N agents simultaneously (one message with multiple Task calls) -- Each agent task **attached** to orchestrator's TodoWrite -- All agents execute concurrently, each attaching their own analysis sub-tasks -- Each agent operates independently reading same guidance-specification.md +**What It Does**: +- Unified command execution for each role +- Loads topic framework from guidance-specification.md +- Applies role-specific template and context +- Generates analysis.md addressing framework discussion points +- Supports optional interactive context gathering (via --include-questions flag) + +**Parallel Execution**: +- Launch N SlashCommand calls simultaneously (one message with multiple SlashCommand invokes) +- Each role command **attached** to orchestrator's TodoWrite +- All roles execute concurrently, each reading same guidance-specification.md +- Each role operates independently +- For ui-designer only: append `--style-skill {style_skill_package}` if provided **Input**: - `selected_roles[]` from Phase 1 - `session_id` from Phase 1 -- guidance-specification.md path +- `guidance-specification.md` (framework reference) +- `style_skill_package` (for ui-designer only) **Validation**: - Each role creates `.workflow/active/WFS-{topic}/.brainstorming/{role}/analysis.md` @@ -189,6 +164,7 @@ TOPIC: {user-provided-topic} - **FORBIDDEN**: `recommendations.md` or any non-`analysis` prefixed files - All N role analyses completed + **TodoWrite Update (Phase 2 agents executed - tasks attached in parallel)**: ```json [ diff --git a/.claude/commands/workflow/brainstorm/data-architect.md b/.claude/commands/workflow/brainstorm/data-architect.md deleted file mode 100644 index d6490dec..00000000 --- a/.claude/commands/workflow/brainstorm/data-architect.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -name: data-architect -description: Generate or update data-architect/analysis.md addressing guidance-specification discussion points for data architecture perspective -argument-hint: "optional topic - uses existing framework if available" -allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) ---- - -## 📊 **Data Architect Analysis Generator** - -### Purpose -**Specialized command for generating data-architect/analysis.md** that addresses guidance-specification.md discussion points from data architecture perspective. Creates or updates role-specific analysis with framework references. - -### Core Function -- **Framework-based Analysis**: Address each discussion point in guidance-specification.md -- **Data Architecture Focus**: Data models, pipelines, governance, and analytics perspective -- **Update Mechanism**: Create new or update existing analysis.md -- **Agent Delegation**: Use conceptual-planning-agent for analysis generation - -### Analysis Scope -- **Data Model Design**: Efficient and scalable data models and schemas -- **Data Flow Design**: Data collection, processing, and storage workflows -- **Data Quality Management**: Data accuracy, completeness, and consistency -- **Analytics and Insights**: Data analysis and business intelligence solutions - -### Role Boundaries & Responsibilities - -#### **What This Role OWNS (Canonical Data Model - Source of Truth)** -- **Canonical Data Model**: The authoritative, system-wide data schema representing domain entities and relationships -- **Entity-Relationship Design**: Defining entities, attributes, relationships, and constraints -- **Data Normalization & Optimization**: Ensuring data integrity, reducing redundancy, and optimizing storage -- **Database Schema Design**: Physical database structures, indexes, partitioning strategies -- **Data Pipeline Architecture**: ETL/ELT processes, data warehousing, and analytics pipelines -- **Data Governance**: Data quality standards, retention policies, and compliance requirements - -#### **What This Role DOES NOT Own (Defers to Other Roles)** -- **API Data Contracts**: Public-facing request/response schemas exposed by APIs → Defers to **API Designer** -- **System Integration Patterns**: How services communicate at the macro level → Defers to **System Architect** -- **UI Data Presentation**: How data is displayed to users → Defers to **UI Designer** - -#### **Handoff Points** -- **TO API Designer**: Provides canonical data model that API Designer translates into public API data contracts (as projection/view) -- **TO System Architect**: Provides data flow requirements and storage constraints to inform system design -- **FROM System Architect**: Receives system-level integration requirements and scalability constraints - -## ⚙️ **Execution Protocol** - -### Phase 1: Session & Framework Detection -```bash -# Check active session and framework -CHECK: find .workflow/active/ -name "WFS-*" -type d -IF active_session EXISTS: - session_id = get_active_session() - brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/ - - CHECK: brainstorm_dir/guidance-specification.md - IF EXISTS: - framework_mode = true - load_framework = true - ELSE: - IF topic_provided: - framework_mode = false # Create analysis without framework - ELSE: - ERROR: "No framework found and no topic provided" -``` - -### Phase 2: Analysis Mode Detection -```bash -# Determine execution mode -IF framework_mode == true: - mode = "framework_based_analysis" - topic_ref = load_framework_topic() - discussion_points = extract_framework_points() -ELSE: - mode = "standalone_analysis" - topic_ref = provided_topic - discussion_points = generate_basic_structure() -``` - -### Phase 3: Agent Execution with Flow Control -**Framework-Based Analysis Generation** - -```bash -Task(conceptual-planning-agent): " -[FLOW_CONTROL] - -Execute data-architect analysis for existing topic framework - -## Context Loading -ASSIGNED_ROLE: data-architect -OUTPUT_LOCATION: .workflow/active/WFS-{session}/.brainstorming/data-architect/ -ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} - -## 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 data-architect planning template - - Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/data-architect.md)) - - Output: role_template_guidelines - -3. **load_session_metadata** - - Action: Load session metadata and existing context - - Command: Read(.workflow/active/WFS-{session}/workflow-session.json) - - Output: session_context - -## Analysis Requirements -**Framework Reference**: Address all discussion points in guidance-specification.md from data architecture perspective -**Role Focus**: Data models, pipelines, governance, analytics platforms -**Structured Approach**: Create analysis.md addressing framework discussion points -**Template Integration**: Apply role template guidelines within framework structure - -## Expected Deliverables -1. **analysis.md**: Comprehensive data architecture analysis addressing all framework discussion points -2. **Framework Reference**: Include @../guidance-specification.md reference in analysis - -## Completion Criteria -- Address each discussion point from guidance-specification.md with data architecture expertise -- Provide data model designs, pipeline architectures, and governance strategies -- Include scalability, performance, and quality considerations -- Reference framework document using @ notation for integration -" -``` - -## 📋 **TodoWrite Integration** - -### Workflow Progress Tracking -```javascript -TodoWrite({ - todos: [ - { - content: "Detect active session and locate topic framework", - status: "in_progress", - activeForm: "Detecting session and framework" - }, - { - content: "Load guidance-specification.md and session metadata for context", - status: "pending", - activeForm: "Loading framework and session context" - }, - { - content: "Execute data-architect analysis using conceptual-planning-agent with FLOW_CONTROL", - status: "pending", - activeForm: "Executing data-architect framework analysis" - }, - { - content: "Generate analysis.md addressing all framework discussion points", - status: "pending", - activeForm: "Generating structured data-architect analysis" - }, - { - content: "Update workflow-session.json with data-architect completion status", - status: "pending", - activeForm: "Updating session metadata" - } - ] -}); -``` - -## 📊 **Output Structure** - -### Framework-Based Analysis -``` -.workflow/active/WFS-{session}/.brainstorming/data-architect/ -└── analysis.md # Structured analysis addressing guidance-specification.md discussion points -``` - -### Analysis Document Structure -```markdown -# Data Architect Analysis: [Topic from Framework] - -## Framework Reference -**Topic Framework**: @../guidance-specification.md -**Role Focus**: Data Architecture perspective - -## Discussion Points Analysis -[Address each point from guidance-specification.md with data architecture expertise] - -### Core Requirements (from framework) -[Data architecture perspective on requirements] - -### Technical Considerations (from framework) -[Data model, pipeline, and storage considerations] - -### User Experience Factors (from framework) -[Data access patterns and analytics user experience] - -### Implementation Challenges (from framework) -[Data migration, quality, and governance challenges] - -### Success Metrics (from framework) -[Data quality metrics and analytics success criteria] - -## Data Architecture Specific Recommendations -[Role-specific data architecture recommendations and solutions] - ---- -*Generated by data-architect analysis addressing structured framework* -``` - -## 🔄 **Session Integration** - -### Completion Status Update -```json -{ - "data_architect": { - "status": "completed", - "framework_addressed": true, - "output_location": ".workflow/active/WFS-{session}/.brainstorming/data-architect/analysis.md", - "framework_reference": "@../guidance-specification.md" - } -} -``` - -### Integration Points -- **Framework Reference**: @../guidance-specification.md for structured discussion points -- **Cross-Role Synthesis**: Data architecture insights available for synthesis-report.md integration -- **Agent Autonomy**: Independent execution with framework guidance diff --git a/.claude/commands/workflow/brainstorm/product-manager.md b/.claude/commands/workflow/brainstorm/product-manager.md deleted file mode 100644 index 0c5806cf..00000000 --- a/.claude/commands/workflow/brainstorm/product-manager.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -name: product-manager -description: Generate or update product-manager/analysis.md addressing guidance-specification discussion points for product management perspective -argument-hint: "optional topic - uses existing framework if available" -allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) ---- - -## 🎯 **Product Manager Analysis Generator** - -### Purpose -**Specialized command for generating product-manager/analysis.md** that addresses guidance-specification.md discussion points from product strategy perspective. Creates or updates role-specific analysis with framework references. - -### Core Function -- **Framework-based Analysis**: Address each discussion point in guidance-specification.md -- **Product Strategy Focus**: User needs, business value, and market positioning -- **Update Mechanism**: Create new or update existing analysis.md -- **Agent Delegation**: Use conceptual-planning-agent for analysis generation - -### Analysis Scope -- **User Needs Analysis**: Target users, problems, and value propositions -- **Business Impact Assessment**: ROI, metrics, and commercial outcomes -- **Market Positioning**: Competitive analysis and differentiation -- **Product Strategy**: Roadmaps, priorities, and go-to-market approaches - -## ⚙️ **Execution Protocol** - -### Phase 1: Session & Framework Detection -```bash -# Check active session and framework -CHECK: find .workflow/active/ -name "WFS-*" -type d -IF active_session EXISTS: - session_id = get_active_session() - brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/ - - CHECK: brainstorm_dir/guidance-specification.md - IF EXISTS: - framework_mode = true - load_framework = true - ELSE: - IF topic_provided: - framework_mode = false # Create analysis without framework - ELSE: - ERROR: "No framework found and no topic provided" -``` - -### Phase 2: Analysis Mode Detection -```bash -# Determine execution mode -IF framework_mode == true: - mode = "framework_based_analysis" - topic_ref = load_framework_topic() - discussion_points = extract_framework_points() -ELSE: - mode = "standalone_analysis" - topic_ref = provided_topic - discussion_points = generate_basic_structure() -``` - -### Phase 3: Agent Execution with Flow Control -**Framework-Based Analysis Generation** - -```bash -Task(conceptual-planning-agent): " -[FLOW_CONTROL] - -Execute product-manager analysis for existing topic framework - -## Context Loading -ASSIGNED_ROLE: product-manager -OUTPUT_LOCATION: .workflow/active/WFS-{session}/.brainstorming/product-manager/ -ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} - -## 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 product-manager planning template - - Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/product-manager.md)) - - Output: role_template_guidelines - -3. **load_session_metadata** - - Action: Load session metadata and existing context - - Command: Read(.workflow/active/WFS-{session}/workflow-session.json) - - Output: session_context - -## Analysis Requirements -**Framework Reference**: Address all discussion points in guidance-specification.md from product strategy perspective -**Role Focus**: User value, business impact, market positioning, product strategy -**Structured Approach**: Create analysis.md addressing framework discussion points -**Template Integration**: Apply role template guidelines within framework structure - -## Expected Deliverables -1. **analysis.md**: Comprehensive product strategy analysis addressing all framework discussion points -2. **Framework Reference**: Include @../guidance-specification.md reference in analysis - -## Completion Criteria -- Address each discussion point from guidance-specification.md with product management expertise -- Provide actionable business strategies and user value propositions -- Include market analysis and competitive positioning insights -- Reference framework document using @ notation for integration -" -``` - -## 📋 **TodoWrite Integration** - -### Workflow Progress Tracking -```javascript -TodoWrite({ - todos: [ - { - content: "Detect active session and locate topic framework", - status: "in_progress", - activeForm: "Detecting session and framework" - }, - { - content: "Load guidance-specification.md and session metadata for context", - status: "pending", - activeForm: "Loading framework and session context" - }, - { - content: "Execute product-manager analysis using conceptual-planning-agent with FLOW_CONTROL", - status: "pending", - activeForm: "Executing product-manager framework analysis" - }, - { - content: "Generate analysis.md addressing all framework discussion points", - status: "pending", - activeForm: "Generating structured product-manager analysis" - }, - { - content: "Update workflow-session.json with product-manager completion status", - status: "pending", - activeForm: "Updating session metadata" - } - ] -}); -``` - -## 📊 **Output Structure** - -### Framework-Based Analysis -``` -.workflow/active/WFS-{session}/.brainstorming/product-manager/ -└── analysis.md # Structured analysis addressing guidance-specification.md discussion points -``` - -### Analysis Document Structure -```markdown -# Product Manager Analysis: [Topic from Framework] - -## Framework Reference -**Topic Framework**: @../guidance-specification.md -**Role Focus**: Product Strategy perspective - -## Discussion Points Analysis -[Address each point from guidance-specification.md with product management expertise] - -### Core Requirements (from framework) -[Product strategy perspective on user needs and requirements] - -### Technical Considerations (from framework) -[Business and technical feasibility considerations] - -### User Experience Factors (from framework) -[User value proposition and market positioning analysis] - -### Implementation Challenges (from framework) -[Business execution and go-to-market considerations] - -### Success Metrics (from framework) -[Product success metrics and business KPIs] - -## Product Strategy Specific Recommendations -[Role-specific product management strategies and business solutions] - ---- -*Generated by product-manager analysis addressing structured framework* -``` - -## 🔄 **Session Integration** - -### Completion Status Update -```json -{ - "product_manager": { - "status": "completed", - "framework_addressed": true, - "output_location": ".workflow/active/WFS-{session}/.brainstorming/product-manager/analysis.md", - "framework_reference": "@../guidance-specification.md" - } -} -``` - -### Integration Points -- **Framework Reference**: @../guidance-specification.md for structured discussion points -- **Cross-Role Synthesis**: Product strategy insights available for synthesis-report.md integration -- **Agent Autonomy**: Independent execution with framework guidance diff --git a/.claude/commands/workflow/brainstorm/product-owner.md b/.claude/commands/workflow/brainstorm/product-owner.md deleted file mode 100644 index 639b3c2f..00000000 --- a/.claude/commands/workflow/brainstorm/product-owner.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -name: product-owner -description: Generate or update product-owner/analysis.md addressing guidance-specification discussion points for product ownership perspective -argument-hint: "optional topic - uses existing framework if available" -allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) ---- - -## 🎯 **Product Owner Analysis Generator** - -### Purpose -**Specialized command for generating product-owner/analysis.md** that addresses guidance-specification.md discussion points from product backlog and feature prioritization perspective. Creates or updates role-specific analysis with framework references. - -### Core Function -- **Framework-based Analysis**: Address each discussion point in guidance-specification.md -- **Product Backlog Focus**: Feature prioritization, user stories, and acceptance criteria -- **Update Mechanism**: Create new or update existing analysis.md -- **Agent Delegation**: Use conceptual-planning-agent for analysis generation - -### Analysis Scope -- **Backlog Management**: User story creation, refinement, and prioritization -- **Stakeholder Alignment**: Requirements gathering, value definition, and expectation management -- **Feature Prioritization**: ROI analysis, MoSCoW method, and value-driven delivery -- **Acceptance Criteria**: Definition of Done, acceptance testing, and quality standards - -## ⚙️ **Execution Protocol** - -### Phase 1: Session & Framework Detection -```bash -# Check active session and framework -CHECK: find .workflow/active/ -name "WFS-*" -type d -IF active_session EXISTS: - session_id = get_active_session() - brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/ - - CHECK: brainstorm_dir/guidance-specification.md - IF EXISTS: - framework_mode = true - load_framework = true - ELSE: - IF topic_provided: - framework_mode = false # Create analysis without framework - ELSE: - ERROR: "No framework found and no topic provided" -``` - -### Phase 2: Analysis Mode Detection -```bash -# Determine execution mode -IF framework_mode == true: - mode = "framework_based_analysis" - topic_ref = load_framework_topic() - discussion_points = extract_framework_points() -ELSE: - mode = "standalone_analysis" - topic_ref = provided_topic - discussion_points = generate_basic_structure() -``` - -### Phase 3: Agent Execution with Flow Control -**Framework-Based Analysis Generation** - -```bash -Task(conceptual-planning-agent): " -[FLOW_CONTROL] - -Execute product-owner analysis for existing topic framework - -## Context Loading -ASSIGNED_ROLE: product-owner -OUTPUT_LOCATION: .workflow/active/WFS-{session}/.brainstorming/product-owner/ -ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} - -## 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 product-owner planning template - - Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/product-owner.md)) - - Output: role_template_guidelines - -3. **load_session_metadata** - - Action: Load session metadata and existing context - - Command: Read(.workflow/active/WFS-{session}/workflow-session.json) - - Output: session_context - -## Analysis Requirements -**Framework Reference**: Address all discussion points in guidance-specification.md from product backlog and feature prioritization perspective -**Role Focus**: Backlog management, stakeholder alignment, feature prioritization, acceptance criteria -**Structured Approach**: Create analysis.md addressing framework discussion points -**Template Integration**: Apply role template guidelines within framework structure - -## Expected Deliverables -1. **analysis.md**: Comprehensive product ownership analysis addressing all framework discussion points -2. **Framework Reference**: Include @../guidance-specification.md reference in analysis - -## Completion Criteria -- Address each discussion point from guidance-specification.md with product ownership expertise -- Provide actionable user stories and acceptance criteria definitions -- Include feature prioritization and stakeholder alignment strategies -- Reference framework document using @ notation for integration -" -``` - -## 📋 **TodoWrite Integration** - -### Workflow Progress Tracking -```javascript -TodoWrite({ - todos: [ - { - content: "Detect active session and locate topic framework", - status: "in_progress", - activeForm: "Detecting session and framework" - }, - { - content: "Load guidance-specification.md and session metadata for context", - status: "pending", - activeForm: "Loading framework and session context" - }, - { - content: "Execute product-owner analysis using conceptual-planning-agent with FLOW_CONTROL", - status: "pending", - activeForm: "Executing product-owner framework analysis" - }, - { - content: "Generate analysis.md addressing all framework discussion points", - status: "pending", - activeForm: "Generating structured product-owner analysis" - }, - { - content: "Update workflow-session.json with product-owner completion status", - status: "pending", - activeForm: "Updating session metadata" - } - ] -}); -``` - -## 📊 **Output Structure** - -### Framework-Based Analysis -``` -.workflow/active/WFS-{session}/.brainstorming/product-owner/ -└── analysis.md # Structured analysis addressing guidance-specification.md discussion points -``` - -### Analysis Document Structure -```markdown -# Product Owner Analysis: [Topic from Framework] - -## Framework Reference -**Topic Framework**: @../guidance-specification.md -**Role Focus**: Product Backlog & Feature Prioritization perspective - -## Discussion Points Analysis -[Address each point from guidance-specification.md with product ownership expertise] - -### Core Requirements (from framework) -[User story formulation and backlog refinement perspective] - -### Technical Considerations (from framework) -[Technical feasibility and implementation sequencing considerations] - -### User Experience Factors (from framework) -[User value definition and acceptance criteria analysis] - -### Implementation Challenges (from framework) -[Sprint planning, dependency management, and delivery strategies] - -### Success Metrics (from framework) -[Feature adoption, value delivery metrics, and stakeholder satisfaction indicators] - -## Product Owner Specific Recommendations -[Role-specific backlog management and feature prioritization strategies] - ---- -*Generated by product-owner analysis addressing structured framework* -``` - -## 🔄 **Session Integration** - -### Completion Status Update -```json -{ - "product_owner": { - "status": "completed", - "framework_addressed": true, - "output_location": ".workflow/active/WFS-{session}/.brainstorming/product-owner/analysis.md", - "framework_reference": "@../guidance-specification.md" - } -} -``` - -### Integration Points -- **Framework Reference**: @../guidance-specification.md for structured discussion points -- **Cross-Role Synthesis**: Product ownership insights available for synthesis-report.md integration -- **Agent Autonomy**: Independent execution with framework guidance diff --git a/.claude/commands/workflow/brainstorm/role-analysis.md b/.claude/commands/workflow/brainstorm/role-analysis.md new file mode 100644 index 00000000..debda864 --- /dev/null +++ b/.claude/commands/workflow/brainstorm/role-analysis.md @@ -0,0 +1,705 @@ +--- +name: role-analysis +description: Unified role-specific analysis generation with interactive context gathering and incremental updates +argument-hint: "[role-name] [--session session-id] [--update] [--include-questions] [--skip-questions]" +allowed-tools: Task(conceptual-planning-agent), AskUserQuestion(*), TodoWrite(*), Read(*), Write(*), Edit(*), Glob(*) +--- + +## 🎯 **Unified Role Analysis Generator** + +### Purpose +**Unified command for generating and updating role-specific analysis** with interactive context gathering, framework alignment, and incremental update support. Replaces 9 individual role commands with single parameterized workflow. + +### Core Function +- **Multi-Role Support**: Single command supports all 9 brainstorming roles +- **Interactive Context**: Dynamic question generation based on role and framework +- **Incremental Updates**: Merge new insights into existing analyses +- **Framework Alignment**: Address guidance-specification.md discussion points +- **Agent Delegation**: Use conceptual-planning-agent with role-specific templates + +### Supported Roles + +| Role ID | Title | Focus Area | Context Questions | +|---------|-------|------------|-------------------| +| `ux-expert` | UX专家 | User research, information architecture, user journey | 4 | +| `ui-designer` | UI设计师 | Visual design, high-fidelity mockups, design systems | 4 | +| `system-architect` | 系统架构师 | Technical architecture, scalability, integration patterns | 5 | +| `product-manager` | 产品经理 | Product strategy, roadmap, prioritization | 4 | +| `product-owner` | 产品负责人 | Backlog management, user stories, acceptance criteria | 4 | +| `scrum-master` | 敏捷教练 | Process facilitation, impediment removal, team dynamics | 3 | +| `subject-matter-expert` | 领域专家 | Domain knowledge, business rules, compliance | 4 | +| `data-architect` | 数据架构师 | Data models, storage strategies, data flow | 5 | +| `api-designer` | API设计师 | API contracts, versioning, integration patterns | 4 | + +--- + +## 📋 **Usage** + +```bash +# Generate new analysis with interactive context +/workflow:brainstorm:role-analysis ux-expert + +# Generate with existing framework + context questions +/workflow:brainstorm:role-analysis system-architect --session WFS-xxx --include-questions + +# Update existing analysis (incremental merge) +/workflow:brainstorm:role-analysis ui-designer --session WFS-xxx --update + +# Quick generation (skip interactive context) +/workflow:brainstorm:role-analysis product-manager --session WFS-xxx --skip-questions +``` + +--- + +## ⚙️ **Execution Protocol** + +### Phase 1: Detection & Validation + +**Step 1.1: Role Validation** +```bash +VALIDATE role_name IN [ + ux-expert, ui-designer, system-architect, product-manager, + product-owner, scrum-master, subject-matter-expert, + data-architect, api-designer +] +IF invalid: + ERROR: "Unknown role: {role_name}. Use one of: ux-expert, ui-designer, ..." + EXIT +``` + +**Step 1.2: Session Detection** +```bash +IF --session PROVIDED: + session_id = --session + brainstorm_dir = .workflow/active/{session_id}/.brainstorming/ +ELSE: + FIND .workflow/active/WFS-*/ + IF multiple: + PROMPT user to select + ELSE IF single: + USE existing + ELSE: + ERROR: "No active session. Run /workflow:brainstorm:artifacts first" + EXIT + +VALIDATE brainstorm_dir EXISTS +``` + +**Step 1.3: Framework Detection** +```bash +framework_file = {brainstorm_dir}/guidance-specification.md +IF framework_file EXISTS: + framework_mode = true + LOAD framework_content +ELSE: + WARN: "No framework found - will create standalone analysis" + framework_mode = false +``` + +**Step 1.4: Update Mode Detection** +```bash +existing_analysis = {brainstorm_dir}/{role_name}/analysis*.md +IF --update FLAG OR existing_analysis EXISTS: + update_mode = true + IF --update NOT PROVIDED: + ASK: "Analysis exists. Update or regenerate?" + OPTIONS: ["Incremental update", "Full regenerate", "Cancel"] +ELSE: + update_mode = false +``` + +### Phase 2: Interactive Context Gathering + +**Trigger Conditions**: +- Default: Always ask unless `--skip-questions` provided +- `--include-questions`: Force context gathering even if analysis exists +- `--skip-questions`: Skip all interactive questions + +**Step 2.1: Load Role Configuration** +```javascript +const roleConfig = { + 'ux-expert': { + title: 'UX专家', + focus_area: 'User research, information architecture, user journey', + question_categories: ['User Intent', 'Requirements', 'UX'], + question_count: 4, + template: '~/.claude/workflows/cli-templates/planning-roles/ux-expert.md' + }, + 'ui-designer': { + title: 'UI设计师', + focus_area: 'Visual design, high-fidelity mockups, design systems', + question_categories: ['Requirements', 'UX', 'Feasibility'], + question_count: 4, + template: '~/.claude/workflows/cli-templates/planning-roles/ui-designer.md' + }, + 'system-architect': { + title: '系统架构师', + focus_area: 'Technical architecture, scalability, integration patterns', + question_categories: ['Scale & Performance', 'Technical Constraints', 'Architecture Complexity', 'Non-Functional Requirements'], + question_count: 5, + template: '~/.claude/workflows/cli-templates/planning-roles/system-architect.md' + }, + 'product-manager': { + title: '产品经理', + focus_area: 'Product strategy, roadmap, prioritization', + question_categories: ['User Intent', 'Requirements', 'Process'], + question_count: 4, + template: '~/.claude/workflows/cli-templates/planning-roles/product-manager.md' + }, + 'product-owner': { + title: '产品负责人', + focus_area: 'Backlog management, user stories, acceptance criteria', + question_categories: ['Requirements', 'Decisions', 'Process'], + question_count: 4, + template: '~/.claude/workflows/cli-templates/planning-roles/product-owner.md' + }, + 'scrum-master': { + title: '敏捷教练', + focus_area: 'Process facilitation, impediment removal, team dynamics', + question_categories: ['Process', 'Risk', 'Decisions'], + question_count: 3, + template: '~/.claude/workflows/cli-templates/planning-roles/scrum-master.md' + }, + 'subject-matter-expert': { + title: '领域专家', + focus_area: 'Domain knowledge, business rules, compliance', + question_categories: ['Requirements', 'Feasibility', 'Terminology'], + question_count: 4, + template: '~/.claude/workflows/cli-templates/planning-roles/subject-matter-expert.md' + }, + 'data-architect': { + title: '数据架构师', + focus_area: 'Data models, storage strategies, data flow', + question_categories: ['Architecture', 'Scale & Performance', 'Technical Constraints', 'Feasibility'], + question_count: 5, + template: '~/.claude/workflows/cli-templates/planning-roles/data-architect.md' + }, + 'api-designer': { + title: 'API设计师', + focus_area: 'API contracts, versioning, integration patterns', + question_categories: ['Architecture', 'Requirements', 'Feasibility', 'Decisions'], + question_count: 4, + template: '~/.claude/workflows/cli-templates/planning-roles/api-designer.md' + } +}; + +config = roleConfig[role_name]; +``` + +**Step 2.2: Generate Role-Specific Questions** + +**9-Category Taxonomy** (from synthesis.md): + +| Category | Focus | Example Question Pattern | +|----------|-------|--------------------------| +| User Intent | 用户目标 | "该分析的核心目标是什么？" | +| Requirements | 需求细化 | "需求的优先级如何排序？" | +| Architecture | 架构决策 | "技术栈的选择考量？" | +| UX | 用户体验 | "交互复杂度的取舍？" | +| Feasibility | 可行性 | "资源约束下的实现范围？" | +| Risk | 风险管理 | "风险容忍度是多少？" | +| Process | 流程规范 | "开发迭代的节奏？" | +| Decisions | 决策确认 | "冲突的解决方案？" | +| Terminology | 术语统一 | "统一使用哪个术语？" | +| Scale & Performance | 性能扩展 | "预期的负载和性能要求？" | +| Technical Constraints | 技术约束 | "现有技术栈的限制？" | +| Architecture Complexity | 架构复杂度 | "架构的复杂度权衡？" | +| Non-Functional Requirements | 非功能需求 | "可用性和可维护性要求？" | + +**Question Generation Algorithm**: +```javascript +async function generateQuestions(role_name, framework_content) { + const config = roleConfig[role_name]; + const questions = []; + + // Parse framework for keywords + const keywords = extractKeywords(framework_content); + + // Generate category-specific questions + for (const category of config.question_categories) { + const question = generateCategoryQuestion(category, keywords, role_name); + questions.push(question); + } + + return questions.slice(0, config.question_count); +} +``` + +**Step 2.3: Multi-Round Question Execution** + +```javascript +const BATCH_SIZE = 4; +const user_context = {}; + +for (let i = 0; i < questions.length; i += BATCH_SIZE) { + const batch = questions.slice(i, i + BATCH_SIZE); + const currentRound = Math.floor(i / BATCH_SIZE) + 1; + const totalRounds = Math.ceil(questions.length / BATCH_SIZE); + + console.log(`\n[Round ${currentRound}/${totalRounds}] ${config.title} 上下文询问\n`); + + 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 + })) + })) + }); + + // Store responses before next round + for (const answer of responses) { + user_context[answer.question] = { + answer: answer.selected, + category: answer.category, + timestamp: new Date().toISOString() + }; + } +} + +// Save context to file +Write( + `${brainstorm_dir}/${role_name}/${role_name}-context.md`, + formatUserContext(user_context) +); +``` + +**Question Quality Rules** (from artifacts.md): + +**MUST Include**: +- ✅ All questions in Chinese (用中文提问) +- ✅ 业务场景作为问题前提 +- ✅ 技术选项的业务影响说明 +- ✅ 量化指标和约束条件 + +**MUST Avoid**: +- ❌ 纯技术选型无业务上下文 +- ❌ 过度抽象的通用问题 +- ❌ 脱离框架的重复询问 + +### Phase 3: Agent Execution + +**Step 3.1: Load Session Metadata** +```bash +session_metadata = Read(.workflow/active/{session_id}/workflow-session.json) +original_topic = session_metadata.topic +selected_roles = session_metadata.selected_roles +``` + +**Step 3.2: Prepare Agent Context** +```javascript +const agentContext = { + role_name: role_name, + role_config: roleConfig[role_name], + output_location: `${brainstorm_dir}/${role_name}/`, + framework_mode: framework_mode, + framework_path: framework_mode ? `${brainstorm_dir}/guidance-specification.md` : null, + update_mode: update_mode, + user_context: user_context, + original_topic: original_topic, + session_id: session_id +}; +``` + +**Step 3.3: Execute Conceptual Planning Agent** + +**Framework-Based Analysis** (when guidance-specification.md exists): +```javascript +Task( + subagent_type="conceptual-planning-agent", + run_in_background=false, + description=`Generate ${role_name} analysis`, + prompt=` +[FLOW_CONTROL] + +Execute ${role_name} analysis for existing topic framework + +## Context Loading +ASSIGNED_ROLE: ${role_name} +OUTPUT_LOCATION: ${agentContext.output_location} +ANALYSIS_MODE: ${framework_mode ? "framework_based" : "standalone"} +UPDATE_MODE: ${update_mode} + +## Flow Control Steps +1. **load_topic_framework** + - Action: Load structured topic discussion framework + - Command: Read(${agentContext.framework_path}) + - Output: topic_framework_content + +2. **load_role_template** + - Action: Load ${role_name} planning template + - Command: Read(${roleConfig[role_name].template}) + - Output: role_template_guidelines + +3. **load_session_metadata** + - Action: Load session metadata and user intent + - Command: Read(.workflow/active/${session_id}/workflow-session.json) + - Output: session_context + +4. **load_user_context** (if exists) + - Action: Load interactive context responses + - Command: Read(${brainstorm_dir}/${role_name}/${role_name}-context.md) + - Output: user_context_answers + +5. **${update_mode ? 'load_existing_analysis' : 'skip'}** + ${update_mode ? ` + - Action: Load existing analysis for incremental update + - Command: Read(${brainstorm_dir}/${role_name}/analysis.md) + - Output: existing_analysis_content + ` : ''} + +## Analysis Requirements +**Primary Reference**: Original user prompt from workflow-session.json is authoritative +**Framework Source**: Address all discussion points in guidance-specification.md from ${role_name} perspective +**User Context Integration**: Incorporate interactive Q&A responses into analysis +**Role Focus**: ${roleConfig[role_name].focus_area} +**Template Integration**: Apply role template guidelines within framework structure + +## Expected Deliverables +1. **analysis.md** (main document, optionally with analysis-{slug}.md sub-documents) +2. **Framework Reference**: @../guidance-specification.md (if framework_mode) +3. **User Context Reference**: @./${role_name}-context.md (if user context exists) +4. **User Intent Alignment**: Validate against session_context + +## Update Requirements (if UPDATE_MODE) +- **Preserve Structure**: Maintain existing analysis structure +- **Add "Clarifications" Section**: Document new user context with timestamp +- **Merge Insights**: Integrate new perspectives without removing existing content +- **Resolve Conflicts**: If new context contradicts existing analysis, document both and recommend resolution + +## Completion Criteria +- Address each discussion point from guidance-specification.md with ${role_name} expertise +- Provide actionable recommendations from ${role_name} perspective within analysis files +- All output files MUST start with "analysis" prefix (no recommendations.md or other naming) +- Reference framework document using @ notation for integration +- Update workflow-session.json with completion status +` +); +``` + +### Phase 4: Validation & Finalization + +**Step 4.1: Validate Output** +```bash +VERIFY EXISTS: ${brainstorm_dir}/${role_name}/analysis.md +VERIFY CONTAINS: "@../guidance-specification.md" (if framework_mode) +IF user_context EXISTS: + VERIFY CONTAINS: "@./${role_name}-context.md" OR "## Clarifications" section +``` + +**Step 4.2: Update Session Metadata** +```json +{ + "phases": { + "BRAINSTORM": { + "${role_name}": { + "status": "${update_mode ? 'updated' : 'completed'}", + "completed_at": "timestamp", + "framework_addressed": true, + "context_gathered": user_context ? true : false, + "output_location": "${brainstorm_dir}/${role_name}/analysis.md", + "update_history": [ + { + "timestamp": "ISO8601", + "mode": "${update_mode ? 'incremental' : 'initial'}", + "context_questions": question_count + } + ] + } + } + } +} +``` + +**Step 4.3: Completion Report** +```markdown +✅ ${roleConfig[role_name].title} Analysis Complete + +**Output**: ${brainstorm_dir}/${role_name}/analysis.md +**Mode**: ${update_mode ? 'Incremental Update' : 'New Generation'} +**Framework**: ${framework_mode ? '✓ Aligned' : '✗ Standalone'} +**Context Questions**: ${question_count} answered + +${update_mode ? ' +**Changes**: +- Added "Clarifications" section with new user context +- Merged new insights into existing sections +- Resolved conflicts with framework alignment +' : ''} + +**Next Steps**: +${selected_roles.length > 1 ? ` + - Continue with other roles: ${selected_roles.filter(r => r !== role_name).join(', ')} + - Run synthesis: /workflow:brainstorm:synthesis --session ${session_id} +` : ` + - Clarify insights: /workflow:brainstorm:synthesis --session ${session_id} + - Generate plan: /workflow:plan --session ${session_id} +`} +``` + +--- + +## 📋 **TodoWrite Integration** + +### Workflow Progress Tracking + +```javascript +TodoWrite({ + todos: [ + { + content: "Phase 1: Detect session and validate role configuration", + status: "in_progress", + activeForm: "Detecting session and role" + }, + { + content: "Phase 2: Interactive context gathering with AskUserQuestion", + status: "pending", + activeForm: "Gathering user context" + }, + { + content: "Phase 3: Execute conceptual-planning-agent for role analysis", + status: "pending", + activeForm: "Executing agent analysis" + }, + { + content: "Phase 4: Validate output and update session metadata", + status: "pending", + activeForm: "Finalizing and validating" + } + ] +}); +``` + +--- + +## 📊 **Output Structure** + +### Directory Layout + +``` +.workflow/active/WFS-{session}/.brainstorming/ +├── guidance-specification.md # Framework (if exists) +└── {role-name}/ + ├── {role-name}-context.md # Interactive Q&A responses + ├── analysis.md # Main analysis (REQUIRED) + └── analysis-{slug}.md # Section documents (optional, max 5) +``` + +### Analysis Document Structure (New Generation) + +```markdown +# ${roleConfig[role_name].title} Analysis: [Topic from Framework] + +## Framework Reference +**Topic Framework**: @../guidance-specification.md +**Role Focus**: ${roleConfig[role_name].focus_area} +**User Context**: @./${role_name}-context.md + +## User Context Summary +**Context Gathered**: ${question_count} questions answered +**Categories**: ${question_categories.join(', ')} + +${user_context ? formatContextSummary(user_context) : ''} + +## Discussion Points Analysis +[Address each point from guidance-specification.md with ${role_name} expertise] + +### Core Requirements (from framework) +[Role-specific perspective on requirements] + +### Technical Considerations (from framework) +[Role-specific technical analysis] + +### User Experience Factors (from framework) +[Role-specific UX considerations] + +### Implementation Challenges (from framework) +[Role-specific challenges and solutions] + +### Success Metrics (from framework) +[Role-specific metrics and KPIs] + +## ${roleConfig[role_name].title} Specific Recommendations +[Role-specific actionable strategies] + +--- +*Generated by ${role_name} analysis addressing structured framework* +*Context gathered: ${new Date().toISOString()}* +``` + +### Analysis Document Structure (Incremental Update) + +```markdown +# ${roleConfig[role_name].title} Analysis: [Topic] + +## Framework Reference +[Existing content preserved] + +## Clarifications +### Session ${new Date().toISOString().split('T')[0]} +${Object.entries(user_context).map(([q, a]) => ` +- **Q**: ${q} (Category: ${a.category}) + **A**: ${a.answer} +`).join('\n')} + +## User Context Summary +[Updated with new context] + +## Discussion Points Analysis +[Existing content enhanced with new insights] + +[Rest of sections updated based on clarifications] +``` + +--- + +## 🔄 **Integration with Other Commands** + +### Called By +- `/workflow:brainstorm:auto-parallel` (Phase 2 - parallel role execution) +- Manual invocation for single-role analysis + +### Calls To +- `conceptual-planning-agent` (agent execution) +- `AskUserQuestion` (interactive context gathering) + +### Coordinates With +- `/workflow:brainstorm:artifacts` (creates framework for role analysis) +- `/workflow:brainstorm:synthesis` (reads role analyses for integration) + +--- + +## ✅ **Quality Assurance** + +### Required Analysis Elements +- [ ] Framework discussion points addressed (if framework_mode) +- [ ] User context integrated (if context gathered) +- [ ] Role template guidelines applied +- [ ] Output files follow naming convention (analysis*.md only) +- [ ] Framework reference using @ notation +- [ ] Session metadata updated + +### Context Quality +- [ ] Questions in Chinese with business context +- [ ] Options include technical trade-offs +- [ ] Categories aligned with role focus +- [ ] No generic questions unrelated to framework + +### Update Quality (if update_mode) +- [ ] "Clarifications" section added with timestamp +- [ ] New insights merged without content loss +- [ ] Conflicts documented and resolved +- [ ] Framework alignment maintained + +--- + +## 🎛️ **Command Parameters** + +### Required Parameters +- `[role-name]`: Role identifier (ux-expert, ui-designer, system-architect, etc.) + +### Optional Parameters +- `--session [session-id]`: Specify brainstorming session (auto-detect if omitted) +- `--update`: Force incremental update mode (auto-detect if analysis exists) +- `--include-questions`: Force context gathering even if analysis exists +- `--skip-questions`: Skip all interactive context gathering +- `--style-skill [package]`: For ui-designer only, load style SKILL package + +### Parameter Combinations + +| Scenario | Command | Behavior | +|----------|---------|----------| +| New analysis | `role-analysis ux-expert` | Generate + ask context questions | +| Quick generation | `role-analysis ux-expert --skip-questions` | Generate without context | +| Update existing | `role-analysis ux-expert --update` | Ask clarifications + merge | +| Force questions | `role-analysis ux-expert --include-questions` | Ask even if exists | +| Specific session | `role-analysis ux-expert --session WFS-xxx` | Target specific session | + +--- + +## 🚫 **Error Handling** + +### Invalid Role Name +``` +ERROR: Unknown role: "ui-expert" +Valid roles: ux-expert, ui-designer, system-architect, product-manager, + product-owner, scrum-master, subject-matter-expert, + data-architect, api-designer +``` + +### No Active Session +``` +ERROR: No active brainstorming session found +Run: /workflow:brainstorm:artifacts "[topic]" to create session +``` + +### Missing Framework (with warning) +``` +WARN: No guidance-specification.md found +Generating standalone analysis without framework alignment +Recommend: Run /workflow:brainstorm:artifacts first for better results +``` + +### Agent Execution Failure +``` +ERROR: Conceptual planning agent failed +Check: ${brainstorm_dir}/${role_name}/error.log +Action: Retry with --skip-questions or check framework validity +``` + +--- + +## 🔧 **Advanced Usage** + +### Batch Role Generation (via auto-parallel) +```bash +# This command handles multiple roles in parallel +/workflow:brainstorm:auto-parallel "topic" --count 3 +# → Internally calls role-analysis for each selected role +``` + +### Manual Multi-Role Workflow +```bash +# 1. Create framework +/workflow:brainstorm:artifacts "Build real-time collaboration platform" --count 3 + +# 2. Generate each role with context +/workflow:brainstorm:role-analysis system-architect --include-questions +/workflow:brainstorm:role-analysis ui-designer --include-questions +/workflow:brainstorm:role-analysis product-manager --include-questions + +# 3. Synthesize insights +/workflow:brainstorm:synthesis --session WFS-xxx +``` + +### Iterative Refinement +```bash +# Initial generation +/workflow:brainstorm:role-analysis ux-expert + +# User reviews and wants more depth +/workflow:brainstorm:role-analysis ux-expert --update --include-questions +# → Asks clarification questions, merges new insights +``` + +--- + +## 📚 **Reference Information** + +### Role Template Locations +- Templates: `~/.claude/workflows/cli-templates/planning-roles/` +- Format: `{role-name}.md` (e.g., `ux-expert.md`, `system-architect.md`) + +### Related Commands +- `/workflow:brainstorm:artifacts` - Create framework and select roles +- `/workflow:brainstorm:auto-parallel` - Parallel multi-role execution +- `/workflow:brainstorm:synthesis` - Integrate role analyses +- `/workflow:plan` - Generate implementation plan from synthesis + +### Context Package +- Location: `.workflow/active/WFS-{session}/.process/context-package.json` +- Used by: `context-search-agent` (Phase 0 of artifacts) +- Contains: Project context, tech stack, conflict risks diff --git a/.claude/commands/workflow/brainstorm/scrum-master.md b/.claude/commands/workflow/brainstorm/scrum-master.md deleted file mode 100644 index 1e5f0f44..00000000 --- a/.claude/commands/workflow/brainstorm/scrum-master.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -name: scrum-master -description: Generate or update scrum-master/analysis.md addressing guidance-specification discussion points for Agile process perspective -argument-hint: "optional topic - uses existing framework if available" -allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) ---- - -## 🎯 **Scrum Master Analysis Generator** - -### Purpose -**Specialized command for generating scrum-master/analysis.md** that addresses guidance-specification.md discussion points from agile process and team collaboration perspective. Creates or updates role-specific analysis with framework references. - -### Core Function -- **Framework-based Analysis**: Address each discussion point in guidance-specification.md -- **Agile Process Focus**: Sprint planning, team dynamics, and delivery optimization -- **Update Mechanism**: Create new or update existing analysis.md -- **Agent Delegation**: Use conceptual-planning-agent for analysis generation - -### Analysis Scope -- **Sprint Planning**: Task breakdown, estimation, and iteration planning -- **Team Collaboration**: Communication patterns, impediment removal, and facilitation -- **Process Optimization**: Agile ceremonies, retrospectives, and continuous improvement -- **Delivery Management**: Velocity tracking, burndown analysis, and release planning - -## ⚙️ **Execution Protocol** - -### Phase 1: Session & Framework Detection -```bash -# Check active session and framework -CHECK: find .workflow/active/ -name "WFS-*" -type d -IF active_session EXISTS: - session_id = get_active_session() - brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/ - - CHECK: brainstorm_dir/guidance-specification.md - IF EXISTS: - framework_mode = true - load_framework = true - ELSE: - IF topic_provided: - framework_mode = false # Create analysis without framework - ELSE: - ERROR: "No framework found and no topic provided" -``` - -### Phase 2: Analysis Mode Detection -```bash -# Determine execution mode -IF framework_mode == true: - mode = "framework_based_analysis" - topic_ref = load_framework_topic() - discussion_points = extract_framework_points() -ELSE: - mode = "standalone_analysis" - topic_ref = provided_topic - discussion_points = generate_basic_structure() -``` - -### Phase 3: Agent Execution with Flow Control -**Framework-Based Analysis Generation** - -```bash -Task(conceptual-planning-agent): " -[FLOW_CONTROL] - -Execute scrum-master analysis for existing topic framework - -## Context Loading -ASSIGNED_ROLE: scrum-master -OUTPUT_LOCATION: .workflow/active/WFS-{session}/.brainstorming/scrum-master/ -ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} - -## 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 scrum-master planning template - - Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/scrum-master.md)) - - Output: role_template_guidelines - -3. **load_session_metadata** - - Action: Load session metadata and existing context - - Command: Read(.workflow/active/WFS-{session}/workflow-session.json) - - Output: session_context - -## Analysis Requirements -**Framework Reference**: Address all discussion points in guidance-specification.md from agile process and team collaboration perspective -**Role Focus**: Sprint planning, team dynamics, process optimization, delivery management -**Structured Approach**: Create analysis.md addressing framework discussion points -**Template Integration**: Apply role template guidelines within framework structure - -## Expected Deliverables -1. **analysis.md**: Comprehensive agile process analysis addressing all framework discussion points -2. **Framework Reference**: Include @../guidance-specification.md reference in analysis - -## Completion Criteria -- Address each discussion point from guidance-specification.md with scrum mastery expertise -- Provide actionable sprint planning and team facilitation strategies -- Include process optimization and impediment removal insights -- Reference framework document using @ notation for integration -" -``` - -## 📋 **TodoWrite Integration** - -### Workflow Progress Tracking -```javascript -TodoWrite({ - todos: [ - { - content: "Detect active session and locate topic framework", - status: "in_progress", - activeForm: "Detecting session and framework" - }, - { - content: "Load guidance-specification.md and session metadata for context", - status: "pending", - activeForm: "Loading framework and session context" - }, - { - content: "Execute scrum-master analysis using conceptual-planning-agent with FLOW_CONTROL", - status: "pending", - activeForm: "Executing scrum-master framework analysis" - }, - { - content: "Generate analysis.md addressing all framework discussion points", - status: "pending", - activeForm: "Generating structured scrum-master analysis" - }, - { - content: "Update workflow-session.json with scrum-master completion status", - status: "pending", - activeForm: "Updating session metadata" - } - ] -}); -``` - -## 📊 **Output Structure** - -### Framework-Based Analysis -``` -.workflow/active/WFS-{session}/.brainstorming/scrum-master/ -└── analysis.md # Structured analysis addressing guidance-specification.md discussion points -``` - -### Analysis Document Structure -```markdown -# Scrum Master Analysis: [Topic from Framework] - -## Framework Reference -**Topic Framework**: @../guidance-specification.md -**Role Focus**: Agile Process & Team Collaboration perspective - -## Discussion Points Analysis -[Address each point from guidance-specification.md with scrum mastery expertise] - -### Core Requirements (from framework) -[Sprint planning and iteration breakdown perspective] - -### Technical Considerations (from framework) -[Technical debt management and process considerations] - -### User Experience Factors (from framework) -[User story refinement and acceptance criteria analysis] - -### Implementation Challenges (from framework) -[Impediment identification and removal strategies] - -### Success Metrics (from framework) -[Velocity tracking, burndown metrics, and team performance indicators] - -## Scrum Master Specific Recommendations -[Role-specific agile process optimization and team facilitation strategies] - ---- -*Generated by scrum-master analysis addressing structured framework* -``` - -## 🔄 **Session Integration** - -### Completion Status Update -```json -{ - "scrum_master": { - "status": "completed", - "framework_addressed": true, - "output_location": ".workflow/active/WFS-{session}/.brainstorming/scrum-master/analysis.md", - "framework_reference": "@../guidance-specification.md" - } -} -``` - -### Integration Points -- **Framework Reference**: @../guidance-specification.md for structured discussion points -- **Cross-Role Synthesis**: Agile process insights available for synthesis-report.md integration -- **Agent Autonomy**: Independent execution with framework guidance diff --git a/.claude/commands/workflow/brainstorm/subject-matter-expert.md b/.claude/commands/workflow/brainstorm/subject-matter-expert.md deleted file mode 100644 index 1ac0bac9..00000000 --- a/.claude/commands/workflow/brainstorm/subject-matter-expert.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -name: subject-matter-expert -description: Generate or update subject-matter-expert/analysis.md addressing guidance-specification discussion points for domain expertise perspective -argument-hint: "optional topic - uses existing framework if available" -allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) ---- - -## 🎯 **Subject Matter Expert Analysis Generator** - -### Purpose -**Specialized command for generating subject-matter-expert/analysis.md** that addresses guidance-specification.md discussion points from domain knowledge and technical expertise perspective. Creates or updates role-specific analysis with framework references. - -### Core Function -- **Framework-based Analysis**: Address each discussion point in guidance-specification.md -- **Domain Expertise Focus**: Deep technical knowledge, industry standards, and best practices -- **Update Mechanism**: Create new or update existing analysis.md -- **Agent Delegation**: Use conceptual-planning-agent for analysis generation - -### Analysis Scope -- **Domain Knowledge**: Industry-specific expertise, regulatory requirements, and compliance -- **Technical Standards**: Best practices, design patterns, and architectural guidelines -- **Risk Assessment**: Technical debt, scalability concerns, and maintenance implications -- **Knowledge Transfer**: Documentation strategies, training requirements, and expertise sharing - -## ⚙️ **Execution Protocol** - -### Phase 1: Session & Framework Detection -```bash -# Check active session and framework -CHECK: find .workflow/active/ -name "WFS-*" -type d -IF active_session EXISTS: - session_id = get_active_session() - brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/ - - CHECK: brainstorm_dir/guidance-specification.md - IF EXISTS: - framework_mode = true - load_framework = true - ELSE: - IF topic_provided: - framework_mode = false # Create analysis without framework - ELSE: - ERROR: "No framework found and no topic provided" -``` - -### Phase 2: Analysis Mode Detection -```bash -# Determine execution mode -IF framework_mode == true: - mode = "framework_based_analysis" - topic_ref = load_framework_topic() - discussion_points = extract_framework_points() -ELSE: - mode = "standalone_analysis" - topic_ref = provided_topic - discussion_points = generate_basic_structure() -``` - -### Phase 3: Agent Execution with Flow Control -**Framework-Based Analysis Generation** - -```bash -Task(conceptual-planning-agent): " -[FLOW_CONTROL] - -Execute subject-matter-expert analysis for existing topic framework - -## Context Loading -ASSIGNED_ROLE: subject-matter-expert -OUTPUT_LOCATION: .workflow/active/WFS-{session}/.brainstorming/subject-matter-expert/ -ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} - -## 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 subject-matter-expert planning template - - Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/subject-matter-expert.md)) - - Output: role_template_guidelines - -3. **load_session_metadata** - - Action: Load session metadata and existing context - - Command: Read(.workflow/active/WFS-{session}/workflow-session.json) - - Output: session_context - -## Analysis Requirements -**Framework Reference**: Address all discussion points in guidance-specification.md from domain expertise and technical standards perspective -**Role Focus**: Domain knowledge, technical standards, risk assessment, knowledge transfer -**Structured Approach**: Create analysis.md addressing framework discussion points -**Template Integration**: Apply role template guidelines within framework structure - -## Expected Deliverables -1. **analysis.md**: Comprehensive domain expertise analysis addressing all framework discussion points -2. **Framework Reference**: Include @../guidance-specification.md reference in analysis - -## Completion Criteria -- Address each discussion point from guidance-specification.md with subject matter expertise -- Provide actionable technical standards and best practices recommendations -- Include risk assessment and compliance considerations -- Reference framework document using @ notation for integration -" -``` - -## 📋 **TodoWrite Integration** - -### Workflow Progress Tracking -```javascript -TodoWrite({ - todos: [ - { - content: "Detect active session and locate topic framework", - status: "in_progress", - activeForm: "Detecting session and framework" - }, - { - content: "Load guidance-specification.md and session metadata for context", - status: "pending", - activeForm: "Loading framework and session context" - }, - { - content: "Execute subject-matter-expert analysis using conceptual-planning-agent with FLOW_CONTROL", - status: "pending", - activeForm: "Executing subject-matter-expert framework analysis" - }, - { - content: "Generate analysis.md addressing all framework discussion points", - status: "pending", - activeForm: "Generating structured subject-matter-expert analysis" - }, - { - content: "Update workflow-session.json with subject-matter-expert completion status", - status: "pending", - activeForm: "Updating session metadata" - } - ] -}); -``` - -## 📊 **Output Structure** - -### Framework-Based Analysis -``` -.workflow/active/WFS-{session}/.brainstorming/subject-matter-expert/ -└── analysis.md # Structured analysis addressing guidance-specification.md discussion points -``` - -### Analysis Document Structure -```markdown -# Subject Matter Expert Analysis: [Topic from Framework] - -## Framework Reference -**Topic Framework**: @../guidance-specification.md -**Role Focus**: Domain Expertise & Technical Standards perspective - -## Discussion Points Analysis -[Address each point from guidance-specification.md with subject matter expertise] - -### Core Requirements (from framework) -[Domain-specific requirements and industry standards perspective] - -### Technical Considerations (from framework) -[Deep technical analysis, architectural patterns, and best practices] - -### User Experience Factors (from framework) -[Domain-specific usability standards and industry conventions] - -### Implementation Challenges (from framework) -[Technical risks, scalability concerns, and maintenance implications] - -### Success Metrics (from framework) -[Domain-specific KPIs, compliance metrics, and quality standards] - -## Subject Matter Expert Specific Recommendations -[Role-specific technical expertise and industry best practices] - ---- -*Generated by subject-matter-expert analysis addressing structured framework* -``` - -## 🔄 **Session Integration** - -### Completion Status Update -```json -{ - "subject_matter_expert": { - "status": "completed", - "framework_addressed": true, - "output_location": ".workflow/active/WFS-{session}/.brainstorming/subject-matter-expert/analysis.md", - "framework_reference": "@../guidance-specification.md" - } -} -``` - -### Integration Points -- **Framework Reference**: @../guidance-specification.md for structured discussion points -- **Cross-Role Synthesis**: Domain expertise insights available for synthesis-report.md integration -- **Agent Autonomy**: Independent execution with framework guidance diff --git a/.claude/commands/workflow/brainstorm/system-architect.md b/.claude/commands/workflow/brainstorm/system-architect.md deleted file mode 100644 index dfc60465..00000000 --- a/.claude/commands/workflow/brainstorm/system-architect.md +++ /dev/null @@ -1,389 +0,0 @@ ---- -name: system-architect -description: Generate or update system-architect/analysis.md addressing guidance-specification discussion points for system architecture perspective -argument-hint: "optional topic - uses existing framework if available" -allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) ---- - -## 🏗️ **System Architect Analysis Generator** - -### Purpose -**Specialized command for generating system-architect/analysis.md** that addresses guidance-specification.md discussion points from system architecture perspective. Creates or updates role-specific analysis with framework references. - -### Core Function -- **Framework-based Analysis**: Address each discussion point in guidance-specification.md -- **Architecture Focus**: Technical architecture, scalability, and system design perspective -- **Update Mechanism**: Create new or update existing analysis.md -- **Agent Delegation**: Use conceptual-planning-agent for analysis generation - -### Analysis Scope -- **Technical Architecture**: Scalable and maintainable system design -- **Technology Selection**: Stack evaluation and architectural decisions -- **Performance & Scalability**: Capacity planning and optimization strategies -- **Integration Patterns**: System communication and data flow design - -### Role Boundaries & Responsibilities - -#### **What This Role OWNS (Macro-Architecture)** -- **System-Level Architecture**: Service boundaries, deployment topology, and system composition -- **Cross-Service Communication Patterns**: Choosing between microservices/monolithic, event-driven/request-response, sync/async patterns -- **Technology Stack Decisions**: Language, framework, database, and infrastructure choices -- **Non-Functional Requirements**: Scalability, performance, availability, disaster recovery, and monitoring strategies -- **Integration Planning**: How systems and services connect at the macro level (not specific API contracts) - -#### **What This Role DOES NOT Own (Defers to Other Roles)** -- **API Contract Details**: Specific endpoint definitions, URL structures, HTTP methods → Defers to **API Designer** -- **Data Schemas**: Detailed data model design and entity relationships → Defers to **Data Architect** -- **UI/UX Design**: Interface design and user experience → Defers to **UX Expert** and **UI Designer** - -#### **Handoff Points** -- **TO API Designer**: Provides architectural constraints (REST vs GraphQL, sync vs async) that define the API design space -- **TO Data Architect**: Provides system-level data flow requirements and integration patterns -- **FROM Data Architect**: Receives canonical data model to inform system integration design - -## ⚙️ **Execution Protocol** - -### Phase 1: Session & Framework Detection -```bash -# Check active session and framework -CHECK: find .workflow/active/ -name "WFS-*" -type d -IF active_session EXISTS: - session_id = get_active_session() - brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/ - - CHECK: brainstorm_dir/guidance-specification.md - IF EXISTS: - framework_mode = true - load_framework = true - ELSE: - IF topic_provided: - framework_mode = false # Create analysis without framework - ELSE: - ERROR: "No framework found and no topic provided" -``` - -### Phase 2: Analysis Mode Detection -```bash -# Check existing analysis -CHECK: brainstorm_dir/system-architect/analysis.md -IF EXISTS: - SHOW existing analysis summary - ASK: "Analysis exists. Do you want to:" - OPTIONS: - 1. "Update with new insights" → Update existing - 2. "Replace completely" → Generate new - 3. "Cancel" → Exit without changes -ELSE: - CREATE new analysis -``` - -### Phase 3: Agent Task Generation -**Framework-Based Analysis** (when guidance-specification.md exists): -```bash -Task(subagent_type="conceptual-planning-agent", - run_in_background=false, - prompt="Generate system architect analysis addressing topic framework - - ## Framework Integration Required - **MANDATORY**: Load and address guidance-specification.md discussion points - **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md - **Output Location**: {session.brainstorm_dir}/system-architect/analysis.md - - ## Analysis Requirements - 1. **Load Topic Framework**: Read guidance-specification.md completely - 2. **Address Each Discussion Point**: Respond to all 5 framework sections from system architecture perspective - 3. **Include Framework Reference**: Start analysis.md with @../guidance-specification.md - 4. **Technical Focus**: Emphasize scalability, architecture patterns, technology decisions - 5. **Structured Response**: Use framework structure for analysis organization - - ## Framework Sections to Address - - Core Requirements (from architecture perspective) - - Technical Considerations (detailed architectural analysis) - - User Experience Factors (technical UX considerations) - - Implementation Challenges (architecture risks and solutions) - - Success Metrics (technical metrics and monitoring) - - ## Output Structure Required - ```markdown - # System Architect Analysis: [Topic] - - **Framework Reference**: @../guidance-specification.md - **Role Focus**: System Architecture and Technical Design - - ## Core Requirements Analysis - [Address framework requirements from architecture perspective] - - ## Technical Considerations - [Detailed architectural analysis] - - ## User Experience Factors - [Technical aspects of UX implementation] - - ## Implementation Challenges - [Architecture risks and mitigation strategies] - - ## Success Metrics - [Technical metrics and system monitoring] - - ## Architecture-Specific Recommendations - [Detailed technical recommendations] - ```", - description="Generate system architect framework-based analysis") -``` - -### Phase 4: Update Mechanism -**Analysis Update Process**: -```bash -# For existing analysis updates -IF update_mode = "incremental": - Task(subagent_type="conceptual-planning-agent", - run_in_background=false, - prompt="Update existing system architect analysis - - ## Current Analysis Context - **Existing Analysis**: @{session.brainstorm_dir}/system-architect/analysis.md - **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md - - ## Update Requirements - 1. **Preserve Structure**: Maintain existing analysis structure - 2. **Add New Insights**: Integrate new technical insights and recommendations - 3. **Framework Alignment**: Ensure continued alignment with topic framework - 4. **Technical Updates**: Add new architecture patterns, technology considerations - 5. **Maintain References**: Keep @../guidance-specification.md reference - - ## Update Instructions - - Read existing analysis completely - - Identify areas for enhancement or new insights - - Add technical depth while preserving original structure - - Update recommendations with new architectural approaches - - Maintain framework discussion point addressing", - description="Update system architect analysis incrementally") -``` - -## Document Structure - -### Output Files -``` -.workflow/active/WFS-[topic]/.brainstorming/ -├── guidance-specification.md # Input: Framework (if exists) -└── system-architect/ - └── analysis.md # ★ OUTPUT: Framework-based analysis -``` - -### Analysis Structure -**Required Elements**: -- **Framework Reference**: @../guidance-specification.md (if framework exists) -- **Role Focus**: System Architecture and Technical Design perspective -- **5 Framework Sections**: Address each framework discussion point -- **Technical Recommendations**: Architecture-specific insights and solutions -- How should we design APIs and manage versioning? - -**4. Performance and Scalability** -- Where are the current system performance bottlenecks? -- How should we handle traffic growth and scaling demands? -- What database scaling and optimization strategies are needed? - -## ⚡ **Two-Step Execution Flow** - -### ⚠️ Session Management - FIRST STEP -Session detection and selection: -```bash -# Check for existing sessions -existing_sessions=$(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null) -if [ multiple_sessions ]; then - prompt_user_to_select_session() -else - use_existing_or_create_new() -fi -``` - -### Step 1: Context Gathering Phase -**System Architect Perspective Questioning** - -Before agent assignment, gather comprehensive system architecture context: - -#### 📋 Role-Specific Questions -1. **Scale & Performance Requirements** - - Expected user load and traffic patterns? - - Performance requirements (latency, throughput)? - - Data volume and growth projections? - -2. **Technical Constraints & Environment** - - Existing technology stack and constraints? - - Integration requirements with external systems? - - Infrastructure and deployment environment? - -3. **Architecture Complexity & Patterns** - - Microservices vs monolithic considerations? - - Data consistency and transaction requirements? - - Event-driven vs request-response patterns? - -4. **Non-Functional Requirements** - - High availability and disaster recovery needs? - - Security and compliance requirements? - - Monitoring and observability expectations? - -#### Context Validation -- **Minimum Response**: Each answer must be ≥50 characters -- **Re-prompting**: Insufficient detail triggers follow-up questions -- **Context Storage**: Save responses to `.brainstorming/system-architect-context.md` - -### Step 2: Agent Assignment with Flow Control -**Dedicated Agent Execution** - -```bash -Task(conceptual-planning-agent): " -[FLOW_CONTROL] - -Execute dedicated system-architect conceptual analysis for: {topic} - -ASSIGNED_ROLE: system-architect -OUTPUT_LOCATION: .brainstorming/system-architect/ -USER_CONTEXT: {validated_responses_from_context_gathering} - -Flow Control Steps: -[ - { - \"step\": \"load_role_template\", - \"action\": \"Load system-architect planning template\", - \"command\": \"bash($(cat ~/.claude/workflows/cli-templates/planning-roles/system-architect.md))\", - \"output_to\": \"role_template\" - } -] - -Conceptual Analysis Requirements: -- Apply system-architect perspective to topic analysis -- Focus on architectural patterns, scalability, and integration points -- Use loaded role template framework for analysis structure -- Generate role-specific deliverables in designated output location -- Address all user context from questioning phase - -Deliverables: -- analysis.md: Main system architecture analysis -- recommendations.md: Architecture recommendations -- deliverables/: Architecture-specific outputs as defined in role template - -Embody system-architect role expertise for comprehensive conceptual planning." -``` - -### Progress Tracking -TodoWrite tracking for two-step process: -```json -[ - {"content": "Gather system architect context through role-specific questioning", "status": "in_progress", "activeForm": "Gathering context"}, - {"content": "Validate context responses and save to system-architect-context.md", "status": "pending", "activeForm": "Validating context"}, - {"content": "Load system-architect planning template via flow control", "status": "pending", "activeForm": "Loading template"}, - {"content": "Execute dedicated conceptual-planning-agent for system-architect role", "status": "pending", "activeForm": "Executing agent"} -] -``` - -## 📊 **Output Specification** - -### Output Location -``` -.workflow/active/WFS-{topic-slug}/.brainstorming/system-architect/ -├── analysis.md # Primary architecture analysis -├── architecture-design.md # Detailed system design and diagrams -├── technology-stack.md # Technology stack recommendations and justifications -└── integration-plan.md # System integration and API strategies -``` - -### Document Templates - -#### analysis.md Structure -```markdown -# System Architecture Analysis: {Topic} -*Generated: {timestamp}* - -## Executive Summary -[Key architectural findings and recommendations overview] - -## Current State Assessment -### Existing Architecture Overview -### Technical Stack Analysis -### Performance Bottlenecks -### Technical Debt Assessment - -## Requirements Analysis -### Functional Requirements -### Non-Functional Requirements -- Performance: [Response time, throughput requirements] -- Scalability: [User growth, data volume expectations] -- Availability: [Uptime requirements] -- Security: [Security requirements] - -## Proposed Architecture -### High-Level Architecture Design -### Component Breakdown -### Data Flow Diagrams -### Technology Stack Recommendations - -## Implementation Strategy -### Migration Planning -### Risk Mitigation -### Performance Optimization -### Security Considerations - -## Scalability and Maintenance -### Horizontal Scaling Strategy -### Monitoring and Observability -### Deployment Strategy -### Long-term Maintenance Plan -``` - -## 🔄 **Session Integration** - -### Status Synchronization -Upon completion, update `workflow-session.json`: -```json -{ - "phases": { - "BRAINSTORM": { - "system_architect": { - "status": "completed", - "completed_at": "timestamp", - "output_directory": ".workflow/active/WFS-{topic}/.brainstorming/system-architect/", - "key_insights": ["scalability_bottleneck", "architecture_pattern", "technology_recommendation"] - } - } - } -} -``` - -### Cross-Role Collaboration -System architect perspective provides: -- **Technical Constraints and Possibilities** → Product Manager -- **Architecture Requirements and Limitations** → UI Designer -- **Data Architecture Requirements** → Data Architect -- **Security Architecture Framework** → Security Expert -- **Technical Implementation Framework** → Feature Planner - -## ✅ **Quality Assurance** - -### Required Analysis Elements -- [ ] Clear architecture diagrams and component designs -- [ ] Detailed technology stack evaluation and recommendations -- [ ] Scalability and performance analysis with metrics -- [ ] System integration and API design specifications -- [ ] Comprehensive risk assessment and mitigation strategies - -### Architecture Design Principles -- [ ] **Scalability**: System can handle growth in users and data -- [ ] **Maintainability**: Clear code structure, easy to modify and extend -- [ ] **Reliability**: Built-in fault tolerance and recovery mechanisms -- [ ] **Security**: Integrated security controls and protection measures -- [ ] **Performance**: Meets response time and throughput requirements - -### Technical Decision Validation -- [ ] Technology choices have thorough justification and comparison analysis -- [ ] Architectural patterns align with business requirements and constraints -- [ ] Integration solutions consider compatibility and maintenance costs -- [ ] Deployment strategies are feasible with acceptable risk levels -- [ ] Monitoring and operations strategies are comprehensive and actionable - -### Implementation Readiness -- [ ] **Technical Feasibility**: All proposed solutions are technically achievable -- [ ] **Resource Planning**: Resource requirements clearly defined and realistic -- [ ] **Risk Management**: Technical risks identified with mitigation plans -- [ ] **Performance Validation**: Architecture can meet performance requirements -- [ ] **Evolution Strategy**: Design allows for future growth and changes diff --git a/.claude/commands/workflow/brainstorm/ui-designer.md b/.claude/commands/workflow/brainstorm/ui-designer.md deleted file mode 100644 index e14a87a5..00000000 --- a/.claude/commands/workflow/brainstorm/ui-designer.md +++ /dev/null @@ -1,221 +0,0 @@ ---- -name: ui-designer -description: Generate or update ui-designer/analysis.md addressing guidance-specification discussion points for UI design perspective -argument-hint: "optional topic - uses existing framework if available" -allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) ---- - -## 🎨 **UI Designer Analysis Generator** - -### Purpose -**Specialized command for generating ui-designer/analysis.md** that addresses guidance-specification.md discussion points from UI/UX design perspective. Creates or updates role-specific analysis with framework references. - -### Core Function -- **Framework-based Analysis**: Address each discussion point in guidance-specification.md -- **UI/UX Focus**: User experience, interface design, and accessibility perspective -- **Update Mechanism**: Create new or update existing analysis.md -- **Agent Delegation**: Use conceptual-planning-agent for analysis generation - -### Analysis Scope -- **Visual Design**: Color palettes, typography, spacing, and visual hierarchy implementation -- **High-Fidelity Mockups**: Polished, pixel-perfect interface designs -- **Design System Implementation**: Component libraries, design tokens, and style guides -- **Micro-Interactions & Animations**: Transition effects, loading states, and interactive feedback -- **Responsive Design**: Layout adaptations for different screen sizes and devices - -### Role Boundaries & Responsibilities - -#### **What This Role OWNS (Concrete Visual Interface Implementation)** -- **Visual Design Language**: Colors, typography, iconography, spacing, and overall aesthetic -- **High-Fidelity Mockups**: Polished designs showing exactly how the interface will look -- **Design System Components**: Building and documenting reusable UI components (buttons, inputs, cards, etc.) -- **Design Tokens**: Defining variables for colors, spacing, typography that can be used in code -- **Micro-Interactions**: Hover states, transitions, animations, and interactive feedback details -- **Responsive Layouts**: Adapting designs for mobile, tablet, and desktop breakpoints - -#### **What This Role DOES NOT Own (Defers to Other Roles)** -- **User Research & Personas**: User behavior analysis and needs assessment → Defers to **UX Expert** -- **Information Architecture**: Content structure and navigation strategy → Defers to **UX Expert** -- **Low-Fidelity Wireframes**: Structural layouts without visual design → Defers to **UX Expert** - -#### **Handoff Points** -- **FROM UX Expert**: Receives wireframes, user flows, and information architecture as the foundation for visual design -- **TO Frontend Developers**: Provides design specifications, component libraries, and design tokens for implementation -- **WITH API Designer**: Coordinates on data presentation and form validation feedback (visual aspects only) - -## ⚙️ **Execution Protocol** - -### Phase 1: Session & Framework Detection -```bash -# Check active session and framework -CHECK: find .workflow/active/ -name "WFS-*" -type d -IF active_session EXISTS: - session_id = get_active_session() - brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/ - - CHECK: brainstorm_dir/guidance-specification.md - IF EXISTS: - framework_mode = true - load_framework = true - ELSE: - IF topic_provided: - framework_mode = false # Create analysis without framework - ELSE: - ERROR: "No framework found and no topic provided" -``` - -### Phase 2: Analysis Mode Detection -```bash -# Determine execution mode -IF framework_mode == true: - mode = "framework_based_analysis" - topic_ref = load_framework_topic() - discussion_points = extract_framework_points() -ELSE: - mode = "standalone_analysis" - topic_ref = provided_topic - discussion_points = generate_basic_structure() -``` - -### Phase 3: Agent Execution with Flow Control -**Framework-Based Analysis Generation** - -```bash -Task(conceptual-planning-agent): " -[FLOW_CONTROL] - -Execute ui-designer analysis for existing topic framework - -## Context Loading -ASSIGNED_ROLE: ui-designer -OUTPUT_LOCATION: .workflow/active/WFS-{session}/.brainstorming/ui-designer/ -ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} - -## 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 ui-designer planning template - - Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/ui-designer.md)) - - Output: role_template_guidelines - -3. **load_session_metadata** - - Action: Load session metadata and existing context - - Command: Read(.workflow/active/WFS-{session}/workflow-session.json) - - Output: session_context - -## Analysis Requirements -**Framework Reference**: Address all discussion points in guidance-specification.md from UI/UX perspective -**Role Focus**: User experience design, interface optimization, accessibility compliance -**Structured Approach**: Create analysis.md addressing framework discussion points -**Template Integration**: Apply role template guidelines within framework structure - -## Expected Deliverables -1. **analysis.md**: Comprehensive UI/UX analysis addressing all framework discussion points -2. **Framework Reference**: Include @../guidance-specification.md reference in analysis - -## Completion Criteria -- Address each discussion point from guidance-specification.md with UI/UX design expertise -- Provide actionable design recommendations and interface solutions -- Include accessibility considerations and WCAG compliance planning -- Reference framework document using @ notation for integration -" -``` - -## 📋 **TodoWrite Integration** - -### Workflow Progress Tracking -```javascript -TodoWrite({ - todos: [ - { - content: "Detect active session and locate topic framework", - status: "in_progress", - activeForm: "Detecting session and framework" - }, - { - content: "Load guidance-specification.md and session metadata for context", - status: "pending", - activeForm: "Loading framework and session context" - }, - { - content: "Execute ui-designer analysis using conceptual-planning-agent with FLOW_CONTROL", - status: "pending", - activeForm: "Executing ui-designer framework analysis" - }, - { - content: "Generate analysis.md addressing all framework discussion points", - status: "pending", - activeForm: "Generating structured ui-designer analysis" - }, - { - content: "Update workflow-session.json with ui-designer completion status", - status: "pending", - activeForm: "Updating session metadata" - } - ] -}); -``` - -## 📊 **Output Structure** - -### Framework-Based Analysis -``` -.workflow/active/WFS-{session}/.brainstorming/ui-designer/ -└── analysis.md # Structured analysis addressing guidance-specification.md discussion points -``` - -### Analysis Document Structure -```markdown -# UI Designer Analysis: [Topic from Framework] - -## Framework Reference -**Topic Framework**: @../guidance-specification.md -**Role Focus**: UI/UX Design perspective - -## Discussion Points Analysis -[Address each point from guidance-specification.md with UI/UX expertise] - -### Core Requirements (from framework) -[UI/UX perspective on requirements] - -### Technical Considerations (from framework) -[Interface and design system considerations] - -### User Experience Factors (from framework) -[Detailed UX analysis and recommendations] - -### Implementation Challenges (from framework) -[Design implementation and accessibility considerations] - -### Success Metrics (from framework) -[UX metrics and usability success criteria] - -## UI/UX Specific Recommendations -[Role-specific design recommendations and solutions] - ---- -*Generated by ui-designer analysis addressing structured framework* -``` - -## 🔄 **Session Integration** - -### Completion Status Update -```json -{ - "ui_designer": { - "status": "completed", - "framework_addressed": true, - "output_location": ".workflow/active/WFS-{session}/.brainstorming/ui-designer/analysis.md", - "framework_reference": "@../guidance-specification.md" - } -} -``` - -### Integration Points -- **Framework Reference**: @../guidance-specification.md for structured discussion points -- **Cross-Role Synthesis**: UI/UX insights available for synthesis-report.md integration -- **Agent Autonomy**: Independent execution with framework guidance diff --git a/.claude/commands/workflow/brainstorm/ux-expert.md b/.claude/commands/workflow/brainstorm/ux-expert.md deleted file mode 100644 index 66dd9f4f..00000000 --- a/.claude/commands/workflow/brainstorm/ux-expert.md +++ /dev/null @@ -1,221 +0,0 @@ ---- -name: ux-expert -description: Generate or update ux-expert/analysis.md addressing guidance-specification discussion points for UX perspective -argument-hint: "optional topic - uses existing framework if available" -allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*) ---- - -## 🎯 **UX Expert Analysis Generator** - -### Purpose -**Specialized command for generating ux-expert/analysis.md** that addresses guidance-specification.md discussion points from user experience and interface design perspective. Creates or updates role-specific analysis with framework references. - -### Core Function -- **Framework-based Analysis**: Address each discussion point in guidance-specification.md -- **UX Design Focus**: User interface, interaction patterns, and usability optimization -- **Update Mechanism**: Create new or update existing analysis.md -- **Agent Delegation**: Use conceptual-planning-agent for analysis generation - -### Analysis Scope -- **User Research**: User personas, behavioral analysis, and needs assessment -- **Information Architecture**: Content structure, navigation hierarchy, and mental models -- **User Journey Mapping**: User flows, task analysis, and interaction models -- **Usability Strategy**: Accessibility planning, cognitive load reduction, and user testing frameworks -- **Wireframing**: Low-fidelity layouts and structural prototypes (not visual design) - -### Role Boundaries & Responsibilities - -#### **What This Role OWNS (Abstract User Experience & Research)** -- **User Research & Personas**: Understanding target users, their goals, pain points, and behaviors -- **Information Architecture**: Organizing content and defining navigation structures at a conceptual level -- **User Journey Mapping**: Defining user flows, task sequences, and interaction models -- **Wireframes & Low-Fidelity Prototypes**: Structural layouts showing information hierarchy (boxes and arrows, not colors/fonts) -- **Usability Testing Strategy**: Planning user testing, A/B tests, and validation methods -- **Accessibility Planning**: WCAG compliance strategy and inclusive design principles - -#### **What This Role DOES NOT Own (Defers to Other Roles)** -- **Visual Design**: Colors, typography, spacing, visual style → Defers to **UI Designer** -- **High-Fidelity Mockups**: Polished, pixel-perfect designs → Defers to **UI Designer** -- **Component Implementation**: Design system components, CSS, animations → Defers to **UI Designer** - -#### **Handoff Points** -- **TO UI Designer**: Provides wireframes, user flows, and information architecture that UI Designer will transform into high-fidelity visual designs -- **FROM User Research**: May receive external research data to inform UX decisions -- **TO Product Owner**: Provides user insights and validation results to inform feature prioritization - -## ⚙️ **Execution Protocol** - -### Phase 1: Session & Framework Detection -```bash -# Check active session and framework -CHECK: find .workflow/active/ -name "WFS-*" -type d -IF active_session EXISTS: - session_id = get_active_session() - brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/ - - CHECK: brainstorm_dir/guidance-specification.md - IF EXISTS: - framework_mode = true - load_framework = true - ELSE: - IF topic_provided: - framework_mode = false # Create analysis without framework - ELSE: - ERROR: "No framework found and no topic provided" -``` - -### Phase 2: Analysis Mode Detection -```bash -# Determine execution mode -IF framework_mode == true: - mode = "framework_based_analysis" - topic_ref = load_framework_topic() - discussion_points = extract_framework_points() -ELSE: - mode = "standalone_analysis" - topic_ref = provided_topic - discussion_points = generate_basic_structure() -``` - -### Phase 3: Agent Execution with Flow Control -**Framework-Based Analysis Generation** - -```bash -Task(conceptual-planning-agent): " -[FLOW_CONTROL] - -Execute ux-expert analysis for existing topic framework - -## Context Loading -ASSIGNED_ROLE: ux-expert -OUTPUT_LOCATION: .workflow/active/WFS-{session}/.brainstorming/ux-expert/ -ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"} - -## 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 ux-expert planning template - - Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/ux-expert.md)) - - Output: role_template_guidelines - -3. **load_session_metadata** - - Action: Load session metadata and existing context - - Command: Read(.workflow/active/WFS-{session}/workflow-session.json) - - Output: session_context - -## Analysis Requirements -**Framework Reference**: Address all discussion points in guidance-specification.md from user experience and interface design perspective -**Role Focus**: UI design, interaction patterns, usability optimization, design systems -**Structured Approach**: Create analysis.md addressing framework discussion points -**Template Integration**: Apply role template guidelines within framework structure - -## Expected Deliverables -1. **analysis.md**: Comprehensive UX design analysis addressing all framework discussion points -2. **Framework Reference**: Include @../guidance-specification.md reference in analysis - -## Completion Criteria -- Address each discussion point from guidance-specification.md with UX design expertise -- Provide actionable interface design and usability optimization strategies -- Include accessibility considerations and interaction pattern recommendations -- Reference framework document using @ notation for integration -" -``` - -## 📋 **TodoWrite Integration** - -### Workflow Progress Tracking -```javascript -TodoWrite({ - todos: [ - { - content: "Detect active session and locate topic framework", - status: "in_progress", - activeForm: "Detecting session and framework" - }, - { - content: "Load guidance-specification.md and session metadata for context", - status: "pending", - activeForm: "Loading framework and session context" - }, - { - content: "Execute ux-expert analysis using conceptual-planning-agent with FLOW_CONTROL", - status: "pending", - activeForm: "Executing ux-expert framework analysis" - }, - { - content: "Generate analysis.md addressing all framework discussion points", - status: "pending", - activeForm: "Generating structured ux-expert analysis" - }, - { - content: "Update workflow-session.json with ux-expert completion status", - status: "pending", - activeForm: "Updating session metadata" - } - ] -}); -``` - -## 📊 **Output Structure** - -### Framework-Based Analysis -``` -.workflow/active/WFS-{session}/.brainstorming/ux-expert/ -└── analysis.md # Structured analysis addressing guidance-specification.md discussion points -``` - -### Analysis Document Structure -```markdown -# UX Expert Analysis: [Topic from Framework] - -## Framework Reference -**Topic Framework**: @../guidance-specification.md -**Role Focus**: User Experience & Interface Design perspective - -## Discussion Points Analysis -[Address each point from guidance-specification.md with UX design expertise] - -### Core Requirements (from framework) -[User interface and interaction design requirements perspective] - -### Technical Considerations (from framework) -[Design system implementation and technical feasibility considerations] - -### User Experience Factors (from framework) -[Usability optimization, accessibility, and user-centered design analysis] - -### Implementation Challenges (from framework) -[Design implementation challenges and progressive enhancement strategies] - -### Success Metrics (from framework) -[UX metrics including usability testing, user satisfaction, and design KPIs] - -## UX Expert Specific Recommendations -[Role-specific interface design patterns and usability optimization strategies] - ---- -*Generated by ux-expert analysis addressing structured framework* -``` - -## 🔄 **Session Integration** - -### Completion Status Update -```json -{ - "ux_expert": { - "status": "completed", - "framework_addressed": true, - "output_location": ".workflow/active/WFS-{session}/.brainstorming/ux-expert/analysis.md", - "framework_reference": "@../guidance-specification.md" - } -} -``` - -### Integration Points -- **Framework Reference**: @../guidance-specification.md for structured discussion points -- **Cross-Role Synthesis**: UX design insights available for synthesis-report.md integration -- **Agent Autonomy**: Independent execution with framework guidance diff --git a/.claude/skills/skill-generator/phases/01-requirements-discovery.md b/.claude/skills/skill-generator/phases/01-requirements-discovery.md index d404bdf5..b54b69c2 100644 --- a/.claude/skills/skill-generator/phases/01-requirements-discovery.md +++ b/.claude/skills/skill-generator/phases/01-requirements-discovery.md @@ -218,3 +218,11 @@ Write(`${workDir}/skill-config.json`, JSON.stringify(config, null, 2)); ``` + +## Next Phase + +→ [Phase 2: Structure Generation](02-structure-generation.md) + +**Data Flow to Phase 2**: +- skill-config.json with all configuration parameters +- Execution mode decision drives directory structure creation diff --git a/.claude/skills/skill-generator/phases/02-structure-generation.md b/.claude/skills/skill-generator/phases/02-structure-generation.md index b840e362..0fdcad2a 100644 --- a/.claude/skills/skill-generator/phases/02-structure-generation.md +++ b/.claude/skills/skill-generator/phases/02-structure-generation.md @@ -191,3 +191,12 @@ function generateReferenceTable(config) { ``` + +## Next Phase + +→ [Phase 3: Phase Generation](03-phase-generation.md) + +**Data Flow to Phase 3**: +- Complete directory structure in .claude/skills/{skill-name}/ +- SKILL.md entry file ready for phase/action generation +- skill-config.json for template population diff --git a/.claude/skills/skill-generator/phases/05-validation.md b/.claude/skills/skill-generator/phases/05-validation.md index 07fb637b..2d90e1ef 100644 --- a/.claude/skills/skill-generator/phases/05-validation.md +++ b/.claude/skills/skill-generator/phases/05-validation.md @@ -1,27 +1,119 @@ # Phase 5: Validation & Documentation -验证生成的 Skill 完整性并生成使用说明。 +Verify generated skill completeness and generate user documentation. ## Objective -- 验证所有必需文件存在 -- 检查文件内容完整性 -- 生成 README.md 使用说明 -- 输出验证报告 +Comprehensive validation and documentation: +- Verify all required files exist +- Check file content quality and completeness +- Generate validation report with issues and recommendations +- Generate README.md usage documentation +- Output final status and next steps ## Input -- 依赖: 所有前序阶段产出 -- 生成的 Skill 目录 +**File Dependencies**: +- `skill-config.json` (from Phase 1) +- `.claude/skills/{skill-name}/` directory (from Phase 2) +- All generated phase/action files (from Phase 3) +- All generated specs/templates files (from Phase 4) -## Execution Steps +**Required Information**: +- Skill name, display name, description +- Execution mode +- Trigger words +- Output configuration +- Complete skill directory structure -### Step 1: 文件完整性检查 +## Output + +**Generated Files**: + +| File | Purpose | Content | +|------|---------|---------| +| `validation-report.json` (workDir) | Validation report with detailed checks | File completeness, content quality, issues, recommendations | +| `README.md` (skillDir) | User documentation | Quick Start, Usage, Output, Directory Structure, Customization | + +**Validation Report Structure** (`validation-report.json`): +```json +{ + "skill_name": "...", + "execution_mode": "sequential|autonomous", + "generated_at": "ISO timestamp", + "file_checks": { + "total": N, + "existing": N, + "with_content": N, + "with_todos": N, + "details": [...] + }, + "content_checks": { + "files_checked": N, + "all_passed": true|false, + "details": [...] + }, + "summary": { + "status": "PASS|REVIEW|FAIL", + "issues": [...], + "recommendations": [...] + } +} +``` + +**README Structure** (`README.md`): +```markdown +# {display_name} +- Quick Start (Triggers, Execution Mode) +- Usage (Examples) +- Output (Format, Location, Filename) +- Directory Structure (Tree view) +- Customization (How to modify) +- Related Documents (Links) +``` + +**Validation Status Gates**: + +| Status | Condition | Meaning | +|--------|-----------|---------| +| PASS | All files exist + All content checks passed | Ready for use | +| REVIEW | All files exist + Some content checks failed | Needs refinement | +| FAIL | Missing files | Incomplete generation | + +## Decision Logic + +``` +Decision (Validation Flow): + ├─ File Completeness Check + │ ├─ All files exist → Continue to content checks + │ └─ Missing files → Status = FAIL, collect missing file errors + │ + ├─ Content Quality Check + │ ├─ Sequential mode → Check phase files for structure + │ ├─ Autonomous mode → Check orchestrator + action files + │ └─ Common → Check SKILL.md, specs/, templates/ + │ + ├─ Status Calculation + │ ├─ All files exist + All checks pass → Status = PASS + │ ├─ All files exist + Some checks fail → Status = REVIEW + │ └─ Missing files → Status = FAIL + │ + └─ Generate Report & README + ├─ validation-report.json (with issues and recommendations) + └─ README.md (with usage documentation) +``` + +## Execution Protocol ```javascript +// Phase 5: Validation & Documentation +// Reference: phases/05-validation.md + +// Load config and setup const config = JSON.parse(Read(`${workDir}/skill-config.json`)); const skillDir = `.claude/skills/${config.skill_name}`; +// Step 1: File completeness check const requiredFiles = { common: [ 'SKILL.md', @@ -64,14 +156,11 @@ const fileCheckResults = filesToCheck.map(file => { }; } }); -``` -### Step 2: 内容质量检查 - -```javascript +// Step 2: Content quality check const contentChecks = []; -// 检查 SKILL.md +// Check SKILL.md structure const skillMd = Read(`${skillDir}/SKILL.md`); contentChecks.push({ file: 'SKILL.md', @@ -83,11 +172,11 @@ contentChecks.push({ ] }); -// 检查 Phase 文件 +// Check phase files const phaseFiles = Glob(`${skillDir}/phases/*.md`); for (const phaseFile of phaseFiles) { - if (phaseFile.includes('/actions/')) continue; // 单独检查 - + if (phaseFile.includes('/actions/')) continue; // Check separately + const content = Read(phaseFile); contentChecks.push({ file: phaseFile.replace(skillDir + '/', ''), @@ -100,7 +189,7 @@ for (const phaseFile of phaseFiles) { }); } -// 检查 Specs 文件 +// Check specs files const specFiles = Glob(`${skillDir}/specs/*.md`); for (const specFile of specFiles) { const content = Read(specFile); @@ -113,16 +202,13 @@ for (const specFile of specFiles) { ] }); } -``` -### Step 3: 生成验证报告 - -```javascript +// Step 3: Generate validation report const report = { skill_name: config.skill_name, execution_mode: config.execution_mode, generated_at: new Date().toISOString(), - + file_checks: { total: fileCheckResults.length, existing: fileCheckResults.filter(f => f.exists).length, @@ -130,13 +216,13 @@ const report = { with_todos: fileCheckResults.filter(f => f.hasTodo).length, details: fileCheckResults }, - + content_checks: { files_checked: contentChecks.length, all_passed: contentChecks.every(c => c.checks.every(ch => ch.pass)), details: contentChecks }, - + summary: { status: calculateOverallStatus(fileCheckResults, contentChecks), issues: collectIssues(fileCheckResults, contentChecks), @@ -146,10 +232,11 @@ const report = { Write(`${workDir}/validation-report.json`, JSON.stringify(report, null, 2)); +// Helper functions function calculateOverallStatus(fileResults, contentResults) { const allFilesExist = fileResults.every(f => f.exists); const allContentPassed = contentResults.every(c => c.checks.every(ch => ch.pass)); - + if (allFilesExist && allContentPassed) return 'PASS'; if (allFilesExist) return 'REVIEW'; return 'FAIL'; @@ -157,44 +244,41 @@ function calculateOverallStatus(fileResults, contentResults) { function collectIssues(fileResults, contentResults) { const issues = []; - + fileResults.filter(f => !f.exists).forEach(f => { issues.push({ type: 'ERROR', message: `文件缺失: ${f.file}` }); }); - + fileResults.filter(f => f.hasTodo).forEach(f => { issues.push({ type: 'WARNING', message: `包含 TODO: ${f.file}` }); }); - + contentResults.forEach(c => { c.checks.filter(ch => !ch.pass).forEach(ch => { issues.push({ type: 'WARNING', message: `${c.file}: 缺少 ${ch.name}` }); }); }); - + return issues; } function generateRecommendations(fileResults, contentResults) { const recommendations = []; - + if (fileResults.some(f => f.hasTodo)) { recommendations.push('替换所有 TODO 占位符为实际内容'); } - + contentResults.forEach(c => { if (c.checks.some(ch => !ch.pass)) { recommendations.push(`完善 ${c.file} 的结构`); } }); - + return recommendations; } -``` -### Step 4: 生成 README.md - -```javascript +// Step 4: Generate README.md const readme = `# ${config.display_name} ${config.description} @@ -210,10 +294,10 @@ ${config.triggers.map(t => `- "${t}"`).join('\n')} **${config.execution_mode === 'sequential' ? 'Sequential (顺序)' : 'Autonomous (自主)'}** ${config.execution_mode === 'sequential' ? - `阶段按固定顺序执行：\n${config.sequential_config.phases.map((p, i) => + `阶段按固定顺序执行：\n${config.sequential_config.phases.map((p, i) => `${i + 1}. ${p.name}` ).join('\n')}` : - `动作由编排器动态选择：\n${config.autonomous_config.actions.map(a => + `动作由编排器动态选择：\n${config.autonomous_config.actions.map(a => `- ${a.name}: ${a.description || ''}` ).join('\n')}`} @@ -283,24 +367,21 @@ ${config.execution_mode === 'sequential' ? `; Write(`${skillDir}/README.md`, readme); -``` -### Step 5: 输出最终结果 - -```javascript +// Step 5: Output final result const finalResult = { skill_name: config.skill_name, skill_path: skillDir, execution_mode: config.execution_mode, - + generated_files: [ 'SKILL.md', 'README.md', ...filesToCheck ], - + validation: report.summary, - + next_steps: [ '1. 审阅生成的文件结构', '2. 替换 TODO 占位符', @@ -319,16 +400,18 @@ console.log('下一步:'); finalResult.next_steps.forEach(s => console.log(s)); ``` -## Output +## Workflow Completion -- `{workDir}/validation-report.json` - 验证报告 -- `{skillDir}/README.md` - 使用说明 +**Final Status**: Skill generation pipeline complete -## Completion +**Generated Artifacts**: +- Complete skill directory structure in `.claude/skills/{skill-name}/` +- Validation report in `{workDir}/validation-report.json` +- User documentation in `{skillDir}/README.md` -Skill 生成流程完成。用户可以： - -1. 查看生成的 Skill 目录 -2. 根据验证报告修复问题 -3. 自定义执行逻辑 -4. 测试 Skill 功能 +**Next Steps**: +1. Review validation report for any issues or recommendations +2. Replace TODO placeholders with actual implementation +3. Test skill execution with trigger words +4. Customize phase logic based on specific requirements +5. Update triggers and descriptions as needed diff --git a/.claude/skills/skill-generator/templates/autonomous-action.md b/.claude/skills/skill-generator/templates/autonomous-action.md index 83cae3c7..0bb8a21c 100644 --- a/.claude/skills/skill-generator/templates/autonomous-action.md +++ b/.claude/skills/skill-generator/templates/autonomous-action.md @@ -2,6 +2,20 @@ 自主模式动作文件的模板。 +## Purpose + +生成 Autonomous 执行模式的 Action 文件，定义可独立执行的动作单元。 + +## Usage Context + +| Phase | Usage | +|-------|-------| +| Phase 3 (Phase Generation) | `config.execution_mode === 'autonomous'` 时生成 | +| Generation Trigger | 为每个 `config.autonomous_config.actions` 生成一个 action 文件 | +| Output Location | `.claude/skills/{skill-name}/phases/actions/{action-id}.md` | + +--- + ## 模板结构 ```markdown diff --git a/.claude/skills/skill-generator/templates/autonomous-orchestrator.md b/.claude/skills/skill-generator/templates/autonomous-orchestrator.md index c88f25eb..a44c9869 100644 --- a/.claude/skills/skill-generator/templates/autonomous-orchestrator.md +++ b/.claude/skills/skill-generator/templates/autonomous-orchestrator.md @@ -2,6 +2,20 @@ 自主模式编排器的模板。 +## Purpose + +生成 Autonomous 执行模式的 Orchestrator 文件，负责状态驱动的动作选择和执行循环。 + +## Usage Context + +| Phase | Usage | +|-------|-------| +| Phase 3 (Phase Generation) | `config.execution_mode === 'autonomous'` 时生成 | +| Generation Trigger | 创建编排器逻辑，管理动作选择和状态更新 | +| Output Location | `.claude/skills/{skill-name}/phases/orchestrator.md` | + +--- + ## ⚠️ 重要提示 > **Phase 0 是强制前置阶段**：在 Orchestrator 启动执行循环之前，必须先完成 Phase 0 的规范研读。 diff --git a/.claude/skills/skill-generator/templates/code-analysis-action.md b/.claude/skills/skill-generator/templates/code-analysis-action.md index c0233186..60b1f1d8 100644 --- a/.claude/skills/skill-generator/templates/code-analysis-action.md +++ b/.claude/skills/skill-generator/templates/code-analysis-action.md @@ -2,6 +2,18 @@ 代码分析动作模板，用于在 Skill 中集成代码探索和分析能力。 +## Purpose + +为 Skill 生成代码分析动作，集成 MCP 工具 (ACE) 和 Agent 进行语义搜索和深度分析。 + +## Usage Context + +| Phase | Usage | +|-------|-------| +| Optional | 当 Skill 需要代码探索和分析能力时使用 | +| Generation Trigger | 用户选择添加 code-analysis 动作类型 | +| Agent Types | Explore, cli-explore-agent, universal-executor | + --- ## 配置结构 diff --git a/.claude/skills/skill-generator/templates/llm-action.md b/.claude/skills/skill-generator/templates/llm-action.md index f003a618..84668a3e 100644 --- a/.claude/skills/skill-generator/templates/llm-action.md +++ b/.claude/skills/skill-generator/templates/llm-action.md @@ -2,6 +2,18 @@ LLM 动作模板，用于在 Skill 中集成 LLM 调用能力。 +## Purpose + +为 Skill 生成 LLM 动作，通过 CCW CLI 统一接口调用 Gemini/Qwen/Codex 进行分析或生成。 + +## Usage Context + +| Phase | Usage | +|-------|-------| +| Optional | 当 Skill 需要 LLM 能力时使用 | +| Generation Trigger | 用户选择添加 llm 动作类型 | +| Tools | gemini, qwen, codex (支持 fallback chain) | + --- ## 配置结构 diff --git a/.claude/skills/skill-generator/templates/script-bash.md b/.claude/skills/skill-generator/templates/script-bash.md index 9b90fa65..8d4108e1 100644 --- a/.claude/skills/skill-generator/templates/script-bash.md +++ b/.claude/skills/skill-generator/templates/script-bash.md @@ -2,6 +2,20 @@ Bash 脚本模板，用于生成技能中的确定性脚本。 +## Purpose + +为 Skill 生成 Bash 脚本，用于执行确定性操作（文件处理、系统命令、数据转换等）。 + +## Usage Context + +| Phase | Usage | +|-------|-------| +| Optional | Phase/Action 中声明 `## Scripts` 时使用 | +| Execution | 通过 `ExecuteScript('script-id', params)` 调用 | +| Output Location | `.claude/skills/{skill-name}/scripts/{script-id}.sh` | + +--- + ## 模板代码 ```bash diff --git a/.claude/skills/skill-generator/templates/script-python.md b/.claude/skills/skill-generator/templates/script-python.md index 87ebb934..8584439c 100644 --- a/.claude/skills/skill-generator/templates/script-python.md +++ b/.claude/skills/skill-generator/templates/script-python.md @@ -2,6 +2,20 @@ Python 脚本模板，用于生成技能中的确定性脚本。 +## Purpose + +为 Skill 生成 Python 脚本，用于执行确定性操作（数据处理、分析、转换等），比 Bash 提供更强的数据处理能力。 + +## Usage Context + +| Phase | Usage | +|-------|-------| +| Optional | Phase/Action 中声明 `## Scripts` 时使用 | +| Execution | 通过 `ExecuteScript('script-id', params)` 调用 | +| Output Location | `.claude/skills/{skill-name}/scripts/{script-id}.py` | + +--- + ## 模板代码 ```python diff --git a/.claude/skills/skill-generator/templates/sequential-phase.md b/.claude/skills/skill-generator/templates/sequential-phase.md index 859e8be5..e4eb0c14 100644 --- a/.claude/skills/skill-generator/templates/sequential-phase.md +++ b/.claude/skills/skill-generator/templates/sequential-phase.md @@ -2,6 +2,20 @@ 顺序模式 Phase 文件的模板。 +## Purpose + +生成 Sequential 执行模式的 Phase 文件，定义固定顺序的执行步骤。 + +## Usage Context + +| Phase | Usage | +|-------|-------| +| Phase 3 (Phase Generation) | `config.execution_mode === 'sequential'` 时生成 | +| Generation Trigger | 为每个 `config.sequential_config.phases` 生成一个 phase 文件 | +| Output Location | `.claude/skills/{skill-name}/phases/{phase-id}.md` | + +--- + ## ⚠️ 重要提示 > **Phase 0 是强制前置阶段**：在实现任何 Phase (1, 2, 3...) 之前，必须先完成 Phase 0 的规范研读。 diff --git a/.claude/skills/skill-generator/templates/skill-md.md b/.claude/skills/skill-generator/templates/skill-md.md index dc01c0fb..a76bc270 100644 --- a/.claude/skills/skill-generator/templates/skill-md.md +++ b/.claude/skills/skill-generator/templates/skill-md.md @@ -2,6 +2,20 @@ 用于生成新 Skill 入口文件的模板。 +## Purpose + +生成新 Skill 的入口文件 (SKILL.md)，作为 Skill 的主文档和执行入口点。 + +## Usage Context + +| Phase | Usage | +|-------|-------| +| Phase 2 (Structure Generation) | 创建 SKILL.md 入口文件 | +| Generation Trigger | `config.execution_mode` 决定架构图样式 | +| Output Location | `.claude/skills/{skill-name}/SKILL.md` | + +--- + ## ⚠️ 重要：YAML Front Matter 规范 > **CRITICAL**: SKILL.md 文件必须以 YAML front matter 开头，即以 `---` 作为文件第一行。 diff --git a/.claude/skills/skill-tuning/SKILL.md b/.claude/skills/skill-tuning/SKILL.md index 5f699a01..1732eaba 100644 --- a/.claude/skills/skill-tuning/SKILL.md +++ b/.claude/skills/skill-tuning/SKILL.md @@ -278,6 +278,83 @@ Bash(`mkdir -p "${workDir}/backups"`); - `issues`: 发现的问题列表 - `proposed_fixes`: 建议的修复方案 +--- + +## Action Reference Guide + +Navigation and entry points for each action in the autonomous workflow: + +### Core Orchestration + +**Document**: 🔗 [phases/orchestrator.md](phases/orchestrator.md) + +| Attribute | Value | +|-----------|-------| +| **Purpose** | Drive tuning workflow via state-driven action selection | +| **Decision Logic** | Termination checks → Action preconditions → Selection | +| **Related** | [phases/state-schema.md](phases/state-schema.md) | + +--- + +### Initialization & Requirements + +| Action | Document | Purpose | Preconditions | +|--------|----------|---------|---------------| +| **action-init** | [action-init.md](phases/actions/action-init.md) | Initialize session, backup target skill | `state.status === 'pending'` | +| **action-analyze-requirements** | [action-analyze-requirements.md](phases/actions/action-analyze-requirements.md) | Decompose user request into dimensions via Gemini CLI | After init, before diagnosis | + +--- + +### Diagnosis Actions + +| Action | Document | Purpose | Detects | +|--------|----------|---------|---------| +| **action-diagnose-context** | [action-diagnose-context.md](phases/actions/action-diagnose-context.md) | Context explosion analysis | Token accumulation, multi-turn bloat | +| **action-diagnose-memory** | [action-diagnose-memory.md](phases/actions/action-diagnose-memory.md) | Long-tail forgetting analysis | Early constraint loss | +| **action-diagnose-dataflow** | [action-diagnose-dataflow.md](phases/actions/action-diagnose-dataflow.md) | Data flow analysis | State inconsistency, format drift | +| **action-diagnose-agent** | [action-diagnose-agent.md](phases/actions/action-diagnose-agent.md) | Agent coordination analysis | Call chain failures, merge issues | +| **action-diagnose-docs** | [action-diagnose-docs.md](phases/actions/action-diagnose-docs.md) | Documentation structure analysis | Missing specs, unclear flow | +| **action-diagnose-token-consumption** | [action-diagnose-token-consumption.md](phases/actions/action-diagnose-token-consumption.md) | Token consumption analysis | Verbose prompts, redundant I/O | + +--- + +### Analysis & Reporting + +| Action | Document | Purpose | Output | +|--------|----------|---------|--------| +| **action-gemini-analysis** | [action-gemini-analysis.md](phases/actions/action-gemini-analysis.md) | Deep analysis via Gemini CLI | Custom issue diagnosis | +| **action-generate-report** | [action-generate-report.md](phases/actions/action-generate-report.md) | Consolidate diagnosis results | `state.final_report` | +| **action-propose-fixes** | [action-propose-fixes.md](phases/actions/action-propose-fixes.md) | Generate fix strategies | `state.proposed_fixes[]` | + +--- + +### Fix & Verification + +| Action | Document | Purpose | Preconditions | +|--------|----------|---------|---------------| +| **action-apply-fix** | [action-apply-fix.md](phases/actions/action-apply-fix.md) | Apply selected fix with backup | User selected fix | +| **action-verify** | [action-verify.md](phases/actions/action-verify.md) | Re-run diagnosis, check quality gates | After fix applied | + +--- + +### Termination + +| Action | Document | Purpose | Trigger | +|--------|----------|---------|---------| +| **action-complete** | [action-complete.md](phases/actions/action-complete.md) | Finalize session with report | All quality gates pass | +| **action-abort** | [action-abort.md](phases/actions/action-abort.md) | Abort session, restore backup | Error limit exceeded | + +--- + +## Template Reference + +| Template | Purpose | When Used | +|----------|---------|-----------| +| [templates/diagnosis-report.md](templates/diagnosis-report.md) | Diagnosis report structure | action-generate-report | +| [templates/fix-proposal.md](templates/fix-proposal.md) | Fix proposal format | action-propose-fixes | + +--- + ## Reference Documents | Document | Purpose | diff --git a/assets/wechat-group-qr.png b/assets/wechat-group-qr.png index ea691d82..da1fdce0 100644 Binary files a/assets/wechat-group-qr.png and b/assets/wechat-group-qr.png differ diff --git a/ccw/src/config/litellm-api-config-manager.ts b/ccw/src/config/litellm-api-config-manager.ts index 6110920c..8bdeddb4 100644 --- a/ccw/src/config/litellm-api-config-manager.ts +++ b/ccw/src/config/litellm-api-config-manager.ts @@ -281,7 +281,8 @@ export function addEndpoint( addClaudeApiEndpoint(homedir(), { id: endpoint.id, name: endpoint.id, // Use endpoint ID as tool name for CLI access - enabled: endpoint.enabled !== false + enabled: endpoint.enabled !== false, + model: endpoint.model // Sync model as primaryModel/secondaryModel }); console.log(`[LiteLLM Config] Synced endpoint ${endpoint.id} to cli-tools.json (api-endpoint)`); } catch (syncError) { @@ -320,13 +321,14 @@ export function updateEndpoint( saveConfig(baseDir, config); - // Sync enabled status to cli-tools.json + // Sync enabled status and model to cli-tools.json const updatedEndpoint = config.endpoints[endpointIndex]; try { addClaudeApiEndpoint(homedir(), { id: updatedEndpoint.id, name: updatedEndpoint.id, - enabled: updatedEndpoint.enabled !== false + enabled: updatedEndpoint.enabled !== false, + model: updatedEndpoint.model // Sync model as primaryModel/secondaryModel }); console.log(`[LiteLLM Config] Synced endpoint ${updatedEndpoint.id} update to cli-tools.json`); } catch (syncError) { diff --git a/ccw/src/core/routes/commands-routes.ts b/ccw/src/core/routes/commands-routes.ts index c2786f71..df630de9 100644 --- a/ccw/src/core/routes/commands-routes.ts +++ b/ccw/src/core/routes/commands-routes.ts @@ -7,7 +7,7 @@ * - POST /api/commands/:name/toggle - Enable/disable single command * - POST /api/commands/group/:groupName/toggle - Batch toggle commands by group */ -import { existsSync, readdirSync, readFileSync, mkdirSync, cpSync, rmSync, renameSync, statSync } from 'fs'; +import { existsSync, readdirSync, readFileSync, mkdirSync, renameSync } from 'fs'; import { join, relative, dirname, basename } from 'path'; import { homedir } from 'os'; import { validatePath as validateAllowedPath } from '../../utils/path-validator.js'; @@ -78,15 +78,6 @@ function getCommandsDir(location: CommandLocation, projectPath: string): string return join(homedir(), '.claude', 'commands'); } -/** - * Get disabled commands directory path - */ -function getDisabledCommandsDir(location: CommandLocation, projectPath: string): string { - if (location === 'project') { - return join(projectPath, '.claude', 'commands', '_disabled'); - } - return join(homedir(), '.claude', 'commands', '_disabled'); -} /** * Parse YAML frontmatter from command file @@ -221,7 +212,6 @@ function scanCommandsRecursive( baseDir: string, currentDir: string, location: CommandLocation, - enabled: boolean, projectPath: string ): CommandInfo[] { const results: CommandInfo[] = []; @@ -235,37 +225,46 @@ function scanCommandsRecursive( for (const entry of entries) { const fullPath = join(currentDir, entry.name); - const relativePath = relative(baseDir, fullPath); + let relativePath = relative(baseDir, fullPath); if (entry.isDirectory()) { - // Skip _disabled directory when scanning enabled commands - if (entry.name === '_disabled') continue; - // Recursively scan subdirectories - results.push(...scanCommandsRecursive(baseDir, fullPath, location, enabled, projectPath)); - } else if (entry.isFile() && entry.name.endsWith('.md')) { - try { - const content = readFileSync(fullPath, 'utf8'); - const metadata = parseCommandFrontmatter(content); - const commandName = metadata.name || basename(entry.name, '.md'); + results.push(...scanCommandsRecursive(baseDir, fullPath, location, projectPath)); + } else if (entry.isFile()) { + // Check for .md or .md.disabled files + const isEnabled = entry.name.endsWith('.md') && !entry.name.endsWith('.md.disabled'); + const isDisabled = entry.name.endsWith('.md.disabled'); - // Get group from external config (not from frontmatter) - const group = getCommandGroup(commandName, relativePath, location, projectPath); + if (isEnabled || isDisabled) { + try { + const content = readFileSync(fullPath, 'utf8'); + const metadata = parseCommandFrontmatter(content); - results.push({ - name: commandName, - description: metadata.description, - group, - enabled, - location, - path: fullPath, - relativePath, - argumentHint: metadata.argumentHint, - allowedTools: metadata.allowedTools - }); - } catch (err) { - // Skip files that fail to read - console.error(`[Commands] Failed to read ${fullPath}:`, err); + // For disabled files, remove .disabled from relativePath for consistency + if (isDisabled) { + relativePath = relativePath.replace(/\.disabled$/, ''); + } + + const commandName = metadata.name || basename(relativePath, '.md'); + + // Get group from external config (not from frontmatter) + const group = getCommandGroup(commandName, relativePath, location, projectPath); + + results.push({ + name: commandName, + description: metadata.description, + group, + enabled: isEnabled, + location, + path: fullPath, + relativePath, + argumentHint: metadata.argumentHint, + allowedTools: metadata.allowedTools + }); + } catch (err) { + // Skip files that fail to read + console.error(`[Commands] Failed to read ${fullPath}:`, err); + } } } } @@ -289,33 +288,13 @@ function getCommandsConfig(projectPath: string): CommandsConfig { const groupSet = new Set(); try { - // Scan project commands + // Scan project commands (includes both .md and .md.disabled) const projectDir = getCommandsDir('project', projectPath); - const projectDisabledDir = getDisabledCommandsDir('project', projectPath); + result.projectCommands = scanCommandsRecursive(projectDir, projectDir, 'project', projectPath); - // Enabled project commands - const enabledProject = scanCommandsRecursive(projectDir, projectDir, 'project', true, projectPath); - result.projectCommands.push(...enabledProject); - - // Disabled project commands - if (existsSync(projectDisabledDir)) { - const disabledProject = scanCommandsRecursive(projectDisabledDir, projectDisabledDir, 'project', false, projectPath); - result.projectCommands.push(...disabledProject); - } - - // Scan user commands + // Scan user commands (includes both .md and .md.disabled) const userDir = getCommandsDir('user', projectPath); - const userDisabledDir = getDisabledCommandsDir('user', projectPath); - - // Enabled user commands - const enabledUser = scanCommandsRecursive(userDir, userDir, 'user', true, projectPath); - result.userCommands.push(...enabledUser); - - // Disabled user commands - if (existsSync(userDisabledDir)) { - const disabledUser = scanCommandsRecursive(userDisabledDir, userDisabledDir, 'user', false, projectPath); - result.userCommands.push(...disabledUser); - } + result.userCommands = scanCommandsRecursive(userDir, userDir, 'user', projectPath); // Collect all groups for (const cmd of [...result.projectCommands, ...result.userCommands]) { @@ -330,40 +309,6 @@ function getCommandsConfig(projectPath: string): CommandsConfig { return result; } -/** - * Move directory with fallback to copy-delete and rollback on failure - */ -function moveDirectory(source: string, target: string): void { - try { - // Ensure target parent directory exists - const targetParent = dirname(target); - if (!existsSync(targetParent)) { - mkdirSync(targetParent, { recursive: true }); - } - - // Try atomic rename first - renameSync(source, target); - } catch (error: unknown) { - const err = error as NodeJS.ErrnoException; - // If rename fails (cross-filesystem, permission issues), fallback to copy-delete - if (err.code === 'EXDEV' || err.code === 'EPERM' || err.code === 'EBUSY') { - cpSync(source, target, { recursive: true, force: true }); - try { - rmSync(source, { recursive: true, force: true }); - } catch (rmError) { - // Rollback: remove the copied target to avoid duplicates - try { - rmSync(target, { recursive: true, force: true }); - } catch { - // Ignore rollback errors - } - throw new Error(`Failed to remove source after copy: ${(rmError as Error).message}`); - } - } else { - throw error; - } - } -} /** * Find command by name in commands list @@ -416,47 +361,48 @@ async function toggleCommand( } const commandsDir = getCommandsDir(location, projectPath); - const disabledDir = getDisabledCommandsDir(location, projectPath); + // relativePath already includes .md extension (e.g., 'workflow/plan.md') + const commandPath = join(commandsDir, command.relativePath); + const disabledPath = commandPath + '.disabled'; if (command.enabled) { - // Disable: move from commands to _disabled - const targetPath = join(disabledDir, command.relativePath); - - // Check if target already exists - if (existsSync(targetPath)) { - return { success: false, message: 'Command already exists in disabled directory', status: 409 }; + // Disable: rename .md to .md.disabled + if (!existsSync(commandPath)) { + return { success: false, message: 'Command file not found', status: 404 }; + } + if (existsSync(disabledPath)) { + return { success: false, message: 'Command already disabled', status: 409 }; } - moveDirectory(command.path, targetPath); - return { - success: true, - message: 'Command disabled', - commandName: command.name, - location + renameSync(commandPath, disabledPath); + return { + success: true, + message: 'Command disabled', + commandName: command.name, + location }; } else { - // Enable: move from _disabled back to commands - // Calculate target path in enabled directory - const targetPath = join(commandsDir, command.relativePath); - - // Check if target already exists - if (existsSync(targetPath)) { - return { success: false, message: 'Command already exists in commands directory', status: 409 }; + // Enable: rename .md.disabled back to .md + if (!existsSync(disabledPath)) { + return { success: false, message: 'Disabled command not found', status: 404 }; + } + if (existsSync(commandPath)) { + return { success: false, message: 'Command already enabled', status: 409 }; } - moveDirectory(command.path, targetPath); - return { - success: true, - message: 'Command enabled', - commandName: command.name, - location + renameSync(disabledPath, commandPath); + return { + success: true, + message: 'Command enabled', + commandName: command.name, + location }; } } catch (error) { - return { - success: false, - message: (error as Error).message, - status: 500 + return { + success: false, + message: (error as Error).message, + status: 500 }; } } diff --git a/ccw/src/templates/dashboard-js/i18n.js b/ccw/src/templates/dashboard-js/i18n.js index 4b0a7ddc..b1768878 100644 --- a/ccw/src/templates/dashboard-js/i18n.js +++ b/ccw/src/templates/dashboard-js/i18n.js @@ -1631,6 +1631,12 @@ const i18n = { 'commands.group.task': 'Task', 'commands.group.issue': 'Issue', 'commands.group.other': 'Other', + 'commands.group.review': 'Review', + 'commands.group.execute': 'Execute', + 'commands.group.plan': 'Plan', + 'commands.group.test': 'Test', + 'commands.group.debug': 'Debug', + 'commands.group.tools': 'Tools', 'commands.enableAll': 'Enable All', 'commands.disableAll': 'Disable All', 'commands.enableGroupConfirm': 'Enable all commands in "{group}" group?', @@ -4307,6 +4313,12 @@ const i18n = { 'commands.group.task': '任务', 'commands.group.issue': '问题', 'commands.group.other': '其他', + 'commands.group.review': '审查', + 'commands.group.execute': '执行', + 'commands.group.plan': '规划', + 'commands.group.test': '测试', + 'commands.group.debug': '调试', + 'commands.group.tools': '工具', 'commands.enableAll': '全部启用', 'commands.disableAll': '全部禁用', 'commands.enableGroupConfirm': '启用 "{group}" 分组中的所有命令？', diff --git a/ccw/src/templates/dashboard-js/views/commands-manager.js b/ccw/src/templates/dashboard-js/views/commands-manager.js index 611b5020..066e99b7 100644 --- a/ccw/src/templates/dashboard-js/views/commands-manager.js +++ b/ccw/src/templates/dashboard-js/views/commands-manager.js @@ -205,6 +205,50 @@ function renderCommandsView() { if (typeof lucide !== 'undefined') lucide.createIcons(); } +// Format group name for display (e.g., 'workflow/review' -> 'Workflow > Review') +function formatGroupName(groupName) { + if (!groupName.includes('/')) { + return t('commands.group.' + groupName) || groupName; + } + + // Split path and translate each part + const parts = groupName.split('/'); + const translatedParts = parts.map(part => t('commands.group.' + part) || part); + return translatedParts.join(' › '); +} + +// Get icon for a group (use top-level parent's icon for nested groups) +function getGroupIcon(groupName) { + const groupIcons = { + cli: 'terminal', + workflow: 'git-branch', + memory: 'brain', + task: 'clipboard-list', + issue: 'alert-circle', + other: 'folder' + }; + + // For nested groups, use the top-level parent's icon + const topLevel = groupName.split('/')[0]; + return groupIcons[topLevel] || 'folder'; +} + +// Get color for a group (use top-level parent's color for nested groups) +function getGroupColor(groupName) { + const groupColors = { + cli: 'text-primary bg-primary/10', + workflow: 'text-success bg-success/10', + memory: 'text-indigo bg-indigo/10', + task: 'text-warning bg-warning/10', + issue: 'text-destructive bg-destructive/10', + other: 'text-muted-foreground bg-muted' + }; + + // For nested groups, use the top-level parent's color + const topLevel = groupName.split('/')[0]; + return groupColors[topLevel] || 'text-muted-foreground bg-muted'; +} + function renderAccordionGroup(groupName, commands) { // Default to expanded for new/custom groups if (expandedGroups[groupName] === undefined) expandedGroups[groupName] = true; @@ -217,31 +261,14 @@ function renderAccordionGroup(groupName, commands) { ? commands : enabledCommands; - // Group icons - const groupIcons = { - cli: 'terminal', - workflow: 'workflow', - memory: 'brain', - task: 'clipboard-list', - issue: 'alert-circle', - other: 'folder' - }; - - // Group colors - const groupColors = { - cli: 'text-primary bg-primary/10', - workflow: 'text-success bg-success/10', - memory: 'text-indigo bg-indigo/10', - task: 'text-warning bg-warning/10', - issue: 'text-destructive bg-destructive/10', - other: 'text-muted-foreground bg-muted' - }; - - const icon = groupIcons[groupName] || 'folder'; - const colorClass = groupColors[groupName] || 'text-muted-foreground bg-muted'; + const icon = getGroupIcon(groupName); + const colorClass = getGroupColor(groupName); + const displayName = formatGroupName(groupName); + const indentLevel = (groupName.match(/\//g) || []).length; + const indentStyle = indentLevel > 0 ? `style="margin-left: ${indentLevel * 20}px;"` : ''; return ` -
+
@@ -250,7 +277,7 @@ function renderAccordionGroup(groupName, commands) {
-

${t('commands.group.' + groupName) || groupName}

+

${displayName}

${enabledCommands.length}/${commands.length} ${t('commands.enabled') || 'enabled'}

diff --git a/ccw/src/tools/claude-cli-tools.ts b/ccw/src/tools/claude-cli-tools.ts index 7e1fa798..a962569c 100644 --- a/ccw/src/tools/claude-cli-tools.ts +++ b/ccw/src/tools/claude-cli-tools.ts @@ -802,13 +802,15 @@ export function getNativeResume(projectDir: string): boolean { */ export function addClaudeApiEndpoint( projectDir: string, - endpoint: { id: string; name: string; enabled: boolean } + endpoint: { id: string; name: string; enabled: boolean; model?: string } ): ClaudeCliToolsConfig { const config = loadClaudeCliTools(projectDir); // Add as a tool with type: 'api-endpoint' config.tools[endpoint.name] = { enabled: endpoint.enabled, + primaryModel: endpoint.model, // Use endpoint.model as primaryModel (can be overridden via --model) + secondaryModel: endpoint.model, // Same as primary for fallback tags: [], type: 'api-endpoint', id: endpoint.id // Store endpoint ID for settings lookup diff --git a/ccw/src/tools/cli-executor-core.ts b/ccw/src/tools/cli-executor-core.ts index 04ca5299..458aa98b 100644 --- a/ccw/src/tools/cli-executor-core.ts +++ b/ccw/src/tools/cli-executor-core.ts @@ -557,6 +557,11 @@ async function executeCliTool( // id field is the LiteLLM endpoint ID (e.g., "g25") const litellmEndpointId = toolConfig.id || toolName; + // Use configured primary model if no explicit model provided + // This allows --model parameter to override the tool's primaryModel + // Use undefined if primaryModel is empty string (endpoint.model will be used as fallback) + const apiEndpointEffectiveModel = model || (toolConfig.primaryModel || undefined); + // Find LiteLLM endpoint configuration const litellmEndpoint = findEndpointById(workingDir, litellmEndpointId); if (litellmEndpoint) { @@ -568,13 +573,14 @@ async function executeCliTool( }); } - // Execute via LiteLLM + // Execute via LiteLLM with model override const result = await executeLiteLLMEndpoint({ prompt, endpointId: litellmEndpointId, baseDir: workingDir, cwd: cd || workingDir, includeDirs: includeDirs ? includeDirs.split(',').map(d => d.trim()) : undefined, + model: apiEndpointEffectiveModel, // Pass effective model (--model or primaryModel) onOutput: onOutput || undefined, }); @@ -587,7 +593,7 @@ async function executeCliTool( id: customId || `${Date.now()}-litellm`, timestamp: new Date(startTime).toISOString(), tool: toolName, - model: litellmEndpoint.model, + model: result.model, // Use effective model from result (reflects any override) mode, prompt, status: result.success ? 'success' : 'error', diff --git a/ccw/src/tools/litellm-executor.ts b/ccw/src/tools/litellm-executor.ts index 2380f6a8..31ee251d 100644 --- a/ccw/src/tools/litellm-executor.ts +++ b/ccw/src/tools/litellm-executor.ts @@ -19,6 +19,7 @@ export interface LiteLLMExecutionOptions { cwd?: string; // Working directory for file resolution includeDirs?: string[]; // Additional directories for @patterns enableCache?: boolean; // Override endpoint cache setting + model?: string; // Override model for this execution (if not specified, uses endpoint.model) onOutput?: (unit: CliOutputUnit) => void; /** Number of retries after the initial attempt (default: 0) */ maxRetries?: number; @@ -56,7 +57,7 @@ export function extractPatterns(prompt: string): string[] { export async function executeLiteLLMEndpoint( options: LiteLLMExecutionOptions ): Promise { - const { prompt, endpointId, baseDir, cwd, includeDirs, enableCache, onOutput } = options; + const { prompt, endpointId, baseDir, cwd, includeDirs, enableCache, model: modelOverride, onOutput } = options; // 1. Find endpoint configuration const endpoint = findEndpointById(baseDir, endpointId); @@ -96,7 +97,10 @@ export async function executeLiteLLMEndpoint( }; } - // 3. Process context cache if enabled + // 3. Determine effective model: use override if provided, otherwise use endpoint.model + const effectiveModel = modelOverride || endpoint.model; + + // 4. Process context cache if enabled let finalPrompt = prompt; let cacheUsed = false; let cachedFiles: string[] = []; @@ -168,12 +172,12 @@ export async function executeLiteLLMEndpoint( } } - // 4. Call LiteLLM + // 5. Call LiteLLM try { if (onOutput) { onOutput({ type: 'stderr', - content: `[LiteLLM: Calling ${provider.type}/${endpoint.model}]\n`, + content: `[LiteLLM: Calling ${provider.type}/${effectiveModel}]\n`, timestamp: new Date().toISOString() }); } @@ -206,14 +210,14 @@ export async function executeLiteLLMEndpoint( delete process.env['CCW_LITELLM_EXTRA_HEADERS']; } - // Use litellm-client to call chat + // Use litellm-client to call chat with effective model const response = await callWithRetries( - () => client.chat(finalPrompt, endpoint.model), + () => client.chat(finalPrompt, effectiveModel), { maxRetries: options.maxRetries ?? 0, baseDelayMs: options.retryBaseDelayMs ?? 1000, onOutput, - rateLimitKey: `${provider.type}:${endpoint.model}`, + rateLimitKey: `${provider.type}:${effectiveModel}`, }, ); @@ -228,7 +232,7 @@ export async function executeLiteLLMEndpoint( return { success: true, output: response, - model: endpoint.model, + model: effectiveModel, provider: provider.type, cacheUsed, cachedFiles, @@ -246,7 +250,7 @@ export async function executeLiteLLMEndpoint( return { success: false, output: '', - model: endpoint.model, + model: effectiveModel, provider: provider.type, cacheUsed, error: errorMsg,