solmate-skills 2.0.11 → 2.0.13

package/AGENTS.md

@@ -99,6 +99,15 @@
 - **프로토타입 예외**: 프로토타입·스파이크·탐색 단계에서는 차단 조건이 아니라 기록성 체크로 적용한다.
 - **안전 예외**: 검증, 인증·인가, 에러 처리, 접근성, 보안, 데이터 보존, 테스트 가능성은 단순화를 이유로 제거하지 않는다.
 
+### 3.3. Agent Harness Gate (Context / Implementation / Verification)
+- **정본 위치**: 역할·권한·인계·Receipt 상세 형식은 `rules-workflow/resources/agent-harness-contract.md`를 따른다.
+- **적용 범위**: `Work Type`이 `code` 또는 `deploy`인 백로그 작업에 필수로 적용한다. `docs`, `prototype`은 기록성 체크로 적용한다.
+- **구현 전 차단**: `blocking` 모드에서는 읽기 전용 Context Agent가 모든 Related 문서를 읽고 PASS Context Receipt를 남기지 않으면 구현을 시작할 수 없다.
+- **완료 전 차단**: `blocking` 모드에서는 읽기 전용 Verification Agent가 명령 결과와 QA 문서 또는 PR 근거를 포함한 PASS Verification Receipt를 남기지 않으면 Done, PR, merge, publish, deploy로 이동할 수 없다.
+- **역할 분리**: Implementation Agent가 작성한 Change Receipt는 독립 검증이 아니다. Verification Agent는 발견 사항을 직접 수정하지 않고 Coordinator를 통해 Implementation Agent로 반환한다.
+- **Claude와 Codex**: Claude Code는 `.claude/agents/solmate-*.md`를 사용한다. Codex는 `rules-workflow` 정본을 사용 가능한 subagent 또는 별도 task에 전달한다.
+- **강제 수준**: 처음 5개 실제 작업은 `warning` 결과를 기록하고 사용자 확인 후 진행한다. 이후 `npx solmate-skills preflight TASK-ID --strict`와 `npx solmate-skills verify TASK-ID --strict`를 차단 게이트로 사용한다.
+
 ## 4. Skills & AI Capabilities
 AI 에이전트는 본 프로젝트에 설치된 다음 **26개 스킬**을 활용하여 작업을 수행하며, 모든 작업 결과물은 이 스킬들의 검증 가이드를 통과해야 한다.
 
@@ -160,3 +169,5 @@ AI 에이전트는 사용자가 스킬을 호출하지 않아도, 아래 상황
 
 ## 6. 최종 약속
 AI 에이전트는 본 **AGENTS.md**를 모든 판단의 최우선 근거로 삼는다. 문서에 정의되지 않은 작업을 수행할 경우 반드시 사용자에게 구현 전 문서 업데이트 필요성을 먼저 확인한다.
+
+**사람용 스킬 사용법** (상황별 선택, 26개 카탈로그, Gate 상세): 프로젝트 루트 `USAGE.md` — 영문 기본, 하단 한국어 (`npx solmate-skills install` 시 복사).

package/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What This Repo Is
 
-`solmate-skills` is an npm package that ships curated AI skill files (SKILL.md) to downstream projects. It is **not** an application — it is a skill library and CLI tool. Each top-level directory (except `bin/`) is a skill that gets copied into `.agent/skills/<skill-name>` of a target project.
+`solmate-skills` is an npm package that ships curated AI skill files (SKILL.md) to downstream projects. It is **not** an application — it is a skill library and CLI tool. Each installable top-level directory contains `SKILL.md` and is copied into `.agent/skills/<skill-name>` of a target project.
 
 ## CLI Commands
 
@@ -17,13 +17,20 @@ npx solmate-skills install <skill-name>
 
 # Install all skills
 npx solmate-skills@latest install all
