flow-epic-run

Files (1)

• SKILL.md

SKILL.md (first lines)

# Goal

You drive one epic toward completion as a **playbook** — a set of judgment
recipes you follow, not a loop you run. Each time the user asks you to make
progress ("run the next part of epic X", "reconcile X", "what's the state of
X"), you **reconcile the plan against reality**, repair any drift, then take
**one deliberate step** and stop. The human stays in the loop; you never walk
away and autonomously churn feature windows.

## The core mental model (plan / truth / hint)

An epic is three things:

- **`manifest.json`** — the committed feature DAG. This is **the plan**.
- **`design.md`** — the committed human-readable reference.
- **`run.json`** — a **per-machine, recomputable cache**. This is a **stale
  hint, never the source of truth**.

The **source of truth for progress** is **GitHub** (merged / open PRs) plus
**git** (branches, worktrees), reconciled against the manifest. **Assume
nothing is perfectly in sync.** run.json can lag reality in three ways you must
expect and repair: a feature's flow session was recreated under a new slug; work
merged out of band with no flow pipeline; or the manifest drifted from what
actually shipped. Your job is to reconcile the cache back to the truth before
you act on it.

# When to use

You are invoked by the `flow epic run <slug>` seed prompt, which begins with the
literal prefix:

```
Use the /flow-epic-run skill for: <slug> EPIC_DIR: .flow/epics/<slug>
```

Capture the `<slug>` between `for:` and ` EPIC_DIR:`, and the literal `EPIC_DIR`
after it. You are **also** directly invocable as `/flow-epic-run <slug>` inside any existing
Claude session — the playbook is the same either way; the seed prompt just opens
a dedicated window for it.

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

The CLI (`flow epic run`) is the SOLE evaluator of the epic path contract. It
embeds the resolved **literal** `EPIC_DIR` (e.g. `.flow/epics/<slug>`) in the
single seed line. You run cwd'd in a **consumer worktree** where flow's `bin/lib/*` does
NOT exist, so you must **never import `bin/lib`** — that import fails here.
Consume the literal `EPIC_DIR` + the **bare-name PATH helpers** only.

# Hard invariants (read before doing anything)

These are byte-exact, load-bearing, and lint-anchored. You must:

- **Never merge a feature PR.** Merging a feature is the feature pipeline's own
  job behind its own auto-merge gate; the orchestrator never `gh pr merge`s a
  child.
- **`gated ⇒ escalate-only, never override`.** A child feature in `gated` is
  escalate-only — surface it to the human. You may interpret _why_ it is gated
  and what the human should do, but you can **never override a gated verdict**
  (a gated verdict is terminal, not advisory — AGENTS.md hard rule) and never
  merge it. **Escalate to the human.**
- **Never `send-keys` into a feature window.** A retry is a clean respawn —
  `flow feature resume <feature-slug> --force` — never typing into a live pane.
- **Never hand-edit run.json.** Repoint or adopt a binding with `flow epic
bind`; record an out-of-band completion with `flow epic bind --external`;
  create+bind atomically with `flow epic launch`. Hand-editing the cache is the
  exact failure mode the safe-write primitives exist to prevent.
- **`escalate-on-exhaustion`.** You are human-in-the-loop and bounded by
  construction: after a reasonable attempt to reconcile or relaunch, if a
  feature still will not progress, **escalate to the human** rather than
  churning windows. There is no autonomous retry/redirect budget to burn.
- **Escalation pause block.** Every escalation message — a `gated ⇒
escalate-only` surface or an `escalate-on-exhaustion` stop — ends in a
  pause block per the cross-skill
  `flow-pipeline/references/pause-output-contract.md` (labeled slots, no
  open prose, ≤12 lines). Compact template:

  > ### ⚠ Escalation — <feature id> will not progress
  >
  > **TLDR:** <the one-sentence user-visible consequence>
  > **Unsolved:** <why it is gated / exhausted, with evidence>
  > **Next action:** <the single most useful human action>.

You spawn **no Task/Agent sub-agent** and fire **no AskUserQuestion form** — the
playbook is plain in-session judgment plus bare-name PATH helpers. This keeps
`/flow-pipeline`'s exactly-nine-Task-exemption and one-AskUserQuestion-form
invariants untouched: a different supervisor in a different window is a different
session, and this one has zero named fan-out surfaces.

# Your hands (the bare-name PATH helpers)

| Hand                                                                       | What it does                                                                                                                                                                                                                                                                                                                                                    |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `flow epic status <slug> --json`                                           | The board as a machine-readable **hypothesis** derived from the possibly-stale run.json — always verify it against GitHub/git before acting.                                                                                                                                                                                                                    |
| `flow-epic-dag --validate <manifest>`                                      | Shape + DAG well-formedness gate for the committed manifest.                                                                                                                                                                                                                                                                                                    |
| `flow-epic-dag --frontier <manifest> --completed <ids> [--launched <ids>]` | The exact ready-frontier math for the completed/launched sets YOU supply from your reconciliation (NOT read from run.json).                                                                                                                                                                                                                                     |
| `flow-epic-manifest-schema --validate <manifest>`                          | Manifest shape gate (used after an `amend-manifest` edit).                                                                                                                                                                                                                                                                                                      |
| `flow-epic-judge-context context --slug <epic> --feature <id>`             | Bounded evidence for ONE halted feature (status, PR, tail-bounded CI failure, manifest neighbourhood, `flags.overridable`). Read-only.                                                                                                                                                                                                                          |
| `flow epic bind <epic> <id> <slug> [--force]`                              | Repoint or adopt a run.json binding safely (the #1 drift tool).                                                                                                                                                                                                                                                                                                 |
| `flow epic bind <epic> <id> --external "<ref>" [--force]`                  | Record a completed out-of-band feature (a PR/issue, no live slug).                                                                                                                                                                                                                                                                                              |
| `flow epic launch <epic> <id> [--force]`                                   | Atomic manifest-read → `flow feature create` → binding recorded.                                                                                                                                                                                                                                                                                                |
| `flow epic ls` / `flow epic done <slug>`                                   | List epics (scoped to this repo, completed hidden by default; `--done`/`--all-repos` widen one axis each, `--all`/`-a` widen both) / remove the per-machine run.json cache.                                                                                                                                                                                     |
| `flow feature create "<desc>"` / `flow feature resume <slug> --force`      | Launch a fresh pipeline / clean-respawn a stalled one (the sanctioned retry actuator).                                                                                                                                                                                                                                                                          |
| `flow-epic-sync --epic-slug <epic> [--check] [--commit] [--push]`          | Derive the whole epic's committed status board from GitHub; `--check` exits non-zero on drift. `--epic-slug` is required here — this session's `$FLOW_SLUG` is the epic-run window's own slug, not the epic's, so a bare invocation resolves nothing. Add `--rederive` to rebuild the board from GitHub ignoring committed rows, when a committed row is wrong. |
| `gh`, `git`, `jq`                                                          | The truth probes + JSON extraction.                                                                                                                                                                                                                                                                                                                             |

# The four recipes

## reconcile-drift

Reconcile the cache (run.json) against the truth (GitHub/git) BEFORE any launch.

1. Read the hypothesis: `flow epic status <slug> --json`. Treat every row as a
   **hypothesis to verify**, not fact — the `source` field says so.
2. For **each** node, verify against truth:
   - **GitHub:** `gh pr list --search "<feature branch or title>"` (and
     `gh pr view <n>`) — did this feature's PR merge? Is one open under a slug
     the cache doesn't know?
   - **git:** `git branch --all` and `git worktree list` — is there a live
     branch/worktree the cache missed, or a recorded slug with nothing behind it?

From gavingolden/flow, MIT.

More from gavingolden/flow