diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 488014e..db9ea21 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -4,13 +4,13 @@ "name": "MTGVim" }, "metadata": { - "description": "SoT gap, route, reflect, learn, browser-verify와 grill/prototype/merge-conflict/handoff/handon/to-prd/to-issues/arch-review를 제공하는 TigerKit Claude Code 플러그인입니다." + "description": "TigerKit `/tk:*` command plugin입니다." }, "plugins": [ { "name": "tk", "source": "./", - "description": "SoT gap, route, reflect, learn, browser-verify와 grill/grooming/prototype/merge-conflict/handoff/handon/to-prd/to-issues/arch-review를 제공하는 TigerKit Claude Code 플러그인입니다. active command surface는 /tk:gap, /tk:route, /tk:reflect, /tk:learn, /tk:browser-verify, /tk:grill, /tk:grooming, /tk:prototype, /tk:arch-review, /tk:merge-conflict, /tk:handoff, /tk:handon, /tk:to-prd, /tk:to-issues 입니다." + "description": "TigerKit `/tk:*` command plugin입니다." } ] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index e900efd..a2f82c9 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "tk", - "description": "SoT gap, route, reflect, learn, browser-verify와 grill/grooming/prototype/merge-conflict/handoff/handon/to-prd/to-issues/arch-review를 제공하는 TigerKit Claude Code 플러그인입니다.", - "version": "16.5.13", + "description": "TigerKit `/tk:*` command plugin입니다.", + "version": "16.5.14", "author": { "name": "MTGVim" }, diff --git a/.tigerkit/docs/usage.md b/.tigerkit/docs/usage.md index dcb319f..4b73074 100644 --- a/.tigerkit/docs/usage.md +++ b/.tigerkit/docs/usage.md @@ -48,6 +48,17 @@ TigerKit은 일반 autopilot 또는 sealed workflow engine이 아니라 gap, rou - `/tk:to-issues`는 vertical-slice issue draft 생성 surface입니다. - `/tk:browser-verify`는 번들된 browser-verify 엔진 skill을 현재 repo에 대응하는 `~/.tigerkit/repos//browser-verify/` profile과 함께 사용하는 direct QA / behavior verification surface입니다. +## Shared command boundaries + +아래 경계는 여러 TigerKit command가 공통으로 따릅니다. + +- command가 직접 소유한 artifact surface가 아니면 source tree, plugin manifest, command source를 임의 수정하지 않습니다. +- preview-only / report-only / draft-only surface는 그 경계를 유지하고 구현 완료처럼 포장하지 않습니다. +- 승인 우회, silent publish, chat dump, endless questioning, fake success 같은 운영 노이즈를 만들지 않습니다. +- 이미 코드나 artifact에서 직접 확인 가능한 사실은 다시 묻거나 장문 복붙으로 반복하지 않습니다. + +개별 command 문서는 이 공통 경계를 반복 나열하는 대신, command-specific guidance와 output contract에 집중합니다. + ## Command Surface | Command | 역할 | 저장 성격 | diff --git a/commands/arch-review.md b/commands/arch-review.md index f83dd7c..ad06342 100644 --- a/commands/arch-review.md +++ b/commands/arch-review.md @@ -1,5 +1,5 @@ --- -description: boundary, ownership, coupling, 반복 마찰을 evidence-first로 검토하는 report-only 구조 리뷰입니다. +description: 구조 마찰을 검토합니다. argument-hint: '"" [--target ] [--print-checklist]' --- @@ -9,7 +9,7 @@ argument-hint: '"" [--target ] [--print-checklist]' 목표: `/tk:arch-review`는 코드베이스의 구조적 문제를 바로 리팩터링으로 밀지 않고, boundary, ownership, coupling, 반복 마찰을 evidence-first로 검토하는 report-only surface입니다. -canonical skill: +related wrapper skill: ```text skills/arch-review/SKILL.md @@ -17,6 +17,7 @@ skills/arch-review/SKILL.md ## Core boundary +- 공통 command boundary는 `.tigerkit/docs/usage.md`의 `Shared command boundaries`를 따릅니다. - report-only - source 수정 금지 - auto refactor 금지 @@ -59,10 +60,3 @@ Arch Review 완료 | Arch Review 중단 ▶️ First step: - ``` - -## Non-goals - -- 구현 완료 보고 -- 근거 없는 대수술 제안 -- source write 없는 척하면서 사실상 리팩터링 강행 -- README/RFC 작성만으로 구조 문제가 해결됐다고 주장 diff --git a/commands/browser-verify.md b/commands/browser-verify.md index aecb4c6..9a0307f 100644 --- a/commands/browser-verify.md +++ b/commands/browser-verify.md @@ -1,5 +1,5 @@ --- -description: 번들된 browser-verify 엔진 skill을 `~/.tigerkit` repo profile과 함께 사용하는 direct QA / behavior verification surface입니다. +description: browser-verify QA를 실행합니다. argument-hint: '"" [--mode ] [--print-profile-template]' --- @@ -9,7 +9,7 @@ argument-hint: '"" [--mode run browser verif ## Core boundary +- 공통 command boundary는 `.tigerkit/docs/usage.md`의 `Shared command boundaries`를 따릅니다. - 이 command는 user-global provisioning mode를 만들지 않습니다. - engine install/update를 수행하지 않습니다. - current repo에 대응하는 `~/.tigerkit` profile만 읽고, profile이 없을 때만 같은 repo-scoped 경로에 missing profile 파일을 신규 생성합니다. @@ -135,11 +136,3 @@ Browser Verify 준비 완료 | Browser Verify 프로필 생성 완료 | Browser /tk:browser-verify "figma랑 이 화면 맞는지 봐줘" --mode figma-diff /tk:browser-verify "이 티켓 기준으로 저장 플로우가 실제로 동작하는지 검증" --mode behavior-verify ``` - -## Non-goals - -- engine provisioning -- user-global profile provisioning -- full install/update workflow -- forced overwrite / merge of profile assets -- legacy profile auto-migration diff --git a/commands/gap.md b/commands/gap.md index d8cb252..15bb31f 100644 --- a/commands/gap.md +++ b/commands/gap.md @@ -1,5 +1,5 @@ --- -description: SoT와 현재 구현의 차이를 구현 전에 한 번 점검하는 분석 명령입니다. +description: SoT gap을 분석합니다. argument-hint: "[SoT refs or pasted source] [--target ] [--print-report]" --- @@ -11,7 +11,7 @@ argument-hint: "[SoT refs or pasted source] [--target ] [--print-repo 이 명령은 workflow를 생성하거나 고정하지 않습니다. -canonical skill: +related wrapper skill: ```text skills/gap/SKILL.md @@ -133,134 +133,46 @@ packet은 최소한 아래를 담아야 합니다. `precedence.status`는 `resolved | unresolved`를 구분해야 하며, unresolved source conflict는 packet에서도 조용히 병합하지 않습니다. `Current`가 plan이나 generated artifact뿐이면 packet의 evidence type도 그대로 남겨, route나 후속 surface가 그것을 implementation proof로 착각하지 않게 합니다. -실제 저장이 필요할 때는 최종 markdown report를 만든 뒤 **설치된 TigerKit plugin cache에서 helper를 발견한 다음** 사용합니다. 현재 작업 repo의 `scripts/` 상대경로를 가정하면 안 되고, `CLAUDE_PLUGIN_ROOT`가 비어 있거나 marketplace mirror를 가리키는 경우도 있으므로 installPath/cache를 직접 확인합니다. +실제 저장이 필요할 때는 최종 markdown report를 만든 뒤 설치된 TigerKit helper `scripts/tigerkit_state.py`를 호출합니다. `CLAUDE_PLUGIN_ROOT`가 있으면 그것을 우선 쓰고, 없으면 설치된 plugin root를 조회합니다. command 문서는 현재 작업 repo에 TigerKit `scripts/`가 있다고 가정하지 않습니다. + +enabled `tk@tiger-kit` install이 이 source checkout보다 오래되어 `draft-paths`, `gap-packet-paths`, `read-gap-packet`, `write-gap-packet` 같은 helper subcommand에서 `invalid choice`가 나오면 먼저 marketplace/plugin을 업데이트하거나, matching checkout/install root를 `CLAUDE_PLUGIN_ROOT`로 지정해야 합니다. + +```bash +claude plugin marketplace update tiger-kit +claude plugin install tk@tiger-kit --scope user +``` ```bash -TIGERKIT_STATE_SCRIPT="$({ -python3 - <<'PY' -import json, re, subprocess -from pathlib import Path - -def version_key_text(text: str): - try: - return tuple(int(part) for part in text.split('.')) - except Exception: - return (0,) - -def version_key_path(path: Path): - return version_key_text(path.parent.parent.name) - -def cache_path_for_version(version: str): - path = Path.home() / '.claude/plugins/cache/tiger-kit/tk' / version / 'scripts' / 'tigerkit_state.py' - return path if path.is_file() else None - -candidates = [] -seen = set() -try: - details = subprocess.check_output(['claude', 'plugin', 'details', 'tk'], text=True) - first = details.splitlines()[0].strip() - match = re.match(r'^tk\s+(\d+(?:\.\d+)*)$', first) - if match: - path = cache_path_for_version(match.group(1)) - if path: - candidates.append(path) - seen.add(str(path)) -except Exception: - pass -try: - plugins = json.loads(subprocess.check_output(['claude', 'plugin', 'list', '--json'], text=True)) -except Exception: - plugins = [] -for item in plugins: - if item.get('id') == 'tk@tiger-kit' and item.get('enabled'): - path = Path(item.get('installPath', '')) / 'scripts' / 'tigerkit_state.py' - if path.is_file() and str(path) not in seen: - candidates.append(path) - seen.add(str(path)) -for path in sorted(Path.home().glob('.claude/plugins/cache/tiger-kit/tk/*/scripts/tigerkit_state.py'), key=version_key_path, reverse=True): - if str(path) not in seen: - candidates.append(path) - seen.add(str(path)) -if not candidates: - raise SystemExit('TigerKit helper not found in installed plugin cache. Run `claude plugin marketplace update tiger-kit` and reinstall/update `tk@tiger-kit`.') -print(candidates[0]) -PY -})" -python3 "$TIGERKIT_STATE_SCRIPT" write-gap --repo-root "$PWD" --report-file /absolute/path/to/final-gap-report.md +TIGERKIT_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$({ claude plugin list --json | python3 -c 'import json,sys; print(next(item["installPath"] for item in json.load(sys.stdin) if item.get("id") == "tk@tiger-kit" and item.get("enabled")))'; })}" +python3 "$TIGERKIT_PLUGIN_ROOT/scripts/tigerkit_state.py" write-gap --repo-root "$PWD" --report-file /absolute/path/to/final-gap-report.md ``` packet path만 확인하려면: ```bash -python3 "$TIGERKIT_STATE_SCRIPT" gap-packet-paths --repo-root "$PWD" +TIGERKIT_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$({ claude plugin list --json | python3 -c 'import json,sys; print(next(item["installPath"] for item in json.load(sys.stdin) if item.get("id") == "tk@tiger-kit" and item.get("enabled")))'; })}" +python3 "$TIGERKIT_PLUGIN_ROOT/scripts/tigerkit_state.py" gap-packet-paths --repo-root "$PWD" ``` 현재 same repo/scope packet을 읽으려면: ```bash -python3 "$TIGERKIT_STATE_SCRIPT" read-gap-packet --repo-root "$PWD" +TIGERKIT_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$({ claude plugin list --json | python3 -c 'import json,sys; print(next(item["installPath"] for item in json.load(sys.stdin) if item.get("id") == "tk@tiger-kit" and item.get("enabled")))'; })}" +python3 "$TIGERKIT_PLUGIN_ROOT/scripts/tigerkit_state.py" read-gap-packet --repo-root "$PWD" ``` packet json을 저장하려면: ```bash -python3 "$TIGERKIT_STATE_SCRIPT" write-gap-packet --repo-root "$PWD" --packet-file /absolute/path/to/final-gap-packet.json +TIGERKIT_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$({ claude plugin list --json | python3 -c 'import json,sys; print(next(item["installPath"] for item in json.load(sys.stdin) if item.get("id") == "tk@tiger-kit" and item.get("enabled")))'; })}" +python3 "$TIGERKIT_PLUGIN_ROOT/scripts/tigerkit_state.py" write-gap-packet --repo-root "$PWD" --packet-file /absolute/path/to/final-gap-packet.json ``` stdin으로 직접 넘길 수도 있습니다. ```bash -TIGERKIT_STATE_SCRIPT="$({ -python3 - <<'PY' -import json, re, subprocess -from pathlib import Path - -def version_key_text(text: str): - try: - return tuple(int(part) for part in text.split('.')) - except Exception: - return (0,) - -def version_key_path(path: Path): - return version_key_text(path.parent.parent.name) - -def cache_path_for_version(version: str): - path = Path.home() / '.claude/plugins/cache/tiger-kit/tk' / version / 'scripts' / 'tigerkit_state.py' - return path if path.is_file() else None - -candidates = [] -seen = set() -try: - details = subprocess.check_output(['claude', 'plugin', 'details', 'tk'], text=True) - first = details.splitlines()[0].strip() - match = re.match(r'^tk\s+(\d+(?:\.\d+)*)$', first) - if match: - path = cache_path_for_version(match.group(1)) - if path: - candidates.append(path) - seen.add(str(path)) -except Exception: - pass -try: - plugins = json.loads(subprocess.check_output(['claude', 'plugin', 'list', '--json'], text=True)) -except Exception: - plugins = [] -for item in plugins: - if item.get('id') == 'tk@tiger-kit' and item.get('enabled'): - path = Path(item.get('installPath', '')) / 'scripts' / 'tigerkit_state.py' - if path.is_file() and str(path) not in seen: - candidates.append(path) - seen.add(str(path)) -for path in sorted(Path.home().glob('.claude/plugins/cache/tiger-kit/tk/*/scripts/tigerkit_state.py'), key=version_key_path, reverse=True): - if str(path) not in seen: - candidates.append(path) - seen.add(str(path)) -if not candidates: - raise SystemExit('TigerKit helper not found in installed plugin cache. Run `claude plugin marketplace update tiger-kit` and reinstall/update `tk@tiger-kit`.') -print(candidates[0]) -PY -})" -python3 "$TIGERKIT_STATE_SCRIPT" write-gap --repo-root "$PWD" <<'EOF' +TIGERKIT_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$({ claude plugin list --json | python3 -c 'import json,sys; print(next(item["installPath"] for item in json.load(sys.stdin) if item.get("id") == "tk@tiger-kit" and item.get("enabled")))'; })}" +python3 "$TIGERKIT_PLUGIN_ROOT/scripts/tigerkit_state.py" write-gap --repo-root "$PWD" <<'EOF' EOF ``` diff --git a/commands/grill.md b/commands/grill.md index 9de59fd..ecda6d8 100644 --- a/commands/grill.md +++ b/commands/grill.md @@ -1,5 +1,5 @@ --- -description: 계획, 설계, RFC, 개선안을 수렴형 질문으로 압박 검증합니다. +description: 계획 허점을 압박 검증합니다. argument-hint: '"" [--target ] [--print-checklist]' --- @@ -11,7 +11,7 @@ argument-hint: '"" [--target ] [--print-checklist]' 사용자가 질문의 답을 모른다고 직접 말하면, 질문 자체는 유지하되 막힘을 줄이기 위해 브레인스토밍 기반 후보를 최대 3개까지 제안할 수 있습니다. -canonical skill: +related wrapper skill: ```text skills/grill/SKILL.md @@ -19,6 +19,7 @@ skills/grill/SKILL.md ## Core boundary +- 공통 command boundary는 `.tigerkit/docs/usage.md`의 `Shared command boundaries`를 따릅니다. - preview-only - source 수정 금지 - 자동 문서 수정 금지 @@ -70,10 +71,3 @@ Grill 진행중 | Grill 중단 | Grill 요약 ▶️ Next step: - ``` - -## Non-goals - -- interview for its own sake -- source write -- approval을 가장한 강압적 endless questioning -- 이미 코드베이스에서 확인 가능한 사실 재질문 diff --git a/commands/grooming.md b/commands/grooming.md index d0ffdb3..c7f2e08 100644 --- a/commands/grooming.md +++ b/commands/grooming.md @@ -1,5 +1,5 @@ --- -description: guidance 파일을 평가하고, 승인된 user-global 변경만 직접 반영하며 나머지는 suggestion-only로 남깁니다. +description: guidance 정비안을 점검합니다. argument-hint: '"[scope]" [--scope ] [--apply=true]' --- @@ -9,7 +9,7 @@ argument-hint: '"[scope]" [--scope ] [--apply=true]' 목표: `/tk:grooming`은 guidance 파일을 바로 정리했다고 주장하지 않고, 먼저 report-only로 평가한 뒤 승인된 범위의 user-global guidance만 직접 apply하고 나머지는 suggestion-only로 남기는 정비 surface입니다. -canonical skill: +related wrapper skill: ```text skills/grooming/SKILL.md @@ -17,6 +17,7 @@ skills/grooming/SKILL.md ## Core boundary +- 공통 command boundary는 `.tigerkit/docs/usage.md`의 `Shared command boundaries`를 따릅니다. - default report-only - no-publish 기본 - 승인 전 write 금지 @@ -24,6 +25,8 @@ skills/grooming/SKILL.md - repo shared / repo local guidance는 suggestion-only - user-global direct apply와 repo suggestion-only가 한 변경 안에 섞이면 전체를 preview-only로 남김 - 원본 파일을 직접 읽고, 세션 주입 사본을 source of truth로 쓰지 않음 +- 신규 guidance를 임의 추가하지 않음 +- reflect/learn 역할 대체 금지 ## Scope contract @@ -98,11 +101,3 @@ Grooming 리포트 | Grooming 적용 완료 | Grooming 중단 ▶️ Next step: - ``` - -## Non-goals - -- repo source code 수정 -- repo guidance direct apply -- 신규 guidance를 임의 추가하는 것 -- reflect/learn 역할 대체 -- 승인 없는 광범위 rewrite diff --git a/commands/handoff.md b/commands/handoff.md index c864402..ed7a3c3 100644 --- a/commands/handoff.md +++ b/commands/handoff.md @@ -1,5 +1,5 @@ --- -description: 다음 세션이나 다른 에이전트가 바로 이어받을 수 있는 handoff를 만듭니다. +description: current-first handoff를 만듭니다. argument-hint: '"" [--output ] [--print-only]' --- @@ -9,7 +9,7 @@ argument-hint: '"" [--output ] [--print-only]' 목표: `/tk:handoff`는 다음 세션이나 다른 에이전트가 바로 이어서 실행할 수 있는 handoff artifact를 만드는 surface입니다. -canonical skill: +related wrapper skill: ```text skills/handoff/SKILL.md @@ -17,6 +17,7 @@ skills/handoff/SKILL.md ## Core boundary +- 공통 command boundary는 `.tigerkit/docs/usage.md`의 `Shared command boundaries`를 따릅니다. - 기본은 repo-scoped `~/.tigerkit` root 아래 worktree-scoped current-first write - 대화 전문 복붙 금지 - 이미 있는 PRD/ADR/issue/diff는 경로/링크 참조 우선 @@ -72,9 +73,3 @@ Handoff 완료 | Handoff 미리보기 | Handoff 중단 ▶️ Next step: - ``` - -## Non-goals - -- chat log dump -- vague diary text -- 이미 artifact에 있는 내용을 장문 복붙 diff --git a/commands/handon.md b/commands/handon.md index 69bb7eb..6149869 100644 --- a/commands/handon.md +++ b/commands/handon.md @@ -1,5 +1,5 @@ --- -description: 현재 worktree의 최신 handoff draft를 다시 읽습니다. +description: current-first handoff를 다시 읽습니다. argument-hint: '[""] [--path-only]' --- @@ -9,7 +9,7 @@ argument-hint: '[""] [--path-only]' 목표: `/tk:handon`은 `/tk:handoff`가 남긴 current-first handoff artifact를 현재 repo/worktree 기준으로 다시 여는 read-only surface입니다. 저장된 handoff 파일을 source of truth로 읽고, 필요하면 focus에 맞춰 짧게 요약하거나 경로만 확인해줍니다. -canonical skill: +related wrapper skill: ```text skills/handon/SKILL.md @@ -21,6 +21,7 @@ handon = current repo/worktree handoff current.md -> read saved artifact -> resu ## Core boundary +- 공통 command boundary는 `.tigerkit/docs/usage.md`의 `Shared command boundaries`를 따릅니다. - read-only 입니다. - 기본은 현재 repo/worktree의 `handoffs/current.md`만 읽습니다. - source of truth는 저장된 handoff artifact이며, chat memory나 추측으로 빈칸을 메우지 않습니다. @@ -37,8 +38,16 @@ handon = current repo/worktree handoff current.md -> read saved artifact -> resu helper 예시: +enabled `tk@tiger-kit` install이 오래되어 `draft-paths`가 `invalid choice`로 실패하면 먼저 marketplace/plugin을 업데이트하거나, matching checkout/install root를 `CLAUDE_PLUGIN_ROOT`로 지정합니다. + +```bash +claude plugin marketplace update tiger-kit +claude plugin install tk@tiger-kit --scope user +``` + ```bash -python3 "$TIGERKIT_STATE_SCRIPT" draft-paths --repo-root "$PWD" --kind handoffs +TIGERKIT_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$({ claude plugin list --json | python3 -c 'import json,sys; print(next(item["installPath"] for item in json.load(sys.stdin) if item.get("id") == "tk@tiger-kit" and item.get("enabled")))'; })}" +python3 "$TIGERKIT_PLUGIN_ROOT/scripts/tigerkit_state.py" draft-paths --repo-root "$PWD" --kind handoffs ``` ## Output contract @@ -73,10 +82,3 @@ Handon 읽기 완료 | Handon 경로 확인 | Handon 없음 /tk:handon "남은 작업만 짧게" /tk:handon --path-only ``` - -## Non-goals - -- 새 handoff 생성 -- 기존 handoff 수정 -- current handoff가 없을 때 예전 draft를 임의 선택 -- chat log를 source of truth로 대체 diff --git a/commands/learn.md b/commands/learn.md index 336fa87..63ca275 100644 --- a/commands/learn.md +++ b/commands/learn.md @@ -1,5 +1,5 @@ --- -description: 경로, 문서, 대화, reflect candidate에서 reusable skill을 직접 만듭니다. +description: reusable skill을 만듭니다. argument-hint: '"" [--name ] [--apply=false|true] [--from-reflect ] [--dry-run]' --- @@ -9,7 +9,7 @@ argument-hint: '"" [--name ] [--apply=false|true] [--fr 목표: `/tk:learn`은 path, directory, URL, 현재 대화, pasted notes, 또는 `/tk:reflect`가 남긴 `candidate_id`를 source로 받아 reusable skill을 직접 만드는 source-to-skill surface입니다. write boundary는 `skill only`이며, repo-local guidance, user-global guidance, hook, command, agent source를 라우팅하지 않습니다. -canonical skill: +related wrapper skill: ```text skills/learn/SKILL.md @@ -21,6 +21,7 @@ learn = explicit source or reflect candidate -> gather evidence -> draft skill - ## Core boundary +- 공통 command boundary는 `.tigerkit/docs/usage.md`의 `Shared command boundaries`를 따릅니다. - `/tk:learn`은 `skill only` surface입니다. - `repo-local`, `repo-shared`, `user-global`, `hook`, `command`, `agent` direct write를 하지 않습니다. - source code, plugin manifest, command source를 수정하지 않습니다. @@ -45,8 +46,16 @@ learn = explicit source or reflect candidate -> gather evidence -> draft skill - reflect candidate helper 예시: +enabled `tk@tiger-kit` install이 오래되어 `read-reflect-candidate`가 `invalid choice`로 실패하면 먼저 marketplace/plugin을 업데이트하거나, matching checkout/install root를 `CLAUDE_PLUGIN_ROOT`로 지정합니다. + +```bash +claude plugin marketplace update tiger-kit +claude plugin install tk@tiger-kit --scope user +``` + ```bash -python3 "$TIGERKIT_STATE_SCRIPT" read-reflect-candidate --repo-root "$PWD" --candidate-id R1 +TIGERKIT_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$({ claude plugin list --json | python3 -c 'import json,sys; print(next(item["installPath"] for item in json.load(sys.stdin) if item.get("id") == "tk@tiger-kit" and item.get("enabled")))'; })}" +python3 "$TIGERKIT_PLUGIN_ROOT/scripts/tigerkit_state.py" read-reflect-candidate --repo-root "$PWD" --candidate-id R1 ``` ## Default target @@ -96,11 +105,3 @@ Learn 완료 | Learn 미리보기 | Learn 중단 - `--dry-run`: preview-only - `--name `: suggested/confirmed 이름 입력 - 이름이 확정되지 않았거나 preview-only면 `Confirmed name`/`Created path` section을 생략하고 `Write result`에 짧게 이유만 남깁니다. - -## Non-goals - -- repo-local guidance 반영 -- user-global guidance 반영 -- hook/command/agent 생성 -- source code 수정 -- publish/merge/release diff --git a/commands/merge-conflict.md b/commands/merge-conflict.md index f2ece9b..1938acf 100644 --- a/commands/merge-conflict.md +++ b/commands/merge-conflict.md @@ -1,5 +1,5 @@ --- -description: merge 또는 rebase conflict를 ours/theirs 의도 기준으로 해결합니다. +description: merge/rebase conflict를 정리합니다. argument-hint: '[--target ] [--print-plan]' --- @@ -9,7 +9,7 @@ argument-hint: '[--target ] [--print-plan]' 목표: `/tk:merge-conflict`는 merge/rebase conflict를 단순 ours/theirs 선택이 아니라 양쪽 intent 기준으로 정리하는 surface입니다. -canonical skill: +related wrapper skill: ```text skills/merge-conflict/SKILL.md @@ -17,10 +17,13 @@ skills/merge-conflict/SKILL.md ## Core boundary +- 공통 command boundary는 `.tigerkit/docs/usage.md`의 `Shared command boundaries`를 따릅니다. - 현재 merge/rebase 상태 확인 필수 - 충돌 파일과 hunk 목록화 필수 - ours/theirs 의도 추적 필수 - 가능한 검증 명령 실행 필수 +- unrelated refactor 금지 +- formatting-only churn 금지 - `git reset --hard` 금지 - `git clean` 금지 - force push 금지 @@ -50,9 +53,3 @@ Merge conflict 분석 | Merge conflict 해결 | Merge conflict 중단 ▶️ Next step: - ``` - -## Non-goals - -- unrelated refactor -- formatting-only churn -- conflict 상태를 숨기고 success 선언 diff --git a/commands/prototype.md b/commands/prototype.md index c335129..874b19d 100644 --- a/commands/prototype.md +++ b/commands/prototype.md @@ -1,5 +1,5 @@ --- -description: UI 또는 logic/state 질문에 대해 throwaway prototype을 빠르게 만들어 검증합니다. +description: throwaway prototype으로 검증합니다. argument-hint: '"" [--ui|--logic] [--target ] [--print-plan]' --- @@ -9,7 +9,7 @@ argument-hint: '"" [--ui|--logic] [--target ] [--print-plan]' 목표: `/tk:prototype`은 UI 또는 logic/state 가설을 production finish 전에 throwaway prototype으로 빠르게 검증하는 surface입니다. -canonical skill: +related wrapper skill: ```text skills/prototype/SKILL.md @@ -17,7 +17,9 @@ skills/prototype/SKILL.md ## Core boundary +- 공통 command boundary는 `.tigerkit/docs/usage.md`의 `Shared command boundaries`를 따릅니다. - 기본 mode는 no-commit +- commit/push/merge 금지 - prototype은 throwaway 전제를 명시 - production 추상화/에러처리/범용화 과투자 금지 - prototype 성공을 merge-ready로 보고하지 않음 @@ -52,9 +54,3 @@ Prototype 준비 | Prototype 완료 | Prototype 중단 ▶️ Next production step: - ``` - -## Non-goals - -- production-ready finish claim -- no-op 문서화만 하고 prototype 미생성 -- commit/push/merge diff --git a/commands/reflect.md b/commands/reflect.md index 66e92b6..34aa691 100644 --- a/commands/reflect.md +++ b/commands/reflect.md @@ -1,5 +1,5 @@ --- -description: 세션 결과에서 재사용 가능한 learning을 분류하고 repo-local/user-global guidance 기본 반영 또는 명시적 skill materialize를 수행할 수 있습니다. +description: learning을 분류합니다. argument-hint: '"[candidate_id|scope]" [--apply=false|true] [--target ] [--desc ""] [--dry-run]' --- @@ -9,7 +9,7 @@ argument-hint: '"[candidate_id|scope]" [--apply=false|true] [--target " [--context ] [--target ] [--print-checklist]' --- @@ -9,7 +9,7 @@ argument-hint: '"" [--context ] [--target ] [--print-chec 목표: `/tk:route`는 지금 작업을 어떤 방식으로 구현할지 얇게 정리하는 decision / brainstorming surface입니다. direct, subagent-driven, goal-driven 같은 route를 비교하고, 가장 무난한 1안과 바로 시작할 첫 스텝을 제안합니다. -canonical skill: +related wrapper skill: ```text skills/route/SKILL.md @@ -21,6 +21,7 @@ route = explicit task + current constraints -> compare implementation routes -> ## Core boundary +- 공통 command boundary는 `.tigerkit/docs/usage.md`의 `Shared command boundaries`를 따릅니다. - 이 command는 source tree, `~/.tigerkit` artifact state, Git branch/index/stash/commit을 변경하지 않습니다. - package-manager script, build, test, lint, typecheck, network request를 실행하지 않습니다. - sealed workflow, spec artifact, approval receipt를 만들지 않습니다. @@ -107,11 +108,3 @@ repo-local helper surface가 보이면 `read-gap-packet`으로 same repo/scope p /tk:route "이거 direct로 할지 subagent-driven으로 할지 정리해줘" /tk:route "멀티파일 리팩터인데 /goal로 푸는 게 나은지 봐줘" ``` - -## Non-goals - -- source 수정 -- spec 생성 -- runtime execute -- 승인 우회 조언 -- command 밖에서만 통과할 수도 있다는 식의 편법 유도 diff --git a/commands/to-issues.md b/commands/to-issues.md index 476f694..a30755e 100644 --- a/commands/to-issues.md +++ b/commands/to-issues.md @@ -1,5 +1,5 @@ --- -description: plan이나 PRD를 independently grabbable vertical-slice issue draft로 분해합니다. +description: issue draft로 쪼갭니다. argument-hint: '"" [--output ] [--print-only] [--publish]' --- @@ -9,7 +9,7 @@ argument-hint: '"" [--output ] [--print-only] [--publish]' 목표: `/tk:to-issues`는 plan/PRD를 independently grabbable vertical-slice issue draft로 분해하는 surface입니다. -canonical skill: +related wrapper skill: ```text skills/to-issues/SKILL.md @@ -17,6 +17,7 @@ skills/to-issues/SKILL.md ## Core boundary +- 공통 command boundary는 `.tigerkit/docs/usage.md`의 `Shared command boundaries`를 따릅니다. - default draft-only - no-publish 기본 - vertical slice only @@ -61,9 +62,3 @@ To-Issues 완료 | To-Issues 미리보기 | To-Issues 중단 ▶️ Next step: - ``` - -## Non-goals - -- publish 기본값 -- layer별 ticket 폭증 -- 독립 실행 불가능한 issue 쪼개기 diff --git a/commands/to-prd.md b/commands/to-prd.md index 2188e8c..dd5d568 100644 --- a/commands/to-prd.md +++ b/commands/to-prd.md @@ -1,5 +1,5 @@ --- -description: 현재 대화나 요구사항을 draft-only PRD로 정리합니다. +description: PRD draft로 정리합니다. argument-hint: '"" [--output ] [--print-only] [--publish]' --- @@ -9,7 +9,7 @@ argument-hint: '"" [--output ] [--print-only] [--publish]' 목표: `/tk:to-prd`는 현재 대화나 요구사항을 implementation 전에 읽기 쉬운 PRD draft로 정리하는 surface입니다. -canonical skill: +related wrapper skill: ```text skills/to-prd/SKILL.md @@ -17,6 +17,7 @@ skills/to-prd/SKILL.md ## Core boundary +- 공통 command boundary는 `.tigerkit/docs/usage.md`의 `Shared command boundaries`를 따릅니다. - default draft-only - no-publish 기본 - approval 전 외부 tracker/doc system 반영 금지 @@ -55,9 +56,3 @@ To-PRD 완료 | To-PRD 미리보기 | To-PRD 중단 ▶️ Next step: - ``` - -## Non-goals - -- publish 기본값 -- 구현 완료 보고 -- acceptance criteria 없는 vague spec diff --git a/scripts/check-command-surface-drift.py b/scripts/check-command-surface-drift.py index 435d5e0..2c4f689 100644 --- a/scripts/check-command-surface-drift.py +++ b/scripts/check-command-surface-drift.py @@ -81,6 +81,68 @@ "to-issues": ROOT / "commands" / "to-issues.md", } +DESCRIPTION_BUDGET = 932 + +INLINE_BOOTSTRAP_TOKENS = [ + "python3 - <<'PY'", + ".claude/plugins/cache/tiger-kit/tk", + 'TIGERKIT_STATE_SCRIPT="$({', +] + +RELATIVE_HELPER_EXAMPLES = [ + "python3 scripts/resolve_tigerkit_state.py", + "python3 scripts/tigerkit_state.py", +] + +INSTALLED_HELPER_DOC_TARGETS = [ + ROOT / "commands" / "gap.md", + ROOT / "commands" / "handon.md", + ROOT / "commands" / "learn.md", +] + +INSTALLED_HELPER_UPDATE_GUARD = "claude plugin marketplace update tiger-kit" + +NO_NON_GOALS_COMMANDS = [ + ROOT / "commands" / "arch-review.md", + ROOT / "commands" / "browser-verify.md", + ROOT / "commands" / "grill.md", + ROOT / "commands" / "grooming.md", + ROOT / "commands" / "handoff.md", + ROOT / "commands" / "handon.md", + ROOT / "commands" / "learn.md", + ROOT / "commands" / "merge-conflict.md", + ROOT / "commands" / "prototype.md", + ROOT / "commands" / "route.md", + ROOT / "commands" / "to-issues.md", + ROOT / "commands" / "to-prd.md", +] + +SHARED_BOUNDARY_MARKER = "Shared command boundaries" + +REHOMED_BOUNDARY_GUARDS = { + ROOT / "commands" / "prototype.md": ["commit/push/merge 금지"], + ROOT / "commands" / "merge-conflict.md": ["unrelated refactor 금지", "formatting-only churn 금지"], + ROOT / "commands" / "grooming.md": ["신규 guidance를 임의 추가하지 않음", "reflect/learn 역할 대체 금지"], +} + +WRAPPER_SKILL_COMMAND_OWNERS = { + ROOT / "skills" / "arch-review" / "SKILL.md": "commands/arch-review.md", + ROOT / "skills" / "gap" / "SKILL.md": "commands/gap.md", + ROOT / "skills" / "grill" / "SKILL.md": "commands/grill.md", + ROOT / "skills" / "grooming" / "SKILL.md": "commands/grooming.md", + ROOT / "skills" / "handoff" / "SKILL.md": "commands/handoff.md", + ROOT / "skills" / "handon" / "SKILL.md": "commands/handon.md", + ROOT / "skills" / "learn" / "SKILL.md": "commands/learn.md", + ROOT / "skills" / "merge-conflict" / "SKILL.md": "commands/merge-conflict.md", + ROOT / "skills" / "prototype" / "SKILL.md": "commands/prototype.md", + ROOT / "skills" / "reflect" / "SKILL.md": "commands/reflect.md", + ROOT / "skills" / "route" / "SKILL.md": "commands/route.md", + ROOT / "skills" / "to-issues" / "SKILL.md": "commands/to-issues.md", + ROOT / "skills" / "to-prd" / "SKILL.md": "commands/to-prd.md", +} + +WRAPPER_SKILL_TOTAL_BUDGET = 11000 + OUTPUT_SYNC_TARGETS = { "gap": "## `/tk:gap` Output Contract", "route": "## `/tk:route` Output Contract", @@ -137,6 +199,11 @@ def load_json(path: Path) -> dict: raise SystemExit(f"invalid json: {path}: {exc}") from exc +def extract_frontmatter_description(path: Path) -> str: + match = re.search(r"^description:\s*(.*)$", path.read_text(), re.M) + return match.group(1).strip() if match else "" + + def check_plugin_manifest() -> None: plugin = load_json(PLUGIN_PATH) raw_commands_obj: object = plugin.get("commands") @@ -169,6 +236,68 @@ def check_banned_tokens() -> None: fail(f"public surface file {path.relative_to(ROOT)} still exposes banned token {token!r}") +def check_description_budget() -> None: + total = 0 + for path in sorted((ROOT / "commands").glob("*.md")): + total += len(extract_frontmatter_description(path)) + for path in sorted((ROOT / "skills").glob("*/SKILL.md")): + total += len(extract_frontmatter_description(path)) + if total > DESCRIPTION_BUDGET: + fail(f"command+skill description budget exceeded: {total} > {DESCRIPTION_BUDGET}") + + +def check_no_inline_state_bootstrap() -> None: + for path in sorted((ROOT / "commands").glob("*.md")): + text = path.read_text() + for token in INLINE_BOOTSTRAP_TOKENS: + if token in text: + fail(f"{path.relative_to(ROOT)} still embeds inline TigerKit state bootstrap token {token!r}") + + +def check_helper_examples_are_repo_independent() -> None: + for path in INSTALLED_HELPER_DOC_TARGETS: + text = path.read_text() + for token in RELATIVE_HELPER_EXAMPLES: + if token in text: + fail(f"{path.relative_to(ROOT)} still documents repo-local TigerKit helper invocation: {token!r}") + if "claude plugin list --json" not in text: + fail(f"{path.relative_to(ROOT)} missing installed-plugin helper resolution flow") + if INSTALLED_HELPER_UPDATE_GUARD not in text: + fail(f"{path.relative_to(ROOT)} missing stale-installed-plugin update guard") + + +def check_shared_boundary_reference() -> None: + usage_text = USAGE_PATH.read_text() + if SHARED_BOUNDARY_MARKER not in usage_text: + fail(f"{USAGE_PATH.relative_to(ROOT)} missing shared command boundary reference section") + for path in NO_NON_GOALS_COMMANDS: + text = path.read_text() + if "## Non-goals" in text: + fail(f"{path.relative_to(ROOT)} still exposes a Non-goals section after boundary consolidation") + if SHARED_BOUNDARY_MARKER not in text: + fail(f"{path.relative_to(ROOT)} missing shared command boundary reference") + for path, required_lines in REHOMED_BOUNDARY_GUARDS.items(): + text = path.read_text() + for line in required_lines: + if line not in text: + fail(f"{path.relative_to(ROOT)} missing re-homed command-specific boundary: {line!r}") + + +def check_wrapper_skill_thinness() -> None: + total_bytes = 0 + for path, command_owner in WRAPPER_SKILL_COMMAND_OWNERS.items(): + text = path.read_text() + total_bytes += len(text.encode("utf-8")) + if command_owner not in text: + fail(f"{path.relative_to(ROOT)} missing canonical command owner reference {command_owner!r}") + if "얇은 wrapper" not in text: + fail(f"{path.relative_to(ROOT)} missing thin-wrapper marker") + if total_bytes > WRAPPER_SKILL_TOTAL_BUDGET: + fail( + f"wrapper skill byte budget exceeded: {total_bytes} > {WRAPPER_SKILL_TOTAL_BUDGET}" + ) + + def extract_first_fenced_block_after_heading(text: str, heading: str) -> str: lines = text.splitlines() try: @@ -256,6 +385,11 @@ def main() -> int: check_plugin_manifest() check_readme_commands() check_banned_tokens() + check_description_budget() + check_no_inline_state_bootstrap() + check_helper_examples_are_repo_independent() + check_shared_boundary_reference() + check_wrapper_skill_thinness() check_command_output_block_shape() check_output_contract_helper_sync() print("command surface drift ok") diff --git a/skills/arch-review/SKILL.md b/skills/arch-review/SKILL.md index cb23b32..ee69408 100644 --- a/skills/arch-review/SKILL.md +++ b/skills/arch-review/SKILL.md @@ -1,42 +1,19 @@ --- name: arch-review -description: boundary, ownership, coupling, 반복 마찰을 evidence-first로 검토하는 report-only 구조 리뷰입니다. +description: 구조 리뷰 트리거입니다. --- # Arch Review -구조 문제를 바로 갈아엎는 대신, 어떤 경계가 새고 있고 어디서 반복 마찰이 생기는지 evidence-first로 검토하는 skill입니다. +`/tk:arch-review` wrapper skill입니다. 상세 계약, output contract, helper/path semantics의 source of truth는 `commands/arch-review.md`입니다. -## Goal +## Use when -- boundary leak를 찾습니다. -- ownership confusion을 줄일 수 있는 방향을 찾습니다. -- coupling hotspot과 repeated pain을 분리해서 봅니다. -- 큰 rewrite보다 작은 단계적 정리 방향을 제안합니다. +- boundary, ownership, coupling, 반복 마찰을 evidence-first로 검토해야 할 때 +- 자동 리팩터링이 아니라 report-only 구조 판단이 먼저일 때 -## Process +## Wrapper rules -1. 변경이 자주 엮이는 파일/영역을 읽습니다. -2. 경계, 책임, 의존 방향, 반복되는 마찰을 구분합니다. -3. 이미 잘 된 구조와 진짜 hotspot을 분리합니다. -4. 리팩터링을 당장 강행하지 말고 가장 작은 다음 단계부터 제안합니다. -5. 보고할 때는 아래를 구분합니다. - - strengths - - hotspots - - boundary risks - - evidence - - smallest safe next step - -## Boundaries - -- report-only -- 자동 refactor/rename/이동 금지 -- 문서 작성만으로 해결됐다고 주장 금지 -- 취향성 리뷰보다 반복 마찰과 구조적 위험을 우선 - -## Good use cases - -- 같은 수정이 여러 파일에 반복 전파될 때 -- ownership이 흐려서 버그 수정 경로가 자주 흔들릴 때 -- 모듈 경계가 애매해 merge conflict나 coupling이 반복될 때 -- 대공사 전에 어디부터 자를지 판단하고 싶을 때 +- 이 skill은 `commands/arch-review.md`를 대체하지 않고, command intent를 빠르게 잡는 얇은 wrapper입니다. +- artifact path / apply boundary / helper invocation / receipt shape는 `commands/arch-review.md`를 그대로 따릅니다. +- command contract에 이미 있는 절차와 경계를 다시 장문으로 복제하지 않습니다. diff --git a/skills/browser-verify/SKILL.md b/skills/browser-verify/SKILL.md index 3c76c7d..c8eecb3 100644 --- a/skills/browser-verify/SKILL.md +++ b/skills/browser-verify/SKILL.md @@ -1,6 +1,6 @@ --- name: browser-verify -description: 실제 브라우저 runtime에서 computed style / bounding rect / 상호작용 결과를 근거로 시각 회귀와 SoT 대비 동작을 검증합니다. `~/.tigerkit` repo profile을 읽습니다. +description: browser-verify 엔진 트리거입니다. --- # Browser Verify diff --git a/skills/gap/SKILL.md b/skills/gap/SKILL.md index be5da10..1fd5eb7 100644 --- a/skills/gap/SKILL.md +++ b/skills/gap/SKILL.md @@ -1,43 +1,19 @@ --- name: gap -description: SoT와 현재 구현의 차이를 evidence-first로 한 번 분석합니다. +description: SoT gap 분석 트리거입니다. --- # Gap -구현을 시작하기 전에 Source of Truth와 Current Implementation 사이의 핵심 차이를 드러내는 skill입니다. +`/tk:gap` wrapper skill입니다. 상세 계약, output contract, helper/path semantics의 source of truth는 `commands/gap.md`입니다. -## Goal +## Use when -- SoT가 있으면 구현 전에 차이를 먼저 확인합니다. -- missing / mismatch / overbuilt / ambiguous를 구분합니다. -- plan-only evidence를 구현 완료 증거로 착각하지 않게 합니다. +- SoT와 current implementation 차이를 한 번 evidence-first로 비교해야 할 때 +- missing / mismatch / overbuilt / ambiguous를 구현 전에 분리하고 싶을 때 -## Process +## Wrapper rules -1. source ref 목록과 access status를 먼저 고정합니다. -2. SoT에서 확인 가능한 requirement만 뽑습니다. -3. Current evidence를 직접 읽은 파일, 실행 결과, rendered output, diff, generated artifact처럼 evidence type별로 분리합니다. -4. source 우선순위가 불명확하면 조용히 섞지 않고 `ambiguous`로 남깁니다. -5. finding마다 SoT / Current / Evidence / Impact / Priority / Suggested fix를 남깁니다. -6. actionable finding에는 `direct | brainstorm | decision` route를 제안합니다. - -## Gap types - -- `missing`: SoT 요구가 Current에 없음 -- `mismatch`: SoT와 Current가 다름 -- `overbuilt`: SoT 밖 구현이 surface 확장이나 유지비를 만든다 -- `ambiguous`: source conflict, owner decision 부족, evidence 부족 - -## Boundaries - -- workflow 생성 금지 -- autopilot / runner / sealed flow 생성 금지 -- finding이 0개 될 때까지 무한 반복 금지 -- 검증 없는 success 선언 금지 - -## Good use cases - -- PRD 대비 구현 점검 -- spec 대비 branch 상태 점검 -- current main/public surface와 target contract 차이 확인 +- 이 skill은 `commands/gap.md`를 대체하지 않고, command intent를 빠르게 잡는 얇은 wrapper입니다. +- artifact path / apply boundary / helper invocation / receipt shape는 `commands/gap.md`를 그대로 따릅니다. +- command contract에 이미 있는 절차와 경계를 다시 장문으로 복제하지 않습니다. diff --git a/skills/grill/SKILL.md b/skills/grill/SKILL.md index 1ee41ee..9ac4402 100644 --- a/skills/grill/SKILL.md +++ b/skills/grill/SKILL.md @@ -1,49 +1,19 @@ --- name: grill -description: 계획, 설계, RFC, 개선안을 수렴형 질문으로 압박 검증합니다. +description: grill 질문 트리거입니다. --- # Grill -애매한 계획이나 설계를 바로 구현으로 밀지 않고, 빠진 전제와 리스크를 드러내는 skill입니다. +`/tk:grill` wrapper skill입니다. 상세 계약, output contract, helper/path semantics의 source of truth는 `commands/grill.md`입니다. -## Goal +## Use when -- open question을 줄입니다. -- 이미 정한 내용은 다시 묻지 않습니다. -- 코드베이스에서 바로 확인 가능한 것은 직접 확인합니다. -- 구현 전에 `결정사항 / 가정 / 남은 리스크`를 남깁니다. -- 사용자가 답을 모른다고 할 때는 막히지 않도록 후보를 최대 3개까지 제안할 수 있습니다. +- 계획, 설계, RFC를 바로 구현으로 밀기 전에 한 번 압박 검증해야 할 때 +- 질문은 유지하되, 사용자가 모른다고 말했을 때만 후보를 좁혀야 할 때 -## Process +## Wrapper rules -1. 먼저 현재 repo와 관련 파일에서 직접 확인 가능한 사실을 읽습니다. -2. 아직 확인되지 않은 전제만 질문합니다. -3. 질문은 한 번에 하나씩, 짧고 날카롭게 던집니다. -4. 사용자가 답을 모른다고 직접 말하면, 질문은 유지하되 브레인스토밍으로 후보를 최대 3개까지 제안할 수 있습니다. - - 후보는 확정 답이 아니라 선택지/가설로 표현합니다. - - 각 후보에는 짧은 근거나 적용 상황을 붙입니다. - - high-risk owner decision은 후보 제안만으로 확정하지 않습니다. -5. 이미 답한 내용은 반복 질문하지 않습니다. -6. 5회 이상 길어지면 hint를 주고, 가정하고 진행할지 멈출지 제안합니다. -7. 사용자가 `멈춰`, `그만`, `가정하고 가`, `그냥 진행`이라고 하면 즉시 중단합니다. -8. 끝날 때는 아래 세 묶음으로 요약합니다. - - 결정사항 - - 가정 - - 남은 리스크 - -## Boundaries - -- preview-only -- source 수정 금지 -- 자동 문서 수정 금지 -- hard cap 5문항 금지 -- 생각나는 걸 다 묻는 interview mode 금지 -- 후보 제안은 사용자가 모른다고 할 때만 허용하고, 질문 surface를 추측 surface로 바꾸지 않습니다. - -## Good use cases - -- RFC 검토 전 -- 구현 범위가 흐릿할 때 -- plan/PRD가 과하게 낙관적일 때 -- route를 정하기 전 전제 검증이 필요할 때 +- 이 skill은 `commands/grill.md`를 대체하지 않고, command intent를 빠르게 잡는 얇은 wrapper입니다. +- artifact path / apply boundary / helper invocation / receipt shape는 `commands/grill.md`를 그대로 따릅니다. +- command contract에 이미 있는 절차와 경계를 다시 장문으로 복제하지 않습니다. diff --git a/skills/grooming/SKILL.md b/skills/grooming/SKILL.md index 82b2275..f0956dc 100644 --- a/skills/grooming/SKILL.md +++ b/skills/grooming/SKILL.md @@ -1,85 +1,19 @@ --- name: grooming -description: guidance 파일을 평가하고, 승인된 user-global 변경만 직접 반영하며 나머지는 suggestion-only로 남깁니다. +description: guidance 정비 트리거입니다. --- # Grooming -guidance 파일(`CLAUDE.md`, `.claude/rules/**`)이 쌓이면서 생기는 오염, 충돌, 죽은 참조, 사실 부정확을 평가하고 정비하는 skill입니다. +`/tk:grooming` wrapper skill입니다. 상세 계약, output contract, helper/path semantics의 source of truth는 `commands/grooming.md`입니다. -## Goal +## Use when -- guidance drift를 report-first로 드러냅니다. -- 승인된 범위만 apply합니다. -- user-global만 direct apply하고 repo 쪽은 suggestion-only로 유지합니다. -- 적용 후에는 readback / re-grep 같은 검증 근거를 남깁니다. +- guidance drift를 report-first로 평가하고 싶을 때 +- user-global만 direct apply하고 repo 쪽은 suggestion-only로 남겨야 할 때 -## Scope +## Wrapper rules -지원 scope는 `user | repo | all`입니다. - -- `user`: `~/.claude/CLAUDE.md`, `~/.claude/rules//CLAUDE.md` -- `repo`: `/CLAUDE.md`, `/CLAUDE.local.md`, `/.claude/rules/**` -- `all`: user + 현재 repo에서 실행 중이면 repo까지 포함 - -기본값은 `user`입니다. - -## Process - -### Phase 1: 평가 (report-only 기본) - -1. 원본 파일을 직접 읽습니다. -2. 아래 문제 클래스를 탐지합니다. - - 위치 오염 - - 자기모순 - - 죽은 참조 - - 실효성 없는 룰 - - 사실 부정확 - - 방어적 반복 - - 추가 제안 후보 -3. 결론 / 근거 / 후속 액션 형태로 보고합니다. -4. 승인 전에는 write하지 않습니다. - -### Phase 2: 승인 후 apply - -1. direct apply 후보와 suggestion-only 후보를 분리합니다. -2. direct apply는 `user-global` exact target이 확정된 변경만 허용합니다. -3. repo shared / repo local guidance는 항상 suggestion-only입니다. -4. user-global direct apply와 repo suggestion-only가 한 변경 안에 섞이면 partial apply를 하지 않고 preview-only로 남깁니다. -5. apply 뒤에는 readback 또는 re-grep로 결과를 검증합니다. - -## Direct-apply boundary - -직접 쓸 수 있는 대상은 user-global guidance뿐입니다. - -```text -~/.claude/CLAUDE.md -~/.claude/rules//CLAUDE.md -``` - -원칙: -- exact target이 확정되지 않으면 direct apply하지 않습니다. -- repo의 `CLAUDE.md`, `CLAUDE.local.md`, `.claude/rules/**`는 전부 suggestion-only입니다. -- mixed-scope change는 preview-only입니다. - -## Protected exclusions - -기본 보호 대상: -- 역사 기록물: branch spec snapshot, `*.original.md`, transcript/history -- 서드파티 관리 블록: `CODEGRAPH_START`, `vowline:start` 같은 marker block -- TigerKit 관리 섹션: 죽은 참조 제거 등 최소 수정만 허용 -- import(`@...`) 및 plugin 주입 블록: 명시 요청이 없으면 범위 밖 - -## Role split - -- grooming: 기존 guidance의 이동·병합·교정·삭제·죽은 참조 정리 제안 / 제한된 apply -- reflect: 세션 결과에서 durable learning 분류 -- learn: reusable skill 생성 - -새 guidance 후보는 grooming이 직접 추가하지 않고 reflect/learn으로 넘깁니다. - -## Verification - -- report-only면 preview-only 사유가 분명해야 합니다. -- user-global apply면 exact target path와 readback 근거가 남아야 합니다. -- repo suggestion-only면 suggestion 대상과 보호 대상 제외 이유가 남아야 합니다. +- 이 skill은 `commands/grooming.md`를 대체하지 않고, command intent를 빠르게 잡는 얇은 wrapper입니다. +- artifact path / apply boundary / helper invocation / receipt shape는 `commands/grooming.md`를 그대로 따릅니다. +- command contract에 이미 있는 절차와 경계를 다시 장문으로 복제하지 않습니다. diff --git a/skills/handoff/SKILL.md b/skills/handoff/SKILL.md index 202dbba..c7a0fe3 100644 --- a/skills/handoff/SKILL.md +++ b/skills/handoff/SKILL.md @@ -1,65 +1,19 @@ --- name: handoff -description: 다음 세션이나 다른 에이전트가 바로 이어받을 수 있는 handoff를 만듭니다. +description: handoff 생성 트리거입니다. --- # Handoff -세션 기록을 늘어놓는 대신, 다음 실행자가 바로 이어서 움직일 수 있는 handoff를 만드는 skill입니다. +`/tk:handoff` wrapper skill입니다. 상세 계약, output contract, helper/path semantics의 source of truth는 `commands/handoff.md`입니다. -## Goal +## Use when -- 다음 사람이나 다음 세션이 맥락 복구에 시간을 쓰지 않게 합니다. -- 이미 있는 artifact는 복붙 대신 경로로 참조합니다. -- 남은 작업과 리스크를 실행 가능한 형태로 남깁니다. +- 다음 세션이나 다른 에이전트가 바로 이어서 움직일 handoff를 남겨야 할 때 +- current-first handoff artifact에 goal / state / risks를 정리해야 할 때 -## Required sections +## Wrapper rules -아래 항목은 빠지면 안 됩니다. - -- Goal -- Current state -- Decisions made -- Changed files -- Commands run -- Verification status -- Remaining tasks -- Open questions -- Risks -- Suggested next skills/commands -- Do-not-repeat context - -## Process - -1. 현재 작업 목표를 한 문장으로 고정합니다. -2. 현재 branch/state/핵심 파일을 적습니다. -3. 뒤집히면 안 되는 결정을 분리해서 적습니다. -4. 실제로 바뀐 파일과 실행한 명령만 적습니다. -5. 검증 완료/미완료를 숨기지 않고 분리합니다. -6. 남은 작업은 다음 실행자가 바로 시작할 순서로 적습니다. -7. 이미 있는 PRD/ADR/issue/diff는 경로 또는 링크로 참조합니다. - -## Default artifact target - -```text -~/.tigerkit/repos//worktrees//handoffs/current.md -``` - -`repo-key`와 `worktree-key`는 `scripts/tigerkit_state.py` helper가 계산합니다. - -같은 current handoff를 다시 열 때는 `/tk:handon`을 사용합니다. - -## Boundaries - -- repo-scoped `~/.tigerkit` root 아래 worktree-scoped current-first write 기본 -- 대화 전문 복붙 금지 -- 감상문 금지 -- 이미 문서화된 내용을 중복 장문 서술 금지 -- unverifed success를 handoff에 넣지 않음 - -## Good use cases - -- 세션 마감 전 상태 인계 -- 다른 agent로 작업 넘길 때 -- 긴 구현 작업 중간 checkpoint -- 실패/보류 상태를 정확히 넘겨야 할 때 +- 이 skill은 `commands/handoff.md`를 대체하지 않고, command intent를 빠르게 잡는 얇은 wrapper입니다. +- artifact path / apply boundary / helper invocation / receipt shape는 `commands/handoff.md`를 그대로 따릅니다. +- command contract에 이미 있는 절차와 경계를 다시 장문으로 복제하지 않습니다. diff --git a/skills/handon/SKILL.md b/skills/handon/SKILL.md index f04996d..4478b46 100644 --- a/skills/handon/SKILL.md +++ b/skills/handon/SKILL.md @@ -1,44 +1,19 @@ --- name: handon -description: 현재 repo/worktree의 최신 handoff draft를 다시 읽습니다. +description: handoff 재열기 트리거입니다. --- # Handon -`/tk:handoff`가 남긴 current-first handoff artifact를 다시 열어 다음 작업을 바로 이어가기 위한 read-only skill입니다. +`/tk:handon` wrapper skill입니다. 상세 계약, output contract, helper/path semantics의 source of truth는 `commands/handon.md`입니다. -## Goal +## Use when -- 현재 repo/worktree의 최신 handoff를 source of truth로 읽습니다. -- handoff가 있으면 남은 작업과 리스크를 빠르게 복구합니다. -- handoff가 없으면 expected path를 정확히 알려주고 추측하지 않습니다. +- 현재 repo/worktree의 saved handoff를 다시 열어 맥락을 빠르게 복구해야 할 때 +- current handoff artifact를 source of truth로 읽고 싶은 때 -## Default source path +## Wrapper rules -```text -~/.tigerkit/repos//worktrees//handoffs/current.md -``` - -`repo-key`와 `worktree-key`는 `scripts/tigerkit_state.py draft-paths --kind handoffs` helper가 계산합니다. - -## Process - -1. 현재 repo/worktree 기준 handoff 경로를 계산합니다. -2. `current.md`가 있으면 그 파일을 source of truth로 읽습니다. -3. 사용자가 focus를 줬으면 그 범위만 더 짧게 정리합니다. -4. handoff가 없으면 missing path를 숨기지 않고 그대로 말합니다. -5. 필요한 첫 행동을 한 줄로 남깁니다. - -## Boundaries - -- read-only 입니다. -- handoff를 regenerate, overwrite, append 하지 않습니다. -- chat memory나 추측으로 빠진 section을 보완하지 않습니다. -- 기본은 current repo/worktree handoff 하나만 읽습니다. - -## Good use cases - -- `/clear` 뒤 직전 handoff 다시 열기 -- 다른 agent가 남긴 current handoff 빠르게 복구하기 -- 남은 작업 / 리스크 / next step만 짧게 다시 보기 -- handoff 파일 path만 확인하기 +- 이 skill은 `commands/handon.md`를 대체하지 않고, command intent를 빠르게 잡는 얇은 wrapper입니다. +- artifact path / apply boundary / helper invocation / receipt shape는 `commands/handon.md`를 그대로 따릅니다. +- command contract에 이미 있는 절차와 경계를 다시 장문으로 복제하지 않습니다. diff --git a/skills/learn/SKILL.md b/skills/learn/SKILL.md index b734c21..49b5d2a 100644 --- a/skills/learn/SKILL.md +++ b/skills/learn/SKILL.md @@ -1,35 +1,20 @@ --- name: learn -description: source나 reflect candidate에서 reusable skill을 직접 만듭니다. +description: skill 작성 트리거입니다. --- # Learn -path, URL, notes, 현재 대화, 또는 reflect candidate를 읽고 reusable skill source를 직접 만드는 skill입니다. 분류 라우터가 아니라 source-to-skill surface이며, write boundary는 skill only입니다. repo-local guidance나 user-global guidance는 이 skill의 대상이 아닙니다. +`/tk:learn` wrapper skill입니다. 상세 계약, output contract, helper/path semantics의 source of truth는 `commands/learn.md`입니다. -## Goal +## Use when -- source를 읽어 reusable procedure를 skill source로 굳힙니다. -- reflect가 고른 skill candidate를 실제 skill source로 마무리할 수 있게 합니다. -- preview/apply/name confirmation을 분리해 무리한 write를 막습니다. +- path / URL / 현재 대화 / reflect candidate에서 reusable skill을 만들고 싶을 때 +- preview/apply/name confirmation을 분리한 skill-only write가 필요할 때 +- reflect candidate와 그 ledger를 source of truth로 읽어야 할 때 -## Source modes +## Wrapper rules -- `direct`: path / directory / URL / current conversation / notes -- `reflect-candidate`: same-session + same-ledger `candidate_id` - -## Process - -1. source와 requirement를 먼저 읽습니다. -2. direct source인지 reflect candidate인지 구분합니다. -3. skill only boundary 안에서 draft를 만듭니다. -4. 이름을 제안하고, 확정 전에는 write하지 않습니다. -5. explicit apply일 때만 user skill surface에 생성합니다. - -## Boundaries - -- `skill only` -- repo-local / user-global / hook / command / agent direct write 금지 -- 이름 확정 전 write 금지 -- reflect candidate는 ledger를 source of truth로 읽음 -- source code 수정 금지 +- 이 skill은 `commands/learn.md`를 대체하지 않고, command intent를 빠르게 잡는 얇은 wrapper입니다. +- artifact path / apply boundary / helper invocation / receipt shape는 `commands/learn.md`를 그대로 따릅니다. +- command contract에 이미 있는 절차와 경계를 다시 장문으로 복제하지 않습니다. diff --git a/skills/merge-conflict/SKILL.md b/skills/merge-conflict/SKILL.md index 8cbeaf1..a33fcd8 100644 --- a/skills/merge-conflict/SKILL.md +++ b/skills/merge-conflict/SKILL.md @@ -1,39 +1,19 @@ --- name: merge-conflict -description: merge 또는 rebase conflict를 ours/theirs 의도 기준으로 해결합니다. +description: conflict 해결 트리거입니다. --- # Merge Conflict -merge/rebase conflict를 단순 문자열 선택이 아니라 양쪽 intent 기준으로 정리하는 skill입니다. +`/tk:merge-conflict` wrapper skill입니다. 상세 계약, output contract, helper/path semantics의 source of truth는 `commands/merge-conflict.md`입니다. -## Goal +## Use when -- conflict 상태를 먼저 정확히 파악합니다. -- hunk마다 어느 쪽 intent가 살아야 하는지 설명할 수 있게 합니다. -- 가능한 검증을 돌린 뒤 마무리합니다. +- merge/rebase conflict를 ours/theirs intent 기준으로 정리해야 할 때 +- 단순 문자열 선택이 아니라 conflict-specific 검증까지 보고해야 할 때 -## Process +## Wrapper rules -1. 현재 merge/rebase 상태를 확인합니다. -2. 충돌 파일과 hunk를 목록화합니다. -3. ours/theirs가 각각 무엇을 바꾸려던 건지 주변 코드와 최근 변경으로 추적합니다. -4. hunk별 해결 방안을 정합니다. -5. 필요하면 최소 추가 수정을 해서 일관성을 맞춥니다. -6. 가능한 typecheck/test/lint를 실행합니다. -7. merge/rebase 완료 또는 다음 수동 조치를 보고합니다. - -## Boundaries - -- `git reset --hard` 금지 -- `git clean` 금지 -- force push 금지 -- 의도 확인 없는 대규모 삭제 금지 -- conflict 해결 없이 포매팅/리팩터링으로 범위 확대 금지 - -## Good use cases - -- feature branch merge conflict -- rebase conflict -- generated file과 source file이 엮인 충돌 -- 양쪽 다 의미 있는 변경이 들어와 단순 ours/theirs 선택이 위험할 때 +- 이 skill은 `commands/merge-conflict.md`를 대체하지 않고, command intent를 빠르게 잡는 얇은 wrapper입니다. +- artifact path / apply boundary / helper invocation / receipt shape는 `commands/merge-conflict.md`를 그대로 따릅니다. +- command contract에 이미 있는 절차와 경계를 다시 장문으로 복제하지 않습니다. diff --git a/skills/prototype/SKILL.md b/skills/prototype/SKILL.md index bd1eb0b..623daba 100644 --- a/skills/prototype/SKILL.md +++ b/skills/prototype/SKILL.md @@ -1,45 +1,19 @@ --- name: prototype -description: UI 또는 logic/state 질문에 대해 throwaway prototype을 빠르게 만들어 검증합니다. +description: prototype 검증 트리거입니다. --- # Prototype -검증이 목적이지 production finish가 목적이 아닌 prototype용 skill입니다. +`/tk:prototype` wrapper skill입니다. 상세 계약, output contract, helper/path semantics의 source of truth는 `commands/prototype.md`입니다. -## Goal +## Use when -- UI 방향이나 state/logic 가설을 빨리 확인합니다. -- production merge 전에 버릴 수 있는 실험 결과를 만듭니다. -- 무엇이 fake인지, 무엇이 실제 연결인지 분리합니다. +- UI 또는 logic/state 가설을 throwaway prototype으로 빠르게 검증해야 할 때 +- 무엇이 fake이고 무엇이 실제 연결인지 분리해서 보고해야 할 때 -## Modes +## Wrapper rules -- `ui`: 레이아웃, interaction, visual flow 확인 -- `logic`: state, branching, reducer, parser, adapter 같은 핵심 로직 확인 - -## Process - -1. prototype question을 한 줄로 다시 적습니다. -2. `ui`인지 `logic`인지 먼저 고릅니다. -3. 최소 파일과 최소 코드만 만듭니다. -4. production 추상화, error handling, config generalization에 과투자하지 않습니다. -5. prototype임을 파일명/경로/설명에서 드러냅니다. -6. 끝날 때 아래를 구분해서 보고합니다. - - 확인된 것 - - 아직 fake인 것 - - production에 옮길 때 필요한 다음 단계 - -## Boundaries - -- no-commit 기본 -- throwaway 전제 -- 테스트/타입/아키텍처를 production 수준으로 다듬는 데 과투자 금지 -- prototype 성공을 곧 merge-ready로 보고하지 않음 - -## Good use cases - -- 모달/폼/플로우 UI 검증 -- reducer/state machine 방향 검증 -- adapter shape 실험 -- 특정 구현 방향이 먹히는지 빨리 확인할 때 +- 이 skill은 `commands/prototype.md`를 대체하지 않고, command intent를 빠르게 잡는 얇은 wrapper입니다. +- artifact path / apply boundary / helper invocation / receipt shape는 `commands/prototype.md`를 그대로 따릅니다. +- command contract에 이미 있는 절차와 경계를 다시 장문으로 복제하지 않습니다. diff --git a/skills/reflect/SKILL.md b/skills/reflect/SKILL.md index 121d43e..cd61911 100644 --- a/skills/reflect/SKILL.md +++ b/skills/reflect/SKILL.md @@ -1,65 +1,20 @@ --- name: reflect -description: 세션 결과와 피드백에서 재사용 가능한 learning을 뽑아 canonical target으로 분류합니다. +description: reflect 분류 트리거입니다. --- # Reflect -세션 결과와 피드백에서 재사용 가능한 learning을 꺼내고, 안전한 durable promotion surface로 분류하는 skill입니다. +`/tk:reflect` wrapper skill입니다. 상세 계약, output contract, helper/path semantics의 source of truth는 `commands/reflect.md`입니다. -## Goal +## Use when -- repo-local guidance와 user-global guidance는 지원 host에서 기본 apply(opt-out) 대상으로 봅니다. -- reusable procedure는 skill/hook/command/agent 후보로 분류합니다. -- skill은 explicit apply일 때만 실제 source로 materialize하며, authoring은 `/tk:learn` pipeline으로 위임합니다. -- writable host-native surface를 확인할 수 없으면 suggest-only로 남깁니다. -- branch-local one-off와 저신뢰 정보는 버립니다. +- 세션 결과와 사용자 피드백에서 reusable learning을 durable target으로 분류해야 할 때 +- repo-local / user-global / skill / hook / command / agent / discard 경계를 먼저 정해야 할 때 +- `/tk:learn`으로 넘길 same session/ledger candidate를 정리해야 할 때 -## Canonical targets +## Wrapper rules -- `repo-local` -- `repo-shared` -- `user-global` -- `skill` -- `hook` -- `command` -- `agent` -- `discard` - -## Process - -1. 세션 결과, 실제 변경, 성공/실패, 사용자 피드백을 읽습니다. -2. reusable candidate를 canonical target으로 분류합니다. -3. `repo-local`과 `user-global`은 지원 host에서 기본 apply 후보로 봅니다. -4. `skill`은 explicit apply일 때만 source 생성 후보로 보고, 같은 session/ledger candidate를 `/tk:learn` pipeline으로 넘깁니다. -5. exact apply plan은 ledger에 남기고 stdout은 compact하게 유지합니다. -6. `hook/command/agent`는 제안만 하고 source는 직접 만들지 않습니다. -7. branch-specific one-off, 민감 정보, 중복, 저신뢰 항목은 `discard`합니다. - -## Repo-local apply - -- 유일한 repo-local direct write target: `/CLAUDE.local.md` -- 기본은 apply enabled -- `--apply=false`면 preview-only -- tracked file / not ignored / symlink / repo 밖 path는 reject - -## User-global apply - -- 지원 host에서는 user-global도 기본 apply 후보입니다. -- Claude Code 계열이면 `~/.claude/CLAUDE.md` 또는 `~/.claude/rules//CLAUDE.md`를 target으로 잡을 수 있습니다. -- host가 `CLAUDE.md` 계열 파일을 직접 다루지 않으면 host-native user-global guidance surface를 사용합니다. -- writable host-native surface를 확인할 수 없으면 `suggest_only`로 남깁니다. - -## Boundaries - -- Claude Code auto memory write/mirror/backup 금지 -- source code / hook settings / command source / agent source / plugin manifest 수정 금지 -- `PROFILE.md`, `automation`, `hookify`를 target 이름으로 쓰지 않음 - -## Skill materialize - -- `reflect`는 candidate를 제안합니다. -- `skill` target은 explicit apply일 때만 실제 skill source를 생성합니다. -- skill source 생성은 `/tk:learn` pipeline이 ledger를 source of truth로 읽어 마무리합니다. -- helper surface가 있으면 `/tk:learn`은 `read-reflect-candidate`로 current ledger candidate를 읽을 수 있습니다. -- `candidate_id`는 same session/ledger candidate로만 유효합니다. +- 이 skill은 `commands/reflect.md`를 대체하지 않고, command intent를 빠르게 잡는 얇은 wrapper입니다. +- artifact path / apply boundary / helper invocation / receipt shape는 `commands/reflect.md`를 그대로 따릅니다. +- command contract에 이미 있는 절차와 경계를 다시 장문으로 복제하지 않습니다. diff --git a/skills/route/SKILL.md b/skills/route/SKILL.md index 5c5fa4c..dd1a164 100644 --- a/skills/route/SKILL.md +++ b/skills/route/SKILL.md @@ -1,58 +1,20 @@ --- name: route -description: 지금 작업을 direct, subagent-driven, goal-driven 중 어떤 경로로 가져갈지 얇게 정리합니다. +description: route 판단 트리거입니다. --- # Route -지금 이 작업을 어떤 구현 경로로 가져가야 하는지 짧고 실용적으로 고르는 skill입니다. +`/tk:route` wrapper skill입니다. 상세 계약, output contract, helper/path semantics의 source of truth는 `commands/route.md`입니다. -## Goal +## Use when -- direct로 바로 갈지 -- subagent-driven으로 나눌지 -- goal-driven orchestration이 맞는지 -- 아니면 SoT/decision이 먼저인지 -를 정합니다. +- direct / subagent-driven / goal-driven / decision / need-sot 중 어디로 갈지 정해야 할 때 +- 구현보다 먼저 역할 분리, SoT, ownership을 얇게 판단해야 할 때 +- same repo/scope `gap packet`이 있으면 그것을 재사용해 route 판단을 이어가야 할 때 -## Canonical routes +## Wrapper rules -- `direct` -- `subagent-driven` -- `goal-driven` -- `decision` -- `need-sot` - -## Process - -1. task 범위와 현재 제약을 읽습니다. -2. same repo/scope `gap packet`이 있으면 source set, precedence, ambiguity를 먼저 읽고 재사용합니다. - - helper surface가 있으면 `read-gap-packet`으로 현재 packet을 읽고, 없으면 packet 없이 진행합니다. -3. source 수정 없이 route만 비교합니다. -4. 가능한 route의 장단점을 짧게 적습니다. -5. 가장 무난한 1안을 고르고 첫 스텝을 제안합니다. 역할/문맥 분리가 route 이유라면 compact delegation plan도 같이 적습니다. -6. `goal-driven`이고 host가 `/goal`을 지원하면 ready-to-run `/goal <추천 목표>`를 같이 제안할 수 있습니다. -7. SoT가 없거나 owner decision이 먼저면 억지 확정 대신 `need-sot` 또는 `decision`으로 남깁니다. - -## Decision policy - -- `direct`는 순수 기계적 변경이고, file-local이며, 낮은 리스크이고, 의미 있는 설계 판단이 거의 없을 때만 우선 검토합니다. -- diff가 작더라도 아래 조건이면 `subagent-driven`을 우선 검토합니다. - - 메인 세션이 이미 긴 planning/design을 거쳤고 구현은 깨끗한 brief에서 다시 시작하는 편이 나을 때 - - 병렬 탐색, 독립 검증, reviewer/implementer 분리 이점이 클 때 - - clean implementor context가 중요해서 구현자는 좁은 implementation brief만 받아야 할 때 - - adversarial diff-only review가 regression 탐지에 더 유리할 때 - - behavior, data flow, auth, permissions, billing, migrations, caching, concurrency, error handling 같은 리스크 경로를 건드릴 때 - - 테스트가 약하거나 없어 cold review가 도움이 될 때 - - 더 강한 모델은 설계, 더 빠른 모델은 구현처럼 역할 분리 이점이 있을 때 -- multi-step orchestration이 핵심이면 `goal-driven` -- 제품 판단이나 owner 확인이 먼저면 `decision` -- SoT 부족이 먼저면 `need-sot` - -## Boundaries - -- source 수정 금지 -- build/test/network 실행 금지 -- approval 우회 문구 유도 금지 -- 안 맞는 surface를 억지 추천하지 않음 -- `/goal` suggestion은 host가 실제로 그 surface를 지원할 때만 제안 +- 이 skill은 `commands/route.md`를 대체하지 않고, command intent를 빠르게 잡는 얇은 wrapper입니다. +- artifact path / apply boundary / helper invocation / receipt shape는 `commands/route.md`를 그대로 따릅니다. +- command contract에 이미 있는 절차와 경계를 다시 장문으로 복제하지 않습니다. diff --git a/skills/to-issues/SKILL.md b/skills/to-issues/SKILL.md index d9953ca..e624c6a 100644 --- a/skills/to-issues/SKILL.md +++ b/skills/to-issues/SKILL.md @@ -1,41 +1,19 @@ --- name: to-issues -description: plan이나 PRD를 independently grabbable vertical-slice issue draft로 분해합니다. +description: issue 분해 트리거입니다. --- # To Issues -plan/PRD를 바로 구현 가능한 issue draft 묶음으로 쪼개는 skill입니다. +`/tk:to-issues` wrapper skill입니다. 상세 계약, output contract, helper/path semantics의 source of truth는 `commands/to-issues.md`입니다. -## Goal +## Use when -- 병렬로 잡아갈 수 있는 작업 단위를 만듭니다. -- layer별 분해가 아니라 user value 기준 vertical slice로 나눕니다. -- publish 전에 draft를 먼저 만듭니다. +- plan/PRD를 independently grabbable vertical-slice issue draft로 쪼개야 할 때 +- publish 전에 dependency와 ordering을 먼저 draft로 고정해야 할 때 -## Process +## Wrapper rules -1. source plan/PRD에서 목표와 제약을 읽습니다. -2. layer별 분해를 피하고 vertical slice 후보를 먼저 만듭니다. -3. 각 issue draft에 아래를 넣습니다. - - title - - user value / outcome - - scope - - acceptance criteria - - blocked-by / order dependency -4. 독립적으로 집을 수 없는 조각은 합치거나 다시 자릅니다. -5. 기본은 markdown draft만 만들고 외부 publish는 하지 않습니다. - -## Boundaries - -- default draft-only -- no-publish 기본 -- no layer slicing -- task spam 금지 -- 독립 실행이 안 되는 issue 쪼개기 금지 - -## Good use cases - -- 병렬 agent 실행 전 issue slicing -- PRD를 GitHub/Linear draft로 옮기기 전 정리 -- 구현 순서와 dependency를 명시적으로 나눌 때 +- 이 skill은 `commands/to-issues.md`를 대체하지 않고, command intent를 빠르게 잡는 얇은 wrapper입니다. +- artifact path / apply boundary / helper invocation / receipt shape는 `commands/to-issues.md`를 그대로 따릅니다. +- command contract에 이미 있는 절차와 경계를 다시 장문으로 복제하지 않습니다. diff --git a/skills/to-prd/SKILL.md b/skills/to-prd/SKILL.md index bcf4090..0b66ff8 100644 --- a/skills/to-prd/SKILL.md +++ b/skills/to-prd/SKILL.md @@ -1,41 +1,19 @@ --- name: to-prd -description: 현재 대화나 요구사항을 draft-only PRD로 정리합니다. +description: PRD 정리 트리거입니다. --- # To PRD -대화나 메모를 바로 구현으로 밀기 전에, 기능 요구를 PRD draft로 압축 정리하는 skill입니다. +`/tk:to-prd` wrapper skill입니다. 상세 계약, output contract, helper/path semantics의 source of truth는 `commands/to-prd.md`입니다. -## Goal +## Use when -- 요구사항을 기능 문서로 정리합니다. -- acceptance criteria를 명시합니다. -- issue publish나 외부 반영 없이 draft를 먼저 만듭니다. +- 현재 대화나 요구사항을 draft-only PRD로 정리해야 할 때 +- acceptance criteria를 구현 전에 먼저 고정해야 할 때 -## Process +## Wrapper rules -1. 현재 대화와 명시된 요구를 읽습니다. -2. 이미 정해진 범위와 아직 열린 질문을 분리합니다. -3. 아래 항목을 갖춘 PRD draft를 만듭니다. - - problem / goal - - user value - - non-goals - - requirements - - acceptance criteria - - risks / open questions -4. 기본은 인터뷰를 길게 끌지 않고, 부족한 점만 최소 질문합니다. -5. 외부 publish 없이 draft artifact만 만듭니다. - -## Boundaries - -- default draft-only -- no-publish 기본 -- approval 전 tracker 반영 금지 -- 문서 생성이 구현 완료를 뜻하지 않음 - -## Good use cases - -- 구현 전 요구를 고정해야 할 때 -- plan 전에 acceptance criteria를 먼저 세우고 싶을 때 -- issue 분해 전 PRD 형태가 필요한 때 +- 이 skill은 `commands/to-prd.md`를 대체하지 않고, command intent를 빠르게 잡는 얇은 wrapper입니다. +- artifact path / apply boundary / helper invocation / receipt shape는 `commands/to-prd.md`를 그대로 따릅니다. +- command contract에 이미 있는 절차와 경계를 다시 장문으로 복제하지 않습니다.