supergoal

/supergoal

English | 한국어

One objective in, a verified result out. The smallest correct change, checked against the real tests. Nothing extra to install. Clone the repo, symlink it into your skills directory, then run /supergoal <objective>. Landing page: cskwork.github.io/supergoal-skill.

An agent skill for heavy coding objectives where a normal "just edit it" pass is too easy to fool. It takes one objective, chooses the right workflow route, uses fresh-context roles for code delivery, makes the smallest correct change, checks the request and project docs against the real behavior, then stops.

What /supergoal does

/supergoal is a routing and verification wrapper around an agent. The useful mental model:

1. Route the objective. The mode table classifies the real work kind, then routes as build, debug, legacy change, spec, wayfinding, prototype, QA, review, architecture, teaching, domain onboarding, harness eval, or skill mining. Broad new-app builds stay GREENFIELD but first get a wayfinder/ Frontier Map so only one vertical slice enters delivery.

2. Load only the needed playbook. The root SKILL.md stays small; each route loads its own reference/ and agents/ files only when needed.

3. Keep contexts fresh, keep dispatches few. Code delivery runs five gates: Frame, Plan approval, Build, Exact Verify/QA, Finalize. Each iteration uses one fresh-context builder and one auditor. Browser/CLI work adds one evidence-only tester before the auditor. Frame discovers full-spec and edge-case coverage into the plan. The builder implements only the approved plan. The tester captures execution evidence. The auditor reruns the real tests and owns the verdict, the GOAL.md ticks, and R-LOOP.md. One optional extra dispatch exists: a trigger-gated pre-Build plan attack for risky or under-specified work.

   Workflow weight comes in three tiers. LIGHT handles narrow tasks with an explicit spec, running the same five gates with state held in context and no vault or role fan-out. STANDARD runs the full loop. DEEP adds the plan attack and an uncapped clarifying interview. Saying "quick" or "thorough" overrides the detection, and upgrades only go one way. Non-trivial runs spec out the request first: interview answers complete the GOAL.md spec, with Given/When/Then criteria, before PLAN.md exists. User-facing reports follow reference/reporting.md. Outcome first, Simplified Technical English, the project's own vocabulary.

4. Run Before/After Eval. Capture the before state, define the after target, write a completion promise, and keep a resumable run state plus command manifest so the final claim proves the delta instead of just saying "tests passed."

5. Prove against the real project. A green test run does not settle it. The run re-reads the whole spec and verifies against the repo's real tests, browser checks, DB evidence when that carries weight, and the prose spec. Hidden requirements the verifier finds become durable GOAL.md criteria, and the builder covers them red-first.

6. Stop at the verified result. No open-ended refactor, no proxy checklist, no fake green.

What it adds over a plain baseline

A strong model reading the real spec is the bar. /supergoal adds the part a plain baseline skips under pressure. A user-reviewed goal plan that already enumerates spec coverage and edge cases. A builder that must exit green. An independent verifier that tries to disprove the result against the project's own tests and docs, with the evidence recorded. Once invoked for code delivery, /supergoal uses the role loop instead of downgrading to an inline shortcut.

Each role is a bundled file in agents/, so dispatch stays harness-agnostic across Claude Code, Codex, agy, and other agent CLIs. Frame, Plan approval, Build, Exact Verify/QA, and Finalize are the mandatory core. The conditional plan attack stays available when the requirements have not surfaced yet. The conductor stays lean. Subagents load the heavy references for their own phase, and independent units run in parallel.

Principles

• Verify against ground truth. Re-run the project's REAL tests and re-read the request, ticket, README, design/API docs, and repo rules for checks the tests miss. Never generate a proxy checklist/verifier and optimize to it.
• Smallest correct change. Match the surrounding code; no whole-file rewrites to change a few lines.
• Forced verification before trust. After Build, compare the request/docs with the current behavior, even when visible tests are green; the plan attack is reserved for latent requirement risk.
• Before/After Eval for real code changes. GREENFIELD proves what was absent or red before. DEBUG reproduces the symptom. LEGACY and brownfield capture the behavior to preserve before changing it.
• Ask only when genuinely ambiguous. Resolve code-answerable questions by reading the code.
• Hard stops. A destructive or irreversible step needs consent. If the real tests cannot pass, report that. Never fake a pass.
• Standing rules (read first). If the target project has .supergoal/rules/RULES.md, supergoal reads it before every run and honors it across all modes as the highest-priority preferences. It never weakens a safety gate. The file is created only when you ask, is gitignored, and is otherwise left untouched (reference/rules.md).

