claude-code-workflow 6.3.37 → 6.3.39

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/clean.md

@@ -0,0 +1,409 @@
+---
+description: Intelligent code cleanup with mainline detection, stale artifact discovery, and safe execution
+argument-hint: [--dry-run] [FOCUS="<area>"]
+---
+
+# Workflow Clean Command
+
+## Overview
+
+Evidence-based intelligent cleanup command. Systematically identifies stale artifacts through mainline analysis, discovers drift, and safely removes unused sessions, documents, and dead code.
+
+**Core workflow**: Detect Mainline → Discover Drift → Confirm → Stage → Execute
+
+## Target Cleanup
+
+**Focus area**: $FOCUS (or entire project if not specified)
+**Mode**: $ARGUMENTS
+
+## Execution Process
+
+```
+Phase 0: Initialization
+   ├─ Parse arguments (--dry-run, FOCUS)
+   ├─ Setup session folder
+   └─ Initialize utility functions
+
+Phase 1: Mainline Detection
+   ├─ Analyze git history (30 days)
+   ├─ Identify core modules (high commit frequency)
+   ├─ Map active vs stale branches
+   └─ Build mainline profile
+
+Phase 2: Drift Discovery (Subagent)
+   ├─ spawn_agent with cli-explore-agent role
+   ├─ Scan workflow sessions for orphaned artifacts
+   ├─ Identify documents drifted from mainline
+   ├─ Detect dead code and unused exports
+   └─ Generate cleanup manifest
+
+Phase 3: Confirmation
+   ├─ Validate manifest schema
+   ├─ Display cleanup summary by category
+   ├─ AskUser: Select categories and risk level
+   └─ Dry-run exit if --dry-run
+
+Phase 4: Execution
+   ├─ Validate paths (security check)
+   ├─ Stage deletion (move to .trash)
+   ├─ Update manifests
+   ├─ Permanent deletion
+   └─ Report results
+```
+
+## Implementation
+
+### Phase 0: Initialization
+
+```javascript
+const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
+
+// Parse arguments
+const args = "$ARGUMENTS"
+const isDryRun = args.includes('--dry-run')
+const focusMatch = args.match(/FOCUS="([^"]+)"/)
+const focusArea = focusMatch ? focusMatch[1] : "$FOCUS" !== "$" + "FOCUS" ? "$FOCUS" : null
+
+// Session setup
+const dateStr = getUtc8ISOString().substring(0, 10)
+const sessionId = `clean-${dateStr}`
+const sessionFolder = `.workflow/.clean/${sessionId}`
+const trashFolder = `${sessionFolder}/.trash`
+const projectRoot = process.cwd()
+
+bash(`mkdir -p ${sessionFolder}`)
+bash(`mkdir -p ${trashFolder}`)
+
+// Utility functions
+function fileExists(p) {
+  try { return bash(`test -f "${p}" && echo "yes"`).includes('yes') } catch { return false }
+}
+
+function dirExists(p) {
+  try { return bash(`test -d "${p}" && echo "yes"`).includes('yes') } catch { return false }
+}
+
+function validatePath(targetPath) {
+  if (targetPath.includes('..')) return { valid: false, reason: 'Path traversal' }
+
+  const allowed = ['.workflow/', '.claude/rules/tech/', 'src/']
+  const dangerous = [/^\//, /^C:\\Windows/i, /node_modules/, /\.git$/]
+
+  if (!allowed.some(p => targetPath.startsWith(p))) {
+    return { valid: false, reason: 'Outside allowed directories' }
+  }
+  if (dangerous.some(p => p.test(targetPath))) {
+    return { valid: false, reason: 'Dangerous pattern' }
+  }
+  return { valid: true }
+}
+```
+
+---
+
+### Phase 1: Mainline Detection
+
+```javascript
+// Check git repository
+const isGitRepo = bash('git rev-parse --git-dir 2>/dev/null && echo "yes"').includes('yes')
+
+let mainlineProfile = {
+  coreModules: [],
+  activeFiles: [],
+  activeBranches: [],
+  staleThreshold: { sessions: 7, branches: 30, documents: 14 },
+  isGitRepo,
+  timestamp: getUtc8ISOString()
+}
+
+if (isGitRepo) {
+  // Commit frequency by directory (last 30 days)
+  const freq = bash('git log --since="30 days ago" --name-only --pretty=format: | grep -v "^$" | cut -d/ -f1-2 | sort | uniq -c | sort -rn | head -20')
+
+  // Parse core modules (>5 commits)
+  mainlineProfile.coreModules = freq.trim().split('\n')
+    .map(l => l.trim().match(/^(\d+)\s+(.+)$/))
+    .filter(m => m && parseInt(m[1]) >= 5)
+    .map(m => m[2])
+
+  // Recent branches
+  const branches = bash('git for-each-ref --sort=-committerdate refs/heads/ --format="%(refname:short)" | head -10')
+  mainlineProfile.activeBranches = branches.trim().split('\n').filter(Boolean)
+}
+
+Write(`${sessionFolder}/mainline-profile.json`, JSON.stringify(mainlineProfile, null, 2))
+```
+
+---
+
+### Phase 2: Drift Discovery
+
+```javascript
+let exploreAgent = null
+
+try {
+  // Launch cli-explore-agent
+  exploreAgent = spawn_agent({
+    message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS
+1. Read: ~/.codex/agents/cli-explore-agent.md
+2. Read: .workflow/project-tech.json (if exists)
+
+## Task Objective
+Discover stale artifacts for cleanup.
+
+## Context
+- Session: ${sessionFolder}
+- Focus: ${focusArea || 'entire project'}
+
+## Discovery Categories
+
+### 1. Stale Workflow Sessions
+Scan: .workflow/active/WFS-*, .workflow/archives/WFS-*, .workflow/.lite-plan/*, .workflow/.debug/DBG-*
+Criteria: No modification >7 days + no related git commits
+
+### 2. Drifted Documents
+Scan: .claude/rules/tech/*, .workflow/.scratchpad/*
+Criteria: >30% broken references to non-existent files
+
+### 3. Dead Code
+Scan: Unused exports, orphan files (not imported anywhere)
+Criteria: No importers in import graph
+
+## Output
+Write to: ${sessionFolder}/cleanup-manifest.json
+
+Format:
+{
+  "generated_at": "ISO",
+  "discoveries": {
+    "stale_sessions": [{ "path": "...", "age_days": N, "reason": "...", "risk": "low|medium|high" }],
+    "drifted_documents": [{ "path": "...", "drift_percentage": N, "reason": "...", "risk": "..." }],
+    "dead_code": [{ "path": "...", "type": "orphan_file", "reason": "...", "risk": "..." }]
+  },
+  "summary": { "total_items": N, "by_category": {...}, "by_risk": {...} }
+}
+`
+  })
+
+  // Wait with timeout handling
+  let result = wait({ ids: [exploreAgent], timeout_ms: 600000 })
+
+  if (result.timed_out) {
+    send_input({ id: exploreAgent, message: 'Complete now and write cleanup-manifest.json.' })
+    result = wait({ ids: [exploreAgent], timeout_ms: 300000 })
+    if (result.timed_out) throw new Error('Agent timeout')
+  }
+
+  if (!fileExists(`${sessionFolder}/cleanup-manifest.json`)) {
+    throw new Error('Manifest not generated')
+  }
+
+} finally {
+  if (exploreAgent) close_agent({ id: exploreAgent })
+}
+```
+
+---
+
+### Phase 3: Confirmation
+
+```javascript
+// Load and validate manifest
+const manifest = JSON.parse(Read(`${sessionFolder}/cleanup-manifest.json`))
+
+// Display summary
+console.log(`
+## Cleanup Discovery Report
+
+| Category | Count | Risk |
+|----------|-------|------|
+| Sessions | ${manifest.summary.by_category.stale_sessions} | ${getRiskSummary('sessions')} |
+| Documents | ${manifest.summary.by_category.drifted_documents} | ${getRiskSummary('documents')} |
+| Dead Code | ${manifest.summary.by_category.dead_code} | ${getRiskSummary('code')} |
+
+**Total**: ${manifest.summary.total_items} items
+`)
+
+// Dry-run exit
+if (isDryRun) {
+  console.log(`
+**Dry-run mode**: No changes made.
+Manifest: ${sessionFolder}/cleanup-manifest.json
+  `)
+  return
+}
+
+// User confirmation
+const selection = AskUser({
+  questions: [
+    {
+      question: "Which categories to clean?",
+      header: "Categories",
+      multiSelect: true,
+      options: [
+        { label: "Sessions", description: `${manifest.summary.by_category.stale_sessions} stale sessions` },
+        { label: "Documents", description: `${manifest.summary.by_category.drifted_documents} drifted docs` },
+        { label: "Dead Code", description: `${manifest.summary.by_category.dead_code} unused files` }
+      ]
+    },
+    {
+      question: "Risk level?",
+      header: "Risk",
+      options: [
+        { label: "Low only", description: "Safest (Recommended)" },
+        { label: "Low + Medium", description: "Includes likely unused" },
+        { label: "All", description: "Aggressive" }
+      ]
+    }
+  ]
+})
+```
+
+---
+
+### Phase 4: Execution
+
+```javascript
+const riskFilter = {
+  'Low only': ['low'],
+  'Low + Medium': ['low', 'medium'],
+  'All': ['low', 'medium', 'high']
+}[selection.risk]
+
+// Collect items to clean
+const items = []
+if (selection.categories.includes('Sessions')) {
+  items.push(...manifest.discoveries.stale_sessions.filter(s => riskFilter.includes(s.risk)))
+}
+if (selection.categories.includes('Documents')) {
+  items.push(...manifest.discoveries.drifted_documents.filter(d => riskFilter.includes(d.risk)))
+}
+if (selection.categories.includes('Dead Code')) {
+  items.push(...manifest.discoveries.dead_code.filter(c => riskFilter.includes(c.risk)))
+}
+
+const results = { staged: [], deleted: [], failed: [], skipped: [] }
+
+// Validate and stage
+for (const item of items) {
+  const validation = validatePath(item.path)
+  if (!validation.valid) {
+    results.skipped.push({ path: item.path, reason: validation.reason })
+    continue
+  }
+
+  if (!fileExists(item.path) && !dirExists(item.path)) {
+    results.skipped.push({ path: item.path, reason: 'Not found' })
+    continue
+  }
+
+  try {
+    const trashTarget = `${trashFolder}/${item.path.replace(/\//g, '_')}`
+    bash(`mv "${item.path}" "${trashTarget}"`)
+    results.staged.push({ path: item.path, trashPath: trashTarget })
+  } catch (e) {
+    results.failed.push({ path: item.path, error: e.message })
+  }
+}
+
+// Permanent deletion
+for (const staged of results.staged) {
+  try {
+    bash(`rm -rf "${staged.trashPath}"`)
+    results.deleted.push(staged.path)
+  } catch (e) {
+    console.error(`Failed: ${staged.path}`)
+  }
+}
+
+// Cleanup empty trash
+bash(`rmdir "${trashFolder}" 2>/dev/null || true`)
+
+// Report
+console.log(`
+## Cleanup Complete
+
+**Deleted**: ${results.deleted.length}
+**Failed**: ${results.failed.length}
+**Skipped**: ${results.skipped.length}
+
+### Deleted
+${results.deleted.map(p => `- ${p}`).join('\n') || '(none)'}
+
+${results.failed.length > 0 ? `### Failed\n${results.failed.map(f => `- ${f.path}: ${f.error}`).join('\n')}` : ''}
+
+Report: ${sessionFolder}/cleanup-report.json
+`)
+
+Write(`${sessionFolder}/cleanup-report.json`, JSON.stringify({
+  timestamp: getUtc8ISOString(),
+  results,
+  summary: {
+    deleted: results.deleted.length,
+    failed: results.failed.length,
+    skipped: results.skipped.length
+  }
+}, null, 2))
+```
+
+---
+
+## Session Folder
+
+```
+.workflow/.clean/clean-{YYYY-MM-DD}/
+├── mainline-profile.json     # Git history analysis
+├── cleanup-manifest.json     # Discovery results
+├── cleanup-report.json       # Execution results
+└── .trash/                   # Staging area (temporary)
+```
+
+## Risk Levels
+
+| Risk | Description | Examples |
+|------|-------------|----------|
+| **Low** | Safe to delete | Empty sessions, scratchpad files |
+| **Medium** | Likely unused | Orphan files, old archives |
+| **High** | May have dependencies | Files with some imports |
+
+## Security Features
+
+| Feature | Protection |
+|---------|------------|
+| Path Validation | Whitelist directories, reject traversal |
+| Staged Deletion | Move to .trash before permanent delete |
+| Dangerous Patterns | Block system dirs, node_modules, .git |
+
+## Iteration Flow
+
+```
+First Call (/prompts:clean):
+   ├─ Detect mainline from git history
+   ├─ Discover stale artifacts via subagent
+   ├─ Display summary, await user selection
+   └─ Execute cleanup with staging
+
+Dry-Run (/prompts:clean --dry-run):
+   ├─ All phases except execution
+   └─ Manifest saved for review
+
+Focused (/prompts:clean FOCUS="auth"):
+   └─ Discovery limited to specified area
+```
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| No git repo | Use file timestamps only |
+| Agent timeout | Retry once with prompt, then abort |
+| Path validation fail | Skip item, report reason |
+| Manifest parse error | Abort with error |
+| Empty discovery | Report "codebase is clean" |
+
+---
+
+**Now execute cleanup workflow** with focus: $FOCUS