@anyberg/agent-conventions 1.0.0

package/skills/backlog-management/scripts/detect-backend.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Prints: github-issues | markdown | none
+set -euo pipefail
+root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+policy="$root/.planning/policy.yml"
+
+if [[ -f "$policy" ]]; then
+  # POSIX classes, not \s: BSD sed (macOS) treats \s as a literal 's', which
+  # leaves the value padded and makes `backend: auto` read as an explicit backend.
+  explicit="$(grep -E '^[[:space:]]*backend:' "$policy" | head -1 \
+    | sed -E 's/.*backend:[[:space:]]*//; s/[[:space:]]*#.*//; s/[[:space:]]+$//' || true)"
+  if [[ -n "${explicit:-}" && "$explicit" != "auto" ]]; then
+    if [[ "$explicit" == "github-issues" && -f "$root/BACKLOG.md" && ! -f "$root/.planning/backlog-migration.json" ]] \
+       && grep -qE '^\| *(LMS|INFRA|DEV|[0-9]{3})' "$root/BACKLOG.md"; then
+      echo "markdown  # policy says github-issues but migration incomplete" >&2
+      echo markdown; exit 0
+    fi
+    echo "$explicit"; exit 0
+  fi
+fi
+
+remote="$(git -C "$root" remote get-url origin 2>/dev/null || true)"
+if [[ "$remote" == *github.com* ]] && gh auth status >/dev/null 2>&1; then
+  if [[ "$(gh api "repos/{owner}/{repo}" --jq .has_issues 2>/dev/null)" == "true" ]]; then
+    echo github-issues; exit 0
+  fi
+fi
+
+if [[ -f "$root/BACKLOG.md" ]]; then echo markdown; exit 0; fi
+echo none; exit 1

package/skills/backlog-management/scripts/generate-policy.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Generates <root>/.planning/policy.yml from the plugin's best-practice
+# template if it does not already exist. Idempotent: never touches an
+# existing file. Prints a human-readable report of what it generated.
+set -euo pipefail
+
+root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+target="$root/.planning/policy.yml"
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+template="$script_dir/../../../policy.example.yml"
+
+if [[ -f "$target" ]]; then
+  echo "policy.yml already exists at $target — leaving it untouched."
+  exit 0
+fi
+
+if [[ ! -f "$template" ]]; then
+  echo "Template not found at $template — cannot generate policy.yml." >&2
+  exit 1
+fi
+
+backend="markdown"
+reason="no GitHub remote, no gh auth, or Issues not enabled"
+remote="$(git -C "$root" remote get-url origin 2>/dev/null || true)"
+if [[ "$remote" == *github.com* ]] && gh auth status >/dev/null 2>&1; then
+  if [[ "$(gh api "repos/{owner}/{repo}" --jq .has_issues 2>/dev/null)" == "true" ]]; then
+    backend="github-issues"
+    reason="origin is on github.com, gh is authenticated, and Issues is enabled"
+  fi
+fi
+
+mkdir -p "$root/.planning"
+sed "s/backend: auto/backend: $backend/" "$template" > "$target"
+
+cat <<EOF
+Generated $target — no existing policy.yml was found.
+
+Detected:
+  backlog.backend = $backend  ($reason)
+
+Everything else uses the best-practice defaults documented inline in the
+generated file (commit types, branch format, versioning, autonomous limits,
+ID scheme, etc.) — none of these were detected from your repo, they are
+starting points.
+
+This file is now yours: edit any value directly at any time, nothing
+regenerates or restarts it, and it will not be overwritten automatically
+again.
+EOF

