claude-code-workflow 7.2.10 → 7.2.11

package/.claude/skills/workflow-tune/SKILL.md

@@ -0,0 +1,487 @@
+---
+name: workflow-tune
+description: Workflow tuning skill for multi-command/skill pipelines. Executes each step sequentially, inspects artifacts after each command, analyzes quality via ccw cli resume, builds process documentation, and generates optimization suggestions. Triggers on "workflow tune", "tune workflow", "workflow optimization".
+allowed-tools: Skill, Agent, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Workflow Tune
+
+Tune multi-step workflows composed of commands or skills. Execute each step, inspect artifacts, analyze via ccw cli resume, build process documentation, and produce actionable optimization suggestions.
+
+## Architecture Overview
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  Workflow Tune Orchestrator (SKILL.md)                                │
+│  → Parse → Decompose → Confirm → Setup → Step Loop → Synthesize     │
+└──────────────────────┬───────────────────────────────────────────────┘
+                       │
+   ┌───────────────────┼───────────────────────────────────┐
+   ↓                   ↓                                   ↓
+┌──────────┐   ┌─────────────────────────────┐     ┌──────────────┐
+│ Phase 1  │   │  Step Loop (2→3 per step)   │     │ Phase 4 + 5  │
+│ Setup    │   │  ┌─────┐  ┌─────┐           │     │ Synthesize + │
+│          │──→│  │ P2  │→ │ P3  │           │────→│ Report       │
+│ Parse +  │   │  │Exec │  │Anal │           │     │              │
+│ Decomp + │   │  └─────┘  └─────┘           │     └──────────────┘
+│ Confirm  │   │       ↑       │  next step  │
+└──────────┘   │       └───────┘             │
+               └─────────────────────────────┘
+
+Phase 1 Detail:
+  Input → [Format 1-3: direct parse] ──→ Command Doc → Confirm → Init
+       → [Format 4: natural lang]   ──→ Semantic Decompose → Command Doc → Confirm → Init
+```
+
+## Key Design Principles
+
+1. **Test-First Evaluation**: Auto-generate per-step acceptance criteria before execution — judge results against concrete requirements, not vague quality
+2. **Step-by-Step Execution**: Each workflow step executes independently, artifacts inspected before proceeding
+3. **Resume-Based Analysis**: Uses ccw cli `--resume` to maintain analysis context across steps
+4. **Process Documentation**: Running `process-log.md` accumulates observations per step
+5. **Two-Tool Pipeline**: Claude/target tool (execute) + Gemini (analyze) = complementary perspectives
+6. **Pure Orchestrator**: SKILL.md coordinates only — execution detail in phase files
+7. **Progressive Phase Loading**: Phase docs read only when that phase executes
+
+## Interactive Preference Collection
+
+```javascript
+// ★ Auto mode detection
+const autoYes = /\b(-y|--yes)\b/.test($ARGUMENTS)
+
+if (autoYes) {
+  workflowPreferences = {
+    autoYes: true,
+    analysisDepth: 'standard',
+    autoFix: false
+  }
+} else {
+  const prefResponse = AskUserQuestion({
+    questions: [
+      {
+        question: "选择 Workflow 调优配置：",
+        header: "Tune Config",
+        multiSelect: false,
+        options: [
+          { label: "Quick (轻量分析)", description: "每步简要检查，快速产出建议" },
+          { label: "Standard (标准分析) (Recommended)", description: "每步详细分析，完整过程文档" },
+          { label: "Deep (深度分析)", description: "每步深度审查，含性能和架构建议" }
+        ]
+      },
+      {
+        question: "是否自动应用优化建议？",
+        header: "Auto Fix",
+        multiSelect: false,
+        options: [
+          { label: "No (仅生成报告) (Recommended)", description: "只分析，不修改" },
+          { label: "Yes (自动应用)", description: "分析后自动应用高优先级建议" }
+        ]
+      }
+    ]
+  })
+
+  const depthMap = {
+    "Quick": "quick",
+    "Standard": "standard",
+    "Deep": "deep"
+  }
+  const selectedDepth = Object.keys(depthMap).find(k =>
+    prefResponse["Tune Config"].startsWith(k)
+  ) || "Standard"
+
+  workflowPreferences = {
+    autoYes: false,
+    analysisDepth: depthMap[selectedDepth],
+    autoFix: prefResponse["Auto Fix"].startsWith("Yes")
+  }
+}
+```
+
+## Input Processing
+
+```
+$ARGUMENTS → Parse:
+  ├─ Workflow definition: one of:
+  │   ├─ Format 1: Inline steps — "step1 | step2 | step3" (pipe-separated commands)
+  │   ├─ Format 2: Skill names — "skill-a,skill-b,skill-c" (comma-separated)
+  │   ├─ Format 3: File path — "--file workflow.json" (JSON definition)
+  │   └─ Format 4: Natural language — free-text description, auto-decomposed into steps
+  ├─ Test context: --context "description of what the workflow should achieve"
+  └─ Flags: --depth quick|standard|deep, -y/--yes, --auto-fix
+```
+
+### Format Detection Priority
+
+```
+1. --file flag present         → Format 3 (JSON)
+2. Contains pipe "|"           → Format 1 (inline commands)
+3. Matches skill-name pattern  → Format 2 (comma-separated skills)
+4. Everything else             → Format 4 (natural language → semantic decomposition)
+```
+
+### Format 4: Semantic Decomposition (Natural Language)
+
+When input is free-text (e.g., "分析 src 目录代码质量，做代码评审，然后修复高优先级问题"), the orchestrator:
+
+1. **Semantic Parse**: Identify intent verbs and targets → map to available skills/commands
+2. **Step Chain Generation**: Produce ordered step chain with tool/mode selection
+3. **Command Doc**: Generate formatted execution plan document
+4. **User Confirmation**: Display plan, ask user to confirm/edit before execution
+
+```javascript
+// Semantic decomposition uses intent-to-tool mapping
+const intentMap = {
+  // Analysis intents
+  '分析|analyze|审查|inspect|scan': { tool: 'gemini', mode: 'analysis', rule: 'analysis-analyze-code-patterns' },
+  '评审|review|code review': { tool: 'gemini', mode: 'analysis', rule: 'analysis-review-code-quality' },
+  '诊断|debug|排查|diagnose': { tool: 'gemini', mode: 'analysis', rule: 'analysis-diagnose-bug-root-cause' },
+  '安全|security|漏洞': { tool: 'gemini', mode: 'analysis', rule: 'analysis-assess-security-risks' },
+  '性能|performance|perf': { tool: 'gemini', mode: 'analysis', rule: 'analysis-analyze-performance' },
+  '架构|architecture': { tool: 'gemini', mode: 'analysis', rule: 'analysis-review-architecture' },
+  // Write intents
+  '修复|fix|repair|解决': { tool: 'claude', mode: 'write', rule: 'development-debug-runtime-issues' },
+  '实现|implement|开发|create': { tool: 'claude', mode: 'write', rule: 'development-implement-feature' },
+  '重构|refactor': { tool: 'claude', mode: 'write', rule: 'development-refactor-codebase' },
+  '测试|test|generate test': { tool: 'claude', mode: 'write', rule: 'development-generate-tests' },
+  // Planning intents
+  '规划|plan|设计|design': { tool: 'gemini', mode: 'analysis', rule: 'planning-plan-architecture-design' },
+  '拆解|breakdown|分解': { tool: 'gemini', mode: 'analysis', rule: 'planning-breakdown-task-steps' },
+};
+
+// Match input segments to intents, produce step chain
+// See phases/01-setup.md Step 1.1b for full algorithm
+```
+
+### Workflow JSON Format (when using --file)
+
+```json
+{
+  "name": "my-workflow",
+  "description": "What this workflow achieves",
+  "steps": [
+    {
+      "name": "step-1-name",
+      "type": "skill|command|ccw-cli",
+      "command": "/skill-name args" | "ccw cli -p '...' --tool gemini --mode analysis",
+      "expected_artifacts": ["output.md", "report.json"],
+      "success_criteria": "description of what success looks like"
+    }
+  ]
+}
+```
+
+### Inline Step Parsing
+
+```javascript
+// Pipe-separated: each segment is a command
+// "ccw cli -p 'analyze' --tool gemini --mode analysis | /review-code src/ | ccw cli -p 'fix' --tool claude --mode write"
+const steps = input.split('|').map((cmd, i) => ({
+  name: `step-${i + 1}`,
+  type: cmd.trim().startsWith('/') ? 'skill' : 'command',
+  command: cmd.trim(),
+  expected_artifacts: [],
+  success_criteria: ''
+}));
+```
+
+## Pre-Execution Confirmation
+
+After parsing (all formats) or decomposition (Format 4), generate a **Command Document** and ask for user confirmation before executing.
+
+### Command Document Format
+
+```markdown
+# Workflow Tune — Execution Plan
+
+**Workflow**: {name}
+**Goal**: {context}
+**Steps**: {count}
+**Analysis Depth**: {depth}
+
+## Step Chain
+
+| # | Name | Type | Command | Tool | Mode |
+|---|------|------|---------|------|------|
+| 1 | {name} | {type} | {command} | {tool} | {mode} |
+| 2 | ... | ... | ... | ... | ... |
+
+## Execution Flow
+
+```
+Step 1: {name}
+  → Command: {command}
+  → Expected: {artifacts}
+  → Feeds into: Step 2
+       ↓
+Step 2: {name}
+  → Command: {command}
+  → Expected: {artifacts}
+  → Feeds into: Step 3
+       ↓
+  ...
+```
+
+## Estimated Scope
+
+- Total CLI calls: {N} (execute) + {N} (analyze) + 1 (synthesize)
+- Analysis tool: gemini (--resume chain)
+- Process documentation: process-log.md (accumulated)
+```
+
+### Confirmation Flow
+
+```javascript
+// ★ Skip confirmation only if -y/--yes flag
+if (!workflowPreferences.autoYes) {
+  // Display command document to user
+  // Output the formatted plan (direct text output, NOT a file)
+
+  const confirmation = AskUserQuestion({
+    questions: [{
+      question: "确认执行以上 Workflow 调优计划？",
+      header: "Confirm Execution",
+      multiSelect: false,
+      options: [
+        { label: "Execute (确认执行)", description: "按计划开始执行" },
+        { label: "Edit steps (修改步骤)", description: "我想调整某些步骤" },
+        { label: "Cancel (取消)", description: "取消本次调优" }
+      ]
+    }]
+  });
+
+  if (confirmation["Confirm Execution"].startsWith("Cancel")) {
+    // Abort workflow
+    return;
+  }
+
+  if (confirmation["Confirm Execution"].startsWith("Edit")) {
+    // Ask user for modifications
+    const editResponse = AskUserQuestion({
+      questions: [{
+        question: "请描述要修改的内容（如：删除步骤2、步骤3改用codex、在步骤1后加入安全扫描）：",
+        header: "Edit Steps"
+      }]
+    });
+    // Apply user edits to steps[] → re-display command doc → re-confirm
+    // (recursive confirmation loop until Execute or Cancel)
+  }
+}
+```
+
+## Execution Flow
+
+> **COMPACT DIRECTIVE**: Context compression MUST check TaskUpdate phase status.
+> The phase currently marked `in_progress` is the active execution phase — preserve its FULL content.
+> Only compress phases marked `completed` or `pending`.
+
+### Phase 1: Setup (one-time)
+
+Read and execute: `Ref: phases/01-setup.md`
+
+- Parse workflow steps from input (Format 1-3: direct parse, Format 4: semantic decomposition)
+- Generate Command Document (formatted execution plan)
+- **User Confirmation**: Display plan, wait for confirm/edit/cancel
+- **Generate Test Requirements**: Auto-create per-step acceptance criteria via Gemini (expected outputs, content signals, quality thresholds, pass/fail criteria, handoff contracts)
+- Create workspace at `.workflow/.scratchpad/workflow-tune-{ts}/`
+- Initialize workflow-state.json (with test_requirements per step)
+- Create process-log.md template
+
+Output: `workDir`, `steps[]` (with test_requirements), `workflowContext`, `commandDoc`, initialized state
+
+### Step Loop (Phase 2 + Phase 3, per step)
+
+```javascript
+// Track analysis session ID for resume chain
+let analysisSessionId = null;
+
+for (let stepIdx = 0; stepIdx < state.steps.length; stepIdx++) {
+  const step = state.steps[stepIdx];
+
+  TaskUpdate(stepLoopTask, {
+    subject: `Step ${stepIdx + 1}/${state.steps.length}: ${step.name}`,
+    status: 'in_progress'
+  });
+
+  // === Phase 2: Execute Step ===
+  // Read: phases/02-step-execute.md
+  // Execute command/skill → collect artifacts
+  // Write step-{N}-artifacts-manifest.json
+
+  // === Phase 3: Analyze Step ===
+  // Read: phases/03-step-analyze.md
+  // Inspect artifacts → ccw cli gemini --resume analysisSessionId
+  // Write step-{N}-analysis.md → append to process-log.md
+  // Update analysisSessionId for next step's resume
+
+  // Update state
+  state.steps[stepIdx].status = 'completed';
+  Write(`${state.work_dir}/workflow-state.json`, JSON.stringify(state, null, 2));
+}
+```
+
+### Phase 2: Execute Step (per step)
+
+Read and execute: `Ref: phases/02-step-execute.md`
+
+- Create step working directory
+- Execute command/skill via ccw cli or Skill tool
+- Collect output artifacts
+- Write artifacts manifest
+
+### Phase 3: Analyze Step (per step)
+
+Read and execute: `Ref: phases/03-step-analyze.md`
+
+- Inspect step artifacts (file list, content summary, quality signals)
+- **Compare actual output against test requirements** (pass_criteria, content_signals, fail_signals, handoff_contract)
+- Build analysis prompt with step context + test requirements + previous process log
+- Execute: `ccw cli --tool gemini --mode analysis [--resume sessionId]`
+- Parse analysis → write step-{N}-analysis.md (with requirement match: PASS/FAIL)
+- Append findings to process-log.md
+- Return analysis session ID for resume chain
+
+### Phase 4: Synthesize (one-time)
+
+Read and execute: `Ref: phases/04-synthesize.md`
+
+- Read complete process-log.md + all step analyses
+- Build synthesis prompt with full workflow context
+- Execute: `ccw cli --tool gemini --mode analysis --resume analysisSessionId`
+- Generate cross-step optimization insights
+- Write synthesis.md
+
+### Phase 5: Optimization Report (one-time)
+
+Read and execute: `Ref: phases/05-optimize-report.md`
+
+- Aggregate all analyses and synthesis
+- Generate structured optimization report
+- Optionally apply high-priority fixes (if autoFix enabled)
+- Write final-report.md
+- Display summary to user
+
+**Phase Reference Documents**:
+
+| Phase | Document | Purpose | Compact |
+|-------|----------|---------|---------|
+| 1 | [phases/01-setup.md](phases/01-setup.md) | Initialize workspace and state | TaskUpdate driven |
+| 2 | [phases/02-step-execute.md](phases/02-step-execute.md) | Execute workflow step | TaskUpdate driven |
+| 3 | [phases/03-step-analyze.md](phases/03-step-analyze.md) | Analyze step artifacts | TaskUpdate driven + resume |
+| 4 | [phases/04-synthesize.md](phases/04-synthesize.md) | Cross-step synthesis | TaskUpdate driven + resume |
+| 5 | [phases/05-optimize-report.md](phases/05-optimize-report.md) | Generate final report | TaskUpdate driven |
+
+## Data Flow
+
+```
+User Input (workflow steps / natural language + context)
+    ↓
+Phase 1: Setup
+    ├─ [Format 1-3] Direct parse → steps[]
+    ├─ [Format 4]   Semantic decompose → steps[]
+    ↓
+    Command Document (formatted plan)
+    ↓
+    User Confirmation (Execute / Edit / Cancel)
+    ↓ (Execute confirmed)
+    ↓
+    Generate Test Requirements (Gemini) → per-step acceptance criteria
+    ↓ workDir, steps[] (with test_requirements), workflow-state.json, process-log.md
+    ↓
+┌─→ Phase 2: Execute Step N (ccw cli / Skill)
+│   ↓ step-N/ artifacts
+│   ↓
+│   Phase 3: Analyze Step N (ccw cli gemini --resume)
+│   ↓ step-N-analysis.md, process-log.md updated
+│   ↓ analysisSessionId carried forward
+│   ↓
+│   [More steps?]─── YES ──→ next step (Phase 2)
+│   ↓ NO
+│   ↓
+└───┘
+    ↓
+Phase 4: Synthesize (ccw cli gemini --resume)
+    ↓ synthesis.md
+    ↓
+Phase 5: Report
+    ↓ final-report.md + optional auto-fix
+    ↓
+Done
+```
+
+## TaskUpdate Pattern
+
+```javascript
+// Initial state
+TaskCreate({ subject: "Phase 1: Setup workspace", activeForm: "Parsing workflow" })
+TaskCreate({ subject: "Step Loop", activeForm: "Executing steps" })
+TaskCreate({ subject: "Phase 4-5: Synthesize & Report", activeForm: "Pending" })
+
+// Per-step tracking
+for (const step of state.steps) {
+  TaskCreate({
+    subject: `Step: ${step.name}`,
+    activeForm: `Pending`,
+    description: `${step.type}: ${step.command}`
+  })
+}
+
+// During step execution
+TaskUpdate(stepTask, {
+  subject: `Step: ${step.name} — Executing`,
+  activeForm: `Running ${step.command}`
+})
+
+// After step analysis
+TaskUpdate(stepTask, {
+  subject: `Step: ${step.name} — Analyzed`,
+  activeForm: `Quality: ${stepQuality} | Issues: ${issueCount}`,
+  status: 'completed'
+})
+
+// Final
+TaskUpdate(synthesisTask, {
+  subject: `Synthesis & Report (${state.steps.length} steps, ${totalIssues} issues)`,
+  status: 'completed'
+})
+```
+
+## Resume Chain Strategy
+
+```
+Step 1 Execute → artifacts
+Step 1 Analyze → ccw cli gemini --mode analysis → sessionId_1
+Step 2 Execute → artifacts
+Step 2 Analyze → ccw cli gemini --mode analysis --resume sessionId_1 → sessionId_2
+  ...
+Step N Analyze → sessionId_N
+Synthesize   → ccw cli gemini --mode analysis --resume sessionId_N → final
+```
+
+Each analysis step resumes the previous session, maintaining full context of:
+- All prior step observations
+- Accumulated quality patterns
+- Cross-step dependency insights
+
+## Error Handling
+
+| Phase | Error | Recovery |
+|-------|-------|----------|
+| 2: Execute | CLI timeout/crash | Retry once, then record failure and continue to next step |
+| 2: Execute | Skill not found | Skip step, note in process-log |
+| 3: Analyze | CLI fails | Retry without --resume, start fresh session |
+| 3: Analyze | Resume session not found | Start fresh analysis session |
+| 4: Synthesize | CLI fails | Generate report from individual step analyses only |
+| Any | 3+ consecutive errors | Terminate with partial report |
+
+**Error Budget**: Each step gets 1 retry. 3 consecutive failures triggers early termination.
+
+## Core Rules
+
+1. **Start Immediately**: First action is preference collection → Phase 1 setup
+2. **Progressive Loading**: Read phase doc ONLY when that phase is about to execute
+3. **Inspect Before Proceed**: Always check step artifacts before moving to next step
+4. **Background CLI**: ccw cli runs in background, wait for hook callback before proceeding
+5. **Resume Chain**: Maintain analysis session continuity via --resume
+6. **Process Documentation**: Every step observation goes into process-log.md
+7. **Single State Source**: `workflow-state.json` is the only source of truth
+8. **DO NOT STOP**: Continuous execution until all steps processed