> This file is meant for agents. You are supposed to do the following - Write the AGENTS.md to a new file or update existing (content below) - Stamp the written file's first line with when you fetched this page (hour accuracy): `` - Create `PAPERCUTS.md` and `UNSURE.md` at repo root if missing (seed templates below) - Ask if they would like to install required skills - [y] Install required skills - `npx skills add janniks/ai` - `npx skills add mattpocock/skills/grilling mattpocock/skills/grill-me mattpocock/skills/handoff mattpocock/skills/research mattpocock/skills/writing-great-skills` - Optional: the `/status` page on this site installs a custom Claude Code statusline (same instructions-for-agents format as this page) - Optional: export `CLAUDE_CODE_AUTO_COMPACT_WINDOW=300000` in your shell rc (`~/.zshrc`) to compact earlier than the default — keeps context fresher on long sessions. Read at launch, so restart Claude Code after setting. ## Upgrading Already set up (AGENTS.md carries a fetched-stamp)? Don't rewrite blindly: - Fetch the `/changelog` page on this site and compare its dated entries against your stamp. - Apply only what's newer — update AGENTS.md sections, add/remove skills, adjust seed files. Preserve the project's `Project Specific Notes`. - Update the stamp to now. --- `AGENTS.md` ````md # AGENTS.md ## Development philosophy > **Simple made easy.** Rich Hickey / Steve Jobs style. Every change should make the system simpler, not just add to it. - Functional, idiomatic, well-abstracted - Simplify the plan first, then make notes on how to edit - No premature abstractions/DRY (it's overrated) - Prefer deleting code over adding code - No over-engineering, no speculative features - If it's not clearly needed right now, don't build it ### Agent format - All work in md files, in-repo. No GitHub issues unless explicitly asked. - Short bullets, few full sentences. Readable at 1/4 desktop width or on mobile. - Commit after each meaningful change. ### Directories - `specs/` — feature intent (problem, stories, decisions). Complex features get a `## Refinement` section (interfaces, estimates, slices). - `notes/` — flat, unstructured scratchpad. One thought per file. Revisit only on request. ### Conventions - `CONVENTIONS.md` — the codebase's conventions and patterns (naming above all). Read it in full before implementing any feature. ### Papercuts & Unsure - `PAPERCUTS.md` — read at session start; things that didn't go as planned, logged so the next session skips the detour. - Trigger: 2+ failed attempts before something worked, or a surprise. Test: would this have saved future-you a detour? - Append-only dated bullets, detail as indented sub-bullets. Add `- spec: ` only when the origin matters. Refactor/clean only with good reason. - `UNSURE.md` — decisions made while unsure but had to pick one. Append liberally — too many beats too few. Never edit or delete existing entries prematurely; humans resolve them typically. - Group entries under `## — `. Each entry is a checkbox with choice, alternative, and why as sub-bullets. - Humans review: write a `verdict:` sub-bullet, check the box. Checked entries are swept on occasional cleanup passes. ### Workflow - `/grill-me` → `/create-spec` → (complex features: `/refine-spec`) → implement slice-by-slice → commit per slice. - Small features go straight from spec to implementation. Refine only when the feature is complex enough to earn it. - While implementing, track progress in a transient root-level `WIP-.md` — current slice, small notes for crash recovery. Delete it on completion; the spec and commits are the record. - Tick acceptance criteria in the spec after each commit. - Deferred items: front-matter `status: deferred` on whatever file fits. No dedicated dir. ### Style guide (example: TypeScript) #### General principles - Keep things in one function unless composable or reusable - Avoid try/catch where possible - Avoid using the `any` type - Prefer single word variable names where possible - Rely on type inference when possible; avoid explicit type annotations or interfaces unless necessary for exports or clarity - Prefer functional array methods (`flatMap`, `filter`, `map`) over for loops; use type guards on filter to maintain type inference downstream #### Naming Prefer short 1-2 word names for variables and functions. > THIS RULE IS MANDATORY FOR AGENT WRITTEN CODE. - Use single word names by default for new locals, params, and helper functions. - Multi-word names are allowed only when a single word would be unclear or ambiguous. - Do not introduce new camelCase compounds when a short single-word alternative is clear. - Before finishing edits, review touched lines and shorten newly introduced identifiers where possible. - Good short names to prefer: `pid`, `ctx`, `err`, `opts`, `dir`, `root`, `child`, `state`, `timeout`, `buildTx`, `fetchItem`. - Examples to avoid unless truly required: `inputPID`, `existingClient`, `connectTimeout`, `workerPath`. ```ts // Good const foo = 1; function journal(dir: string) {} // Bad const fooBar = 1; function prepareJournal(dir: string) {} ``` Reduce total variable count by inlining when a value is only used once. ```ts // Good const data = await fs.readFile(path.join(dir, "journal.json"), "utf-8"); // Bad const journalPath = path.join(dir, "journal.json"); const data = await fs.readFile(journalPath, "utf-8"); ``` #### Destructuring Avoid unnecessary destructuring. Use dot notation to preserve context. ```ts // Good obj.a; obj.b; // Bad const { a, b } = obj; ``` #### Variables Always use `const` over `let`/`var`. Use ternaries or early returns instead of reassignment. ```ts // Good const foo = condition ? 1 : 2; // Bad let foo; if (condition) foo = 1; else foo = 2; ``` #### Control Flow Avoid `else` statements. Prefer early returns. ```ts // Good function foo() { if (condition) return 1; return 2; } // Bad function foo() { if (condition) return 1; else return 2; } ``` #### Comments Code should be self-documenting and NOT need commenting. Comments are reserved for when something is **unexpected**. Never comment for documenting _what_ is happening, only for _why_ something is happening in cases where the user would be surprised when reading the line of code without a comment. #### Testing - Avoid mocks as much as possible - Test actual implementation, do not duplicate logic into tests ## Project Specific Notes ```` --- Seed template for `PAPERCUTS.md`: `PAPERCUTS.md` ```md # PAPERCUTS > Agents: read at session start. Append-only log of things that didn't go as planned — so the next session skips the detour. Trigger: 2+ failed attempts before something worked, or a surprise. - [2026-07-10] example: use the MCP build tool, not raw `xcodebuild` - failed 3x on code signing before switching - spec: specs/example.md ``` Seed template for `UNSURE.md`: `UNSURE.md` ```md # UNSURE > Agents: append decisions you were unsure about but had to make. When in doubt, log it — too many beats too few. Never edit or delete existing entries prematurely; humans write a `verdict:` and check the box. ## 2026-07-10 — specs/example.md - [ ] example: chose Zod over valibot - both viable; picked ecosystem maturity - verdict: ``` --- Note: The guide is mainly generic and related to our workflow and development process/style. We end with a `Project Specific Notes` for non-template notes for individual projects.