Skip to content

cskwork/supergoal-skill / skills/supergoal

supergoal

Unverified

Route objective-driven development, verification, planning, "teach/explain", codebase learning, and skill evaluation through the Supergoal workflow. Use when Supergoal is requested or an autonomous delivery workflow is needed.

FileKindSize
SKILL.mdskill md12.8 KB
agents/analyst.mdmarkdown1.5 KB
agents/architect.mdmarkdown1.7 KB
agents/code-reviewer.mdmarkdown2.5 KB
agents/db-reader.mdmarkdown2.0 KB
agents/debugger.mdmarkdown2.0 KB
agents/designer.mdmarkdown6.3 KB
agents/executor.mdmarkdown2.8 KB
agents/explore.mdmarkdown2.0 KB
agents/qa-auditor.mdmarkdown4.3 KB
agents/qa-tester.mdmarkdown3.2 KB
agents/security-reviewer.mdmarkdown1.2 KB
agents/skill-forger.mdmarkdown1.6 KB
agents/skill-miner.mdmarkdown1.6 KB
reference/agent-browser.mdmarkdown2.8 KB
reference/arch.mdmarkdown5.1 KB
reference/archify.mdmarkdown3.6 KB
reference/db-access.mdmarkdown2.9 KB
reference/debugging.mdmarkdown6.5 KB
reference/delivery-gate.mdmarkdown6.6 KB
reference/domain-context.mdmarkdown7.8 KB
reference/domain-rules.mdmarkdown1.6 KB
reference/engagement.mdmarkdown3.8 KB
reference/functional-ui.mdmarkdown6.4 KB
reference/harness-eval.mdmarkdown28.7 KB
reference/interview.mdmarkdown7.7 KB
reference/learn-domain.mdmarkdown12.7 KB
reference/market-research.mdmarkdown1.7 KB
reference/observability.mdmarkdown5.0 KB
reference/plan-grounding.mdmarkdown4.3 KB
reference/playwright-cli.mdmarkdown2.6 KB
reference/prototype.mdmarkdown4.5 KB
reference/qa-only.mdmarkdown12.7 KB
reference/qa.mdmarkdown7.9 KB
reference/reporting.mdmarkdown1.5 KB
reference/research.mdmarkdown2.7 KB
reference/review-only.mdmarkdown2.4 KB
reference/role-loop.mdmarkdown26.7 KB
reference/rules.mdmarkdown982 B
reference/skill-mine.mdmarkdown7.6 KB
reference/taste-aesthetics.mdmarkdown7.5 KB
reference/taste-skill-v2.mdmarkdown18.8 KB
reference/taste-sources.mdmarkdown3.0 KB
reference/teach.mdmarkdown28.0 KB
reference/ui-ux.mdmarkdown4.0 KB
reference/vercel-host.mdmarkdown3.6 KB
reference/wayfinder.mdmarkdown7.2 KB
templates/GOAL.mdmarkdown1.3 KB
templates/PLAN.mdmarkdown1.4 KB
templates/QA.mdmarkdown1.2 KB
templates/R-LOOP.mdmarkdown569 B
templates/Z-DONE.mdmarkdown301 B
templates/arch-report.htmlother8.1 KB
templates/commit-gate.shexecutablescript11.6 KB
templates/contrast-gate.mjsexecutablescript4.3 KB
templates/db-access/.env.exampleother451 B
templates/db-access/check-connection.shexecutablescript134 B
templates/db-access/db-access.cmdscript39 B
templates/db-access/db-access.mjsexecutablescript5.2 KB
templates/db-access/read-only-query.shexecutablescript138 B
templates/db-access/schema-summary.shexecutablescript132 B
templates/domain-agent/code-map.mdmarkdown744 B
templates/domain-agent/config.jsonconfig291 B
templates/domain-agent/decisions/README.mdmarkdown270 B
templates/domain-agent/flows/README.mdmarkdown800 B
templates/domain-agent/freshness.mdmarkdown1.2 KB
templates/domain-agent/glossary.mdmarkdown781 B
templates/domain-agent/index.mdmarkdown1.3 KB
templates/domain-agent/invariants.mdmarkdown504 B
templates/domain-agent/qa/README.mdmarkdown879 B
templates/domain-agent/qa/nav-map.mdmarkdown1.2 KB
templates/domain-agent/test-map.mdmarkdown432 B
templates/domain-agent/tickets/README.mdmarkdown204 B
templates/domain-onboarding.htmlother9.2 KB
templates/harness-eval-case.yamlconfig4.4 KB
templates/harness-eval-cases/authored/authored-underspec-001-deepmerge.yamlconfig2.2 KB
templates/harness-eval-cases/authored/authored-underspec-002-csvline.yamlconfig2.0 KB
templates/harness-eval-cases/authored/authored-underspec-003-authz-cache.yamlconfig1.6 KB
templates/harness-eval-cases/fixtures/README.mdmarkdown2.8 KB
templates/harness-eval-cases/fixtures/revfactory-case-002-async-race/package.jsonmanifest124 B
templates/harness-eval-cases/fixtures/revfactory-case-002-async-race/src/cache.mjsscript494 B
templates/harness-eval-cases/fixtures/revfactory-case-002-async-race/test/cache.hidden.test.mjsscript2.2 KB
templates/harness-eval-cases/fixtures/revfactory-case-002-async-race/test/cache.visible.test.mjsscript950 B
templates/harness-eval-cases/fixtures/revfactory-case-003-refactoring/package.jsonmanifest125 B
templates/harness-eval-cases/fixtures/revfactory-case-003-refactoring/src/order.mjsscript1.3 KB
templates/harness-eval-cases/fixtures/revfactory-case-003-refactoring/test/order.hidden.test.mjsscript2.2 KB
templates/harness-eval-cases/fixtures/revfactory-case-003-refactoring/test/order.visible.test.mjsscript1.2 KB
templates/harness-eval-cases/fixtures/underspec-001-deepmerge/package.jsonmanifest124 B
templates/harness-eval-cases/fixtures/underspec-001-deepmerge/src/merge.mjsscript84 B
templates/harness-eval-cases/fixtures/underspec-001-deepmerge/test/merge.hidden.test.mjsscript1013 B
templates/harness-eval-cases/fixtures/underspec-001-deepmerge/test/merge.visible.test.mjsscript276 B
templates/harness-eval-cases/fixtures/underspec-002-csvline/package.jsonmanifest122 B
templates/harness-eval-cases/fixtures/underspec-002-csvline/src/csv.mjsscript77 B
templates/harness-eval-cases/fixtures/underspec-002-csvline/test/csv.hidden.test.mjsscript804 B
templates/harness-eval-cases/fixtures/underspec-002-csvline/test/csv.visible.test.mjsscript240 B
templates/harness-eval-cases/fixtures/underspec-003-authz-cache/package.jsonmanifest126 B
templates/harness-eval-cases/fixtures/underspec-003-authz-cache/src/authorizer.mjsscript601 B
templates/harness-eval-cases/fixtures/underspec-003-authz-cache/test/authorizer.hidden.test.mjsscript3.8 KB
templates/harness-eval-cases/fixtures/underspec-003-authz-cache/test/authorizer.visible.test.mjsscript1.2 KB
templates/harness-eval-cases/revfactory-case-001-rest-api.yamlconfig2.1 KB
templates/harness-eval-cases/revfactory-case-002-bug-fix.yamlconfig2.4 KB
templates/harness-eval-cases/revfactory-case-003-refactoring.yamlconfig2.4 KB
templates/harness-eval-cases/revfactory-case-004-documentation.yamlconfig2.1 KB
templates/harness-eval-cases/revfactory-case-005-complex.yamlconfig2.0 KB
templates/harness-eval-cases/revfactory-case-006-research.yamlconfig2.1 KB
templates/harness-eval-cases/revfactory-case-007-interpreter.yamlconfig2.1 KB
templates/harness-eval-cases/revfactory-case-008-microservice.yamlconfig2.1 KB
templates/harness-eval-cases/revfactory-case-009-sql-engine.yamlconfig2.0 KB
templates/harness-eval-cases/revfactory-case-010-crdt.yamlconfig2.0 KB
templates/harness-eval-cases/revfactory-case-011-raft-kv.yamlconfig2.1 KB
templates/harness-eval-cases/revfactory-case-012-spreadsheet.yamlconfig2.1 KB
templates/harness-eval-cases/revfactory-case-013-bytecode-vm.yamlconfig2.1 KB
templates/harness-eval-cases/revfactory-case-014-event-sourcing.yamlconfig2.1 KB
templates/harness-eval-cases/revfactory-case-015-lsp.yamlconfig2.3 KB
templates/harness-eval-cases/run-local-eval.mjsscript43.3 KB
templates/harness-eval-cases/run-underspec-n3.mjsscript41.1 KB
templates/harness-eval-external/deepswe/README.mdmarkdown9.9 KB
templates/harness-eval-external/deepswe/prepare-supergoal-arm.mjsscript4.4 KB
templates/harness-eval-external/deepswe/run-default-suite.mjsscript6.1 KB
templates/harness-eval-external/deepswe/run-full-cycle.mjsscript25.3 KB
templates/harness-eval-external/deepswe/task-set.yamlconfig12.2 KB
templates/harness-eval-external/featadd/README.mdmarkdown3.9 KB
templates/harness-eval-external/featadd/features.tsvother1.6 KB
templates/harness-eval-external/featadd/gen.shscript4.0 KB
templates/harness-eval-external/featadd/package.pyscript6.2 KB
templates/harness-eval-gate.mjsscript24.9 KB
templates/harness-eval-report.mdmarkdown5.8 KB
templates/harness-eval-result.jsonconfig11.9 KB
templates/harness-eval-runner.mjsscript19.9 KB
templates/harness-eval-stats.mjsscript1.8 KB
templates/learn-grounding-gate.mjsscript6.1 KB
templates/observability/heartbeat.schema.jsonconfig2.5 KB
templates/observability/sg-emit.shexecutablescript5.4 KB
templates/qa-gate.shexecutablescript6.9 KB
templates/qa-only-gate.shexecutablescript5.1 KB
templates/qa-report.mdmarkdown2.8 KB
templates/rules.mdmarkdown301 B
templates/run-state-gate.mjsscript2.2 KB
templates/run-state.jsonconfig474 B
templates/skill-frontmatter-gate.mjsscript3.7 KB
templates/skill-install-audit.mjsexecutablescript3.7 KB
templates/skill-mine/mine.mjsscript7.8 KB
templates/skill.md.templateother568 B
templates/teach-lesson-gate.mjsscript5.4 KB
templates/teach/README.mdmarkdown4.1 KB
templates/teach/assets/lesson-book.jsscript5.8 KB
templates/teach/assets/lesson-template.htmlother6.1 KB
templates/teach/assets/lesson.cssother11.8 KB
templates/teach/assets/quiz.jsscript3.2 KB
---
name: supergoal
description: Route objective-driven development, verification, planning, "teach/explain", codebase learning, and skill evaluation through the Supergoal workflow. Use when Supergoal is requested or an autonomous delivery workflow is needed.
---

