Multi Agent Orchestration

Multi-Agent Orchestration

Use one parent orchestrator to own ordering, scope, review, landing, and cross-train coordination. A train manager coordinates only its named train; it does not use one shared mutation worktree for all of the train's blocks. Each independently landable node/block has its own implementation owner and candidate. Use subagents for concrete bounded implementation or fresh review work when the task calls for multi-agent execution.

Tama readiness and the database-owned DAG

The program DAG is owned by the TAMA controller's database. Nodes, predecessors, charters, contracts, plans, decision records, issue mappings and implementation state all live there; the repository carries none of it. There is no roadmap/ directory, no implementation ledger file, no repository-side DAG validator and no CI roadmap lane, and none may be reintroduced by a node's patch.

Readiness is intentionally simple. A node is implemented when the controller records its merge; a dispatchable node is READY when every transitive DAG ancestor is implemented. No activation, conditional, or in-progress state participates, and nothing in the repository is consulted to derive it.

An implementation patch therefore never edits DAG state. It does not add, move or rewrite charters, contracts, plans, decision records, ledgers or node tables in the tree, and it does not ship a per-node "constitution" or "ratification" harness that loads a repository DAG. A documentation or contract node lands its durable text where the code's own documentation lives (docs/, package READMEs, skill files) and records the ratified contract as a DAG asset through the controller. Landing the reviewed PR is what marks the node implemented.

GitHub is the landing path, not a mirror. Issue identity for a node, when one exists, comes from the controller's mapping, and the controller's own GitHub engine opens, labels and closes issues and pull requests. The repository's scripts/githubctl keeps only the offline doctor and the ruleset protection commands; issue sync, scheduling, project status, release planning and ledger writes are not repository concerns.

Landed charters are immutable historical acceptance records. Never retrofit this operating policy into a charter whose node is already implemented; update the owning active contract and orchestration policy through the controller instead.

When a user or maintainer directs DAG work to land without a GitHub PR, put one exact Closes #<n> line per controller-mapped issue in the final squash commit body before review. The issue closes when that commit reaches the origin default branch. Never put this coordination citation in source or tests.

If an existing GitHub issue must become DAG work, a maintainer authors the node and its charter in the controller. Never generate, propose, import, or apply DAG authority from GitHub or from repository files automatically.

Admission and scope

Before implementation, confirm the node is READY, read its packet and charter, enumerate independently landable outcomes, and select proportionate evidence for every acceptance outcome. Split work that combines unrelated authority changes or independently rollbackable concerns. Tests are evidence, not quota; behavioral changes use TDD.

Production LOC and file budgets are planning references, not hard lines. Compare the actual candidate with them and investigate material drift in either direction. If a charter expects one production file and the candidate changes ten, treat that as a scope smell requiring a coherent explanation and a check for hidden independently landable work; do not reject, pad, or split a coherent implementation merely to hit the estimate. rescope_loc and rescope_files are stronger investigation signals under the same judgment-based rule.

Conflict domains, resources, external requirements, and effort fields are planning instructions. They are not leases or machine-validated authorizations. The maintainer coordinates ownership and ordering.

Implementation and worktrees

The default landing unit is one independently landable node/block. Give it one dedicated branch/worktree, one stable candidate patch, one squash commit, and—when GitHub control is active—one mapped issue and one PR. Implement only that node's authorized scope, run targeted evidence, rebase as needed, and squash to one conventional commit before final review; the patch carries no DAG state. A train manager coordinates ordering and cross-node dependencies; it does not accumulate sibling-node changes in a shared mutation worktree.

Use one shared branch/worktree for multiple nodes only when the user or maintainer explicitly requests a single atomic train landing before mutation begins. Record why the nodes are not independently landable and keep the combined candidate reviewable as one unit; the controller marks every included node implemented when the candidate lands. Convenience, fewer PRs, shared files, or membership in the same named train are not sufficient reasons. Without that explicit exception, never mix independently landable nodes in one worktree, branch, squash, or PR.

One implementation or fix owner mutates a node candidate at a time. Additional implementation agents may work concurrently only in separate worktrees with disjoint landing units; reviewers and verifiers are read-only against a stable candidate. Do not add receipt files, candidate manifests, runtime state, or SHA-bound evidence.

Roadmap identity stays out of landed code and tests. Production file/module names and comments, plus all test file/module/test names, comments, fixtures, snapshots, assertion messages, and guard diagnostics, must describe durable behavior, never the program, roadmap/DAG, node/block/train ID, phase/stage, implementation sequence, or deletion history. A GitHub issue citation is allowed only for a specific independently reported defect outside the DAG-controlled issue mappings, and only alongside the durable behavioral explanation. Never cite the node's mapped issue or PR as code/test rationale.

In a fresh worktree, run pnpm install --frozen-lockfile before JS/TS tests or workspace-importing Node scripts so missing gitignored dependencies do not look like regressions.

Reviewers should inspect one stable node candidate patch, or the explicitly approved atomic multi-node candidate. The trust model does not require machine enforcement of immutability. Any material fix invalidates affected review conclusions by judgment; rerun the relevant review and verification without restamping identities.