Docs + orchestration playbook in tool descriptions

[monneyboi]

Part of the fork v2 worker-lifecycle redesign. Covers behavior introduced in #2, #3, #4, and #5; lands incrementally as each ships.

Context

The README documents fire-and-forget spawning; the v2 lifecycle (verdict loop, checks, worktrees, ledger) changes the model substantially. Tool descriptions are also the playbook surface — the only prompt-level guidance every orchestrator session reliably sees — and should encode the workflow the research validates, without turning fork into a supervisor.

Proposal

• README: rewrite "How it works" around the worker lifecycle; document message_agent / close_agent / list_agents, checks, isolate, all fork.json keys, and the orphan/reconciliation behavior.
• AGENTS.md: record the design decisions so future changes preserve them: fork coordinates but never decides (no plan parsing, no scheduling, no auto-merge, no approval logic); flat hierarchy (children get none of the parent tools); deterministic mechanics + LLM judgment; the merge is the only approval event.
• Tool descriptions as playbook (concise): cold-start task briefs (objective, context, scope, validation); isolate parallel code work, share the tree only for read-only/research chunks; review the branch diff, not the child's claims; merging is approval; one objective per chunk; never delegate overlapping write scopes concurrently on a shared tree; don't poll — results arrive as turns.

Acceptance criteria

• README + AGENTS.md match implemented behavior
• Tool descriptions consistent with each other and with the child system prompt
• No guidance that assumes a scheduler, plan parsing, or inter-agent messaging beyond the implemented tools

Sources

• Anthropic, "Building effective agents" (deterministic workflows + agent judgment): https://www.anthropic.com/research/building-effective-agents
• Anthropic, "How we built our multi-agent research system": https://www.anthropic.com/engineering/multi-agent-research-system
• Cognition, "Don't Build Multi-Agents" (context-coherence caution): https://cognition.com/blog/dont-build-multi-agents