mtg-commander

What this skill does

# MTG Commander Deck Builder

Multi-agent pipeline for building optimized, format-legal, budget-compliant Commander (EDH) decklists.

> **User-facing guide:** see [`README.md`](README.md) for install, quick start, and troubleshooting. Config authoring walkthrough at [`references/config-walkthrough.md`](references/config-walkthrough.md).

## Sub-Agent Dispatch Guardrail

Every pipeline step — primary agents and challenger agents alike — MUST be dispatched as a separate sub-agent via the Agent tool. This is NON-NEGOTIABLE.

NEVER inline any pipeline step. Running a pipeline step inside the orchestrator's own context instead of spawning a dedicated sub-agent is a GUARDRAIL VIOLATION. If you catch yourself thinking "I'll just run this step inline to save time," stop. That thought is the violation.

**Rationale:**

- **Context isolation** — each agent receives only its defined inputs (deck state, intake params, reference files). No bleed from prior agent reasoning.
- **Adversarial independence** — challengers MUST NOT share context with the primary they are reviewing. Shared context defeats the entire adversarial architecture.
- **Correction loop integrity** — self-correction routing depends on clean agent boundaries. Inlined steps corrupt the correction signal.

**Anti-pattern (from real session 0876a59e):**

> "I'll run the agent roles inline to keep things moving..."

This collapsed all four agents into a single context window, destroyed adversarial independence, and produced a deck with 14 undetected color identity violations. The correction loop never fired because there were no agent boundaries to trigger it. NEVER repeat this.

**All 8 dispatches** (4 primary + 4 challenger) MUST be separate Agent tool invocations. No exceptions. No "just this once." No "it's a simple deck."

## Configuration (.mtg-commander.yml)

At pipeline start (after intake confirmation, before the pipeline banner), check the user's working directory for `.mtg-commander.yml`.

**If absent:** Use all defaults. Output a one-line note: `No .mtg-commander.yml found — using defaults. Create one to customize loop caps, price goals, and escalation.`

**If present:** Validate keys against the schema below. Apply overrides for recognized keys. Use defaults for any missing keys. Warn on invalid or unrecognized keys (list their names) but NEVER fail the pipeline due to config. A parse-failure (invalid YAML) also warns and falls back to all defaults.

**Status line** (shown after intake, before banner):
- Config loaded: `Config loaded from .mtg-commander.yml (version 1)`
- Config absent: `No .mtg-commander.yml found — using defaults.`

### Schema (version 1)

```yaml
version: 1                    # schema version — required for future migrations
loops:
  deck_builder: 2             # max adversarial loop iterations for Deck Builder/Challenger
  rules_judge: 2              # max adversarial loop iterations for Rules Judge/Challenger
  optimizer: 2                # max adversarial loop iterations for Optimization/Challenger
  price_evaluator: 2          # max adversarial loop iterations for Price/Challenger
price_rules:
  max_card_price: null         # soft per-card goal in USD; null = no goal (15% hard cap still applies)
  escalation: true             # true = escalate unsubstitutable over-goal cards to user; false = auto-substitute silently
  budget_source: higher        # higher | tcgplayer | cardkingdom — which vendor total to use for budget check
escalation:
  on_loop_exhaustion: warn     # warn | block | best-effort — behavior when adversarial loop cap is reached without PASS
```

### Defaults

All keys above show their default values. Missing file = all defaults. Partial file = stated values override defaults, unstated keys use defaults. Unknown keys = warned and ignored.

### Validation Rules

- `version` must be `1` (integer). Other values: warn, use defaults.
- `loops.*` must be positive integers >= 1. Invalid: warn, use default (2).
- `price_rules.max_card_price` must be null or a positive number. Invalid: warn, use null.
- `price_rules.escalation` must be boolean. Invalid: warn, use true.
- `price_rules.budget_source` must be one of `higher`, `tcgplayer`, `cardkingdom`. Invalid: warn, use `higher`.
- `escalation.on_loop_exhaustion` must be one of `warn`, `block`, `best-effort`. Invalid: warn, use `warn`.

