AI harness framework for brownfield feature work with on-demand discovery, bounded context, multi-host adapters, CaveBus summaries, and verification evidence.
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.
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.
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.
npm install -g @feneto/lh
lh --help
lh doctorInitialize in a target project:
lh init --host allLeanHarness 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
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- 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
Rebuild the graph when:
- Starting work in a new codebase
- After large refactors
- If discovery seems to miss relevant files
lh doctorreports graph files missing
# 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 --validateImportant:
lh buildwithout--dry-runinvokes an external agent host. Always dry-run first.lh checkis the completion gate. Do not mark work done without a passing check.- Use dry-runs before invoking real agent hosts.
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 enforcementOr via .lh/config.yml:
boundary_enforcement:
mode: warn # strict | warn | off
always_allow: # glob patterns always permitted
- "**/*.test.ts"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.
The password reset example shows a complete feature lifecycle with all artifacts:
- 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:
npm install
npm run build
npm run typecheck
npm test
npm run test:watch
node dist/index.js doctorSee CONTRIBUTING.md for development setup and contribution guidelines.
LeanHarness uses Changesets for automated releases:
- Add a changeset in your feature PR:
npm run changeset
- Merge PRs to
main. - GitHub Actions opens/updates a "Version Packages" release PR.
- 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.
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-modeorboundary_enforcement.modein.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
.envand credential files. lh checkrequires 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.