k-harness 0.3.0 → 0.5.0

package/README.md

@@ -1,16 +1,17 @@
 # K-Harness
 
-LLM Development Harness — IDE-agnostic rules, skills, and agents that prevent common AI coding failures.
+Project Direction Management Framework for LLM-Driven Development.
 
 ## What It Does
 
-K-Harness installs structured instruction files into your project that guide LLM coding agents (Copilot, Claude, Cursor, Codex, Windsurf) to avoid common mistakes:
+K-Harness manages your **project's direction** — goals, decisions, scope — so LLM coding agents stay aligned across sessions. It combines BMAD's systematic project management with gstack's simplicity: zero dependencies, IDE-native format generation, and minimal context overhead.
 
-- **Iron Laws** — Hard rules the LLM must follow every session (mock sync, type checking, security)
-- **Skills** — Step-by-step procedures for specific tasks (debugging, code review, security checks)
-- **Agents** — Role-based personas (reviewer, sprint manager)
+- **Direction Guard** — Every coding request is checked against project goals/non-goals before execution
+- **State Files** — 5 markdown files that persist project knowledge across LLM sessions
+- **Skills** — Step-by-step procedures for planning, review, debugging, and direction changes
+- **Agents** — Role-based personas that enforce the workflow (planner, reviewer, sprint-manager)
 - **Failure Patterns** — Project-specific failure log that prevents repeat mistakes
-- **State Tracking** — Sprint/Story state so the LLM knows what to work on
+- **Decision Log** — Records why decisions were made so LLMs don't re-debate settled choices
 
 ## Quick Start
 
@@ -20,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
@@ -46,13 +53,13 @@ npx k-harness init --ide antigravity
 |-----|-------------|-------------------|--------|--------|
 | **VS Code Copilot** | `.github/copilot-instructions.md` | `.vscode/instructions/*.instructions.md` | `.github/skills/*/SKILL.md` | `.github/agents/*.agent.md` |
 | **Claude Code** | `CLAUDE.md` | (merged into CLAUDE.md) | `.claude/skills/*/SKILL.md` | (merged into CLAUDE.md) |
-| **Cursor** | `.cursor/rules/core.mdc` | `.cursor/rules/*.mdc` | `.cursor/rules/*.mdc` | `.cursor/rules/*.mdc` |
+| **Cursor** | `.cursor/rules/core.mdc` | `.cursor/rules/*.mdc` | (merged into rules) | (merged into rules) |
 | **Codex** | `AGENTS.md` | (merged into AGENTS.md) | `.agents/skills/*/SKILL.md` | (merged into AGENTS.md) |
 | **Windsurf** | `.windsurfrules` | (merged) | (merged) | (merged) |
 | **Augment Code** | `.augment/rules/core.md` | `.augment/rules/*.md` | `.augment/skills/*/SKILL.md` | `.augment/skills/*/SKILL.md` |
 | **Google Antigravity** | `.agent/rules/core.md` | `.agent/rules/*.md` | `.agent/skills/*/SKILL.md` | `.agent/skills/*/SKILL.md` |
 
-All IDEs also get `project-state.md`, `failure-patterns.md`, `features.md`, and `project-brief.md` at the project root.
+All IDEs also get `project-state.md`, `project-brief.md`, `features.md`, `failure-patterns.md`, and `dependency-map.md` at the project root.
 
 ## What Gets Installed
 
@@ -62,47 +69,69 @@ All IDEs also get `project-state.md`, `failure-patterns.md`, `features.md`, and
 - **Backend Rules** — Dependency inversion, type safety, explicit staging (applied to source files)
 
 ### Skills (on-demand procedures)
+- **bootstrap** — Onboard project into K-Harness: scans codebase + fills state files automatically
+- **learn** — End-of-session wrap-up: captures failure patterns, updates project state
+- **pivot** — Propagate direction changes across all state files when goals/tech/scope changes
 - **test-integrity** — Verify mock/interface synchronization before committing
 - **security-checklist** — Pre-commit security risk scan
 - **investigate** — 4-phase systematic debugging (evidence → scope → fix → verify)
+- **impact-analysis** — Assess change blast radius before modifying shared modules
+- **feature-breakdown** — Decompose features into dependency-ordered implementation tasks
 
 ### Agents (role-based personas)
