Implementation Pipeline (batch)

Turns a confirmed design into a sequence of review-sized slices, and implements all of them, end to end, without waiting for the user. Each slice is still gated and still reviewed — by machines and by an independent reviewer agent, not by the human. The human reviews afterwards, slice by slice, on code that is already complete (/review-desk).

The point is to fix three failure modes:

1. Agents re-read an ever-growing design doc and burn tokens on stale decisions.
2. A single bulk implementation produces a diff too large for a human to review.
3. The human is a synchronous dependency. Slice N+1 waiting on the user's approval of slice N means total implementation time is dominated by the user's availability, not by the work.

The fix for (3) is not to drop review — it is to move the human's review off the critical path while keeping the slice boundaries intact, so the review that happens later is still slice-sized.

MUST invoke Skill(design-workflow) before running this skill. If the current project also ships .claude/rules/design-workflow.md, read that too — a project rule narrows the global one, never contradicts it.

Arguments

/impl-pipeline [task-file] [--slices N] [--resume S-n] [--stepwise] [--explain]

The two modes

Batch mode is the default because a confirmed design is what this pipeline consumes. If the ledger is full of decisions you are not sure about, the right fix is /design-reconcile, not --stepwise.

Core Principles

Read these before Phase A. They override convenience at every step.

• The skill supplies the procedure; the project supplies the facts. "Split a big decision along the layer boundary" is procedure and holds everywhere. What the layers are is a project fact — it is read from the project in Step 0, never assumed from another repo.
• Slice boundary = review boundary = checkpoint commit. In batch mode the checkpoint commit is what carries the slice boundary to the user's later review. Without it, every slice merges into one working-tree blob and per-slice review becomes impossible. This is why commit authorization is part of the Run Contract and not an afterthought.
• The user approves once, up front, and is not asked again during the run. Everything that would have been a question mid-run becomes an item in the review desk. The run does not stall on a question.
• The reviewer agent is not the implementer. A fresh agent, with the decision text and the conventions but not the implementer's rationalizations, reviews each slice. Same-agent self-review finds nothing.
• Only blocking defects are fixed during the run. Taste, naming debates, and "why this way" go to the review desk untouched. The run is not allowed to relitigate the design with itself.
• Never read the design document in full. Use ledger current only. When delegating, inject the current output into the prompt — never pass a document path and let the subagent read it.
• Complexity gate — simple work bypasses the pipeline. ≤2 files or a single decision with no cross-layer impact → do not run this. Implement in one pass, user reviews the diff. State the bypass out loud.
• Sequential slices. Slice N+1 starts after slice N is finished (committed or parked) — not after it is approved. Slices are never implemented concurrently: they share a working tree and a base, and a conflict costs more than the wall-clock it saves.
• Artifacts are an aid, never the truth. The raw diff is the truth. If the gate, the walkthrough, or the explainer fails to produce, the run continues and the failure is recorded.
• No explanatory comments in code. Issues, caveats, and design gaps go in the agent's report, never in a code comment.

Phase A — Setup and the one user stop

Step 0 — Load project context

Nothing project-specific is hardcoded in this skill. Resolve it here, once, and write it to context.json so the downstream skills reuse it instead of re-deriving it.

0a. Repo basics

ROOT=$(git rev-parse --show-toplevel)
BRANCH=$(git branch --show-current)
SLUG=$(echo "$BRANCH" | tr '/' '-')
mkdir -p "$ROOT/.claude/review/$SLUG"

Batch mode precondition — a clean starting point. Checkpoint commits are only meaningful if the working tree starts clean. Run git status --porcelain:

• Clean → proceed.
• Dirty → show the user what is uncommitted and ask: commit it first, stash it, or run --stepwise. Never commit or stash someone else's work-in-progress yourself.
• Current branch is the base branch → stop. Batch mode never commits onto a base branch. Offer to cut a work branch first, named by whatever this repo's own branch convention says.

0b. Base branch (never assume dev / main)

Resolution order — stop at the first that answers:

1. .claude/review/{slug}/context.json → .base_branch (a previous run already settled it).
2. The project's own git rules, if it documents one (.claude/rules/git*.md, docs/**/git*.md, CONTRIBUTING.md).
3. Nearest merge-base wins. Among the remote branches that exist, pick the one this branch is closest to — a feature branch cut from dev sits far fewer commits from dev than from main:

   for C in origin/dev origin/develop origin/main origin/master; do
     git rev-parse --verify -q "$C" >/dev/null && \
       echo "$(git rev-list --count "$C"..HEAD) $C"
   done | sort -n | head -1

