Supergoal: one /goal command that plans and builds a task end-to-end

The problem Supergoal actually solves, and who feels it

Long agentic builds fail in a boring way. The agent plans a step, you execute or approve it, you re-prompt, and the context that held the original intent drifts. Supergoal's README frames the alternative as "Traditional planning": ask for a plan, get one back, then re-prompt at every step until the task ends after many turns. The project's answer is to move all the phase work into files on disk and reduce human involvement to two actions, one approval and one paste.

That shapes the audience narrowly. This is for someone already running Claude Code or Codex CLI who has a task big enough to need phases but not big enough to justify hand-holding a session for hours. The README's own example is an Expo app that converts photos to ASCII art, which is a weekend-sized build with real integration surface. If your tasks are one-file edits, the planning stages cost more than they save.

It is also explicitly a planner plus orchestrator, not a generator. Supergoal decomposes work, writes specs, and hands a /goal line to the host agent. The actual building is done by the model you are already paying for.

How the stages and the autonomous loop fit together

The README publishes a full flowchart, and it is worth reading as a state machine rather than a marketing diagram. Stage 0 loads memory and detects which tools and MCPs are available in the session. Stage 1 branches: greenfield projects walk a category checklist (platform, stack, design direction, integrations, scope, audience, performance, data model) in batches of up to four questions, while brownfield repositories get "0 to 2 questions" because recon answers most gaps. Stage 2 runs a parallel codebase and environment scan. Stage 3 produces a top-3 risk list with dependencies. Stage 4 decomposes into N phases, and the README is explicit that N is adaptive with "no fixed count". Stage 5 writes ROADMAP, STATE, and phase-N.md specs to disk. Stage 6 self-critiques and offers a revision menu, and Stage 6.5 runs a pre-flight smoke check that must come back green before Stage 7 prints the /goal line.

The execution loop is where the design gets opinionated. Each phase reads its spec, does the work, runs SUPERGOAL_PHASE_VERIFY (which the README says includes a cleanliness grep), writes memory, then emits SUPERGOAL_PHASE_DONE. Failures escalate in three strikes: an automatic retry with a probe injected, then a written fix-spec executed inline, then a stop with full probe history. After the last phase, a final audit re-verifies against the ROADMAP, re-runs mandatory commands, spot-checks criteria, and compares deliverables against a Baseline ref. Audit gaps get up to two inline fix rounds before AUDIT_HANDOFF. Clean runs end with AUDIT_COMPLETE, a coverage percentage, and SUPERGOAL_RUN_COMPLETE.

Installing the skill in Claude Code and running a first task

The README gives three commands for the Claude Code marketplace route, run inside a session. After the third, /supergoal is available immediately.

/plugin marketplace add https://github.com/robzilla1738/supergoal.git
/plugin install supergoal@supergoal
/reload-plugins

The README notes a real failure mode here: the owner/repo shorthand (`/plugin marketplace add robzilla1738/supergoal`) works only when GitHub SSH keys are configured, because it defaults to cloning over [email protected]. If you see "SSH authentication failed" or "Permission denied (publickey)", use the HTTPS URL form. If install reports "not found", the README says to run `/plugin marketplace update supergoal` and retry.

If you would rather skip the marketplace, the manual path copies the skill directory into your Claude skills folder. Note the clone goes to /tmp and is removed afterward.

mkdir -p ~/.claude/skills
git clone https://github.com/robzilla1738/supergoal /tmp/supergoal-clone
cp -R /tmp/supergoal-clone/skills/supergoal ~/.claude/skills/
rm -rf /tmp/supergoal-clone

Codex CLI has no plugin marketplace, so the README's install is the same clone-and-copy against a different target. Restart Codex afterward, and re-run the same block to update later.

mkdir -p ~/.codex/skills
git clone https://github.com/robzilla1738/supergoal /tmp/supergoal-clone
cp -R /tmp/supergoal-clone/skills/supergoal ~/.codex/skills/
rm -rf /tmp/supergoal-clone

For a first real use, the README's example is a single line. Expect the planner to run Stages 0 through 6.5 before you see anything pasteable.

/supergoal build me an Expo app that converts photos to ASCII art

What you should see is a plan, a risk list, memory hits, and then one /goal command. You paste it once. The README states the install was verified end-to-end against the live repository, installing as supergoal@supergoal with roughly 307 always-on tokens and about 10k on invoke.

The one-paste design depends on an assumption about /goal

