diff --git a/README.md b/README.md index 63439c1..3b1c27a 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,17 @@ Fleet Engineering — Govern populations of agents with accountability

+> **You don’t have an agent problem. You have a population problem. Get a Fleet Ready score.** + **Fleet engineering is replacing ad-hoc populations of agents with an accountable organization. You design the registry, identity, permissions, inbox, audit trail, and sovereign control that let many loops run safely across a team.** +```bash +npx @cobusgreyling/fleet-init . +npx @cobusgreyling/fleet-audit . --suggest +# Optional: attach a loop layer +npx @cobusgreyling/fleet-init . --with-loop daily-triage +``` + A fleet is not "many agents." A fleet is a **governed population** where every action answers one sentence: > *Which agent did it, with what authority, against what task, evidenced by what?* @@ -23,6 +32,8 @@ A fleet is not "many agents." A fleet is a **governed population** where every a

→ cobusgreyling.github.io/fleet-engineering
+ → Fleet Ready Score (F0–F3) +
→ Fleet Engineering essay on Substack

@@ -51,6 +62,8 @@ Unsure? Use the [Pattern Picker](docs/pattern-picker.md). | Start here | Description | |------------|-------------| +| [**Fleet Ready Score**](docs/fleet-ready-score.md) | F0–F3 scoring contract (`fleet-audit`) — same ritual as Loop Ready | +| [**Relaunch playbook**](docs/LAUNCH.md) | Growth pack: positioning, 7-day ship plan, metrics | | [Concepts](docs/concepts.md) | Fleet vs loop vs harness — **read this first** | | [Assistant vs Claw](https://github.com/cobusgreyling/assistant-vs-claw) | Runnable identity models (on-behalf-of vs fixed credentials) | | [Maturity Model](docs/maturity-model.md) | F0–F3 phased rollout | diff --git a/docs/LAUNCH.md b/docs/LAUNCH.md new file mode 100644 index 0000000..8435b99 --- /dev/null +++ b/docs/LAUNCH.md @@ -0,0 +1,181 @@ +# Fleet Engineering — Relaunch Playbook + +Turn **fleet-engineering** from “correct sequel” (24★) into the same growth curve as **loop-engineering** (~8.8k★). + +This is not a rewrite. The product mostly exists. The gap is **solo-day-one aha**, **score addiction**, and **distribution**. + +--- + +## Positioning (lock this) + +| | Loop | Fleet | +|--|------|-------| +| Unit | One autonomous system | A governed population | +| Pain | “I keep re-prompting” | “We have agents everywhere” | +| Promise | Design the loop | Design the registry + inbox + kill switch | +| Score | Loop Ready (L0–L3) | **Fleet Ready (F0–F3)** | +| Tagline | Stop prompting. Design the loop. | **You don’t have an agent problem. You have a population problem.** | + +**One-sentence pitch (README hero + social):** + +> Fleet engineering replaces ad-hoc agent sprawl with an accountable organization — registry, identity, permissions, inbox, budgets, and a kill switch — so every action answers: *which agent, with what authority, against what task, evidenced by what?* + +**Do not pitch as:** multi-agent framework, CrewAI competitor, or “enterprise only.” + +**Do pitch as:** the practical reference kit *after* loop-engineering — same house style, next layer of the stack. + +``` +Context → Harness → Loop → Fleet +``` + +--- + +## Non-negotiable viral mechanics (copy loop) + +1. **One command** — `npx @cobusgreyling/fleet-init .` +2. **One score** — `npx @cobusgreyling/fleet-audit .` → 0–100 + F0–F3 + `--suggest` +3. **15-second demo GIF** — empty dir → init → audit climbs (see [relaunch demo script](../stories/relaunch-demo-script.md)) +4. **Pattern picker** — already at `docs/pattern-picker.md` + Pages +5. **Week-one safe path** — F1 catalog + inbox only; no unattended L2+ loops +6. **Dogfood badge** — fleet-audit on every PR (already wired) +7. **Cross-link from loop** — loop README “Scale to a fleet” section + Substack Part 2 + +If any of these are weak, fix them before new features. + +--- + +## Relaunch week (7 days) + +### Day 0 — Freeze the demo path + +```bash +rm -rf /tmp/fleet-demo && mkdir /tmp/fleet-demo && cd /tmp/fleet-demo +npx @cobusgreyling/fleet-init . --pattern team-agent-registry +npx @cobusgreyling/fleet-audit . --suggest +# Target: score jumps from ~10 → ≥40 (F1) with clear next steps +``` + +Checklist: +- [ ] Init works without cloning the monorepo +- [ ] Audit score is explained in human output (not only JSON) +- [ ] `--suggest` prints copy-pasteable commands +- [ ] README hero shows the two commands above +- [ ] GIF recorded and linked from README + Pages + +### Day 1 — README hero rewrite + +Lead with pain → command → score → stack diagram. Move maturity theory below the fold. + +Hero structure: +1. Tagline +2. `fleet-init` + `fleet-audit` code block +3. “Fleet Ready” score screenshot/GIF +4. “Already have loops?” → `starters/fleet-plus-loop` +5. Pattern table (symptom → pattern) + +### Day 2 — Score productization + +Document weights in [fleet-ready-score.md](./fleet-ready-score.md). Mirror loop-audit UX: + +``` +Fleet Ready: 62/100 (F2 shared) +✓ FLEET.md ✓ registry ✓ manifests ✓ budget +! inbox-runbook missing ! kill switch not tested +→ npx @cobusgreyling/fleet-init . --pattern shared-inbox-hitl +``` + +CI gate examples: + +```yaml +- run: npx @cobusgreyling/fleet-audit . --min-score=40 +``` + +### Day 3 — Killer demo story + +Publish one story with numbers (use real or dogfood): + +> Three shadow agents, one shared key, $X surprise bill → registry + budget guard + kill switch in 45 minutes. Fleet Ready 18 → 71. + +File: `stories/` + Substack excerpt + tweet thread. + +### Day 4 — Loop cross-promo + +In **loop-engineering** README (and docs/QUICKSTART): + +```markdown +## Scale beyond one loop + +When multiple loops/agents share a team, adopt fleet engineering: +npx @cobusgreyling/fleet-init . --with-loop daily-triage +``` + +Pin fleet in profile README under the stack. + +### Day 5 — Essay + influencer pack + +Substack: **“Fleet Engineering: the outer organization for your loops”** + +Sections: +1. Why loop success creates fleet pain +2. Accountability test (one sentence) +3. F0→F3 without buying a platform +4. DIY 5-minute path +5. Link repo + score GIF + +Outreach list: anyone who boosted loop (Addy orbit, agent-harness authors, Grok/Claude Code communities). + +### Day 6–7 — Distribution blitz + +- Show HN / Reddit r/LocalLLaMA + r/ClaudeAI + r/ChatGPTCoding (practical tone) +- X thread: problem → accountability sentence → init → score → inbox → kill switch +- LinkedIn: engineering-manager angle (cost + audit) +- Update Pages showcase with “Start here if you have 3+ agents” + +--- + +## Content that converts (prioritize) + +| Asset | Job | +|-------|-----| +| Demo GIF | Trust in 15s | +| Symptom → pattern table | Self-selection | +| `fleet-plus-loop` starter | Convert loop users | +| Failure modes | Seriousness / SEO | +| Stories (honest fails) | Social proof | + +Skip until after relaunch: new frameworks integrations, multi-fleet theory deep dives, enterprise-only F3 polish. + +--- + +## Success metrics (30 days) + +| Signal | Target | +|--------|--------| +| GitHub stars | 500+ (path to 2k if loop cross-promo works) | +| `fleet-init` weekly npm | Measurable (publish if not already) | +| Stars from loop README | Track referrer / campaign UTM in essay | +| Issues/PRs | External pattern or starter PR | +| “Fleet Ready” mentions | Organic quote tweets / blog cites | + +If stars move but npm doesn’t: onboarding broken. +If npm moves but retention doesn’t: patterns not stealable enough. + +--- + +## What *not* to do + +- Don’t rename to compete with outerloop/harness-foundry messaging in public — **fleet is the growth surface** +- Don’t require a paid control plane for the aha moment +- Don’t lead with seven primitives before the 5-minute path +- Don’t launch memory-engineering the same week (split attention) + +--- + +## Owner checklist (ship this pack) + +- [ ] [fleet-ready-score.md](./fleet-ready-score.md) linked from README +- [ ] [relaunch-demo-script.md](../stories/relaunch-demo-script.md) recorded as GIF +- [ ] README hero matches this positioning +- [ ] Loop repo cross-link merged +- [ ] Essay draft published +- [ ] npm packages discoverable under `@cobusgreyling/fleet-*` diff --git a/docs/fleet-ready-score.md b/docs/fleet-ready-score.md new file mode 100644 index 0000000..8f46ac5 --- /dev/null +++ b/docs/fleet-ready-score.md @@ -0,0 +1,79 @@ +# Fleet Ready Score + +Public contract for `npx @cobusgreyling/fleet-audit`. + +Mirrors **Loop Ready** so people who already trust loop-audit adopt fleet-audit without relearning the ritual. + +## Levels + +| Level | Score | Meaning | Safe autonomy | +|-------|-------|---------|----------------| +| **F0** | 0–39 | Ad-hoc population | Humans only; catalog what exists | +| **F1** | 40–64 | Cataloged | Report + HITL inbox; no unattended prod writes | +| **F2** | 65–84 | Shared fleet | Budgets + kill switch + clone policy | +| **F3** | 85–100 | Enterprise fleet | Policy-as-code, compliance export, SLOs | + +Default CI gate for “we know our agents”: `--min-score=40` (F1). +Default gate for “shared team fleet”: `--min-score=65` (F2). + +## Score weights (target product UX) + +Approximate contributions used by `fleet-audit` (base 10): + +| Signal | Points | Why | +|--------|--------|-----| +| `FLEET.md` posture | +15 | Written intent and sovereign control | +| `FLEET-STATE.md` | +12 | Human-readable catalog | +| Registry present | +12 | Machine list of agents | +| Manifests | +8–14 | Per-agent identity + owner | +| Permissions model | +10 | clone / run / edit clarity | +| Budget file | +10 | Economics exist | +| Kill switch language | +8 | Sovereign control | +| Accountability test | +10 | The one-sentence standard | +| Patterns registry | +6 | Intentional design | +| Audit workflow dogfood | +5 | Continuous readiness | +| Schema valid / no shadows | penalties | Lies in the registry are worse than no registry | +| Inbox + audit runbooks | bonus via files | HITL path | + +Exact numbers may drift; **levels and the accountability sentence must not.** + +## Human output template + +``` +Fleet Ready: 48/100 · F1 cataloged + +OK + FLEET.md present + Registry file found + 2 agent manifest(s) + Fleet budget file present + +WARN + Missing inbox-runbook.md + Kill switch not documented + Accountability test not referenced + +Suggested actions + npx @cobusgreyling/fleet-init . --pattern shared-inbox-hitl + Document kill switch + FLEET_PAUSE in FLEET.md + Add the accountability sentence to FLEET.md +``` + +## How to climb fast (solo, 30 minutes) + +1. `npx @cobusgreyling/fleet-init . --pattern team-agent-registry` +2. Fill owners on each manifest +3. Add inbox pattern if any agent can write +4. Write kill switch paragraph +5. `npx @cobusgreyling/fleet-audit . --suggest` +6. Stop at F1 for a week — do not skip to unattended loops + +## Mapping from Loop Ready + +| Loop | Fleet expectation | +|------|-------------------| +| L1 report-only | Register at F1 | +| L2 assisted | F1 inbox + identity required | +| L3 unattended | F2 budgets + kill switch minimum | + +See [maturity-model.md](./maturity-model.md) and [accountability-test.md](./accountability-test.md). diff --git a/scripts/record-relaunch-demo.sh b/scripts/record-relaunch-demo.sh new file mode 100755 index 0000000..78eda48 --- /dev/null +++ b/scripts/record-relaunch-demo.sh @@ -0,0 +1,52 @@ +#!/usr/bin/env bash +# Cold-path Fleet Ready demo for GIF recording (15–30s). +# Usage: +# ./scripts/record-relaunch-demo.sh +# ./scripts/record-relaunch-demo.sh --pause # wait for keypress between beats +set -euo pipefail + +PAUSE=0 +if [[ "${1:-}" == "--pause" ]]; then PAUSE=1; fi + +step() { + echo "" + echo "────────────────────────────────────────" + echo "▶ $1" + echo "────────────────────────────────────────" + if [[ "$PAUSE" -eq 1 ]]; then + read -r -p "(press Enter)" _ + else + sleep 1.2 + fi +} + +ROOT="$(cd "$(dirname "$0")/.." && pwd)" +DEMO="${FLEET_DEMO_DIR:-/tmp/fleet-ready-demo}" +INIT_CLI="$ROOT/tools/fleet-init/cli.js" +AUDIT_CLI="$ROOT/tools/fleet-audit/cli.js" + +if [[ ! -f "$INIT_CLI" || ! -f "$AUDIT_CLI" ]]; then + echo "Expected local fleet-init/fleet-audit CLIs under tools/" >&2 + exit 1 +fi + +step "1/4 Empty dir — expect low Fleet Ready" +rm -rf "$DEMO" +mkdir -p "$DEMO" +cd "$DEMO" +node "$AUDIT_CLI" . || true + +step "2/4 fleet-init team-agent-registry" +node "$INIT_CLI" . --pattern team-agent-registry --tool grok + +step "3/4 fleet-audit --suggest (score should jump)" +node "$AUDIT_CLI" . --suggest + +step "4/4 Optional inbox pattern (second beat)" +node "$INIT_CLI" . --pattern shared-inbox-hitl || true +node "$AUDIT_CLI" . + +echo "" +echo "Done. Record this terminal with asciinema/agg or CleanShot." +echo "Demo dir: $DEMO" +echo "Narration: stories/relaunch-demo-script.md" diff --git a/stories/relaunch-demo-script.md b/stories/relaunch-demo-script.md new file mode 100644 index 0000000..608d481 --- /dev/null +++ b/stories/relaunch-demo-script.md @@ -0,0 +1,68 @@ +# Relaunch Demo Script (15–30s GIF) + +Record this cold path. No monorepo clone. No enterprise setup. + +## One-command local rehearsal (preferred) + +From a clone of this repo (uses local CLIs — no npm publish required): + +```bash +chmod +x scripts/record-relaunch-demo.sh +./scripts/record-relaunch-demo.sh # auto-paced for GIF capture +./scripts/record-relaunch-demo.sh --pause # keypress between beats +``` + +Record the terminal (examples): + +```bash +# asciinema + agg → gif +asciinema rec /tmp/fleet-ready.cast -c './scripts/record-relaunch-demo.sh' +agg /tmp/fleet-ready.cast assets/visuals/fleet-ready-demo.gif +``` + +## Terminal script (npx / published packages) + +```bash +# Clean slate +rm -rf /tmp/fleet-ready-demo && mkdir /tmp/fleet-ready-demo && cd /tmp/fleet-ready-demo + +# Before (expect low score) +npx @cobusgreyling/fleet-audit . 2>/dev/null || echo "Fleet Ready: ~10 (empty)" + +# Scaffold F1 +npx @cobusgreyling/fleet-init . --pattern team-agent-registry --tool grok + +# After +npx @cobusgreyling/fleet-audit . --suggest + +# Optional second beat: inbox +npx @cobusgreyling/fleet-init . --pattern shared-inbox-hitl +npx @cobusgreyling/fleet-audit . +``` + +## Narration (overlay or voice) + +1. “Three agents. No list. No owner. No kill switch.” +2. “Fleet engineering: design the population, not another prompt.” +3. Show score climb. +4. “Every action must answer: which agent, what authority, what task, what evidence.” +5. CTA: `github.com/cobusgreyling/fleet-engineering` + +## Visual checklist + +- [ ] Large terminal font +- [ ] Score number centered in frame on final frame +- [ ] Repo URL end card 2s +- [ ] Dark theme matching loop-engineering GIF +- [ ] Under 30s total (15s ideal) + +## Placement + +1. README hero (under init commands) +2. GitHub Pages showcase +3. Substack embed +4. Tweet 1 of relaunch thread + +## Honesty bar + +If init does not raise score by ≥25 points on empty dir, fix audit/init before publishing the GIF.