4. Ambiguous or tied → ask the user. Do not guess. (This is part of the Run Contract stop, not an extra one — resolve it before presenting the contract.)

Persist the answer as base_branch in context.json.

0c. Convention documents

Probe, in this order, and read what exists:

From these, extract three things and state them out loud before slicing:

1. The layer model — the ordered chain a change travels through in this repo.
2. The new-feature checklist — every artifact a new feature must produce in this repo.
3. The lint / diagnostics command — how this repo checks a file (used by /review-gate).

e.g. a layered Python backend might resolve to Model + migration → Repository → Service → DTO → Route → DI container, a React frontend to Route/page → hook → API client → type, a data worker to handler → transform → sink. None of these is the default. Read the project.

0d. No convention documents?

Do not stall, and do not import another repo's conventions.

1. Infer the structure from the codebase — directory names, an existing feature's file set, imports.
2. State the inferred layer model and the inferred slicing axis in the Run Contract (Step 2) and get it confirmed there — not as a separate stop.
3. Record the confirmed answer in context.json (layers, lint_cmd) so later slices are consistent.
4. Mark conventions: null in context.json — this tells /review-gate to report the convention check as SKIPPED (no convention docs) rather than failing.

0e. Code graph project (optional, for /change-walkthrough)

Resolve the codebase-memory project name by path, never by guessing the name — indexed names are not always path-derived — a repo may be indexed under a short service name while another sits under a path-shaped name:

mcp__codebase-memory-mcp__list_projects()

→ pick the project whose root_path (or git.canonical_root) equals git rev-parse --show-toplevel. In a git worktree, also compare against the main worktree root (git worktree list | head -1).

• Match → record its name as project in context.json.
• No match → record "project": null. The pipeline runs in degraded mode: the walkthrough drops the call-chain map. Do not run index_repository — it is expensive. Put the offer in the Run Contract ("인덱싱하면 호출 체인 Map을 받을 수 있다. 지금 인덱싱할까?") and index only if the user says yes there.

0f. Write context.json

.claude/review/{branch-slug}/context.json — the handoff record for /review-gate and /change-walkthrough:

{"task_file": "0713-task1-주문-생성-설계",
 "project": "<Step 0e에서 list_projects → root_path 매칭으로 얻은 이름. 없으면 null>",
 "base_branch": "origin/<Step 0b에서 해석한 base>",
 "conventions": ["<Step 0c에서 실제로 찾은 컨벤션 문서 경로들. 없으면 null>"],
 "layers": ["<이 프로젝트의 레이어 체인, 의존 순서대로>"],
 "lint_cmd": "<이 프로젝트가 실제로 쓰는 린트 명령>"}

project, conventions, layers, lint_cmd may be null — a null is a fact, not a failure, and the downstream skills degrade on it instead of aborting.

Also check that the artifact directory will not be committed:

git check-ignore -q .claude/review && echo IGNORED || echo TRACKED

TRACKED → warn the user once in the Run Contract: ".claude/review/가 gitignore되지 않는다. 배치 러닝은 슬라이스마다 커밋하므로 산출물이 섞인다. .gitignore에 추가하라." Do not edit their .gitignore yourself — but in batch mode, never stage anything under .claude/review/ regardless.

0g. 진행 대시보드에 리뷰 폴더 등록 (선택 — 원장 백엔드가 대시보드를 렌더하는 경우)

리뷰 산출물 폴더의 절대경로를 task 문서에 한 번 기록한다. 그러면 원장 백엔드가 대시보드를 렌더하면 각 슬라이스의 워크스루/explain-diff를 거기서 이어준다 (실패해도 무시 — aid이지 gate 아님):

"$LEDGER" review-link --file <task> --dir "$ROOT/.claude/review/$SLUG"

Step 1 — Load the design

Do not open the task document. Read only the ledger, via CLI:

LEDGER="${CLAUDE_PLUGIN_ROOT}/scripts/ledger/ledger"

"$LEDGER" current --file <task> --ids-only     # which decisions exist
"$LEDGER" current --file <task>                # body of the active decisions

• If task-file was not given, locate recent task docs and ask the user which one:

  "$LEDGER" ls

• If current returns nothing, the design is not confirmed yet. Stop and tell the user to confirm decisions first (ledger decide). Do not invent decisions from the document body.
• If the current subcommand is unavailable, report it and stop — do not fall back to reading the whole document, that defeats the purpose of the skill.

