Graph Goal

---
name: graph-goal
description: Compile a long-horizon goal into a PERSISTENT goal graph at
  .claude/graph-state/<slug>.json — frozen objectives, dependency-ordered nodes,
  and a machine-checkable acceptance gate on every node — so an agent can work
  it across sessions with /graph-next. The durable companion to one-shot /graph.
argument-hint: <goal>
disable-model-invocation: true
---

# Graph-goal: compile a goal into a persistent graph

One-shot `/graph` designs a DAG in context, runs it, and forgets it. This skill
writes the DAG **to disk** so a loop can grind at it across sessions:

> $ARGUMENTS

If no goal was provided, ask for one and stop. This skill only *compiles* —
it never starts the work; `/graph-next` does that, one gated tick at a time.

**Read `../graph/reference/goal-state.md` first** — it is the single source of
truth for the file format, statuses, and invariants. Do not improvise fields.

## Procedure

1. **Slug + collision.** Kebab-case slug from the goal. If
   `.claude/graph-state/<slug>.json` exists, stop and say so — suggest
   `/graph-next <slug>` to continue it, or a different slug. Never overwrite a
   live goal graph without explicit confirmation.

2. **Freeze the objectives.** Distill the goal into 1–5 outcome-level
   objectives — *what must be true when this goal is done*, not tasks. These are
   *immutable to agents* after this step (the scope-creep bound), so get them
   right: **show the objectives list to the user and get a yes before writing
   the file.** In a non-interactive run (headless, piped, autonomous — the
   Step-0 rule from the `graph` skill applies here verbatim), don't dead-end:
   write the file with your best-judgment objectives and record it as a
   conforming `history` entry (never a free-form note): `{date, tick: 0,
   node: null, action: "objectives-auto-frozen-unreviewed", gate: "n/a",
   sha: <HEAD, or null if no commits>}`.

3. **Decompose into nodes** using the `graph` skill's Step 1 discipline:
   verb-first ids, one job per node, split by context boundaries, deps only
   where an artifact genuinely flows. Every node references an objective id.
   Keep it coarse — 5–15 nodes; a tick can split a node later, and a
   30-node upfront plan is speculation wearing a graph costume.

4. **Gate every node.** For each node, pick the acceptance kind by the same
   failure-mode routing as the `graph` skill's Step 0.5, and state the routing
   in the node's first `log` entry (`"routed: harness — result is executable"`):
   - result runs → `harness`: write a rerunnable script to
     `.claude/graph-state/harness/<node-id>.sh` now (card 9 discipline: it must
     FAIL against the current repo — run it once to confirm; a gate that passes
     before the work exists is not a gate, fix it until it fails).
   - mechanical fact (file exists, build passes, string present, tests green) →
     `checks` with concrete commands. Run each once to confirm it currently
     fails (or note why a subset already passes).
   - genuinely normative → `human`, with a `note` saying why no machine gate
     exists. If you find yourself reaching for `human` more than ~twice,
     the decomposition is too vague — re-split until gates are checkable.

5. **Mark `wide: true`** only on discovery/audit-shaped nodes (find/sweep/audit
   over many files) where a `/graph` fan-out genuinely beats one context.
   Default false — the tick loop is cheap on purpose.

6. **Write the file** (valid JSON, all invariants from goal-state.md), plus the
   harness scripts, and show the user:
   - the frozen objectives,
   - the node table (`id | job | deps | gate kind | wide`),
   - the frontier (what `/graph-next` will pick up first),
   - one line: *"Tick it with `/graph-next <slug>` — one gated node per tick;
     run it under `/loop` for continuous progress."*

7. **Commit** `.claude/graph-state/` — not optional-for-sharing: the SHA-based
   drift check assumes the state and the code share a history, and `/graph-next`
   commits every gated tick. If the repo has no commits yet, this is the
   initial commit.

## What this skill refuses

- Prose done-conditions ("auth works well") — every node gets a command or an
  explicit `human` gate.
- Objectives smuggled in as nodes — if a node doesn't serve a frozen objective,
  it doesn't go in.
- Starting the work — compilation and execution are separate on purpose
  (design first, run second is the `graph` skill's oldest rule).