# About

One objective -> smallest correct change -> verified against ground truth. If invoked, run this skill's
contract instead of downgrading to an inline shortcut. `SKILL.md` is the router; `reference/` carries procedure.
Unless explicitly invoked, pure brainstorming and user-driven step-by-step work use normal direct collaboration.

**Standing rules (read first, every mode).** Before classifying the mode, read
`.supergoal/rules/RULES.md` if present. Honor it across phases as top-priority preference, but rules never
weaken safety gates. Create/edit it only when the user explicitly asks (`reference/rules.md`). Check only
the repo root (`.supergoal/rules/RULES.md`), and skip the check entirely in an
ephemeral single-task workspace (auto-LIGHT tier; see role-loop `## Tier selection`).

## Core principles

- Ground truth beats proxy: re-run REAL tests, re-read request/docs, and do not optimize to self-grading.
- Exact proof beats review; implementation is delegated to a builder subagent.
- LIGHT tier substitutes in-context equivalents for vault artifacts, gate scripts, the Z file, and the builder dispatch; its approval rule and commit bar live in `reference/role-loop.md` `## Tier selection`.
- Smallest correct change; match surrounding code. Scope-minimalism governs code surface area, not UI
  quality: polished user-facing UI is baseline correctness.
- GREENFIELD / DEBUG / LEGACY code changes use Before/After Eval before Build: prove before, target after, and delta with trusted commands (`reference/delivery-gate.md`).
- Ask only when genuinely ambiguous; resolve code-answerable questions by reading the code.
- Report for humans: outcome first, Simplified Technical English prose, the project's own vocabulary (`reference/reporting.md`); machine-checked markers stay verbatim.
- Docs language: for persistent repo docs (`docs/**`, run vaults, `.domain-agent/**`, ADR/spec/changelog), match the target repo's dominant prose language; mixed/none -> the user's language. Keep identifiers, paths, commands, and machine-checked anchors in canonical English so checks keep matching.
- DEBUG done-bar: a green reported-repro is NOT done. Before commit, print three literal lines and
  satisfy them - `GATE.owner=` the invariant-owning frame (for a raised exception: the frame that RAISES
  it via the traceback, not where it surfaces; for recursion: inside the enumerated cycle),
  `GATE.alt_repro=` a structurally different second repro now passing, `GATE.conformance=`
  raw-literal returns reachable through the patched path (and its symmetric sibling methods) converted to
  the module's canonical forms (`S.One` over `1`). Full rules: role-loop "DEBUG hidden-contract gate".
