LeanHarness

AI harness framework for brownfield feature work with on-demand discovery, bounded context, multi-host adapters, CaveBus summaries, and verification evidence.

Status

v1.3.0 — configurable boundary enforcement. The core workflow is implemented with a deterministic CLI, two agent host adapters (Claude Code, OpenCode), configurable boundary enforcement modes, and a comprehensive test suite.

What it does

LeanHarness provides workflow, artifacts, boundaries, compression, verification, and guardrails around AI coding agents.

The agent provides coding power. LeanHarness provides discipline.

A developer gives a feature request. LeanHarness guides the agent through a structured workflow:

Specify → Discover → Build → Check

Each phase produces artifacts. Each artifact is bounded. The result is verifiable feature delivery, not a sprawling code generation session.

Why brownfield-first

Most software work happens in existing codebases. LeanHarness is designed for brownfield environments:

• No full-repo scan required. On-demand discovery finds only relevant files.
• Respects existing project structure, conventions, and tooling.
• Uses change boundaries to limit agent scope.
• Escalates discovery only when the current boundary is insufficient.

Greenfield projects work too — they are the simpler case.

Quick start

npm install -g @feneto/lh
lh --help
lh doctor

Initialize in a target project:

lh init --host all

Graph System

LeanHarness maintains a code graph for smarter discovery and bounded context:

• Import graph — File-level dependencies and import relationships
• Symbol graph — Class, function, and interface tracking (TypeScript AST-based)
• Knowledge graph — Cross-feature patterns and decisions

Commands

lh graph build          # Build graphs from scratch
lh graph update         # Incremental update (detects changes)
lh graph inspect        # Show graph statistics
lh graph clear          # Remove graph files

How it's used

• Discovery: Graph scoring boosts files near your change boundary
• Context compiler: Knowledge graph adds relevant patterns to task context
• Symbol lookup: Find class/interface/function declarations via AST
• Call graph: Track function calls and type references

When to rebuild

Rebuild the graph when:

• Starting work in a new codebase
• After large refactors
• If discovery seems to miss relevant files
• lh doctor reports graph files missing

Core workflow

# Create a feature spec
lh spec "Add password reset without replacing existing auth" --title "Password reset"

# Discover relevant code and produce change boundary
lh discover F001 --depth D2

# Create plan and task breakdown
lh plan F001

# Preview build without invoking agent (always dry-run first)
lh build F001 --host claude-code --dry-run

# Or with OpenCode
lh build F001 --host opencode --opencode-agent lh-builder --dry-run

# Run real build (invokes agent host)
lh build F001 --host claude-code

# Verify against acceptance criteria (completion gate)
lh check F001

# Generate compact CaveBus summaries
lh compress F001

# Validate CaveBus log
lh cavebus F001 --validate

Important:

• lh build without --dry-run invokes an external agent host. Always dry-run first.
• lh check is the completion gate. Do not mark work done without a passing check.
• Use dry-runs before invoking real agent hosts.

Boundary enforcement

Change boundaries are enforced via hooks (Claude Code) and plugins (OpenCode). You can configure enforcement strictness:

lh boundary status          # view current config
lh boundary set-mode strict # block edits outside boundary
lh boundary set-mode warn   # warnings only (default)
lh boundary set-mode off    # disable enforcement

Or via .lh/config.yml:

boundary_enforcement:
  mode: warn           # strict | warn | off
  always_allow:        # glob patterns always permitted
    - "**/*.test.ts"

Agent hosts

LeanHarness supports multiple agent hosts through adapters:

| Host | Adapter | Integration | |------|---------|-------------| | Claude Code | src/adapters/claude-code.ts | Skills, subagents, hooks | | OpenCode | src/adapters/opencode.ts | Agents, guardrail plugin |

Both hosts read and write the same .lh/ artifact store and use the same lh CLI for deterministic operations.

• Agent hosts overview
• Claude Code host
• OpenCode host
• Host adapters

Example

The password reset example shows a complete feature lifecycle with all artifacts:

• Password reset walkthrough
• Password reset example artifacts

Documentation

• Installation
• Commands
• Configuration
• Boundary enforcement
• Graph system
• Host adapters
• Claude Code host
• OpenCode host
• CaveBus protocol
• Dogfooding guide
• Password reset example
• Cookbook
• Troubleshooting
• Release checklist
• Migration guide
• Security and safety
• Contributing

Design documentation:

• Vision
• Workflow
• Architecture
• Principles
• Glossary

Development

npm install
npm run build
npm run typecheck
npm test
npm run test:watch
node dist/index.js doctor

See CONTRIBUTING.md for development setup and contribution guidelines.

Releasing

LeanHarness uses Changesets for automated releases:

1. Add a changeset in your feature PR:

   npm run changeset

2. Merge PRs to main.
3. GitHub Actions opens/updates a "Version Packages" release PR.
4. Merge that release PR to automatically create tag(s), GitHub Release notes, and publish to npm.

Repository maintainers must configure the NPM_TOKEN GitHub Actions secret for publishing.

Safety model

LeanHarness guardrails are best-effort safety measures, not a security sandbox:

• Change boundaries limit which files an agent can modify.
• Boundary enforcement modes — configure strict (block), warn (log), or off (disabled) via lh boundary set-mode or boundary_enforcement.mode in .lh/config.yml.
• Risk gates require approval for high-risk changes (auth, payments, migrations, dependencies).
• Command policies block known-destructive commands.
• Secret protection blocks reads of .env and credential files.
• lh check requires evidence before a feature can pass.

Guardrails are enforced by hooks (Claude Code) and plugins (OpenCode). Agent hosts can still execute code if users approve actions. Use dry-runs before real agent execution.

See docs/security.md for the full safety model.

License

MIT