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
├── card_cache.json         # Local cache of Scryfall card data
├── deck_analysis.json      # Analysis output
├── collection/             # Raw decklist text files
├── collection_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
├── 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 (decks/*.json)

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

Card Data (collection_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 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
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