claude-code-workflow 6.2.1 → 6.2.3

package/.claude/workflows/coding-philosophy.md

@@ -0,0 +1,70 @@
+# Coding Philosophy
+
+## Core Beliefs
+
+- **Pursue good taste** - Eliminate edge cases to make code logic natural and elegant
+- **Embrace extreme simplicity** - Complexity is the root of all evil
+- **Be pragmatic** - Code must solve real-world problems, not hypothetical ones
+- **Data structures first** - Bad programmers worry about code; good programmers worry about data structures
+- **Never break backward compatibility** - Existing functionality is sacred and inviolable
+- **Incremental progress over big bangs** - Small changes that compile and pass tests
+- **Learning from existing code** - Study and plan before implementing
+- **Clear intent over clever code** - Be boring and obvious
+- **Follow existing code style** - Match import patterns, naming conventions, and formatting of existing codebase
+- **Minimize changes** - Only modify what's directly required; avoid refactoring, adding features, or "improving" code beyond the request
+- **No unsolicited documentation** - NEVER generate reports, documentation files, or summaries without explicit user request. If required, save to .workflow/.scratchpad/
+
+## Simplicity Means
+
+- Single responsibility per function/class
+- Avoid premature abstractions
+- No clever tricks - choose the boring solution
+- If you need to explain it, it's too complex
+
+## Fix, Don't Hide
+
+**Solve problems, don't silence symptoms** - Skipped tests, `@ts-ignore`, empty catch, `as any`, excessive timeouts = hiding bugs, not fixing them
+
+**NEVER**:
+- Make assumptions - verify with existing code
+- Generate reports, summaries, or documentation files without explicit user request
+- Use suppression mechanisms (`skip`, `ignore`, `disable`) without fixing root cause
+
+**ALWAYS**:
+- Plan complex tasks thoroughly before implementation
+- Generate task decomposition for multi-module work (>3 modules or >5 subtasks)
+- Track progress using TODO checklists for complex tasks
+- Validate planning documents before starting development
+- Commit working code incrementally
+- Update plan documentation and progress tracking as you go
+- Learn from existing implementations
+- Stop after 3 failed attempts and reassess
+- **Edit fallback**: When Edit tool fails 2+ times on same file, try Bash sed/awk first, then Write to recreate if still failing
+
+## Learning the Codebase
+
+- Find 3 similar features/components
+- Identify common patterns and conventions
+- Use same libraries/utilities when possible
+- Follow existing test patterns
+
+## Tooling
+
+- Use project's existing build system
+- Use project's test framework
+- Use project's formatter/linter settings
+- Don't introduce new tools without strong justification
+
+## Content Uniqueness Rules
+
+- **Each layer owns its abstraction level** - no content sharing between layers
+- **Reference, don't duplicate** - point to other layers, never copy content
+- **Maintain perspective** - each layer sees the system at its appropriate scale
+- **Avoid implementation creep** - higher layers stay architectural
+
+# Context Requirements
+
+Before implementation, always:
+- Identify 3+ existing similar patterns
+- Map dependencies and integration points
+- Understand testing framework and coding conventions

package/.claude/workflows/context-tools.md

@@ -0,0 +1,84 @@
+## MCP Tools Usage
+
+### smart_search - Code Search (REQUIRED - HIGHEST PRIORITY)
+
+**OVERRIDES**: All other search/discovery rules in other workflow files
+
+**When**: ANY code discovery task, including:
+- Find code, understand codebase structure, locate implementations
+- Explore unknown locations
+- Verify file existence before reading
+- Pattern-based file discovery
+
+**Priority Rule**:
+1. **Always use smart_search FIRST** for any code/file discovery
+2. Only use Built-in Grep for single-file exact line search (after location confirmed)
+3. Only use Built-in Read for known, confirmed file paths
+
+**Workflow** (search first, init if needed):
+```javascript
+// Step 1: Try search directly (works if index exists or uses ripgrep fallback)
+smart_search(query="authentication logic")
+
+// Step 2: Only if search warns "No CodexLens index found", then init
+smart_search(action="init", path=".")   // Creates FTS index only
+
+// Note: For semantic/vector search, use "ccw view" dashboard to create vector index
+```
+
+**Modes**: `auto` (intelligent routing), `hybrid` (semantic, needs vector index), `exact` (FTS), `ripgrep` (no index)
+
+---
+
+### read_file - Read File Contents
+
+**When**: Read files found by smart_search
+
+**How**:
+```javascript
+read_file(path="/path/to/file.ts")                   // Single file
+read_file(path="/src/**/*.config.ts")                // Pattern matching
+```
+
+---
+
+### edit_file - Modify Files
+
+**When**: Built-in Edit tool fails or need advanced features
+
+**How**:
+```javascript
+edit_file(path="/file.ts", old_string="...", new_string="...", mode="update")
+edit_file(path="/file.ts", line=10, content="...", mode="insert_after")
+```
+
+**Modes**: `update` (replace text), `insert_after`, `insert_before`, `delete_line`
+
+---
+
+### write_file - Create/Overwrite Files
+
+**When**: Create new files or completely replace content
+
+**How**:
+```javascript
+write_file(path="/new-file.ts", content="...")
+```
+
+---
+
+### Exa - External Search
+
+**When**: Find documentation/examples outside codebase
+
+**How**:
+```javascript
+mcp__exa__search(query="React hooks 2025 documentation")
+mcp__exa__search(query="FastAPI auth example", numResults=10)
+mcp__exa__search(query="latest API docs", livecrawl="always")
+```
+
+**Parameters**:
+- `query` (required): Search query string
+- `numResults` (optional): Number of results to return (default: 5)
+- `livecrawl` (optional): `"always"` or `"fallback"` for live crawling