+
+# Refresh native Claude project agents
+npx solmate-skills@latest install agents
+
+# Check backlog context and verification receipts
+npx solmate-skills preflight TASK-000 --strict
+npx solmate-skills verify TASK-000 --strict
 ```
 
-There are no build, test, or lint scripts in this repo (`"test": "echo \"Error: no test specified\" && exit 1"`).
+Run `npm test` to validate the harness receipt parser and blocking behavior. There is no build or lint script.
 
 ## Installing Skills via Symlink (Dev)
 
-`init-skills.sh` creates symlinks from a target project's `.agent/skills/` to this repo, and links `AGENTS.md` to the project root. Run it from inside the target project:
+`init-skills.sh` creates symlinks from a target project's `.agent/skills/` to this repo, links `AGENTS.md` and `USAGE.md` to the project root, and links the namespaced Claude project agents under `.claude/agents/`. Run it from inside the target project:
 
 ```bash
 bash /Users/namhyeongseog/Documents/solmate-skills/init-skills.sh
@@ -33,6 +40,7 @@ bash /Users/namhyeongseog/Documents/solmate-skills/init-skills.sh
 
 ```
 bin/cli.js          — CLI entrypoint; discovers skills as top-level dirs, copies them to .agent/skills/
+bin/harness-check.js — Backlog Context/Verification Receipt parser and blocking checks
 AGENTS.md           — Global AI collaboration rules (linked into target projects)
 init-skills.sh      — Symlink installer for local development
 <skill-name>/
@@ -40,6 +48,7 @@ init-skills.sh      — Symlink installer for local development
   templates/        — (optional) document templates
   resources/        — (optional) reference files
   examples/         — (optional) example outputs
+  adapters/         — (optional) runtime-specific thin adapters; canonical policy remains in resources/
 ```
 
 Skills discovered by `bin/cli.js` = any top-level directory not in `IGNORED_FOLDERS` (`bin`, `node_modules`, `.git`, `.github`, `.gemini`, `.agent`).
@@ -61,6 +70,7 @@ Skills discovered by `bin/cli.js` = any top-level directory not in `IGNORED_FOLD
 - **Conventional Commits in Korean**: `type(scope): 한글 요약` (e.g. `feat(login): 소셜 로그인 API 연동`).
 - **5-Layer doc structure**: `docs/01_Concept_Design/`, `02_UI_Screens/`, `03_Technical_Specs/`, `04_Logic_Progress/`, `05_QA_Validation/`.
 - **Backlogs and roadmaps** belong exclusively in `docs/04_Logic_Progress/`.
+- **Agent Harness Gate**: code/deploy work requires a passing Context Receipt before implementation and an independent Verification Receipt before completion or release.
 
 ## Skill Categories
 

package/README.md

@@ -1,8 +1,8 @@
 # solmate-skills
 
-Reusable AI-agent skills for disciplined product work.
+Reusable AI-agent harness and workflow skills for disciplined product work.
 
-`solmate-skills` packages the Solmate workflow as installable skills: plan the product, create browser-viewable UI previews, lock backlog tasks to their source documents, plan components and libraries before coding, implement with YAGNI/KISS/DRY approval gates, and verify the result before release.
+`solmate-skills` packages the Solmate workflow as installable skills: plan the product, create browser-viewable UI previews, lock backlog tasks to their source documents, prove that required context was read, plan components and libraries before coding, implement with YAGNI/KISS/DRY approval gates, and independently verify the result before release.
 
 Use it when you want an AI coding agent to follow a shared workflow instead of improvising project structure, documentation, implementation order, and QA.
 
@@ -22,9 +22,14 @@ npx solmate-skills@latest install rules-product
 
 # Install proactive hook suggestions for Claude Code projects
 npx solmate-skills@latest install hooks
+
+# Refresh native Claude agents for the shared harness
+npx solmate-skills@latest install agents
 ```
 
-The installer copies each selected skill folder into `.agent/skills/<skill-name>` in your current project.
+The installer copies each selected skill folder into `.agent/skills/<skill-name>` in your current project and copies [USAGE.md](./USAGE.md) to the project root. Installing `rules-workflow` or `all` also installs the namespaced Claude project agents under `.claude/agents/`; Codex uses the same canonical contract through `rules-workflow`, reinforced by `AGENTS.md` when that file is linked into the project.
+
+**Detailed usage:** see `USAGE.md` at the project root (English default, Korean below) for the situation-to-skill cheat sheet, orchestrator map, full skill catalog (26 skills), gate details, and recommended prompts.
 
 ## What You Get
 
