solmate-skills 2.0.12 → 2.0.14

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개 실제 작업은 Coordinator가 내부 `warning` 결과를 기록하고 사용자 확인 후 진행한다. 이후 Coordinator 또는 CI가 `preflight TASK-ID --strict`와 `verify TASK-ID --strict`를 차단 게이트로 사용한다. 사용자에게 이 명령·Task ID·Receipt 작성을 요구하지 않고, 통과 결과 또는 막힌 사유만 보고한다.
+
 ## 4. Skills & AI Capabilities
 AI 에이전트는 본 프로젝트에 설치된 다음 **26개 스킬**을 활용하여 작업을 수행하며, 모든 작업 결과물은 이 스킬들의 검증 가이드를 통과해야 한다.
 
@@ -142,8 +151,8 @@ AI 에이전트는 사용자가 스킬을 호출하지 않아도, 아래 상황
 | 기술 선택, DB/API/아키텍처 설계 논의 시작 | `manage-decisions` | "결정이 필요한 상황입니다. `/manage-decisions`로 유형별 질문을 진행할까요?" |
 | 보안·인증·인가·환경변수 관련 코드 작성 전후 | `verify-security` | "보안 관련 변경입니다. `/verify-security`로 OWASP 점검을 실행할까요?" |
 | 성능·렌더링·이미지·번들 관련 작업 완료 후 | `verify-performance` | "성능 영향이 있을 수 있습니다. `/verify-performance`로 Lighthouse 점검을 실행할까요?" |
-| UI·화면·컴포넌트 구현 완료 후 | `verify-ui` | "UI 구현 변경입니다. `/verify-ui`로 HTML Preview·화면 문서·사용자 동선 정합성을 검증할까요?" |
-| PR 생성 전, 코드 변경 완료 후 | `verify-code`, `verify-implementation` | "PR 전 최종 점검입니다. `/verify-implementation`으로 전체 검증을 실행할까요?" |
+| UI·화면·컴포넌트 구현 완료 후 | `verify-ui` | Coordinator가 관련 UI 검증을 자동 실행하고 결과만 보고 |
+| 기능 구현 완료 또는 PR 생성 전 | `verify-code`, `verify-implementation` | Coordinator가 `/verify-implementation`과 필요한 내부 Harness 검증을 즉시 실행하고 결과만 보고 |
 | 기획·UI 문서 작성 요청 | `docs-plan` | "Layer 1-2 문서 작성은 `/docs-plan`을 사용하세요." |
 | DB 스키마·API 명세·백로그 작성 요청 | `docs-dev` | "Layer 3-5 문서 작성은 `/docs-dev`를 사용하세요." |
 | Drizzle 스키마 파일 수정 | `verify-drizzle-schema` | "스키마 변경 후 `/verify-drizzle-schema`로 정합성을 검증하세요." |

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` and `USAGE.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,12 @@ 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 and copies [USAGE.md](./USAGE.md) to the project root.
+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.
 
@@ -37,8 +40,99 @@ 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.
 
+## Agent Harness
+
+The shared Claude/Codex agent harness strengthens the existing Solmate workflow. 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).
+
+### Default behavior: ask for a feature, receive a verified result
+
+You do not run Harness commands during normal feature work. Ask the coding agent to implement the feature; the Coordinator finds the backlog task, checks the linked documents before coding, and starts independent verification immediately after implementation.
+
+| You say | The agent does internally | You receive |
+|:---|:---|:---|
+| "Implement file upload" | Finds the related backlog task, reads its linked documents, and runs the Context gate | Either implementation begins or a plain-language explanation of the missing decision or document |
+| "The feature is done" | Runs `verify-implementation`, relevant checks, and the Verification gate | A concise PASS/FAIL report, remaining risks, and the next decision only when needed |
+
+The agent must not ask you to type `preflight`, `verify`, `validate-harness`, a task ID, or Receipt content. When a gate blocks progress, it explains what is missing rather than exposing its internal command.
+
+### Advanced automation and CI
+
+The following interfaces are for Coordinator runtimes, CI, and teams building custom automation. They are optional; existing backlog Receipt projects do not need structured artifacts.
+
+<details>
+<summary>Internal Receipt and structured-artifact commands</summary>
+
+```bash
+npx solmate-skills preflight TASK-000 --strict
+npx solmate-skills verify TASK-000 --strict
+
+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 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 |
+
+</details>
+
+### 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.14
+
+`solmate-skills@2.0.14` makes verification an agent responsibility instead of a user checklist.
+
+- After implementation, the Coordinator automatically starts `verify-implementation` and the required Harness Receipt checks before reporting completion.
+- Context and Verification agents run their applicable checks internally and return plain-language results or a blocked decision.
+- `npx solmate-skills list` now describes automatic workflow verification rather than presenting internal Harness commands as the default path.
+- README and `USAGE.md` keep `preflight`, `verify`, and `validate-harness` in advanced runtime/CI guidance.
+
+## What's New in 2.0.13
+
+`solmate-skills@2.0.13` introduced the shared Agent Harness contract, versioned artifacts, Context/Change/Verification Receipts, and the `validate-harness` validator.
+
 ## 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.
@@ -86,7 +180,7 @@ 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.
 
 ---
 
@@ -98,7 +192,8 @@ Install skills, then invoke one command based on your situation.
 |:---|:---|:---|
 | 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 |
+| Feature implementation just finished | No extra command | The Coordinator automatically starts `verify-implementation` and reports the result |
+| Explicit audit request | `/verify-implementation` | Runs the verify-* family in order |
 
 **Recommended first line:**
 
@@ -137,15 +232,18 @@ Reinstall from the project root, then diagnose — do not restart from Phase 1 b
 ```bash
 npx solmate-skills@latest install all
 npx solmate-skills@latest install hooks
