v3

.agents/skills/backend-guidance/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: backend-guidance
+description: Overlay for server-side networked code — HTTP handlers, gRPC services, message consumers. Use alongside the repo's implementation skill when implementing or reviewing backend logic.
+---
+
+# Backend Guidance
+
+Read `AGENTS.md` first. This is a composable overlay, not a standalone workflow.
+Use alongside the repo's implementation skill (e.g. **coding-guidance-cpp**, **project-core-dev**)
+when the change touches backend code.
+
+## When to use
+
+The repo has server-side networked code: HTTP route handlers, gRPC service
+methods, message/event consumers, or similar request-processing pipelines.
+
+## Not for
+
+HTTP client code, CLI tools that make outbound requests, batch processors, or
+offline data pipelines. These do not have the handler/service/boundary shape
+this skill addresses.
+
+## Rules
+
+- Keep handlers thin in responsibility, not by literal line count — parse
+  input, call a service function, map transport concerns, serialize output. If
+  a handler starts owning business decisions, extract that logic into a service
+  or core module.
+- Keep business logic testable without transport — no HTTP context, no gRPC
+  metadata leaking into domain functions.
+- Isolate data access behind an interface when it simplifies testing. Do not
+  add an abstraction layer when the data access is trivial or test-only.
+- Validate and sanitize external input at the boundary, before it reaches
+  business logic. Internal calls between trusted modules do not need redundant
+  validation.
+- Keep boundary-only concerns at the edge: authentication, authorization,
+  request decoding, transport-specific error mapping, and idempotency checks
+  where applicable.
+- Use dependency injection where it makes tests simpler — not as a default
+  architectural pattern.
+
+## Decision Heuristics
+
+- **Handler size:** if a handler is hard to read in one screen or mixes
+  transport concerns with business decisions, it is doing too much. Extract the
+  logic; keep the handler as glue.
+- **Test smell:** if testing a function requires standing up a server or faking
+  a transport layer, the function has a boundary problem. Move the logic
+  inward.
+- **Validation placement:** validate once, at the outer edge. If you find
+  validation scattered across layers, consolidate it at the boundary.
+
+## Validation
+
+A backend change is done when (in addition to the base implementation skill's
+validation):
+
+- handlers delegate to testable service functions
+- business logic tests run without transport dependencies
+- external input is validated at the boundary
+- transport-specific error handling stays at the boundary instead of leaking
+  into domain logic

.agents/skills/coding-guidance-cpp/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: coding-guidance-cpp
+description: C++ implementation and review skill. Use when writing, modifying, or reviewing C++ code — feature work, bug fixes, refactors, or code review. Portable across C++ repos and build systems.
+---
+
+# C++ Coding Guidance
+
+Read `AGENTS.md` first. This skill adds C++ implementation and review guidance.
+
+## Adjacent Skills
+
+This skill provides portable C++ engineering principles. Compose with:
+
+- **Workflow:** **thinking** (planning), **recursive-thinking** (stress-testing),
+  **security** (threat modeling)
+- **Domain overlays:** **backend-guidance** (server-side code),
+  **ui-guidance** (graphical UI/web frontend),
+  **project-core-dev** (repo-specific build/test commands)
+
+## Implementation Workflow
+
+1. Read the touched code, build shape, and existing tests.
+2. Identify the narrowest change that solves the problem.
+3. Implement with simple, behavior-oriented interfaces.
+4. Add or update tests using the repo's established test framework, close to the
+   changed behavior.
+5. Run the repo's formatter, then run relevant build, test, and analyzer targets.
+
+## Review Workflow
+
+When reviewing (not implementing), skip the implementation workflow and use this
+instead:
+
+1. Read the change in full before commenting.
+2. Identify findings, ordered by severity: `Critical` > `Important` > `Suggestion`.
+3. Prioritize: bugs and regressions, ownership/lifetime issues, missing
+   validation or error handling, missing tests, security or performance risks
+   with real impact.
+4. Report findings first. Skip praise unless the change is notably well-done.
+
+## C++ Rules
+
+### First tier — causes bugs
+
+- Treat raw pointers and references as non-owning; make ownership transfer
+  explicit in the type or documented in a comment
+- Avoid `new`/`delete` — use RAII wrappers and smart pointers
+- Prefer `std::unique_ptr` by default when single ownership is intended; use
+  `std::shared_ptr` only when shared lifetime is a real requirement
+- Avoid unchecked bounds access — prefer `.at()`, range-for, or
+  iterator patterns over raw indexing when bounds are uncertain
+- Avoid silent narrowing conversions — use explicit casts or `narrow_cast`
+
+### Second tier — prevents mistakes
+
+- Avoid C-style casts — use `static_cast`, `const_cast`, `reinterpret_cast`
+  to make intent visible
+- Prefer rule-of-zero types; if you write a destructor, justify it
+- Prefer `std::array` over C arrays, `std::string_view` and, where available,
+  `std::span` over raw pointer-plus-length pairs when lifetime rules are clear
+- Prefer explicit helper structs over ambiguous adjacent parameters of the
+  same type
+- Use `[[nodiscard]]` on functions where ignoring the return value is a bug
+- Avoid unnecessary copies in range-for — use `const auto&` by default, but
+  prefer value iteration for cheap copy types or when ownership transfer is the
+  point
+- Keep warnings at zero in repo-owned code
+
+## Decision Heuristics
+
+Use these when the right choice is not obvious:
+
+- **Scope check:** if a change touches more than 3 public interfaces, stop and
+  plan before continuing — the change is bigger than it looks.
+- **Ownership clarity:** if resource ownership is not obvious from the type
+  signature alone, add a one-line comment documenting the contract.
+- **Repo conventions:** if the repo has established rules for exceptions,
+  ownership types, containers, or error handling, follow them unless they cause
+  a correctness or safety problem.
+- **Test setup size:** if test setup exceeds ~20 lines, extract a fixture — but
+  only if the setup is reused by at least 2 tests.
+- **Narrowness vs. quality:** implement the narrowest change that solves the
+  problem. When narrowness conflicts with correctness or safety, prefer
+  correctness. When it conflicts with style, prefer narrowness unless
+  explicitly time-boxed for cleanup.
+- **Refactor boundary:** when modifying a file, fix at most one small adjacent
+  issue. Do not refactor unrelated code in the same change.
+- **Abstraction threshold:** three similar code blocks is a pattern; two is
+  coincidence. Do not extract a helper until the third occurrence unless the
+  duplication crosses a module boundary.
+
+## Validation
+
+A change is done when:
+
+- the code compiles without new warnings, unless the repo explicitly treats a
+  known warning set as baseline debt outside the change
+- existing tests pass
+- new or changed behavior has test coverage
+- the repo's formatter has been run
+- static analyzers (if configured) report no new findings
+- review findings at `Critical` and `Important` severity are addressed

