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:

Process:

1. For each category, ask: did the user's prompt mention it? Does memory have a relevant preference?
2. If yes → use that, surface as "Applied from memory: …" or "From your prompt: …"
3. If no → that category becomes a question.
4. Ask all remaining questions in batches of up to 4 (the AskUserQuestion tool ceiling) until every material gap is filled. Two batches is fine for greenfield; three is rare but allowed if a complex task genuinely warrants it.
5. Within each batch, lead with the highest-leverage choices (the ones that change the phase shape most).

Anti-patterns:

• Don't ask one batch and then plan around silent assumptions for the rest. If you're about to assume the design direction, the auth provider, AND the scope cut-line, that's 3 assumptions and one batch of follow-up is cheaper than getting it wrong.
• Don't pad questions when memory/prompt already covers them. Reading "I want a SwiftUI iOS app with Liquid Glass" → don't ask "what platform?", "what stack?", or "what aesthetic?". Just ask about integrations, scope, and use case.
• Don't ask micro-details that belong in plan review: naming, file paths, copy wording, color palette specifics, library minor versions, default test framework if the stack has one. Those go into ROADMAP.md as assumptions and surface in Stage 6's revision menu.

Brownfield — 0–2 questions, one batch

The codebase plus recon scripts already answer most structural questions (stack, package manager, build/test/lint, conventions, what exists). Ask only for true gaps memory + prompt + recon leave open:

• Scope cut-line ("just this surface, or also touch the related ones?")
• Compatibility surface ("backwards compat with the old API path, or break it?")
• Primary fork when ambiguous ("which of these two existing patterns do you want me to extend?")

Most well-described brownfield tasks ask zero questions.

In both modes

1. Lead with "Applied from memory: …" and "From your prompt: …" so the user sees what's being inherited or read off before answering.
2. Each AskUserQuestion batch caps at 4 (tool limit). Greenfield can use multiple sequential batches; brownfield is one batch max.
3. If you genuinely need zero questions, say "No clarifying questions — proceeding from prompt + memory + recon." and move straight to Stage 2.
4. Never ask about anything you can responsibly assume — those go into the Stage 6 plan review for one-click correction.

Stage 2 — Recon (parallel)

Run recon scripts in parallel. They populate context files under $SUPERGOAL_ROOT/.

Brownfield path

bash "$SUPERGOAL_DIR/scripts/detect-stack.sh"   > "$SUPERGOAL_ROOT/context.md"
bash "$SUPERGOAL_DIR/scripts/summarize-repo.sh" > "$SUPERGOAL_ROOT/repo-map.md"

Greenfield path

bash "$SUPERGOAL_DIR/scripts/detect-env.sh" > "$SUPERGOAL_ROOT/context.md"

Read the outputs. Then print a 5-line summary to the user: stack, package manager, build/test/lint commands, notable modules (if any), risky areas. This is what tells them you've actually understood their codebase before planning.

Stage 3 — Deep think

This is the difference between a generic plan and a Supergoal. Spend real cycles here — but use only what's available.

Required regardless of tools:

• Identify the top 3 risks: what's most likely to go wrong, what's hardest to undo, what's easy to miss until shipped.
• Identify non-obvious dependencies: things that have to happen in a specific order or block other work.
• Apply memory hits from $SUPERGOAL_ROOT/applied-memories.md — bake them into goals, constraints, or risk mitigations.

Optional, use if available (check $SUPERGOAL_ROOT/tools.md):

• Context7 — if available, query current docs for any third-party SDK touched. Don't plan against stale APIs. If unavailable, lean on training-cutoff knowledge and call it out as an assumption ("planned against my training-cutoff understanding of Expo SDK — verify in phase 1").
• WebSearch — if available, look up current consensus on patterns you're unsure about (auth flows, payment idempotency, accessibility standards). If unavailable, skip.
• Project skills — if relevant skills are listed in $SUPERGOAL_ROOT/applied-skills.md (e.g. clerk-auth, mobile-ios-design), note them in THINKING.md as "consult <skill> skill during phase N" so the executor invokes them at the right moment.

