k-harness 0.5.0 → 0.7.0

package/README.md

@@ -59,7 +59,7 @@ npx k-harness init --ide antigravity
 | **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`, `project-brief.md`, `features.md`, `failure-patterns.md`, and `dependency-map.md` at the project root.
+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
 
@@ -125,7 +125,7 @@ See [docs/reference.md](docs/reference.md) for detailed descriptions of every sk
 | | 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 |
+| 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) |

package/harness/agents/planner.md

@@ -42,9 +42,9 @@ If `docs/project-brief.md` alone is empty → Warn the user but proceed (the pla
 
 1. Read `docs/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.
+   - **Goal Alignment**: Does it serve a listed Goal? If no clear link → **warn but proceed**. Include the warning in the plan output.
+   - **Non-Goal Violation**: Does it fall into Non-Goals? If yes → **stop and ask the user**. Do not proceed until the user confirms this is intentional (may need `pivot` skill).
+   - **Decision Consistency**: Does it contradict any Decision Log entry? If yes → **stop and warn**. 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 `docs/features.md` to understand what already exists
 4. Read `docs/dependency-map.md` to understand current architecture

package/harness/agents/reviewer.md

@@ -75,6 +75,7 @@ Verify that state file updates actually happened. Check each:
 - [ ] **docs/dependency-map.md**: If new modules were created, are they registered? If dependencies changed, are relationships updated?
 - [ ] **docs/failure-patterns.md**: If a bug was fixed that matched a pattern, was frequency incremented?
 - [ ] **docs/project-brief.md**: If a technology or architectural decision was made, is it in Decision Log?
+- [ ] **docs/agent-memory/*.md**: If an agent (reviewer/planner/sprint-manager) was used this session, was its memory updated by the learn skill?
 
 For each missing update: flag as `[STATE-AUDIT]` in the output and provide the exact update that should be made.
 

package/harness/core-rules.md

@@ -81,6 +81,15 @@ When starting a NEW chat session, read these files in order before doing any wor
 
 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.

package/harness/failure-patterns.md

@@ -14,6 +14,12 @@ Keep resolved patterns for regression prevention.
 - **Applied in**: testing rules, test-integrity skill, reviewer agent
 - **Status**: Template — activate when first occurrence is logged
 
+<!-- Activation example: When this pattern first occurs, update like this:
+- **Occurred**: S1-2
+- **Frequency**: 1
+- **Status**: Active
+On subsequent occurrences, increment Frequency and append to Occurred (e.g., S1-2, S2-1) -->
+
 ---
 
 ## FP-002: Type confusion (enum vs union, wrong parameter count)

package/harness/skills/bootstrap.md

@@ -2,8 +2,9 @@
 
 ## Purpose
 
-Onboard a new or existing project into K-Harness by filling state files automatically.
+Onboard a new or existing project into K-Harness by filling **state files AND rules files** automatically.
 Solves the cold-start problem: users don't know which `.md` files to fill or how.
+One command does everything — no manual editing required.
 
 ## When to Apply
 
@@ -41,6 +42,7 @@ Ask the user these questions (skip any already answered by Phase 1):
 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?"
+6. "What is your test command?" (show detected command if found, e.g., `npm test`, `pytest`, `go test ./...`)
 
 ### Phase 3: Fill State Files
 
@@ -73,6 +75,55 @@ 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:
+   - 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
@@ -87,6 +138,7 @@ Using data from Phase 1 + Phase 2, fill the following files:
 
 ### Project: [name]
 ### Tech Stack: [detected stack]
+### Language: [detected language]
 ### Modules Found: [count]
 ### Features Mapped: [count]
 ### Dependency Links: [count]
@@ -98,15 +150,22 @@ Using data from Phase 1 + Phase 2, fill the following files:
 - [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
 ```
 
 ## Rules
 
-- Never modify source code — this skill only writes to state files
+- Never modify source code — this skill only writes to state files and rules 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
+- 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)
 
 ## Anti-patterns
@@ -117,3 +176,6 @@ STATUS: DONE
 | 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 |
+| Leave rules file TODOs unfilled | Phase 3.5 fills ALL TODO sections — no manual editing needed |
+| Use TypeScript globs for non-TS projects | Detect language in Phase 1 and set correct globs |
+| Only fill state files, skip rules | Bootstrap fills BOTH — state files AND rules files |

package/harness/skills/impact-analysis.md

@@ -61,7 +61,7 @@ Plan: 4 files to update, all within S3-2 scope
 
 After completing the analysis, update these files:
 
-- [ ] **docs/dependency-map.md**: Update the Interface Change Log table with: Date, Module, Change description, Affected Modules, Status.
+- [ ] **docs/dependency-map.md**: Update the Interface Change Log table with: Date, Module, Change description, Affected Modules, Status. **This is mandatory for ALL interface changes** — do not skip even if the change seems minor.
 - [ ] **docs/project-state.md**: If scope exceeds current Story, add a note to Recent Changes.
 
 ## Related Failure Patterns

package/harness/skills/learn.md

@@ -8,11 +8,13 @@ This is K-Harness's memory mechanism — without it, the same mistakes repeat ac
 
 ## When to Apply
 
-- Before ending a chat session (recommended as the LAST skill invoked)
+- Before ending a chat session (recommended as the LAST skill invoked, **once per session**)
 - 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
 
+> **Timing**: Invoke this skill **once at session end**, not after each individual skill. It aggregates the entire session's work into state files.
+
 ## Procedure
 
 ### Step 1: Review Session Activity
@@ -63,7 +65,10 @@ For each issue/error that occurred in this session:
 If an agent (reviewer, planner, sprint-manager) was used in this session, update its memory file in `docs/agent-memory/`:
 
 1. Read `docs/agent-memory/{agent-name}.md`
-2. Add session-specific learnings to the appropriate section:
+2. If the file only contains placeholder comments (`<!-- 예시:... -->`), initialize it by replacing the comments with actual entries. Example:
+   - Before: `<!-- 예시: Wave 1 추정: 정확 -->`
+   - After: `- [S1-2] Wave 1 추정: 정확 (3 tasks, 실제 소요 1일)`
+3. Add session-specific learnings to the appropriate section:
    - **reviewer.md**: Review patterns, frequently missed items, statistics
    - **planner.md**: Estimation accuracy, architecture insights, repeated patterns
    - **sprint-manager.md**: Velocity data, scope drift incidents, sizing recommendations

package/package.json

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

package/src/init.js

@@ -59,6 +59,50 @@ const AGENT_MEMORY_FILES = [
 
 const STATE_DEST_DIR = 'docs';
 
+// ─── Language detection ──────────────────────────────────────
+function detectLanguage(targetDir) {
+  const markers = [
+    ['python', ['requirements.txt', 'pyproject.toml', 'setup.py', 'Pipfile', 'setup.cfg']],
+    ['go', ['go.mod']],
+    ['java', ['pom.xml', 'build.gradle', 'build.gradle.kts']],
+    ['rust', ['Cargo.toml']],
+    ['ruby', ['Gemfile']],
+  ];
+  for (const [lang, files] of markers) {
+    for (const f of files) {
+      if (fs.existsSync(path.join(targetDir, f))) return lang;
+    }
+  }
+  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 ──────────────────────────────────────────
 
 function writeStateFiles(targetDir, overwrite) {
@@ -93,6 +137,8 @@ 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');
@@ -102,12 +148,12 @@ function generateVscode(targetDir, overwrite) {
 
   // File-scoped instructions (add VS Code applyTo frontmatter)
   const testingWithFrontmatter =
-    '---\napplyTo: "**/*.test.ts,**/*.test.js,**/*.spec.ts,**/*.spec.js,**/__mocks__/**,**/__tests__/**"\n---\n\n' +
+    `---\napplyTo: "${globs.testing}"\n---\n\n` +
     testingRules;
   writeFile(targetDir, '.vscode/instructions/testing.instructions.md', testingWithFrontmatter, overwrite);
 
   const backendWithFrontmatter =
-    '---\napplyTo: "src/**/*.ts,src/**/*.js"\n---\n\n' +
+    `---\napplyTo: "${globs.backend}"\n---\n\n` +
     backendRules;
   writeFile(targetDir, '.vscode/instructions/backend.instructions.md', backendWithFrontmatter, overwrite);
 
