k-harness 0.2.0 → 0.4.0

package/README.md

@@ -1,16 +1,17 @@
 # K-Harness
 
-LLM Development Harness — IDE-agnostic rules, skills, and agents that prevent common AI coding failures.
+Project Direction Management Framework for LLM-Driven Development.
 
 ## What It Does
 
-K-Harness installs structured instruction files into your project that guide LLM coding agents (Copilot, Claude, Cursor, Codex, Windsurf) to avoid common mistakes:
+K-Harness manages your **project's direction** — goals, decisions, scope — so LLM coding agents stay aligned across sessions. It combines BMAD's systematic project management with gstack's simplicity: zero dependencies, IDE-native format generation, and minimal context overhead.
 
-- **Iron Laws** — Hard rules the LLM must follow every session (mock sync, type checking, security)
-- **Skills** — Step-by-step procedures for specific tasks (debugging, code review, security checks)
-- **Agents** — Role-based personas (reviewer, sprint manager)
+- **Direction Guard** — Every coding request is checked against project goals/non-goals before execution
+- **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
-- **State Tracking** — Sprint/Story state so the LLM knows what to work on
+- **Decision Log** — Records why decisions were made so LLMs don't re-debate settled choices
 
 ## Quick Start
 
@@ -29,13 +30,14 @@ npx k-harness init --ide cursor
 npx k-harness init --ide codex
 npx k-harness init --ide windsurf
 npx k-harness init --ide augment