Run /design-reconcile <task> first if the ledger looks inconsistent (SUPERSEDED decisions still described in the current section, TBD language, etc.). In batch mode this matters more than usual: the user will not be there to catch a slice built on a stale decision. A ledger that smells inconsistent is a reason to reconcile now, or to run --stepwise.

If the design is dense and the user wants to understand it before committing to a batch run, offer /explain-design-html <task> — its Playground shows where a decision flips, which is the strongest signal available that a decision is not yet safe to build a whole unattended run on.

Step 2 — Decompose, then the Run Contract (the only user stop)

The lead does the decomposition — not a subagent. The lead holds the design context.

Decomposition axis (in order)

1. Per decision (D-n) — the default. One decision → one slice.
2. Per layer, when a single decision is too big — split along the layer model resolved in Step 0, in dependency order (the layer nothing depends on goes first).
3. Order independent slices first. Later slices may depend on earlier ones; never the reverse.

Dependency edges are mandatory in batch mode

Every slice records which earlier slices it depends on (Depends: S-1). This is not bookkeeping — it is what makes "park the failure and keep going" safe: when a slice is parked, the run skips exactly its dependents and nothing else. A slice with no edge recorded is treated as independent, so an unrecorded edge means the run will happily build on broken ground. Derive edges from imports/symbols the slice consumes, not from the order alone.

Completeness check

Cross-check the slices against the new-feature checklist resolved in Step 0 so nothing is dropped. Every checklist item that the design implies must land in exactly one slice.

If the project publishes no checklist, derive one from an existing comparable feature in the codebase (list its files, in layer order) and show that derived checklist with the decomposition.

Each slice must carry

Record it in the ledger

Write the decomposition into the task document's ## 작업 큐 section with Edit. The CLI does not manage this section — this skill owns it.

### S-1 · {title}
- status: 대기
- Decisions: D-1, D-3
- Depends: —
- Tier: B
- Files: `packages/db/db/models/foo.py`, `apps/web-api/web_api/repositories/foo_*.py`
- Acceptance:
  - ...

- status: 필드는 슬라이스 진척의 단일 진실원이다 (enum: 대기·구현중·게이트·검수대기·승인·커밋·보류). 최초 분해 시 전부 대기로 쓰고, 이후 전이는 본문을 직접 고치지 말고 CLI로 바꾼다 — ledger slice-status --file <task> --slice N --status <상태>. 다른 필드(Depends, Tier, Files)는 CLI가 무시하므로 자유롭게 둔다.

The Run Contract

Present one AskUserQuestion that covers the whole run. After this, the user is free until the run reports back. Show:

1. 슬라이스 분해 — ID · 제목 · 결정 · 의존 · 티어 · 파일 글롭 (표 하나)
2. 모드 — 무중단 배치. 슬라이스마다 구현 → 게이트 → 에이전트 리뷰 → 수정 → 워크스루 → 체크포인트 커밋
3. 커밋 권한 — "슬라이스가 GREEN이 될 때마다 <브랜치>에 체크포인트 커밋한다. 푸시는 안 한다. 마지막에 목적별로 재편성할 수 있다." ← 이 승인이 없으면 배치 모드는 실행하지 않는다
4. 실패 정책 — 막힌 슬라이스는 보류 + 의존 슬라이스만 스킵, 나머지는 끝까지 진행
5. 검수 시점 — 러닝 종료 후 /review-desk로 슬라이스별 사후 리뷰, 수정 요청은 큐에 모아 일괄 처리
6. 미해결 사항 — Step 0에서 확정 못 한 것 전부 (base branch 후보, 추론한 레이어 모델, 코드그래프 인덱싱 여부, gitignore 경고)

Options should include: 이대로 진행 / 분해 수정 / --stepwise로 전환 / 커밋 없이 진행(스냅샷만).

커밋 권한을 거부하면 배치 모드로 가되 슬라이스 종료마다 git diff > .claude/review/{slug}/S-n.diff 스냅샷만 남긴다. 이 경우 나중 리뷰의 슬라이스 경계는 스냅샷 파일이 유일한 근거이고, 되돌리기는 수동이라는 점을 명시하라.

Do not implement anything before this contract is approved.

Write run.json

.claude/review/{branch-slug}/run.json — the run manifest. /review-desk reads this, possibly in a different session days later, so it must be self-sufficient.

