Dotfiles, but for agents.
If you want to go straight to the 'dotfiles', go here.
Agent configuration files are managed with Mise and GNU Stow.
.
├── .agents/ # repo-local skills and agent instructions
├── agents/ # managed dotfiles packages
│ ├── agents-shared/ # shared AGENTS.md for Pi, OpenCode, and Codex
│ ├── dotagents/ # shared global skills under ~/.agents/skills/
│ ├── pi/ # Pi package
│ ├── vibe/ # Vibe package
│ ├── zerostack/ # ZeroStack package
│ └── … # other agent packages as needed
└── docs/ # package-specific documentation
├── agents-shared/
├── dotagents/
├── pi/
├── vibe/
├── zerostack/
└── … # other package docs as needed
agents/contains all managed agent packages.- Every direct
agents/<name>/subdirectory is a Stow package, so its contents are symlinked into the home directory. - Keep only package directories directly under
agents/.
Agents-shared provides one canonical AGENTS.md symlinked to Pi, OpenCode, and Codex global paths.
Dotagents installs reusable global skills under ~/.agents/skills/.
- detect-jujutsu and use-jujutsu are the stable Jujutsu guidance pair. Combine them with instructions in
AGENTS.md. - use-jujutsu-workspaces is an experimental, under-construction companion for
jj workspaceworkflows when running parallel agent work. It is not yet a default recommendation alongside the main Jujutsu skills. - compare-implementations compares competing solutions against the same request and recommends what to retain.
- karpathy-guidelines is a reusable coding-behaviour skill. To default-enable it for a project, add this to the project's
AGENTS.md:- Use the skill 'karpathy-guidelines' for coding tasks. - document-architectural-decisions guides creation and review of Architecture Decision Records using traditional ADRs or Y-statements.
- document-change-intentions-using-change-intent-records is a new skill under evaluation for documenting change intent worth remembering with lightweight Change Intent Records (CIRs), based on Bryan Liles' Change Intent Records pattern.
- landing-the-plane runs the end-of-task closure workflow.
.agents/skills/ holds repository-local skills that are never stowed or installed globally. They apply only to work done inside this repository.
- less-is-more restrains agent-setup growth.
- agentfiles-commit-prefixes guides commit subjects.
- extension-security-review reviews extensions/plugins before install.
- evaluate-model-routing evaluates model routing across coding agents (Pi first). It verifies a per-agent profile, fetches published benchmark results with zero-dependency Node scripts, scores capabilities per stage with declared weights, adds an advisory judge assessment, and renders a fixed Markdown + HTML report under
docs/routing-reviews/. It is recommendation-only and never changes routing. - audit-model-config finds and fixes model references that no longer work. It refreshes Pi's catalogs, audits every configured model reference in the repository against the live catalog, provider auth, and a reachability probe, then updates the configuration with an approval step and records the change.
Located in Pi.
- A global
APPEND_SYSTEM.mdfor Pi-specific startup and questionnaire-steering behaviour - An experimental
/recapprompt atagents/pi/.pi/agent/prompts/recap.mdfor a short catch-up on the current conversation. It uses the recap skill. Remove it if it does not prove useful. - A
/run-stage-planprompt atagents/pi/.pi/agent/prompts/enhanced/run-stage-plan.mdfor read-only planning before implementation. - A
/reviewprompt atagents/pi/.pi/agent/prompts/enhanced/review.mdfor read-only code review. - A
/run-stage-breakprompt atagents/pi/.pi/agent/prompts/enhanced/run-stage-break.mdfor read-only adversarial QA and failure-mode hunting. - A
/review-planprompt atagents/pi/.pi/agent/prompts/enhanced/review-plan.mdfor critical review of plan text before execution. - custom themes
-
A Jujutsu-aware footer extension that shows the nearest bookmark name, commits ahead, the short working-copy change ID, and an explicit working-copy state (clean or
+/~/‑/!file counts) on a dedicated TUI status line. Requires Jujutsu (jj) onPATH. Documentation. -
A Questionnaire extension for bounded multi-question clarification flows. Documentation.
-
A Discovery tools extension that keeps Pi's built-in
grep,find, andlstools active alongside the default coding tools. Documentation. -
A Brave search extension that registers
web_search,fetch_content, andget_fetched_content. Documentation- requires Brave
bxonPATHwith a configured API key
- requires Brave
-
A Usage statistics extension that tracks skill, loaded extensions, command, tool, and model usage into a local JSONL file, with standalone reporting executables at
~/.pi/agent/bin/pi-usage-reportand~/.pi/agent/bin/pi-usage-report-html. The reports include configurable time-interval filtering, consistent most-used, least-used, and full-list artifact rankings for skills, custom tools, and enabled models, inline extension context for extension-owned commands/tools, and an HTML at-a-glance summary. Documentation -
A Task-oriented system prompt extension that removes Pi's built-in "expert coding assistant" wording from the generated system prompt. Documentation
-
A Skill model switch extension that switches to a configured model before executing explicit
/skill:<name>commands. Mapping is read from an adjacent JSON config file. Documentation -
A Force session start model extension that resets the active model and thinking level to user-configured values on every new session, avoiding collision with Pi's own
defaultModelpersistence. Documentation -
A Command guardrails extension that enforces opt-in warn/block rules for Pi
bashtool calls from global and project-localguardrails.conffiles. It is command safety, not file secrecy or sandboxing. Documentation- no extra setup required
-
A Sandbox EPERM halt extension that detects sandbox permission failures (EPERM / "Operation not permitted") in built-in tool results and halts the agent for the current turn. It is a best-effort "stop trying" signal layered on top of sandbox containment. Documentation
- no extra setup required
Located in Vibe.
- A
config.tomlfor the Vibe CLI with Mistral provider settings, model aliases, and tool permission profiles.
Located in ZeroStack.
- A
config.tomlfor ZeroStack with Opencode Go provider configuration, model settings, and permission profiles. - An
AGENTS.mdin Zerostack's config location that that instructs every Zerostack session to integrate Agent Skills. This requiresskills-primerto be available on the CLI.
Decision logs remain active reference material:
- See
docs/decisions.mdfor repo-wide decisions - See
docs/<agent>/decisions.mdfor agent-specific decisions
For new durable change intent, we prefer lightweight Change Intent Records (CIRs):
- Repo-wide CIRs live in
docs/cir/ - Package-scoped CIRs live in
docs/<package>/cir/ - A CIR may supersede an earlier decision record when it replaces or invalidates that prior decision
The document-change-intentions-using-change-intent-records skill provides guidance on when and how to create CIRs.
For issues or pull requests visit Codeberg.
For maintainer-only tooling, common tasks, and setup instructions see SETUP.md.