Architecture Council Skill Guide

Workflow

1. Confirm the architecture question with the user. Clarify scope and which repos are relevant.
2. Build context: run build-context.sh to extract structure, dependencies, API surface, and auth patterns from each repo.
3. Run debate: execute debate.sh to orchestrate propose → critique → synthesize cycle.
4. Present the final synthesis to the user. Highlight the ADR, unresolved tensions, and concrete next steps.
5. Offer follow-up: additional rounds, deeper dive into a specific repo, or implementation planning.

Quick Reference

| Use case | Key flags | | --------------------------------- | ------------------------------------------------------------- | | Single-repo architecture review | --repos "/path/to/repo" | | Multi-repo decision | --repos "/path/repo1,/path/repo2,/path/repo3" | | Quick review (tighter timeouts) | --claude-timeout 300 --codex-timeout 240 | | Deep multi-round debate | --rounds 3 | | Pre-built context | --context-file /path/to/context.md | | Dry run (preview commands) | --dry-run | | Custom models | --claude-model sonnet --codex-model gpt-5.4-pro |

Command Patterns

Full debate (single repo)

bash arch-council/scripts/debate.sh \
  --question "Should we split the API into microservices or keep the monolith?" \
  --repos "/path/to/my-api"

Multi-repo debate

bash arch-council/scripts/debate.sh \
  --question "How should we share auth tokens across these three services?" \
  --repos "/path/to/auth-service,/path/to/api-gateway,/path/to/user-service" \
  --rounds 2

Context-only (for inspection before running debate)

bash arch-council/scripts/build-context.sh \
  --repos "/path/repo1,/path/repo2" \
  --output /tmp/context.md

Dry run

bash arch-council/scripts/debate.sh \
  --question "test" \
  --repos "/path/to/repo" \
  --dry-run

Debate Structure

Each round follows three phases:

1. Propose (Claude): Analyzes codebase context and answers the architecture question with a specific, opinionated recommendation including tradeoffs and migration path.
2. Critique (Codex): Attacks the proposal on hidden coupling, migration traps, auth edge cases, operational complexity, and elegant-but-wrong abstractions. Every criticism must include a concrete alternative.
3. Synthesize (Claude): Produces the final recommendation, incorporating valid critiques and rejecting invalid ones. Includes an ADR and concrete next steps.

Multi-round debates feed the previous synthesis back as input to the next round's proposal, refining through iteration.

Output Artifacts

All artifacts are saved to the output directory (/tmp/arch-council-<timestamp>/ by default):

| File | Description | | ----------------------------- | ------------------------------ | | context.md | Multi-repo context pack | | round<N>_proposal.md | Claude's architecture proposal | | round<N>_critique.md | Codex's critical review | | round<N>_synthesis.md | Final synthesized decision | | round<N>_*_prompt.txt | Prompts sent to each agent |

Error Handling

• Timeout: If Claude or Codex exceeds their timeout, the script continues with partial output if any was captured. Adjust with --claude-timeout / --codex-timeout.
• Empty output: Each agent call retries once on empty output (with stderr visible on retry) before failing.
• Missing CLI: Fails fast with install instructions if claude or codex binaries are not found.
• Non-existent repo: build-context.sh warns and skips missing directories.

Prerequisites

• claude CLI installed and authenticated
• codex CLI installed and authenticated
• git available on PATH
• For reliable timeouts on macOS: brew install coreutils (provides gtimeout)