afm-mesh-driven-development

Mesh-Driven Development

Execute a plan by sending each task as a durable AFM request to a named team writer, validating the returned work against evidence, and only then moving on. This is subagent-driven development re-based onto the AFM mesh: requests and replies replace dispatch and report, afm agent wait + yield replaces blocking on a child, and a shared worktree replaces isolated contexts.

Division of labor. This skill defines the dispatch, recovery and acceptance protocol. The CALLING FLOW owns ordering and gates — sections, review rounds, markers, board duties. Apply the loop below to the flow's current unit of work; writers finishing never by itself completes a unit or the stage.

You are the orchestrator. You assign, verify and integrate; writers write. Never implement a task yourself while its assigned writer is active, and never use native subagents for work the mesh team owns. Stage-started AFM helpers are available for bounded review and analysis (see below).

Key differences from native subagents

The Task Loop

1. Reconcile before acting. At the start of EVERY turn — before any send or edit — load the ledger (team-progress.json or the flow's equivalent), <your_requests> and afm agent inbox, and reconcile them. afm's own records are the source of truth: a request present in <your_requests> but missing from the ledger WAS sent — record it, never resend it. Re-dispatching completed or pending work is the single most expensive failure. Persist in the ledger: the current unit/phase, each task's assignee, request/reply IDs with their purpose, task ACCEPTANCE separately from "reply received", and retry counts. Write via temp file + atomic rename. A missing or stale ledger is rebuilt from <your_requests>/inbox before anything is dispatched. A registered batch and the replies already collected for it survive a restart; check afm agent wait-status before deciding whether a request still needs an answer.
2. Contracts come from the plan. If parallel tasks share a contract, pin down the one the plan or the code already defines; delegate only missing contract work the plan requires, and accept it before dependent tasks start. Do not create abstractions solely to enable parallelism.
3. One request per plan task. Each request is self-contained — a writer never reads your session history. It names: the task id, allowed files (explicit ownership), dependencies and interfaces from earlier tasks, acceptance criteria, required checks, the TDD requirement for behavior changes (failing test first, red→green evidence in the reply), and any identifiers the calling flow requires (board key etc.). Ownership covers the tests, fixtures, manifests and generated files the task's commands may touch; a writer needing a file outside its grant must stop and ask — resolve the overlap and record the expanded grant before it proceeds. Record the baseline (git rev-parse HEAD plus the dirty state) before dispatching — acceptance is read against it. Corrections are linked follow-up requests to the same writer, not replays of the original. Include the diagnosis and escalation checkpoints below in writer requests: writers may not have loaded this skill. An ownership handoff records a new assignee instead of sending another correction to the original writer.
4. Record, then wait. Record every returned message_id immediately (step 0 fields). For independent requests whose outcomes belong in one round, register ONE afm agent wait --condition reply_to_all --message-ids <id1,id2,...> (optionally with --deadline-seconds N; at most 16 IDs). ready means all have ended; yield means save the batch_id and END YOUR TURN. A separate incoming question can wake you before the batch ends: answer it, check the batch, then park again if it is still pending. Never poll or sleep in a shell, and never write a final summary while requests are pending.
5. Classify every outcome by its request's purpose. On continuation, read afm agent wait-status --wait-id <batch_id> for each item's status and reason, and afm agent inbox --all for its answer. An implementation reply must carry the completed scope and verification evidence; a review reply must cover the requested scope — an explicit "no findings" is a valid, complete review. An acknowledgement or partial status is NEITHER: do not re-wait the satisfied message id and do not redispatch the task — send one linked follow-up to the same agent asking for the final result. A cancelled or expired item is an outcome without an answer, even when the batch status is ready: retain the other results and its reason. It proves nothing about the tree: confirm the writer stopped editing and inspect the partial changes in its files before retrying (at most one retry per request chain, counted in the ledger) or reporting the concrete blocker.
6. Accept on evidence, not on words. The writer's changes are ALREADY in the shared worktree — never apply a returned diff on top of them. Acceptance = inspect the staged, unstaged and new-file changes against the recorded baseline, verify the acceptance criteria and the ownership boundaries. Missing red→green evidence: ask for the existing record first; if the test-first step simply did not happen, record the unmet requirement — never invent evidence or rewind the shared tree to manufacture a red state.
7. Integrate. Reuse successful writer checks for the same relevant code and environment; HEAD alone does not identify a dirty shared tree. Run missing checks and checks needed for combined changes. Repeat broad suites after relevant edits, failures or a concrete new concern, not on every wake-up. Preserve every final gate required by the calling flow. Record the command, actual exit code, log location and tested tree state; piping through tail must not hide the check's failure. Attribute a failure BEFORE routing it: it may belong to this task, another writer's unfinished work, or the environment — do not send writer A to fix writer B's red phase or expand ownership just to make an aggregate check green. Small integration fixes are yours; a writer-sized defect goes back to its owner, subject to the escalation budget below.