Repository-specific instructions for coding agents working in this public dotfiles repo. Keep shared cross-project agent behaviour in the global ~/.config/opencode/AGENTS.md. This file should only describe this repo's source layout, stow workflow, repo-local commands, and validation expectations. Don't catalogue skills or commands here: skills self-document via their injected description, commands via their frontmatter and the generated docs reference. Keep only repo facts and routing those don't capture.
Author and maintain the Blume docs site (docs/, dotfiles.timmo.dev) in this repo. Use when editing or pruning docs pages, blume.config.ts navigation, README docs links or docs/AGENTS.md, or deciding whether a change needs a docs edit.
This directory is the Blume + Astro documentation site for the dotfiles repo, deployed to dotfiles.timmo.dev. Keep changes small and aligned with existing patterns. Each distro/* branch publishes its own copy of this site to its own Cloudflare Worker, so every site describes only what its branch ships. The header Distro switcher and the /distros page link them together. To add a distro:
This repo contains the standalone notes CLI and MCP server. Run these after source changes: CI validates .agents/skills/ with the shared lint-agent-skills workflow.
Keep all scoped code work contained to the user-defined changeset. Use for implementation, fixes, diagnosis, refactoring, cleanup, and review when explicit instructions, named files, diffs, branches, pull requests, or injected work scopes define the boundary.
Review a pull request, branch, work-in-progress changes, or diff for concrete defects, unmet requirements, and repository convention violations. Keep findings scoped, evidenced, and proportionate.
Use @timmo001/docs-kit to set up or change a timmo001 documentation site. Apply when creating a Blume docs site, editing its blume.config.ts, components.ts or theme.css, changing the home banner or header GitHub link, or generating share cards, social previews, logo PNGs or Apple touch icons from a site's SVG logo.
Use @timmo001/effect-gh for GitHub CLI integration in Effect TypeScript code. Apply when adding or changing gh-backed API requests, repository, issue, pull request or workflow operations, streaming output, or migrating hand-written gh subprocess wrappers to Effect.
Use @timmo001/effect-herdr for Effect TypeScript integrations with Herdr's local socket API. Apply when adding, migrating, debugging or reviewing SDK consumers, including agent coordination, event streams, panes and workspaces. For operating terminals or workspaces as an agent, use the herdr skill.
Design Effect services. Use when designing a new Effect service module or auditing an existing codebase for service, Layer, and composition improvements.
Opinionated guide for building production TypeScript applications with Effect v4. Use when implementing Effect workflows, services, layers, schemas, configuration, schedules, caches, streams, HTTP clients, or tests.
Use the notes CLI to find, read, create, update, and delete repository notes. Use for shell-based note workflows, notes commands, and handoff storage. For Notes MCP tool calls, use notes-mcp instead.
Use the Notes MCP server to list, read, create, update, or delete repository notes. Use for note_list, note_read, note_write, and note_delete tool calls, including client-prefixed names. For shell-based Notes commands, use notes-cli instead.
Build terminal UIs with OpenTUI. Covers Core, frameworks, components, application APIs, testing, extensions, integrations, deployment, and public API lookup.
Name skills with an owner prefix so they do not collide with shared, imported or other repositories' skills. Use when creating, renaming, importing or reviewing a skill name, especially for repository-local or tool-owned skills.
Run and write project tasks so checks, builds, tests and dev servers finish fast - run only what a change needs, in parallel, skipping work that is already up to date. Use when running linters, type checks, test suites or builds; when writing or reviewing task runner config (mise.toml, package.json scripts, justfile, deno.json, Makefile, pitchfork.toml) or CI steps; or when a check, build or task run is slow.
Choose tests for their concrete regression value, avoid low-value coverage, and verify changes by exercising the real built behaviour. Use during implementation, fixes, planning, diagnosis, and code review when choosing verification, adding or changing tests, considering a missing-test finding, or when the user asks to test, check, or verify a change.
Write commit messages, PR and issue text and comments, docs (README), code comments, and user-facing strings (notifications, UI labels, toasts, error messages) in the project owner's voice: concise, human, UK English, no em-dashes, no robotic or marketing tone. Use when writing, editing, or reviewing these, including requests to make writing sound natural or remove jargon. Keep the meaning and follow the repo's established writing style.
This repo contains the standalone context CLI and MCP server. Run these after source changes. Regenerate first, because the generators rewrite docs that format:check and the docs build read:
Plain text files in a repository that tell a coding agent how the project works: commands to run, conventions to follow and things to avoid. CLAUDE.md, AGENTS.md, cursor rules and skills are the common kinds.
CLAUDE.md or AGENTS.md?
CLAUDE.md is read by Claude Code. AGENTS.md is an open format that Codex, Cursor and other agents read. Many projects keep one and point the other at it.
What is a skill?
A folder with a SKILL.md that describes one capability, such as filling PDFs or reviewing code. The agent loads it only when the task calls for it.
Can I search my own team's files too?
Your agents already can, over MCP, limited to the files you're allowed to read. Searching them from this page is coming.
timmo001AGENTS.md