conclave: Instructions file for Codex

AGENTS.md

Instructions for AI coding assistants working on Conclave.

Project Overview

Conclave is a Go CLI that queries multiple LLM providers in parallel and synthesizes their responses. It operates in two modes:

• CLI Mode (default): Wraps provider CLIs (gemini, claude, codex, etc.). Exception: glm calls the Z.ai Coding Plan over HTTP directly (no CLI binary) — see ADR-007.
• API Mode (-g): Direct API calls to providers
• Per-provider transport (<provider>@cli / <provider>@api): pins one token to a transport regardless of -g; bare tokens follow the global mode — see ADR-012.

Architectural decisions are recorded in docs/adr/ (the directory is the index). Run python ~/.claude/skills/adr-ops/scripts/adr-touching.py <path> to find which ADR governs a file before changing it.

Architecture

cmd/
  root.go          # Main CLI entry, flag parsing, orchestration
  decide.go        # `conclave decide`: decision-model panel (ADR-016)
  init.go          # Interactive API key setup

internal/
  config/          # Configuration loading (.env, config.yaml)
  context/         # File/stdin context building
  decide/          # Decision models' non-provider half: question loader, consensus maths, --json/table render (ADR-016)
  benchmarks/      # External quality sources for `models --frontier` (ADR-018); fetched + cached, never committed
    decisionindex/ # Decision Index recomputed from upstream, edition-pinned, mirror-checked
    openrouter/    # OpenRouter benchmarks feed (AA indices, evals; keyed) + decision-model catalog (public)
  frontier/        # Pareto maths, Result assembly, decider name map, terminal + self-contained HTML report (ADR-018)
  judge/           # Verdict synthesis logic
  jsonscan/        # The one "find the JSON object in the prose" scanner (CLI stdout, judge verdicts)
  orchestrator/    # Parallel provider execution
  output/          # Result formatting (JSON, human, brief)
  pricing/         # Cached OpenRouter model catalog: drift warnings, batch prices (ADR-009)
  cache/           # Opt-in response cache, $XDG_CACHE_HOME/conclave/responses/ (ADR-011)
  tui/             # Terminal progress display (Charm bubbletea; silent under --json/-q)
  providers/       # Provider implementations
    provider.go    # Provider interface
    registry.go    # Provider registration and lookup (holds BOTH sets, picks per token)
    transport.go   # <provider>[@cli|@api] token grammar, TransportOf (ADR-012)
    gemini.go      # CLI provider
    api_gemini.go  # API provider
    api_openrouter.go  # Slash-routed OpenRouter backend: any vendor/model token in -g mode (ADR-010)
    decider.go     # Decider interface + typed Question/Answer (NOT a Provider, ADR-016)
    decide_*.go    # System One wire client (decide_systemone.go), jev, clef/clef-flash, OpenRouter slash deciders (ADR-017)
    ...