Lazy-Harness

AI-first development harness that turns project knowledge, decisions, behavior, tests, and recovery rules into a living framework.

Status: standalone source-of-truth repository extracted from Medivance dogfooding, with framework self-test and host sync validation passing.

What this repo is

lazy-harness is a portable .lazy-harness/ framework body plus project-local operating rules for AI coding agents. It is designed so an agent must consult the host's records before changing code, then preserve newly confirmed knowledge as structured records.

Core goals:

• Context-first work: DDD, SDD, BDD, TDD, ADR, and SSOT records guide every change.
• Progressive knowledge graph: conversations and implementation discoveries become candidate records, then confirmed graph-backed knowledge.
• Regression resistance: fixes require regression registration and protection evidence.
• Portable host sync: the canonical framework in this repository syncs into real host projects such as Medivance.
• Jcode integration: private .jcode/* instructions can load the harness behavior without modifying team-shared files.

Repository layout

.
├── AGENTS.md                 # Root agent policy, mirrors lazy-harness behavior rules
├── README.md                 # GitHub-facing project overview
├── package.json              # Minimal package metadata and test hook
├── src/                      # Small fixture/source surface for framework tests
├── tests/                    # Test fixtures for lazy-harness behavior
└── .lazy-harness/            # Canonical framework body, source of truth
    ├── AGENTS.md             # Installed host agent instructions
    ├── README.md             # Full framework documentation
    ├── JCODE-INTEGRATION.md  # Optional host-side Jcode wiring guide
    ├── framework/            # Framework contract and principles
    ├── decisions/          # 47 ADRs
    ├── domain/               # DDD records
    ├── spec/                 # SDD records and platform specs
    ├── behavior/             # BDD scenarios
    ├── tests/                # TDD plans and mappings
    ├── ssot/                 # Single-source-of-truth records
    ├── knowledge/            # Progressive knowledge graph stores
    ├── manifests/            # Init/sync manifests and skills
    ├── hooks/                # Lifecycle and git hooks
    ├── scripts/              # Doctor, self-test, sync, trigger tooling
    └── schemas/              # JSON/XML schemas

Source-of-truth rule

Framework development happens in a source checkout of this repository. The checkout can live anywhere on each computer.

Dogfooding hosts, for example /path/to/host/.lazy-harness, are installed copies. Do not treat host copies as source. Update them via lazy-sync from the source checkout or lazy update.

Install into a host project

This repository is public and the installer is intentionally generic and secret-free.

Cross-platform prerequisites

Install these before running the installer on a new computer:

• macOS: Bash is already available; install Git and Python 3 with Xcode Command Line Tools/Homebrew, then install Bun.

  xcode-select --install  # if git is missing
  brew install git python@3
  curl -fsSL https://bun.sh/install | bash

• Debian/Ubuntu:

  sudo apt-get update && sudo apt-get install -y git python3 curl unzip
  curl -fsSL https://bun.sh/install | bash

• Fedora:

  sudo dnf install -y git python3 curl unzip
  curl -fsSL https://bun.sh/install | bash

• Arch:

  sudo pacman -S git python curl unzip
  curl -fsSL https://bun.sh/install | bash

The installer checks git, bun, and python3 before mutating the target. Pi/OMP integration additionally requires the chosen agent binary (pi or omp) on PATH; Google ADC MCP imports require gcloud only for authProviderType: "google_credentials" bridges.

From the target project's git root:

curl -fsSL https://raw.githubusercontent.com/lazy-dinosaur/lazy-harness/main/install.sh | bash

Or from a local checkout:

./install.sh --target /path/to/host

Useful options:

./install.sh --target /path/to/host --dry-run
./install.sh --target /path/to/host --force
./install.sh --target /path/to/host --skip-hooks
./install.sh --target /path/to/host --source /path/to/lazy-harness --force

The installer keeps a persistent framework source clone at ~/.cache/lazy-harness/source by default. That lets future lazy-sync operations know which source checkout the host was installed from.

Project-local Jcode wiring is generated by default and kept local/private through .git/info/exclude. The generated .jcode/ includes config, harness instructions, hooks, and lazy-* skills. .jcode/harness/05-lazy-harness.md points at .lazy-harness/AGENTS.md, so framework instruction updates arrive through normal lazy update. Generated .jcode files are refreshed only while they still carry the lazy-harness generated marker; user-owned local edits are preserved. Use --skip-jcode only for hosts that do not use Jcode.

Update an installed host

After installation, update a host from the public main branch with:

cd /path/to/host
.lazy-harness/bin/lazy update

For day-to-day use, this is the command to remember. It refreshes the cached source checkout, syncs .lazy-harness/, and repairs missing generated .jcode/ defaults while preserving host memory and user-owned .jcode files.

Useful update options:

.lazy-harness/bin/lazy update --dry-run
.lazy-harness/bin/lazy update --force
.lazy-harness/bin/lazy update --ref main
.lazy-harness/bin/lazy update --source /path/to/lazy-harness --force

Use --force when the host marker is behind/divergent but you intentionally want to apply the latest framework. lazy update still preserves Category B institutional memory such as domain/spec/behavior/test/decision/SSOT records.

Repair a partial install

If .lazy-harness/ exists but .jcode/ or lazy-* skills are missing, run:

cd /path/to/host
.lazy-harness/bin/lazy update --force

If the host's installed lazy update is very old, use the public installer again. Re-running install is safe with --force because host records are initialized/synced by manifest and .jcode user-owned files are preserved:

cd /path/to/host
curl -fsSL https://raw.githubusercontent.com/lazy-dinosaur/lazy-harness/main/install.sh | bash -s -- --force

Local dogfooding from a checkout:

/path/to/lazy-harness/install.sh --target /path/to/host --source /path/to/lazy-harness --force

Quick validation

Run the primary framework gates from the repo root:

python3 .lazy-harness/scripts/doctor.py --profile smoke
python3 .lazy-harness/scripts/self-test.py --scope framework

Expected smoke output includes:

lazy-harness doctor ok (smoke, scope=framework)

Sync into a host project

Example dogfooding sync into another host:

cd /path/to/host
bun /path/to/lazy-harness/.lazy-harness/scripts/lazy-sync.ts \
  --from /path/to/lazy-harness \
  --target /path/to/host \
  --force
.lazy-harness/bin/lazy test

The sync manifest intentionally includes important explanation and instruction documents such as:

• .lazy-harness/AGENTS.md
• .lazy-harness/README.md
• .lazy-harness/JCODE-INTEGRATION.md
• .lazy-harness/framework/framework-contract.md
• progressive knowledge graph plan/spec/SSOT/schema files

These documents are part of the product contract, not optional extras.

Progressive knowledge graph direction

The current design keeps human-readable layer documents and adds machine-readable graph stores:

• .lazy-harness/knowledge/candidates.jsonl
• .lazy-harness/knowledge/graph-drafts.jsonl
• .lazy-harness/knowledge/graph.jsonl

Canonical graph writes require confirmation. Candidate/draft capture may be automatic, but confirmed project knowledge should be traceable, typed, and conflict-aware.

See:

• .lazy-harness/plans/progressive-knowledge-graph-pipeline.md
• .lazy-harness/spec/platform/progressive-knowledge-graph.md
• .lazy-harness/ssot/knowledge-graph-storage.md
• .lazy-harness/decisions/0028-progressive-knowledge-graph-backbone.md

Jcode private instruction support

For Jcode hosts, prefer private .jcode/* instruction loading over fragile blocking prompt hooks. The harness expects private instructions to remain user-local while shared .lazy-harness/AGENTS.md stays the portable behavior contract.

See .lazy-harness/JCODE-INTEGRATION.md for wiring details.

Development notes

• Do not push host-only institutional memory back into this framework repo unless it belongs to the reusable framework.
• Keep AGENTS.md, README files, integration docs, schemas, specs, and manifests in sync when behavior changes.
• Run focused validation after code or framework changes.
• Do not delete legacy worktrees or host data without explicit confirmation.

License

Private/internal unless a license is added later.