@kodevibe/harness 0.8.3

package/harness/skills/feature-breakdown.md

@@ -0,0 +1,136 @@
+# Feature Breakdown
+
+## Purpose
+
+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
+- **architect** agent — when structural validation requires task decomposition review
+
+> **Note**: feature-breakdown is responsible for task decomposition only. It does NOT invoke `impact-analysis`. The planner calls both skills independently: feature-breakdown (Step 8) for task ordering, then impact-analysis (Step 9) for blast radius analysis.
+
+## When to Apply
+
+- Starting a new feature or Story
+- A feature touches 3+ modules
+- Unsure which module to build first
+- After the Planner agent creates a high-level plan
+
+## Procedure
+
+1. **Describe the feature** in one sentence
+2. **Read docs/project-brief.md** — verify the feature aligns with Goals and does not violate Non-Goals. If project-brief.md is empty (bootstrap hasn't run), skip this check but warn the user. 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
+6. **Build dependency order**:
+   - List modules topologically: modules with zero dependencies first, then modules depending on first layer, etc.
+   - Example: Module A (no deps) → Module B (depends A) → Module C (depends A, B)
+   - Group into implementation waves (parallel-safe batches)
+7. **Create task sequence**: Convert waves into numbered tasks
+8. **Annotate each task** with:
+   - Module name
+   - 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
+
+```markdown
+## Feature: [one-sentence description]
+
+### Wave 1 (no dependencies)
+- [ ] Task 1: [Module A] — Create entity + repository interface
+  - Files: <!-- list files to create/modify -->
+  - Tests: <!-- list test files -->
+  - Depends on: none
+
+### Wave 2 (depends on Wave 1)
+- [ ] Task 2: [Module B] — Implement use case
+  - Files: <!-- list files to create/modify -->
+  - Tests: <!-- list test files -->
+  - Depends on: Task 1
+
+### Wave 3 (depends on Wave 2)
+- [ ] Task 3: [Module C] — Add API endpoint / UI integration
+  - Files: <!-- list files to create/modify -->
+  - Tests: <!-- list test files -->
+  - Depends on: Task 2
+
+### Dependency Map Updates
+- [ ] Register Module A in docs/dependency-map.md
+- [ ] Update Module B's "Depends On" column
+```
+
+## Rules
+
+- 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 docs/dependency-map.md (Iron Law #6) — the breakdown OUTPUT section lists these registrations, and planner (or the user, if invoked directly) is responsible for executing the actual state file writes
+- If a task exceeds Story scope, stop and report to user
+
+## State File Updates (mandatory — Step 9)
+
+After completing the breakdown, update these files in the same session:
+
+- [ ] **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.
+
+### 🧭 Navigation — After Feature Breakdown
+
+Feature-breakdown is invoked BY planner (Step 8), so the 🧭 returns control to planner's flow.
+If invoked directly by the user, append:
+
+```
+---
+🧭 Next Step
+→ Next: `planner`
+→ Prompt: "breakdown을 기반으로 Sprint Story를 생성해줘"
+→ Why: Tasks are defined — planner will register Stories and update state files
+→ Pipeline: 🟢 Step 2/6 (returns to planner)
+---
+```
+
+## Anti-patterns
+
+| Anti-pattern | Correct Approach |
+|---|---|
+| Start from UI, work backward | Start from domain, work forward |
+| One giant task for the whole feature | Break into single-module tasks |
+| 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
+
+<!-- TEAM_MODE_START -->
+## Team Mode: Feature Breakdown
+
+### Pre-Pull
+Before updating shared state files, run `git pull` on the default branch to get the latest docs/features.md and docs/dependency-map.md (per project-brief.md → Key Technical Decisions; default: main).
+
+### Owner Assignment
+- When adding new rows to docs/features.md, set the Owner column to your name
+- When adding new modules to docs/dependency-map.md, set the Owner column to your name
+- Do NOT modify rows owned by other developers — if there is a dependency, note it in your task description instead
+
+### Cross-Developer Dependencies
+If your feature depends on a module owned by another developer:
+1. Note the dependency in the task description (e.g., "Depends on [module] owned by [dev]")
+2. Coordinate with the module owner before implementation
+<!-- TEAM_MODE_END -->

package/harness/skills/impact-analysis.md

@@ -0,0 +1,110 @@
+# Impact Analysis
+
+## Purpose
+
+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 10: for each existing module being modified
+- **reviewer** agent — Step 7: when interface changes affect 2+ dependent modules
+- **architect** agent — when structural validation requires blast radius analysis
+
+## When to Apply
+
+- Adding, removing, or changing a module's public interface
+- Modifying shared types, entities, or DTOs
+- Refactoring that touches more than 2 files
+- When a test fails in a module you didn't directly change
+
+## Procedure
+
+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. **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 7
+7. **Trace each dependent** (direct dependents only):
+   - List files in each dependent module that import from the target
+   - Identify which functions/types they use
+   - Determine if the interface change breaks them
+   - Note: Transitive dependents (modules importing from a dependent, not the target) are not traced here. Check them later if direct dependent interfaces also change.
+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)
+- [ ] All changes within current Story scope
+- [ ] Escalated to user if scope exceeds current Story
+
+## Example
+
+### Good
+```
+Target: auth module
+Change: Added `resetPassword(email: string): Promise<void>`
+Dependents: api, admin
+Impact:
+  - api/routes/auth.ts imports AuthService → needs new route
+  - admin/controllers/user.ts imports AuthService → needs admin endpoint
+  - tests/__mocks__/AuthService.ts → needs new mock method
+Plan: 4 files to update, all within S3-2 scope
+```
+
+### Bad
+```
+"I'll just add this method and see what breaks."
+→ Tests fail in 3 modules, mock out of sync, 2 hours wasted
+```
+
+## State File Updates (mandatory)
+
+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 ("In Progress" until all dependents updated, then "Updated"). **This is mandatory for ALL interface changes** — do not skip even if the change seems minor. **Status transition**: impact-analysis sets the initial status to "In Progress". After all dependent modules are verified updated (by reviewer Step 7 or test-integrity), update Status to "Updated".
+- [ ] **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.
+
+### 🧭 Navigation — After Impact Analysis
+
+Impact-analysis is invoked BY `planner` (Step 9) or `reviewer` (Step 7). After completion, control returns to the caller's flow.
+If invoked directly by the user, append:
+
+```
+---
+🧭 Next Step
+→ Next: `planner` or `reviewer`
+→ Prompt: "영향도 분석 결과를 반영해줘"
+→ Why: Blast radius mapped — incorporate into plan or review
+→ Pipeline: N/A (utility skill — invoked by planner Step 9 or reviewer Step 7)
+---
+```
+
+## Related Failure Patterns
+
+- 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)
+
+<!-- TEAM_MODE_START -->
+## Team Mode: Impact Analysis
+
+### Owner-Aware Blast Radius
+- When listing affected modules from docs/dependency-map.md, check the Owner column
+- If a dependent module is owned by another developer, the blast radius extends to their scope
+- Flag cross-owner impacts: "⚠️ Module [X] owned by [dev] will be affected"
+
+### Notification
+- For interface changes affecting modules owned by other developers, **list them explicitly** in the analysis output
+- Recommend notifying affected module owners before proceeding with changes
+<!-- TEAM_MODE_END -->

