028 Agents 2e6bfc71

# AGENTS.MD

Antonio owns this.

## Agent Protocol

- Workspace: `~/Projects`. Missing antoniolg repo: clone `https://github.com/antoniolg/<repo>.git`. 
- 3rd-party/OSS (non-antoniolg): clone under `~/Projects/oss`.
- GitHub: use `gh` CLI
- “Make a note” => edit AGENTS.md (shortcut; not a blocker). Ignore `CLAUDE.md`.
- Guardrails: use `trash` for deletes.
- 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`).
- Editor: `code <path>`.
- When asked to open a file: use `code` for code/Markdown files, otherwise use `open`.
- 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).
- Web: search early; quote exact errors; prefer 2025 sources;
- Transcription: when asked to transcribe video/audio, use `parakeet-mlx` by default (already installed).

## Screenshots (“use a screenshot”)

- Use `pngpaste`
- Verify it’s the right UI (ignore filename).
- Size: `sips -g pixelWidth -g pixelHeight <file>` (prefer 2×).
- Optimize: `imageoptim <file>` (install: `brew install imageoptim-cli`).
- Replace asset; keep dimensions; commit; run gate; verify CI.

## Important Locations

- Blog repo:
  - Spanish: `~/Projects/devexpert-io/devexpert-site`
  - English: `~/Projects/antoniolg/blog`

- Obsidian vault: `'/Users/antonio/Library/Mobile Documents/iCloud~md~obsidian/Documents/Cerebro'`

## Docs

- Read README/docs before coding.
- Follow links until domain makes sense; honor `Read when` hints.
- Keep notes short; update docs when behavior/API changes (no ship w/o docs).
- Add `read_when` hints on cross-cutting docs.
- When creating new skills, write the skill content in English (including `SKILL.md`).
- Skills are public: avoid any sensitive data (tokens, internal URLs, IDs, private paths). Use placeholders or env vars.

## 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. Prefer pnpm for Node projects unless the repo specifies otherwise.
- 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`, …).
- Remotes under `~/Projects`: prefer HTTPS; flip SSH->HTTPS before pull/push.
- Don’t delete/rename unexpected stuff; stop + ask.
- No repo-wide S/R scripts; keep edits small/reviewable.
- If user types a command (“pull and push”), that’s consent for that command.
- No amend unless asked.
- Multi-agent: check `git status/diff` before edits; ship small commits.

## Critical Thinking

- Fix root cause (not band-aid).
- Unsure: read more code; if still stuck, ask.
- 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

### trash

- Move files to Trash: `trash …` (system command).

### bin/browser-tools / scripts/browser-tools.ts

- Chrome DevTools helper. Cmds: `start`, `nav`, `eval`, `screenshot`, `pick`, `cookies`, `inspect`, `kill`.
- Rebuild: `bun build scripts/browser-tools.ts --compile --target bun --outfile bin/browser-tools`.

### gh

- GitHub CLI for PRs/CI/releases. Given issue/PR URL (or `/pull/5`): use `gh`, not web search.
- Examples: `gh issue view <url> --comments -R owner/repo`, `gh pr view <url> --comments --files -R owner/repo`.

### mcporter

- MCP launcher: `mcporter <server>` (see `npx mcporter --help`)

### 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`.

## GitHub CLI formatting note
- For `gh pr` / `gh issue` bodies, avoid literal escaped `\\n` sequences.
- Use real multiline text (heredoc) or `--body-file` to preserve line breaks.