k-harness 0.4.0 → 0.5.0

package/README.md

@@ -21,6 +21,12 @@ npx k-harness init
 
 Select your IDE when prompted. Files are installed into the current directory.
 
+After installation, ask your LLM to run the `bootstrap` skill:
+
+> "Run bootstrap to onboard this project."
+
+This scans your codebase and fills all 5 state files automatically.
+
 ### Non-interactive
 
 ```bash
@@ -87,10 +93,7 @@ All IDEs also get `project-state.md`, `project-brief.md`, `features.md`, `failur
 ## How It Works
 
 ### 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.
+After `k-harness init`, run the `bootstrap` skill. It scans your codebase, interviews you about goals/non-goals, and fills all 5 state files automatically. **This is the most important step** — without it, Direction Guard and other skills have no context.
 
 ### 2. Direction Guard (every request)
 Before ANY coding task, the LLM reads `project-brief.md` and checks:
@@ -113,14 +116,9 @@ When goals, technology, or scope changes, run the `pivot` skill:
 - Records the decision with reasoning in Decision Log
 - Prevents silent inconsistencies across files
 
-## Design Principles
+## Documentation
 
-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`
+See [docs/reference.md](docs/reference.md) for detailed descriptions of every skill, agent, rule, and state file.
 
 ## Why Not BMAD or gstack?
 
@@ -135,8 +133,6 @@ When goals, technology, or scope changes, run the `pivot` skill:
 | 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
 
 MIT

package/harness/agent-memory/planner.md

@@ -0,0 +1,25 @@
+# Planner Memory
+
+> 이 파일은 planner 에이전트가 세션 간 학습 내용을 유지하기 위해 자동 업데이트합니다.
+> learn 스킬이 세션 종료 시 갱신합니다. 직접 편집하지 마세요.
+
+## 추정 정확도
+
+<!-- 예시:
+- Wave 1 추정: 정확 (실제 소요시간과 일치)
+- Wave 3+ 추정: 낙관적 경향 — 실제로 2배 소요
+-->
+
+## 프로젝트 아키텍처 인사이트
+
+<!-- 예시:
+- 이 프로젝트는 domain → application → infrastructure 순으로 의존
+- shared/ 폴더 변경 시 전체 리빌드 필요
+-->
+
+## 반복 패턴
+
+<!-- 예시:
+- 새 기능 추가 시 항상 middleware + route + controller + service 4파일 세트
+- DB 마이그레이션 파일 생성을 빠뜨리는 경향
+-->

package/harness/agent-memory/reviewer.md

@@ -0,0 +1,24 @@
+# Reviewer Memory
+
+> 이 파일은 reviewer 에이전트가 세션 간 학습 내용을 유지하기 위해 자동 업데이트합니다.
+> learn 스킬이 세션 종료 시 갱신합니다. 직접 편집하지 마세요.
+
+## 프로젝트별 리뷰 패턴
+
+<!-- 예시:
+- SQL injection 패턴이 빈번 — req.params를 직접 쿼리에 넣는 코드가 반복됨
+- mock sync 누락률 높음 — interface 변경 시 50%가 mock 미동기화
+-->
+
+## 자주 놓치는 항목
+
+<!-- 예시:
+- docs/features.md 업데이트 누락 (Iron Law #7)
+- 테스트 파일에 실제 DB 연결하는 코드
+-->
+
+## 리뷰 통계
+
+- 총 리뷰 횟수: 0
+- 자동 수정 건수: 0
+- 에스컬레이션 건수: 0

package/harness/agent-memory/sprint-manager.md

@@ -0,0 +1,26 @@
+# Sprint Manager Memory
+
+> 이 파일은 sprint-manager 에이전트가 세션 간 학습 내용을 유지하기 위해 자동 업데이트합니다.
+> learn 스킬이 세션 종료 시 갱신합니다. 직접 편집하지 마세요.
+
+## Velocity 추적
+
+<!-- 예시:
+- Sprint 1: 3 stories 완료 / 5 stories 계획 (60%)
+- Sprint 2: 4 stories 완료 / 4 stories 계획 (100%)
+- 평균 velocity: 스프린트당 3.5 stories
+-->
+
+## 스코프 드리프트 이력
+
+<!-- 예시:
+- S1-003에서 스코프 밖 파일 3개 수정 발생 — 사전 경고 부족
+- S2-001에서 방향 전환 요청 → pivot 스킬로 전환
+-->
+
+## 추천 패턴
+
+<!-- 예시:
+- 이 프로젝트는 스프린트당 4 stories가 적절
+- Story 크기가 5파일 이상이면 분할 권장
+-->

package/harness/agents/planner.md

@@ -13,11 +13,11 @@ The Planner is the entry point for new features — use it BEFORE writing code.
 
 ## Referenced Files
 
-- project-brief.md — Project vision, goals, and non-goals
-- features.md — Feature registry
-- dependency-map.md
-- project-state.md
-- failure-patterns.md
+- docs/project-brief.md — Project vision, goals, and non-goals
+- docs/features.md — Feature registry
+- docs/dependency-map.md
+- docs/project-state.md
+- docs/failure-patterns.md
 
 ## Input
 
@@ -31,42 +31,42 @@ One of:
 ### 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)
+- `docs/project-brief.md` — Must have Vision and Goals filled
+- `docs/features.md` — Must have at least one feature row
+- `docs/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).
+If `docs/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, **non-goals**, and **Decision Log**
+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.
    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
+3. Read `docs/features.md` to understand what already exists
+4. Read `docs/dependency-map.md` to understand current architecture
+5. Read `docs/project-state.md` for current Sprint context
 6. Identify which existing modules are affected
 7. Identify new modules that need to be created
 8. Run **feature-breakdown** skill to create ordered task list
 9. Run **impact-analysis** skill for each existing module being modified
-10. Check `failure-patterns.md` for relevant past mistakes
+10. Check `docs/failure-patterns.md` for relevant past mistakes
 11. Produce implementation plan (see Output Format)
-12. Update `project-state.md` with the new Story
-13. Update `features.md` with the new feature entry
+12. Update `docs/project-state.md` with the new Story
+13. Update `docs/features.md` with the new feature entry
 
 ### For Architecture Query
 
-1. Read `dependency-map.md`
+1. Read `docs/dependency-map.md`
 2. Answer the query with specific module names, dependencies, and layer info
 3. If the query reveals missing entries in the map, flag them
 
 ### For Refactor Plan
 
-1. Read `dependency-map.md` to map the blast radius
+1. Read `docs/dependency-map.md` to map the blast radius
 2. Run **impact-analysis** skill on each module being refactored
 3. Identify safe refactoring order (leaf modules first, core modules last)
 4. Produce refactoring plan with rollback checkpoints
@@ -93,7 +93,7 @@ If `project-brief.md` alone is empty → Warn the user but proceed (the plan wil
 - [Any high-coupling areas to watch]
 
 ### Dependency Map Changes
-[Additions/modifications to dependency-map.md]
+[Additions/modifications to docs/dependency-map.md]
 ```
 
 ### Architecture Query Response