-- **reviewer** — Code review: architecture, tests, security, failure pattern cross-check
-- **sprint-manager** — Sprint/Story state management, scope drift prevention
-
-### State Files
-- **project-state.md** — Current sprint, stories, and progress tracking
-- **failure-patterns.md** — Template for logging project-specific failure patterns
-
-## After Installation
+- **planner** — Feature planning, dependency analysis, Direction Alignment (goal/non-goal/decision check)
+- **reviewer** — Code review + State File Audit (verifies state files were actually updated)
+- **sprint-manager** — Sprint/Story state management, scope drift prevention, Next Step Recommendation
 
-1. **Edit `project-state.md`** — Set up your first sprint and stories
-2. **Customize global rules** — Add your architecture, type rules, and directory structure
-3. **Log failures** — When an LLM makes a repeated mistake, record it in `failure-patterns.md`
+### State Files (project memory)
+- **project-brief.md** — Project vision, goals, non-goals, Decision Log (the "why")
+- **project-state.md** — Current sprint, stories, and progress tracking (the "where")
+- **features.md** — Living feature registry so LLMs know what exists (the "what")
+- **dependency-map.md** — Module dependency graph for impact analysis (the "how")
+- **failure-patterns.md** — Project-specific failure patterns that prevent repeat mistakes (the "watch out")
 
-## Design Principles
+## How It Works
 
-1. **State Injection** — Project state injected at every session start
-2. **Rigid Workflow** — Hard "do/don't" rules; soft suggestions get ignored by LLMs
-3. **Failure-Driven Rules** — Rules derived only from actual project failures
-4. **Completion Status Protocol** — DONE / BLOCKED / NEEDS_CONTEXT reporting
-5. **Scope Lock** — Escalate before modifying files outside current story scope
+### 1. Bootstrap (once)
+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.
 
-## Research & Analysis
+### 2. Direction Guard (every request)
+Before ANY coding task, the LLM reads `project-brief.md` and checks:
+- Does this align with Goals? → proceed
+- Does this fall under Non-Goals? → warn, suggest `pivot`
+- Does this contradict a Decision Log entry? → warn, suggest `pivot`
 
+### 3. Workflow Pipeline
 ```
-docs/
-├── analysis/           # Framework comparisons
-│   ├── comparison.md   # BMAD vs gstack
-│   ├── bmad-deep-dive.md
-│   └── gstack-deep-dive.md
-├── architecture/       # K-Harness design
-│   ├── design-principles.md
-│   ├── file-structure.md
-│   └── skill-spec.md
-└── case-study/
-    └── mcphub-lessons.md
+bootstrap → planner → [code] → reviewer → sprint-manager → learn
 ```
+- **planner**: Checks direction alignment, breaks down features
+- **reviewer**: Reviews code + audits state file updates
+- **sprint-manager**: Tracks progress, recommends next action
+- **learn**: Captures lessons before session ends
+
+### 4. Direction Changes
+When goals, technology, or scope changes, run the `pivot` skill:
+- Updates ALL 5 state files consistently
+- Records the decision with reasoning in Decision Log
+- Prevents silent inconsistencies across files
+
+## Documentation
+
+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 | 15 |
+| Dependencies | Node 20+ | Bun + Node + Playwright | Zero |
+| IDE support | 20+ (installer) | 5 (setup --host) | 7 (native format) |
+| Direction management | ❌ | ❌ | ✅ (Direction Guard + pivot + Decision Log) |
+| Cold start | ❌ | ❌ | ✅ (bootstrap) |
+| State file audit | ❌ | ❌ | ✅ (reviewer Step 8) |
+| Context per task | 4-6 files | 1 file | 2-3 files |
 
 ## License
 

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
 
@@ -28,31 +28,45 @@ One of:
 
 ## Procedure
 
+### Step 0: State File Readiness
+
+Before proceeding, verify that required state files have content (not just TODO placeholders):
+- `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 `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, and **non-goals**
-2. **Direction Guard**: Verify the requested feature aligns with the project goals and does NOT fall into non-goals. If it conflicts, warn the user before proceeding.
-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
+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 `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
@@ -79,7 +93,7 @@ One of:
 - [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
@@ -93,8 +107,8 @@ One of:
 
 ## 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,12 +13,20 @@ 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:
+- `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."
+
 ### Input
 
 Changed file list (user-provided or from `git diff --name-only`)
