/supergoal

Get started시작하기

You need Claude Code and Node 18+. Two commands to install, one to run. No service, no config.

필요한 건 Claude Code와 Node 18+뿐입니다. 설치는 명령어 두 개, 실행은 하나. 별도 서비스도 설정도 없습니다.

› git clone https://github.com/cskwork/supergoal-skill.git
› ln -s "$(pwd)/supergoal-skill" ~/.claude/skills/supergoal
# then, in Claude Code, hand it one objective:
› /supergoal build a CLI todo app and ship it

› git clone https://github.com/cskwork/supergoal-skill.git
› ln -s "$(pwd)/supergoal-skill" ~/.claude/skills/supergoal
# 그다음 Claude Code에서 목표 하나를 건네세요:
› /supergoal CLI 할 일 앱을 만들고 출시해줘

zero dependencies의존성 없음no external orchestrator외부 오케스트레이터 없음 no TUI / serviceTUI·서비스 없음runs in-session세션 안에서 실행

Four modes, one command네 가지 모드, 하나의 명령

The skill reads your objective and picks the right pipeline, including how much to parallelize. Broad work (research, scaffolding several files) fans out to many agents at once; focused work (one bug, one feature) stays with a single driver. The three code-writing modes pause at Human Feedback before touching code. A fourth mode, LEARN, writes no code at all.

스킬이 목표를 읽고 알맞은 파이프라인과 병렬화 수준을 고릅니다. 폭넓은 작업(리서치, 여러 파일 스캐폴딩)은 여러 에이전트로 한꺼번에 펼치고, 집중된 작업(버그 하나, 기능 하나)은 단일 드라이버가 맡습니다. 코드를 쓰는 세 모드는 코드를 건드리기 전에 Human Feedback에서 승인을 요청합니다. 네 번째 모드 LEARN은 아예 코드를 쓰지 않습니다.

How it works동작 방식

The skill is the director: it never writes production code. It picks the mode, hands each phase to a fresh expert subagent, and reads back only short summaries (never full transcripts). The subagents never talk to each other; they pass work through one shared folder, the vault. Phases run forward only: the next phase opens only after the current one passes its check, and going backward happens only as an explicit, logged rewind.

스킬은 디렉터입니다. 프로덕션 코드를 직접 쓰지 않습니다. 모드를 정하고, 각 단계를 새 전문가 서브에이전트에게 넘기며, 전체 기록이 아닌 짧은 요약만 돌려받습니다. 서브에이전트끼리는 서로 대화하지 않고, 하나의 공유 폴더인 볼트(vault)를 통해 작업을 주고받습니다. 단계는 앞으로만 진행됩니다. 현재 단계가 검사를 통과해야 다음 단계가 열리고, 되돌아가는 일은 명시적으로 기록된 되감기로만 일어납니다.

GREENFIELD: ship a new appGREENFIELD: 새 앱 출시

DEBUG: root-cause a hard bugDEBUG: 까다로운 버그 근본 원인 추적

LEGACY: add to existing codeLEGACY: 기존 코드에 기능 추가

LEARN: understand something (no code)LEARN: 무언가 이해하기 (코드 없음)

LEARN skips the build/verify/deliver gates entirely. Its delivery gate is human: you restate every key term and the whole idea in your own words. Until you can, it loops.

LEARN은 build/verify/deliver 게이트를 모두 건너뜁니다. 이 모드의 딜리버리 게이트는 사람입니다. 핵심 용어와 전체 개념을 당신의 말로 다시 설명해야 합니다. 그럴 수 있을 때까지 루프를 돕니다.

Before it builds: a grounded plan, shaped by your domain's rules구현에 들어가기 전: 도메인 규칙으로 다듬은, 근거 있는 계획

Two advisory layers sharpen the plan before the Human Feedback gate (neither replaces a hard gate). Plan grounding: in the Plan phase the planner self-runs a design-tree grill against the project's own docs and architecture (CONTEXT.md, ADRs, the explored map) and answers each challenge itself. Feature work sharpens terms and contracts; "improve / refactor" work hunts for deepening opportunities. Domain priority rules: right after mode detection the objective is routed through the ten-rules skill and distilled into ≤10 abstract priority rules (e.g. web-design + ecommerce), recorded once and carried into Plan, Build, and Review.

두 가지 advisory 레이어가 Human Feedback 게이트 전에 계획을 다듬습니다(둘 다 하드 게이트를 대체하지 않습니다). Plan grounding: Plan 단계에서 플래너가 프로젝트 자체 문서·아키텍처(CONTEXT.md, ADR, 탐색 맵)에 대해 디자인 트리 그릴을 스스로 돌리고 각 질문에 직접 답합니다. 기능 작업은 용어·계약을 날카롭게 하고, "개선/리팩터" 작업은 심화 기회를 찾습니다. Domain priority rules: 모드 감지 직후 목표를 ten-rules 스킬로 라우팅해 ≤10개의 추상적 우선순위 규칙(예: web-design + ecommerce)으로 정제하고, 한 번 기록해 Plan· Build·Review까지 가져갑니다.

Why it catches real bugs: the builder never grades itself진짜 버그를 잡는 이유: 구현자는 자기 일을 채점하지 않습니다

   Builder  (writes the code)             Verifier  (a fresh, separate agent)
   ──────────────────────────             ──────────────────────────────────
   writes code + a CLAIM:                 reads ONLY the claim + the code,
     "run-to-prove: npm test"   ───────▶  re-runs every "run-to-prove" from a
     (its own report, NOT trusted)        clean slate, tries to disprove it,
                                          and checks the test suite is real
                                                       │
                          verdict: RED  ◀──────────────┴──────────────▶  verdict: GREEN
                               │                                              │
                        back to Build                                  review by security
                        (max 5 tries; same                             + code-review, both
                         error 3× → STOP &                             must approve, then
                         escalate to you)                              the delivery gate
  

