@rch4com/agent-setup 1.15.0 → 1.16.0

package/lib/bootstrap/templates.mjs

@@ -30,7 +30,105 @@ Document the actual commands used by this repository:
 - Do not modify files outside this repository.
 - Do not add production dependencies without explicit approval.
 - Do not edit generated files directly.
-- Never commit credentials, access tokens, or connection strings.`
+- Never commit credentials, access tokens, or connection strings.
+
+## Behavioral guidelines
+
+Behavioral guidelines to reduce common LLM coding mistakes.
+
+**Scope:** Only what current models still get wrong. If the model or the
+harness already handles something reliably, it doesn't belong here - a rule
+that restates default behavior burns context and buys nothing.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial
+tasks, use judgment.
+
+### 1. State Assumptions, Then Proceed
+
+**Say what you assumed. Keep going. Default the rest.**
+
+Before implementing:
+
+- State your assumptions in one line, then start.
+- If multiple interpretations exist, pick the likeliest and say which one you
+  picked.
+- If a simpler approach exists, say so while doing the work - not as a question
+  that blocks it.
+- Ask only when the answer changes what gets built, not how well, and the wrong
+  choice can't be cheaply undone.
+
+A stated assumption gets corrected in seconds. A question costs a round-trip
+and hands the work back to the user. If you're about to ask a second question
+in one task, you're doing it wrong.
+
+### 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes,
+simplify.
+
+### 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+### 4. Verify Before Done
+
+**If you touched code, run the check before saying "done" - and report what
+actually ran.**
+
+- \`npm test\`, \`pytest\`, \`cargo test\`, whatever the project uses. Smallest
+  relevant check first, broader checks when risk is high.
+- No test setup? At minimum, verify the project builds or typechecks.
+- Report the exact command and its result: "passed", "failed with X", or "not
+  run because Y".
+- Never write "done", "fixed", or "works" unless a concrete check backs it.
+- Run it proactively, before the user signals "끝", "완료", "다 됐어".
+
+This is the step LLMs skip most often. Treat it as non-negotiable.
+
+### 5. Teach One Thing On The Way Out
+
+**End with what the user would want to know next time. Two or three
+sentences.**
+
+When the work is done:
+
+- Name the one concept, tradeoff, or gotcha that actually mattered here.
+- Teach what the code doesn't show: why this way over the obvious one, which
+  default you leaned on, what breaks first at scale.
+- If it needs a heading, it's too long. If it restates the diff, delete it.
+- Skip it when the change is trivial, or when the user is the one who taught
+  you the thing.
+
+Why: an agent that only ships code leaves the user unable to maintain it. They
+should finish each task slightly more able to do it without you.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer
+rewrites due to overcomplication, and stated assumptions get corrected early
+instead of surfacing as mistakes late.`
 
 export const CLAUDE_BLOCK = `<!-- agent-kit:begin -->
 @AGENTS.md

package/lib/catalog.mjs

@@ -166,11 +166,15 @@ export function definePlugin({ id, label, installId, detectIds, marketplace, not
   }
 }
 
-export function defineSkill({ id, label, scope, detect, install, uninstall, note, group = null, unsupported: reasons = {} }) {
+// supports는 이 항목이 실제로 배선하는 CLI다. 기본값이 claude 하나인 것은
+// 대부분의 스킬 상류가 Claude 경로만 주기 때문이고, 상류가 런타임별 설치를
+// 주는 항목(skill.gsd)은 목록을 직접 넘긴다 — 넘긴 CLI는 미배선 사유 대상에서
+// 빠진다.
+export function defineSkill({ id, label, scope, detect, install, uninstall, note, group = null, supports = ['claude'], unsupported: reasons = {} }) {
   const unsupported = Object.fromEntries(
-    CLI_IDS.filter((c) => c !== 'claude').map((c) => [c, reasons[c] ?? msg('item.unsupported.claudeSkill')]),
+    CLI_IDS.filter((c) => !supports.includes(c)).map((c) => [c, reasons[c] ?? msg('item.unsupported.claudeSkill')]),
   )
-  return { id, category: 'skill', label, scope, supports: ['claude'], unsupported, note, group, detect, install, uninstall }
+  return { id, category: 'skill', label, scope, supports: [...supports], unsupported, note, group, detect, install, uninstall }
 }
 
 // 이 저장소가 공유 스킬 자리로 쓰는 디렉터리. vercel-labs/skills 레지스트리의

package/lib/i18n/catalog/en.mjs

@@ -242,7 +242,9 @@ export default {
   'item.unsupported.bkitPort': 'upstream ships separate ports (bkit-codex / bkit-gemini) installed apart from this plugin; the Gemini port is still a Gemini CLI extension and has had no update since the 2026-06-18 sunset',
   'item.unsupported.impeccableJunction': 'upstream supports it, but npx impeccable install breaks the shared .agents/skills link, so only the plugin route is wired',
   'item.unsupported.gstackHost': 'upstream supports it via ./setup --host — this item installs for Claude Code only',
-  'item.unsupported.gsdFlag': 'upstream supports it via a runtime flag — this item installs with --claude only',
+  'item.unsupported.gstackShared': 'the upstream --host route is user-scoped, so it is not used. In a bootstrapped repository the shared .agents/skills junction reaches this CLI instead, and it scans recursively, so it sees the individual skills too (measured 2026-08-15)',
+  'item.unsupported.gstackSharedShallow': 'in a bootstrapped repository the shared .agents/skills junction reaches this CLI, but it scans only one level, so just the router skill shows up (measured 2026-08-15)',
+  'item.unsupported.gsdKimiLocal': 'upstream still blocks project-scope installs — --kimi --local refuses with "Project-level Kimi install semantics remain deferred" (measured 2026-08-15)',
   'item.unsupported.gsdGemini': 'upstream dropped Gemini CLI (sunset 2026-06) — Antigravity succeeds it via --antigravity',
   'item.mcp.partial': 'registered: {present} / missing: {missing}',
   'item.plugin.partial': 'wired: {present} / missing: {missing}',
@@ -280,8 +282,8 @@ export default {
   'item.skill.mcp-builder.note': 'a guide for building MCP servers (Python FastMCP, Node MCP SDK). Its four reference/ documents and the Apache-2.0 LICENSE.txt are copied along inside the skill directory. Harness-neutral content shared by all 10 CLIs',
   'item.skill.mattpocock-skills.note': 'copies 35 skills into the shared .agents/skills so all 10 CLIs see them. Upstream documents this route itself, and with no hooks involved nothing is lost against the plugin edition. Only one of the two can be chosen',
   'item.skill.karpathy.note': 'behavioral guidelines that curb overbuilding and vague success criteria',
-  'item.skill.gstack.note': 'repo-local clone + setup (needs bash; Git Bash on Windows). Runtime state (~/.gstack) may be created globally.',
-  'item.skill.gsd.note': 'npx @opengsd/gsd-core, installed per project. Upstream supports 18 runtimes (Codex, Antigravity, …); this item wires --claude only',
+  'item.skill.gstack.note': 'repo-local clone + setup (needs bash; Git Bash on Windows). Runtime state (~/.gstack) may be created globally. In a bootstrapped repository .claude/skills is a junction, so the files land in the shared .agents/skills — codex and opencode scan recursively and see the individual skills too',
+  'item.skill.gsd.note': 'npx @opengsd/gsd-core, installed per project — wires five runtimes in one run: claude, codex, opencode, copilot, kilo (.claude/commands, .codex/skills, .opencode/skills, .github/skills, .kilo/skills). Each runtime writes roughly 700 files. gemini was dropped upstream and kimi still blocks project installs',
   // 커밋 템플릿은 CLI 배선이 아니라 저장소 규약이다 — note가 "무엇이 놓이고
   // 무엇이 설정되는가"를 대신 말한다(상세 패널에 배선표가 없다).
   'item.config.gitmessage.en.note': 'commit messages in English. Writes the template and points git commit.template at it, so it opens in every editor and every tool in this repository',

package/lib/i18n/catalog/ko.mjs

@@ -235,7 +235,9 @@ export default {
   'item.unsupported.bkitPort': '상류가 별도 배포판(bkit-codex·bkit-gemini)으로 지원합니다 — 이 플러그인과 별개 설치입니다. Gemini판은 Gemini CLI 확장 그대로이고 2026-06-18 종료 이후 갱신이 없습니다',
   'item.unsupported.impeccableJunction': '상류는 지원하지만 npx impeccable install이 공유 .agents/skills 연결을 끊어 플러그인 경로만 배선합니다',
   'item.unsupported.gstackHost': '상류는 ./setup --host로 지원합니다 — 이 항목은 Claude Code에만 설치합니다',
-  'item.unsupported.gsdFlag': '상류는 런타임 플래그로 지원합니다 — 이 항목은 --claude로만 설치합니다',
+  'item.unsupported.gstackShared': '상류 --host 경로는 사용자 스코프라 쓰지 않습니다. 대신 부트스트랩 저장소에서는 공유 .agents/skills Junction으로 닿고, 이 CLI는 재귀 스캔이라 개별 스킬까지 봅니다(2026-08-15 실측)',
+  'item.unsupported.gstackSharedShallow': '부트스트랩 저장소에서는 공유 .agents/skills Junction으로 닿지만, 이 CLI는 1단계만 훑어 라우터 스킬 하나만 보입니다(2026-08-15 실측)',
+  'item.unsupported.gsdKimiLocal': '상류가 프로젝트 스코프 설치를 아직 막습니다 — --kimi --local이 "Project-level Kimi install semantics remain deferred"로 거부합니다(2026-08-15 실측)',
   'item.unsupported.gsdGemini': '상류가 Gemini CLI 지원을 제거했습니다(2026-06 종료) — Antigravity가 --antigravity로 승계합니다',
   'item.mcp.partial': '등록됨: {present} / 누락: {missing}',
   'item.plugin.partial': '배선됨: {present} / 누락: {missing}',
@@ -273,8 +275,8 @@ export default {
   'item.skill.mcp-builder.note': 'MCP 서버 제작 가이드(Python FastMCP·Node MCP SDK). reference/ 문서 4종과 Apache-2.0 LICENSE.txt가 스킬 디렉터리에 함께 복사됩니다. 내용이 하네스 중립이라 10개 CLI가 함께 씁니다',
   'item.skill.mattpocock-skills.note': '공유 .agents/skills에 스킬 35종을 복사해 10개 CLI가 함께 봅니다. 상류가 직접 안내하는 경로이며 훅이 없어 플러그인 판에 견줘 잃는 것이 없습니다. 둘 중 하나만 고를 수 있습니다',
   'item.skill.karpathy.note': '과설계와 모호한 완료 기준을 줄이는 행동 지침',
-  'item.skill.gstack.note': '저장소 로컬 clone + setup (bash 필요, Windows는 Git Bash). 런타임 상태(~/.gstack)는 전역에 생길 수 있음.',
-  'item.skill.gsd.note': 'npx @opengsd/gsd-core 프로젝트 로컬 설치. 상류는 Codex·Antigravity 등 18개 런타임을 지원합니다(이 항목은 --claude)',
+  'item.skill.gstack.note': '저장소 로컬 clone + setup (bash 필요, Windows는 Git Bash). 런타임 상태(~/.gstack)는 전역에 생길 수 있음. 부트스트랩 저장소에서는 .claude/skills가 Junction이라 실물이 공유 .agents/skills에 앉습니다 — codex·opencode는 재귀 스캔이라 개별 스킬까지 함께 봅니다',
+  'item.skill.gsd.note': 'npx @opengsd/gsd-core 프로젝트 로컬 설치 — claude·codex·opencode·copilot·kilo 다섯 런타임을 한 번에 배선합니다(.claude/commands, .codex/skills, .opencode/skills, .github/skills, .kilo/skills). 런타임마다 700개 안팎의 파일이 생깁니다. gemini는 상류가 제거했고 kimi는 프로젝트 설치를 아직 막습니다',
   // 커밋 템플릿은 CLI 배선이 아니라 저장소 규약이다 — en.mjs 쪽 주석 참고.
   'item.config.gitmessage.en.note': '커밋 메시지를 영어로 씁니다. 템플릿을 놓고 git commit.template이 그것을 가리키게 하므로, 저장소의 모든 편집기와 도구에서 함께 열립니다',
   'item.config.gitmessage.ko.note': '커밋 메시지를 한국어로 씁니다. 템플릿을 놓고 git commit.template이 그것을 가리키게 하므로, 저장소의 모든 편집기와 도구에서 함께 열립니다',

package/lib/items/skill.gsd.mjs

@@ -4,43 +4,95 @@ import { defineSkill } from '../catalog.mjs'
 import { CLI_IDS } from '../clis.mjs'
 import { LocalizedError, msg } from '../i18n/index.mjs'
 
+// 상류(v1.10.0)는 런타임 플래그 18종을 주는데, 그중 이 저장소의 CLI이면서
+// **프로젝트 스코프(--local)로 설치되고 그 CLI가 실제로 읽는 것**만 배선한다.
+// 다섯 자리 전부 2026-08-15에 실측했다:
+//   claude   `.claude/commands`에 gsd-* (680파일). skills가 아니라 commands다 —
+//            부트스트랩 저장소의 `.claude/skills` Junction과 무관하다.
+//   codex    `.codex/skills`에 gsd-* 71종. `codex debug prompt-input`이 이
+//            경로를 스킬 루트로 등록하고 전부 나열하는 것을 확인했다.
+//   opencode `.opencode/skills`. `opencode debug skill`이 로드한다.
+//   copilot  `.github/skills`. `copilot skill list`가 전부 표시한다.
+//   kilo     `.kilo/skills` 71종을 @kilocode/cli 7.3.45가 읽는다(2026-08-15).
+//
+// 플래그는 한 번에 여러 개를 줄 수 있다 — `--claude --codex --local`이 두
+// 디렉터리를 만드는 것을 실측했다. 그래서 설치·제거 모두 호출 한 번이다.
+// `--uninstall`도 같은 플래그를 받아 그 런타임만 지운다(`--codex --local
+// --uninstall`이 .codex만 비우고 나머지 넷을 보존하는 것을 확인).
+//
+// 미배선 넷의 사유가 전부 다르다:
+//   gemini  상류가 명시 제거(2026-06-18 종료). `--gemini --local`은 안내만 찍고
+//           파일을 하나도 만들지 않는다.
+//   kimi    `--kimi --local`이 "Project-level Kimi install semantics remain
+//           deferred"를 찍고 거부한다 — 전역 설치만 가능하다.
+//   kiro·grok·vscode  상류 런타임 목록에 없다.
+const RUNTIMES = [
+  { cli: 'claude', dirs: ['.claude/commands', '.claude/skills'] },
+  { cli: 'codex', dirs: ['.codex/skills'] },
+  { cli: 'opencode', dirs: ['.opencode/skills'] },
+  { cli: 'copilot', dirs: ['.github/skills'] },
+  { cli: 'kilo', dirs: ['.kilo/skills'] },
+]
+const SUPPORTS = RUNTIMES.map((r) => r.cli)
+
+// gsd-* 이름을 기준으로 센다. 상류 제거가 `gsd-install-state.json`과 훅 몇
+// 개를 남기는 것을 실측했는데(디렉터리는 남고 gsd-* 스킬만 사라진다), 파일
+// 존재만 보면 제거한 런타임이 영원히 설치됨으로 읽힌다.
 function hasGsdFiles(dir) {
-  return existsSync(dir) && readdirSync(dir).some((f) => f.startsWith('gsd-'))
+  try {
+    return readdirSync(dir).some((f) => f.startsWith('gsd-'))
+  } catch {
+    return false
+  }
+}
+
+function wiredClis(root) {
+  return RUNTIMES.filter((r) => r.dirs.some((d) => hasGsdFiles(join(root, ...d.split('/'))))).map((r) => r.cli)
 }
 
