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.