@@ -35,8 +40,92 @@ The installer copies each selected skill folder into `.agent/skills/<skill-name>
 - **Component & Library Planning Gate**: React work must name the shadcn/ui components, custom components, reused components, libraries to add, libraries to avoid, and preset action before coding.
 - **YAGNI/KISS/DRY Gate**: `rules-dev` is the canonical source for avoiding future-only features, preferring the simplest existing/native path, and removing only true duplicate knowledge.
 - **Implementation workflow**: `/rules-workflow` keeps coding work tied to approved documents, preconditions, and acceptance criteria.
+- **Agent harness**: a read-only Context Agent proves required documents were read, an Implementation Agent returns a scoped change summary, and a read-only Verification Agent provides independent evidence before completion.
+- **Machine-checkable receipts**: `preflight TASK-ID` checks linked document coverage and `verify TASK-ID` checks command results plus QA/PR evidence; `--strict` turns findings into blocking exit codes.
+- **Versioned harness artifacts**: `validate-harness` checks v1 task manifests, structured messages, ordered state events, role activation, evidence gates, and exclusive write ownership.
 - **Release verification**: `/verify-implementation` runs the verification family for docs, UI, code, security, performance, DB schema, and skill package readiness.
 
+## What's New in 2.0.13: Agent Harness Contracts
+
+`solmate-skills@2.0.13` strengthens the existing Solmate workflow with a shared Claude/Codex agent harness. It addresses two recurring failure modes in long AI-assisted projects:
+
+1. An implementation starts from a backlog item without reading the linked concept, UI, technical, and QA documents.
+2. An agent marks work complete based only on its own summary, without independent verification evidence.
+
+The harness makes both boundaries explicit and machine-checkable while preserving the existing skill installation and backlog format.
+
+### How the harness works
+
+```text
+Coordinator
+  -> read-only Context Agent -> Context Receipt
+  -> Implementation Agent    -> Change Receipt
+  -> read-only QA Inspector   -> Verification Receipt
+  -> Done / PR / merge / publish / deploy
+```
+
+- **Context Receipt** records every required backlog reference that was read, the extracted constraints, and any conflict found before implementation.
+- **Change Receipt** records changed files, covered requirements, excluded scope, checks, and remaining risks. It is a handoff, not independent proof.
+- **Verification Receipt** records commands, results, unrun checks, detailed QA evidence, and the independent PASS/FAIL decision.
+- Code and deploy tasks are blocked from implementation without Context evidence and from completion without Verification evidence. Documentation and prototype work remain advisory.
+
+The canonical contract lives at [`rules-workflow/resources/agent-harness-contract.md`](./rules-workflow/resources/agent-harness-contract.md).
+
+### Backlog Receipt checks
+
+Existing projects can keep their current `00_BACKLOG.md` workflow and add the checks incrementally:
+
+```bash
+# Confirm required linked documents were read before coding
+npx solmate-skills preflight TASK-000
+
+# Confirm independent command and QA/PR evidence before completion
+npx solmate-skills verify TASK-000
+
+# Turn findings into blocking exit codes for CI or release gates
+npx solmate-skills preflight TASK-000 --strict
+npx solmate-skills verify TASK-000 --strict
+```
+
+### Versioned manifest, message, and event checks
+
+Projects that need structured multi-agent coordination can opt into the v1 contract without rewriting existing backlog Receipts:
+
+```bash
+npx solmate-skills validate-harness manifest _workspace/harness/TASK-000/manifest.json
+npx solmate-skills validate-harness message _workspace/harness/TASK-000/attempt-01/messages/msg-001.json \
+  --manifest _workspace/harness/TASK-000/manifest.json
+npx solmate-skills validate-harness events _workspace/harness/TASK-000/events.jsonl \
+  --manifest _workspace/harness/TASK-000/manifest.json
+```
+
+[`agent-harness-v1.schema.json`](./rules-workflow/resources/agent-harness-v1.schema.json) defines the manifest, message, and state-event shapes. The validator additionally checks task identity, legal state transitions, active roles, message authority, required evidence, canonical file paths, and exclusive write ownership.
+
+| Mode / result | Exit code | Behavior |
+|:---|:---:|:---|
+| Default warning mode, valid | `0` | Reports PASS |
+| Default warning mode, contract finding | `0` | Reports findings without blocking migration |
+| `--strict`, contract finding | `1` | Blocks the workflow or CI step |
+| Invalid command input, unreadable file, malformed JSON/JSONL | `2` | Reports an operational error |
+
+### Compatibility and current scope
+
+- Existing `preflight`, `verify`, and backlog Receipt fixtures continue to work without structured artifact files.
+- The structured v1 contract is opt-in and warning-first; projects can move to `--strict` after a real-task pilot.
+- The implementation uses the Node standard library and adds no runtime dependency.
+- Claude Code can install the current namespaced `solmate-*` project agents with `install agents`; Codex follows the same canonical contract through its available delegation mechanism.
+- Specialist personas, runtime orchestration, persistent recovery, pilot automation, and blocking rollout remain separate follow-up work.
+- This release ships the contract and validation foundation; specialist personas and runtime orchestration remain separately gated follow-up work.
+
+## What's New in 2.0.12
+
+`solmate-skills@2.0.12` adds a bilingual usage guide and copies it into every target project on install.
+
+- [USAGE.md](./USAGE.md) documents all 26 skills in English (default) with Korean below: cheat sheet, orchestrator map, gates, and prompts.
+- `npx solmate-skills install` (single skill, `all`, or `hooks`) now copies `USAGE.md` to the project root.
+- [README.md](./README.md) is trimmed to a 5-minute start; detailed usage lives in `USAGE.md`.
+- `init-skills.sh` symlinks `USAGE.md` alongside `AGENTS.md` for local development.
+
 ## What's New in 2.0.11
 
 `solmate-skills@2.0.11` adds a Component & Library Planning Gate so React implementation starts from approved UI context and an explicit component/library plan.
@@ -75,30 +164,39 @@ Recent workflow guardrails:
 
 ## Install Details
 
-`install all` installs only skill folders that contain `SKILL.md`. Use `install hooks` separately when you want prompt/file-change suggestions that nudge the agent toward `/rules-product`, `/rules-workflow`, and the relevant `verify-*` skills.
+`install all` installs only skill folders that contain `SKILL.md` and adds the namespaced Claude agent adapters. Use `install hooks` separately when you want prompt/file-change suggestions. Use `install agents` to refresh `rules-workflow`, its canonical contract, and the native Claude adapters in an existing project.
 
 ---
 
 ## Quick Start
 
-설치 후 상황에 맞는 스킬을 하나 실행하는 것으로 시작합니다.
+Install skills, then invoke one command based on your situation.
 
-| 상황 | 시작 명령 | 설명 |
+| Situation | Start with | Notes |
 |:---|:---|:---|
-| 신규 프로젝트 — 아무것도 없을 때 | `/rules-product` | 현재 단계를 자동 진단하고 Phase 1부터 순서대로 안내 |
-| 기획은 있고 코드를 작성하려 할 때 | `/rules-dev` | 커밋 형식, 환경변수, TypeScript 기준 등 컨벤션 먼저 정립 |
-| 기능 하나를 구현하려 할 때 | `/rules-product` → `/rules-workflow` | 현재 Phase를 먼저 진단한 뒤 계획 수립부터 PR까지 진행 |
-| PR 전 최종 점검 | `/verify-implementation` | 모든 `verify-*` 스킬을 순차 실행하여 통합 보고 |
+| New project or "where do I start?" | `/rules-product` | Diagnoses phase and delegates to the right skill |
+| Implement one feature | `/rules-product` then `/rules-workflow` | Gates must pass before coding |
+| Pre-PR / pre-release check | `/verify-implementation` | Runs the verify-* family in order |
 
-**가장 권장하는 시작 한 줄:**
+**Recommended first line:**
 
-```
+```text
 /rules-product
 ```
 