- Hard stops: a destructive or irreversible step (drop data, force-push, external publish) needs explicit consent; if the real tests cannot pass, report it - never fake a pass.

## Run isolation (GREENFIELD / DEBUG / LEGACY that edits code)

After mode detection, resolve the source/base branch and target/integration branch (repo policy, else
ask). Verify both refs before mutating files, then create a run worktree from the source/base branch. Do
all code work there. Do not mutate the original checkout. Commit or merge only into the verified
target/integration branch after verification and user acceptance. Commit is hard-gated by the Commit gate
(`reference/delivery-gate.md`, backstop `templates/commit-gate.sh`): non-green means fix/ask, never commit
on assumption. Full contract: `reference/role-loop.md`.

## Mode (classify, state it in one line)

| Signal in the objective | Mode | Route |
|---|---|---|
| build / make / ship a new app/tool | GREENFIELD | default loop; broad/foggy builds first use a `wayfinder/` Frontier Map inside the run vault, then deliver one selected frontier ticket |
| fix / broken / failing / crash / why does | DEBUG | default loop; observe live symptom, then failing-test repro (`reference/debugging.md`, driver persona `agents/debugger.md`); web: `reference/qa.md`, `reference/agent-browser.md` |
| add / integrate / refactor existing code | LEGACY | default loop; map first (`agents/explore.md`, `reference/domain-context.md`); optional DB evidence (`reference/db-access.md`); existing API: capture its exact behavior first as a preserve-baseline; shared code/state changes: characterization baseline (`reference/qa.md`) |
| spec / requirements first / break down / tickets / roadmap / big vague effort / frontier / what should we do first | WAYFINDER | map the destination, optional ticket-depth requirements, ticket graph, blockers, and next frontier; no product code by default (`reference/wayfinder.md`) |
| prototype / spike / try variants / prove approach before build | PROTOTYPE | throwaway proof that answers one question, then delete/quarantine or route to delivery (`reference/prototype.md`) |
| explain / teach / how does X work (no code) | TEACH | stateful `teach/<topic>/` workspace (`reference/teach.md`); use an Archify diagram by default for structure/flow; lessons must pass `node templates/teach-lesson-gate.mjs` |
| learn / onboard / map this codebase (persist a wiki) | LEARN-DOMAIN | Survey -> Map -> Ground -> Onboard a `.domain-agent/` wiki (`reference/learn-domain.md`; gate `templates/learn-grounding-gate.mjs`) |
| QA / verify / 검증만 / compare data (no code) | QA-ONLY | Impact Matrix QA (`reference/qa-only.md`; gate `templates/qa-only-gate.sh`) |
| review / audit this code/diff/PR (no fixes) | REVIEW-ONLY | `reference/review-only.md` |
| improve the architecture / find refactoring opportunities / 구조 개선 / draw · diagram · 그려 (arch·flow·sequence·state) | ARCHITECTURE | draw-only ask: render self-contained HTML via `reference/archify.md`, deliver the `.html`, stop. Else friction survey -> candidates -> grill the pick -> route to LEGACY/WAYFINDER (`reference/arch.md`) |
| test harness/skill effectiveness / with vs without / does the skill help / measure skill lift | HARNESS-EVAL | `reference/harness-eval.md` |
| turn repeated work into a reusable skill | SKILL-MINE | `reference/skill-mine.md` |

