claude-code-workflow 6.2.3 → 6.2.5

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

@@ -1,70 +0,0 @@
-# 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

@@ -1,84 +0,0 @@
-## 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

@@ -1,64 +0,0 @@
-# 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

@@ -1,336 +0,0 @@
-# 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