@anyberg/agent-conventions 1.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "aanyberg",
+  "description": "Alexander Nyberg's Claude Code plugins for conventions and workflows.",
+  "owner": {
+    "name": "Alexander Nyberg"
+  },
+  "plugins": [
+    {
+      "name": "conventions",
+      "source": ".",
+      "description": "Skills and agents for backlog management, git conventions, code standards, and planning workflows.",
+      "version": "1.0.0"
+    }
+  ],
+  "metadata": {
+    "description": "Alexander Nyberg's Claude Code plugins for conventions and workflows.",
+    "version": "1.0.0"
+  }
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "conventions",
+  "displayName": "Conventions",
+  "description": "Skills and agents for backlog management, git conventions, code standards, and planning workflows.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Alexander Nyberg"
+  }
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "agent-conventions",
+  "version": "1.0.0",
+  "description": "Skills and agents for backlog management, git conventions, code standards, and planning workflows.",
+  "skills": "./skills/"
+}

package/AGENTS.md

@@ -0,0 +1,24 @@
+# Global Configuration
+
+## When to Load Skills
+
+| Trigger | Skill |
+|---------|-------|
+| Listing, creating, claiming, releasing, de-duplicating work items; checking what is in flight; any "add to backlog" or "update status" | `backlog-management` |
+| Creating/managing tasks, checking merge readiness, running autonomously as an agent or subagent | `task-workflow` |
+| Architectural decisions, new services/modules, tech choices | `architecture-planning` |
+| Committing, branching, PRs, worktrees, git operations | `git-conventions` |
+| Reviewing a PR or branch, acting as independent reviewer | `code-review` |
+| Writing/reviewing code, linting | `code-standards` + the language guideline skill |
+| Writing/updating docs, READMEs, changelogs, role/layer docs | `docs-standards` |
+| Auditing code health, prioritising refactors | `tech-debt` |
+
+## Quick Reference
+
+**Policy:** `<root>/.planning/policy.yml` is read before any action that creates items, branches, or PRs. It defines backend, ID scheme, statuses, commit types, branch format, versioning, and autonomous limits. Missing file: `backlog-management`'s `scripts/generate-policy.sh` creates it from best-practice defaults (backend auto-detected) the first time it's needed, and reports what it generated. Never regenerated or overwritten silently after that — edit it directly to change anything.
+**Backlog:** only via `backlog-management`. Backend (`github-issues` or `BACKLOG.md`) resolved from policy, never assumed. Status `backlog → ready → active → in-review → done`, side states `blocked`, `cancelled`. Agents select `ready` + `agent-safe` only; only triage or a human sets those.
+**Task:** `<type>_<short-description>.md` in `.planning/tasks/` with Backlog ID, Status, Goal, Acceptance Criteria, Plan before any code.
+**Commits:** `<type>(<scope>): <imperative>`, types from policy (default `feat`, `fix`, `chore`, `docs`, `refactor`, `test`). Branches `<type>/<id>-<short-kebab>`.
+**Architecture:** record decisions as ADRs in `.planning/architecture.md`. Structural choices are blockers: surface and confirm, or set `blocked` when autonomous.
+**Agent rule:** no branch without a claimed item, no item without evidence, no code without a task file. Surface blockers, do not guess. Never force push, edit branch protection, add a dependency, or delete a test without a human.
+**Migration:** if a project still has `.agents/tasks/`, `.agents/planning/`, `.agents/architecture.md`, or `.agents/backlog.md`, migrate to `.planning/` and root `BACKLOG.md` automatically before proceeding (see `task-workflow` and `backlog-management`).

package/README.md