**Tier (code modes; state it with the mode line).** GREENFIELD / DEBUG / LEGACY also declare
LIGHT / STANDARD / DEEP per `reference/role-loop.md` `## Tier selection`. User words
"quick"/"light" or "thorough"/"deep" override detection; upgrade is one-way, never downgrade.

The no-code/utility/planning modes - **QA-ONLY**, REVIEW-ONLY, ARCHITECTURE, WAYFINDER, PROTOTYPE, TEACH,
LEARN-DOMAIN, HARNESS-EVAL, SKILL-MINE - write no product code by default and confirm before installing
anything. PROTOTYPE may write throwaway sandbox code; it cannot ship until routed back through delivery.

**UI/UX overlay (any mode shipping user-facing UI).** Load `reference/ui-ux.md` at Frame; apply the
Expressive/polished baseline by default (`reference/taste-skill-v2.md` is the authority for ALL
user-facing UI), through Build and Verify. GREENFIELD frontend: always; LEGACY: only new UI (else reuse
the existing design system); non-visual work (lib, API, backend, CLI): skip.

**Board overlay (optional).** If the live dashboard is enabled, the conductor calls `sg-emit` at each
phase transition; it observes only, never gates (`reference/observability.md`).

## Default loop (GREENFIELD / DEBUG / LEGACY) - five gates, fresh context per gate

