Archive-Suite: Instructions file for Claude Code

Archive Suite — Agent / Concurrent-Development Guide

Umbrella conventions for working in this monorepo (solo or with multiple agents in parallel). Each app also has its own AGENTS.md with app‑specific lanes — read it before working inside a subdir: ArchiveProcessor/AGENTS.md · ArchiveReader/AGENTS.md · ArchiveNotes/AGENTS.md.

🛑 If the owner asks for the "daemon report" (or "the report", or the old name "morning review"), that is a WALKTHROUGH — one decision at a time, waiting for each answer, writing nothing. It is not a summary and not a plan entry. Read CLAUDE.md → "THE DAEMON REPORT IS A WALKTHROUGH, NOT A DOCUMENT" before replying. Appending to that section is the unattended daemon's job, never yours.

Ground rules

• Worktree-first — mandatory, not optional. Before any edit/build/commit, be in your own git worktree; never work in the primary checkout, even if you think you're the only instance running. Run the idempotent first-step check in CLAUDE.md → "Worktree-first" (it creates ../suite-wt-<stamp> only if you're not already isolated, so it's safe to run every session). Per‑worktree DerivedData (-derivedDataPath ./build/DD, already the default in each launch.sh) keeps parallel builds from colliding. Remove your worktree once your work is pushed so they don't pile up for the owner. Only ever touch worktrees you created — another agent's uncommitted WIP is not yours to clean up. Superseded 2026-07-29: the long-standing "never touch the Codex worktree ~/Documents/GPT/archive-suite-processor-fixes" instruction is retired — the owner asked for it to be removed and it is gone (its work was preserved first; see §"Working the to-do list as an external agent", rule 6). Don't go looking for it. The standing rule is unchanged and matters more than the exception: if you find a stray worktree carrying uncommitted work, preserve it before removing anything, and never --force past a git refusal.
• After any pull/switch, xcodegen generate (or the app's bootstrap.sh) — the .xcodeproj is gitignored.
• Stay in your lane. A change scoped to one app touches only that subdir. Loading the other app is almost always unnecessary (see the token‑efficiency directive in CLAUDE.md).
• Never write to a real corpus during dev/test (copy to scratchpad); never add a tag‑write call outside Reader's audited TagWriter, or any move/rename/delete/content‑write call anywhere.
• Done = code + docs in the same commit. Ship a SUITE_TODO.md item → flip its checkbox (cite the commit); fix/find a bug → update KNOWN_ISSUES.md; ship an execution-plans/ plan → delete it. SUITE_TODO.md is the tracker of record — an unattended run reconciles it before ending, never leaning on a private plan file. The owner shouldn't have to catch a stale tracker. (Full rule: CLAUDE.md → "Docs & backlog convention.")