# Architect

> Architectural decision-making workflow using tournament-based proposal generation and ranking. Generates proposals from multiple LLM providers (google, openai, xai) via llmx unified CLI, ranks them via tournament evaluation, optionally refines with feedback loops, and records decisions as ADRs. Use when exploring architectural alternatives, comparing implementation approaches, or making significant design decisions. Requires API keys, Python 3.10+.

- Skill: `markusstrasser/architect` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx skillmds@latest add markusstrasser/architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/markusstrasser/architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: markusstrasser (https://skillmd.com/u/markusstrasser)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/markusstrasser/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

```bash
# 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:**

```bash
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):**

```bash
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):**

```bash
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

```bash
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

```bash
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.

```bash
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:

```bash
# 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)

```bash
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)

```bash
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

| Setting           | Default | Description                       |
| ----------------- | ------- | --------------------------------- |
| Proposal Count    | 3       | Generate from 3 providers         |
| Auto-decide       | false   | Require human approval by default |
| Refine Max Rounds | 5       | Maximum refinement iterations     |

## 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

```bash
# 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

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

### Refine Before Deciding

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
# 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

```bash
# 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

| Path                             | Contents                       |
| -------------------------------- | ------------------------------ |
| `.architect/review-runs/`        | Individual review workflows    |
| `.architect/adr/`                | Architectural Decision Records |
| `.architect/review-ledger.jsonl` | Append-only provenance log     |
| `.architect/specs/`              | Refined specifications         |

## Templates

| Template | Path                              | Use                    |
| -------- | --------------------------------- | ---------------------- |
| ADR      | `data/templates/adr-template.md`  | Decision records       |
| Spec     | `data/templates/spec-template.md` | Refined specifications |

## 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/`