-// 상류(v1.10.0)는 런타임 플래그 19개(--codex·--antigravity 등)를 지원하지만
-// 이 항목은 --claude만 배선한다. Gemini CLI는 상류가 명시 제거했다 —
-// `--gemini --local`이 2026-06-18 종료 안내를 찍고 파일을 하나도 만들지 않는
-// 것을 실측했다(2026-08-15).
-// --kilo가 이 저장소의 Kilo Code와 같은 제품인지는 오래 미확인이었는데,
-// `--kilo --local`이 만든 .kilo/skills/ 71개를 설치된 Kilo Code
-// (@kilocode/cli 7.3.45)가 전부 로드하는 것을 실측해 해소했다(2026-08-15).
-const FLAGS = ['codex', 'opencode', 'copilot', 'kimi', 'kilo']
+const flagsFor = (clis) => clis.map((c) => `--${c}`)
 
 export default defineSkill({
   id: 'skill.gsd', label: 'GSD (Get Shit Done)', group: '__flow', scope: 'project',
   note: 'item.skill.gsd.note',
+  supports: SUPPORTS,
   unsupported: Object.fromEntries(
-    CLI_IDS.filter((c) => c !== 'claude').map((c) => [
+    CLI_IDS.filter((c) => !SUPPORTS.includes(c)).map((c) => [
       c,
-      FLAGS.includes(c) ? msg('item.unsupported.gsdFlag')
-        : c === 'gemini' ? msg('item.unsupported.gsdGemini')
+      c === 'gemini' ? msg('item.unsupported.gsdGemini')
+        : c === 'kimi' ? msg('item.unsupported.gsdKimiLocal')
           : msg('item.unsupported.upstreamNone'),
     ]),
   ),
+
   async detect({ root }) {
-    const found = hasGsdFiles(join(root, '.claude', 'commands')) || hasGsdFiles(join(root, '.claude', 'skills'))
-    return { status: found ? 'installed' : 'absent' }
+    const present = wiredClis(root)
+    if (present.length === 0) return { status: 'absent' }
+    if (present.length === SUPPORTS.length) return { status: 'installed' }
+    return {
+      status: 'partial',
+      detail: msg('item.mcp.partial', {
+        present: present.join(', '),
+        missing: SUPPORTS.filter((c) => !present.includes(c)).join(', '),
+      }),
+    }
   },
+
   async install({ root, exec }) {
-    const r = await exec('npx', ['-y', '@opengsd/gsd-core@latest', '--claude', '--local'], { cwd: root })
+    // 이미 있는 런타임은 빼고 부른다 — 상류가 덮어써도 무해하지만, 부분
+    // 설치를 완성할 때 3,500개 파일을 다시 쓰는 것은 낭비다.
+    const missing = SUPPORTS.filter((c) => !wiredClis(root).includes(c))
+    if (missing.length === 0) return
+    const r = await exec('npx', ['-y', '@opengsd/gsd-core@latest', ...flagsFor(missing), '--local'], { cwd: root })
     if (!r.ok) throw new LocalizedError('error.gsdInstall', { output: r.output })
   },
+
   async uninstall({ root, exec }) {
-    // 런타임 플래그가 없으면 상류가 기본값 claude를 지운다 — 지금은 --claude만
-    // 설치하므로 맞지만, 다른 런타임을 설치하게 되면 여기에도 같은 플래그를
-    // 넘겨야 엉뚱한 설치본이 지워지지 않는다.
-    const r = await exec('npx', ['-y', '@opengsd/gsd-core@latest', '--uninstall'], { cwd: root })
+    // 런타임 플래그 없는 `--uninstall`은 기본값 claude만 지운다 — 설치된
+    // 런타임을 전부 넘겨야 나머지 넷이 남지 않는다.
+    const present = wiredClis(root)
+    if (present.length === 0) return
+    const r = await exec('npx', ['-y', '@opengsd/gsd-core@latest', ...flagsFor(present), '--local', '--uninstall'], { cwd: root })
     if (!r.ok) throw new LocalizedError('error.gsdUninstall', { output: r.output })
   },
 })

package/lib/items/skill.gstack.mjs

@@ -12,8 +12,19 @@ const REL_DIR = '.claude/skills/gstack'
 // 인자 없이 실행하며 setup의 기본값이 claude 단독이다. README 표에 있는
 // --host cursor·slate는 setup의 case 문이 거부해 exit 1로 죽는다 —
 // 확장한다면 안전한 값은 claude·codex·kiro·factory·opencode·auto뿐이다
-// (2026-08-02 검증).
-const HOSTS = ['codex', 'kiro', 'opencode']
+// (2026-08-02 검증, 2026-08-15 재확인: case 문과 에러 문구 그대로).
+//
+// 그런데 --host를 늘릴 필요가 없다는 것이 2026-08-15 실측으로 드러났다.
+// 상류 --host 경로는 홈(~/.codex/skills 등)에 까는 사용자 스코프인데, 이
+// 항목이 clone하는 `.claude/skills/gstack`은 부트스트랩 저장소에서 Junction
+// 이라 실물이 공유 `.agents/skills/gstack`에 앉는다. 거기서부터는 CLI의 스킬
+// 스캔 깊이가 도달 범위를 정한다 — gstack은 클론 루트에 라우터 SKILL.md가
+// 있고 개별 스킬이 그 아래 한 단계 더 들어간 2단계 구조다.
+//   codex·opencode  재귀 스캔이라 개별 스킬까지 전부 인식(중첩 프로브로 실측).
+//   copilot         1단계만 훑어 라우터 스킬 하나만 보인다(같은 프로브).
+// 나머지 CLI의 스캔 깊이는 미실측이라 "상류 경로 없음"으로 남긴다 — Junction
+// 도달은 우리 부트스트랩의 부수 효과지 상류 지원이 아니다.
+const SHARED_RECURSIVE = ['codex', 'opencode']
 
 export default defineSkill({
   id: 'skill.gstack', label: 'gstack', group: '__flow', scope: 'project',
@@ -21,7 +32,10 @@ export default defineSkill({
   unsupported: Object.fromEntries(
     CLI_IDS.filter((c) => c !== 'claude').map((c) => [
       c,
-      HOSTS.includes(c) ? msg('item.unsupported.gstackHost') : msg('item.unsupported.upstreamNone'),
+      SHARED_RECURSIVE.includes(c) ? msg('item.unsupported.gstackShared')
+        : c === 'copilot' ? msg('item.unsupported.gstackSharedShallow')
+          : c === 'kiro' ? msg('item.unsupported.gstackHost')
+            : msg('item.unsupported.upstreamNone'),
     ]),
   ),
   async detect({ root }) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rch4com/agent-setup",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Repository-scoped bootstrap and optional-item installer for using multiple coding-agent CLIs in one repository | 여러 코딩 에이전트 CLI를 한 저장소에서 함께 쓰기 위한 저장소 범위 부트스트랩과 선택 항목 설치기",
   "keywords": [
     "agents-md",