package/skills/code-review/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: code-review
+description: Review code changes on the current branch or PR before merge, in any language. Detects the languages in the diff and applies the matching guideline skill (python-coding-guidelines, typescript-coding-guidelines, rust-coding-guidelines). Use for PR reviews, branch audits, test adequacy checks, and as the independent reviewer step in task-workflow merge readiness. Constructive tone, actionable findings.
+---
+
+# Code Review
+
+Structured review of code modified on the current branch, focusing on correctness and edge cases, readability and maintainability, idiomatic usage per language, typing quality, test coverage of business logic, KISS, pragmatic SOLID, and separation of concerns.
+
+Uses constructive, collaborative phrasing ("Have you considered ...?") with practical suggestions.
+
+## When to use
+
+- Reviewing a pull request or branch before merge
+- Acting as the independent reviewer in **task-workflow** row 12
+- Auditing recent changes for quality
+- Improving test strategy for new functionality
+
+## Reviewer independence
+
+When invoked as the independent reviewer, the reviewer receives only: the diff, the backlog item (goal and acceptance criteria), and the tests. It does not receive the author's reasoning, plan, or log. It runs in a fresh context or as a separate subagent. The author never approves their own PR.
+
+## Workflow
+
+### 1) Collect changed files
+
+```bash
+git fetch origin
+base=$(git merge-base HEAD origin/main)
+git diff --name-only "$base"...HEAD
+```
+
+Group by language from extension: `.py` → python-coding-guidelines; `.ts .tsx .js .jsx` → typescript-coding-guidelines; `.rs` → rust-coding-guidelines. Load each applicable guideline skill plus **code-standards**. Files with no matching guideline (SQL, YAML, shell, Terraform) are reviewed against the universal checks only. If no reviewable files changed, report that and stop.
+
+### 2) Review each changed file
+
+Universal checks, every language:
+
+1. **Correctness**: bugs, missed edge cases, failure modes, error handling, input validation at boundaries.
+2. **Security**: authz on every new endpoint or query path, no secrets in code or logs, no injection via string-built queries or shell, no new dependency without a human label.
+3. **Tests**: business logic and complex behaviour tested; critical paths, edge cases, regressions covered; no test deleted or skipped without justification; no exhaustive tests demanded for trivial wrappers.
+4. **Design**: KISS, cohesion, dependency direction, interface clarity, split overly complex units.
+5. **Scope**: diff matches the acceptance criteria, no unrelated changes, no drive-by refactors outside task scope.
+6. **Docs**: `CHANGELOG.md` and `.planning/architecture.md` updated when behaviour or structure changed.
+
+Language-specific checks:
+
+**Python**
+- Google Python Style Guide alignment, naming, docstrings, clear control flow
+- Public APIs and core logic typed; precise hints; no unnecessary `Any`
+- Idiomatic constructs, no overengineering
+
+**TypeScript / JavaScript**
+- `strict` respected; `unknown` over `any`; `as` only with documented safety reasoning; `@ts-expect-error` only with a comment
+- Discriminated unions and `never` exhaustiveness on sum types
+- Runtime validation (zod or equivalent) at every external boundary: request bodies, env, third-party responses
+- Async errors handled; no swallowed `.catch`; domain error classes with `cause`
+- Named exports, import order, no circular imports
+- Changed behaviour has a unit test or a Playwright test; stubs preferred over full module mocks
+- Frontend: accessible markup (labels, roles, keyboard), no layout done with `any`-typed props
+
+**Rust**
+- Per rust-coding-guidelines: ownership clarity, error types with `thiserror` or equivalent, no `unwrap` in library paths, clippy clean
+
+### 3) Prioritise findings
+
+- **High**: likely bug, missing critical test, unsafe behaviour, authz gap, scope violation
+- **Medium**: maintainability risk, weak typing, design concern, missing boundary validation
+- **Low**: style or readability polish
+
+### 4) Constructive language
+
+Prefer "Have you considered handling ...?", "Would it simplify this if ...?", "Could this be split into ... for clearer separation?". Avoid "This is wrong."
+
+### 5) Actionable suggestions
+
+Every significant finding: why it matters, concrete improvement, optional code sketch.
+
+## Output format
+
+1. **Summary**: scope reviewed (files, languages), overall impression, verdict `approve` | `request-changes` | `needs-human`.
+2. **Findings by priority**: High / Medium / Low, file + location, observation + suggestion.
+3. **Testing assessment**: what is adequately tested, what critical behaviour is not.
+4. **Refactor opportunities**: KISS simplifications, separation of concerns, idiomatic upgrades.
+5. **Acceptance criteria check** (independent reviewer only): each criterion with met / not met / cannot verify.
+
+`needs-human` is mandatory when the diff touches a `policy.autonomous.require_human_review_if_touches` path, adds a dependency, or changes a public API or schema.
+
+## Quality checks before finishing
+
+- Reviewed only changed branch files, or stated the deviation
+- Loaded the guideline skill for every language present
+- Included typing, security, and testing assessment
+- Called out complexity with simplification options
+- Verdict stated explicitly

