Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

feat: LE → Foundry funnel (loop-audit 1.7 + loop-init --with-foundry)

Cobus Greyling3e92b24043b8
diff --git a/README.md b/README.md
index 6ef60f0..7cbc1c8 100644
--- a/README.md
+++ b/README.md
@@ -36,9 +36,11 @@
```bash
npx @cobusgreyling/loop-init .
+# Optional: also scaffold a versioned harness (harness-foundry)
+npx @cobusgreyling/loop-init . --with-foundry
```
-`loop-init` scaffolds skills, state, and budget files, then prints your **Loop Ready** score and first loop command. Swap `--tool` for `claude`, `codex`, or `opencode`.
+`loop-init` scaffolds skills, state, and budget files, then prints your **Loop Ready** score and first loop command. Swap `--tool` for `claude`, `codex`, or `opencode`. Use `--with-foundry` when you want the loop as a composable runtime stack.
<p align="center">
<a href="docs/QUICKSTART.md">
@@ -87,8 +89,10 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent
| [Patterns](patterns/README.md) | 7 production patterns + [interactive picker](https://cobusgreyling.github.io/loop-engineering/#interactive) |
| [Starters](starters/) | Clone-and-run kits (Grok, Claude Code, Codex, Opencode) |
| [Opencode examples](examples/opencode/) | CLI-first loops: cron/systemd + `opencode run`, skills, worktrees |
-| [loop-audit](tools/loop-audit/) | Loop Readiness Score CLI (v1.6 — constraints + governance scoring) — `npx @cobusgreyling/loop-audit . --suggest` · `--badge` for README |
-| [loop-init](tools/loop-init/) | Scaffold starters + budget/run-log + constraints (v1.4) — `npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok` |
+| [loop-audit](tools/loop-audit/) | Loop Readiness Score CLI (v1.7 — constraints + governance + **Harness Runtime**) — `npx @cobusgreyling/loop-audit . --suggest` · `--badge` for README |
+| [loop-init](tools/loop-init/) | Scaffold starters + budget/run-log + constraints (v1.5) — `npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok` · **`--with-foundry`** for harness stack |
+| [harness-foundry](https://github.com/cobusgreyling/harness-foundry) | **Companion runtime:** versioned stacks, sessions, traces — `npx @cobusgreyling/harness-foundry init --from loop-engineering:daily-triage` |
+| [outerloop](https://github.com/cobusgreyling/outerloop) | **Companion governance:** evidence → verdict → answerability |
| [loop-cost](tools/loop-cost/) | Token spend estimator — `npx @cobusgreyling/loop-cost` |
| [loop-sync](tools/loop-sync/) | Drift detection between `STATE.md` and `LOOP.md` — `npx @cobusgreyling/loop-sync .` |
| [loop-context](tools/loop-context/) | Stateful memory manager + circuit breaker for long runs — `npx @cobusgreyling/loop-context --check --ledger run.json` |
@@ -97,6 +101,21 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent
| [loop-gate](tools/loop-gate/) | Mechanical enforcement of the path denylist + auto-merge allowlist from `gate.yaml` — `npx @cobusgreyling/loop-gate check --action auto-merge --paths <f1,f2,...>` |
| [Goal Engineering](https://github.com/cobusgreyling/goal-engineering) | **Companion:** loops discover, goals finish — `/goal` + [stack cookbook](https://github.com/cobusgreyling/goal-engineering/blob/main/docs/stack-cookbook.md) (`npx @cobusgreyling/goal doctor .`) |
| [Stories](stories/) | Real wins and honest failures |
+
+### Ecosystem stack
+
+```
+loop-engineering → harness-foundry → outerloop
+ (patterns) (runtime) (governance)
+```
+
+| Layer | You get | Start |
+|-------|---------|--------|
+| **Design** (this repo) | Patterns, starters, Loop Ready score | `npx @cobusgreyling/loop-init .` |
+| **Runtime** | Versioned harness, traces, evolve | `npx @cobusgreyling/loop-init . --with-foundry` or [Foundry showcase](https://github.com/cobusgreyling/harness-foundry/blob/main/docs/showcase.md) |
+| **Govern** | Evidence, verdict, answerability | [outerloop](https://github.com/cobusgreyling/outerloop) |
+
+**Next after Loop Ready 80+:** version the loop as a harness — `loop-init` prints the CTA automatically; `loop-audit` recommends Foundry when the score is strong but `.foundry/stack.yaml` is missing.
| [Contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123) | **Help wanted:** 21 scoped `good first issues` — comment *I'll take this* to get assigned |
| [Community update](https://github.com/cobusgreyling/loop-engineering/discussions/145) | **July 4:** 5.5k stars, traffic sources, contributor merges |
| [Community week (Jul 8)](https://github.com/cobusgreyling/loop-engineering/discussions/219) | loop-worktree npm, MCP quickstart, tool appendices |
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index 2ec897c..0e1a7ca 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -20,6 +20,8 @@ Run this in the root of any git project (no clone required):
```bash
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
+# Optional one-command funnel into harness-foundry:
+npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --with-foundry
```
Swap `--pattern` for any pattern from [patterns/registry.yaml](../patterns/registry.yaml). List all patterns:
@@ -72,6 +74,14 @@ Scores 0–100 with concrete next steps. Re-run after each improvement. Paste a
npx @cobusgreyling/loop-audit . --badge
```
+When the score is **≥ 80**, audit (and `loop-init`) nudge you to version the loop as a [harness-foundry](https://github.com/cobusgreyling/harness-foundry) stack — declarative runtime, traces, outerloop emit:
+
+```bash
+npx @cobusgreyling/loop-init . --with-foundry
+npx @cobusgreyling/harness-foundry validate
+npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"
+```
+
### Catch drift before you schedule (`loop-sync`)
`loop-audit` scores readiness; `loop-sync` checks that your `STATE.md` and `LOOP.md` still agree. When they drift — you edit `LOOP.md` to add a loop but never wire it into `STATE.md`, or a starter update leaves one file behind — a scheduled loop can run against stale instructions.
diff --git a/tools/loop-audit/CHANGELOG.md b/tools/loop-audit/CHANGELOG.md
index 9131c9f..d48dcf0 100644
--- a/tools/loop-audit/CHANGELOG.md
+++ b/tools/loop-audit/CHANGELOG.md
@@ -2,6 +2,14 @@
All notable changes to `@cobusgreyling/loop-audit` are documented here.
+## [1.7.0] - 2026-07-20
+
+### Added
+- **Harness Runtime** scoring signals for the LE → harness-foundry funnel:
+ - `.foundry/stack.yaml`, `stack.lock`, sessions/traces, outerloop emit path, host integrate hints
+- Loop Ready **80+** recommendation / human report CTA → `loop-init --with-foundry`
+- `--suggest` copy commands for Foundry scaffold + first `foundry run`
+
## [1.6.0] - 2026-07-09
### Added
diff --git a/tools/loop-audit/README.md b/tools/loop-audit/README.md
index dbe1dae..9c96e7b 100644
--- a/tools/loop-audit/README.md
+++ b/tools/loop-audit/README.md
@@ -52,7 +52,7 @@ npm run build
npm publish --access public
```
-## Signals Checked (v1.6+)
+## Signals Checked (v1.7+)
| Signal | Notes |
|-------------------------|-------|
@@ -74,6 +74,13 @@ npm publish --access public
| Stall / no-progress detection | loop-context circuit breaker, a ledger, or a documented max-attempts / no-progress rule |
| Human-escalation path | LOOP.md / safety docs define when to stop and hand off to a human |
| **loopActivity (v1.4)** | **Dynamic proof**: "Last run" timestamps in state, loop-related git commits, scheduled workflows, run logs |
+| **Harness Runtime (v1.7)** | `.foundry/stack.yaml`, lock, sessions/traces, outerloop emit, host integrate — LE → [harness-foundry](https://github.com/cobusgreyling/harness-foundry) funnel |
+
+When score ≥ 80 and no `.foundry/stack.yaml`, audit recommends:
+
+```bash
+npx @cobusgreyling/loop-init . --with-foundry
+```
L3 requires verifier + state + cost observability (budget + run log + LOOP.md budget) **and** proven loop activity (not just files on disk).
diff --git a/tools/loop-audit/dist/auditor.d.ts b/tools/loop-audit/dist/auditor.d.ts
index 24e462e..5d68416 100644
--- a/tools/loop-audit/dist/auditor.d.ts
+++ b/tools/loop-audit/dist/auditor.d.ts
@@ -62,6 +62,14 @@ export interface LoopSignals {
present: boolean;
evidence: string[];
};
+ /** harness-foundry runtime signals (LE → Foundry funnel). */
+ harness: {
+ stack: boolean;
+ lock: boolean;
+ sessions: boolean;
+ emit: boolean;
+ host: boolean;
+ };
}
export interface Finding {
level: 'ok' | 'warn' | 'fail';
diff --git a/tools/loop-audit/dist/auditor.js b/tools/loop-audit/dist/auditor.js
index 4b90013..24df9d0 100644
--- a/tools/loop-audit/dist/auditor.js
+++ b/tools/loop-audit/dist/auditor.js
@@ -37,6 +37,12 @@ const SCORE_WEIGHTS = {
constraintsFile: 4,
constraintsSkill: 2,
loopActivity: 6,
+ /** Harness Runtime (harness-foundry) — stack, lock, sessions, emit, host */
+ harnessStack: 4,
+ harnessLock: 1,
+ harnessSessions: 2,
+ harnessEmit: 1,
+ harnessHost: 1,
};
const LEVEL_THRESHOLDS = {
L1: 38,
@@ -162,7 +168,7 @@ async function findSkills(root) {
}
async function detectLoopActivity(root) {
const evidence = [];
- const stateCandidates = [...STATE_FILES, 'STATE.md'];
+ const stateCandidates = [...STATE_FILES];
// 1. Look for "Last run" timestamps or dated entries inside state files (strong real-usage signal)
for (const sf of stateCandidates) {
try {
@@ -278,6 +284,16 @@ export function computeScore(signals) {
score += w.constraintsSkill;
if (signals.loopActivity.present)
score += w.loopActivity;
+ if (signals.harness.stack)
+ score += w.harnessStack;
+ if (signals.harness.lock)
+ score += w.harnessLock;
+ if (signals.harness.sessions)
+ score += w.harnessSessions;
+ if (signals.harness.emit)
+ score += w.harnessEmit;
+ if (signals.harness.host)
+ score += w.harnessHost;
score = Math.min(100, Math.max(0, score));
const costReady = signals.cost.budgetDoc &&
signals.cost.runLog &&
@@ -343,9 +359,6 @@ export async function auditProject(target) {
break;
}
}
- if (!safetyDocPresent) {
- safetyDocPresent = await fileExists(path.join(root, 'docs', 'safety.md'));
- }
const mcpPresent = (await Promise.all(MCP_FILES.map(f => fileExists(path.join(root, f))))).some(Boolean) ||
/MCP|mcp server|plugins & connectors/i.test(loopMdContent);
// Light evidence of worktree usage (common in patterns/starters/LOOP)
@@ -457,6 +470,46 @@ export async function auditProject(target) {
ledgerPresent ||
STALL_HINTS.some((re) => re.test(governanceCorpus));
const escalation = ESCALATION_HINTS.some((re) => re.test(governanceCorpus));
+ // Harness Runtime (harness-foundry) — versioned stack, sessions/traces, outerloop emit, host bridge
+ const foundryStackPath = path.join(root, '.foundry', 'stack.yaml');
+ const harnessStack = await fileExists(foundryStackPath);
+ const harnessLock = (await fileExists(path.join(root, '.foundry', 'stack.lock'))) ||
+ (await fileExists(path.join(root, '.foundry', 'stack.lock.yaml')));
+ let harnessSessions = false;
+ const sessionsDir = path.join(root, '.foundry', 'sessions');
+ if (await fileExists(sessionsDir)) {
+ try {
+ const entries = await readdir(sessionsDir, { withFileTypes: true });
+ harnessSessions = entries.some((e) => e.isDirectory() || (e.isFile() && e.name !== '.gitkeep'));
+ }
+ catch {
+ harnessSessions = false;
+ }
+ }
+ let harnessEmit = false;
+ if (harnessStack) {
+ try {
+ const stackTxt = await readFile(foundryStackPath, 'utf8');
+ if (/emit\/outerloop-evidence|outerloop/i.test(stackTxt))
+ harnessEmit = true;
+ }
+ catch { }
+ }
+ if (!harnessEmit && (await fileExists(path.join(root, '.foundry', 'hooks', 'outerloop.yaml')))) {
+ harnessEmit = true;
+ }
+ const harnessHost = (await fileExists(path.join(root, '.foundry', 'host', 'cursor'))) ||
+ (await fileExists(path.join(root, '.foundry', 'host', 'claude-code'))) ||
+ (await fileExists(path.join(root, '.cursor', 'rules', 'foundry.mdc'))) ||
+ (await fileExists(path.join(root, '.claude', 'foundry.md'))) ||
+ /foundry host integrate|harness-foundry/i.test(loopMdContent);
+ const harness = {
+ stack: harnessStack,
+ lock: harnessLock,
+ sessions: harnessSessions,
+ emit: harnessEmit,
+ host: harnessHost,
+ };
const signals = {
stateFile: { present: statePaths.length > 0, paths: statePaths },
loopConfig: { present: loopMd, path: loopMd ? 'LOOP.md' : undefined },
@@ -475,6 +528,7 @@ export async function auditProject(target) {
cost: { budgetDoc, runLog, loopMdBudget, budgetSkill },
governance: { toolScope, stallDetection, escalation },
loopActivity,
+ harness,
};
if (!signals.stateFile.present) {
findings.push({ level: 'fail', message: 'No state file (STATE.md or pattern-specific state).' });
@@ -603,7 +657,40 @@ export async function auditProject(target) {
else {
findings.push({ level: 'ok', message: `Loop activity detected — real usage signals present (${signals.loopActivity.evidence.length} sources).` });
}
+ if (!signals.harness.stack) {
+ findings.push({
+ level: 'warn',
+ message: 'No harness-foundry stack (.foundry/stack.yaml) — loop is designed but not versioned as a composable harness runtime.',
+ });
+ recommendations.push('Scaffold a harness: npx @cobusgreyling/loop-init . --with-foundry (or npx @cobusgreyling/harness-foundry init --from loop-engineering:daily-triage)');
+ }
+ else {
+ findings.push({ level: 'ok', message: 'Harness stack present (.foundry/stack.yaml).' });
+ if (!signals.harness.emit) {
+ findings.push({
+ level: 'warn',
+ message: 'Harness stack has no outerloop emit path (emit/outerloop-evidence or .foundry/hooks/outerloop.yaml).',
+ });
+ recommendations.push('Add emit/outerloop-evidence to the reliability layer, or enable .foundry/hooks/outerloop.yaml');
+ }
+ else {
+ findings.push({ level: 'ok', message: 'Harness emit path to outerloop present.' });
+ }
+ if (!signals.harness.sessions) {
+ findings.push({
+ level: 'warn',
+ message: 'No harness sessions yet — run foundry once to produce traces.',
+ });
+ recommendations.push('npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring" then re-audit');
+ }
+ else {
+ findings.push({ level: 'ok', message: 'Harness session/trace evidence present.' });
+ }
+ }
const { score, level, assessment } = computeScore(signals);
+ if (score >= 80 && !signals.harness.stack) {
+ recommendations.unshift('Loop Ready 80+: version this loop as a harness — npx @cobusgreyling/loop-init . --with-foundry · showcase https://github.com/cobusgreyling/harness-foundry/blob/main/docs/showcase.md');
+ }
const costReady = signals.cost.budgetDoc &&
signals.cost.runLog &&
signals.cost.loopMdBudget;
diff --git a/tools/loop-audit/dist/cli.js b/tools/loop-audit/dist/cli.js
index a50a2bd..d7f8d12 100644
--- a/tools/loop-audit/dist/cli.js
+++ b/tools/loop-audit/dist/cli.js
@@ -10,7 +10,7 @@ const suggest = args.includes('--suggest') || args.includes('--fix');
const badge = args.includes('--badge');
const help = args.includes('--help') || args.includes('-h');
if (help) {
- console.log(`loop-audit — Loop Readiness Score CLI (v1.6+)
+ console.log(`loop-audit — Loop Readiness Score CLI (v1.7+)
Usage:
loop-audit [path] [options]
@@ -22,6 +22,10 @@ Options:
--badge Markdown README badge (Loop Ready level + score)
--help, -h This help
+New in v1.7:
+ • Harness Runtime signals: .foundry/stack.yaml, stack.lock, sessions/traces, outerloop emit, host integrate
+ • Loop Ready 80+ funnel CTA → harness-foundry (loop-init --with-foundry)
+
New in v1.6:
• Governance signals: least-privilege tool scope, stall / no-progress detection, human-escalation path
@@ -91,6 +95,11 @@ try {
console.log(' npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok');
console.log(' npx @cobusgreyling/loop-cost --pattern daily-triage --level L1');
console.log('');
+ console.log(' # Version as a harness (harness-foundry) — one-command LE → Foundry funnel:');
+ console.log(' npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --with-foundry');
+ console.log(' # or: npx @cobusgreyling/harness-foundry init --from loop-engineering:daily-triage');
+ console.log(' npx @cobusgreyling/harness-foundry validate && npx @cobusgreyling/harness-foundry run --goal "Verify wiring"');
+ console.log('');
console.log(' # IMPORTANT (v1.4): After scaffolding, actually RUN a loop (report-only) and commit the updated STATE.md.');
console.log(' # This creates the "loopActivity" evidence that pushes you toward real L2/L3 scores.');
console.log('');
diff --git a/tools/loop-audit/dist/reporter.js b/tools/loop-audit/dist/reporter.js
index a25b71d..f93e257 100644
--- a/tools/loop-audit/dist/reporter.js
+++ b/tools/loop-audit/dist/reporter.js
@@ -45,6 +45,17 @@ export function formatHuman(r) {
lines.push(`Share: npx @cobusgreyling/loop-audit ${auditTargetArg(r.target)} --badge`);
lines.push('Docs: docs/loop-design-checklist.md');
lines.push('Tip: rerun with --suggest for ready-to-paste copy commands from templates/starters.');
+ if (r.score >= 80 && !r.signals.harness?.stack) {
+ lines.push('');
+ lines.push('Next after Loop Ready 80+: version this loop as a harness');
+ lines.push(' npx @cobusgreyling/loop-init . --with-foundry');
+ lines.push(' Showcase: https://github.com/cobusgreyling/harness-foundry/blob/main/docs/showcase.md');
+ }
+ else if (r.signals.harness?.stack && !r.signals.harness.sessions) {
+ lines.push('');
+ lines.push('Harness stack present — run a session to earn session/trace credit:');
+ lines.push(' npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"');
+ }
lines.push('');
return lines.join('\n');
}
diff --git a/tools/loop-audit/package.json b/tools/loop-audit/package.json
index 5da74d3..e2b39b6 100644
--- a/tools/loop-audit/package.json
+++ b/tools/loop-audit/package.json
@@ -1,7 +1,7 @@
{
"name": "@cobusgreyling/loop-audit",
- "version": "1.6.1",
- "description": "Loop engineering readiness auditor. Compute Loop Readiness Score (L0-L3), detect activity, and get actionable suggestions. npx @cobusgreyling/loop-audit . --suggest",
+ "version": "1.7.0",
+ "description": "Loop engineering readiness auditor. Compute Loop Readiness Score (L0-L3), detect activity + harness runtime, and get actionable suggestions. npx @cobusgreyling/loop-audit . --suggest",
"type": "module",
"bin": {
"loop-audit": "./dist/cli.js"
diff --git a/tools/loop-audit/src/auditor.ts b/tools/loop-audit/src/auditor.ts
index 159b711..30e2862 100644
--- a/tools/loop-audit/src/auditor.ts
+++ b/tools/loop-audit/src/auditor.ts
@@ -29,6 +29,14 @@ export interface LoopSignals {
};
constraints: { present: boolean; hasConstraintsSkill: boolean };
loopActivity: { present: boolean; evidence: string[] };
+ /** harness-foundry runtime signals (LE → Foundry funnel). */
+ harness: {
+ stack: boolean;
+ lock: boolean;
+ sessions: boolean;
+ emit: boolean;
+ host: boolean;
+ };
}
export interface Finding {
@@ -83,6 +91,12 @@ const SCORE_WEIGHTS = {
constraintsFile: 4,
constraintsSkill: 2,
loopActivity: 6,
+ /** Harness Runtime (harness-foundry) — stack, lock, sessions, emit, host */
+ harnessStack: 4,
+ harnessLock: 1,
+ harnessSessions: 2,
+ harnessEmit: 1,
+ harnessHost: 1,
} as const;
const LEVEL_THRESHOLDS = {
@@ -304,6 +318,11 @@ export function computeScore(signals: LoopSignals): { score: number; level: 'L0'
if (signals.constraints.present) score += w.constraintsFile;
if (signals.constraints.hasConstraintsSkill) score += w.constraintsSkill;
if (signals.loopActivity.present) score += w.loopActivity;
+ if (signals.harness.stack) score += w.harnessStack;
+ if (signals.harness.lock) score += w.harnessLock;
+ if (signals.harness.sessions) score += w.harnessSessions;
+ if (signals.harness.emit) score += w.harnessEmit;
+ if (signals.harness.host) score += w.harnessHost;
score = Math.min(100, Math.max(0, score));
@@ -490,6 +509,52 @@ export async function auditProject(target: string): Promise<AuditResult> {
const escalation = ESCALATION_HINTS.some((re) => re.test(governanceCorpus));
+ // Harness Runtime (harness-foundry) — versioned stack, sessions/traces, outerloop emit, host bridge
+ const foundryStackPath = path.join(root, '.foundry', 'stack.yaml');
+ const harnessStack = await fileExists(foundryStackPath);
+ const harnessLock =
+ (await fileExists(path.join(root, '.foundry', 'stack.lock'))) ||
+ (await fileExists(path.join(root, '.foundry', 'stack.lock.yaml')));
+
+ let harnessSessions = false;
+ const sessionsDir = path.join(root, '.foundry', 'sessions');
+ if (await fileExists(sessionsDir)) {
+ try {
+ const entries = await readdir(sessionsDir, { withFileTypes: true });
+ harnessSessions = entries.some(
+ (e) => e.isDirectory() || (e.isFile() && e.name !== '.gitkeep'),
+ );
+ } catch {
+ harnessSessions = false;
+ }
+ }
+
+ let harnessEmit = false;
+ if (harnessStack) {
+ try {
+ const stackTxt = await readFile(foundryStackPath, 'utf8');
+ if (/emit\/outerloop-evidence|outerloop/i.test(stackTxt)) harnessEmit = true;
+ } catch {}
+ }
+ if (!harnessEmit && (await fileExists(path.join(root, '.foundry', 'hooks', 'outerloop.yaml')))) {
+ harnessEmit = true;
+ }
+
+ const harnessHost =
+ (await fileExists(path.join(root, '.foundry', 'host', 'cursor'))) ||
+ (await fileExists(path.join(root, '.foundry', 'host', 'claude-code'))) ||
+ (await fileExists(path.join(root, '.cursor', 'rules', 'foundry.mdc'))) ||
+ (await fileExists(path.join(root, '.claude', 'foundry.md'))) ||
+ /foundry host integrate|harness-foundry/i.test(loopMdContent);
+
+ const harness = {
+ stack: harnessStack,
+ lock: harnessLock,
+ sessions: harnessSessions,
+ emit: harnessEmit,
+ host: harnessHost,
+ };
+
const signals: LoopSignals = {
stateFile: { present: statePaths.length > 0, paths: statePaths },
loopConfig: { present: loopMd, path: loopMd ? 'LOOP.md' : undefined },
@@ -508,6 +573,7 @@ export async function auditProject(target: string): Promise<AuditResult> {
cost: { budgetDoc, runLog, loopMdBudget, budgetSkill },
governance: { toolScope, stallDetection, escalation },
loopActivity,
+ harness,
};
if (!signals.stateFile.present) {
@@ -644,8 +710,46 @@ export async function auditProject(target: string): Promise<AuditResult> {
findings.push({ level: 'ok', message: `Loop activity detected — real usage signals present (${signals.loopActivity.evidence.length} sources).` });
}
+ if (!signals.harness.stack) {
+ findings.push({
+ level: 'warn',
+ message: 'No harness-foundry stack (.foundry/stack.yaml) — loop is designed but not versioned as a composable harness runtime.',
+ });
+ recommendations.push(
+ 'Scaffold a harness: npx @cobusgreyling/loop-init . --with-foundry (or npx @cobusgreyling/harness-foundry init --from loop-engineering:daily-triage)',
+ );
+ } else {
+ findings.push({ level: 'ok', message: 'Harness stack present (.foundry/stack.yaml).' });
+ if (!signals.harness.emit) {
+ findings.push({
+ level: 'warn',
+ message: 'Harness stack has no outerloop emit path (emit/outerloop-evidence or .foundry/hooks/outerloop.yaml).',
+ });
+ recommendations.push('Add emit/outerloop-evidence to the reliability layer, or enable .foundry/hooks/outerloop.yaml');
+ } else {
+ findings.push({ level: 'ok', message: 'Harness emit path to outerloop present.' });
+ }
+ if (!signals.harness.sessions) {
+ findings.push({
+ level: 'warn',
+ message: 'No harness sessions yet — run foundry once to produce traces.',
+ });
+ recommendations.push(
+ 'npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring" then re-audit',
+ );
+ } else {
+ findings.push({ level: 'ok', message: 'Harness session/trace evidence present.' });
+ }
+ }
+
const { score, level, assessment } = computeScore(signals);
+ if (score >= 80 && !signals.harness.stack) {
+ recommendations.unshift(
+ 'Loop Ready 80+: version this loop as a harness — npx @cobusgreyling/loop-init . --with-foundry · showcase https://github.com/cobusgreyling/harness-foundry/blob/main/docs/showcase.md',
+ );
+ }
+
const costReady =
signals.cost.budgetDoc &&
signals.cost.runLog &&
diff --git a/tools/loop-audit/src/cli.ts b/tools/loop-audit/src/cli.ts
index 1ae39fd..48213ce 100644
--- a/tools/loop-audit/src/cli.ts
+++ b/tools/loop-audit/src/cli.ts
@@ -12,7 +12,7 @@ const badge = args.includes('--badge');
const help = args.includes('--help') || args.includes('-h');
if (help) {
- console.log(`loop-audit — Loop Readiness Score CLI (v1.6+)
+ console.log(`loop-audit — Loop Readiness Score CLI (v1.7+)
Usage:
loop-audit [path] [options]
@@ -24,6 +24,10 @@ Options:
--badge Markdown README badge (Loop Ready level + score)
--help, -h This help
+New in v1.7:
+ • Harness Runtime signals: .foundry/stack.yaml, stack.lock, sessions/traces, outerloop emit, host integrate
+ • Loop Ready 80+ funnel CTA → harness-foundry (loop-init --with-foundry)
+
New in v1.6:
• Governance signals: least-privilege tool scope, stall / no-progress detection, human-escalation path
@@ -91,6 +95,11 @@ try {
console.log(' npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok');
console.log(' npx @cobusgreyling/loop-cost --pattern daily-triage --level L1');
console.log('');
+ console.log(' # Version as a harness (harness-foundry) — one-command LE → Foundry funnel:');
+ console.log(' npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --with-foundry');
+ console.log(' # or: npx @cobusgreyling/harness-foundry init --from loop-engineering:daily-triage');
+ console.log(' npx @cobusgreyling/harness-foundry validate && npx @cobusgreyling/harness-foundry run --goal "Verify wiring"');
+ console.log('');
console.log(' # IMPORTANT (v1.4): After scaffolding, actually RUN a loop (report-only) and commit the updated STATE.md.');
console.log(' # This creates the "loopActivity" evidence that pushes you toward real L2/L3 scores.');
console.log('');
diff --git a/tools/loop-audit/src/reporter.ts b/tools/loop-audit/src/reporter.ts
index 348578b..e46826a 100644
--- a/tools/loop-audit/src/reporter.ts
+++ b/tools/loop-audit/src/reporter.ts
@@ -52,6 +52,16 @@ export function formatHuman(r: AuditResult): string {
lines.push(`Share: npx @cobusgreyling/loop-audit ${auditTargetArg(r.target)} --badge`);
lines.push('Docs: docs/loop-design-checklist.md');
lines.push('Tip: rerun with --suggest for ready-to-paste copy commands from templates/starters.');
+ if (r.score >= 80 && !r.signals.harness?.stack) {
+ lines.push('');
+ lines.push('Next after Loop Ready 80+: version this loop as a harness');
+ lines.push(' npx @cobusgreyling/loop-init . --with-foundry');
+ lines.push(' Showcase: https://github.com/cobusgreyling/harness-foundry/blob/main/docs/showcase.md');
+ } else if (r.signals.harness?.stack && !r.signals.harness.sessions) {
+ lines.push('');
+ lines.push('Harness stack present — run a session to earn session/trace credit:');
+ lines.push(' npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"');
+ }
lines.push('');
return lines.join('\n');
}
diff --git a/tools/loop-audit/test/auditor.test.mjs b/tools/loop-audit/test/auditor.test.mjs
index af64144..d0f76fd 100644
--- a/tools/loop-audit/test/auditor.test.mjs
+++ b/tools/loop-audit/test/auditor.test.mjs
@@ -26,6 +26,7 @@ function emptySignals() {
cost: { budgetDoc: false, runLog: false, loopMdBudget: false, budgetSkill: false },
governance: { toolScope: false, stallDetection: false, escalation: false },
loopActivity: { present: false, evidence: [] },
+ harness: { stack: false, lock: false, sessions: false, emit: false, host: false },
};
}
@@ -196,6 +197,47 @@ test('formatBadge: includes level and score', () => {
assert.match(badge, /loop-engineering/);
});
+test('computeScore: harness signals add points', () => {
+ const base = emptySignals();
+ const { score: without } = computeScore(base);
+ const withHarness = emptySignals();
+ withHarness.harness = { stack: true, lock: true, sessions: true, emit: true, host: true };
+ const { score: withScore } = computeScore(withHarness);
+ assert.equal(withScore - without, 9);
+});
+
+test('auditProject: detects .foundry stack and emit hook', async () => {
+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-audit-foundry-'));
+ try {
+ await mkdir(path.join(dir, '.foundry', 'hooks'), { recursive: true });
+ await writeFile(
+ path.join(dir, '.foundry', 'stack.yaml'),
+ 'name: demo\nversion: 1.0.0\nlayers:\n reliability:\n - primitive: emit/outerloop-evidence\n',
+ );
+ await writeFile(
+ path.join(dir, '.foundry', 'hooks', 'outerloop.yaml'),
+ 'enabled: false\nadapter: outerloop\n',
+ );
+ const result = await auditProject(dir);
+ assert.equal(result.signals.harness.stack, true);
+ assert.equal(result.signals.harness.emit, true);
+ assert.equal(result.signals.harness.sessions, false);
+ } finally {
+ await rm(dir, { recursive: true, force: true });
+ }
+});
+
+test('auditProject: missing harness recommends --with-foundry', async () => {
+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-audit-nofoundry-'));
+ try {
+ const result = await auditProject(dir);
+ assert.equal(result.signals.harness.stack, false);
+ assert.ok(result.recommendations.some((r) => r.includes('--with-foundry') || r.includes('harness-foundry')));
+ } finally {
+ await rm(dir, { recursive: true, force: true });
+ }
+});
+
test('auditProject: git commit with triage counts as loop activity', async () => {
const dir = await mkdtemp(path.join(tmpdir(), 'loop-audit-git-'));
try {
diff --git a/tools/loop-init/CHANGELOG.md b/tools/loop-init/CHANGELOG.md
new file mode 100644
index 0000000..88738db
--- /dev/null
+++ b/tools/loop-init/CHANGELOG.md
@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to `@cobusgreyling/loop-init` are documented here.
+
+## [1.5.0] - 2026-07-20
+
+### Added
+- `--with-foundry` — one-command LE → harness-foundry funnel
+ - Scaffolds `.foundry/stack.yaml`, hooks, sessions dir, and README
+ - Pattern mapping: report-only → `minimal`, fix-capable → `implementer`
+- Post-scaffold Foundry CTA on every run (stronger when Loop Ready ≥ 80)
+- Help text for Foundry presets and examples
+
+## [1.4.0]
+
+- Prior release (starters, circuit breaker, intake, observability scaffolds)
diff --git a/tools/loop-init/README.md b/tools/loop-init/README.md
index f458aac..5fab2c1 100644
--- a/tools/loop-init/README.md
+++ b/tools/loop-init/README.md
@@ -13,12 +13,31 @@ npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
npx @cobusgreyling/loop-init . --pattern daily-triage --tool opencode
npx @cobusgreyling/loop-init . -p pr-babysitter -t claude
npx @cobusgreyling/loop-init . -p dependency-sweeper --dry-run
+# One-command LE → harness-foundry funnel:
+npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --with-foundry
```
See [docs/RELEASE.md](../../docs/RELEASE.md) for npm publish tags. The published package bundles `starters/` and `templates/` from this monorepo.
After scaffolding, always run `npx @cobusgreyling/loop-audit . --suggest` and actually execute the first report-only loop to generate activity signals.
+## `--with-foundry` (harness runtime)
+
+Scaffolds a [harness-foundry](https://github.com/cobusgreyling/harness-foundry) stack beside your loop files:
+
+| LE pattern | Foundry preset |
+|------------|----------------|
+| `daily-triage`, `issue-triage`, `changelog-drafter` | `minimal` |
+| `pr-babysitter`, `ci-sweeper`, `dependency-sweeper`, `post-merge-cleanup` | `implementer` |
+
+Creates `.foundry/stack.yaml`, outerloop hook stub, and a short README. Equivalent alias on the Foundry CLI:
+
+```bash
+npx @cobusgreyling/harness-foundry init --from loop-engineering:daily-triage
+```
+
+Every `loop-init` run prints a Foundry CTA; when Loop Ready is **≥ 80**, the CTA is emphasized as the next step after design.
+
## Patterns
| Pattern | Default state file |
diff --git a/tools/loop-init/dist/cli.js b/tools/loop-init/dist/cli.js
index dc72211..b2d9868 100644
--- a/tools/loop-init/dist/cli.js
+++ b/tools/loop-init/dist/cli.js
@@ -55,11 +55,23 @@ const PATTERN_BUDGET = {
'changelog-drafter': { name: 'Changelog Drafter', maxRunsPerDay: 1, dailyCap: 100_000, maxSpawnsL1: 0, maxSpawnsL2: 2 },
'issue-triage': { name: 'Issue Triage', maxRunsPerDay: 12, dailyCap: 80_000, maxSpawnsL1: 0, maxSpawnsL2: 1 },
};
+/** Map LE patterns → harness-foundry stack presets (report-only → minimal, fix → implementer). */
+const PATTERN_FOUNDRY_PRESET = {
+ 'daily-triage': 'minimal',
+ 'issue-triage': 'minimal',
+ 'changelog-drafter': 'minimal',
+ 'pr-babysitter': 'implementer',
+ 'ci-sweeper': 'implementer',
+ 'dependency-sweeper': 'implementer',
+ 'post-merge-cleanup': 'implementer',
+};
+const FOUNDRY_SHOWCASE = 'https://github.com/cobusgreyling/harness-foundry/blob/main/docs/showcase.md';
function parseArgs(argv) {
let pattern = 'daily-triage';
let tool = 'grok';
let target = '.';
let dryRun = false;
+ let withFoundry = false;
for (let i = 0; i < argv.length; i++) {
const a = argv[i];
if (a === '--pattern' || a === '-p')
@@ -68,12 +80,134 @@ function parseArgs(argv) {
tool = argv[++i];
else if (a === '--dry-run')
dryRun = true;
+ else if (a === '--with-foundry')
+ withFoundry = true;
else if (a === '--help' || a === '-h')
- return { help: true, pattern, tool, target, dryRun };
+ return { help: true, pattern, tool, target, dryRun, withFoundry };
else if (!a.startsWith('-'))
target = a;
}
- return { help: false, pattern, tool, target, dryRun };
+ return { help: false, pattern, tool, target, dryRun, withFoundry };
+}
+function foundryStackYaml(stackName, pattern, preset) {
+ if (preset === 'implementer') {
+ return `name: ${stackName}
+version: 1.0.0
+description: "loop-engineering ${pattern} → implementer harness (loop-init --with-foundry)"
+layers:
+ interface:
+ - primitive: model/anthropic
+ config:
+ model: claude-sonnet-4-20250514
+ composition:
+ - primitive: context/state-file
+ - primitive: tools/git-worktree-write
+ execution:
+ - primitive: sandbox/worktree-isolated
+ - primitive: control/token-budget-100k
+ reliability:
+ - primitive: observability/span-per-turn
+ - primitive: recovery/revert-on-test-fail
+ - primitive: emit/outerloop-evidence
+`;
+ }
+ return `name: ${stackName}
+version: 1.0.0
+description: "loop-engineering ${pattern} → minimal harness (loop-init --with-foundry)"
+layers:
+ interface:
+ - primitive: model/mock
+ composition:
+ - primitive: context/state-file
+ execution:
+ - primitive: control/token-budget-100k
+ - primitive: sandbox/worktree-isolated
+ reliability:
+ - primitive: observability/span-per-turn
+ - primitive: emit/outerloop-evidence
+`;
+}
+/**
+ * Scaffold a harness-foundry stack next to loop files so LE graduates land in
+ * a versioned harness in one command (no foundry package dependency).
+ */
+async function scaffoldFoundry(pattern, targetDir, dryRun) {
+ const preset = PATTERN_FOUNDRY_PRESET[pattern];
+ const foundryRoot = path.join(targetDir, '.foundry');
+ const stackFile = path.join(foundryRoot, 'stack.yaml');
+ const stackName = path.basename(targetDir) || 'project';
+ if (await exists(stackFile)) {
+ console.log(` skip: ${stackFile} already exists`);
+ return { preset, stackFile };
+ }
+ const files = [
+ { path: stackFile, content: foundryStackYaml(stackName, pattern, preset) },
+ {
+ path: path.join(foundryRoot, 'hooks', 'outerloop.yaml'),
+ content: `enabled: false
+adapter: outerloop
+emitOn:
+ - session.end
+`,
+ },
+ {
+ path: path.join(foundryRoot, 'README.md'),
+ content: `# Harness stack (from loop-engineering)
+
+Scaffolded by \`loop-init --with-foundry\` for pattern **${pattern}** (preset: **${preset}**).
+
+\`\`\`
+loop-engineering → harness-foundry → outerloop
+ (patterns) (runtime) (governance)
+\`\`\`
+
+## Next
+
+\`\`\`bash
+npx @cobusgreyling/harness-foundry validate
+npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"
+npx @cobusgreyling/harness-foundry evolve report --session <id>
+\`\`\`
+
+Showcase: ${FOUNDRY_SHOWCASE}
+`,
+ },
+ {
+ path: path.join(foundryRoot, 'sessions', '.gitkeep'),
+ content: '',
+ },
+ ];
+ for (const f of files) {
+ if (dryRun) {
+ console.log(` would write: ${f.path}`);
+ continue;
+ }
+ await mkdir(path.dirname(f.path), { recursive: true });
+ await writeFile(f.path, f.content);
+ console.log(` created: ${path.relative(targetDir, f.path)}`);
+ }
+ return { preset, stackFile };
+}
+function printFoundryCta(opts) {
+ const { pattern, tool, withFoundry, score, preset } = opts;
+ const mapped = preset ?? PATTERN_FOUNDRY_PRESET[pattern];
+ console.log('');
+ if (withFoundry) {
+ console.log(`Harness stack ready (.foundry/, preset: ${mapped} for ${pattern})`);
+ console.log(' npx @cobusgreyling/harness-foundry validate');
+ console.log(' npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"');
+ console.log(` Showcase: ${FOUNDRY_SHOWCASE}`);
+ return;
+ }
+ const highReady = score !== null && score >= 80;
+ console.log(highReady
+ ? 'Next after Loop Ready 80+: version this loop as a harness'
+ : 'Optional: make this loop a versioned harness (harness-foundry)');
+ console.log(` npx @cobusgreyling/loop-init . --pattern ${pattern} --tool ${tool} --with-foundry`);
+ console.log(` # or: npx @cobusgreyling/harness-foundry init --from loop-engineering:${pattern}`);
+ if (highReady) {
+ console.log(` Showcase: ${FOUNDRY_SHOWCASE}`);
+ }
}
async function exists(p) {
try {
@@ -386,7 +520,7 @@ async function main() {
console.log(`loop-init — scaffold loop engineering starters
Usage:
- loop-init [target-dir] --pattern <name> --tool <grok|claude|codex|opencode>
+ loop-init [target-dir] --pattern <name> --tool <grok|claude|codex|opencode> [--with-foundry]
Patterns:
daily-triage (default)
@@ -398,19 +532,25 @@ Patterns:
issue-triage (new low-risk issue queue health companion to daily triage)
Options:
- -p, --pattern Pattern to scaffold
- -t, --tool Tool target (default: grok)
- --dry-run Print actions without copying
- -h, --help This help
+ -p, --pattern Pattern to scaffold
+ -t, --tool Tool target (default: grok)
+ --with-foundry Also scaffold .foundry/ stack (harness-foundry runtime)
+ --dry-run Print actions without copying
+ -h, --help This help
+
+Foundry presets (with --with-foundry):
+ report-only patterns → minimal
+ fix-capable patterns → implementer
Examples:
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
- npx @cobusgreyling/loop-init . -p pr-babysitter -t claude
+ npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --with-foundry
+ npx @cobusgreyling/loop-init . -p pr-babysitter -t claude --with-foundry
npx @cobusgreyling/loop-init . -p daily-triage -t opencode
`);
process.exit(0);
}
- const { pattern, tool, target, dryRun } = args;
+ const { pattern, tool, target, dryRun, withFoundry } = args;
const validPatterns = Object.keys(PATTERN_STARTERS);
const validTools = Object.keys(TOOL_SUFFIX);
if (!validPatterns.includes(pattern)) {
@@ -523,10 +663,19 @@ npm run lint
await writeFile(path.join(targetDir, 'AGENTS.md'), agentsTemplate);
console.log(' created: AGENTS.md (template)');
}
+ let foundryPreset;
+ if (withFoundry) {
+ console.log('');
+ console.log('Harness foundry:');
+ const foundry = await scaffoldFoundry(pattern, targetDir, dryRun);
+ foundryPreset = foundry?.preset;
+ }
const auditArg = auditTargetArg(target, targetDir);
+ let auditScore = null;
if (!dryRun) {
const audit = await runAuditSummary(targetDir);
if (audit) {
+ auditScore = audit.score;
console.log('');
console.log(`✓ Loop Ready: ${audit.score}/100 (${audit.level})`);
console.log(` ${formatScoreBar(audit.score)}`);
@@ -554,6 +703,13 @@ npm run lint
console.log(` ${firstLoopCommand(pattern, tool)}`);
console.log('');
console.log(`Estimate cost: npx @cobusgreyling/loop-cost --pattern ${pattern} --level L1`);
+ printFoundryCta({
+ pattern,
+ tool,
+ withFoundry,
+ score: auditScore,
+ preset: foundryPreset,
+ });
printContributorCta();
}
async function readDirNames(dir) {
diff --git a/tools/loop-init/package.json b/tools/loop-init/package.json
index 2d4691a..837aef4 100644
--- a/tools/loop-init/package.json
+++ b/tools/loop-init/package.json
@@ -1,7 +1,7 @@
{
"name": "@cobusgreyling/loop-init",
- "version": "1.4.0",
- "description": "Scaffold loop engineering patterns and starters into any project. Supports Grok, Claude Code, Codex, Opencode and more. npx @cobusgreyling/loop-init . --pattern daily-triage --tool opencode",
+ "version": "1.5.0",
+ "description": "Scaffold loop engineering patterns and starters into any project. Optional --with-foundry harness stack. Supports Grok, Claude Code, Codex, Opencode and more. npx @cobusgreyling/loop-init . --pattern daily-triage --tool opencode --with-foundry",
"type": "module",
"bin": {
"loop-init": "./dist/cli.js"
@@ -50,7 +50,7 @@
"access": "public"
},
"dependencies": {
- "@cobusgreyling/loop-audit": "^1.5.0"
+ "@cobusgreyling/loop-audit": "^1.7.0"
},
"devDependencies": {
"@types/node": "^26.0.0",
diff --git a/tools/loop-init/src/cli.ts b/tools/loop-init/src/cli.ts
index 75b1561..9e7c31e 100644
--- a/tools/loop-init/src/cli.ts
+++ b/tools/loop-init/src/cli.ts
@@ -78,22 +78,186 @@ const PATTERN_BUDGET: Record<
'issue-triage': { name: 'Issue Triage', maxRunsPerDay: 12, dailyCap: 80_000, maxSpawnsL1: 0, maxSpawnsL2: 1 },
};
+type FoundryPreset = 'minimal' | 'implementer';
+
+/** Map LE patterns → harness-foundry stack presets (report-only → minimal, fix → implementer). */
+const PATTERN_FOUNDRY_PRESET: Record<Pattern, FoundryPreset> = {
+ 'daily-triage': 'minimal',
+ 'issue-triage': 'minimal',
+ 'changelog-drafter': 'minimal',
+ 'pr-babysitter': 'implementer',
+ 'ci-sweeper': 'implementer',
+ 'dependency-sweeper': 'implementer',
+ 'post-merge-cleanup': 'implementer',
+};
+
+const FOUNDRY_SHOWCASE =
+ 'https://github.com/cobusgreyling/harness-foundry/blob/main/docs/showcase.md';
+
function parseArgs(argv: string[]) {
let pattern: Pattern = 'daily-triage';
let tool: Tool = 'grok';
let target = '.';
let dryRun = false;
+ let withFoundry = false;
for (let i = 0; i < argv.length; i++) {
const a = argv[i];
if (a === '--pattern' || a === '-p') pattern = argv[++i] as Pattern;
else if (a === '--tool' || a === '-t') tool = argv[++i] as Tool;
else if (a === '--dry-run') dryRun = true;
- else if (a === '--help' || a === '-h') return { help: true as const, pattern, tool, target, dryRun };
+ else if (a === '--with-foundry') withFoundry = true;
+ else if (a === '--help' || a === '-h')
+ return { help: true as const, pattern, tool, target, dryRun, withFoundry };
else if (!a.startsWith('-')) target = a;
}
- return { help: false as const, pattern, tool, target, dryRun };
+ return { help: false as const, pattern, tool, target, dryRun, withFoundry };
+}
+
+function foundryStackYaml(stackName: string, pattern: Pattern, preset: FoundryPreset): string {
+ if (preset === 'implementer') {
+ return `name: ${stackName}
+version: 1.0.0
+description: "loop-engineering ${pattern} → implementer harness (loop-init --with-foundry)"
+layers:
+ interface:
+ - primitive: model/anthropic
+ config:
+ model: claude-sonnet-4-20250514
+ composition:
+ - primitive: context/state-file
+ - primitive: tools/git-worktree-write
+ execution:
+ - primitive: sandbox/worktree-isolated
+ - primitive: control/token-budget-100k
+ reliability:
+ - primitive: observability/span-per-turn
+ - primitive: recovery/revert-on-test-fail
+ - primitive: emit/outerloop-evidence
+`;
+ }
+
+ return `name: ${stackName}
+version: 1.0.0
+description: "loop-engineering ${pattern} → minimal harness (loop-init --with-foundry)"
+layers:
+ interface:
+ - primitive: model/mock
+ composition:
+ - primitive: context/state-file
+ execution:
+ - primitive: control/token-budget-100k
+ - primitive: sandbox/worktree-isolated
+ reliability:
+ - primitive: observability/span-per-turn
+ - primitive: emit/outerloop-evidence
+`;
+}
+
+/**
+ * Scaffold a harness-foundry stack next to loop files so LE graduates land in
+ * a versioned harness in one command (no foundry package dependency).
+ */
+async function scaffoldFoundry(
+ pattern: Pattern,
+ targetDir: string,
+ dryRun: boolean,
+): Promise<{ preset: FoundryPreset; stackFile: string } | null> {
+ const preset = PATTERN_FOUNDRY_PRESET[pattern];
+ const foundryRoot = path.join(targetDir, '.foundry');
+ const stackFile = path.join(foundryRoot, 'stack.yaml');
+ const stackName = path.basename(targetDir) || 'project';
+
+ if (await exists(stackFile)) {
+ console.log(` skip: ${stackFile} already exists`);
+ return { preset, stackFile };
+ }
+
+ const files: Array<{ path: string; content: string }> = [
+ { path: stackFile, content: foundryStackYaml(stackName, pattern, preset) },
+ {
+ path: path.join(foundryRoot, 'hooks', 'outerloop.yaml'),
+ content: `enabled: false
+adapter: outerloop
+emitOn:
+ - session.end
+`,
+ },
+ {
+ path: path.join(foundryRoot, 'README.md'),
+ content: `# Harness stack (from loop-engineering)
+
+Scaffolded by \`loop-init --with-foundry\` for pattern **${pattern}** (preset: **${preset}**).
+
+\`\`\`
+loop-engineering → harness-foundry → outerloop
+ (patterns) (runtime) (governance)
+\`\`\`
+
+## Next
+
+\`\`\`bash
+npx @cobusgreyling/harness-foundry validate
+npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"
+npx @cobusgreyling/harness-foundry evolve report --session <id>
+\`\`\`
+
+Showcase: ${FOUNDRY_SHOWCASE}
+`,
+ },
+ {
+ path: path.join(foundryRoot, 'sessions', '.gitkeep'),
+ content: '',
+ },
+ ];
+
+ for (const f of files) {
+ if (dryRun) {
+ console.log(` would write: ${f.path}`);
+ continue;
+ }
+ await mkdir(path.dirname(f.path), { recursive: true });
+ await writeFile(f.path, f.content);
+ console.log(` created: ${path.relative(targetDir, f.path)}`);
+ }
+
+ return { preset, stackFile };
+}
+
+function printFoundryCta(opts: {
+ pattern: Pattern;
+ tool: Tool;
+ withFoundry: boolean;
+ score: number | null;
+ preset?: FoundryPreset;
+}) {
+ const { pattern, tool, withFoundry, score, preset } = opts;
+ const mapped = preset ?? PATTERN_FOUNDRY_PRESET[pattern];
+ console.log('');
+ if (withFoundry) {
+ console.log(`Harness stack ready (.foundry/, preset: ${mapped} for ${pattern})`);
+ console.log(' npx @cobusgreyling/harness-foundry validate');
+ console.log(' npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"');
+ console.log(` Showcase: ${FOUNDRY_SHOWCASE}`);
+ return;
+ }
+
+ const highReady = score !== null && score >= 80;
+ console.log(
+ highReady
+ ? 'Next after Loop Ready 80+: version this loop as a harness'
+ : 'Optional: make this loop a versioned harness (harness-foundry)',
+ );
+ console.log(
+ ` npx @cobusgreyling/loop-init . --pattern ${pattern} --tool ${tool} --with-foundry`,
+ );
+ console.log(
+ ` # or: npx @cobusgreyling/harness-foundry init --from loop-engineering:${pattern}`,
+ );
+ if (highReady) {
+ console.log(` Showcase: ${FOUNDRY_SHOWCASE}`);
+ }
}
async function exists(p: string): Promise<boolean> {
@@ -469,7 +633,7 @@ async function main() {
console.log(`loop-init — scaffold loop engineering starters
Usage:
- loop-init [target-dir] --pattern <name> --tool <grok|claude|codex|opencode>
+ loop-init [target-dir] --pattern <name> --tool <grok|claude|codex|opencode> [--with-foundry]
Patterns:
daily-triage (default)
@@ -481,20 +645,26 @@ Patterns:
issue-triage (new low-risk issue queue health companion to daily triage)
Options:
- -p, --pattern Pattern to scaffold
- -t, --tool Tool target (default: grok)
- --dry-run Print actions without copying
- -h, --help This help
+ -p, --pattern Pattern to scaffold
+ -t, --tool Tool target (default: grok)
+ --with-foundry Also scaffold .foundry/ stack (harness-foundry runtime)
+ --dry-run Print actions without copying
+ -h, --help This help
+
+Foundry presets (with --with-foundry):
+ report-only patterns → minimal
+ fix-capable patterns → implementer
Examples:
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
- npx @cobusgreyling/loop-init . -p pr-babysitter -t claude
+ npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --with-foundry
+ npx @cobusgreyling/loop-init . -p pr-babysitter -t claude --with-foundry
npx @cobusgreyling/loop-init . -p daily-triage -t opencode
`);
process.exit(0);
}
- const { pattern, tool, target, dryRun } = args;
+ const { pattern, tool, target, dryRun, withFoundry } = args;
const validPatterns = Object.keys(PATTERN_STARTERS) as Pattern[];
const validTools = Object.keys(TOOL_SUFFIX) as Tool[];
@@ -627,11 +797,21 @@ npm run lint
console.log(' created: AGENTS.md (template)');
}
+ let foundryPreset: FoundryPreset | undefined;
+ if (withFoundry) {
+ console.log('');
+ console.log('Harness foundry:');
+ const foundry = await scaffoldFoundry(pattern, targetDir, dryRun);
+ foundryPreset = foundry?.preset;
+ }
+
const auditArg = auditTargetArg(target, targetDir);
+ let auditScore: number | null = null;
if (!dryRun) {
const audit = await runAuditSummary(targetDir);
if (audit) {
+ auditScore = audit.score;
console.log('');
console.log(`✓ Loop Ready: ${audit.score}/100 (${audit.level})`);
console.log(` ${formatScoreBar(audit.score)}`);
@@ -661,6 +841,13 @@ npm run lint
console.log(` ${firstLoopCommand(pattern, tool)}`);
console.log('');
console.log(`Estimate cost: npx @cobusgreyling/loop-cost --pattern ${pattern} --level L1`);
+ printFoundryCta({
+ pattern,
+ tool,
+ withFoundry,
+ score: auditScore,
+ preset: foundryPreset,
+ });
printContributorCta();
}
diff --git a/tools/loop-init/test/cli.test.mjs b/tools/loop-init/test/cli.test.mjs
index d041bbb..f99aa3b 100644
--- a/tools/loop-init/test/cli.test.mjs
+++ b/tools/loop-init/test/cli.test.mjs
@@ -183,3 +183,68 @@ test('loop-init does NOT scaffold circuit breaker for report-only daily-triage',
await rm(dir, { recursive: true, force: true });
}
});
+
+test('loop-init prints foundry CTA without --with-foundry', async () => {
+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-init-cta-'));
+ try {
+ const { stdout } = await exec('node', [CLI, dir, '--pattern', 'daily-triage', '--tool', 'grok']);
+ assert.match(stdout, /--with-foundry/);
+ assert.match(stdout, /harness-foundry/);
+ await assert.rejects(() => access(path.join(dir, '.foundry', 'stack.yaml')));
+ } finally {
+ await rm(dir, { recursive: true, force: true });
+ }
+});
+
+test('loop-init --with-foundry scaffolds minimal stack for daily-triage', async () => {
+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-init-foundry-'));
+ try {
+ const { stdout } = await exec('node', [
+ CLI,
+ dir,
+ '--pattern',
+ 'daily-triage',
+ '--tool',
+ 'grok',
+ '--with-foundry',
+ ]);
+ await access(path.join(dir, '.foundry', 'stack.yaml'));
+ await access(path.join(dir, '.foundry', 'hooks', 'outerloop.yaml'));
+ await access(path.join(dir, '.foundry', 'README.md'));
+ const stack = await readFile(path.join(dir, '.foundry', 'stack.yaml'), 'utf8');
+ assert.match(stack, /model\/mock/);
+ assert.match(stack, /emit\/outerloop-evidence/);
+ assert.match(stdout, /Harness stack ready/);
+ assert.match(stdout, /preset: minimal/);
+ } finally {
+ await rm(dir, { recursive: true, force: true });
+ }
+});
+
+test('loop-init --with-foundry scaffolds implementer stack for ci-sweeper', async () => {
+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-init-foundry-impl-'));
+ try {
+ const { stdout } = await exec('node', [
+ CLI,
+ dir,
+ '--pattern',
+ 'ci-sweeper',
+ '--tool',
+ 'grok',
+ '--with-foundry',
+ ]);
+ const stack = await readFile(path.join(dir, '.foundry', 'stack.yaml'), 'utf8');
+ assert.match(stack, /model\/anthropic/);
+ assert.match(stack, /tools\/git-worktree-write/);
+ assert.match(stack, /recovery\/revert-on-test-fail/);
+ assert.match(stdout, /preset: implementer/);
+ } finally {
+ await rm(dir, { recursive: true, force: true });
+ }
+});
+
+test('loop-init --help documents --with-foundry', async () => {
+ const { stdout } = await exec('node', [CLI, '--help']);
+ assert.match(stdout, /--with-foundry/);
+ assert.match(stdout, /harness-foundry|implementer|minimal/);
+});