Load and follow `reference/role-loop.md`; it is the sole detailed authority for run setup, vault
lifecycle, role inputs/outputs, retries, verification, and finalization. Invoking `supergoal` for these
modes is explicit authorization to use its fresh-context subagents; ask again only for normal safety or
permission gates. Red-green evidence is required, plus DB evidence when persisted data is load-bearing.

Mandatory core: Frame -> Plan approval -> Build -> Exact Verify/QA -> Finalize. Use one builder + one
auditor verifier per iteration; browser/CLI proof adds one evidence-only qa-tester before the auditor.
Only a named, recorded escalation trigger permits the conditional plan attack. Frame writes `GOAL.md`
first and freezes a self-sufficient `PLAN.md`; Build starts only after approval and runs in a separate
fresh-context builder from that plan; `qa-tester` captures the promised browser/CLI evidence, then a
fresh adversarial verifier (`qa-auditor`) reruns REAL tests, audits the promised E2E/live/API/browser
proof, and owns the final verdict, GOAL ticks, and R-LOOP.
Finalize requires every criterion green, the completion marker, user acceptance, and the commit gate.
Exact verification outranks review.

Roles -> personas: builder/improver=`agents/executor.md`, evidence-only browser/CLI tester=
`agents/qa-tester.md`, final verifier for every default-loop path=`agents/qa-auditor.md`, escalation
reviewer=`agents/code-reviewer.md`, security=`agents/security-reviewer.md` (others in
`agents/<role>.md`).

## Reference map (load only what the current phase needs)

