Claude-Code-Workflow/.claude/skills/skill-tuning/phases/orchestrator.md

Orchestrator

State-driven orchestrator for autonomous skill-tuning workflow.

Role

Read state → Select action → Execute → Update → Repeat until termination.

Decision Logic

Termination Checks (priority order)

Condition	Action
status === 'user_exit'	null (exit)
status === 'completed'	null (exit)
error_count >= max_errors	action-abort
iteration_count >= max_iterations	action-complete
quality_gate === 'pass'	action-complete

Action Selection

Priority	Condition	Action
1	status === 'pending'	action-init
2	Init done, req analysis missing	action-analyze-requirements
3	Req needs clarification	null (wait)
4	Req coverage unsatisfied	action-gemini-analysis
5	Gemini requested/critical issues	action-gemini-analysis
6	Gemini running	null (wait)
7	Diagnosis pending (in order)	action-diagnose-{type}
8	All diagnosis done, no report	action-generate-report
9	Report done, issues exist	action-propose-fixes
10	Pending fixes exist	action-apply-fix
11	Fixes need verification	action-verify
12	New iteration needed	action-diagnose-context (restart)
13	Default	action-complete

Diagnosis Order: context → memory → dataflow → agent → docs → token_consumption

Gemini Triggers:

• gemini_analysis_requested === true
• Critical issues detected
• Focus areas include: architecture, prompt, performance, custom
• Second iteration with unresolved issues

State Management

// Read
const state = JSON.parse(Read(`${workDir}/state.json`));

// Update (with sliding window for history)
function updateState(workDir, updates) {
  const state = JSON.parse(Read(`${workDir}/state.json`));
  const newState = {
    ...state,
    ...updates,
    updated_at: new Date().toISOString()
  };
  Write(`${workDir}/state.json`, JSON.stringify(newState, null, 2));
  return newState;
}

Execution Loop

async function runOrchestrator(workDir) {
  let iteration = 0;
  const MAX_LOOP = 50;

  while (iteration++ < MAX_LOOP) {
    // 1. Read state
    const state = JSON.parse(Read(`${workDir}/state.json`));

    // 2. Select action
    const actionId = selectNextAction(state);
    if (!actionId) break;

    // 3. Update: mark current action (sliding window)
    updateState(workDir, {
      current_action: actionId,
      action_history: [...state.action_history, {
        action: actionId,
        started_at: new Date().toISOString()
      }].slice(-10)  // Keep last 10
    });

    // 4. Execute action
    try {
      const actionPrompt = Read(`phases/actions/${actionId}.md`);

      // Pass state path + key fields (not full state)
      const stateKeyInfo = {
        status: state.status,
        iteration_count: state.iteration_count,
        quality_gate: state.quality_gate,
        target_skill: { name: state.target_skill.name, path: state.target_skill.path }
      };

      const result = await Task({
        subagent_type: 'universal-executor',
        run_in_background: false,
        prompt: `
[CONTEXT]
Action: ${actionId}
Work directory: ${workDir}

[STATE KEY INFO]
${JSON.stringify(stateKeyInfo, null, 2)}

[FULL STATE PATH]
${workDir}/state.json
(Read full state from this file if needed)

[ACTION INSTRUCTIONS]
${actionPrompt}

[OUTPUT]
Return JSON: { stateUpdates: {}, outputFiles: [], summary: "..." }
`
      });

      // 5. Parse result
      let actionResult = result;
      try { actionResult = JSON.parse(result); } catch {}

      // 6. Update: mark complete
      updateState(workDir, {
        current_action: null,
        completed_actions: [...state.completed_actions, actionId],
        ...actionResult.stateUpdates
      });

    } catch (error) {
      // Error handling (sliding window for errors)
      updateState(workDir, {
        current_action: null,
        errors: [...state.errors, {
          action: actionId,
          message: error.message,
          timestamp: new Date().toISOString()
        }].slice(-5),  // Keep last 5
        error_count: state.error_count + 1
      });
    }
  }
}

Action Preconditions

Action	Precondition
action-init	status='pending'
action-analyze-requirements	Init complete, not done
action-diagnose-*	status='running', focus area includes type
action-gemini-analysis	Requested OR critical issues OR high complexity
action-generate-report	All diagnosis complete
action-propose-fixes	Report generated, issues > 0
action-apply-fix	pending_fixes > 0
action-verify	applied_fixes with pending verification
action-complete	Quality gates pass OR max iterations
action-abort	error_count >= max_errors

User Interaction Points

1. action-init: Confirm target skill, describe issue
2. action-propose-fixes: Select which fixes to apply
3. action-verify: Review verification, decide to continue or stop
4. action-complete: Review final summary

Error Recovery

Error Type	Strategy
Action execution failed	Retry up to 3 times, then skip
State parse error	Restore from backup
File write error	Retry with alternative path
User abort	Save state and exit gracefully

Termination Conditions

• Normal: status === 'completed', quality_gate === 'pass'
• User: status === 'user_exit'
• Error: status === 'failed', error_count >= max_errors
• Iteration limit: iteration_count >= max_iterations
• Clarification wait: requirement_analysis.status === 'needs_clarification' (pause, not terminate)