agent-skills

Multi-agent coordination discipline: one-message-then-wait (send complete context, wait for reply before sending again), idle notifications are heartbeats (no action unless extended + blocking + user asked), no polling loops (event-driven only), never fabricate agent responses (wait for real system events), sequential agent spawning (acknowledge between each), and proper shutdown protocol (request, wait, respect rejection). Activate when orchestrating multiple agents, coordinating handoffs between agents, spawning subagents, or building multi-agent workflows. Triggers on: "coordinate agents", "spawn multiple agents", "manage agents", "agent keeps sending messages", "polling loop", "agent idle", "shut down agent", "multi-agent workflow", "agent handoff", "coordinate parallel work", "stop bothering the other agent". Also relevant when an agent is fabricating responses, sending follow-up messages before replies arrive, or reacting to idle notifications unnecessarily.

Architecture Decision Records with a four-phase lifecycle (RESEARCH -> DRAFT -> HOLD -> MERGE). Use this skill whenever the user needs to make a technology choice, choose a database, select a framework, define system boundaries, record architectural decisions, review or evaluate an existing ADR, create or update ARCHITECTURE.md, or inventory decision points for a new project. Triggers on: "choose a database", "architecture decision", "ADR", "which technology should we use", "is this ADR ready to merge", "review this architecture decision", "what decisions do we need to make", "tech stack decision", "define system boundaries", "record this decision". Enforces research-before-writing and explicit merge authorization. NOT for: code review (use code-review), implementation decisions within established patterns, or design system choices (use design-system).

Trigger this skill immediately when the user says "bootstrap" in any form. Also trigger it for any request about initializing a project's workflow, configuring development practices, or setting up a codebase for the first time. Key signals: "bootstrap", "set up workflow", "configure TDD", "generate AGENTS.md", "recommend skills", "onboard to project", "what tools should I use", "greenfield", "just cloned", "new developer joining". Detects the project environment, recommends skills by phase, configures TDD strategy, and generates instruction files. Project-level onboarding -- NOT for writing code, tests, or performing specific dev tasks.

Deterministic CI/CD interaction patterns with structured evidence output. Push-and-wait discipline (one pending run at a time), five-category failure triage (test-failure, lint-failure, build-failure, flaky-test, infra-failure) with classification-specific fix strategies, self-healing for lint/format/infra failures, flaky test detection, and CI_RESULT JSON evidence packets for every run. Use when pushing code to CI, triaging CI failures, waiting for pipeline results, classifying build errors, dealing with flaky tests, or producing CI evidence for quality gates. Triggers on: "CI failed", "push and wait for CI", "triage build failure", "flaky test", "CI pipeline", "build broke", "CI evidence". NOT for: individual test debugging (use debugging-protocol), code review (use code-review).

Three-stage code review protocol covering spec compliance, code quality, and domain integrity. Use this skill whenever the user asks to review code, prepare or check a PR, assess implementation quality, verify code against a spec or acceptance criteria, or audit for security and domain modeling issues. Triggers on: "review this code", "review my PR", "check implementation against spec", "code quality audit", "does this match the requirements", "review for security issues", "check for primitive obsession", "monetary precision review", "review test coverage gaps". Also activates when the user wants structured PASS/FAIL verdicts per requirement, severity-rated findings, or a gated review that blocks on critical issues. NOT for: style/formatting linting, debugging runtime errors, writing new code, or automated CI checks.

Systematic 4-phase debugging: (1) understand the failure by reading the complete error and reproducing it, (2) find working examples to compare against, (3) test one hypothesis at a time with a single change, (4) fix the root cause and verify with tests. Includes the Three Strikes Rule (escalate after 3 failed fix attempts) and the Iron Law (no fixes without investigation). Activate when tests fail unexpectedly, errors occur, behavior is wrong, something that worked before is now broken, or a user reports a bug. Triggers on: "debug", "why is this failing", "test failure", "unexpected error", "bug", "broken", "investigate this error", "fix this bug", "tests are failing", "weird behavior", "something broke", "track down this issue". Also activates when multiple bugs need systematic investigation (one at a time, not batch-fixed). NOT for: writing new tests from scratch (use tdd), or general code review (use code-review).