package/harness/skills/investigate.md

@@ -0,0 +1,172 @@
+# Investigate
+
+## Purpose
+
+Debug bugs systematically. Prevent "symptom patching" — fixing without understanding root cause.
+4-phase debugging process inspired by gstack's /investigate.
+
+## Invoked By
+
+- **User** (direct) — "이 버그 조사해줘", "왜 실패하는지 찾아줘"
+- **sprint-manager** — bug blocking progress 시 권장
+- **core-rules** (3-Failure Stop) → investigate Recalculating Mode
+
+## When to Apply
+
+- Test failures with unclear cause
+- Runtime errors
+- Regression bugs ("it worked yesterday")
+- Unexplained behavior
+
+### Edge Case: No Reproducible Error
+
+If the user reports "weird behavior" but there is no error message or stack trace:
+1. Ask the user to clarify: (A) Performance issue? (B) Logic error — show expected vs actual output? (C) Intermittent/race condition?
+2. For (A): Profile or add timing logs, then proceed to Phase 1 with timing data as "evidence"
+3. For (B): Use expected vs actual output as the error evidence for Phase 1
+4. For (C): Add logging to capture the intermittent state, attempt reproduction 3 times before escalating.
+   **Async race condition example**:
+   ```
+   Evidence: "Data shows stale value intermittently (1 in 5 runs)"
+   Logging: Add timestamp + thread/event-loop ID at read/write points
+   Reproduction: Run 5 times with logging enabled
+   If reproduced: capture the interleaving sequence → Phase 2
+   If not reproduced after 5 attempts: escalate to user with collected logs
+   ```
+
+## Procedure
+
+### Phase 1: Evidence Collection (NO FIXES)
+
+> **failure-patterns.md responsibility**: investigate READS patterns (Phase 1) to see if this is a known bug, and WRITES updates (Phase 4) to record new patterns. The `reviewer` agent only READS patterns (Step 5) as a warning check. The `learn` skill WRITES patterns only for failures NOT already recorded by investigate in the same session.
+
+1. Record the full error message (first 500 chars) and top 5-10 stack frames
+2. Trace the code path backwards from the error
+3. Check recent changes: `git log --oneline -20 -- <related files>`
+4. Verify the bug is reproducible
+
+**Do NOT modify code in this phase.**
+
+### Phase 2: Scope Lock
+
+1. Identify the module/directory containing the root cause
+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, **STOP and ask the user**: (1) expand scope to include the module, or (2) report to the module owner. Do not proceed without user approval (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
+
+1. State the root cause hypothesis:
+   - **Simple bugs**: One sentence is sufficient (e.g., "findById returns null but no null check exists")
+   - **Complex bugs** (race conditions, multi-module cascades): One-sentence SUMMARY followed by supporting context (reproduction steps, timing data, affected modules). Max 5 lines total.
+2. Implement the minimal fix based on the hypothesis
+3. Verify the fix does not break existing tests
+
+### Phase 4: Verify + Record
+
+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 docs/failure-patterns.md
+
+## Checklist
+
+- [ ] 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
+- [ ] Escalated to user after 3 failed attempts
+
+## Example
+
+### Good
+```
+Phase 1: TypeError: Cannot read property 'id' of undefined at UserService.ts:45
+Phase 2: Scope → src/application/services/UserService.ts, src/domain/entities/User.ts
+Phase 3: Hypothesis — findById returns null but no null check exists
+         Fix — add null guard at UserService.ts:44
+Phase 4: Tests pass, null case test added
+```
+
+### Bad
+```
+"Error occurred so I added an if statement."
+→ Root cause unknown, no reproduction conditions recorded, same error possible elsewhere
+```
+
+## State File Updates (mandatory)
+
+After the fix is verified (Phase 4):
+
+- [ ] **docs/failure-patterns.md**: If the root cause is a repeatable pattern, add a new FP-NNN entry or increment the Frequency of an existing one. Increment Frequency if the ROOT CAUSE is the same (e.g., all SQL injection bugs = same FP-NNN regardless of which module). Different root causes = different patterns. This is NOT optional. **Note**: When investigate updates failure-patterns.md here, the `learn` skill (Step 3) will skip re-incrementing this same pattern for this session to avoid double-counting.
+- [ ] **docs/project-state.md**: Add the fix to Recent Changes with the root cause hypothesis.
+
+## Recalculating Mode (invoked by 3-Failure Stop)
+
+When investigate is triggered by another skill/agent's 3-Failure Stop (not by a user-reported bug):
+
+**Required input**: The caller MUST provide a failure context summary:
+```
+[Recalculating Mode]
+Failed Attempt 1: [approach] → [error message]
+Failed Attempt 2: [approach] → [error message]
+Failed Attempt 3: [approach] → [error message]
+```
+This input is mandatory — if not provided, ask the caller to supply it before proceeding.
+
+1. **Read the failure context first** — understand what was already tried and why it failed
+2. Skip Phase 3 (Hypothesis + Fix) — do NOT attempt a fix
+3. Complete Phase 1 (Evidence) and Phase 2 (Scope Lock) to diagnose the blocker
+4. Propose 1-2 **alternative approaches** that are fundamentally different from ALL 3 failed attempts
+5. Present to the user for decision — do not auto-execute the alternatives
+6. If investigate itself hits 3 failures in this mode → **full stop**, no further recursion
+
+## Enforced Rules
+
+- **3-Failure Stop**: If the same fix approach fails 3 times, stop and report to the user. Do not keep trying.
+- **Concreteness**: Specify exact file paths and line numbers. Quote error messages. Specify expected vs actual types.
+- **Scope Lock**: Do not modify files outside the identified problem scope (Phase 2).
+
+### 🧭 Navigation — After Investigate
+
+After investigation and fix, always append a 🧭 block:
+
+| Investigate Result | 🧭 Next Step |
+|---|---|
+| Fix applied, tests pass | `reviewer` — "수정한 코드를 리뷰해줘" |
+| Root cause found but fix is out of scope | User decision — "수정 범위가 Story 밖입니다. scope를 확장하겠습니까?" |
+| 3 attempts failed | 🛑 User escalation — "3회 시도 실패. 다른 접근법을 논의합시다" |
+| Invoked by 3-Failure Recalculating | Diagnose blocker → propose 1-2 alternative routes → user decides |
+
+Example 🧭 block:
+```
+---
+🧭 Next Step
+→ Next: `reviewer`
+→ Prompt: "수정한 코드를 리뷰해줘"
+→ Why: Bug fix applied — review before commit
+→ Pipeline: 🔴 Step 3/4
+---
+```
+
+## Related Failure Patterns
+
+- 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
+
+<!-- TEAM_MODE_START -->
+## Team Mode: Investigation
+
+### Owner Awareness
+- In Phase 2 (Scope Lock), check docs/dependency-map.md Owner column for the affected module
+- If the root cause module is owned by another developer, **notify them** before applying a fix
+- If the bug is in a shared module (no single Owner), document the fix in your PR description so the team can review
+
+### Personal State
+- Record new failure patterns in your personal .harness/failure-patterns.md
+- If the pattern affects the whole team, promote it (see learn skill Team Mode section)
+<!-- TEAM_MODE_END -->