k-harness 0.7.0 → 0.8.2

package/README.md

@@ -1,5 +1,9 @@
 # K-Harness
 
+[![npm version](https://img.shields.io/npm/v/k-harness.svg)](https://www.npmjs.com/package/k-harness)
+[![npm downloads](https://img.shields.io/npm/dm/k-harness.svg)](https://www.npmjs.com/package/k-harness)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 Project Direction Management Framework for LLM-Driven Development.
 
 ## What It Does
@@ -49,24 +53,22 @@ npx k-harness init --ide antigravity
 
 ## Supported IDEs
 
-| IDE | Global Rules | File-Scoped Rules | Skills | Agents |
-|-----|-------------|-------------------|--------|--------|
-| **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` | (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/skills/*/SKILL.md` | `.augment/skills/*/SKILL.md` |
-| **Google Antigravity** | `.agent/rules/core.md` | `.agent/rules/*.md` | `.agent/skills/*/SKILL.md` | `.agent/skills/*/SKILL.md` |
+| IDE | Dispatcher (always-on) | Skills | Agents |
+|-----|----------------------|--------|--------|
+| **VS Code Copilot** | `.github/copilot-instructions.md` | `.github/skills/*/SKILL.md` | `.github/agents/*.agent.md` |
+| **Claude Code** | `.claude/rules/core.md` | `.claude/skills/*/SKILL.md` | `.claude/skills/*/SKILL.md` |
+| **Cursor** | `.cursor/rules/core.mdc` | `.cursor/rules/*.mdc` | `.cursor/rules/*.mdc` |
+| **Codex** | `AGENTS.md` | `.agents/skills/*/SKILL.md` | (merged into AGENTS.md) |
+| **Windsurf** | `.windsurfrules` | (merged) | (merged) |
+| **Augment Code** | `.augment/rules/core.md` | `.augment/skills/*/SKILL.md` | `.augment/skills/*/SKILL.md` |
+| **Google Antigravity** | `.agent/rules/core.md` | `.agent/skills/*/SKILL.md` | `.agent/skills/*/SKILL.md` |
 
 All IDEs also get state files (`project-state.md`, `project-brief.md`, `features.md`, `failure-patterns.md`, `dependency-map.md`) in the `docs/` directory.
 
 ## What Gets Installed
 
-### Rules (always active)
-- **Core Rules** — Architecture enforcement, Iron Laws, completion protocol, concreteness rules
-- **Testing Rules** — Mock synchronization, forbidden patterns (applied to test files)
-- **Backend Rules** — Dependency inversion, type safety, explicit staging (applied to source files)
+### Dispatcher (always active)
+- **Core Rules** — 22-line dispatcher: session start guidance, workflow references, state file list. Detailed rules are embedded in each skill/agent that enforces them.
 
 ### Skills (on-demand procedures)
 - **bootstrap** — Onboard project into K-Harness: scans codebase + fills state files automatically
@@ -120,18 +122,18 @@ When goals, technology, or scope changes, run the `pivot` skill:
 
 See [docs/reference.md](docs/reference.md) for detailed descriptions of every skill, agent, rule, and state file.
 
-## 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 | ~20 |
-| 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 |
+## Why K-Harness?
+
+| | BMAD v6.2.2 | gstack v0.15.1 | GSD v1.33.0 | K-Harness |
+|---|---|---|---|---|
+| Focus | Enterprise SDLC methodology | 1-person software factory | Full lifecycle automation | Project direction management |
+| Files | 200+ | ~40 | Hundreds | ~20 |
+| Dependencies | Node 20+ | Bun + Node + Playwright | Node 18+ | Zero |
+| IDE support | 20+ (installer) | 5 (setup --host) | 13 (runtime select) | 7 (native format) |
+| Direction management | ❌ | ❌ | ❌ | ✅ (Direction Guard + pivot + Decision Log) |
+| Iron Laws (code quality rules) | ❌ | ❌ | ❌ | ✅ (6 laws embedded in skills) |
+| Cold start | ❌ | ❌ | `/gsd-new-project` | ✅ (`bootstrap` skill) |
+| Context per task | 4-6 files | 1 file | Fresh 200k per plan | 2-3 files (22-line dispatcher) |
 
 ## License
 

package/harness/agents/planner.md

@@ -105,6 +105,16 @@ If `docs/project-brief.md` alone is empty → Warn the user but proceed (the pla
 - Last changed: [Sprint/Story reference]
 ```
 
+## Enforced Rules
+
+- **Direction Guard**: Before planning, read `docs/project-brief.md` and check:
+  - If it conflicts with **Non-Goals** → stop and ask the user
+  - If it contradicts a **Decision Log** entry → warn and recommend `pivot` skill
+  - If it represents a direction change → recommend `pivot` skill
+- **Dependency Map**: When the plan adds or modifies modules, include docs/dependency-map.md updates in the plan.
+- **Feature Registry**: When the plan adds a new feature, include docs/features.md registration in the plan.
+- **Type Check**: Before referencing constructors or factories, verify parameters from source files. Do not rely on memory (FP-002).
+
 ## Constraints
 
 - Never skip reading docs/dependency-map.md — the plan is only as good as the map

package/harness/agents/reviewer.md

@@ -99,6 +99,40 @@ For each missing update: flag as `[STATE-AUDIT]` in the output and provide the e
 STATUS: DONE / DONE_WITH_CONCERNS / BLOCKED
 ```
 
+## Embedded Rules
+
+These rules are enforced during every review:
+
+### Iron Laws
+1. **Mock Sync**: Interface change → mock updated in same commit (FP-001)
+2. **Type Check**: Verify constructor/factory parameters from source, not memory (FP-002)
+3. **Scope Compliance**: Changes must be within current Story scope (docs/project-state.md)
+4. **Security**: No credentials, passwords, or API keys in code or commits
+5. **3-Failure Stop**: Same approach failed 3 times → stop and report
+6. **Dependency Map**: New/modified module → docs/dependency-map.md updated
+7. **Feature Registry**: New feature → docs/features.md updated
+8. **Session Handoff**: Session end → docs/project-state.md Quick Summary updated
+
+### Testing Rules
+- New feature = New test. No feature code without tests.
+- Mocks must implement ALL interface methods with sensible defaults.
+- No `any` type casting on mocks. Use the actual interface type.
+- No `skip`, `only`, or debug statements (`console.log`, `print`) in committed test files.
+- Async tests must use `await`. No floating promises.
+
+### Backend Rules
+- Follow project architecture pattern strictly (e.g., Domain must not import Infrastructure)
+- No hardcoded environment variables or secrets — use centralized config
+- Use explicit file staging (`git add <file>`), never `git add .` or `git add -A`
+
+### Completion Protocol
+Report using: **DONE** | **DONE_WITH_CONCERNS** | **BLOCKED** | **NEEDS_CONTEXT**
+
+### Concreteness
+- Specify exact file paths and line numbers
+- Quote test names and error messages on failure
+- Specify expected vs actual types on type errors
+
 ## Constraints
 
 - Do not refactor beyond the review scope

package/harness/agents/sprint-manager.md

@@ -98,6 +98,11 @@ Progress: {done}/{total} Stories
 STATUS: DONE
 ```
 
+## Enforced Rules
+
+- **Scope Compliance**: Do not modify files outside the current Story scope. If user requests an out-of-scope change, warn first and proceed only after confirmation.
+- **Completion Protocol**: Report using: **DONE** | **DONE_WITH_CONCERNS** | **BLOCKED** | **NEEDS_CONTEXT**
+
 ## Constraints
 
 - Do not modify code directly — manage state only

package/harness/core-rules.md

@@ -1,135 +1,24 @@
-# Project Instructions
+# K-Harness
 
-## Architecture
+This project uses K-Harness for structured AI-assisted development.
+Skills and agents work together through shared state files — invoke them as needed.
 
-<!-- TODO: Describe your project's architecture here.
-   Example:
-   TypeScript / Express / PostgreSQL
-   Hexagonal Architecture (Port + Adapter)
--->
+## Session Start
 
-## Directory Structure
+Read `docs/project-state.md` first. If all state files are empty, run `bootstrap` skill.
 
-<!-- TODO: Map your directory structure.
-   Example:
-   src/
-   ├── domain/           # Entities, Repository interfaces
-   ├── application/      # Use Cases
-   ├── infrastructure/   # DB, HTTP adapters
-   ├── presentation/     # Controllers, DTOs
-   └── shared/           # Utils, types, errors
--->
+## Workflow
 
-## Core Type Rules
+- New feature → run `planner` before coding
+- Before commit → run `reviewer`
+- Bug or issue → run `investigate`
+- Session end → run `learn`
+- Direction change → run `pivot`
 
-<!-- TODO: Document type decisions that LLMs frequently get wrong.
-   Example:
-   - `ServerType` is a union type ("stdio" | "sse"), NOT an enum.
-   - `UserRole` is a union type ("admin" | "user"), NOT an enum.
--->
+## State Files
 
-## Iron Laws
-
-1. **Mock Sync**: When you modify a repository/service interface, update corresponding mocks in the same commit.
-2. **Type Check**: Before calling a constructor or factory, read the actual source file to verify parameters. Do not rely on memory.
-3. **Scope Compliance**: Do not modify files outside the current Story scope (see docs/project-state.md) without reporting first.
-4. **Security**: Never include credentials, passwords, or API keys in code or commits.
-5. **3-Failure Stop**: If the same approach fails 3 times, stop and report to the user.
-6. **Dependency Map**: When adding or modifying a module, update docs/dependency-map.md in the same commit. Register new modules, update relationship columns.
-7. **Feature Registry**: When adding a new feature, register it in docs/features.md in the same commit. Include key files and test files.
-8. **Session Handoff**: Before ending a chat session, update docs/project-state.md Quick Summary. Never leave the project in an undocumented state.
-
-## Test Rules
-
-- New feature = New test. Do not commit feature code without tests.
-- Test command: <!-- TODO: e.g. npm test, pytest, go test ./..., mvn test -->
-- Mock location: <!-- TODO: e.g. tests/__mocks__/, test/fixtures/ -->
-
-## Completion Status Protocol
-
-Report completion using one of:
-- **DONE**: All steps completed. Present evidence (test results, file list, etc).
-- **DONE_WITH_CONCERNS**: Completed but with concerns. List each concern.
-- **BLOCKED**: Cannot proceed. Describe the cause and what was tried.
-- **NEEDS_CONTEXT**: Need more information. Describe exactly what is needed.
-
-## Concreteness Rules
-
-- When modifying files, specify exact paths and line numbers.
-- 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 `docs/project-brief.md` — check Vision, Goals, Non-Goals, and Decision Log
-2. If `docs/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:
-1. `docs/project-state.md` — Quick Summary tells you where we left off
-2. `docs/features.md` — What features exist in this project
-3. `docs/failure-patterns.md` — What mistakes to avoid
-4. `docs/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.
-
-### Health Check (every session start)
-
-After reading state files, also check this file for unfilled placeholders:
-- If the `## Architecture` section still has `<!-- TODO -->` → warn: **"Core rules are incomplete. Run `bootstrap` to auto-fill."**
-- If the `## Test Rules` section still has `<!-- TODO -->` for test command → warn the same
-- If any rules file has globs that don't match the project language (e.g., `src/**/*.ts` for a Python project) → warn: **"Rules globs don't match your project language. Run `bootstrap` to fix."**
-
-Do NOT proceed with work until the user acknowledges or resolves these warnings.
-
-## 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
-
-- docs/project-brief.md — Project vision, goals, non-goals (the "why")
-- docs/features.md — Feature registry (the "what")
-- docs/project-state.md — Sprint/Story tracking, module registry (the "where")
-- docs/dependency-map.md — Module dependency graph (the "how")
-- docs/failure-patterns.md — Log of known failure patterns (the "watch out")
-- docs/agent-memory/ — Per-agent persistent memory (the "learned")
-
-## State File Size Limits
-
-State files must stay compact to fit in LLM context windows. Enforce these limits:
-- **docs/project-brief.md**: Max 200 lines. Keep Vision/Goals/Non-Goals concise.
-- **docs/project-state.md**: Max 300 lines. Archive completed sprints when exceeding limit.
-- **docs/failure-patterns.md**: Max 50 patterns. Periodically remove `Status: Resolved` entries.
-- **docs/dependency-map.md**: Max 100 modules. Merge trivial internal modules.
-- **docs/features.md**: Max 50 features. Archive shipped features when exceeding limit.
-- **docs/agent-memory/*.md**: Max 100 lines each. Keep only actionable learnings.
+- docs/project-state.md — current sprint/story and quick summary
+- docs/failure-patterns.md — known pitfalls (FP-NNN)
+- docs/dependency-map.md — module dependency graph
+- docs/features.md — feature registry
+- docs/project-brief.md — project vision, goals, and non-goals

package/harness/skills/bootstrap.md

@@ -75,55 +75,23 @@ Using data from Phase 1 + Phase 2, fill the following files:
 - Keep FP-001 through FP-004 as templates (Frequency: 0)
 - No changes unless user reports known issues
 
-### Phase 3.5: Rules Auto-Configuration
-
-Using language/framework detected in Phase 1 + user answers from Phase 2, auto-configure the project's rules files.
-
-1. **Find the core rules file** — Search for the file containing `<!-- TODO: Describe your project's architecture here -->`:
-   - VS Code: `.github/copilot-instructions.md`
-   - Claude: `CLAUDE.md`
-   - Cursor: `.cursor/rules/core.mdc`
-   - Codex: `AGENTS.md`
-   - Windsurf: `.windsurfrules`
-   - Augment: `.augment/rules/core.md`
-   - Antigravity: `.agent/rules/core.md`
-
-2. **Fill `## Architecture` section** — Replace the TODO with detected tech stack:
-   ```
-   ## Architecture
-   [Language] / [Framework] / [Database if detected]
-   [Architecture pattern from user answer #4]
-   ```
-
-3. **Fill `## Directory Structure` section** — Replace the TODO with actual tree from Phase 1:
-   ```
-   ## Directory Structure
-   project-root/
-   ├── src/           # [purpose from scan]
-   ├── tests/         # [purpose from scan]
-   └── ...
-   ```
-
-4. **Fill `## Core Type Rules` section** — Replace the TODO with user answer #5 plus language defaults:
+### Phase 3.5: Project Brief Auto-Configuration
+
+Using language/framework detected in Phase 1 + user answers from Phase 2, enrich `docs/project-brief.md`:
+
+1. **Fill Key Technical Decisions** with detected tech stack:
+   - Language, framework, database (from Phase 1)
+   - Architecture pattern (from user answer #4)
+   - Type conventions (from user answer #5)
+   - Test command and mock location (from user answer #6)
+
+2. **Add language-specific defaults** to Key Technical Decisions if not already present:
    - Python: `Use Pydantic models for API schemas, not plain dicts.`
    - TypeScript: `Prefer union types ("a" | "b") over enums.`
    - Go: `Use interfaces for dependency injection.`
    - Java: `Use records for DTOs.`
    - Rust: `Use enum variants, not string constants.`
 
-5. **Fill `## Test Rules`** — Set test command (from user answer #6) and mock location (from Phase 1):
-   ```
-   - Test command: [detected or user-provided, e.g. pytest, npm test, go test ./...]
-   - Mock location: [detected, e.g. tests/conftest.py, tests/__mocks__/]
-   ```
-
-6. **Verify globs** — Check backend and testing rules files have correct globs for the detected language:
-   - Python: backend `**/*.py`, testing `**/test_*.py,**/tests/**/*.py`
-   - TypeScript: backend `src/**/*.ts,src/**/*.js`, testing `**/*.test.*,**/*.spec.*`
-   - Go: backend `**/*.go`, testing `**/*_test.go`
-   - Java: backend `src/main/**/*.java`, testing `src/test/**/*.java`
-   - If globs don't match → **edit the file directly** to set correct globs
-
 ### Phase 4: Verify
 
 1. Present a summary of all filled state files to the user
@@ -150,12 +118,6 @@ Using language/framework detected in Phase 1 + user answers from Phase 2, auto-c
 - [x]docs/project-state.md — Sprint 1 initialized
 - [ ]docs/failure-patterns.md — templates only (no changes)
 
-### Rules Files Configured:
-- [x] Core rules — Architecture, Directory Structure, Type Rules filled
-- [x] Test command — [detected command]
-- [x] Backend globs — [globs set]
-- [x] Testing globs — [globs set]
-
 STATUS: DONE
 ```
 
@@ -168,6 +130,28 @@ STATUS: DONE
 - Rules file TODO sections can be overwritten without asking (they are placeholders)
 - Run this skill only once per project (or when explicitly requested for refresh)
 
+## Embedded Knowledge
+
+### Session Bootstrap Protocol
+When starting a NEW session (not during bootstrap), read these files in order:
+1. `docs/project-state.md` — Quick Summary tells you where we left off
+2. `docs/features.md` — What features exist
+3. `docs/failure-patterns.md` — What mistakes to avoid
+4. `docs/project-brief.md` — Project vision and non-goals
+
+### Workflow Pipeline
+- New feature: `planner → [code] → reviewer → sprint-manager → learn`
+- Bug fix: `investigate → [fix] → test-integrity → reviewer → learn`
+- Session lifecycle: `sprint-manager ("where are we?") → [work] → learn`
+
+### State File Size Limits
+- docs/project-brief.md: Max 200 lines
+- docs/project-state.md: Max 300 lines
+- docs/failure-patterns.md: Max 50 patterns
+- docs/dependency-map.md: Max 100 modules
+- docs/features.md: Max 50 features
+- docs/agent-memory/*.md: Max 100 lines each
+
 ## Anti-patterns
 
 | Anti-pattern | Correct Approach |

package/harness/skills/investigate.md

@@ -74,6 +74,12 @@ After the fix is verified (Phase 4):
 - [ ] **docs/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.
 - [ ] **docs/project-state.md**: Add the fix to Recent Changes with the root cause hypothesis.
 
+## Enforced Rules
+
+- **3-Failure Stop**: If the same fix approach fails 3 times, stop and report to the user. Do not keep trying.
+- **Concreteness**: Specify exact file paths and line numbers. Quote error messages. Specify expected vs actual types.
+- **Scope Lock**: Do not modify files outside the identified problem scope (Phase 2).
+
 ## Related Failure Patterns
 
 - FP-002: Type confusion → Phase 1 requires verifying actual types

package/harness/skills/learn.md

@@ -108,6 +108,17 @@ STATUS: DONE
 - 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
 
+## Enforced Rules
+
+- **Session Handoff**: Before ending a session, docs/project-state.md Quick Summary MUST be updated. Never leave the project in an undocumented state.
+- **State File Size Limits**: Keep state files compact for LLM context windows:
+  - docs/project-brief.md: Max 200 lines
+  - docs/project-state.md: Max 300 lines (archive completed sprints)
+  - docs/failure-patterns.md: Max 50 patterns (remove resolved entries)
+  - docs/dependency-map.md: Max 100 modules
+  - docs/features.md: Max 50 features
+  - docs/agent-memory/*.md: Max 100 lines each
+
 ## Anti-patterns
 
 | Anti-pattern | Correct Approach |

package/harness/skills/test-integrity.md

@@ -48,6 +48,15 @@ After synchronizing mocks:
 - [ ] **docs/failure-patterns.md**: If mock sync was missed and caused a test failure, increment FP-001 Frequency.
 - [ ] **docs/dependency-map.md**: If the interface change altered module relationships, update the relevant row.
 
+## Testing Rules (enforced during this skill)
+
+- Mocks must implement ALL interface methods. Missing method = build failure.
+- No `any` type casting on mocks. Create mocks using the actual interface type.
+- New methods must have default mock return values (e.g., `mockResolvedValue`, stub returns).
+- No `skip`, `only`, or debug statements in committed test files.
+- Async tests must use `await`. No floating promises.
+- Each test must be independent. No shared state between tests.
+
 ## Related Failure Patterns
 
 - FP-001: Interface changed, mock not updated → Checklist item 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "k-harness",
-  "version": "0.7.0",
+  "version": "0.8.2",
   "description": "LLM Development Harness — IDE-agnostic rules, skills, and agents that prevent common AI coding failures",
   "keywords": [
     "llm",

package/src/init.js

@@ -76,32 +76,7 @@ function detectLanguage(targetDir) {
   return 'typescript';
 }
 
-const LANG_GLOBS = {
-  typescript: {
-    backend: 'src/**/*.ts,src/**/*.js',
-    testing: '**/*.test.ts,**/*.test.js,**/*.spec.ts,**/*.spec.js,**/__mocks__/**,**/__tests__/**',
-  },
-  python: {
-    backend: '**/*.py',
-    testing: '**/test_*.py,**/tests/**/*.py,**/*_test.py,**/conftest.py',
-  },
-  go: {
-    backend: '**/*.go',
-    testing: '**/*_test.go',
-  },
-  java: {
-    backend: 'src/main/**/*.java',
-    testing: 'src/test/**/*.java',
-  },
-  rust: {
-    backend: 'src/**/*.rs',
-    testing: 'tests/**/*.rs,**/tests.rs',
-  },
-  ruby: {
-    backend: '**/*.rb',
-    testing: 'spec/**/*.rb,test/**/*.rb',
-  },
-};
+
 
 // ─── Shared writers ──────────────────────────────────────────
 
@@ -137,26 +112,11 @@ function writeAgentsAsSkills(targetDir, skillsDir, overwrite) {
 // ─── IDE Generators ──────────────────────────────────────────
 
 function generateVscode(targetDir, overwrite) {
-  const lang = detectLanguage(targetDir);
-  const globs = LANG_GLOBS[lang];
   const coreRules = readTemplate('core-rules.md');
-  const testingRules = readTemplate('testing-rules.md');
-  const backendRules = readTemplate('backend-rules.md');
 
-  // Global instructions
+  // Global instructions (dispatcher only — rules are embedded in skills)
   writeFile(targetDir, '.github/copilot-instructions.md', coreRules, overwrite);
 
-  // File-scoped instructions (add VS Code applyTo frontmatter)
-  const testingWithFrontmatter =
-    `---\napplyTo: "${globs.testing}"\n---\n\n` +
-    testingRules;
-  writeFile(targetDir, '.vscode/instructions/testing.instructions.md', testingWithFrontmatter, overwrite);
-
-  const backendWithFrontmatter =
-    `---\napplyTo: "${globs.backend}"\n---\n\n` +
-    backendRules;
-  writeFile(targetDir, '.vscode/instructions/backend.instructions.md', backendWithFrontmatter, overwrite);
-
   // Skills (.github/skills — VS Code default search path, SKILL.md with frontmatter)
   writeSkills(targetDir, '.github/skills', overwrite);
 
@@ -174,50 +134,32 @@ function generateVscode(targetDir, overwrite) {
 }
 
 function generateClaude(targetDir, overwrite) {
-  // CLAUDE.md — merge core + testing + backend rules
-  const merged = [
-    readTemplate('core-rules.md'),
-    '\n---\n\n',
-    readTemplate('testing-rules.md'),
-    '\n---\n\n',
-    readTemplate('backend-rules.md'),
-  ].join('');
-  writeFile(targetDir, 'CLAUDE.md', merged, overwrite);
+  // .claude/rules/core.md — dispatcher only (no paths = always loaded)
+  writeFile(targetDir, '.claude/rules/core.md', readTemplate('core-rules.md'), overwrite);
 
-  // Skills (SKILL.md with frontmatter for slash commands)
+  // Skills (SKILL.md with frontmatter)
   writeSkills(targetDir, '.claude/skills', overwrite);
 
+  // Agents as skills (Claude Code skills pattern)
+  writeAgentsAsSkills(targetDir, '.claude/skills', overwrite);
+
   // State files
   writeStateFiles(targetDir, overwrite);
 }
 
 function generateCursor(targetDir, overwrite) {
-  const lang = detectLanguage(targetDir);
-  const globs = LANG_GLOBS[lang];
-  // .cursor/rules/*.mdc — each needs frontmatter
+  // .cursor/rules/core.mdc — dispatcher only
   const coreRules = readTemplate('core-rules.md');
   const coreMdc =
-    '---\ndescription: Core project rules — Iron Laws, completion protocol, concreteness\nalwaysApply: true\n---\n\n' +
+    '---\ndescription: K-Harness dispatcher — workflow guidance and state file references\nalwaysApply: true\n---\n\n' +
     coreRules;
   writeFile(targetDir, '.cursor/rules/core.mdc', coreMdc, overwrite);
 
-  const testingRules = readTemplate('testing-rules.md');
-  const testingMdc =
-    `---\ndescription: Testing rules — mock sync, forbidden patterns\nglobs: "${globs.testing}"\nalwaysApply: false\n---\n\n` +
-    testingRules;
-  writeFile(targetDir, '.cursor/rules/testing.mdc', testingMdc, overwrite);
-
-  const backendRules = readTemplate('backend-rules.md');
-  const backendMdc =
-    `---\ndescription: Backend code rules — architecture enforcement, type safety\nglobs: "${globs.backend}"\nalwaysApply: false\n---\n\n` +
-    backendRules;
-  writeFile(targetDir, '.cursor/rules/backend.mdc', backendMdc, overwrite);
-
   // Skills as rules
   for (const skill of SKILLS) {
     const content = readTemplate(`skills/${skill.id}.md`);
     const mdc =
-      `---\ndescription: Skill — ${skill.id}\nalwaysApply: false\n---\n\n` +
+      `---\ndescription: ${skill.desc}\nalwaysApply: false\n---\n\n` +
       content;
     writeFile(targetDir, `.cursor/rules/${skill.id}.mdc`, mdc, overwrite);
   }
@@ -226,7 +168,7 @@ function generateCursor(targetDir, overwrite) {
   for (const agent of AGENTS) {
     const content = readTemplate(agent.file);
     const mdc =
-      `---\ndescription: Agent — ${agent.id}\nalwaysApply: false\n---\n\n` +
+      `---\ndescription: ${agent.desc}\nalwaysApply: false\n---\n\n` +
       content;
     writeFile(targetDir, `.cursor/rules/${agent.id}.mdc`, mdc, overwrite);
   }
@@ -236,15 +178,8 @@ function generateCursor(targetDir, overwrite) {
 }
 
 function generateCodex(targetDir, overwrite) {
-  // AGENTS.md — merge core + testing + backend rules
-  const merged = [
-    readTemplate('core-rules.md'),
-    '\n---\n\n',
-    readTemplate('testing-rules.md'),
-    '\n---\n\n',
-    readTemplate('backend-rules.md'),
-  ].join('');
-  writeFile(targetDir, 'AGENTS.md', merged, overwrite);
+  // AGENTS.md — dispatcher only
+  writeFile(targetDir, 'AGENTS.md', readTemplate('core-rules.md'), overwrite);
 
   // Skills (SKILL.md with frontmatter for slash commands)
   writeSkills(targetDir, '.agents/skills', overwrite);
@@ -254,48 +189,21 @@ function generateCodex(targetDir, overwrite) {
 }
 
 function generateWindsurf(targetDir, overwrite) {
-  // .windsurfrules — everything in one file
-  const sections = [
-    readTemplate('core-rules.md'),
-    readTemplate('testing-rules.md'),
-    readTemplate('backend-rules.md'),
-    '---\n\n# Skills\n\n',
-  ];
-  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);
+  // .windsurfrules — dispatcher only (rules are embedded in skills)
+  writeFile(targetDir, '.windsurfrules', readTemplate('core-rules.md'), overwrite);
 
   // State files
   writeStateFiles(targetDir, overwrite);
 }
 
 function generateAugment(targetDir, overwrite) {
-  const lang = detectLanguage(targetDir);
-  const globs = LANG_GLOBS[lang];
-  // .augment/rules/ — Always-type rules for core, testing, backend
+  // .augment/rules/core.md — dispatcher only
   const coreRules = readTemplate('core-rules.md');
   const coreRule =
-    '---\ndescription: Core project rules — Iron Laws, completion protocol, concreteness\ntype: always\n---\n\n' +
+    '---\ndescription: K-Harness dispatcher — workflow guidance and state file references\ntype: always\n---\n\n' +
     coreRules;
   writeFile(targetDir, '.augment/rules/core.md', coreRule, overwrite);
 
-  const testingRules = readTemplate('testing-rules.md');
-  const testingRule =
-    `---\ndescription: Testing rules — mock sync, forbidden patterns\ntype: auto\nglobs: "${globs.testing}"\n---\n\n` +
-    testingRules;
-  writeFile(targetDir, '.augment/rules/testing.md', testingRule, overwrite);
-
-  const backendRules = readTemplate('backend-rules.md');
-  const backendRule =
-    `---\ndescription: Backend code rules — architecture enforcement, type safety\ntype: auto\nglobs: "${globs.backend}"\n---\n\n` +
-    backendRules;
-  writeFile(targetDir, '.augment/rules/backend.md', backendRule, overwrite);
-
   // .augment/skills/ — SKILL.md format (enables / slash commands)
   writeSkills(targetDir, '.augment/skills', overwrite);
   writeAgentsAsSkills(targetDir, '.augment/skills', overwrite);
@@ -305,27 +213,13 @@ function generateAugment(targetDir, overwrite) {
 }
 
 function generateAntigravity(targetDir, overwrite) {
-  const lang = detectLanguage(targetDir);
-  const globs = LANG_GLOBS[lang];
-  // .agent/rules/ — Always-type rules (same as Augment format, read by Antigravity)
+  // .agent/rules/core.md — dispatcher only
   const coreRules = readTemplate('core-rules.md');
   const coreRule =
-    '---\ndescription: Core project rules — Iron Laws, completion protocol, concreteness\ntype: always\n---\n\n' +
+    '---\ndescription: K-Harness dispatcher — workflow guidance and state file references\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: "${globs.testing}"\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: "${globs.backend}"\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);
@@ -437,4 +331,4 @@ async function run(argv) {
   }
 }
 
-module.exports = { run, detectLanguage, LANG_GLOBS };
+module.exports = { run, detectLanguage };

package/harness/backend-rules.md

@@ -1,24 +0,0 @@
-# Backend Code Rules
-
-## Required
-
-- 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.
-  - 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
-
-- 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
-
-- docs/failure-patterns.md FP-002: Type confusion
-- docs/failure-patterns.md FP-004: Unnecessary files committed

package/harness/testing-rules.md

@@ -1,21 +0,0 @@
-# Testing Rules
-
-## Required
-
-- When interface changes, update corresponding mocks in the same commit (FP-001).
-- Mocks must implement ALL interface methods. Missing method = build failure.
-- Do not use real credentials in test data. Use fixtures or fakers.
-- Async tests must use `await`. No floating promises.
-- Each test must be independent. No shared state between tests.
-
-## Forbidden
-
-- Casting mocks with `any` type. Create mocks using the actual interface type.
-- 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 debugging statements (e.g. `console.log`, `print`, `println`).
-
-## References
-
-- test-integrity skill
-- docs/failure-patterns.md FP-001: Mock not updated