cx-skills 1.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "cx-skills",
+  "description": "CLI-first multi-model orchestrator — Codex/Gemini/Claude routing with DAG execution, auto-triage, and cost optimization",
+  "owner": {
+    "name": "tellang"
+  },
+  "plugins": [
+    {
+      "name": "cx-skills",
+      "description": "CLI-first multi-model orchestrator for Claude Code. Routes tasks to Codex, Gemini, and Claude CLIs with automatic triage (Sonnet classification + Opus decomposition), DAG-based parallel execution, and cost-optimized routing. Includes 16 skills, HUD status bar, and shell-based CLI routing wrapper.",
+      "version": "1.0.0",
+      "author": {
+        "name": "tellang"
+      },
+      "source": "./",
+      "category": "productivity",
+      "homepage": "https://github.com/tellang/cx-skills",
+      "tags": [
+        "multi-model",
+        "codex",
+        "gemini",
+        "cli-routing",
+        "orchestration",
+        "cost-optimization",
+        "dag-execution"
+      ]
+    }
+  ],
+  "version": "1.0.0"
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "cx-skills",
+  "version": "1.0.0",
+  "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
+  "author": {
+    "name": "tellang"
+  },
+  "repository": "https://github.com/tellang/cx-skills",
+  "homepage": "https://github.com/tellang/cx-skills",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "codex",
+    "gemini",
+    "cli-routing",
+    "orchestration",
+    "multi-model"
+  ],
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": "./.mcp.json"
+}

package/.mcp.json

