Architect

Architect Skill

Minimal-linear review workflow for architectural decision-making: proposals → tournament → ADR

Default Migration Stance

Unless the user explicitly asks for compatibility, evaluate proposals as breaking refactors with full migration.

• Prefer architectures that replace old paths cleanly over ones that preserve them via wrappers, adapters, or phased coexistence.
• Treat compatibility layers as costs that require explicit justification, not default prudence.
• If a compatibility boundary must remain, proposals should name the live boundary and its removal condition.

Quick Start

# Full cycle (generate → rank → optionally decide)
skills/architect/run.sh review "How should we implement event sourcing?"

# Step-by-step workflow with source context (RECOMMENDED)
cat proposal.md src/core/*.cljc | \
  skills/architect/run.sh propose "Should we add fourth kernel operation?"

skills/architect/run.sh rank <run-id>
skills/architect/run.sh decide <run-id> approve <proposal-id> "Best approach"

Critical: Provide Full Context

Lesson learned: LLMs need complete context to understand architectural decisions correctly.

Best prompt (95% success) - Include vision, overview, AND source:

cat VISION.md \
    dev/overviews/AUTO-SOURCE-OVERVIEW.md \
    src/core/*.cljc | \
  skills/architect/run.sh propose "Review this architecture from first principles. \
  If the current design is already solid and elegant, say so - we don't want to \
  change unnecessarily."

Good prompt (80% success):

cat .architect/analysis/proposal.md \
    src/core/ops.cljc \
    src/plugins/selection/core.cljc | \
  skills/architect/run.sh propose "Evaluate this specific proposal"

Bad prompt (0% success):

skills/architect/run.sh propose "Should we add a fourth operation?"
# → LLMs guess what you mean, usually incorrectly

Why this matters:

• Generic descriptions → misunderstanding
• Source code context → accurate evaluation
• Vision/overview docs → understanding project goals and philosophy
• Explicit "if current is good, say so" → prevents unnecessary spiraling
• Explicit framing → focused analysis

Context checklist:

• Project vision/philosophy (VISION.md, CLAUDE.md, etc.)
• Architecture overview (AUTO-SOURCE-OVERVIEW.md, etc.)
• Relevant source code (use repomix for full context)
• Explicit evaluation criteria in prompt
• Permission to recommend "keep as-is"

Commands

review - Full Cycle

One-shot review: generate proposals → rank → present results

skills/architect/run.sh review "problem description"

Options:

• --auto-decide - Automatically approve if confidence > threshold
• --confidence 0.85 - Confidence threshold for auto-decision (default: 0.85)
• --constraints-file <path> - Project constraints file (default: .architect/project-constraints.md)

propose - Generate Proposals

Generate proposals from multiple LLM providers in parallel via llmx

skills/architect/run.sh propose "problem description"

Options:

• --providers gemini,codex,grok,kimi2 - Specify providers (default: gemini,codex,grok)
• --constraints-file <path> - Project constraints file

Providers: gemini, codex (with reasoning-effort high), grok, kimi2

Output:

• .architect/review-runs/{run-id}/run.json - Run metadata
• .architect/review-runs/{run-id}/proposal-{provider}.json - Individual proposals
• Returns run_id for next steps

rank - Rank Proposals

NOTE: Ranking uses simple fallback heuristic because tournament CLI is not available.

skills/architect/run.sh rank <run-id>

Options:

• --auto-decide - Auto-approve if confidence > threshold
• --confidence 0.8 - Confidence threshold (default: 0.8)
• --constraints-file <path> - Project constraints file

Output:

• .architect/review-runs/{run-id}/ranking.json - Rankings with winner
• Shows next actions: approve, revise, or reject_all

Limitation: The Python script runs in subprocess and cannot access MCP tools.

Better approach: Use tournament MCP from Claude Code directly:

# After propose finishes, ask Claude Code to rank via tournament MCP
# Example: "Use tournament MCP to rank proposals from run <run-id>"

Important distinction:

• Validation use case: Same prompt → multiple providers → check consensus
  • If tournament returns INVALID (all theta=1.0), proposals are identical = validation success!
• Comparison use case: Different architectures → rank by quality
  • Requires semantically different proposals to compare

See IMPROVEMENTS.md for details on tournament integration and use cases.

refine - Refine Proposal

Refine a proposal with feedback loops (max 5 rounds)

skills/architect/run.sh refine <run-id> <proposal-id> "feedback message"

Options:

• --max-rounds 5 - Maximum refinement rounds (default: 5)

Output:

• .architect/review-runs/{run-id}/spec.json - Refined specification
• Validation results for each round

decide - Record Decision

Record final decision as ADR (Architectural Decision Record)

skills/architect/run.sh decide <run-id> approve <proposal-id> "rationale"
skills/architect/run.sh decide <run-id> reject <proposal-id> "reason"
skills/architect/run.sh decide <run-id> defer "" "needs more research"

Output:

• .architect/review-runs/{run-id}/adr-{run-id}.md - Decision record
• Logs to .architect/review-ledger.jsonl

Configuration

LLM Providers

Working models (2025-11-07):

• gemini-3.1-pro-preview, gpt-5-pro, grok-4-latest, kimi-k2-thinking, claude-sonnet-4-5

Gotchas:

• --reasoning-effort high only works with OpenAI (gpt-5-pro)
• Model names: hyphens not dots (claude-sonnet-4-5 not 4.5)
• subprocess: Use input=prompt, NOT shell=True (breaks with parentheses)
• gpt-5-pro requires --temperature 1

Tournament Settings

Gotcha: Judge names ≠ llmx model names

• llmx: gemini-3.1-pro-preview (hyphens, dots)
• tournament judges: gemini25-pro (no dots, compact)

Available judges: gpt5-pro, gemini25-pro, grok-4, claude-4.5, kimi-k2-thinking

Default: ["gemini25-pro", "claude-4.5"], max_rounds=3

Workflow Settings

Evaluation Criteria

Rankings prioritize (in order):

1. Simplicity (HIGHEST) - Solo dev can understand/debug easily
2. Debuggability - Observable state, clear errors, REPL-friendly
3. Flexibility - Can skip stages, run tools independently
4. Provenance - Trace proposal → spec → implementation
5. Quality gates - Catch bad specs before implementation

Red flags:

• Infinite refinement loops
• Hidden automation
• Complex orchestration (hard to debug when stuck)
• Tight coupling (can't run stages independently)
• Over-engineering (10+ agents, dynamic planning)

File Structure

All outputs go to .architect/:

.architect/
├── review-runs/{run-id}/      # Architect workflows
│   ├── run.json              # Metadata
│   ├── proposal-google.json  # Proposals from each provider
│   ├── proposal-openai.json
│   ├── proposal-xai.json
│   ├── ranking.json          # Tournament results
│   ├── spec.json            # Refined spec (if refined)
│   └── adr-{run-id}.md      # Decision record
├── reports/{research-id}/     # Research reports
├── review-ledger.jsonl        # Append-only provenance log
└── project-constraints.md     # Project-specific constraints

Requirements

CLI Tools:

• llmx - Unified LLM CLI for all providers (google, openai, xai)
• tournament-mcp - Tournament evaluation (optional, uses fallback if unavailable)

API Keys:

• GEMINI_API_KEY
• OPENAI_API_KEY
• XAI_API_KEY

Python:

• Python 3.10+
• No external dependencies (uses stdlib only)

Examples

Explore Multiple Approaches

# Generate proposals from all providers
skills/architect/run.sh propose "How should we implement undo/redo?"

# Review proposals (stored in .architect/review-runs/{run-id}/)
cat .architect/review-runs/{run-id}/proposal-*.json

# Rank them
skills/architect/run.sh rank {run-id}

# Decide
skills/architect/run.sh decide {run-id} approve {winner-id} "Clear and simple"

Quick Decision

# Full cycle with auto-decision if confidence > 85%
skills/architect/run.sh review "State management approach" --auto-decide --confidence 0.85

Refine Before Deciding

# Generate and rank
skills/architect/run.sh propose "API design patterns"
skills/architect/run.sh rank {run-id}

# Refine winner with feedback
skills/architect/run.sh refine {run-id} {winner-id} "Add error handling examples"

# Then decide
skills/architect/run.sh decide {run-id} approve {winner-id} "Complete after refinement"

With Project Constraints

# Create constraints file
cat > .architect/project-constraints.md <<EOF
# Project Constraints

## Hard Requirements
- ClojureScript only
- REPL-friendly (no hidden state)
- Event sourcing architecture

## Soft Preferences
- Prefer core.async over callbacks
- Minimize dependencies
EOF

# Use constraints in review
skills/architect/run.sh review "How to handle async operations?" \
  --constraints-file .architect/project-constraints.md

Integration

With Tournament-MCP

The skill can use tournament-mcp for ranking when called from Claude Code:

# Generate proposals
skills/architect/run.sh propose "problem description"

# Then ask Claude Code to rank them
# "Use tournament MCP to rank proposals from run <run-id>"

Two use cases:

1. Validation: Same prompt, multiple providers → check consensus (INVALID = good!)
2. Comparison: Different architectures → rank by quality

With Research Skill

Combine with research for comprehensive analysis:

# Research existing approaches
skills/research/run.sh explore re-frame "state management patterns"

# Generate proposals informed by research
skills/architect/run.sh propose "State management: re-frame vs reagent"

Utility Commands

# List all review runs
skills/architect/run.sh list

# Show run details
skills/architect/run.sh show <run-id>

# View provenance ledger
skills/architect/run.sh ledger

Storage Paths

Templates

Troubleshooting

No API keys:

• Set GEMINI_API_KEY, OPENAI_API_KEY, XAI_API_KEY in .env
• Or export in shell: export GEMINI_API_KEY="your-key"

Tournament-mcp not found:

• Ranking will use simplified comparison mode
• Install tournament-mcp for full tournament evaluation

Empty proposals:

• Check API key validity
• Check CLI tool is in PATH: which llmx
• Check .env is sourced

Run not found:

• Verify run ID: ls .architect/review-runs/
• Check file exists: cat .architect/review-runs/{run-id}/run.json

Python command not found:

• Install Python 3.10+ or uv
• Skill auto-detects: uv > python3 > python

Resources (Level 3)

• run.sh - Main CLI wrapper
• lib/architect.py - Python implementation
• data/templates/ - ADR and spec templates
• .architect/ - All outputs and logs
• test-variant-a.sh - Test script for variant-a prompts
• GPT5_IMPROVEMENTS.md - GPT-5 integration notes

See Also

• Project docs: ../../CLAUDE.md#agent-skills-overview
• GPT-5 prompting: ../gpt5-prompting/SKILL.md
• Research skill: ../research/SKILL.md
• Tournament MCP: ~/Projects/tournament-mcp/