claude-code-workflow 7.2.10 → 7.2.11

package/.claude/skills/workflow-tune/phases/02-step-execute.md

@@ -0,0 +1,197 @@
+# Phase 2: Execute Step
+
+> **COMPACT SENTINEL [Phase 2: Execute Step]**
+> This phase contains 4 execution steps (Step 2.1 -- 2.4).
+> If you can read this sentinel but cannot find the full Step protocol below, context has been compressed.
+> Recovery: `Read("phases/02-step-execute.md")`
+
+Execute a single workflow step and collect its output artifacts.
+
+## Objective
+
+- Determine step execution method (skill invoke / ccw cli / shell command)
+- Execute step with appropriate tool
+- Collect output artifacts into step directory
+- Write artifacts manifest
+
+## Execution
+
+### Step 2.1: Prepare Step Directory
+
+```javascript
+const stepIdx = currentStepIndex;  // from orchestrator loop
+const step = state.steps[stepIdx];
+const stepDir = `${state.work_dir}/steps/step-${stepIdx + 1}`;
+const artifactsDir = `${stepDir}/artifacts`;
+
+// Capture pre-execution state (git status, file timestamps)
+const preGitStatus = Bash('git status --porcelain 2>/dev/null || echo "not a git repo"').stdout;
+
+// ★ Warn if dirty git working directory (first step only)
+if (stepIdx === 0 && preGitStatus.trim() && preGitStatus.trim() !== 'not a git repo') {
+  const dirtyLines = preGitStatus.trim().split('\n').length;
+  // Log warning — artifact collection via git diff may be unreliable
+  // This is informational; does not block execution
+  console.warn(`⚠ Dirty git working directory detected (${dirtyLines} changed files). Artifact collection via git diff may include pre-existing changes.`);
+}
+
+const preExecSnapshot = {
+  timestamp: new Date().toISOString(),
+  git_status: preGitStatus,
+  working_files: Glob('**/*.{ts,js,md,json}').slice(0, 50)  // sample
+};
+Write(`${stepDir}/pre-exec-snapshot.json`, JSON.stringify(preExecSnapshot, null, 2));
+```
+
+### Step 2.2: Execute by Step Type
+
+```javascript
+let executionResult = { success: false, method: '', output: '', duration: 0 };
+const startTime = Date.now();
+
+switch (step.type) {
+  case 'skill': {
+    // Skill invocation — use Skill tool
+    // Extract skill name and arguments from command
+    const skillCmd = step.command.replace(/^\//, '');
+    const [skillName, ...skillArgs] = skillCmd.split(/\s+/);
+
+    // Execute skill (this runs synchronously within current context)
+    // Note: Skill execution produces artifacts in the working directory
+    // We capture changes by comparing pre/post state
+    Skill({
+      name: skillName,
+      arguments: skillArgs.join(' ')
+    });
+
+    executionResult.method = 'skill';
+    executionResult.success = true;
+    break;
+  }
+
+  case 'ccw-cli': {
+    // Direct ccw cli command
+    const cliCommand = step.command;
+
+    Bash({
+      command: cliCommand,
+      run_in_background: true,
+      timeout: 600000  // 10 minutes
+    });
+
+    // STOP — wait for hook callback
+    // After callback:
+    executionResult.method = 'ccw-cli';
+    executionResult.success = true;
+    break;
+  }
+
+  case 'command': {
+    // Generic shell command
+    const result = Bash({
+      command: step.command,
+      timeout: 300000  // 5 minutes
+    });
+
+    executionResult.method = 'command';
+    executionResult.output = result.stdout || '';
+    executionResult.success = result.exitCode === 0;
+
+    // Save command output
+    if (executionResult.output) {
+      Write(`${artifactsDir}/command-output.txt`, executionResult.output);
+    }
+    if (result.stderr) {
+      Write(`${artifactsDir}/command-stderr.txt`, result.stderr);
+    }
+    break;
+  }
+}
+
+executionResult.duration = Date.now() - startTime;
+```
+
+### Step 2.3: Collect Artifacts
+
+```javascript
+// Capture post-execution state
+const postExecSnapshot = {
+  timestamp: new Date().toISOString(),
+  git_status: Bash('git status --porcelain 2>/dev/null || echo "not a git repo"').stdout,
+  working_files: Glob('**/*.{ts,js,md,json}').slice(0, 50)
+};
+
+// Detect changed/new files by comparing snapshots
+const preFiles = new Set(preExecSnapshot.working_files);
+const newOrChanged = postExecSnapshot.working_files.filter(f => !preFiles.has(f));
+
+// Also check git diff for modified files
+const gitDiff = Bash('git diff --name-only 2>/dev/null || true').stdout.trim().split('\n').filter(Boolean);
+
+// Collect all artifacts (new files + git-changed files + declared expected_artifacts)
+const declaredArtifacts = (step.expected_artifacts || []).filter(f => {
+  // Verify declared artifacts actually exist
+  const exists = Glob(f);
+  return exists.length > 0;
+}).flatMap(f => Glob(f));
+
+const allArtifacts = [...new Set([...newOrChanged, ...gitDiff, ...declaredArtifacts])];
+
+// Copy detected artifacts to step artifacts dir (or record references)
+const artifactManifest = {
+  step: step.name,
+  step_index: stepIdx,
+  execution_method: executionResult.method,
+  success: executionResult.success,
+  duration_ms: executionResult.duration,
+  artifacts: allArtifacts.map(f => ({
+    path: f,
+    type: f.endsWith('.md') ? 'markdown' : f.endsWith('.json') ? 'json' : 'other',
+    size: 'unknown'  // Can be filled by stat if needed
+  })),
+  // For skill type: also check .workflow/.scratchpad for generated files
+  scratchpad_files: step.type === 'skill'
+    ? Glob('.workflow/.scratchpad/**/*').filter(f => {
+        // Only include files created after step started
+        return true;  // Heuristic: include recent scratchpad files
+      }).slice(0, 20)
+    : [],
+  collected_at: new Date().toISOString()
+};
+
+Write(`${stepDir}/artifacts-manifest.json`, JSON.stringify(artifactManifest, null, 2));
+```
+
+### Step 2.4: Update State
+
+```javascript
+state.steps[stepIdx].status = 'executed';
+state.steps[stepIdx].execution = {
+  method: executionResult.method,
+  success: executionResult.success,
+  duration_ms: executionResult.duration,
+  artifacts_dir: artifactsDir,
+  manifest_path: `${stepDir}/artifacts-manifest.json`,
+  artifact_count: artifactManifest.artifacts.length,
+  started_at: preExecSnapshot.timestamp,
+  completed_at: new Date().toISOString()
+};
+
+state.updated_at = new Date().toISOString();
+Write(`${state.work_dir}/workflow-state.json`, JSON.stringify(state, null, 2));
+```
+
+## Error Handling
+
+| Error | Recovery |
+|-------|----------|
+| Skill not found | Record failure, set success=false, continue to Phase 3 |
+| CLI timeout (10min) | Retry once with shorter timeout, then record failure |
+| Command exit non-zero | Record stderr, set success=false, continue to Phase 3 |
+| No artifacts detected | Continue to Phase 3 — analysis evaluates step definition quality |
+
+## Output
+
+- **Files**: `pre-exec-snapshot.json`, `artifacts-manifest.json`, `artifacts/` (if command type)
+- **State**: `steps[stepIdx].execution` updated
+- **Next**: Phase 3 (Analyze Step)

