Design Workflow

Applies in every project, whenever a task is design-then-implement above the complexity gate below. How a design becomes reviewed code: decisions live in a CLI-enforced ledger, implementation ships in review-sized slices, and each slice passes a machine gate before a human reads the diff.

The human reviews after the fact, not in the loop. A confirmed design is implemented end to end without stopping for the user (/impl-pipeline, batch mode); the user approves the plan once, and then reviews the finished slices one at a time (/review-desk). Slice boundaries survive the wait because each slice lands as its own checkpoint commit. Stopping between slices (--stepwise) is the exception, for designs that are not actually settled.

The workflow supplies the procedure. The project supplies the facts — its layers, conventions, base branch, and risk areas are read from the project at runtime, never assumed from another repo.

Decision Ledger

Design decisions live in the ledger task document, in four sections: ## 현재 설계 (confirmed decisions only) · ## 작업 큐 (implementation slices) · ## 결정 로그 (append-only) · ## 진행 로그.

Leftover superseded prose in the current section means someone bypassed the CLI. Run /design-reconcile, which moves — never deletes — such content back to the log.

Reading Protocol

• Never read the design document in full. Use ledger current --file <task> [--topic <slug>].
• When delegating, inject the current output into the prompt — never hand a subagent a document path.

This is what keeps token cost independent of document length. A subagent that reads the whole document re-reads every superseded decision.

/design-reconcile is the one exception: inconsistency detection requires comparing the current section against the decision log, so it reads the raw document for analysis only.

Project Facts Are Resolved, Never Assumed

These four are project-specific. Read them from the project at the start of a run; never carry them over from another repo:

A project with no convention docs is not an error. Infer, confirm, and mark the convention check SKIPPED rather than failing the gate on it.

Slices

• A slice is a review boundary, and therefore a commit candidate. When a slice lands, propose a checkpoint commit (see below). Outside an authorized batch run, the agent never commits on its own — it proposes; the user decides.
• Decompose by decision (D-n) first; split a large decision along the project's own layer boundary (resolved above), in dependency order. Order independent slices first.
• Every slice carries target file globs, acceptance criteria, and — in a batch run — the slices it depends on. The gate uses the globs to detect out-of-design changes; the dependency edges are what let a failed slice be parked without poisoning the ones after it.
• Decomposition is confirmed with the user before implementation starts.
• Slices are implemented sequentially, one at a time. Never two at once: they share a working tree, and a conflict costs more than the wall-clock it saves. Removing the user's wait is what shortens a run — not overlapping the work.

Who reviews a slice, and when

Taste, naming debates, and "is this the best shape" are carried, not fixed, during a run. An unattended agent rewriting code on taste is how a batch run turns into an unreviewable diff.

Checkpoint Commits

Applies to all work, not just the pipeline. An uncommitted diff that grows past review size is the single biggest cause of unreviewable change. Do not let it accumulate silently and dump it on the user at the end. Surface it while it is still small, so that later the user can review one purpose at a time and skip what they already accepted.

Propose a checkpoint when ANY of these fires

How to propose

Stop and tell the user — do not keep implementing through the trigger.

1. State why it fired (which trigger, with the actual numbers).
2. Show the purpose-based phase split you would stage, not just a file count.
3. Ask for approval. Never git add / git commit before the user answers.

The proposal is a suggestion, not a gate. If the user says keep going, keep going — but do not re-ask on every subsequent file. Re-ask at the next distinct trigger.

The one exception — an authorized batch run

/impl-pipeline batch mode commits a checkpoint per slice, without asking each time. That is legal only under all of these:

• The user approved it explicitly, in that run's Run Contract, before any code was written.
• run.json.commit_authorized: true records the approval, and the run is scoped to one branch.
• The branch is not the base branch, and the working tree was clean when the run started.
• Only the slice's own changed files are staged (/commit-msg --checkpoint), never git add -A, never .claude/review/**. Never git push.

The approval expires with the run. /review-desk — which happens afterwards — has no such authority: every commit there is approved individually, as always.

The reason for the exception is mechanical, not convenience: without a commit per slice, an unattended run collapses into one working-tree blob and the user's later slice-by-slice review becomes impossible. The commit is the review boundary.

Still true

• Outside that authorization, the agent never commits or stages autonomously. Approval is required every time, in every project.
• Commit message and phase split follow the project's own git rules, not this file's.
• No AI attribution trailers in commit messages (Co-Authored-By, Claude-Session) — user policy.

Complexity Gate

Simple work bypasses the pipeline. If a change touches ≤2 files, or maps to a single decision with no cross-layer impact, implement it in one pass and let the user review the diff normally.

Pipeline overhead must not exceed its benefit.

Risk Tiers (when the project has no review-policy.md)

Tier A (정독 필수) = ① money / permissions / personal data · ② schema migration · ③ transaction, lock, or concurrency boundary changed · ④ high fan-in symbol (many callers, most untouched). Everything else is tier B; machine-certified boilerplate is tier C and gets folded away.

Review Artifacts

• Gate results and walkthroughs go to .claude/review/{branch-slug}/. If that path is not gitignored in this repo, warn the user — never edit their .gitignore.
• The raw diff is the truth; artifacts are an aid. If an artifact fails to generate, review proceeds on the raw diff — report the failure, don't block. Degraded ≠ failed.
• Artifacts carry a SHA stamp. If the stamp differs from HEAD, the artifact is stale — regenerate it.

No Explanatory Comments

Do not put change rationale or design justification in code comments. The review guide carries the "why".

Implementation agents report issues, design gaps, and unstated assumptions in their report text, never as a code comment.

(Inline comments explaining non-obvious business logic remain required where the project's own convention says so. The ban is on comments that exist to explain a change to a reviewer.)

Skills

The flow, end to end

설계 확정 (decide)
  → /impl-pipeline        ← 사용자 승인 1회 (Run Contract)
      S-1 … S-n 무중단: 구현 → 게이트 → 에이전트 리뷰 → 수정 → 워크스루 → 체크포인트 커밋
  → 러닝 리포트 + 알림      ← 사용자는 이 시점에 자유롭게 복귀
  → /review-desk          ← 슬라이스별 사후 검수, 수정 요청은 큐에 축적
  → 큐 일괄 반영 + 재게이트 → 커밋 정리 (매번 승인) → 구현완료