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.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
feat: implement fleet-engineering bridge (#366)
THRISHAL DOMAaad1645ce023
diff --git a/templates/fleet-inbox.md b/templates/fleet-inbox.mdnew file mode 100644index 0000000..a6fa73f--- /dev/null+++ b/templates/fleet-inbox.md@@ -0,0 +1,10 @@+# Fleet Inbox++Agents operating in a fleet can post cross-loop tasks, hand-offs, and communication messages here.++## Tasks++- `[ ]` **Task ID:** Title+ - **From:** Agent ID+ - **To:** Target Agent ID+ - **Context:** Description of the work required.diff --git a/templates/fleet-registry.md b/templates/fleet-registry.mdnew file mode 100644index 0000000..59dfe6b--- /dev/null+++ b/templates/fleet-registry.md@@ -0,0 +1,14 @@+# Fleet Registry++This file defines the populations of agents in your fleet, their roles, and their specific tool scopes (least-privilege).++## Agents++- **Agent ID:** (e.g. `ci-sweeper-1`)+- **Role:** Describe the agent's purpose.+- **Allowed Tools:**+ - `bash` (read-only scopes)+ - `git`+- **Capabilities:**+ - Automated PR reviews+ - Test fixingdiff --git a/tools/loop-audit/dist/auditor.d.ts b/tools/loop-audit/dist/auditor.d.tsindex 81972b4..091aa9e 100644--- a/tools/loop-audit/dist/auditor.d.ts+++ b/tools/loop-audit/dist/auditor.d.ts@@ -77,6 +77,11 @@ export interface LoopSignals {tiers: boolean;budget: boolean;};+ /** fleet-engineering setup (fleet-registry.md, fleet-inbox.md) */+ fleet: {+ registry: boolean;+ inbox: boolean;+ };}export type { Finding };export interface AuditResult extends BaseAuditResult<'L0' | 'L1' | 'L2' | 'L3', LoopSignals> {diff --git a/tools/loop-audit/dist/auditor.js b/tools/loop-audit/dist/auditor.jsindex e3fd9a8..a1a906b 100644--- a/tools/loop-audit/dist/auditor.js+++ b/tools/loop-audit/dist/auditor.js@@ -48,6 +48,9 @@ const SCORE_WEIGHTS = {/** Memory Engineering (memory-tiers.md, memory-budget.md) */memoryTiers: 4,memoryBudget: 2,+ /** Fleet Engineering (fleet-registry.md, fleet-inbox.md) */+ fleetRegistry: 4,+ fleetInbox: 2,};const LEVEL_THRESHOLDS = {L1: 38,@@ -279,6 +282,10 @@ export function computeScore(signals) {score += w.memoryTiers;if (signals.memory.budget)score += w.memoryBudget;+ if (signals.fleet.registry)+ score += w.fleetRegistry;+ if (signals.fleet.inbox)+ score += w.fleetInbox;score = Math.min(100, Math.max(0, score));const costReady = signals.cost.budgetDoc &&signals.cost.runLog &&@@ -500,6 +507,10 @@ export async function auditProject(target) {const memoryTiers = await fileExists(path.join(root, 'memory-tiers.md'));const memoryBudget = await fileExists(path.join(root, 'memory-budget.md'));const memory = { tiers: memoryTiers, budget: memoryBudget };+ // Fleet Engineering (fleet-registry.md, fleet-inbox.md)+ const fleetRegistry = await fileExists(path.join(root, 'fleet-registry.md'));+ const fleetInbox = await fileExists(path.join(root, 'fleet-inbox.md'));+ const fleet = { registry: fleetRegistry, inbox: fleetInbox };const signals = {stateFile: { present: statePaths.length > 0, paths: statePaths },loopConfig: { present: loopMd, path: loopMd ? 'LOOP.md' : undefined },@@ -520,6 +531,7 @@ export async function auditProject(target) {loopActivity,harness,memory,+ fleet,};if (!signals.stateFile.present) {findings.push({ level: 'fail', message: 'No state file (STATE.md or pattern-specific state).' });@@ -708,6 +720,26 @@ export async function auditProject(target) {findings.push({ level: 'ok', message: 'Memory budget defined.' });}}+ if (!signals.fleet.registry) {+ findings.push({+ level: 'warn',+ message: 'No fleet-registry.md — multi-agent populations and roles are not defined.',+ });+ recommendations.push('Scaffold a fleet: npx @cobusgreyling/loop-init . --with-fleet');+ }+ else {+ findings.push({ level: 'ok', message: 'Fleet registry defined (fleet-registry.md).' });+ if (!signals.fleet.inbox) {+ findings.push({+ level: 'warn',+ message: 'Fleet registry defined but no fleet-inbox.md — agents cannot cross-communicate.',+ });+ recommendations.push('Add fleet-inbox.md to enable cross-loop tasks.');+ }+ else {+ findings.push({ level: 'ok', message: 'Fleet inbox defined.' });+ }+ }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');@@ -715,6 +747,9 @@ export async function auditProject(target) {if (score >= 80 && !signals.memory.tiers) {recommendations.unshift("Loop Ready 80+: version this loop's memory — npx @cobusgreyling/loop-init . --with-memory");}+ if (score >= 80 && !signals.fleet.registry) {+ recommendations.unshift("Loop Ready 80+: version this loop for a fleet — npx @cobusgreyling/loop-init . --with-fleet");+ }const costReady = signals.cost.budgetDoc &&signals.cost.runLog &&signals.cost.loopMdBudget;diff --git a/tools/loop-audit/dist/reporter.js b/tools/loop-audit/dist/reporter.jsindex 72df05f..1484e3f 100644--- a/tools/loop-audit/dist/reporter.js+++ b/tools/loop-audit/dist/reporter.js@@ -61,6 +61,11 @@ export function formatHuman(r) {lines.push('Next after Loop Ready 80+: add cross-session memory (memory-engineering)');lines.push(' npx @cobusgreyling/loop-init . --with-memory');}+ if (r.score >= 80 && !r.signals.fleet?.registry) {+ lines.push('');+ lines.push('Next after Loop Ready 80+: version this loop for a fleet (fleet-engineering)');+ lines.push(' npx @cobusgreyling/loop-init . --with-fleet');+ }lines.push('');return lines.join('\n');}diff --git a/tools/loop-audit/src/auditor.ts b/tools/loop-audit/src/auditor.tsindex 4cdb256..be1ee55 100644--- a/tools/loop-audit/src/auditor.ts+++ b/tools/loop-audit/src/auditor.ts@@ -44,6 +44,11 @@ export interface LoopSignals {tiers: boolean;budget: boolean;};+ /** fleet-engineering setup (fleet-registry.md, fleet-inbox.md) */+ fleet: {+ registry: boolean;+ inbox: boolean;+ };}export type { Finding };@@ -97,6 +102,9 @@ const SCORE_WEIGHTS = {/** Memory Engineering (memory-tiers.md, memory-budget.md) */memoryTiers: 4,memoryBudget: 2,+ /** Fleet Engineering (fleet-registry.md, fleet-inbox.md) */+ fleetRegistry: 4,+ fleetInbox: 2,} as const;const LEVEL_THRESHOLDS = {@@ -303,6 +311,8 @@ export function computeScore(signals: LoopSignals): { score: number; level: 'L0'if (signals.harness.host) score += w.harnessHost;if (signals.memory.tiers) score += w.memoryTiers;if (signals.memory.budget) score += w.memoryBudget;+ if (signals.fleet.registry) score += w.fleetRegistry;+ if (signals.fleet.inbox) score += w.fleetInbox;score = Math.min(100, Math.max(0, score));@@ -541,6 +551,11 @@ export async function auditProject(target: string): Promise<AuditResult> {const memoryBudget = await fileExists(path.join(root, 'memory-budget.md'));const memory = { tiers: memoryTiers, budget: memoryBudget };+ // Fleet Engineering (fleet-registry.md, fleet-inbox.md)+ const fleetRegistry = await fileExists(path.join(root, 'fleet-registry.md'));+ const fleetInbox = await fileExists(path.join(root, 'fleet-inbox.md'));+ const fleet = { registry: fleetRegistry, inbox: fleetInbox };+const signals: LoopSignals = {stateFile: { present: statePaths.length > 0, paths: statePaths },loopConfig: { present: loopMd, path: loopMd ? 'LOOP.md' : undefined },@@ -561,6 +576,7 @@ export async function auditProject(target: string): Promise<AuditResult> {loopActivity,harness,memory,+ fleet,};if (!signals.stateFile.present) {@@ -758,6 +774,25 @@ export async function auditProject(target: string): Promise<AuditResult> {}}+ if (!signals.fleet.registry) {+ findings.push({+ level: 'warn',+ message: 'No fleet-registry.md — multi-agent populations and roles are not defined.',+ });+ recommendations.push('Scaffold a fleet: npx @cobusgreyling/loop-init . --with-fleet');+ } else {+ findings.push({ level: 'ok', message: 'Fleet registry defined (fleet-registry.md).' });+ if (!signals.fleet.inbox) {+ findings.push({+ level: 'warn',+ message: 'Fleet registry defined but no fleet-inbox.md — agents cannot cross-communicate.',+ });+ recommendations.push('Add fleet-inbox.md to enable cross-loop tasks.');+ } else {+ findings.push({ level: 'ok', message: 'Fleet inbox defined.' });+ }+ }+const { score, level, assessment } = computeScore(signals);if (score >= 80 && !signals.harness.stack) {@@ -772,6 +807,12 @@ export async function auditProject(target: string): Promise<AuditResult> {);}+ if (score >= 80 && !signals.fleet.registry) {+ recommendations.unshift(+ "Loop Ready 80+: version this loop for a fleet — npx @cobusgreyling/loop-init . --with-fleet",+ );+ }+const costReady =signals.cost.budgetDoc &&signals.cost.runLog &&diff --git a/tools/loop-audit/src/reporter.ts b/tools/loop-audit/src/reporter.tsindex f3cbcf8..432dbe7 100644--- a/tools/loop-audit/src/reporter.ts+++ b/tools/loop-audit/src/reporter.ts@@ -68,6 +68,12 @@ export function formatHuman(r: AuditResult): string {lines.push('Next after Loop Ready 80+: add cross-session memory (memory-engineering)');lines.push(' npx @cobusgreyling/loop-init . --with-memory');}++ if (r.score >= 80 && !r.signals.fleet?.registry) {+ lines.push('');+ lines.push('Next after Loop Ready 80+: version this loop for a fleet (fleet-engineering)');+ lines.push(' npx @cobusgreyling/loop-init . --with-fleet');+ }lines.push('');return lines.join('\n');}diff --git a/tools/loop-audit/test/auditor.test.mjs b/tools/loop-audit/test/auditor.test.mjsindex 1f5920f..9c9f34f 100644--- a/tools/loop-audit/test/auditor.test.mjs+++ b/tools/loop-audit/test/auditor.test.mjs@@ -28,6 +28,7 @@ function emptySignals() {loopActivity: { present: false, evidence: [] },harness: { stack: false, lock: false, sessions: false, emit: false, host: false },memory: { tiers: false, budget: false },+ fleet: { registry: false, inbox: false },};}@@ -268,6 +269,26 @@ test('auditProject: missing memory recommends --with-memory', async () => {}});+test('computeScore: fleet signals add points', () => {+ const base = emptySignals();+ const { score: without } = computeScore(base);+ const withFleet = emptySignals();+ withFleet.fleet = { registry: true, inbox: true };+ const { score: withScore } = computeScore(withFleet);+ assert.equal(withScore - without, 6);+});++test('auditProject: missing fleet recommends --with-fleet', async () => {+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-audit-nofleet-'));+ try {+ const result = await auditProject(dir);+ assert.equal(result.signals.fleet.registry, false);+ assert.ok(result.recommendations.some((r) => r.includes('--with-fleet')));+ } 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/dist/cli.js b/tools/loop-init/dist/cli.jsindex 3593796..f0a9013 100644--- a/tools/loop-init/dist/cli.js+++ b/tools/loop-init/dist/cli.js@@ -73,6 +73,7 @@ function parseArgs(argv) {let dryRun = false;let withFoundry = false;let withMemory = false;+ let withFleet = false;for (let i = 0; i < argv.length; i++) {const a = argv[i];if (a === '--pattern' || a === '-p')@@ -85,12 +86,14 @@ function parseArgs(argv) {withFoundry = true;else if (a === '--with-memory')withMemory = true;+ else if (a === '--with-fleet')+ withFleet = true;else if (a === '--help' || a === '-h')- return { help: true, pattern, tool, target, dryRun, withFoundry, withMemory };+ return { help: true, pattern, tool, target, dryRun, withFoundry, withMemory, withFleet };else if (!a.startsWith('-'))target = a;}- return { help: false, pattern, tool, target, dryRun, withFoundry, withMemory };+ return { help: false, pattern, tool, target, dryRun, withFoundry, withMemory, withFleet };}function foundryStackYaml(stackName, pattern, preset) {if (preset === 'implementer') {@@ -191,6 +194,16 @@ Showcase: ${FOUNDRY_SHOWCASE}}return { preset, stackFile };}+async function scaffoldFleet(targetDir, templatesRoot, dryRun) {+ const registryTemplate = path.join(templatesRoot, 'fleet-registry.md');+ if (await exists(registryTemplate)) {+ await copyFile(registryTemplate, path.join(targetDir, 'fleet-registry.md'), dryRun);+ }+ const inboxTemplate = path.join(templatesRoot, 'fleet-inbox.md');+ if (await exists(inboxTemplate)) {+ await copyFile(inboxTemplate, path.join(targetDir, 'fleet-inbox.md'), dryRun);+ }+}async function scaffoldMemory(targetDir, templatesRoot, dryRun) {const tiersTemplate = path.join(templatesRoot, 'memory-tiers.md');const tiersDest = path.join(targetDir, 'memory-tiers.md');@@ -224,6 +237,19 @@ function printFoundryCta(opts) {console.log(` Showcase: ${FOUNDRY_SHOWCASE}`);}}+function printFleetCta(opts) {+ const { pattern, tool, withFleet, score } = opts;+ console.log('');+ if (withFleet) {+ console.log('Fleet engineering stack ready (fleet-registry.md, fleet-inbox.md)');+ return;+ }+ const highReady = score !== null && score >= 80;+ console.log(highReady+ ? 'Next after Loop Ready 80+: version this loop for a fleet (fleet-engineering)'+ : 'Optional: add fleet-engineering for multi-agent populations');+ console.log(` npx @cobusgreyling/loop-init . --pattern ${pattern} --tool ${tool} --with-fleet`);+}function printMemoryCta(opts) {const { pattern, tool, withMemory, score } = opts;console.log('');@@ -564,6 +590,7 @@ Options:-t, --tool Tool target (default: grok)--with-foundry Also scaffold .foundry/ stack (harness-foundry runtime)--with-memory Also scaffold memory-engineering tiers and budget+ --with-fleet Also scaffold fleet-engineering registry and inbox--dry-run Print actions without copying-h, --help This help@@ -577,10 +604,11 @@ Examples:npx @cobusgreyling/loop-init . -p pr-babysitter -t claude --with-foundrynpx @cobusgreyling/loop-init . -p daily-triage -t opencodenpx @cobusgreyling/loop-init . --with-memory+ npx @cobusgreyling/loop-init . --with-fleet`);process.exit(0);}- const { pattern, tool, target, dryRun, withFoundry, withMemory } = args;+ const { pattern, tool, target, dryRun, withFoundry, withMemory, withFleet } = args;const validPatterns = Object.keys(PATTERN_STARTERS);const validTools = Object.keys(TOOL_SUFFIX);if (!validPatterns.includes(pattern)) {@@ -705,6 +733,11 @@ npm run lintconsole.log('Memory engineering:');await scaffoldMemory(targetDir, templatesRoot, dryRun);}+ if (withFleet) {+ console.log('');+ console.log('Fleet engineering:');+ await scaffoldFleet(targetDir, templatesRoot, dryRun);+ }const auditArg = auditTargetArg(target, targetDir);let auditScore = null;if (!dryRun) {@@ -751,6 +784,12 @@ npm run lintwithMemory,score: auditScore,});+ printFleetCta({+ pattern,+ tool,+ withFleet,+ score: auditScore,+ });printContributorCta();}async function readDirNames(dir) {diff --git a/tools/loop-init/src/cli.ts b/tools/loop-init/src/cli.tsindex d19cc72..52ed587 100644--- a/tools/loop-init/src/cli.ts+++ b/tools/loop-init/src/cli.ts@@ -101,6 +101,7 @@ function parseArgs(argv: string[]) {let dryRun = false;let withFoundry = false;let withMemory = false;+ let withFleet = false;for (let i = 0; i < argv.length; i++) {const a = argv[i];@@ -109,12 +110,13 @@ function parseArgs(argv: string[]) {else if (a === '--dry-run') dryRun = true;else if (a === '--with-foundry') withFoundry = true;else if (a === '--with-memory') withMemory = true;+ else if (a === '--with-fleet') withFleet = true;else if (a === '--help' || a === '-h')- return { help: true as const, pattern, tool, target, dryRun, withFoundry, withMemory };+ return { help: true as const, pattern, tool, target, dryRun, withFoundry, withMemory, withFleet };else if (!a.startsWith('-')) target = a;}- return { help: false as const, pattern, tool, target, dryRun, withFoundry, withMemory };+ return { help: false as const, pattern, tool, target, dryRun, withFoundry, withMemory, withFleet };}function foundryStackYaml(stackName: string, pattern: Pattern, preset: FoundryPreset): string {@@ -227,6 +229,21 @@ Showcase: ${FOUNDRY_SHOWCASE}return { preset, stackFile };}+async function scaffoldFleet(+ targetDir: string,+ templatesRoot: string,+ dryRun: boolean,+) {+ const registryTemplate = path.join(templatesRoot, 'fleet-registry.md');+ if (await exists(registryTemplate)) {+ await copyFile(registryTemplate, path.join(targetDir, 'fleet-registry.md'), dryRun);+ }+ const inboxTemplate = path.join(templatesRoot, 'fleet-inbox.md');+ if (await exists(inboxTemplate)) {+ await copyFile(inboxTemplate, path.join(targetDir, 'fleet-inbox.md'), dryRun);+ }+}+async function scaffoldMemory(targetDir: string,templatesRoot: string,@@ -280,6 +297,30 @@ function printFoundryCta(opts: {}}+function printFleetCta(opts: {+ pattern: Pattern;+ tool: Tool;+ withFleet: boolean;+ score: number | null;+}) {+ const { pattern, tool, withFleet, score } = opts;+ console.log('');+ if (withFleet) {+ console.log('Fleet engineering stack ready (fleet-registry.md, fleet-inbox.md)');+ return;+ }++ const highReady = score !== null && score >= 80;+ console.log(+ highReady+ ? 'Next after Loop Ready 80+: version this loop for a fleet (fleet-engineering)'+ : 'Optional: add fleet-engineering for multi-agent populations',+ );+ console.log(+ ` npx @cobusgreyling/loop-init . --pattern ${pattern} --tool ${tool} --with-fleet`,+ );+}+function printMemoryCta(opts: {pattern: Pattern;tool: Tool;@@ -693,6 +734,7 @@ Options:-t, --tool Tool target (default: grok)--with-foundry Also scaffold .foundry/ stack (harness-foundry runtime)--with-memory Also scaffold memory-engineering tiers and budget+ --with-fleet Also scaffold fleet-engineering registry and inbox--dry-run Print actions without copying-h, --help This help@@ -706,11 +748,12 @@ Examples:npx @cobusgreyling/loop-init . -p pr-babysitter -t claude --with-foundrynpx @cobusgreyling/loop-init . -p daily-triage -t opencodenpx @cobusgreyling/loop-init . --with-memory+ npx @cobusgreyling/loop-init . --with-fleet`);process.exit(0);}- const { pattern, tool, target, dryRun, withFoundry, withMemory } = args;+ const { pattern, tool, target, dryRun, withFoundry, withMemory, withFleet } = args;const validPatterns = Object.keys(PATTERN_STARTERS) as Pattern[];const validTools = Object.keys(TOOL_SUFFIX) as Tool[];@@ -857,6 +900,12 @@ npm run lintawait scaffoldMemory(targetDir, templatesRoot, dryRun);}+ if (withFleet) {+ console.log('');+ console.log('Fleet engineering:');+ await scaffoldFleet(targetDir, templatesRoot, dryRun);+ }+const auditArg = auditTargetArg(target, targetDir);let auditScore: number | null = null;@@ -906,6 +955,12 @@ npm run lintwithMemory,score: auditScore,});+ printFleetCta({+ pattern,+ tool,+ withFleet,+ score: auditScore,+ });printContributorCta();}diff --git a/tools/loop-init/test/cli.test.mjs b/tools/loop-init/test/cli.test.mjsindex 7b53c79..67a0ad7 100644--- a/tools/loop-init/test/cli.test.mjs+++ b/tools/loop-init/test/cli.test.mjs@@ -288,3 +288,43 @@ test('loop-init --help documents --with-memory', async () => {assert.match(stdout, /--with-memory/);assert.match(stdout, /memory-engineering tiers and budget/);});++test('loop-init prints fleet CTA without --with-fleet', async () => {+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-init-fleet-cta-'));+ try {+ const { stdout } = await exec('node', [CLI, dir, '--pattern', 'daily-triage', '--tool', 'grok']);+ assert.match(stdout, /--with-fleet/);+ assert.match(stdout, /fleet-engineering/);+ await assert.rejects(() => access(path.join(dir, 'fleet-registry.md')));+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++test('loop-init --with-fleet scaffolds registry and inbox', async () => {+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-init-fleet-'));+ try {+ const { stdout } = await exec('node', [+ CLI,+ dir,+ '--pattern',+ 'daily-triage',+ '--tool',+ 'grok',+ '--with-fleet',+ ]);+ await access(path.join(dir, 'fleet-registry.md'));+ await access(path.join(dir, 'fleet-inbox.md'));+ const registry = await readFile(path.join(dir, 'fleet-registry.md'), 'utf8');+ assert.match(registry, /Fleet Registry/);+ assert.match(stdout, /Fleet engineering stack ready/);+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++test('loop-init --help documents --with-fleet', async () => {+ const { stdout } = await exec('node', [CLI, '--help']);+ assert.match(stdout, /--with-fleet/);+ assert.match(stdout, /fleet-engineering registry and inbox/);+});