Claude-Code-Workflow/.claude/skills/skill-generator/specs/execution-modes.md

Execution Modes Specification

Detailed specification definitions for two Skill execution modes.

---

Mode Overview

Feature	Sequential (Fixed Order)	Autonomous (Dynamic)
Execution Order	Fixed (numeric prefix)	Dynamic (orchestrator decision)
Phase Dependencies	Strong dependencies	Weak/no dependencies
State Management	Implicit (phase output)	Explicit (state file)
Use Cases	Pipeline tasks	Interactive tasks
Complexity	Low	Medium-High
Extensibility	Insert sub-phases	Add new actions

---

Mode 1: Sequential (Fixed Order Mode)

Definition

Phases execute linearly in fixed order, with each phase's output serving as input to the next phase.

Directory Structure

phases/
├── 01-{first-step}.md
├── 02-{second-step}.md
├── 02.5-{sub-step}.md      # Optional: sub-phase
├── 03-{third-step}.md
└── ...

Execution Flow

┌─────────┐     ┌─────────┐     ┌─────────┐
│Phase 01 │────▶│Phase 02 │────▶│Phase 03 │────▶ ...
└─────────┘     └─────────┘     └─────────┘
     │               │               │
     ▼               ▼               ▼
  output1.json   output2.md      output3.md

Phase File Specification

# Phase N: {Phase Name}

{One-sentence description}

## Objective

{Detailed objective}

## Input

- Dependencies: {Previous phase output}
- Configuration: {Configuration file}

## Execution Steps

### Step 1: {Step}
{Execution code or description}

### Step 2: {Step}
{Execution code or description}

## Output

- **File**: `{Output file}`
- **Format**: {JSON/Markdown}

## Next Phase

→ [Phase N+1: xxx](0N+1-xxx.md)

Applicable Scenarios

• Document Generation: Collect → Analyze → Assemble → Optimize
• Code Analysis: Scan → Parse → Report
• Data Processing: Extract → Transform → Load

Advantages

• Clear logic, easy to understand
• Simple debugging, can validate phase by phase
• Predictable output

Disadvantages

• Low flexibility
• Difficult to handle branching logic
• Limited user interaction

---

Mode 2: Autonomous (Dynamic Mode)

Definition

No fixed execution order. The orchestrator dynamically selects the next action based on current state.

Directory Structure

phases/
├── orchestrator.md          # Orchestrator: core decision logic
├── state-schema.md          # State structure definition
└── actions/                 # Independent actions (no order)
    ├── action-{a}.md
    ├── action-{b}.md
    ├── action-{c}.md
    └── ...

Core Components

1. Orchestrator

# Orchestrator

## Role

Select and execute the next action based on current state.

## State Reading

Read state file: `{workDir}/state.json`

## Decision Logic

```javascript
function selectNextAction(state) {
  // 1. Check termination conditions
  if (state.status === 'completed') return null;
  if (state.error_count > MAX_RETRIES) return 'action-abort';

  // 2. Select action based on state
  if (!state.initialized) return 'action-init';
  if (state.pending_items.length > 0) return 'action-process';
  if (state.needs_review) return 'action-review';

  // 3. Default action
  return 'action-complete';
}

Execution Loop

while (true) {
  state = readState();
  action = selectNextAction(state);
  if (!action) break;

  result = executeAction(action, state);
  updateState(result);
}

#### 2. State Schema

```markdown
# State Schema

## State File

Location: `{workDir}/state.json`

## Structure Definition

```typescript
interface SkillState {
  // Metadata
  skill_name: string;
  started_at: string;
  updated_at: string;

  // Execution state
  status: 'pending' | 'running' | 'completed' | 'failed';
  current_action: string | null;
  completed_actions: string[];

  // Business data
  context: Record<string, any>;
  pending_items: any[];
  results: Record<string, any>;

  // Error tracking
  errors: Array<{
    action: string;
    message: string;
    timestamp: string;
  }>;
  error_count: number;
}

Initial State

{
  "skill_name": "{skill-name}",
  "started_at": "{ISO8601}",
  "updated_at": "{ISO8601}",
  "status": "pending",
  "current_action": null,
  "completed_actions": [],
  "context": {},
  "pending_items": [],
  "results": {},
  "errors": [],
  "error_count": 0
}

#### 3. Action

```markdown
# Action: {action-name}

