Stage: planning

Runtime config (canonical): workflow.json → stages.planning

Purpose: Produce an approved plan the writer subagent can consume deterministically. Works for both create from scratch and edit an existing workflow — the difference is the starting point. Output artifact: write to the absolute path provided in your I/O context Valid results this stage writes: pending (plan drafted, awaiting user approval), approved (user has explicitly confirmed)

This is an interruptible stage — the stop hook allows natural pauses for Q&A.

Step 1 — Detect mode and load context

Read the setup_context input at the absolute path shown in your I/O context. It contains JSON with these fields:

• mode: "create" or "edit"
• description: the original natural-language description the user passed to /meta-workflow:create-workflow (may be empty). This is the only place the description shows up — it is NOT in state.md's topic: field.
• source_dir: (edit mode only) absolute path to the existing workflow to edit

Log the parsed mode and description before proceeding:

• "mode":"create" → skip to Step 2 (create).
• "mode":"edit" → skip to Step 2 (edit).

Step 2 (create) — Understand the request

Use the description from setup_context as the user's request. If it's empty or too vague to decompose, ask ONE clarifying question at a time (cap at 5 total). Useful axes:

• What kind of work does this workflow orchestrate? (coding, writing, data analysis, review, research, etc.)
• What are the rough phases? A 3-line sketch is enough — you'll refine it below.
• Any phase where the user should pause for input? → interruptible inline stage.
• Any phase that benefits from a stronger model? → subagent stage with model: opus (or leave model unspecified for sonnet default).
• Any external validation / test run? → subagent or inline stage that runs a command.
• What's the success terminal? (usually complete.)

Stop asking once you can draft a stage decomposition. Skip to Step 3 — Propose the decomposition.

Step 2 (edit) — Load existing workflow

Do NOT verify ownership by calling the cloud API, running curl, or piping bundle JSON through jq for author/user_id checks. SKILL.md has already refetched the bundle into $source_dir and the setup script has gated on ownership; the fact that source_dir is readable is sufficient proof that you're allowed to edit. Any additional probing (curl → jq chains, python3 JSON parsing, etc.) produces terminal noise and exploration latency without changing the outcome. Treat source_dir as authoritative.

Read the source directory (source_dir from setup_context). Run this so the current design flows into your context:

SRC="<absolute-path-from-setup_context>"
echo "===== workflow.json ====="; cat "$SRC/workflow.json"
for f in "$SRC"/*.md; do
  echo "===== $(basename "$f") ====="; cat "$f"; echo
done

Present the current design to the user as a table + transition graph (same format as Step 3 below). Call it out as "current design — propose changes against this."

Treat the description from setup_context (if non-empty) as the user's change request. If it's empty, ask: "What changes do you want to make to this workflow?"

Continue to Step 3 with the current design as the starting point.

Step 3 — Propose the decomposition

Present the (proposed or updated) design as:

Stage table

Transition graph

Inputs per stage

For each stage, list required and optional inputs using from_stage <name> or from_run_file <name>. Required inputs are enforced at transition time by update-status.sh.

Run files (optional)

If the workflow needs setup-time constants (e.g. git SHA baseline, current date), list each run_files entry: name, description, and the shell init command.

Step 4 — Pick / confirm the suffix

• Create mode: derive a short, kebab-case suffix from the description (e.g. "Python library dev with docs and publish" → python-lib). Confirm with the user. Target directory: ~/.config/meta-workflow/workflows/<suffix>/. If the directory already exists, ask whether to overwrite or pick a different name.
• Edit mode: suffix = basename(source_dir); target directory = source_dir itself (writer will overwrite files in place). Do not ask — this is fixed by the setup_context.

Step 5 — Iterate until approved

Ask: "Does this design look right? Any changes to stages, order, inputs, or naming?" Iterate until the user explicitly approves.

If the user says "no changes" in Edit mode, write the plan anyway with the current design verbatim (writing is idempotent — same files get re-emitted).

Step 6 — Write the plan into the output artifact

Once the user has confirmed the design, write the output artifact (use the current epoch from state.md):

---
epoch: <epoch>
result: pending
---
# Workflow Plan

## Mode
<create or edit>

## Description
<one paragraph — what this workflow orchestrates>

## Suffix
<kebab-case-suffix>

## Target directory
`/absolute/path/to/dir/`
(absolute path — writer will `mkdir -p` this and write files. For edit mode, this is the existing source_dir — writer overwrites in place.)

## Stages

| Stage | Execution | Model | Interruptible | Purpose | Result values → next |
|---|---|---|---|---|---|
| `<name>` | inline / subagent | (omit / opus / sonnet / haiku) | true / false | <short> | `<result>` → `<next>` |

## Transition graph

<initial_stage> --(<result>)--> <next> ...

result: pending signals "plan written but not approved yet."

Step 7 — Get user approval

"Plan saved. Please review and confirm to start writing, or request changes."

If the user requests changes, iterate on the plan body — keep result: pending.

Step 8 — Finalize

Once the user explicitly approves, edit the artifact: change result: pending → result: approved.

The main loop reads the artifact's result: and calls update-status.sh to advance — do NOT call it yourself from this stage file.