@@ -146,6 +192,8 @@ function generateClaude(targetDir, overwrite) {
 }
 
 function generateCursor(targetDir, overwrite) {
+  const lang = detectLanguage(targetDir);
+  const globs = LANG_GLOBS[lang];
   // .cursor/rules/*.mdc — each needs frontmatter
   const coreRules = readTemplate('core-rules.md');
   const coreMdc =
@@ -155,13 +203,13 @@ function generateCursor(targetDir, overwrite) {
 
   const testingRules = readTemplate('testing-rules.md');
   const testingMdc =
-    '---\ndescription: Testing rules — mock sync, forbidden patterns\nglobs: "**/*.test.*,**/*.spec.*,**/__mocks__/**,**/__tests__/**"\nalwaysApply: false\n---\n\n' +
+    `---\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: "src/**/*.ts,src/**/*.js"\nalwaysApply: false\n---\n\n' +
+    `---\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);
 
@@ -227,6 +275,8 @@ function generateWindsurf(targetDir, overwrite) {
 }
 
 function generateAugment(targetDir, overwrite) {
+  const lang = detectLanguage(targetDir);
+  const globs = LANG_GLOBS[lang];
   // .augment/rules/ — Always-type rules for core, testing, backend
   const coreRules = readTemplate('core-rules.md');
   const coreRule =
@@ -236,13 +286,13 @@ function generateAugment(targetDir, 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' +
+    `---\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: "src/**/*.ts,src/**/*.js"\n---\n\n' +
+    `---\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);
 
@@ -255,6 +305,8 @@ 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)
   const coreRules = readTemplate('core-rules.md');
   const coreRule =
@@ -264,13 +316,13 @@ function generateAntigravity(targetDir, 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' +
+    `---\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: "src/**/*.ts,src/**/*.js"\n---\n\n' +
+    `---\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);
 
@@ -378,10 +430,11 @@ async function run(argv) {
     }
 
     const gen = GENERATORS[ide];
-    console.log(`\n  Installing for ${gen.name}...\n`);
+    const lang = detectLanguage(args.dir);
+    console.log(`\n  Installing for ${gen.name}... (detected language: ${lang})\n`);
     gen.fn(args.dir, args.overwrite);
-    console.log(`\n  Done! Edit docs/project-state.md to set up your first sprint.\n`);
+    console.log(`\n  Done! Run "bootstrap" in your AI chat to auto-fill state files and rules.\n`);
   }
 }
 
-module.exports = { run };
+module.exports = { run, detectLanguage, LANG_GLOBS };