OpenCode & Agents

The repo ships a shared OpenCode configuration: agents, slash commands, skills, and lifecycle plugins. The source lives in agents/.config/opencode/ (agents, commands, plugins, and shared lib/ modules) and agents/.agents/skills/ (skills exposed through the shared ~/.agents/skills/ path).

These are generated from this dotfiles repo and published automatically to timmo001/opencode-config so they can be browsed, imported, and installed independently of the full dotfiles repo.

The portable basis

Unlike the rest of these (personal) dotfiles, the OpenCode config is built to be reused. opencode-config is a standalone, portable export with its own install instructions, so you can adopt individual agents, commands, skills, or plugins without taking on anything else here. Plugins that share support modules are published with the lib/ directory they import and should be copied with that directory.

AgentsAgent catalogue with links to each execution posture.

CommandsSlash commands that route to agents and skills.

SkillsReusable workflows and behavioural contracts.

PluginsContext, evidence, and enforcement hooks.

MCP ServersModel Context Protocol servers wired into the config.

Agents / LLMsllms.txt bundles for loading these docs into AI-assisted sessions.

How it fits together

• Graduated agent permissions - agents range from workspace-read-only (reviewer, ask) through ask-gated (build-ask) to edit-capable (refactorer). Read-only primary agents use native task allowlists, while general-readonly and researcher-readonly are terminal subagents with task delegation denied. The interactive researcher can fan out once without allowing recursive research chains.
• Comparative primary-source research - /research answers direct facts from the source that owns them. When judgement is involved, it compares relevant project policy, maintainer and contributor practice, independent evidence, and credible disagreement claim by claim rather than ranking people by reputation. Research agents can inspect indexed local agent history through the read-only ctx status, source, search, show, locate, docs, and SQL commands; shell output flags remain blocked across these read-only agents.
• Workflow failure diagnosis - /fix-workflows inspects recent GitHub Actions failures for the current branch, or a named workflow or run, reproduces the failing path locally where possible, applies the smallest fix, and verifies it without committing, pushing, or rerunning workflows automatically.
• Skill-based routing - commands are thin wrappers that name an agent, declare required skills, and state whether branch context is needed. The workflow logic lives in skills and plugins.
• Question-led stress-testing - /grill supports Light and Full intensity through one shared workflow. Phrases such as “lightly grill me” or “ask me a couple” select a short pass directly; when the requested intensity is unclear, it asks once before proceeding.
• Staged implementation - /plan identifies one active stage, records separate reviewable stages as deferred, and makes no edits. It recommends one numbered handoff per deferred reviewable phase. In a new repository it tries handoffs first, then proposes one temporary, all-in-one repository-local working Markdown plan when repository notes are not available yet; that document tracks numbered phases and updates their status at every checkpoint. During execution, the staged-implementation skill defines shared contracts before delegation, uses targeted checks while iterating, runs one focused review before full validation, and pauses at validated checkpoints between separate review units unless the user requested one combined delivery.
• Visual plan and code review - Plannotator opens plan review from OpenCode’s plan agent and provides /plannotator-review, /plannotator-annotate, and /plannotator-last for manual review. Its CLI is pinned through mise’s GitHub backend because it is not available from Arch, AUR, or the Aqua registry.
• Branch context injection - commands registered with the branch-context plugin receive pre-computed git and PR state as structured XML instead of running their own git or gh calls. The plugin consumes the standalone context CLI (context git --json), preserves explicit unresolved default-branch state, and keeps the plugin-specific injection rules here. /commit, /commit-push, and /update-docs query the Context MCP server’s git_context tool directly when they need branch or recent-change state.
• Codebase stack injection - the stack-context plugin injects a deterministic tech-stack summary (languages, ecosystems, and frameworks with their general locations) computed by context stack --json, including structured notices when safety limits make a section partial. It injects automatically on the first message of a session inside a git repository, and on demand via /inject-stack or (alongside branch context) /inject-context.
• Repository notes: the repo-notes plugin injects the current repository’s notes path, the notes MCP server owns vault reads and writes, and notes-guard blocks direct file or shell access to the notes vault. See Notes & Handoffs and MCP Servers.
• Secret protection - the env-protection plugin blocks reads of .env files (except .env.example).
• Generated artefact protection - the generated-artifact-guard plugin blocks direct mutation of generated dotfiles artefacts and names the canonical regeneration command. Read-only inspection (cat, git diff, rg, and similar) is allowed. The guard activates only inside this dotfiles repository layout.

Generated artefact	Regenerate with
docs/src/content/docs/dot/commands.md	mise run docs:gen:cli
docs/src/content/docs/reference/{agents,commands,skills,plugins}.md	mise run docs:gen:opencode
bash/.local/share/bash-completion/completions/dot	dot completions bash
fish/.config/fish/completions/dot.fish	dot completions fish
zsh/.local/share/zsh/site-functions/_dot	dot completions zsh
scripts/.local/bin/dot	mise run dot:build
docs/public/og.png	mise run docs:og

• Background dev servers - starting a long-running dev server follows a precedence: the project’s own AGENTS.md workflow first, then framework-native background mode (Astro 7+ self-detaches astro dev under an agent), then pitchfork as the fallback. The pitchfork-dev-server-guard plugin covers only the pitchfork tier, redirecting foreground dev commands to serve:* or pitchfork start when a project declares pitchfork.toml, and it leaves astro dev to Astro’s native mode.
• Contextual notifications - top-level task completion and permission events ring BEL, send an Omarchy-formatted desktop notification when omarchy is available, and play the freedesktop message sound when paplay is available. When the plugin starts under Hyprland, it captures the active window address so clicking a notification can return focus to that window. Background subagent completions stay silent.

Tooling

• opencode is installed through mise’s Aqua backend. The explicit c alias resolves to the same binary and keeps the GitHub MCP bearer scoped to the launched harness process.
• dot agents-sync — mirror ~/.config/opencode/AGENTS.md into agent harness instruction files. Runs automatically at the end of full dot update and dot init.
• opencode debug <paths|config|skill|info|agent> — inspect resolved OpenCode config, paths, skills, and agents directly.
• DOT_CONTEXT_CAPTURE=1 - capture assembled system-prompt segments and tool definitions for starter-context profiling. See Environment Variables.
• dot skill-updates / dot skill-check: check/apply upstream skill updates and validate branch-context command wiring.
• dot is-agent — detect whether dot is running under an AI agent, from agent environment variables with a Linux /proc ancestry fallback (exit 0/1, so scripts can branch with if dot is-agent). DOT_AGENT=1/0 overrides detection. When an agent (or a non-interactive stdout) invokes a dot command that would open the TUI, dot refuses and points at the machine-readable equivalent instead.

Publishing to opencode-config happens automatically via GitHub Actions on push. The Agents, Commands, Skills, and Plugins pages above are generated by mise run docs:gen:opencode from the live assets, so they always match what ships — edit the source assets, not the generated pages. See also the generated dot Command Reference.