dotfiles/.codex/AGENTS.md

AGENTS.MD

Work style: telegraph; noun-phrases ok; drop grammar; min tokens.

Agent Protocol

• PRs: use gh pr view/diff (no URLs).
• Need upstream file: stage in /tmp/, then cherry-pick; never overwrite tracked.
• Keep files <~500 LOC; split/refactor as needed.
• Commits: Conventional Commits (feat|fix|refactor|build|ci|chore|docs|style|perf|test).
• Prefer end-to-end verify; if blocked, say what’s missing.

Docs

• Keep notes short; update docs when behavior/API changes (no ship w/o docs).

PR Feedback

• Active PR: gh pr view --json number,title,url --jq '"PR #\\(.number): \\(.title)\\n\\(.url)"'.
• PR comments: gh pr view … + gh api …/comments --paginate.
• Replies: cite fix + file/line; resolve threads only after fix lands.
• When merging a PR: thank the contributor in CHANGELOG.md.

Build / Test

• Release: read docs/RELEASING.md (or find best checklist if missing).

Git

• Safe by default: git status/diff/log. Push only when user asks.
• git checkout ok for PR review / explicit request.
• Branch changes require user consent.
• Destructive ops forbidden unless explicit (reset --hard, clean, restore, rm, …).
• Don’t delete/rename unexpected stuff; stop + ask.
• No repo-wide S/R scripts; keep edits small/reviewable.
• Avoid manual git stash; if Git auto-stashes during pull/rebase, that’s fine (hint, not hard guardrail).
• If user types a command (“pull and push”), that’s consent for that command.
• No amend unless asked.
• Big review: git --no-pager diff --color=never.
• Multi-agent: check git status/diff before edits; ship small commits.

Language/Stack Notes

• Swift: use workspace helper/daemon; validate swift build + tests; keep concurrency attrs right.
• TypeScript: use repo PM; keep files small; follow existing patterns.

Critical Thinking

• Fix root cause (not band-aid).
• Unsure: read more code; if still stuck, ask w/ short options.
• Conflicts: call out; pick safer path.
• Unrecognized changes: assume other agent; keep going; focus your changes. If it causes issues, stop + ask user.
• Leave breadcrumb notes in thread.

Frontend Aesthetics

<frontend_aesthetics> Avoid “AI slop” UI. Be opinionated + distinctive.

Do:

• Typography: pick a real font; avoid Inter/Roboto/Arial/system defaults.
• Theme: commit to a palette; use CSS vars; bold accents > timid gradients.
• Motion: 1–2 high-impact moments (staggered reveal beats random micro-anim).
• Background: add depth (gradients/patterns), not flat default.

Avoid: purple-on-white clichés, generic component grids, predictable layouts. </frontend_aesthetics>