@@ -107,8 +107,8 @@ If `project-brief.md` alone is empty → Warn the user but proceed (the plan wil
 
 ## Constraints
 
-- Never skip reading dependency-map.md — the plan is only as good as the map
-- If dependency-map.md is empty or outdated, report this FIRST
+- Never skip reading docs/dependency-map.md — the plan is only as good as the map
+- If docs/dependency-map.md is empty or outdated, report this FIRST
 - All plans must include test tasks (no code without tests)
 - If a feature affects 5+ modules, flag as High Risk
 - If the plan exceeds one Sprint's worth of work, suggest splitting into sub-features

package/harness/agents/reviewer.md

@@ -13,17 +13,17 @@ Finds issues and auto-fixes where safe, escalates where not.
 
 ## Referenced Files
 
-- failure-patterns.md — Project failure patterns
-- project-state.md — Current Story scope
-- dependency-map.md — Module dependency graph
+- docs/failure-patterns.md — Project failure patterns
+- docs/project-state.md — Current Story scope
+- docs/dependency-map.md — Module dependency graph
 
 ## 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)
+- `docs/failure-patterns.md` — Must exist (needed for Step 5 cross-check)
+- `docs/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."
 
@@ -35,7 +35,7 @@ Changed file list (user-provided or from `git diff --name-only`)
 
 **Step 1: Identify Change Scope**
 - Run `git diff --cached --stat` or `git diff --stat` to see changed files
-- Compare against current Story scope in project-state.md
+- Compare against current Story scope in docs/project-state.md
 
 **Step 2: Architecture Rule Check**
 - [ ] No imports from infrastructure in domain layer
@@ -53,28 +53,28 @@ Changed file list (user-provided or from `git diff --name-only`)
 - [ ] No injection vulnerabilities (SQL, XSS)
 
 **Step 5: Failure Pattern Cross-Check**
-- Compare current changes against all FP-NNN items in failure-patterns.md
+- Compare current changes against all FP-NNN items in docs/failure-patterns.md
 - Warn if any pattern applies
 
 **Step 6: Feature Registry Check**
-- [ ] If a new feature was added, verify it is registered in features.md (Iron Law #7)
-- [ ] If feature files changed, verify features.md key files are up to date
-- [ ] If tests were added/removed, verify features.md test files column is accurate
+- [ ] If a new feature was added, verify it is registered in docs/features.md (Iron Law #7)
+- [ ] If feature files changed, verify docs/features.md key files are up to date
+- [ ] If tests were added/removed, verify docs/features.md test files column is accurate
 
 **Step 7: Dependency Map Check**
-- [ ] If new modules were added, verify they are registered in dependency-map.md (Iron Law #6)
+- [ ] If new modules were added, verify they are registered in docs/dependency-map.md (Iron Law #6)
 - [ ] If module interfaces changed, verify "Depends On" / "Depended By" columns are updated
-- [ ] If module was deleted/renamed, verify dependency-map.md is cleaned up
+- [ ] If module was deleted/renamed, verify docs/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?
+- [ ] **docs/project-state.md**: If stories were worked on, is Quick Summary current? Are story statuses updated?
+- [ ] **docs/features.md**: If new features were added, are they registered? If features were completed, is status updated?
+- [ ] **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?
 
 For each missing update: flag as `[STATE-AUDIT]` in the output and provide the exact update that should be made.
 

package/harness/agents/sprint-manager.md

@@ -7,18 +7,18 @@ Keeps the LLM focused on the current work item.
 
 ## Referenced Files
 
-- project-state.md — Current state (this is the core file)
-- failure-patterns.md — Recurring failure tracking
+- docs/project-state.md — Current state (this is the core file)
+- docs/failure-patterns.md — Recurring failure tracking
 
 ## Procedure
 
 ### Step 0: State File Readiness
 
-Before handling any request, verify `project-state.md` has content:
+Before handling any request, verify `docs/project-state.md` has content:
 - Quick Summary must not be all TODO placeholders
 - Story Status table must have at least one row
 
-If `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."
+If `docs/project-state.md` is empty/placeholder-only → **Recommend running `bootstrap` skill first.** Report: docs/project-state.md is empty. Run bootstrap to initialize project state before tracking sprints."
 
 ### Input
 
@@ -27,7 +27,7 @@ User request: "next task", "current status", "story done", "new sprint", "scope
 ### Handlers
 
 **Request: "current status" / "where are we"**
-1. Read project-state.md
+1. Read docs/project-state.md
 2. Summarize: current Sprint, in-progress Story, completed Stories
 3. Run **Next Step Recommendation** (see below)
 
@@ -35,13 +35,13 @@ User request: "next task", "current status", "story done", "new sprint", "scope
 
 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`
+1. Read `docs/project-state.md`, `docs/features.md`, `docs/project-brief.md`, `docs/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" |
+|docs/project-brief.md has no Vision/Goals | → "Fill out docs/project-brief.md — this is critical for direction" |
 | No stories exist | → "Run `planner` to break down your first feature" |
 | 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" |
@@ -56,21 +56,21 @@ After every status check, recommend the next action based on current context:
 ```
 
 **Request: "story done" / "S{N}-{M} done"**
-1. Update the Story status to `done` in project-state.md
+1. Update the Story status to `done` in docs/project-state.md
 2. Add completion record to "Recent Changes" section
 3. Guide to next Story if available
 
 **Request: "new story" / "next task"**
-1. Find next `todo` Story in project-state.md
+1. Find next `todo` Story in docs/project-state.md
 2. Change its status to `in-progress`
 3. Specify Story scope (related files/directories)
-4. Alert relevant failure-patterns.md items
+4. Alert relevant docs/failure-patterns.md items
 
 **Request: "new sprint"**
 1. Check all Stories in current Sprint
 2. Warn if incomplete Stories exist
 3. Confirm new Sprint number and theme (user input)
-4. Update project-state.md
+4. Update docs/project-state.md
 
 **Scope Check (automatic)**
 - If user requests a file modification outside current Story scope:
@@ -101,5 +101,5 @@ STATUS: DONE
 ## Constraints
 
 - Do not modify code directly — manage state only
-- Only write to project-state.md; read-only for all other files
+- Only write to docs/project-state.md; read-only for all other files
 - Always confirm with user before modifying scope boundaries

package/harness/backend-rules.md

@@ -20,5 +20,5 @@
 
 ## References
 
-- failure-patterns.md FP-002: Type confusion
-- failure-patterns.md FP-004: Unnecessary files committed
+- docs/failure-patterns.md FP-002: Type confusion
+- docs/failure-patterns.md FP-004: Unnecessary files committed

package/harness/core-rules.md

@@ -32,12 +32,12 @@
 
 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 project-state.md) without reporting first.
+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 dependency-map.md in the same commit. Register new modules, update relationship columns.
-7. **Feature Registry**: When adding a new feature, register it in features.md in the same commit. Include key files and test files.
-8. **Session Handoff**: Before ending a chat session, update project-state.md Quick Summary. Never leave the project in an undocumented state.
+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
 
@@ -63,8 +63,8 @@ Report completion using one of:
 
 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
+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
@@ -74,10 +74,10 @@ This applies to EVERY request, not just new sessions. Skip only for trivial ques
 ## New Session Bootstrap
 
 When starting a NEW chat session, read these files in order before doing any work:
-1. `project-state.md` — Quick Summary tells you where we left off
-2. `features.md` — What features exist in this project
-3. `failure-patterns.md` — What mistakes to avoid
-4. `project-brief.md` — Project vision, goals, and non-goals
+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.
 
@@ -108,8 +108,19 @@ investigate → [fix] → test-integrity → reviewer → learn
 
 ## References
 
-- project-brief.md — Project vision, goals, non-goals (the "why")
-- features.md — Feature registry (the "what")
-- project-state.md — Sprint/Story tracking, module registry (the "where")
-- dependency-map.md — Module dependency graph (the "how")
-- failure-patterns.md — Log of known failure patterns (the "watch out")
+- 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.

package/harness/dependency-map.md

@@ -29,7 +29,7 @@ When modifying a module:
 3. For each dependent module:
    - Check if the change affects the public interface
    - Update tests and mocks for all affected dependents
-4. Record the change in project-state.md
+4. Record the change in docs/project-state.md
 
 ## Interface Change Log
 

package/harness/failure-patterns.md

@@ -32,7 +32,7 @@ Keep resolved patterns for regression prevention.
 - **Occurred**: <!-- Sprint/Story where this happened -->
 - **Frequency**: 0
 - **Cause**: LLM lost track of current scope in large workflows. Skipped "report and wait for approval" steps.
-- **Prevention**: Track current Story in project-state.md. Sprint manager agent detects scope violations.
+- **Prevention**: Track current Story in docs/project-state.md. Sprint manager agent detects scope violations.
 - **Applied in**: sprint-manager agent, global instructions
 - **Status**: Template — activate when first occurrence is logged
 

package/harness/project-state.md

@@ -25,7 +25,7 @@
 
 ## Module Registry
 
-<!-- Summary of current modules. Full details in dependency-map.md -->
+<!-- Summary of current modules. Full details in docs/dependency-map.md -->
 | Module | Layer | Status |
 |--------|-------|--------|
 <!-- Fill as modules are created -->
@@ -45,11 +45,11 @@
 Before ending a chat session, you MUST:
 1. Update the **Quick Summary** section above (3 lines)
 2. Update **Story Status** table with current progress
-3. Add any new failure patterns to `failure-patterns.md`
-4. Update `features.md` if any features were added/changed
+3. Add any new failure patterns to `docs/failure-patterns.md`
+4. Update `docs/features.md` if any features were added/changed
 
 When starting a new chat session, read these files first:
-1. `project-state.md` (this file) — where we are
-2. `features.md` — what exists
-3. `failure-patterns.md` — what to watch out for
-4. `project-brief.md` — why we're building this
+1. `docs/project-state.md` (this file) — where we are
+2. `docs/features.md` — what exists
+3. `docs/failure-patterns.md` — what to watch out for
+4. `docs/project-brief.md` — why we're building this

package/harness/skills/bootstrap.md

@@ -46,30 +46,30 @@ Ask the user these questions (skip any already answered by Phase 1):
 
 Using data from Phase 1 + Phase 2, fill the following files:
 
-**project-brief.md**:
+**docs/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**:
+**docs/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**:
+**docs/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**:
+**docs/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
+- Module Registry: summary from docs/dependency-map.md
 
-**failure-patterns.md**:
+**docs/failure-patterns.md**:
 - Keep FP-001 through FP-004 as templates (Frequency: 0)
 - No changes unless user reports known issues
 
@@ -92,11 +92,11 @@ Using data from Phase 1 + Phase 2, fill the following files:
 ### 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)
+- [x]docs/project-brief.md — [summary]
+- [x]docs/features.md — [N] features registered
+- [x]docs/dependency-map.md — [N] modules, [N] dependencies
+- [x]docs/project-state.md — Sprint 1 initialized
+- [ ]docs/failure-patterns.md — templates only (no changes)
 
 STATUS: DONE
 ```

package/harness/skills/feature-breakdown.md

@@ -15,7 +15,7 @@ Ensures bottom-up implementation: foundations first, then layers that depend on
 ## Procedure
 
 1. **Describe the feature** in one sentence
-2. **Read dependency-map.md** to understand current module relationships
+2. **Read docs/dependency-map.md** to understand current module relationships
 3. **Identify affected modules**: List every module that needs changes
 4. **Classify changes per module**:
    - NEW_MODULE: Entirely new module to create
@@ -58,7 +58,7 @@ Ensures bottom-up implementation: foundations first, then layers that depend on
   - Depends on: Task 2
 
 ### Dependency Map Updates
-- [ ] Register Module A in dependency-map.md
+- [ ] Register Module A in docs/dependency-map.md
 - [ ] Update Module B's "Depends On" column
 ```
 
@@ -67,16 +67,16 @@ Ensures bottom-up implementation: foundations first, then layers that depend on
 - Never implement a module before its dependencies exist
 - Each task should be completable in one session
 - Every task must include its test files
-- New modules MUST be registered in dependency-map.md (Iron Law #6)
+- New modules MUST be registered in docs/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.
+- [ ] **docs/dependency-map.md**: Register all NEW_MODULE entries. Update "Depends On" / "Depended By" for INTERFACE_CHANGE entries.
+- [ ] **docs/features.md**: Add a new row for the feature with Status `🔧 active`, Key Files from Wave tasks, and Test Files.
+- [ ] **docs/project-state.md**: Add Stories to the Story Status table for each Wave.
 
 ## Anti-patterns
 

package/harness/skills/impact-analysis.md

@@ -15,7 +15,7 @@ The most common cause of regressions in growing projects is changing one module
 ## Procedure
 
 1. **Identify the target module**: Which module are you about to change?
-2. **Read dependency-map.md**: Find the target module's row
+2. **Read docs/dependency-map.md**: Find the target module's row
 3. **List dependents**: Read the "Depended By" column — these are the blast radius
 4. **Check interface impact**: Does your change affect the module's public interface?
    - If NO (internal-only change) → proceed, but still run dependent tests
@@ -25,11 +25,11 @@ The most common cause of regressions in growing projects is changing one module
    - Identify which functions/types they use
    - Determine if the interface change breaks them
 6. **Plan updates**: Create a task list of all files that need modification
-7. **Verify scope**: Confirm all files are within the current Story scope (project-state.md)
+7. **Verify scope**: Confirm all files are within the current Story scope docs/project-state.md)
 
 ## Checklist
 
-- [ ] Target module identified in dependency-map.md
+- [ ] Target module identified in docs/dependency-map.md
 - [ ] All dependent modules listed
 - [ ] Interface vs internal change classified
 - [ ] Files importing from target module enumerated
@@ -61,8 +61,8 @@ Plan: 4 files to update, all within S3-2 scope
 
 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.
+- [ ] **docs/dependency-map.md**: Update the Interface Change Log table with: Date, Module, Change description, Affected Modules, Status.
+- [ ] **docs/project-state.md**: If scope exceeds current Story, add a note to Recent Changes.
 
 ## Related Failure Patterns
 

package/harness/skills/investigate.md

@@ -27,7 +27,7 @@ Debug bugs systematically. Prevent "symptom patching" — fixing without underst
 
 1. Identify the module/directory containing the root cause
 2. Exclude files outside that scope from modification
-3. Check failure-patterns.md for matching patterns
+3. Check docs/failure-patterns.md for matching patterns
 
 ### Phase 3: Hypothesis + Fix
 
@@ -39,7 +39,7 @@ Debug bugs systematically. Prevent "symptom patching" — fixing without underst
 
 1. Run all related tests after the fix
 2. Add a regression test (prevent the same bug from recurring)
-3. Decide if the pattern should be recorded in failure-patterns.md
+3. Decide if the pattern should be recorded in docs/failure-patterns.md
 
 ## Checklist
 
@@ -71,8 +71,8 @@ Phase 4: Tests pass, null case test added
 
 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.
+- [ ] **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.
 
 ## Related Failure Patterns
 

package/harness/skills/learn.md

@@ -3,7 +3,7 @@
 ## Purpose
 
 Capture lessons from the current session before ending.
-Updates failure-patterns.md with new patterns and refreshes project-state.md Quick Summary.
+Updates docs/failure-patterns.md with new patterns and refreshes docs/project-state.md Quick Summary.
 This is K-Harness's memory mechanism — without it, the same mistakes repeat across sessions.
 
 ## When to Apply
@@ -25,7 +25,7 @@ This is K-Harness's memory mechanism — without it, the same mistakes repeat ac
 
 For each issue/error that occurred in this session:
 
-1. Read `failure-patterns.md`
+1. Read `docs/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:
@@ -43,7 +43,7 @@ For each issue/error that occurred in this session:
 
 3. If the failure relates to a specific skill or agent, note it for that skill's checklist
 
-### Step 3: Update project-state.md
+### Step 3: Update docs/project-state.md
 
 1. Update **Quick Summary** (3 lines):
    - Line 1: What was accomplished in this session
@@ -52,13 +52,25 @@ For each issue/error that occurred in this session:
 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)
