8.3 KiB
Agent Quickstart
Things the last agent had to figure out by exploration. Read this before you start.
What This Repo Is
D&D item cards for a homebrew "Northlands Guild" setting. Each item is a credit-card-sized SVG with a front (mechanics) and back (lore). SVGs are the working files; PDFs are generated for printing.
Key Files to Read First
| File | What it tells you |
|---|---|
.cursor/skills/guild-pack-cards/SKILL.md |
Full pipeline docs, style guide, lore voice, pitfalls 1-19, QA checklist |
AGENTS.md |
Worktree isolation rules, PDF workflow, source-of-truth contract |
HANDOFF.md |
Current work queue (if one exists) |
scripts/README.md |
Detailed script reference |
Repo Structure
0a Novice/ — Tier 0a, handmade mini-items
0b Intermediate/ — Tier 0b, handmade full items
0c Specialist/ — Tier 0c (Tier-1), 7 flavor subdirs
Defense/
Magic/
Offense/
Recovery/
Stealth/
Strike/
Utility/
1 Capable/ — Tier-2, same flavor structure
2 Expert/ — Tier-3
3 Master/ — Tier-4
4 Grandmaster/ — Tier-5
5 Exit/ — Tier-6
scripts/ — Python pipeline
raw-materials*/ — Historical text/images (gitignored)
Each tier folder contains:
*.svg— Card source files (DM version with both front + back) — master sourceITEMS.md— Derived document, generated from SVGs bygenerate-source-of-truth.pyPACKS.md— Pack compositionBALANCE.md— Price/rarity summaryPDFs Players/Singles/— Player-facing PDFs (gitignored)
The Source of Truth Chain
SVGs are the master source. ITEMS.md is derived from SVGs — never edit ITEMS.md directly.
The flow is always: SVG → PDF → ITEMS.md
- Edit lore/mechanics in the SVG (via
rewrite-lore.pyorgenerate-card.py) - Commit SVGs, merge to integration branch
- From the main checkout: export PDFs, then regenerate ITEMS.md
generate-source-of-truth.py --tier "0c Specialist" regenerates ITEMS.md for one tier (use --tier to avoid processing all 8 tiers). It must run from the main checkout where raw materials live.
How Lore Gets Into SVGs
SVG lore lives in <text> elements with shape-inside style and a matrix transform with x_offset > 50. The text is stored as <tspan> elements with explicit x/y coordinates.
To rewrite lore on an existing card:
python3 scripts/rewrite-lore.py "path/to/Card.svg" "New lore text here..."
This uses the same format_lore_text() + set_text_content() pipeline as generate-card.py. It handles paragraph splitting, quote detection, and tspan layout automatically.
NEVER extract lore from SVG tspans, edit it, and reinsert. Tspan line-wrap boundaries eat spaces when concatenated (e.g., "percentof", "aresolved"). Always write complete clean text.
Paragraph break control: rewrite-lore.py calls format_lore_text() which auto-re-paragraphs text at evenly-spaced sentence boundaries, overriding any explicit \n\n breaks in your input. If you need precise control over where paragraph breaks fall (e.g., to set up a punchline), bypass format_lore_text() and call gc.set_text_content(lore_el, text_with_explicit_breaks, wrap_width=42) directly in a Python one-liner. See the Dragonspit Ampoule commit for an example.
To extend the lore text field (when lore clips at bottom):
Lore text on the card back is rendered inside a shape-inside SVG rect. If lore clips at the bottom edge, extend the rect. The technique: find the rect ID from the lore text element's shape-inside:url(#rectID) style, then adjust its y (move up) and height (grow down). A safe default is y-5, height+20 (about one extra line of text).
# In Python (or adapt to a one-liner):
import xml.etree.ElementTree as ET, re
tree = ET.parse("path/to/Card.svg")
root = tree.getroot()
# Find lore text element: shape-inside + matrix x_offset > 50
# Extract rect ID from style: shape-inside:url(#rectID)
# Find rect, adjust: y -= 5, height += 20
# tree.write(...)
This was needed for ~10 Capable-tier cards where 100-120 word lore clipped the last line. The rect dimensions are consistent across cards of the same rarity template, so if one card clips, others from the same template likely will too.
To generate a card from scratch:
python3 scripts/generate-card.py \
--template "path/to/template.svg" \
--item-text "raw-materials/.../Item [Rarity] [Price].txt" \
--image "raw-materials/.../Item_1.png" \
--lore-choice main \
--output "path/to/output.svg" \
--flavor Recovery --tier 0c
To export player PDFs:
python3 scripts/export-player-pdf.py "path/to/card.svg" \
-o "path/to/PDFs Players/Singles/Card Name (price).pdf"
Requires Inkscape (inkscape on PATH). Only works in the main checkout where PDFs live.
Worktree Gotchas
-
Raw materials are gitignored.
raw-materials*/won't exist in worktrees. Scripts that need them (generate-source-of-truth.py,batch-generate.py) must run from the main checkout. -
Never run
generate-source-of-truth.pyin a worktree. Without raw materials, it silently drops consensus negotiation blocks and image references from ITEMS.md. Always run it from the main checkout after merging SVG changes. -
Never edit ITEMS.md directly. It's a derived document. Edit the SVG, merge, then regenerate ITEMS.md from the main checkout.
-
PDFs are gitignored. Generate them from the main checkout after merging.
-
Only commit SVGs from worktrees. The post-merge workflow (PDFs + ITEMS.md regeneration) happens in the main checkout.
Lore Voice (TL;DR)
Tired, competent quartermaster filing field reports who happens to be funnier than they intend. Terry Pratchett footnotes meet British civil servant describing a dragon attack with understatement.
- Opening: Origin story or physical description with unexpected angle. Never "this item does X."
- Middle: In-character experience of using the item. Class/profession reactions for contrast.
- Closing: Earned punchline, practical warning, or dry observation.
- No puns. Humor is structural and observational.
- No boilerplate. See SKILL.md pitfall #10 and #14 for known boilerplate signals.
- 100-120 words, 3-4 paragraphs.
Read the exemplar lore in SKILL.md and study the Master tier (Tier-4) entries in 3 Master/ITEMS.md for tone calibration.
Post-Merge PDF Rebuild (from main checkout)
After merging SVG changes, rebuild PDFs from the main checkout:
# 1. Export DM + Player PDFs for all cards in a tier
bash scripts/rebuild-specialist-pdfs.sh # exports all 0c Specialist
# 2. Assemble packs + QA verification
python3 scripts/assemble-packs.py "0c Specialist"
# 3. Regenerate ITEMS.md
python3 scripts/generate-source-of-truth.py --tier "0c Specialist"
PDF naming convention: Card Name (price).pdf — price tag is required. Remove any PDFs without price tags if they exist alongside price-tagged versions.
Pack assembly gotchas
- Cross-flavor references: Packs can reference cards from other flavors (e.g., Strike packs include Offense cards).
assemble-packs.pysearches all flavors. - Name aliases: PACKS.md uses display names ("Oil of Keen Edge") while SVGs use inverted names ("Keen Edge (oil of)"). The script handles these via an alias table + inversion rules. If a new item has this pattern, add it to
ALIASESinassemble-packs.py. - Curly apostrophes: SVG filenames may contain
'(U+2019) while PACKS.md uses straight'. The script normalizes these for matching.
QA Checklist (run before declaring "done")
- Pack page counts: Each card = 1 page in a player PDF. A 5-card pack = 5 pages.
assemble-packs.pyreports this automatically. Any pack with <4 pages is suspicious. - Singles vs SVGs: The number of player single PDFs per flavor should equal the number of non-template SVGs. Mismatches indicate missed exports or stale files.
- No priceless PDFs: Every PDF in
Singles/andPDFs DM/should have a(price)suffix. Runls */PDFs*/Singles/*.pdf | grep -v '('to check. - ITEMS.md regenerated: After all changes, regenerate ITEMS.md from the main checkout and verify the new lore appears with
grep. - Warnings = 0: The pack assembly script should produce 0 warnings. The only acceptable exception is a card that genuinely doesn't exist yet (document it in the commit message).