Files
rick 8f6dbf3aac 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
2026-04-16 19:11:27 +02:00

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 checkout branches in shared checkouts while other agents may be active.
  • Use one worktree per task and one branch per worktree.
  • Keep a .agent-lock file 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

  1. Create isolated worktree and branch from integration base:
    • git worktree add .worktree/<topic> -b agent/<topic>
  2. Work only in that worktree path:
    • .worktree/<topic>
    • Exception: create and edit OpenSpec documents in the main checkout at openspec/changes/<topic>/.
  3. Commit and push branch:
    • agent/<topic>
  4. Open PR into integration branch.
  5. 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):

  1. 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"
    
  2. 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.
  3. Never re-scaffold over existing artifacts. openspec new change refuses to overwrite, but if the directory was lost and you recreate it, the fresh .openspec.yaml resets 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:

  1. Commit any uncommitted implementation work in the agent worktree.
  2. Merge the agent branch into the integration branch from the main checkout.
  3. Push the integration branch to origin.
  4. Archive the change artifacts (mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>).
  5. 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.):

  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:
    # 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.