diff --git a/AGENTS.md b/AGENTS.md index 8d1c8b6..c035ff9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1 +1,40 @@ - +I'm Joshua. You're my agent. We will be working togehter a lot, so I thought it would be worth introducting myself. + +I love to build. I focus on building complex things as simple as possible. I love to find ways to reduce complexity when solving problems. + +I wanted to share some of my preferences here so we can be more aligned as we work together + +# Coding preferences - general +- Keep things simple. Channel "yagni" energy unless told otherwise. +- Typesafety is useful, take advantage of it. +- Don't be scared to purpose bold ideas if they can meaningfully benefit our work. +- Be careful with destructive actions that are not explicityly requested by the user. +- Tests are good! Endless smoke tests, "regression tests" for feature deletions, etc, are much less good. Tests shoudl be focused, not slop. +- Comments are a great way to clarify functionality and how code is used. Don't comment every line, but feel free to describe (concisely) how functions are used above function definitions, classes, etc. +- Keep comments up to date! When making changes, it's important to keep things in sync. +- Write TypeScript in ways that Matt Pocock and Theo would be proud of. + +# Questions are read-only +- A question is a request for an answer, not changes. If the message opens with "how hard would it be", "what are your thoughts", "why does", "should we", "is it possible", "can X do Y", or otherwise asks rather that instructs: answer it, and do not edit files +- If the answer is obvious and the change is tribial, still answer first and offer the change. Ask before making it. + +# Match ceremony to the task +- Do not spawn subagents or a multi-agent panel for work a single agent finishes in one pass. Delegation is for breadths or adversarial review, not for ordinary tasks. +- When several agents do work in parallel, state file ownership up front so they do not collide. + +# Visual and design work +- Do nto edit real components first. For any non-trivial UI, layout, or copy change, build several distinct static mocks, publish them with the `html-communication` skill, report the URL, and stop. Wait for a pick before implementing. +- Standing contraints: dark mode, true black (`#000`) background, white primary text. Information-dense, no dectorative card/pill chrome, no light-gray subtitle lines above sections. Minimal copy. No em dsahes. +- Avoid continously repainting CSS animations (pulse, shimmer, blur, spinners); they peg the GPU on high-refresh displays. + +# Blast Radius +- Never touch production, live databases, or daily-driver build/preview channels unless explicitly told to. When a task is adjacent to any of them, name what you are about to touch before touching it. + +# Pull Requests +- I run my own Gitea server at `https://git.abunchofknowitalls.com`. Use the `tea` CLI to lookup open pull requests, issues, comments on PRs and CI status. +- Make sure titles follow convextions from the repo. They should be simple and easy to understand. Conventional cmmit styles in porjects that use them, i.e. "fix(web): new threads no longer spike CPU" +- PR descriptions should aim for simplicity. Open with a minimal, clear description of the problem. Follow up with how you solved it. +- Add a blurb to the end of the PR description about what model and harness is making the changes. +- *Open a real PR, not a draft.* Drafts do not get review-bot coverage. +- *Rebase onto the latest `main` before opening*. Stale branches conflict and wast a review round. +- When asked to monitor or babysit a PR: poll checks and comments newer than the last push; verify each bot finding against the source before acting on it; fix real ones and dismiss false positives with written reason; fix CI failures, distinguishing real breaks from known infra flakes. If nothing is new, stay quite and never post filler comments. Stop when the repo's review bots are green on the latest commit. Merge only per the disposition given in the request (merge when green or stop and report). If none was given, report and ask. \ No newline at end of file diff --git a/setup.sh b/setup.sh index 6d1629c..a7a0ab6 100755 --- a/setup.sh +++ b/setup.sh @@ -5,3 +5,5 @@ ln -s ./AGENTS.md ~/.codex/AGENTS.md ln -s ./AGENTS.md ~/.claude/CLAUDE.md ln -s ./AGENTS.md ~/.config/opencode/AGENTS.md ln -s ./AGENTS.md ~/.agents/AGENTS.md + +ln -s ./skills ~/.agents/skills \ No newline at end of file diff --git a/skills/babysit-pr/SKILL.md b/skills/babysit-pr/SKILL.md new file mode 100644 index 0000000..957e804 --- /dev/null +++ b/skills/babysit-pr/SKILL.md @@ -0,0 +1,29 @@ +--- +name: babysit-pr +description: Monitor a pull request through review and CI. Use when the user asks to monitor, wathc, or a babysit a PR +--- + +# Babysit PR +All the repos we work in have various AI review bots. They're helpful, even if they are not always right. + +If your harness offers tools to monitor a PR, use them so you can respond when comments arrive. Otherwise, poll the PR for new comments and checks. + +Only act on checks and comments newer than the latest push. Verify every bot finding against the source before changing code. Fix real findings and CI failures, distinguish repository failures from infrastructure flakes, and reply with a written reason when dismissing false positives. + +Keep an eye on changes to `main` and rebase when needed. If an overlapping PR makes this one obsolete, stop monitoring, report it to the user, and ask before closing the PR unless closure was explicitly authorized. + +If a review bot leaves feedback you believe is not worth addressing, reply and +resolve the comment. Format comments left on Joshua's behalf as: + +```md +[MODEL-SLUG] RESPONDING ON BEHALF OF JOSHUA +----- + +[actual reply] +``` + +Screenshots and videos are helpful as well. use the `file-upload` skill when needed. + +Do not let review feedback expand the PR beyodn the user's original goal. Address real shortcomings, but avoid scope creep. + +If nothing has changed, stay quiet rather than posting filler comments. Stop when the review bots and required checks are green on the latest commit. Merge only when the user explicitly requested it; otherwise report that the PR is ready. \ No newline at end of file diff --git a/skills/file-pr/SKILL.md b/skills/file-pr/SKILL.md new file mode 100644 index 0000000..a80de0e --- /dev/null +++ b/skills/file-pr/SKILL.md @@ -0,0 +1,29 @@ +--- +name: file-pr +description: File a concise pull request. Use when the user asks to file, open, or create a PR. +--- + +# File PR +Before filing, check whether a PR for this branch already exists. Review +the diff locally against `origin/main` to make sure its contents match the +goal. + +PR titles usually become commit messages, so follow the repository's +title conventions. Look at recently merged PRs and Git history for examples. +Prefer a concise, human-readable title that explains why the change matters: + +BAD +> ❌ perf (server): negotiate permessage-deflate on the websocket + +GOOD +> ✅ perf (server): cut websocket frame size by 70%+ with gzipping + +Open the description with a simple explanation of the problem based on the user's original prompt, then briefly explain the solution. Do not lead with an implementation inventory: + +BAD +> ❌ Removed implicit wokspace carry-over from every "new thread" entry point (cmd+n / cmd+shift+o, sidebar v1/v2 buttons, command palette). New threads inherit only the project from context; branch, worktree, and env mode always come from the configured defaults. Deleted buildContextualThreadOptions, startNewThreadInProjectFromContext, and the v1 sidebar's seed-context machinery. + +GOOD +> ✅ My "new worktree" default was ignored when starting new threads on existing worktrees. Super unintuitive. Now your preferences always apply. + +Open a real PR rather than a draft so review bots run. If the user also asked to babysit it, continue with the `babysit-pr` skill. \ No newline at end of file diff --git a/skills/file-upload/SKILL.md b/skills/file-upload/SKILL.md new file mode 100644 index 0000000..b075f8a --- /dev/null +++ b/skills/file-upload/SKILL.md @@ -0,0 +1,32 @@ +--- +name: file-upload +description: When a user asks to upload a file, or one is needed for PR descriptions, use this skill. +--- + +# File upload + +Upload files to `https://files.gitcoffee.dev` and return the permanent public URL from the reponse body. Authenticate with `FILE_HOST_TOKEN`. If it is unset, tell the user instead of guessing. + +## Upload + +```bash +curl -sS --fail-with-body -X PUT -T \ + -H "X-Upload-Token: $FILE_HOST_TOKEN" \ + "https://files.gitcoffee.dev" +``` + +- Use only the file's basename for ``, such as `login-flow.mp4`. The server slugifies it and adds a random suffix, so names do not need to be unique. +- Treat the response body as the permanent public URL and use it directly. +- On HTTP 401, report that the token is wrong or unset. Do not retry. + +## Use the URL in GitHub/my selfhosted Gitea + +- Embed images (`png`, `jpg`, `gif`, `webp`) as `![description](URL)` +- Link videos (`mp4`, `mov`, `webm`) as `[screen recording](URL)` because inline video players are not well supported. +- When an inline preview genuienly helps and the clip is shorter than about 30 seconds, also upload a GIF preview: + +```bash +ffmpeg -i recording.mp4 -vf "fps=10,scale=800:-1" -loop 0 preview.gif +``` + +Embed the GIF and link the full-quality video below it. diff --git a/skills/html-communication/SKILL.md b/skills/html-communication/SKILL.md new file mode 100644 index 0000000..44be36d --- /dev/null +++ b/skills/html-communication/SKILL.md @@ -0,0 +1,43 @@ +--- +name: html-communication +description: When the user asks for an HTML writeup of work (NOT as part of the codebase), use this skill to create and always upload in Postplan. Also useful for reading plan.gitcoffee.dev URLs. +--- + +# HTML Communication + +## When to use + +Use this skill when the user wants a plan, spec, write-up, findings, summary, report, comparison, or set of UI mocks presented as readable HTML. + +Do not use it for HTML that ships as part of the product. + +## Document + +Create one self-contained HTML file, capped at 512 KB. + +- Write it like a spec, not a landing page: dense, scannable, no hero, decorative chrome, marketing voice, or em dashes. +- Default to true black (`#000`), white primary text, and dark gray only for secondary surfaces or accents. +- Make it mobile-readable with a responsive viewport and no fixed-width layout. +- Use semantic HTML, inline CSS, inline SVG, and HTTPS or data-URL images. +- Use an inline classic script only when interactivity materially helps. Keep scripted pages useful without JavaScript; the sandbox blocks storage, fetch workers, frames, forms, and popups. +- In script-free files, give external links `target="_blank"` and +`rel="noopener noreferrer"`. If any script exists, omit `target="_blank"`. + +Never include external or module scripts, inline event handlers, `javascript:` URLs, forms, frames, embeds, objects, applets, meta refresh, linked stylesheets, secrets, private URLs, or local filesystem paths. + +## UI Mocks + +When the user asks for variants: + +- Render real styled variants, not descriptions. +- Label them `A`, `B`, `C`... for easy selection. +- Lay them out for direct comparison. +- Keep one file across iterations so its Postplan URL stays stable. + +## Publish + +Joshua has given standing permission to upload every artifact created or updated with this skill. Upload is required, including in Auto mode. Do not ask for separate permission or stop at the local file. + +1. Write the HTML file locally. +2. Run `npx postplan upload ` +3. Report the local path and returned Postplan URL. \ No newline at end of file diff --git a/skills/postplan-read/SKILL.md b/skills/postplan-read/SKILL.md new file mode 100644 index 0000000..79dcff6 --- /dev/null +++ b/skills/postplan-read/SKILL.md @@ -0,0 +1,11 @@ +--- +name: postplan-read +description: Use when the user provides a plan.gitcoffee.dev URL to read. +--- + +# Postplan Read + +Fetch the uploaded HTML with the shell. Do not use web search or a browser. +1. Remove a trailing slash, then append `/raw` unless the URL already ends in `/raw`. +2. Run curl --fail --silent --show-error --location --max-time 30 --output /tmp/postplan. html ``. +3. Read `/tmp/postplan.html` and continue the user's request from its contents. If `curl` fails, report its actual status or network error. Do not substitute search results. \ No newline at end of file