package/skills/code-standards/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: code-standards
+description: Use when writing code, running linters, or reviewing pull requests. Covers universal cross-language code rules (style, naming, error handling, imports, testing), testing boundaries, language style-guide loading, and semantic versioning.
+---
+
+# Code Standards
+
+Enforces consistent code quality and architectural boundaries.
+
+## General Rules
+
+### Testing Boundaries
+- **Strict separation:** no implementation in test files, no test code in implementation files.
+- Test files are for validation; implementation files are for logic.
+- Shared test utilities go in a dedicated `test-utils` or `testing` module.
+
+### Style Guides
+
+Load language skills based on the files being changed. Each language skill carries only **language-specific** idioms, type-system usage, and tooling; the **Universal Code Rules** below apply to every language.
+
+- **Python** (`.py`, `pyproject.toml`, `requirements.txt`): load `python-best-practices` + `python-coding-guidelines`; also load `python-design-patterns` when designing or refactoring component structure
+- **TypeScript / JavaScript** (`.ts`, `.tsx`, `.js`, `.jsx`): load `typescript-coding-guidelines`
+- **Rust** (`.rs`, `Cargo.toml`): load `rust-best-practices` + `rust-coding-guidelines`; also load `rust-design-patterns` when designing or refactoring component structure
+- **Docs** (`.md`, `README`, `CHANGELOG`, role/layer docs): load `docs-standards`
+- **Hatch projects**: load `hatch-workflow` for test, lint, and build entrypoints
+
+### Semantic Versioning
+- **Source of truth:** `pyproject.toml` (Python) or `package.json` (Node.js/TypeScript)
+- Format: `MAJOR.MINOR.PATCH` (e.g., `1.2.3`)
+- Bump version when cutting a release alongside a commit that updates CHANGELOG.md
+
+### Conciseness
+- Answers are short, no loss of information.
+- "Fix this: X" > "We need to fix this: X"
+- Comments explain *why*, not *what*; code is self-documenting.
+
+## Universal Code Rules
+
+Language-agnostic rules shared across Python, TypeScript, and Rust. The language coding-guidelines skills add the specifics (syntax, mechanisms, tooling) on top of these.
+
+### Style
+- Keep each commit/PR focused on a single stated purpose — exclude unrelated changes even if conceptually related (in Gerrit-style repos, each commit *is* a PR).
+- Wrap code identifiers in backticks in user-facing messages (errors, warnings, logs).
+- Centralize validation at one layer — validate/parse into a trusted type once at the boundary, then rely on it; prevents validation drift.
+- Extract duplicated logic into a shared helper after 2+ occurrences — refactor rather than fork a parallel implementation.
+- Consolidate duplicate logic across conditional branches (combined conditions, extracted variables, hoisted shared code).
+- Remove commented-out code, unused definitions, and superseded implementations — version control preserves history.
+- Inline single-use helpers that only wrap field/property access or delegation — removes needless indirection.
+- Scope helpers and constants to their single usage site — don't hoist to module/crate root "just in case".
+- Compile static regex patterns once as module-level constants — avoid recompiling on every call.
+
+### Naming
+- Drop redundant prefixes when context is clear — `Config.description`, not `Config.config_description`.
+- Use specific names that convey meaning (`user_id`, `order_id`) over generic `id`, `name`, `data`.
+- Boolean functions/variables read as predicates — `is_*`, `has_*`, `can_*`.
+- Avoid redundant type suffixes (`Value`, `Type`, `Class`, `List`, `Str`) when the type is already clear.
+- Rename functions/methods when their behavior changes — names must reflect actual scope, return values, and abstraction level.
+
+### Error Handling
+- Use domain-specific error types and preserve the cause chain when wrapping or re-raising (see each language skill for the mechanism).
+- Don't use assertions as error handling — raise/throw a descriptive error including the relevant identifiers.
+- Validate inputs before expensive work — fail fast.
+- Catch specific error types, not a blanket catch-all, when the failure modes are known.
+
+### Imports
+- Place imports at the top of the file — no inline imports inside functions unless intentional, documented lazy-loading.
+- Remove unused and duplicate imports.
+
+### Testing
+- Remove tests when redundant, obsolete, or duplicative — each test should verify distinct, currently-existing behavior.
+- Test behavior through the public interface, not private internals.
+- Use descriptive test names that read as sentences.
+- Don't suppress coverage to hide gaps — write the test; only mark genuinely unreachable paths.

