Apm Dotfiles

---
name: apm-dotfiles
description: >
  Use when deciding where Stuart's reusable agent customization belongs:
  public dotfiles vs private overlay, dot-agent vs dot-skill, APM target
  compatibility, or plugin/config-fragment structure. Not for repo Rust details.
---

# APM Dotfiles

## Place the change

| Content | Owner |
|---|---|
| reusable interaction or coding workflow | `dot-agent` |
| skill/plugin authoring and maintenance | `dot-skill` |
| repository-specific guidance | that repository's `.agents/skills/` |
| work, host, employer, or private guidance | private overlay plugin |
| model/reasoning/UI defaults | public `conf/agent-settings.toml` |
| skills, hooks, prompts, instructions, MCP | APM plugin or fragment |

Prefer one narrow skill per recurring behavior. Update an existing skill instead
of adding a near-duplicate.

## Plugin rules

- Use native layout: `apm.yml`, `includes: auto`, and `.apm/<primitive>/`.
- Keep local package names short and `dot-*`.
- Reference local packages with forward slashes.
- Public files contain no secrets, private URLs, or employer-confidential data.
- Private overlays add fragments/plugins through overlay symlink config and
  reference credentials through environment variables.
- Keep self-defined MCP servers direct unless transitive trust is intentional.

## Target compatibility

- Top-level `targets` selects default harnesses.
- A dependency-level `targets` list narrows the entire package.
- Split packages when primitives need different target sets.
- Cowork remains an experimental, skills-only target. A Cowork-targeted
  package's skills must work without its MCP servers, hooks, prompts, agents,
  commands, or instructions.
- Dotfiles enables Cowork's APM feature and honors APM's configured path, then
  follows lockfile target subsets during ACL-safe file reconciliation.
  Dependency filters are authoritative.

## Verify

Use the dotfiles checkout's `docs/TESTING.md` for scoped checks and previews,
and its `ai-tooling-apm` skill for implementation details. Skill-text-only edits
need frontmatter, link, and routing review, not a live install or deployment.
For behavior changes, prefer current-source checks with isolated homes and
synthetic overlays; a wrapper may bootstrap or run an older installed binary.
An authorized preview with a real overlay can execute its cooperative
`--check`/`--dryrun` scripts. Inspect trusted scripts first and keep private paths
and output out of public reports.