+npx k-harness init --ide antigravity
 ```
 
 ### Options
 
 | Flag | Description |
 |------|-------------|
-| `--ide <name>` | Target IDE: `vscode`, `claude`, `cursor`, `codex`, `windsurf`, `augment` |
+| `--ide <name>` | Target IDE: `vscode`, `claude`, `cursor`, `codex`, `windsurf`, `augment`, `antigravity` |
 | `--dir <path>` | Target directory (default: current directory) |
 | `--overwrite` | Overwrite existing files |
 
@@ -45,12 +47,13 @@ npx k-harness init --ide augment
 |-----|-------------|-------------------|--------|--------|
 | **VS Code Copilot** | `.github/copilot-instructions.md` | `.vscode/instructions/*.instructions.md` | `.github/skills/*/SKILL.md` | `.github/agents/*.agent.md` |
 | **Claude Code** | `CLAUDE.md` | (merged into CLAUDE.md) | `.claude/skills/*/SKILL.md` | (merged into CLAUDE.md) |
-| **Cursor** | `.cursor/rules/core.mdc` | `.cursor/rules/*.mdc` | `.cursor/rules/*.mdc` | `.cursor/rules/*.mdc` |
+| **Cursor** | `.cursor/rules/core.mdc` | `.cursor/rules/*.mdc` | (merged into rules) | (merged into rules) |
 | **Codex** | `AGENTS.md` | (merged into AGENTS.md) | `.agents/skills/*/SKILL.md` | (merged into AGENTS.md) |
 | **Windsurf** | `.windsurfrules` | (merged) | (merged) | (merged) |
-| **Augment Code** | `.augment/rules/core.md` | `.augment/rules/*.md` | `.augment/rules/*.md` | `.augment/rules/*.md` |
+| **Augment Code** | `.augment/rules/core.md` | `.augment/rules/*.md` | `.augment/skills/*/SKILL.md` | `.augment/skills/*/SKILL.md` |
+| **Google Antigravity** | `.agent/rules/core.md` | `.agent/rules/*.md` | `.agent/skills/*/SKILL.md` | `.agent/skills/*/SKILL.md` |
 
-All IDEs also get `project-state.md`, `failure-patterns.md`, `features.md`, and `project-brief.md` at the project root.
+All IDEs also get `project-state.md`, `project-brief.md`, `features.md`, `failure-patterns.md`, and `dependency-map.md` at the project root.
 
 ## What Gets Installed
 
@@ -60,47 +63,79 @@ All IDEs also get `project-state.md`, `failure-patterns.md`, `features.md`, and
 - **Backend Rules** — Dependency inversion, type safety, explicit staging (applied to source files)
 
 ### Skills (on-demand procedures)
+- **bootstrap** — Onboard project into K-Harness: scans codebase + fills state files automatically
+- **learn** — End-of-session wrap-up: captures failure patterns, updates project state
+- **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
 
 ### Agents (role-based personas)
-- **reviewer** — Code review: architecture, tests, security, failure pattern cross-check
-- **sprint-manager** — Sprint/Story state management, scope drift prevention
+- **planner** — 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
 
-### State Files
-- **project-state.md** — Current sprint, stories, and progress tracking
-- **failure-patterns.md** — Template for logging project-specific failure patterns
+### State Files (project memory)
+- **project-brief.md** — Project vision, goals, non-goals, Decision Log (the "why")
+- **project-state.md** — Current sprint, stories, and progress tracking (the "where")
+- **features.md** — Living feature registry so LLMs know what exists (the "what")
+- **dependency-map.md** — Module dependency graph for impact analysis (the "how")
+- **failure-patterns.md** — Project-specific failure patterns that prevent repeat mistakes (the "watch out")
 
-## After Installation
+## How It Works
 
-1. **Edit `project-state.md`** — Set up your first sprint and stories
-2. **Customize global rules** — Add your architecture, type rules, and directory structure
-3. **Log failures** — When an LLM makes a repeated mistake, record it in `failure-patterns.md`
-
-## Design Principles
-
-1. **State Injection** — Project state injected at every session start
-2. **Rigid Workflow** — Hard "do/don't" rules; soft suggestions get ignored by LLMs
-3. **Failure-Driven Rules** — Rules derived only from actual project failures
-4. **Completion Status Protocol** — DONE / BLOCKED / NEEDS_CONTEXT reporting
-5. **Scope Lock** — Escalate before modifying files outside current story scope
+### 1. Bootstrap (once)
+```bash
+npx k-harness init --ide vscode
+```
+Then ask your LLM to run the `bootstrap` skill — it scans your codebase and fills all 5 state files automatically.
 
-## Research & Analysis
+### 2. Direction Guard (every request)
+Before ANY coding task, the LLM reads `project-brief.md` and checks:
+- Does this align with Goals? → proceed
+- Does this fall under Non-Goals? → warn, suggest `pivot`
+- Does this contradict a Decision Log entry? → warn, suggest `pivot`
 
+### 3. Workflow Pipeline
 ```
-docs/
-├── analysis/           # Framework comparisons
-│   ├── comparison.md   # BMAD vs gstack
-│   ├── bmad-deep-dive.md
-│   └── gstack-deep-dive.md
-├── architecture/       # K-Harness design
-│   ├── design-principles.md
-│   ├── file-structure.md
-│   └── skill-spec.md
-└── case-study/
-    └── mcphub-lessons.md
+bootstrap → planner → [code] → reviewer → sprint-manager → learn
 ```
+- **planner**: Checks direction alignment, breaks down features
+- **reviewer**: Reviews code + audits state file updates
+- **sprint-manager**: Tracks progress, recommends next action
+- **learn**: Captures lessons before session ends
+
+### 4. Direction Changes
+When goals, technology, or scope changes, run the `pivot` skill:
+- Updates ALL 5 state files consistently
+- Records the decision with reasoning in Decision Log
+- Prevents silent inconsistencies across files
+
+## Design Principles
+
+1. **Direction First** — Every request checked against project goals before code is written
+2. **State Injection** — Project state injected at every session start
+3. **Rigid Workflow** — Hard "do/don't" rules; soft suggestions get ignored by LLMs
+4. **Enforced Updates** — Reviewer audits that state files were actually updated, not just instructed
+5. **Failure-Driven Rules** — Rules derived only from actual project failures
+6. **Context Minimization** — ≤3 files per task, zero dependencies, one `npm install`
+
+## Why Not BMAD or gstack?
+
+| | BMAD v6.2.2 | gstack v0.15.1 | K-Harness |
+|---|---|---|---|
+| Focus | Enterprise SDLC methodology | 1-person software factory | Project direction management |
+| Files | 200+ | ~40 | 15 |
+| Dependencies | Node 20+ | Bun + Node + Playwright | Zero |
+| IDE support | 20+ (installer) | 5 (setup --host) | 7 (native format) |
+| Direction management | ❌ | ❌ | ✅ (Direction Guard + pivot + Decision Log) |
+| Cold start | ❌ | ❌ | ✅ (bootstrap) |
+| State file audit | ❌ | ❌ | ✅ (reviewer Step 8) |
+| Context per task | 4-6 files | 1 file | 2-3 files |
+
+See [docs/analysis/comparison.md](docs/analysis/comparison.md) for the full analysis.
 
 ## License
 

package/harness/agents/planner.md

@@ -28,10 +28,24 @@ One of:
 
 ## Procedure
 
+### Step 0: State File Readiness
+
+Before proceeding, verify that required state files have content (not just TODO placeholders):
+- `project-brief.md` — Must have Vision and Goals filled
+- `features.md` — Must have at least one feature row
+- `dependency-map.md` — Must have at least one module row (for existing projects)
+
+If ALL files are empty/placeholder-only → **Stop and run the `bootstrap` skill first.** Report: "State files are empty. Running bootstrap to onboard this project."
+If `project-brief.md` alone is empty → Warn the user but proceed (the plan will lack direction guard).
+
 ### For New Feature
 
-1. Read `project-brief.md` to understand project vision, goals, and **non-goals**
-2. **Direction Guard**: Verify the requested feature aligns with the project goals and does NOT fall into non-goals. If it conflicts, warn the user before proceeding.
+1. Read `project-brief.md` to understand project vision, goals, **non-goals**, and **Decision Log**
+2. **Direction Alignment**: Verify the requested feature against three checkpoints:
+   - **Goal Alignment**: Does it serve a listed Goal? If no clear link, warn the user.
+   - **Non-Goal Violation**: Does it fall into Non-Goals? If yes, **stop and ask** — this may be a pivot.
+   - **Decision Consistency**: Does it contradict any Decision Log entry? If yes, warn that a previous decision conflicts — recommend running the `pivot` skill before proceeding.
+   If the request represents a clear direction change → recommend running the `pivot` skill instead of proceeding with planning.
 3. Read `features.md` to understand what already exists
 4. Read `dependency-map.md` to understand current architecture
 5. Read `project-state.md` for current Sprint context

package/harness/agents/reviewer.md

@@ -19,6 +19,14 @@ Finds issues and auto-fixes where safe, escalates where not.
 
 ## Procedure
 
+### Step 0: State File Readiness
+
+Before reviewing, verify that required state files exist and are not empty:
+- `failure-patterns.md` — Must exist (needed for Step 5 cross-check)
+- `project-state.md` — Must have current Sprint info (needed for scope check)
+
+If state files are empty/placeholder-only → Warn: "State files are not filled. Review will proceed but scope check and failure pattern cross-check will be limited. Consider running `bootstrap` skill."
+
 ### Input
 
 Changed file list (user-provided or from `git diff --name-only`)
@@ -59,6 +67,17 @@ Changed file list (user-provided or from `git diff --name-only`)
 - [ ] If module was deleted/renamed, verify dependency-map.md is cleaned up
 - [ ] Run impact-analysis skill if interface changes affect 2+ dependent modules
 
+**Step 8: State File Audit**
+
+Verify that state file updates actually happened. Check each:
+- [ ] **project-state.md**: If stories were worked on, is Quick Summary current? Are story statuses updated?
+- [ ] **features.md**: If new features were added, are they registered? If features were completed, is status updated?
+- [ ] **dependency-map.md**: If new modules were created, are they registered? If dependencies changed, are relationships updated?
+- [ ] **failure-patterns.md**: If a bug was fixed that matched a pattern, was frequency incremented?
+- [ ] **project-brief.md**: If a technology or architectural decision was made, is it in Decision Log?
+
+For each missing update: flag as `[STATE-AUDIT]` in the output and provide the exact update that should be made.
+
 ### Output Format
 
 ```

package/harness/agents/sprint-manager.md

@@ -12,6 +12,14 @@ Keeps the LLM focused on the current work item.
 
 ## Procedure
 
+### Step 0: State File Readiness
+
+Before handling any request, verify `project-state.md` has content:
+- Quick Summary must not be all TODO placeholders
+- Story Status table must have at least one row
+
+If `project-state.md` is empty/placeholder-only → **Recommend running `bootstrap` skill first.** Report: "project-state.md is empty. Run bootstrap to initialize project state before tracking sprints."
+
 ### Input
 
 User request: "next task", "current status", "story done", "new sprint", "scope check"
@@ -21,7 +29,31 @@ User request: "next task", "current status", "story done", "new sprint", "scope
 **Request: "current status" / "where are we"**
 1. Read project-state.md
 2. Summarize: current Sprint, in-progress Story, completed Stories
-3. Recommend next action
+3. Run **Next Step Recommendation** (see below)
+
+**Next Step Recommendation**
+
+After every status check, recommend the next action based on current context:
+
+1. Read `project-state.md`, `features.md`, `project-brief.md`, `failure-patterns.md`
+2. Determine the project phase and recommend accordingly:
+
+| Situation | Recommendation |
+|-----------|---------------|
+| State files are empty | → "Run `bootstrap` to onboard this project" |
+| project-brief.md has no Vision/Goals | → "Fill out project-brief.md — this is critical for direction" |
+| No stories exist | → "Run `planner` 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" |
+| A direction change was discussed | → "Run `pivot` to update all state files before continuing" |
+| Recent failure patterns apply | → "Watch out for FP-{NNN}: [description]" |
+
+3. Format the recommendation as:
+```
+💡 Recommended next: [action]
+   Why: [one-sentence reason]
+   Command: [exact skill/agent to invoke]
+```
 
 **Request: "story done" / "S{N}-{M} done"**
 1. Update the Story status to `done` in project-state.md

package/harness/backend-rules.md

@@ -2,18 +2,20 @@
 
 ## Required
 
-- Follow the project's architecture patterns strictly:
+- Follow the project's architecture patterns strictly.
+  <!-- TODO: Define your architecture layers. Examples:
   - Domain layer must not import from infrastructure.
   - Application layer accesses data only through domain interfaces.
   - Infrastructure implements domain interfaces.
-  - Presentation handles routing and DTO conversion only. No business logic.
-- Before calling any constructor, read the actual source file to verify parameters. Do not trust memory. (FP-002)
+  - Controllers/routes handle request/response only. No business logic.
+  -->
+- Before calling any constructor or factory, read the actual source file to verify parameters. Do not trust memory. (FP-002)
 
 ## Forbidden
 
-- Importing infrastructure from domain (dependency inversion violation).
-- `any` type usage — when unavoidable, add `// eslint-disable-next-line` with reason comment.
-- Hardcoding environment variables in code. Use `process.env` with centralized config.
+- Violating the project's dependency direction (e.g. importing infrastructure from domain).
+- Suppressing type safety without an explicit reason comment.
+- Hardcoding environment variables or secrets in code. Use centralized config.
 - `git add .` or `git add -A` — use explicit per-file staging.
 
 ## References

package/harness/core-rules.md

@@ -42,8 +42,8 @@
 ## Test Rules
 
 - New feature = New test. Do not commit feature code without tests.
-- Test command: `npm test` <!-- TODO: customize -->
-- Mock location: `tests/__mocks__/` <!-- TODO: customize -->
+- Test command: <!-- TODO: e.g. npm test, pytest, go test ./..., mvn test -->
+- Mock location: <!-- TODO: e.g. tests/__mocks__/, test/fixtures/ -->
 
 ## Completion Status Protocol
 
@@ -59,6 +59,18 @@ Report completion using one of:
 - When tests fail, quote the test name and error message.
 - When type errors occur, specify expected type and actual type.
 
+## Direction Guard (Every Request)
+
+Before starting ANY coding task, do this:
+
+1. Read `project-brief.md` — check Vision, Goals, Non-Goals, and Decision Log
+2. If `project-brief.md` is empty → run the `bootstrap` skill first, then return to the request
+3. If the request conflicts with **Non-Goals** → stop and warn: "This falls under Non-Goals. Do you want to proceed? If yes, run `pivot` skill first."
+4. If the request contradicts a **Decision Log** entry → warn: "This conflicts with a previous decision: [entry]. Run `pivot` skill to update direction."
+5. If aligned → proceed
+
+This applies to EVERY request, not just new sessions. Skip only for trivial questions ("what does this function do?").
+
 ## New Session Bootstrap
 
 When starting a NEW chat session, read these files in order before doing any work:
@@ -67,6 +79,33 @@ When starting a NEW chat session, read these files in order before doing any wor
 3. `failure-patterns.md` — What mistakes to avoid
 4. `project-brief.md` — Project vision, goals, and non-goals
 
+If ALL state files are empty (only TODOs/placeholders), run the `bootstrap` skill before doing anything else.
+
+## Workflow Pipeline
+
+Follow this order for different workflows. Each step's output feeds the next.
+
+### New Feature
+```
+bootstrap (if state files empty) → planner → [code] → reviewer → sprint-manager → learn
+```
+
+### Bug Fix
+```
+investigate → [fix] → test-integrity → reviewer → learn
+```
+
+### Session Lifecycle
+```
+[session start] → sprint-manager ("where are we?") → [work] → learn → [session end]
+```
+
+### Key Rules
+- **planner before code**: Never start coding a feature without running planner first.
+- **reviewer before commit**: Never commit without running reviewer.
+- **learn before closing**: Run learn as the last skill of every session.
+- **bootstrap once**: Run bootstrap once when state files are empty. Not needed after that.
+
 ## References
 
 - project-brief.md — Project vision, goals, non-goals (the "why")

package/harness/project-brief.md

@@ -1,49 +1,69 @@
 # Project Brief
 
+> **Fill this out immediately after running `k-harness init`.** The Planner agent uses this file for Direction Guard — without it, scope drift cannot be prevented.
+
 ## Vision
 
-<!-- What is this project and why does it exist?
-   Example: "An open-source MCP hub that connects AI tools to enterprise services."
-   Keep it to 1-2 sentences. This is the north star for all decisions. -->
+<!-- What is this project and why does it exist? Keep it to 1-2 sentences.
+   This is the north star for all decisions.
+   Examples:
+   - "An open-source MCP hub that connects AI tools to enterprise services."
+   - "A CLI tool that generates IDE-specific instruction files for LLM agents."
+   - "An e-commerce platform focused on local artisan products."
+-->
 
 ## Goals
 
-<!-- What must this project achieve? List 3-5 concrete goals.
-   Example:
+<!-- What must this project achieve? List 3-5 concrete, measurable goals.
+   Examples:
    - Support 50+ MCP servers with auto-discovery
    - Sub-100ms routing latency
    - Zero-config developer experience
+   - API coverage for all CRUD operations by v1.0
 -->
 
 ## Non-Goals
 
 <!-- What is explicitly OUT OF SCOPE? This is equally important as Goals.
-   Example:
+   The Planner agent will WARN you when a requested feature falls here.
+   Examples:
    - Not a hosting platform — users deploy their own
    - Not supporting legacy REST APIs — MCP only
    - Not building a UI dashboard in v1
+   - No mobile app — web only
 -->
 
 ## Target Users
 
-<!-- Who is this for?
-   Example: "Solo developers and small teams (1-3) using AI coding assistants."
+<!-- Who is this for? Be specific.
+   Examples:
+   - "Solo developers and small teams (1-3) using AI coding assistants."
+   - "Enterprise teams migrating from monolith to microservices."
+   - "Data scientists who need reproducible ML pipelines."
 -->
 
 ## Key Technical Decisions
 
-<!-- Record major architecture choices that should NOT be reversed without discussion.
-   Example:
-   - TypeScript + Node.js (not Go, not Python)
-   - SQLite for local storage (not PostgreSQL)
-   - Monorepo with npm workspaces
+<!-- Record foundational technology choices. Helps LLMs generate correct code.
+   Examples:
+   - Language: TypeScript 5.x (strict mode)
+   - Framework: Express + Prisma ORM
+   - Test runner: Vitest (not Jest)
+   - Database: PostgreSQL 16
+   - Architecture: Hexagonal (Port + Adapter)
+   - Language: Python 3.12, Framework: FastAPI, Tests: pytest
+   - Language: Go 1.22, no framework, Tests: go test
 -->
 
-## Success Criteria
+## Decision Log
+
+<!-- Record WHY key decisions were made. The Planner uses this to avoid re-debating settled decisions.
+   Use the `pivot` skill to add entries here when direction changes.
+   Format:
 
-<!-- How do we know this project is working?
-   Example:
-   - Users can install and run in under 5 minutes
-   - All MCP tools discoverable without manual configuration
-   - 90%+ test coverage on core modules
+### [YYYY-MM-DD] [Decision Title]
+- **Change**: What changed
+- **Reason**: Why this decision was made
+- **Impact**: What was affected
+- **Alternatives Considered**: What else was considered and rejected
 -->

package/harness/skills/bootstrap.md

@@ -0,0 +1,119 @@
+# Bootstrap
+
+## Purpose
+
+Onboard a new or existing project into K-Harness by filling state files automatically.
+Solves the cold-start problem: users don't know which `.md` files to fill or how.
+
+## When to Apply
+
+- Right after running `k-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"
+
+## Procedure
+
+### Phase 1: Project Discovery (read-only)
+
+1. **Scan project root** for configuration files:
+   - `package.json`, `tsconfig.json` → Node.js/TypeScript
+   - `go.mod`, `go.sum` → Go
+   - `requirements.txt`, `pyproject.toml`, `setup.py` → Python
+   - `pom.xml`, `build.gradle` → Java
+   - `Cargo.toml` → Rust
+   - `Gemfile` → Ruby
+2. **Scan directory structure**: List top-level directories and identify patterns
+   - `src/`, `lib/`, `app/` → source code
+   - `tests/`, `test/`, `__tests__/`, `spec/` → test directories
+   - `docs/` → documentation
+3. **Scan for existing tests**: Find test files and map them to source modules
+4. **Scan imports/dependencies**: Trace module relationships from import statements
+
+**Do NOT modify any code files in this phase.**
+
+### Phase 2: User Interview (interactive)
+
+Ask the user these questions (skip any already answered by Phase 1):
+
+1. "What does this project do? (one sentence)"
+2. "What are the top 3 goals of this project?"
+3. "What is explicitly OUT of scope? (non-goals)"
+4. "What architecture pattern are you using?" (show detected pattern if found)
+5. "Are there any type decisions or conventions the AI should know about?"
+
+### Phase 3: Fill State Files
+
+Using data from Phase 1 + Phase 2, fill the following files:
+
+**project-brief.md**:
+- Project Name → from package.json name, go.mod module, or user input
+- Vision → from user answer #1
+- Goals → from user answer #2
+- Non-Goals → from user answer #3
+- Key Technical Decisions → from Phase 1 scan + user answer #4, #5
+
+**features.md**:
+- Add one row per detected module/feature area
+- Status: `✅ done` for modules with passing tests, `🔧 active` for modules without tests
+- Key Files: actual file paths from scan
+- Test Files: actual test file paths from scan
+
+**dependency-map.md**:
+- Add one row per module
+- Layer: inferred from directory structure (domain/application/infrastructure/presentation)
+- Depends On / Depended By: inferred from import scan
+
+**project-state.md**:
+- Quick Summary: filled with current project state
+- Sprint 1 stories: based on what bootstrap discovered
+- Module Registry: summary from dependency-map.md
+
+**failure-patterns.md**:
+- Keep FP-001 through FP-004 as templates (Frequency: 0)
+- No changes unless user reports known issues
+
+### Phase 4: Verify
+
+1. Present a summary of all filled state files to the user
+2. Ask "Does this look correct? What should I change?"
+3. Apply corrections if any
+4. Report completion
+
+## Output Format
+
+```
+## Bootstrap Complete
+
+### Project: [name]
+### Tech Stack: [detected stack]
+### Modules Found: [count]
+### Features Mapped: [count]
+### Dependency Links: [count]
+
+### State Files Updated:
+- [x] project-brief.md — [summary]
+- [x] features.md — [N] features registered
+- [x] dependency-map.md — [N] modules, [N] dependencies
+- [x] project-state.md — Sprint 1 initialized
+- [ ] failure-patterns.md — templates only (no changes)
+
+STATUS: DONE
+```
+
+## Rules
+
+- Never modify source code — this skill only writes to state files
+- Always show the user what was discovered BEFORE writing files
+- If the project has 0 source files, skip Phase 1 scan and go straight to Phase 2
+- If a state file already has content, ask before overwriting
+- Run this skill only once per project (or when explicitly requested for refresh)
+
+## Anti-patterns
+
+| Anti-pattern | Correct Approach |
+|---|---|
+| Guess module boundaries | Scan actual directory structure and imports |
+| Skip user interview | Phase 1 scan alone is insufficient — always confirm with user |
+| Overwrite existing state files silently | Ask before overwriting non-empty files |
+| Create perfect dependency map on first try | Start with what's detectable, refine over time |

package/harness/skills/feature-breakdown.md

@@ -41,20 +41,20 @@ Ensures bottom-up implementation: foundations first, then layers that depend on
 
 ### Wave 1 (no dependencies)
 - [ ] Task 1: [Module A] — Create entity + repository interface
-  - Files: src/domain/entities/X.ts, src/domain/repositories/XRepository.ts
-  - Tests: tests/domain/X.test.ts
+  - Files: <!-- list files to create/modify -->
+  - Tests: <!-- list test files -->
   - Depends on: none
 
 ### Wave 2 (depends on Wave 1)
 - [ ] Task 2: [Module B] — Implement use case
-  - Files: src/application/usecases/DoX.ts
-  - Tests: tests/application/DoX.test.ts
+  - Files: <!-- list files to create/modify -->
+  - Tests: <!-- list test files -->
   - Depends on: Task 1
 
 ### Wave 3 (depends on Wave 2)
-- [ ] Task 3: [Module C] — Add API endpoint
-  - Files: src/presentation/routes/x.ts, src/presentation/dto/XDto.ts
-  - Tests: tests/presentation/x.test.ts
+- [ ] Task 3: [Module C] — Add API endpoint / UI integration
+  - Files: <!-- list files to create/modify -->
+  - Tests: <!-- list test files -->
   - Depends on: Task 2
 
 ### Dependency Map Updates
@@ -70,6 +70,14 @@ Ensures bottom-up implementation: foundations first, then layers that depend on
 - New modules MUST be registered in dependency-map.md (Iron Law #6)
 - If a task exceeds Story scope, stop and report to user
 
+## State File Updates (mandatory)
+
+After completing the breakdown, update these files in the same session:
+
+- [ ] **dependency-map.md**: Register all NEW_MODULE entries. Update "Depends On" / "Depended By" for INTERFACE_CHANGE entries.
+- [ ] **features.md**: Add a new row for the feature with Status `🔧 active`, Key Files from Wave tasks, and Test Files.
+- [ ] **project-state.md**: Add Stories to the Story Status table for each Wave.
+
 ## Anti-patterns
 
 | Anti-pattern | Correct Approach |
@@ -78,3 +86,4 @@ Ensures bottom-up implementation: foundations first, then layers that depend on
 | One giant task for the whole feature | Break into single-module tasks |
 | Skip dependency-map registration | Register immediately when creating module |
 | Tests "later" | Tests in the same task |
+| Produce breakdown but skip state file updates | State file updates are part of the breakdown, not a separate step |

package/harness/skills/impact-analysis.md

@@ -57,6 +57,13 @@ Plan: 4 files to update, all within S3-2 scope
 → Tests fail in 3 modules, mock out of sync, 2 hours wasted
 ```
 
+## State File Updates (mandatory)
+
+After completing the analysis, update these files:
+
+- [ ] **dependency-map.md**: Update the Interface Change Log table with: Date, Module, Change description, Affected Modules, Status.
+- [ ] **project-state.md**: If scope exceeds current Story, add a note to Recent Changes.
+
 ## Related Failure Patterns
 
 - FP-001: Interface changed, mock not updated → Checklist item 5

package/harness/skills/investigate.md

@@ -67,6 +67,13 @@ Phase 4: Tests pass, null case test added
 → Root cause unknown, no reproduction conditions recorded, same error possible elsewhere
 ```
 
+## State File Updates (mandatory)
+
+After the fix is verified (Phase 4):
+
+- [ ] **failure-patterns.md**: If the root cause is a repeatable pattern, add a new FP-NNN entry or increment the Frequency of an existing one. This is NOT optional.
+- [ ] **project-state.md**: Add the fix to Recent Changes with the root cause hypothesis.
+
 ## Related Failure Patterns
 
 - FP-002: Type confusion → Phase 1 requires verifying actual types

package/harness/skills/learn.md

@@ -0,0 +1,100 @@
+# Learn
+
+## Purpose
+
+Capture lessons from the current session before ending.
+Updates failure-patterns.md with new patterns and refreshes project-state.md Quick Summary.
+This is K-Harness's memory mechanism — without it, the same mistakes repeat across sessions.
+
+## When to Apply
+
+- Before ending a chat session (recommended as the LAST skill invoked)
+- After a debugging session where a non-obvious fix was found
+- After a review revealed a repeated mistake
+- When the user explicitly asks to record a lesson
+
+## Procedure
+
+### Step 1: Review Session Activity
+
+1. Scan recent git changes: `git log --oneline -10` and `git diff --stat HEAD~3`
+2. Identify what was accomplished in this session
+3. Identify any errors, failures, or unexpected issues that occurred
+
+### Step 2: Failure Pattern Detection
+
+For each issue/error that occurred in this session:
+
+1. Read `failure-patterns.md`
+2. Check if this matches an existing pattern (FP-NNN):
+   - **If match found**: Increment the Frequency counter, add the Sprint/Story to "Occurred"
+   - **If new pattern**: Assign next FP-NNN number, create a new entry using this format:
+
+```markdown
+## FP-NNN: [Short description]
+
+- **Occurred**: S[sprint]-[story]
+- **Frequency**: 1
+- **Cause**: [What went wrong and why]
+- **Prevention**: [Specific check to prevent recurrence]
+- **Applied in**: [Which skills/agents/rules should enforce this]
+- **Status**: Active
+```
+
+3. If the failure relates to a specific skill or agent, note it for that skill's checklist
+
+### Step 3: Update project-state.md
+
+1. Update **Quick Summary** (3 lines):
+   - Line 1: What was accomplished in this session
+   - Line 2: What is currently in progress
+   - Line 3: What should be done next
+2. Update **Story Status** table if any stories changed
+3. Add to **Recent Changes** section with date and summary
+
+### Step 4: Update features.md (if applicable)
+
+1. If new features were added → add row to Feature List
+2. If existing features were modified → update Key Files and Test Files columns
+3. If features were completed → update Status to `✅ done`
+
+### Step 5: Report
+
+Present a summary of all updates made.
+
+## Output Format
+
+```
+## Session Learn Complete
+
+### Lessons Captured:
+- [FP-NNN] (new/updated): [description]
+
+### State Files Updated:
+- [x] project-state.md — Quick Summary refreshed
+- [x] failure-patterns.md — [N] patterns added/updated
+- [x] features.md — [N] features updated (if applicable)
+
+### Next Session Should:
+1. [recommended first action]
+2. [next priority]
+
+STATUS: DONE
+```
+
+## Rules
+
+- Never invent patterns that didn't actually occur — record only real failures
+- Keep failure pattern descriptions concise (1-2 sentences for Cause and Prevention)
+- If no failures occurred, skip Step 2 and just update state files
+- Do not modify source code — this skill only updates state files
+- Quick Summary must be exactly 3 lines — concise enough for the next session to scan instantly
+
+## Anti-patterns
+
+| Anti-pattern | Correct Approach |
+|---|---|
+| Record theoretical risks as failure patterns | Only record failures that actually happened |
+| Write vague descriptions ("something broke") | Be specific: file name, error message, root cause |
+| Skip this skill because "nothing went wrong" | Still update Quick Summary and Story Status |
+| Update failure-patterns.md but not project-state.md | Always update both — they serve different purposes |

package/harness/skills/pivot.md

@@ -0,0 +1,102 @@
+# Pivot
+
+## Purpose
+
+When a project direction changes — technology swap, scope expansion/reduction, architecture shift — this skill propagates the change across ALL state files consistently.
+Without this, direction changes create silent inconsistencies: project-brief.md says "GraphQL" but dependency-map.md still references REST modules.
+
+## When to Apply
+
+- Technology change: "Switch from REST to GraphQL", "Replace PostgreSQL with MongoDB"
+- Scope change: "Add real-time features", "Remove mobile support", "Downscope to MVP"
+- Architecture shift: "Move from monolith to microservices", "Switch from SSR to SPA"
+- Goal change: "Pivot from B2C to B2B", "Change target users"
+- Any time the user says "let's change direction", "pivot", "switch to", "drop [feature area]"
+
+## Procedure
+
+### Step 1: Capture the Change
+
+1. Ask the user to describe the change in one sentence
+2. Classify the change type:
+   - **Tech Swap**: Replacing one technology with another
+   - **Scope Change**: Adding or removing feature areas
+   - **Architecture Shift**: Changing system structure
+   - **Goal Pivot**: Changing project purpose or target
+
+### Step 2: Impact Scan
+
+Read ALL state files and identify what needs updating:
+
+1. **project-brief.md**:
+   - Does Vision need rewording?
+   - Do Goals need updating?
+   - Do Non-Goals need updating?
+   - Do Key Technical Decisions need changing?
+   - Record the decision with reasoning in the Decision Log section
+
+2. **features.md**:
+   - Which existing features are affected?
+   - Which features should be marked `⛔ dropped`?
+   - Are new features needed?
+
+3. **dependency-map.md**:
+   - Which modules are obsoleted by this change?
+   - Which new modules are needed?
+   - Which dependency relationships change?
+
+4. **project-state.md**:
+   - Which in-progress stories are affected?
+   - Does the current sprint goal change?
+   - Update Quick Summary to reflect the pivot
+
+5. **failure-patterns.md**:
+   - Are any existing patterns invalidated by this change?
+   - Mark invalidated patterns as `Status: Obsolete (pivot: [reason])`
+
+### Step 3: Present Change Plan
+
+Before writing anything, present a summary to the user:
+
+```
+## Pivot: [one-sentence description]
+Type: [Tech Swap | Scope Change | Architecture Shift | Goal Pivot]
+
+### State File Changes:
+- project-brief.md: [what changes]
+- features.md: [N features affected, M dropped, K added]
+- dependency-map.md: [N modules obsoleted, M added, K relationships changed]
+- project-state.md: [N stories affected]
+- failure-patterns.md: [N patterns obsoleted]
+
+### Confirm? (yes/no)
+```
+
+### Step 4: Execute Updates
+
+After user confirms, update ALL state files in order:
+
+1. **project-brief.md** first (source of truth for direction)
+2. **features.md** second (what we're building)
+3. **dependency-map.md** third (how it connects)
+4. **project-state.md** fourth (current work status)
+5. **failure-patterns.md** last (historical patterns)
+
+### Step 5: Decision Log Entry
+
+Add an entry to the Decision Log section in project-brief.md:
+
+```markdown
+### [YYYY-MM-DD] [Decision Title]
+- **Change**: [What changed]
+- **Reason**: [Why this decision was made]
+- **Impact**: [What was affected]
+- **Alternatives Considered**: [What else was considered and rejected]
+```
+
+## Rules
+
+- **Never skip the confirmation step** — the user must approve before any state file is written
+- **Never update partially** — if you update project-brief.md, you MUST check and update all other state files too
+- **Preserve history** — mark dropped features as `⛔ dropped`, don't delete rows
+- **Record the why** — every pivot must have a Decision Log entry with reasoning

package/harness/skills/security-checklist.md

@@ -44,6 +44,12 @@ git add .
 const dbPassword = "super_secret_123";
 ```
 
+## State File Updates (mandatory)
+
+After completing the security check:
+
+- [ ] **failure-patterns.md**: If a security issue was found (credentials staged, hardcoded secret), add a new FP-NNN entry or increment FP-004 Frequency.
+
 ## Related Failure Patterns
 
 - FP-004: Dangerous file committed → Checklist items 1, 4

package/harness/skills/test-integrity.md

@@ -41,6 +41,13 @@ Interface adds findByFilters() → Mock unchanged
 → Runtime error: method not found on mock object
 ```
 
+## State File Updates (mandatory)
+
+After synchronizing mocks:
+
+- [ ] **failure-patterns.md**: If mock sync was missed and caused a test failure, increment FP-001 Frequency.
+- [ ] **dependency-map.md**: If the interface change altered module relationships, update the relevant row.
+
 ## Related Failure Patterns
 
 - FP-001: Interface changed, mock not updated → Checklist item 1

package/harness/testing-rules.md

@@ -11,9 +11,9 @@
 ## Forbidden
 
 - Casting mocks with `any` type. Create mocks using the actual interface type.
-- Creating mocks with bare `jest.fn()` only. Set default return values with `mockResolvedValue` etc.
+- Creating mocks with no default return values. Always set sensible defaults (e.g. `mockResolvedValue`, stub returns).
 - Committing with `skip` or `only` left in test files.
-- Committing with `console.log` debugging statements.
+- Committing with debugging statements (e.g. `console.log`, `print`, `println`).
 
 ## References
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "k-harness",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "LLM Development Harness — IDE-agnostic rules, skills, and agents that prevent common AI coding failures",
   "keywords": [
     "llm",
@@ -35,6 +35,9 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "scripts": {
+    "test": "node --test tests/*.test.js"
+  },
   "publishConfig": {
     "access": "public"
   }

package/src/init.js

@@ -24,6 +24,61 @@ function writeFile(targetDir, relPath, content, overwrite) {
   return true;
 }
 
+// ─── Shared definitions ──────────────────────────────────────
+
+const SKILLS = [
+  { id: 'test-integrity', desc: 'Ensure test mocks stay synchronized when interfaces change. Use when modifying repository or service interfaces.' },
+  { id: 'security-checklist', desc: 'Security risk inspection before commits. Use when reviewing code for security issues.' },
+  { id: 'investigate', desc: 'Investigate and diagnose issues. Use when debugging or analyzing unexpected behavior.' },
+  { id: 'impact-analysis', desc: 'Assess change blast radius. Use when modifying shared modules or interfaces.' },
+  { id: 'feature-breakdown', desc: 'Break down features into implementable stories. Use when planning new features.' },
+  { id: 'bootstrap', desc: 'Onboard project into K-Harness. Scans codebase and fills state files. Use after k-harness init or when state files are empty.' },
+  { id: 'learn', desc: 'Capture session lessons and update state files. Use at the end of every session.' },
+  { id: 'pivot', desc: 'Propagate direction changes across all state files. Use when project goals, technology, scope, or architecture changes.' },
+];
+
+const AGENTS = [
+  { id: 'reviewer', file: 'agents/reviewer.md', desc: 'Code review + auto-fix. Validates quality, security, and test integrity before commits.' },
+  { id: 'sprint-manager', file: 'agents/sprint-manager.md', desc: 'Sprint/Story state tracking, next task guidance, scope drift prevention.' },
+  { id: 'planner', file: 'agents/planner.md', desc: 'Feature planning and dependency management. Analyze architecture, break down features.' },
+];
+
+const STATE_FILES = [
+  'project-state.md',
+  'failure-patterns.md',
+  'dependency-map.md',
+  'features.md',
+  'project-brief.md',
+];
+
+// ─── Shared writers ──────────────────────────────────────────
+
+function writeStateFiles(targetDir, overwrite) {
+  for (const file of STATE_FILES) {
+    writeFile(targetDir, file, readTemplate(file), overwrite);
+  }
+}
+
+function writeSkills(targetDir, skillsDir, overwrite) {
+  for (const skill of SKILLS) {
+    const content = readTemplate(`skills/${skill.id}.md`);
+    const skillMd =
+      `---\nname: ${skill.id}\ndescription: '${skill.desc}'\n---\n\n` +
+      content;
+    writeFile(targetDir, `${skillsDir}/${skill.id}/SKILL.md`, skillMd, overwrite);
+  }
+}
+
+function writeAgentsAsSkills(targetDir, skillsDir, overwrite) {
+  for (const agent of AGENTS) {
+    const content = readTemplate(agent.file);
+    const skillMd =
+      `---\nname: ${agent.id}\ndescription: '${agent.desc}'\n---\n\n` +
+      content;
+    writeFile(targetDir, `${skillsDir}/${agent.id}/SKILL.md`, skillMd, overwrite);
+  }
+}
+
 // ─── IDE Generators ──────────────────────────────────────────
 
 function generateVscode(targetDir, overwrite) {
@@ -45,38 +100,20 @@ function generateVscode(targetDir, overwrite) {
     backendRules;
   writeFile(targetDir, '.vscode/instructions/backend.instructions.md', backendWithFrontmatter, overwrite);
 
-  // Skills (.github/skills — VS Code default search path)
-  writeFile(targetDir, '.github/skills/test-integrity/SKILL.md', readTemplate('skills/test-integrity.md'), overwrite);
-  writeFile(targetDir, '.github/skills/security-checklist/SKILL.md', readTemplate('skills/security-checklist.md'), overwrite);
-  writeFile(targetDir, '.github/skills/investigate/SKILL.md', readTemplate('skills/investigate.md'), overwrite);
-  writeFile(targetDir, '.github/skills/impact-analysis/SKILL.md', readTemplate('skills/impact-analysis.md'), overwrite);
-  writeFile(targetDir, '.github/skills/feature-breakdown/SKILL.md', readTemplate('skills/feature-breakdown.md'), overwrite);
-
-  // Agents (.github/agents — VS Code default search path)
-  const reviewerContent = readTemplate('agents/reviewer.md');
-  const reviewerAgent =
-    '---\nname: reviewer\ndescription: "Code review + auto-fix. Validates quality, security, and test integrity before commits."\n---\n\n' +
-    reviewerContent;
-  writeFile(targetDir, '.github/agents/reviewer.agent.md', reviewerAgent, overwrite);
-
-  const sprintContent = readTemplate('agents/sprint-manager.md');
-  const sprintAgent =
-    '---\nname: sprint-manager\ndescription: "Sprint/Story state tracking, next task guidance, scope drift prevention."\n---\n\n' +
-    sprintContent;
-  writeFile(targetDir, '.github/agents/sprint-manager.agent.md', sprintAgent, overwrite);
-
-  const plannerContent = readTemplate('agents/planner.md');
-  const plannerAgent =
-    '---\nname: planner\ndescription: "Feature planning and dependency management. Analyze architecture, break down features, track module relationships."\n---\n\n' +
-    plannerContent;
-  writeFile(targetDir, '.github/agents/planner.agent.md', plannerAgent, overwrite);
+  // Skills (.github/skills — VS Code default search path, SKILL.md with frontmatter)
+  writeSkills(targetDir, '.github/skills', overwrite);
+
+  // Agents (.github/agents — VS Code uses .agent.md format with frontmatter)
+  for (const agent of AGENTS) {
+    const content = readTemplate(agent.file);
+    const agentMd =
+      `---\nname: ${agent.id}\ndescription: "${agent.desc}"\n---\n\n` +
+      content;
+    writeFile(targetDir, `.github/agents/${agent.id}.agent.md`, agentMd, overwrite);
+  }
 
   // State files
-  writeFile(targetDir, 'project-state.md', readTemplate('project-state.md'), overwrite);
-  writeFile(targetDir, 'failure-patterns.md', readTemplate('failure-patterns.md'), overwrite);
-  writeFile(targetDir, 'dependency-map.md', readTemplate('dependency-map.md'), overwrite);
-  writeFile(targetDir, 'features.md', readTemplate('features.md'), overwrite);
-  writeFile(targetDir, 'project-brief.md', readTemplate('project-brief.md'), overwrite);
+  writeStateFiles(targetDir, overwrite);
 }
 
 function generateClaude(targetDir, overwrite) {
@@ -90,19 +127,11 @@ function generateClaude(targetDir, overwrite) {
   ].join('');
   writeFile(targetDir, 'CLAUDE.md', merged, overwrite);
 
-  // Skills (Claude uses same SKILL.md format)
-  writeFile(targetDir, '.claude/skills/test-integrity/SKILL.md', readTemplate('skills/test-integrity.md'), overwrite);
-  writeFile(targetDir, '.claude/skills/security-checklist/SKILL.md', readTemplate('skills/security-checklist.md'), overwrite);
-  writeFile(targetDir, '.claude/skills/investigate/SKILL.md', readTemplate('skills/investigate.md'), overwrite);
-  writeFile(targetDir, '.claude/skills/impact-analysis/SKILL.md', readTemplate('skills/impact-analysis.md'), overwrite);
-  writeFile(targetDir, '.claude/skills/feature-breakdown/SKILL.md', readTemplate('skills/feature-breakdown.md'), overwrite);
+  // Skills (SKILL.md with frontmatter for slash commands)
+  writeSkills(targetDir, '.claude/skills', overwrite);
 
   // State files
-  writeFile(targetDir, 'project-state.md', readTemplate('project-state.md'), overwrite);
-  writeFile(targetDir, 'failure-patterns.md', readTemplate('failure-patterns.md'), overwrite);
-  writeFile(targetDir, 'dependency-map.md', readTemplate('dependency-map.md'), overwrite);
-  writeFile(targetDir, 'features.md', readTemplate('features.md'), overwrite);
-  writeFile(targetDir, 'project-brief.md', readTemplate('project-brief.md'), overwrite);
+  writeStateFiles(targetDir, overwrite);
 }
 
 function generateCursor(targetDir, overwrite) {
@@ -126,35 +155,25 @@ function generateCursor(targetDir, overwrite) {
   writeFile(targetDir, '.cursor/rules/backend.mdc', backendMdc, overwrite);
 
   // Skills as rules
-  const skills = ['test-integrity', 'security-checklist', 'investigate', 'impact-analysis', 'feature-breakdown'];
-  for (const skill of skills) {
-    const content = readTemplate(`skills/${skill}.md`);
+  for (const skill of SKILLS) {
+    const content = readTemplate(`skills/${skill.id}.md`);
     const mdc =
-      `---\ndescription: Skill — ${skill}\nalwaysApply: false\n---\n\n` +
+      `---\ndescription: Skill — ${skill.id}\nalwaysApply: false\n---\n\n` +
       content;
-    writeFile(targetDir, `.cursor/rules/${skill}.mdc`, mdc, overwrite);
+    writeFile(targetDir, `.cursor/rules/${skill.id}.mdc`, mdc, overwrite);
   }
 
   // Agents as rules
-  const agents = [
-    { name: 'reviewer', file: 'agents/reviewer.md' },
-    { name: 'sprint-manager', file: 'agents/sprint-manager.md' },
-    { name: 'planner', file: 'agents/planner.md' },
-  ];
-  for (const agent of agents) {
+  for (const agent of AGENTS) {
     const content = readTemplate(agent.file);
     const mdc =
-      `---\ndescription: Agent — ${agent.name}\nalwaysApply: false\n---\n\n` +
+      `---\ndescription: Agent — ${agent.id}\nalwaysApply: false\n---\n\n` +
       content;
-    writeFile(targetDir, `.cursor/rules/${agent.name}.mdc`, mdc, overwrite);
+    writeFile(targetDir, `.cursor/rules/${agent.id}.mdc`, mdc, overwrite);
   }
 
   // State files
-  writeFile(targetDir, 'project-state.md', readTemplate('project-state.md'), overwrite);
-  writeFile(targetDir, 'failure-patterns.md', readTemplate('failure-patterns.md'), overwrite);
-  writeFile(targetDir, 'dependency-map.md', readTemplate('dependency-map.md'), overwrite);
-  writeFile(targetDir, 'features.md', readTemplate('features.md'), overwrite);
-  writeFile(targetDir, 'project-brief.md', readTemplate('project-brief.md'), overwrite);
+  writeStateFiles(targetDir, overwrite);
 }
 
 function generateCodex(targetDir, overwrite) {
@@ -168,19 +187,11 @@ function generateCodex(targetDir, overwrite) {
   ].join('');
   writeFile(targetDir, 'AGENTS.md', merged, overwrite);
 
-  // Skills (Codex uses .agents/skills/ format)
-  writeFile(targetDir, '.agents/skills/test-integrity/SKILL.md', readTemplate('skills/test-integrity.md'), overwrite);
-  writeFile(targetDir, '.agents/skills/security-checklist/SKILL.md', readTemplate('skills/security-checklist.md'), overwrite);
-  writeFile(targetDir, '.agents/skills/investigate/SKILL.md', readTemplate('skills/investigate.md'), overwrite);
-  writeFile(targetDir, '.agents/skills/impact-analysis/SKILL.md', readTemplate('skills/impact-analysis.md'), overwrite);
-  writeFile(targetDir, '.agents/skills/feature-breakdown/SKILL.md', readTemplate('skills/feature-breakdown.md'), overwrite);
+  // Skills (SKILL.md with frontmatter for slash commands)
+  writeSkills(targetDir, '.agents/skills', overwrite);
 
   // State files
-  writeFile(targetDir, 'project-state.md', readTemplate('project-state.md'), overwrite);
-  writeFile(targetDir, 'failure-patterns.md', readTemplate('failure-patterns.md'), overwrite);
-  writeFile(targetDir, 'dependency-map.md', readTemplate('dependency-map.md'), overwrite);
-  writeFile(targetDir, 'features.md', readTemplate('features.md'), overwrite);
-  writeFile(targetDir, 'project-brief.md', readTemplate('project-brief.md'), overwrite);
+  writeStateFiles(targetDir, overwrite);
 }
 
 function generateWindsurf(targetDir, overwrite) {
@@ -190,24 +201,18 @@ function generateWindsurf(targetDir, overwrite) {
     readTemplate('testing-rules.md'),
     readTemplate('backend-rules.md'),
     '---\n\n# Skills\n\n',
-    readTemplate('skills/test-integrity.md'),
-    readTemplate('skills/security-checklist.md'),
-    readTemplate('skills/investigate.md'),
-    readTemplate('skills/impact-analysis.md'),
-    readTemplate('skills/feature-breakdown.md'),
-    '---\n\n# Agents\n\n',
-    readTemplate('agents/reviewer.md'),
-    readTemplate('agents/sprint-manager.md'),
-    readTemplate('agents/planner.md'),
   ];
+  for (const skill of SKILLS) {
+    sections.push(readTemplate(`skills/${skill.id}.md`));
+  }
+  sections.push('---\n\n# Agents\n\n');
+  for (const agent of AGENTS) {
+    sections.push(readTemplate(agent.file));
+  }
   writeFile(targetDir, '.windsurfrules', sections.join('\n\n---\n\n'), overwrite);
 
   // State files
-  writeFile(targetDir, 'project-state.md', readTemplate('project-state.md'), overwrite);
-  writeFile(targetDir, 'failure-patterns.md', readTemplate('failure-patterns.md'), overwrite);
-  writeFile(targetDir, 'dependency-map.md', readTemplate('dependency-map.md'), overwrite);
-  writeFile(targetDir, 'features.md', readTemplate('features.md'), overwrite);
-  writeFile(targetDir, 'project-brief.md', readTemplate('project-brief.md'), overwrite);
+  writeStateFiles(targetDir, overwrite);
 }
 
 function generateAugment(targetDir, overwrite) {
@@ -230,46 +235,51 @@ function generateAugment(targetDir, overwrite) {
     backendRules;
   writeFile(targetDir, '.augment/rules/backend.md', backendRule, overwrite);
 
-  // Skills as Auto rules
-  const skills = ['test-integrity', 'security-checklist', 'investigate', 'impact-analysis', 'feature-breakdown'];
-  for (const skill of skills) {
-    const content = readTemplate(`skills/${skill}.md`);
-    const rule =
-      `---\ndescription: Skill — ${skill}\ntype: manual\n---\n\n` +
-      content;
-    writeFile(targetDir, `.augment/rules/${skill}.md`, rule, overwrite);
-  }
+  // .augment/skills/ — SKILL.md format (enables / slash commands)
+  writeSkills(targetDir, '.augment/skills', overwrite);
+  writeAgentsAsSkills(targetDir, '.augment/skills', overwrite);
 
-  // Agents as Manual rules
-  const agents = [
-    { name: 'reviewer', file: 'agents/reviewer.md' },
-    { name: 'sprint-manager', file: 'agents/sprint-manager.md' },
-    { name: 'planner', file: 'agents/planner.md' },
-  ];
-  for (const agent of agents) {
-    const content = readTemplate(agent.file);
-    const rule =
-      `---\ndescription: Agent — ${agent.name}\ntype: manual\n---\n\n` +
-      content;
-    writeFile(targetDir, `.augment/rules/${agent.name}.md`, rule, overwrite);
-  }
+  // State files
+  writeStateFiles(targetDir, overwrite);
+}
+
+function generateAntigravity(targetDir, overwrite) {
+  // .agent/rules/ — Always-type rules (same as Augment format, read by Antigravity)
+  const coreRules = readTemplate('core-rules.md');
+  const coreRule =
+    '---\ndescription: Core project rules — Iron Laws, completion protocol, concreteness\ntype: always\n---\n\n' +
+    coreRules;
+  writeFile(targetDir, '.agent/rules/core.md', coreRule, overwrite);
+
+  const testingRules = readTemplate('testing-rules.md');
+  const testingRule =
+    '---\ndescription: Testing rules — mock sync, forbidden patterns\ntype: auto\nglobs: "**/*.test.*,**/*.spec.*,**/__mocks__/**,**/__tests__/**"\n---\n\n' +
+    testingRules;
+  writeFile(targetDir, '.agent/rules/testing.md', testingRule, overwrite);
+
+  const backendRules = readTemplate('backend-rules.md');
+  const backendRule =
+    '---\ndescription: Backend code rules — architecture enforcement, type safety\ntype: auto\nglobs: "src/**/*.ts,src/**/*.js"\n---\n\n' +
+    backendRules;
+  writeFile(targetDir, '.agent/rules/backend.md', backendRule, overwrite);
+
+  // .agent/skills/ — SKILL.md format (enables / slash commands)
+  writeSkills(targetDir, '.agent/skills', overwrite);
+  writeAgentsAsSkills(targetDir, '.agent/skills', overwrite);
 
   // State files
