// Use when starting work in any repository. Auto-surface when an agent is about to write code, create a PR, or verify work. Teaches the discovery pattern for finding and applying per-repo conventions (AGENTS.md, PR templates, CONTRIBUTING.md) before acting.
Use when verifying that completed work actually works. Auto-surface during /verify mode, post-implementation review, or before claiming a task is done. Teaches the discipline of testing outcomes vs implementation, the unit/integration/smoke gradient, and what "done" actually means.
Use when building a new CLI tool that needs one-line install via uv or npm, subcommand dispatch with a default action, or 3-tier config resolution (CLI flags, config file, hardcoded defaults).
Use when designing a curl-piped install script for a project that cannot use uv tool install or npm publish — multi-service stacks (Docker Compose), raw TS/React apps, tools that bootstrap system dependencies, or installs for non-technical audiences. Documents the security trade-off, the community convention used by rustup, bun, deno, fly, ollama, and supabase, and the cases where this pattern is the wrong answer.
Use when your service needs authentication that works without friction locally but secures remote access, automatic TLS certificate setup, or token-based auth with auto-generation and localhost bypass.
Use when your tool needs persistent configuration files with safe defaults merging, atomic state writes that survive crashes, or conventional file locations for config vs state vs secrets.
Use when running tasks in Docker containers with safety limits, watchdog monitoring for resource enforcement, orphan container recovery, sidecar container provisioning, or scripting reproducible dev stack environments.
| name | per-repo-conventions |
| description | Use when starting work in any repository. Auto-surface when an agent is about to write code, create a PR, or verify work. Teaches the discovery pattern for finding and applying per-repo conventions (AGENTS.md, PR templates, CONTRIBUTING.md) before acting. |
When you work in a repo, you're a guest. The repo's owners maintain conventions that encode their experience — including bugs they have already paid for. Read those conventions before you act.
The foundation/kernel layer defines philosophy. Individual repos define specifics. The kernel does not know what a particular repo's smoke test command is, what its PR checklist requires, or which gates its maintainers consider non-negotiable. The repo does. Honor it.
At the start of any task that touches a repo, before writing code, walk this checklist:
AGENTS.md — check the repo root first, then walk up from the current
working directory if you're working in a subdirectory. This is the
highest-signal file for agent behavior in this ecosystem..github/PULL_REQUEST_TEMPLATE.md — check at repo root. This is the
checklist your PR must honor.CONTRIBUTING.md — check at repo root. General contribution
conventions.Skim each file that exists. Apply the relevant conventions to your work.
AGENTS.md — agent-facing conventions. Test commands, common pitfalls,
build steps, environment requirements, areas to avoid touching, and the
shape of "done" in this repo. Often the only place where tribal knowledge
is written down..github/PULL_REQUEST_TEMPLATE.md — the checklist that auto-populates
every PR body. Treat each checkbox as a required action, not a suggestion.CONTRIBUTING.md — broader contributor guidance. Style, branching,
review process, sign-off requirements.I'm about to fix a bug in some-repo. Before writing code, I read:
- some-repo/AGENTS.md
→ "Smoke test required: ./scripts/smoke-test.sh on a fresh DTU"
→ "Engine changes require a live pipeline run, not just unit tests"
- some-repo/.github/PULL_REQUEST_TEMPLATE.md
→ "[ ] Smoke test passed (link log)"
→ "[ ] Live run exercising changed code path (link events.jsonl)"
My plan:
1. Implement the fix.
2. Run unit tests (necessary, not sufficient).
3. Run ./scripts/smoke-test.sh on a fresh DTU per AGENTS.md. Capture log.
4. Run a live pipeline exercising the changed path. Capture events.jsonl.
5. PR body addresses each checklist item explicitly with links to evidence.
The cost of this discovery pass is minutes. The cost of skipping it is the integration-blocking bug the repo's conventions were written to prevent.
foundation:docs/PER_REPO_CONVENTIONS.md — canonical statement of the
principle.skills/verification-discipline/ — the complementary skill that explains
why per-repo gates (especially smoke and integration tests) matter and
what "verified" actually means.