package/.claude/workflows/file-modification.md

@@ -0,0 +1,64 @@
+# File Modification
+
+Before modifying files, always:
+- Try built-in Edit tool first
+- Escalate to MCP tools when built-ins fail
+- Use write_file only as last resort
+
+## MCP Tools Usage
+
+### edit_file - Modify Files
+
+**When**: Built-in Edit fails, need dry-run preview, or need line-based operations
+
+**How**:
+```javascript
+edit_file(path="/file.ts", oldText="old", newText="new")              // Replace text
+edit_file(path="/file.ts", oldText="old", newText="new", dryRun=true) // Preview diff
+edit_file(path="/file.ts", oldText="old", newText="new", replaceAll=true) // Replace all
+edit_file(path="/file.ts", mode="line", operation="insert_after", line=10, text="new line")
+edit_file(path="/file.ts", mode="line", operation="delete", line=5, end_line=8)
+```
+
+**Modes**: `update` (replace text, default), `line` (line-based operations)
+
+**Operations** (line mode): `insert_before`, `insert_after`, `replace`, `delete`
+
+---
+
+### write_file - Create/Overwrite Files
+
+**When**: Create new files, completely replace content, or edit_file still fails
+
+**How**:
+```javascript
+write_file(path="/new-file.ts", content="file content here")
+write_file(path="/existing.ts", content="...", backup=true)  // Create backup first
+```
+
+---
+
+## Priority Logic
+
+> **Note**: Search priority is defined in `context-tools.md` - smart_search has HIGHEST PRIORITY for all discovery tasks.
+
+**Search & Discovery** (defer to context-tools.md):
+1. **smart_search FIRST** for any code/file discovery
+2. Built-in Grep only for single-file exact line search (location already confirmed)
+3. Exa for external/public knowledge
+
+**File Reading**:
+1. Unknown location → **smart_search first**, then Read
+2. Known confirmed file → Built-in Read directly
+3. Pattern matching → smart_search (action="find_files")
+
+**File Editing**:
+1. Always try built-in Edit first
+2. Fails 1+ times → edit_file (MCP)
+3. Still fails → write_file (MCP)
+
+## Decision Triggers
+
+**Search tasks** → Always start with smart_search (per context-tools.md)
+**Known file edits** → Start with built-in Edit, escalate to MCP if fails
+**External knowledge** → Use Exa

package/.claude/workflows/review-directory-specification.md

