Skill

---
name: supergoal
description: "Drive the durable project state machine (projstate): start a goal, decompose it into independently verifiable units, run the verify loop, checkpoint progress, and replay verified memory across context loss. Use when the user wants to start or resume a multi-step goal, asks where the work stands or what was in flight, wants progress that survives /clear or compaction, wants to mark a unit verified, or types /supergoal. Triggers on: 立目标, 开始任务, 继续上次, 我们做到哪了, 恢复进度, 状态机, checkpoint, resume work, where were we, what's next, track this goal."
---

# supergoal

Drives `~/.claude/scripts/projstate.py`, the durable state machine defined in `<project_state>` of the global `CLAUDE.md`. Canonical state is `.claude/state/state.json`; `.claude/state/STATUS.md` is its rendered view; verified experience lives in `.claude/state/memory.jsonl`.

A `SessionStart` hook already runs `bootstrap --quiet` on startup, resume, clear, and compact — recovery is automatic and this skill does not need to re-implement it. This skill is the **driving** half: creating goals, decomposing them, running verification, and checkpointing.

Set once per session for brevity:

```bash
PS="python3 ~/.claude/scripts/projstate.py"
```

## Dispatch on the argument

| Invocation | Action |
|---|---|
| `/supergoal` or `status` | `$PS bootstrap` — report phase, `next`, blockers, verified lessons. Stop there unless told to continue. |
| `/supergoal <goal text>` | Start a goal. If state already exists, show it and confirm before overwriting. |
| `/supergoal next` / `continue` | `$PS bootstrap`, then execute the `next` field. |
| `/supergoal verify [unit]` | `$PS verify <unit>` — never mark work done any other way. |
| `/supergoal done` | Verify every pending unit, then `$PS set --phase DONE` and `$PS checkpoint`. |

## Starting a goal

1. `$PS bootstrap` first — never overwrite live state blindly.
2. Restate the goal in one line and fix `done_when` as an **observable** condition (a command that exits 0, a behavior that can be demonstrated). Reject vague goals: "improve performance" becomes "p99 under 200ms measured by `bench/run.sh`".
3. `$PS init --goal "..." --done-when "..."`
4. Decompose into units that can each be verified alone. For every unit supply a real command:
   ```bash
   $PS unit add parser --verify "cargo test -p parser" --path crates/parser
   $PS unit add api    --verify "go test ./internal/api/..." --path internal/api
   ```
   A unit with no runnable verify command is not a unit — split it or define the check first.
5. `$PS set --phase EXECUTE --now <unit> --next "<exact next action>"`

## The loop

`ORIENT -> PLAN -> EXECUTE -> VERIFY -> CHECKPOINT -> next unit, or DONE`

Work one unit at a time. After each unit:

```bash
$PS verify <unit>        # exit 0 promotes it; anything else marks it failed and blocks
$PS set --next "<the exact next action>"
$PS checkpoint --note "<what changed>"
```

Keep `next` runnable by a session holding zero other context — that field is the whole recovery contract.

## Rules that make this worth running

- **Verification is not self-reported.** A unit passes only when its command actually exits 0. Do not edit state to say `passed`; run `$PS verify`. A non-zero exit sets the unit to `failed` and the phase to `BLOCKED` — report the failure rather than routing around it.
- **Checkpoint at transitions, not on a timer.** A unit passes; before and after a risky or irreversible step; before delegating; after a handoff; on a decisive failure; at the end of any turn that changed code or state. Never let state lag the working tree.
- **Record only grounded lessons.** When execution proves something non-obvious, attach the command that proved it:
  ```bash
  $PS lesson add "sqlx offline mode needs SQLX_OFFLINE=true or the build hits the DB" --evidence "cargo build --offline" --tag build
  ```
  Without `--evidence` it is stored unverified and must not be relied on later. Read `$PS memory` at ORIENT and do not re-derive what it already proves; if a lesson contradicts current runtime evidence, re-verify and correct it.
- **Blocked is a real state.** On a decisive failure: `$PS set --blocker "<what is needed to get unstuck>"`. Do not silently retry the same thing — change an input, environment, dependency, timing, or assumption first.
- **Scale to the task.** A one-line fix does not need a state machine. Engage this for multi-step, cross-session, or multi-agent work. If state already exists, keep it current even for small changes.

## Reporting back

Lead with phase and the next action, then evidence. One or two lines is usually right:

> `EXECUTE` — parser verified (`cargo test -p parser`, exit 0), 2/3 units done. Next: wire the API handler.

Do not paste raw `STATUS.md` at the user unless asked; it is a machine artifact.