SuperAPI AI Directory

issue-merge

General & other

View repository

Updated 10-15 21:02

About this skill

문제가 생기면 상황 → 문제 → 멀쩡한 것 → 원인 → 선택 순서로 쉬운 말로 보고하고, 마지막은 질문 블록으로 닫는다.
문제 상황이 아니어도 말을 걸 때는 현재 단계를 함께 밝힌다.
Overall flow
flowchart TD
    A[/"/issue-merge"/] --> B[base 전용 임시 워크트리 생성]
    B --> C[inventory: 워크트리·이슈·PR·증거]
    C --> C0{후보 0개?}
    C0 -- 예 --> C1[제외 사유 보고 후 종료] --> Z
    C0 -- 아니오 --> D[워크트리별 이슈 내용 확인]
    D --> E{증거로 해결 확인?}
    E -- 아니오 --> E1[후보에서 제외 · 사유 기록] --> F
    E -- 예 --> E2[merge 후보 리스트업] --> F

    F[plan-dir: .issue/merge/16-21-53-64/] --> F1[preflight: 후보별 · 순서대로 누적]
    F1 --> G[분석 서브에이전트 N개 병렬]
    G --> H[plan.md 작성 · 충돌 현황 포함]
    H --> P{충돌 있음?}
    P -- 없음 --> I
    P -- 있음 --> R0[resolve: 작업 브랜치에서 판 깔기]
    R0 --> R1[해소 서브에이전트 병렬]
    R1 -- escalate --> R2[해당 PR 보류 · 사용자 확인] --> I
    R1 -- resolved --> R3{diff 승인}
    R3 -- 거부 --> R4[resolve --abort] --> R2
    R3 -- 승인 --> R5[--continue --push] --> R6[preflight 재확인]
    R6 -- 여전히 충돌 --> R0
    R6 -- clean --> I

    I[비판 서브에이전트: 계획 + 해소 결과]
    I -- block --> H
    I -- revise --> H
    I -- proceed --> J{사용자 승인}

    J -- 거부 --> Z[중단]
    J -- 승인 --> K0[PR 본문 Closes/Fixes/Resolves 제거]
    K0 --> K[PR 순서대로 merge]
    K --> L[통합 테스트: 각 이슈 증거 기준 재현]
    L -- 실패 --> L1[원인 보고 · 후속 이슈 제안] --> M
    L -- 통과 --> M[통과분 이슈 close]
    M --> N[워크트리 정리 · base-tree 제거]
    N --> O[보고 + 다음 행동 4지선다]
Machine-step API

The automatic orchestrator uses only node <skill>/scripts/issue-merge.mjs phase --request <absolute-canonical-json>. The request schema is contracts/issue-merge-phase-api-v1.json, and the full 9-step capability·effect·approval·checkpoint· reconciliation contract and raw-byte closure are contracts/issue-phase-capability-bundle-v1.json. Keep the order of cumulative preflight, per-PR approval, close after integration verification, and finally cleanup, and if the contract or closure verification fails, do not start an active run.

Script path

Among the following, the first path that exists를 <skill> is used.

.claude/skills/issue-merge      # 현재 프로젝트 (Claude Code)
.codex/skills/issue-merge       # 현재 프로젝트 (Codex)
~/.claude/skills/issue-merge    # 홈 설치
~/.codex/skills/issue-merge     # 홈 설치

<skill> 이 .claude/ If under , the execution family is claude, .codex/ If under , codex 다.

subagent
claude  .claude/agents/issue-merge-analyst.md    (model: haiku)
        .claude/agents/issue-merge-resolver.md   (model: sonnet)
        .claude/agents/issue-merge-critic.md     (model: haiku)
codex   .codex/agents/issue-merge-analyst.toml   (model = "gpt-5.6-luna")
        .codex/agents/issue-merge-resolver.toml  (model = "gpt-5.6-terra")
        .codex/agents/issue-merge-critic.toml    (model = "gpt-5.6-luna")

analyst and critic only make judgments, so a small model is sufficient. resolver fixes the code. If merged incorrectly, a regression nobody knows about remains, so the model is not downgraded.

If not present, install it.

sh <migrate-skill-agent>/scripts/migrate-skill-agent.sh --agent issue-merge-analyst  --target home --link --clone
sh <migrate-skill-agent>/scripts/migrate-skill-agent.sh --agent issue-merge-resolver --target home --link --clone
sh <migrate-skill-agent>/scripts/migrate-skill-agent.sh --agent issue-merge-critic   --target home --link --clone

If installation fails, proceed with the default subagent but report "model pinning failed" in one line. The critique step itself is not skipped. Whatever the model is, the plan must be broken once. If the resolver could not be pinned, disclose that fact together when showing the resolution diff — it gives the user grounds to look more carefully.

Execution order

Step 0

references/ask.md 의 the canonical 9 lines of step names as-is into TodoWrite items. Do not shorten or change the wording — it must match the step labels shown to the user. Update to completed immediately each time a step ends.

To the default branch, "checkout without bringing the change history", but do not touch the user's working tree.

node <skill>/scripts/issue-merge.mjs base-tree

.issue/merge/base/ A detached worktree is created at . All subsequent integration work is done inside it. If it already exists, just align it to the latest origin/<base> .

Steps 1–2

node <skill>/scripts/issue-merge.mjs inventory

A worktree with no commits ahead of the default branch is automatically excluded. Because there are no changes to merge and nothing to judge. It is not silently discarded but left in excluded with the reason, so record it in one line in the round report.

count If is 0, there is nothing to merge. Report only that fact and the exclusion reason and finish. Do not make a plan or launch subagents.

Details are in references/inventory.md.

Step 3

Compare each worktree's issue completion criteria against the evidence. references/inventory.md Follow the judgment rules of .

Steps 4–5

node <skill>/scripts/issue-merge.mjs plan-dir 16 21 53 64
node <skill>/scripts/issue-merge.mjs preflight --branch <브랜치>            # 후보마다
node <skill>/scripts/issue-merge.mjs preflight --branch <브랜치> --onto <commit>   # 계획 순서대로 누적

.issue/merge/16-21-53-64/ is created. Here, plan.md 와 review.md is used.

preflight Run first. The merge order is determined not by the number of files but by the conflict relationships finalized here. --onto with the previous round's commit must be carried over, so that cases of "passing on its own but breaking due to order" are caught.

If there are conflicts, resolve resolve them on the working branch side, and push after the diff is approved. If there are 0 conflicts, skip the resolution section entirely.

For details, references/merge-plan.md.

steps 6–7

references/verify-and-close.md follow.

close replaces the progress status label with status:close right before closing the issue (automatic). No separate call is needed.

Step 8

references/next-actions.md present the four choices as is.

Final report

대상        <n>개 워크트리 / [#16](url) [#21](url) [#53](url) [#64](url)
충돌        <n>건 감지 / <n>건 해소 / <n>건 보류
merge 됨    [#16](url) [#21](url) [#53](url)
보류        [#64](url) — <사유>
통합 테스트  <통과/실패 요약>
close 됨    [#16](url) [#21](url) [#53](url) (status:close)
정리        워크트리 <n>개 제거 / base-tree 제거
남은 것     <다음에 해야 할 것>
다음        <사용자가 고른 행동>

현재 단계 — issue-merge 8단계(다음 행동 선택) 완료

Links and paths follow references/ask.md Section 5 — the issue number is inventory of the output issueUrl, and the worktree path uses the display value.