+npx solmate-skills@latest install agents
 ```
 
+For a `code` or `deploy` backlog item, ask the agent to implement the feature. The Coordinator handles the Context and Verification gates internally and reports only the result or the decision needed to unblock it.
+
 Example prompts: [USAGE.md §9 Recommended Prompts](./USAGE.md#9-recommended-prompts) (EN) · [§9 권장 프롬프트](./USAGE.md#9-권장-프롬프트-모음) (KO)
 
 ---
 
 ## Skills at a Glance
 
-26 installable skills plus `hooks`. Category summary:
+26 installable skills plus `hooks` and `agents` utilities. Category summary:
 
 | Category | Skills |
 |:---|:---|

package/USAGE.md

@@ -3,12 +3,12 @@
 <a id="solmate-skills-usage-guide"></a>
 
 Created Date: 2026-06-25 03:00  
-Last Updated Date: 2026-06-29 15:20
+Last Updated Date: 2026-07-17 00:33
 
 **Language:** English (default) · [Korean version below](#solmate-skills-usage-guide-korean)
 
 This is a **human-readable** guide for choosing and invoking skills.  
-Agent execution rules live in each `SKILL.md` and the installed `AGENTS.md`.
+Agent execution rules live in each `SKILL.md` and the project `AGENTS.md` when it is linked or installed.
 
 ---
 
@@ -29,9 +29,10 @@ Run /verify-implementation on the current changes
 ```bash
 npx solmate-skills@latest install all      # .agent/skills/<skill-name>/ + ./USAGE.md
 npx solmate-skills@latest install hooks    # Claude Code suggestions (optional) + ./USAGE.md
+npx solmate-skills@latest install agents   # Refresh rules-workflow + native Claude project agents
 ```
 
-Every `install` command (single skill, `all`, or `hooks`) copies `USAGE.md` to the **project root**.
+Every `install` command (single skill, `all`, `hooks`, or `agents`) copies `USAGE.md` to the **project root**. Installing `rules-workflow` or `all` also installs the namespaced Claude agents automatically.
 
 ### Local development (symlink)
 
@@ -42,7 +43,7 @@ When hacking on the `solmate-skills` repo itself:
 bash /path/to/solmate-skills/init-skills.sh
 ```
 
-This symlinks `.agent/skills/` to the repo and links `AGENTS.md` and `USAGE.md` at the project root.
+This symlinks `.agent/skills/` to the repo, links `AGENTS.md` and `USAGE.md` at the project root, and links the namespaced Claude agents under `.claude/agents/`.
 
 ---
 
@@ -107,11 +108,52 @@ This symlinks `.agent/skills/` to the repo and links `AGENTS.md` and `USAGE.md`
 | `rules-workflow` | Plan → implement → cleanup → PR (18 steps) | Feature work, commit/PR prep |
 | `verify-implementation` | Run verify-* by changed files, unified report | Pre-PR / pre-release |
 
