supergoal

A durable state machine for Claude Code.
Work survives /clear. Nothing is "done" until a command actually exits 0.

The problem

Claude Code loses everything on /clear, on compaction, and between sessions. The usual workarounds do not hold:

• Notes in CLAUDE.md get stale the moment work moves on, and nobody updates them mid-task.
• Asking the model to remember fails by definition — the context is gone.
• Telling the model to "check a status file" is probabilistic. It reads the file when it remembers to, which is exactly not the moment you need it.

And separately: an agent that reports its own success is grading its own homework. "Done" too often means the model believes it is done.

What this does

Two things, and only two.

1. Recovery is deterministic, not remembered. A SessionStart hook runs on startup, resume, clear, and compact. The harness executes it — not the model — so the resume block is in context before the first action of the session. A fresh session opens with this already on screen:

[projstate] resume  phase=BLOCKED  updated=2026-09-21T14:30:27Z
goal:      Add rate limiter
done_when: go test ./internal/rl/... passes
units:     1/2 passed
  [ ] metrics  verify: go test ./internal/rl -run Metrics
now:       limiter
NEXT:      implement token bucket
BLOCKER:   metrics verify failed (exit 1)
git:       main @ 3f1a2c4 wire limiter  dirty=3
memory:    2 verified lesson(s), most recent:
  - bucket refill must use monotonic clock

Nobody typed anything. Nobody had to remember the project existed.

2. Verification is grounded, not self-reported. A unit becomes passed only when its verify command really exits 0. projstate.py verify runs the command and lets the exit code decide. A non-zero exit marks the unit failed, moves the phase to BLOCKED, and records the blocker. The agent cannot write "passed" into the state by concluding that it worked.

This grounding rule is borrowed from RSIAgent (Aether Labs, UCSD, UIC), whose Verifier Agent validates execution independently of the Actor's reasoning. Its exploration machinery is not reused here — broad autonomous exploration makes sense for an unknown GUI environment, not for your repository.

What it does not do. It does not make the model smarter. Weights do not change; RSIAgent is explicit that "model parameters stay fixed". What improves is task performance: state stops evaporating, verification stops being self-graded, and hard-won facts stop being rediscovered.

Architecture

Three layers, each doing a job the others cannot.

The split matters: the hook cannot be replaced by the skill. After /clear there is nobody present to invoke a skill. Recovery must not depend on anyone remembering anything.

Install

git clone https://github.com/uk0/supergoal.git
cd supergoal
./install.sh

Then append the contract so Claude knows how to drive the loop:

cat docs/claude-md-snippet.md >> ~/.claude/CLAUDE.md

The installer is idempotent, backs up settings.json before touching it, and merges into existing SessionStart hooks rather than replacing them. Options:

./install.sh --no-hook          # skip the settings.json change
CLAUDE_DIR=/tmp/x ./install.sh  # install somewhere else

Requires python3 (stdlib only) and Claude Code with hooks support.

Use

/supergoal Ship the auth refactor

Natural language works too — the skill triggers on "我们做到哪了", "继续上次", "where were we", "what's next".

How it works

ORIENT -> PLAN -> EXECUTE -> VERIFY -> CHECKPOINT -> next unit, or DONE
                                 |
                                 +-- non-zero exit -> BLOCKED

Exactly one phase is current, and the state file always names it.

The next field is the whole recovery contract: it must be runnable by a session holding zero other context.

CLI

The skill drives these for you, but they are a normal CLI:

projstate.py bootstrap                      # resume block (what the hook runs)
projstate.py init --goal T [--done-when T]
projstate.py set --phase P [--now T] [--next T] [--blocker T]
projstate.py unit add NAME --verify CMD [--path P]
projstate.py verify NAME                    # exit code decides the unit
projstate.py lesson add TEXT --evidence CMD [--tag T]
projstate.py memory [--limit N]
projstate.py checkpoint [--note T]

Memory

lesson add requires --evidence, the command that proved the claim. Without it the lesson is stored unverified and is explicitly not to be relied on later:

projstate.py lesson add "sqlx offline mode needs SQLX_OFFLINE=true or the build hits the DB" \
  --evidence "cargo build --offline" --tag build

Verified lessons are replayed on every bootstrap, so the next session starts knowing what the last one learned the hard way.

Design notes

• Silent by default. In a repository that never used the loop, the hook prints nothing. No nagging.
• State is a claim, not proof. Bootstrap reconciles against git status and git log, and flags a mismatch when the phase says settled but the tree is dirty. Runtime evidence wins.
• Scale to the task. A one-line fix does not need a state machine. This is for multi-step, cross-session, or multi-agent work.
• Your data is yours. uninstall.sh removes the script, the skill, and the hook entries. It never touches .claude/state/.

Uninstall

./uninstall.sh

Credits

The verification-grounding and memory-replay design follows RSIAgent: Autonomous Exploration for Recursive Self-improvement in New Environments — Aether Labs with UCSD and UIC. The logo was generated with Codex.

License

MIT — see LICENSE.