flow-epic-create

Files (1)

• SKILL.md

SKILL.md (first lines)

# Goal

You are the supervisor of one tmux window's **epic-design** pipeline. The user
typed `flow epic create "<prompt>"` from a terminal; tmux opened a window,
launched Claude Code in it, and seeded this chat with a prompt that invokes
you. From here you turn the epic prompt into a **reviewed, dependency-ordered
decomposition** — `design.md` + `manifest.json` under `.flow/epics/<slug>/` —
committed on a per-pipeline branch and surfaced as an **open design PR** that
copilot auto-reviews. You then STOP at the `epic-design-pending-review`
checkpoint and wait for the user to **approve**, **redirect**, or **cancel**.

This is a different supervisor session from `/flow-pipeline`. You fire your own
named `AskUserQuestion` clarification form, and the `MODE: epic` designer runs
through the in-process `/flow-product-planning` wrapper, whose single Task
spawn is the one discovery sub-agent. Those are NOT among `/flow-pipeline`'s
one `AskUserQuestion` form / seven Task-tool exemptions — a different supervisor
in a different window is a different session.

The Step 4.5 **cross-model design review** is a
**Bash fan-out, not an eighth exemption** — it shells `flow-plan-review` (via
`flow-delegate`/AGY), reusing the SAME `review.gemini` gate as
`/flow-pipeline`'s Step-3 plan review. It spawns no Task and fires no
`AskUserQuestion` form, so `/flow-epic-create`'s
**two named surfaces** (the clarification form + the `MODE: epic` designer
fan-out) are unchanged; documented bidirectionally in `.claude/rules/flow-supervisor-contracts.md` `## Don'ts`.

## EPIC_DIR and the prompt come from the seed (R1 — never import `bin/lib`)

The CLI (`flow epic create`) is the SOLE evaluator of the epic path contract.
The seed it delivers is a **single control-char-free line** carrying
`REQUEST_FILE`, the resolved **literal** `EPIC_DIR` (e.g. `.flow/epics/<slug>`),
and the resolved **literal** product-planning `SKILL_DIR`:

```
Use the /flow-epic-create skill. REQUEST_FILE: <abs>/<slug>.request.md EPIC_DIR: .flow/epics/<slug> SKILL_DIR: <abs>/skills/pipeline/flow-product-planning
```

The prompt no longer rides the seed itself — a stray control character (a
TAB, a newline) inside the free-form prompt used to reach the pane raw and
corrupt delivery, so the CLI now writes the prompt to `REQUEST_FILE` before
launching and the seed carries only a pointer to it. **Read `REQUEST_FILE`
first and treat its full contents as the verbatim prompt.** This applies to
the fresh-create seed above only — the `--resume` seed
(`flow epic create --resume <slug>`) carries no `REQUEST_FILE`; see
`# Resume mode` below, which is what governs that invocation instead. Only
when a fresh-create seed's `REQUEST_FILE` is absent, escalate
`NEEDS HUMAN: request-file-missing` as a plain line — there is no request to
continue from, so recording a pause with `flow-epic-escalate` (see
`## Escalating to NEEDS HUMAN`) would leave nothing for a resume to pick up.

Capture the literal `EPIC_DIR` and use it verbatim for every path below
(`<EPIC_DIR>/design.md`, `<EPIC_DIR>/manifest.json`). Likewise capture the
literal `SKILL_DIR` from the seed (Step 3 loads `/flow-product-planning`
in-process, so the Skill-tool base-directory mechanism supplies it there; the
seed field may stay). You
run cwd'd in a
**consumer worktree** where flow's `bin/lib/*` does NOT exist, so you must
**NEVER `import` `bin/lib`** (`epicDirRelative`, `EPIC_*_FILENAME`) — that
import fails here. Consume the literal + the **bare-name PATH validators**
(`flow-epic-manifest-schema`, `flow-epic-dag`) + the bare-name
`flow-epic-resume-decide` + `flow-epic-escalate` + `jq` only.

# HALT contract (read before doing anything)

F5 OPENS the design PR but **NEVER merges it**. The approve branch leaves the
PR OPEN for the human to merge. You must:

- **never** compute a Kahn frontier / ready-set from the manifest;
- **never** `flow feature create` a feature window or open a per-feature worktree;
- **never** `gh pr merge` the design PR (no auto-merge exemption is claimed or
  needed).

`flowNewHints` in the manifest + the committed manifest itself are the only
orchestrator seam — leave them for the deferred `flow epic run` phase.

## Escalating to NEEDS HUMAN

Every NEEDS HUMAN escalation below runs ONE command — never a hand-written
phase write, checkpoint write, or `echo`:

```bash
flow-epic-escalate --reason <tag> --why "<one line>"
```

It records `phase: needs-human` (the phase history keeps the paused phase),
writes a "Paused at phase" note, arms the terminal checkpoint, and prints the
pause block ending in the byte-exact `NEEDS HUMAN: <reason>` sentinel. Echo its
`checkpointed: …` stderr line verbatim as the last line of your turn — a
`checkpointed: false` line means a `/clear` will lose unsaved in-chat state
(`/flow-checkpoint` prints the same banner) — then **END the turn**:
`needs-human` is a terminal phase, so `flow-stop-guard` permits it. The user
replies `done` here once the human step is resolved, or `/clear`s (or crashes)
and runs `flow epic create --resume <slug>`; both land on the Resume-mode
`awaiting-human` row and continue the paused step. Only the two escalations
with nothing to resume from (`request-file-missing`: no request to continue
from; `state-missing-on-resume`: no state file to record against) stay plain
`NEEDS HUMAN: <reason>` lines.

# The steps

## Step 0 — Echo the originating request

Run `flow prompt` (bare — no slug argument; auto-resolves the slug from
`$FLOW_SLUG`, exactly like `flow-new-worktree` in Step 1 below). The
`--resume` seed carries no slug-bearing prefix to parse, so the bare
ambient call is the only form that works on both a fresh launch and a
resume re-entry. Document `flow prompt <slug>` only as the form a user
types in another terminal.

Extract the region from the FIRST `<!-- flow-request-echo:start -->` marker
to the LAST `<!-- flow-request-echo:end -->` marker in its stdout (not the
first end marker — a request body that itself quotes the end-marker string
would otherwise truncate the echo) and echo it VERBATIM as the session's
FIRST assistant output — prose, not a tool-call result, since Claude Code
truncates Bash tool output. Never paraphrase, reorder, truncate, or re-wrap
the originating epic prompt.

Step 0 writes no state and is inert on control flow. On any non-zero exit
from `flow prompt`, emit one plain line noting the request could not be

From gavingolden/flow, MIT.

More from gavingolden/flow