## Purpose

{Action purpose}

## Preconditions

- [ ] Condition 1
- [ ] Condition 2

## Execution

{Execution logic}

## State Updates

```javascript
return {
  completed_actions: [...state.completed_actions, 'action-name'],
  results: {
    ...state.results,
    action_name: { /* result */ }
  },
  // Other state updates
};

Next Actions (Hints)

• On success: action-{next}
• On failure: action-retry or action-abort

### Execution Flow

┌─────────────────────────────────────────────────────────────────┐ │ Orchestrator Loop │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │ Read │────▶│ Select │────▶│ Execute │ │ │ │ │ │ State │ │ Action │ │ Action │ │ │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ ▲ │ │ │ │ │ │ ▼ │ │ │ │ │ ┌──────────┐ │ │ │ │ └───────────│ Update │◀────────────────────────┘ │ │ │ │ State │ │ │ │ └──────────┘ │ │ │ │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────┐ │ │ │ Termination? │ │ │ │ - completed │ │ │ │ - max_retries │ │ │ │ - user_abort │ │ │ └──────────────────┘ │ └─────────────────────────────────────────────────────────────────┘

### Action Catalog

Defined in `specs/action-catalog.md`:

```markdown
# Action Catalog

## Available Actions

| Action | Purpose | Preconditions | Effects |
|--------|---------|---------------|---------|
| action-init | Initialize state | status=pending | status=running |
| action-process | Process pending items | pending_items.length>0 | pending_items-- |
| action-review | User review | needs_review=true | needs_review=false |
| action-complete | Complete task | pending_items.length=0 | status=completed |
| action-abort | Abort task | error_count>MAX | status=failed |

## Action Dependencies Graph

```mermaid
graph TD
    INIT[action-init] --> PROCESS[action-process]
    PROCESS --> PROCESS
    PROCESS --> REVIEW[action-review]
    REVIEW --> PROCESS
    REVIEW --> COMPLETE[action-complete]
    PROCESS --> ABORT[action-abort]

### Applicable Scenarios

- **Interactive Tasks**: Q&A, dialog, form filling
- **State Machine Tasks**: Issue management, workflow approval
- **Exploratory Tasks**: Debugging, diagnosis, search

### Advantages

- Highly flexible, adapts to dynamic requirements
- Supports complex branching logic
- Easy to extend with new actions

### Disadvantages

- High complexity
- State management overhead
- Large debugging difficulty

---

## Mode Selection Guide

### Decision Flow

Analyze user requirements │ ▼ ┌────────────────────────────┐ │ Are there strong │ │ dependencies between │ │ phases? │ └────────────────────────────┘ │ ├── Yes → Sequential │ └── No → Continue decision │ ▼ ┌────────────────────────────┐ │ Do you need dynamic │ │ response to user intent? │ └────────────────────────────┘ │ ├── Yes → Autonomous │ └── No → Sequential

### Quick Decision Table

| Question | Sequential | Autonomous |
|----------|------------|------------|
| Is output structure fixed? | Yes | No |
| Do you need multi-turn user interaction? | No | Yes |
| Can phases be skipped/repeated? | No | Yes |
| Is there complex branching logic? | No | Yes |
| Should debugging be simple? | Yes | No |

---

## Hybrid Mode

Some complex Skills may need to use both modes in combination:

phases/ ├── 01-init.md # Sequential: initialization ├── 02-orchestrator.md # Autonomous: core interaction loop │ └── actions/ │ ├── action-a.md │ └── action-b.md └── 03-finalize.md # Sequential: finalization

**Applicable Scenarios**:
- Initialization and finalization are fixed, middle interaction is flexible
- Multi-phase tasks where certain phases need dynamic decisions