ateles: Instructions file for Claude Code

Ateles — Claude Code Project Instructions

How to read a <!-- CONFLICT --> marker. A few rules below are marked as deliberately unresolved: two rules that pull against each other, kept as they are because deciding which framing governs is the operator's call, not a merge's. Never resolve one by editing prose — reword neither bullet, delete neither, and do not collapse the pair into one. Each marker states both framings and what to do in the meantime, so it works without network access to the issue it cites.

Plan and task maintenance (automatic)

Each session maintains the Neotoma plan entity that matches its own workstream — never a fixed, hardcoded plan. The swarm-architecture plan ent_99ace4dd6673aa36ed08b1fe ("Ateles Agent Swarm Architecture") is the plan for swarm-architecture work only. Unrelated workstreams (tax prep, Neotoma release engineering, website, cloud hosting, etc.) each have their own plan and MUST NOT write into the swarm plan. Writing one workstream's decisions/todos into another's plan is the collision that corrupted this plan in June 2026.

Select the bound plan once per session, as soon as the workstream is clear:

1. Resolve the matching plan: retrieve entities against the operator's prod Neotoma instance (whichever connected Neotoma server targets it), with entity_type: plan and a search for the workstream; pick the closest match. If the target instance can't be established unambiguously — no connected server clearly targets the operator's prod instance, or several are connected and the target is ambiguous — stop and ask rather than write.
2. If no existing plan fits, create one (/update-plan skill) and bind to it.
3. Maintain only that bound plan for the rest of the session.

Apply these rules on every turn, without being asked — to the bound plan:

• Before correcting decisions or todos, RE-READ the current field and MERGE. correct replaces the entire field, so add or update only the keys/items you authored and preserve every entry already present. NEVER rebuild a field from a stale in-memory copy — that silently deletes other sessions' entries. If the field changed since you last read it, re-read and re-merge before writing.
• When a todo item is completed — correct its status to "done" in todos, with relevant entity IDs, file paths, or PR numbers in a notes field.
• Never mark a task or todo done while citing a commit, branch, file, or PR that does not resolve. Verify the artifact exists first (git cat-file/ls-remote, GitHub). Unverifiable completion claims are the second failure mode that corrupted this plan in June 2026.
• When a decision is settled — add or correct one entry in the decisions map. One sentence, snake_case key.
• When blockers change (something unblocked, something newly blocked) — correct next_steps to reflect the current state.
• When a new actionable task is identified — create a task entity and link it PART_OF the bound plan. Use the update-tasks skill for field values and priority mapping.
• When a daemon, entity, or file is renamed — correct any stale references in body, decisions, and todos in the same turn the rename happens.