claude-code-workflow 6.0.0

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

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,71 @@
+# 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
+
+## ⚡ Bash Text Processing (sed/awk)
+
+**When to Use**: Edit tool fails 2+ times on same file
+
+### sed Quick Reference
+
+```bash
+# Replace first occurrence per line
+sed 's/old/new/' file.txt
+
+# Replace all occurrences (global)
+sed 's/old/new/g' file.txt
+
+# In-place edit (modify file directly)
+sed -i 's/old/new/g' file.txt
+
+# Delete lines matching pattern
+sed '/pattern/d' file.txt
+
+# Insert line before match
+sed '/pattern/i\new line' file.txt
+
+# Insert line after match
+sed '/pattern/a\new line' file.txt
+
+# Replace on specific line number
+sed '5s/old/new/' file.txt
+
+# Multi-line replacement (escape newlines)
+sed ':a;N;$!ba;s/old\npattern/new\ntext/g' file.txt
+```
+
+### awk Quick Reference
+
+```bash
+# Print specific column
+awk '{print $1}' file.txt
+
+# Print lines matching pattern
+awk '/pattern/' file.txt
+
+# Replace field value
+awk '{$2="new"; print}' file.txt
+
+# Conditional replacement
+awk '/pattern/{gsub(/old/,"new")}1' file.txt
+
+# Insert line after match
+awk '/pattern/{print; print "new line"; next}1' file.txt
+
+# Multi-field operations
+awk -F',' '{print $1, $3}' file.csv
+```
+
+### Fallback Strategy
+
+1. **Edit fails 2+ times** → Try sed for simple replacements
+2. **sed fails** → Try awk for complex patterns
+3. **awk fails** → Use Write to recreate file