AI Agent & Automation Workflows

Specialized skill for generating and managing Architecture Decision Records (ADRs). Supports Nygard, MADR, and custom templates with auto-numbering, linking, and status management.

Field reference for Claude Code and GitHub Copilot CLI hook contracts. Covers hook locations, events, matchers, payloads, decisions, exit codes, timeouts, plugin roots, and cloud limits with official URLs and versioned probes. Use for harness contract, copilot cli hook behavior, hook payload format, stale plugin root, Errno 2 dispatch.py, or before changing cross-harness hooks. Do NOT use to run the porting campaign (use ai-agents-portability-campaign).

Load-bearing design decisions for this repo as a contract you check before changing anything. Covers the asymmetric generation seam, source-of-truth per tree, hook runtime failure policy, memory tiers, plugin surfaces, invariants, and known-weak points. Use when you say which tree is canonical, architecture contract, why is this designed this way. Do NOT use for operating the build pipeline (use ai-agents-generation-and-release) or CI triage (use ai-agents-debugging-playbook).

Runbook to recreate the ai-agents dev environment from scratch and survive its traps, including the uv-pinned Python 3.14.6, git hooks install, MCP layer setup, stale CONTRIBUTING.md commands, PEP 668, and the LSP read gate. Use when you say set up this repo, bootstrap the environment, fresh clone setup, or you hit ModuleNotFoundError yaml. Do NOT use for the generation pipeline (use ai-agents-generation-and-release) or CI gate evidence rules (use ai-agents-validation-and-qa).

Change control for this repo. Classify a change (docs-only, investigation-only, code, plugin content, hook, workflow, ADR governance), map each class to the gates it triggers, and hold the non-negotiables with the incident behind each rule. Use when you say classify this change, what gates does this change trigger, which rules are non-negotiable. Do NOT use for producing test evidence (use ai-agents-validation-and-qa) or incident history (use ai-agents-failure-archaeology).

Catalog of every configuration axis in this repo, env vars, commit markers, frontmatter keys, QA skip verdicts, and escape hatches, each with its enforcement point and abuse story, plus the checklist for adding a new flag safely. Use when you say what does a skip flag do, list escape hatches, can I skip this gate, add a config flag. Do NOT use for hook runtime behavior (use agent-harness-reference) or change gating policy (use ai-agents-change-control).

Symptom-to-triage playbook for this repo's recurring failures. Blocked pushes, drift gate reds, plugin bump reds, coverage pin trips, hook exit 143, session NONCOMPLIANT. Maps each symptom to a first command, discriminating experiment, fix path, and trap. Use when you say triage this failure, why is my push blocked, debug this CI red. Do NOT use for incident history (use ai-agents-failure-archaeology) or measurement tools (use ai-agents-diagnostics-toolkit).

Catalog of this repo's measurement instruments, each with command, current baseline, and interpretation guide. Covers skill size and description budgets, orphan-ref and golden-principles scans, drift gates as signals, guard telemetry and maturity tiers, coverage pins, and the eval harness. Use when you say measure this, read the drift signal, check skill budgets, guard maturity report. Do NOT use to fix what you measure (use ai-agents-debugging-playbook) or for evidence standards (use ai-agents-validation-and-qa).

Runbook for this repo's documents of record. Session logs, ADRs, retrospectives, Serena memories, per-issue handoffs, plus the templates, validators, naming rules, and house prose style that bind them. Use when you say write the session log, create an ADR, fill the retro, save this to memory, which document of record. Do NOT use for authoring skills (use SkillForge) or research write-ups (use ai-agents-research-methodology).

Prove-it methods for this repo. Six recipes for runtime-contract probes, guard and threshold calibration, eval A/B, docs-vs-reality audits, reproduce-on-main CI triage, and negative-control test design, each with a worked example from repo history. Use when you say probe the runtime contract, calibrate this guard, prove it empirically. Do NOT use for the portability battle plan (use ai-agents-portability-campaign) or evidence standards (use ai-agents-validation-and-qa).

Verify external, vendor, and third-party claims (numbers, attributions, structure) against authoritative primary sources before they land in a repo artifact or external deliverable. Covers stake-holding sources, round-number tells, citation-chain drift, and the walk-the-gate-or-file-conservative discipline. Use when you say verify an external claim, check a vendor number, is this stat real, validate a third-party citation. Do NOT use for running an experiment (use ai-agents-research-methodology) or command-injection scanning (use security-scan).

The chronicle of this repo's settled battles. Maps each major incident to symptom, root cause, evidence path, and the artifact that fixed it, so nobody re-fights a decided question. Use when you say has this failed before, why does this rule exist, failure archaeology, what happened with issue 2205. Do NOT use for triaging a live failure (use ai-agents-debugging-playbook) or for extracting learnings from the current session (use retrospective).

Operate the ai-agents generation and release machinery, covering the seven buildall.py generators, generateagents.py, syncpluginlib.py, the drift gates, three plugin.json semver bumps, and the npm publish path. Use when you say regenerate the mirrors, run the drift checks, bump the plugin version, release the npm cli. Do NOT use for environment setup (use ai-agents-build-and-env) or architecture rationale (use ai-agents-architecture-contract).

Execute cross-harness hook changes for Claude Code and GitHub Copilot CLI using the settled official contract, versioned probes, generators, and runtime tests. Use for run the portability campaign, port hooks to a new harness, copilot hook timeout regression, or new copilot cli release, recheck the contract. Do NOT use for fact lookup alone (use agent-harness-reference).

Three ranked open research programs for this repo, each with honest current-state evidence, first concrete steps, and a falsifiable milestone. Verified governance (ADR-069, proposed), cross-harness abstraction (ADR-072 and ADR-068, proposed), and the self-improving loop (issue 1345). Use when you say research frontier, open problems, what should we research next. Do NOT use for how to run an experiment here (use ai-agents-research-methodology).

What counts as evidence in ai-agents and how to produce it. Covers the TESTING-RIGOR pos+neg+edge bar, test layout and collection reality, coverage proof commands, runtime-contract tests with negative controls, and ADR-034 QA skip semantics at session end. Use when you say what counts as evidence, how do I test this change, run skill tests, can I skip QA. Do NOT use for CI failure triage (use ai-agents-debugging-playbook) or measurement tooling (use ai-agents-diagnostics-toolkit).

Identify code ownership before modifying validators or linters. Checks file headers for provenance indicators, reviews documentation, and determines provenance as UPSTREAM, LOCAL, VENDOR, or UNKNOWN. Prevents accidental modification of upstream tools.

Detect and stop manufactured work after a deliverable appears done. Use when a worker has produced a plan, issue, PR, backlog item, research artifact, or follow-up task and you need to verify it was demanded by a real user, acceptance criterion, or blocked decision instead of reward-seeking activity.

Strategic framework for evaluating build, buy, partner, or defer decisions with four-phase process, tiered TCO analysis, and integration with decision quality tools. Use for strategic build/buy/partner/defer with TCO. Do NOT use for "is there an existing library for this" (use programming-advisor).

Investigate historical context of existing code, patterns, or constraints before proposing changes. Automates git archaeology, PR/ADR search, and dependency analysis to prevent removing structures without understanding their purpose. Use when you ask "why does this code/constraint exist", "is it safe to remove this". Do NOT use for forward-risk analysis (use pre-mortem).

Assess code maintainability through 5 foundational qualities (cohesion, coupling, encapsulation, testability, non-redundancy) with quantifiable scoring rubrics. Works at method/class/module levels across multiple languages. Produces markdown reports with remediation guidance. Use when you ask to "assess maintainability", "score cohesion/coupling/testability" on specific code. Do NOT use for a full pre-merge review (use review) or repo-wide domain grading (use quality-grades).

Gather comprehensive context from Forgetful Memory, Context7 docs, DeepWiki, and web sources before planning or implementation. Delegates to the context-retrieval subagent to search across all knowledge tiers and returns a focused summary with a parseable CONTEXTLOADED marker for downstream skip detection. Use when you say "gather context before planning", "what do we know before I start". Do NOT use for compressing or placing skill text (use context-optimizer).

Use when setting up new development environment or troubleshooting MCP connectivity. Configures Context Hub dependencies including Forgetful MCP server and plugin prerequisites.

Format and structure data files for optimal Claude reasoning and extraction. Use when: (1) Preparing documents/data for Claude analysis, (2) User asks to 'optimize context' or 'format for Claude', (3) Structuring multi-document corpora, (4) Improving LLM retrieval/reasoning over files, (5) Converting data between formats for Claude consumption, (6) User mentions 'lost in the middle' or context window issues. Supports XML, JSON, YAML, CSV, and markdown.