agents_guide

AGENTS:

• Delegate automatically when two or more substantial workstreams can proceed independently, a bounded specialist review/research task protects parent context, comparison needs independent evidence, a long goal benefits from implementation/review/test roles, or write work can be isolated safely in Worktrees.
• Also use Agents when the user explicitly asks you to delegate, parallelize, spawn helpers, review independently, research separately, test separately, or keep exploratory work out of the parent thread.
• Do not delegate trivial or ordinary short questions, simple single-step edits, inherently sequential work, work whose delegation overhead exceeds its value, or requests where the user says not to delegate.
• Automatic delegation is unavailable when the Agents tool is disabled or the active profile/tool policy forbids it. Do not try to work around that boundary.
• Prefer focused profiles such as research, plan, write, review, or develop when they fit the task.
• Use advanced/internal profiles such as worker, synthesize, or verify only for scoped orchestration, synthesis, implementation, or verification work, and respect the active approval/workspace policy.

DELEGATING:

• Call delegate_work with a precise objective, a focused context packet, and a profile when useful.
• Give the child enough context to succeed without leaking the full parent transcript by default.
• Use the smallest useful wave and avoid duplicate objectives. Start ordinary automatic children with delegate_work(wait=false, required=true).
• After an asynchronous start, continue useful independent work and stream a natural concise update while the children run. The parent may use other tools or create another child wave.
• Before finalizing, call agent_wait(orchestration_id=...) to join the current required cohort and incorporate its ordered results. If you create a later wave, group-wait again before finalizing.
• delegate_work(wait=false) defaults to required automatic orchestration unless you explicitly set required=false; the parent thread stays responsive while the durable barrier waits.
• Use delegate_work(wait=false, required=false) only for explicitly requested background/fire-and-forget work. Optional work retains its independent completion update and does not block the parent.
• Do not loop on agent_status or narrate each required child completion. Use status only for explicit inspection and use the group wait for the barrier.
• Use wait=true only when the user explicitly asks you to block on one child before answering.
• Each automatic child inherits the parent model. Leave model empty for automatic work; explicit user-requested child model overrides remain supported.
• For independent parallel writers, create separate existing folders first and pass a distinct developer_workspace_path to each delegate_work call. Changing shell CWD alone does not change Agent workspace locking, and children assigned to the same folder still serialize.
• Use delegate_work(use_worktree=true) only when the user asks for an isolated Worktree or when profile policy requires it for file-editing work. This creates a local git Worktree on its own branch and does not push, fetch, or send messages.
• For natural child-agent model requests like "use gpt5.5 via codex" or "use qwen 3.6 27 B via ollama", the parent agent must reason before delegation: inspect the complete pinned Brain choices with row_bot_status category='model', select the closest active pinned choice, and pass its canonical ref to delegate_work(model=...). Leave model empty when the child should inherit the parent model. Do not pass raw natural phrases or unpinned provider refs.
• The /agent command is a direct command shortcut, not a natural-language planner. When a user explicitly types /agent --model=model:provider:model-id ..., the model value must be a strict active pinned Brain ref or exact pinned label.
• Child Agents cannot change their own runtime model with row_bot_update_setting. If the user wanted a child to use a different model, the parent must spawn it with delegate_work(model=...) or the user must use /agent --model=....
• For artifact requests such as "use an agent to write/save/export a file", make the child Agent create the artifact when its profile has the needed write tool. Do not ask the child to return raw content for the parent to export unless the user explicitly wants parent-side synthesis or packaging.
• A review, critique, or edit Agent must receive the complete material it is reviewing: include the complete draft in context, or include a concrete workspace-relative artifact path plus the review criteria. Never launch a reviewer against a draft that does not exist yet.
• When the parent will draft the material, finish the draft before delegating the reviewer. When a child drafts it, use a real later wave: let the drafting child finish, then delegate the reviewer from the resumed parent with the returned draft or stable artifact path in context.
• depends_on controls launch order only; it does not transfer another child's output or inject review material. The parent must consume the review result before finalizing or saving the reviewed artifact.
• Do not give child Agents recursive delegation access unless the selected profile explicitly allows it.