@@ -0,0 +1,3 @@
+{
+  "mcpServers": {}
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 tellang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,329 @@
+[English](README.md) | 한국어
+
+# cx-skills
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+**Claude Code를 위한 CLI 기반 멀티모델 오케스트레이터. Codex, Gemini, Claude로 작업을 라우팅합니다.**
+
+[빠른 시작](#빠른-시작) · [스킬](#스킬) · [아키텍처](#아키텍처) · [연결 설정](#codex--gemini-연결-설정)
+
+---
+
+## 빠른 시작
+
+**Step 1: 설치**
+
+```bash
+# 방법 A: Claude Code 플러그인 (권장)
+/plugin marketplace add https://github.com/tellang/cx-skills
+/plugin install cx-skills
+
+# 방법 B: npm
+npm install -g cx-skills
+```
+
+**Step 2: 사용**
+```bash
+# 자동 모드 — AI가 분류 + 분해
+/cx-auto "인증 모듈 리팩터링 + 로그인 UI 개선 + 테스트 추가"
+
+# 수동 모드 — agent 직접 지정
+/cx-auto 3:codex "src/api, src/auth, src/payment 각각 리뷰"
+
+# 단일 에이전트 라우팅
+/cx-route executor "JWT 인증 미들웨어 구현" implement 300
+```
+
+끝입니다. `cli-route.sh`는 세션 시작 시 자동 설치됩니다.
+
+---
+
+## 왜 cx-skills인가?
+
+- **비용 최적화** — Codex/Gemini(무료 티어) 우선 라우팅, Claude는 필요할 때만
+- **CLI 네이티브** — MCP 오버헤드 없이 Codex/Gemini CLI 직접 셸 실행
+- **자동 트리아지** — Sonnet이 작업 분류, Opus가 병렬 서브태스크로 분해
+- **DAG 실행** — 의존성 인식 병렬 실행 + 컨텍스트 전달
+- **설정 불필요** — 플러그인이 `cli-route.sh`와 HUD를 첫 세션에 자동 설치
+- **OMC 호환** — 단독 사용 또는 oh-my-claudecode 확장으로 함께 사용 가능
+
+---
+
+## 실행 모드
+
+| 모드 | 워커 수 | 용도 |
+|------|---------|------|
+| **cx-auto** (자동) | N (AI 결정) | 복합 작업 — AI가 분류 + 분해 |
+| **cx-auto** (수동) | N:agent | 직접 제어 — agent와 워커 수 지정 |
+| **cx-route** | 1 | 단일 작업 — 에이전트 하나, 프롬프트 하나 |
+| **bteam** | N Codex | 코드 중심 병렬 작업 |
+| **hteam** | Codex + Gemini + Claude | 혼합 작업 (코드 + UI + 테스트) |
+| **kteam** | N (Windows 안정화) | Windows 환경 Gemini 안정화 적용 |
+
+---
+
+## 스킬
+
+### 오케스트레이션
+
+| 스킬 | 설명 | 예시 |
+|------|------|------|
+| **cx-auto** | 통합 병렬 오케스트레이터 | `/cx-auto "분석 + 구현 + 테스트"` |
+| **cx-route** | 단일 에이전트 CLI 라우팅 | `/cx-route executor "기능 구현"` |
+
+### CLI 커맨드 (`sc` 라우터 경유)
+
+| 커맨드 | 라우팅 대상 | 용도 |
+|--------|-----------|------|
+| `/implement` | Codex | 코드 구현 |
+| `/analyze` | Codex | 코드 분석 / 디버깅 |
+| `/build` | Codex | 빌드 에러 수정 |
+| `/research` | Codex | 기술 리서치 |
+| `/design` | Gemini | UI/UX 디자인 |
+| `/document` | Gemini | 문서 작성 |
+| `/test` | Claude | 테스트 실행 |
+| `/explain` | Codex | 코드 설명 |
+
+[전체 커맨드 목록 →](skills/sc/SKILL.md)
+
+### 팀 오케스트레이션
+
+| 스킬 | 설명 |
+|------|------|
+| **bteam** | Codex 워커 기반 멀티 에이전트 팀 |
+| **hteam** | 하이브리드 팀 (Codex + Gemini + Claude) |
+| **kteam** | Windows 안정화 팀 변형 |
+
+### 유틸리티
+
+| 스킬 | 설명 |
+|------|------|
+| **auto-verify** | 실행 후 스킬 업데이트 + 검증 |
+| **manage-skills** | 변경사항 분석, 검증 스킬 생성/업데이트 |
+| **verify-implementation** | 전체 검증 스킬 실행, 통합 리포트 생성 |
+
+---
+
+## 아키텍처
+
+### 라우팅 전략
+
+```
+사용자 입력
+    |
+    +-- agent 지정됨? ──YES──→ [Opus 분해만] → 병렬 실행
+    |
+    NO
+    |
+    v
+[Sonnet 분류]
+  → codex (코드), gemini (UI/문서), claude (탐색/검증)
+    |
+    v
+[Opus 분해]
+  → N개 독립 서브태스크에 agent + 범위 배정
+    |
+    v
+[cli-route.sh × N 병렬 실행]
+  → 결과 수집 + 보고
+```
+
+### 에이전트 → CLI 매핑
+
+| 에이전트 | CLI | 용도 |
+|----------|-----|------|
+| executor, build-fixer, debugger | Codex | 코드 구현 / 분석 |
+| architect, planner, critic | Codex | 설계 / 계획 |
+| code-reviewer, security-reviewer | Codex | 코드 리뷰 |
+| designer, writer | Gemini | UI / 문서 |
+| explore | Claude Haiku | 코드베이스 탐색 |
+| verifier, test-engineer | Claude Sonnet | 테스트 / 검증 |
+
+### DAG 실행
+
+의존성이 있는 작업은 토폴로지 정렬 후 레벨별로 실행합니다:
+
+```
+Level 0: [리서치A] [리서치B]    ← 병렬
+Level 1: [구현]                  ← L0 완료 후
+Level 2: [테스트]                ← L1 완료 후
+```
+
+레벨 간 컨텍스트는 `.omc/context/{session}/` 파일로 전달됩니다.
+
+---
+
+## 필수 조건
+
+- [Claude Code](https://docs.anthropic.com/claude-code) CLI
+- Claude Max/Pro 구독
+
+### 선택: 멀티모델 오케스트레이션
+
+| 제공자 | 설치 | 용도 |
+|--------|------|------|
+| [Codex CLI](https://github.com/openai/codex) | `npm install -g @openai/codex` | 코드 구현, 분석, 리뷰 |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm install -g @google/gemini-cli` | 문서, UI 디자인 |
+
+**비용:** 3개 Pro 플랜 (Claude + Gemini + ChatGPT)으로 월 ~$60에 전체 커버. Codex와 Gemini 무료 티어로 대부분의 작업 처리 가능.
+
+---
+
+## Codex / Gemini 연결 설정
+
+### API 키 설정
+
+```bash
+# Codex (OpenAI)
+export OPENAI_API_KEY="sk-..."
+# 또는 Codex Pro 구독 시 자동 인증 (추가 설정 불필요)
+
+# Gemini (Google)
+export GEMINI_API_KEY="..."
+# 또는 Google AI Studio에서 gemini auth login
+```
+
+> 셸 프로필 (`~/.bashrc`, `~/.zshrc`)에 추가하면 매 세션마다 자동 로드됩니다.
+
+### 설치 확인
+
+```bash
+# Codex 확인
+codex --version
+codex exec --full-auto "echo hello"
+
+# Gemini 확인
+gemini --version
+gemini -p "echo hello"
+```
+
+### 트러블슈팅
+
+| 증상 | 원인 | 해결 |
+|------|------|------|
+| `codex: command not found` | Codex CLI 미설치 | `npm install -g @openai/codex` |
+| `gemini: command not found` | Gemini CLI 미설치 | `npm install -g @google/gemini-cli` |
+| Codex 인증 실패 | API 키 미설정 또는 만료 | `export OPENAI_API_KEY="sk-..."` |
+| Gemini 인증 실패 | API 키 미설정 | `export GEMINI_API_KEY="..."` 또는 `gemini auth login` |
+| Gemini Windows 행 | node-pty 호환 문제 | cx-skills가 자동으로 `--timeout 60` + health check 적용 |
+| `cli-route.sh: not found` | 자동 설치 실패 | `cp scripts/cli-route.sh ~/.claude/scripts/` 수동 복사 |
+| Codex 타임아웃 (300s) | 작업 범위가 너무 큼 | 작업 분할하거나 타임아웃 늘리기: `/cx-route executor "작업" implement 600` |
+| `status: failed` + stderr | CLI 실행 에러 | `/tmp/omc-route-{agent}-*-stderr.log` 확인 |
+
+### CLI 없이 사용
+
+Codex/Gemini CLI가 없어도 cx-skills는 동작합니다. 해당 CLI가 없으면 자동으로 **Claude 네이티브 에이전트로 fallback**합니다.
+
+```
+Codex 없음 → executor/debugger 등이 Claude Sonnet Agent로 실행
+Gemini 없음 → designer/writer 등이 Claude Sonnet Agent로 실행
+둘 다 없음 → 모든 작업이 Claude 네이티브로 실행 (비용 증가)
+```
+
+---
+
+## 버저닝
+
+### 현재 버전 확인
+
+```bash
+# 플러그인 버전
+cat ~/.claude/plugins/installed_plugins.json | grep -A5 cx-skills
+
+# cli-route.sh 버전
+head -6 ~/.claude/scripts/cli-route.sh | grep VERSION
+```
+
+### 버전 체계
+
+[Semantic Versioning](https://semver.org/) 준수:
+
+| 변경 유형 | 버전 | 예시 |
+|-----------|------|------|
+| 하위호환 버그 수정 | PATCH (1.0.x) | cli-route.sh 에러 핸들링 수정 |
+| 하위호환 기능 추가 | MINOR (1.x.0) | 새 스킬 추가, 새 에이전트 매핑 |
+| 호환 깨지는 변경 | MAJOR (x.0.0) | 스킬 인터페이스 변경, CLI 인자 변경 |
+
+### 변경 이력
+
+`cli-route.sh` 버전 이력:
+
+| 버전 | 변경 |
+|------|------|
+| v1.0 | 기본 라우팅 (Codex/Gemini/Claude 분기) |
+| v1.1 | stderr 분리, 출력 필터링, 타임아웃, MCP 프로필 지원 |
+| v1.2 | effort 동적 라우팅, bg/fg 모드, Opus 직접 수행, Gemini 모델 분기 |
+| v1.3 | context-file 지원, DAG 실행 연계 |
+
+### 자동 업데이트
+
+플러그인 설치 시 SessionStart 훅이 버전을 비교하여 자동 동기화합니다:
+- `cli-route.sh` → `~/.claude/scripts/cli-route.sh`
+- `hud-qos-status.mjs` → `~/.claude/hud/hud-qos-status.mjs`
+
+기존 파일보다 플러그인 버전이 새로우면 자동 덮어씁니다.
+
+---
+
+## OMC 호환성
+
+cx-skills는 **단독** 또는 **oh-my-claudecode (OMC)와 함께** 사용 가능합니다:
+
+| 구성 | 동작 |
+|------|------|
+| cx-skills만 | 전체 CLI 라우팅 — 모든 스킬 사용 가능 |
+| cx-skills + OMC | cx-skills가 CLI 라우팅 담당, OMC가 오케스트레이션(team, autopilot, ralph) 담당 |
+
+둘 다 설치되면 cx-skills가 Codex/Gemini에 대한 직접 CLI 접근을 제공하여 MCP 오버헤드를 우회합니다.
+
+---
+
+## 프로젝트 구조
+
+```
+cx-skills/
+├── .claude-plugin/        # 플러그인 등록
+│   ├── plugin.json        # 플러그인 메타데이터
+│   └── marketplace.json   # 마켓플레이스 등록
+├── .mcp.json              # MCP 서버 정의
+├── hooks/
+│   └── hooks.json         # 라이프사이클 훅 (자동 설정)
+├── scripts/
+│   ├── cli-route.sh       # CLI 라우팅 래퍼 (v1.3)
+│   └── setup.mjs          # 세션 시작 시 자동 설치
+├── skills/                # 16개 스킬 (자동 발견)
+│   ├── cx-auto/           # 통합 병렬 오케스트레이터
+│   ├── cx-route/          # 단일 에이전트 라우팅
+│   ├── sc/                # CLI 커맨드 라우터
+│   ├── bteam/             # Codex 팀
+│   ├── hteam/             # 하이브리드 팀
+│   └── ...
+├── hud/
+│   └── hud-qos-status.mjs # 상태바 HUD
+├── package.json
+├── LICENSE
+└── README.md
+```
+
+---
+
+## 업데이트
+
+```bash
+# 마켓플레이스 업데이트
+/plugin marketplace update cx-skills
+```
+
+업데이트 후 문제가 발생하면:
+```bash
+# 플러그인 재설치
+/plugin uninstall cx-skills
+/plugin install cx-skills
+```
+
+---
+
+## 라이선스
+
+MIT