dotfiles/.codex/AGENTS.md

AGENTS.MD

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

Agent Protocol

• Contact: Kyle Yasuda (@sudacode, suda@sudacode.com).
• Workspace: ~/Projects.
• “MacBook Air” / “Mac Mini” => SSH there; find hosts/IPs via tailscale status.
• PRs: use gh pr view/diff (no URLs).
• “Make a note” => edit AGENTS.md (shortcut; not a blocker). Ignore CLAUDE.md.
• No ./runner. Guardrails: use trash for deletes.
• Need upstream file: stage in /tmp/, then cherry-pick; never overwrite tracked.
• Bugs: add regression test when it fits.
• Keep files <~500 LOC; split/refactor as needed.
• Commits: Conventional Commits (feat|fix|refactor|build|ci|chore|docs|style|perf|test).
• Subagents: read Subagent Coordination Protocol.
• If Backlog.md is set up for the project, each task must be associated with a ticket on the backlog. Create a new ticket on the board if it does not already exist
• Editor: code <path>.
• CI: gh run list/view (rerun/fix til green).
• Prefer end-to-end verify; if blocked, say what’s missing.
• New deps: quick health check (recent releases/commits, adoption).
• Slash cmds: ~/.codex/prompts/.
• Web: search early; quote exact errors; prefer 2024–2025 sources; fallback Firecrawl (pnpm mcp:*) / mcporter.
• Style: telegraph. Drop filler/grammar. Min tokens (global AGENTS + replies).

Important Locations

• Blog repo: ~/projects/sudacode-blog
• Obsidian Vault: ~/S/obsidian/Vault (e.g. mac-studio.md, mac-vm.md)

Docs

• Keep notes short; update docs when behavior/API changes (no ship w/o docs).
• Add read_when hints on cross-cutting 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.

Flow & Runtime

• Use repo’s package manager/runtime; no swaps w/o approval.
• Use Codex background for long jobs; tmux only for interactive/persistent (debugger/server).

Build / Test

• Before handoff: run full gate (lint/typecheck/tests/docs).
• CI red: gh run list/view, rerun, fix, push, repeat til green.
• Keep it observable (logs, panes, tails, MCP/browser tools).
• 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.

macOS Permissions / Signing (TCC)

• Never re-sign / ad-hoc sign / change bundle ID as “debug” without explicit ok (can mess TCC).

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.

Tools

Read ~/projects/agent-scripts/tools.md for the full tool catalog if it exists.

tmux

• Use only when you need persistence/interaction (debugger/server).
• Quick refs: tmux new -d -s codex-shell, tmux attach -t codex-shell, tmux list-sessions, tmux kill-session -t codex-shell.

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>

Output Context

<output_contract>

• Return exactly the sections requested, in the requested order.
• If the prompt defines a preamble, analysis block, or working section, do not treat it as extra output.
• Apply length limits only to the section they are intended for.
• If a format is required (JSON, Markdown, SQL, XML), output only that format. </output_contract>

Verbosity Controls

<verbosity_controls>

• Prefer concise, information-dense writing.
• Avoid repeating the user's request.
• Keep progress updates brief.
• Do not shorten the answer so aggressively that required evidence, reasoning, or completion checks are omitted. </verbosity_controls>

Default Follow Through Policy

<default_follow_through_policy>

• If the user’s intent is clear and the next step is reversible and low-risk, proceed without asking.
• Ask permission only if the next step is: (a) irreversible, (b) has external side effects (for example sending, purchasing, deleting, or writing to production), or (c) requires missing sensitive information or a choice that would materially change the outcome.
• If proceeding, briefly state what you did and what remains optional. </default_follow_through_policy>

Parallel Tool Calling

<parallel_tool_calling>

• When multiple retrieval or lookup steps are independent, prefer parallel tool calls to reduce wall-clock time.
• Do not parallelize steps that have prerequisite dependencies or where one result determines the next action.
• After parallel retrieval, pause to synthesize the results before making more calls.
• Prefer selective parallelism: parallelize independent evidence gathering, not speculative or redundant tool use. </parallel_tool_calling>

Force Completion on Long-Running Tasks

<completeness_contract>

• Treat the task as incomplete until all requested items are covered or explicitly marked [blocked].
• Keep an internal checklist of required deliverables.
• For lists, batches, or paginated results:
  • determine expected scope when possible,
  • track processed items or pages,
  • confirm coverage before finalizing.
• If any item is blocked by missing data, mark it [blocked] and state exactly what is missing. </completeness_contract>

Verification Loop

<verification_loop> Before finalizing:

• Check correctness: does the output satisfy every requirement?
• Check grounding: are factual claims backed by the provided context or tool outputs?
• Check formatting: does the output match the requested schema or style?
• Check safety and irreversibility: if the next step has external side effects, ask permission first. </verification_loop>