rjmurillo/project-toolkit-delivery

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 (in the ai-agents repository, use ai-agents-portability-campaign).

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 in the ai-agents repository) or command-injection scanning (use security-scan).

Systematic multi-step codebase analysis producing prioritized findings with file-line evidence. Covers architecture reviews, security assessments, and code quality evaluations through guided exploration, investigation planning, and synthesis. Use when you say "analyze this codebase", "run security assessment", "architecture review of this system", "find code smells", or "review code quality" across multiple files. Do NOT use for single-file maintainability scoring (use code-qualities-assessment) or CWE-78 injection pattern scanning (use security-scan).

Write API docs around a developer use case, with executed examples and failure recovery. Use when you say document this API or write the API guide. Do NOT use to verify doc claims (use doc-accuracy) or design the API.

Cross-model benchmark. Runs one prompt or skill through Claude, GPT (Codex CLI), and Gemini side by side and compares latency, tokens, cost, tool calls, and optionally output quality via an Anthropic-API judge. Answers "which model is actually best for this skill?" with data. Use when you say "benchmark models", "compare models", "which model is best for X", "cross-model comparison", or "model shootout". Do NOT use to measure web page performance.

Implement a planned change in thin vertical slices, test-first, with atomic commits and four mandatory exit gates. Use when you say build this, implement this slice, or write the code for this task, and run it after plan. Do NOT use to decide what to build (use spec) or to sequence the work (use plan), and do NOT use to review a finished diff (use review).

Design and document chaos engineering experiments. Guide steady state baseline, hypothesis formation, failure injection plans, and results analysis. Use when you say "design a chaos experiment", "plan a game day", "failure injection", "test resilience", or "chaos engineering". Do NOT use for security threat analysis (use threat-modeling) or pre-launch project risk identification (use pre-mortem).

Assess maintainability of code through 5 foundational qualities (cohesion, coupling, encapsulation, testability, non-redundancy) with quantifiable scoring rubrics. assess.py scores source code only; rules, skills, and agents are assessed manually against the same qualities per references/executable-nl-artifacts.md. 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).

Execute CodeQL security scans with language detection, database caching, and SARIF output. Use when performing static security analysis on Python or GitHub Actions code.

Prove blast radius and recovery before a change that deletes, overwrites, drops, or revokes state. Scans for destructive sinks, traces callers and flags, previews scope without mutating, and blocks on unknown scope, bad cardinality, or no rollback. Use when you say is this delete safe or blast radius. Do NOT use for read-only changes or security review (use security-scan).

Multi-phase documentation verification treating code as source of truth. Use when you say "check documentation accuracy", "verify code examples compile", "audit docs vs code", "check doc consistency", or "run doc-accuracy". Use for pre-release doc audits and checking behavioral claims. Do NOT use for broad codebase analysis (use analyze) or fixing markdown fence syntax (use fix-markdown-fences).

Evidence-based developer experience audit. Discovers the target, tests onboarding and setup flows, evaluates API/CLI ergonomics, error messages, documentation, upgrade paths, developer environment, community health, and DX measurement practices. Produces a scorecard where every score cites evidence labeled TESTED, PARTIAL, or INFERRED. Measures Time-to-Hello-World when the target supports it. Compares against a prior dx-review result when one exists (boomerang). Use when asked to "run a DX audit", "test the developer experience", "measure onboarding friction", "DX scorecard", or "evaluate developer ergonomics".

Manage execution plans as versioned artifacts with progress tracking and decision logs. Use when you say "create execution plan", "update plan progress", "log decision", "complete plan", or "abandon plan". Do NOT use to break work into milestones (use plan) or to execute an approved plan file through delegation (use planner).

Repair malformed markdown code fence closings. Use when you say "fix markdown fences", "repair code block closings", "markdown rendering broken", "code blocks bleeding into content", or "validate markdown code blocks" on any .md file. Do NOT use for documentation accuracy checks or verifying code examples (use doc-accuracy).

Advanced Git workflows including rebasing, cherry-picking, bisect, worktrees, and reflog. Use when managing complex Git histories, collaborating on feature branches, or recovering from repository issues. Use when you say "rebase my branch", "cherry-pick a commit", "find the breaking commit", "recover lost commits", or "triage stale worktrees".

Execute GitHub operations (PRs, issues, milestones, labels, comments, merges) using Python scripts with structured output and error handling. Use when working with pull requests, issues, review comments, CI checks, or milestones instead of raw gh. Use when you say "create a PR", "add label to issue", or "check CI status". Do NOT use to read a pasted github.com URL (use github-url-intercept).

BLOCKING INTERCEPT: When ANY github.com URL appears in user input, STOP and use this skill. Never fetch GitHub HTML pages directly - they are 5-10MB and will exhaust your context window. This skill routes URLs to efficient API calls (1-50KB). Triggers on: gist.github.com, gist.githubusercontent.com, pull/, issues/, blob/, tree/, commit/, compare/. Use when you paste a GitHub URL, say "analyze this PR", "look at this issue", or "what does this commit do". Do NOT use for creating PRs, posting comments, or adding labels (use github instead).