Collaborative design system creation using Atomic Design methodology with a structured seven-phase process (Philosophy, Tokens, Atoms, Molecules, Organisms, Templates, Assembly). Produces a specification artifact with philosophy traceability, named design tokens, and full component hierarchy. Use when creating a design system, defining a visual language, specifying UI tokens (colors, typography, spacing), building a component catalog, or planning component architecture before implementation. Triggers on: "create a design system", "define design tokens", "component library spec", "visual language", "atoms and molecules", "style guide", "UI philosophy", "component hierarchy". NOT for: implementing components in code (use atomic-design), choosing frameworks (use architecture-decisions).

Use this skill when the user asks about domain modeling, primitive obsession, parse-don't-validate, semantic types, value objects, or making invalid states unrepresentable. Triggers on: "review for domain issues", "primitive obsession", "design domain types", "value object", "newtype wrapper", "semantic type", "make invalid states unrepresentable", "bool-as-state", requests to replace raw strings/ints with proper types, requests to fix swappable parameters, or any code review focusing on type safety and domain integrity. Also activates during TDD domain review phases. NOT for general code review (style, formatting), debugging, database schema design, or design patterns unrelated to domain type modeling.

Set up a full AI ensemble/mob programming team for any software project. Creates agent definition files (.claude/agents/), coordinator instructions (.team/coordinator-instructions.md), project owner constraints (PROJECT.md), team conventions (AGENTS.md), architectural decisions (docs/ARCHITECTURE.md), domain glossary, and supporting docs. Use when: (1) starting a new project and wanting a full expert agent team, (2) the user asks to "set up a team", "create a mob team", "set up ensemble programming", or "create agent profiles", (3) converting an existing project to the driver-reviewer mob model, (4) the user wants AI agents to work as a coordinated product team with retrospectives and consensus-based decisions.

Event modeling facilitation for discovering and designing event-sourced systems using a structured 9-step workflow. Use when modeling domain workflows, designing event-sourced systems, writing Given/When/Then scenarios for commands or views, validating event models, or discussing event sourcing and domain-driven design. Triggers on: "model this workflow", "event model", "event sourcing", "what events do we need", "write GWT scenarios", "Given/When/Then", "validate the event model", "decompose into slices", "map this domain", "brainstorm events". Also activates for discovering domain actors, identifying automations, mapping integrations, or decomposing workflows into vertical slices. NOT for: implementing event store infrastructure, choosing databases, or writing application code.

Structures the human review experience for factory-mode builds with dashboard-style audit trail summaries (slice counts, rework rates, gate failure distribution), PR digests (per merged PR with gate results), retrospective synthesis (recurring rework causes, pair effectiveness, domain hotspots), quality trend tracking (session-over-session comparison), escalation review (rework history with resolve/override/send-back options), and autonomy tuning interface. Use during Phase 3 human review of factory-mode builds or when assessing autonomous build quality. Triggers on: "review the build", "factory review", "audit trail", "quality trends", "escalation review", "PR digest", "autonomy tuning", "rework rate". NOT for: running the pipeline (use pipeline), individual code reviews (use code-review).

Persistent cross-session memory using Memento MCP knowledge graph (mcp__memento__* tools). Recall-before-acting: search memory before starting tasks, on errors, and when receiving corrections. Multi-dimensional search: two queries per recall event (technical topic + process/workflow learnings). Store-after-discovery: persist solutions, conventions, and corrections immediately. Three-step recall: search, open_nodes, traverse relations. WORKING_STATE.md for crash recovery. Self-reminder protocol every 5-10 messages. Activate on task start, errors, corrections, session boundaries, or explicit memory requests. See references/agents-md-setup.md for AGENTS.md integration.