| Read this | When |
|---|---|
| `reference/role-loop.md` | default loop + run isolation contract |
| `agents/<role>.md` | dispatch a role persona |
| `reference/domain-rules.md` | Frame: distill <=10 priority rules |
| `reference/rules.md` | read project standing rules (`.supergoal/rules/RULES.md`) first, before any mode |
| `reference/domain-context.md` | repo-local Domain Brief |
| `reference/debugging.md` | DEBUG: hypothesis-ledger diagnose loop |
| `reference/interview.md` | interview: ambiguity (what) + blast-radius confirm (approach, tiered) |
| `reference/reporting.md` | any user-facing message: plan/spec presentation, interview questions, verdicts, final report |
| `reference/delivery-gate.md`, `templates/GOAL.md`, `templates/PLAN.md`, `templates/QA.md`, `templates/R-LOOP.md`, `templates/Z-DONE.md`, `templates/run-state.json`, `templates/commit-gate.sh` | run vault file set + Before/After Eval + resumable run state + commit gate for GREENFIELD / DEBUG / LEGACY code changes |
| `reference/wayfinder.md` | WAYFINDER: issue map -> vertical tickets -> optional EARS/user-story depth -> blockers -> next frontier; also GREENFIELD internal Frontier Map for broad/foggy new builds |
| `reference/research.md` | WAYFINDER research-needed tickets; docs/API/source facts that need high-trust cited evidence |
| `reference/prototype.md` | PROTOTYPE: throwaway logic/UI proof -> capture answer -> delete/quarantine or route to delivery; UI/interaction prototypes must also load the installed `superdesign` skill |
| `reference/vercel-host.md` | PROTOTYPE: after explicit approval, publish an isolated browser prototype to a public Vercel URL and verify anonymous access |
| `reference/plan-grounding.md` | ground the approach before committing |
| `reference/db-access.md`, `templates/db-access/` | read-only DB evidence (required when persisted data is load-bearing) |
| `reference/qa.md`, `qa-only.md`, `agent-browser.md`, `playwright-cli.md` | QA / no-code verify; agent-browser default, playwright-cli fallback |
| `reference/review-only.md` | REVIEW-ONLY: findings, no fixes |
| `reference/arch.md` | ARCHITECTURE: friction survey -> route out |
| `reference/archify.md`, `templates/archify/` | diagrams as self-contained HTML (typed JSON IR -> validated render): ARCHITECTURE reports, TEACH lessons, and LEARN-DOMAIN onboarding |
| `reference/teach.md`, `learn-domain.md` | teach a human / onboard the agent |
| `reference/ui-ux.md`, `taste-skill-v2.md`, `functional-ui.md`, `taste-aesthetics.md`, `engagement.md` | user-facing UI tier |
| `reference/harness-eval.md`, `templates/harness-eval-runner.mjs`, `templates/harness-eval-external/deepswe/run-default-suite.mjs` | HARNESS-EVAL; the runner is the DEFAULT portable eval driver (adapters + preflight + fallback + retry, serial by default). Difficult SWE/harness-effectiveness claims default to the forced five-task DeepSWE suite (measured-difficult tasks) - use it, don't hand-roll a single-CLI run.mjs |
| `reference/skill-mine.md` | SKILL-MINE |
| `reference/market-research.md` | GREENFIELD: validate demand (optional) |
| `reference/observability.md`, `tui/` | Board: opt-in live dashboard |

**Done =** mode stated; smallest diff; Before/After Eval complete for code-mode changes; REAL
tests + request/docs green (not proxy); runtime MUST proven by real behavior; code-mode runs use
red-green test + DB evidence if data load-bearing; neighbor snapshots re-run with unnamed drift resolved; every
`GOAL.md` Success Criterion checked, with no orphan scope; `Z-<date>.md` written with run branch +
completion timestamp; DEBUG prod issue has reproduction fidelity and, if
non-exact, residual risk + post-deploy confirmation plan; user-facing UI at the Expressive baseline;
destructive steps consented; commit/merge only after the commit gate passes (`reference/delivery-gate.md`);
verified commands reported.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall