Lesson 0001 · ~12 minutes

What SwarmForge actually is (three layers)

One skill: explain the system as runtime + handoff protocol + discipline — so a Rust/TS rewrite targets the right seams instead of “reimplement all the shell.”

Glossary System map Resources Mission

Win for this lesson

After the quiz, you can sketch SwarmForge on a whiteboard in under a minute and point at which layer a TUI rewrite would replace.

1. The product in one breath

From the project README: SwarmForge is a local, tmux-based agent orchestration platform. It does not train models and does not host agents in the cloud. It coordinates several AI coding CLIs that work on the same project without stepping on each other.

Isolation is physical and social at once:

Physical: each role gets a tmux session and usually a git worktree.
Social: roles only talk through a strict handoff protocol, and each role’s prompt says what it may and may not do.

If you only remember “multi-agent tmux,” you will miss the half that makes the system interesting for a rewrite: the protocol and the discipline layer.

2. Three layers (your migration map)

For reimplementation, treat SwarmForge as three stacked products. The original repo mixes them in shell + Babashka; you do not have to keep that packaging.

Runtime

Processes and OS glue: parse swarmforge.conf, create worktrees, open tmux sessions, launch claude/codex/copilot/grok, open terminal windows, watchdog, sleep prevention, cleanup. Code lives mainly in swarmforge/scripts/swarmforge.bb.

Protocol

Durable file mail: agents write validated drafts → outbox → handoffd copies into inboxes → agents claim with ready_for_next and finish with done_with_current. Spec: handoff-protocol.md.

Discipline

Behavior law: layered constitution articles + per-role prompts + pack pipelines (two/four/six). This is why the README claims “reliable, professional software engineers” — not because of fancy IPC alone.

Rewrite implication

A TS TUI can replace most of the runtime surface (multi Terminal windows, even tmux) if it still isolates roles and delivers wake-ups. A Rust rewrite should treat the protocol as the domain core. Discipline is mostly data — prompts and pack configs — and is your main customization surface.

3. main vs packs (why cloning main is not enough)

The main branch is documentary + shared machinery. The workflows you actually drop into a project live on pack branches:

Branch	Shape	Typical chain
`two-pack`	Fast backend loop	coder → cleaner → coder
`four-pack`	Spec + compact gates	specifier → coder → refactorer → architect → …
`six-pack`	Full quality split	specifier → coder → cleaner → architect → hardender → QA

Each pack carries swarmforge.conf, role prompts, and local constitution. The ./swarm wrapper downloads scripts from main when the local swarmforge/scripts/ tree is missing, then launches the launcher. That split matters for customization: change a pack to change workflow; change main scripts to change the platform.

4. What “how” looks like at startup (sketch only)

You do not need every flag yet. Keep this ordered list; later lessons expand each step from the real code.

Read swarmforge/swarmforge.conf (topology).
Ensure git repo + ignore runtime dirs.
Create worktrees under .worktrees/ (unless master/none).
Prepare per-role handoff directories under .swarmforge/handoffs/.
Start tmux sessions + handoff daemon.
Launch each agent CLI with role env + scripts on PATH.
Open terminal surfaces; first window is shutdown handle.

After that, agents follow the constitution loop: accept handoffs, do owned work, commit, send the next git_handoff. The chain always forwards intermediate work even for “no functional change” — that is discipline encoded as protocol policy (details in later lessons).

5. Why these design choices (preview)

Files over sockets for work: durable queue, restart safety, audit trail in headers — tmux is only a lossy pager.
Worktrees over shared checkout: concurrent agents need separate dirty trees; merge happens via git handoffs.
Prompts as law: ownership boundaries (“coder does not own mutation”) reduce thrash without a central scheduler brain.
Config-driven topology: packs are data, so you can invent your own roles without forking the whole platform.

Check yourself

Equal-length choices on purpose. Answer from memory before opening the system map.

Question 1

Which layer is the handoff daemon (handoffd) primarily part of?

Question 2

You want to run a real four-agent Gherkin workflow in a product repo. What do you install?

Question 3

For a TypeScript TUI rewrite, which statement matches the three-layer map?

Question 4

How do roles primarily pass real work downstream in the design?

Primary source (read next)

Read the top of the official README — Intent, Branches, What SwarmForge Does (through “Core Features”). Then skim the opening of handoff-protocol.md (“Goal” + “Summary” only). Local mirrors: /tmp/swarm-forge/README.md and /tmp/swarm-forge/swarmforge/handoff-protocol.md.

Ask the teacher Anything fuzzy — pack vs main, whether you need tmux in a rewrite, or how this compares to other multi-agent tools — ask here. That feedback steers the next lesson (likely: handoff lifecycle end-to-end).

Where this sits in the mission

Mission: understand deeply enough to migrate and customize. Today you only earned the map. Next lessons will walk the protocol state machine, the launcher’s worktree/tmux decisions, and pack role ownership — then a migration boundary map for Rust vs TS+TUI.

Compressed map: system-map.html
Terms: glossary.html