{"mode": "batch",
 "task_file": "<ledger task doc>",
 "base_branch": "origin/<resolved base>",
 "branch": "<current branch>",
 "commit_authorized": true,
 "started_at": "2026-09-09T21:40:00+09:00",
 "finished_at": null,
 "start_sha": "<HEAD sha at contract approval>",
 "slices": [
   {"id": "S-1", "title": "…", "decisions": ["D-1"], "depends": [], "tier": "B",
    "globs": ["…"], "status": "대기",
    "gate": null, "agent_review": null, "commit_sha": null,
    "artifacts": {"walkthrough": null, "explain": null, "agent_review": null},
    "carried_items": [], "blocked_reason": null}
 ]}

Update the slice entry after every step of Phase B — a run that dies mid-way must be resumable (--resume S-n) and reviewable from what it already produced.

Phase B — The unattended loop (no user stops)

For each slice in order. Never run two slices concurrently.

B0. Skip check

If any slice in depends has status 보류, skip this slice: status 보류, blocked_reason: "S-k 보류로 인한 스킵", record it, move on. Do not attempt a partial build on a missing dependency.

B1. Implement

ledger slice-status --slice n --status 구현중, then delegate to an implementation agent (impl-executor). One slice per delegation. The prompt must inline the decision text:

"$LEDGER" current --file <task> --topic <slug>

Required elements of the delegation prompt:

1. TASK — implement slice S-n only.
2. DECISIONS — the full current --topic output pasted inline. Never a document path.
3. TARGET FILE GLOBS — the slice's globs.
4. ACCEPTANCE — the slice's acceptance criteria.
5. CONTEXT — what earlier slices already landed (their titles + the symbols they introduced), so the agent builds on them instead of re-creating them. In batch mode this replaces the user's "yes that's there now" that --stepwise used to supply.
6. MUST NOT —
   • Do not modify files outside the target globs. Exceptions, allowed without asking: mechanical collateral only — import cleanup, formatting, and the project's own boilerplate registrations (whatever Step 0's checklist marks as mandatory bookkeeping, e.g. a re-export or a DI registration).
   • Do not commit or stage anything. The lead commits, not the implementer.
   • Do not add explanatory comments describing why a change was made — that belongs in the report. (Inline comments explaining non-obvious business logic remain allowed per the project's own comment convention, in the project's own comment language.)
   • Do not refactor adjacent code that the slice does not require.
7. CONVENTIONS — the specific convention files from Step 0 that cover the layers this slice touches. Name the files; do not tell the agent to go hunting. If the project has none, say so explicitly and instead point at one existing comparable file to imitate.
8. REPORT — files changed, decisions covered, and any issue / design gap / unstated assumption discovered while implementing. These go in the report text, not in code.

B2. Machine gate

/review-gate S-{n} --task <task>

status 게이트. Always pass --task — the gate needs the ledger to check design conformance. Produces .claude/review/{branch-slug}/S-{n}-gate.json and a GREEN/RED verdict.

• RED → the gate auto-fixes and retries, up to 2 attempts.
• Still RED → park the slice (see B5). Do not stop the run.
• Gate fails to run at all → record gate: "SKIPPED (reason)" and continue to B3. The slice will carry an uncertified axis into the review desk, flagged.

B3. Independent agent review — this is what replaces the user

A fresh agent, never the one that implemented the slice. It reads the diff, the decisions, and the conventions, and it reviews as a senior engineer would.

Agent(subagent_type="slice-reviewer", description="Review slice S-n", prompt=...)
# slice-reviewer 가 없는 환경이면 general-purpose 로. 단, 구현을 맡았던 에이전트는 절대 재사용하지 않는다.

Its prompt carries: the slice diff (git diff <prev-slice-sha or start_sha>...HEAD -- <globs> — in snapshot mode, the saved S-n.diff), the inlined decision text, the convention file paths, the gate JSON, and the implementer's report.

Review dimensions, in this order of weight:

Each finding is classified — and the classification decides who acts:

Artifact: .claude/review/{branch-slug}/S-{n}-agentreview.md — findings with file:line, class, 근거(결정 ID 또는 컨벤션 문단), 제안. CARRY/QUESTION items are copied into run.json.carried_items.

Why CARRY is not fixed during the run: an unattended agent rewriting code on taste is how a batch run turns into an unreviewable diff. The run fixes what is wrong, not what is arguable.

B4. Fix loop

BLOCKING findings → delegate a fix (a fresh implementation agent, scoped to the cited locations only) → re-run /review-gate → re-run the reviewer on the fix only.

Cap: 2 rounds. If BLOCKING findings survive round 2, park the slice (B5). Do not shotgun.

B5. Park on failure (never stop the run)

"$LEDGER" slice-status --file <task> --slice n --status 보류

