rjmurillo/project-toolkit

Create comprehensive Architectural Decision Records (ADRs). Researches the destination directory to detect existing template conventions, gathers context, determines next ADR number, generates the ADR, validates completeness, and saves. Supports multiple ADR formats (MADR, Nygard, Alexandrian, project canonical). Use when documenting technical decisions, creating new ADR files, or capturing rationale so future readers can revisit a choice. Use when you say "write an ADR", "document this decision", "document these design choices", "record why we chose this", "capture the rationale", or "for future maintainers", or when creating an ADR-like markdown file under docs/decisions/, docs/adr/, docs/architecture/, architecture/decisions/, or .project-toolkit/architecture/. Do NOT use to debate or review an existing ADR (use adr-review).

Multi-agent debate orchestration for Architecture Decision Records. Automatically triggers on ADR create/edit/delete. Coordinates architect, critic, independent-thinker, security, analyst, and high-level-advisor agents in structured debate rounds until consensus. Use when you say "review this ADR", when an ADR is created/edited/deleted, or when reviewing, accepting, or updating a decision file under .project-toolkit/architecture/, docs/architecture/, docs/decisions/, docs/adr/, or architecture/decisions/, including intent like "review this decision record" or "check this rationale for future maintainers". Do NOT use to author a new ADR (use adr-generator).

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).

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.

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.

Route any request to the right skill, command, or agent chain with defaults, so nobody hand-picks from the full catalog. Use when you say /autoplan, do it, handle it, figure this out, or when a concrete request names no skill. Do NOT use when the user names a specific skill or lifecycle command; invoke that directly.

Detect and stop manufactured work after a deliverable appears done, and classify a post-completion finding into the four contract classes builder-ethos.md delegates here. 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.

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).

Route a founder problem to the right business framework, then load that framework on demand. Distills 14 business books (customer discovery, positioning, pricing, sales, growth, persuasion) into scored, decision-tree skills. Use when you say diagnose my business problem, what framework applies, how do I validate demand, price this, position this, generate leads, or close deals. Do NOT use for software design (use the engineering rules) or for a single named decision (use decision-critic).

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).

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).

Write a timestamped, secret-redacted snapshot of decisions, progress and next actions to the checkpoints directory, then link it from the active session log. Use when you say checkpoint this, save a recovery point, or snapshot where we are before a risky change or at the end of a working block. Do NOT use to commit or push (it never does either), and do NOT use to write a retrospective (use retro).

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 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).

Scaffold project documentation (README, ARCHITECTURE, API, CODE_COMMENTS) from templates with documented standards. Use when bootstrapping docs for a new or under-documented codebase.

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

Gather comprehensive context from Serena memory, Context7 docs, DeepWiki, and web sources before planning or implementation. Searches across all knowledge tiers and returns a focused summary ending in a CONTEXT_LOADED marker that this skill scans to skip a repeat fetch in the same conversation. 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).

Check the Serena and Context7 plugin prerequisites and report what is missing, with the install command for each. Use when you say set up context hub, check my plugin prerequisites, or troubleshoot MCP connectivity. Do NOT use to actually gather context for a task (use context-gather), and do NOT use to search memory (use memory-search).

Analyze skill content for optimal placement (Skill vs Passive Context vs Hybrid), compress markdown to pipe-delimited format, and validate compliance against the decision framework. Passive context wins for what the model cannot know (post-cutoff APIs, repo gotchas); pre-trained knowledge belongs in progressive disclosure. Use for "analyze skill placement", "compress markdown", "optimize context", "extract and index", or "audit always-on rules". Do NOT use for gathering knowledge before a task (use context-gather) or for creating or improving a skill (use skillforge).

Maintain Serena memory files in place. Mark superseded content, keep current truth visible inline, and run the supersession sweep that proposes a disposition per file without editing it. Use when you say "how do I mark a memory obsolete", "how do I supersede a memory", or "run the supersession sweep". Do NOT use for merging or deleting Serena files or tidying Serena indexes; use memory-consolidate.

Systematic abstraction discovery using Commonality Variability Analysis. Build matrix of what varies vs what's constant, then let patterns emerge. Prevents wrong abstractions by deferring pattern selection until requirements are analyzed. Use when facing multiple similar requirements and need to discover natural abstractions.

Classify problems into Cynefin Framework domains (Clear, Complicated, Complex, Chaotic, Confusion) and recommend appropriate response strategies. Use when unsure how to approach a problem, facing analysis paralysis, or needing to choose between expert analysis and experimentation.

Structured decision critic that systematically stress-tests reasoning before commitment surfacing hidden assumptions verifying claims and generating adversarial perspectives to improve decision quality. Do NOT use to surface failure risks pre-launch (use pre-mortem), probe why a constraint exists (use chestertons-fence), or ask the user to choose (use decision-question).

Ask the user to choose only when blocked on a decision they own, with the smallest complete decision brief. Use when you say ask the user to choose, do I need a user decision here, or present a decision brief. Do NOT use to review a decision already made (use decision-critic) or to surface project risks (use pre-mortem).

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).

Design an API, schema, or module boundary from the business behavior it must support, not from source payload shape or generic CRUD. Decides explicit state, domain operation versus CRUD, and history, then checks the design against use cases. Use when you say design this schema, API design, or CRUD or domain operation. Do NOT use for abstraction discovery (use cva-analysis).

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".

Decide whether evidence is independent or the same loop twice, and whether a named check was run. Classifies lineage (premise, origin, time, mutability, environment), keeps authority a separate axis, and reports VERIFIED, NOT RUN, UNAVAILABLE, or FAILED. Use when you say is this independent evidence, did the reviewer confirm this, closed loop, or count the confirmations. Do NOT use to report progress (use the voice rule) or to pick the governing validator (use validation-authority).

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.

Thin router for the tiered memory system. Points callers at the focused sub-skills for each operation, Tier 1 search, the reflexion write path, the memory-first gate, maintenance, and consolidation. Use when you ask "what do we know about X", "recall prior context", or "search memory" and are not sure which operation you need. Do NOT use for adding citations (use memory-enhancement) or narrative cross-system reports (use memory-documentary).

Reflective consolidation pass over Serena memory files. Separates durable context (preferences, working style, key relationships, recurring workflows) from dated context (projects, deadlines, one-off tasks), merges duplicate topic files onto the richer path, converts relative dates to absolute ones, and tidies memory-index.md so a future session orients fast without re-asking. Use when you say consolidate memory, consolidate Serena memory, merge memory files, or tidy the memory index. Do NOT use for in-file supersession markers (use curating-memories) or health, token, or size checks (use memory-maintenance).

Generate evidence-based documentary reports by searching across all 3 memory systems (Claude-Mem, Serena, DeepWiki), .agents/ artifacts, and GitHub issues. Produces investigative journalism-style analysis with full citation chains. Use when you ask for an "evidence-based report", "investigate across all memory systems", "what happened with X over time". Do NOT use for a single semantic recall (use memory) or for citation hygiene (use memory-enhancement).

Manage memory citations, verify code references, and track confidence scores. Use when adding citations to memories, checking memory health, or verifying code references are still valid. Use when you say "add a citation", "verify this memory's code refs", "check memory health". Do NOT use for searching or creating memories (use memory) or for documentary reports (use memory-documentary).

Memory-First Gate (BLOCKING) and the Chesterton's Fence investigation protocol, split out of the memory router per ADR-063. Forces a memory search before you change existing code, constraints, or protocol, so the "why" is recovered before the fence comes down. Use when you say memory-first gate, search memory before changing, or chesterton fence check. Do NOT use for plain Tier 1 lookups (use memory-search) or recording a session (use memory-reflexion).

Memory-system maintenance operations, split out of the memory router per ADR-063. Runs health checks, token-cost counting, atomicity size validation, graph-density improvement, and performance benchmarking against the canonical memory scripts. Use when you say check memory health, count memory tokens, or benchmark memory performance. Do NOT use for Tier 1 search (use memory-search) or recording a session (use memory-reflexion).

Tier 2 episode extraction, the reflexion write path split out of the memory router per ADR-063. Extracts an episode from a completed session log so later sessions can replay what was tried and what it cost. Use when you say extract episode from session, record what happened this session, or re-extract this episode. Do NOT use for Tier 1 lookups (use memory-search) or for adding citations (use memory-enhancement).

Tier 1 semantic memory search across the Serena corpus with progressive disclosure and token-budget warnings. The focused search operation split out of the memory router per ADR-063. Use when you say search memory, what do we know about X, or recall prior context. Do NOT use to extract session episodes (use memory-reflexion) or add citations (use memory-enhancement).

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".

Deal intelligence skill for offer analysis and counter-proposal drafting. Trigger on review this offer, analyze counter, value gap, draft counter, should I walk. Apply when reviewing any offer (real estate, compensation, vendor, resource allocation) or designing negotiation analysis behavior in agentic systems. Quantifies value gaps and applies the RADAR protocol.

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".

Triage raw unstructured input (transcripts, brain dumps) into evaluated thread inventories and a synthesized gold-found file. Four phases: front-gate, extract, evaluate, synthesize. Use when you say "pan for gold", "triage transcript", "synthesize gold-found", or hand it a voice transcript or brain dump. Do NOT use for structured input like specs or ADRs (use analyst or spec-generator instead).

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. Designed to be invoked automatically after any change-making skill creates a PR.

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).

Script-guided plan-and-execute workflow run one numbered step at a time. planner.py drafts a plan through forced reflection pauses, then runs a technical-writer and quality-reviewer review of the plan file; executor.py delegates each milestone of an approved plan file to specialized agents and, on resume, reconciles the file against completed work. Use when you say "run the planner workflow", "review the plan file at plans/X.md", "execute the plan at plans/X.md", "pick up where the plan left off", or "resume execution". Do NOT use to decompose a spec into milestones and tasks in the lifecycle chain (use plan), or to log progress on a plan artifact (use execution-plans).

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).

Guide prospective hindsight analysis to identify project risks before failure occurs. Teams imagine the project has failed spectacularly, then work backward to identify causes. Increases risk identification by 30% compared to traditional planning. Use when you say "run a pre-mortem on", "what could cause this to fail", "identify project risks", or "what could go wrong with". Do NOT use to stress-test a single decision's reasoning (use decision-critic).

Evaluate existing solutions (libraries, SaaS, open source) AND internal prior-art before custom development to avoid reinventing the wheel. Use when considering building new features, asking "should I build or use existing", "do we already have this", "is there existing code for X in this repo", "is there a library for this", or need build vs buy cost analysis with token estimates. Checks internal reuse (leverage/extend) before external. Do NOT use for strategic multi-option TCO (use buy-vs-build-framework).

Optimize system prompts for Claude Code agents using proven prompt engineering patterns. Use when users request prompt improvement, optimization, or refinement for agent workflows, tool instructions, or system behaviors. Use when you say "optimize this prompt", "improve this system prompt", or "review my agent prompt".

Pre-emit AI-vernacular self-check an agent runs on its OWN prose before writing a session-log narrative, ADR context section, retrospective, or PR description. Four layers ordered by reader-trust, not ease of detection. Use when you say prose self-check, audit my writing for AI tells, does this read as AI-written, or before emitting any prose artifact. Do NOT use for code style (use style-enforcement) or to rewrite human-authored text.

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).

CRITICAL learning capture. Extracts HIGH/MED/LOW confidence patterns from conversations to prevent repeating mistakes and preserve what works. Use PROACTIVELY after user corrections ("no", "wrong"), after praise ("perfect", "exactly"), when discovering edge cases, or when skills are heavily used. Without reflection, valuable learnings are LOST forever. Acts as continuous improvement engine for all skills. Invoke EARLY and OFTEN - every correction is a learning opportunity.

Adversarial requirements interview that walks the design tree to elicit testable requirements before any code is written (the grill-me pattern), or audits an existing multi-section spec for ambiguity with source-anchored questions. Skip any question the codebase can already answer. Use when you say "interview me on this", "grill me on the requirements", "walk the design tree", or "audit this spec for ambiguity".

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.

Fill an unfilled auto-retrospective skeleton for a date, or list the skeletons still pending. Use when you say retro fill, fill retro skeleton, or list pending retros. Do NOT use to run the retrospective analysis itself (this hands off to the retrospective skill), and do NOT use to write a session log.

Extract learnings from a session or task through structured retrospective frameworks. Gathers evidence, runs Five Whys and fishbone diagnosis, scores atomicity, and writes a canonical retrospective artifact. Use to turn execution experience into institutional knowledge. Use when you say "run a retrospective", "retro fill", or "extract learnings from this session". Do NOT use for in-conversation correction capture (use the reflect skill).

Review before merge. Stage-1 spec-compliance gate, then risk-selected Stage-2 review axes from the canonical set. analyst always runs, callers can pin extra always-on axes, and explicit deep review runs the full 16-axis set. Run after /test. Do NOT invoke code-qualities-assessment, doc-accuracy, golden-principles, or taste-lints directly for a full review; review can select them when requested or when deep review is explicit.

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).

Detect infrastructure and security-critical file changes to trigger security agent review recommendations ensuring proper security oversight for sensitive modifications. Use when you ask "did I touch security-critical files", "should the security agent review this". Detection only. Do NOT use to scan source for injection patterns (use security-scan).

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).

