harness-foundry

August 13, 2026 · View on GitHub

harness-foundry

Practical, composable harness engineering for production agents.

The missing runtime layer between model and reliable behaviour.

→ Showcase site · Showcase doc — demos, stacks, full-stack walkthroughs, and stories
→ Launch discussion — Show HN / first-run Q&A

Ecosystem

loop-engineering  →  harness-foundry  →  outerloop
   (patterns)         (runtime)          (governance)

Repo	Role
loop-engineering	Design reliable inner loops
harness-foundry	Execute composable harness primitives
outerloop	Evidence, verdict, answerability

→ Showcase · Core concepts · vs alternatives · architecture

The stack in 60 seconds

Model  →  Primitives  →  Runtime  →  Trace  →  Evidence
         (compose)      (session)    (jsonl)   (outerloop)

Compose harnesses from declarative primitives. Run sessions, record traces, evolve stacks from real runs.

Try it now

npx @cobusgreyling/harness-foundry init --from minimal
# From a loop-engineering pattern (LE → Foundry funnel):
npx @cobusgreyling/harness-foundry init --from loop-engineering:daily-triage
# Or scaffold both from LE:
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --with-foundry
foundry validate
foundry run --goal "Verify harness wiring"
foundry sessions list
foundry trace show --session <id>
foundry evolve report --session <id>

+ Governance: see the with-outerloop example for evidence → verdict → answerability.

+ Cursor / Claude Code:

foundry host integrate cursor    # or claude-code
foundry run --goal "Implement feature X" --host cursor

Or clone and run the full demo:

git clone https://github.com/cobusgreyling/harness-foundry.git
cd harness-foundry && pnpm install && pnpm build && pnpm demo

Demo (terminal)

pnpm demo — full session output

=== 1. Init harness ===
Harness "demo" initialized (minimal)
  .foundry/stack.yaml
  .foundry/stack.lock

=== 2. Validate ===
Stack is valid.

=== 5. Run session ===
Session complete
  ID: 41dfdac5-921e-4e13-9ade-1f7e35932a3c
  Host: standalone
  Status: completed
  Turns: 1

=== 7. Trace ===
session.start → stack.resolved → turn.start
primitive.activate (model/mock) → primitive.complete (model/mock)
primitive.activate (sandbox/worktree-isolated) → ...
session.end

=== 9. Evolve proposal (L2) ===
L2 proposal written — Human gate: review before applying to stack.yaml

→ Full transcript: docs/demo-terminal.txt

→ QUICKSTART.md · Windows

Choose your stack

Persona	Get started
Smoke / CI	`foundry init --from minimal`
Implementer	`foundry init --from implementer`
Review / triage	`foundry init --from reviewer` · `foundry init --from triage`
CI sweeper	`foundry init --from ci-sweeper`
MCP worker	`foundry init --from mcp-worker`
+ Governance	`foundry init --from with-outerloop`
+ IDE host	`foundry host integrate cursor`

Four-layer taxonomy

Layer	Packages	Responsibility
L1 Interface	`interface`	Model providers (mock, anthropic, openai, grok)
L2 Composition	`compose`, `mcp`	Tools, context, catalogue
L3 Execution	`runtime`	Turn loop, sandbox, control
L4 Reliability	`trace`, `evolve`, `emit`	Traces, recovery, evidence

CLI essentials

Command	Purpose
`init`	Scaffold `.foundry/` with stack preset
`validate`	Check stack against primitive catalogue
`run`	Execute session, write trace + lock
`host integrate`	Install Cursor / Claude Code integration
`primitives list` / `show`	Browse available primitives
`sessions list`	List past sessions (from session index)
`trace replay`	Narrative replay of a session
`evolve report`	L1 trace analysis
`evolve proposal`	L2 stack diff (human review)
`completion`	Print bash / zsh / fish completions

→ CLI reference · API · composition

CI integration

jobs:
  foundry-gate:
    uses: cobusgreyling/harness-foundry/.github/workflows/foundry-gate.yml@main

→ docs/github-action.md

Monorepo packages

Package	Responsibility
`@cobusgreyling/harness-foundry-core`	Schemas, types, paths
`@cobusgreyling/harness-foundry-compose`	Stack builder, catalogue, lock
`@cobusgreyling/harness-foundry-interface`	Model adapters
`@cobusgreyling/harness-foundry-mcp`	MCP stdio JSON-RPC client
`@cobusgreyling/harness-foundry-runtime`	Session runner
`@cobusgreyling/harness-foundry-trace`	Trace recorder
`@cobusgreyling/harness-foundry-evolve`	L1/L2 evolution
`@cobusgreyling/harness-foundry-emit`	outerloop evidence
`@cobusgreyling/harness-foundry-host`	Cursor / Claude Code adapters
`@cobusgreyling/harness-foundry`	`foundry` CLI

Status

v0.5.1 — Catalogue depth (≥ 25 primitives), enforced policy primitives, host-bridge traces, session index.

Platform plan (six pillars → v1): catalogue → registry → evolve → fleet → observe → bench.

→ CHANGELOG.md · ROADMAP.md · Platform roadmap

Development

git clone https://github.com/cobusgreyling/harness-foundry.git
cd harness-foundry && pnpm install && pnpm build && pnpm test
pnpm demo
pnpm demo:outerloop   # full stack with outerloop

Dev Container: open in VS Code / GitHub Codespaces — .devcontainer/ runs install + build on create.

→ Contributor start here · CONTRIBUTING.md · Good first issues
Code of Conduct · Security policy

Contributors

Name	GitHub	Role
Cobus Greyling	@cobusgreyling	Creator & maintainer

→ CONTRIBUTORS.md · contributors graph

Contributing philosophy

Primitives are versioned, declarative, and swappable.
Traces drive evolution — report before you tune.
Human gates before stack auto-apply.
Don't want to touch TypeScript? Propose a primitive.

Built on loop-engineering, companion to outerloop, and the broader agentic engineering community.