@@ -27,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
@@ -45,20 +53,31 @@ 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:
+- [ ] **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.
+
 ### Output Format
 
 ```

package/harness/agents/sprint-manager.md

@@ -7,11 +7,19 @@ 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 `docs/project-state.md` has content:
+- Quick Summary must not be all TODO placeholders
+- Story Status table must have at least one row
+
+If `docs/project-state.md` is empty/placeholder-only → **Recommend running `bootstrap` skill first.** Report: docs/project-state.md is empty. Run bootstrap to initialize project state before tracking sprints."
+
 ### Input
 
 User request: "next task", "current status", "story done", "new sprint", "scope check"
@@ -19,26 +27,50 @@ 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. Recommend next action
+3. Run **Next Step Recommendation** (see below)
+
+**Next Step Recommendation**
+
+After every status check, recommend the next action based on current context:
+
+1. Read `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" |
+|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" |
+| A direction change was discussed | → "Run `pivot` to update all state files before continuing" |
+| Recent failure patterns apply | → "Watch out for FP-{NNN}: [description]" |
+
+3. Format the recommendation as:
+```
+💡 Recommended next: [action]
+   Why: [one-sentence reason]
+   Command: [exact skill/agent to invoke]
+```
 
 **Request: "story done" / "S{N}-{M} done"**
-1. Update the Story status to `done` in project-state.md
+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:
@@ -69,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

@@ -2,21 +2,23 @@
 
 ## Required
 
-- Follow the project's architecture patterns strictly:
+- Follow the project's architecture patterns strictly.
+  <!-- TODO: Define your architecture layers. Examples:
   - Domain layer must not import from infrastructure.
   - Application layer accesses data only through domain interfaces.
   - Infrastructure implements domain interfaces.
-  - Presentation handles routing and DTO conversion only. No business logic.
-- Before calling any constructor, read the actual source file to verify parameters. Do not trust memory. (FP-002)
+  - Controllers/routes handle request/response only. No business logic.
+  -->
+- Before calling any constructor or factory, read the actual source file to verify parameters. Do not trust memory. (FP-002)
 
 ## Forbidden
 
-- Importing infrastructure from domain (dependency inversion violation).
-- `any` type usage — when unavoidable, add `// eslint-disable-next-line` with reason comment.
-- Hardcoding environment variables in code. Use `process.env` with centralized config.
+- Violating the project's dependency direction (e.g. importing infrastructure from domain).
+- Suppressing type safety without an explicit reason comment.
+- Hardcoding environment variables or secrets in code. Use centralized config.
 - `git add .` or `git add -A` — use explicit per-file staging.
 
 ## References
 
-- 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,18 +32,18 @@
 
 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
 
 - New feature = New test. Do not commit feature code without tests.
-- Test command: `npm test` <!-- TODO: customize -->
-- Mock location: `tests/__mocks__/` <!-- TODO: customize -->
+- Test command: <!-- TODO: e.g. npm test, pytest, go test ./..., mvn test -->
+- Mock location: <!-- TODO: e.g. tests/__mocks__/, test/fixtures/ -->
 
 ## Completion Status Protocol
 
@@ -59,18 +59,68 @@ Report completion using one of:
 - When tests fail, quote the test name and error message.
 - When type errors occur, specify expected type and actual type.
 
+## Direction Guard (Every Request)
+
+Before starting ANY coding task, do this:
+
+1. Read `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. `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.
+
+## Workflow Pipeline
+
+Follow this order for different workflows. Each step's output feeds the next.
+
+### New Feature
+```
+bootstrap (if state files empty) → planner → [code] → reviewer → sprint-manager → learn
+```
+
+### Bug Fix
+```
+investigate → [fix] → test-integrity → reviewer → learn
+```
+
+### Session Lifecycle
+```
+[session start] → sprint-manager ("where are we?") → [work] → learn → [session end]
+```
+
+### Key Rules
+- **planner before code**: Never start coding a feature without running planner first.
+- **reviewer before commit**: Never commit without running reviewer.
+- **learn before closing**: Run learn as the last skill of every session.
+- **bootstrap once**: Run bootstrap once when state files are empty. Not needed after that.
 
 ## References
 
-- project-brief.md — Project vision, goals, non-goals (the "why")
-- 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