+### Agent harness sequence
+
+For backlog tasks with `Work Type: code` or `Work Type: deploy`:
+
+```text
+Coordinator
+  -> read-only Context Agent -> Context Receipt
+  -> Implementation Agent    -> Change Receipt
+  -> read-only Verifier       -> Verification Receipt
+  -> Coordinator completion decision
+```
+
+- Claude Code uses `.claude/agents/solmate-context-reader.md`, `solmate-implementer.md`, and `solmate-verifier.md`.
+- Codex uses available subagents or separate tasks with the same canonical contract from `rules-workflow/resources/agent-harness-contract.md`.
+- The verifier reports findings but does not modify source files.
+- Receipt summaries stay in the backlog; detailed verification links to a QA document or GitHub PR.
+- For normal feature work, the Coordinator runs Context and Verification checks internally. Do not ask the user to run a Harness command, choose a task ID, or fill in a Receipt. Report only a PASS/FAIL result or the missing decision and document.
+
+<details>
+<summary>Advanced: runtime and CI commands</summary>
+
+Use warning mode for the first five real tasks, then let the Coordinator or CI switch to blocking checks:
+
+```bash
+npx solmate-skills preflight TASK-000 --strict
+npx solmate-skills verify TASK-000 --strict
+```
+
+Optional v1 structured artifacts use the same warning-to-blocking migration:
+
+```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
+```
+
+Add `--strict` for blocking validation. Contract failures then exit `1`; malformed JSON, missing files, and invalid command input exit `2`. Existing backlog-only projects do not need to create these files.
+
+</details>
+
 ### Individual verify-* vs master
 
 | Situation | Use |
 |:---|:---|
-| Full pre-PR / pre-release | `verify-implementation` |
+| Feature implementation just finished | Coordinator automatically invokes `verify-implementation` |
+| Explicit full audit request | `verify-implementation` |
 | Docs only changed | `verify-docs` |
 | TSX screens only | `verify-ui` |
 | API / auth / env changed | `verify-security` (+ `verify-code` if needed) |
@@ -129,9 +171,10 @@ Phase 2  UI design docs      → docs-plan (02_UI_Screens)
          UI-First Gate        → screens, flows, data, states
          Pre-Code Technical Brief → API, state, acceptance criteria
          Component & Library Planning Gate → shadcn, custom, reuse, libraries
+         Context Receipt Gate  → linked docs read by a read-only agent
 Phase 3  React implementation → rules-react (+ tools-shadcn)
 Phase 4  Dev docs              → docs-dev (03–05)