package/skills/docs-standards/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: docs-standards
+description: Use when writing or updating documentation — READMEs, CHANGELOGs, role/layer docs, ADRs, or API references. Covers doc placement, changelog format, the mandatory role-doc layout, writing style, and when to hand off to the docs-change-steward agent.
+---
+
+# Documentation Standards
+
+Keeps repository documentation consistent, factual, and in sync with the code it describes.
+
+## When to Load
+
+Load this skill when:
+
+- Writing or editing `.md` files (README, guides, runbooks)
+- Adding a `CHANGELOG.md` entry or preparing release notes
+- Creating or updating role docs (`docs/roles/*.md`) or layer docs
+- Documenting a public API, module, or behavioural change
+- Reviewing a pull request that changes documentation
+
+For **multi-file doc synchronisation** after a code change — mapping a diff to every affected page and maintaining release traceability — hand off to the **docs-change-steward** agent, which enforces these same standards at scale.
+
+## Where Documentation Lives
+
+| Doc | Location | Owning skill / agent |
+|-----|----------|----------------------|
+| Project overview | `README.md` | docs-standards |
+| Release history | `CHANGELOG.md` | docs-standards + code-standards (versioning) |
+| System-as-is + ADRs | `.planning/architecture.md` | architecture-planning |
+| Role behaviour | `docs/roles/*.md` | docs-change-steward |
+| Layer / locked-version tables | layer docs | docs-change-steward |
+| Task / backlog records | `.planning/tasks/`, `BACKLOG.md` | task-workflow, backlog-management |
+
+Keep each doc in its canonical location. Do not duplicate the same information across files — link instead.
+
+## Writing Style
+
+- **Factual and concise.** Describe what is true now; never invent versions, dates, or behaviour.
+- **Explain *why*, not *what*.** The code shows *what*; docs add rationale and context.
+- **Match existing terminology.** Reuse the repo's nouns and headings; don't introduce synonyms.
+- **Prefer tables and short lists** over long prose for reference material.
+- **Imperative, active voice** in instructions ("Run", not "You should run").
+
+## Markdown Conventions
+
+- One `#` H1 per file (the title); nest headings without skipping levels.
+- Fenced code blocks always carry a language hint (` ```bash `, ` ```python `).
+- Use relative links between repo docs so they survive clones and moves.
+- Wrap file names, paths, commands, and identifiers in backticks.
+
+## CHANGELOG Format
+
+Follow *Keep a Changelog* with Semantic Versioning. The version source of truth is `pyproject.toml` (Python) or `package.json` (Node/TypeScript) per **code-standards**.
+
+```markdown
+## [1.4.0] - 2025-01-30
+### Added
+- Short, user-facing description of the change.
+### Fixed
+- ...
+```
+
+- Group entries under `Added`, `Changed`, `Fixed`, `Removed`, `Deprecated`, `Security`.
+- Add an entry **only when public or observable behaviour changes** (mirrors **task-workflow** merge-readiness step 5).
+- Bump the version and update `CHANGELOG.md` in the same commit that cuts the release (**code-standards** → Semantic Versioning).
+
+## Role Doc Layout (mandatory)
+
+When creating or updating a role document under `docs/roles/*.md`, use this exact top-level section order so files stay consistent with the **docs-change-steward** agent:
+
+1. `## What is this role?`
+2. `## What does this role do?`
+3. `## Configuration`
+4. `## Files and Templates`
+5. `## Other Important Information` (only if needed)
+
+Rules:
+
+- Do not add alternative top-level headings (no "Overview", "Features", "Requirements").
+- Omit `Other Important Information` when there is nothing extra to say.
+- Save locked software versions in their layer-doc version tables when applicable.
+
+## Keeping Docs in Sync
+
+Treat stale documentation like a failing test — fix it in the same branch as the change that made it wrong:
+
+- A behavioural change updates the affected page **and** `CHANGELOG.md`.
+- A structural change updates `.planning/architecture.md` (see **architecture-planning**).
+- Missing or outdated docs are **Documentation debt** — log them via **tech-debt**, then track through **backlog-management**.
+
+## Commits & Branches
+
+Documentation-only changes use the `docs` type (see **git-conventions**):
+
+- Commit: `docs(<scope>): <imperative>` — e.g. `docs(api): clarify retry backoff`
+- Branch: `docs/<short-kebab-description>`