-`rules-product`는 프로젝트 상태를 스스로 진단해 현재 어느 단계인지 파악하고, 해당 단계의 올바른 스킬로 위임하는 오케스트레이터입니다. 새 프로젝트든 재개 중인 프로젝트든 동일하게 사용할 수 있습니다.
+### Orchestrator map
 
-`rules-product` and `rules-workflow` should show a short Flow Status Block at the start of work, before implementation, before verification, and at handoff:
+```text
+rules-product  →  diagnose phase, check gates, delegate
+rules-workflow →  plan → implement → verify → PR (18 steps)
+verify-implementation →  run verify-* skills and report
+```
+
+Full pipeline, gates, backlog template, and all 26 skill entries: **[USAGE.md](./USAGE.md)**
+
+### Flow Status Block
+
+`rules-product` and `rules-workflow` report progress in this format:
 
 ```text
 [Flow]
@@ -110,301 +208,52 @@ Gate: UI-First Gate 진행 중
 권장 스킬: /docs-plan
 ```
 
-### Using Skills in an Existing Project
+### Existing projects
 
-이미 진행 중인 프로젝트에도 최신 `solmate-skills`를 다시 설치해서 사용할 수 있습니다. 사용 방식은 신규 프로젝트와 같지만, 시작점은 항상 현재 프로젝트 상태를 먼저 진단하는 것입니다.
-
-**Update or reinstall skills from the project root:**
+Reinstall from the project root, then diagnose — do not restart from Phase 1 by default.
 
 ```bash
 npx solmate-skills@latest install all
 npx solmate-skills@latest install hooks
+npx solmate-skills@latest install agents
 ```
 