-Phase 5  Quality verification  → verify-implementation
+Phase 5  Independent verification → Verification Receipt + verify-implementation
 Phase 6  Deliverables (opt.)   → docs-pitch / docs-business
 ```
 
@@ -171,9 +214,9 @@ Each entry: **When** / **Prerequisites** / **Invoke** / **Outputs** / **Next**
 #### `rules-workflow`
 
 - **When:** Feature implementation, planning, commit/PR (18 steps)
-- **Prerequisites:** HTML UI Preview Gate, UI-First Gate, Backlog Context Lock, Component & Library Plan (non-prototype)
+- **Prerequisites:** HTML UI Preview Gate, UI-First Gate, Backlog Context Lock, Component & Library Plan, Context Receipt (code/deploy)
 - **Invoke:** `/rules-workflow` — implement this backlog item
-- **Outputs:** Plan review, implementation, self-check, PR readiness
+- **Outputs:** Context Receipt, plan review, Change Receipt, independent Verification Receipt, PR readiness
 - **Next:** `verify-implementation`
 
 #### `rules-dev`
@@ -428,11 +471,22 @@ Required fields per item in `docs/04_Logic_Progress/00_BACKLOG.md`:
 
 - `Related Concept Docs`, `Related UI Docs`, `Related HTML Preview`
 - `Related Technical Docs`, `Related QA Docs`
-- `Implementation Preconditions`, `Component & Library Plan`
+- `Work Type`, `Implementation Preconditions`, `Component & Library Plan`
+- `Context Receipt`, `Change Receipt`, `Verification Receipt`
 - `Acceptance Criteria`, `Document Sync Check`
 
 Use `N/A - reason` when a doc does not exist. Pause implementation if a missing doc blocks a safe decision.
 
+### Agent Harness Gate
+
+- Canonical contract: `rules-workflow/resources/agent-harness-contract.md`
+- `code` and `deploy`: Context Receipt before implementation; Verification Receipt before Done, PR, merge, publish, or deploy
+- `docs` and `prototype`: advisory receipts
+- Context and Verification agents are read-only
+- Verification details must link to an existing `docs/05_QA_Validation/` document or GitHub PR
+- Default CLI mode is `warning`; `--strict` returns a blocking non-zero exit
+- `preflight`, `verify`, and `validate-harness` are Coordinator/CI interfaces, not commands a normal user needs to run
+
 ### YAGNI/KISS/DRY Gate
 
 - **Canonical:** `rules-dev` § Minimal Implementation Gate
@@ -447,6 +501,7 @@ Use `N/A - reason` when a doc does not exist. Pause implementation if a missing
 ### [ ] TASK-000: Implement feature name
 
 - Status: ToDo
+- Work Type: code
 - Related Concept Docs:
   - [Product Specs](../01_Concept_Design/03_PRODUCT_SPECS.md) - feature purpose and user value
 - Related UI Docs:
@@ -464,6 +519,13 @@ Use `N/A - reason` when a doc does not exist. Pause implementation if a missing
   - [ ] Confirm user path and screen-by-screen data flow
   - [ ] Confirm loading, empty, and error states
   - [ ] Confirm implementation scope does not conflict with documented intent
+- Context Receipt:
+  - Status: PENDING
+  - Required References Read:
+    - PENDING - repeat every linked Related document after reading it
+  - Constraints:
+    - PENDING - extracted implementation constraints
+  - Conflicts: PENDING - use `None` only after checking
 - Component & Library Plan:
   - shadcn/ui components: button, card, form, or `N/A - reason`
   - Custom components: feature-specific components or `N/A - reason`
@@ -475,6 +537,23 @@ Use `N/A - reason` when a doc does not exist. Pause implementation if a missing
   - [ ] Feature follows the confirmed screen structure and user path
   - [ ] Feature behavior matches linked Concept/UI/Technical docs
   - [ ] QA criteria are testable and satisfied
+- Change Receipt:
+  - Files Changed:
+    - PENDING
+  - Requirements Covered:
+    - PENDING
+  - Excluded Scope: PENDING
+  - Basic Checks:
+    - PENDING
+  - Remaining Risks: PENDING
+- Verification Receipt:
+  - Status: PENDING
+  - Commands and Results:
+    - PENDING - `command` - PASS/FAIL - exact scope and result
+  - Unrun Checks:
+    - PENDING - skipped checks and reasons
+  - Detailed Evidence:
+    - PENDING - link an existing QA document or GitHub PR
 - Document Sync Check:
   - [ ] No mismatch between implementation and linked documents
   - [ ] Update related documents if implementation changes the agreed behavior
@@ -540,7 +619,7 @@ Run /verify-implementation on current changes. Include a Flow Status Block in th
 **언어:** [English (default)](#solmate-skills-usage-guide) · 한국어 (아래)
 
 사람이 읽기 위한 스킬 사용법 가이드입니다.  
-에이전트 실행 규칙의 정본은 각 `SKILL.md`와 프로젝트에 설치된 `AGENTS.md`입니다.
+에이전트 실행 규칙의 정본은 각 `SKILL.md`와 프로젝트에 링크 또는 설치된 `AGENTS.md`입니다.
 
 ---
 
@@ -561,9 +640,10 @@ Run /verify-implementation on current changes. Include a Flow Status Block in th
 ```bash
 npx solmate-skills@latest install all      # .agent/skills/<skill-name>/ + ./USAGE.md
 npx solmate-skills@latest install hooks    # Claude Code 자동 제안 (별도) + ./USAGE.md
+npx solmate-skills@latest install agents   # rules-workflow + Claude 프로젝트 에이전트 갱신
 ```
 
-모든 `install` 명령(단일 스킬, `all`, `hooks`)은 `USAGE.md`를 **프로젝트 루트**에 복사합니다.
+모든 `install` 명령(단일 스킬, `all`, `hooks`, `agents`)은 `USAGE.md`를 **프로젝트 루트**에 복사합니다. `rules-workflow` 또는 `all` 설치 시 Claude 에이전트도 자동 설치됩니다.
 
 ### 로컬 개발 (symlink)
 
@@ -574,7 +654,7 @@ npx solmate-skills@latest install hooks    # Claude Code 자동 제안 (별도)
 bash /path/to/solmate-skills/init-skills.sh
 ```
 
-`.agent/skills/`가 저장소로 symlink되고, `AGENTS.md`와 `USAGE.md`가 루트에 링크됩니다.
+`.agent/skills/`가 저장소로 symlink되고, `AGENTS.md`와 `USAGE.md`가 루트에 링크되며, `.claude/agents/`에 Solmate 에이전트가 연결됩니다.
 
 ---
 
