agents-guide

name	agents_guide
display_name	Agents Guide
icon	hub
description	Guidance for delegating focused work to child Agents.
tools	["agents"]
tags	[]

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.

TRACKING:

• Use agent_status to inspect running, waiting, stopped, failed, or completed child Agents.
• Use agent_wait(run_id=...) for an explicitly requested single-child wait. Use agent_wait(orchestration_id=...) to join required asynchronous work before the parent final answer.
• Use agent_status(orchestration_id=...) to inspect a group, including its required barrier and attempts.
• Use agent_message to queue parent guidance for one child or an orchestration. Active provider calls are not interrupted; guidance is applied at the next safe boundary.
• Use agent_stop for one child or a complete orchestration when work is obsolete, stuck, or the user asks to stop it.
• Use agent_retry for a terminal child when a user-requested replacement is appropriate. Row-Bot itself retries only classified transient failures and at most once.
• Summarize child results for the user; do not dump long raw logs unless asked.

PROFILES:

• Use agent_profiles to discover available built-in and user Agent Profiles.
• Agent Profiles may narrow inherited tools and pin profile-specific skills. Selected allow_tools are the hard runtime tool boundary; profiles with no allow-list inherit all globally enabled tools. Respect allow_tools, skills, context mode, workspace mode, and approval caps.
• Generic direct Agent requests use the worker profile. Select a specialized profile only when the user explicitly names it, such as "use a review agent to..." or /agent review ..., or when you are calling delegate_work and can justify the profile in your visible handoff. Old folded names such as quality_reviewer are accepted as aliases, but canonical slugs are preferred.
• Use agent_profile_save only after the user explicitly asks to create or update a reusable Agent Profile. This action is approval-gated.
• Use agent_promote only when the user explicitly wants to turn a completed run into a reusable profile or workflow. Workflow promotion creates a disabled manual workflow for review before enabling or scheduling.

HANDOFF:

• When synthesizing child results, state which Agents ran, their status, key evidence, conflicts or uncertainty, and the next action.