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/.
+```

protocols/telemetry.md

@@ -0,0 +1,73 @@
+# Standardized Agent Telemetry Protocol
+
+This protocol defines the **WHAT-WHY-HOW-LEARNINGS** communication standard for
+autonomous agents. It eliminates unstructured conversational filler and ensures
+every completion report and pull request provides verified empirical evidence and
+captures reusable operational memory.
+
+## Governing principle
+
+**"The model proposes, but the engine measures."**
+An agent must never claim completion based on internal heuristics or theoretical
+assumptions. Verification requires concrete CLI execution evidence with explicit
+exit codes and metric outputs.
+
+## Telemetry structure
+
+When reporting task completion or generating pull request bodies, format the
+output using these four distinct sections:
+
+### 1. WHAT (System Modifications)
+Itemize physical repository deltas. Do not use speculative language. Mirror the
+factual `git status` / `git diff` state:
+- **Modified Components**: Relative paths of modified files.
+- **Added Assets**: Relative paths of newly created modules, tests, or configurations.
+- **Removed Assets**: Deprecated files, removed functions, or deleted packages.
+
+### 2. WHY (Context & Architectural Intent)
+Articulate the underlying rationale and business justification:
+- **Problem Statement**: Explicit description of the bug, requirement, or performance bottleneck.
+- **Requirement Traceability**: Reference to specification issue, plan bead, or task ticket.
+- **Design Justification**: Why this approach was selected over alternative implementations.
+
+### 3. HOW (Technical Implementation & Verification Evidence)
+Detail the mechanical execution and empirical proof of correctness:
+- **Implementation Details**: Summary of algorithmic changes, API updates, or data structures.
+- **Deterministic Verification Evidence**:
+  - Exact command(s) executed (e.g. `pytest tests/unit/test_auth.py -v`).
+  - Terminal exit code (must be 0).
+  - Test runner output metrics (e.g. `38 passed, 0 failed, 100% pass rate in 1.4s`).
+- **Static Analysis & Type Checks**:
+  - Linter/type checker commands and output (e.g. `ruff check src/` -> clean).
+
+### 4. LEARNINGS & ARCHITECTURAL GOTCHAS
+Capture operational traps, latent technical debt, and environment quirks:
+- **Operational Traps**: Version sensitivities, platform discrepancies, race conditions.
+- **Uncovered Debt**: Missing mocks, tight couplings, or obsolete patterns uncovered.
+- **Repository Gotchas**: When a new trap or quirk is discovered, persist it to
+  `docs/gotchas/<slug>.md` so subsequent sessions load it into context.
+- **Upstream Dependencies**: Follow-up tasks or recommendations.
+
+## Markdown template for PRs and task reports
+
+```markdown
+### 1. WHAT (System Modifications)
+- **Modified**: `src/auth/session.py`
+- **Added**: `tests/unit/test_session_refresh.py`
+- **Removed**: None
+
+### 2. WHY (Context & Architectural Intent)
+- **Problem**: Concurrent session refresh requests cause race conditions and invalid tokens.
+- **Traceability**: Closes #142 (Task T-3).
+- **Design Justification**: Implemented in-process locking with Redis token leases.
+
+### 3. HOW (Technical Implementation & Verification Evidence)
+- **Implementation**: Wrapped refresh logic in distributed mutex with 5s expiry.
+- **Verification Commands Executed**:
+  - `pytest tests/unit/test_session_refresh.py` (Exit Code: 0, 12 passed in 0.8s)
+  - `ruff check src/auth/` (Exit Code: 0, clean)
+
+### 4. LEARNINGS & ARCHITECTURAL GOTCHAS
+- **Operational Trap**: Redis cluster failover resets key TTL in mock environment.
+- **Indexed Gotcha**: Saved to `docs/gotchas/redis-mock-cluster-ttl.md`.
+```

protocols/workflow.md

@@ -0,0 +1,45 @@
+# Shared workflow
+
+Skills simplify an authorized task. User instructions and repository conventions
+set the scope; a skill supplies defaults where those leave a gap.
+
+- Use the existing conversation, files, and project state before asking questions.
+  Ask only when a missing answer changes the outcome and cannot be inferred safely.
+- A report or audit stays read-only. An implementation request authorizes the
+  necessary reversible edits and checks. Continue authorized work without asking
+  the user to approve each step.
+- Follow the repository's operational boundaries ([agents-template.md](agents-template.md)):
+  distinguish autonomous actions (ALWAYS), user-approved boundaries (ASK FIRST),
+  and hard invariants (NEVER).
+- Do not create a spec, force a review, run an editing skill, or start a refactor
+  merely because another skill mentions it. Use another workflow only when its
+  prerequisites and purpose fit the current task.
+- Preserve unrelated changes. Stage and commit only within the authorized scope,
+  following repository and session instructions. A skill does not require commits.
+- Keep references optional: read the relevant section when needed. Do not load
+  every protocol or checklist on each task.
+- Report completion and pull requests using the [telemetry protocol](telemetry.md)
+  (WHAT-WHY-HOW-LEARNINGS).
+
+## Verification
+
+**"The model proposes, but the engine measures."**
+Choose checks that can detect a real failure in the changed behavior.
+
+1. Run the smallest relevant check first: syntax, a focused test, type check,
+   rendered interaction, or direct output inspection.
+2. Broaden to integration or the full suite when shared behavior, security,
+   migrations, or unresolved failures justify it, or project instructions require it.
+3. Do not add tests that mirror implementation or cover only a reversible prose
+   or cosmetic edit. Add regression coverage for meaningful behavioral bugs when
+   practical; a reproduction or manual check can be the evidence when automation
+   is unsuitable.
+4. Distinguish new failures from pre-existing failures and missing dependencies.
+   Report what passed and what remains unverified; do not claim unavailable checks
+   passed or rewrite unrelated code to make the entire repository green.
+5. Once relevant checks pass, stop repeating them unless something changed.
+6. When reporting verification in task handoffs or PRs, document the exact terminal
+   command, exit code, and pass counts under the HOW section of telemetry.
+
+Complete means the requested behavior is implemented and supported by empirical
+evidence. A successful command exit alone does not prove the user-facing outcome.