supergoal

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" "$ARGUMENTS")"
  export SUPERGOAL_ROOT
  echo "SUPERGOAL_ROOT=$SUPERGOAL_ROOT"   # e.g. .supergoal/add-dark-mode-Ab3Kx9
  

  claim-run.sh uses mktemp -d to create-and-claim the dir atomically, so two simultaneous starts always get distinct dirs — the race that caused the overwrite is gone.

• Resume — if an active run clearly matches this task (its STATE.md title ≈ $ARGUMENTS, or the user said "resume"/"continue"), set SUPERGOAL_ROOT to that run dir and follow the resume path (don't re-plan). If several active runs exist and intent is ambiguous, ask with one AskUserQuestion which to resume — or to start fresh.

Coexistence notice (load-bearing — print it). If ACTIVE_RUNS is non-empty and you're starting a fresh run, surface this before continuing:

⚠ Another Supergoal run is active in this working tree (<list>). Your planning artifacts are isolated under <SUPERGOAL_ROOT>, so they won't collide — but two /goal executions in the same working tree will still edit the same source files and clobber each other's code. Namespacing protects the plan, not the build. For true parallel execution, run each task in its own git worktree; or resume the existing run instead of starting a second.

That boundary is the honest one: namespacing removes the artifact overwrite that happens during planning; it does not make two autonomous builds in one tree safe.

Memory preload

# Detect a memory directory. Common locations:
MEM_DIR=""
for cand in \
  "$HOME/.claude/projects/-Users-$(whoami)/memory" \
  "$HOME/.claude/memory" \
  "$PWD/.claude/memory" \
  "$SUPERGOAL_ROOT/memory"; do
  [[ -d "$cand" ]] && MEM_DIR="$cand" && break
done
echo "MEM_DIR=$MEM_DIR"

if [[ -n "$MEM_DIR" && -f "$MEM_DIR/MEMORY.md" ]]; then
  echo "--- MEMORY INDEX ---"
  cat "$MEM_DIR/MEMORY.md"
fi

Read the index. Then selectively read individual memory files that look relevant to the task (feedback memories about the stack/domain, user role memories, related project memories). Don't dump them all into context — pull what matters.

Capture applicable memory hits in $SUPERGOAL_ROOT/applied-memories.md (one line per memory: name, why-applicable, what-it-changes). Surface them in Stage 1 as "Applied from memory: …" so the user can see what's being inherited and correct anything stale.

Tool discovery

Tools differ between sessions and hosts (Claude Code vs Codex, different MCP server sets). Detect, don't assume:

• Context7 — available if mcp__claude_ai_Context7__resolve-library-id or similar is in the tool list. If absent, skip it; rely on training-cutoff knowledge + WebSearch if that's present.
• WebSearch / WebFetch — available if listed. If neither, skip web research.
• Project skills — check the available-skills list for domain-relevant skills (e.g. mobile-ios-design, clerk-auth, expo-dev-client) and note them in $SUPERGOAL_ROOT/applied-skills.md to invoke from inside phase goals if relevant.
• Prior Supergoal state — handled above in "Claim the run namespace": active runs are detected per-namespace and either resumed (reuse their $SUPERGOAL_ROOT) or explicitly coexisted-with.

Write detected tools to $SUPERGOAL_ROOT/tools.md. Stage 3 and the phase goals reference this file when deciding what to invoke.

Resume detection

If you resolved to resume a run in "Claim the run namespace", read its $SUPERGOAL_ROOT/STATE.md. If Status is IN_PROGRESS / READY_TO_DISPATCH / BLOCKED with a phase pending, do not re-plan. Print a one-line "Resuming Supergoal from phase N ($SUPERGOAL_ROOT)" and jump straight to Stage 6 (plan review) with the existing artifacts, or directly to Stage 7 (dispatch) if the user confirms resume.

Stage 1 — Intake & clarifying questions

Echo the task back in one sentence. Then classify it (tags can combine):

Calibrate the question count to the context. Greenfield has no codebase to scan, so it needs enough verbal context to plan well — never artificially limit questions when material info is missing. Brownfield runs lean on recon, so questions are sparse.

Greenfield — gather enough context to plan well

A new project has no signal beyond the user's prompt + memory. The planner's job in Stage 1 is to enumerate every category that meaningfully shapes the plan, eliminate the ones already answered by memory or prompt, and ask about every remaining one. Don't stop until every material gap is filled.

Category checklist — work through this for every greenfield run:

Content truncated.