docs: add card content workflow to AGENTS.md, create QUICKSTART.md
AGENTS.md: document SVG → PDF → ITEMS.md flow. SVGs are master source; ITEMS.md is derived. Never edit ITEMS.md directly or run generate-source-of-truth.py in a worktree (drops consensus blocks). QUICKSTART.md: captures repo structure, source-of-truth chain, lore pipeline, worktree gotchas, and voice guide for agent onboarding. Made-with: Cursor
This commit is contained in:
@@ -53,6 +53,28 @@ When archiving a change (`openspec-archive`), always perform the complete close-
|
||||
|
||||
"Done" means done — no orphan worktrees, no unmerged branches, no unpushed commits.
|
||||
|
||||
## Card Content Workflow: SVG → PDF → ITEMS.md
|
||||
|
||||
**SVGs are the master source for card content.** ITEMS.md is a derived document generated from SVGs by `scripts/generate-source-of-truth.py`. Never edit ITEMS.md directly — it will be overwritten on the next regeneration.
|
||||
|
||||
PDFs (`**/*.pdf`), images (`**/*.png`), and raw materials (`raw-materials*/`) are gitignored. They only exist in the main checkout's local filesystem, not in worktrees.
|
||||
|
||||
**Workflow for card content changes (lore, mechanics, etc.):**
|
||||
|
||||
1. **Edit SVGs in the worktree** — use `scripts/rewrite-lore.py` for lore-only changes, or `scripts/generate-card.py` for full card generation.
|
||||
2. **Commit SVG changes and merge to integration branch** from the main checkout.
|
||||
3. **From the main checkout** (which has raw materials and PDF directories), regenerate derived artifacts:
|
||||
```bash
|
||||
# Export player PDFs for changed cards
|
||||
python3 scripts/export-player-pdf.py "path/to/card.svg" \
|
||||
-o "path/to/PDFs Players/Singles/Card Name (price).pdf"
|
||||
|
||||
# Regenerate ITEMS.md (use --tier to target a single tier)
|
||||
python3 scripts/generate-source-of-truth.py --tier "0c Specialist"
|
||||
```
|
||||
|
||||
**Key constraint:** `generate-source-of-truth.py` requires raw materials for consensus negotiation blocks and image references. Running it in a worktree will silently drop that data. Always run it from the main checkout after merge.
|
||||
|
||||
## Lock File Contract
|
||||
|
||||
Each active worktree contains `.agent-lock` with owner/task/timestamp. If lock ownership is unclear, stop and ask before making edits.
|
||||
|
||||
+117
@@ -0,0 +1,117 @@
|
||||
# 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-18 |
|
||||
| `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 source**
|
||||
- `ITEMS.md` — Derived document, generated from SVGs by `generate-source-of-truth.py`
|
||||
- `PACKS.md` — Pack composition
|
||||
- `BALANCE.md` — Price/rarity summary
|
||||
- `PDFs 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**
|
||||
|
||||
1. Edit lore/mechanics in the SVG (via `rewrite-lore.py` or `generate-card.py`)
|
||||
2. Commit SVGs, merge to integration branch
|
||||
3. 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:
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
### To generate a card from scratch:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
1. **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.
|
||||
|
||||
2. **Never run `generate-source-of-truth.py` in 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.
|
||||
|
||||
3. **Never edit ITEMS.md directly.** It's a derived document. Edit the SVG, merge, then regenerate ITEMS.md from the main checkout.
|
||||
|
||||
4. **PDFs are gitignored.** Generate them from the main checkout after merging.
|
||||
|
||||
5. **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.
|
||||
Reference in New Issue
Block a user