claude-code-workflow 6.2.1 → 6.2.3

package/.claude/workflows/task-core.md

@@ -0,0 +1,214 @@
+# Task System Core Reference
+
+## Overview
+Task commands provide single-execution workflow capabilities with full context awareness, hierarchical organization, and agent orchestration.
+
+## Task JSON Schema
+All task files use this simplified 5-field schema:
+
+```json
+{
+  "id": "IMPL-1.2",
+  "title": "Implement JWT authentication",
+  "status": "pending|active|completed|blocked|container",
+
+  "meta": {
+    "type": "feature|bugfix|refactor|test-gen|test-fix|docs",
+    "agent": "@code-developer|@action-planning-agent|@test-fix-agent|@universal-executor"
+  },
+
+  "context": {
+    "requirements": ["JWT authentication", "OAuth2 support"],
+    "focus_paths": ["src/auth", "tests/auth", "config/auth.json"],
+    "acceptance": ["JWT validation works", "OAuth flow complete"],
+    "parent": "IMPL-1",
+    "depends_on": ["IMPL-1.1"],
+    "inherited": {
+      "from": "IMPL-1",
+      "context": ["Authentication system design completed"]
+    },
+    "shared_context": {
+      "auth_strategy": "JWT with refresh tokens"
+    }
+  },
+
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "gather_context",
+        "action": "Read dependency summaries",
+        "command": "bash(cat .workflow/*/summaries/IMPL-1.1-summary.md)",
+        "output_to": "auth_design_context",
+        "on_error": "skip_optional"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Implement JWT authentication system",
+        "description": "Implement comprehensive JWT authentication system with token generation, validation, and refresh logic",
+        "modification_points": ["Add JWT token generation", "Implement token validation middleware", "Create refresh token logic"],
+        "logic_flow": ["User login request → validate credentials", "Generate JWT access and refresh tokens", "Store refresh token securely", "Return tokens to client"],
+        "depends_on": [],
+        "output": "jwt_implementation"
+      }
+    ],
+    "target_files": [
+      "src/auth/login.ts:handleLogin:75-120",
+      "src/middleware/auth.ts:validateToken",
+      "src/auth/PasswordReset.ts"
+    ]
+  }
+}
+```
+
+## Field Structure Details
+
+### focus_paths Field (within context)
+**Purpose**: Specifies concrete project paths relevant to task implementation
+
+**Format**:
+- **Array of strings**: `["folder1", "folder2", "specific_file.ts"]`
+- **Concrete paths**: Use actual directory/file names without wildcards
+- **Mixed types**: Can include both directories and specific files
+- **Relative paths**: From project root (e.g., `src/auth`, not `./src/auth`)
+
+**Examples**:
+```json
+// Authentication system task
+"focus_paths": ["src/auth", "tests/auth", "config/auth.json", "src/middleware/auth.ts"]
+
+// UI component task
+"focus_paths": ["src/components/Button", "src/styles", "tests/components"]
+```
+
+### flow_control Field Structure
+**Purpose**: Universal process manager for task execution
+
+**Components**:
+- **pre_analysis**: Array of sequential process steps
+- **implementation_approach**: Task execution strategy
+- **target_files**: Files to modify/create - existing files in `file:function:lines` format, new files as `file` only
+
+**Step Structure**:
+```json
+{
+  "step": "gather_context",
+  "action": "Human-readable description",
+  "command": "bash(executable command with [variables])",
+  "output_to": "variable_name",
+  "on_error": "skip_optional|fail|retry_once|manual_intervention"
+}
+```
+
+## Hierarchical System
+
+### Task Hierarchy Rules
+- **Format**: IMPL-N (main), IMPL-N.M (subtasks) - uppercase required
+- **Maximum Depth**: 2 levels only
+- **10-Task Limit**: Hard limit enforced across all tasks
+- **Container Tasks**: Parents with subtasks (not executable)
+- **Leaf Tasks**: No subtasks (executable)
+- **File Cohesion**: Related files must stay in same task
+
+### Task Complexity Classifications
+- **Simple**: ≤5 tasks, single-level tasks, direct execution
+- **Medium**: 6-10 tasks, two-level hierarchy, context coordination
+- **Over-scope**: >10 tasks requires project re-scoping into iterations
+
+### Complexity Assessment Rules
+- **Creation**: System evaluates and assigns complexity
+- **10-task limit**: Hard limit enforced - exceeding requires re-scoping
+- **Execution**: Can upgrade (Simple→Medium→Over-scope), triggers re-scoping
+- **Override**: Users can manually specify complexity within 10-task limit
+
+### Status Rules
+- **pending**: Ready for execution
+- **active**: Currently being executed
+- **completed**: Successfully finished
+- **blocked**: Waiting for dependencies
+- **container**: Has subtasks (parent only)
+
+## Session Integration
+
+### Active Session Detection
+```bash
+# Check for active session in sessions directory
+active_session=$(find .workflow/active/ -name 'WFS-*' -type d 2>/dev/null | head -1)
+```
+
+### Workflow Context Inheritance
+Tasks inherit from:
+1. `workflow-session.json` - Session metadata
+2. Parent task context (for subtasks)
+3. `IMPL_PLAN.md` - Planning document
+
+### File Locations
+- **Task JSON**: `.workflow/active/WFS-[topic]/.task/IMPL-*.json` (uppercase required)
+- **Session State**: `.workflow/active/WFS-[topic]/workflow-session.json`
+- **Planning Doc**: `.workflow/active/WFS-[topic]/IMPL_PLAN.md`
+- **Progress**: `.workflow/active/WFS-[topic]/TODO_LIST.md`
+
+## Agent Mapping
+
+### Automatic Agent Selection
+- **@code-developer**: Implementation tasks, coding, test writing
+- **@action-planning-agent**: Design, architecture planning
+- **@test-fix-agent**: Test execution, failure diagnosis, code fixing
+- **@universal-executor**: Optional manual review (only when explicitly requested)
+
+### Agent Context Filtering
+Each agent receives tailored context:
+- **@code-developer**: Complete implementation details, test requirements
+- **@action-planning-agent**: High-level requirements, risks, architecture
+- **@test-fix-agent**: Test execution, failure diagnosis, code fixing
+- **@universal-executor**: Quality standards, security considerations (when requested)
+
+## Deprecated Fields
+
+### Legacy paths Field
+**Deprecated**: The semicolon-separated `paths` field has been replaced by `context.focus_paths` array.
+
+**Old Format** (no longer used):
+```json
+"paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts"
+```
+
+**New Format** (use this instead):
+```json
+"context": {
+  "focus_paths": ["src/auth", "tests/auth", "config/auth.json", "src/middleware/auth.ts"]
+}
+```
+
+## Validation Rules
+
+### Pre-execution Checks
+1. Task exists and is valid JSON
+2. Task status allows operation
+3. Dependencies are met
+4. Active workflow session exists
+5. All 5 core fields present (id, title, status, meta, context, flow_control)
+6. Total task count ≤ 10 (hard limit)
+7. File cohesion maintained in focus_paths
+
+### Hierarchy Validation
+- Parent-child relationships valid
+- Maximum depth not exceeded
+- Container tasks have subtasks
+- No circular dependencies
+
+## Error Handling Patterns
+
+### Common Errors
+- **Task not found**: Check ID format and session
+- **Invalid status**: Verify task can be operated on
+- **Missing session**: Ensure active workflow exists
+- **Max depth exceeded**: Restructure hierarchy
+- **Missing implementation**: Complete required fields
+
+### Recovery Strategies
+- Session validation with clear guidance
+- Automatic ID correction suggestions
+- Implementation field completion prompts
+- Hierarchy restructuring options

package/.claude/workflows/tool-strategy.md

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