conclave AGENTS.md

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

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
  init.go          # Interactive API key setup

internal/
  config/          # Configuration loading (.env, config.yaml)
  context/         # File/stdin context building
  judge/           # Verdict synthesis logic
  orchestrator/    # Parallel provider execution
  output/          # Result formatting (JSON, human, brief)
  progress/        # Terminal progress display
  providers/       # Provider implementations
    provider.go    # Provider interface
    registry.go    # Provider registration and lookup
    gemini.go      # CLI provider
    api_gemini.go  # API provider
    ...

Key Conventions

Provider Pattern

Each provider implements the Provider interface:

type Provider interface {
    Name() string
    DefaultModel() string
    IsAvailable() bool
    Query(ctx context.Context, prompt string, model string) (string, time.Duration, *Metrics, error)
}

• CLI providers wrap external commands (gemini.go, claude.go) and embed baseProvider
• API providers make HTTP calls (api_gemini.go, api_anthropic.go) and embed apiBaseProvider
• Exception: glm.go is a CLI-mode provider that embeds apiBaseProvider (HTTP to the Coding Plan endpoint, no binary) — ADR-007

Adding a New Provider

1. Create internal/providers/{name}.go (CLI) and/or api_{name}.go (API)
2. Implement the Provider interface
3. Register in AllCLIProviders() or AllAPIProviders() in registry.go
4. Add to providerSetupInfo in cmd/init.go for interactive setup
5. Update tests in provider_test.go
6. Document in README.md and docs/MODEL_REGISTRY.md