.agents

Split one oversized Markdown reference document into a progressive-disclosure tree - a curated index page plus one file per top-level section - without altering a byte of prose. Use when a single doc has grown too large to read whole (a multi-hundred-line architecture spec, PRD, or reference), when asked to split, shard, or break up a doc into sections, when converting a monolith-plus-stale-digest pair into an index-plus-sections layout, or when a digest has drifted from the doc it summarizes. Covers header-tiling extraction, concat-vs-original byte verification, per-link relative-depth repair with a grep sweep, deriving the index fresh from each section's current content in the repo's index style, deleting a now-redundant digest, and reconciling context-file pointers. Do NOT use for authoring new documentation content (that is make-docs), for choosing a Diataxis type, for splitting source code, or for editing prose during the move.

Convert a technical specification, tracker reference, or feature request into a rigorous, atomic, dependency-ordered implementation plan the coder agent executes step-by-step. Use whenever the output is a Markdown plan file under `.plans/`, or when asked to plan, break down work, sequence implementation phases, turn a spec into actionable tasks, write a roadmap, decompose a feature into phases, or convert a `Spec-*.md` into a `Plan-*.md` artifact. Defines phase structure, output-style rules (WHAT not HOW, signatures only, no language-tagged code fences, symbol references over file paths), step anatomy (atomic, file-explicit, verify-gated), per-phase constraint checks, the philosophy-checklist self-gate, and a validation script. Do NOT use for writing the specification itself, writing implementation code, writing tests, code review, or evaluating an existing plan.

Write technical specifications from feature requests, prompts, or tracker references. Use when asked to specify, architect, design, write a spec, define requirements, create a technical specification, analyze a feature request, or produce a specification document. Also use when given a tracker reference (Jira, GitHub issue, Linear, Asana, etc.) and a specification is the expected output. Do NOT use for code review, implementation, implementation planning, or reviewing existing specs. Produces structured specification documents the implementer can build from without further clarification.

Use when writing Jira issue descriptions, comments, or work logs. Also use when converting Markdown to Jira wiki markup, when the user says 'format for Jira', 'Jira markup', 'wiki notation', or asks to create, update, or validate Jira ticket content. Handles bug report and feature request templates. Do NOT use for Jira API operations, JQL queries, or workflow transitions.

Create, edit, search, transition, close, and triage Jira tickets via the Atlassian MCP. Use when asked to file a bug, request a feature, create a task, log a defect, search the backlog, triage findings into the tracker, edit ticket fields, transition status, or manage Jira work items. Also use when the user says 'create a Jira issue', 'file a bug', 'open a ticket', 'add to backlog', 'search Jira', 'close ticket', 'move to Done', or names any Jira issue key (e.g. 'PROJ-123'). Handles type discovery, parent linking, label assignment, duplicate detection via JQL, status transitions, and issue-link creation. Defers all field-content formatting to the `jira-syntax` skill. Do NOT use for pull requests, changelog entries, non-Jira trackers (GitHub Issues, Linear, GitLab), or managing local TODO.md.

Explain technical concepts, mechanisms, and systems to a technically fluent reader who is unfamiliar with the specific topic. Use when asked to explain how something works, walk through an algorithm or protocol, write a deep-dive or onboarding article, answer 'what is X', 'why does X behave this way', 'how does X work', 'break down X', or when synthesising findings from research into a written explanation. Builds understanding progressively along the reader's 'aha path' - opens with the why, bridges to adjacent knowledge, introduces one concept at a time, traces mechanics through worked examples, closes with tradeoffs and a runnable experiment. Do NOT use for end-user documentation aimed at non-technical audiences, marketing copy, code review, reference-style API documentation, or commit messages.

Investigate a technical question with a detective's discipline - gathering evidence from primary sources, cross-referencing independent confirmations, and never accepting the first plausible answer. Use when asked to investigate, research, fact-check, verify, deep-dive, or 'find out the truth' about a technology, claim, system, or behaviour. Also use before any explanation of a real-world system, library, or protocol that depends on external facts. Establishes source priority, scales effort to question complexity, triangulates every implementation claim across at least two independent sources, reports conflicts between sources, and refuses to cite training data as evidence. Do NOT use for opinion questions, code generation independent of external facts, internal refactoring, or trivial lookups the user could do themselves.

