Multi-Agent Development¶

yaya is built by multiple agents (Claude, Codex, …) working in parallel. Coordination happens through GitHub, not chat context.

Rules¶

One agent, one worktree, one branch, one PR. Agents never share a working tree.
Shared state is the issue tracker. Discussion, status, plans, and hand-off happen in issue/PR comments — @claude, @codex mentions route work.
No cross-branch edits. An agent never pushes to another agent's branch. Hand-off = comment + new PR.
Parallelism condition: issues are dispatched in parallel only when they touch disjoint files. If two issues overlap, serialize them or use stacked PRs (rararulab/.github/docs/stacked-prs.md).
Identity is a label. Every issue and PR carries agent:claude or agent:codex so authorship is auditable.
No shadow task records. Do not create .agents/tasks/, story files, or local task databases for agent work. Use the GitHub issue, PR body, and comments as the durable hand-off record.

Dispatch pattern¶

User request
  ├─ decompose into N independent issues (gh issue create …)
  ├─ for each issue i: spawn subagent in .worktrees/issue-{i}-{slug}
  ├─ subagents run in parallel, each opens its own PR
  └─ PRs reviewed + merged independently on GitHub

Subagent dispatch template — required `Read first` items¶

Every prompt that dispatches a coding subagent MUST include this list, in order:

GOAL.md — product anchor.
AGENT.md — root agent index.
docs/wiki/lessons-learned.md — recurring review findings to avoid.
The authoritative contract for the area of work (e.g. docs/dev/plugin-protocol.md for kernel/plugin work).
Folder-local AGENT.md for every folder the subagent will touch.
docs/dev/workflow.md, testing.md, code-comments.md, agent-spec.md, maintaining-agent-md.md as relevant.
The GitHub issue itself (gh issue view <N>).
The issue's Agent Task Packet section and the latest issue comments.

Skipping item 3 causes the subagent to re-commit known anti-patterns; every review round that uncovers a new hazard appends a bullet to the wiki doc in the same PR.

Always create the worktree from a fresh origin/main:
```
git fetch origin
git worktree add .worktrees/issue-{N}-{slug} -b issue-{N}-{slug} origin/main
```
A worktree based on a stale local main can miss doc/rule updates (like the lessons-learned wiki) that other PRs have just landed.

Large features that cannot be decomposed into independent issues use stacked PRs: one epic issue, sub-issues branched off feat/{name}, final summary PR to main.

Role hand-off records¶

When agents split planning, implementation, and review, keep the hand-off in GitHub:

Planner: post the implementation plan as an issue comment. Include the Agent Task Packet deltas if discovery changed the expected touch points, validation commands, or forbidden areas.
Implementer: preserve what context was actually used in the PR body. Call out deviations from the issue packet or BDD spec explicitly.
Reviewer: leave findings as PR review comments. If a finding exposes a reusable hazard, append it to docs/wiki/lessons-learned.md in the fixing PR.

Do not hide hand-off notes in chat context. If the next agent needs it, it belongs in the issue or PR.

Done criteria (per PR)¶