@@ -0,0 +1,244 @@
+# agent-conventions
+
+A collection of specialized agents, skills, and development guidelines for AI coding assistants.
+
+This repository contains:
+
+- **`skills/` and `agents/`** — The repository root is itself a Claude Code plugin (`conventions`), so these sit at the top level rather than nested under a plugin directory. That is also where the wider agent ecosystem scans for `SKILL.md` files. See [docs/CONSUMER.md](docs/CONSUMER.md) for how a consumer repo loads them via the `aanyberg` marketplace, with no copying into `~/.claude`.
+  - **Agents** — Specialized multi-step task runners for common development workflows (feature planning, refactoring, documentation updates, etc.)
+  - **Skills** — Focused knowledge modules covering code standards, best practices, and workflows across Python, TypeScript, and general development
+- **Instructions** — A single `AGENTS.md` file with project-level guidance that works across all supported tools
+
+These components enhance AI coding assistants by providing domain knowledge, coding conventions, and structured workflows.
+
+## Installation
+
+### Everything, one command
+
+```bash
+# this machine, every project — skills and global instructions
+npx github:aanyberg/agent-conventions -g
+
+# preview without writing anything
+npx github:aanyberg/agent-conventions -g --dry-run
+```
+
+Once the package is on npm the shorter `npx @anyberg/agent-conventions@latest` works identically.
+
+> **Note the spelling.** The npm scope is `@anyberg` (one `a`); the GitHub org and the Claude marketplace are `aanyberg` (two). They are separate namespaces and the handles differ — `github:aanyberg/…` and `conventions@aanyberg` are correct as written. The `github:` form needs nothing published and accepts any ref — `github:aanyberg/agent-conventions#v1.1.0` pins a release.
+
+Run bare, it asks for scope and agents, prints every path it will touch, and defaults to **no**. `-y` skips the prompt but still prints the plan. Nothing global is written without the paths appearing on screen first.
+
+It writes a receipt, so `uninstall` removes exactly what was installed and nothing else:
+
+```bash
+npx github:aanyberg/agent-conventions uninstall -g
+```
+
+**Existing files are never clobbered.** Global instructions are appended inside `<!-- BEGIN/END -->` markers, so your own content survives an install and is restored byte-for-byte by an uninstall. If an instruction path is already a **symlink** — which it will be if you followed the older setup below — the installer refuses it rather than writing through the link into your clone. `--replace-symlinks` converts it, leaving the file it pointed at untouched.
+
+Your project's own `AGENTS.md` is never written. That file is yours.
+
+### Skills — any agent
+
+The skills follow the [Agent Skills specification](https://agentskills.io/specification), so one copy works in every agent that reads it. Install them with the ecosystem's CLI:
+
+```bash
+# this project only
+npx skills add aanyberg/agent-conventions
+
+# every project on this machine
+npx skills add aanyberg/agent-conventions -g
+```
+
+It prompts for scope and agents. To skip the prompts:
+
+```bash
+npx skills add aanyberg/agent-conventions -a codex -a github-copilot -a opencode -y
+```
+
+Agent flags: `claude-code`, `codex`, `github-copilot`, `opencode`, `cursor`, `gemini-cli`, and [70+ others](https://github.com/vercel-labs/skills#supported-agents).
+
+**Only two directories are ever written**, at either scope:
+
+| Path | Read by |
+| --- | --- |
+| `.agents/skills/` (or `~/.agents/skills/`) | Codex, GitHub Copilot, OpenCode, Cursor, Gemini CLI, Cline, Zed, Amp and others — this is the cross-vendor convention |
+| `.claude/skills/` (or `~/.claude/skills/`) | Claude Code, the one holdout — symlinked to the above, not a second copy |
+
+Because Claude Code is a symlink into the same files, there is no duplicate to drift. At project scope, commit `.agents/skills/` and gitignore `.claude/skills/`.
+
+### Native plugin install
+
+Each ecosystem has its own manifest, all pointing at the same top-level [`skills/`](skills):
+
+```bash
+# Codex, Cursor, ChatGPT, Kiro, VS Code — via the Agent Plugins standard
+# (plugin.json at the repo root)
+
+claude plugin marketplace add aanyberg/agent-conventions   # Claude Code
+copilot plugin marketplace add aanyberg/agent-conventions  # GitHub Copilot CLI
+gemini extensions install aanyberg/agent-conventions       # Gemini CLI
+```
+
+Codex discovers the repo through `.codex-plugin/plugin.json`; Copilot CLI reads the same `.claude-plugin/marketplace.json` Claude Code does.
+
+### Skills & agents — Claude Code plugin
+
+The plugin route additionally installs the [`agents/`](agents), which are Claude-specific, and updates through `claude plugin update` rather than re-running an installer:
+
+```bash
+claude plugin marketplace add aanyberg/agent-conventions
+claude plugin install conventions@aanyberg
+```
+
+A consumer repo can commit the marketplace in `.claude/settings.json` so contributors need no per-person install at all — see [docs/CONSUMER.md](docs/CONSUMER.md).
+
+### Global Instructions
+
+`AGENTS.md` is the single source of truth. The filename is the portable part — 30+ tools read a project's `AGENTS.md` directly — but *global* instructions are a different matter: each tool looks in its own config directory, and two of them expect a different filename there. So every tool below needs a link, and what portability buys you is one file to edit rather than three to keep in sync.
+
+> **This step is manual for now.** The symlinks below are the current method; they are being replaced by an installer that appends a marked block instead, so an existing file is never clobbered. Until then, note that a symlink means edits to the target write back into this repository.
+
+Symlink `AGENTS.md` to each tool's expected config path:
+
+**Claude Code**
+```bash
+ln -s /path/to/agent-conventions/AGENTS.md ~/.claude/CLAUDE.md
+```
+
+**GitHub Copilot**
+```bash
+mkdir -p ~/.copilot
+ln -s /path/to/agent-conventions/AGENTS.md ~/.copilot/copilot-instructions.md
+```
+
+**OpenAI Codex CLI**
+```bash
+mkdir -p ~/.codex
+ln -s /path/to/agent-conventions/AGENTS.md ~/.codex/AGENTS.md
+```
+
+Replace `/path/to/agent-conventions` with the absolute path to your local clone, e.g. `/home/<username>/projects/agent-conventions`.
+
+## Removing
+
+Whatever put this on your machine is what takes it off — the routes do not clean up after each other.
+
+| Installed with | Remove with |
+| --- | --- |
+| `npx github:aanyberg/agent-conventions` | `npx github:aanyberg/agent-conventions uninstall -g` (or `-p`) |
+| `npx skills add …` | `npx skills remove -g` |
+| `claude plugin install` | `claude plugin uninstall conventions@aanyberg` |
+| `claude plugin marketplace add` | `claude plugin marketplace remove aanyberg` |
+| `gemini extensions install` | see `gemini extensions --help` |
+
+### What the installer's uninstall removes
+
+It works from the receipt written at install time, so it removes **exactly** what was installed and nothing adjacent:
+
+- every skill directory it created, and the links it made into `.claude/skills/`
+- its block from each instruction file, leaving your own content byte-for-byte as it was — and deleting the file outright only if the installer created it and nothing else is in it
+- the receipt itself
+
+A skill someone else put in the same directory is left alone. That is the point of the receipt: removal is never inferred from what an install *would* have produced.
+
+### `npm uninstall` does not do this
+
+`npm uninstall` removes the package and **nothing the installer wrote**. It cannot — npm removed uninstall lifecycle scripts in v7, on the grounds that a removal has too many possible causes to give a script useful context.
+
+So if you installed the package globally, remove the content first and the package second:
+
+```bash
+npx github:aanyberg/agent-conventions uninstall -g
+npm uninstall -g @anyberg/agent-conventions
+```
+
+The other order strands the files with the tool gone. Recoverable — the receipt is still on disk and `npx` re-fetches — but avoidable.
+
+### By hand
+
+If the receipt is gone, or you would rather see exactly what is there, these are all the paths the installer ever writes. Substitute the project root for `~` if you installed with `-p`:
+
+```bash
+~/.agents/skills/          # the 19 skills — the real files
+~/.claude/skills/          # links into the above
+~/.agent-conventions.json  # the receipt
+```
+
+Instruction files are edited, not created wholesale, so delete only the block between the markers and leave the rest:
+
+```bash
+~/.claude/CLAUDE.md
+~/.copilot/copilot-instructions.md
+~/.codex/AGENTS.md
+~/.gemini/GEMINI.md
+```
+
+Each block is delimited by `<!-- BEGIN aanyberg/agent-conventions -->` and `<!-- END aanyberg/agent-conventions -->`. Anything outside those markers was yours.
+
+## Releasing
+
+Six manifests declare a version. Set them together, never by hand:
+
+```bash
+node scripts/bump-version.mjs 1.1.0
+git commit -am "chore: release 1.1.0"
+git tag v1.1.0 && git push --tags
+```
+
+The tag triggers [`release.yml`](.github/workflows/release.yml), which **re-runs both suites rather than trusting merge-time checks** — an `--admin` merge bypasses required status checks as well as the approval rule, so a publish cannot assume the PR was green. It also verifies the tag matches the manifests, packs the tarball and asserts it contains the skills, agents, `AGENTS.md` and the binary, then installs that exact tarball and runs a full install/uninstall round trip. Only then does it publish.
+
+Publishing uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) over OIDC: no `NPM_TOKEN` is stored anywhere, the credential is short-lived and scoped to this one workflow, and npm attaches a provenance attestation automatically.
+
+### One-time setup
+
+Neither step can be scripted from here — both need an authenticated session:
+
+1. **npm** — publish `1.0.0` manually once (`npm publish --access public`), since a trusted publisher can only be added to a package that exists. Then under the package's *Settings → Trusted publishers*, add: repository `aanyberg/agent-conventions`, workflow `release.yml`, environment `release`.
+2. **GitHub** — create an environment named `release` (*Settings → Environments*). Adding yourself as a required reviewer there puts a human approval in front of every publish, which is worth having for a public registry.
+
+Until step 1 is done, `npx @anyberg/agent-conventions` will not resolve — use the `github:` form above, which needs nothing published. Publishing buys a shorter command, a tarball fetch instead of a clone, and a provenance attestation; it does not add capability.
+
+There is deliberately **no `postinstall` hook**. `npm install` does nothing on its own; the installer is run explicitly.
+
+That is not only a matter of taste. `npm uninstall` removes the package and **nothing the installer wrote** — not the skills, not the instruction blocks, not the receipt — and it cannot, because npm removed uninstall lifecycle scripts in v7 ("there's no clear way to currently give the script enough context to be useful"). An auto-installing `postinstall` would therefore be a one-way door: files written into `$HOME` with no supported mechanism to remove them. The explicit installer plus a receipt is the only arrangement here that fully reverses itself.
+
+See [Removing](#removing) for how to take any of this back off.
+
+## Validation
+
+Every change is gated by a validation suite. It parses the same files Claude Code
+parses at load time — so a failure means the plugin would load wrong — checks each
+skill against the [Agent Skills specification](https://agentskills.io/specification)
+so the single copy stays installable in every other agent, and runs the shipped shell
+scripts end to end in throwaway git repos.
+
+```bash
+uv run --frozen pytest tests   # structure, skills, agents, manifests
+node --test tests-js/           # the installer and the version bump
+```
+
+It takes about two seconds and needs no API access or GitHub auth — `gh` is stubbed.
+`.github/workflows/validate.yml` gates every pull request on Linux, and repeats the
+suite on macOS after merge to `main` as a canary.
+
+What it checks:
+
+| Area | Checks |
+| --- | --- |
+| Release | the version bump sets all six manifests together, refuses a non-semver input without writing, is idempotent, and leaves every other field and the file formatting untouched. A separate test asserts the six currently agree, so drift fails a PR rather than a release |
+| Installer | the CLI runs end to end against a throwaway `HOME`: both scopes, symlink and copy modes, idempotent reinstall, and an uninstall that restores a pre-existing file byte-for-byte and leaves a foreign skill in the same directory alone. The symlink guard has its own tests — the one failure mode here that destroys data rather than annoying someone |
+| Install manifests | the four ecosystem manifests parse, declare the same version, and point at the same `skills/`; `plugin.json` matches the Agent Plugins name grammar and carries no key outside its schema, which sets `additionalProperties: false` so an extra key invalidates the file rather than being ignored |
+| Manifests | `marketplace.json` and `plugin.json` parse, agree on descriptions, use semver, and every declared `source` resolves to a real plugin. Plugin identity comes from the manifest pair, not the directory name — the root plugin is `conventions` while its directory is the repo itself |
+| Skills | frontmatter has `name` and `description`, `name` matches the directory, names are unique, descriptions fit the loader budget, and every key is one the Agent Skills spec permits — `version` is not one of them, it belongs inside `metadata` |
+| Agents | `name` matches the filename and is kebab-case; `tools`, `model`, `effort`, `maxTurns`, and `permissionMode` are present and valid; `plan`-mode agents declare no write tools |
+| References | relative markdown links resolve, shipped scripts are executable with a shebang, and every skill or agent named in prose exists |
+| Policy | `policy.example.yml` parses, has exactly one copy, keeps the `backend: auto` line `generate-policy.sh` substitutes, and contains every key the skills read |
+| Scripts | `detect-backend.sh` and `generate-policy.sh` run against real git repos with a stubbed `gh`: explicit and auto backend resolution, the incomplete-migration guard, idempotent generation, a missing template, and a round trip proving what one writes the other reads back |
+| Shell lint | `shellcheck --severity=warning` over every shipped script, using the binary vendored by `shellcheck-py` so no separate install is needed |
+| Cross-agent portability | the repo ships one copy of each skill, so no skill or agent body may depend on a single vendor: no interpolated `${CLAUDE_*}` variable, no vendor component directory (`.claude/skills/`, `.cursor/rules/`, …), no vendor instruction file (`CLAUDE.md`, `copilot-instructions.md`), and no tool named from one agent's vocabulary. Naming a vendor directory as somewhere *not* to write stays legal — `task-workflow` does exactly that with `~/.claude` and `~/.copilot`. Each rule is pinned to a sample it must catch and a sample it must ignore, so a regex that rots fails loudly instead of passing on everything |
+| Script portability | shipped scripts use no GNU-only regex escape (`\s`, `\d`, `\w`, …) or flag (`grep -P`, bare `sed -i`, `readlink -f`, `date -d`). shellcheck does not parse regex arguments, and a `\s` in `sed -E` silently produced a wrong backend on macOS while passing every Linux run |
+
+Adding a skill or agent needs no test changes — the suite discovers files by glob and
+parametrises per file, so each one fails independently with its own path in the failure.

package/agents/code-reviewer.md

@@ -0,0 +1,36 @@
+---
+name: code-reviewer
+description: Use for a short final review of a completed, significant, or high-risk diff. Prefer this over general-purpose for correctness, regression, security, and test-coverage review. Do not use for implementation or routine low-risk changes that do not justify Opus cost.
+tools: Read, Grep, Glob, Bash
+model: opus
+effort: high
+maxTurns: 12
+permissionMode: default
+color: purple
+---
+
+# Code Reviewer Agent
+
+Review the assigned diff for concrete defects that could cause incorrect behavior, regressions, security problems, data loss, or missing essential coverage.
+
+## Rules
+
+- Remain review-only. Do not edit files or apply fixes.
+- Review the specified diff and only the surrounding code required to validate it.
+- Prioritize behavior and risk over formatting, naming preferences, and speculative redesign.
+- Verify each finding against the code. Do not report hypothetical issues without a plausible trigger and consequence.
+- Account for existing tests and project conventions before claiming coverage is missing.
+- Do not repeat the implementation summary or praise the change.
+- Keep the review short. If there are no material findings, say so directly.
+
+## Response
+
+List findings in descending severity. For each finding include:
+
+- Severity: critical, high, medium, or low.
+- Exact file and line or symbol.
+- Trigger and user-visible or operational consequence.
+- Smallest appropriate fix.
+- Missing test, when applicable.
+
+After the findings, list any residual testing gaps. Do not include non-actionable commentary.

package/agents/docs-change-steward.md

@@ -0,0 +1,71 @@
+---
+description: "Use when changes need to be reflected in documentation, including role docs, layer docs, software version updates, release notes, and changelog maintenance. Trigger phrases: update docs for changes, sync docs, document role changes, document layer changes, track version bump, update changelog, prepare release notes."
+name: docs-change-steward
+argument-hint: "Describe what changed and whether this is a regular update or release preparation."
+tools: Read, Grep, Glob, Bash, Edit, Write
+model: sonnet
+effort: medium
+maxTurns: 20
+permissionMode: default
+color: blue
+---
+You are a specialist agent for documentation synchronization and release traceability.
+Your job is to detect project changes and keep repository documentation current, especially in docs for layers and roles, plus changelog artifacts.
+
+## Scope
+- Keep documentation aligned with implemented changes in code, playbooks, roles, inventory, and configuration files.
+- Prioritize updates in docs folders that describe architecture layers, role behavior, and versioned dependencies.
+- Maintain release-facing change records in changelog artifacts.
+
+## Primary Responsibilities
+1. Change-to-doc impact mapping
+- Review the relevant git diff and changed files.
+- Map each behavioral or version change to affected documentation pages.
+- Ensure role and layer documentation reflects the current behavior and versions.
+
+2. Documentation synchronization
+- Update docs in the appropriate locations, including layer and role docs.
+- Capture version updates explicitly when software/tool versions change.
+- Keep wording factual and consistent with repository terminology.
+
+3. Changelog maintenance
+- Update changelog entries for user-visible or operationally relevant changes.
+- During release preparation, ensure all notable changes are represented and grouped clearly.
+
+## Constraints
+- Do not invent versions, dates, or release details.
+- If a change impact is ambiguous, state assumptions explicitly and ask concise follow-up questions.
+- Keep edits minimal, targeted, and consistent with existing doc style.
+
+## Mandatory Role Doc Layout
+When creating or updating a role document under `docs/roles/*.md`, you must use this exact top-level section order to match repository standards:
+
+1. `## What is this role?`
+2. `## What does this role do?`
+3. `## Configuration`
+4. `## Files and Templates`
+5. `## Other Important Information` (only if needed)
+
+Layout rules:
+- Do not add alternative top-level headings for role docs (for example: "Overview", "Features", "Requirements").
+- Keep the writing style aligned with existing role docs such as `automatic_updates.md` and `qualys.md`.
+- If additional operational or security context exists, place it under `Other Important Information` rather than creating new top-level sections.
+- If no extra context is needed, omit `Other Important Information`.
+- Preserve factual consistency with the actual role implementation.
+- Save the locked software version in their respective tables in the layers docs when applicable.
+
+## Approach
+1. Inspect changed files and categorize impacts: roles, layers, versions, release notes.
+2. Locate the corresponding docs pages and changelog targets.
+3. For role docs, enforce the mandatory role doc layout in this file.
+4. Apply precise edits to reflect current behavior and versions.
+5. Verify consistency between source changes and docs/changelog wording.
+6. Return a concise summary of what was updated and any open questions.
+
+## Output Format
+- Updated files with one-line reason per file
+- Coverage checklist: roles docs, layers docs, version tracking, changelog
+- Open questions or assumptions
+
+For role-doc updates, include an extra line:
+- `Role layout check: pass/fail` (against the mandatory role doc layout)

package/agents/feature-planner.md

@@ -0,0 +1,24 @@
+---
+description: "Use this agent when the user wants to plan a new feature implementation or asks for help designing how to build something.\n\nTrigger phrases include:\n- 'how should I implement this?'\n- 'let's plan this feature'\n- 'help me design the approach for...'\n- 'what's the best way to add...?'\n- 'I need to implement a new feature'\n- 'can you help me think through...?'\n\nExamples:\n- User says 'I want to add authentication to the user management system - how should I approach this?' → invoke this agent to collaboratively develop an implementation plan\n- User asks 'help me plan how to refactor the data layer' → invoke this agent to explore options and reach agreement on approach\n- User says 'I'm about to build a new API endpoint, let's plan it out first' → invoke this agent to discuss design decisions and finalize the plan"
+name: feature-planner
+tools: Read, Grep, Glob, Bash, Write, AskUserQuestion
+model: opus
+effort: high
+maxTurns: 20
+permissionMode: default
+color: orange
+---
+
+# feature-planner instructions
+
+You are a collaborative planning partner, not a decision maker. Work with the user to understand what they want to build, explore the existing codebase for reusable patterns, propose 2–3 concrete implementation approaches with explicit trade-offs, and iterate until they agree on an approach. The user has final say.
+
+Produce a final plan with these sections:
+
+- **FEATURE OVERVIEW**: 1–2 sentences summarizing what will be built
+- **DESIGN DECISIONS**: Key architectural or implementation choices made
+- **STEP-BY-STEP IMPLEMENTATION**: Numbered, actionable steps
+- **DEPENDENCIES & RISKS**: External dependencies, data changes, or potential issues
+- **TESTING APPROACH**: How the feature will be tested
+- **EFFORT ESTIMATE**: Rough complexity (if applicable)
+- **NOTES**: Assumptions, open questions, or future improvements

package/agents/implementation.md

@@ -0,0 +1,35 @@
+---
+name: implementation
+description: Use for a well-scoped feature, bug fix, or refactor after the desired outcome and acceptance criteria are known. Prefer this over general-purpose for writing code. Do not use for open-ended exploration, architecture decisions, or unrelated cleanup.
+tools: Read, Grep, Glob, Bash, Edit, Write
+model: sonnet
+effort: medium
+maxTurns: 30
+permissionMode: default
+color: green
+---
+
+# Implementation Agent
+
+Deliver the smallest complete change that satisfies the assigned acceptance criteria.
+
+## Rules
+
+- Confirm the requested outcome, scope, and acceptance criteria from the task before editing.
+- Inspect only the files and nearby dependencies needed for the change.
+- Preserve existing behavior unless the task explicitly changes it.
+- Keep the diff focused. Do not perform unrelated cleanup, broad renaming, dependency upgrades, or speculative abstractions.
+- Preserve pre-existing working-tree changes and never overwrite work you did not create.
+- Add or update focused tests when behavior changes.
+- Run the narrowest relevant verification after editing.
+- Never commit, push, publish, deploy, or modify remote state unless explicitly instructed.
+- After two failed implementation approaches, stop and report the evidence instead of continuing to churn.
+
+## Response
+
+Return only:
+
+1. What changed and why.
+2. Files changed.
+3. Verification run and its result.
+4. Remaining risks, assumptions, or blockers.

package/agents/refactoring-planner.md

@@ -0,0 +1,38 @@
+---
+description: "Use this agent when the user wants to plan a Python refactoring or improve code structure and organization.\n\nTrigger phrases include:\n- 'help me plan a refactoring'\n- 'how should I refactor this code?'\n- 'let's plan out the refactoring'\n- 'help me improve this code structure'\n- 'what's the best way to reorganize this?'\n- 'I need to refactor this, where do I start?'\n\nExamples:\n- User says 'I want to improve the structure of this module - where should I start?' → invoke this agent to create a refactoring plan\n- User asks 'How can I make this code more maintainable?' → invoke this agent to analyze structure and propose improvements\n- User says 'I'm about to refactor our data models, let's plan this out first' → invoke this agent to discuss approach, type system choices, and phasing\n- User comments 'This class is getting too complex' → invoke this agent to suggest a refactoring strategy with phasing and migration path"
+name: refactoring-planner
+tools: Read, Grep, Glob, Bash, Write, AskUserQuestion
+model: opus
+effort: high
+maxTurns: 20
+permissionMode: default
+color: orange
+---
+
+# refactoring-planner instructions
+
+You create actionable, phased Python refactoring plans that improve readability, maintainability, and type safety while minimising disruption. Ask clarifying questions about scope, constraints, and pain points before proposing anything.
+
+## Type System Decision Framework
+
+Choose the right structure for the domain:
+
+- **Immutable, simple data** → `NamedTuple` or `@dataclass(frozen=True)`
+- **Mutable domain objects with defaults** → `dataclass` with `field(default=...)`
+- **JSON / external data with type safety** → `TypedDict` or Pydantic model
+- **Complex validation, serialization, API contracts** → Pydantic `BaseModel`
+- **Composition over inheritance** — prefer composition for complex types; use inheritance sparingly
+- **Backward compatibility** — if removing or renaming fields, plan a transition period
+
+## Output Format
+
+Deliver the refactoring plan with these sections:
+
+1. **Executive Summary**: 2–3 sentences on goals and expected benefits
+2. **Current State Analysis**: Identified pain points and why change is needed
+3. **Proposed Improvements**: New/updated types, organizational changes, design patterns
+4. **Phased Refactoring Plan**: Table with phase name, specific changes, affected files, effort (S/M/L), dependencies, validation steps
+5. **Code Examples**: Before/after for key transformations
+6. **Risk Assessment**: Potential risks and mitigations
+7. **Success Criteria**: Clear metrics to evaluate the outcome
+8. **Migration Path**: How existing callers should adapt if breaking changes are introduced

package/agents/repo-search.md

@@ -0,0 +1,32 @@
+---
+name: repo-search
+description: "Use for bounded, read-only repository discovery: locating code, tracing references, identifying ownership, or answering a specific codebase question. Prefer this over general-purpose for search and exploration. Do not use for edits, implementation, or broad open-ended analysis."
+tools: Read, Grep, Glob
+model: haiku
+effort: low
+maxTurns: 12
+permissionMode: plan
+color: cyan
+---
+
+# Repository Search Agent
+
+Find the minimum evidence needed to answer the assigned repository question.
+
+## Rules
+
+- Remain read-only. Never create, edit, rename, or delete files.
+- Stay within the requested scope. Do not inventory the entire repository unless explicitly asked.
+- Search narrowly, follow only relevant references, and stop once the evidence supports a clear answer.
+- Prefer symbols, paths, and focused excerpts over reading whole large files.
+- Do not repeat large file contents or speculate beyond the evidence.
+- If the request actually requires implementation, return the relevant evidence and recommend handing it to `implementation`.
+
+## Response
+
+Return only:
+
+1. A concise answer to the assigned question.
+2. Evidence with file paths, symbols, and line numbers when available.
+3. Important unknowns or conflicts.
+4. The smallest sensible next action.

package/agents/test-runner.md

@@ -0,0 +1,34 @@
+---
+name: test-runner
+description: Use to run a bounded test, lint, type-check, build, or formatting verification and summarize failures. Prefer this over general-purpose for command execution and log triage. Do not use to edit source files or redesign code.
+tools: Read, Grep, Glob, Bash
+model: haiku
+effort: low
+maxTurns: 15
+permissionMode: default
+color: yellow
+---
+
+# Test Runner Agent
+
+Run the smallest verification that answers the assigned question and report actionable results.
+
+## Rules
+
+- Do not edit source, configuration, tests, snapshots, or generated artifacts intentionally.
+- Do not install or upgrade dependencies unless the task explicitly authorizes it.
+- Start with the narrowest relevant check. Expand only when it passes or broader verification is requested.
+- Preserve pre-existing working-tree changes. Never clean, reset, restore, or delete user files.
+- Distinguish product failures from environment, dependency, permission, and flaky-test failures.
+- Do not dump full logs. Quote only the lines needed to identify the failure.
+- After two materially different attempts without new evidence, stop and report the blocker.
+
+## Response
+
+Return only:
+
+1. Commands run.
+2. Pass, fail, or blocked status for each command.
+3. The first actionable failure and its likely location.
+4. Any working-tree side effects created by the commands.
+5. The smallest recommended next action.