@kodevibe/harness 0.8.4 → 0.9.1

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.8.4** — 6 IDE support, Navigation Dispatcher, 5 Pipelines ( 🟢🔵🔴🟡🟣), Crew Artifact Integration, EXTERNAL_DEP classification.
-
-## 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 (planner, reviewer, sprint-manager)
-- **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 `bootstrap` skill:
-
-> "Run bootstrap to onboard this project."
+```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,28 +54,59 @@ 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 `bootstrap` 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
 
@@ -132,21 +127,21 @@ All IDEs also get state files (`project-state.md`, `project-brief.md`, `features
 - **Core Rules** — 136-line dispatcher: session start guidance, workflow references, state file list, and Iron Laws. Detailed rules are embedded in each skill/agent that enforces them.
 
 ### Skills (on-demand procedures)
-- **bootstrap** — Onboard project into kode:harness: scans codebase + fills state files automatically
-- **learn** — End-of-session wrap-up: captures failure patterns, updates project state, detects direction drift
+- **setup** — Onboard project into kode:harness: scans codebase + fills state files automatically
+- **wrap-up** — End-of-session wrap-up: captures failure patterns, updates project state, detects direction drift
 - **pivot** — Propagate direction changes across all state files when goals/tech/scope changes
-- **test-integrity** — Verify mock/interface synchronization before committing
-- **security-checklist** — Pre-commit security risk scan
-- **investigate** — 4-phase systematic debugging (evidence → scope → fix → verify)
-- **impact-analysis** — Assess change blast radius before modifying shared modules
-- **feature-breakdown** — Decompose features into dependency-ordered implementation tasks
-- **code-review-pr** — Review incoming Pull Requests for quality, security, and direction alignment
-- **deployment** — Pre-deployment validation checklist (tests, state files, security, versioning)
+- **sync-tests** — Verify mock/interface synchronization before committing
+- **secure** — Pre-commit security risk scan
+- **debug** — 4-phase systematic debugging (evidence → scope → fix → verify)
+- **check-impact** — Assess change blast radius before modifying shared modules
+- **breakdown** — Decompose features into dependency-ordered implementation tasks
+- **pr-review** — Review incoming Pull Requests for quality, security, and direction alignment
+- **release** — Pre-release validation checklist (tests, state files, security, versioning)
 
 ### Agents (role-based personas)
-- **planner** — Feature planning, dependency analysis, Direction Alignment (goal/non-goal/decision check)
+- **pm** — Feature planning, dependency analysis, Direction Alignment (goal/non-goal/decision check)
 - **reviewer** — Code review + State File Audit (verifies state files were actually updated)
-- **sprint-manager** — Sprint/Story state management, scope drift prevention, Next Step Recommendation
+- **lead** — Sprint/Story state management, scope drift prevention, Next Step Recommendation
 - **architect** — Design review gate: validates structural changes against project direction and module boundaries
 
 ### State Files (project memory)