Detect CWE-78 (command injection) regex patterns in Python, PowerShell, Bash, and C# files before PR submission. CWE-22 is delegated to CodeQL; see Scope. Use when you ask "scan for command injection", "CWE-78 check before PR". Do NOT use to decide whether security review is warranted (use security-detection).

Run the four pre-flight checks, then create the PR or validate a contributor branch without touching it. Use when you say ship it, ship this branch, or run pre-flight and open the PR, and run it after review. Do NOT use to open a PR without the gates (use push-pr), and do NOT use to run the review axes themselves (use review).

Intelligent skill router and creator. Analyzes ANY input to recommend existing skills, improve them, or create new ones. Uses deep iterative analysis with 11 thinking models, regression questioning, evolution lens, and multi-agent synthesis panel. Phase 0 triage ensures you never duplicate existing functionality. Use when you say "create a skill", "do I have a skill for", "which skill should I use", "improve the X skill", or "SkillForge: {goal}". Do NOT use for context optimization, placement analysis, markdown compression, extraction and indexing, or rule audits (use context-optimizer), or eval-gated optimization of an existing skill (use skillopt).

Improve a skill, agent file, or prompt through bounded patches and a held-out, per-task acceptance gate. Use when you say optimize this skill, make this skill better, compress these skills safely, tune this prompt against an eval, or a skill keeps failing the same way. Refuses unscored improvement claims. Do NOT use to create or route skills (use skillforge) or to decide skill placement or compress markdown without an eval (use context-optimizer).

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.

Route software engineering design and discovered code-risk tasks to on-demand book references. Use for architecture review, layer boundary change, dependency boundary, module interface shape, domain modeling, bounded context, refactoring, code smell, legacy code, low test coverage, old file, characterization test, external API calls, queues, retries, transactions, event ordering, data layer, storage design, consistency, schema evolution, timeout, circuit breaker, bulkhead, DRY at the knowledge level, orthogonality, tracer bullet, broken windows, design by contract, and a forbidden-patterns blocklist review in .py, .cs, .ts, .tsx, .js, .ps1, .sql, and service design docs. Do NOT use for reinventing-the-wheel or build-vs-buy, use programming-advisor. Do NOT use for single-file maintainability scoring, use code-qualities-assessment. Do NOT use for CVA design, use cva-analysis.

Turn a problem into testable requirements with acceptance criteria, through a first-principles gate, a memory-first prior-art gate, and a PRD schema. Use when you say spec this out, what should we build, or define the requirements, and run it before plan. Do NOT use to sequence work into milestones (use plan), do NOT use to write the code (use build), and do NOT use to emit the REQ, DESIGN and TASK files directly (use spec-generator, which this invokes).

Transform feature descriptions into 3-tier specifications (Requirements, Design, Tasks) using EARS syntax, with schema-validated frontmatter on every emitted file. Reads the canonical spec schema before writing and rejects any out-of-range enum value. Use when you say "generate spec", "formalize requirements", or "create requirements/design/tasks". Do NOT use to decide what to build or to run the gates that precede it (use spec, which invokes this to write the artifacts).

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.

Detect agent conversation loops via topic-signature similarity and emit a self-reflection nudge. Use as an orchestrator guard against repetitive responses and token-burning loops. Use when you say "check stuck loop", "detect repetition", "agent looping", or "reset stuck history". Do NOT use for semantic similarity checks or multi-turn intent tracking; use a richer evaluation tool for those.

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.

Guidance for using Serena's LSP-powered symbol analysis. Use when you say "how do I find a symbol", "trace references for this method", "explore this file's structure", or when grep/text search would be imprecise. Do NOT use for memory guidance (use memory).

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.

Run a 5-layer interview to elicit how a team actually works (rhythms, decisions, dependencies, institutional knowledge, friction) and emit a structured operating model. Use when you say "elicit operating model", "interview team operating model", "how does this team actually work", or "validate operating model". Do NOT use for code analysis (use the analyst agent), external audience narratives (use the explainer agent), or retrospectives (use the retrospective agent).

Twenty-minute diagnostic mapping a team to a world-model paradigm (vector DB, structured ontology, signal-fidelity). Use when you say "run the world model diagnostic", "audit our world model", "which world model architecture fits us", or "audit where we automate judgment". Use for AI readiness assessments and boundary-layer audits where automated judgment is safe. Do NOT use for mapping team operating rhythms or decision flows; use work-operating-model instead.