Modes

/supergoal detects the mode from your objective:

flowchart TD
    A["/supergoal <one heavy objective>"] --> B["Frame the goal<br/>acceptance criteria<br/>hidden risks"]
    B --> C{"Route by objective"}

    C -->|"build / make / ship"| GREENFIELD["GREENFIELD<br/>new app or tool"]
    C -->|"fix / broken / failing"| DEBUG["DEBUG<br/>reproduce, diagnose, fix"]
    C -->|"add / integrate / refactor"| LEGACY["LEGACY<br/>map existing code first"]
    C -->|"spec / requirements / roadmap"| WAYFINDER["WAYFINDER<br/>map -> ticket depth -> frontier"]
    C -->|"prototype / spike"| PROTOTYPE["PROTOTYPE<br/>throwaway proof"]
    C -->|"QA / verify only"| QAONLY["QA-ONLY<br/>Impact Matrix + evidence"]
    C -->|"review / audit"| REVIEW["REVIEW-ONLY<br/>findings, no fixes"]
    C -->|"architecture improvement"| ARCHITECTURE["ARCHITECTURE<br/>friction survey -> candidates"]
    C -->|"explain / teach"| TEACH["TEACH<br/>stateful teaching workspace"]
    C -->|"learn / onboard"| LEARN["LEARN-DOMAIN<br/>persist domain wiki"]
    C -->|"harness effectiveness"| HARNESS["HARNESS-EVAL<br/>baseline vs harness"]
    C -->|"make a reusable skill"| SKILLMINE["SKILL-MINE<br/>mine -> forge -> install"]

    GREENFIELD --> LOOP["Default delivery loop<br/>Frame -> Plan approval -> Build<br/>-> Exact Verify/QA -> Finalize<br/>(plan attack opt-in)"]
    DEBUG --> LOOP
    LEGACY --> LOOP

    WAYFINDER --> REPORT
    PROTOTYPE --> REPORT
    ARCHITECTURE --> PICK["Grill chosen candidate<br/>then route to LEGACY or WAYFINDER"]

    QAONLY --> REPORT["No product code by default<br/>report evidence and risk"]
    REVIEW --> REPORT
    TEACH --> REPORT
    LEARN --> REPORT
    HARNESS --> REPORT
    SKILLMINE --> REPORT

Default loop (GREENFIELD / DEBUG / LEGACY):

1. Frame the goal: write GOAL.md first (the user's request verbatim + refined spec + falsifiable Success Criteria checkboxes + browser QA cases for web apps), freeze a self-sufficient PLAN.md (steps, tools & skills, verification strategy), start QA.md ## Before plus run-state.json. The Success Criteria already enumerate full-spec coverage and edge-case/resilience checks, so the user reviews them at the next gate. For broad GREENFIELD requests, Frame first writes an internal wayfinder/map.md, creates vertical tickets under wayfinder/tickets/, selects the first unblocked frontier, and copies only that ticket's acceptance checks into delivery. The route remains GREENFIELD; WAYFINDER stays the explicit no-code planning mode.
2. Plan approval. The user reviews the goal plan. An interactive session needs the user's explicit OK; an autonomous run auto-approves and records that. Build never starts before this gate.
3. Build the smallest correct change in one fresh-context implementer briefed by PLAN.md alone, test-first, so a bug gets a failing test first. The builder covers every planned criterion in the plan's ## Acceptance checklist, including the edge-case and resilience criteria discovered at Frame, and exits only on a green suite.
4. Exact Verify/QA with a fresh-context auditor in an adversarial stance. Browser/CLI work first dispatches an evidence-only tester for real scenarios and captures, then the auditor consumes that evidence, reruns the real non-browser tests, diffs the change against GOAL.md, ticks proven criteria, and owns the final verdict. Non-browser work goes directly to the auditor. Unmet criteria go to a timestamped R-LOOP.md section and the implementer relaunches. That loop-back is the only fix channel.
5. Finalize. Stop only after every GOAL.md box is checked and the Z-<date>.md completion marker (run branch plus timestamp) is written with the command output recorded. Then pass the commit gate and merge after user acceptance. The Build to Verify loop caps at 3 iterations by default, forces a