@@ -159,7 +154,7 @@ All IDEs also get state files (`project-state.md`, `project-brief.md`, `features
 ## How It Works
 
 ### 1. Bootstrap (once)
-After `harness init`, run the `bootstrap` skill. It scans your codebase, interviews you about goals/non-goals, and fills all 5 state files automatically. **This is the most important step** — without it, Direction Guard and other skills have no context.
+After `harness init`, run the `setup` skill. It scans your codebase, interviews you about goals/non-goals, and fills all 5 state files automatically. **This is the most important step** — without it, Direction Guard and other skills have no context.
 
 ### 2. Direction Guard (every request)
 Before ANY coding task, the LLM reads `project-brief.md` and checks:
@@ -169,26 +164,26 @@ Before ANY coding task, the LLM reads `project-brief.md` and checks:
 
 ### 3. Workflow Pipeline
 ```
-bootstrap → planner → [code] → reviewer → sprint-manager → learn
+setup → pm → [code] → reviewer → lead → wrap-up
 ```
 
 kode:harness provides **5 pipelines** for different scenarios:
 
 | Pipeline | When | Flow |
 |---|---|---|
-| 🟢 New Dev | First feature | bootstrap → planner → sprint-manager → [code] → reviewer → learn |
-| 🔵 Continue | Resuming work | sprint-manager → [code] → reviewer → learn |
-| 🔴 Bug Fix | Debugging | investigate → [fix] → reviewer → learn |
-| 🟡 Direction Change | Goals/tech shift | pivot → planner → sprint-manager → [code] → reviewer → learn |
-| 🟣 Crew-Driven | With external planning artifacts | bootstrap(crew) → planner → sprint-manager → [code] → reviewer → learn |
+| 🟢 New Dev | First feature | setup → pm → lead → [code] → reviewer → wrap-up |
+| 🔵 Continue | Resuming work | lead → [code] → reviewer → wrap-up |
+| 🔴 Bug Fix | Debugging | debug → [fix] → reviewer → wrap-up |
+| 🟡 Direction Change | Goals/tech shift | pivot → pm → lead → [code] → reviewer → wrap-up |
+| 🟣 Crew-Driven | With external planning artifacts | setup(crew) → pm → lead → [code] → reviewer → wrap-up |
 
 Each step ends with a 🧭 **Navigation block** telling you exactly what to do next — including the prompt to type.
 
-- **planner**: Checks direction alignment, breaks down features. **Confirm-First gate** — won't proceed without your approval.
+- **pm**: Checks direction alignment, breaks down features. **Confirm-First gate** — won't proceed without your approval.
 - **reviewer**: Reviews code + audits state file updates
-- **sprint-manager**: Tracks progress via **Wave-Level Pacing** — runs tests between implementation waves
-- **learn**: Captures lessons before session ends
-- **investigate**: **Recalculating Mode** — after 3 failed attempts, proposes alternative approaches
+- **lead**: Tracks progress via **Wave-Level Pacing** — runs tests between implementation waves
+- **wrap-up**: Captures lessons before session ends
+- **debug**: **Recalculating Mode** — after 3 failed attempts, proposes alternative approaches
 
 ### 4. Direction Changes
 When goals, technology, or scope changes, run the `pivot` skill:
@@ -227,24 +222,26 @@ These 8 rules are enforced across all skills and agents. They form the quality b
 
 | # | Law | Enforced By |
 |---|-----|-------------|
-| 1 | **Mock Sync** — Interface change → update mocks in the same commit | `reviewer`, `test-integrity` |
+| 1 | **Mock Sync** — Interface change → update mocks in the same commit | `reviewer`, `sync-tests` |
 | 2 | **Type Check** — Read the source before calling constructors. Never trust memory. | `reviewer` |
-| 3 | **Scope Compliance** — Stay within current Story scope. Report before modifying out-of-scope files. | `sprint-manager`, `reviewer` |
-| 4 | **Security** — No credentials, passwords, or API keys in code or commits. | `security-checklist`, `reviewer` |
+| 3 | **Scope Compliance** — Stay within current Story scope. Report before modifying out-of-scope files. | `lead`, `reviewer` |
+| 4 | **Security** — No credentials, passwords, or API keys in code or commits. | `secure`, `reviewer` |
 | 5 | **3-Failure Stop** — Same approach fails 3 times → stop and report. | All agents |
-| 6 | **Dependency Map** — New/modified module → update `dependency-map.md` in the same commit. | `reviewer`, `learn` |
-| 7 | **Feature Registry** — New feature → register in `features.md` in the same commit. | `reviewer`, `learn` |
-| 8 | **Session Handoff** — Session end → update `project-state.md` Quick Summary. | `learn` |
+| 6 | **Dependency Map** — New/modified module → update `dependency-map.md` in the same commit. | `reviewer`, `wrap-up` |
+| 7 | **Feature Registry** — New feature → register in `features.md` in the same commit. | `reviewer`, `wrap-up` |
+| 8 | **Session Handoff** — Session end → update `project-state.md` Quick Summary. | `wrap-up` |
 
 ## Documentation
 
 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 |
 |---|---|---|---|---|
@@ -272,19 +269,20 @@ Original crew documents are **never modified**. Only the index and tracker are c
 | IDE support | 20+ (installer) | 5 (setup --host) | 13 (runtime select) | 6 (native format) |
 | Direction management | ❌ | ❌ | ❌ | ✅ (Direction Guard + pivot + Decision Log) |
 | Iron Laws (code quality rules) | ❌ | ❌ | ❌ | ✅ (8 laws embedded in skills) |
-| Cold start | ❌ | ❌ | `/gsd-new-project` | ✅ (`bootstrap` skill) |
+| Cold start | ❌ | ❌ | `/gsd-new-project` | ✅ (`setup` skill) |
 | Context per task | 4-6 files | 1 file | Fresh 200k per plan | 2-3 files (136-line dispatcher) |
 
 ## Roadmap
 
-kode:harness is at **v0.8.4** — 6 IDE support complete, Navigation Dispatcher and Crew Artifact Integration stable.
+kode:harness is at **v0.9.0** — naming redesign complete, 6 IDE support, Navigation Dispatcher and Crew Artifact Integration stable.
 
 | Phase | Version | Status | Focus |
 |---|---|---|---|
 | **Foundation** | v0.5.0 | ✅ Done | Core framework: 6 IDE support, 8 skills, 3 agents, Team Mode, Direction Guard |
 | **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 | ✅ Current | 🧭 Navigation Dispatcher, 5 Pipelines, Crew Artifact Integration, 100-point quality audit, Confirm-First gate, Wave-Level Pacing, Recalculating Mode |
+| **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 |
 | **Validation** | v1.0 | 🔜 Next | Real-world project adoption, user feedback collection |
 
 ### What's Next

package/harness/agent-memory/architect.md

@@ -1,6 +1,6 @@
 # Architect Memory
 
-> Auto-updated by the `learn` skill at session end. Do not edit manually.
+> Auto-updated by the `wrap-up` skill at session end. Do not edit manually.
 > **Initialization**: After the first architecture review, replace placeholder comments below with real data.
 > **Update trigger**: Only updated when the `architect` agent runs. If architect was not invoked this session, this file stays unchanged.
 
@@ -27,7 +27,7 @@
 <!-- Record anti-patterns with severity, detection method, and prevention.
    Format: Pattern — Severity (HIGH/MED/LOW) — Detection — Resolution — Prevention
    Examples:
-   - Circular dep auth↔user — HIGH — dependency-map bidirectional check — extracted shared types — run impact-analysis before interface changes
+   - Circular dep auth↔user — HIGH — dependency-map bidirectional check — extracted shared types — run check-impact before interface changes
    - God module in utils/ (800+ lines) — MED — file size check — decompose into auth-utils, date-utils, string-utils — enforce max 200 lines per module
 -->
 

package/harness/agent-memory/{sprint-manager.md → lead.md}

@@ -1,8 +1,8 @@
 # Sprint Manager Memory
 
-> Auto-updated by the `learn` skill at session end. Do not edit manually.
+> Auto-updated by the `wrap-up` skill at session end. Do not edit manually.
 > **Initialization**: After the first sprint completes, replace placeholder comments below with real data.
-> **Update trigger**: Updated when `learn` skill runs after sprint management actions.
+> **Update trigger**: Updated when `wrap-up` skill runs after sprint management actions.
 
 ## Velocity Tracking
 
@@ -12,13 +12,13 @@
    - [Sprint 1] 3/5 (60%) — ramp-up phase, scope adjusted mid-sprint
    - [Sprint 2] 4/4 (100%) — right-sized after Sprint 1 calibration
    - [Sprint 3] 5/5 (100%) — team rhythm established
-   Benchmark: Set after 3+ sprints. If rate < 50% for 2 consecutive sprints → flag in sprint-manager recommendations.
+   Benchmark: Set after 3+ sprints. If rate < 50% for 2 consecutive sprints → flag in lead recommendations.
    Average velocity: recalculate after each sprint (e.g., "Average: 4.0 stories/sprint after 3 sprints")
 -->
 
 ## Scope Drift History
 
-<!-- Record scope violations caught by sprint-manager or reviewer.
+<!-- Record scope violations caught by lead or reviewer.
    Format: [Story ID] Drift type — Files affected — Resolution
    Examples:
    - [S1-003] Out-of-scope modification — 3 files in auth/ (not in story scope) — reverted, created new story S1-005

package/harness/agent-memory/{planner.md → pm.md}

@@ -1,8 +1,8 @@
 # Planner Memory
 
-> Auto-updated by the `learn` skill at session end. Do not edit manually.
+> Auto-updated by the `wrap-up` skill at session end. Do not edit manually.
 > **Initialization**: After the first sprint completes, replace placeholder comments below with real data.
-> **Update trigger**: Updated when `learn` skill runs after a planner session.
+> **Update trigger**: Updated when `wrap-up` skill runs after a pm session.
 
 ## Estimation Accuracy
 
@@ -43,5 +43,5 @@
    - [Sprint 1] Planned: 5, Done: 3, Rate: 60% — ramp-up phase, team unfamiliar with codebase
    - [Sprint 2] Planned: 4, Done: 4, Rate: 100% — right-sized after Sprint 1 data
    - [Sprint 3] Planned: 4, Done: 5, Rate: 125% — acceleration, consider planning 5 next sprint
-   Benchmark: After 3+ sprints, calculate average rate. If < 60% for 2 consecutive sprints → investigate causes
+   Benchmark: After 3+ sprints, calculate average rate. If < 60% for 2 consecutive sprints → debug causes
 -->

package/harness/agent-memory/reviewer.md

@@ -1,8 +1,8 @@
 # Reviewer Memory
 
-> Auto-updated by the `learn` skill at session end. Do not edit manually.
+> Auto-updated by the `wrap-up` skill at session end. Do not edit manually.
 > **Initialization**: After the first code review, replace placeholder comments below with real data.
-> **Update trigger**: Updated when `learn` skill runs after a reviewer session.
+> **Update trigger**: Updated when `wrap-up` skill runs after a reviewer session.
 
 ## Project-Specific Review Patterns
 
@@ -10,7 +10,7 @@
    Format: Pattern — Location — Severity — Prevention
    Examples:
    - SQL injection risk in src/api/routes/ — req.params used directly — HIGH — add parameterized query wrapper
-   - Mock sync miss rate 50% — interface changes in src/domain/ — HIGH — run test-integrity skill pre-commit
+   - Mock sync miss rate 50% — interface changes in src/domain/ — HIGH — run sync-tests skill pre-commit
    - Hardcoded timeout 5000ms in tests — tests/integration/ — LOW — extract to test config
 -->
 
@@ -32,7 +32,7 @@
 - Escalations: 0
 <!-- Track ratios after 5+ reviews:
    - Auto-fix rate: auto-fixes / total issues (if > 30% → consider automating those checks)
-   - Escalation rate: escalations / total reviews (if > 20% → investigate root cause)
+   - Escalation rate: escalations / total reviews (if > 20% → debug root cause)
 -->
 
 ## Test Failure Patterns
@@ -40,7 +40,7 @@
 <!-- Track which test patterns commonly fail during reviews.
    Format: Pattern — Frequency — Root Cause — Mitigation
    Examples:
-   - Mock method missing after interface change — 4/10 reviews — FP-001 — run test-integrity pre-commit
+   - Mock method missing after interface change — 4/10 reviews — FP-001 — run sync-tests pre-commit
    - Async test timeout — 2/10 reviews — missing await — enforce eslint no-floating-promises
    - Snapshot mismatch after UI change — 3/10 reviews — stale snapshots — update snapshots in same commit
 -->

package/harness/agents/architect.md

@@ -9,12 +9,12 @@ The Architect is invoked when changes affect multiple modules, introduce new lay
 ## Invoked By
 
 - **User** (direct) — "아키텍처 리뷰해줘", "설계 검토해줘"
-- **planner** (optional) — when proposed changes affect 3+ modules or introduce new layers
+- **pm** (optional) — when proposed changes affect 3+ modules or introduce new layers
 
 ## Referenced Skills
 
-- impact-analysis — Change blast radius assessment
-- feature-breakdown — Task decomposition for structural changes
+- check-impact — Change blast radius assessment
+- breakdown — Task decomposition for structural changes
 
 ## Referenced Files
 
@@ -45,7 +45,7 @@ Before proceeding, verify that required state files have content:
 - `docs/dependency-map.md` — Must have at least one module row (for existing projects)
 - `docs/project-brief.md` — Must have Vision and Goals filled
 
-If `docs/project-brief.md` has no Vision/Goals filled OR `docs/dependency-map.md` has zero module rows → **Stop and run the `bootstrap` skill first.** Report: "State files are empty. Running bootstrap to onboard this project."
+If `docs/project-brief.md` has no Vision/Goals filled OR `docs/dependency-map.md` has zero module rows → **Stop and run the `setup` skill first.** Report: "State files are empty. Running setup to onboard this project."
 
 **Step 0.1: Circular Dependency Check**
 
@@ -85,7 +85,7 @@ Apply these insights when evaluating the current proposal. If the memory file is
 4. If misaligned → **warn and recommend `pivot` before proceeding**
 
 **Step 3: Impact Analysis**
-1. Run `impact-analysis` skill on all affected modules
+1. Run `check-impact` skill on all affected modules
 2. Identify:
    - Modules that will be modified
    - Modules that depend on modified modules (ripple effect)
@@ -140,7 +140,7 @@ After architecture review completes, always append a 🧭 block:
 
 | Architect Result | 🧭 Next Step |
 |---|---|
-| APPROVE | `planner` — "승인된 설계로 기능을 계획해줘" |
+| APPROVE | `pm` — "승인된 설계로 기능을 계획해줘" |
 | REVISE | [Redesign] — "설계를 수정하고 다시 `architect` 호출" |
 | REJECT | User decision — "설계가 반려되었습니다. 대안을 논의합시다" |
 | Direction misaligned | `pivot` — "방향을 전환하고 state 파일을 업데이트해줘" |
@@ -149,10 +149,10 @@ Example 🧭 block for APPROVE:
 ```
 ---
 🧭 Next Step
-→ Next: `planner`
+→ Next: `pm`
 → Prompt: "승인된 설계로 기능을 계획해줘"
 → Why: Architecture approved — proceed to feature planning
-→ Pipeline: 🟢 Pre-pipeline (leads to planner Step 2/6)
+→ Pipeline: 🟢 Pre-pipeline (leads to pm Step 2/6)
 ---
 ```
 
@@ -161,7 +161,7 @@ Example 🧭 block for APPROVE:
 - This agent reviews design, it does NOT implement changes
 - Always defer to `docs/project-brief.md` Decision Log for settled architectural decisions
 - If unsure about direction, recommend involving the designated authority (per project-brief.md; default: team lead)
-- For implementation after approval, hand off to the `planner` agent
+- For implementation after approval, hand off to the `pm` agent
 
 <!-- TEAM_MODE_START -->
 ## Team Mode: Cross-Team Architecture

package/harness/agents/{sprint-manager.md → lead.md}

@@ -8,22 +8,22 @@ Keeps the LLM focused on the current work item.
 ## Invoked By
 
 - **User** (direct) — "다음 Story는?", "현재 상태 보여줘"
-- **planner** → User confirmation → sprint-manager (🟢 pipeline Step 3)
-- **reviewer** (pass, more stories) → sprint-manager — "다음 Story는?"
+- **pm** → User confirmation → lead (🟢 pipeline Step 3)
+- **reviewer** (pass, more stories) → lead — "다음 Story는?"
 
 ## Referenced Skills
 
-- bootstrap — Recommended when state files are empty
-- learn — Recommended at session end or when all stories are done
+- setup — Recommended when state files are empty
+- wrap-up — Recommended at session end or when all stories are done
 - pivot — Recommended when direction change is detected
-- investigate — Recommended when bug is blocking progress
+- debug — Recommended when bug is blocking progress
 
 ## Referenced Files
 
 ### Required — 반드시 읽기
 - docs/project-state.md — 핵심 파일: 현재 Sprint/Story 상태 (Step 0, 모든 Handler에서 사용)
 - docs/features.md — 진행률 개요 (Next Step Recommendation에서 사용)
-- docs/agent-memory/sprint-manager.md — 과거 velocity 및 scope drift 데이터
+- docs/agent-memory/lead.md — 과거 velocity 및 scope drift 데이터
 
 ### Optional — 해당 Step에서만 읽기
 - docs/project-brief.md — 방향 확인 필요 시에만 읽기
@@ -38,11 +38,11 @@ Before handling any request, verify `docs/project-state.md` has content:
 - Quick Summary must not be all TODO placeholders
 - Story Status table must have at least one row
 
-If `docs/project-state.md` is empty/placeholder-only → **Recommend running `bootstrap` skill first.** Report: "docs/project-state.md is empty. Run bootstrap to initialize project state before tracking sprints."
+If `docs/project-state.md` is empty/placeholder-only → **Recommend running `setup` skill first.** Report: "docs/project-state.md is empty. Run setup to initialize project state before tracking sprints."
 
 ### Step 0.5: Load Agent Memory
 
-Read `docs/agent-memory/sprint-manager.md` for past learnings:
+Read `docs/agent-memory/lead.md` for past learnings:
 - Team velocity data (stories per sprint)
 - Scope drift history (how often did scope expand?)
 - Story sizing accuracy (were estimates correct?)
@@ -71,15 +71,15 @@ After every status check, recommend the next action based on current context:
 
 | Situation | Recommendation |
 |-----------|---------------|
-| State files are empty | → "Run `bootstrap` to onboard this project" |
+| State files are empty | → "Run `setup` to onboard this project" |
 |docs/project-brief.md has no Vision/Goals | → "Fill out docs/project-brief.md — this is critical for direction" |
-| No stories exist | → "Run `planner` to break down your first feature" |
+| No stories exist | → "Run `pm` to break down your first feature" |
 | A story is in-progress | → "Continue S{N}-{M}: [title]. Scope: [files]" |
-| All stories in sprint are done | → "Run `learn` to capture session lessons, then start a new sprint" |
+| All stories in sprint are done | → "Run `wrap-up` to capture session lessons, then start a new sprint" |
 | A direction change was discussed | → "Run `pivot` to update all state files before continuing" |
 | Recent failure patterns apply | → "Watch out for FP-{NNN}: [description]" |
 <!-- CREW_MODE_START -->
-| Unplanned KPI/FR in Validation Tracker | → "Run `planner` — add Stories for unplanned KPI/FR items" |
+| Unplanned KPI/FR in Validation Tracker | → "Run `pm` — add Stories for unplanned KPI/FR items" |
 | All ARB Fail items resolved | → "ARB Fail items all resolved — deployment readiness can be checked" |
 <!-- CREW_MODE_END -->
 
@@ -109,20 +109,20 @@ After every status check, recommend the next action based on current context:
 3. Read `docs/dependency-map.md` to identify modules involved in this Story
 4. Specify Story scope (related files/directories from dependency-map)
 5. Alert relevant docs/failure-patterns.md items
-6. Recommend relevant skill: "Consider running `planner` if this story needs detailed breakdown"
+6. Recommend relevant skill: "Consider running `pm` if this story needs detailed breakdown"
 
-**Request: "plan approved" / "플랜 반영해줘" (planner → sprint-manager handoff)**
+**Request: "plan approved" / "플랜 반영해줘" (pm → lead handoff)**
 
-When invoked after planner approval, verify that planner wrote state files correctly:
+When invoked after pm approval, verify that pm wrote state files correctly:
 
 1. Read `docs/project-state.md` — check if Stories from the approved plan exist
 2. **If Stories exist** → proceed to "new story" handler (set first `todo` Story to `in-progress`)
-3. **If Stories are missing** (planner failed to write):
+3. **If Stories are missing** (pm failed to write):
    a. Read the approved plan from the conversation context
    b. Create Sprint entry in `docs/project-state.md` (Sprint N, theme from plan)
    c. Add all Story rows to the Story Status table (status = `⬜ todo`)
    d. Update Quick Summary section
-   e. Report: "Planner가 state files에 반영하지 않아 sprint-manager가 보완했습니다."
+   e. Report: "Planner가 state files에 반영하지 않아 lead가 보완했습니다."
    f. Proceed to set the first Story to `in-progress`
 <!-- CREW_MODE_START -->
 4. If 🟣 pipeline: verify `docs/project-brief.md` Validation Tracker has Story mappings. If missing, fill them from the plan.
@@ -134,7 +134,7 @@ When invoked after planner approval, verify that planner wrote state files corre
 
 **Wave-Level Pacing (Turn-by-Turn Guidance)**
 
-When a Story contains multiple Tasks/Waves (from feature-breakdown):
+When a Story contains multiple Tasks/Waves (from breakdown):
 - Guide implementation **one Wave at a time** (not one file at a time, not all at once)
 - After each Wave is implemented, **run tests (or invoke `reviewer` for a quick check)** to verify the Wave is clean before proceeding
 - Only after verification passes, prompt: "Wave {N} 완료 (tests pass). Wave {N+1}로 넘어갈까요?"
@@ -178,7 +178,7 @@ STATUS: DONE
 #### Validation Dashboard (🟣 Pipeline only)
 
 When `docs/project-brief.md` contains a `## Validation Tracker` section with data, display the Validation Tracker as a dashboard in every status output.
-If the Validation Tracker exists but has zero rows (no KPIs/FRs indexed yet), display: `KPI Coverage: 0/0 (N/A) — consider running bootstrap to populate Artifact Index`.
+If the Validation Tracker exists but has zero rows (no KPIs/FRs indexed yet), display: `KPI Coverage: 0/0 (N/A) — consider running setup to populate Artifact Index`.
 
 ```
 ### 📊 Validation Dashboard
@@ -190,19 +190,19 @@ If the Validation Tracker exists but has zero rows (no KPIs/FRs indexed yet), di
 - [KPI/FR ID]: [description] — 관련 Story 없음
 ```
 
-**Sprint Manager reads and reports the Validation Tracker numbers.** It does NOT auto-create Stories for missing coverage — that is the planner's role. If unplanned items exist, recommend running `planner`.
+**Sprint Manager reads and reports the Validation Tracker numbers.** It does NOT auto-create Stories for missing coverage — that is the pm's role. If unplanned items exist, recommend running `pm`.
 <!-- CREW_MODE_END -->
 
 ### 🧭 Navigation — What Comes After Sprint Manager
 
-After sprint-manager completes, always append a 🧭 block based on the outcome:
+After lead completes, always append a 🧭 block based on the outcome:
 
 | Sprint Manager Result | 🧭 Next Step |
 |---|---|
-| State files empty | `bootstrap` — "프로젝트를 온보딩해줘" |
-| No stories exist | `planner` — "[기능]을 계획해줘" |
+| State files empty | `setup` — "프로젝트를 온보딩해줘" |
+| No stories exist | `pm` — "[기능]을 계획해줘" |
 | Story set to in-progress | [Coding] — "S{N}-{M} 구현을 시작해줘". 완료 후 **새 채팅**에서 reviewer 호출 |
-| All stories done | `learn` — "세션을 마무리해줘" |
+| All stories done | `wrap-up` — "세션을 마무리해줘" |
 | Direction change detected | `pivot` — "방향을 전환해줘" |
 
 Example 🧭 block for starting a story: