@kaydash9999/banker-plugins 0.4.0 → 0.5.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude Code skills + commands — QA, audit, docs, architecture, dependency setup, and wiki; the banker plugin marketplace.",
-    "version": "0.4.0"
+    "version": "0.5.0"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "banker",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Claude Code plugin: QA/audit/docs/architecture skills + commands, a /banker:setup installer for OS dependencies (playwright, etc.), and wiki compaction.",
   "author": {
     "name": "smallOpenSource",

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.5.0] - 2026-07-15
+
+### Added
+- **신규 스킬 9종** (전부 `target: both`, 런타임 인식 — Claude=OMC / Codex=OMX): 개발환경 "harness" 구성요소를 OS별·런타임별로 개별 설치/구성하는 스킬 계층. USER_RESOURCES의 과거버전 가이드(5-OS Claude Code + 6-OS Codex/Azure)에서 공통 유용요소를 추출하고 2026 현행 방식으로 현행화했다.
+  - `setup-node`: nvm + Node 22 (winget/nvm-windows) per-OS. npx 기반 MCP·CLI의 전제.
+  - `setup-python`: Python 3.11 + pipx + uv per-OS (dnf module/deadsnakes/winget/brew, PEP668). `docs-setup`가 이 런타임을 소비.
+  - `setup-java`: JDK 21 + JAVA_HOME per-OS (Debian은 Adoptium Temurin 전용). `setup-lsp`의 jdtls가 요구.
+  - `setup-lsp`: 언어별 LSP(vtsls·basedpyright·bash·jdtls·spring) + lsp-mcp 브리지. Claude=LSP MCP 도구, Codex=`config.toml [mcp_servers.lsp_bridge]`. `--lang` 선택.
+  - `setup-tmux`: tmux per-OS (Rocky8 `3.6a` 소스빌드·apt/brew·Windows psmux). OMC team·worktree / OMX `$team`·HUD 전제.
+  - `setup-pwsh`: Windows PowerShell 7 환경(`$PROFILE` UTF-8·Terminal·Git). Claude=`CLAUDE_CODE_GIT_BASH_PATH`, Codex=네이티브 셸. 비-Windows는 no-op 안내.
+  - `setup-mcp`: 공통 MCP 서버(context7·sequential-thinking·filesystem·git·fetch). Claude=`claude mcp add`, Codex=`config.toml [mcp_servers.*]` (timeout 300).
+  - `setup-sandbox`: OS별 샌드박스(bubblewrap+userns / AppContainer / Seatbelt) + rust/cargo + git `safe.directory`. Codex=`sandbox_mode`.
+  - `harness-factory`: revfactory/harness(팀 아키텍처 팩토리) 플러그인 설치+구성+사용안내. Claude=`harness@harness-marketplace`(+`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 를 settings.json에 영속), Codex=`SaehwanPark/meta-harness`. 설치를 넘어 모드/6패턴 선택·비용가드(~7× 토큰)·experimental 리스크 고지까지 담되, harness references는 이식하지 않고 설치된 플러그인 참조(Apache-2.0 연동/참조, banker 재배포 아님).
+
+### Changed
+- Codex 설치 스킬 수 **32 → 41**(+커맨드 2 유지, claude-only=0). **2계층 아키텍처**: 얇은 setup-* 실행 유닛 + `banker:setup`/`harness-factory` 오케스트레이터가 조합·의존성 관리(setup-lsp→node/python/java, setup-mcp→node/python, docs-setup→python).
+- `commands/setup.md` 오케스트레이터에 신규 9 스킬(계층·의존성)을 추가하고, `README.md`·`codex/transform-matrix.md`를 동기화했다. `scripts/smoke-test.js`에 `copies===41` + 신규 9 존재 회귀 단언을 추가했다.
+- **서드파티 명시(연동/참조, 재배포 아님)**: revfactory/harness·SaehwanPark/meta-harness(Apache-2.0), jdtls(EPL), tmux(ISC), psmux, basedpyright·vtsls·bash-language-server·lsp-mcp 등 각 프로젝트 라이선스 소유.
+- **per-OS CI**: `.github/workflows/`에 GitHub-hosted 러너(ubuntu/windows/macos + Rocky8 컨테이너) 기반 설치·동작 검증 워크플로를 추가했다(설치가 실제 실행되는 도구를 만드는지 "존재 vs 동작" 검증).
+
 ## [0.4.0] - 2026-07-15
 
 ### Added

package/README.md

@@ -7,7 +7,7 @@
 
 [빠른 시작](#빠른-시작) · [구성](#구성) · [설치 상세](#설치-상세-npm--codex) · [요구사항](#요구사항) · [업데이트 / 제거](#업데이트--제거) · [라이선스 / 서드파티](#라이선스--서드파티)
 
-banker는 QA, 보안 감사, 문서, 아키텍처, 위키 작업을 위한 스킬 32개와 의존성 설치 스킬을 묶은 Claude Code 플러그인입니다. 설치하면 스킬과 커맨드가 `/banker:<이름>` 네임스페이스로 노출됩니다. 이 저장소 자체가 Claude Code 마켓플레이스(`.claude-plugin/marketplace.json`)이자 플러그인(`.claude-plugin/plugin.json`, name `banker`)이며, 도구에 무관한 스킬은 Codex CLI에도 설치됩니다.
+banker는 QA, 보안 감사, 문서, 아키텍처, 위키 작업을 위한 스킬 41개와 의존성·개발환경(OS별) 설치 스킬을 묶은 Claude Code 플러그인입니다. 설치하면 스킬과 커맨드가 `/banker:<이름>` 네임스페이스로 노출됩니다. 이 저장소 자체가 Claude Code 마켓플레이스(`.claude-plugin/marketplace.json`)이자 플러그인(`.claude-plugin/plugin.json`, name `banker`)이며, 도구에 무관한 스킬은 Codex CLI에도 설치됩니다.
 
 > npm 패키지(`@kaydash9999/banker-plugins`)와 GitHub 저장소(`smallOpenSource/banker_plugins`)는 같은 메인테이너가 관리합니다.
 
@@ -83,11 +83,27 @@ playwright(브라우저 QA)나 oh-my-claudecode(OMC/OMX)처럼 별도 의존성
 | `smart-compact` | 컨텍스트 임계 초과 시 위키·resume 저장 게이트 자동 무장 |
 | `deep-research` | 다중 소스 팬아웃 + 적대적 검증 인용 리서치 |
 
+### 스킬: 개발환경 setup (OS별 · 런타임별)
+
+USER_RESOURCES 가이드의 공통 요소를 OS별·런타임별(Claude Code/Codex)로 구성하는 얇은 실행 유닛. `/banker:setup` 오케스트레이터가 의존 순서(런타임 먼저)로 조합한다.
+
+| 스킬 | 설명 |
+|---|---|
+| `setup-node` | nvm + Node 22 (winget/nvm-windows) |
+| `setup-python` | Python 3.11 + pipx + uv (PEP668) |
+| `setup-java` | JDK 21 + JAVA_HOME (Debian=Adoptium Temurin) |
+| `setup-lsp` | 언어별 LSP(vtsls·basedpyright·bash·jdtls·spring) + lsp-mcp 브리지 (node·python·java 의존) |
+| `setup-tmux` | tmux(Rocky8 3.6a 소스빌드) / psmux(Windows) |
+| `setup-pwsh` | Windows PowerShell 7 환경(비-Windows no-op) |
+| `setup-mcp` | 공통 MCP 서버(context7·seq-thinking·filesystem·git·fetch) |
+| `setup-sandbox` | OS별 샌드박스(bubblewrap+userns / Seatbelt) + rust + git safe.directory |
+
 ### 스킬: 설치 (`/banker:setup` 가 호출)
 
 | 스킬 | 설명 |
 |---|---|
 | `setup-omc` | oh-my-claudecode(OMC) 설치·갱신 (Codex는 OMX) |
+| `harness-factory` | revfactory/harness 팀 아키텍처 팩토리 설치·구성·사용안내 (Codex=meta-harness) |
 | `setup-playwright` | Playwright + headless 브라우저 (RHEL8/Rocky8·non-root·no-conda 폴백) |
 | `setup-omc-hud` | omc_hud 상태표시줄 (OS별) |
 | `setup-insane-search` | insane-search 플러그인 설치 (Claude·Codex) |
@@ -109,7 +125,7 @@ banker uninstall        # 제거
 
 - `--scope project` 로 프로젝트 로컬(`./.codex`)에 설치하고, `--dry-run` 으로 미리 볼 수 있습니다.
 - non-root 전용입니다(전역 sudo 설치 시 root 소유 파일을 방지). postinstall이 없으므로 `banker setup` 을 직접 실행합니다.
-- Codex에는 스킬 32개가 `~/.codex/skills/banker-<name>/` 에, 커맨드 2개가 `~/.codex/prompts/banker-<name>.md` 에 설치됩니다(`codex/manifest.json`). 디렉터리명과 일치하도록 프론트매터 `name:` 이 `banker-<name>` 으로 재작성되어 Codex가 `banker-<name>` 으로 인식합니다.
+- Codex에는 스킬 41개가 `~/.codex/skills/banker-<name>/` 에, 커맨드 2개가 `~/.codex/prompts/banker-<name>.md` 에 설치됩니다(`codex/manifest.json`). 디렉터리명과 일치하도록 프론트매터 `name:` 이 `banker-<name>` 으로 재작성되어 Codex가 `banker-<name>` 으로 인식합니다.
 - OMC/Claude 에 결합됐던 오케스트레이터·설치·유틸 표면(all-in-one·ultra-init·front-qa·setup·setup-omc·setup-omc-hud·setup-stitch·omc-reference·compact-copy)은 본문이 **런타임 인식**이라 Codex에서도 동작합니다 — Codex에선 OMC 대신 **oh-my-codex(OMX)** 의 동명 스킬(ralplan·ralph·ultraqa·hud 등)과 `codex mcp`·내장 `/copy` 를 사용합니다(Codex는 `omx setup` 전제).
 - `~/.codex/AGENTS.md` 는 건드리지 않습니다(omx가 재생성하므로 `~/.codex/skills/` 자동 검색에 의존).
 
@@ -154,9 +170,11 @@ banker 자체는 **MIT** ([LICENSE](LICENSE)). Owner: [smallOpenSource](https://
 - Python: python-pptx(MIT, `arch-diagram`), python-docx(MIT, `rfp-author`), Playwright(Apache-2.0, `audit-web-page`·`play-qa`·`ultra-ui-qa`), detect-secrets(Apache-2.0, `lineage` 시크릿 스캔).
 - 브라우저·렌더링: Chromium(BSD-3-Clause), SwiftShader(Apache-2.0), Xvfb·X.Org(MIT). `setup-playwright` 및 브라우저 QA 스킬이 사용.
 - 문서·다이어그램: PlantUML(GPL 계열·다중 라이선스, `arch-diagram`), Poppler(GPL, `pdftoppm`), ImageMagick(ImageMagick License, `pdf-vision-extract`).
+- 개발환경·LSP: Node.js·nvm(MIT), uv(Apache-2.0/MIT), OpenJDK·Temurin(GPL+CE), jdtls(EPL-2.0), basedpyright(MIT)·vtsls·bash-language-server(MIT)·vscode-langservers-extracted, lsp-mcp([CesarPetrescu/lsp-mcp](https://github.com/CesarPetrescu/lsp-mcp)), tmux(ISC)·psmux, bubblewrap(LGPL-2.0), rustup. `setup-node`·`setup-python`·`setup-java`·`setup-lsp`·`setup-tmux`·`setup-sandbox` 가 설치.
 
 **연동·참조 (외부 프레임워크·서비스·브랜드)**
 - 프레임워크: oh-my-claudecode(OMC, **MIT**)·oh-my-codex(OMX, **MIT**), by [Yeachan-Heo](https://github.com/Yeachan-Heo). `all-in-one`·`ultra-init`·`/banker:front-qa`·`setup-omc` 가 사용.
 - 플러그인: insane-search(**MIT**, © fivetaku, [fivetaku/gptaku_plugins](https://github.com/fivetaku/gptaku_plugins)). `setup-insane-search` 가 설치.
+- 팀 아키텍처 팩토리: revfactory/harness(**Apache-2.0**, © Minho Hwang, [revfactory/harness](https://github.com/revfactory/harness))·Codex 포트 SaehwanPark/meta-harness(**Apache-2.0**). `harness-factory` 가 설치(banker 는 재배포하지 않고 설치·구성만 안내).
 - 서비스·디자인(독점·상표): Notion(`make-notion-guide`), Google Stitch(`setup-stitch`), Nothing 디자인 언어(`nothing-design`).
 - QA 대상 엔진(예시): Godot(MIT), Phaser(MIT) 등(`play-qa`).

package/codex/manifest.json

@@ -38,6 +38,16 @@
     { "name": "smart-compact",        "type": "skill",   "target": "both",        "reason": "context-threshold compaction-hygiene gate (statusLine detect + hook bridge + assistant chain + TUI handoff); runtime-aware", "supportingFiles": [] },
     { "name": "visual-ralph",         "type": "skill",   "target": "both",        "reason": "measured visual build loop (port of OMX visual-ralph); Claude ralph+visual-verdict+Stitch imagegen, Codex $ralph+$imagegen; runtime-aware", "supportingFiles": [] },
 
+    { "name": "setup-node",           "type": "skill",   "target": "both",        "reason": "installs nvm+Node22 (or winget/nvm-windows) per-OS; prerequisite for npx MCP servers + Codex/OMX tooling; runtime-agnostic installer", "supportingFiles": [] },
+    { "name": "setup-python",         "type": "skill",   "target": "both",        "reason": "installs Python 3.11 + pipx + uv per-OS (dnf module/deadsnakes/winget/brew, PEP668); runtime foundation; docs-setup consumes it", "supportingFiles": [] },
+    { "name": "setup-java",           "type": "skill",   "target": "both",        "reason": "installs JDK 21 + JAVA_HOME per-OS (dnf/apt-Adoptium/winget/brew); required by jdtls in setup-lsp", "supportingFiles": [] },
+    { "name": "setup-lsp",            "type": "skill",   "target": "both",        "reason": "installs per-language LSP servers (vtsls/basedpyright/bash/jdtls/spring) + lsp-mcp bridge; Claude=LSP MCP tools, Codex=config.toml [mcp_servers.lsp_bridge]; needs setup-node/python/java", "supportingFiles": [] },
+    { "name": "setup-tmux",           "type": "skill",   "target": "both",        "reason": "installs tmux per-OS (Rocky8 3.6a source-build, apt/brew, Windows psmux); OMC team/worktree + OMX $team/HUD require it", "supportingFiles": [] },
+    { "name": "setup-pwsh",           "type": "skill",   "target": "both",        "reason": "Windows PowerShell 7 env (Terminal/Git/$PROFILE UTF-8); Claude CLAUDE_CODE_GIT_BASH_PATH, Codex native shell; no-op off-Windows", "supportingFiles": [] },
+    { "name": "setup-mcp",            "type": "skill",   "target": "both",        "reason": "installs common standalone MCP servers (context7/seq-thinking/filesystem/git/fetch); Claude `claude mcp add`, Codex config.toml [mcp_servers.*]; needs setup-node/python", "supportingFiles": [] },
+    { "name": "setup-sandbox",        "type": "skill",   "target": "both",        "reason": "agent sandbox per-OS (bubblewrap+userns / AppContainer / Seatbelt) + rust/cargo + git safe.directory; Codex sandbox_mode", "supportingFiles": [] },
+    { "name": "harness-factory",      "type": "skill",   "target": "both",        "reason": "installs+configures+guides the revfactory/harness team-architecture factory plugin (Claude harness@harness-marketplace, Codex SaehwanPark/meta-harness); Apache-2.0 referenced not redistributed", "supportingFiles": [] },
+
     { "name": "front-qa",             "type": "command", "target": "both",        "reason": "ralplan->ralph frontend-QA pipeline; Claude=OMC, Codex=OMX", "supportingFiles": [] },
     { "name": "setup",                "type": "command", "target": "both",        "reason": "installer orchestrator; Claude AskUserQuestion multi-select, Codex prompt-based selection", "supportingFiles": [] }
   ]

package/commands/setup.md

@@ -1,5 +1,5 @@
 ---
-description: "(banker) 구성요소·의존성을 multi-select로 골라 설치하는 오케스트레이터(oh-my-claudecode·playwright·omc-hud·insane-search·stitch·docs-setup)."
+description: "(banker) 구성요소·의존성을 multi-select로 골라 설치하는 오케스트레이터(런타임 node·python·java, LSP, tmux, MCP, sandbox, OMC, harness-factory, playwright 등)."
 argument-hint: "[설치할 컴포넌트명 — 비우면 multi-select 표시]"
 ---
 
@@ -11,22 +11,34 @@ banker 플러그인이 제공하는 설치 스킬들을 **multi-select**로 골
 ## 절차
 
 1. **선택 받기**: `$ARGUMENTS` 에 컴포넌트명이 명시돼 있으면 그것만 실행(질문 생략).
-   비어 있으면 아래 5개를 `AskUserQuestion`(**multiSelect: true**)으로 제시한다(**Codex 런타임엔 AskUserQuestion 이 없으므로 목록을 제시하고 설치할 항목을 사용자에게 물어 받는다**):
-   - **setup-omc** — oh-my-claudecode(OMC) 설치/갱신. `all-in-one`·`ultra-init`·`/banker:front-qa` 의존성(Codex는 OMX).
-   - **setup-playwright** — Playwright + 브라우저 + headless 디스플레이(Xvfb). RHEL8/Rocky8 등 비공식 지원·non-root·no-conda 폴백 포함. (`ultra-ui-qa`·`audit-web-page`·`play-qa` 의존성)
-   - **setup-omc-hud** — omc_hud 상태표시줄 설치(OS별).
-   - **setup-insane-search** — insane-search 플러그인(차단 사이트 우회) 설치(Claude/Codex 양쪽 경로).
+   비어 있으면 아래를 `AskUserQuestion`(**multiSelect: true**)으로 제시한다(**Codex 런타임엔 AskUserQuestion 이 없으므로 목록을 제시하고 설치할 항목을 사용자에게 물어 받는다**). 항목은 **계층/의존 순서**로 묶여 있으니, 뒤 계층을 고르면 앞 계층 전제를 먼저 채운다:
+
+   **런타임 (기반 — 먼저)**
+   - **setup-node** — nvm + Node 22(winget/nvm-windows). npx 기반 MCP·CLI 전제.
+   - **setup-python** — Python 3.11 + pipx + uv(PEP668). `setup-lsp`·`setup-mcp`·`docs-setup` 전제.
+   - **setup-java** — JDK 21 + JAVA_HOME(Debian=Adoptium). `setup-lsp` 의 jdtls 요구.
+
+   **개발도구**
+   - **setup-lsp** — 언어별 LSP(vtsls·basedpyright·bash·jdtls·spring) + lsp-mcp 브리지. (의존: node·python·java)
+   - **setup-tmux** — tmux(Rocky8 3.6a 소스빌드)/psmux(Windows). OMC team·OMX `$team`/HUD 전제.
+   - **setup-pwsh** — Windows PowerShell 7 환경($PROFILE UTF-8·Terminal·Git). 비-Windows는 no-op.
+   - **setup-mcp** — 공통 MCP 서버(context7·seq-thinking·filesystem·git·fetch). (의존: node·python)
+   - **setup-sandbox** — OS별 샌드박스(bubblewrap+userns / AppContainer / Seatbelt) + rust + git safe.directory.
+
+   **프레임워크·플러그인**
+   - **setup-omc** — oh-my-claudecode(OMC) 설치/갱신(Codex는 OMX). `all-in-one`·`ultra-init`·`/banker:front-qa` 의존성.
+   - **harness-factory** — revfactory/harness(팀 아키텍처 팩토리) 설치+구성+안내(Codex=meta-harness).
+   - **setup-insane-search** — insane-search 플러그인(차단 사이트 우회, Claude/Codex 양쪽).
+   - **setup-omc-hud** — omc_hud 상태표시줄(OS별).
    - **setup-stitch** — Stitch(디자인 생성) MCP 프록시 등록(RockyLinux8 proxy-script, API key 필요).
-   - **docs-setup** — arch-diagram·pdf-vision-extract 의존성(python-pptx·pymupdf·plantuml) 설치(python path 질문 또는 자동 감지).
-
-2. **실행**: 선택된 각 항목의 스킬을 호출한다(미선택은 건드리지 않음). Claude Code는 `Skill("banker:<name>")`, **Codex 런타임에선 설치된 `banker-<name>` 스킬을 적용**한다:
-   - setup-omc → `Skill("banker:setup-omc")`
-   - setup-playwright → `Skill("banker:setup-playwright")`
-   - setup-omc-hud → `Skill("banker:setup-omc-hud")`
-   - setup-insane-search → `Skill("banker:setup-insane-search")`
-   - setup-stitch → `Skill("banker:setup-stitch")`
-   - docs-setup → `Skill("banker:docs-setup")`
-   각 스킬이 OS를 감지해 알맞은 절차로 설치하고 끝에 검증한다. 한 항목이 실패해도 정직히 보고하고 다음 항목 진행.
+
+   **의존성 라이브러리**
+   - **setup-playwright** — Playwright + 브라우저 + Xvfb(RHEL8/Rocky8 폴백). (`ultra-ui-qa`·`audit-web-page`·`play-qa` 의존성)
+   - **docs-setup** — arch-diagram·pdf-vision-extract 의존성(python-pptx·pymupdf·plantuml). (의존: python)
+
+2. **실행**: 선택된 각 항목을 호출한다(미선택은 건드리지 않음). Claude Code는 `Skill("banker:<name>")`, **Codex 런타임에선 설치된 `banker-<name>` 스킬을 적용**한다(예: `Skill("banker:setup-node")`).
+   - **의존 순서 강제**: 뒤 계층을 고르면 전제 스킬을 먼저 실행한다 — `setup-lsp` 전에 setup-node·setup-python·setup-java; `setup-mcp` 전에 setup-node·setup-python; `docs-setup` 전에 setup-python. 이미 설치돼 있으면 각 스킬이 감지해 skip(멱등).
+   - 각 스킬이 OS를 감지해 알맞은 절차로 설치하고 끝에 검증한다. 한 항목이 실패해도 정직히 보고하고 다음 항목 진행.
 
 3. **마무리 보고(한글)**: 설치된 항목·검증 결과·**재시작/reload 필요 여부**.
    - 플러그인 설치(insane-search)는 `/reload-plugins`(Claude) 또는 재시작 후 반영(Codex는 재시작).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaydash9999/banker-plugins",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "banker — Claude Code + Codex CLI plugin (QA, audit, docs, architecture, wiki skills). Install via Claude Code marketplace, or `npm i -g @kaydash9999/banker-plugins` then `banker setup`.",
   "bin": {
     "banker": "bin/banker.js"

package/skills/harness-factory/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: harness-factory
+description: "(banker) revfactory/harness(팀 아키텍처 팩토리) 플러그인 설치·구성·사용안내. Claude=harness@harness-marketplace, Codex=meta-harness. 'harness-factory'/'하네스 팩토리'/'에이전트팀 생성' 또는 /banker:setup 시 사용."
+---
+
+# harness-factory: revfactory/harness 팀 아키텍처 팩토리 설치·구성
+
+`harness`는 도메인을 한 줄로 받아 `.claude/agents/`+`.claude/skills/`(전문 에이전트팀 + 그 에이전트가 쓸
+스킬)를 생성하는 **메타 스킬**이다. 이 플러그인의 본체는 설치물이 아니라 **방법론**이다. 따라서 이
+스킬은 설치에서 그치지 않고 구성(experimental flag 영속화)과 사용 안내(모드·패턴·비용 가드)까지
+책임진다. 이미 설치돼 있으면 갱신·재확인만 한다(멱등). 답변은 한글.
+
+## 런타임 배선
+- **Claude Code** = `revfactory/harness` 플러그인(마켓플레이스 설치, 네이티브 팀 프리미티브 사용).
+- **Codex** = `SaehwanPark/meta-harness`(별개 레포·Python 인스톨러·파일 handoff). Codex엔 네이티브 팀
+  프리미티브가 없어 파일 기반 순차 handoff로 우회한다(banker의 OMX 패턴과 동일 원리).
+
+## 0. 감지 (먼저, 추정 금지)
+```bash
+command -v claude >/dev/null && claude --version || echo "claude: 미설치"
+ls -la .claude/agents .claude/skills 2>/dev/null   # 기존 harness 산출물 흔적 감사
+```
+- **v2.1.178 경계 주의**: 그 이후 버전은 `TeamCreate`/`TeamDelete` 도구가 제거되고 팀이 세션 시작 시
+  자동 구성된다. harness SKILL.md·OMC 문서의 `TeamCreate` 호출 예시가 현행 CLI와 어긋날 수 있다.
+  버전을 확인하고 **불일치 가능성을 사용자에게 정직히 고지**한다(가짜 확신 금지).
+- 기존 `.claude/agents/`·`.claude/skills/`·`CLAUDE.md`에 harness 흔적이 있으면 신규 생성이 아니라
+  확장·유지보수로 다룬다(harness 자신의 Phase 0 감사 원칙).
+
+## 1. 설치
+### Claude Code
+세션 안(슬래시 커맨드):
+```
+/plugin marketplace add revfactory/harness
+/plugin install harness@harness-marketplace
+/reload-plugins
+```
+- **정답 슬러그는 `harness@harness-marketplace` 하나뿐이다.** 하드코딩한다. 저장소 문서가 3-way로
+  어긋나 있으니(KO/JA README=`harness-marketplace`[`harness@` 접두 누락], quickstart=`harness@harness`
+  [마켓플레이스 접미 오류]) 그대로 복붙하지 말 것.
+- 설치 전 `claude plugin marketplace list`로 등록명을 재확인한다.
+- 대안(마켓플레이스 없이 글로벌 스킬 직접 설치): `cp -r skills/harness ~/.claude/skills/harness`.
+
+### Codex CLI
+마켓플레이스 개념이 없고 Python 인스톨러를 쓴다:
+```bash
+git clone https://github.com/SaehwanPark/meta-harness
+cd meta-harness
+python3 scripts/install_harness.py --scope user --layout codex
+# 프로젝트 범위: python3 scripts/install_harness.py --scope project --target <repo> --layout codex
+```
+
+## 2. 구성 (핵심)
+팀 프리미티브는 **experimental flag로 게이트**된다. 셸 세션이 아니라 `settings.json`에 영속화한다:
+```json
+{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
+```
+- 셸 `export`는 **그 셸에서 띄운 claude에만** 적용되어 재시작 후 유실된다. 반드시 `settings.json`
+  `env`에 기록해야 영속한다.
+- 미설정 시 **에러 없이 조용히 단일 에이전트로 폴백**되어 Pipeline/Fan-out-in/Supervisor/Hierarchical
+  패턴이 소리 없이 깨진다(harness 관리자가 `docs/experimental-dependency.md`에 공식 인정). Claude Code
+  v2.x+ 필요.
+
+## 3. 사용 안내 (요약; 심층은 설치된 플러그인 references/ 위임)
+> harness 자신이 6종 references/(패턴 카탈로그·오케스트레이터 템플릿·팀 예시·skill writing/testing·QA)로
+> Progressive Disclosure한다. 여기서는 요약만 담고, 깊이는 설치된 플러그인의 references/를 읽게 위임한다
+> (상류 문서를 verbatim 복사하지 않는다).
+
+**(a) 모드 결정트리** (team / subagent / hybrid):
+- 2+ 에이전트 + 실시간 상호통신(교차검증·발견 공유)이 가치를 더하면 → **team**.
+- 단일 작업·독립 병렬·결과만 반환이면 → **subagent**(경량·토큰효율).
+- 공식 비용지침: **순차·동일 파일 편집·의존성 많은 작업은 subagent/단일세션이 유리**하다. harness의
+  "2+면 팀 기본"과 어긋날 수 있으니, 팀이 정말 필요한지 재확인하는 게이트를 둔다.
+
+**(b) 6개 아키텍처 패턴**(1줄):
+- **Pipeline** (순차 의존): n 출력이 n+1 입력.
+- **Fan-out/Fan-in** (병렬+집계): 팀모드가 가장 자연스럽다.
+- **Expert Pool** (라우팅 택1): 라우터가 입력 분류 후 전문가 하나 호출, subagent 적합.
+- **Producer-Reviewer** (생성·검증): 재시도 캡 2-3(무한루프 방지).
+- **Supervisor** (동적 분배): 중앙이 런타임 조건으로 워커 배정.
+- **Hierarchical** (재귀 위임): 깊이 ≤ 2(3+는 지연·컨텍스트 손실).
+
+**(c) 비용 가드**: 팀 실행은 단일세션 대비 **약 7× 토큰**(공식). 그러므로:
+- 팀 규모 **3-5명**(집중된 3명 > 분산된 5명).
+- 워커 모델은 **Sonnet** 기본.
+- 작업 완료 즉시 종료. spawn 프롬프트는 간결하게.
+
+## 4. 리스크 고지
+harness는 실험적 팀 API에 의존한다. `docs/experimental-dependency.md`가 3시나리오를 자체 정의한다:
+- **A** 플래그 제거(GA 승격) / **B** Managed Agents 서버사이드 실행으로 대체 / **C** 하위호환 없는
+  시그니처 변경.
+- **C는 v2.1.178에서 사실상 현실화된 정황이다**(`TeamCreate`/`TeamDelete` 제거). 설치 시 "실험적 기능
+  의존"이라는 사실을 반드시 드러낸다.
+- **부작용(read-only 아님)**: 실행 시 사용자 프로젝트에 파일을 직접 생성한다(`.claude/agents/`·
+  `.claude/skills/`·중간산출물 `_workspace/`). 기존 파일 충돌 처리·CLAUDE.md 포인터 등록을 안내한다.
+
+## 검증 (보고 의무)
+1. **산출물**: `ls -la .claude/agents .claude/skills` 로 에이전트/스킬 파일이 실제 생성됐는지.
+2. **flag 영속**: `settings.json`에 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`이 기록됐는지.
+3. **팀 스폰**: 간단한 샘플 태스크로 **팀이 실제로 스폰되는지**(무증상 단일 에이전트 폴백이 아닌지).
+4. **Codex**: meta-harness 산출물(스킬·`_workspace/` handoff)이 생성됐는지.
+
+보고는 4필드로 한다: **감지(버전·기존흔적) · 설치(플러그인 or meta-harness) · 구성(flag 영속) ·
+검증(산출물·팀스폰)**. 실패·불명확은 정직 보고(가짜 성공 금지).
+
+## 함정
+- **3-way 설치명령 버그**: 유일 정답은 `harness@harness-marketplace`. KO/JA README·quickstart는 틀림.
+- **무증상 폴백**: flag 없으면 팀 패턴이 조용히 단일 에이전트로 저하(에러 안 남).
+- **비용 7×**: 팀은 고토큰. 규모·모델·종료 가드 없이 돌리지 말 것.
+- **버전 drift**: v2.1.178에서 `TeamCreate`/`TeamDelete` 제거. 상류 문서의 팀 호출 예시가 현행과 어긋남.
+- **릴리스/태그 0건**: GitHub Releases·Tags 모두 없음. 버전 근거는 오직 `plugin.json`의 `1.2.0`.
+- **라이선스 Apache-2.0**: 연동·참조이지 banker 재배포가 아니다. 상류 references/를 verbatim 복사하지
+  않고 설치된 플러그인 자체를 가리킨다.
+
+ARGUMENTS: `[--scope user|project]` (Codex meta-harness 설치 범위; 기본 user)

package/skills/setup-java/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: setup-java
+description: "(banker) JDK 21 + JAVA_HOME 설치(alternatives로 java·javac 비대칭 방지, Debian은 Adoptium 전용). jdtls 등 Java LSP 전제. 'setup-java'/'JDK 설치'/'Java 21 설치' 또는 /banker:setup 시 사용."
+---
+
+# setup-java: JDK 21 + JAVA_HOME 설치
+
+Java LSP(`jdtls`) 등 Java 도구가 요구하는 JDK 21과 `JAVA_HOME`을 설치·구성한다.
+멱등(이미 21이면 skip·검증만). 답변은 한글(명령·경로는 영문).
+
+## 런타임 배선
+- **Claude Code**: `docs-setup`의 PlantUML 렌더(`java -jar plantuml.jar`)가 java 존재를 전제로 동작.
+- **Codex/OMX**: `jdtls`(Java LSP)와 Spring Boot Language Server(`java -jar ...`)가 JDK 21을 요구한다. 이를 실제로 내려받아 구동하는 별도 LSP 설치 스킬(예: setup-lsp)의 전제조건이 이 스킬이다.
+- 이 스킬은 JDK 설치·`JAVA_HOME` 확정까지만 담당하고, jdtls 자체 배포·`JDTLS_JVM_ARGS` 같은 힙 튜닝은 LSP 설치 스킬의 영역이다.
+
+## 0. 감지 (먼저, 추정 금지)
+```bash
+[ -f /etc/os-release ] && . /etc/os-release && echo "distro=$ID ${VERSION_ID}"
+command -v java  >/dev/null && java -version 2>&1 | head -1 || echo "java=미설치"
+command -v javac >/dev/null && javac -version 2>&1          || echo "javac=미설치"
+echo "JAVA_HOME=${JAVA_HOME:-미설정}"
+```
+```powershell
+$PSVersionTable.PSVersion
+if (Get-Command java -ErrorAction SilentlyContinue) { java -version } else { "java: 미설치" }
+[Environment]::GetEnvironmentVariable('JAVA_HOME','User')
+```
+
+## 1. Rocky Linux 8
+```bash
+sudo dnf install -y java-21-openjdk-devel
+JAVA21_HOME=$(dirname "$(dirname "$(readlink -f /usr/lib/jvm/java-21-openjdk*/bin/java)")")
+sudo alternatives --install /usr/bin/java  java  "$JAVA21_HOME/bin/java"  21 \
+  --slave /usr/bin/javac javac "$JAVA21_HOME/bin/javac" \
+  --slave /usr/bin/jar   jar   "$JAVA21_HOME/bin/jar"
+sudo alternatives --set java "$JAVA21_HOME/bin/java"
+export JAVA_HOME="$JAVA21_HOME"   # 아래 "rc 마커 공통"이 참조
+```
+- `--slave`로 `java`·`javac`·`jar`를 한 그룹으로 묶는 이유: 나중에 `alternatives --config java`로 버전을 바꿀 때 `javac`가 따로 놀면(비대칭) 컴파일이 엉뚱한 버전으로 실행된다.
+
+## 2. Ubuntu 20.04~24.04
+```bash
+sudo apt update
+sudo apt install -y openjdk-21-jdk || echo "openjdk-21-jdk 미제공. 아래 3. Debian의 Adoptium 블록을 그대로 적용"
+sudo update-alternatives --config java     # 여러 버전 중 21 선택(javac도 slave로 동반 전환)
+javac -version   # java와 버전 일치 확인(비대칭 점검)
+export JAVA_HOME="$(dirname "$(dirname "$(readlink -f "$(command -v javac)")")")"   # 아래 "rc 마커 공통"이 참조
+```
+
+## 3. Debian 12 (bookworm): Adoptium Temurin 전용
+⚠️ **default·backports 저장소 모두 JDK 21을 제공하지 않는다.** Adoptium 레포 추가가 유일한 경로(재확인: 배포판이 이후 21을 backport하면 이 단계는 생략 가능).
+```bash
+sudo apt-get install -y wget gnupg
+wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | \
+  sudo gpg --dearmor -o /usr/share/keyrings/adoptium.gpg
+echo "deb [signed-by=/usr/share/keyrings/adoptium.gpg] https://packages.adoptium.net/artifactory/deb bookworm main" | \
+  sudo tee /etc/apt/sources.list.d/adoptium.list
+sudo apt-get update
+sudo apt-get install -y temurin-21-jdk
+sudo update-alternatives --config java
+export JAVA_HOME="/usr/lib/jvm/temurin-21-jdk-$(dpkg --print-architecture)"   # amd64/arm64 자동
+```
+(Ubuntu에서 `openjdk-21-jdk`가 없을 때도 이 블록을 그대로 재사용한다.)
+
+## 4. macOS (Apple Silicon / Intel)
+```zsh
+brew install openjdk@21
+sudo ln -sfn "$(brew --prefix openjdk@21)/libexec/openjdk.jdk" \
+  /Library/Java/JavaVirtualMachines/openjdk-21.jdk   # 유일한 sudo, 1회성
+export JAVA_HOME="$(brew --prefix openjdk@21)"        # 아래 공통 rc 블록 참고
+/usr/libexec/java_home -v 21
+```
+Apple Silicon(`/opt/homebrew`)·Intel(`/usr/local`) 차이는 `brew --prefix`가 자동 흡수하므로 이 스크립트는 두 아키텍처에 동일 적용.
+
+## 5. Windows 10/11
+```powershell
+winget install --id Microsoft.OpenJDK.21 -e
+$jdk = (Get-ChildItem "$env:ProgramFiles\Microsoft\jdk-21*" -Directory | Select-Object -First 1).FullName
+[Environment]::SetEnvironmentVariable('JAVA_HOME', $jdk, 'User')
+[Environment]::SetEnvironmentVariable('PATH', "$jdk\bin;" + [Environment]::GetEnvironmentVariable('PATH','User'), 'User')
+```
+User-scope로 지정하면 Machine-scope에 남아있을 수 있는 구버전(Java 8 등)보다 PATH 우선순위가 앞선다. 새 터미널에서 반영 확인.
+
+## rc 마커 공통 (Linux/macOS, Windows 제외)
+```bash
+RC_FILE="$HOME/.bashrc"    # macOS는 $HOME/.zshrc
+grep -q '### BANKER_JAVA_BEGIN ###' "$RC_FILE" || cat >> "$RC_FILE" <<EOF
+
+### BANKER_JAVA_BEGIN ###
+export JAVA_HOME="$JAVA_HOME"
+export PATH="\$JAVA_HOME/bin:\$PATH"
+### BANKER_JAVA_END ###
+EOF
+source "$RC_FILE"
+```
+
+## 검증 (보고 의무)
+```bash
+java -version    # openjdk 21.x 기대
+javac -version   # java와 동일 21.x(다르면 alternatives 비대칭)
+echo "$JAVA_HOME"
+```
+4-field 보고: 변경(설치 패키지·alternatives 전환·JAVA_HOME 값) / Evidence(위 출력) / 검증(java·javac 버전 일치) / Unknown(관리자 권한 부재로 alternatives 미실행 등, 가짜 성공 금지).
+
+## 함정
+- **java/javac 비대칭**: `alternatives`(RHEL 계열)·`update-alternatives`(Debian 계열)에서 `java`만 바꾸고 `javac`를 안 바꾸면 "실행은 21, 컴파일은 8" 같은 사고 발생 → `--slave`로 묶거나 전환 직후 `javac -version` 대조.
+- **Debian 12 저장소 공백**: default·backports 모두 21 없음 → Adoptium 필수(버전 상황은 실행 전 재확인).
+- **Adoptium GPG/네트워크 차단**: 사내 프록시 환경이면 `packages.adoptium.net` 접근이 막힐 수 있음 → 정직 보고, 프록시 예외 요청.
+- **macOS symlink**: 1회성 sudo. `brew upgrade`로 21 내 패치 버전이 올라가도 재실행 불요하나, 메이저가 바뀌면(예: 21→25) 재실행 필요.
+- **Windows JAVA_HOME 누락**: 설정 안 하면 jdtls 등이 엉뚱한(또는 없는) JRE를 찾아 조용히 실패 → User-scope로 명시 설정 후 새 터미널에서 확인.
+- **버전 기준 재확인**: JDK 21 고정은 jdtls 호환 기준(2026-07 시점). 이후 jdtls·Spring Boot LS가 더 최신 LTS(예: 25)를 요구하게 되면 이 스킬의 버전 인자를 올려 재실행.
+
+ARGUMENTS: [--version <n>] (없으면 21 자동 설치)