council

# Council Protocol

This protocol is loaded on demand by the architect stub in `src/agents/architect.ts`.
The architect prompt keeps only activation, action, and hard safety constraints;
the full execution details live here.

### MODE: COUNCIL

Activates when: user invokes `/swarm council <question>` (optionally with
`--preset <name>` and/or `--spec-review`).

Purpose: convene a fixed three-agent multi-model General Council
(generalist / skeptic / domain expert) for an advisory deliberation. The
architect runs a curated web research pass upfront, dispatches the three agents
in parallel with the gathered RESEARCH CONTEXT, routes any disagreements back
for one targeted reconciliation round, and synthesizes the final user-facing
answer directly.

This mode is ADVISORY. It does not block any other workflow and does not modify
code, plans, or specs. The output is for the user (general mode) or for the spec
being drafted (spec_review mode is available via `/swarm council --spec-review`
for manual spec review). General Council advisory input is offered as an early
workflow option in MODE: BRAINSTORM (Phase 1b).

#### Pre-flight (always run first)

1. Read `council.general` from the resolved opencode-swarm config. Resolution
   is global first (`~/.config/opencode/opencode-swarm.json`), then project
   override (`.opencode/opencode-swarm.json`). A global config is valid and must
   be used when no project override is present; do not fail after checking only
   the project file. If `council.general.enabled` is not true OR no search API
   key is configured (neither `council.general.searchApiKey` nor the
   corresponding env var `TAVILY_API_KEY` / `BRAVE_SEARCH_API_KEY`),
   surface to the user: "General Council is not enabled. Set
   council.general.enabled: true and configure a search API key in
   global ~/.config/opencode/opencode-swarm.json or project
   .opencode/opencode-swarm.json." Then STOP.

#### Research Phase (always run before dispatching council agents)

2. Formulate 1-3 targeted `web_search` queries that best capture the
   information needed to answer the question. Prefer specific, keyword-focused
   queries over broad ones.

   Hard grounding rules:
   - Do not append a model training-cutoff year to searches.
   - Use `web_search` with its default `freshness: "auto"` behavior for
     current queries unless the user explicitly asked for a historical window.
   - Preserve each `web_search` result's normalized `query`, `temporalIntent`,
     `freshness`, and `removedStaleYears` metadata in RESEARCH CONTEXT audit
     notes.
   - For current, latest, today, now, state-of-the-art, pricing, release-status,
     legal/regulatory, financial, security, or otherwise time-sensitive
     questions, the Research Phase must produce usable current sources before
     council dispatch.
   - If `web_search` returns no results or an error for a time-sensitive
     question, stop and surface the failed search result to the user instead of
     dispatching ungrounded members.
   - For stable/non-current questions, if `web_search` returns no results or an
     error, note this in the dispatch message and proceed without a context
     block. In that degraded mode, members may use stable background knowledge
     only and must not make current-fact claims.

   Compile all successful results into a RESEARCH CONTEXT block in this format:

```text
RESEARCH CONTEXT
================
[1] <title> - <url>
    <snippet>
    query: <normalized query>; temporalIntent: <current|historical|unspecified>; freshness: <day|week|month|year|none>; removedStaleYears: <comma-separated years or none>

[2] <title> - <url>
    <snippet>
...
```

#### Round 1 - Parallel Independent Analysis

3. Dispatch `the active swarm's council_generalist agent`,
   `the active swarm's council_skeptic agent`, and
   `the active swarm's council_domain_expert agent` in PARALLEL -- one message
   per agent, then STOP and wait for all responses. Each dispatch message must
   include:
   - The question
   - Round number: 1
   - The CURRENT DATE in ISO `YYYY-MM-DD` form
   - The full RESEARCH CONTEXT block from step 2
   - Instruction: "Cite from the RESEARCH CONTEXT for external evidence. Your
     memberId and role are hardcoded in your system prompt."

Do NOT share other agents' responses at this stage.

4. Collect all three JSON responses. The `round1Responses` array will contain
   entries with `memberId` of `council_generalist`, `council_skeptic`, and
   `council_domain_expert` and `role` of `generalist`, `skeptic`, and
   `domain_expert` respectively. These come from the agents' JSON output; no
   manual construction is needed.

#### Synthesis and Deliberation (when council.general.deliberate is true; default true)

5. Call `convene_general_council` with mode set from the command (`general` or
   `spec_review`), `question`, and the collected `round1Responses` only (omit
   `round2Responses`). Inspect the returned `disagreementsCount`.

6. If `disagreementsCount > 0`:
   a. For each disagreement in the tool's response, identify the disputing
      agents (the agents listed in the disagreement's positions, identified by
      memberId: `council_generalist`, `council_skeptic`, or
      `council_domain_expert`).
   b. Re-delegate ONLY to the disputing agents -- one message per agent --
      passing: their Round 1 response, the disagreement topic, the opposing
      position(s), round number 2, and the same RESEARCH CONTEXT block.
   c. Collect the Round 2 responses.
   d. Call `convene_general_council` AGAIN with both `round1Responses` AND
      `round2Responses` populated.

#### Output

7. Present the final answer to the user from the `synthesis` returned by
   `convene_general_council`. Apply these output rules directly:
   - LEAD WITH CONSENSUS: open with the strongest consensus position.
     Confidence-weighted: higher-confidence claims from multiple agents rank
     first, but evidence quality outranks raw confidence. Never elevate a