Agent Instructions These instructions apply to all AI assistants working in this repository. ## Core Rules - Always review `CHANGELOG.

Agent Instructions

These instructions apply to all AI assistants working in this repository.

Core Rules

• Always review CHANGELOG.md and ROADMAP.md before starting significant work.
• Treat DOCS/ as the documentation source of truth.
• Do not work directly on main for substantial changes.
• Use codex/<project-number>-<slug> for agent branches and <project-number>-<slug> for human branches.
• Update docs when code changes affect behavior, workflows, or interfaces.
• Maintain frontmatter (title, description, status, lastUpdated, owner).
• Keep DOCS/README.md and DOCS/index.md accurate.
• Use checkpoint-based progress updates instead of today/tomorrow handoff wording.
• Generate timestamps with node scripts/docs/timestamp-et.mjs --json (never hand-type them).
• Keep repo context explicit:
  • ios/ contains the SwiftUI iPhone app generated from XcodeGen.
  • backend/ contains the Cloudflare Worker API and Neon integration seam.
• Commit and config hygiene:
  • Keep real env and signing files untracked.
  • Update .env.example, backend/.dev.vars.example, and ios/Config/Local.example.xcconfig when runtime requirements change.
• Each project update must include:
  • absolute timestamp (YYYY-MM-DD HH:MM ET (America/New_York))
  • completed since prior checkpoint
  • next checkpoint targets

Project Planning

• Create a numbered project doc under DOCS/PROJECTS/active/ at project kickoff.
• Record the working branch in the project doc when implementation begins.
• Open a draft PR early for every substantial stream and record the PR number/link in the project doc.
• Move the doc across status folders as work progresses.
• Move a project to DOCS/PROJECTS/in-review/ and set status: in-review only when implementation is complete and a draft PR exists for review.
• Move a project to DOCS/PROJECTS/blocked/ and set status: blocked when waiting on user decisions, permissions, access, or missing inputs.
• Do not move a project to DOCS/PROJECTS/completed/ until collaborative walkthrough/sign-off is complete.
• While projects are in in-review or blocked, continue execution by pulling the next prioritized backlog/stale stream.
• Reference the project number in roadmap and changelog entries.
• Maintain a checkpoint log in each project doc and add a checkpoint for major decisions, delivery milestones, or scope changes.

Git And PR Flow

• Default path: create/update project doc -> create branch -> implement -> push branch -> open draft PR -> gather evidence -> mark ready -> squash merge -> delete branch.
• Every draft PR should include scope, env/config changes, verification evidence, preview evidence, and risks.
• Use gh pr list, gh pr checks --watch, and gh pr view --comments as the default monitoring loop.
• Prefer squash merges and branch deletion after merge.

UX/UI Bug Intake

• Log user-visible UX/UI defects in DOCS/UX_UI_BUGS/INBOX.md first, then normalize serious or durable items into DOCS/UX_UI_BUGS/TRIAGED.md.
• The main agent is the canonical logger/router for UX/UI bugs, even when the user or a subagent detects them.
• Use simulator/device debugging to gather evidence, then summarize the result into the bug register instead of leaving it only in chat or raw logs.
• Only let blocker-class or active-slice-local UX/UI bugs interrupt the current stream immediately; otherwise capture and defer them into the right planned slice.

Docs Tooling

• Run node scripts/docs/normalize-frontmatter.mjs DOCS before larger docs cleanup passes.
• Run node scripts/docs/manifest.mjs DOCS after adding or moving docs files.
• Run node scripts/docs/check-links.mjs DOCS before merging docs-only changes.

Provenance

• Source file: AGENTS.md
• Source URL: https://github.com/maggielerman/maintain-ios/blob/main/AGENTS.md