Supergoal's central claim is that a single /goal can cover an entire multi-phase run. The README explains why: on both hosts, /goal takes a short end-state condition that an evaluator checks against the transcript after each turn, not a long task body. Phase work lives in files the agent reads from disk, so there is no character budget to fight and no chain of sessions to keep alive.

That is a genuine architectural argument, and it is also the project's biggest dependency. Everything downstream assumes the end-state condition the planner writes is both short enough for /goal and checkable by the evaluator. The README does not document what happens when a condition is ambiguous, when the evaluator disagrees with the agent's own SUPERGOAL_PHASE_VERIFY result, or how the two verdicts are reconciled. The three-strike recovery handles build failures; it is not described as handling evaluator disagreement. Treat the /goal condition as the highest-risk artifact Supergoal produces, and read it before pasting.

The second assumption is stated plainly rather than hidden: slash commands only fire from user input, so Stage 7 cannot launch the run itself. The README calls this "an honest one-paste handoff". It is a host limitation, not a Supergoal choice, but it means the automation is never fully unattended from the planner's side.

Where Supergoal is the wrong tool

The install surface is the clearest boundary. Claude Code gets a marketplace flow; Codex CLI gets a manual clone-and-copy. There is no documented install for any other host, no container image, no package manager entry, and no hosted version. If your team standardizes on a different agent runtime, nothing in the README applies.

The second boundary is task shape. Greenfield work triggers the full category checklist in batches of up to four questions, which the README presents as thoroughness. For a small script or a bug fix, that intake is pure overhead, and the brownfield path only reduces it to "0 to 2 questions" rather than eliminating it.

Third, the failure escapes are stops, not recoveries. After the third strike the run hands off with full probe history, and after a third audit round it emits AUDIT_HANDOFF for persistent gaps. Those are correct safety choices, but they mean Supergoal does not promise completion on hard tasks. The README also does not document rollback, so a run that modifies a working tree and then stops leaves you to unwind it yourself. Commit or stash before you paste.

Supergoal versus a plain plan-then-execute loop

The honest alternative is what most people already do: ask the agent for a plan, then work through it turn by turn, re-prompting as you go. The README's comparison diagram labels that path as the toil case and contrasts it with Supergoal's single approval plus single paste.

The difference is not depth of planning so much as where the plan lives. In the turn-by-turn approach the plan exists in the conversation, and it degrades as context grows. Supergoal writes ROADMAP, STATE, and per-phase specs to disk and has the agent read them back, which is why the run can survive across many turns without a chain of sessions. The cost is that you now maintain planning artifacts in your repository, and stale ones are worse than none.

A second real difference is verification. The turn-by-turn loop has no built-in notion of a phase being done beyond your judgment. Supergoal defines SUPERGOAL_PHASE_VERIFY, a cleanliness grep, per-phase memory writeback, and a final audit that re-runs mandatory commands against the original ROADMAP. That is more machinery than a chat loop, and it is the part that justifies reading the flowchart before installing.

Maintenance, licence, and what upgrading costs you

The repository is not archived, and its last push was on 2026-08-18. There are no retrieved releases, so versioning appears to be by commit on the main branch rather than tagged versions. The README's update instructions match that: in Claude Code you re-run the marketplace install or `/plugin marketplace update supergoal`, and in Codex CLI you re-run the clone-and-copy block. There is no migration guide and no documented compatibility matrix between Supergoal versions and host versions.

The practical upgrade cost is the always-on token footprint. The README cites roughly 307 always-on tokens plus about 10k on invoke, which is the number to watch if the skill grows. Because the skill installs into ~/.claude/skills or ~/.codex/skills as a copied directory, a manual install will not pick up upstream changes until you copy again.

The licence is MIT, which permits commercial and private use with the usual requirement to preserve the copyright and licence notice. Nothing in the README describes a CLA, a commercial tier, or a hosted service with separate terms. This is a description of the repository metadata, not legal advice; read the LICENSE file in the clone before you redistribute.

Editorial conclusion

Adopt Supergoal if you already work inside Claude Code or Codex CLI and want the planning artifacts (ROADMAP, STATE, phase-N.md specs) written to disk before any code is touched. Skip it if you need a hosted service, a GUI, or any execution outside those two hosts, since the README describes only plugin/marketplace installation for Claude Code and a manual clone for Codex. Verify three things first: that skills/supergoal exists in the cloned repository, that ~/.claude/skills or ~/.codex/skills is the path your host actually reads, and that the /goal end-state condition the planner prints is one your session's evaluator can check against the transcript. The whole design rests on that last assumption, and it is the one to test on a throwaway task before you point it at a real repository.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. robzilla1738/supergoal on GitHub