agent-docs

Kevin Codex Preset

The global Codex preset source. Bootstrap links it to ~/.codex/AGENTS.md. Keep it short: everything else is one kb call away.

Kevin's brain

Kevin-Wiki (~/repos/Kevin-Wiki) is the memory every agent Kevin runs shares: his projects, people, tools, decisions and rules. kb searches it from any directory.

  • At the start of a session, read ~/repos/Kevin-Wiki/config/brain-card.md. It lists the projects with recent commits and the pages pinned for every session. Run kb card only when that file is missing.
  • Before work that names one of Kevin's projects, people, tools or past decisions, run kb <words>, then kb get <name> for the page's top lines and outline.
  • Each page says when it was last checked. Where the code or the live site disagrees with it, trust them and note the difference.
  • When you learn a durable fact (a project's state, a decision, a rule Kevin states), run kb note <page> "<fact>" --source "<where>". The weekly harvest writes notes into their pages. Edit wiki pages directly only from a Kevin-Wiki worktree.
  • If kb is not found, run ~/.local/bin/kb or node ~/repos/Kevin-Wiki/scripts/kb.mjs with the same arguments. Only ~/.zshrc puts ~/.local/bin on PATH, so non-interactive shells miss it.
  • In the Kevin-Wiki repo, read its AGENTS.md first.

Mac rules

These apply in every directory. Full rules and sources: ~/repos/Kevin-Wiki/wiki/meta/mac-agent-operations.md.

  • Never stop, queue or pause work because of memory; headroom can-start always exits 0 and Headroom is read-only for agents (Kevin, 2026-10-21).
  • Stop every server, browser and watcher you start, by its recorded PID, as soon as its check is done.
  • Start every new task in a new session (a spawn_task chip or start_session), never in the one you are in; a session whose Claude process passes 20 GB writes a handoff and continues in a new one (Kevin, 2026-11-05).
  • Never run pkill, killall or any pattern kill; read ps -o pid,command -p <pid> and kill only exact PIDs you started.
  • If a process you did not start uses too much memory, tell Kevin and leave it alone.
  • Never SendMessage a running workflow agent; it starts a second copy that edits the same files.
  • Search many literals with rg -F -f <file> or git grep -I -F -f <file>, never one large regex alternation.
  • A reboot or app restart wipes /private/tmp and the scratchpad; keep logs, checkpoints and notes elsewhere and make long runs resumable.
  • Run df -h /System/Volumes/Data before large batches, keep 30 GB free, and remove your worktrees once their branches are pushed.
  • The Bash tool runs zsh: never name a variable path, write ${VAR}: before a colon, quote globs, and split with ${=var}.
  • This Mac has no timeout, gtimeout or setsid, and its shell grep is ugrep; use /usr/bin/grep in scripts.
  • Never edit a script in place while a copy of it runs.
  • Never use git stash; every worktree shares the stash list. Set work aside with a WIP commit.
  • Stage and commit by explicit path, and read git diff --cached --stat before committing in a shared checkout.
  • Ask Kevin before any push, deploy, publish, paid, credentialed or destructive action.
  • Commit as the GitHub noreply address 66856750+Kevin-Liu-01@users.noreply.github.com (General Translation repos keep their local work address), never Kevin's personal Gmail.

Where rules go

A rule that applies outside the current repository goes to its owner wiki page through kb note <page>. General Translation working rules go to ~/repos/Prototemplate/skills/.

npm run boot-rules writes the Mac rules block from the wiki page; edit the page, not this file. Wiki closeout steps live in the Kevin-Wiki AGENTS.md.