swarm-implement

name	swarm-implement
description	Implementation phase — turn a validated design into dependency-ordered tickets, then work them as one of N parallel agents with atomic claims, model tiering, and tests-in-ticket definition of done. Use to plan tickets from a design, pick up/continue implementation work, coordinate parallel agents, or check what to build next.

swarm-implement — implementation phase

Two roles. Check flow-state: no tickets yet → you're the planner; tickets exist → you're a worker.

Planner (strong model, once per milestone batch)

Gate: validated design. Read docs/design.md and the milestone's FR specs.

1. Emit tickets to 30 Plans/<P>/tickets/TK-NNN-<slug>.md (template: 90 Templates/ticket.md, machine lane): FR-ID trace, requires: edges (tracer-bullet order: thinnest end-to-end slice first), suggested tier (size) and kind (design/planning/coding/review/docs — lets orchestration route the right model), DoD checklist, and CONTEXT — the exact notes/design sections a worker needs (nothing more). Also name the layers. requires: orders tickets that exist; it cannot say whether the thing being ordered exists at all. Two tickets were once written as if a persistence layer were there — the engine belonged to one ticket, the tables to another, and the carrier between them to nobody, so both DoDs were unreachable as written and the gap was findable only by grepping for a repository and finding none. So every ticket carries:
   • provides: — the layers this ticket makes exist (ledger repository, recurrence tables)
   • needs: — the layers it builds on, in the same words Every needs: must match some ticket's provides:. board prints a PLANNING GAPS section and doctor fails the ticket coverage check when one does not, when a requires: names a ticket that was never written, or when two tickets claim the same layer. Run doctor before you hand the batch to workers — the gap is cheap now and a stalled worker later.
2. Ask the user ONCE (skip in auto mode if already answered at SRS validation): parallelism appetite, and is a browser/test environment available for UI verification?
3. Update flow-state (phase: implement, ticket count) — J1: state first, work second.

Model tiers: top — architecture-touching, complex logic, tricky concurrency; mid — standard features, refactors; small — boilerplate, docs, simple UI. Workers on the wrong tier for a ticket should say so rather than proceed on hard tickets.

Worker loop (any agent, any platform, N in parallel)

1. Pick: next status: open ticket whose requires: are all done (swarmvault.py query --project P --type ticket). If orchestration is on, check board --project P first: a ticket listed for this session was routed to you by fit — take that one, on the model shown beside it (switch model if your platform lets you; say which model you want if it doesn't). Don't spawn an agent for work already routed here.
2. Claim: swarmvault.py claim TK-NNN --project P --agent <you> — claim won = yours; lost = pick another. Claims stale past the TTL: --break-stale (it logs the takeover).
3. Read only the ticket's CONTEXT — not the whole vault (token economy).
4. Implement to the DoD:
   • Acceptance criteria of the FR demonstrably met — no feature is complete until it fulfills its requirement.
   • Unit tests per function: happy path + edge cases + exception paths.
   • UI work: verify in the real browser/app when the env allows (Playwright); else mark the ticket needs-ui-verify honestly.
   • Craft — write it for the next human (a future teammate or agent):
     • Simple: the least code that does the job; delete before you add; no speculative generality. YAGNI outranks every principle below it.
     • Reusable: search first — call an existing function instead of a near-duplicate. Two occurrences are a coincidence, the third is a pattern; abstract only when the copies change together.
     • Readable: intention-revealing names, functions that do one nameable thing, early returns over deep nesting, match the file's existing idiom and vocabulary.
     • Maintainable: obvious data flow, no hidden globals/side effects, deep modules behind simple interfaces.
     • Errors: never swallow one. Catch only what you can actually handle, fail loudly with context (what was attempted, with what input), propagate the rest.
     • Tests assert behavior, not implementation — if a pure refactor breaks a test, the test was wrong. Happy path + boundaries + empty + failure, every time.
     • Comment sparingly: the code shows what; comments/docstrings only capture why — a constraint, a tradeoff, a non-obvious edge — never narrate lines. But "clean code needs no comments" is not the rule: an unexplained business rule is a defect too. Delete commented-out code.
     • Don't follow a rule into a worse codebase. Fragmented functions, one-implementation abstractions, patterns where a function would do, and SRP shrapnel are the documented failure modes of clean code applied without judgment — the next human's comprehension wins over any rule. Depth, the smell scan, and the tie-breakers: .

Scope discipline: your change wants to cross into another ticket's files → note the ticket link and stop; never expand scope silently.

Milestone boundary: last ticket of a milestone done → trigger swarm-review (auto mode) or offer it (gated).

---

Influences: superpowers subagent-driven-development, executing-plans & dispatching-parallel-agents; Pocock's implement & to-tickets; euxx code-simplifier; Martin's Clean Code and its documented failure modes; Ousterhout's deep modules; Conventional Commits — see CREDITS.md.