@uzysjung/agent-harness 26.83.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jay (Uzys Jung)
+
+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,279 @@
+# uzys-agent-harness
+
+**Claude Code · Codex · OpenCode · Antigravity 용 트랙 기반 에이전트 하네스.**
+
+스택 트랙 하나 고르면 **검증된** 스킬 · 플러그인 · 룰을 사용자가 직접 확인·선택해 프로젝트에 세팅한다. 디폴트 install 은 **project scope** — 명시적으로 선택하지 않는 한 글로벌 영역 미수정.
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Version](https://img.shields.io/github/v/tag/uzysjung/uzys-agent-harness?label=version)](https://github.com/uzysjung/uzys-agent-harness/releases)
+[![CI](https://github.com/uzysjung/uzys-agent-harness/actions/workflows/test.yml/badge.svg)](https://github.com/uzysjung/uzys-agent-harness/actions)
+
+![agent-harness 데모 — 검증된 AI 코딩 워크플로 원커맨드 설치](https://raw.githubusercontent.com/uzysjung/uzys-agent-harness/main/docs/assets/agent-harness-demo.gif)
+
+🇺🇸 [English](./README.md)
+
+---
+
+## 설치
+
+```bash
+npx -y @uzysjung/agent-harness
+```
+
+6-step interactive wizard 가 안내. flag 필요 없음.
+
+```
+Step 1/6  Tracks            ← 스택 선택
+Step 2/6  CLI               ← claude / codex / opencode / antigravity
+Step 3/6  Install items     ← 추천 항목 (pre-checked) 확인
+Step 4/6  Scope             ← Project (default) 또는 Global
+Step 5/6  Confirm
+Step 6/6  Installing
+```
+
+설치 후:
+
+```bash
+claude
+> /uzys:spec    # step 3 에서 "uzys-harness 6-Gate workflow" 체크한 경우에만
+```
+
+---
+
+## Tracks
+
+Step 1 에서 1개 또는 multi 선택. 트랙 선택 결과로 Step 3 의 추천 항목이 결정됨.
+
+### Dev tracks
+
+| Track | Stack |
+|---|---|
+| `csr-supabase` | Vite + React + Supabase |
+| `csr-fastify` | Vite + React + Fastify |
+| `csr-fastapi` | Vite + React + FastAPI |
+| `ssr-nextjs` | Next.js (App Router) |
+| `ssr-htmx` | HTMX + server-side |
+| `data` | DuckDB + Polars + PySide6 |
+| `full` | dev 트랙 전체 union |
+
+### Business tracks
+
+| Track | 용도 |
+|---|---|
+| `executive` | 제안서, DD, 발표자료, 재무모델 |
+| `project-management` | PM 워크플로우 + 리뷰 |
+| `growth-marketing` | Growth + 콘텐츠 마케팅 |
+
+### Meta
+
+| Track | 용도 |
+|---|---|
+| `tooling` | Bash + Markdown 메타프로젝트 (앱 스택 없음) |
+
+---
+
+## 트랙별 설치 항목
+
+트랙 선택 결과로 자동 추천. Step 3 에서 pre-checked 상태로 표시 — 설치 전 자유롭게 토글.
+
+### Frontend (csr-* / ssr-nextjs / full)
+
+| Asset | What | Source |
+|---|---|---|
+| `react-best-practices` | React 패턴 + 컴포넌트 가이드 | LokeshSakthivel |
+| `shadcn-ui` | Radix 기반 컴포넌트 카피 + Tailwind 테마 | shadcn (official) |
+| `web-design-guidelines` | UX/UI best practice | LokeshSakthivel |
+| `impeccable` | UI 디자인, critique, visual review | pbakaus |
+| `next-skills` (ssr-nextjs only) | Next.js App Router 패턴 | vercel-labs |
+
+### Backend (csr-* / ssr-* / full)
+
+| Asset | What | Source |
+|---|---|---|
+| `railway-skills` | Railway 배포 + project/service/env 관리 | Railway 공식 |
+| `supabase-agent-skills` (csr-supabase) | Supabase agent skills | Supabase 공식 |
+| `postgres-best-practices` (csr-supabase) | Postgres 패턴 | Supabase 공식 |
+| `supabase-cli` (csr-supabase) | Supabase CLI (`supabase login` OAuth 필요) | npm |
+| `vercel-cli` (csr-supabase) | Vercel CLI | npm |
+| `netlify-cli` (csr-supabase) | Netlify CLI | npm |
+
+### Data (data / full)
+
+| Asset | What | Source |
+|---|---|---|
+| `polars-K-Dense` | Polars — Rust 기반 fast DataFrame (pandas 대안) | K-Dense-AI |
+| `dask-K-Dense` | Dask — 분산 처리 | K-Dense-AI |
+| `python-resource-management` | 메모리 / CPU 관리 패턴 | wshobson |
+| `python-performance-optimization` | 프로파일링 + vectorize | wshobson |
+| `anthropic-data-plugin` | 시각화 + SQL exploration | Anthropic 공식 |
+
+### Business (executive / project-management / growth-marketing)
+
+| Asset | What | Source | Tracks |
+|---|---|---|---|
+| `anthropic-document-skills` | pptx / docx / xlsx / pdf 작성 | Anthropic | executive · full |
+| `c-level-skills` | 28 advisory skills (CEO/CFO/COO) | claude-code-skills | executive · full |
+| `business-growth-skills` | Growth · finance · marketing 플레이북 | claude-code-skills | executive · full · growth-marketing |
+| `finance-skills` | 재무 모델 | claude-code-skills | executive · full |
+| `pm-skills` | PM 워크플로우 | claude-code-skills | project-management |
+| `product-skills` | Product discovery + delivery | claude-code-skills | dev + PM |
+| `marketing-skills` / `content-creator` / `demand-gen` / `research-summarizer` | 마케팅 플레이북 | claude-code-skills | growth-marketing |
+
+### Dev Tools (모든 dev tracks)
+
+| Asset | What | Source |
+|---|---|---|
+| `playwright-skill` | Playwright E2E 테스트 작성 | testdino-hq |
+| `find-skills` | 설치된 skills 검색 · ranking | vercel-labs |
+| `agent-browser` | 에이전트용 브라우저 자동화 CLI | npm |
+| `architecture-decision-record` | ADR 작성 | yonatangross |
+| `karpathy-coder` | Pre-commit quality gate hook | claude-code-skills |
+| `product-skills` | Product engineering | claude-code-skills |
+
+### Workflow (opt-in — step 3 에서 선택)
+
+| Asset | What | 활성 시 |
+|---|---|---|
+| `uzys-harness 6-Gate workflow` | `/uzys:spec` → `/uzys:plan` → `/uzys:build` → `/uzys:test` → `/uzys:review` → `/uzys:ship` (hook 으로 게이트 강제) | 6-gate workflow (아래 참조) |
+| `addy-agent-skills` | `/spec` `/plan` `/build` `/test` `/review` `/ship` `/code-simplify` | addyosmani 워크플로우 |
+| `superpowers` | Agentic skills 프레임워크 (Anthropic 공식 marketplace) | obra/superpowers |
+| `gsd-orchestrator` | 대형 프로젝트 오케스트레이션 | get-shit-done-cc |
+
+### Security & ECC (opt-in)
+
+| Asset | What | Source |
+|---|---|---|
+| `trailofbits-skills` | Differential 보안 리뷰 | Trail of Bits |
+| `ecc-plugin` | ECC plugin (`prune-ecc.sh` 로 project-scoped) | affaan-m |
+| `ecc-prune` | ECC 를 curated 셋 (4 agents + 8 skills + 3 commands) 으로 trim | 본 프로젝트 |
+
+---
+
+## Trust tiers (검증 등급)
+
+모든 외부 자산은 **trust tier** 를 가지며 Step 3 에서 배지로 표시된다:
+
+- **★ official** — Anthropic 공식 marketplace + 본 하네스 자체 자산.
+- **vetted** — GitHub star ≥ 1000 + 활성 유지보수 커뮤니티 자산. track 적합 시 pre-checked.
+- **⚠ experimental** — star 1000 미만. opt-in 만 (pre-check 안 함), 카테고리 하단 표시.
+
+tier 는 **정보 제공일 뿐 차단하지 않는다** — 최종 선택은 항상 사용자. 권장 자산(official/vetted + track 적합)이 상단 정렬.
+
+---
+
+## 6-Gate workflow (opt-in 시에만)
+
+6-gate workflow 는 **default OFF**. Step 3 에서 `uzys-harness 6-Gate workflow` 체크 시 활성 (또는 비대화형 `--with uzys-harness`).
+
+```
+/uzys:spec → /uzys:plan → /uzys:build → /uzys:test → /uzys:review → /uzys:ship
+```
+
+| Gate | 목적 |
+|---|---|
+| `/uzys:spec` | 코드 이전 build 대상 정의 |
+| `/uzys:plan` | spec → 작고 검증 가능한 task 분해 |
+| `/uzys:build` | 점진적 구현 |
+| `/uzys:test` | 동작 증명 |
+| `/uzys:review` | 다중 관점 코드/보안 리뷰 |
+| `/uzys:ship` | 프리런치 체크리스트 + 배포 |
+
+각 게이트는 `.claude/hooks/` 의 hook 으로 강제. 이전 게이트 미완료 시 다음 게이트 fail (exit code 2). opt-in 안 했으면 `/uzys:*` 커맨드 미설치, hook 비활성 — 트랙의 다른 자산은 그대로 사용 가능.
+
+---
+
+## Scope
+
+Step 4 에서 install write 위치 선택.
+
+| | Project (default) | Global (opt-in) |
+|---|---|---|
+| `claude plugin` | `--scope project` (`installed_plugins.json` 의 `projectPath` 로 격리) | `--scope user` |
+| `npx skills` | project `node_modules` | `-g` (user-level) |
+| `npm` | `--save-dev` (devDependency) | `-g` |
+| Codex (prompts / skills / config) | 프로젝트 `.codex/` | `~/.codex/` |
+| Antigravity (skills / workflows) | 프로젝트 `.agents/` | `~/.gemini/antigravity/` |
+| `~/.claude/skills/` · `~/.codex/` · `~/.opencode/` · `~/.gemini/` · `npm root -g` | **미수정** | 자산별 write |
+
+Project scope 는 install 을 본 레포에 가둠. 동일 머신의 다른 프로젝트는 영향 받지 않음.
+
+Claude CLI 자체는 scope 와 무관하게 `~/.claude/plugins/cache/` 에 plugin 파일을 write — 단 `installed_plugins.json` 메타데이터가 `projectPath` 로 격리하므로 다른 프로젝트에서 안 보임.
+
+---
+
+## Uninstall
+
+```bash
+npx -y @uzysjung/agent-harness uninstall
+```
+
+`.claude/.harness-install.json` (install 시 생성) 을 읽어 자동 reverse.
+
+- Project-scope 자산: 자동 제거 (`claude plugin uninstall --scope project`, `npm uninstall --save-dev`, `.codex/` cleanup 등).
+- 프로젝트 루트 `CLAUDE.md`: install 시점과 내용이 동일할 때만 제거 (sha256). 설치 후 직접 수정했다면 안내와 함께 보존.
+- Global-scope 자산: advisory 만 출력 — 사용자가 직접 제거. uninstall 이 명시적 동의 없이 다른 프로젝트나 글로벌 설정을 절대 안 건드림.
+
+Flag:
+
+| Flag | What |
+|---|---|
+| `--dry-run` | reverse list 만 출력, 변경 없음 |
+| `--keep-templates` | external 자산만 제거, `.claude/`, `.codex/`, `.opencode/` 보존 |
+
+---
+
+## 동작 방식
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  npx agent-harness                                      │
+│         │                                                │
+│         ▼                                                │
+│  ┌─ 6-step wizard ──────────────────────────────────┐    │
+│  │  Track(s) → CLI(s) → Items → Scope → Confirm    │    │
+│  └──────────────────┬───────────────────────────────┘    │
+│                     ▼                                    │
+│  ┌─ Phase 1: Templates ─────────────────────────────┐    │
+│  │  .claude/{rules,agents,hooks,commands,skills}    │    │
+│  │  CLAUDE.md (merged) · .mcp.json                  │    │
+│  └──────────────────┬───────────────────────────────┘    │
+│                     ▼                                    │
+│  ┌─ Phase 2: External assets ───────────────────────┐    │
+│  │  claude plugin / npx skills / npm / shell-script │    │
+│  │  Step 4 에서 선택한 scope 따름                    │    │
+│  └──────────────────┬───────────────────────────────┘    │
+│                     ▼                                    │
+│  ┌─ Phase 3: install log ───────────────────────────┐    │
+│  │  .claude/.harness-install.json                   │    │
+│  │  (uninstall 의 source)                           │    │
+│  └──────────────────────────────────────────────────┘    │
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## CLI 지원
+
+| CLI | 지원 |
+|---|---|
+| Claude Code | First class — 모든 자산 + hook |
+| Codex (OpenAI) | Skills + `AGENTS.md`. 슬래시 프롬프트 `/uzys-*` 는 global `~/.codex/prompts/`(opt-in)에서 작동; project `.codex/prompts/` 는 upstream [#9848](https://github.com/openai/codex/issues/9848) 대비 pre-position (아직 미작동) |
+| OpenCode | Skills + AGENTS.md 통합 |
+| Antigravity (Google) | Project: `.agents/rules/` (context, 항상) + `.agents/skills/` + `.agents/workflows/` (6-Gate opt-in). Global (opt-in `--with-antigravity-global` + `--scope global`): `~/.gemini/antigravity/{skills,global_workflows}/uzys-*` (v26.66.0+) |
+
+Step 2 에서 1개 또는 multi 선택.
+
+---
+
+## 심화
+
+- [docs/USAGE.md](./docs/USAGE.md) — 워크플로우 상세, install 내부, CI flag, ECC 통합, Codex/OpenCode 설정
+- [docs/NORTH_STAR.md](./docs/NORTH_STAR.md) — 디자인 원칙
+- [docs/decisions/](./docs/decisions/) — ADR (아키텍처 결정)
+- [docs/REFERENCE.md](./docs/REFERENCE.md) — 트랙별 자산 매트릭스 상세
+
+---
+
+## License
+
+MIT.

package/README.md

@@ -0,0 +1,306 @@
+# uzys-agent-harness
+
+**Track-based agent harness for Claude Code, Codex, OpenCode, and Antigravity.**
+
+Pick a stack track. Get a curated set of **vetted** skills, plugins, and rules — you review and choose what installs — wired into your project. Project scope by default; no global pollution unless you ask.
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Version](https://img.shields.io/github/v/tag/uzysjung/uzys-agent-harness?label=version)](https://github.com/uzysjung/uzys-agent-harness/releases)
+[![CI](https://github.com/uzysjung/uzys-agent-harness/actions/workflows/test.yml/badge.svg)](https://github.com/uzysjung/uzys-agent-harness/actions)
+
+![agent-harness demo — one-command install of vetted AI-coding workflows](https://raw.githubusercontent.com/uzysjung/uzys-agent-harness/main/docs/assets/agent-harness-demo.gif)
+
+🇰🇷 [한국어](./README.ko.md)
+
+---
+
+## Install
+
+```bash
+npx -y @uzysjung/agent-harness
+```
+
+A 6-step interactive wizard guides everything. No flags needed.
+
+```
+Step 1/6  Tracks            ← pick your stack
+Step 2/6  CLI               ← claude / codex / opencode / antigravity
+Step 3/6  Install items     ← review pre-checked recommendations
+Step 4/6  Scope             ← Project (default) or Global
+Step 5/6  Confirm
+Step 6/6  Installing
+```
+
+After install:
+
+```bash
+claude
+> /uzys:spec    # only if you checked "uzys-harness 6-Gate workflow" in step 3
+```
+
+### Non-interactive install (CI / scripts / Docker)
+
+The wizard needs a TTY. For CI pipelines, onboarding scripts, or containers, use flags — the same path our own verification CI runs on:
+
+```bash
+npx -y @uzysjung/agent-harness install \
+  --track tooling --cli claude --scope project \
+  --with uzys-harness --with bmad-method
+```
+
+| Flag | Meaning |
+|------|---------|
+| `--track <name>` | Track to install (repeatable) |
+| `--cli <target>` | `claude` / `codex` / `opencode` / `antigravity` (repeatable) |
+| `--scope <s>` | `project` (default) or `global` |
+| `--with <asset-id>` / `--without <asset-id>` | Add / remove any catalog asset by id (repeatable) — ids in the [compatibility matrix](docs/COMPATIBILITY.md) |
+
+> v26.81.0 (ADR-022): per-asset flags like `--with-bmad` were removed — `--with <asset-id>` is the single opt-in surface. Behavior flags (`--with-karpathy-hook`, `--with-codex-prompts`, `--with-antigravity-global`, `--with-prune`, …) remain.
+
+---
+
+## Tracks
+
+Pick one or more at step 1. Each track determines which skills/plugins/rules are pre-checked in step 3.
+
+### Dev tracks
+
+| Track | Stack |
+|---|---|
+| `csr-supabase` | Vite + React + Supabase |
+| `csr-fastify` | Vite + React + Fastify |
+| `csr-fastapi` | Vite + React + FastAPI |
+| `ssr-nextjs` | Next.js (App Router) |
+| `ssr-htmx` | HTMX + server-side |
+| `data` | DuckDB + Polars + PySide6 |
+| `full` | union of all dev tracks |
+
+### Business tracks
+
+| Track | Use |
+|---|---|
+| `executive` | proposals, due diligence, decks, financial models |
+| `project-management` | PM workflow + reviews |
+| `growth-marketing` | growth + content marketing |
+
+### Meta
+
+| Track | Use |
+|---|---|
+| `tooling` | Bash + Markdown meta-projects (no app stack) |
+
+---
+
+## What gets installed per track
+
+External assets are recommended automatically based on your track selection. Step 3 shows them pre-checked; you can toggle anything before install.
+
+### Frontend (csr-* / ssr-nextjs / full)
+
+| Asset | What | Source |
+|---|---|---|
+| `react-best-practices` | React patterns and component guidelines | LokeshSakthivel |
+| `shadcn-ui` | Radix-based component copy + Tailwind theme | shadcn (official) |
+| `web-design-guidelines` | UX/UI best practices | LokeshSakthivel |
+| `impeccable` | UI design, critique, and visual review skills | pbakaus |
+| `next-skills` (ssr-nextjs only) | Next.js App Router patterns | vercel-labs |
+
+### Backend (csr-* / ssr-* / full)
+
+| Asset | What | Source |
+|---|---|---|
+| `railway-skills` | Railway deploy + project/service/env management | Railway official |
+| `supabase-agent-skills` (csr-supabase) | Supabase agent skills | Supabase official |
+| `postgres-best-practices` (csr-supabase) | Postgres patterns | Supabase official |
+| `supabase-cli` (csr-supabase) | Supabase CLI (`supabase login` for OAuth) | npm |
+| `vercel-cli` (csr-supabase) | Vercel CLI | npm |
+| `netlify-cli` (csr-supabase) | Netlify CLI | npm |
+
+### Data (data / full)
+
+| Asset | What | Source |
+|---|---|---|
+| `polars-K-Dense` | Polars — fast Rust DataFrame (pandas alternative) | K-Dense-AI |
+| `dask-K-Dense` | Dask — distributed processing | K-Dense-AI |
+| `python-resource-management` | Memory / CPU management patterns | wshobson |
+| `python-performance-optimization` | Profiling + vectorization | wshobson |
+| `anthropic-data-plugin` | Visualization + SQL exploration | Anthropic official |
+
+### Business (executive / project-management / growth-marketing)
+
+| Asset | What | Source | Tracks |
+|---|---|---|---|
+| `anthropic-document-skills` | pptx / docx / xlsx / pdf authoring | Anthropic | executive · full |
+| `c-level-skills` | 28 advisory skills (CEO/CFO/COO) | claude-code-skills | executive · full |
+| `business-growth-skills` | Growth, finance, marketing playbooks | claude-code-skills | executive · full · growth-marketing |
+| `finance-skills` | Financial models | claude-code-skills | executive · full |
+| `pm-skills` | PM workflows | claude-code-skills | project-management |
+| `product-skills` | Product discovery + delivery | claude-code-skills | dev + PM |
+| `marketing-skills` / `content-creator` / `demand-gen` / `research-summarizer` | Marketing playbooks | claude-code-skills | growth-marketing |
+
+### Dev Tools (all dev tracks)
+
+| Asset | What | Source |
+|---|---|---|
+| `playwright-skill` | E2E test authoring with Playwright | testdino-hq |
+| `find-skills` | Search and rank installed skills | vercel-labs |
+| `agent-browser` | Browser automation CLI for agents | npm |
+| `architecture-decision-record` | ADR authoring | yonatangross |
+| `karpathy-coder` | Pre-commit quality gate hook | claude-code-skills |
+| `product-skills` | Product engineering | claude-code-skills |
+
+### Workflow (opt-in — pick one or more at step 3)
+
+> **Which one?** See the [Workflow curation guide](docs/WORKFLOWS.md) — a vetted comparison of all 8 installable workflows (plus honest pointers to Spec Kit / Kiro, which we recommend but don't auto-install).
+
+| Asset | What | Activates |
+|---|---|---|
+| `uzys-harness 6-Gate workflow` | `/uzys:spec` → `/uzys:plan` → `/uzys:build` → `/uzys:test` → `/uzys:review` → `/uzys:ship` with hook-enforced gates | The 6-gate flow described below |
+| `superpowers` | Agentic skills framework, Anthropic official marketplace | obra/superpowers |
+| `ecc-plugin` | 60 agents · 230 skills · 75 commands | affaan-m |
+| `gsd-orchestrator` | Orchestration for large projects | get-shit-done-cc |
+| `openspec` | Spec-driven brownfield delta workflow (propose → apply → archive) | Fission-AI |
+| `bmad-method` | Multi-agent agile workflow (PM/Architect/Dev, 12+ agents) | bmad-code-org |
+| `addy-agent-skills` | `/spec` `/plan` `/build` `/test` `/review` `/ship` `/code-simplify` skills | addyosmani's workflow |
+| `wshobson-agents` | Multi-agent orchestration workflows (full-stack/tdd/review), cross-CLI | wshobson |
+
+### Security & ECC (opt-in)
+
+| Asset | What | Source |
+|---|---|---|
+| `trailofbits-skills` | Differential security review | Trail of Bits |
+| `ecc-plugin` | ECC plugin (project-scoped via `prune-ecc.sh`) | affaan-m |
+| `ecc-prune` | Trim ECC down to a curated set (4 agents + 8 skills + 3 commands) | this project |
+
+---
+
+## Trust tiers
+
+Every external asset carries a **trust tier**, shown as a badge in step 3:
+
+- **★ official** — Anthropic-official marketplaces + this harness's own assets.
+- **vetted** — community assets with ≥ 1000 GitHub stars and active maintenance. Pre-checked when they match your track.
+- **⚠ experimental** — under 1000 stars. Opt-in only (not pre-checked), listed at the bottom of each category.
+
+Tiers **inform, never block** — you always review and choose what installs. Recommended assets (official/vetted matching your track) sort to the top.
+
+> **How is "verified" backed up?** See the [Compatibility & verification matrix](docs/COMPATIBILITY.md) — install methods are checked against real registries/marketplaces, and the core workflow set is verified by **real install in an isolated Docker container** (not a static table). Trust tiers are auto-monitored for star-drift monthly.
+
+---
+
+## 6-Gate workflow (only if you opt in)
+
+The 6-gate workflow is **off by default**. To enable it, check `uzys-harness 6-Gate workflow` at step 3 (or pass `--with uzys-harness` for non-interactive install).
+
+```
+/uzys:spec → /uzys:plan → /uzys:build → /uzys:test → /uzys:review → /uzys:ship
+```
+
+| Gate | Purpose |
+|---|---|
+| `/uzys:spec` | Define what you're building before code |
+| `/uzys:plan` | Decompose the spec into small, verifiable tasks |
+| `/uzys:build` | Implement incrementally |
+| `/uzys:test` | Prove it works |
+| `/uzys:review` | Multi-perspective code/security review |
+| `/uzys:ship` | Pre-launch checklist + deploy |
+
+Gates are enforced by hooks installed under `.claude/hooks/`. Skipping a gate fails the next one (exit code 2). If you didn't opt in, `/uzys:*` commands aren't installed and the hooks aren't active — you get the rest of the track's assets without the gating.
+
+---
+
+## Scope
+
+Step 4 asks where the install writes.
+
+| | Project (default) | Global (opt-in) |
+|---|---|---|
+| `claude plugin` | `--scope project` (entries isolated by `projectPath` in `installed_plugins.json`) | `--scope user` |
+| `npx skills` | project `node_modules` | `-g` (user-level) |
+| `npm` | `--save-dev` (devDependency) | `-g` |
+| Codex (prompts / skills / config) | `.codex/` in your project | `~/.codex/` |
+| Antigravity (skills / workflows) | `.agents/` in your project | `~/.gemini/antigravity/` |
+| `~/.claude/skills/` · `~/.codex/` · `~/.opencode/` · `~/.gemini/` · `npm root -g` | **not touched** | written per asset |
+
+Project scope keeps the install confined to your repo. Other projects on the same machine are unaffected.
+
+Claude CLI itself writes plugin cache under `~/.claude/plugins/cache/` regardless of scope — but the metadata in `installed_plugins.json` isolates entries by `projectPath`, so other projects don't see them.
+
+---
+
+## Uninstall
+
+```bash
+npx -y @uzysjung/agent-harness uninstall
+```
+
+Reads `.claude/.harness-install.json` (created during install) and reverses what was installed.
+
+- Project-scope assets: removed automatically (`claude plugin uninstall --scope project`, `npm uninstall --save-dev`, `.codex/` cleanup, etc.).
+- Project root `CLAUDE.md`: removed only if it still matches the installed version (sha256); kept with a notice if you've edited it since install.
+- Global-scope assets: listed as advisory only — you remove them yourself. Uninstall never touches another project or your global config without explicit action.
+
+Flags:
+
+| Flag | What |
+|---|---|
+| `--dry-run` | List reverse steps, change nothing |
+| `--keep-templates` | Remove external assets but keep `.claude/`, `.codex/`, `.opencode/` |
+
+---
+
+## How it works
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  npx agent-harness                                      │
+│         │                                                │
+│         ▼                                                │
+│  ┌─ 6-step wizard ──────────────────────────────────┐    │
+│  │  Track(s) → CLI(s) → Items → Scope → Confirm    │    │
+│  └──────────────────┬───────────────────────────────┘    │
+│                     ▼                                    │
+│  ┌─ Phase 1: Templates ─────────────────────────────┐    │
+│  │  .claude/{rules,agents,hooks,commands,skills}    │    │
+│  │  CLAUDE.md (merged) · .mcp.json                  │    │
+│  └──────────────────┬───────────────────────────────┘    │
+│                     ▼                                    │
+│  ┌─ Phase 2: External assets ───────────────────────┐    │
+│  │  claude plugin / npx skills / npm / shell-script │    │
+│  │  Honors the scope chosen at step 4               │    │
+│  └──────────────────┬───────────────────────────────┘    │
+│                     ▼                                    │
+│  ┌─ Phase 3: install log ───────────────────────────┐    │
+│  │  .claude/.harness-install.json                   │    │
+│  │  (drives `uninstall`)                            │    │
+│  └──────────────────────────────────────────────────┘    │
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## CLI support
+
+| CLI | Status |
+|---|---|
+| Claude Code | First class — all assets and hooks |
+| Codex (OpenAI) | Skills + `AGENTS.md`. Slash prompts `/uzys-*` work via global `~/.codex/prompts/` (opt-in); project `.codex/prompts/` is pre-positioned for upstream [#9848](https://github.com/openai/codex/issues/9848) (not active yet) |
+| OpenCode | Skills + AGENTS.md integration |
+| Antigravity (Google) | Project: `.agents/rules/` (context, always) + `.agents/skills/` + `.agents/workflows/` (6-Gate opt-in). Global (opt-in via `--with-antigravity-global` + `--scope global`): `~/.gemini/antigravity/{skills,global_workflows}/uzys-*` (v26.66.0+) |
+
+Pick one or more at step 2.
+
+---
+
+## Advanced
+
+- [docs/USAGE.md](./docs/USAGE.md) — workflow detail, install internals, CI flags, ECC integration, Codex/OpenCode setup
+- [docs/NORTH_STAR.md](./docs/NORTH_STAR.md) — design principles
+- [docs/decisions/](./docs/decisions/) — ADRs (architecture decisions)
+- [docs/REFERENCE.md](./docs/REFERENCE.md) — per-track asset matrix in detail
+
+---
+
+## License
+
+MIT.