@kodevibe/harness 0.8.3

package/README.md

@@ -0,0 +1,314 @@
+<div align="right">
+  <a href="README.ko.md"><img src="https://img.shields.io/badge/lang-한국어-blue.svg" alt="한국어"></a>
+</div>
+
+# kode:harness
+
+[![npm version](https://img.shields.io/npm/v/@kodevibe/harness.svg)](https://www.npmjs.com/package/@kodevibe/harness)
+[![npm downloads](https://img.shields.io/npm/dm/@kodevibe/harness.svg)](https://www.npmjs.com/package/@kodevibe/harness)
+[![CI](https://github.com/AIDD-Projects/harness/actions/workflows/ci.yml/badge.svg)](https://github.com/AIDD-Projects/harness/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Keep every developer's AI aligned on one project direction.**
+
+kode:harness is built on **harness engineering** for multi-developer, enterprise-grade AI-assisted development.
+
+> **v0.8.3** — 6 IDE support, Navigation Dispatcher, 5 Pipelines (🟢🔵🔴🟡🟣), Crew Artifact Integration, 100-point quality audit.
+
+## From Harness to Enterprise Harness Engineering
+
+The concept of an AI "harness" — structured markdown files that guide LLM coding agents — has become a foundational pattern in AI-assisted development. Frameworks like BMAD, gstack, and GSD pioneered this approach for **solo developers**.
+
+This approach takes harness engineering beyond solo tooling. It evolves the harness concept into an **enterprise-grade direction management method** for both multi-developer teams and solo developers. **kode:harness** is the product form of that approach.
+
+| | Traditional Harness | kode:harness + harness engineering |
+|---|---|---|
+| Target | Solo developer | **Multi-developer teams** |
+| Focus | What the AI does | **Where the AI is going** |
+| Direction management | ❌ | ✅ Direction Guard + pivot + Decision Log |
+| Team state sharing | ❌ | ✅ Shared/personal state separation |
+| Token budget | 200+ files | **~25 files (~17K tokens)** — works with small LLMs too |
+
+## The Problem
+
+When one developer uses an AI coding assistant, direction stays consistent. But in **enterprise teams**, each developer runs their own AI sessions — and each AI drifts independently. Developer A's AI refactors toward microservices while Developer B's AI doubles down on the monolith. Without shared direction management, **AI agents across multiple developers pull the project apart.**
+
+kode:harness solves this. It gives every developer's AI the same goals, non-goals, decisions, and project state — so all AI sessions converge on **one direction**, regardless of who's coding or which IDE they use.
+
+## What It Does
+
+kode:harness manages your **project's direction** — goals, decisions, scope — so LLM coding agents stay aligned **across developers and sessions**. Zero dependencies, 6 IDE support, native format generation. The underlying approach is harness engineering for multi-developer and enterprise-grade execution.
+
+- **Direction Guard** — Every coding request is checked against project goals/non-goals before execution
+- **Navigation Dispatcher** — 🧭 Turn-by-Turn navigation guides developers through 5 pipelines with explicit next-step prompts
+- **5 Pipelines** — 🟢 New Dev → 🟕 Continue → 🟤 Bug Fix → 🟡 Direction Change → 🟣 Crew-Driven (external planning artifact integration)
+- **Crew Artifact Integration** — Reads external planning output (PRD, Architecture, ARB Checklist) directly — no manual copy needed
+- **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
+- **Decision Log** — Records why decisions were made so LLMs don't re-debate settled choices
+
+## Quick Start
+
+```bash
+# Solo mode (default)
+npx @kodevibe/harness init
+
+# Team mode (multi-developer)
+npx @kodevibe/harness init --team
+```
+
+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
+npx @kodevibe/harness init --ide vscode
+npx @kodevibe/harness init --ide claude
+npx @kodevibe/harness init --ide cursor
+npx @kodevibe/harness init --ide codex
+npx @kodevibe/harness init --ide windsurf
+npx @kodevibe/harness init --ide antigravity
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--ide <name>` | Target IDE: `vscode`, `claude`, `cursor`, `codex`, `windsurf`, `antigravity` |
+| `--mode <mode>` | Project mode: `solo` (default) or `team` |
+| `--dir <path>` | Target directory (default: current directory) |
+| `--team` | Shorthand for `--mode team` |
+| `--batch` | Non-interactive mode (requires `--ide`; defaults to solo mode) |
+| `--overwrite` | Overwrite existing files (including state files) |
+| `--version` | Show version number |
+
+### Health Check
+
+```bash
+# Verify kode:harness files are installed
+npx @kodevibe/harness doctor
+
+# Verify state files have real content (not just placeholders)
+npx @kodevibe/harness validate
+```
+
+### IDE Configuration (Optional)
+
+Large projects with crew artifacts may require increased turn limits:
+
+| IDE | Setting | Recommended |
+|-----|---------|-------------|
+| VS Code | `chat.agent.maxRequests` in settings.json | `100` |
+| Cursor | Auto-managed | Default OK |
+| Windsurf | Auto-managed | Default OK |
+| Claude Code | Terminal-based | Default OK |
+
+> This is only needed when running `bootstrap` with crew artifacts on projects that have many existing frameworks. Normal coding/review operations work within default limits.
+
+## Supported IDEs
+
+| IDE | Dispatcher (always-on) | Skills | Agents |
+|-----|----------------------|--------|--------|
+| **VS Code Copilot** | `.github/copilot-instructions.md` | `.github/skills/*/SKILL.md` | `.github/agents/*.agent.md` |
+| **Claude Code** | `.claude/rules/core.md` | `.claude/skills/*/SKILL.md` | `.claude/agents/*.md` |
+| **Cursor** | `.cursor/rules/core.mdc` | `.cursor/skills/*/SKILL.md` | `.cursor/agents/*.md` |
+| **Codex** | `AGENTS.md` | `.agents/skills/*/SKILL.md` | `.codex/agents/*.toml` |
+| **Windsurf** | `.windsurf/rules/core.md` | `.windsurf/skills/*/SKILL.md` | *(agents installed as skills)* |
+| **Antigravity** | `GEMINI.md` | `.gemini/skills/*/SKILL.md` | `.gemini/agents/*.md` |
+
+All IDEs also get state files (`project-state.md`, `project-brief.md`, `features.md`, `failure-patterns.md`, `dependency-map.md`) in the `docs/` directory.
+
+## What Gets Installed
+
+### Dispatcher (always active)
+- **Core Rules** — 136-line dispatcher: session start guidance, workflow references, state file list, and Iron Laws. Detailed rules are embedded in each skill/agent that enforces them.
+
+### Skills (on-demand procedures)
+- **bootstrap** — Onboard project into kode:harness: scans codebase + fills state files automatically
+- **learn** — End-of-session wrap-up: captures failure patterns, updates project state, detects direction drift
+- **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
+- **code-review-pr** — Review incoming Pull Requests for quality, security, and direction alignment
+- **deployment** — Pre-deployment validation checklist (tests, state files, security, versioning)
+
+### Agents (role-based personas)
+- **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
+- **architect** — Design review gate: validates structural changes against project direction and module boundaries
+
+### 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")
+
+## How It Works
+
+### 1. Bootstrap (once)
+After `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:
+- 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
+```
+bootstrap → planner → [code] → reviewer → sprint-manager → learn
+```
+
+kode:harness provides **5 pipelines** for different scenarios:
+
+| Pipeline | When | Flow |
+|---|---|---|
+| 🟢 New Dev | First feature | bootstrap → planner → sprint-manager → [code] → reviewer → learn |
+| 🔵 Continue | Resuming work | sprint-manager → [code] → reviewer → learn |
+| 🔴 Bug Fix | Debugging | investigate → [fix] → reviewer → learn |
+| 🟡 Direction Change | Goals/tech shift | pivot → planner → sprint-manager → [code] → reviewer → learn |
+| 🟣 Crew-Driven | With external planning artifacts | bootstrap(crew) → planner → sprint-manager → [code] → reviewer → learn |
+
+Each step ends with a 🧭 **Navigation block** telling you exactly what to do next — including the prompt to type.
+
+- **planner**: Checks direction alignment, breaks down features. **Confirm-First gate** — won't proceed without your approval.
+- **reviewer**: Reviews code + audits state file updates
+- **sprint-manager**: Tracks progress via **Wave-Level Pacing** — runs tests between implementation waves
+- **learn**: Captures lessons before session ends
+- **investigate**: **Recalculating Mode** — after 3 failed attempts, proposes alternative approaches
+
+### 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
+
+## Team Mode
+
+This is where harness engineering matters most. When multiple developers each run their own AI sessions, direction divergence is inevitable — unless you have shared guardrails.
+
+```bash
+npx @kodevibe/harness init --team
+```
+
+| | Solo Mode | Team Mode |
+|---|---|---|
+| Shared State | `docs/` (git tracked) | `docs/` (git tracked): project-brief, features, dependency-map |
+| Personal State | `docs/` (git tracked) | `.harness/` (gitignored): project-state, failure-patterns |
+| Agent Memory | `docs/agent-memory/` | `.harness/agent-memory/` |
+| Target | Solo developer | Enterprise team |
+| Team Rules | — | Pre-Pull, Owner, Read-Only, Append-Only, Pivot Lock, FP Promotion |
+
+**How it keeps everyone aligned:**
+
+- **Shared state** (`project-brief.md`, `features.md`, `dependency-map.md`) is git-tracked — every developer's AI reads the same goals, non-goals, and decisions
+- **Personal state** (`project-state.md`, `failure-patterns.md`) goes to `.harness/` (gitignored) — each developer tracks their own sprint progress without conflicts
+- **Pre-Pull Protocol** — Before every session, AI pulls latest shared state so no one works on stale direction
+- **Pivot Lock** — Direction changes require the `pivot` skill, which updates ALL state files atomically and records the decision with reasoning
+- **FP Promotion** — Local failure patterns get promoted to shared `failure-patterns.md` so the whole team learns from each developer's mistakes
+- **Owner Tracking** — Dependency map marks module owners to prevent accidental cross-team overwrites
+
+## Iron Laws
+
+These 8 rules are enforced across all skills and agents. They form the quality backbone of every kode:harness project managed with harness engineering.
+
+| # | Law | Enforced By |
+|---|-----|-------------|
+| 1 | **Mock Sync** — Interface change → update mocks in the same commit | `reviewer`, `test-integrity` |
+| 2 | **Type Check** — Read the source before calling constructors. Never trust memory. | `reviewer` |
+| 3 | **Scope Compliance** — Stay within current Story scope. Report before modifying out-of-scope files. | `sprint-manager`, `reviewer` |
+| 4 | **Security** — No credentials, passwords, or API keys in code or commits. | `security-checklist`, `reviewer` |
+| 5 | **3-Failure Stop** — Same approach fails 3 times → stop and report. | All agents |
+| 6 | **Dependency Map** — New/modified module → update `dependency-map.md` in the same commit. | `reviewer`, `learn` |
+| 7 | **Feature Registry** — New feature → register in `features.md` in the same commit. | `reviewer`, `learn` |
+| 8 | **Session Handoff** — Session end → update `project-state.md` Quick Summary. | `learn` |
+
+## Documentation
+
+See [docs/reference.md](docs/reference.md) for detailed descriptions of every skill, agent, rule, and state file.
+
+## Why kode:harness?
+
+### The Core Insight
+
+Existing AI coding frameworks focus on **what the AI does** (generate code, run tests, deploy). kode:harness focuses on **where the AI is going** — ensuring every developer's AI moves in the same direction. harness engineering is the discipline that keeps the whole team on course.
+
+### Crew Artifact Integration (🟣 Pipeline)
+
+If your team uses an **external planning tool** (or any tool that produces PRD, Architecture, ARB Checklist documents), kode:harness reads them directly:
+
+```bash
+npx @kodevibe/harness init
+# Then ask your LLM:
+> "crew 산출물을 기반으로 프로젝트를 세팅해줘"
+```
+
+Bootstrap auto-detects crew artifacts in `docs/crew/`, `docs/PM/`, `docs/Analyst/`, `docs/ARB/` and creates:
+- **Artifact Index** — maps every crew document with path, role, and key contents
+- **Validation Tracker** — tracks KPI coverage, FR coverage, and ARB Fail resolution across Stories
+
+Original crew documents are **never modified**. Only the index and tracker are created.
+
+### Comparison
+
+| | BMAD v6.2.2 | gstack v0.15.1 | GSD v1.33.0 | kode:harness |
+|---|---|---|---|---|
+| Focus | Enterprise SDLC methodology | 1-person software factory | Full lifecycle automation | **Multi-developer direction alignment** |
+| Files | 200+ | ~40 | Hundreds | ~25 |
+| Dependencies | Node 20+ | Bun + Node + Playwright | Node 18+ | Zero |
+| 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) | ❌ | ❌ | ❌ | ✅ (8 laws embedded in skills) |
+| Cold start | ❌ | ❌ | `/gsd-new-project` | ✅ (`bootstrap` skill) |
+| Context per task | 4-6 files | 1 file | Fresh 200k per plan | 2-3 files (136-line dispatcher) |
+
+## Roadmap
+
+kode:harness is at **v0.8.3** — 6 IDE support complete, Navigation Dispatcher and Crew Artifact Integration stable.
+
+| Phase | Version | Status | Focus |
+|---|---|---|---|
+| **Foundation** | v0.5.0 | ✅ Done | Core framework: 6 IDE support, 8 skills, 3 agents, Team Mode, Direction Guard |
+| **Hardening** | v0.6.5 | ✅ Done | 10 skills, 4 agents, Iron Laws, CLI batch/doctor/validate, merge conflict SOP, direction drift detection |
+| **Flexibility** | v0.7.x | ✅ Done | Delegate team conventions to project-brief.md, remove prescriptive rules |
+| **Navigation** | v0.8.x | ✅ Current | 🧭 Navigation Dispatcher, 5 Pipelines, Crew Artifact Integration, 100-point quality audit, Confirm-First gate, Wave-Level Pacing, Recalculating Mode |
+| **Validation** | v1.0 | 🔜 Next | Real-world project adoption, user feedback collection |
+
+### What's Next
+
+- [ ] Pilot: Run external planning artifacts through kode:harness's 🟣 pipeline on a real project
+- [ ] Adopt kode:harness in real projects and collect usage data
+- [ ] Document case studies: solo vs team, crew vs no-crew
+- [ ] Gather user feedback on friction points and missing features
+- [ ] Iterate based on real-world evidence, not assumptions
+
+## Contributing & Feedback
+
+kode:harness is in active development and we'd love your input.
+
+- **Bug reports & feature requests** → [GitHub Issues](https://github.com/AIDD-Projects/harness/issues)
+- **Discussions & ideas** → [GitHub Discussions](https://github.com/AIDD-Projects/harness/discussions)
+- **Try it on your project** → `npx @kodevibe/harness init` and tell us what works (or doesn't)
+
+We're especially interested in:
+- How Direction Guard performs in teams of 3+ developers
+- Whether the 6 Team Rules (Pre-Pull, Owner, Read-Only, etc.) are sufficient or need more
+- Which IDE integrations need improvement
+- What skills or agents are missing for your workflow
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+const { run } = require('../src/init');
+run(process.argv.slice(2));

package/harness/agent-memory/architect.md

@@ -0,0 +1,42 @@
+# Architect Memory
+
+> Auto-updated by the `learn` skill at session end. Do not edit manually.
+> **Initialization**: After the first architecture review, replace placeholder comments below with real data.
+> **Update trigger**: Only updated when the `architect` agent runs. If architect was not invoked this session, this file stays unchanged.
+
+## Design Decision History
+
+<!-- Record each architecture decision with context and rationale.
+   Format: [Date] Decision — Rationale (alternatives rejected: X, Y)
+   Examples:
+   - [2025-01-15] Chose layered architecture — simpler for 2-person team (rejected: hexagonal, too much boilerplate)
+   - [2025-01-20] Rejected microservices — traffic < 1K req/s, monolith sufficient (revisit when traffic > 10K)
+-->
+
+## Module Boundary Insights
+
+<!-- Record coupling hotspots and stable zones discovered during reviews.
+   Format: Module — Observation — Impact (depended-by count)
+   Examples:
+   - shared/ is coupling hotspot — changes ripple to 5+ modules — consider splitting into shared/types and shared/utils
+   - API layer is stable — rarely modified when business logic changes — safe to skip in impact analysis for domain changes
+-->
+
+## Architectural Anti-patterns Observed
+
+<!-- Record anti-patterns with severity, detection method, and prevention.
+   Format: Pattern — Severity (HIGH/MED/LOW) — Detection — Resolution — Prevention
+   Examples:
+   - Circular dep auth↔user — HIGH — dependency-map bidirectional check — extracted shared types — run impact-analysis before interface changes
+   - God module in utils/ (800+ lines) — MED — file size check — decompose into auth-utils, date-utils, string-utils — enforce max 200 lines per module
+-->
+
+## Architecture Review Trends
+
+<!-- Track patterns across reviews to identify systemic issues.
+   Format: [Sprint] Reviews: N, Issues found: N, Recurring: list
+   Examples:
+   - [Sprint 1] Reviews: 2, Issues: 3, Recurring: none (first sprint)
+   - [Sprint 2] Reviews: 3, Issues: 2, Recurring: circular dependency (2nd occurrence → escalate)
+   Threshold: If same issue recurs 3+ times → add to failure-patterns.md
+-->

package/harness/agent-memory/planner.md

@@ -0,0 +1,47 @@
+# Planner Memory
+
+> Auto-updated by the `learn` skill at session end. Do not edit manually.
+> **Initialization**: After the first sprint completes, replace placeholder comments below with real data.
+> **Update trigger**: Updated when `learn` skill runs after a planner session.
+
+## Estimation Accuracy
+
+<!-- Track estimate vs actual effort per wave to calibrate future planning.
+   Format: [Sprint] Wave N: estimate vs actual (ratio)
+   Examples:
+   - [Sprint 1] Wave 1: accurate (1.0x) — simple CRUD, well-understood domain
+   - [Sprint 1] Wave 3: optimistic (2.3x) — integration complexity underestimated
+   - [Sprint 2] Wave 2: accurate (1.1x) — applied 1.5x buffer from Sprint 1 lesson
+   Rule: If ratio > 2.0x for 2+ sprints → apply mandatory 2x buffer for that wave depth
+-->
+
+## Architecture Insights
+
+<!-- Record structural patterns that affect planning.
+   Format: Pattern — Planning Impact
+   Examples:
+   - Domain → Application → Infrastructure dependency order — plan domain layer first in every feature
+   - Changes to shared/ require full rebuild — always estimate +30 min for shared/ changes
+   - DB migration file creation frequently forgotten — add explicit "create migration" task to every DB-touching story
+-->
+
+## Repeated Patterns
+
+<!-- Track recurring task patterns with frequency to auto-generate checklists.
+   Format: Pattern — Frequency (N/total features) — Action
+   Examples:
+   - New feature = middleware + route + controller + service (4-file set) — 5/5 features — auto-include in breakdown
+   - DB migration forgotten — 3/5 features needing DB — add explicit migration task
+   - Auth middleware required for new routes — 4/6 route additions — default to auth-required
+-->
+
+## Velocity Trends
+
+<!-- Track stories-per-sprint to predict capacity and detect trajectory changes.
+   Format: [Sprint N] Planned: X, Done: Y, Rate: Z%
+   Examples:
+   - [Sprint 1] Planned: 5, Done: 3, Rate: 60% — ramp-up phase, team unfamiliar with codebase
+   - [Sprint 2] Planned: 4, Done: 4, Rate: 100% — right-sized after Sprint 1 data
+   - [Sprint 3] Planned: 4, Done: 5, Rate: 125% — acceleration, consider planning 5 next sprint
+   Benchmark: After 3+ sprints, calculate average rate. If < 60% for 2 consecutive sprints → investigate causes
+-->

package/harness/agent-memory/reviewer.md

@@ -0,0 +1,46 @@
+# Reviewer Memory
+
+> Auto-updated by the `learn` skill at session end. Do not edit manually.
+> **Initialization**: After the first code review, replace placeholder comments below with real data.
+> **Update trigger**: Updated when `learn` skill runs after a reviewer session.
+
+## Project-Specific Review Patterns
+
+<!-- Record patterns specific to THIS project that future reviews should check.
+   Format: Pattern — Location — Severity — Prevention
+   Examples:
+   - SQL injection risk in src/api/routes/ — req.params used directly — HIGH — add parameterized query wrapper
+   - Mock sync miss rate 50% — interface changes in src/domain/ — HIGH — run test-integrity skill pre-commit
+   - Hardcoded timeout 5000ms in tests — tests/integration/ — LOW — extract to test config
+-->
+
+## Frequently Missed Items
+
+<!-- Track items that reviews catch repeatedly to prioritize attention.
+   Format: Item — Frequency (N/total reviews) — Iron Law reference
+   Examples:
+   - docs/features.md update omitted — 3/5 reviews — Iron Law #7
+   - dependency-map.md not updated after new module — 2/5 reviews — Iron Law #6
+   - Test files connecting to real database — 1/5 reviews — testing rules
+   Threshold: If frequency > 50% → recommend adding to pre-commit hook
+-->
+
+## Review Statistics
+
+- Total reviews: 0
+- Auto-fixes applied: 0
+- Escalations: 0
+<!-- Track ratios after 5+ reviews:
+   - Auto-fix rate: auto-fixes / total issues (if > 30% → consider automating those checks)
+   - Escalation rate: escalations / total reviews (if > 20% → investigate root cause)
+-->
+
+## Test Failure Patterns
+
+<!-- Track which test patterns commonly fail during reviews.
+   Format: Pattern — Frequency — Root Cause — Mitigation
+   Examples:
+   - Mock method missing after interface change — 4/10 reviews — FP-001 — run test-integrity pre-commit
+   - Async test timeout — 2/10 reviews — missing await — enforce eslint no-floating-promises
+   - Snapshot mismatch after UI change — 3/10 reviews — stale snapshots — update snapshots in same commit
+-->

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

@@ -0,0 +1,49 @@
+# Sprint Manager Memory
+
+> Auto-updated by the `learn` skill at session end. Do not edit manually.
+> **Initialization**: After the first sprint completes, replace placeholder comments below with real data.
+> **Update trigger**: Updated when `learn` skill runs after sprint management actions.
+
+## Velocity Tracking
+
+<!-- Track planned vs completed stories per sprint.
+   Format: [Sprint N] Done/Planned (Rate%) — Notes
+   Examples:
+   - [Sprint 1] 3/5 (60%) — ramp-up phase, scope adjusted mid-sprint
+   - [Sprint 2] 4/4 (100%) — right-sized after Sprint 1 calibration
+   - [Sprint 3] 5/5 (100%) — team rhythm established
+   Benchmark: Set after 3+ sprints. If rate < 50% for 2 consecutive sprints → flag in sprint-manager recommendations.
+   Average velocity: recalculate after each sprint (e.g., "Average: 4.0 stories/sprint after 3 sprints")
+-->
+
+## Scope Drift History
+
+<!-- Record scope violations caught by sprint-manager or reviewer.
+   Format: [Story ID] Drift type — Files affected — Resolution
+   Examples:
+   - [S1-003] Out-of-scope modification — 3 files in auth/ (not in story scope) — reverted, created new story S1-005
+   - [S2-001] Direction change requested — switched to pivot skill — recorded in Decision Log
+   - [S2-004] Feature creep — added caching (not planned) — extracted to S3-001
+   Pattern: If drift > 2 per sprint → reduce story scope or improve planning precision
+-->
+
+## Recommended Patterns
+
+<!-- Record data-backed recommendations for project workflow.
+   Format: Recommendation — Evidence (N sprints) — Confidence
+   Examples:
+   - Plan 4 stories per sprint — based on 5 sprints: avg 4.2 done, 3 caused underutilization, 5+ caused overrun — HIGH
+   - Stories touching 5+ files should be split — based on S1-003, S2-004 both overran with 6+ files — MEDIUM
+   - Schedule integration stories in Sprint N+1 after domain stories — based on Wave ordering pattern — HIGH
+-->
+
+## Story Sizing Accuracy
+
+<!-- Track if story estimates match actual effort to improve future planning.
+   Format: [Story ID] Estimated: X, Actual: Y, Ratio — Notes
+   Examples:
+   - [S1-001] Estimated: 1 session, Actual: 1 session, 1.0x — simple scaffolding
+   - [S1-002] Estimated: 2 sessions, Actual: 4 sessions, 2.0x — underestimated DB migration complexity
+   - [S2-001] Estimated: 2 sessions, Actual: 2 sessions, 1.0x — applied 1.5x buffer from S1 lesson
+   Rule: If ratio > 2.0x for 3+ stories → adjust estimation method (break into smaller tasks or add buffers)
+-->