Create, update, and validate Architecture Decision Records (ADRs) following MADR 4.0 format. Use when the user mentions ADR, architecture decision, decision record, or asks to document a technical decision. Also use when creating new files in docs/decisions/. Handles numbering, frontmatter, section structure, and README index updates. Do NOT use for general documentation or non-architectural decisions.

Create, edit, search, close, and triage GitHub Issues via the gh CLI. Use when asked to file a bug, request a feature, create a task, report a problem, search the backlog, triage issues, or manage the issue tracker. Also use when the user says 'create an issue', 'file a bug', 'open a ticket', 'add to backlog', 'search issues', 'close issue', or mentions GitHub Issues in any task-management context. Handles label/milestone assignment, duplicate detection, and project board integration. Do NOT use for pull requests, changelog entries, or non-GitHub trackers (Jira, Linear, GitLab) or managing TODO.md file.

Use when creating, improving, comparing, evaluating, reviewing or packaging Agent Skills following the agentskills.io specification. Also use when deciding whether a skill is the right solution vs MCP servers, Claude Rules Files, CLAUDE.md or AGENTS.md. Handles SKILL.md authoring, frontmatter optimization, description writing, progressive disclosure, platform targeting, invocation control, vendor-specific extensions, and distribution.

Resolve reviewer comments on a pull request or pasted feedback using a six-step evidence-grounded protocol. Use when asked to resolve review feedback, address reviewer comments, process PR comments, triage review feedback, apply review suggestions, handle code review feedback, decide which review comments to accept or reject, or babysit a PR through its review lifecycle. The protocol verifies every library claim with Context7, classifies each comment across seven categories, applies changes surgically or defers them to the project's issue tracker, and emits the summary directly in the chat response for the human operator (never to a file). The skill NEVER posts replies, reactions, or messages back to the reviewer. Do NOT use for authoring a new code review, for security scans, or for opening a new PR.

Conduct a principal-level architecture review of a system, specification, diagram, or set of design decisions. Use when asked to review an architecture, evaluate a design, assess coupling/cohesion, check for anti-patterns, audit system boundaries, or produce an Architecture Review Board (ARB) style verdict. Also use when someone says 'review this architecture', 'is this design sound', 'what's wrong with this topology', 'evaluate these tradeoffs', or 'audit this system'. Produces a structured verdict organized around critical risks, significant concerns, observations, strengths, and open questions, grounded in evidence from the codebase and cited against established methodology (ATAM, ISO/IEC 25010, documented anti-pattern catalogues). Do NOT use for line-by-line code review, spec-vs-implementation verification, or PR-level correctness checks.

Architectural review of a specification or design document, performed before implementation begins. Use whenever a spec or design proposal is in scope and the user asks any quality question — even when not phrased explicitly: 'review this spec', 'evaluate this design', 'is this spec implementable', 'is this ready to build', 'check this architecture proposal', 'review the design for feature X', 'is this design sound', 'what's missing from this spec'. Also triggers when a file under `.specs/` is being evaluated without an existing implementation. Do NOT use for verifying an existing implementation against a spec, reviewing a PR or implementation changes, reviewing an existing system's architecture, or security review.

Forensic audit of an implementation against its authoritative specification. Use whenever a specification document and an implementation are both in scope and the user asks any conformance question - even when not phrased explicitly: 'does this code match the spec', 'verify this implementation', 'check spec conformance', 'audit compliance between design and code', 'is the implementation faithful', 'verify spec coverage', 'audit against requirements', 'spec-vs-code'. Also triggers when a file path under `.specs/` is mentioned alongside an implementation. Do NOT use for general code review, specification design review before implementation begins, security review, or architecture review without a spec document.