+### Step 4: Update docs/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
+### Step 5: Update Agent Memory (if applicable)
+
+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:
+   - **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
+3. Keep entries concise — one line per learning
+4. If no agent was used in this session, skip this step
+
+### Step 6: Report
 
 Present a summary of all updates made.
 
@@ -71,9 +83,10 @@ Present a summary of all updates made.
 - [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)
+- [x]docs/project-state.md — Quick Summary refreshed
+- [x]docs/failure-patterns.md — [N] patterns added/updated
+- [x]docs/features.md — [N] features updated (if applicable)
+- [x] docs/agent-memory/{name}.md — [N] agents updated (if applicable)
 
 ### Next Session Should:
 1. [recommended first action]
@@ -97,4 +110,4 @@ STATUS: DONE
 | 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 |
+| Update docs/failure-patterns.md but not docs/project-state.md | Always update both — they serve different purposes |

package/harness/skills/pivot.md

@@ -3,7 +3,7 @@
 ## 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.
+Without this, direction changes create silent inconsistencies:docs/project-brief.md says "GraphQL" but docs/dependency-map.md still references REST modules.
 
 ## When to Apply
 
@@ -28,29 +28,29 @@ Without this, direction changes create silent inconsistencies: project-brief.md
 
 Read ALL state files and identify what needs updating:
 
