vision-to-fleet

name

vision-to-fleet

description

The full discovery-to-execution pipeline for taking a major feature area or system from Arman's initial ideas all the way to a fleet of parallel agents building it — vision capture, reality audit against live code + DB, world-class competitive research (with screenshots + design), vision ratification, infrastructure groundwork, decomposition into hand-off-blind project briefs, and fleet assignment. Use this whenever Arman says anything like "let's plan out X", "I want to build/overhaul the X system", "do the full discovery process on X", "get this ready for a fleet of agents", "create the vision and plan for X", "do what we did for education for X", or hands over rough ideas for a big feature area and wants them turned into an executable multi-agent plan. Also use it when picking up ANY intermediate artifact of this pipeline (a VISION doc, a COMPETITIVE_INSIGHTS doc, a roadmap, a work-packages briefs folder) and being asked to carry it forward. NOT for single features inside a live system (build-sub-feature) or auditing one existing feature (feature-deep-dive) — this is for system-scale work that ends in many parallel agents.

Vision → Fleet: the discovery-to-execution pipeline

The paved road from "Arman has some ideas about X" to "N agents are building X in parallel from briefs they can execute blind." First run: the Education Hub (2026-06/07) — its converged record, including what went wrong the second time around, is common-docs/systems/education/STATE.md; every template referenced below names a live worked example in references/templates.md.

The one-sentence job: produce documents so good that a capable agent, handed one brief and the repo, ships the right thing without ever talking to you — and keep every document truthful at every step along the way.

Phases run in order, but this is a pipeline you can enter mid-stream: figure out which artifacts already exist (vision? insights doc? briefs?), verify them instead of trusting them, and continue from there. Templates for every artifact: references/templates.md. Research mechanics: references/research-playbook.md.

---

Cross-cutting laws (apply in every phase)

1. Ground everything in the live system. Claims about code cite file paths; claims about data cite live row counts (Supabase MCP execute_sql). A doc claim older than a few days is stale in this repo — many concurrent sessions land on main daily. Re-verify before building on anything, including your own earlier docs.
2. Compare the code to the vision, never the vision to the code. The project exists because the current approach isn't working. The current implementation is evidence of what exists, never evidence of what was intended — especially where it violates best practices. When code and vision disagree, the default is the code is wrong; confirm with Arman only when the evidence genuinely cuts both ways.
3. Decisions are Arman's; asking is your job; burying is a failure. Product-semantics calls (what's free, what a hierarchy means, what enters the vision) go to him DIRECTLY in your reply — AskUserQuestion with clear options, or crisp prose. Never leave a decision as a "flag" inside a document he'd have to dig for. Batch questions; make each answerable in seconds by someone juggling ten projects.
4. Every doc is versioned truth. Each artifact gets a status date, a changelog, and — when superseded — a loud pointer to what replaced it. When a decision lands, write it back into the doc that raised it (see the education master plan §8: flags become DECISIONS RECORDED). Stale docs corrupt every future agent's mental model.
5. Fleet-aware git hygiene. Other sessions ARE working on main right now. git status before every commit; stage only your files by explicit path; expect (and tolerate) your work riding in others' commits and vice versa — small commits, never lose work, never stash someone else's.
6. This is an AI-application company. In every phase, "where do agents plug in" is a first-class design question, not an implementation detail — which surfaces get an authored agent, what context it receives, what it returns (structured, cited), how it streams.

---

Phase 0 — Intake