.agents/skills/development-contract-core/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: development-contract-core
+description: Portable workflow for repos that require tracked change contracts, verifier evidence, and smallest-proof validation. Use when a repo has a contract policy file or enforced feature-plan checker.
+---
+
+# Development Contract Core
+
+Read `AGENTS.md` first. Then find the repo's contract policy file and use it as the source of truth for repo-specific paths, plan locations, lanes, and validation profiles.
+
+## Use this skill when
+
+- work may trigger a tracked change contract
+- a repo requires a plan update for substantive changes
+- a checker validates plan structure, ownership, or evidence
+- you need to choose the smallest proving validation set for a substantive change
+
+## Core workflow
+
+1. Read `AGENTS.md`, the touched files, and the repo contract policy file before editing.
+2. Decide whether the change is substantive using policy data rather than guesswork.
+3. If the change is substantive, create or update a non-template plan in the policy-defined plan directory.
+4. Keep the plan aligned with the repo's enforced template, required evidence lanes, and lifecycle-directory rules.
+5. Keep implementation ownership and verification ownership explicit.
+6. Record verifier commands, observed results, and contract mismatches concretely.
+7. Run the smallest validation profile that proves the change, then extend only when the surface justifies it.
+8. Before closing work, run the repo's checker command and any additional checks implied by the chosen validation profile.
+
+## Decision rules
+
+- Treat the policy file as the single source of truth for substantive-path detection, plan location, section requirements, lane names, and default validation commands.
+- If the repo ships a lifecycle transition helper, prefer it over manual file moves so path and lifecycle state stay synchronized.
+- Do not duplicate repo literals across the skill, docs, checker, and template when policy can express them once.
+- Keep the schema stable by default; use policy for repo-level variation and only change the schema when portability or correctness requires it.
+- Prefer small repo overlays over forking the core skill.
+- If a repo needs extra instructions that policy cannot express, add them in a thin overlay skill rather than bloating the core.
+
+## Output expectations
+
+When this skill applies, the final work should leave behind:
+
+- code or docs aligned with `AGENTS.md`
+- a plan update when the change is substantive
+- explicit verifier evidence
+- a concise report of what was validated and what could not be validated
+
+## References
+
+- `references/policy-reference.md` for the portable policy surface and adoption rules
+- `references/run-release-checklist.example.sh` for a portable pre-release runner scaffold

.agents/skills/development-contract-core/references/policy-reference.md

@@ -0,0 +1,34 @@
+# Development Contract Policy Reference
+
+Use a small repo-local policy file as the source of truth for contract enforcement.
+
+## Minimum policy surface
+
+- plan directory
+- template basename
+- substantive path patterns
+- substantive top-level files
+- required section headings
+- allowed lifecycle values
+- allowed uncertainty/cost values
+- evidence lane names
+- checker command
+
+Prefer a repo-neutral path such as `config/change-contract-policy.sh`, when the repository itself, CI, or shell scripts depend on the policy.
+
+## Recommended additions
+
+- named validation profiles such as `docs`, `code`, and `release`
+- repo-specific examples for install or smoke-test commands
+- comments that explain why a path or lane is part of the contract
+- a release-runner example kept as a skill reference, while the runnable repo copy lives under `scripts/`
+- a repo-owned lifecycle helper when records live in state-specific subdirectories
+
+## Portability rules
+
+- keep policy data repo-local and declarative
+- keep the core skill generic
+- keep the checker reading the same policy file that humans read
+- keep template and docs aligned with policy names
+- keep lifecycle folder rules and any transition helper aligned with the checker
+- prefer extending policy over cloning the core skill