package/.claude/skills/workflow-tune/phases/03-step-analyze.md

@@ -0,0 +1,386 @@
+# Phase 3: Analyze Step
+
+> **COMPACT SENTINEL [Phase 3: Analyze Step]**
+> This phase contains 5 execution steps (Step 3.1 -- 3.5).
+> If you can read this sentinel but cannot find the full Step protocol below, context has been compressed.
+> Recovery: `Read("phases/03-step-analyze.md")`
+
+Analyze a completed step's artifacts and quality using `ccw cli --tool gemini --mode analysis`. Uses `--resume` to maintain context across step analyses, building a continuous analysis chain.
+
+## Objective
+
+- Inspect step artifacts (file list, content, quality signals)
+- Build analysis prompt with step context + prior process log
+- Execute via ccw cli Gemini with resume chain
+- Parse analysis results → write step-{N}-analysis.md
+- Append findings to process-log.md
+- Return updated session ID for resume chain
+
+## Execution
+
+### Step 3.1: Inspect Artifacts
+
+```javascript
+const stepIdx = currentStepIndex;
+const step = state.steps[stepIdx];
+const stepDir = `${state.work_dir}/steps/step-${stepIdx + 1}`;
+
+// Read artifacts manifest
+const manifest = JSON.parse(Read(`${stepDir}/artifacts-manifest.json`));
+
+// Build artifact summary based on analysis depth
+let artifactSummary = '';
+
+if (state.analysis_depth === 'quick') {
+  // Quick: just file list and sizes
+  artifactSummary = `Artifacts (${manifest.artifacts.length} files):\n` +
+    manifest.artifacts.map(a => `- ${a.path} (${a.type})`).join('\n');
+} else {
+  // Standard/Deep: include file content summaries
+  artifactSummary = manifest.artifacts.map(a => {
+    const maxLines = state.analysis_depth === 'deep' ? 300 : 150;
+    try {
+      const content = Read(a.path, { limit: maxLines });
+      return `--- ${a.path} (${a.type}) ---\n${content}`;
+    } catch {
+      return `--- ${a.path} --- [unreadable]`;
+    }
+  }).join('\n\n');
+
+  // Deep: also include scratchpad files
+  if (state.analysis_depth === 'deep' && manifest.scratchpad_files?.length > 0) {
+    artifactSummary += '\n\n--- Scratchpad Files ---\n' +
+      manifest.scratchpad_files.slice(0, 5).map(f => {
+        const content = Read(f, { limit: 100 });
+        return `--- ${f} ---\n${content}`;
+      }).join('\n\n');
+  }
+}
+
+// Execution result summary
+const execSummary = `Execution: ${step.execution.method} | ` +
+  `Success: ${step.execution.success} | ` +
+  `Duration: ${step.execution.duration_ms}ms | ` +
+  `Artifacts: ${manifest.artifacts.length} files`;
+```
+
+### Step 3.2: Build Prior Context
+
+```javascript
+// Build accumulated process log context for this analysis
+const priorProcessLog = Read(`${state.work_dir}/process-log.md`);
+
+// Build step chain context (what came before, what comes after)
+const stepChainContext = state.steps.map((s, i) => {
+  const status = i < stepIdx ? 'completed' : i === stepIdx ? 'CURRENT' : 'pending';
+  const score = s.analysis?.quality_score || '-';
+  return `${i + 1}. [${status}] ${s.name} (${s.type}) — Quality: ${score}`;
+}).join('\n');
+
+// Previous step handoff context (if not first step)
+let handoffContext = '';
+if (stepIdx > 0) {
+  const prevStep = state.steps[stepIdx - 1];
+  const prevAnalysis = prevStep.analysis;
+  if (prevAnalysis) {
+    handoffContext = `PREVIOUS STEP OUTPUT SUMMARY:
+Step "${prevStep.name}" produced ${prevStep.execution?.artifact_count || 0} artifacts.
+Quality: ${prevAnalysis.quality_score}/100
+Key outputs: ${prevAnalysis.key_outputs?.join(', ') || 'unknown'}
+Handoff notes: ${prevAnalysis.handoff_notes || 'none'}`;
+  }
+}
+```
+
+### Step 3.3: Construct Analysis Prompt
+
+```javascript
+// Ref: templates/step-analysis-prompt.md
+
+const depthInstructions = {
+  quick: 'Provide brief assessment (3-5 bullet points). Focus on: execution success, output completeness, obvious issues.',
+  standard: 'Provide detailed assessment. Cover: execution quality, output completeness, artifact quality, step-to-step handoff readiness, potential issues.',
+  deep: 'Provide exhaustive assessment. Cover: execution quality, output completeness and correctness, artifact quality and structure, step-to-step handoff integrity, error handling, performance signals, architecture implications, edge cases.'
+};
+
+// ★ Build test requirements section (the evaluation baseline)
+const testReqs = step.test_requirements;
+let testReqSection = '';
+if (testReqs) {
+  testReqSection = `
+TEST REQUIREMENTS (Acceptance Criteria — use these as the PRIMARY evaluation baseline):
+  Pass Criteria: ${testReqs.pass_criteria}
+  Expected Outputs: ${(testReqs.expected_outputs || []).join(', ') || 'not specified'}
+  Content Signals (patterns that indicate success): ${(testReqs.content_signals || []).join(', ') || 'not specified'}
+  Quality Thresholds: ${(testReqs.quality_thresholds || []).join(', ') || 'not specified'}
+  Fail Signals (patterns that indicate failure): ${(testReqs.fail_signals || []).join(', ') || 'not specified'}
+  Handoff Contract (what next step needs): ${testReqs.handoff_contract || 'not specified'}
+
+IMPORTANT: Score quality_score based on how well the actual output matches these test requirements.
+  - 90-100: All pass_criteria met, all expected_outputs present, content_signals found, no fail_signals
+  - 70-89: Most criteria met, minor gaps
+  - 50-69: Partial match, significant gaps
+  - 0-49: Fail — fail_signals present or pass_criteria not met`;
+} else {
+  testReqSection = `
+NOTE: No pre-generated test requirements for this step. Evaluate based on general quality signals and workflow context.`;
+}
+
+const analysisPrompt = `PURPOSE: Evaluate workflow step "${step.name}" (step ${stepIdx + 1}/${state.steps.length}) against its acceptance criteria. Judge whether the command execution met the pre-defined test requirements.
+
+WORKFLOW CONTEXT:
+Name: ${state.workflow_name}
+Goal: ${state.workflow_context}
+Step Chain:
+${stepChainContext}
+
+CURRENT STEP:
+Name: ${step.name}
+Type: ${step.type}
+Command: ${step.command}
+${step.success_criteria ? `Success Criteria: ${step.success_criteria}` : ''}
+${testReqSection}
+
+EXECUTION RESULT:
+${execSummary}
+
+${handoffContext}
+
+STEP ARTIFACTS:
+${artifactSummary}
+
+ANALYSIS DEPTH: ${state.analysis_depth}
+${depthInstructions[state.analysis_depth]}
+
+TASK:
+1. **Requirement Matching**: Compare actual output against test requirements (pass_criteria, expected_outputs, content_signals)
+2. **Fail Signal Detection**: Check for any fail_signals in the output
+3. **Handoff Contract Verification**: Does the output satisfy handoff_contract for the next step?
+4. **Gap Analysis**: What's missing between actual output and requirements?
+5. **Quality Score**: Rate 0-100 based on requirement fulfillment (NOT general quality)
+
+EXPECTED OUTPUT (strict JSON, no markdown):
+{
+  "quality_score": <0-100>,
+  "requirement_match": {
+    "pass": <true|false>,
+    "criteria_met": ["<which pass_criteria were satisfied>"],
+    "criteria_missed": ["<which pass_criteria were NOT satisfied>"],
+    "expected_outputs_found": ["<expected files that exist>"],
+    "expected_outputs_missing": ["<expected files that are absent>"],
+    "content_signals_found": ["<success patterns detected in output>"],
+    "content_signals_missing": ["<success patterns NOT found>"],
+    "fail_signals_detected": ["<failure patterns found, if any>"]
+  },
+  "execution_assessment": {
+    "success": <true|false>,
+    "completeness": "<complete|partial|failed>",
+    "notes": "<brief assessment>"
+  },
+  "artifact_assessment": {
+    "count": <number>,
+    "quality": "<high|medium|low>",
+    "key_outputs": ["<main output 1>", "<main output 2>"],
+    "missing_outputs": ["<expected but missing>"]
+  },
+  "handoff_assessment": {
+    "ready": <true|false>,
+    "contract_satisfied": <true|false|null>,
+    "next_step_compatible": <true|false|null>,
+    "handoff_notes": "<what next step should know>"
+  },
+  "issues": [
+    { "severity": "high|medium|low", "description": "<issue>", "suggestion": "<fix>" }
+  ],
+  "optimization_opportunities": [
+    { "area": "<area>", "description": "<opportunity>", "impact": "high|medium|low" }
+  ],
+  "step_summary": "<1-2 sentence summary for process log>"
+}
+
+CONSTRAINTS: Be specific, reference artifact content where possible, score against requirements not general quality, output ONLY JSON`;
+```
+
+### Step 3.4: Execute via ccw cli Gemini with Resume
+
+```javascript
+function escapeForShell(str) {
+  return str.replace(/"/g, '\\"').replace(/\$/g, '\\$').replace(/`/g, '\\`');
+}
+
+// Build CLI command with optional resume
+let cliCommand = `ccw cli -p "${escapeForShell(analysisPrompt)}" --tool gemini --mode analysis`;
+
+// Resume from previous step's analysis session (maintains context chain)
+if (state.analysis_session_id) {
+  cliCommand += ` --resume ${state.analysis_session_id}`;
+}
+
+Bash({
+  command: cliCommand,
+  run_in_background: true,
+  timeout: 300000  // 5 minutes
+});
+
+// STOP — wait for hook callback
+```
+
+### Step 3.5: Parse Results and Update Process Log
+
+After CLI completes:
+
+```javascript
+const rawOutput = /* CLI output from callback */;
+
+// Extract session ID from CLI output for resume chain
+const sessionIdMatch = rawOutput.match(/\[CCW_EXEC_ID=([^\]]+)\]/);
+if (sessionIdMatch) {
+  state.analysis_session_id = sessionIdMatch[1];
+}
+
+// Parse JSON
+const jsonMatch = rawOutput.match(/\{[\s\S]*\}/);
+let analysis;
+
+if (jsonMatch) {
+  try {
+    analysis = JSON.parse(jsonMatch[0]);
+  } catch (e) {
+    // Fallback: extract score heuristically
+    const scoreMatch = rawOutput.match(/"quality_score"\s*:\s*(\d+)/);
+    analysis = {
+      quality_score: scoreMatch ? parseInt(scoreMatch[1]) : 50,
+      execution_assessment: { success: step.execution.success, completeness: 'unknown', notes: 'Parse failed' },
+      artifact_assessment: { count: manifest.artifacts.length, quality: 'unknown', key_outputs: [], missing_outputs: [] },
+      handoff_assessment: { ready: true, next_step_compatible: null, handoff_notes: '' },
+      issues: [{ severity: 'low', description: 'Analysis output parsing failed', suggestion: 'Review raw output' }],
+      optimization_opportunities: [],
+      step_summary: 'Analysis parsing failed — raw output saved for manual review'
+    };
+  }
+} else {
+  analysis = {
+    quality_score: 50,
+    step_summary: 'No structured analysis output received'
+  };
+}
+
+// Write step analysis file
+const reqMatch = analysis.requirement_match;
+const reqMatchSection = reqMatch ? `
+## Requirement Match — ${reqMatch.pass ? 'PASS ✓' : 'FAIL ✗'}
+
+### Criteria Met
+${(reqMatch.criteria_met || []).map(c => `- ✓ ${c}`).join('\n') || '- None'}
+
+### Criteria Missed
+${(reqMatch.criteria_missed || []).map(c => `- ✗ ${c}`).join('\n') || '- None'}
+
+### Expected Outputs
+- Found: ${(reqMatch.expected_outputs_found || []).join(', ') || 'None'}
+- Missing: ${(reqMatch.expected_outputs_missing || []).join(', ') || 'None'}
+
+### Content Signals
+- Detected: ${(reqMatch.content_signals_found || []).join(', ') || 'None'}
+- Missing: ${(reqMatch.content_signals_missing || []).join(', ') || 'None'}
+
+### Fail Signals
+${(reqMatch.fail_signals_detected || []).length > 0
+  ? (reqMatch.fail_signals_detected || []).map(f => `- ⚠ ${f}`).join('\n')
+  : '- None detected'}
+` : '';
+
+const stepAnalysisReport = `# Step ${stepIdx + 1} Analysis: ${step.name}
+
+**Quality Score**: ${analysis.quality_score}/100
+**Requirement Match**: ${reqMatch ? (reqMatch.pass ? 'PASS' : 'FAIL') : 'N/A (no test requirements)'}
+**Date**: ${new Date().toISOString()}
+${reqMatchSection}
+## Execution
+- Success: ${analysis.execution_assessment?.success}
+- Completeness: ${analysis.execution_assessment?.completeness}
+- Notes: ${analysis.execution_assessment?.notes}
+
+## Artifacts
+- Count: ${analysis.artifact_assessment?.count}
+- Quality: ${analysis.artifact_assessment?.quality}
+- Key Outputs: ${analysis.artifact_assessment?.key_outputs?.join(', ') || 'N/A'}
+- Missing: ${analysis.artifact_assessment?.missing_outputs?.join(', ') || 'None'}
+
+## Handoff Readiness
+- Ready: ${analysis.handoff_assessment?.ready}
+- Contract Satisfied: ${analysis.handoff_assessment?.contract_satisfied}
+- Next Step Compatible: ${analysis.handoff_assessment?.next_step_compatible}
+- Notes: ${analysis.handoff_assessment?.handoff_notes}
+
+## Issues
+${(analysis.issues || []).map(i => `- [${i.severity}] ${i.description} → ${i.suggestion}`).join('\n') || 'None'}
+
+## Optimization Opportunities
+${(analysis.optimization_opportunities || []).map(o => `- [${o.impact}] ${o.area}: ${o.description}`).join('\n') || 'None'}
+`;
+
+Write(`${stepDir}/step-${stepIdx + 1}-analysis.md`, stepAnalysisReport);
+
+// Append to process log
+const reqPassStr = reqMatch ? (reqMatch.pass ? 'PASS' : 'FAIL') : 'N/A';
+const processLogEntry = `
+## Step ${stepIdx + 1}: ${step.name} — Score: ${analysis.quality_score}/100 | Req: ${reqPassStr}
+
+**Command**: \`${step.command}\`
+**Result**: ${analysis.execution_assessment?.completeness || 'unknown'} | ${analysis.artifact_assessment?.count || 0} artifacts
+**Requirement Match**: ${reqPassStr}${reqMatch ? ` — Met: ${(reqMatch.criteria_met || []).length}, Missed: ${(reqMatch.criteria_missed || []).length}, Fail Signals: ${(reqMatch.fail_signals_detected || []).length}` : ''}
+**Summary**: ${analysis.step_summary || 'No summary'}
+**Issues**: ${(analysis.issues || []).filter(i => i.severity === 'high').map(i => i.description).join('; ') || 'None critical'}
+**Handoff**: ${analysis.handoff_assessment?.contract_satisfied ? 'Contract satisfied' : analysis.handoff_assessment?.handoff_notes || 'Ready'}
+
+---
+`;
+
+// Append to process-log.md
+const currentLog = Read(`${state.work_dir}/process-log.md`);
+Write(`${state.work_dir}/process-log.md`, currentLog + processLogEntry);
+
+// Update state
+state.steps[stepIdx].analysis = {
+  quality_score: analysis.quality_score,
+  requirement_pass: reqMatch?.pass ?? null,
+  criteria_met_count: (reqMatch?.criteria_met || []).length,
+  criteria_missed_count: (reqMatch?.criteria_missed || []).length,
+  fail_signals_count: (reqMatch?.fail_signals_detected || []).length,
+  key_outputs: analysis.artifact_assessment?.key_outputs || [],
+  handoff_notes: analysis.handoff_assessment?.handoff_notes || '',
+  contract_satisfied: analysis.handoff_assessment?.contract_satisfied ?? null,
+  issue_count: (analysis.issues || []).length,
+  high_issues: (analysis.issues || []).filter(i => i.severity === 'high').length,
+  optimization_count: (analysis.optimization_opportunities || []).length,
+  analysis_file: `${stepDir}/step-${stepIdx + 1}-analysis.md`
+};
+state.steps[stepIdx].status = 'analyzed';
+
+state.process_log_entries.push({
+  step_index: stepIdx,
+  step_name: step.name,
+  quality_score: analysis.quality_score,
+  summary: analysis.step_summary,
+  timestamp: new Date().toISOString()
+});
+
+state.updated_at = new Date().toISOString();
+Write(`${state.work_dir}/workflow-state.json`, JSON.stringify(state, null, 2));
+```
+
+## Error Handling
+
+| Error | Recovery |
+|-------|----------|
+| CLI timeout | Retry once without --resume (fresh session) |
+| Resume session not found | Start fresh analysis session, continue |
+| JSON parse fails | Extract score heuristically, save raw output |
+| No output | Default score 50, minimal process log entry |
+
+## Output
+
+- **Files**: `step-{N}-analysis.md`, updated `process-log.md`
+- **State**: `steps[stepIdx].analysis` updated, `analysis_session_id` updated
+- **Next**: Phase 2 for next step, or Phase 4 (Synthesize) if all steps done