Arman brings ideas: a paragraph, a rant, a competitor screenshot, or a half-written doc. Extract: the domain, the ambition level, what he believes exists already, and what triggered this now (the trigger usually reveals what's broken). Classify:

• Brownfield (usual): significant parts exist somewhere in the codebase → Phase 1 and Phase 2 run in parallel.
• Greenfield (rare): nothing exists → Phase 1, then straight to Phase 3.

Ask the scoping questions NOW, in one batch (they shape everything): who is this for, what does winning look like, what's explicitly out, and — critical for Phase 3 — what function is this, really? (see the benchmark rule below).

Phase 1 — Vision capture

Draft the VISION document — the single most load-bearing artifact; everything downstream cites it. Follow the education example's register (app/(core)/education/VISION-education-hub.md): capability voice, not aspiration voice — "the platform generates X" not "we hope to build X" — covering: who it serves (segments table), the core feature set (numbered sections, one per pillar, dense bullets), platform architecture status table (✅ live / 🔲 roadmap — honest), coming-soon, competitive landscape table, and "Why We Win" numbered differentiators.

• Write it where the feature lives (e.g. app/(core)/<area>/VISION-<area>.md) and register it as the source of truth in whatever plan docs follow. Avoid mirrors; if one must exist, note the sync obligation in both.
• Review is progressive, not terminal. Show Arman the skeleton + pillars early; checkpoint again after research changes it (Phase 4). Never let a large vision diverge silently from what he'd endorse.

Phase 2 — Reality audit (brownfield)

Produce the current-status summary that every later claim rests on. Method that worked:

1. Fan out parallel Explore agents, one per suspected subsystem, each with a precise question sheet ("is X still a stub? which of these six items shipped? what does the uncommitted diff in Y do?"). Ask for file paths in every claim.
2. Yourself, in parallel: live DB truth — information_schema sweep of the relevant schemas with row counts; sample ambiguous tables. Row counts are gold: "table exists, 0 rows, queried nowhere" is a completely different fact from "table exists."
3. Chase every anomaly to a verdict. A mystery table (education's quiz_sessions) gets its columns read, its data dated, and its writers grepped — until it's resolved, not flagged.
4. Check git motion since any prior audit: git log --since=<date> -- <paths>. In-flight work by other agents becomes an explicit "owned elsewhere — do not absorb" list.

Output (section in the plan doc, not a separate file): DONE (real, verified — the assets to build on), IN FLIGHT (owner named), MISSING (what decomposition will cover), plus resolved-anomalies and open flags. Also fix trivial drift you find (a stale "coming soon" label) in the same pass — leaving known-wrong metadata is negligence.

Phase 3 — Competitive research

Full mechanics: references/research-playbook.md. The essentials:

• Benchmark against the best at the FUNCTION, never against AI-engine peers. Building a file system? Study Google Drive and Dropbox, not how some RAG product handles files. Building billing? Stripe's own checkout and the FTC's dark-patterns record. Include the niche masters, not just giants. Getting this framing wrong invalidates the whole phase.
• ~8–10 parallel deep-research passes, one per competitor/cluster, each mining real user sentiment (Trustpilot, app-store reviews, Reddit, G2, feature boards, news, academic papers, regulatory records). What do people LOVE, what do they HATE, what did the company fumble. Cited claims only; self-reported marketing numbers flagged as such.
• Visual capture (was missed on education — do not skip again): browser-agent passes that screenshot each competitor's key flows (onboarding, the hero feature, paywall, empty states) into a research-assets/<competitor>/ folder with an index. These feed the design step.
• Design pass (also previously missed): for every surface the plan will build, a design direction informed by the screenshots — what the best-in-function get right visually, what we adopt/reject — so build-phase agents inherit direction instead of inventing it. Use the ui-* / web-design skills.

Synthesize into a COMPETITIVE_INSIGHTS_AND_REPRIORITIZATION.md (template in templates.md): strategic thesis first, ranked market wants with signal counts, per-competitor nails/hated-for/one-thing-to-take table, cross-cutting themes, then proposed vision elevations/additions clearly marked FOR APPROVAL — research never edits the vision by itself.

Phase 4 — Vision ratification

Take the proposed elevations/additions to Arman directly (law 3) — one question set, clear options, recommendation marked. On approval, amend the vision in place, in each item's home section (merge, don't append a "research findings" appendix), update mirrors, changelog it. Deferred items get documented deferral — a real brief marked "Wave 2, do not assign" (see W2-class-hub.md) — because "later" without a document means "forgotten."

Phase 5 — Infrastructure groundwork

Before decomposing, decide the platform layer so N agents don't invent N solutions:

• Data model: the canonical content-model pattern per entity family (base columns, associations edges, visibility, RLS via the canonical generator, registry entries). New tables go through the db-change skill family. Name the pattern-reference implementation each brief should copy.
• Server/client split per the data-flow doctrine (CLAUDE.md): browser ↔ Supabase direct for all pure data ops; Python only for real server needs (bytes, signing, heavy compute, auth/anon boundaries). Every brief states which side each piece lives on; cross-repo (aidream) work is part of a project, never a follow-up ticket.
• Agent integration points (law 6): enumerate every AI touchpoint; each becomes "author agent via agent_author → wire via the launch/streaming pattern" work inside some brief, with the agent-spec doc named.
• Day-1 contracts: identify every interface where two projects would otherwise block on each other (access gates, entitlements, trust envelopes, converters, data contracts). Each gets an owner, a typed signature, and the rule: publish the signature (stub if needed) on day 1 so consumers wire call sites immediately. This is what makes full parallelism real instead of aspirational.

Phase 6 — Decomposition into briefs

The milestone deliverable: a briefs folder (docs/proposals/<area>-projects/) containing a MASTER PLAN (README.md), one brief per project, an ASSIGN.md prompt, and F-addenda for agents already in flight. All templates + the sizing rules: references/templates.md.

Sizing rules (Arman's, verbatim in spirit): each project is a substantial, coherent body of work — a full subsystem or vertical slice, never a task list; prefer fewer, larger projects (merge anything knockable-out-quickly into a neighbor); maximize parallelism by pushing every cross-dependency into a Phase-5 contract. Small tasks → one agent overseeing a group; large tasks → one agent each. Work already owned by a live agent goes in an F-addendum to that agent, with hand-offs in/out stated explicitly.

Every brief must pass the blind-handoff test: could a strong agent with only this brief + the repo ship the right thing? If any section makes you think "they'll figure it out," it fails.

Map convergence points (integration milestones with their own DoD), fan-out (what each convergence unlocks), and waves ordered by vision impact. Then surface every remaining flag to Arman directly (law 3), record his answers back into the docs, and commit.

Phase 7 — Assignment & fleet operations

• Arman assigns via ASSIGN.md's copy-paste prompt — fresh session per project; F-addenda go to the owning agent's existing session. Track assignment state in ASSIGN.md's table.
• While the fleet runs, the master plan is living: decisions recorded, contracts updated when an owner ships the real thing, kickoff addenda added when concurrent work lands on a brief's turf (see P7's share-links addendum for the shape).
• Your own remaining moves: answer escalations fast with evidence, keep docs truthful, and at each convergence run the integration audit its DoD defines.

Done means

Vision ratified and current · reality audit grounded every claim · research synthesized with visuals + design direction · infrastructure contracts published · every brief blind-executable · flags asked and answers recorded · everything committed · Arman pasting assignment prompts.