@kodevibe/harness 0.9.0 → 0.9.3

package/README.ko.md

@@ -9,83 +9,33 @@
 [![CI](https://github.com/AIDD-Projects/harness/actions/workflows/ci.yml/badge.svg)](https://github.com/AIDD-Projects/harness/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**모든 개발자의 AI를 하나의 프로젝트 방향으로 정렬합니다.**
+> **AI 코딩 에이전트는 세션이 끝나면 모든 것을 잊습니다. kode:harness는 목표, 결정, 실패, 프로젝트 방향을 기억하게 합니다.**
 
-kode:harness는 **harness engineering** 원칙을 기반으로 합니다. 멀티 개발자와 엔터프라이즈급 환경, 그리고 solo 개발 흐름까지 고려한 AI 개발 엔지니어링 방식을 제품 형태로 제공하는 구조입니다.
-
-> **v0.9.0** — 네이밍 재설계 (스킬/에이전트 이름 직관화), 6개 IDE 지원, Navigation Dispatcher, 5개 파이프라인 (🟢🔵🔴🟡🟣), Crew Artifact Integration.
-
----
-
-## Harness에서 Enterprise Harness Engineering으로
-
-AI "harness" — LLM 코딩 에이전트를 안내하는 구조화된 마크다운 파일 — 는 AI 기반 개발의 기본 패턴이 되었습니다. BMAD, gstack, GSD 같은 프레임워크가 **1인 개발자**를 위해 이 접근법을 개척했습니다.
-
-이 접근은 harness 엔지니어링을 1인 도구 수준에서 멀티 개발자 팀과 solo 개발자까지 포괄하는 **엔터프라이즈급 방향 관리 기법**으로 확장합니다. **kode:harness**는 이 접근을 제품 형태로 구현한 실행 프레임워크입니다.
-
-| | 기존 Harness | kode:harness + harness engineering |
-|---|---|---|
-| 대상 | 1인 개발자 | **멀티 개발자 팀** |
-| 초점 | AI가 무엇을 하는지 | **AI가 어디로 가는지** |
-| 방향 관리 | ❌ | ✅ Direction Guard + pivot + Decision Log |
-| 팀 상태 공유 | ❌ | ✅ 공유/개인 상태 분리 |
-| 토큰 예산 | 200+ 파일 | **~25개 파일 (~17K 토큰)** — 소형 LLM도 작동 |
-
-## 어떤 문제를 해결하나요?
-
-혼자 개발할 때는 AI 코딩 어시스턴트의 방향이 일관됩니다. 하지만 **기업 팀**에서는 각 개발자가 독립된 AI 세션을 실행하고, 각 AI는 제각각 다른 방향으로 흘러갑니다.
-
-- 개발자 A의 AI → 마이크로서비스로 리팩토링
-- 개발자 B의 AI → 모놀리스를 강화
-- 개발자 C의 AI → 이미 결정된 사항을 다시 논의
-
-공유된 방향 관리 없이는 **여러 개발자의 AI가 프로젝트를 분리시킵니다.**
-
-kode:harness는 모든 개발자의 AI에게 동일한 목표·비목표·결정사항·프로젝트 상태를 제공하여, 누가 코딩하든 어떤 IDE를 쓰든 **하나의 방향**으로 수렴하게 합니다.
-
-## 핵심 설계 원칙
-
-> **경량성**: Claude Sonnet이나 GPT-4o 같은 대형 LLM뿐 아니라, 프라이빗 망의 소형 LLM(GPT OSS 120B급, 로컬 LLM 등)도 kode:harness 파일을 읽고 프로젝트 방향을 유지할 수 있어야 합니다. BMAD의 200개 이상 파일 대비 **~25개 파일, ~17K 토큰**으로 동일한 효과를 달성합니다.
-
----
-
-## 주요 기능
-
-| 기능 | 설명 |
-|------|------|
-| 🧭 **Direction Guard** | 모든 코딩 요청을 프로젝트 목표/비목표와 대조 후 실행 |
-| 🧭 **Navigation Dispatcher** | Turn-by-Turn 네비게이션으로 5개 파이프라인을 따라 다음 단계 프롬프트를 자동 안내 |
-| 🟢🔵🔴🟡🟣 **5개 파이프라인** | New Dev → Continue → Bug Fix → Direction Change → Crew-Driven |
-| 🟣 **Crew Artifact Integration** | 외부 기획 도구 산출물(PRD, Architecture, ARB Checklist)을 직접 읽기 — 수동 복사 불필요 |
-| 📝 **State Files** | LLM 세션 간 프로젝트 지식을 유지하는 5개 마크다운 파일 |
-| 🛠️ **Skills** | 기획, 리뷰, 디버깅, 방향 전환을 위한 단계별 절차 10개 |
-| 🤖 **Agents** | 워크플로를 강제하는 역할 기반 페르소나 4개 |
-| ⚠️ **Failure Patterns** | 동일 실수 반복을 방지하는 프로젝트별 실패 기록 |
-| 📝 **Decision Log** | 결정의 이유를 기록해 LLM이 확정된 사항을 재논의하지 않도록 방지 |
+AI 코딩 에이전트를 위한 프로덕션급 가드레일. 컨텍스트 부패를 방지하고, 프로젝트 방향을 강제하며, 세션 간 상태를 유지합니다. **Copilot, Claude, Cursor, Codex, Windsurf, Gemini** 지원. 의존성 제로.
 
 ---
 
 ## 빠른 시작
 
 ```bash
-# Solo 모드 (기본)
-npx @kodevibe/harness init
-
-# Team 모드 (멀티 개발자)
-npx @kodevibe/harness init --team
+npx @kodevibe/harness init          # IDE 선택
 ```
 
-프롬프트에서 IDE를 선택하면 현재 디렉토리에 파일이 설치됩니다.
-
-설치 후, LLM에게 `setup` 스킬을 실행하도록 요청하세요:
-
+```bash
+# 그 후 AI 에이전트에게:
 > "setup을 실행해서 이 프로젝트를 온보딩해줘."
+```
 
-코드베이스를 스캔하고 5개 State 파일을 자동으로 채웁니다.
+끝입니다. 이제 AI는 영속적인 메모리, 방향 가드레일, 자기 교정 루프를 갖게 됩니다.
 
-### 비대화형 모드
+<details>
+<summary>추가 설치 옵션</summary>
 
 ```bash
+# Team 모드 (멀티 개발자 방향 정렬)
+npx @kodevibe/harness init --team
+
+# 비대화형 (CI/스크립트)
 npx @kodevibe/harness init --ide vscode
 npx @kodevibe/harness init --ide claude
 npx @kodevibe/harness init --ide cursor
@@ -94,8 +44,6 @@ npx @kodevibe/harness init --ide windsurf
 npx @kodevibe/harness init --ide antigravity
 ```
 
-### 옵션
-
 | 플래그 | 설명 |
 |--------|------|
 | `--ide <이름>` | 대상 IDE: `vscode`, `claude`, `cursor`, `codex`, `windsurf`, `antigravity` |
@@ -106,14 +54,58 @@ npx @kodevibe/harness init --ide antigravity
 | `--overwrite` | 기존 파일 덮어쓰기 (state 파일 포함) |
 | `--version` | 버전 번호 표시 |
 
-### 헬스체크
+</details>
 
-```bash
-# kode:harness 파일 설치 상태 확인
-npx @kodevibe/harness doctor
+---
+
+## 문제: 컨텍스트 부패 (Context Rot)
+
+AI 코딩 에이전트는 매 세션 제로에서 시작합니다. 세션 3에서는 세션 1의 아키텍처 결정을 잊고, 세션 10에서는 이미 확정된 사항을 다시 논의하며 자신의 이전 작업과 모순됩니다.
+
+팀에서는 더 심각합니다 — 개발자 A의 AI는 마이크로서비스로 리팩토링하고, 개발자 B의 AI는 모놀리스를 강화합니다. **공유 가드레일 없이는 AI 에이전트가 프로젝트를 분리시킵니다.**
+
+kode:harness는 세 가지 메커니즘으로 해결합니다:
+
+| 메커니즘 | 방지하는 문제 |
+|---------|-------------|
+| **상태 영속성** | AI가 세션 간 목표, 결정, 진행 상황을 잊는 것 |
+| **방향 가드** | AI가 프로젝트 목표에서 이탈하거나 과거 결정과 모순되는 것 |
+| **실패 패턴** | AI가 세션 간 같은 실수를 반복하는 것 |
+
+---
 
-# State 파일에 실제 내용이 있는지 검증 (플레이스홀더가 아닌지)
-npx @kodevibe/harness validate
+## 왜 그냥 ...을 쓰면 안 되나요?
+
+| 접근법 | 한계 | kode:harness 차이점 |
+|--------|------|---------------------|
+| **`.cursorrules` / `copilot-instructions.md`** | 정적. 상태 영속성 없음, 자기 교정 없음, 세션 간 기억 없음. | 매 세션 업데이트되는 살아있는 state 파일. Direction Guard가 매 요청을 목표와 대조. |
+| **LangChain / CrewAI** | AI 앱 구축용 런타임 오케스트레이션. AI 코딩 에이전트 방향 관리용이 아님. | IDE 안에서 작동하는 마크다운 네이티브 가드레일. 런타임 없음, SDK 없음. |
+| **BMAD / gstack / GSD** | 1인 개발자용. 200+ 파일. 방향 관리 없음. | ~25개 파일 (~17K 토큰). Direction Guard + Decision Log. 멀티 개발자 팀 지원. |
+| **"조심하면 되지"** | 잊을 때까지만 동작. LLM은 과거 세션에서 배우지 않음. | 자동화: `wrap-up`이 교훈 캡처, `debug`가 실패 추적, `reviewer`가 state 감사. |
+
+---
+
+## 주요 기능
+
+| 기능 | 설명 |
+|------|------|
+| 🛡️ **Direction Guard** | 모든 코딩 요청을 프로젝트 목표/비목표와 대조 후 실행 |
+| 🧭 **Navigation Dispatcher** | 5개 파이프라인을 따라 다음 단계 프롬프트를 자동 안내 |
+| 📝 **상태 영속성** | LLM 세션 간 프로젝트 지식을 유지하는 5개 마크다운 파일 |
+| 🔄 **5개 파이프라인** | 🟢 신규 → 🔵 계속 → 🔴 버그 수정 → 🟡 방향 전환 → 🟣 Crew 기반 |
+| 🛠️ **10개 스킬** | 단계별 절차: setup, debug, breakdown, review, pivot 등 |
+| 🤖 **4개 에이전트** | 역할 기반 페르소나: pm, reviewer, lead, architect |
+| ⚠️ **실패 패턴** | 세션 간 같은 실수를 방지하는 프로젝트별 실패 기록 |
+| 📋 **Decision Log** | 결정의 이유를 기록해 LLM이 확정된 사항을 재논의하지 않도록 방지 |
+| 🟣 **Crew Artifact Integration** | 외부 기획 산출물 (PRD, Architecture, ARB Checklist) 직접 읽기 |
+
+---
+
+## 헬스체크
+
+```bash
+npx @kodevibe/harness doctor    # 파일 설치 상태 확인
+npx @kodevibe/harness validate  # state 파일에 실제 내용 확인
 ```
 
 ---
@@ -123,11 +115,11 @@ npx @kodevibe/harness validate
 | IDE | 디스패처 (always-on) | 스킬 | 에이전트 |
 |-----|---------------------|------|----------|
 | **VS Code Copilot** | `.github/copilot-instructions.md` | `.github/skills/*/SKILL.md` | `.github/agents/*.agent.md` |
-| **Claude Code** | `.claude/rules/core.md` | `.claude/skills/*/SKILL.md` | `.claude/agents/*.md` |
-| **Cursor** | `.cursor/rules/core.mdc` | `.cursor/skills/*/SKILL.md` | `.cursor/agents/*.md` |
-| **Codex** | `AGENTS.md` | `.agents/skills/*/SKILL.md` | `.codex/agents/*.toml` |
+| **Claude Code** | `CLAUDE.md` (+ `.claude/rules/core.md`) | `.claude/skills/*/SKILL.md` | `.claude/agents/*.md` |
+| **Cursor** | `.cursor/rules/core.mdc` (+ `AGENTS.md`) | `.cursor/skills/*/SKILL.md` | `.cursor/agents/*.md` |
+| **Codex** | `AGENTS.md` | `.agents/skills/*/SKILL.md` | `.codex/agents/*.md` |
 | **Windsurf** | `.windsurf/rules/core.md` | `.windsurf/skills/*/SKILL.md` | *(스킬로 설치)* |
-| **Antigravity** | `GEMINI.md` | `.gemini/skills/*/SKILL.md` | `.gemini/agents/*.md` |
+| **Antigravity** | `GEMINI.md` (+ `AGENTS.md`) | `.gemini/skills/*/SKILL.md` | `.gemini/agents/*.md` |
 
 모든 IDE에 `docs/` 디렉토리에 State 파일(`project-state.md`, `project-brief.md`, `features.md`, `failure-patterns.md`, `dependency-map.md`)도 함께 설치됩니다.
 
@@ -267,14 +259,13 @@ npx @kodevibe/harness init --team
 
 ---
 
-## 왜 kode:harness인가?
+## 왜 만들었나
 
-### 핵심 통찰
+기존 AI 코딩 프레임워크는 **AI가 무엇을 하는지** — 코드 생성, 테스트 실행, 배포에 집중합니다. 하지만 진짜 문제는 능력이 아닙니다. **방향**입니다.
 
-기존 AI 코딩 프레임워크는 **AI가 무엇을 하는지**(코드 생성, 테스트 실행, 배포)에 집중합니다.
-kode:harness는 **AI가 어디로 가는지** — 모든 개발자의 AI가 같은 방향으로 움직이는지에 집중합니다.
+혼자 개발하면 방향이 일관됩니다. 하지만 팀에서는 각 개발자의 AI가 독립적으로 이탈합니다. 그리고 혼자 개발해도 세션 간 방향을 잃습니다 — 우리가 **컨텍스트 부패(Context Rot)**라 부르는 현상입니다. AI는 아키텍처 결정을 잊고, 확정된 사항을 재논의하며, 자신의 이전 작업과 모순됩니다.
 
-이것은 개별 AI가 제멋대로 움직이는 것과, harness 기반 방향 관리 기법이 팀 전체를 한 방향으로 이끄는 것의 차이입니다.
+kode:harness는 **AI가 어디로 가는지**에 집중합니다. 개발자, IDE, 시간을 넘어 모든 AI 세션에 동일한 목표, 결정, 프로젝트 상태를 제공합니다. 이 근간이 되는 원칙이 **harness engineering** — 어떤 LLM이든 읽을 수 있는 경량 마크다운 네이티브 가드레일입니다.
 
 ### Crew Artifact Integration (🟣 파이프라인)
 
@@ -292,7 +283,7 @@ Bootstrap이 `docs/crew/`, `docs/PM/`, `docs/Analyst/`, `docs/ARB/`에서 crew
 
 원본 crew 문서는 **절대 수정되지 않습니다**. 인덱스와 트래커만 생성됩니다.
 
-### 비교
+### 다른 프레임워크와의 비교
 
 | | BMAD v6.2.2 | gstack v0.15.1 | GSD v1.33.0 | **kode:harness** |
 |---|---|---|---|---|
@@ -309,7 +300,7 @@ Bootstrap이 `docs/crew/`, `docs/PM/`, `docs/Analyst/`, `docs/ARB/`에서 crew
 
 ## 로드맵
 
-kode:harness는 현재 **v0.9.0** — 네이밍 재설계 완료, 6개 IDE 지원, Navigation Dispatcher와 Crew Artifact Integration 안정화.
+kode:harness는 현재 **v0.9.2** — state-check 스킬, Iron Law #10 (Self-Verify), Confirmation Gate Defaults, 멀티 IDE 설치 수정, Crew 모드용 CI Artifact Index 도입.
 
 | 단계 | 버전 | 상태 | 초점 |
 |------|------|------|------|
@@ -317,7 +308,8 @@ kode:harness는 현재 **v0.9.0** — 네이밍 재설계 완료, 6개 IDE 지
 | **Hardening** | v0.6.5 | ✅ 완료 | 10 스킬, 4 에이전트, Iron Laws, CLI batch/doctor/validate, 방향 드리프트 감지 |
 | **Flexibility** | v0.7.x | ✅ 완료 | 팀 컨벤션을 project-brief.md에 위임, prescriptive 규칙 제거 |
 | **Navigation** | v0.8.x | ✅ 완료 | 🧭 Navigation Dispatcher, 5개 파이프라인, Crew Artifact Integration, 100점 품질 감사, Confirm-First 게이트, Wave-Level Pacing, Recalculating Mode |
-| **Naming** | v0.9.0 | ✅ 현재 | 스킬/에이전트 네이밍 재설계 — 직관성과 발견성 강화 |
+| **Naming** | v0.9.0 | ✅ 완료 | 스킬/에이전트 네이밍 재설계 — 직관성과 발견성 강화 |
+| **Self-Verify** | v0.9.2 | ✅ 현재 | state-check 스킬, Iron Law #10, Confirmation Gate Defaults, 멀티 IDE 수정, CI Artifact Index |
 | **Validation** | v1.0 | 🔜 다음 | 실사용 검증, 사용자 피드백 수집 |
 
 ### 다음 단계

package/README.md

@@ -9,67 +9,33 @@
 [![CI](https://github.com/AIDD-Projects/harness/actions/workflows/ci.yml/badge.svg)](https://github.com/AIDD-Projects/harness/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Keep every developer's AI aligned on one project direction.**
+> **Your AI coding agent forgets everything between sessions. kode:harness makes it remember — goals, decisions, failures, and project direction.**
 
-kode:harness is built on **harness engineering** for multi-developer, enterprise-grade AI-assisted development.
+Production-grade guardrails for AI coding agents. Prevents context rot, enforces project direction, and persists state across sessions. Works with **Copilot, Claude, Cursor, Codex, Windsurf, and Gemini**. Zero dependencies.
 
-> **v0.9.0** — Naming redesign (clearer skill/agent names), 6 IDE support, Navigation Dispatcher, 5 Pipelines (🟢🔵🔴🟡🟣), Crew Artifact Integration.
-
-## From Harness to Enterprise Harness Engineering
-
-The concept of an AI "harness" — structured markdown files that guide LLM coding agents — has become a foundational pattern in AI-assisted development. Frameworks like BMAD, gstack, and GSD pioneered this approach for **solo developers**.
-
-This approach takes harness engineering beyond solo tooling. It evolves the harness concept into an **enterprise-grade direction management method** for both multi-developer teams and solo developers. **kode:harness** is the product form of that approach.
-
-| | Traditional Harness | kode:harness + harness engineering |
-|---|---|---|
-| Target | Solo developer | **Multi-developer teams** |
-| Focus | What the AI does | **Where the AI is going** |
-| Direction management | ❌ | ✅ Direction Guard + pivot + Decision Log |
-| Team state sharing | ❌ | ✅ Shared/personal state separation |
-| Token budget | 200+ files | **~25 files (~17K tokens)** — works with small LLMs too |
-
-## The Problem
-
-When one developer uses an AI coding assistant, direction stays consistent. But in **enterprise teams**, each developer runs their own AI sessions — and each AI drifts independently. Developer A's AI refactors toward microservices while Developer B's AI doubles down on the monolith. Without shared direction management, **AI agents across multiple developers pull the project apart.**
-
-kode:harness solves this. It gives every developer's AI the same goals, non-goals, decisions, and project state — so all AI sessions converge on **one direction**, regardless of who's coding or which IDE they use.
-
-## What It Does
-
-kode:harness manages your **project's direction** — goals, decisions, scope — so LLM coding agents stay aligned **across developers and sessions**. Zero dependencies, 6 IDE support, native format generation. The underlying approach is harness engineering for multi-developer and enterprise-grade execution.
-
-- **Direction Guard** — Every coding request is checked against project goals/non-goals before execution
-- **Navigation Dispatcher** — 🧭 Turn-by-Turn navigation guides developers through 5 pipelines with explicit next-step prompts
-- **5 Pipelines** — 🟢 New Dev → 🟕 Continue → 🟤 Bug Fix → 🟡 Direction Change → 🟣 Crew-Driven (external planning artifact integration)
-- **Crew Artifact Integration** — Reads external planning output (PRD, Architecture, ARB Checklist) directly — no manual copy needed
-- **State Files** — 5 markdown files that persist project knowledge across LLM sessions
-- **Skills** — Step-by-step procedures for planning, review, debugging, and direction changes
-- **Agents** — Role-based personas that enforce the workflow (pm, reviewer, lead)
-- **Failure Patterns** — Project-specific failure log that prevents repeat mistakes
-- **Decision Log** — Records why decisions were made so LLMs don't re-debate settled choices
+---
 
 ## Quick Start
 
 ```bash
-# Solo mode (default)
-npx @kodevibe/harness init
-
-# Team mode (multi-developer)
-npx @kodevibe/harness init --team
+npx @kodevibe/harness init          # pick your IDE
 ```
 
-Select your IDE when prompted. Files are installed into the current directory.
-
-After installation, ask your LLM to run the `setup` skill:
-
+```bash
+# Then tell your AI agent:
 > "Run setup to onboard this project."
+```
 
-This scans your codebase and fills all 5 state files automatically.
+That's it. Your AI now has persistent memory, direction guardrails, and self-correction loops.
 
-### Non-interactive
+<details>
+<summary>More install options</summary>
 
 ```bash
+# Team mode (multi-developer direction alignment)
+npx @kodevibe/harness init --team
+
+# Non-interactive (CI/scripts)
 npx @kodevibe/harness init --ide vscode
 npx @kodevibe/harness init --ide claude
 npx @kodevibe/harness init --ide cursor
@@ -78,8 +44,6 @@ npx @kodevibe/harness init --ide windsurf
 npx @kodevibe/harness init --ide antigravity
 ```
 
-### Options
-
 | Flag | Description |
 |------|-------------|
 | `--ide <name>` | Target IDE: `vscode`, `claude`, `cursor`, `codex`, `windsurf`, `antigravity` |
@@ -90,39 +54,70 @@ npx @kodevibe/harness init --ide antigravity
 | `--overwrite` | Overwrite existing files (including state files) |
 | `--version` | Show version number |
 
-### Health Check
+</details>
 
-```bash
-# Verify kode:harness files are installed
-npx @kodevibe/harness doctor
+---
 
-# Verify state files have real content (not just placeholders)
-npx @kodevibe/harness validate
-```
+## The Problem: Context Rot
+
+Your AI coding agent starts every session from zero. By session 3, it's forgotten the architecture decisions from session 1. By session 10, it's re-debating settled choices and contradicting its own earlier work.
+
+In teams, it's worse — Developer A's AI refactors toward microservices while Developer B's AI doubles down on the monolith. **Without shared guardrails, AI agents pull the project apart.**
+
+kode:harness solves this with three mechanisms:
+
+| Mechanism | What it prevents |
+|-----------|-----------------|
+| **State Persistence** | AI forgetting goals, decisions, and progress between sessions |
+| **Direction Guard** | AI drifting away from project goals or contradicting past decisions |
+| **Failure Patterns** | AI repeating the same mistakes across sessions |
 
-### IDE Configuration (Optional)
+---
 
-Large projects with crew artifacts may require increased turn limits:
+## Why not just...?
 
-| IDE | Setting | Recommended |
-|-----|---------|-------------|
-| VS Code | `chat.agent.maxRequests` in settings.json | `100` |
-| Cursor | Auto-managed | Default OK |
-| Windsurf | Auto-managed | Default OK |
-| Claude Code | Terminal-based | Default OK |
+| Approach | Limitation | kode:harness difference |
+|----------|-----------|------------------------|
+| **`.cursorrules` / `copilot-instructions.md`** | Static. No state persistence, no self-correction, no cross-session memory. | Living state files that update every session. Direction Guard checks every request against goals. |
+| **LangChain / CrewAI** | Runtime orchestration for building AI apps. Not for directing AI coding agents. | Markdown-native guardrails that work inside your IDE. No runtime, no SDK. |
+| **BMAD / gstack / GSD** | Built for solo developers. 200+ files. No direction management. | ~25 files (~17K tokens). Direction Guard + Decision Log. Multi-developer team support. |
+| **"I'll just be careful"** | Works until you forget. LLMs don't learn from past sessions. | Automated: `wrap-up` captures lessons, `debug` tracks failures, `reviewer` audits state. |
 
-> This is only needed when running `setup` with crew artifacts on projects that have many existing frameworks. Normal coding/review operations work within default limits.
+---
+
+## What It Does
+
+| Feature | Description |
+|---------|-------------|
+| 🛡️ **Direction Guard** | Every coding request is checked against project goals/non-goals before execution |
+| 🧭 **Navigation Dispatcher** | Turn-by-Turn navigation through 5 pipelines with copy-paste next-step prompts |
+| 📝 **State Persistence** | 5 markdown files that persist project knowledge across LLM sessions |
+| 🔄 **5 Pipelines** | 🟢 New Dev → 🔵 Continue → 🔴 Bug Fix → 🟡 Direction Change → 🟣 Crew-Driven |
+| 🛠️ **10 Skills** | Step-by-step procedures: setup, debug, breakdown, review, pivot, and more |
+| 🤖 **4 Agents** | Role-based personas: pm, reviewer, lead, architect |
+| ⚠️ **Failure Patterns** | Project-specific failure log that prevents repeat mistakes across sessions |
+| 📋 **Decision Log** | Records why decisions were made so LLMs don't re-debate settled choices |
+| 🟣 **Crew Artifact Integration** | Reads external planning output (PRD, Architecture, ARB Checklist) directly |
+
+---
+
+## Health Check
+
+```bash
+npx @kodevibe/harness doctor    # verify files are installed
+npx @kodevibe/harness validate  # verify state files have real content
+```
 
 ## Supported IDEs
 
 | IDE | Dispatcher (always-on) | Skills | Agents |
 |-----|----------------------|--------|--------|
 | **VS Code Copilot** | `.github/copilot-instructions.md` | `.github/skills/*/SKILL.md` | `.github/agents/*.agent.md` |
-| **Claude Code** | `.claude/rules/core.md` | `.claude/skills/*/SKILL.md` | `.claude/agents/*.md` |
-| **Cursor** | `.cursor/rules/core.mdc` | `.cursor/skills/*/SKILL.md` | `.cursor/agents/*.md` |
-| **Codex** | `AGENTS.md` | `.agents/skills/*/SKILL.md` | `.codex/agents/*.toml` |
+| **Claude Code** | `CLAUDE.md` (+ `.claude/rules/core.md`) | `.claude/skills/*/SKILL.md` | `.claude/agents/*.md` |
+| **Cursor** | `.cursor/rules/core.mdc` (+ `AGENTS.md`) | `.cursor/skills/*/SKILL.md` | `.cursor/agents/*.md` |
+| **Codex** | `AGENTS.md` | `.agents/skills/*/SKILL.md` | `.codex/agents/*.md` |
 | **Windsurf** | `.windsurf/rules/core.md` | `.windsurf/skills/*/SKILL.md` | *(agents installed as skills)* |
-| **Antigravity** | `GEMINI.md` | `.gemini/skills/*/SKILL.md` | `.gemini/agents/*.md` |
+| **Antigravity** | `GEMINI.md` (+ `AGENTS.md`) | `.gemini/skills/*/SKILL.md` | `.gemini/agents/*.md` |
 
 All IDEs also get state files (`project-state.md`, `project-brief.md`, `features.md`, `failure-patterns.md`, `dependency-map.md`) in the `docs/` directory.
 
@@ -240,11 +235,13 @@ These 8 rules are enforced across all skills and agents. They form the quality b
 
 See [docs/reference.md](docs/reference.md) for detailed descriptions of every skill, agent, rule, and state file.
 
-## Why kode:harness?
+## Why We Built This
+
+Existing AI coding frameworks focus on **what the AI does** — generate code, run tests, deploy. But the real problem isn't capability. It's **direction**.
 
-### The Core Insight
+When one developer uses AI, direction stays consistent. But in teams, each developer's AI drifts independently. And even solo developers lose direction across sessions — what we call **Context Rot**. The AI forgets architecture decisions, re-debates settled choices, and contradicts its own earlier work.
 
-Existing AI coding frameworks focus on **what the AI does** (generate code, run tests, deploy). kode:harness focuses on **where the AI is going** — ensuring every developer's AI moves in the same direction. harness engineering is the discipline that keeps the whole team on course.
+kode:harness focuses on **where the AI is going**. It gives every AI session — across developers, across IDEs, across time — the same goals, decisions, and project state. The underlying discipline is **harness engineering**: lightweight, markdown-native guardrails that any LLM can read.
 
 ### Crew Artifact Integration (🟣 Pipeline)
 
@@ -262,7 +259,7 @@ Bootstrap auto-detects crew artifacts in `docs/crew/`, `docs/PM/`, `docs/Analyst
 
 Original crew documents are **never modified**. Only the index and tracker are created.
 
-### Comparison
+### How It Compares
 
 | | BMAD v6.2.2 | gstack v0.15.1 | GSD v1.33.0 | kode:harness |
 |---|---|---|---|---|
@@ -277,7 +274,7 @@ Original crew documents are **never modified**. Only the index and tracker are c
 
 ## Roadmap
 
-kode:harness is at **v0.9.0** — naming redesign complete, 6 IDE support, Navigation Dispatcher and Crew Artifact Integration stable.
+kode:harness is at **v0.9.2** — state-check skill, Iron Law #10 (Self-Verify), Confirmation Gate Defaults, multi-IDE installation fixes, and CI Artifact Index for crew mode.
 
 | Phase | Version | Status | Focus |
 |---|---|---|---|
@@ -285,7 +282,8 @@ kode:harness is at **v0.9.0** — naming redesign complete, 6 IDE support, Navig
 | **Hardening** | v0.6.5 | ✅ Done | 10 skills, 4 agents, Iron Laws, CLI batch/doctor/validate, merge conflict SOP, direction drift detection |
 | **Flexibility** | v0.7.x | ✅ Done | Delegate team conventions to project-brief.md, remove prescriptive rules |
 | **Navigation** | v0.8.x | ✅ Done | 🧭 Navigation Dispatcher, 5 Pipelines, Crew Artifact Integration, 100-point quality audit, Confirm-First gate, Wave-Level Pacing, Recalculating Mode |
-| **Naming** | v0.9.0 | ✅ Current | Skill/agent naming redesign for clarity and discoverability |
+| **Naming** | v0.9.0 | ✅ Done | Skill/agent naming redesign for clarity and discoverability |
+| **Self-Verify** | v0.9.2 | ✅ Current | state-check skill, Iron Law #10, Confirmation Gate Defaults, multi-IDE fix, CI Artifact Index |
 | **Validation** | v1.0 | 🔜 Next | Real-world project adoption, user feedback collection |
 
 ### What's Next

package/harness/agents/pm.md

@@ -63,6 +63,36 @@ Apply these insights when creating the implementation plan. If the memory file i
 
 > **Team Mode**: In Team mode, agent memory is personal (`.harness/agent-memory/`). Each developer accumulates their own planning insights.
 
+### Step 0.7: Feature Roadmap Planning (Draft & Correct)
+
+**Trigger**: `docs/project-brief.md`에 `## Feature Roadmap` 섹션이 없을 때
+
+<!-- CREW_MODE_START -->
+**Crew 파이프라인(🟣)**: FR목록이 이미 Roadmap 역할을 하므로 이 Step을 skip한다.
+<!-- CREW_MODE_END -->
+
+1. `docs/project-brief.md`의 Goals + `docs/dependency-map.md`의 현재 모듈 구조를 읽는다
+2. Phase 구조의 Feature Roadmap **초안**을 생성한다:
+   ```
+   ## Feature Roadmap
+   
+   ### Phase 1 — Core (Goal 달성 필수)
+   - [ ] F-001: [기능명] — [어떤 Goal에 대응하는지]
+   - [ ] F-002: ...
+   
+   ### Phase 2 — Enhancement (사용성/완성도)
+   - [ ] F-003: ...
+   
+   ### Phase 3 — Nice-to-have
+   - [ ] F-004: ...
+   ```
+3. 사용자에게 초안을 제시한다: **"이 Feature Roadmap을 검토하고, 추가/삭제/순서 변경을 알려주세요."**
+   > **물어보지 말고, 초안을 만들어서 교정받는다.** 빈 칸을 채우는 것보다 틀린 것을 고치는 것이 쉽다.
+4. 사용자 교정을 반영한 최종 Roadmap을 `docs/project-brief.md`에 `## Feature Roadmap` 섹션으로 기록한다
+5. Feature Roadmap이 확정되면 아래 "For New Feature" 절차로 진행한다
+
+> **pivot 이후**: pivot이 `project-brief.md`를 업데이트하면, pm은 변경된 Roadmap을 읽고 Checkpoint에서 반영한다.
+
 ### For New Feature
 
 1. Read `docs/project-brief.md` to understand project vision, goals, **non-goals**, and **Decision Log**
@@ -196,6 +226,16 @@ After user approves the plan, perform these writes in order:
 
 If any write fails, report the failure and retry. Do NOT proceed to 🧭 with incomplete state files.
 
+### ✅ MANDATORY: Self-Verify with state-check (Iron Law #10)
+
+After the Post-Approval state writes complete, run the `state-check` skill:
+1. Invoke `state-check` skill — deterministic verification of state file consistency
+2. If state-check returns **PASS** → proceed to output 🧭 Next Step
+3. If state-check returns **WARN** → include the warnings in the plan output, then proceed
+4. If state-check returns **FAIL** → do NOT output STATUS: DONE. Fix the listed drift, then re-run state-check.
+
+> Iron Law #10 (Self-Verify) applies to every agent. The pm runs state-check **after** state writes — not before — because the writes are what create the consistency to verify.
+
 ## Output Format
 
 ### New Feature Plan
@@ -249,6 +289,50 @@ Use this format when Crew Artifact Index exists in project-brief.md. If no Artif
 ```
 <!-- CREW_MODE_END -->
 
+## Sprint Completion Checkpoint
+
+**Trigger**: 현재 Sprint의 모든 Story가 ✅ 완료되었을 때 (reviewer pass → pm checkpoint)
+
+이 절차는 Sprint 종료 시 자동으로 실행된다. "계속할까요?"가 아니라 **구체적 선택을 강제**한다.
+
+### 절차
+
+1. **진척 현황 읽기**:
+<!-- CREW_MODE_START -->
+   - 🟣 crew 파이프라인: `docs/project-brief.md`의 Validation Tracker에서 FR Coverage를 읽는다
+<!-- CREW_MODE_END -->
+   - 🟢🔵 no-crew 파이프라인: `docs/project-brief.md`의 Feature Roadmap을 읽는다
+
+2. **Phase별 진척 표시**:
+   ```
+   📊 Feature Roadmap Progress
+   Phase 1 (Core):        ████████░░ 4/5
+   Phase 2 (Enhancement): ░░░░░░░░░░ 0/3
+   Phase 3 (Nice-to-have): ░░░░░░░░░░ 0/2
+   ```
+
+3. **선택지 제시** (Yes/No 아님 — Selection Forcing):
+   ```
+   다음 Sprint에 포함할 기능을 선택하세요:
+
+   Phase 1 (Core) — 미완료:
+     [ ] F-005: [기능명]
+
+   Phase 2 (Enhancement):
+     [ ] F-006: [기능명]
+     [ ] F-007: [기능명]
+
+   🏁 마무리: 현재 상태로 프로젝트를 완료하고 wrap-up 진행
+   ```
+   > **"계속"은 선택지에 없다.** 사용자는 구체적 기능을 골라야 하거나, 명시적으로 "마무리"를 선택해야 한다.
+
+4. **사용자 선택에 따라 분기**:
+   - **기능 선택** → 선택된 기능으로 Sprint 계획 (위의 "For New Feature" 절차 진행)
+   - **"마무리" 선택** → 🧭 Next Step을 `wrap-up`으로 출력
+   - Feature Roadmap에 없는 기능 추가 요청 → Roadmap에 먼저 추가한 후 Sprint 계획
+
+5. **Roadmap 업데이트**: 완료된 기능의 체크박스를 `[x]`로 변경하고 `docs/project-brief.md`에 기록
+
 ### Architecture Query Response
 ```markdown
 ## Module: [name]

package/harness/agents/reviewer.md

@@ -65,6 +65,30 @@ Changed file list (user-provided or from `git diff --name-only`)
 - [ ] Constructor parameters match actual source (FP-002)
 - [ ] **Common First (Iron Law #9)**: No crew-specific logic outside crew marker blocks. All features must work without crew artifacts.
 
+<!-- CREW_MODE_START -->
+**Step 2.5: CI Standards Compliance (🟣 Pipeline only)**
+
+**Trigger**: Changed files include any build/CI artifacts:
+- `Dockerfile`, `.dockerignore`
+- `.github/workflows/*.yml`, `.gitlab-ci.yml`, `Jenkinsfile`
+- `pom.xml`, `build.gradle`, `gradle.properties`
+- `package.json` (scripts changes), `yarn.lock`, `package-lock.json`
+- `pyproject.toml`, `requirements.txt`, `Pipfile`, `poetry.lock`
+- `go.mod`, `go.sum`
+
+**Procedure**:
+1. Check if `docs/project-brief.md` has a `## CI Artifact Index` section (or `.harness/ci-index.md` exists). If neither → skip this step.
+2. Read the project's primary language/build tool from `docs/project-brief.md` Key Technical Decisions.
+3. Match the language/build tool to a row in the CI Artifact Index → get the reference URL and Key Constraints.
+4. Surface the reference in review output under a `### CI Standards Compliance` section:
+   - Reference URL (the indexed guide)
+   - Key Constraints listed in the index (echoed back so the user does not need to re-read the guide)
+   - `[CI-STANDARD]` flag if any obvious mismatch is detected against a listed constraint (best-effort LLM judgment based only on the changed files)
+5. **Warning only — do NOT block commit**. The user (or a human reviewer) decides whether the changes meet company standards. The reviewer agent never asserts compliance; it only points to the authoritative guide.
+
+If neither `## CI Artifact Index` nor `.harness/ci-index.md` is present → skip this step entirely (also true for 🟢/🔵/🔴 pipelines).
+<!-- CREW_MODE_END -->
+
 **Step 3: Test Integrity (sync-tests skill)**
 - [ ] Interface changes have synchronized mocks (FP-001)
 - [ ] New features have tests
@@ -125,7 +149,11 @@ If no Crew Artifact Index → skip this step entirely.
 
 **Step 8: State File Audit**
 
-Verify that state file updates actually happened. Check each:
+Verify that state file updates actually happened. **Run the `state-check` skill first** (Iron Law #10) for deterministic cross-checks, then perform the human-judgment items below that state-check cannot mechanically verify.
+
+> `state-check` covers: file existence, Story↔Feature consistency, dependency-map↔src/ drift, and agent-memory legacy names. The items below complement it with semantic checks the skill cannot perform.
+
+After running state-check, also verify:
 - [ ] **docs/project-state.md**: If stories were worked on, is Quick Summary current? Are story statuses updated?
 - [ ] **docs/features.md**: If new features were added, are they registered? If features were completed, is status updated?
 - [ ] **Cross-check features ↔ stories**: If a feature status is `✅ done` in features.md, verify all related stories in project-state.md are also `done`. If stories are `done` but their feature is still `🔄 in-progress`, flag as `[STATE-AUDIT]`.
@@ -180,6 +208,9 @@ If review is BLOCKED → do NOT suggest commit. Fix first.
 - Test integrity: ✅ / ⚠️ (detail)
 - Security check: ✅ / ❌ (detail)
 - Failure pattern check: ✅ / ⚠️ (FP-NNN)
+<!-- CREW_MODE_START -->
+- CI standards (🟣): ✅ / ⚠️ [CI-STANDARD] (detail) — included only when CI Artifact Index exists
+<!-- CREW_MODE_END -->
 
 STATUS: DONE / DONE_WITH_CONCERNS / BLOCKED
 ```

package/harness/core-rules.md

@@ -1,6 +1,6 @@
-# Musher
+# kode:harness
 
-This project uses Musher for structured AI-assisted development.
+This project uses kode:harness for structured AI-assisted development.
 Skills and agents work together through shared state files.
 **Every response must end with a 🧭 Next Step block** — guide the user to the next action.
 
@@ -54,6 +54,7 @@ When external planning artifacts exist (requirements, analysis, design documents
 
 > Crew artifacts are detected by: `docs/crew/` directory, `docs/PM/`+`docs/Analyst/`+`docs/ARB/` directories, or user explicitly provides requirements/design documents (e.g., mentions "PRD", "산출물", "설계서", or provides file paths to planning artifacts).
 > **Reference, don't summarize**: setup creates a Crew Artifact Index (path table) in project-brief.md — each skill reads the original artifact directly via the indexed path.
+> Crew mode also enables the **CI Artifact Index** reference layer: if `docs/project-brief.md` contains `## CI Artifact Index`, reviewer Step 2.5 and release Step 3.5 surface the indexed company CI/CD guide when build/CI files change. The guide content stays external; only the path and key constraints are indexed.
 > This pipeline produces the same state files as 🟢 — the difference is the INPUT source and the addition of Validation Tracker for traceability.
 <!-- CREW_MODE_END -->
 
@@ -98,7 +99,7 @@ When a skill or agent reports STATUS: DONE, output the next step in this format:
 | `lead` (story started) | [Coding] | "S{N}-{M} 구현을 시작해줘" → 완료 후 **새 채팅**에서 `@reviewer` 호출 |
 | [Coding done] | `reviewer` | "S{N}-{M} 코드를 리뷰해줘" |
 | `reviewer` (pass, more stories) | Commit → `lead` | \"커밋 후 다음 Story는?\" |
-| `reviewer` (pass, all done) | Commit → `wrap-up` | \"커밋 후 세션 마무리해줘\" |
+| `reviewer` (pass, sprint all done) | Commit → `pm` checkpoint | \"커밋 후 Sprint 완료 — pm checkpoint 실행\" |
 | `reviewer` (STATE-AUDIT) | `wrap-up` | "state 파일을 정리하고 세션 마무리해줘" |
 | `debug` | `reviewer` | "수정한 코드를 리뷰해줘" |
 | `pivot` | `pm` | "변경된 방향에 맞춰 재계획해줘" |
@@ -134,3 +135,16 @@ These laws are enforced across all skills and agents. Violations should be flagg
 7. **Feature Registry**: When adding a feature, register it in features.md in the same commit.
 8. **Session Handoff**: At session end, update project-state.md Quick Summary so the next session has context.
 9. **Common First**: All features must work at Common level (🟢🔵🔴) without crew dependency. Crew-specific logic must be inside crew marker blocks only. Never add crew-only code to Common paths.
+10. **Self-Verify**: Every agent MUST run the `state-check` skill before reporting STATUS: DONE. If state-check returns FAIL, the agent must NOT report DONE — fix the listed drift first. WARN may proceed but warnings must be included in the agent's output.
+
+## Confirmation Gate Defaults
+
+When the user does not respond to a confirmation prompt within the conversation, agents must apply the SAFE default — never assume implicit approval. The SAFE default for each gate:
+
+| Gate | Owner | SAFE default (no response) | Rationale |
+|------|-------|---------------------------|-----------|
+| Plan Confirmation | `pm` | Do NOT write `features.md` / `project-state.md` / `dependency-map.md`. Hold the plan and re-prompt. | Prevents state file pollution from rejected plans. |
+| Scope Check | `lead` | NO — block edits outside the current Story scope. | Iron Law #3 (Scope Compliance) cannot be silently bypassed. |
+| Commit Approval | `reviewer` | Hold the commit. Output the proposed commit command but do NOT execute it. | Code commits are hard to reverse without `git reset` — user must explicitly approve. |
+
+Any agent that wants to proceed past one of these gates without explicit approval is in violation of Iron Law #10 and must STOP.

package/harness/project-brief.md

@@ -1,6 +1,6 @@
 # Project Brief
 
-> **Fill this out immediately after running `musher init`.** The Planner agent uses this file for Direction Guard — without it, scope drift cannot be prevented.
+> **Fill this out immediately after running `@kodevibe/harness init`.** The Planner agent uses this file for Direction Guard — without it, scope drift cannot be prevented.
 
 ## Vision
 
@@ -106,6 +106,28 @@
    Status legend: ⬜ Not started, 🟡 In progress, ✅ Done
    Update flow: setup creates → pm fills Story column → wrap-up updates Status
 -->
+
+## CI Artifact Index
+
+<!-- 🟣 Pipeline only — references to company CI/CD standard guides.
+   reviewer Step 2.5 and release Step 3.5 read this index to surface the relevant guide
+   when build/CI files change or before deploy.
+
+   Reference Layer pattern: the original guide lives outside this repo (Confluence,
+   internal wiki, etc.). This index stores ONLY the path/URL and the key constraints
+   so that AI agents do not need to re-read the guide every time. The actual guide
+   content is never copied into this repository.
+
+   | Language | Build Tool | Reference URL | Key Constraints |
+   |----------|-----------|---------------|-----------------|
+   | _(예: Java)_ | _(예: Maven)_ | _(URL placeholder — fill with the company guide URL)_ | _(예: 표준 base image 사용, ACR 캐시 사용, 보안 스캔 단계 포함)_ |
+
+   Tips for filling this table:
+   - 1행만 채워도 충분 — 프로젝트의 주 언어/빌드도구만 기재
+   - 다중 서비스 (모놀리식 X, 멀티 모듈 O)인 경우 서비스/모듈별로 한 행씩
+   - Key Constraints는 LLM이 변경된 파일 대비 자동 점검할 수 있도록 짧고 검증 가능한 형태로 작성 (e.g., "base image: company-base:latest", "cache: 회사 ACR 미러 사용")
+   - Reference URL은 회사 내부 가이드 위치 (Confluence, wiki 등). OSS 코드베이스에는 절대 회사 URL을 커밋하지 않음 — 이 파일은 사용자 로컬 또는 사내 저장소에서만 채움.
+-->
 <!-- CREW_MODE_END -->
 
 ## Key Technical Decisions

package/harness/skills/release.md

@@ -44,6 +44,24 @@ Verify all state files are up to date:
 - [ ] **Validation Tracker FR Coverage**: All Functional Requirements (FR) have at least one mapped Story (`docs/project-brief.md` → Validation Tracker)
 - [ ] **Validation Tracker ARB Fail Resolution**: All ARB Fail items resolved (✅) or explicitly deferred with rationale
 - [ ] **KPI Coverage**: All KPIs addressed or deferred with documented reason
+- [ ] **CI Standards (🟣)**: If `docs/project-brief.md` has `## CI Artifact Index`, deploy artifacts (Dockerfile, CI workflow, build config) match the indexed guide's Key Constraints (see Step 3.5)
+<!-- CREW_MODE_END -->
+
+<!-- CREW_MODE_START -->
+### Step 3.5: CI Standards Compliance (🟣 Pipeline only)
+
+If `docs/project-brief.md` has a `## CI Artifact Index` section:
+
+1. Read the indexed reference URL and Key Constraints for the project's primary language/build tool.
+2. Verify the deployed configuration matches each Key Constraint listed in the index:
+   - Base image (e.g., must use the standard company base image)
+   - Build cache strategy (e.g., must use the company-approved cache mirror)
+   - Required CI stages (e.g., security scan, signing)
+   - Any other constraint listed in the index row
+3. If **any** constraint is unmet → mark **NOT_READY** and list the unmet constraints in the verdict.
+4. If `## CI Artifact Index` does not exist (or is empty) → skip this step entirely.
+
+This step references the indexed company guide; it does not embed the guide content itself. The reviewer agent (Step 2.5) catches CI standard issues earlier in the cycle; this step is the final gate before deploy.
 <!-- CREW_MODE_END -->
 
 ### Step 4: Security Scan
@@ -77,6 +95,9 @@ Verify all state files are up to date:
 - [x/✗] Security scan clean
 - [x/✗] Git status clean
 - [x/✗] Release notes prepared
+<!-- CREW_MODE_START -->
+- [x/✗/–] CI standards (🟣): [verdict] — `–` if no CI Artifact Index
+<!-- CREW_MODE_END -->
 
 ### Verdict: READY / NOT_READY
 [blockers if not ready]

package/harness/skills/setup.md

@@ -2,13 +2,13 @@
 
 ## Purpose
 
-Onboard a new or existing project into Musher by filling **state files AND rules files** automatically.
+Onboard a new or existing project into kode:harness by filling **state files AND rules files** automatically.
 Solves the cold-start problem: users don't know which `.md` files to fill or how.
 One command does everything — no manual editing required.
 
 ## When to Apply
 
-- Right after running `musher init` on a new project
+- Right after running `@kodevibe/harness init` on a new project
 - When joining an existing project that has empty state files
 - When state files are outdated and need a refresh
 - When any agent reports "state files are empty"
@@ -49,6 +49,16 @@ One command does everything — no manual editing required.
 
 4. **Scan for existing tests**: Find test files and map them to source modules
 5. **Scan imports/dependencies**: Trace module relationships from import statements
+6. **Detect legacy agent-memory files** (v0.9 migration):
+   - Look in `docs/agent-memory/` and `.harness/agent-memory/` for these legacy names from earlier framework versions:
+     - `planner.md` → should be renamed to `pm.md`
+     - `sprint-manager.md` → should be renamed to `lead.md`
+     - `navigator.md` → should be renamed to `lead.md`
+     - `builder.md` → should be renamed to `pm.md`
+   - For each legacy file found:
+     - If the new name does NOT exist → offer to rename: `mv {legacy}.md {new}.md` (preserves history)
+     - If BOTH exist → ask the user which to keep, or merge contents into the new name and delete the legacy
+   - Confirm with the user before renaming. Record the migration in `docs/project-state.md` Recent Changes.
 
 **Do NOT modify any code files in this phase.**
 
@@ -137,6 +147,7 @@ Using data from Phase 1 + Phase 2, fill the following files:
 <!-- CREW_MODE_START -->
 - Crew Artifact Index → from Phase 1.5 (🟣 pipeline only — leave as template comment for 🟢 pipeline)
 - Validation Tracker → from Phase 1.5 (🟣 pipeline only — leave as template comment for 🟢 pipeline)
+- CI Artifact Index → 🟣 pipeline only. After filling crew fields, ask the user: "회사 CI/CD 표준 가이드(Dockerfile/CI 파이프라인 규약)가 있다면 한 줄로 인덱싱하시겠습니까? (URL과 Key Constraints만 기록 — 가이드 본문은 외부에 둠)". If yes, fill one row in the CI Artifact Index table with their primary language/build tool, the guide URL, and 2-3 short Key Constraints. If no or skip → leave template comment as-is. Never commit company-specific URLs to the OSS template — this row is meant to be filled in the user's local/private project-brief.md only.
 <!-- CREW_MODE_END -->
 - Key Technical Decisions → from Phase 1 scan + user answer #4, #5
 
@@ -307,14 +318,14 @@ When starting a NEW session (not during setup), read these files in order:
 When running setup in Team mode:
 
 ### New Project (first developer)
-1. Run `musher init --team` to create shared + personal state files
+1. Run `@kodevibe/harness init --team` to create shared + personal state files
 2. Fill all state files via normal setup procedure
 3. Commit shared files (docs/) to git
 4. Push to remote — teammates will clone this
 
 ### Joining Developer (existing project)
 1. Clone the repository (shared docs/ already exist)
-2. Run `musher init --team` — only personal files (.harness/) are created; shared files are skipped
+2. Run `@kodevibe/harness init --team` — only personal files (.harness/) are created; shared files are skipped
 3. **DO NOT re-run setup interviews** — shared state is already filled by the first developer
 4. Review docs/project-brief.md to understand project goals
 5. Create your personal .harness/project-state.md with your current Story assignment

package/harness/skills/state-check.md

@@ -0,0 +1,189 @@
+# State Check
+
+## Purpose
+
+Deterministic verification that state files are internally consistent and not silently drifting.
+This skill exists because LLM self-checks miss state drift — every Iron Law #10 self-verify pass should run this skill before reporting STATUS: DONE.
+
+## Invoked By
+
+- **pm** agent — Post-Approval step (after writing features.md / project-state.md / dependency-map.md)
+- **reviewer** agent — Step 8 (State File Audit) — supplements existing STATE-AUDIT logic
+- **wrap-up** skill — Step 5.5 (after dependency-map verify)
+- **User** (direct) — "state 파일 일관성 점검해줘"
+
+## When to Apply
+
+- After ANY agent writes to state files (mandatory before STATUS: DONE)
+- Before committing changes that touch `docs/` or `.harness/`
+- When the user reports state files "feel out of sync"
+- Periodically — even when nothing recently changed (drift accumulates silently)
+
+## Procedure
+
+> **Philosophy**: Use deterministic cross-checks, not LLM intuition. Each check has a single PASS/WARN/FAIL outcome that does not depend on judgment. The LLM performs the file reads and comparisons listed below — no shell scripts, no external dependencies.
+
+### Check 1: Required State Files Exist with Non-Placeholder Content
+
+For each required state file, verify it exists and is not just a template stub:
+
+| File | Placeholder Sentinel (FAIL if present) |
+|------|----------------------------------------|
+| `docs/project-state.md` (or `.harness/`) | `S1-1 \| Project scaffolding` |
+| `docs/project-brief.md` | `This is the north star for all decisions` |
+| `docs/dependency-map.md` | `Add new modules above this line` |
+| `docs/features.md` | `Add new features above this line` |
+
+For each file:
+- **Missing** → FAIL: `[FAIL] {file} not found`
+- **Sentinel present** → WARN: `[WARN] {file} contains template placeholder — run setup`
+- **Real content** → PASS
+
+> `failure-patterns.md` is excluded — FP-001~004 templates with Frequency: 0 are normal initial state.
+
+### Check 2: features.md ↔ project-state.md Story Consistency
+
+1. Read all `✅ done` Stories from `docs/project-state.md` (or `.harness/project-state.md` in Team mode) Story Status table
+2. Read `docs/features.md` Feature Registry
+3. For each `✅ done` Story:
+   - If Story has `[FR-NNN]` prefix → must map to a feature row with that FR reference
+   - Otherwise → must map to at least one feature row whose Key Files overlap with the Story's Scope
+4. Outcomes:
+   - Story ✅ done but no matching feature row → FAIL: `[FAIL] Story {S-N-M} done but no feature registered`
+   - Story ✅ done but feature still `⬜ planned` → FAIL: `[FAIL] Feature status drift — {feature} is planned but Story {S-N-M} is done`
+   - All consistent → PASS
+
+### Check 3: dependency-map.md vs Actual src/ Directory Count
+
+> **Goal**: detect orphan modules (in src/ but not registered) and stale entries (registered but deleted).
+
+1. Read `docs/dependency-map.md` and count rows in the Module table (excluding header / comment lines like `Add new modules above this line`)
+2. Inspect the source root (priority order — first existing path wins):
+   - `src/`
+   - `lib/`
+   - `app/`
+   - Project root (if no src-like directory)
+3. Count direct child directories of the source root that look like modules (skip `__pycache__/`, `node_modules/`, `dist/`, `build/`, `.next/`, hidden dirs)
+4. Compare:
+   - `|map_count - dir_count| / max(map_count, dir_count) <= 0.20` → PASS
+   - Difference > 20% → WARN: `[WARN] dependency-map has {map_count} modules but src/ has {dir_count} directories — likely drift`
+   - One side is 0 and the other > 0 → FAIL: `[FAIL] dependency-map empty but {dir_count} src directories exist (or vice versa)`
+
+> For tiny projects (<3 modules), this check always passes — see setup.md "Small Project Guidance".
+
+### Check 4: agent-memory Legacy Names
+
+Verify no legacy agent-memory file names remain after the v0.9 rename (planner→pm, sprint-manager→lead, navigator→lead, builder→pm):
+
+1. Scan `docs/agent-memory/` (and `.harness/agent-memory/` in Team mode)
+2. If any of these legacy names exist → WARN with rename suggestion:
+   - `planner.md` → rename to `pm.md`
+   - `sprint-manager.md` → rename to `lead.md`
+   - `navigator.md` → rename to `lead.md`
+   - `builder.md` → rename to `pm.md`
+3. If both legacy and new names exist for the same role → FAIL: `[FAIL] Both {legacy} and {new} exist — merge then delete legacy`
+
+### Check 5: Iron Law #10 Self-Verify Marker
+
+When invoked from another agent (pm, reviewer, wrap-up), confirm the calling agent declared its self-verify intent:
+- The calling agent should have written nothing else after invoking state-check
+- If the agent already produced STATUS: DONE before calling state-check → WARN: `[WARN] Iron Law #10 violation — STATUS: DONE issued before state-check`
+
+This check is informational — humans calling the skill directly can ignore it.
+
+<!-- CREW_MODE_START -->
+### Check 6 (🟣 Pipeline only): Validation Tracker Coverage
+
+If `docs/project-brief.md` contains a `## Validation Tracker` section:
+
+1. Read FR Coverage table — for each FR with at least one Story, that Story must exist in project-state.md Story Status
+2. Read ARB Fail Resolution table — for each Fail item with a Story link, the Story must exist
+3. Outcomes:
+   - Tracker references missing Story → FAIL: `[FAIL] Validation Tracker references {S-N-M} but Story not found in project-state.md`
+   - Story marked ✅ done in project-state but Tracker still shows ⬜ → WARN: `[WARN] Validation Tracker out of sync — {Story} done but {KPI/FR/ARB} status unchanged`
+
+If no Validation Tracker → skip.
+<!-- CREW_MODE_END -->
+
+## Output Format
+
+```
+## State Check Result
+
+### Check 1: Required Files
+- [x] docs/project-state.md — has content
+- [x] docs/project-brief.md — has content
+- [x] docs/dependency-map.md — has content
+- [x] docs/features.md — has content
+
+### Check 2: Story ↔ Feature Consistency
+- {N} ✅ done Stories cross-checked
+- {M} matched / {K} drifted
+
+### Check 3: dependency-map ↔ src/ Coverage
+- map: {N} modules, src/: {M} directories — {diff}% drift
+
+### Check 4: Agent Memory Legacy Names
+- No legacy names found (or list of legacy files to rename)
+
+<!-- CREW_MODE_START -->
+### Check 6: Validation Tracker (🟣)
+- {N} FR references checked / {M} drifted
+<!-- CREW_MODE_END -->
+
+### Findings
+- [PASS] {N} checks passed
+- [WARN] {N} warnings: {list}
+- [FAIL] {N} failures: {list}
+
+STATUS: PASS | WARN | FAIL
+```
+
+### Result Interpretation
+
+- **PASS** — all checks passed; calling agent may proceed with STATUS: DONE
+- **WARN** — non-blocking issues; calling agent should include warnings in its output but may proceed
+- **FAIL** — blocking; calling agent must NOT report STATUS: DONE until failures are resolved
+
+### 🧭 Navigation — After State Check
+
+When invoked directly (not by another agent), append:
+
+```
+---
+🧭 Next Step
+→ Result: {PASS | WARN | FAIL}
+→ Next: {fix the listed issues, then re-run state-check} or {return to caller}
+→ Why: state-check is the deterministic gate before STATUS: DONE
+→ Pipeline: utility skill (no pipeline step)
+---
+```
+
+When invoked by another agent (pm/reviewer/wrap-up), control returns to the caller — no separate 🧭 block.
+
+## Rules
+
+- Do NOT invent data. Read the files and report exactly what you find.
+- Do NOT modify state files in this skill — diagnosis only. Caller decides remediation.
+- Do NOT run shell scripts. All checks are markdown-described file reads + comparisons.
+- If a check cannot be performed (e.g., `docs/` missing entirely), report it as FAIL and stop — further checks are meaningless.
+
+## Anti-patterns
+
+| Anti-pattern | Correct Approach |
+|---|---|
+| Skip state-check because "I just wrote those files" | Run it anyway — Iron Law #10 mandates self-verify |
+| Report PASS when one check could not be performed | Report FAIL with reason; PASS requires all applicable checks ran |
+| Auto-fix drift inside this skill | This skill is read-only diagnosis — caller fixes drift |
+
+<!-- TEAM_MODE_START -->
+## Team Mode: State Check
+
+In Team mode:
+- Personal state files live in `.harness/` (project-state.md, failure-patterns.md, agent-memory/)
+- Shared files live in `docs/` (project-brief.md, features.md, dependency-map.md)
+- Check 1 looks in BOTH directories — file exists if either path has it
+- Check 2 (Story ↔ Feature) reads `.harness/project-state.md` (personal) against `docs/features.md` (shared) — drift is per-developer
+- Check 4 (legacy agent-memory) scans `.harness/agent-memory/` only
+- If `git pull` was skipped before this run, shared-file checks may report stale data — note this in WARN output
+<!-- TEAM_MODE_END -->

package/harness/skills/wrap-up.md

@@ -4,7 +4,7 @@
 
 Capture lessons from the current session before ending.
 Updates docs/failure-patterns.md with new patterns and refreshes docs/project-state.md Quick Summary.
-This is Musher's memory mechanism — without it, the same mistakes repeat across sessions.
+This is kode:harness's memory mechanism — without it, the same mistakes repeat across sessions.
 
 ## Invoked By
 
@@ -131,8 +131,12 @@ For each issue/error that occurred in this session:
    - New module without dependency-map entry → **add it now**
    - Interface change without Interface Change Log entry → **add it now**
 4. Cross-reference `docs/features.md` Key Files against `docs/dependency-map.md` modules — flag orphaned modules
+5. **Run `state-check` skill** (Iron Law #10 — mandatory before STATUS: DONE):
+   - PASS → proceed to Step 5.6
+   - WARN → include warnings in the final wrap-up report, then proceed
+   - FAIL → fix the listed drift (update affected state files), then re-run state-check until PASS or WARN
 
-> **Self-check**: `docs/dependency-map.md`에 이 세션에서 새로 추가한 모듈이 모두 등록되었는지 확인. 누락 시 즉시 추가.
+> **Self-check**: `docs/dependency-map.md`에 이 세션에서 새로 추가한 모듈이 모두 등록되었는지 확인. 누락 시 즉시 추가. state-check가 PASS 또는 WARN을 반환해야 다음 단계로 진행합니다.
 
 ### Step 5.6: Resolve STATE-AUDIT Flags (if applicable)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kodevibe/harness",
-  "version": "0.9.0",
+  "version": "0.9.3",
   "description": "kode:harness — harness engineering for keeping every developer's AI aligned on one project direction.",
   "keywords": [
     "llm",

package/src/init.js

@@ -38,6 +38,7 @@ const SKILLS = [
   { id: 'pivot', desc: 'Propagate direction changes across all state files. Use when project goals, technology, scope, or architecture changes.' },
   { id: 'pr-review', desc: 'Review external Pull Requests for quality, security, and direction alignment. Use when reviewing incoming PRs.' },
   { id: 'release', desc: 'Pre-deployment validation checklist. Use before deploying, publishing, or creating release tags.' },
+  { id: 'state-check', desc: 'Deterministic verification of state file consistency. Use before STATUS: DONE (Iron Law #10) and when state drift is suspected.' },
 ];
 
 const AGENTS = [
@@ -250,8 +251,14 @@ function generateVscode(targetDir, overwrite, mode = 'solo', crew = false) {
 }
 
 function generateClaude(targetDir, overwrite, mode = 'solo', crew = false) {
-  // .claude/rules/core.md — dispatcher only (no paths = always loaded)
-  writeFile(targetDir, '.claude/rules/core.md', resolveContent(readTemplate('core-rules.md'), mode, crew), true);
+  const coreRules = resolveContent(readTemplate('core-rules.md'), mode, crew);
+
+  // CLAUDE.md — Claude Code's canonical project memory file (auto-loaded at session start)
+  writeFile(targetDir, 'CLAUDE.md', coreRules, true);
+
+  // .claude/rules/core.md — secondary dispatcher (also auto-loaded by Claude Code's
+  // InstructionsLoaded mechanism; kept for redundancy and rule-discovery tooling)
+  writeFile(targetDir, '.claude/rules/core.md', coreRules, true);
 
   // Skills (SKILL.md with frontmatter)
   writeSkills(targetDir, '.claude/skills', true, mode, crew);
@@ -271,6 +278,9 @@ function generateCursor(targetDir, overwrite, mode = 'solo', crew = false) {
     coreRules;
   writeFile(targetDir, '.cursor/rules/core.mdc', coreMdc, true);
 
+  // AGENTS.md — Cursor CLI also reads project-root AGENTS.md as a rule
+  writeFile(targetDir, 'AGENTS.md', coreRules, true);
+
   // Skills (.cursor/skills — invokable by mentioning skill name)
   writeSkills(targetDir, '.cursor/skills', true, mode, crew);
 
@@ -282,14 +292,16 @@ function generateCursor(targetDir, overwrite, mode = 'solo', crew = false) {
 }
 
 function generateCodex(targetDir, overwrite, mode = 'solo', crew = false) {
-  // AGENTS.md — dispatcher only
+  // AGENTS.md — Codex CLI's canonical project instructions file (the only file
+  // Codex CLI auto-loads). All skill/agent references must be discoverable from here.
   writeFile(targetDir, 'AGENTS.md', resolveContent(readTemplate('core-rules.md'), mode, crew), true);
 
   // Skills (SKILL.md with frontmatter — invokable via $skill-name)
   writeSkills(targetDir, '.agents/skills', true, mode, crew);
 
-  // Agents (.codex/agents/ — Codex TOML agent definition files)
-  writeAgentsAsToml(targetDir, '.codex/agents', true, mode, crew);
+  // Agents (.codex/agents/ — markdown subagent files with YAML frontmatter,
+  // matching the Cursor/Claude convention used as a Codex compat directory)
+  writeAgentsAsMd(targetDir, '.codex/agents', true, mode, crew);
 
   // State files (respect user's --overwrite for data files)
   writeStateFiles(targetDir, overwrite, mode, crew);
@@ -314,8 +326,14 @@ function generateWindsurf(targetDir, overwrite, mode = 'solo', crew = false) {
 }
 
 function generateAntigravity(targetDir, overwrite, mode = 'solo', crew = false) {
-  // GEMINI.md — project context (always loaded by Gemini CLI)
-  writeFile(targetDir, 'GEMINI.md', resolveContent(readTemplate('core-rules.md'), mode, crew), true);
+  const coreRules = resolveContent(readTemplate('core-rules.md'), mode, crew);
+
+  // GEMINI.md — Gemini CLI / Antigravity's canonical project context file
+  writeFile(targetDir, 'GEMINI.md', coreRules, true);
+
+  // AGENTS.md — Antigravity also follows the AGENTS.md convention shared by
+  // Codex / Cursor CLI; emitting it broadens compatibility with no downside
+  writeFile(targetDir, 'AGENTS.md', coreRules, true);
 
   // Skills (.gemini/skills/ — SKILL.md format)
   writeSkills(targetDir, '.gemini/skills', true, mode, crew);
@@ -520,14 +538,16 @@ function runDoctor(targetDir) {
     }
   }
 
-  // Check for IDE-specific files (detect which IDE was used)
+  // Check for IDE-specific files (detect which IDE was used).
+  // Order matters: IDE-unique markers MUST be checked before AGENTS.md,
+  // because Cursor and Antigravity now also emit AGENTS.md for compat.
   const ideChecks = [
     ['.github/copilot-instructions.md', 'vscode'],
     ['.claude/rules/core.md', 'claude'],
     ['.cursor/rules/core.mdc', 'cursor'],
-    ['AGENTS.md', 'codex'],
     ['.windsurf/rules/core.md', 'windsurf'],
     ['GEMINI.md', 'antigravity'],
+    ['AGENTS.md', 'codex'],
   ];
 
   let detectedIde = null;