-1. **project-brief.md**:
+1. **docs/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**:
+2. **docs/features.md**:
    - Which existing features are affected?
    - Which features should be marked `⛔ dropped`?
    - Are new features needed?
 
-3. **dependency-map.md**:
+3. **docs/dependency-map.md**:
    - Which modules are obsoleted by this change?
    - Which new modules are needed?
    - Which dependency relationships change?
 
-4. **project-state.md**:
+4. **docs/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**:
+5. **docs/failure-patterns.md**:
    - Are any existing patterns invalidated by this change?
    - Mark invalidated patterns as `Status: Obsolete (pivot: [reason])`
 
@@ -63,11 +63,11 @@ Before writing anything, present a summary to the user:
 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]
+- docs/project-brief.md: [what changes]
+- docs/features.md: [N features affected, M dropped, K added]
+- docs/dependency-map.md: [N modules obsoleted, M added, K relationships changed]
+- docs/project-state.md: [N stories affected]
+- docs/failure-patterns.md: [N patterns obsoleted]
 
 ### Confirm? (yes/no)
 ```
@@ -76,15 +76,15 @@ Type: [Tech Swap | Scope Change | Architecture Shift | Goal Pivot]
 
 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)
+1. **docs/project-brief.md** first (source of truth for direction)
+2. **docs/features.md** second (what we're building)
+3. **docs/dependency-map.md** third (how it connects)
+4. **docs/project-state.md** fourth (current work status)
+5. **docs/failure-patterns.md** last (historical patterns)
 
 ### Step 5: Decision Log Entry
 
-Add an entry to the Decision Log section in project-brief.md:
+Add an entry to the Decision Log section in docs/project-brief.md:
 
 ```markdown
 ### [YYYY-MM-DD] [Decision Title]
