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
4.5 KiB
Agent Isolation Workflow
This repository uses per-agent worktree isolation. Every agent task must run in its own branch and worktree.
Rules
- Do not edit from the shared integration checkout.
- Do not
git checkoutbranches in shared checkouts while other agents may be active. - Use one worktree per task and one branch per worktree.
- Keep a
.agent-lockfile in each active worktree. - Keep OpenSpec change artifacts in the main checkout under
openspec/changes/, even when implementation work happens in an agent worktree.
Standard Flow
- Create isolated worktree and branch from integration base:
git worktree add .worktree/<topic> -b agent/<topic>
- Work only in that worktree path:
.worktree/<topic>- Exception: create and edit OpenSpec documents in the main checkout at
openspec/changes/<topic>/.
- Commit and push branch:
agent/<topic>
- Open PR into integration branch.
- After merge, remove worktree:
git worktree remove .worktree/<topic> --force && git branch -d agent/<topic>
OpenSpec Artifact Persistence
Untracked files in the main checkout can vanish between agent sessions. To prevent loss of OpenSpec artifacts across phases (propose, apply, verify, archive):
- Commit after every phase. After creating or updating artifacts under
openspec/changes/<topic>/, immediately stage and commit them in the main checkout:git add openspec/changes/<topic>/ git commit -m "openspec(<topic>): <phase> artifacts" - Before any phase, verify artifacts exist. At the start of apply, verify, or archive, confirm the change directory and its files are present. If missing, check
git log --all --oneline -- openspec/changes/<topic>/to find and restore them before proceeding. - Never re-scaffold over existing artifacts.
openspec new changerefuses to overwrite, but if the directory was lost and you recreate it, the fresh.openspec.yamlresets artifact tracking. Restore from git history instead of re-creating.
Branch boundary note: Committing OpenSpec artifacts on the main checkout's branch while implementation lives on a worktree branch (e.g. agent/<topic>) is a deliberate cross-branch arrangement, not a mistake. It is safe because the openspec/changes/<topic>/ namespace is exclusively owned by that change — no other branch or worktree writes to it.
Archive = Full Close-Out
When archiving a change (openspec-archive), always perform the complete close-out sequence — not just the artifact move. The full sequence is:
- Commit any uncommitted implementation work in the agent worktree.
- Merge the agent branch into the integration branch from the main checkout.
- Push the integration branch to origin.
- Archive the change artifacts (
mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>). - Remove the worktree and branch:
git worktree remove .worktree/<topic> --force git branch -d agent/<topic>
"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.):
- Edit SVGs in the worktree — use
scripts/rewrite-lore.pyfor lore-only changes, orscripts/generate-card.pyfor full card generation. - Commit SVG changes and merge to integration branch from the main checkout.
- From the main checkout (which has raw materials and PDF directories), regenerate derived artifacts:
# 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.