---

## Required Setup

Before using this plugin, add these domains to your allowed WebFetch domains in Claude Code settings:

  Settings > Permissions > WebFetch > Add: api.scryfall.com
  Settings > Permissions > WebFetch > Add: archidekt.com

## Overview

This skill orchestrates four sub-agents through a sequential pipeline:

1. **Deck Builder** -- Intake, commander validation, synergy-first card selection
2. **Rules Judge** -- Format legality validation (100 cards, color identity, banned list, singleton)
3. **Optimization Reviewer** -- Synergy density, structural minimums, mana curve analysis
4. **Price Evaluator** -- Budget compliance, per-card caps, live Scryfall pricing

The pipeline self-corrects: when an agent returns FAIL, violations route back to the Deck Builder for correction. Max correction cycles are governed by `pipeline.max_self_correction` in `.delivery/config.yml` (default: 3).

---

## Card Lookup Utility

All agents use `card_lookup.py` via the Bash tool for Scryfall API access:

```
python ${SKILL_DIR}/scripts/card_lookup.py validate --name "Sol Ring"
python ${SKILL_DIR}/scripts/card_lookup.py search --query "oracle:sacrifice type:creature id:B legal:commander"
python ${SKILL_DIR}/scripts/card_lookup.py batch --names "Sol Ring" "Dark Ritual" "Cabal Coffers"
python ${SKILL_DIR}/scripts/card_lookup.py price --name "Sol Ring"
python ${SKILL_DIR}/scripts/card_lookup.py batch-price --names "Sol Ring" "Dark Ritual"
python ${SKILL_DIR}/scripts/card_lookup.py ck-price --name "Sol Ring"
python ${SKILL_DIR}/scripts/card_lookup.py ck-batch-price --names "Sol Ring" "Dark Ritual" "Phyrexian Arena"
python ${SKILL_DIR}/scripts/card_lookup.py random-commander --colors BG --strategy sacrifice
python ${SKILL_DIR}/scripts/card_lookup.py validate-deck --commander "Karlov of the Ghost Council" --cards "Sol Ring" "Sejiri Refuge" "Dark Ritual"
```

---

## Intake Flow

When a user requests a Commander deck, extract the 7 intake parameters. Detect which intake mode applies based on the user's first message.

### Mode Detection

**Mode A (Full Inline)**: The user provides all or most parameters in one message. Extract all 7 parameters, confirm what was found, and proceed directly to the pipeline.

**Mode B (Partial Inline)**: The user provides some parameters. Extract what is given, then ask for the remaining parameters one at a time. Each answer can inform the next question's context.

**Mode C (Guided)**: The user provides no parameters or asks for help. Walk through all 7 questions sequentially.

### The 7 Intake Parameters

| # | Parameter | Smart Behavior | Default |
|---|-----------|---------------|---------|
| 1 | Color identity | If user names a commander first, derive from commander | None (must specify or name commander) |
| 2 | Commander name | If color identity given, offer 3 suggestions filtered by color + strategy | None (must specify or request suggestions) |
| 3 | Strategy archetype | Infer from commander if possible | Inferred from commander's typical builds |
| 4 | Power level (1-10) | Describe the scale in plain language | 6 ("focused casual") |
| 5 | Meta alignment | Adapt description to power level answer | "Casual" if <= 5, "Mid-power" if 6-7, "High-power" if 8+ |
| 6 | Total budget (USD) | Warn if budget is very low for the commander's color count | None (must specify) |
| 7 | Card restrictions | Prompt with examples: must-include, must-exclude, per-card cap, no infinite combos | None |

Load `references/intake-questions.md` for the full question text, valid ranges, and validation rules.

### Power Level Scale (show on first use or when user asks)

```
Pow