Multi agent

Multi Agent

Turn an authorized objective into controlled parallel execution. Keep the main agent as coordinator, give workers bounded ownership, and verify the integrated result independently.

Authority gate

Before delegation:

1. Read the objective, repository instructions, current changes, and any implementation brief.
2. Confirm that the user authorized the requested implementation or external action. A plan alone is not implementation authority.
3. Inspect discoverable facts before asking questions.
4. If material product or architecture decisions remain unresolved, pause only for choices that genuinely require the user. Recommend $grill-with-tree when a structured decision interview would help.
5. If subagent tools are unavailable, explain the limitation. Do not silently replace an explicitly requested multi-agent workflow with sequential work.

Decide whether to parallelize

Use multiple agents only when work can be divided into bounded streams that improve speed, quality, or context isolation.

Prefer:

• independent repository exploration;
• distinct reviews such as security, correctness, and test coverage;
• disjoint implementation surfaces with a settled interface;
• separate documentation, migration, or test work with exclusive ownership.

Keep work with the coordinator or run it sequentially when:

• tasks write the same files or mutable external state;
• one task depends on the still-changing output of another;
• a tool or environment is single-flight;
• coordination costs more than the work;
• the task is small or has only one coherent implementation path.

Do not spawn agents merely to fill capacity.

Build the task graph

For every task, define:

• goal and concrete deliverable;
• dependencies and execution wave;
• exclusive write ownership;
• shared interfaces and settled contracts;
• allowed and forbidden scope;
• acceptance criteria;
• required verification;
• whether it is safe to run in parallel.

Assign every shared file, schema, or external mutation to exactly one owner. Treat the filesystem as shared unless isolation is explicitly guaranteed.

Read assets/execution-plan.md when a durable task board or handoff document would help. Do not create a plan file for a trivial run.

Delegate in waves

Spawn only the workers needed for the current dependency wave and available concurrency.

Give every worker a self-contained brief:

Task: <ID and name>

Objective:
<one bounded outcome>

Read first:
<brief, files, evidence, and repository rules>

Settled contracts:
- <behavior or interface that must not change>

Write ownership:
- Allowed: <paths, components, or external objects>
- Forbidden: <paths, components, or external objects>

Dependencies:
- <completed task or fixed interface>

Deliverables:
- <artifact or result>

Verification:
- <commands, tests, or checks>

Return:
- outcome;
- files changed or evidence inspected;
- verification results;
- blockers, risks, and assumptions.

Tell workers not to:

• edit the shared plan or another worker's owned surface;
• delegate further unless recursive delegation is explicitly required;
• commit, push, deploy, message people, or perform other external side effects unless explicitly authorized;
• widen scope to solve adjacent problems.

Keep doing useful coordinator work while agents run, but do not duplicate an assigned task.

Coordinate and integrate

• Communicate newly discovered interface facts to affected workers.
• Steer a worker when its task changes instead of starting duplicate work.
• Inspect actual files, diffs, evidence, and test output; do not trust summaries alone.
• Send fixes back to the original owner when practical.
• Keep shared-state mutations and documented single-flight tools sequential.
• Resolve conflicts according to the settled contracts, not by whichever result arrived first.
• Preserve pre-existing user changes.

Verify independently

Require focused verification from every worker.

After integration, assign an independent verifier when the task is material:

Independently verify <task or integrated result> against <brief>.
Inspect the actual files and diff; do not rely on worker summaries.
Run the focused checks that materially prove the settled contracts.
Report reproducible findings by severity with evidence and a minimal fix direction.
Do not modify files or change settled behavior unless explicitly asked.

Auto-fix only clear in-scope violations of the settled brief. Return behavior-changing conflicts, scope expansions, and unresolved product decisions to the user.

Run final integrated checks after task-level checks pass.

Failure handling

• If a worker fails, diagnose whether to steer, retry with a narrower brief, reassign, or complete the bounded task as coordinator.
• If only one implementation task is coherent, use one worker followed by an independent verifier rather than inventing parallel work.
• If agent capacity is lower than the task count, execute dependency waves in batches.
• Never report completion while a required task, integration check, or material verification finding remains unresolved.

Final report

Report:

• implemented or investigated outcome;
• task graph and worker results;
• changed files or external scope;
• verification evidence;
• conflicts resolved by the coordinator;
• remaining risks, blockers, or unverified assumptions.

Separate verified facts from assumptions.