Write $SUPERGOAL_ROOT/THINKING.md with sections: Goals, Constraints, Risks, Dependencies, Open Questions (already-assumed), Memory hits applied, Tools/skills relied on, Best Practices Applied. Keep it tight — 1–2 pages. This is the substrate the roadmap derives from.

See references/planning-depth.md for the bar to clear here.

Stage 4 — Decompose into phases

Break the work into as many phases as the task actually needs — no fixed count, no upper or lower cap. The right number falls out of the work itself: how many independently verifiable units exist between empty repo (or current state) and "done perfectly." A trivial change might need 2 phases; a typical feature 4–6; a full-stack greenfield app 8–12; a major migration 15+. Read references/phase-design.md for how to slice well — the short version:

• Each phase delivers something verifiable on its own (it builds, it passes its own tests, you could ship it as a partial increment)
• Phases have explicit dependencies (phase 3 depends on 1 and 2)
• The last phase is always a "Polish & Harden" phase covering edge cases, error states, security, accessibility, copy, perf — this is how "every aspect is perfect" gets enforced
• For UI work, include a dedicated visual polish phase with screenshot/visual evidence requirements
• For brownfield, include an early safety net phase if test coverage is thin (add characterization tests before changing behavior)

Each phase has:

• Name (5 words max, action-first: "Build auth foundation")
• Why (1 sentence)
• Deliverables (concrete files/features that will exist when done)
• Acceptance criteria (5–10 measurable items)
• Mandatory commands (build, typecheck, lint, test that must pass)
• Evidence required (what the agent must print into the transcript to prove completion)
• Dependencies (which prior phases must be done)

Stage 5 — Write the roadmap and phase specs

Three files, all under $SUPERGOAL_ROOT/:

1. ROADMAP.md — the plan (template at $SUPERGOAL_DIR/templates/ROADMAP.md).
2. STATE.md — live progress file the executor updates per phase (template at $SUPERGOAL_DIR/templates/STATE.md).
3. phases/phase-N.md — one work-spec file per phase (template at $SUPERGOAL_DIR/templates/phase-goal.txt, renamed conceptually to "phase spec"). Any length — these are read from disk by the executor, not passed to /goal, so no char budget.

Each phase spec must include these markers so the agent and evaluator both have stable anchors:

SUPERGOAL_PHASE_START
Phase: <N> of <total> — <name>
Task: <one-line>
Mandatory commands: <list>
Acceptance criteria: <count>
Evidence required: <list>
Depends on phases: <list or "none">

[... full work description, acceptance criteria, evidence requirements ...]

[Agent will print SUPERGOAL_PHASE_VERIFY and SUPERGOAL_PHASE_DONE here during execution]

Validate each spec with bash $SUPERGOAL_DIR/scripts/validate-phase.sh "$SUPERGOAL_ROOT/phases/phase-N.md" — it confirms the required markers exist. No char budget.

Stage 6 — Plan review & confirmation (hard gate)

Before any /goal is dispatched, show the user the full plan and ask for explicit confirmation. The chain runs unsupervised once it starts, so this is the last cheap moment to correct course. Skipping this step is a bug.

Stage 6a — Self-critique pass (cheap, runs once)

Plan-time is the cheapest moment to catch the most expensive bugs (vague criteria, mis-sliced phases, weak dependencies). Before printing the summary, run one self-critique turn answering exactly three questions:

1. Falsifiability: Is every acceptance criterion across every phase a yes/no test, not a vibe? Flag any that say "works", "good", "ready", "correct" without a measurable predicate.
2. Phase atomicity: Is any phase secretly two coherent units packed into one (deliverables that don't share a verify gate, names containing "and", split-able dependency lines)?
3. Weakest dependency: Where would a partial failure cascade worst? (e.g., phase 2 unblocks 3, 4, and 5 — if 2 ships shaky, three phases inherit the bug.)

Output:

• If clean: record Self-critique: clean. and proceed.
• If findings: list 1–3 specific findings (no padding). For falsifiability issues, rewrite the offending criteria in place in the affected phase-N.md files and ROADMAP.md before printing the summary. Re-run validate-phase.sh on any touched spec. Surface the rewrites in the Stage 6 summary so the user sees the post-critique version, not the pre-critique one.

Honesty check: this pass must produce findings or a "clean" verdict per run. If it silently always says "clean" on real plans, it's theater and we remove it in the next release.

Stage 6b — Summary print

Print a scannable summary in this exact shape:

✓ Plan ready for review. <N> phases.

Applied from memory:
  - <memory hit 1>
  - <memory hit 2>
  (or: "none — clean run")

Phases:
  1. <name> — <one-line deliverable>
  2. <name> — <one-line deliverable>
  ...
  N. Polish & Harden — every aspect verified

Stack: <stack> · pkg: <pm> · build/test/lint: <commands>

Key assumptions (correct any that are wrong):
  - <assumption 1>
  - <assumption 2>
  - <assumption 3>

Top risks & mitigations:
  1. <risk> → <mitigation>
  2. <risk> → <mitigation>
  3. <risk> → <mitigation>

Self-critique:
  - <finding 1, or "clean">
  - <finding 2 (optional)>
  - <finding 3 (optional)>
  (criteria rewrites applied in-place if any were flagged)

Artifacts:
  Roadmap: <run-root>/ROADMAP.md
  Progress: <run-root>/STATE.md (auto-updates)
  Phase specs: <run-root>/phases/phase-1..N.md

Once you confirm, I'll print a ready-to-paste `/goal` line. Paste it
once and the chain runs through to completion, with auto-retry and
fix-spec recovery.

Then call AskUserQuestion with one question, header "Start chain?", offering concrete revision modes (not a vague "revise plan"):

• Start now — run pre-flight smoke check (Stage 6.5), then print the ready-to-paste /goal line; I paste it and the chain runs unsupervised
• Adjust an assumption — pick one to change (will re-show plan)
• Tweak a phase — change criteria, scope, or commands for a specific phase
• Restructure phases — merge, split, add, or remove a phase

Keep options at 4 max. If the user picks any revision option, follow up with a second AskUserQuestion to pin down exactly what (e.g., "Which assumption?" with the assumptions listed). Apply the change, update ROADMAP/THINKING/STATE and the affected phase specs, re-run validate-phase.sh on each touched spec, then re-show the Stage 6 summary and ask again. Loop until "Start now" or user aborts.

Wait for the answer. Do not dispatch /goal until the user picks "Start now". Never assume confirmation; never start the chain on silence.

Stage 6.5 — Pre-flight smoke check

After Stage 6 returns "Start now" and before printing the /goal block, run a single pre-flight pass against the deduplicated mandatory commands. This catches the case where the baseline is already broken (e.g., pnpm build red before phase 1 ever ran) — without this, the 3-strike loop would thrash trying to "fix" phase 1 work that was never the cause.

Procedure:

1. Read every phase-N.md spec and union their Mandatory commands: lines into a deduplicated set.
2. Run each once. Capture exit code and last ~5 lines.
3. If all green:
   • Append a Notable events line to $SUPERGOAL_ROOT/STATE.md: <DATE> — Pre-flight green: <N> commands clean.
   • Print PREFLIGHT_GREEN with the per-command summary.
   • Proceed to Stage 7.
4. If any red:
   • Append <DATE> — Pre-flight red: <cmd> exited <code>. to STATE.md.
   • Print PREFLIGHT_RED with the failing command, exit code, last ~5 lines.
   • Re-show the Stage 6 summary with the failures surfaced and a revised menu (still 4 options to stay under the AskUserQuestion ceiling): "Skip pre-flight, dispatch anyway" (replaces "Start now" — the user might know the baseline is intentionally broken, e.g., phase 1's whole job is to fix it) / "Adjust an assumption" / "Tweak a phase" / "Restructure phases". If "Skip pre-flight, dispatch anyway" → log <DATE> — Pre-flight bypassed by user. and proceed to Stage 7. Any other choice loops back through the normal Stage 6 revision flow; after the user finishes revising, Stage 6.5 re-runs.

Honesty test: real command run, real exit code. The "skip anyway" option keeps the user in control — no forced re-plan if the baseline being red is the point.