workflow-creator

What this skill does

**Announce:** "Using workflow-creator to design/audit/improve a structured workflow."

**Load workflow-creator's own constraints** (auto-discovered + `applies-to`-filtered — surfaces the `wc-*` behavioral rules at load time, complementing the `wc-constraint-check.py` post-edit hook):

!`uv run python3 ${CLAUDE_SKILL_DIR}/../../scripts/load-constraints.py workflow-creator`

Detect mode from user request, then follow the corresponding process below:
- **Mode 1 (Create)** — "create/design a workflow", "break a task into phases"
- **Mode 2 (Audit)** — "audit/score a workflow"
- **Mode 3 (Improve)** — "improve a workflow", audit-fix loop, **"migrate a fan-out phase to an ultracode workflow"** (a migration is an improvement — see `${CLAUDE_SKILL_DIR}/references/dynamic-workflow-migration.md`)

**Note on workflow-creator's Structure:**

workflow-creator is a **meta-tool** that CREATES workflows. It is exempt from certain requirements it enforces on workflows it creates:

- **Two entry points:** workflow-creator has one entry with mode detection (not a multi-phase workflow). Workflows it creates MUST have two entry points.
- **Single responsibility per phase:** workflow-creator has 3 modes (toolkit, not workflow). Workflows it creates MUST have single-responsibility phases.
- **Skill Dependencies (cross-file phase chaining):** workflow-creator is a single SKILL.md, so it has no next-phase `Read()` chain. Its structural equivalent is **stronger**: the `wc-step-gate-guard.py` hook + the STATE.md step-chain enforce step ordering at the tool-call layer (a skipped step is blocked, not merely un-chained). Workflows it creates with multiple phase files MUST still wire phase-to-phase `Read()` transitions.
- **Iteration topology labels (P09):** workflow-creator's own steps are a fixed sequence, not a per-phase topology menu, so they carry no `[one-shot|serial|parallel]` label. Workflows it creates MUST assign a topology per phase.

This document defines the PROCESS for creating workflows. The workflows created by this process must follow all principles from PHILOSOPHY.md.

**The mode flowcharts below ARE the authoritative spec.** Each mode (Create, Audit, Improve) opens with an ASCII step/phase diagram. If the prose for a step ever conflicts with its mode's flowchart, **the flowchart wins** — treat a diagram-violating shortcut as a process error, not a "minor deviation from documentation."

---

## Startup: State Check

Before detecting mode, check for existing workflow-creator state:

1. **IDENTIFY:** Run `Glob(".planning/wc/*/HANDOFF.md")` and `Glob(".planning/wc/*/STATE.md")`
2. **READ:** If any HANDOFF.md found → read it. If STATE.md found without HANDOFF.md → read STATE.md to determine last completed step.
3. **VERIFY:** If HANDOFF.md exists, confirm the recorded mode/step match what STATE.md shows. If they conflict, trust STATE.md (it's hook-enforced).
4. **DECIDE:** If resumable state found → offer to resume from recorded position (skip mode detection). If not found → proceed with mode detection below. [checkpoint: decision]

**Determining `{name}`:** The `{name}` in all state file paths is the target workflow name (e.g., `dev`, `ds`, `writing`, `teaching`). For Mode 1, use the proposed workflow name from the interview. For Modes 2-3, use the workflow being audited/improved.

**Why `.planning/wc/`:** workflow-creator's state files must NOT conflict with the target project's `.planning/` state files (SPEC.md, PLAN.md, STATE.md, etc.). The `wc/` subdirectory isolates workflow-creator's meta-state from the workflow state it's auditing or creating.

**Namespace by target workflow:** Each workflow-creator invocation operates on a specific target workflow. State files go in `.planning/wc/{workflow-name}/` to prevent clashes when auditing/improving multiple workflows in parallel (e.g., parallel companions auditing dev, ds, writing simultaneously).

```
.planning/wc/
├── dev/                    → audit/improve state for dev workflow
│   ├── STATE.md
│   ├── AUDIT.md
│   └── SCORES.md
├── ds/                     → audit/improve state for ds workflow
│   ├── STATE.md
│   ├── AUDIT.md
│   └── SCORES.md
└── writing/                → audit/improve state for writing workflow
    ├── STATE.md
    └── AUDIT.md
```

For Mode 1 (create), use the proposed workflow name: `.planning/wc/{new-workflow-name}/`.

**Standard workflow-creator state files:**

| File | Purpose | Created By |
|------|---------|-----------|
| `.planning/wc/{name}/STATE.md` | Current mode + step | All modes at startup |
| `.planning/wc/{name}/INTERVIEW.md` | Captured interview answers | Mode 1 Step 2 |
| `.planning/wc/{name}/DESIGN.md` | Phase decomposition decisions | Mode 1 Step 3 |
| `.planning/wc/{name}/AUDIT.md` | Audit findings and scores | Mode 2 Step 4, Mode 3 Phase A |
| `.planning/wc/{name}/SCORES.md` | Score history across iterations | Mode 3 Phase A |
| `.planning/wc/{name}/VALIDATION.md` | Maps each WC-NN requirement → verification evidence (which gate/audit confirms it) + scope tag (v1/v2/out-of-scope) | Mode 1 Step 7, Mode 2 Step 4 |
| `.planning/wc/{name}/LEARNINGS.md` | Log of what the user attended to / changed at present-to-user checkpoints (Step 6/7) — the observe→record→offer loop wc prescribes for created workflows, applied to itself | Mode 1 Step 6-7 |
| `.planning/wc/{name}/HANDOFF.md` | Session resume context | Any mode on context exhaustion |

**wc HANDOFF.md template** (workflow-creator's own handoff — the same structured format it mandates for the workflows it creates, applied to itself, so a resuming session starts immediately without re-discovery):
```yaml
---
mode: create | audit | improve
step: <current step or phase>
status: paused
target: <workflow name>
context_remaining: <e.g. 24%>
last_updated: <ISO8601 — pass in via args; do not invent>
---
## Current State
<what is in progress right now>
## Completed Work
<steps done + key artifacts written>
## Remaining Work
<steps/phases left>
## Decisions Made / Rejected Approaches
<so the resume doesn't relitigate>
## Next Action
<specific enough to start immediately — not "continue">
```

---

## Mode 1: Create New Workflow

```
Step 1: Philosophy ──→ Step 2: Interview ──→ Step 3/3b: Decomposition + Artifact Gates
  [auto]                [pause: interview]     [auto]
    │                       │                      │
    ▼                       ▼                      ▼
  STATE.md updated        INTERVIEW.md           DESIGN.md
                          STATE.md updated       STATE.md updated
                                                     │
Step 7: Self-Audit ◄── Step 6: Generate ◄── Step 5: Entry Points ◄── Step 4/4b: Enforcement
  [decision: present]    [decision: present]   [auto]                    [auto]
    │                       │                      │                        │
    ▼                       ▼                      ▼                        ▼
  AUDIT.md via subagent   Skill files written    STATE.md updated         STATE.md updated
  Score ≥ 8.0? ──NO──→ Fix ──→ Re-audit (max 3)
    │ YES
    ▼
  Present to user
```

<EXTREMELY-IMPORTANT>
**NO PAUSE BETWEEN STEPS.** After completing each step, immediately start the next. Do NOT ask "should I continue?", do NOT summarize what you just did, do NOT wait for confirmation — pause ONLY where explicitly required (Step 6: present files; Step 7: present audit results). Pausing between steps is procrastination disguised as courtesy: it strands the workflow and hands the user a management burden they should never have to carry.
</EXTREMELY-IMPORTANT>

<EXTREMELY-IMPORTANT>
**Enforcement architecture:** Step transitions are hook-enforced via `wc-step-gate-guard.py`:
- **Layer 2 (step-chain):** Writing `step: N` to STATE.md is BLOCKED unless `step: N-1` shows `status: completed`. This fires for ALL modes (create, audit, improve).
- **Layer 1 (file-path gates):** Writing INTERVIEW.md, DESIGN.md, AUDIT.md, and skill/constraint files is BLOCKED unless the prerequisite