Swarm implement

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).
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: references/clean-code.md.
     • Text a user will read (UI strings, error copy, CLI output, README, release notes) is not code: route it through swarm-write and the project's voice.md. Placeholder copy shipped as final is a defect.
   • Deep reasoning that would bloat comments → code-note in 10 Projects/<P>/code-notes/ + one pointer line in the file header.
   • Commit: Conventional Commits with the FR in scope — feat(FR-12): ….
5. Checkpoint as you go (J1): significant progress or a blocker → one compact line appended to the ticket. A killed session must be resumable from the ticket alone.
6. Close: swarmvault.py release TK-NNN --project P --done; record commit + test refs in the ticket frontmatter; journal a session note (DID/NEXT/BLOCKED).
7. Report the swarm's state at the boundaries only — a finished ticket, a real blocker, a milestone. When orchestration is enabled also signal --event done|blocked so other agents see it, then show board --project P --brief (one line) and pick up the next ticket. Use the full board when the user asks or at a milestone; never poll it on a timer, and never per heartbeat — monitoring must not cost more than the work (swarm-orchestrate has the cheap paths, including the status.md the supervisor keeps current for free).

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.