Review implementation changes for a given task against architectural standards. Use when reviewing a PR, evaluating recently committed code, assessing whether implementation changes are correct and architecturally sound, or when asked to 'review my changes', 'check this implementation', 'review what I built', 'is this PR ready', or 'audit recent commits'. Accepts a task description, task tracker URL, or issue shorthand (owner/repo#123, #123) as input. Produces a structured review with severity-rated findings, code evidence, and a verdict (Block / Request changes / Approve with notes / Approve). Saves the review to .reviews/Review-impl-{slug}.md. Do NOT use for specification review or spec-vs-implementation verification.

Detect when a missing Agent Skill would have made the current task faster or more reliable, then scaffold a candidate SKILL.md for user review. Use after a non-trivial task when one of these signals fires: the same procedure repeated 3+ times, error recovery required inventing a workflow, the user corrected the approach (not the answer), the agent realized mid-task that a playbook did not exist, or 5+ tool calls produced what should have taken 1-2. Detects which `.{vendor}/skills/` directories actually exist on the host (project and home), reads every existing SKILL.md across them before proposing, and never duplicates. Writes candidates into the project's preferred .{vendor}/skills/{name} directory — .agents/skills/ by default — never the home folder. Do NOT use for first-attempt failures, one-off questions, fact gaps that belong in research, or style gaps that belong in rules files.

Produce structured architectural comparison documents that evaluate two tools, technologies, or solutions against weighted criteria. Use when asked to compare tools, evaluate alternatives, write a technology assessment, create a build-vs-buy analysis, or produce a recommendation report. Also use when someone says 'which should we use', 'should we adopt X or keep Y', 'compare X vs Y', 'evaluate X against Y', or 'is X better than Y'. Handles evaluation framework design, weighted scoring, cost analysis, risk assessment, gap analysis, and actionable recommendations with reversal conditions.

Create or validate project context files (AGENTS.md, CLAUDE.md, GEMINI.md). Use when bootstrapping a new project, initializing agent configuration, writing a context file, or when asked to create, review, audit, or validate an existing context file. Handles codebase archaeology, user interviews, golden-rule validation, and platform-specific formatting. Do NOT use for creating Agent Skills, rules or .instructions.md files.

Use when asked to update the changelog, document version changes, prepare a release, or add entries for recent work. Handles CHANGELOG.md updates following Keep a Changelog format and Semantic Versioning. Do NOT use for committing or creating release notes outside CHANGELOG.md.

Use when asked to create a pull request, open a PR, or submit changes for review. Handles branch verification, change analysis, title and description generation, and gh pr create. Do NOT use for committing, pushing without PR, or reviewing existing PRs

Read, update, validate, and report on the project roadmap (TODO.md). Use when asked to add tasks, mark tasks complete, check roadmap status, find what to work on next, triage deferred items into the roadmap, validate TODO.md format, reorder or renumber tasks, or edit milestone descriptions. Also use when the user mentions 'roadmap', 'TODO', 'backlog', 'milestone', 'task list', or asks 'what's next'. Do NOT use for architecture decisions, for changelog entries, for creating implementation plans from specs or managing Issue Trackers (Jira, GitHub, Linear, etc.).

Run a Snyk SAST + SCA security audit on the repository, remediate findings that pass the project's verification gates, and write a prioritized report to .audit/. Optional scope argument: all (default), code, deps, or changed.

Use when asked to commit, save, or persist changes to Git. Handles atomic commits, branch safety, Conventional Commits format, and project style matching. Do NOT use for pushing, creating PRs, or branch management beyond safety checks.

Write, review, and run TypeScript/React tests for this Next.js 16 App Router project. Use whenever writing or modifying *.test.ts or *.test.tsx files, adding test coverage to components, hooks, Server Actions, or utilities, setting up Vitest configuration, or asked about testing strategy. Covers Vitest (the project's test runner, not Jest), React Testing Library v16, accessibility-first queries, user-event for interactions, AAA structure, parameterized tests with describe.each and it.each, Prisma mock patterns, next/navigation and next/headers mocking, and the RSC boundary testing strategy. Do NOT use for Playwright end-to-end tests or performance benchmarks.

Write, review, and improve Go test code for this project. Use whenever generating, reviewing, or modifying Go tests - including when invoked by the Tester agent, the /test prompt, or any test-related request. Covers table-driven tests, subtests, t.Parallel(), test helpers with t.Helper(), error assertions via errors.As/errors.Is, fixture loading from testdata/, httptest servers, env-gated integration tests, mock/fake/spy patterns, and adapter conformance. Do NOT use for benchmarks or performance profiling.

Create, edit, and validate technical documentation using the Diataxis framework. Use when writing tutorials, how-to guides, reference docs, or explanations. Use when reviewing or auditing existing documentation for structural correctness. Use when deciding what type of document to write. Also use when the user mentions Diataxis, documentation quality, documentation types, or asks to write 'deep dive' articles, onboarding guides, API docs, or architectural explanations. Do NOT use for code comments, commit messages, changelogs, or README generation.