k-harness 0.8.4 → 0.9.1

package/README.md

@@ -127,7 +127,7 @@ See [docs/reference.md](docs/reference.md) for detailed descriptions of every sk
 | 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) |
+| IDE support | 20+ (installer) | 5 (setup --host) | 13 (runtime select) | 6 (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) |

package/harness/agents/planner.md

@@ -18,6 +18,7 @@ The Planner is the entry point for new features — use it BEFORE writing code.
 - docs/dependency-map.md
 - docs/project-state.md
 - docs/failure-patterns.md
+- docs/agent-memory/planner.md — Past estimation accuracy and architecture insights
 
 ## Input
 
@@ -38,6 +39,17 @@ Before proceeding, verify that required state files have content (not just TODO
 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).
 
+### Step 0.5: Load Agent Memory
+
+Read `docs/agent-memory/planner.md` for past learnings:
+- Estimation accuracy from previous sprints (did Wave estimates match reality?)
+- Architecture patterns that worked or failed in this project
+- Repeated planning mistakes to avoid
+
+Apply these insights when creating the implementation plan. If the memory file is empty or contains only placeholders, skip this step.
+
+> **Team Mode**: In Team mode, agent memory is personal (`.harness/agent-memory/`). Each developer accumulates their own planning insights.
+
 ### For New Feature
 
 1. Read `docs/project-brief.md` to understand project vision, goals, **non-goals**, and **Decision Log**

package/harness/agents/reviewer.md

@@ -13,9 +13,12 @@ Finds issues and auto-fixes where safe, escalates where not.
 
 ## Referenced Files
 
+- docs/project-brief.md — Project vision, goals, non-goals, and Decision Log
+- docs/features.md — Feature registry (for Step 6 Feature Registry Check)
 - docs/failure-patterns.md — Project failure patterns
 - docs/project-state.md — Current Story scope
 - docs/dependency-map.md — Module dependency graph
+- docs/agent-memory/reviewer.md — Past review patterns and frequently missed items
 
 ## Procedure
 
@@ -27,6 +30,15 @@ Before reviewing, verify that required state files exist and are not empty:
 
 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."
 
+### Step 0.5: Load Agent Memory
+
+Read `docs/agent-memory/reviewer.md` for past learnings:
+- Frequently missed review items in this project
+- Common code patterns that caused issues
+- Review statistics (pass rate, common failure categories)
+
+Pay extra attention to items flagged in past reviews. If the memory file is empty or contains only placeholders, skip this step.
+
 ### Input
 
 Changed file list (user-provided or from `git diff --name-only`)
@@ -138,3 +150,10 @@ Report using: **DONE** | **DONE_WITH_CONCERNS** | **BLOCKED** | **NEEDS_CONTEXT*
 - Do not refactor beyond the review scope
 - Auto-apply security fixes but always record them in output
 - Escalate with NEEDS_CONTEXT after 3 uncertain judgments
+
+## STATE-AUDIT Handoff
+
+When Step 8 (State File Audit) produces `[STATE-AUDIT]` flags:
+1. List all flagged items in the review output
+2. The `learn` skill (run at session end) will verify and resolve these flags
+3. If a flag is critical (missing module in dependency-map, unregistered feature), recommend fixing immediately rather than deferring to learn

package/harness/agents/sprint-manager.md

@@ -5,10 +5,21 @@
 Manage Sprint/Story state, guide development sequence, and prevent scope drift.
 Keeps the LLM focused on the current work item.
 
+## Referenced Skills
+
+- bootstrap — Recommended when state files are empty
+- learn — Recommended at session end or when all stories are done
+- pivot — Recommended when direction change is detected
+- investigate — Recommended when bug is blocking progress
+
 ## Referenced Files
 
 - docs/project-state.md — Current state (this is the core file)
+- docs/project-brief.md — Project vision and goals (for direction checks)
+- docs/features.md — Feature registry (for progress overview)
+- docs/dependency-map.md — Module graph (for scope validation)
 - docs/failure-patterns.md — Recurring failure tracking
+- docs/agent-memory/sprint-manager.md — Past velocity and scope drift data
 
 ## Procedure
 
@@ -18,7 +29,18 @@ 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."
+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."
+
+### Step 0.5: Load Agent Memory
+
+Read `docs/agent-memory/sprint-manager.md` for past learnings:
+- Team velocity data (stories per sprint)
+- Scope drift history (how often did scope expand?)
+- Story sizing accuracy (were estimates correct?)
+
+Use these insights when recommending story order and estimating sprint capacity. If the memory file is empty or contains only placeholders, skip this step.
+
+> **Team Mode**: In Team mode, agent memory is personal (`.harness/agent-memory/`). Each developer tracks their own velocity and scope drift patterns.
 
 ### Input
 