package/skills/git-conventions/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: git-conventions
+description: Use when committing, creating branches, opening PRs, or managing git workflow, including worktrees for parallel agents. Covers Conventional Commits, branch naming tied to backlog IDs, one-change-per-branch discipline, worktree isolation scripts, versioning policy, and actions agents must never take.
+---
+
+# Git Conventions
+
+Enforces Conventional Commits and disciplined branching across all projects. Values marked *policy* come from `<root>/.planning/policy.yml`, generated on first use from best-practice defaults if the file doesn't exist (see **backlog-management**'s `scripts/generate-policy.sh`); the defaults stated below apply for any individual key still missing from an existing file.
+
+## Commit Format
+
+```
+<type>(<scope>): <imperative verb>
+
+Optional longer description explaining why, not what.
+```
+
+**Types:** *policy* `git.commit_types`, default `feat`, `fix`, `chore`, `docs`, `refactor`, `test`. The set matches backlog item types so every item can have a matching branch.
+
+**Examples:**
+- `feat(auth): add JWT refresh rotation`
+- `fix(search): resolve partial index corruption`
+- `refactor(courses): extract pagination helper`
+- `test(enrolment): cover duplicate enrolment path`
+- `chore(deps): bump typescript to 5.1`
+- `docs(api): clarify retry backoff behavior`
+
+**Rules:**
+- Imperative mood only: "add", not "added" or "adds"
+- Lowercase after colon, no period at end
+- Scope optional but preferred
+- Breaking changes get `!` before colon: `feat!: remove legacy API`
+- Backlog-only commits use scope `backlog`: `chore(backlog): claim 231`
+
+## Branch Naming
+
+*policy* `git.branch_format`, default:
+
+```
+<type>/<id>-<short-kebab-description>
+```
+
+`<id>` is the backlog-management ID. It lets tooling join branches, PRs, and items without parsing titles.
+
+**Examples:**
+- `feat/231-user-authentication`
+- `fix/244-cache-invalidation-race`
+- `docs/250-api-endpoint-reference`
+- `chore/backlog-sweep-2026-09-03-a1b2c3d` (routine branches carry a run ID instead)
+
+Match the branch type to the commit type. Legacy branches without an ID are allowed only for work predating the backlog claim rule.
+
+## Pull Requests
+
+- Body contains `Closes #<id>` (github-issues backend) or the item ID in the first line (markdown backend).
+- Body sections: Summary, Verification (the merge-readiness rows with pass/fail), Backlog link.
+- Label `needs-human` when the diff touches any *policy* `autonomous.require_human_review_if_touches` path. Such PRs are never merged by an agent.
+- Draft PR as soon as the branch exists when working autonomously. It doubles as a visible claim.
+
+## Versioning
+
+*policy* `versioning.bump`:
+- `release-commit-only` (default): never bump `package.json` or `pyproject.toml` in a feature branch. Releases are cut in their own commit with `CHANGELOG.md`.
+- `per-branch`: bump in the branch per **code-standards**.
+
+## Discipline
+
+- **One logical change per branch.** No "WIP" or "misc" commits on shared branches. Squash or amend first.
+- **Delete branches once merged.**
+- **Never commit to protected branches directly.**
+- **Forbidden without a human present:** force push, rewriting shared history, editing branch protection or rulesets, adding or upgrading a dependency, deleting or skipping a test. Mirrors *policy* `autonomous.forbidden`.
+
+## Worktrees (parallel work only)
+
+Use a worktree only when agents work concurrently on the same repo. Sequential single-agent work uses a plain branch.
+
+Use the project scripts, *policy* `worktrees.up` and `worktrees.down`:
+
+```bash
+scripts/worktree-up.sh <id> <branch>   # creates ../<repo>-<id>, allocates a port block,
+                                       # a DB name per id, writes .env, runs migrations
+cd ../<repo>-<id>                      # commit + push from here
+git push -u origin <branch>
+scripts/worktree-down.sh <id>          # drops DB, removes worktree, git worktree prune
+```
+
+If the scripts do not exist, do not improvise: create a `chore` backlog item for them and run at most one worktree until they are merged. Raw fallback for that single worktree:
+
+```bash
+git worktree add ../<repo>-<id> <branch>
+git worktree remove ../<repo>-<id>     # add --force to discard changes
+git worktree prune
+```
+
+**Rules:** no two worktrees share ports, DB names, or `.env`. Remove the worktree before declaring the task done. Run `git worktree list` to audit stragglers at the end of every run.