Scan repository for golden principle violations with agent-readable remediation. Enforces GP-001 through GP-008 from .agents/governance/golden-principles.md. Use when auditing compliance, preparing PRs, or running garbage collection scans.

Resolve merge conflicts by analyzing git history and commit intent. Handles PR conflicts, branch conflicts, and session file conflicts with automated resolution for known patterns. Use when you say "resolve merge conflicts", "fix conflicts on this branch", "PR has conflicts with main", "can't merge due to conflicts", or "resolve PR conflicts". Do NOT use for rebasing, cherry-picking, or complex history rewrites (use git-advanced-workflows).

Collect agent usage metrics from git history and generate health reports. Use when measuring agent adoption, reviewing system health, or producing periodic dashboards. Collects Invocation Rate, Coverage, Infrastructure Review, and Usage Distribution. Use when you say "collect agent metrics", "generate metrics dashboard", or "weekly metrics report".

Use when you say query agent logs, find slow tool calls, show agent errors, or what to log. Query and analyze agent JSONL event logs for debugging, performance analysis, and decision tracing.

Detect references to skills and scripts in structured artifacts (specs, ADRs, eval fixtures, plugin manifests, skill descriptions) that do not match working-tree state. Run as a /build Mandatory Exit Gate to block orphan refs pre-commit instead of paying iteration rounds in /pr-quality:all post-PR. Use when you say "scan for orphan refs", "validate orphan references", or "check skill catalog drift".

Discovers, triggers, and monitors Azure DevOps pipelines (PR, Buddy Build, Buddy Release) for the current repo and branch. Auto-diagnoses failures from build logs, applies fixes, commits, pushes, and re-triggers until all pipelines pass or max retries reached. Validates PR existence and description completeness. Invoke explicitly; Azure DevOps only, not for GitHub PRs.

Decompose a spec into milestones and atomic tasks with dependency ordering, risk register, and complexity sizing. Use when you say plan how to build this, break this into milestones, or decompose this spec, and run it after spec. Do NOT use to decide what to build (use spec), to write the code (use build), or to run or resume an approved plan file through script-driven delegation (use planner).

Fix PRs autonomously. Triage open PRs by tier, address thread feedback, fix CI failures, and enable auto-merge when the 4-condition Ready-to-Merge gate passes. Use when you say pr-autofix, autofix this pr, or monitor open prs. Do NOT use to answer review comments interactively on one PR (use pr-review), and do NOT use to run the six quality axes over your working changes (use pr-quality-all).

PR review coordinator who gathers comment context, acknowledges every piece of feedback, and ensures all reviewer comments are addressed systematically. Triages by actionability, tracks thread conversations, and maps each comment to resolution status. Use when you say "respond to PR comments", "address review feedback on PR 123", "handle PR review comments", "fix PR review issues", or "reply to reviewer". Do NOT use for a single-comment reply with a known response (use post_pr_comment_reply.py directly), for a full pre-merge code review (use review), or to run the local quality gates before pushing (use pr-quality-all).

Run all six PR quality axes (security, QA, analyst, architect, DevOps, roadmap) against your working changes and merge their verdicts into one. Use when you say run all the quality gates, pr-quality all, or full pre-push review. Do NOT use to run one axis on its own (use pr-quality-security or its sibling for that axis), and do NOT use as the pre-merge gate (use review).

Assess a local diff for code quality, blast radius, and maintainability cost, and return a PASS/WARN/CRITICAL_FAIL verdict. Use when you say analyst review my changes, run the analyst gate, or what does this change cost us. Do NOT use to run all six axes (use pr-quality-all), and do NOT use to plan the work (use plan).

Review a local diff for design patterns, system boundaries, coupling and cohesion, and ADR compliance, and return a PASS/WARN/CRITICAL_FAIL verdict. Use when you say architect review my changes, run the architect gate, or does this respect our boundaries. Do NOT use to run all six axes (use pr-quality-all), and do NOT use to author a new ADR (use architect).

Evaluate a local diff for CI/CD, build pipeline, and infrastructure risk, and return a PASS/WARN/CRITICAL_FAIL verdict. Use when you say devops review my changes, run the devops gate, or is this workflow change safe. Do NOT use to run all six axes (use pr-quality-all), and do NOT use to author the pipeline itself (use the devops agent).

Judge a local diff on test coverage, error handling, and whether the tests would fail if the code regressed, and return a PASS/WARN/CRITICAL_FAIL verdict. Use when you say qa review my changes, run the qa gate, or are these tests good enough. Do NOT use to run all six axes (use pr-quality-all), and do NOT use to write the tests themselves (use test).

Assess a local diff for strategic alignment, scope creep, and user value, and return a PASS/WARN/CRITICAL_FAIL verdict. Use when you say roadmap review my changes, run the roadmap gate, or does this serve a real user. Do NOT use to run all six axes (use pr-quality-all), and do NOT use to set the roadmap (use the roadmap agent).

Scan a local diff for vulnerabilities, secret exposure, and OWASP Top 10 anti-patterns, and return a PASS/WARN/CRITICAL_FAIL verdict. Use when you say security review my changes, run the security gate, or check this diff for vulnerabilities. Do NOT use to run all six axes (use pr-quality-all), and do NOT use for a full pre-merge review (use review).

Respond to review comments on one or more pull requests. Clusters the threads, fixes and pushes, then runs the dispatchable completion gate for a verdict. Use when you say respond to PR review comments, pr-review 1234, or address the review feedback. Do NOT use to fix a red check that carries no review comments (use pr-autofix), and do NOT use to work one PR's threads as a step inside another workflow (use pr-comment-responder).

Commit the working tree, push the branch, and open a pull request with the repository template filled in from the real diff. Use when you say push and open a PR, open a pull request, or push this branch. Do NOT use to run the pre-ship review gates (use ship), and do NOT use to validate PR metadata alone (use validate-pr-description).

Grade each product domain and architectural layer with A-F scoring and gap tracking. Produces markdown or JSON reports showing grades, file counts, gaps, and trends. Use when you ask "grade quality", "audit domain quality", "show quality gaps", "domain quality report", or "run quality grades" across a repo. Use for repo-wide A-F domain grading and trend tracking. Do NOT use for single-file maintainability scoring (use code-qualities-assessment) or a pre-merge review (use review).

Research an external topic, write a 3000-to-5000-word analysis, map it onto this project, and draft the follow-up issue for the owner. Use when you say research this topic, what does the literature say about X, or analyze this external practice for us. Do NOT use to search this repository (use memory or grep), and do NOT use when no spec, issue, or artifact consumes the result.

Verify a review finding before acting on it. Splits a finding into verdict, diagnosis, and prescribed fix, each needing its own evidence, so you verify before you fix and check the supporting claims rather than only the conclusion. Use when you say "address this review comment", "the bot flagged this", "handle this finding", "a sub-agent reported this", or when you inherit findings from a prior session. Do NOT use to produce a review (use review) or to run the PR thread workflow end to end (use pr-comment-responder, which applies this per finding).

Security review knowledge delivered as parent-inline context (the form-factor counterpart to the security agent). Threat-models a code change, scores risk with CWE/CVE evidence, and returns a verdict. Use to review a diff or snippet for vulnerabilities when you want the security knowledge inline rather than dispatched to a subagent. Do NOT use for STRIDE attack-surface analysis of a system or architecture; use threat-modeling instead. Do NOT use to decide whether security review is warranted (use security-detection).

Design Service Level Objectives (SLOs) with SLIs, targets, alerting thresholds, and error budget calculations following Google SRE best practices. Use when defining reliability targets, designing SLOs, calculating error budgets, or establishing service level indicators.

Match file paths against steering file glob patterns to determine applicable steering guidance. Use when you say "match steering for these files", "which steering applies to this task", or "inject steering context". Use when orchestrator needs to inject context-aware guidance based on files being modified. Do NOT use for reading steering files directly when the applicable file is already known; read the file manually instead.

Validate code against style rules from .editorconfig, StyleCop.json, and Directory.Build.props. Use when you say "check style compliance", "validate editorconfig rules", "run style enforcement", "check naming conventions", or "validate line endings". Detects line ending violations, naming convention issues, indentation problems, and charset mismatches across C#, Python, PowerShell, and JavaScript. Do NOT use for taste/style invariants like file size or structured logging (use taste-lints).

Detect Spec-to-Code drift by scanning REQ, DESIGN and TASK specs for references to code that no longer exists, then report it for triage. Use when you say detect spec drift, sync the specs, or did my refactor break a spec, and run it after a hand-edit that moved or deleted code. Do NOT use to write a spec (use spec), and do NOT use to auto-rewrite specs; it reports and never edits.

Use when you say run taste lints, check file size, or lint taste invariants. Custom lints with agent-readable remediation instructions for file size, naming conventions, structured logging, and complexity.

Prove a change works across six gates covering functional, non-functional, security, DevOps, developer experience, and observability quality. Use when you say prove this works, run the test gates, or validate this change, and run it after build. Do NOT use to write the implementation or its first tests (use build), and do NOT use to run pre-flight and open a PR (use ship).

Structured security analysis using OWASP Four-Question Framework and STRIDE methodology. Generates threat matrices with risk ratings, mitigations, and prioritization. Use for attack surface analysis, security architecture review, or when asking what can go wrong. Do NOT use for per-change diff or snippet risk review; use security-review instead.

Validate a PR title and body against conventional commit format, issue-linking keywords, and template compliance before submission. Use when you say validate my PR description, check my PR title, or is this PR body compliant. Do NOT use to open, update, or push a PR (use the github skill or push-pr), and do NOT use to review the code diff (use review).

Treat upstream validators as authoritative. Align local config to them. Use when validation fails unexpectedly, before modifying validator behavior, or when tempted to change upstream tool code.

Automates Windows container image migration for OneBranch pipelines. Bumps AdoPipelineGeneration package, regenerates pipeline configs via ConfigGen, and verifies old image reference is removed. Use for LTSC2019 to LTSC2022 migration, container image updates, OneBranch pipeline image upgrades.