seed-agent — a fleet-style multi-agent framework for coding agents

A small, language- and domain-agnostic scaffold that turns your coding agent into a disciplined lead-orchestrator + specialist crew team. Clone it into any project, fill in the knowledge layer, and start delegating.

Works with any agent. The operating model lives in one AGENTS.md; init also drops a thin pointer for each tool's native config file — Claude Code (CLAUDE.md), Codex / Gemini CLI / Zed / Jules (AGENTS.md), GitHub Copilot, Cursor, Windsurf, and Aider — so every tool boots into the same Firstmate model.

cd your-project && npx seed-agent init

seed-agent gives you a ready-made operating model for agentic coding:

• Captain — you, the human. Sets direction, approves, steers.
• Firstmate — the lead orchestrator (Claude, top tier). Decomposes intent, issues ORDER briefs to crews, integrates REPORT briefs, runs a review gate, and reports conclusions back to the Captain.
• Crews — specialist sub-agents (Frontend, Backend, Data, QA, Scout). Each loads only its own definition plus the knowledge it needs, and returns a terse REPORT — never a file dump.

The framework ships the engine (roles, the ORDER/REPORT brief protocol, the work loop, guardrails) fully filled in and stack-neutral. The knowledge layer (your modules, conventions, schema, screens/features) ships as empty templates with a short "fill this in" guide, so it adapts to any language or domain.

Why

A single agent that does everything burns context and drifts. This scaffold encodes three ideas that scale better:

1. Token-lean communication. Crews talk in briefs — conclusions, changed files, verification results — not raw file contents. See .ai/brief.md.
2. Right model for the job. Cheap search (Scout) is separated from implementation (crews) and from orchestration/review (Firstmate). Assign model tiers to match.
3. A living knowledge base. Project-specific facts live in .ai/* and are updated as you learn them — so the next task starts smarter.

Quick start (CLI)

From inside your project directory:

npx seed-agent init

This scaffolds the framework next to your project (not inside your source tree) and wires up a per-tool entry point:

parent/
├─ your-project/
│   ├─ CLAUDE.md                       ← Claude Code
│   ├─ AGENTS.md                       ← Codex, Gemini CLI, Zed, Jules, …
│   ├─ .github/copilot-instructions.md ← GitHub Copilot
│   ├─ .cursor/rules/seed-agent.mdc    ← Cursor
│   ├─ .windsurfrules                  ← Windsurf
│   └─ CONVENTIONS.md                  ← Aider
└─ your-project-seed-agent/            ← generated: engine + empty knowledge templates
    ├─ AGENTS.md                       ← the constitution (single source of truth)
    └─ .ai/…

Every entry file is a thin pointer: it tells its tool to read ../your-project-seed-agent/AGENTS.md and take on the Firstmate role. Open any supported agent in your-project/ and it boots into the same operating model.

Options:

| Flag | Effect | |------|--------| | --name <slug> | Override the framework folder name → <slug>-seed-agent (default: current folder name) | | --force | Overwrite an existing CLAUDE.md / framework folder |

init stops rather than clobber any existing entry file (CLAUDE.md, AGENTS.md, CONVENTIONS.md, …) — merge the bootstrap by hand, or pass --force.

Manual install (no CLI)

Prefer to vendor it in-tree? Drop this repo into your project and point an entry file at it:

your-project/
├─ AGENTS.md          → thin pointer for Codex/Gemini/Zed/… (and the standard)
├─ CLAUDE.md          → thin pointer for Claude Code
└─ seed-agent/        → this repo (keep it out of your build tree)

1. Copy seed-agent/ next to (or inside) your project — or add it as a submodule.
2. Add an entry file for each agent you use (or merge into an existing one), and point it at seed-agent/AGENTS.md. Each just tells the tool to read that file first and act as the Firstmate. Add only the ones you need:
   • Claude Code → CLAUDE.md
   • Codex / Gemini CLI / Zed / Jules → AGENTS.md
   • GitHub Copilot → .github/copilot-instructions.md
   • Cursor → .cursor/rules/seed-agent.mdc (legacy: .cursorrules)
   • Windsurf → .windsurfrules
   • Aider → CONVENTIONS.md
3. Fill in the knowledge layer (next section). Start with AGENTS.md's routing table and .ai/knowledge/modules.md.

Customize (the only files you must edit)

| File | What to put there | |------|-------------------| | AGENTS.md — routing table | Map your task types → crew → which knowledge to load | | .ai/knowledge/modules.md | Your module boundaries, folder map, file conventions | | .ai/knowledge/conventions.md | Naming, types, layout, per-language rules | | .ai/knowledge/domain-codes.md | Domain vocabulary, codes, enums, business rules | | .ai/knowledge/gotchas.md | Real traps you hit (append as you go) | | .ai/schema/README.md | Where your DB/schema source-of-truth lives + how to query it | | .ai/screens/ (or features) | One doc per screen/feature, from _TEMPLATE.md | | .ai/guardrails.md | Your invariants (VCS rules, safe roots, destructive-op policy) |

The crew definitions (.ai/crew/*.md) are written generically; tune wording to your stack if you like, but they work as-is.

Layout

seed-agent/
├─ bin/cli.js              # the `seed-agent init` scaffolder (no deps)
├─ package.json            # npm bin entry
├─ AGENTS.md               # the constitution: roster, comms, routing, work loop
├─ CLAUDE.md               # entry-point pointer (Claude Code; other tools get their own)
├─ LICENSE
└─ .ai/
   ├─ brief.md             # ORDER / REPORT protocol (token-lean comms)
   ├─ guardrails.md        # invariant rules
   ├─ crew/                # role definitions
   │   ├─ firstmate.md     #   lead orchestrator (top tier)
   │   ├─ fe.md            #   frontend
   │   ├─ be.md            #   backend
   │   ├─ data.md          #   data / persistence
   │   ├─ qa.md            #   QA / tests / acceptance
   │   └─ scout.md         #   read-only search (cheap tier)
   ├─ knowledge/           # ← YOU FILL THIS IN
   │   ├─ modules.md
   │   ├─ conventions.md
   │   ├─ domain-codes.md
   │   └─ gotchas.md
   ├─ schema/              # ← YOU FILL THIS IN
   │   └─ README.md
   └─ screens/             # ← YOU FILL THIS IN (features work too)
       ├─ README.md
       └─ _TEMPLATE.md

License

MIT — see LICENSE.