@kodevibe/harness

kode:harness

Your AI coding agent forgets everything between sessions. kode:harness makes it remember — goals, decisions, failures, and project direction.

Pre-1.0 guardrails for AI coding agents, designed for real project pilots and teams that need direction, proof, and memory across sessions. Prevents context rot, enforces project direction, and persists state across sessions. Works with Copilot, Claude, Cursor, Codex, Windsurf, and Gemini. Zero dependencies.

Where this fits. kode:harness is the execution layer of the kode:vibe ecosystem — it sits between a planning layer (PRD / architecture / ARB) and an infrastructure layer (CI / runtime). kode:harness keeps the AI on direction while you code; the other layers are optional. You can use kode:harness alone.

Pre-1.0 stability notice. Active 0.x development. CLI flags, state files, and skill/agent contracts may change between minor versions. v1.0.0 ships only after 30 days of frozen IDE compatibility matrix + external production usage.

Quick Start

npx @kodevibe/harness init          # pick your IDE

# Then tell your AI agent:
> "Run setup to onboard this project."

That's it. Your AI now has persistent memory, direction guardrails, and self-correction loops.

New to kode:harness? Start with docs/GETTING_STARTED.md, then read docs/PROOF_LEDGER_WALKTHROUGH.md for the proof-first loop. Teams should also read docs/TEAM_ONBOARDING.md. For install and uninstall trust boundaries, see docs/SAFETY_GUIDE.md.

v0.11 adds Proof-First Enforcement on top of the Common Mode Confidence Loop: pm must define runnable proof, lead cannot mark a Story done without passing evidence, reviewer blocks commit guidance when proof is missing or failing, and state-check audits Proof Ledger coverage.

# Team mode (multi-developer direction alignment)
npx @kodevibe/harness init --team

# Non-interactive (CI/scripts)
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

Upgrade an existing install

If you already have kode:harness installed, running init again refreshes IDE configuration files while preserving project state and agent memory. No data loss by default — only IDE config files are updated, and previous versions are automatically backed up.

Safe re-init (recommended for version upgrades)

npx @kodevibe/harness init --ide <vscode|claude|cursor|codex|windsurf|antigravity> --batch

State files and agent memory remain intact.

Force overwrite (caution)

npx @kodevibe/harness init --ide vscode --batch --overwrite

--overwrite will erase your current project-state.md, failure-patterns.md, and agent memory files. Recover the previous versions from .harness/init-backups/<ISO-timestamp>/ if needed.

Uninstall Safely

Every init now writes .harness/install-manifest.json, which records the generated files, hashes, IDE target, mode, and backup paths. uninstall uses that manifest to remove only kode:harness-managed files.

# Preview first. No files are changed.
npx @kodevibe/harness uninstall --ide claude --dry-run

# Apply. State files and agent memory are preserved by default.
npx @kodevibe/harness uninstall --ide claude --yes

Safety rules:

• docs/project-state.md, docs/project-brief.md, docs/features.md, docs/dependency-map.md, docs/failure-patterns.md, and agent memory are kept by default.
• Existing root files such as CLAUDE.md or AGENTS.md are restored from .harness/init-backups/<timestamp>/... when init overwrote them.
• Files modified after install are skipped unless --force is used.
• Shared cross-tool paths such as AGENTS.md and .agents/skills/* are kept while another active IDE install still owns them.
• Deleted/restored files are copied to .harness/uninstall-backups/<timestamp>/... before changes are applied.

Additional options:

npx @kodevibe/harness uninstall --all --dry-run       # preview all detected IDE installs
npx @kodevibe/harness uninstall --ide vscode --yes    # remove one IDE surface
npx @kodevibe/harness uninstall --ide vscode --yes --purge-state
npx @kodevibe/harness uninstall --all --yes --purge-state --purge-backups

Use --purge-state only when you intentionally want to delete generated state files too. Backup directories are kept unless --purge-backups is explicitly provided. Combining --purge-state --purge-backups removes .harness/install-manifest.json too once no active installs remain, leaving no kode:harness state behind.

The Problem: Context Rot

Your AI coding agent starts every session from zero. By session 3, it's forgotten the architecture decisions from session 1. By session 10, it's re-debating settled choices and contradicting its own earlier work.

In teams, it's worse — Developer A's AI refactors toward microservices while Developer B's AI doubles down on the monolith. Without shared guardrails, AI agents pull the project apart.

kode:harness solves this with three mechanisms:

Why not just...?

What It Does

Health Check

npx @kodevibe/harness doctor    # verify files are installed
npx @kodevibe/harness validate  # verify state files have real content
npx @kodevibe/harness uninstall --dry-run --ide vscode  # preview safe removal

Installed projects can run the same deterministic guard without cloning this repo:

npx @kodevibe/harness guard --dir .
npx @kodevibe/harness guard --all --dir .
npx @kodevibe/harness guard --wrap-up --dir .
npx @kodevibe/harness guard --state-sync --dir .

To enforce the same checks in GitHub Actions, copy templates/github-actions/kode-harness-guard.yml to .github/workflows/kode-harness-guard.yml in the target project. The template blocks PRs/pushes when deterministic proof/state/security/policy checks fail:

- run: npx --yes @kodevibe/harness guard --all --dir .
- run: npx --yes @kodevibe/harness guard --state-sync --dir .

Source repo maintainers can also run the deterministic guard and model-tier evidence checks:

npm run harness:check-pack
npm run harness:guard:all
npm run harness:guard:wrap-up -- --quiet
npm run harness:state-sync
npm run harness:dependency-scan
npm run harness:llm-bench:smoke

For release evidence, replace the example fixture with sealed results from at least three real model tiers. Each run must use the standard scenarios in docs/llm-bench-scenarios.json and include capturedAt, a matching promptHash, and outputHash or transcriptHash.

npm run harness:llm-bench:export
node scripts/llm-bench.js --collect-results --model-id local-small-2026-06-08 --tier constrained --outputs bench/r10/local-small-2026-06-08 --out docs/llm-bench-results.json --append
npm run harness:llm-bench:real

See docs/LLM_BENCH_GUIDE.md for the full three-model evidence workflow.

Supported IDEs

Not sure which to pick? Use the IDE you already code in — each install path is generated from the same harness/ source, so the underlying skills/agents are identical:

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)

• setup — Onboard project into kode scans codebase + fills state files automatically
• wrap-up — 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
• sync-tests — Verify mock/interface synchronization before committing
• secure — Pre-commit security risk scan
• security-policy — Apply company security policy packs to auth, PII, secrets, sessions, DB, logs, and workflow evidence
• ci-workflow — Create, review, or drift-check GitHub Actions/container CI workflows from sealed company CI/CD policy pages
• e2e-proof — Prove running UI/API/login flows with URL, scenario, observed result, and test data setup
• context-handoff — Create compact state-based handoff when a long LLM session hits context limits
• debug — 4-phase systematic debugging (evidence → scope → fix → verify)
• check-impact — Assess change blast radius before modifying shared modules
• breakdown — Decompose features into dependency-ordered implementation tasks
• docs-bridge — Create a local index that can connect repository docs to a wiki/docs hub while preserving originals and visibility boundaries
• pr-review — Review incoming Pull Requests for quality, security, and direction alignment
• release — Pre-release validation checklist (tests, state files, security, versioning)

Agents (role-based personas)

• pm — Feature planning, dependency analysis, Direction Alignment (goal/non-goal/decision check)
• reviewer — Code review + State File Audit (verifies state files were actually updated)
• lead — 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")

project-brief.md can also carry a Project Docs Hub Index when you want local docs discoverable from a wiki, Confluence space, Obsidian vault, or other documentation hub. The tracked index stores repo-relative sources and sanitized hub aliases only; machine-specific resolver details belong in ignored .harness/docs-bridge.local.* files.

How It Works

1. Bootstrap (once)

After harness init, run the setup 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

setup → pm → [code] → reviewer → lead → wrap-up

kode:harness provides 5 pipelines for different scenarios:

Each step ends with a Navigation block telling you exactly what to do next — including the prompt to type.

• pm: Checks direction alignment, breaks down features. Confirm-First gate — won't proceed without your approval.
• reviewer: Reviews code + audits state file updates
• lead: Tracks progress via Wave-Level Pacing — runs tests between implementation waves
• wrap-up: Captures lessons before session ends
• debug: 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.

npx @kodevibe/harness init --team

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 11 rules are enforced across all skills and agents. They form the quality backbone of every kode:harness project managed with harness engineering.

Documentation

Package users can start with this README. Repository maintainers can use the GitHub-only docs/wiki-index.md as the source repo documentation map; it links the contribution guide, architecture notes, release history, and local docs hub boundaries without installing active harness instructions into this repo.

Why We Built This

Existing AI coding frameworks focus on what the AI does — generate code, run tests, deploy. But the real problem isn't capability. It's direction.

When one developer uses AI, direction stays consistent. But in teams, each developer's AI drifts independently. And even solo developers lose direction across sessions — what we call Context Rot. The AI forgets architecture decisions, re-debates settled choices, and contradicts its own earlier work.

kode:harness focuses on where the AI is going. It gives every AI session — across developers, across IDEs, across time — the same goals, decisions, and project state. The underlying discipline is harness engineering: lightweight, markdown-native guardrails that any LLM can read.

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:

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.

Project Docs Bridge

When a project already has useful docs spread across README files, docs/, ADRs, runbooks, API specs, or planning artifacts, run docs-bridge:

> "connect this project's docs to our wiki/docs hub"

It adds a Project Docs Hub Index to project-brief.md with each local source, role, sanitized hub target, sync direction, visibility, status, and review date. The repository keeps the originals. External hub summaries or links are written only when the user explicitly asks and visibility boundaries are confirmed.

How It Compares

Roadmap

kode:harness is at v0.11.10 — extends v0.11.9 POC readiness with explicit CI workflow CREATE/REVIEW/DRIFT-CHECK routing across pm, lead, reviewer, wrap-up, and release.

What's Next

• Pilot: Run v0.11 proof-first Common Mode on a real project and measure proof coverage
• 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
• Discussions & ideas → GitHub 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