@@ -0,0 +1,336 @@
+# Review Directory Specification
+
+## Overview
+
+Unified directory structure for all review commands (session-based and module-based) within workflow sessions.
+
+## Core Principles
+
+1. **Session-Based**: All reviews run within a workflow session context
+2. **Unified Structure**: Same directory layout for all review types
+3. **Type Differentiation**: Review type indicated by metadata, not directory structure
+4. **Progressive Creation**: Directories created on-demand during review execution
+5. **Archive Support**: Reviews archived with their parent session
+
+## Directory Structure
+
+### Base Location
+```
+.workflow/active/WFS-{session-id}/.review/
+```
+
+### Complete Structure
+```
+.workflow/active/WFS-{session-id}/.review/
+├── review-state.json              # Review orchestrator state machine
+├── review-progress.json           # Real-time progress for dashboard polling
+├── review-metadata.json           # Review configuration and scope
+├── dimensions/                    # Per-dimension analysis results
+│   ├── security.json
+│   ├── architecture.json
+│   ├── quality.json
+│   ├── action-items.json
+│   ├── performance.json
+│   ├── maintainability.json
+│   └── best-practices.json
+├── iterations/                    # Deep-dive iteration results
+│   ├── iteration-1-finding-{uuid}.json
+│   ├── iteration-2-finding-{uuid}.json
+│   └── ...
+├── reports/                       # Human-readable reports
+│   ├── security-analysis.md
+│   ├── security-cli-output.txt
+│   ├── architecture-analysis.md
+│   ├── architecture-cli-output.txt
+│   ├── ...
+│   ├── deep-dive-1-{uuid}.md
+│   └── deep-dive-2-{uuid}.md
+├── REVIEW-SUMMARY.md              # Final consolidated summary
+└── dashboard.html                 # Interactive review dashboard
+```
+
+## Review Metadata Schema
+
+**File**: `review-metadata.json`
+
+```json
+{
+  "review_id": "review-20250125-143022",
+  "review_type": "module|session",
+  "session_id": "WFS-auth-system",
+  "created_at": "2025-01-25T14:30:22Z",
+  "scope": {
+    "type": "module|session",
+    "module_scope": {
+      "target_pattern": "src/auth/**",
+      "resolved_files": [
+        "src/auth/service.ts",
+        "src/auth/validator.ts"
+      ],
+      "file_count": 2
+    },
+    "session_scope": {
+      "commit_range": "abc123..def456",
+      "changed_files": [
+        "src/auth/service.ts",
+        "src/payment/processor.ts"
+      ],
+      "file_count": 2
+    }
+  },
+  "dimensions": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
+  "max_iterations": 3,
+  "cli_tools": {
+    "primary": "gemini",
+    "fallback": ["qwen", "codex"]
+  }
+}
+```
+
+## Review State Schema
+
+**File**: `review-state.json`
+
+```json
+{
+  "review_id": "review-20250125-143022",
+  "phase": "init|parallel|aggregate|iterate|complete",
+  "current_iteration": 1,
+  "dimensions_status": {
+    "security": "pending|in_progress|completed|failed",
+    "architecture": "completed",
+    "quality": "in_progress",
+    "action-items": "pending",
+    "performance": "pending",
+    "maintainability": "pending",
+    "best-practices": "pending"
+  },
+  "severity_distribution": {
+    "critical": 2,
+    "high": 5,
+    "medium": 12,
+    "low": 8
+  },
+  "critical_files": [
+    "src/auth/service.ts",
+    "src/payment/processor.ts"
+  ],
+  "iterations": [
+    {
+      "iteration": 1,
+      "findings_selected": ["uuid-1", "uuid-2", "uuid-3"],
+      "completed_at": "2025-01-25T15:30:00Z"
+    }
+  ],
+  "completion_criteria": {
+    "critical_count": 0,
+    "high_count_threshold": 5,
+    "max_iterations": 3
+  },
+  "next_action": "execute_parallel_reviews|aggregate_findings|execute_deep_dive|generate_final_report|complete"
+}
+```
+
+## Session Integration
+
+### Session Discovery
+
+**review-session-cycle** (auto-discover):
+```bash
+# Auto-detect active session
+/workflow:review-session-cycle
+
+# Or specify session explicitly
+/workflow:review-session-cycle WFS-auth-system
+```
+
+**review-module-cycle** (require session):
+```bash
+# Must have active session or specify one
+/workflow:review-module-cycle src/auth/** --session WFS-auth-system
+
+# Or use active session
+/workflow:review-module-cycle src/auth/**
+```
+
+### Session Creation Logic
+
+**For review-module-cycle**:
+
+1. **Check Active Session**: Search `.workflow/active/WFS-*`
+2. **If Found**: Use active session's `.review/` directory
+3. **If Not Found**:
+   - **Option A** (Recommended): Prompt user to create session first
+   - **Option B**: Auto-create review-only session: `WFS-review-{pattern-hash}`
+
+**Recommended Flow**:
+```bash
+# Step 1: Start session
+/workflow:session:start --new "Review auth module"
+# Creates: .workflow/active/WFS-review-auth-module/
+
+# Step 2: Run review
+/workflow:review-module-cycle src/auth/**
+# Creates: .workflow/active/WFS-review-auth-module/.review/
+```
+
+## Command Phase 1 Requirements
+
+### Both Commands Must:
+
+1. **Session Discovery**:
+   ```javascript
+   // Check for active session
+   const sessions = Glob('.workflow/active/WFS-*');
+   if (sessions.length === 0) {
+     // Prompt user to create session first
+     error("No active session found. Please run /workflow:session:start first");
+   }
+   const sessionId = sessions[0].match(/WFS-[^/]+/)[0];
+   ```
+
+2. **Create .review/ Structure**:
+   ```javascript
+   const reviewDir = `.workflow/active/${sessionId}/.review/`;
+
+   // Create directory structure
+   Bash(`mkdir -p ${reviewDir}/dimensions`);
+   Bash(`mkdir -p ${reviewDir}/iterations`);
+   Bash(`mkdir -p ${reviewDir}/reports`);
+   ```
+
+3. **Initialize Metadata**:
+   ```javascript
+   // Write review-metadata.json
+   Write(`${reviewDir}/review-metadata.json`, JSON.stringify({
+     review_id: `review-${timestamp}`,
+     review_type: "module|session",
+     session_id: sessionId,
+     created_at: new Date().toISOString(),
+     scope: {...},
+     dimensions: [...],
+     max_iterations: 3,
+     cli_tools: {...}
+   }));
+
+   // Write review-state.json
+   Write(`${reviewDir}/review-state.json`, JSON.stringify({
+     review_id: `review-${timestamp}`,
+     phase: "init",
+     current_iteration: 0,
+     dimensions_status: {},
+     severity_distribution: {},
+     critical_files: [],
+     iterations: [],
+     completion_criteria: {},
+     next_action: "execute_parallel_reviews"
+   }));
+   ```
+
+4. **Generate Dashboard**:
+   ```javascript
+   const template = Read('~/.claude/templates/review-cycle-dashboard.html');
+   const dashboard = template
+     .replace('{{SESSION_ID}}', sessionId)
+     .replace('{{REVIEW_TYPE}}', reviewType)
+     .replace('{{REVIEW_DIR}}', reviewDir);
+   Write(`${reviewDir}/dashboard.html`, dashboard);
+
+   // Output to user
+   console.log(`📊 Review Dashboard: file://${absolutePath(reviewDir)}/dashboard.html`);
+   console.log(`📂 Review Output: ${reviewDir}`);
+   ```
+
+## Archive Strategy
+
+### On Session Completion
+
+When `/workflow:session:complete` is called:
+
+1. **Preserve Review Directory**:
+   ```javascript
+   // Move entire session including .review/
+   Bash(`mv .workflow/active/${sessionId} .workflow/archives/${sessionId}`);
+   ```
+
+2. **Review Archive Structure**:
+   ```
+   .workflow/archives/WFS-auth-system/
+   ├── workflow-session.json
+   ├── IMPL_PLAN.md
+   ├── TODO_LIST.md
+   ├── .task/
+   ├── .summaries/
+   └── .review/                    # Review results preserved
+       ├── review-metadata.json
+       ├── REVIEW-SUMMARY.md
+       └── dashboard.html
+   ```
+
+3. **Access Archived Reviews**:
+   ```bash
+   # Open archived dashboard
+   start .workflow/archives/WFS-auth-system/.review/dashboard.html
+   ```
+
+## Benefits
+
+### 1. Unified Structure
+- Same directory layout for all review types
+- Consistent file naming and schemas
+- Easier maintenance and tooling
+
+### 2. Session Integration
+- Review history tracked with implementation
+- Easy correlation between code changes and reviews
+- Simplified archiving and retrieval
+
+### 3. Progressive Creation
+- Directories created only when needed
+- No upfront overhead
+- Clean session initialization
+
+### 4. Type Flexibility
+- Module-based and session-based reviews in same structure
+- Type indicated by metadata, not directory layout
+- Easy to add new review types
+
+### 5. Dashboard Consistency
+- Same dashboard template for both types
+- Unified progress tracking
+- Consistent user experience
+
+## Migration Path
+
+### For Existing Commands
+
+**review-session-cycle**:
+1. Change output from `.workflow/.reviews/session-{id}/` to `.workflow/active/{session-id}/.review/`
+2. Update Phase 1 to use session discovery
+3. Add review-metadata.json creation
+
+**review-module-cycle**:
+1. Add session requirement (or auto-create)
+2. Change output from `.workflow/.reviews/module-{hash}/` to `.workflow/active/{session-id}/.review/`
+3. Update Phase 1 to use session discovery
+4. Add review-metadata.json creation
+
+### Backward Compatibility
+
+**For existing standalone reviews** in `.workflow/.reviews/`:
+- Keep for reference
+- Document migration in README
+- Provide migration script if needed
+
+## Implementation Checklist
+
+- [ ] Update workflow-architecture.md with .review/ structure
+- [ ] Update review-session-cycle.md command specification
+- [ ] Update review-module-cycle.md command specification
+- [ ] Update review-cycle-dashboard.html template
+- [ ] Create review-metadata.json schema validation
+- [ ] Update /workflow:session:complete to preserve .review/
+- [ ] Update documentation examples
+- [ ] Test both review types with new structure
+- [ ] Validate dashboard compatibility
+- [ ] Document migration path for existing reviews