workflow-skill-designer

# Workflow Skill Designer

Meta-skill for creating structured workflow skills following the orchestrator + phases pattern. Generates complete skill packages with SKILL.md as coordinator and phases/ folder for execution details.

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────────┐
│  Workflow Skill Designer                                         │
│  → Analyze requirements → Design orchestrator → Generate phases  │
└───────────────┬─────────────────────────────────────────────────┘
                │
    ┌───────────┼───────────┬───────────┐
    ↓           ↓           ↓           ↓
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Phase 1 │ │ Phase 2 │ │ Phase 3 │ │ Phase 4 │
│ Require │ │  Orch   │ │ Phases  │ │ Valid   │
│ Analysis│ │ Design  │ │ Design  │ │ & Integ │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
     ↓           ↓           ↓           ↓
  workflow    SKILL.md    phases/     Complete
  config     generated   0N-*.md     skill pkg
```

## Target Output Structure

The skill this meta-skill produces follows this structure:

```
.claude/skills/{skill-name}/
├── SKILL.md                    # Orchestrator: coordination, data flow, TodoWrite
├── phases/
│   ├── 01-{phase-name}.md      # Phase execution detail (full content)
│   ├── 02-{phase-name}.md
│   ├── ...
│   └── 0N-{phase-name}.md
├── specs/                      # [Optional] Domain specifications
└── templates/                  # [Optional] Reusable templates
```

## Core Design Patterns

Patterns extracted from successful workflow skill implementations (workflow-plan, project-analyze, etc.):

### Pattern 1: Orchestrator + Progressive Loading

**SKILL.md** = Pure coordinator. Contains:
- Architecture diagram (ASCII)
- Execution flow with `Ref: phases/0N-xxx.md` markers
- Phase Reference Documents table (read on-demand)
- Data flow between phases
- Core rules and error handling

**Phase files** = Full execution detail. Contains:
- Complete agent prompts, bash commands, code implementations
- Validation checklists, error handling
- Input/Output specification
- Next Phase link

**Key Rule**: SKILL.md references phase docs via `Ref:` markers. Phase docs are read **only when that phase executes**, not all at once.

### Pattern 2: TodoWrite Attachment/Collapse

```
Phase starts:
  → Sub-tasks ATTACHED to TodoWrite (in_progress + pending)
  → Orchestrator executes sub-tasks sequentially

Phase ends:
  → Sub-tasks COLLAPSED back to high-level summary (completed)
  → Next phase begins
```

### Pattern 3: Inter-Phase Data Flow

```
Phase N output → stored in memory/variable → Phase N+1 input
                  └─ or written to session file for persistence
```

Each phase receives outputs from prior phases via:
- In-memory variables (sessionId, contextPath, etc.)
- Session directory files (.workflow/active/{sessionId}/...)
- Planning notes (accumulated constraints document)

### Pattern 4: Conditional Phase Execution

```
Phase N output contains condition flag
  ├─ condition met → Execute Phase N+1
  └─ condition not met → Skip to Phase N+2
```

### Pattern 5: Input Structuring

User input (free text) → Structured format before Phase 1:
```
GOAL: [objective]
SCOPE: [boundaries]
CONTEXT: [background/constraints]
```

### Pattern 6: Interactive Preference Collection (SKILL.md Responsibility)

Workflow preferences (auto mode, force explore, etc.) MUST be collected via AskUserQuestion in SKILL.md **before** dispatching to phases. Phases reference these as `workflowPreferences.{key}` context variables.

**Anti-Pattern**: Command-line flags (`--yes`, `-e`, `--explore`) parsed within phase files via `$ARGUMENTS.includes(...)`.

```javascript
// CORRECT: In SKILL.md (before phase dispatch)
const prefResponse = AskUserQuestion({
  questions: [
    { question: "是否跳过确认？", header: "Auto Mode", options: [
      { label: "Interactive (Recommended)", description: "交互模式" },
      { label: "Auto", description: "跳过所有确认" }
    ]}
  ]
})
workflowPreferences = { autoYes: prefResponse.autoMode === 'Auto' }

// CORRECT: In phase files (reference only)
const autoYes = workflowPreferences.autoYes

// WRONG: In phase files (flag parsing)
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
```

### Pattern 7: Direct Phase Handoff

When one phase needs to invoke another phase within the same skill, read and execute the phase document directly. Do NOT use Skill() routing back through SKILL.md.

```javascript
// CORRECT: Direct handoff (executionContext already set)
Read("phases/02-lite-execute.md")
// Execute with executionContext (Mode 1)

// WRONG: Skill routing (unnecessary round-trip)
Skill(skill="workflow-lite-plan", args="--in-memory")
```

### Pattern 8: Phase File Hygiene

Phase files are internal execution documents. They MUST NOT contain:

| Prohibited | Reason | Correct Location |
|------------|--------|------------------|
| Flag parsing (`$ARGUMENTS.includes(...)`) | Preferences collected in SKILL.md | SKILL.md via AskUserQuestion |
| Invocation syntax (`/skill-name "..."`) | Not user-facing docs | Removed or SKILL.md only |
| Conversion provenance (`Source: Converted from...`) | Implementation detail | Removed |
| Skill routing for inter-phase (`Skill(skill="...")`) | Use direct phase read | Direct `Read("phases/...")` |

### Pattern 9: Compact Recovery (Phase Persistence)

Multi-phase workflows span long conversations. Context compression (compact) will naturally summarize earlier phase documents. The strategy uses **双重保险**: TodoWrite 跟踪 active phase 保护其不被压缩，sentinel 作为兜底在压缩发生时触发恢复。

**Design principle**: TodoWrite `in_progress` = active phase → protect from compact | Sentinel = re-read fallback if protection fails.

**Double insurance mechanism**:

| Layer | Role | Mechanism |
|-------|------|-----------|
| **1. Active Phase Protection** | 预防 | TodoWrite `in_progress` 标记当前 phase → compact 时保留该 phase 完整内容，不压缩 |
| **2. Sentinel Re-read** | 恢复 | Phase 文件嵌入标识符 → 若仍被压缩，检测到 sent