• run.json: status: "보류", blocked_reason: "<게이트 RED 잔존 항목 | BLOCKING 미해결 항목>".
• Record what was attempted, in full, in .claude/review/{slug}/S-{n}-blocked.md.
• Code state. Decide by the gate's diagnostics check (check 1), not by the RED verdict as a whole:
  • Diagnostics clean (the slice compiles/type-checks; it failed on convention or on a BLOCKING review finding) → commit it as a checkpoint anyway: /commit-msg --checkpoint S-n --allow-red. The later slices build on working code, and the user reviews the parked slice at the desk.
  • Diagnostics not clean (the tree is broken) → the next slice must not inherit it. Park the work where it is recoverable:

    git stash push -u -m "impl-pipeline S-{n} parked (broken)" -- <the slice's changed files>

    This is safe only because batch mode started from a clean tree (Step 0a) — everything being stashed is this run's own work. Record the stash message in S-{n}-blocked.md. If the tree did not start clean, or the stash fails, stop the run and report — a broken tree poisons every later slice, and that is the one failure worth interrupting for.
• Mark every dependent slice as skipped (B0).
• Then continue with the next independent slice.

B6. Review artifacts

/change-walkthrough S-{n}

→ .claude/review/{branch-slug}/S-{n}.md. Degraded (no call chain) if context.json.project is null.

Additionally generate the interactive explainer when the slice is tier A, when the diff is large or dense, or when --explain was passed:

/explain-diff-html S-{n}

In batch mode the explainer matters more than it did in stepwise: the user will be reading this slice cold, possibly days later, having never seen it grow. Generating it during the run costs nothing the user is waiting on. Never block a slice on it — a failure is recorded, not retried.

B7. Checkpoint commit

/commit-msg --checkpoint S-{n} --task <task>

Stages only the files the gate recorded as changed (never .claude/review/**, never -A), commits with the slice message, and writes the SHA back to run.json. Requires run.json.commit_authorized.

Commit-less mode (the user declined): save git diff > .claude/review/{slug}/S-{n}.diff and the file list instead, and record commit_sha: null.

Then ledger slice-status --slice n --status 검수대기 — 구현·기계검증은 끝났고 사람 검수만 남았다는 뜻이다. 승인/커밋 은 사용자가 데스크에서 승인했을 때만 찍는다. 그래서 러닝 직후 대시보드 완료율은 낮게 보이는 것이 정상이다 — 그 숫자는 "사용자가 본 것"을 세는 숫자다.

B8. Next slice

Loop to B0. No user interaction. No summary chatter between slices — one line per slice is enough: S-2 ✅ GREEN · 이월 2 · a3f9c21.

Phase C — Run report and handoff

When every slice is finished (committed, parked, or skipped):

1. run.json: finished_at, final per-slice state.
2. /change-walkthrough --all → .claude/review/{slug}/INDEX.md, the single entry point the review desk opens. (Per-slice guides already exist from B6; this only builds the index.)
3. Notify the user — they walked away. Use PushNotification if available; otherwise just report.
4. Present the run report, compactly:

구현 완료 — S-1~S-6 (승인 대기)

  S-1 ✅ 커밋 a3f9c21 · 게이트 GREEN · 이월 0
  S-2 ✅ 커밋 5b1e004 · 게이트 GREEN(fix 1) · 이월 2
  S-3 ⚠️ 보류 — 게이트 RED 잔존: order_service.py 순환 참조
  S-4 ⏭ 스킵 — S-3 의존
  S-5 ✅ 커밋 9c2ff31 · 게이트 GREEN · 이월 1  ← tier A, 이해자료 있음
  S-6 ✅ 커밋 1d40aa2 · 게이트 GREEN · 이월 0

  막힌 것 1 · 이월 5건 · 산출물 .claude/review/{slug}/
  다음: /review-desk  — 슬라이스별로 검수하고, 수정 요청은 큐에 모아 한 번에 반영한다

5. Do not open the review. The point of batch mode is that the user starts the review when they are ready. Say /review-desk and stop.
6. Do not run task-status 구현완료 yet — the ledger's "구현완료" means reviewed and approved. The review desk sets it at the end.

If the user is present when the run finishes and says "바로 보자", just invoke /review-desk — it is the same flow either way.

--stepwise (the old behavior)

Phase A identical (minus commit authorization). Then per slice: B1 → B2 → B6 → present to the user and wait. B3 (agent review) is optional in stepwise — the user is the reviewer. Approval branches:

Failure Handling