claude-code-workflow 6.1.4 → 6.2.2

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/tool-strategy.md

@@ -1,79 +1,216 @@
-# Tool Strategy
-
-## ⚡ Exa Triggering Mechanisms
-
-**Auto-Trigger**:
-- User mentions "exa-code" or code-related queries → `mcp__exa__get_code_context_exa`
-- Need current web information → `mcp__exa__web_search_exa`
-
-**Manual Trigger**:
-- Complex API research → Exa Code Context
-- Real-time information needs → Exa Web Search
-
-## ⚡ CCW edit_file Tool (AI-Powered Editing)
-
-**When to Use**: Edit tool fails 1+ times on same file
-
-### Usage
-
-**Best for**: Code block replacements, function rewrites, multi-line changes
-
-```bash
-ccw tool exec edit_file --path "file.py" --old "def old():
-    pass" --new "def new():
-    return True"
-```
-
-**Parameters**:
-- `--path`: File path to edit
-- `--old`: Text to find and replace
-- `--new`: New text to insert
-
-**Features**:
-- ✅ Exact text matching (precise and predictable)
-- ✅ Auto line ending adaptation (CRLF/LF)
-- ✅ No JSON escaping issues
-- ✅ Multi-line text supported with quotes
-
-### Fallback Strategy
-
-1. **Edit fails 1+ times** → Use `ccw tool exec edit_file`
-2. **Still fails** → Use Write to recreate file
-
-## ⚡ sed Line Operations (Line Mode Alternative)
-
-**When to Use**: Precise line number control (insert, delete, replace specific lines)
-
-### Common Operations
-
-```bash
-# Insert after line 10
-sed -i '10a\new line content' file.txt
-
-# Insert before line 5
-sed -i '5i\new line content' file.txt
-
-# Delete line 3
-sed -i '3d' file.txt
-
-# Delete lines 5-8
-sed -i '5,8d' file.txt
-
-# Replace line 3 content
-sed -i '3c\replacement line' file.txt
-
-# Replace lines 3-5 content
-sed -i '3,5c\single replacement line' file.txt
-```
-
-### Operation Reference
-
-| Operation | Command | Example |
-|-----------|---------|---------|
-| Insert after | `Na\text` | `sed -i '10a\new' file` |
-| Insert before | `Ni\text` | `sed -i '5i\new' file` |
-| Delete line | `Nd` | `sed -i '3d' file` |
-| Delete range | `N,Md` | `sed -i '5,8d' file` |
-| Replace line | `Nc\text` | `sed -i '3c\new' file` |
-
-**Note**: Use `sed -i` for in-place file modification (works in Git Bash on Windows)
+# Tool Strategy - When to Use What
+
+> **Focus**: Decision triggers and selection logic, NOT syntax (already registered with Claude)
+
+## Quick Decision Tree
+
+```
+Need context?
+├─ Exa available? → Use Exa (fastest, most comprehensive)
+├─ Large codebase (>500 files)? → codex_lens
+├─ Known files (<5)? → Read tool
+└─ Unknown files? → smart_search → Read tool
+
+Need to modify files?
+├─ Built-in Edit fails? → mcp__ccw-tools__edit_file
+└─ Still fails? → mcp__ccw-tools__write_file
+
+Need to search?
+├─ Semantic/concept search? → smart_search (mode=semantic)
+├─ Exact pattern match? → Grep tool
+└─ Multiple search modes needed? → smart_search (mode=auto)
+```
+
+---
+
+## 1. Context Gathering Tools
+
+### Exa (`mcp__exa__get_code_context_exa`)
+
+**Use When**:
+- ✅ Researching external APIs, libraries, frameworks
+- ✅ Need recent documentation (post-cutoff knowledge)
+- ✅ Looking for implementation examples in public repos
+- ✅ Comparing architectural patterns across projects
+
+**Don't Use When**:
+- ❌ Searching internal codebase (use smart_search/codex_lens)
+- ❌ Files already in working directory (use Read)
+
+**Trigger Indicators**:
+- User mentions specific library/framework names
+- Questions about "best practices", "how does X work"
+- Need to verify current API signatures
+
+---
+
+### read_file (`mcp__ccw-tools__read_file`)
+
+**Use When**:
+- ✅ Reading multiple related files at once (batch reading)
+- ✅ Need directory traversal with pattern matching
+- ✅ Searching file content with regex (`contentPattern`)
+- ✅ Want to limit depth/file count for large directories
+
+**Don't Use When**:
+- ❌ Single file read → Use built-in Read tool (faster)
+- ❌ Unknown file locations → Use smart_search first
+- ❌ Need semantic search → Use smart_search or codex_lens
+
+**Trigger Indicators**:
+- Need to read "all TypeScript files in src/"
+- Need to find "files containing TODO comments"
+- Want to read "up to 20 config files"
+
+**Advantages over Built-in Read**:
+- Batch operation (multiple files in one call)
+- Pattern-based filtering (glob + content regex)
+- Directory traversal with depth control
+
+---
+
+### codex_lens (`mcp__ccw-tools__codex_lens`)
+
+**Use When**:
+- ✅ Large codebase (>500 files) requiring repeated searches
+- ✅ Need semantic understanding of code relationships
+- ✅ Working across multiple sessions (persistent index)
+- ✅ Symbol-level navigation needed
+
+**Don't Use When**:
+- ❌ Small project (<100 files) → Use smart_search (no indexing overhead)
+- ❌ One-time search → Use smart_search or Grep
+- ❌ Files change frequently → Indexing overhead not worth it
+
+**Trigger Indicators**:
+- "Find all implementations of interface X"
+- "What calls this function across the codebase?"
+- Multi-session workflow on same codebase
+
+**Action Selection**:
+- `init`: First time in new codebase
+- `search`: Find code patterns
+- `search_files`: Find files by path/name pattern
+- `symbol`: Get symbols in specific file
+- `status`: Check if index exists/is stale
+- `clean`: Remove stale index
+
+---
+
+### smart_search (`mcp__ccw-tools__smart_search`)
+
+**Use When**:
+- ✅ Don't know exact file locations
+- ✅ Need concept/semantic search ("authentication logic")
+- ✅ Medium-sized codebase (100-500 files)
+- ✅ One-time or infrequent searches
+
+**Don't Use When**:
+- ❌ Known exact file path → Use Read directly
+- ❌ Large codebase + repeated searches → Use codex_lens
+- ❌ Exact pattern match → Use Grep (faster)
+
+**Mode Selection**:
+- `auto`: Let tool decide (default, safest)
+- `exact`: Know exact pattern, need fast results
+- `fuzzy`: Typo-tolerant file/symbol names
+- `semantic`: Concept-based ("error handling", "data validation")
+- `graph`: Dependency/relationship analysis
+
+**Trigger Indicators**:
+- "Find files related to user authentication"
+- "Where is the payment processing logic?"
+- "Locate database connection setup"
+
+---
+
+## 2. File Modification Tools
+
+### edit_file (`mcp__ccw-tools__edit_file`)
+
+**Use When**:
+- ✅ Built-in Edit tool failed 1+ times
+- ✅ Need dry-run preview before applying
+- ✅ Need line-based operations (insert_after, insert_before)
+- ✅ Need to replace all occurrences
+
+**Don't Use When**:
+- ❌ Built-in Edit hasn't failed yet → Try built-in first
+- ❌ Need to create new file → Use write_file
+
+**Trigger Indicators**:
+- Built-in Edit returns "old_string not found"
+- Built-in Edit fails due to whitespace/formatting
+- Need to verify changes before applying (dryRun=true)
+
+**Mode Selection**:
+- `mode=update`: Replace text (similar to built-in Edit)
+- `mode=line`: Line-based operations (insert_after, insert_before, delete)
+
+---
+
+### write_file (`mcp__ccw-tools__write_file`)
+
+**Use When**:
+- ✅ Creating brand new files
+- ✅ MCP edit_file still fails (last resort)
+- ✅ Need to completely replace file content
+- ✅ Need backup before overwriting
+
+**Don't Use When**:
+- ❌ File exists + small change → Use Edit tools
+- ❌ Built-in Edit hasn't been tried → Try built-in Edit first
+
+**Trigger Indicators**:
+- All Edit attempts failed
+- Need to create new file with specific content
+- User explicitly asks to "recreate file"
+
+---
+
+## 3. Decision Logic
+
+### File Reading Priority
+
+```
+1. Known single file? → Built-in Read
+2. Multiple files OR pattern matching? → mcp__ccw-tools__read_file
+3. Unknown location? → smart_search, then Read
+4. Large codebase + repeated access? → codex_lens
+```
+
+### File Editing Priority
+
+```
+1. Always try built-in Edit first
+2. Fails 1+ times? → mcp__ccw-tools__edit_file
+3. Still fails? → mcp__ccw-tools__write_file (last resort)
+```
+
+### Search Tool Priority
+
+```
+1. External knowledge? → Exa
+2. Exact pattern in small codebase? → Built-in Grep
+3. Semantic/unknown location? → smart_search
+4. Large codebase + repeated searches? → codex_lens
+```
+
+---
+
+## 4. Anti-Patterns
+
+**Don't**:
+- Use codex_lens for one-time searches in small projects
+- Use smart_search when file path is already known
+- Use write_file before trying Edit tools
+- Use Exa for internal codebase searches
+- Use read_file for single file when Read tool works
+
+**Do**:
+- Start with simplest tool (Read, Edit, Grep)
+- Escalate to MCP tools when built-ins fail
+- Use semantic search (smart_search) for exploratory tasks
+- Use indexed search (codex_lens) for large, stable codebases
+- Use Exa for external/public knowledge
+

package/.claude/workflows/windows-platform.md

@@ -0,0 +1,16 @@
+# Windows Platform Guidelines
+
+## Path Format Guidelines
+
+### MCP Tools
+- Use double backslash: `D:\\path\\file.txt`
+- Example: `read_file(paths="D:\\Claude_dms3\\src\\index.ts")`
+
+### Bash Commands
+- Use forward slash: `D:/path/file.txt` or `/d/path/file.txt`
+- Example: `cd D:/Claude_dms3/src`
+
+### Relative Paths
+- Universal format works in both MCP and Bash contexts
+- Example: `./src/index.ts` or `../shared/utils.ts`
+