/supergoal

name: supergoal
description: Plan and autonomously build a software task end-to-end. Triggered by `/supergoal`, "plan and ship X", "supercharged plan", "autonomous build", "plan it out and don't stop until it's done", "I don't want to babysit this", or any non-trivial feature/refactor/redesign the user wants driven to completion. Strongly prefer over a plain plan when the user signals "every aspect", "fully", "perfectly", "until done", or wants depth + autonomous follow-through. Recons the codebase, applies preloaded memory, researches best practices with whatever tools are available, decomposes into the right number of phases, gets one confirmation, then prepares a single ready-to-paste `/goal` command — one paste between you and done — that drives the entire chain to completion with built-in retry, fix-spec recovery, and per-phase memory writeback. Works on Claude Code and Codex.
argument-hint: <describe what you want built, fixed, or shipped>

Supergoal

You are running the Supergoal workflow. The user's task is:

$ARGUMENTS

Your job: **plan deeply, then auto-execute under a single `/goal`** until the task is verifiably complete across every phase.

What "every aspect is perfect" means here

The user's bar is high. Translate it into measurable criteria, not vibes:

• **Functional** — the feature works for the golden path and the obvious edge cases
• **Engineering** — build, typecheck, lint, tests all pass; no new warnings
• **Polish** — UX/copy, error states, empty states, loading states are handled
• **Hardening** — security review, input validation, no obvious regressions
• **Verification** — every phase produces transcript evidence the evaluator can see

If a phase can't be measured, it isn't a phase. Rewrite it until it can.

How this skill works (one-shot summary)

0. **Available context** — preload memory; detect available tools (Context7, WebSearch, MCPs, skills); resume any in-progress Supergoal state 1. **Intake** — restate, classify, ask enough questions to cover every material gap. Greenfield walks the full category checklist (platform, stack, design direction, integrations, scope, audience, perf, data model) in batches of up to 4 until everything material is filled in; brownfield asks 0–2 since recon answers most structural questions. 2. **Recon** — parallel codebase + environment scan 3. **Deep think** — research best practices with whatever tools exist (optional, not required); list top-3 risks + dependencies 4. **Decompose** — derive phase count from the task itself; no fixed cap 5. **Write phase specs** — one work-spec file per phase under `$SUPERGOAL_ROOT/phases/phase-N.md` (any length, no char budget) 6. **Plan review** — show summary + concrete revision menu; wait for explicit go/no-go 7. **Hand off one ready-to-paste `/goal`** with a short end-state condition; the user pastes once, and the agent inside that fresh `/goal` session executes phases sequentially with retry + fix-spec recovery + per-phase memory writeback, then runs a **final audit** that re-verifies the work against the original ROADMAP and self-heals any gaps before completion holds

Two human gates only: **clarifying questions for true gaps (Stage 1)** and **plan review (Stage 6)**. Everything else runs autonomously.

Why one `/goal`, not a chain

`/goal` in both Claude Code and Codex takes a **short end-state condition**, not a long task body. A fast evaluator checks the condition against the transcript after each turn and auto-continues until it holds. Supergoal v3 leverages this directly: one `/goal` covers the whole run; phase work lives in files the agent reads from disk; the condition is "all phases done, `SUPERGOAL_RUN_COMPLETE` printed." No char budget, no inter-session chain dispatch, no fragility.

Locate the skill directory

SUPERGOAL_DIR=$(dirname "$(ls -1 \
  "$HOME/.claude/skills/supergoal/SKILL.md" \
  "$PWD/.claude/skills/supergoal/SKILL.md" \
  2>/dev/null | head -n1)")
export SUPERGOAL_DIR
# $SUPERGOAL_BASE holds ALL runs. Each run gets its own namespaced subdir under it
# (claimed in Stage 0) so two runs in the same working tree never clobber each other.
# The per-run dir — $SUPERGOAL_ROOT — is set in Stage 0, not here.
export SUPERGOAL_BASE="${SUPERGOAL_BASE:-.supergoal}"
mkdir -p "$SUPERGOAL_BASE"
echo "SUPERGOAL_DIR=$SUPERGOAL_DIR"
echo "SUPERGOAL_BASE=$SUPERGOAL_BASE"

All artifacts for a run live under `$SUPERGOAL_ROOT` — a per-run subdir of `$SUPERGOAL_BASE`, claimed in Stage 0. Skill assets (scripts, references, templates) live under `$SUPERGOAL_DIR`.

---

Stage 0 — Available context (memory + tools)

Before doing anything else, sense what's available this session. This is what makes the run frictionless — if memory already knows the user's preferences, don't ask; if a tool isn't available, don't try to call it.

Claim the run namespace (resume or fresh)

**Do this first** — before memory preload, recon, or anything that writes a file. Every run gets its **own** subdirectory under `$SUPERGOAL_BASE`, so two runs started in the same working tree can never overwrite each other's STATE/ROADMAP/phases (the v0.7 fix for concurrent-run clobbering).

# Look for an in-progress run to resume. Scan per-run dirs AND the legacy flat layout
# (.supergoal/STATE.md from pre-0.7 runs). A run is "active" unless its STATE.md Status
# is COMPLETE. (The unfilled template's "PLANNING → IN_PROGRESS → COMPLETE" arrow line
# is not a terminal COMPLETE, so it correctly reads as active.)
ACTIVE_RUNS=""
for s in "$SUPERGOAL_BASE"/*/STATE.md "$SUPERGOAL_BASE"/STATE.md; do
  [ -f "$s" ] || continue
  grep -Eqi 'status:\**[[:space:]]*complete[[:space:]]*$' "$s" && continue
  ACTIVE_RUNS="${ACTIVE_RUNS}$(dirname "$s")"$'\n'
done
printf 'Active runs in this tree:\n%s\n' "${ACTIVE_RUNS:-  (none)}"

Then decide:

• **Fresh run (default for a new task)** — claim a unique namespace:

  SUPERGOAL_ROOT="$(bash "$SUPERGOAL_DIR/scripts/claim-run.sh" "$