In live testing this caught 2 SSRF holes and a concurrency race that all passed the builder's own green tests. Separating who writes from who approves is the whole point.

실제 테스트에서 이 구조가 구현자의 green 테스트를 모두 통과한 SSRF 취약점 2건과 동시성 레이스 1건을 잡아냈습니다. 누가 작성하느냐와 누가 승인하느냐를 분리하는 것이 핵심입니다. (다이어그램은 정렬 유지를 위해 영어로 표기.)

The approval and delivery gates: scripts the agent can't fake승인 및 딜리버리 게이트: 에이전트가 위조할 수 없는 스크립트

human-feedback-gate.mjs runs before Build or Fix. It requires plan.md to include ### Plain-language brief at the top, ### Technical brief below it, term definitions, and state.json.approval for the target phase.

human-feedback-gate.mjs는 Build 또는 Fix 전에 실행됩니다. plan.md 안에 위쪽 평문 브리프, 아래쪽 기술 브리프, 용어 정의가 있어야 하고 state.json.approval이 대상 단계를 승인해야 합니다.

delivery-gate.sh is a plain shell script the agent is forbidden to edit. It exits 0 only when, in order: (1) the required files exist (brief.md, plan.md, verification.md); (2) verification.md says verdict: GREEN with no leftover verdict: RED; (3) for a new app, the Decision: is GO; (4) the project's own tests pass right here in the workspace. Nothing is called "done" until that exit-0 output is shown as proof.

delivery-gate.sh는 에이전트가 편집할 수 없는 평범한 셸 스크립트입니다. 다음을 순서대로 만족할 때만 exit 0이 됩니다: (1) 필수 파일 존재(brief.md, plan.md, verification.md); (2) verification.md가 verdict: GREEN이고 남은 verdict: RED가 없음; (3) 새 앱이라면 Decision:가 GO; (4) 프로젝트 자체 테스트가 바로 이 워크스페이스에서 통과. 이 exit 0 출력이 증거로 제시되기 전까지는 무엇도 "완료"라 부르지 않습니다.

The vault: the one shared file store볼트: 단 하나의 공유 파일 저장소

Each phase is a fresh context, so a single folder docs/changelog/<date-slug>/ (committed as the run's changelog) is the only hand-off, just six files. Two rules keep it honest: claims are untrusted (only the Verifier marks a verdict, by re-running the proof) and frozen files stay frozen (the plan can't drift mid-build; it's hashed and re-checked). On a re-run, state.json resumes where it left off.

각 단계는 새 컨텍스트라서, 단 하나의 폴더 docs/changelog/<date-slug>/(실행의 체인지로그로 커밋됨)가 유일한 인계 수단입니다. 파일 여섯 개뿐. 두 규칙이 정직성을 지킵니다: 주장은 신뢰하지 않음(검증자만이 증명을 재실행해 판정을 매김), 고정된 파일은 고정된 채로(계획은 빌드 도중 변하지 않음. 해시로 재확인). 재실행 시 state.json이 멈춘 지점부터 이어갑니다.

Expert roster전문가 구성

Each role maps to an existing Claude Code agent type, runs on a model tier matched to the difficulty of the task, and reads only the part of the vault it needs. A reviewer never inherits the coder's assumptions.

각 역할은 기존 Claude Code 에이전트 타입에 대응되고, 작업 난이도에 맞춘 모델 티어에서 돌며, 볼트에서 필요한 부분만 읽습니다. 리뷰어가 코더의 가정을 물려받는 일이 없습니다.

*Opus when the slice is new or algorithm-heavy. †Designer joins only on jobs that ship visual UI. It builds against the vendored taste-skill v2 design authority, and QA adds a pre-flight design check. It never self-approves: the adversarial Verify and committee still gate Deliver.

*새롭거나 알고리즘이 무거운 슬라이스에는 Opus. †디자이너는 시각적 UI를 출시하는 작업에만 합류합니다. 내장된 taste-skill v2 디자인 권위를 기준으로 구현하고, QA에 사전 점검 게이트가 추가됩니다. 스스로 승인하지 않습니다: 적대적 Verify와 위원회가 여전히 Deliver를 통제합니다.

The non-negotiable gates타협 불가 게이트

The spine: never weakened, never skipped. Three are literal scripts the agent can't edit to pass: validate-gate.sh, human-feedback-gate.mjs, and delivery-gate.sh.

이 스킬의 척추: 절대 약화되지도, 건너뛰어지지도 않습니다. 그중 셋은 에이전트가 통과시키려고 편집할 수 없는 리터럴 스크립트입니다: validate-gate.sh, human-feedback-gate.mjs, delivery-gate.sh.

Proof it works동작 증명

All three code-writing modes were run end-to-end on one real, zero-dependency service (68 tests). The adversarial check caught a real defect in 2 of 3 runs: bugs that passed the builder's own green tests. The full audit trail ships in examples/url-shortener/docs/changelog/.

코드를 쓰는 세 모드 모두 실제 무의존성 서비스 하나(테스트 68개)에서 엔드투엔드로 돌렸습니다. 적대적 검증이 3번 중 2번에서 진짜 결함을 잡아냈습니다. 구현자 자신의 green 테스트를 통과한 버그들입니다. 전체 감사 기록은 examples/url-shortener/docs/changelog/에 함께 담겨 있습니다.