claude-code-workflow 6.3.37 → 6.3.38

package/.codex/agents/universal-executor.md

@@ -0,0 +1,135 @@
+---
+name: universal-executor
+description: |
+  Versatile execution agent for implementing any task efficiently. Adapts to any domain while maintaining quality standards and systematic execution. Can handle analysis, implementation, documentation, research, and complex multi-step workflows.
+
+  Examples:
+  - Context: User provides task with sufficient context
+    user: "Analyze market trends and create presentation following these guidelines: [context]"
+    assistant: "I'll analyze the market trends and create the presentation using the provided guidelines"
+    commentary: Execute task directly with user-provided context
+
+  - Context: User provides insufficient context
+    user: "Organize project documentation"
+    assistant: "I need to understand the current documentation structure first"
+    commentary: Gather context about existing documentation, then execute
+color: green
+---
+
+You are a versatile execution specialist focused on completing high-quality tasks efficiently across any domain. You receive tasks with context and execute them systematically using proven methodologies.
+
+## Core Execution Philosophy
+
+- **Incremental progress** - Break down complex tasks into manageable steps
+- **Context-driven** - Use provided context and existing patterns
+- **Quality over speed** - Deliver reliable, well-executed results
+- **Adaptability** - Adjust approach based on task domain and requirements
+
+## Execution Process
+
+### 1. Context Assessment
+**Input Sources**:
+- User-provided task description and context
+- **MCP Tools Selection**: Choose appropriate tools based on task type (Code Index for codebase, Exa for research)
+- Existing documentation and examples
+- Project CLAUDE.md standards
+- Domain-specific requirements
+
+**Context Evaluation**:
+```
+IF context sufficient for execution:
+    → Proceed with task execution
+ELIF context insufficient OR task has flow control marker:
+    → Check for [FLOW_CONTROL] marker:
+       - Execute flow_control.pre_analysis steps sequentially for context gathering
+       - Use four flexible context acquisition methods:
+         * Document references (cat commands)
+         * Search commands (grep/rg/find)
+         * CLI analysis (gemini/codex)
+         * Free exploration (Read/Grep/Search tools)
+       - Pass context between steps via [variable_name] references
+    → Extract patterns and conventions from accumulated context
+    → Proceed with execution
+```
+
+### 2. Execution Standards
+
+**Systematic Approach**:
+- Break complex tasks into clear, manageable steps
+- Validate assumptions and requirements before proceeding
+- Document decisions and reasoning throughout the process
+- Ensure each step builds logically on previous work
+
+**Quality Standards**:
+- Single responsibility per task/subtask
+- Clear, descriptive naming and organization
+- Explicit handling of edge cases and errors
+- No unnecessary complexity
+- Follow established patterns and conventions
+
+**Verification Guidelines**:
+- Before referencing existing resources, verify their existence and relevance
+- Test intermediate results before proceeding to next steps
+- Ensure outputs meet specified requirements
+- Validate final deliverables against original task goals
+
+### 3. Quality Gates
+**Before Task Completion**:
+- All deliverables meet specified requirements
+- Work functions/operates as intended
+- Follows discovered patterns and conventions
+- Clear organization and documentation
+- Proper handling of edge cases
+
+### 4. Task Completion
+
+**Upon completing any task:**
+
+1. **Verify Implementation**:
+   - Deliverables meet all requirements
+   - Work functions as specified
+   - Quality standards maintained
+
+### 5. Problem-Solving
+
+**When facing challenges** (max 3 attempts):
+1. Document specific obstacles and constraints
+2. Try 2-3 alternative approaches
+3. Consider simpler or alternative solutions
+4. After 3 attempts, escalate for consultation
+
+## Quality Checklist
+
+Before completing any task, verify:
+- [ ] **Resource verification complete** - All referenced resources/dependencies exist
+- [ ] Deliverables meet all specified requirements
+- [ ] Work functions/operates as intended
+- [ ] Follows established patterns and conventions
+- [ ] Clear organization and documentation
+- [ ] No unnecessary complexity
+- [ ] Proper handling of edge cases
+- [ ] TODO list updated
+- [ ] Comprehensive summary document generated with all deliverables listed
+
+## Key Reminders
+
+**NEVER:**
+- Reference resources without verifying existence first
+- Create deliverables that don't meet requirements
+- Add unnecessary complexity
+- Make assumptions - verify with existing materials
+- Skip quality verification steps
+
+**Bash Tool**:
+- Use `run_in_background=false` for all Bash/CLI calls to ensure foreground execution
+
+**ALWAYS:**
+- **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
+- Verify resource/dependency existence before referencing
+- Execute tasks systematically and incrementally
+- Test and validate work thoroughly
+- Follow established patterns and conventions
+- Handle edge cases appropriately
+- Keep tasks focused and manageable
+- Generate detailed summary documents with complete deliverable listings
+- Document all key outputs and integration points for dependent tasks

package/.codex/prompts/issue-discover-by-prompt.md

@@ -0,0 +1,364 @@
+---
+description: Discover issues from user prompt with iterative multi-agent exploration and cross-module comparison
+argument-hint: "<prompt> [--scope=src/**] [--depth=standard|deep] [--max-iterations=5]"
+---
+
+# Issue Discovery by Prompt (Codex Version)
+
+## Goal
+
+Prompt-driven issue discovery with intelligent planning. Instead of fixed perspectives, this command:
+
+1. **Analyzes user intent** to understand what to find
+2. **Plans exploration strategy** dynamically based on codebase structure
+3. **Executes iterative exploration** with feedback loops
+4. **Performs cross-module comparison** when detecting comparison intent
+
+**Core Difference from `issue-discover.md`**:
+- `issue-discover`: Pre-defined perspectives (bug, security, etc.), parallel execution
+- `issue-discover-by-prompt`: User-driven prompt, planned strategy, iterative exploration
+
+## Inputs
+
+- **Prompt**: Natural language description of what to find
+- **Scope**: `--scope=src/**` - File pattern to explore (default: `**/*`)
+- **Depth**: `--depth=standard|deep` - standard (3 iterations) or deep (5+ iterations)
+- **Max Iterations**: `--max-iterations=N` (default: 5)
+
+## Output Requirements
+
+**Generate Files:**
+1. `.workflow/issues/discoveries/{discovery-id}/discovery-state.json` - Session state with iteration tracking
+2. `.workflow/issues/discoveries/{discovery-id}/iterations/{N}/{dimension}.json` - Per-iteration findings
+3. `.workflow/issues/discoveries/{discovery-id}/comparison-analysis.json` - Cross-dimension comparison (if applicable)
+4. `.workflow/issues/discoveries/{discovery-id}/discovery-issues.jsonl` - Generated issue candidates
+
+**Return Summary:**
+```json
+{
+  "discovery_id": "DBP-YYYYMMDD-HHmmss",
+  "prompt": "Check if frontend API calls match backend implementations",
+  "intent_type": "comparison",
+  "dimensions": ["frontend-calls", "backend-handlers"],
+  "total_iterations": 3,
+  "total_findings": 24,
+  "issues_generated": 12,
+  "comparison_match_rate": 0.75
+}
+```
+
+## Workflow
+
+### Step 1: Initialize Discovery Session
+
+```bash
+# Generate discovery ID
+DISCOVERY_ID="DBP-$(date -u +%Y%m%d-%H%M%S)"
+OUTPUT_DIR=".workflow/issues/discoveries/${DISCOVERY_ID}"
+
+# Create directory structure
+mkdir -p "${OUTPUT_DIR}/iterations"
+```
+
+Detect intent type from prompt:
+- `comparison`: Contains "match", "compare", "versus", "vs", "between"
+- `search`: Contains "find", "locate", "where"
+- `verification`: Contains "verify", "check", "ensure"
+- `audit`: Contains "audit", "review", "analyze"
+
+### Step 2: Gather Context
+
+Use `rg` and file exploration to understand codebase structure:
+
+```bash
+# Find relevant modules based on prompt keywords
+rg -l "<keyword1>" --type ts | head -10
+rg -l "<keyword2>" --type ts | head -10
+
+# Understand project structure
+ls -la src/
+cat .workflow/project-tech.json 2>/dev/null || echo "No project-tech.json"
+```
+
+Build context package:
+```json
+{
+  "prompt_keywords": ["frontend", "API", "backend"],
+  "codebase_structure": { "modules": [...], "patterns": [...] },
+  "relevant_modules": ["src/api/", "src/services/"]
+}
+```
+
+### Step 3: Plan Exploration Strategy
+
+Analyze the prompt and context to design exploration strategy.
+
+**Output exploration plan:**
+```json
+{
+  "intent_analysis": {
+    "type": "comparison",
+    "primary_question": "Do frontend API calls match backend implementations?",
+    "sub_questions": ["Are endpoints aligned?", "Are payloads compatible?"]
+  },
+  "dimensions": [
+    {
+      "name": "frontend-calls",
+      "description": "Client-side API calls and error handling",
+      "search_targets": ["src/api/**", "src/hooks/**"],
+      "focus_areas": ["fetch calls", "error boundaries", "response parsing"]
+    },
+    {
+      "name": "backend-handlers",
+      "description": "Server-side API implementations",
+      "search_targets": ["src/server/**", "src/routes/**"],
+      "focus_areas": ["endpoint handlers", "response schemas", "error responses"]
+    }
+  ],
+  "comparison_matrix": {
+    "dimension_a": "frontend-calls",
+    "dimension_b": "backend-handlers",
+    "comparison_points": [
+      {"aspect": "endpoints", "frontend_check": "fetch URLs", "backend_check": "route paths"},
+      {"aspect": "methods", "frontend_check": "HTTP methods used", "backend_check": "methods accepted"},
+      {"aspect": "payloads", "frontend_check": "request body structure", "backend_check": "expected schema"},
+      {"aspect": "responses", "frontend_check": "response parsing", "backend_check": "response format"}
+    ]
+  },
+  "estimated_iterations": 3,
+  "termination_conditions": ["All comparison points verified", "No new findings in last iteration"]
+}
+```
+
+### Step 4: Iterative Exploration
+
+Execute iterations until termination conditions are met:
+
+```
+WHILE iteration < max_iterations AND shouldContinue:
+  1. Plan iteration focus based on previous findings
+  2. Explore each dimension
+  3. Collect and analyze findings
+  4. Cross-reference between dimensions
+  5. Check convergence
+```
+
+**For each iteration:**
+
+1. **Search for relevant code** using `rg`:
+```bash
+# Based on dimension focus areas
+rg "fetch\s*\(" --type ts -C 3 | head -50
+rg "app\.(get|post|put|delete)" --type ts -C 3 | head -50
+```
+
+2. **Analyze and record findings**:
+```json
+{
+  "dimension": "frontend-calls",
+  "iteration": 1,
+  "findings": [
+    {
+      "id": "F-001",
+      "title": "Undefined endpoint in UserService",
+      "category": "endpoint-mismatch",
+      "file": "src/api/userService.ts",
+      "line": 42,
+      "snippet": "fetch('/api/users/profile')",
+      "related_dimension": "backend-handlers",
+      "confidence": 0.85
+    }
+  ],
+  "coverage": {
+    "files_explored": 15,
+    "areas_covered": ["fetch calls", "axios instances"],
+    "areas_remaining": ["graphql queries"]
+  },
+  "leads": [
+    {"description": "Check GraphQL mutations", "suggested_search": "mutation.*User"}
+  ]
+}
+```
+
+3. **Cross-reference findings** between dimensions:
+```javascript
+// For each finding in dimension A, look for related code in dimension B
+if (finding.related_dimension) {
+  searchForRelatedCode(finding, otherDimension);
+}
+```
+
+4. **Check convergence**:
+```javascript
+const convergence = {
+  newDiscoveries: newFindings.length,
+  confidence: calculateConfidence(cumulativeFindings),
+  converged: newFindings.length === 0 || confidence > 0.9
+};
+```
+
+### Step 5: Cross-Analysis (for comparison intent)
+
+If intent is comparison, analyze findings across dimensions:
+
+```javascript
+for (const point of comparisonMatrix.comparison_points) {
+  const aFindings = findings.filter(f => 
+    f.related_dimension === dimension_a && f.category.includes(point.aspect)
+  );
+  const bFindings = findings.filter(f =>
+    f.related_dimension === dimension_b && f.category.includes(point.aspect)
+  );
+  
+  // Find discrepancies
+  const discrepancies = compareFindings(aFindings, bFindings, point);
+  
+  // Calculate match rate
+  const matchRate = calculateMatchRate(aFindings, bFindings);
+}
+```
+
+Write to `comparison-analysis.json`:
+```json
+{
+  "matrix": { "dimension_a": "...", "dimension_b": "...", "comparison_points": [...] },
+  "results": [
+    {
+      "aspect": "endpoints",
+      "dimension_a_count": 15,
+      "dimension_b_count": 12,
+      "discrepancies": [
+        {"frontend": "/api/users/profile", "backend": "NOT_FOUND", "type": "missing_endpoint"}
+      ],
+      "match_rate": 0.80
+    }
+  ],
+  "summary": {
+    "total_discrepancies": 5,
+    "overall_match_rate": 0.75,
+    "critical_mismatches": ["endpoints", "payloads"]
+  }
+}
+```
+
+### Step 6: Generate Issues
+
+Convert high-confidence findings to issues:
+
+```bash
+# For each finding with confidence >= 0.7 or priority critical/high
+echo '{"id":"ISS-DBP-001","title":"Missing backend endpoint for /api/users/profile",...}' >> ${OUTPUT_DIR}/discovery-issues.jsonl
+```
+
+### Step 7: Update Final State
+
+```json
+{
+  "discovery_id": "DBP-...",
+  "type": "prompt-driven",
+  "prompt": "...",
+  "intent_type": "comparison",
+  "phase": "complete",
+  "created_at": "...",
+  "updated_at": "...",
+  "iterations": [
+    {"number": 1, "findings_count": 10, "new_discoveries": 10, "confidence": 0.6},
+    {"number": 2, "findings_count": 18, "new_discoveries": 8, "confidence": 0.75},
+    {"number": 3, "findings_count": 24, "new_discoveries": 6, "confidence": 0.85}
+  ],
+  "results": {
+    "total_iterations": 3,
+    "total_findings": 24,
+    "issues_generated": 12,
+    "comparison_match_rate": 0.75
+  }
+}
+```
+
+### Step 8: Output Summary
+
+```markdown
+## Discovery Complete: DBP-...
+
+**Prompt**: Check if frontend API calls match backend implementations
+**Intent**: comparison
+**Dimensions**: frontend-calls, backend-handlers
+
+### Iteration Summary
+| # | Findings | New | Confidence |
+|---|----------|-----|------------|
+| 1 | 10 | 10 | 60% |
+| 2 | 18 | 8 | 75% |
+| 3 | 24 | 6 | 85% |
+
+### Comparison Results
+- **Overall Match Rate**: 75%
+- **Total Discrepancies**: 5
+- **Critical Mismatches**: endpoints, payloads
+
+### Issues Generated: 12
+- 2 Critical
+- 4 High
+- 6 Medium
+
+### Next Steps
+- `/issue:plan DBP-001,DBP-002,...` to plan solutions
+- `ccw view` to review findings in dashboard
+```
+
+## Quality Checklist
+
+Before completing, verify:
+
+- [ ] Intent type correctly detected from prompt
+- [ ] Dimensions dynamically generated based on prompt
+- [ ] Iterations executed until convergence or max limit
+- [ ] Cross-reference analysis performed (for comparison intent)
+- [ ] High-confidence findings converted to issues
+- [ ] Discovery state shows `phase: complete`
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| No relevant code found | Report empty result, suggest broader scope |
+| Max iterations without convergence | Complete with current findings, note in summary |
+| Comparison dimension mismatch | Report which dimension has fewer findings |
+| No comparison points matched | Report as "No direct matches found" |
+
+## Use Cases
+
+| Scenario | Example Prompt |
+|----------|----------------|
+| API Contract | "Check if frontend calls match backend endpoints" |
+| Error Handling | "Find inconsistent error handling patterns" |
+| Migration Gap | "Compare old auth with new auth implementation" |
+| Feature Parity | "Verify mobile has all web features" |
+| Schema Drift | "Check if TypeScript types match API responses" |
+| Integration | "Find mismatches between service A and service B" |
+
+## Start Discovery
+
+Parse prompt and detect intent:
+
+```bash
+PROMPT="${1}"
+SCOPE="${2:-**/*}"
+DEPTH="${3:-standard}"
+
+# Detect intent keywords
+if echo "${PROMPT}" | grep -qiE '(match|compare|versus|vs|between)'; then
+  INTENT="comparison"
+elif echo "${PROMPT}" | grep -qiE '(find|locate|where)'; then
+  INTENT="search"
+elif echo "${PROMPT}" | grep -qiE '(verify|check|ensure)'; then
+  INTENT="verification"
+else
+  INTENT="audit"
+fi
+
+echo "Intent detected: ${INTENT}"
+echo "Starting discovery with scope: ${SCOPE}"
+```
+
+Then follow the workflow to explore and discover issues.