agent-design

Designing cc-suite Advisor Agents

cc-suite advisor agents are project-scoped consultative personas backed by claude-octopus. Each lives at .cc-suite/agents/<name>.md and is registered as an MCP server in both .mcp.json (Claude side) and .codex/config.toml (Codex side) by scripts/bridge_agents.py. Either tool can call any agent via mcp__<name>__<tool_name>.

Advisors are not subagents that do work. They are advisors that judge work. Get this mental model right and the rest follows.

When to make an advisor vs use the Task tool vs write a skill

• Task tool / subagent: needed when you want a subagent to execute a focused chunk of work in isolated context (research, refactor a file, run a probe). The subagent returns a result and disappears.
• Skill: knowledge or convention that any caller can load on demand. Static text. No model invocation.
• Advisor agent: needed when you want a persistent persona with a stable point of view that the main caller can consult repeatedly. Different system prompt, different tool restrictions, different model — and the advisor remembers past consultations via its timeline directory.

Rule of thumb: if you'd describe the thing as "a person you'd ask for an opinion," it's an advisor. If you'd describe it as "a job you'd hand off," it's a subagent. If it's "a rulebook," it's a skill.

The file format

---
name: <kebab_or_snake_case_name>          # required if filename ≠ desired name
description: |                             # multi-line block scalar — see below
  <one-line caller-facing summary>

  <example>
  Context: <when a caller would consult this advisor>
  user: "<the kind of question they'd ask>"
  assistant: "<how Claude/Codex would invoke the advisor — show the framing, not the answer>"
  </example>

  <example>
  Context: <a second, different scenario>
  user: "<another representative question>"
  assistant: "<another framing>"
  </example>
tool_name: <name>_consult                  # optional; default <name>_consult
model: opus | sonnet | haiku               # optional; default = caller's setting
allowed_tools: [Read, Grep, Glob]          # default for advisors
disallowed_tools: []                       # optional
permission_mode: default                   # default | acceptEdits | plan | dontAsk | auto | bypassPermissions
max_turns: 5                               # default 5 for advisors
max_budget_usd: 0.50                       # per-consultation cap
effort: high                               # low | medium | high | max
cwd: .                                     # relative to project root, default "."
additional_dirs: []                        # extra readable dirs
prompt_mode: append                        # append (default) or replace
---

# Body content — the system prompt

State the values, not the procedures. See the writing rules below.