---
name: counselors
description: Run multi-agent code reviews with the counselors CLI and synthesize actionable findings.
compatibility: opencode
---

# Counselors Skill

Use this skill when the user asks for second opinions, multi-model review, architecture critique, or bug/risk hunting.

## Core workflow

1. Gather context quickly.
   - Identify the target files and question scope.
   - If needed, inspect `git diff HEAD` and `git diff --staged`.

2. Discover configured tools and groups.
   - Run:
     - `counselors ls`
     - `counselors groups ls`
   - Show the full outputs to the user and ask which tools/group to use.

3. Build prompt file with counselors.
   - Use `counselors mkdir --json` and pipe prompt content in.
   - Use `@path/to/file` references instead of inlining large files.

4. Dispatch run.
   - Single pass: `counselors run -f <promptFilePath> --tools <ids> --read-only best-effort --json`
   - Iterative pass: `counselors loop -f <promptFilePath> --tools <ids> --read-only best-effort --json`
   - Preset loop: `counselors loop --preset <preset> "<focus>" --tools <ids> --read-only best-effort --json`

5. Read outputs and synthesize.
   - Parse the JSON manifest.
   - Read each `outputFile` for successful tools.
   - Check `stderrFile` for failed/empty tools.
   - Produce concise synthesis:
     - consensus
     - disagreements
     - key risks
     - recommendation
   - Include the saved output directory path.

## Usage guardrails

- Ask for tool/group selection before dispatch.
- Confirm final tool list before running.
- Prefer `--json` output for parseability.
- Use long timeouts for dispatch (often 10+ minutes).
- If selected tools include custom `opencode-*`, avoid `--read-only strict` because those tools are configured as `bestEffort` and will be skipped under strict policy.
- If no tools are configured, instruct user to run `counselors init --auto`.

## Useful commands

- `counselors init --auto`
- `counselors tools add`
- `counselors ls`
- `counselors groups ls`
- `counselors run --help`
- `counselors loop --help`