---

name: agent-forest description: Orchestrate a 4-32 agent parallel investigation workflow where the current conversation model plans the forest and synthesizes the final answer, while an external OpenAI-compatible API generates the individual agent reports. Use this skill for multi-perspective research, adversarial review, architecture tradeoff analysis, due diligence, or any task that benefits from distinct parallel viewpoints with optional persisted personas and presets.

Agent Forest

Overview

Use this skill when the user wants a true multi-agent workflow instead of a single-pass answer.

Keep the responsibility split strict:

• The current conversation model owns planning, agent design, and final synthesis.
• The external API owns the 4-32 parallel agent reports.
• Do not offload the final integrated answer to the external agents.

When To Use

Use agent-forest when the task benefits from multiple independent viewpoints:

• research and investigation
• market scans or competitive analysis
• architecture debates and tradeoff reviews
• risk discovery and adversarial critique
• product strategy or launch readiness review

Skip this skill for small edits, simple factual questions, or tasks where a single deterministic pass is enough.

Workflow

1. Decide whether the task needs a forest.
2. In the chat model, design a forest with 4-32 distinct agents.
3. Choose one of two planning modes:
   • Dynamic mode: define the agents inline for the current task.
   • Persistent mode: use persona_ref entries or a preset from assets/agent-forest.config.example.json.
4. Prepare a JSON payload containing:
   • task
   • optional context
   • optional research_mode
   • optional constraints
   • optional report_sections
   • either agents or a preset
5. Run the executor script.
6. Read the returned agent reports.
7. Synthesize the final answer locally in the current conversation.

Default Execution Posture

• Default to optimistic execution: draft the payload and try run first.
• Do not gate the first attempt on validate-config, deep config inspection, or extra confirmation unless the user explicitly asks for that.
• If the run fails, use the concrete error to decide the next step.
• Only ask the user for input when the executor proves something is actually missing, such as an API key, base URL, or task detail.
• For chat-driven runs, do not create payload temp files unless the user explicitly asks for saved artifacts. Prefer --payload-stdin first, then --payload-json.
• For result files, prefer stdout by default, but allow the runtime to spill oversized JSON into a temp file when needed to avoid transport truncation.
• Default research posture to research_mode: "agent-led". When the external agent runtime supports web search, browsing, or retrieval, let the forest gather its own evidence instead of front-loading source collection in the launcher.

Execution Rules

• Always keep the forest size between 4 and 32.
• Agent roles should be meaningfully distinct.
• Prefer persisted personas when the user wants stable personalities across runs.
• Prefer inline agents when the task is unusual or needs bespoke viewpoints.
• Treat every external agent response as a report, not the final answer.
• After the reports return, explicitly compare, reconcile, and synthesize them in the chat model.
• For live runs, prefer python scripts/agent_forest.py run --progress ... so the user can see real execution status while the forest is running.
• If your terminal tool supports streaming sessions, keep the run attached and relay short status updates using the actual counts for completed, running, pending, and failed agents.
• Tell the user the planned forest size before launch, and explicitly report which personas or agent viewpoints were selected for this run. Include the persona names, and include roles or goals when that adds clarity.
• When research-capable agents are available, keep launcher-provided context lean. Pass framing, constraints, or proprietary facts, but do not pre-chew the whole public research packet unless the user explicitly wants a shared-context run.
• Keep progress updates anchored to real agent events instead of estimated percentages.
• Never describe the forest as "starting", "running", or "waiting" after the terminal has already emitted completed forest or the shell command has exited successfully. At that point, switch to finished-state wording and continue with synthesis or follow-up research.
• If the runtime switches to summary stdout and saves the full result to a temp file, tell the user that happened and include a clickable file link to the saved JSON.
• Prefer the mutable config path assets/agent-forest.config.json for chat-driven runs. If it does not exist yet, the runtime will fall back to the sibling example config automatically.

Commands

Run first with the mutable config path:

python scripts/agent_forest.py run \
  --config assets/agent-forest.config.json \
  --payload-stdin \
  --stdout-mode auto \
  --progress \
  --pretty
<<'JSON'
{"task":"...","agents":[{"persona_ref":"evidence-hunter"},{"persona_ref":"systems-thinker"},{"persona_ref":"risk-auditor"},{"persona_ref":"contrarian"}]}
JSON

Persist API settings from the conversation:

python scripts/agent_forest.py configure \
  --config assets/agent-forest.config.json \
  --api-base https://ai.huan666.de/v1/chat/completions \
  --model grok-4.20-expert \
  --api-key sk-...

List available presets:

python scripts/agent_forest.py list-presets \
  --config assets/agent-forest.config.json

Run with a preset:

python scripts/agent_forest.py run \
  --config assets/agent-forest.config.json \
  --payload-stdin \
  --preset research-squad-4 \
  --stdout-mode auto \
  --progress \
  --pretty
<<'JSON'
{"task":"..."}
JSON

Run with fully dynamic agents:

python scripts/agent_forest.py run \
  --config assets/agent-forest.config.json \
  --payload-json '{"task":"...","agents":[{"persona_ref":"evidence-hunter"},{"persona_ref":"systems-thinker"},{"persona_ref":"risk-auditor"},{"persona_ref":"contrarian"}]}' \
  --stdout-mode auto \
  --progress \
  --pretty

Inspect the compiled requests without calling the API:

python scripts/agent_forest.py run \
  --config assets/agent-forest.config.json \
  --payload-json '{"task":"...","agents":[{"persona_ref":"evidence-hunter"},{"persona_ref":"systems-thinker"},{"persona_ref":"risk-auditor"},{"persona_ref":"contrarian"}]}' \
  --stdout-mode full \
  --dry-run \
  --pretty

Validate the config only when you need to troubleshoot configuration issues:

python scripts/agent_forest.py validate-config \
  --config assets/agent-forest.config.json

--progress writes live status logs to stderr. --stdout-mode auto keeps full JSON on stdout when it is small enough, and automatically saves oversized results to a temp file while leaving a compact summary plus file path on stdout.

Payload Guidance

Read these only when needed:

• Config details: references/configuration.md
• Payload schema and examples: references/payload-schema.md

Good payloads are explicit about the task, evidence standard, and report shape. Keep synthesis instructions out of the external agents unless the user explicitly wants one agent to act as a recommendation voice. Final synthesis still happens locally.

By default, treat the forest as the primary research engine. If the external agents support web search or retrieval, let them fan out and discover different evidence on their own. Use context for seed facts, proprietary constraints, or a starting frame, not as the default replacement for independent research. Only switch to research_mode: "shared-context" when you intentionally want the launcher to provide the main source pack.

Conversation Configuration

When the user provides api_key, model, or api_base in chat, persist them into the writable config instead of asking the user to edit JSON manually.

• Prefer assets/agent-forest.config.json as the mutable file.
• Keep assets/agent-forest.config.example.json as the checked-in template.
• Use configure to update provider settings directly from the conversation.