Skip to content

AGENTS.md

Latest commit

 

History

History
48 lines (35 loc) · 2.6 KB

AGENTS.md

File metadata and controls

48 lines (35 loc) · 2.6 KB
Raw

AGENTS

Personal dotfiles managed with GNU Stow across macOS and Linux.

Preferences

  • Prefer event-based systems over polling when both are viable.
  • Planning tasks should be vertical slices with observable outcomes, not horizontal layers.
  • Add a brief intent comment when code preserves a non-obvious constraint, ordering/lifecycle requirement, workaround, performance tradeoff, or fallback whose reason is not clear from names, types, and local control flow; do not restate obvious mechanics.

Essentials

  • Do not edit generated state/lock files (e.g. nvim-pack-lock.json, AGS GIR typings, Fish auto-generated dirs).
  • Follow symlinks when reading docs.
  • Dotfiles repo root is ~/dotfiles.
  • Shared skills live in .agents/skills/ and are mirrored under .config/{codex,github,claude}/skills.
  • Dotfiles-specific Pi skills live in .pi/skills/.
  • Before editing a skill, check skills-lock.json; do not modify skills sourced from upstream repositories. Put local guidance in a locally authored skill or instruction file instead.

OpenSpec

  • Use <domain>-<behavior> when a domain disambiguates the capability, such as hypr-custom-layout-ordering, ags-calendar-widget, or neovim-context-mcp-bridge.
  • Keep each change as one cross-cutting vertical slice when it affects multiple areas.

Commands

  • just stow-apply
  • just stow-check
  • Add and run tests through devenv test.
  • Run Caliper skill evaluations through scripts/caliper-skill-eval.sh; do not invoke caliper run directly.

Pi Extensions

  • Extensions in .pi/agent/extensions/ are auto-discovered from the Stow-linked ~/.pi/agent/extensions/; use /reload after changes.
  • Before changing Pi extensions or upgrading Pi, follow SDK alignment; compile and test against the installed runtime, not stale npm declarations.
  • Configure the main agent's startup tools through defaultTools in .pi/agent/settings.json, using +tool_name to preserve the inherited selection. Do not hardcode startup activation in extension JavaScript or TypeScript.
  • Keep optional tools deferred in their registrations. Enable only the needed entry point by default, such as subagent; leave subagent_result and subagent_control discoverable on demand.

References