@@ -620,11 +700,52 @@ bash /path/to/solmate-skills/init-skills.sh
 | `rules-workflow` | 승인된 문서 기준으로 계획→구현→정리→PR (18단계) | 기능 구현·커밋·PR 직전 |
 | `verify-implementation` | 변경 파일에 맞춰 verify-* 순차 실행·통합 보고 | PR·배포 전 최종 점검 |
 
+### 에이전트 하네스 순서
+
+`Work Type`이 `code` 또는 `deploy`인 백로그 작업은 다음 순서로 진행합니다.
+
+```text
+Coordinator
+  -> 읽기 전용 Context Agent -> Context Receipt
+  -> Implementation Agent    -> Change Receipt
+  -> 읽기 전용 Verifier      -> Verification Receipt
+  -> Coordinator 완료 판단
+```
+
+- Claude Code는 `.claude/agents/solmate-*.md`를 사용합니다.
+- Codex는 `rules-workflow/resources/agent-harness-contract.md`의 같은 계약을 subagent 또는 별도 task에 전달합니다.
+- 검증자는 문제를 직접 수정하지 않고 Implementation Agent로 돌려보냅니다.
+- Receipt 요약은 백로그에, 상세 검증 근거는 QA 문서 또는 GitHub PR에 남깁니다.
+- 일반 기능 작업에서는 Coordinator가 Context·Verification 검사를 내부적으로 실행합니다. 사용자에게 Harness 명령, Task ID, Receipt 작성을 요구하지 않고 통과/실패 결과 또는 필요한 결정과 문서만 설명합니다.
+
+<details>
+<summary>고급: 런타임·CI 명령</summary>
+
+처음 5개 실제 작업은 Coordinator 또는 CI가 warning으로 확인한 뒤 blocking으로 전환합니다.
+
+```bash
+npx solmate-skills preflight TASK-000 --strict
+npx solmate-skills verify TASK-000 --strict
+```
+
+선택형 v1 구조화 산출물도 같은 warning-to-blocking 마이그레이션을 사용합니다.
+
+```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
+```
+
+차단 검증에는 `--strict`를 추가합니다. 계약 위반은 종료 코드 `1`, JSON 파싱·파일·명령 입력 오류는 종료 코드 `2`입니다. 기존 백로그 Receipt만 사용하는 프로젝트는 이 파일을 만들 필요가 없습니다.
+
+</details>
+
 ### verify-* 개별 vs 통합
 
 | 상황 | 사용 |
 |:---|:---|
-| PR·배포 전 전체 점검 | `verify-implementation` |
+| 기능 구현 직후 | Coordinator가 `verify-implementation`을 자동 실행 |
+| 명시적 전체 점검 요청 | `verify-implementation` |
 | 문서만 수정함 | `verify-docs` |
 | TSX 화면만 수정함 | `verify-ui` |
 | API·auth·env 수정함 | `verify-security` (+ 필요 시 `verify-code`) |
@@ -642,9 +763,10 @@ Phase 2  UI 설계 문서     → docs-plan (02_UI_Screens)
          UI-First Gate          → 화면·동선·데이터 흐름·상태 확인
          Pre-Code Technical Brief → API·상태·acceptance criteria 합의
          Component & Library Planning Gate → shadcn·커스텀·재사용·라이브러리 계획
+         Context Receipt Gate → 읽기 전용 에이전트의 관련 문서 확인
 Phase 3  React 구현       → rules-react (+ tools-shadcn)
 Phase 4  개발문서         → docs-dev (03~05)
-Phase 5  품질 검증        → verify-implementation
+Phase 5  독립 품질 검증   → Verification Receipt + verify-implementation
 Phase 6  전달물 (선택)    → docs-pitch / docs-business
 ```
 
@@ -738,6 +860,7 @@ Gate: UI-First Gate 진행 중
 - **UI-First Gate:** 화면·동선·CTA·데이터 흐름·로딩/빈/오류 상태
 - **Component & Library Planning Gate:** shadcn·커스텀·재사용·라이브러리·preset
 - **Backlog Context Lock:** Related Docs, Preconditions, Component Plan, Acceptance, Sync Check
+- **Agent Harness Gate:** code/deploy 작업은 Context Receipt와 독립 Verification Receipt 필수
 - **YAGNI/KISS/DRY Gate:** `rules-dev` 정본; 프로토타입은 기록성 체크
 
 백로그 템플릿: [영문 §7 Backlog item template](#backlog-item-template) (필드명은 영문 유지)