{
  "markdown": "<p align=\"center\"><img src=\"logo.png\" width=\"120\" alt=\"logo\" /></p>\n\n# /supergoal\n\n**English** | [한국어](README.ko.md)\n\n**One objective in, a verified result out. The smallest correct change, checked against the real tests.**\nNothing extra to install. Clone the repo, symlink it into your skills directory, then run\n`/supergoal <objective>`.\nLanding page: [cskwork.github.io/supergoal-skill](https://cskwork.github.io/supergoal-skill/).\n\nAn agent skill for heavy coding objectives where a normal \"just edit it\" pass is too easy to fool. It\ntakes one objective, chooses the right workflow route, uses fresh-context roles for code delivery, makes\nthe smallest correct change, checks the request and project docs against the real behavior, then stops.\n\n## What `/supergoal` does\n\n`/supergoal` is a routing and verification wrapper around an agent. The useful mental model:\n\n1. **Route the objective.** The mode table classifies the real work kind, then routes as build,\n   debug, legacy change, spec, wayfinding, prototype, QA, review, architecture, teaching, domain\n   onboarding, harness eval, or skill mining.\n   Broad new-app builds stay GREENFIELD but first get a `wayfinder/` Frontier Map so only one vertical slice enters delivery.\n2. **Load only the needed playbook.** The root `SKILL.md` stays small; each route loads its own\n   `reference/` and `agents/` files only when needed.\n3. **Keep contexts fresh, keep dispatches few.** Code delivery runs five gates: Frame, Plan approval,\n   Build, Exact Verify/QA, Finalize. Each iteration uses one fresh-context builder and one auditor.\n   Browser and CLI work adds one evidence-only tester before the auditor. Frame discovers full-spec and\n   edge-case coverage into the plan. The builder implements only the approved plan. The tester captures\n   execution evidence. The auditor reruns the real tests and owns the verdict, the `GOAL.md` ticks, and\n   `R-LOOP.md`. One optional extra dispatch exists: a trigger-gated pre-Build plan attack for risky or\n   under-specified work.\n\n   Workflow weight comes in three tiers. LIGHT handles narrow tasks with an explicit spec, running the\n   same five gates with state held in context and no vault or role fan-out. STANDARD runs the full loop.\n   DEEP adds the plan attack and an uncapped clarifying interview. Saying \"quick\" or \"thorough\"\n   overrides the detection, and upgrades only go one way. Non-trivial runs spec out the request first:\n   interview answers complete the `GOAL.md` spec, with Given/When/Then criteria, before `PLAN.md`\n   exists. User-facing reports follow `reference/reporting.md`. Outcome first, Simplified Technical\n   English, the project's own vocabulary.\n4. **Run Before/After Eval.** Capture the before state, define the after target, write a completion\n   promise, and keep a resumable run state plus command manifest so the final claim proves the delta\n   instead of just saying \"tests passed.\"\n5. **Prove against the real project.** A green test run does not settle it. The run re-reads the whole\n   spec and verifies against the repo's real tests, browser checks, DB evidence when that carries\n   weight, and the prose spec. Hidden requirements the verifier finds become durable `GOAL.md` criteria,\n   and the builder covers them red-first.\n6. **Stop at the verified result.** No open-ended refactor, no proxy checklist, no fake green.\n\n## What it adds over a plain baseline\n\nA strong model reading the real spec is the bar. `/supergoal` adds the part a plain baseline skips\nunder pressure. A user-reviewed goal plan that already enumerates spec coverage and edge cases. A\nbuilder that must exit green. An independent verifier that tries to disprove the result against the\nproject's own tests and docs, with the evidence recorded. Once invoked for code delivery, `/supergoal`\nuses the role loop instead of downgrading to an inline shortcut.\n\nEach role is a bundled file in `agents/`, so dispatch stays harness-agnostic across Claude Code, Codex,\nagy, and other agent CLIs. Frame, Plan approval, Build, Exact Verify/QA, and Finalize are the mandatory\ncore. The conditional plan attack stays available when the requirements have not surfaced yet. The\nconductor stays lean. Subagents load the heavy references for their own phase, and independent units\nrun in parallel.\n\n## Principles\n\n- **Verify against ground truth.** Re-run the project's REAL tests and re-read the request, ticket,\n  README, design/API docs, and repo rules for checks the tests miss. Never generate a proxy\n  checklist/verifier and optimize to it.\n- **Smallest correct change.** Match the surrounding code; no whole-file rewrites to change a few lines.\n- **Forced verification before trust.** After Build, compare the request/docs with the current behavior,\n  even when visible tests are green; the plan attack is reserved for latent requirement risk.\n- **Before/After Eval for real code changes.** GREENFIELD proves what was absent or red before. DEBUG\n  reproduces the symptom. LEGACY and brownfield capture the behavior to preserve before changing it.\n- **Ask only when genuinely ambiguous.** Resolve code-answerable questions by reading the code.\n- **Hard stops.** A destructive or irreversible step needs consent. If the real tests cannot pass,\n  report that. Never fake a pass.\n- **Standing rules (read first).** If the target project has `.supergoal/rules/RULES.md`, supergoal reads\n  it before every run and honors it across all modes as the highest-priority preferences. It never\n  weakens a safety gate. The file is created only when you ask, is gitignored, and is otherwise left\n  untouched (`reference/rules.md`).\n\n## Modes\n\n`/supergoal` detects the mode from your objective:\n\n```mermaid\nflowchart TD\n    A[\"/supergoal <one heavy objective>\"] --> B[\"Frame the goal<br/>acceptance criteria<br/>hidden risks\"]\n    B --> C{\"Route by objective\"}\n\n    C -->|\"build / make / ship\"| GREENFIELD[\"GREENFIELD<br/>new app or tool\"]\n    C -->|\"fix / broken / failing\"| DEBUG[\"DEBUG<br/>reproduce, diagnose, fix\"]\n    C -->|\"add / integrate / refactor\"| LEGACY[\"LEGACY<br/>map existing code first\"]\n    C -->|\"spec / requirements / roadmap\"| WAYFINDER[\"WAYFINDER<br/>map -> ticket depth -> frontier\"]\n    C -->|\"prototype / spike\"| PROTOTYPE[\"PROTOTYPE<br/>throwaway proof\"]\n    C -->|\"QA / verify only\"| QAONLY[\"QA-ONLY<br/>Impact Matrix + evidence\"]\n    C -->|\"review / audit\"| REVIEW[\"REVIEW-ONLY<br/>findings, no fixes\"]\n    C -->|\"architecture improvement\"| ARCHITECTURE[\"ARCHITECTURE<br/>friction survey -> candidates\"]\n    C -->|\"explain / teach\"| TEACH[\"TEACH<br/>stateful teaching workspace\"]\n    C -->|\"learn / onboard\"| LEARN[\"LEARN-DOMAIN<br/>persist domain wiki\"]\n    C -->|\"harness effectiveness\"| HARNESS[\"HARNESS-EVAL<br/>baseline vs harness\"]\n    C -->|\"make a reusable skill\"| SKILLMINE[\"SKILL-MINE<br/>mine -> forge -> install\"]\n\n    GREENFIELD --> LOOP[\"Default delivery loop<br/>Frame -> Plan approval -> Build<br/>-> Exact Verify/QA -> Finalize<br/>(plan attack opt-in)\"]\n    DEBUG --> LOOP\n    LEGACY --> LOOP\n\n    WAYFINDER --> REPORT\n    PROTOTYPE --> REPORT\n    ARCHITECTURE --> PICK[\"Grill chosen candidate<br/>then route to LEGACY or WAYFINDER\"]\n\n    QAONLY --> REPORT[\"No product code by default<br/>report evidence and risk\"]\n    REVIEW --> REPORT\n    TEACH --> REPORT\n    LEARN --> REPORT\n    HARNESS --> REPORT\n    SKILLMINE --> REPORT\n```\n\n| Objective looks like | Mode | Approach |\n|---|---|---|\n| \"build / ship a new app/tool\" | **GREENFIELD** | default loop; broad/foggy app requests first use a `wayfinder/` Frontier Map, then one selected vertical slice enters Build |\n| \"fix / broken / failing / why does\" | **DEBUG** | default loop; reproduce with a failing test first |\n| \"add X to our existing/legacy code\" | **LEGACY** | default loop; map the code first; refactoring an existing API: capture its exact behavior first, Verify diffs against that baseline |\n| \"spec this / break this into tickets / roadmap / what first?\" | **WAYFINDER** | issue map under the run vault's `wayfinder/` folder -> optional ticket-depth sections (glossary, user story, EARS checks, design notes, tasks) and cited research assets via `reference/research.md` when outside facts are needed -> vertical tickets -> blocker edges -> next frontier; route one ticket, stop, then ask for context clear + integration test before the next |\n| \"prototype / spike / try variants before building\" | **PROTOTYPE** | throwaway proof answers one question; UI/interaction prototypes load SuperDesign for design and render gates; then delete/quarantine or route the decision into delivery |\n| \"explain / teach me X\" (no code) | **TEACH** | Mission -> Source -> Bridge -> Teach (Archify when relationships matter) -> Check (explain-back) |\n| \"learn / map / onboard onto this codebase\" | **LEARN-DOMAIN** | Survey -> Map -> Ground -> Persist a `.domain-agent/` wiki |\n| \"QA only / verify / compare data - no code\" | **QA-ONLY** | Detailed Impact Matrix (feature-impact QA map) + read-only DB -> evidence -> `report.md` |\n| \"review / audit this code/diff/PR - no fixes\" | **REVIEW-ONLY** | Two independent reviewers -> verified findings -> `report.md` |\n| \"improve the architecture / find refactoring opportunities\" or \"draw / diagram / 그려\" (arch, flow, sequence, state) | **ARCHITECTURE** | Draw-only ask: render a self-contained HTML diagram via archify and stop. Else friction survey -> candidates as a visual `report.html` -> grill the pick -> refactor routes to LEGACY/WAYFINDER |\n| \"test harness effectiveness / with vs without\" | **HARNESS-EVAL** | Cases -> baseline run -> harness run -> machine checks -> quality score -> compare |\n| \"make a skill from history - no product code\" | **SKILL-MINE** | Mine history -> rank -> you pick -> forge portable `SKILL.md` -> install |\n\n**Default loop (GREENFIELD / DEBUG / LEGACY):**\n\n1. **Frame** the goal: write `GOAL.md` first (the user's request verbatim + refined spec + falsifiable\n   Success Criteria checkboxes + browser QA cases for web apps), freeze a self-sufficient `PLAN.md`\n   (steps, tools & skills, verification strategy), start `QA.md` `## Before` plus `run-state.json`.\n   The Success Criteria already enumerate full-spec coverage and edge-case/resilience checks, so the\n   user reviews them at the next gate. For broad GREENFIELD requests, Frame first writes an internal\n   `wayfinder/map.md`, creates vertical tickets under `wayfinder/tickets/`, selects the first unblocked\n   frontier, and copies only that ticket's acceptance checks into delivery. The route remains\n   GREENFIELD; WAYFINDER stays the explicit no-code planning mode.\n2. **Plan approval.** The user reviews the goal plan. An interactive session needs the user's explicit\n   OK; an autonomous run auto-approves and records that. Build never starts before this gate.\n3. **Build** the smallest correct change in one fresh-context implementer briefed by `PLAN.md` alone,\n   test-first, so a bug gets a failing test first. The builder covers every planned criterion in the\n   plan's `## Acceptance checklist`, including the edge-case and resilience criteria discovered at\n   Frame, and exits only on a green suite.\n4. **Exact Verify/QA** with a fresh-context auditor in an adversarial stance. Browser/CLI work first\n   dispatches an evidence-only tester for real scenarios and captures, then the auditor consumes that\n   evidence, reruns the real non-browser tests, diffs the change against `GOAL.md`, ticks proven\n   criteria, and owns the final verdict. Non-browser work goes directly to the auditor. Unmet criteria\n   go to a timestamped `R-LOOP.md` section and the implementer relaunches. That loop-back is the only\n   fix channel.\n5. **Finalize.** Stop only after every `GOAL.md` box is checked and the `Z-<date>.md` completion marker\n   (run branch plus timestamp) is written with the command output recorded. Then pass the commit gate\n   and merge after user acceptance. The Build to Verify loop caps at 3 iterations by default, forces a\n   reflection, then escalates to the user.\n\nCoding and debug runs use a run worktree by default. Resolve and verify the source/base branch and the\ntarget/integration branch before editing, create the run worktree from source/base, and commit or merge\ninto the verified target/integration branch only after green verification and user acceptance. Browser\nUI changes also require real browser QA: `Tool: agent-browser` evidence and\n`qa-gate.sh <vault> browser`.\n\n```text\n/supergoal build a habit-tracker app and ship it\n/supergoal the checkout page hangs intermittently in prod. fix it\n/supergoal add SSO to our legacy Django monolith\n/supergoal break this billing migration into tickets with blockers and tell me what to do first\n/supergoal prototype three checkout flows before we commit to the implementation\n/supergoal learn this codebase and build a domain wiki\n/supergoal QA the checkout flow on staging and check the order totals match the DB (no code change)\n/supergoal compare this migration harness with and without the harness on 3 cases\n```\n\nWAYFINDER, PROTOTYPE, QA-ONLY, REVIEW-ONLY, ARCHITECTURE, TEACH/LEARN-DOMAIN, HARNESS-EVAL, and\nSKILL-MINE each serve a separate purpose: ticket maps, throwaway proofs, detailed no-code QA,\nfindings-only review, teaching and onboarding, harness measurement, and skill forging. QA-ONLY is the\nbroad regression lane. Its Impact Matrix maps everything the feature can affect: displayed data\nconsistency, direct behavior, adjacent screens, complex multi-step scenarios, before/during/after\nactions, and the risk left uncovered inside the action cap. Independent QA areas can run as scenario\nshards, and the conductor merges them through `qa/scenario-ledger.md`.\nThese modes write no product code by default. PROTOTYPE writes only isolated throwaway code and has to\nroute back through delivery before anything ships. UI and interaction prototypes load SuperDesign;\nlogic/state and data/API prototypes keep their lightweight, non-visual paths.\n\n## Board (optional live dashboard)\n\nWatch progress across concurrent agents in real time. `bash tui/launch.sh &` opens a Textual dashboard\nin the browser. It shows each agent's mode and workflow stage, from Frame through Plan approval, Build,\nExact Verify/QA, and Finalize, with the plan attack appearing only when escalated. A Jira-like task\nboard groups the agents by repo, branch, and worktree. Branch is advisory and never locked, so several\nagents can share a branch freely.\n\nThe Board only observes. It is opt-in, best-effort, and it never gates or blocks a run. If no agent\nemits, every mode still passes unchanged. When enabled, the conductor calls `sg-emit`\n(`templates/observability/`) at each phase transition, writing one atomically-replaced heartbeat JSON\nper agent under `~/.supergoal/runs/agents/`. The dashboard in `tui/` polls and renders them.\nCorrectness needs only one writer per file plus an atomic rename, so there is no lock anywhere.\nIn-browser serving needs `pip install textual-serve`; without it, run the local TUI with\n`python -m tui.app`. Full spec: [`reference/observability.md`](reference/observability.md).\n\n## Install\n\nThis repo **is** the skill. Put it where your agent CLI finds skills:\n\n```bash\ngit clone https://github.com/cskwork/supergoal-skill.git\ncd supergoal-skill\nSRC=\"$(pwd)\"\nmkdir -p ~/.agents/skills ~/.codex/skills ~/.claude/skills\n\n# Recommended: one canonical source checkout, symlinked into each active agent.\n# If a target already exists, audit it first and preserve any local edits before replacing it.\nln -s \"$SRC\" ~/.agents/skills/supergoal\nln -s \"$SRC\" ~/.codex/skills/supergoal\nln -s \"$SRC\" ~/.claude/skills/supergoal\n\n# Read-only drift check for active installs:\nnode templates/skill-install-audit.mjs \"$SRC\"\n\n# Canonical repo verification:\nbash tests/run-all.sh\n```\n\nThen in your agent CLI: `/supergoal <your objective>`.\n\n### Windows\n\nThe skill runs on Windows. The remaining gate and test scripts are POSIX shell, so run them under Git\nBash or WSL, with `node` on `PATH`. The repo pins `.gitattributes eol=lf`. If symlinks need admin\nrights, install by copy instead: `cp -R` in Git Bash or WSL, or `mklink /D` from an elevated `cmd`.\nAfter copying, run `node templates/skill-install-audit.mjs <source-skill-dir>`, then run the contract\ntests under WSL bash.\n\n## Layout\n\n```\nSKILL.md            thin spine: baseline-first loop, modes, reference map\nagents/             one persona file per role (analyst, architect, executor, debugger, explore, designer, qa-*, db-reader, code-reviewer, security-reviewer)\nreference/          domain-rules · rules (project standing rules) · domain-context · debugging · interview · reporting · delivery-gate · plan-grounding · research · market-research · qa · qa-only · db-access · teach · learn-domain · ui-ux · taste-skill-v2 · functional-ui · harness-eval · skill-mine · observability\nteach/              TEACH-mode format guides + per-topic teaching workspaces\ntemplates/          GOAL.md · PLAN.md · QA.md · R-LOOP.md · Z-DONE.md · run-state.json · rules.md · qa-gate.sh · qa-only-gate.sh · commit-gate.sh · contrast-gate.mjs · learn-grounding-gate.mjs · qa-report.md · db-access/ · domain-agent/ · domain-onboarding.html · arch-report.html · harness-eval-gate.mjs · harness-eval-stats.mjs · harness-eval-cases/ · skill-mine/ · skill-frontmatter-gate.mjs · skill-install-audit.mjs · skill.md.template · observability/ (sg-emit board state)\ntests/              contract tests + run-all.sh canonical verifier\ntui/                optional live Board: state.py (reader) · app.py (Textual UI) · serve.py (in-browser) · launch.sh\ndocs/               DESIGN.md · research-brief.md · experiments/ (the harness evals) · changelog/ · index.html (landing)\nexamples/           optional worked services when vendored; run-all skips them when absent\n```\n\n## Evidence\n\nThe design comes out of head-to-head evals, especially\n`docs/experiments/2026-07-01-roleloop-coverage-fix-claude-ab/FINDINGS.md` and\n`docs/harness-eval-explained.md`. One result shapes the current skill. On tasks with an explicit spec,\nthe request/docs verification pass beat the one-shot baseline, and it matched or beat role separation\nat lower ceremony. Generated-proxy verifiers can score worse, because the run optimizes to the proxy.\nThe next thing to prove is not more synthetic fixtures. It is the production-adoption plan in\n`docs/changelog/2026-07/02-production-adoption/plan.md`, which tracks symlink deployment, trigger\naccuracy, and production pilot metrics: date, mode, gaps, and gate results. Older worked examples may\nbe vendored under `examples/`; the canonical verifier skips that optional step when they are absent.\n\n## Harness eval reference\n\nHARNESS-EVAL reusable sample cases come from RevFactory's `claude-code-harness`:\nhttps://github.com/revfactory/claude-code-harness/\n\nCurrent HARNESS-EVAL claims use four axes: task correctness, token/cost, wall-clock speed, and routing\naccuracy. Binary pass/fail comparisons use paired McNemar with SNR filtering; gradient quality scores\nkeep the existing sign-flip/BCa gate.\n\n## Credit\n\nConcept and workflow adapted from oh-my-symphony by cskwork\n(https://github.com/cskwork/oh-my-symphony). WAYFINDER and the research-depth ideas also credit\nMatt Pocock's public skills, especially the research and skill-writing patterns. UI and interaction\nprototypes route through cskwork's superdesign-skill\n(https://github.com/cskwork/superdesign-skill).\n\n## License\n\nMIT. See [`LICENSE`](LICENSE).\n",
  "bytes": 19459,
  "sha": "1fd5f82768cf8af6e3e86c48394fefc1395a779a2fe860ba89257d5fb589a36d",
  "repo_slug": "cskwork/supergoal-skill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_cskwork_supergoal_skill_ea47cf7d/readme"
}