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: implement fleet-engineering bridge (#366)

THRISHAL DOMAaad1645ce023
diff --git a/templates/fleet-inbox.md b/templates/fleet-inbox.md
new file mode 100644
index 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.md
new file mode 100644
index 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 fixing
diff --git a/tools/loop-audit/dist/auditor.d.ts b/tools/loop-audit/dist/auditor.d.ts
index 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.js
index 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.js
index 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.ts
index 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.ts
index 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.mjs
index 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.js
index 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-foundry
npx @cobusgreyling/loop-init . -p daily-triage -t opencode
npx @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 lint
console.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 lint
withMemory,
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.ts
index 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-foundry
npx @cobusgreyling/loop-init . -p daily-triage -t opencode
npx @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 lint
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: number | null = null;
@@ -906,6 +955,12 @@ npm run lint
withMemory,
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.mjs
index 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/);
+});