-  writeFile(targetDir, 'project-state.md', readTemplate('project-state.md'), overwrite);
-  writeFile(targetDir, 'failure-patterns.md', readTemplate('failure-patterns.md'), overwrite);
-  writeFile(targetDir, 'dependency-map.md', readTemplate('dependency-map.md'), overwrite);
-  writeFile(targetDir, 'features.md', readTemplate('features.md'), overwrite);
-  writeFile(targetDir, 'project-brief.md', readTemplate('project-brief.md'), overwrite);
+  writeStateFiles(targetDir, overwrite);
 }
 
 // ─── IDE registry ────────────────────────────────────────────
 const GENERATORS = {
-  vscode:   { name: 'VS Code Copilot',  fn: generateVscode },
-  claude:   { name: 'Claude Code',      fn: generateClaude },
-  cursor:   { name: 'Cursor',           fn: generateCursor },
-  codex:    { name: 'Codex (OpenAI)',    fn: generateCodex },
-  windsurf: { name: 'Windsurf',         fn: generateWindsurf },
-  augment:  { name: 'Augment Code',     fn: generateAugment },
+  vscode:       { name: 'VS Code Copilot',      fn: generateVscode },
+  claude:       { name: 'Claude Code',           fn: generateClaude },
+  cursor:       { name: 'Cursor',                fn: generateCursor },
+  codex:        { name: 'Codex (OpenAI)',         fn: generateCodex },
+  windsurf:     { name: 'Windsurf',              fn: generateWindsurf },
+  augment:      { name: 'Augment Code',          fn: generateAugment },
+  antigravity:  { name: 'Google Antigravity',    fn: generateAntigravity },
 };
 
 // ─── Interactive prompt ──────────────────────────────────────
@@ -309,7 +319,7 @@ function showHelp() {
     npx k-harness init [options]
 
   Options:
-    --ide <name>     IDE target: vscode, claude, cursor, codex, windsurf, augment
+    --ide <name>     IDE target: vscode, claude, cursor, codex, windsurf, augment, antigravity
     --dir <path>     Target directory (default: current directory)
     --overwrite      Overwrite existing files
     --help           Show this help