Mutation testing quality gate with scenario coverage enforcement and structured evidence output. Detects project type and runs the right tool (cargo-mutants, Stryker, mutmut, Muzak), analyzes surviving mutants by mutation type (arithmetic, comparison, boolean, return value, statement removal), enforces scenario coverage check before recommending tests, produces MUTATION_RESULT JSON evidence packets, and enforces a 100% kill rate quality gate. Use when running mutation testing, validating test quality, preparing PRs, or analyzing surviving mutants. Triggers on: "run mutation testing", "mutation score", "surviving mutants", "kill rate", "cargo mutants", "stryker", "pre-PR quality check", "are my tests good enough". NOT for: writing tests (use tdd), debugging test failures (use debugging-protocol).

Autonomous build-phase orchestrator with 8-stage per-slice pipeline (decompose, slice readiness review, implement via TDD pairs, three-stage code review, address feedback, mutation testing, push/CI, merge/flag). Manages slice queue (walking skeleton first, dependency ordering), dispatches TDD pairs with capability detection, enforces 5 binary quality gates with 3-cycle rework budgets and human escalation, maintains audit trail, and respects strict controller boundaries (never writes code, delegates all creative work). Supports three autonomy levels (conservative/standard/full). Use when running factory mode, orchestrating build phases, managing slice queues, or coordinating TDD pairs with review gates. Triggers on: "run the pipeline", "factory mode", "build phase", "slice queue", "quality gates", "autonomous build". NOT for: individual TDD (use tdd), standalone code reviews (use code-review), CI-only workflows (use ci-integration).

Structured session analysis and project instruction refinement using a five-type intervention taxonomy (Correction, Repetition, Role Redirect, Frustration Escalation, Workaround) with severity scoring. Refines project instructions (CLAUDE.md, AGENTS.md) with structural language, maintains WORKING_STATE.md for crash recovery, and implements a self-reminder protocol to prevent role drift. Includes advisory-to-structural promotion for recurring gaps. Use after milestones, repeated user corrections, session restarts, crash recovery, every 5 completed tasks, or on request. Triggers on: "reflect on this session", "why do I keep correcting you", "update project instructions", "session retrospective", "crash recovery", "context compaction", "role drift", "analyze my corrections". Also relevant when noticing repeated corrections or resuming after compaction.

Work decomposition, dependency ordering, and status tracking for software tasks. Provides hierarchical decomposition (features into stories into leaf tasks), Slice-to-Task decomposition (walking skeleton first, then acceptance tests before implementation), GWT acceptance criteria on every task, explicit dependency declarations, estimated scope, and a strict lifecycle (Open/Active/Closed with one-at-a-time active task rule). Use when breaking down features, managing work items, tracking dependencies, creating stories or epics, slicing work for incremental delivery, or deciding what to work on next. Triggers on: "decompose this feature", "create tasks", "what should I work on next", "break this into smaller pieces", "walking skeleton", "slice into tasks", "task dependencies". Works with any task tool.

Use this skill whenever the user wants to write code using TDD, test-driven development, or test-first methodology. Triggers on: "/tdd", "let's do TDD", "write a failing test", "red green refactor", "test-first", "start a TDD cycle", or any request to implement a feature by writing tests before code. Adaptive five-step cycle (RED-DOMAIN-GREEN-DOMAIN-COMMIT) that detects harness capabilities and routes to guided (/tdd red|domain|green|commit) or automated (/tdd) mode. NOT for running existing tests, debugging test failures, or reviewing code -- only for the disciplined test-first cycle.

Six-criterion readiness evaluation for development tickets (user stories, feature requests, bug reports). Produces a structured READY / NEARLY READY / NOT READY verdict with specific remediation guidance and before/after examples. Use this skill whenever the user asks to triage, evaluate, assess, review, or check the readiness of a ticket, story, issue, or work item. Triggers on: "is this ticket ready", "triage this ticket", "review this story", "evaluate this issue", "what's wrong with this ticket", "check acceptance criteria", "is this user story well-written", "improve this ticket", "assess ticket readiness", "are these ACs testable", "is this appropriately sliced". Also activates when the user pastes a ticket and asks for feedback, fetches an issue from Jira/Linear/GitHub, or wants to know if a ticket has adequate validation criteria for data models. NOT for: code review (use code-review), sprint planning, project management, or writing tickets from scratch.