# 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/ -b agent/` 2. Work only in that worktree path: - `.worktree/` - Exception: create and edit OpenSpec documents in the main checkout at `openspec/changes//`. 3. Commit and push branch: - `agent/` 4. Open PR into integration branch. 5. After merge, remove worktree: - `git worktree remove .worktree/ --force && git branch -d agent/` ## 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//`, immediately stage and commit them in the main checkout: ```bash git add openspec/changes// git commit -m "openspec(): 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//` 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/`) is a deliberate cross-branch arrangement, not a mistake. It is safe because the `openspec/changes//` 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/ openspec/changes/archive/YYYY-MM-DD-`). 5. **Remove the worktree and branch:** ```bash git worktree remove .worktree/ --force git branch -d agent/ ``` "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.