@@ -97,6 +97,6 @@ Add an entry to the Decision Log section in project-brief.md:
 ## 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
+- **Never update partially** — if you update docs/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

@@ -48,7 +48,7 @@ const dbPassword = "super_secret_123";
 
 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.
+- [ ] **docs/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
 

package/harness/skills/test-integrity.md

@@ -45,8 +45,8 @@ Interface adds findByFilters() → Mock unchanged
 
 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.
+- [ ] **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.
 
 ## Related Failure Patterns
 

package/harness/testing-rules.md

@@ -18,4 +18,4 @@
 ## References
 
 - test-integrity skill
-- failure-patterns.md FP-001: Mock not updated
+- docs/failure-patterns.md FP-001: Mock not updated

package/package.json

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

package/src/init.js

@@ -51,11 +51,22 @@ const STATE_FILES = [
   'project-brief.md',
 ];
 
+const AGENT_MEMORY_FILES = [
+  'agent-memory/reviewer.md',
+  'agent-memory/planner.md',
+  'agent-memory/sprint-manager.md',
+];
+
+const STATE_DEST_DIR = 'docs';
+
 // ─── Shared writers ──────────────────────────────────────────
 
 function writeStateFiles(targetDir, overwrite) {
   for (const file of STATE_FILES) {
-    writeFile(targetDir, file, readTemplate(file), overwrite);
+    writeFile(targetDir, `${STATE_DEST_DIR}/${file}`, readTemplate(file), overwrite);
+  }
+  for (const file of AGENT_MEMORY_FILES) {
+    writeFile(targetDir, `${STATE_DEST_DIR}/${file}`, readTemplate(file), overwrite);
   }
 }
 
@@ -369,7 +380,7 @@ async function run(argv) {
     const gen = GENERATORS[ide];
     console.log(`\n  Installing for ${gen.name}...\n`);
     gen.fn(args.dir, args.overwrite);
-    console.log(`\n  Done! Edit project-state.md to set up your first sprint.\n`);
+    console.log(`\n  Done! Edit docs/project-state.md to set up your first sprint.\n`);
   }
 }