@@ -63,8 +85,10 @@ After every status check, recommend the next action based on current context:
 **Request: "new story" / "next task"**
 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 docs/failure-patterns.md items
+3. Read `docs/dependency-map.md` to identify modules involved in this Story
+4. Specify Story scope (related files/directories from dependency-map)
+5. Alert relevant docs/failure-patterns.md items
+6. Recommend relevant skill: "Consider running `planner` if this story needs detailed breakdown"
 
 **Request: "new sprint"**
 1. Check all Stories in current Sprint
@@ -108,3 +132,7 @@ STATUS: DONE
 - Do not modify code directly — manage state only
 - Only write to docs/project-state.md; read-only for all other files
 - Always confirm with user before modifying scope boundaries
+
+## Related Failure Patterns
+
+- FP-003: Scope drift → Scope Check handler detects out-of-scope modifications and warns the user before proceeding

package/harness/core-rules.md

@@ -9,6 +9,8 @@ Read `docs/project-state.md` first. If all state files are empty, run `bootstrap
 
 ## Workflow
 
+- First time / empty state → run `bootstrap`
+- Session start → run `sprint-manager` to check status
 - New feature → run `planner` before coding
 - Before commit → run `reviewer`
 - Bug or issue → run `investigate`

package/harness/dependency-map.md

@@ -12,6 +12,7 @@ A living document of module relationships. Update whenever modules are added or
 | services   | application   | Business logic         | auth, database | api           |
 | database   | infrastructure| Data persistence       | -              | services      |
 -->
+<!-- Add new modules above this line -->
 
 ## Dependency Rules
 

package/harness/features.md

@@ -13,6 +13,7 @@ This is LLM's map to understand "what exists" — without this, features get for
 | Admin Dashboard | ⬜ planned | -                                       | -                             | - |
 | Legacy REST API | ❌ dropped | -                                       | -                             | - |
 -->
+<!-- Add new features above this line -->
 
 ## Status Legend
 

package/harness/skills/feature-breakdown.md

@@ -5,6 +5,10 @@
 Decompose a feature into implementation tasks ordered by dependency.
 Ensures bottom-up implementation: foundations first, then layers that depend on them.
 
+## Invoked By
+
+- **planner** agent — Step 8: Create ordered task list for new features
+
 ## When to Apply
 
 - Starting a new feature or Story
@@ -15,24 +19,26 @@ Ensures bottom-up implementation: foundations first, then layers that depend on
 ## Procedure
 
 1. **Describe the feature** in one sentence
-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**:
+2. **Read docs/project-brief.md** — verify the feature aligns with Goals and does not violate Non-Goals. If it conflicts with Non-Goals, **stop and warn the user** before proceeding. (Direction Guard — prevents breakdown of out-of-scope features even when invoked directly without planner)
+3. **Read docs/dependency-map.md** to understand current module relationships
+4. **Identify affected modules**: List every module that needs changes
+5. **Classify changes per module**:
    - NEW_MODULE: Entirely new module to create
    - INTERFACE_CHANGE: Existing module's public interface changes
    - INTERNAL_CHANGE: Only internal implementation changes
    - TEST_ONLY: Only test updates needed
-5. **Build dependency order**:
+6. **Build dependency order**:
    - Draw a mini dependency graph for just the affected modules
    - Sort topologically: modules with no dependencies come first
    - Group into implementation waves (parallel-safe batches)
-6. **Create task sequence**: Convert waves into numbered tasks
-7. **Annotate each task** with:
+7. **Create task sequence**: Convert waves into numbered tasks
+8. **Annotate each task** with:
    - Module name
-   - Change type (from step 4)
+   - Change type (from step 5)
    - Files to create/modify
    - Tests to write
    - Dependency (which prior task must finish first)
+   - ⚠️ Relevant failure patterns (check docs/failure-patterns.md)
 
 ## Output Format
 
@@ -87,3 +93,9 @@ After completing the breakdown, update these files in the same session:
 | Skip dependency-map registration | Register immediately when creating module |
 | Tests "later" | Tests in the same task |
 | Produce breakdown but skip state file updates | State file updates are part of the breakdown, not a separate step |
+
+## Related Failure Patterns
+
+- FP-001: Interface changed, mock not updated → When creating tasks that modify interfaces, include "Update mock" as an explicit sub-task
+- FP-002: Type confusion → When annotating tasks, specify expected types for new interfaces
+- FP-003: Scope drift → If the breakdown exceeds the current Story scope, stop and report

package/harness/skills/impact-analysis.md

@@ -5,6 +5,11 @@
 Before modifying any module, trace all affected modules to prevent cascade failures.
 The most common cause of regressions in growing projects is changing one module without updating its dependents.
 
+## Invoked By
+
+- **planner** agent — Step 9: for each existing module being modified
+- **reviewer** agent — Step 7: when interface changes affect 2+ dependent modules
+
 ## When to Apply
 
 - Adding, removing, or changing a module's public interface
@@ -16,21 +21,25 @@ The most common cause of regressions in growing projects is changing one module
 
 1. **Identify the target module**: Which module are you about to change?
 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?
+3. **Read docs/failure-patterns.md**: Check if any active patterns (FP-001, FP-002, etc.) apply to the target module or change type. If FP-001 frequency > 0, flag mock updates as mandatory in step 6.
+4. **List dependents**: Read the "Depended By" column — these are the blast radius
+5. **Read docs/features.md**: Identify which features include the target module in their Key Files column. These features may need status or Key Files updates.
+6. **Check interface impact**: Does your change affect the module's public interface?
    - If NO (internal-only change) → proceed, but still run dependent tests
-   - If YES → continue to step 5
-5. **Trace each dependent**:
+   - If YES → continue to step 7
+7. **Trace each dependent**:
    - List files in each dependent module that import from the target
    - 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 docs/project-state.md)
+8. **Plan updates**: Create a task list of all files that need modification
+9. **Verify scope**: Confirm all files are within the current Story scope (docs/project-state.md)
 
 ## Checklist
 
 - [ ] Target module identified in docs/dependency-map.md
+- [ ] docs/failure-patterns.md checked for active patterns
 - [ ] All dependent modules listed
+- [ ] Affected features identified from docs/features.md
 - [ ] Interface vs internal change classified
 - [ ] Files importing from target module enumerated
 - [ ] Mock/test updates planned for each dependent (FP-001)
@@ -62,9 +71,10 @@ 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. **This is mandatory for ALL interface changes** — do not skip even if the change seems minor.
+- [ ] **docs/features.md**: If the interface change affects a feature's Key Files, update the Key Files column. If test files change, update the Test Files column.
 - [ ] **docs/project-state.md**: If scope exceeds current Story, add a note to Recent Changes.
 
 ## Related Failure Patterns
 
-- FP-001: Interface changed, mock not updated → Checklist item 5
-- FP-002: Type confusion across modules → Step 5 verification
+- FP-001: Interface changed, mock not updated → Checklist item 7 (mock/test updates planned)
+- FP-002: Type confusion across modules → Step 7 (trace each dependent, verify types)

package/harness/skills/investigate.md

@@ -26,8 +26,10 @@ Debug bugs systematically. Prevent "symptom patching" — fixing without underst
 ### Phase 2: Scope Lock
 
 1. Identify the module/directory containing the root cause
-2. Exclude files outside that scope from modification
-3. Check docs/failure-patterns.md for matching patterns
+2. **Read docs/dependency-map.md**: Find the target module's row. Check "Depended By" column to understand which other modules might be affected by the same root cause or by your fix.
+3. **Read docs/project-state.md**: Verify the fix scope is within the current Story scope. If the root cause is in a module outside the current Story, **warn the user** before proceeding (Iron Law #3: Scope Compliance).
+4. Exclude files outside that scope from modification
+5. Check docs/failure-patterns.md for matching patterns
 
 ### Phase 3: Hypothesis + Fix
 
@@ -45,6 +47,8 @@ Debug bugs systematically. Prevent "symptom patching" — fixing without underst
 
 - [ ] Root cause hypothesis is stated explicitly
 - [ ] Did NOT skip Phase 1 (evidence collection) and jump straight to fixing
+- [ ] docs/dependency-map.md consulted for blast radius understanding
+- [ ] Fix scope verified against current Story in docs/project-state.md
 - [ ] Fix scope is limited to the problem's scope
 - [ ] All related tests pass after the fix
 - [ ] Regression test is added
@@ -82,5 +86,6 @@ After the fix is verified (Phase 4):
 
 ## Related Failure Patterns
 
-- FP-002: Type confusion → Phase 1 requires verifying actual types
 - FP-001: Mock not updated → Phase 4 requires checking mock sync
+- FP-002: Type confusion → Phase 1 requires verifying actual types
+- FP-003: Scope drift → Phase 2 Scope Lock must verify fix is within current Story scope

package/harness/skills/learn.md

@@ -60,6 +60,22 @@ For each issue/error that occurred in this session:
 2. If existing features were modified → update Key Files and Test Files columns
 3. If features were completed → update Status to `✅ done`
 
+### Step 4.5: Verify docs/dependency-map.md (mandatory)
+
+1. Check if any new modules were created in this session (scan `git diff --stat` for new directories)
+2. Check if any module interfaces changed
+3. For each finding:
+   - New module without dependency-map entry → **add it now**
+   - Interface change without Interface Change Log entry → **add it now**
+4. Cross-reference `docs/features.md` Key Files against `docs/dependency-map.md` modules — flag orphaned modules
+
+### Step 4.6: Resolve STATE-AUDIT Flags (if applicable)
+
+If the `reviewer` agent was run in this session and produced `[STATE-AUDIT]` flags:
+1. Review each flagged item
+2. Apply the recommended state file update
+3. If the flag was already resolved during the session, skip it
+
 ### 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/`:
@@ -88,9 +104,10 @@ Present a summary of all updates made.
 - [FP-NNN] (new/updated): [description]
 
 ### State Files Updated:
-- [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/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/dependency-map.md — [N] modules verified/added (if applicable)
 - [x] docs/agent-memory/{name}.md — [N] agents updated (if applicable)
 
 ### Next Session Should:

package/harness/skills/pivot.md

@@ -100,3 +100,16 @@ Add an entry to the Decision Log section in docs/project-brief.md:
 - **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
+
+## Team Mode
+
+If `.harness/` directory exists (Team mode is active):
+
+- **pivot MUST be run on the main branch** by the team lead or architect only
+- Feature branches should NOT run pivot independently
+- If a direction change is needed from a feature branch:
+  1. Document the proposed change
+  2. Share with the team
+  3. Team lead runs pivot on main
+  4. All developers pull main to get updated shared state files
+  5. Each developer's `.harness/` personal state is unaffected (update manually if needed)

package/harness/skills/security-checklist.md

@@ -5,6 +5,10 @@
 Inspect for security risks before committing code.
 Prevents credential leaks and accidental commits of sensitive files. (FP-004)
 
+## Invoked By
+
+- **reviewer** agent — Step 4: Security risk inspection
+
 ## When to Apply
 
 - Before running `git add` or committing
@@ -15,13 +19,15 @@ Prevents credential leaks and accidental commits of sensitive files. (FP-004)
 ## Procedure
 
 1. **Check staging area**: Run `git diff --cached --name-only` to list files staged for commit
-2. **Scan for forbidden files**: Check if .env, credentials, *.pem, *.key files are staged
-3. **Scan for hardcoded secrets**: Search staged files for passwords, API keys, tokens
-4. **Verify .gitignore**: Ensure new environment files are covered by .gitignore
-5. **Check for temp files**: Verify tmp_*, debug_*, coverage_* files are not staged
+2. **Read docs/failure-patterns.md**: Check FP-004 status. If frequency > 0, apply extra scrutiny to all staged files and verify .gitignore coverage is comprehensive.
+3. **Scan for forbidden files**: Check if .env, credentials, *.pem, *.key files are staged
+4. **Scan for hardcoded secrets**: Search staged files for passwords, API keys, tokens
+5. **Verify .gitignore**: Ensure new environment files are covered by .gitignore
+6. **Check for temp files**: Verify tmp_*, debug_*, coverage_* files are not staged
 
 ## Checklist
 
+- [ ] docs/failure-patterns.md reviewed for FP-004 history
 - [ ] (FP-004) No .env, credentials, *.key files in staging area
 - [ ] (FP-004) No hardcoded passwords, API keys, or tokens in code
 - [ ] Sensitive file patterns are registered in .gitignore
@@ -49,7 +55,8 @@ const dbPassword = "super_secret_123";
 After completing the security check:
 
 - [ ] **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.
+- [ ] **docs/project-state.md**: If a security issue was found, add to Recent Changes: "⚠️ Security: [description of issue found/fixed]". This ensures the next session's Quick Summary includes the security context.
 
 ## Related Failure Patterns
 
-- FP-004: Dangerous file committed → Checklist items 1, 4
+- FP-004: Dangerous file committed → Checklist items 2, 5 (no forbidden files, no temp files)

package/harness/skills/test-integrity.md

@@ -5,6 +5,10 @@
 Ensure test mocks stay synchronized when repository/service interfaces change.
 Prevents the most common LLM coding failure: updating an interface but forgetting to update corresponding mocks. (FP-001)
 
+## Invoked By
+
+- **reviewer** agent — Step 3: Mock synchronization verification
+
 ## When to Apply
 
 - Adding, removing, or modifying methods on a repository/service interface
@@ -13,16 +17,18 @@ Prevents the most common LLM coding failure: updating an interface but forgettin
 
 ## Procedure
 
-1. **Identify changed interfaces**: Find modified files in your interface directory
-2. **Map to mock files**: Locate the corresponding mock file for each changed interface
-3. **Sync methods**: Verify every interface method exists in the mock
-4. **Verify return types**: Confirm mock return values match the interface return types
-5. **Check consumers**: Verify use case tests configure the mock correctly for new methods
+1. **Read docs/failure-patterns.md**: Check FP-001 status. If frequency > 0, this project has a history of mock sync failures — apply extra scrutiny to every interface change.
+2. **Identify changed interfaces**: Find modified files in your interface directory
+3. **Map to mock files**: Locate the corresponding mock file for each changed interface
+4. **Sync methods**: Verify every interface method exists in the mock
+5. **Verify return types**: Confirm mock return values match the interface return types (FP-002: watch for type confusion)
+6. **Check consumers**: Verify use case tests configure the mock correctly for new methods
 
 ## Checklist
 
+- [ ] docs/failure-patterns.md reviewed for FP-001 history
 - [ ] (FP-001) Every changed interface method is reflected in its mock
-- [ ] Mock return types match interface signatures
+- [ ] (FP-002) Mock return types match interface signatures (no type confusion)
 - [ ] New methods have default mock return values set
 - [ ] Use case tests correctly use the new mock methods
 - [ ] Existing tests still pass
@@ -47,6 +53,7 @@ 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.
+- [ ] **docs/project-state.md**: If mock sync issues were found and fixed, add to Recent Changes: "🔧 Test: [interface] mock synchronized". This ensures the next session is aware of the fix.
 
 ## Testing Rules (enforced during this skill)
 
@@ -59,4 +66,5 @@ After synchronizing mocks:
 
 ## Related Failure Patterns
 
-- FP-001: Interface changed, mock not updated → Checklist item 1
+- FP-001: Interface changed, mock not updated → Checklist item 2
+- FP-002: Type confusion → Step 5 return type verification

package/package.json

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

package/src/init.js

@@ -57,7 +57,43 @@ const AGENT_MEMORY_FILES = [
   'agent-memory/sprint-manager.md',
 ];
 
+const PERSONAL_STATE_FILES = ['project-state.md', 'failure-patterns.md'];
+const PERSONAL_DIRS = ['agent-memory/'];
+
 const STATE_DEST_DIR = 'docs';
+const PERSONAL_DEST_DIR = '.harness';
+
+// ─── Team mode path resolver ─────────────────────────────────
+const TEAM_MODE_SECTION = `
+
+## Team Mode
+
+This project uses Team mode. State files are split into shared and personal.
+
+### File Locations
+- **Shared** (docs/, git committed): project-brief.md, features.md, dependency-map.md
+- **Personal** (.harness/, gitignored): project-state.md, failure-patterns.md, agent-memory/
+
+### Rules
+1. Shared files: only modify your own rows (check Owner column)
+2. Other developers' Owner rows are READ ONLY
+3. New rows go at the bottom of the table
+4. The \`pivot\` skill must be run on the main branch by the team lead only
+`;
+
+function resolveContent(content, mode) {
+  if (mode !== 'team') return content;
+  let result = content
+    .replaceAll('docs/project-state.md', '.harness/project-state.md')
+    .replaceAll('docs/failure-patterns.md', '.harness/failure-patterns.md')
+    .replaceAll('docs/agent-memory/', '.harness/agent-memory/');
+
+  // Append Team Mode section to core-rules (detected by the heading)
+  if (result.includes('## State Files') && result.includes('## Session Start')) {
+    result += TEAM_MODE_SECTION;
+  }
+  return result;
+}
 
 // ─── Language detection ──────────────────────────────────────
 function detectLanguage(targetDir) {
@@ -80,18 +116,22 @@ function detectLanguage(targetDir) {
 
 // ─── Shared writers ──────────────────────────────────────────
 
-function writeStateFiles(targetDir, overwrite) {
+function writeStateFiles(targetDir, overwrite, mode = 'solo') {
   for (const file of STATE_FILES) {
-    writeFile(targetDir, `${STATE_DEST_DIR}/${file}`, readTemplate(file), overwrite);
+    const isPersonal = PERSONAL_STATE_FILES.includes(file);
+    const destDir = (mode === 'team' && isPersonal) ? PERSONAL_DEST_DIR : STATE_DEST_DIR;
+    const content = resolveContent(readTemplate(file), mode);
+    writeFile(targetDir, `${destDir}/${file}`, content, overwrite);
   }
   for (const file of AGENT_MEMORY_FILES) {
-    writeFile(targetDir, `${STATE_DEST_DIR}/${file}`, readTemplate(file), overwrite);
+    const destDir = mode === 'team' ? PERSONAL_DEST_DIR : STATE_DEST_DIR;
+    writeFile(targetDir, `${destDir}/${file}`, readTemplate(file), overwrite);
   }
 }
 
-function writeSkills(targetDir, skillsDir, overwrite) {
+function writeSkills(targetDir, skillsDir, overwrite, mode = 'solo') {
   for (const skill of SKILLS) {
-    const content = readTemplate(`skills/${skill.id}.md`);
+    const content = resolveContent(readTemplate(`skills/${skill.id}.md`), mode);
     const skillMd =
       `---\nname: ${skill.id}\ndescription: '${skill.desc}'\n---\n\n` +
       content;
@@ -99,9 +139,9 @@ function writeSkills(targetDir, skillsDir, overwrite) {
   }
 }
 
-function writeAgentsAsSkills(targetDir, skillsDir, overwrite) {
+function writeAgentsAsSkills(targetDir, skillsDir, overwrite, mode = 'solo') {
   for (const agent of AGENTS) {
-    const content = readTemplate(agent.file);
+    const content = resolveContent(readTemplate(agent.file), mode);
     const skillMd =
       `---\nname: ${agent.id}\ndescription: '${agent.desc}'\n---\n\n` +
       content;
@@ -111,18 +151,18 @@ function writeAgentsAsSkills(targetDir, skillsDir, overwrite) {
 
 // ─── IDE Generators ──────────────────────────────────────────
 
-function generateVscode(targetDir, overwrite) {
-  const coreRules = readTemplate('core-rules.md');
+function generateVscode(targetDir, overwrite, mode = 'solo') {
+  const coreRules = resolveContent(readTemplate('core-rules.md'), mode);
 
   // Global instructions (dispatcher only — rules are embedded in skills)
   writeFile(targetDir, '.github/copilot-instructions.md', coreRules, overwrite);
 
   // Skills (.github/skills — VS Code default search path, SKILL.md with frontmatter)
-  writeSkills(targetDir, '.github/skills', overwrite);
+  writeSkills(targetDir, '.github/skills', overwrite, mode);
 
   // Agents (.github/agents — VS Code uses .agent.md format with frontmatter)
   for (const agent of AGENTS) {
-    const content = readTemplate(agent.file);
+    const content = resolveContent(readTemplate(agent.file), mode);
     const agentMd =
       `---\nname: ${agent.id}\ndescription: "${agent.desc}"\n---\n\n` +
       content;
@@ -130,87 +170,87 @@ function generateVscode(targetDir, overwrite) {
   }
 
   // State files
-  writeStateFiles(targetDir, overwrite);
+  writeStateFiles(targetDir, overwrite, mode);
 }
 
-function generateClaude(targetDir, overwrite) {
+function generateClaude(targetDir, overwrite, mode = 'solo') {
   // .claude/rules/core.md — dispatcher only (no paths = always loaded)
-  writeFile(targetDir, '.claude/rules/core.md', readTemplate('core-rules.md'), overwrite);
+  writeFile(targetDir, '.claude/rules/core.md', resolveContent(readTemplate('core-rules.md'), mode), overwrite);
 
   // Skills (SKILL.md with frontmatter)
-  writeSkills(targetDir, '.claude/skills', overwrite);
+  writeSkills(targetDir, '.claude/skills', overwrite, mode);
 
   // Agents as skills (Claude Code skills pattern)
-  writeAgentsAsSkills(targetDir, '.claude/skills', overwrite);
+  writeAgentsAsSkills(targetDir, '.claude/skills', overwrite, mode);
 
   // State files
-  writeStateFiles(targetDir, overwrite);
+  writeStateFiles(targetDir, overwrite, mode);
 }
 
-function generateCursor(targetDir, overwrite) {
+function generateCursor(targetDir, overwrite, mode = 'solo') {
   // .cursor/rules/core.mdc — dispatcher only (always active)
-  const coreRules = readTemplate('core-rules.md');
+  const coreRules = resolveContent(readTemplate('core-rules.md'), mode);
   const coreMdc =
     '---\ndescription: K-Harness dispatcher — workflow guidance and state file references\nalwaysApply: true\n---\n\n' +
     coreRules;
   writeFile(targetDir, '.cursor/rules/core.mdc', coreMdc, overwrite);
 
   // Skills (.cursor/skills — invokable by mentioning skill name)
-  writeSkills(targetDir, '.cursor/skills', overwrite);
+  writeSkills(targetDir, '.cursor/skills', overwrite, mode);
 
   // Agents as skills
-  writeAgentsAsSkills(targetDir, '.cursor/skills', overwrite);
+  writeAgentsAsSkills(targetDir, '.cursor/skills', overwrite, mode);
 
   // State files
-  writeStateFiles(targetDir, overwrite);
+  writeStateFiles(targetDir, overwrite, mode);
 }
 
-function generateCodex(targetDir, overwrite) {
+function generateCodex(targetDir, overwrite, mode = 'solo') {
   // AGENTS.md — dispatcher only
-  writeFile(targetDir, 'AGENTS.md', readTemplate('core-rules.md'), overwrite);
+  writeFile(targetDir, 'AGENTS.md', resolveContent(readTemplate('core-rules.md'), mode), overwrite);
 
   // Skills (SKILL.md with frontmatter — invokable via $skill-name)
-  writeSkills(targetDir, '.agents/skills', overwrite);
+  writeSkills(targetDir, '.agents/skills', overwrite, mode);
 
   // Agents as skills
-  writeAgentsAsSkills(targetDir, '.agents/skills', overwrite);
+  writeAgentsAsSkills(targetDir, '.agents/skills', overwrite, mode);
 
   // State files
-  writeStateFiles(targetDir, overwrite);
+  writeStateFiles(targetDir, overwrite, mode);
 }
 
-function generateWindsurf(targetDir, overwrite) {
+function generateWindsurf(targetDir, overwrite, mode = 'solo') {
   // .windsurf/rules/core.md — dispatcher (trigger: always_on)
-  const coreRules = readTemplate('core-rules.md');
+  const coreRules = resolveContent(readTemplate('core-rules.md'), mode);
   const coreRule =
     '---\ntrigger: always_on\n---\n\n' +
     coreRules;
   writeFile(targetDir, '.windsurf/rules/core.md', coreRule, overwrite);
 
   // Skills (.windsurf/skills — Agent Skills standard)
-  writeSkills(targetDir, '.windsurf/skills', overwrite);
+  writeSkills(targetDir, '.windsurf/skills', overwrite, mode);
 
   // Agents as skills
-  writeAgentsAsSkills(targetDir, '.windsurf/skills', overwrite);
+  writeAgentsAsSkills(targetDir, '.windsurf/skills', overwrite, mode);
 
   // State files
-  writeStateFiles(targetDir, overwrite);
+  writeStateFiles(targetDir, overwrite, mode);
 }
 
-function generateAntigravity(targetDir, overwrite) {
+function generateAntigravity(targetDir, overwrite, mode = 'solo') {
   // .agent/rules/core.md — dispatcher only
-  const coreRules = readTemplate('core-rules.md');
+  const coreRules = resolveContent(readTemplate('core-rules.md'), mode);
   const coreRule =
     '---\ndescription: K-Harness dispatcher — workflow guidance and state file references\ntype: always\n---\n\n' +
     coreRules;
   writeFile(targetDir, '.agent/rules/core.md', coreRule, overwrite);
 
   // .agent/skills/ — SKILL.md format (enables / slash commands)
-  writeSkills(targetDir, '.agent/skills', overwrite);
-  writeAgentsAsSkills(targetDir, '.agent/skills', overwrite);
+  writeSkills(targetDir, '.agent/skills', overwrite, mode);
+  writeAgentsAsSkills(targetDir, '.agent/skills', overwrite, mode);
 
   // State files
-  writeStateFiles(targetDir, overwrite);
+  writeStateFiles(targetDir, overwrite, mode);
 }
 
 // ─── IDE registry ────────────────────────────────────────────
@@ -251,6 +291,85 @@ async function promptIde() {
   return keys[idx];
 }
 
+async function promptMode() {
+  console.log('  Project mode:\n');
+  console.log('    1. Solo  — Single developer (all state files in docs/)');
+  console.log('    2. Team  — Multiple developers (personal state in .harness/, shared in docs/)');
+  console.log();
+
+  const answer = await askQuestion('  Choice (1-2, default: 1): ');
+  if (answer === '2' || answer.toLowerCase() === 'team') return 'team';
+  return 'solo';
+}
+
+// ─── Team mode helpers ───────────────────────────────────────
+function appendGitignore(targetDir) {
+  const gitignorePath = path.join(targetDir, '.gitignore');
+  const entry = '\n# K-Harness personal state (Team mode)\n.harness/\n';
+  if (fs.existsSync(gitignorePath)) {
+    const content = fs.readFileSync(gitignorePath, 'utf8');
+    if (content.includes('.harness/')) {
+      console.log('  ⏭  Skipped (exists): .gitignore entry');
+      return;
+    }
+    fs.appendFileSync(gitignorePath, entry);
+  } else {
+    fs.writeFileSync(gitignorePath, entry.trimStart());
+  }
+  console.log('  ✓  .gitignore — added .harness/');
+}
+
+function writeGitattributes(targetDir) {
+  const content =
+    '# K-Harness Team mode — merge strategy for shared state files\n' +
+    'docs/features.md merge=union\n' +
+    'docs/dependency-map.md merge=union\n';
+  writeFile(targetDir, '.gitattributes', content, false);
+}
+
+// ─── Post-install guide ──────────────────────────────────────
+function showPostInstallGuide(ideName, mode) {
+  const modeLabel = mode === 'team' ? 'Team' : 'Solo';
+  const lines = [
+    '',
+    '  ──────────────────────────────────────────',
+    '  ✅ K-Harness initialized successfully!',
+    '',
+    `  Mode: ${modeLabel}`,
+    `  IDE:  ${ideName}`,
+    '',
+  ];
+
+  if (mode === 'team') {
+    lines.push(
+      '  📁 Files:',
+      '     docs/           — shared state (git committed)',
+      '     .harness/       — personal state (gitignored)',
+      '     .gitignore      — .harness/ added',
+      '     .gitattributes  — merge=union for shared files',
+    );
+  } else {
+    lines.push(
+      '  📁 Files:',
+      '     docs/           — all state files',
+    );
+  }
+
+  lines.push(
+    '',
+    '  🚀 Next steps:',
+    '     1. Ask your AI: "Run bootstrap to onboard this project"',
+    '     2. AI scans your codebase and fills state files automatically',
+    '     3. Start coding with: @planner "Add [feature name]"',
+    '',
+    '  📖 Docs: https://www.npmjs.com/package/k-harness',
+    '  ──────────────────────────────────────────',
+    '',
+  );
+
+  console.log(lines.join('\n'));
+}
+
 // ─── CLI entry ───────────────────────────────────────────────
 function showHelp() {
   console.log(`
@@ -261,6 +380,7 @@ function showHelp() {
 
   Options:
     --ide <name>     IDE target: vscode, claude, cursor, codex, windsurf, antigravity
+    --mode <mode>    Project mode: solo (default) or team
     --dir <path>     Target directory (default: current directory)
     --overwrite      Overwrite existing files
     --help           Show this help
@@ -268,16 +388,19 @@ function showHelp() {
   Examples:
     npx k-harness init
     npx k-harness init --ide vscode
+    npx k-harness init --ide vscode --mode team
     npx k-harness init --ide claude --dir ./my-project
 `);
 }
 
 function parseArgs(argv) {
-  const args = { command: null, ide: null, dir: process.cwd(), overwrite: false, help: false };
+  const args = { command: null, ide: null, mode: null, dir: process.cwd(), overwrite: false, help: false };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === 'init') args.command = 'init';
     else if (arg === '--ide' && argv[i + 1]) { args.ide = argv[++i]; }
+    else if (arg === '--mode' && argv[i + 1]) { args.mode = argv[++i]; }
+    else if (arg === '--team') { args.mode = 'team'; }
     else if (arg === '--dir' && argv[i + 1]) { args.dir = path.resolve(argv[++i]); }
     else if (arg === '--overwrite') args.overwrite = true;
     else if (arg === '--help' || arg === '-h') args.help = true;
@@ -307,11 +430,29 @@ async function run(argv) {
       ide = await promptIde();
     }
 
+    // Determine mode
+    let mode = args.mode;
+    if (mode && !['solo', 'team'].includes(mode)) {
+      console.error(`  Unknown mode: ${mode}`);
+      console.error('  Available: solo, team');
+      process.exit(1);
+    }
+    if (!mode) {
+      mode = await promptMode();
+    }
+
     const gen = GENERATORS[ide];
     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! Run "bootstrap" in your AI chat to auto-fill state files and rules.\n`);
+    console.log(`\n  Installing for ${gen.name} (${mode} mode)... (detected language: ${lang})\n`);
+    gen.fn(args.dir, args.overwrite, mode);
+
+    // Team mode extras
+    if (mode === 'team') {
+      appendGitignore(args.dir);
+      writeGitattributes(args.dir);
+    }
+
+    showPostInstallGuide(gen.name, mode);
   }
 }