package/skills/hatch-workflow/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: hatch-workflow
+description: Workflow for working with hatch based VCC projects. Contains entrypoints for running tests, static analysis and building.
+---
+
+# Hatch command agenda
+
+This file lists the common `hatch` commands you can use in this repository to **test**, **type-check/lint/format**, and **build** artifacts like **wheels**, **docs**, and the **container**.
+
+> Notes:
+>
+> - Commands are shown as you can run them from the repository root.
+> - Some environments are matrix-based (e.g. `hatch-test`); you may see Hatch create env names like `hatch-test.py3.10-highest`.
+
+---
+
+## 1) Testing
+
+### Run all tests (default selection)
+
+```bash
+hatch test
+```
+
+### Run all tests with coverage enabled (as configured)
+
+```bash
+hatch test -c
+```
+
+### Run tests without xdist parallelism (useful for debugging / CI parity)
+
+```bash
+hatch test -c -n0
+```
+
+### Run a specific test file (example)
+
+```bash
+hatch test -c -n0 tests/unittest/test_constraint.py
+```
+
+---
+
+## 2) Static analysis (linting/formatting/docstring lint)
+
+### Lint and format with autofixes
+
+```bash
+hatch fmt
+```
+
+### Docstring lint only
+
+```bash
+hatch run hatch-static-analysis:lint-doc-string
+```
+
+### Lint (check) only
+
+```bash
+hatch fmt --check --linter
+```
+
+### Lint with autofixes
+
+```bash
+hatch fmt --linter
+```
+
+### Format check (no changes)
+
+```bash
+hatch fmt --check --formatter
+```
+
+### Format apply (write changes)
+
+```bash
+hatch fmt --formatter
+```
+
+---
+
+## 3) Type checking (mypy)
+
+### Run mypy (installs any missing stubs automatically)
+
+```bash
+hatch run types:check
+```
+
+### Type-check a subset (example: only `src/vcc`)
+
+```bash
+hatch run types:check src/vcc
+```
+
+---
+
+## 4) Build Python artifacts (wheel / sdist)
+
+### Build both sdist + wheel
+
+```bash
+hatch build
+```
+
+### Clean build (recommended for release artifacts)
+
+```bash
+hatch build -c
+```
+
+### Build only the wheel
+
+```bash
+hatch build -c -t wheel
+```
+
+### Build only the sdist
+
+```bash
+hatch build -c -t sdist
+```
+
+---
+
+## 5) Documentation (Sphinx)
+
+### Generate API docs (sphinx-apidoc) into `docs/code`
+
+```bash
+hatch run docs:gen-api
+```
+
+### Build HTML documentation into `tmp/docs/build/html`
+
+```bash
+hatch run docs:build
+```
+
+### Serve docs with live reload (sphinx-autobuild)
+
+```bash
+hatch run docs:serve
+```