feat: refresh shared skills catalog

protocols/agents-template.md

@@ -0,0 +1,65 @@
+# Autonomous Agent Repository Rules Template
+
+This protocol defines the standard structure for a repository's root `AGENTS.md`
+(and symlinked `CLAUDE.md`). It establishes concise behavioral baselines,
+deterministic boundary tiers, and progressive disclosure pointers.
+
+## Design imperatives
+
+- **Length limit**: Keep the root instruction file concise ($\le 100$ lines target,
+  300 lines maximum). Long rule files dilute model attention and are ignored.
+- **Progressive disclosure**: Keep the root file an index of essential build/test
+  commands and pointers. Direct deep subsystem knowledge or tutorials into
+  specialized documents under `docs/` or `.agents/`.
+- **Deterministic tooling**: Never delegate code formatting, whitespace, or import
+  sorting to LLM prompt prose. Formatting and linting belong exclusively to
+  deterministic CLI tools (Ruff, Biome, Prettier) run via hooks or CI.
+
+## Three-tier operational boundaries
+
+Root repository instructions must establish three explicit operational tiers:
+
+### 1. ALWAYS (Autonomous Execution)
+Actions the agent must execute autonomously without asking for confirmation:
+- Run targeted local unit and regression tests after making code changes.
+- Execute deterministic linters and formatters before staging files.
+- Update relevant documentation and architectural records when public interfaces change.
+- Follow existing repository patterns, conventions, and module structure.
+
+### 2. ASK FIRST (Human Confirmation Required)
+Boundary actions requiring explicit confirmation before invocation:
+- Modifying database schemas or executing destructive data migrations.
+- Introducing new third-party dependencies, packages, or external services.
+- Altering production deployment configurations, Dockerfiles, or CI workflows.
+- Deleting existing tracked source files or removing deprecated public APIs.
+
+### 3. NEVER (Non-Negotiable Invariants)
+Hard negative constraints that must never be violated under any circumstances:
+- Never commit plain-text credentials, tokens, or environment files (`.env`).
+- Never force-push (`git push --force` or `-f`) to any remote tracking branch.
+- Never execute destructive git resets (`git reset --hard` or `git clean -f`) on uncommitted work.
+- Never commit directly to primary branches (`main` or `master`).
+- Never suppress compiler warnings or type errors with blanket ignores (`# noqa`, `@ts-ignore`).
+
+## Canonical AGENTS.md template
+
+```markdown
+# [Project Name] Agent Rules
+
+## Stack & Commands
+- Language & Runtime: [e.g. Python 3.12 / Node 20 / Rust 1.80]
+- Package Manager: [e.g. uv / pnpm / cargo]
+- Fast Check: [e.g. pytest tests/unit/ / pnpm test / cargo test]
+- Linter & Formatter: [e.g. ruff check --fix && ruff format / pnpm biome check --apply]
+- Type Checker: [e.g. pyright / pnpm tsc --noEmit]
+
+## Three-Tier Boundaries
+- **ALWAYS**: Run relevant checks before declaring completion. Run deterministic formatters.
+- **ASK FIRST**: Adding dependencies, altering database schemas, or changing CI/deploy configs.
+- **NEVER**: Direct commits to main, force pushes, hard resets, or committing secrets/.env.
+
+## Workflow & References
+- Feature work occurs in isolated git worktrees or dedicated branches.
+- Follow WHAT-WHY-HOW-LEARNINGS telemetry format for commits and pull requests.
+- Subsystem details: see docs/architecture.md and docs/gotchas/.
+```