implement

name	implement
description	Implements a single issue, creates a GitHub Issue/PR, and links them with `Closes
argument-hint	[ISSUE-number]
disable-model-invocation	true
allowed-tools	Read, Glob, Grep, Write, Edit, Bash(bash scripts/checkpoint.sh *), Bash(bash scripts/wt_setup.sh *), Bash(bash scripts/wt_cleanup.sh *), Bash(bash scripts/registry_edit.sh *), Bash(bash scripts/flock_edit.sh *), Bash(bash scripts/worktree.sh *), Bash(python3 scripts/*), Bash(git *), Bash(gh *), Bash(bash ${CLAUDE_PLUGIN_ROOT}/scripts/*), Bash(python3 ${CLAUDE_PLUGIN_ROOT}/scripts/*)

Kit Preamble — implement

Kit Script Root

Kit root: ${CLAUDE_PLUGIN_ROOT}

• Absolute path above → plugin install (substituted at load time; no project scripts/ dir): prefix every kit script command with it, e.g. bash <kit-root>/scripts/checkpoint.sh …. Absolute paths also work from worktrees.
• Literal ${…} placeholder above → standalone layout: run commands as written.

Project Context Detection

Run these checks silently at the start. Use results to adapt behavior:

• [ -f issues.md ] — if true, this project uses the sprint system. Respect issue numbering and STATUS.md.
• [ -f docs/sprint_state.md ] — if true and Status shows running, a sprint is active. Be aware of parallel work in worktrees.
• [ -f docs/prd_digest.md ] — if true, read it for quick project context before starting.

Kit Rules

• Verify gh auth status before any GitHub operation.

Checkpoint Verification Pattern

Every phase has a checkpoint. Run the verification command and check the exit code.

• Exit non-zero (blocking gate): STOP immediately, report failure, do NOT proceed.
• Exit 0 with an ADVISORY: line (advisory gate): report the gap, self-correct, continue. Standard prefix:

bash scripts/checkpoint.sh

Append --skill <name> --phase <phase> --issue <ID> for the specific check. checkpoint.sh resolves the main repo root internally, so the command stays a single prefix-matchable form (safe to allowlist as Bash(bash scripts/checkpoint.sh *)).

Worktree Setup Pattern

Pipeline skills operate in git worktrees to isolate changes from main.

• Create + freeze: WT="$(bash scripts/wt_setup.sh <branch>)" — creates the worktree via scripts/worktree.sh create and writes .claude-kit/freeze-dir.txt inside it in a single step.
• Resolve main root: bash scripts/worktree.sh root
• Remove safely: bash scripts/wt_cleanup.sh <branch> — cd's to main root inside a subshell, then removes the worktree (never leaves CWD dangling). All file operations happen inside $WT/. Shared files live on main only.

Registry Update Pattern

Shared files (issues.md, STATUS.md, CHANGELOG.md) are managed on main only. Always use registry_edit.sh for concurrent-safe writes — it resolves the main repo root internally and delegates to flock_edit.sh:

bash scripts/registry_edit.sh issues.md -- bash -c '<update command>'

Never commit these files to feature branches.

Checkpoint Rules — MANDATORY

Every phase in this skill has a CHECKPOINT block. You MUST run the verification command after completing each phase. Blocking gates (MANDATORY — NEVER SKIP) exit non-zero on failure: STOP immediately, report, do NOT proceed. Advisory gates (ADVISORY (report & continue)) always exit 0 and print an ADVISORY: line on failure: report the gap, self-correct, then continue — do NOT halt on them (ISSUE-031). Never skip running a checkpoint of either tier.

Path convention: Checkpoint commands use the bash scripts/checkpoint.sh wrapper, which resolves the main repo root internally (via scripts/worktree.sh root). This ensures the verification script is found regardless of whether CWD is the main repo or a worktree, and keeps the command prefix-matchable for permission allowlists.

Hard requirements:

• Create GitHub Issue if missing: gh issue create
• Create/update PR and include Closes #<issue_number> in PR body.

Algorithm:

1. Ensure gh authenticated (gh auth status).

Phase 0 — Spec gate (MANDATORY, runs before any other phase)

Before reading the test plan, the issue body, or anything else, evaluate the spec gate for $ARGUMENTS. This protects against the failure mode where a non-trivial feature gets coded without any reviewable decision artifact.

0a) Parse flags: check $ARGUMENTS for --skip-spec-gate. If present, the gate logs a telemetry-style bypass note (one line printed to stdout) and proceeds to step 1. Strip the flag from $ARGUMENTS before continuing.

0b) Compute the gate decision:

python3 scripts/spec_gate.py $ARGUMENTS [--skip-spec-gate]

The script reads issues.md, detects sprint mode via KIT_SPRINT_MODE=1, scans the issue body for signals (api/schema/migration/breaking/protocol/데이터모델/new-package + estimate-at-cap), and prints a JSON object with decision, reasons, signals, spec_path, sprint_mode.

0c) Branch on decision:

• decision: "proceed" — log the reasons (and signals if non-empty) inline so the user can see why the gate let it through, then continue to step 1.

• decision: "auto_spec" (sprint mode, Spec-Required, no SPEC yet) — invoke the /spec skill inline on the current branch:

  • Set env KIT_SPRINT_MODE=1 so /spec knows it is being auto-invoked.
  • Pass the issue id: /spec $ARGUMENTS.
  • Wait for /spec to complete and produce docs/specs/SPEC-<NNN>.md with the Spec: field updated on the issue.
  • The SPEC commit message format is enforced by /spec (docs(spec): SPEC-<NNN> — <decision summary>).
  • After /spec returns, re-run python3 scripts/spec_gate.py $ARGUMENTS to confirm the new decision is proceed. If it is still not proceed, STOP and report.

• decision: "hold" (non-sprint, requires user input) — present a structured 3-way choice using the project's question mechanism (e.g., AskUserQuestion):

  • Option 1 — Run /spec now: invoke /spec $ARGUMENTS, then resume at step 0b (re-evaluate gate after SPEC lands).
  • Option 2 — Mark Spec-Required: false: ask the user for a one-line reason; rewrite the issue's Spec-Required: field to false and append the reason to the issue's Implementation Notes; then proceed to step 1.
  • Option 3 — Cancel implement: print the gate's reasons and STOP cleanly.

  Quote the gate's reasons and signals to the user so they understand the prompt.

• decision: "bypassed" (--skip-spec-gate was passed) — print the one-line bypass note (telemetry-style: spec_gate_bypassed issue=$ARGUMENTS) and continue.

0d) Only after Phase 0 produces a proceed-equivalent outcome does the rest of the algorithm run.

CHECKPOINT — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill implement --phase test-plan --issue $ARGUMENTS Verifies docs/test_plan.md exists with a non-empty Risk Matrix. If exit code ≠ 0: STOP — run /kickoff first or create test_plan.md manually.

2. Locate $ARGUMENTS in issues.md. Read the issue's Goal, Scope, AC, and Implementation Notes.

   • Manual check: If the issue has Manual: true, STOP immediately. Report to the user: "This issue requires manual action — see Implementation Notes." Do NOT proceed with automated implementation. 2a) Figma prototype upsert — MANDATORY when Figma URLs exist: Scan the issue's Implementation Notes for Figma URLs (pattern: figma.com/design/ or figma.com/file/).

   If NO Figma URLs found: skip to step 2a checkpoint.

   If Figma URLs ARE found — you MUST execute ALL of the following steps:

   1. Determine the platform from the issue's Platform field:

      • mobile → --mobile
      • desktop → --desktop
      • web or empty → no flag (default) Run the fetch script with the platform flag and all extracted URLs:

      python3 scripts/figma_fetch.py [--mobile|--desktop] <url1> <url2> ...
      

      If the script exits with non-zero (e.g., FIGMA_TOKEN not set, invalid URL, API error): STOP and report the error to the user. Do NOT proceed — the issue explicitly requires Figma data.

   2. figma_fetch.py automatically generates:

      • figma-export/design_data.json — full node tree data
      • figma-export/figma_styles.css — complete CSS rules (gradients, shadows, fonts, positioning, responsive, states)
      • figma-export/component_map.json — node→class→asset mapping with html_hint
      • figma-export/assets/ — downloaded SVG/PNG icons and images
      • figma-export/renders/ — Figma-rendered reference PNGs

   3. Extract breakpoints from the issue. Read the issue's Implementation Notes or the PRD for responsive breakpoint specs (e.g., "Desktop 1400px+ / Tablet 768px+ / Mobile 360px+"). If found, pass them explicitly to the figma-converter prompt below. If not found, use the Figma frame widths as breakpoints.

   4. Invoke the figma-converter agent (via Task) with this prompt:

      You are the figma-converter agent. Read agents/figma-converter.md for your full instructions.
      
      ## Responsive Breakpoints (from project spec — use EXACTLY these values)
      {Insert the breakpoints extracted in step 3, e.g.:
       - Desktop: > 1400px (default)
       - Tablet: ≤ 1400px
       - Mobile: ≤ 768px}
      
      ## Required Steps (do ALL of these — a placeholder HTML is NOT acceptable)
      
      ### Step 1: Read all input files
      - Read figma-export/renders/*.png (open each image — these are your visual target)
      - Read figma-export/design_data.json (full content — contains node tree with coordinates, text, styles)
      - Read figma-export/figma_styles.css (skim — contains pre-generated CSS classes)
      - Read figma-export/component_map.json (skim — contains asset paths and html_hints)
      
      ### Step 2: Build desktop HTML
      - Read frames[0].tree from design_data.json
      - Frame origin: tree.x, tree.y. Element position: element.y - frame.y, element.x - frame.x
      - Create a .frame container (width:100%, height:{frame_h}px)
      - Background images: class="bg", width:100%, position:absolute, z-index:1
      - Content wrapper: class="cw", width:{frame_w}px, left:50%, transform:translateX(-50%), z-index:3
      - Every element inside cw: position:absolute, top/left from coordinates, WITH a class name
      - Import figma_styles.css via <link>
      - z-index layers: bg(1) → deco(5) → content(10) → nav(50)
      - All text from design_data.json text_content fields — do NOT invent text
      
      ### Step 3: Add tablet @media
      - **Read the issue's breakpoint spec** from issues.md or PRD — use THOSE breakpoint values, NOT defaults
      - Read frames[1].tree from design_data.json
      - Write @media block with THAT frame's coordinates, font sizes, widths
      - Every element that exists in frames[1] gets repositioned
      - Check text_style.segments for mixed font-weights → generate <span> tags
      
      ### Step 4: Add mobile @media
      - Use the issue's breakpoint spec for mobile threshold
      - Read frames[2].tree from design_data.json
      - Same process as Step 3
      
      ### Step 5: Verify
      - Open the HTML in browser. Compare with render PNGs.
      - Scroll through entire page. Check: backgrounds visible? Text readable? Footer present?
      
      ## Output
      Write to: prototype/screens/desktop.html
      This must be a COMPLETE HTML file — not a placeholder.
      If you cannot complete it, explain what blocked you.
      

   5. Verify the output is not a placeholder. Read the generated HTML file. If it contains "placeholder" or is less than 1KB, the figma-converter failed — retry with the same prompt.

   Do NOT skip this step when Figma URLs exist. The checkpoint below WILL fail if figma_fetch.py was not executed.

CHECKPOINT — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill implement --phase figma --issue $ARGUMENTS Auto-passes when no Figma URLs exist. Fails if Figma URLs found but design_data.json not generated. If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

2b) Gather context — read the following docs (if they exist, skip silently if not). Read all applicable documents via parallel Read tool calls in a single message. Do NOT read them sequentially.

• docs/prd_digest.md — quick PRD context (goals, features, NFRs, scope)
• docs/architecture.md — tech stack, modules, API design
• docs/data_model.md — schema, indexes, query patterns, seed data, migrations
• docs/requirements.md — related FRs/NFRs referenced by the issue
• recalled review lessons (native memory) — known recurring review findings to proactively avoid
• docs/test_plan.md — test strategy, risk matrix, critical flows to guide test writing
• UI context — read all of the following in parallel (when the issue has UI: true, or contains UI keywords in Track/title):
  • docs/design_system.md — CSS tokens, component specs
  • docs/design_philosophy.md — aesthetic direction
  • docs/wireframes.md — layout for the relevant screen
  • docs/interactions.md — states, transitions, animations for the relevant flow
  • docs/copy_guide.md — UI labels, error messages, empty states, glossary
  • prototype/screens/*.html — visual reference for the relevant screen
  • figma-export/skeleton.html — complete HTML structure to copy into implementation (semantic tags, text, assets, CSS classes)
  • figma-export/figma_styles.css — ready-to-use CSS rules (includes responsive @media queries + :hover/:focus states)
  • figma-export/component_map.json — maps Figma nodes to CSS classes, asset paths (with html_hint), children order
  • figma-export/assets/ — downloaded SVG/PNG icons and images from Figma
• Mobile UI context — read all of the following in parallel (when the issue involves mobile/React Native work):
  • docs/design_system_mobile.md — React Native design tokens, component specs
  • docs/design_philosophy.md — aesthetic direction (shared with web)
  • docs/wireframes_mobile.md — mobile layout, gestures, safe areas
  • docs/interactions_mobile.md — gesture specs, haptic mapping, transitions
  • docs/copy_guide.md — UI labels, error messages (shared with web)
  • prototype-mobile/src/screens/*.tsx — React Native screen reference
• Pass all relevant context to the developer subagent prompt.

3. Ensure Branch is set; if empty, derive issue/$ARGUMENTS-<slug> and write back.
   • File lock: wrap the issues.md read-modify-write with: bash scripts/registry_edit.sh issues.md -- bash -c '<update command>'
4. Ensure GH-Issue exists:
   • If empty: gh issue create --title "[$ARGUMENTS] <title>" --body "<body>"
   • Body must include: issue goal, scope (in/out), acceptance criteria, and implementation notes from issues.md.
   • Capture issue number/url; write back to issues.md.
   • File lock: wrap the issues.md write-back with: bash scripts/registry_edit.sh issues.md -- bash -c '<update command>'

CHECKPOINT — ADVISORY (report & continue) Run: bash scripts/checkpoint.sh --skill implement --phase issue --issue $ARGUMENTS Advisory: exits 0 even on failure, printing an ADVISORY: line — report the gap, self-correct, then continue.

5. Create worktree for the branch (and auto-initialize the freeze marker):

   WT="$(bash scripts/wt_setup.sh issue/$ARGUMENTS-<slug>)"
   

   wt_setup.sh creates the worktree via scripts/worktree.sh create and writes .claude-kit/freeze-dir.txt inside it in a single step. All subsequent file operations (code, tests) happen inside $WT/. From this point, Edit/Write operations outside $WT/ will be blocked (if /freeze or /guard hooks are active). Registry files on main (issues.md, STATUS.md) are updated via bash scripts/registry_edit.sh from the main repo root — this is the only exception.

CHECKPOINT — ADVISORY (report & continue) Run: bash scripts/checkpoint.sh --skill implement --phase worktree --issue $ARGUMENTS Advisory: exits 0 even on failure, printing an ADVISORY: line — report the gap, self-correct, then continue.

6. Write tests FIRST (TDD Red phase) inside $WT/. This project follows TDD: write failing tests before writing implementation code.
   • Read test_plan.md first: If docs/test_plan.md exists, read it. Use the Risk Matrix and Critical Flows to prioritize which scenarios to test. Map your tests to the test cases defined there (TC-NNN).
   • Every new behavior MUST have at least one test. No exceptions.
   • Each AC (Acceptance Criterion) in the issue maps to at least one test case.
   • Cover the happy path AND at least one error/edge case per AC.
   • Test files must follow project conventions (e.g., test_*.py in tests/).
   • Tests must contain real assertions — empty test functions, pass-only bodies, or tests without assert/expect will be rejected at checkpoint.
   • E2E tests: If the issue involves a critical user journey (as defined in docs/test_plan.md Risk Matrix), write an E2E test. Web: tests/e2e/*.spec.ts. Mobile: e2e/*.yaml or e2e/*.test.ts.
   • Do NOT skip this step. Code without meaningful tests will be rejected at checkpoint. 6b) Verify test coverage (self-check before checkpoint):
   • Cross-reference your test files against the issue's AC list. Each AC should have a corresponding test.
   • If docs/test_plan.md exists, check that any High-risk flows affected by your changes have test coverage.
   • The checkpoint will warn about potential AC coverage gaps.

CHECKPOINT — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill implement --phase tests-written --issue $ARGUMENTS If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

7. Verify RED — Run tests to confirm they FAIL (no implementation yet). Tests should fail because the implementation code doesn't exist yet. This ensures tests are testing real behavior, not vacuously passing.

CHECKPOINT — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill implement --phase red --issue $ARGUMENTS If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

8. Implement minimal code inside $WT/. Write the minimum code needed to make all tests pass. Follow existing project patterns.

   Minimality gate — walk the Decision Ladder before generating code (the developer subagent enforces this; the orchestrator must not write prompts that contradict it):

   1. Does this need to exist? (YAGNI) → 2. Does stdlib cover it? → 3. Native platform/framework feature? → 4. Already-installed dependency? → 5. Can it be one line? → 6. Only then write the minimum that works. Prohibitions: no abstraction with a single implementation, no avoidable new dependency, no unrequested boilerplate — deletion over addition, fewest files possible. This never overrides safety: it does not license skipping the TDD tests, input validation, error handling, security, accessibility, or Figma/design fidelity. Minimal means less code, not less correct.

   If Figma data exists (figma-export/ directory present):

   • BEFORE writing any code, read prototype/screens/*.html — this is your visual target
   • Read figma-export/figma_styles.css — import this CSS directly
   • Read figma-export/component_map.json — use class names and asset paths
   • Read figma-export/renders/*.png — compare your implementation against these
   • Your implementation must visually match the prototype HTML. Do NOT guess the design.

   🚫 Structure-source prohibition (when figma-export/ exists) — applies to BOTH this skill and any developer subagent prompt you write:

   • prototype/screens/*.html (generated by figma-converter from Figma) is the ONLY structural source of truth. Layout, grid, hero composition, card count, decorative elements, breakpoint thresholds — all come from the prototype.
   • It is FORBIDDEN to designate any other existing project file (e.g., a sibling product's template, a previous page in the same repo) as the structure source. Reference other files only for coding patterns (Django template tags, view conventions, naming) — never for visual structure.
   • When invoking the developer subagent, you MUST NOT write prompts containing phrases like:
     • "model on the existing X.html pattern"
     • "copy X structure as the starting point"
     • "replace X-specific values with Y values" (this implies copying X's structure)
     • "use X.html as the template"
   • Instead, the developer prompt MUST say: "The visual source of truth is prototype/screens/desktop.html (and tablet/mobile variants). Reproduce its structure exactly. Use other project files only as a reference for coding conventions, not for layout."
   • Rationale: a previous incident produced a page that visually matched a sibling product instead of the Figma design, because the orchestrator prompt reframed an unrelated template as the structure source. Static checkpoints cannot detect this drift after the fact — the prohibition must be enforced at prompt-authoring time.

CHECKPOINT — ADVISORY (report & continue) Run: bash scripts/checkpoint.sh --skill implement --phase code --issue $ARGUMENTS Advisory: exits 0 even on failure, printing an ADVISORY: line — report the gap, self-correct, then continue.

9. Run tests (GREEN phase) inside $WT/. All tests must pass. If any fail, fix the implementation (not the tests) until green. The checkpoint also runs platform-specific gates (e2e-web, e2e-mobile, etc.) as warnings. Gate failures don't block implementation but flag integration risks early.

CHECKPOINT — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill implement --phase test --issue $ARGUMENTS If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

9.5) Figma fidelity loop (UI issues with Figma data only — skip if no figma-export/design_data.json): Iteratively refine the implementation until all Figma tokens match and structure is correct.

a) Token compliance (primary — blocking):

MAX_ITERATIONS = 3
for i in 1..MAX_ITERATIONS:
  Run: python3 scripts/verify_figma_compliance.py --project-path $WT
  IF exit code = 0 (all tokens match): BREAK.
  IF exit code ≠ 0:
    1. Read the violation report — each violation shows file:line, found value, and Figma-allowed values.
    2. Fix the implementation: replace wrong colors/fonts/spacings/etc. with Figma values.
    3. Re-run tests to ensure fixes don't break functionality.
    4. Continue loop.
IF all MAX_ITERATIONS exhausted: log remaining violations and proceed.

b) Computed style verification loop (primary — blocking):

MAX_ITERATIONS = 3
for i in 1..MAX_ITERATIONS:
  Run: python3 scripts/verify_computed_styles.py --project-path $WT
  IF exit code = 0 (all computed styles match): BREAK.
  IF exit code ≠ 0:
    1. Read the violation report — shows ACTUAL rendered values vs Figma-allowed values.
       These are real computed values from the browser, not source code regex matches.
    2. Fix: the violation tells you exactly which element, property, and computed value is wrong.
    3. Re-run tests.
    4. Continue loop.
IF all MAX_ITERATIONS exhausted: log remaining violations and proceed.

c) Structural match loop (primary — blocking, per-viewport):

MAX_ITERATIONS = 3
for i in 1..MAX_ITERATIONS:
  Run: python3 scripts/verify_structural_match.py --project-path $WT
  IF exit code = 0 (all viewports matched): BREAK.
  IF exit code ≠ 0:
    1. Read the per-viewport report. Each violation shows:
       - Which viewport (desktop/tablet/mobile) has missing elements
       - Missing element types (buttons, inputs, icons, navigation)
       - Missing text content (copy from Figma not found)
       - Missing responsive CSS (@media queries for each breakpoint)
    2. Fix the implementation:
       - Add missing elements for each viewport
       - Add @media queries for tablet/mobile breakpoints
       - Ensure responsive behavior matches Figma's per-viewport design
    3. Re-run tests to ensure fixes don't break functionality.
    4. Continue loop.
IF all MAX_ITERATIONS exhausted: log remaining violations and proceed.

c) Layout verification loop (primary — blocking):

MAX_ITERATIONS = 3
for i in 1..MAX_ITERATIONS:
  Run: python3 scripts/verify_layout.py --project-path $WT
  IF exit code = 0 (layout matches): BREAK.
  IF exit code ≠ 0:
    1. Read the violation report:
       - Wrong direction: "sidebar should be row but has flex-direction: column"
       - Wrong order: "nav should be left-of content but appears after it"
    2. Fix: adjust flex-direction, reorder DOM elements, fix container structure
    3. Re-run tests.
    4. Continue loop.
IF all MAX_ITERATIONS exhausted: log remaining violations and proceed.

e) Same-renderer visual diff (blocking — prototype HTML vs implementation, both Chromium):

Run: python3 scripts/verify_visual_diff.py --project-path $WT --threshold 1
IF exit code ≠ 0: read diff images, fix visible layout/style issues, re-run.

Both prototype and implementation are rendered by the same Chromium engine, so there are no font hinting or anti-aliasing false positives.

f) Visual diff advisory (non-blocking):

Run: python3 scripts/verify_visual_diff.py --project-path $WT --threshold 5

Generates diff images in figma-export/visual-diff/ for visual inspection. Do NOT block on pixel diff — it's an advisory signal due to renderer differences (Figma vs Chromium). If diff > 5%: review the diff images and fix obvious layout issues.

10. Commit + push (from $WT/).

CHECKPOINT — ADVISORY (report & continue) Run: bash scripts/checkpoint.sh --skill implement --phase push --issue $ARGUMENTS Advisory: exits 0 even on failure, printing an ADVISORY: line — report the gap, self-correct, then continue.

11. Create PR (or update):

• Title: [$ARGUMENTS] <title>
• Body begins with Closes #<issue_number>

CHECKPOINT — ADVISORY (report & continue) Run: bash scripts/checkpoint.sh --skill implement --phase pr --issue $ARGUMENTS Advisory: exits 0 even on failure, printing an ADVISORY: line — report the gap, self-correct, then continue.

12. Record PR URL in issues.md; set Status=done; update STATUS.md. Use registry_edit.sh — it resolves the main repo root internally so you never have to build paths via command substitution:

bash scripts/registry_edit.sh issues.md -- bash -c '<update command>'
bash scripts/registry_edit.sh STATUS.md -- bash -c '<update command>'

CHECKPOINT — ADVISORY (report & continue) Run: bash scripts/checkpoint.sh --skill implement --phase registry --issue $ARGUMENTS Advisory: exits 0 even on failure, printing an ADVISORY: line — report the gap, self-correct, then continue.

Shared Registry Files

IMPORTANT: Never commit issues.md, STATUS.md, or CHANGELOG.md to the feature branch. These are registry files managed only on main. Always use bash scripts/registry_edit.sh <file> -- bash -c '<update command>' — the wrapper resolves the main repo root internally.

Error Handling

• If gh auth status fails: stop and instruct the user to run gh auth login.
• If issue not found in issues.md: stop and report the missing issue number.
• If gh issue create fails: retry once; if still failing, stop and report the error.
• If tests fail: do NOT push or create PR. Report failing tests and stop.
• If git push fails: check for upstream conflicts; report and stop.
• If gh pr create fails: retry once; if still failing, the branch is already pushed — report and let user create PR manually.

Rollback

• Use bash scripts/wt_cleanup.sh <branch> for safe worktree removal. The wrapper cd's to the main repo root and then removes the worktree in a single subshell, so the caller never ends up with a deleted CWD.
• If failure occurs after worktree creation but before PR:
  1. bash scripts/wt_cleanup.sh <branch>
  2. git push origin --delete <branch> (remote cleanup, if pushed)
• If failure occurs after PR creation:
  1. gh pr close <pr_number> to close the broken PR.
  2. Clean up worktree and branch as above.
• Revert issues.md status back to doing or backlog if it was prematurely set to done.