-**Recommended first prompt:**
-
-```text
-/rules-product를 사용해서 이 프로젝트의 현재 진행 상태를 진단하고, 다음 작업을 Flow Status Block 기준으로 안내해줘.
-```
+For a `code` or `deploy` backlog item:
 
-**When starting implementation work:**
-
-```text
-/rules-workflow를 사용해서 현재 기능 작업을 진행해줘. 먼저 Flow Status Block으로 현재 위치를 알려주고, UI-First 흐름에 맞춰 진행해줘.
-```
-
-**When verifying finished work:**
-
-```text
-/verify-implementation으로 현재 변경사항을 전체 검증해줘. Flow Status Block을 포함해서 보고해줘.
+```bash
+npx solmate-skills preflight TASK-000 --strict
+npx solmate-skills verify TASK-000 --strict
 ```
 
-진행 중인 프로젝트에서는 Phase 1부터 강제로 다시 시작하지 않습니다. `/rules-product`가 기존 문서, 코드, 백로그, 변경사항을 보고 현재 위치를 진단한 뒤, 이어서 진행할 Phase와 필요한 Gate를 제안해야 합니다.
+Example prompts: [USAGE.md §9 Recommended Prompts](./USAGE.md#9-recommended-prompts) (EN) · [§9 권장 프롬프트](./USAGE.md#9-권장-프롬프트-모음) (KO)
 
 ---
 
-## Available Skills
-
-Skills are organized into five categories.
+## Skills at a Glance
 
-### Governance
+26 installable skills plus `hooks` and `agents` utilities. Category summary:
 
-| Skill | Description |
+| Category | Skills |
 |:---|:---|
-| `role-team-lead` | Team lead protocols: branch protection, PR review, DB migration, deployment. |
-| `role-team-member` | Team member protocols: branching, Conventional Commits (Korean), PR creation. |
+| Orchestration | `rules-product`, `rules-workflow` |
+| Rules | `rules-docs`, `rules-dev`, `rules-react`, `manage-collaboration`, `manage-decisions`, `manage-skills` |
+| Documentation | `docs-plan`, `docs-dev`, `docs-pitch`, `docs-business` |
+| Verification | `verify-implementation`, `verify-docs`, `verify-ui`, `verify-code`, `verify-security`, `verify-performance`, `verify-drizzle-schema`, `verify-skills` |
+| Roles | `role-team-lead`, `role-team-member` |
+| Tools | `tools-shadcn`, `tools-obsidian` |
+| External | `ext-awesome-design`, `ext-k-skill` |
 
-### Rules
-
-| Skill | Description |
-|:---|:---|
-| `rules-docs` | Master documentation rules and 365 Principle governance. |
-| `rules-dev` | Enforce development setup, coding conventions, and quality rules. |
-| `rules-react` | Create modular, premium React components and pages. |
-| `rules-workflow` | Full 18-step implementation and execution lifecycle. |
-| `rules-product` | Orchestrate the full product development pipeline. |
-| `manage-collaboration` | Enforce AI-Human collaboration standards. |
-| `manage-decisions` | Question-driven decision making for tech, DB, API, UX, and architecture choices. |
-| `manage-skills` | Detect and fix drift between verify skills and changed code. |
-
-### Documentation
-
-| Skill | Description |
-|:---|:---|
-| `docs-plan` | Create and manage **planning documents** (Layer 1-2: vision, UI screens). |
-| `docs-dev` | Create and manage **development documents** (Layer 3-5: specs, logic, QA). |
-| `docs-pitch` | Create pitch decks for investors, hackathons, and demo days. |
-| `docs-business` | Generate professional business plans for funding or partnerships. |
-| `verify-docs` | Audit documentation structure and metadata standards. |
-
-### Special Tools
-
-| Skill | Description |
-|:---|:---|
-| `tools-shadcn` | Expert guidance for shadcn/ui components. |
-| `tools-obsidian` | Sync documentation with an Obsidian vault. |
-
-### External Extensions
-
-| Skill | Description |
-|:---|:---|
-| `ext-awesome-design` | Premium design system and markdown templates. |
-| `ext-k-skill` | Collection of specialized Korean tools and services. |
-
-### Quality & Automation
-
-| Skill | Description |
-|:---|:---|
-| `verify-implementation` | Dynamically discover and run all `verify-*` skills. |
-| `verify-drizzle-schema` | Verify Drizzle ORM schema matches architecture specs. |
-| `verify-security` | Check for security vulnerabilities based on OWASP Top 10. |
-| `verify-performance` | Lighthouse & Core Web Vitals check. |
-| `verify-code` | Comprehensive pre-PR code quality review. |
-| `verify-ui` | Verify implemented UI against screen docs, HTML previews, and user flows. |
-| `verify-skills` | Verify skill package metadata, CLI output, and release readiness. |
+**Situation cheat sheet, per-skill when/prerequisites/outputs/next:** [USAGE.md](./USAGE.md)
 
 ---
 
-## Usage Guide
+## Hooks (optional)
 
-### Documentation System
-
-The documentation system follows the **365 Principle** (3 Investor Lenses, 6 Rubrics, 5 Documentation Layers) and is split across two skills based on the type of document.
-
-**Which skill to use:**
-
-```
-Product vision, Lean Canvas, UI design  →  docs-plan
-DB schema, API specs, roadmap, QA       →  docs-dev
-Unsure which layer?                     →  rules-docs
-```
-
-**5-Layer structure:**
-
-```
-docs/
-├── 01_Concept_Design/   ← docs-plan
-├── 02_UI_Screens/       ← docs-plan
-├── 03_Technical_Specs/  ← docs-dev
-├── 04_Logic_Progress/   ← docs-dev
-└── 05_QA_Validation/    ← docs-dev
-```
-
-**Typical workflow:**
-
-```
-1. /docs-plan    → Write VISION_CORE.md, LEAN_CANVAS.md, PRODUCT_SPECS.md
-2. /docs-plan    → Write SCREEN_FLOW.md, UI_DESIGN.md, and HTML UI previews
-3. HTML UI Preview Gate → Show browser-viewable HTML screens and capture user feedback
-4. UI-First Gate → Confirm screens, user paths, data flow, and UI states before coding
-5. Pre-Code Technical Brief → Confirm data sources, API shape, state strategy, and acceptance criteria
-6. Component & Library Planning Gate → Confirm shadcn components, custom components, reused components, and libraries
-7. /docs-dev     → Write DEVELOPMENT_PRINCIPLES.md, DB_SCHEMA.md, API_SPECS.md
-8. /docs-dev     → Write ROADMAP.md, BACKLOG.md with mandatory related document links
-9. /rules-workflow → Implement each backlog item only after reading linked docs and passing UI-First and Component & Library gates
-10. /verify-implementation  → Audit docs, UI, code, security, performance, DB, and skill package changes
-```
-
-Backlog items are intentionally document-linked. Each task in `docs/04_Logic_Progress/00_BACKLOG.md` must include related Concept, UI, Technical Spec, and QA documents, plus implementation preconditions, acceptance criteria, and a document sync check. If a related document does not exist, the item must say `N/A - 사유`; implementation should pause when the missing document is required for a safe decision.
-
-### Backlog Context Lock
-
-Backlog Context Lock makes `docs/04_Logic_Progress/00_BACKLOG.md` act as a bridge between planning documents and implementation. A backlog item is not considered ready for coding until it names the documents that define why the task exists, how the UI should behave, what technical constraints apply, and how the work will be verified.
-
-### UI-First Gate
-
-UI-First Gate prevents implementation from starting before the team has reviewed the actual screens and the user's path through them. Before coding, confirm the core screen structure, user entry and exit paths, CTAs, screen-by-screen data flow, loading states, empty states, and error states. If these are missing, update `docs/02_UI_Screens/`, its HTML previews, or the backlog first.
-
-### HTML UI Preview Gate
-
-UI planning documents are not complete with Markdown alone. For every major screen or user flow, create a browser-viewable HTML preview and store it under:
-
-```text
-docs/02_UI_Screens/previews/
-```
-
-Recommended naming:
-
-```text
-docs/02_UI_Screens/previews/01_main_flow_preview.html
-docs/02_UI_Screens/previews/02_dashboard_preview.html
-```
-
-Each related UI document must link to the HTML file with a relative path. The preview must be shown to the user before implementation, and feedback must be captured in `XX_PROTOTYPE_REVIEW.md`, `00_SCREEN_FLOW.md`, `01_UI_DESIGN.md`, or the related backlog item.
-
-### Component & Library Planning Gate
-
-React implementation should not begin until the team has listed the UI building blocks and library choices. Record the shadcn/ui components to add, custom components to create, existing components to reuse, libraries to install, libraries intentionally not added, and whether the project needs `init --preset`, `apply --preset`, `apply --only theme`, or `N/A - reason`.
-
-Required fields for every backlog item:
-
-- `Related Concept Docs`
-- `Related UI Docs`
-- `Related HTML Preview`
-- `Related Technical Docs`
-- `Related QA Docs`
-- `Implementation Preconditions`
-- `Component & Library Plan`
-- `Acceptance Criteria`
-- `Document Sync Check`
-
-If a related document does not exist, write `N/A - 사유`. Do not leave the field blank. If the missing document is required to make a safe implementation decision, pause implementation and write or update the document first.
-
-**Backlog item template:**
-
-```markdown
-### [ ] TASK-000: Implement feature name
-
-- Status: ToDo
-- Related Concept Docs:
-  - [Product Specs](../01_Concept_Design/03_PRODUCT_SPECS.md) - feature purpose and user value
-- Related UI Docs:
-  - [Screen Flow](../02_UI_Screens/00_SCREEN_FLOW.md) - target screen and interaction flow
-- Related HTML Preview:
-  - [Main Flow Preview](../02_UI_Screens/previews/01_main_flow_preview.html) - browser-viewable UI for user review
-- Related Technical Docs:
-  - [API Specs](../03_Technical_Specs/02_API_SPECS.md) - endpoint and data contract
-- Related QA Docs:
-  - [QA Checklist](../05_QA_Validation/02_QA_CHECKLIST.md) - acceptance and release criteria
-- Implementation Preconditions:
-  - [ ] Read all related documents before coding
-  - [ ] Confirm screen/UI before coding
-  - [ ] Show the HTML UI preview to the user and capture feedback
-  - [ ] Confirm user path and screen-by-screen data flow
-  - [ ] Confirm loading, empty, and error states
-  - [ ] Confirm implementation scope does not conflict with documented intent
-- Component & Library Plan:
-  - shadcn/ui components: button, card, form, or `N/A - reason`
-  - Custom components: feature-specific components or `N/A - reason`
-  - Reused components: existing paths or `N/A - reason`
-  - New libraries: package names and reasons or `N/A - reason`
-  - Libraries intentionally not added: rejected options and reasons or `N/A - reason`
-  - shadcn preset action: init --preset / apply --preset / apply --only theme / N/A - reason
-- Acceptance Criteria:
-  - [ ] Feature follows the confirmed screen structure and user path
-  - [ ] Feature behavior matches linked Concept/UI/Technical docs
-  - [ ] QA criteria are testable and satisfied
-- Document Sync Check:
-  - [ ] No mismatch between implementation and linked documents
-  - [ ] Update related documents if implementation changes the agreed behavior
-```
-
----
-
-### Pitch Deck
-
-Create a pitch deck from existing `docs-plan` documents.
-
-**Prerequisites:** `docs-plan` Layer 1 documents (VISION_CORE, LEAN_CANVAS, PRODUCT_SPECS) should exist first.
-
-**Output modes:**
-
-| Mode | When to use | Output |
-|:---|:---|:---|
-| Markdown | Content-first, will export to Notion/Slides | `docs/01_Concept_Design/XX_PITCH_DECK.md` |
-| Reveal.js HTML | Present directly in browser, deploy to GitHub Pages | `pitch/index.html` |
-
-**Typical workflow:**
-
-```
-1. /docs-plan    → Ensure VISION_CORE, LEAN_CANVAS, PRODUCT_SPECS exist
-2. /docs-pitch   → Select output mode → Answer Phase 0-2 questions → Generate deck
-```
-
----
-
-### Development Workflow
-
-**Typical workflow:**
-
-```
-1. /rules-dev                → Review conventions before writing code
-2. /rules-product            → Orchestrate the development pipeline
-3. /verify-implementation    → Run all verify-* skills before PR
-4. /manage-collaboration     → Check branch naming, PR format, and workflow status
-```
-
----
-
-### Governance
-
-**Role-based skills** define protocols for team lead and team member roles:
-
-```
-/role-team-lead    → Branch protection, PR review, DB migration, deployment
-/role-team-member  → Branching, commits (Conventional Commits in Korean), PR creation
-```
-
----
-
-### Proactive Skill Suggestions (Hooks)
-
-Install hook scripts so Claude **automatically suggests** the right skill as you work — without needing to invoke them manually.
-
-**Two layers work together:**
-
-| Layer | Mechanism | Trigger |
-|:---|:---|:---|
-| Method 1 | AGENTS.md rules | Claude judges context and suggests skills by reasoning |
-| Method 2 | Hook scripts | Keyword/file-pattern matching fires on every prompt or file edit |
-
-**Install hooks into your project:**
+For Claude Code, install hooks to get keyword and file-pattern skill suggestions:
 
 ```bash
-# 1. Install the hooks skill first (if not already installed)
-npx solmate-skills install hooks
-
-# 2. Run the installer from your project root
+npx solmate-skills@latest install hooks
 bash .agent/skills/hooks/install.sh
 ```
 
-This copies two scripts to `.claude/hooks/` and merges the hook config into `.claude/settings.json`:
-
-| Script | Event | What it detects |
-|:---|:---|:---|
-| `solmate-suggest.sh` | UserPromptSubmit | Keywords: 결정/설계, 보안, 성능, PR, 코드리뷰, 문서, 기능구현, 피치덱, 새 프로젝트 |
-| `solmate-watch.sh` | PreToolUse | File patterns: `schema.ts`, `.env*`, `SKILL.md`, `page.tsx`, `api/route.ts`, `auth.ts`, `AGENTS.md` |
-
-**To review or disable hooks:** open `/hooks` in Claude Code.
-
-**To uninstall:** remove `.claude/hooks/` and the `hooks` section from `.claude/settings.json`.
+Details: [USAGE.md §8 Hooks](./USAGE.md#8-hooks-claude-code-suggestions) (EN) · [§8 Hooks 한국어](./USAGE.md#8-hooks-claude-code-자동-제안) (KO)