mtg-builder/AGENTS.md

AGENTS.md

Guide for AI assistants working on this codebase.

Build/Verify Commands

This project has no external dependencies or test framework.

# No lint/typecheck commands currently
# Verify scripts work by running them:
python hydrate.py --help
python scripts/analyze_decks.py --help

Code Style

• Language: Python 3 (stdlib only, no external packages)
• Formatting: 4-space indent, max line length ~100
• Imports: Standard library only (argparse, json, pathlib, urllib, re, sys, os, time)
• CLI: Use argparse with subparsers for multi-command tools
• Error handling: Print to stderr, use sys.exit(1) for failures
• Docstrings: Triple-quoted at module and function level with usage examples
• Type hints: Optional but encouraged for complex functions

Project Structure

├── hydrate.py              # Main CLI - fetches card data from Scryfall
├── cache/
│   └── card_cache.json     # Local cache of Scryfall card data
├── output/
│   ├── deck_analysis.json  # Analysis output
│   └── hydrated/           # Enriched card data by type
│       ├── deck.json       # All cards combined
│       ├── commander.json
│       ├── creatures.json
│       ├── instants.json
│       ├── sorceries.json
│       ├── artifacts.json
│       ├── enchantments.json
│       ├── lands.json
│       └── planeswalkers.json
├── data/
│   ├── collection/         # Raw decklist text files
│   └── decks/              # Deck definitions (JSON)
│       └── <deck_name>.json    # name, commander, colors, archetype, cards
├── scripts/
│   ├── analyze_decks.py    # Find upgrade options for decks
│   ├── find_synergies.py   # Search for synergistic cards
│   ├── parse_deck.py       # Parse text decklists to JSON
│   └── deck_report.py      # Generate markdown reports
└── docs/
    └── templates/          # Documentation templates

Data Formats

Deck JSON (data/decks/*.json)

{
  "name": "Deck Name",
  "commander": "Commander Name",
  "colors": ["U", "G", "W"],
  "archetype": "Theme Description",
  "cards": {
    "Card Name": count,
    ...
  }
}

Card Data (output/hydrated/*.json)

Array of card objects with Scryfall fields:

• name, mana_cost, cmc, colors, color_identity
• type_line, oracle_text, power, toughness, loyalty
• scryfall_uri, count

Extension Guide

Adding a New Deck

1. Create data/decks/<name>.json with required fields
2. Run python scripts/update_docs.py to regenerate documentation

Adding a New Script

1. Create scripts/<name>.py with argparse CLI
2. Follow existing patterns: load_collection(), argparse with --help
3. Update README template with usage example
4. Run python scripts/update_docs.py

Modifying Deck Analysis

• scripts/analyze_decks.py: Core logic for finding upgrades
• Color identity matching uses color_identity field from Scryfall
• Cards are categorized by type_line

Current Decks

Deck	Colors	Commander	Archetype
my_choco_deck	BUW	G'raha Tia, Scion Reborn	Auto-generated
Choco	UGW	Choco, Seeker of Paradise	Bird Tribal Landfall
Hazel	BG	Hazel of the Rootbloom	Golgari Aristocrats
Palamecia	UR	The Emperor of Palamecia // The Lord Master of Hell	Izzet Self-Mill Storm
Yshtola	UBW	Y'shtola, Night's Blessed	Esper Stax Drain