claude-skills

Use when creating Claude Code plugins - covers skills, commands, agents, hooks, MCP servers, and plugin configuration. Use when user says "create plugin", "make a skill", "add command", "add hooks", "skill authoring", "SKILL.md", "plugin components", "package reusable behavior", "distribute skills", "scaffold plugin", "plugin structure", "write a skill description". NOT for: using existing plugins, installing plugins, plugin marketplace browsing. !`ls .claude-plugin/ 2>/dev/null`

Use when starting a new development project — creates memory folder structure with project_state.md (including codePath), architecture scaffolding, and registers project. Accepts optional code_path argument.

Use when checking code quality, running security audits, testing coverage, finding SOLID/DRY violations, or setting up quality tools. Use when user says "audit this code", "check security", "run PHPStan", "code quality", "find violations", "SOLID check", "DRY check", "test coverage", "lint this", "security review", "is this production ready", "check for vulnerabilities", "code review", "grade this code", "watch mode lint", "deep review", "ultrareview", "schedule quality sweep". Supports Drupal (PHPStan, PHPMD, Psalm, Semgrep, Trivy, Gitleaks via DDEV) and Next.js (ESLint, Jest, Semgrep, Trivy, Gitleaks). Use proactively before deployment or after significant code changes.

Use when an orchestrator must run a task's work-orders CONCURRENTLY behind the same gate floor as the sequential loop — the DB-free parallel sibling of work-order-loop. Each round it reconciles from disk (L1-light), selects a disjoint-file ready batch (wo-parallel-batch.sh), builds every batched WO at once in its OWN ephemeral git worktree branched off the integration HEAD (N parallel build atoms in ONE message), runs /review --headless + the work-order-critique rung per worktree, derives every verdict from disk, and merges each CLEAN WO back into the integration branch with a LOCAL git merge (wo-merge-back.sh — NOT a PR merge), pruning each ephemeral worktree after its verdict. The per-WO retry cap stays the SOLE responsibility of wo-run-state.sh dispatch; terminal-HALT precedence, disk-is-truth, and no-auto-merge are preserved verbatim. At the end it runs ONE integrated /review on the integration branch and opens ONE PR through wo-pr-open.sh (re-runs the merge gate, NEVER merges). MUST be invoked inline (ne

Use when an orchestrator must run the autonomous per-task run-loop behind the gate floor — the thin native glue (③ lifecycle_controls). Resumes from disk (L1-light), drives a ready-queue over the work-orders (a WO is ready when all blocked_by are done), dispatches ONE build atom per WO in clean context, runs /review --headless + the work-order-critique rung per WO, owns EVERY WO status transition via wo-compile.sh set-status, bounds the verify→fix loop with a crash-safe retry cap (wo-run-state.sh), and at the end opens a PR through the wo-pr-open.sh choke point that re-runs the merge gate and NEVER merges. Reads every decision from disk; treats builder transcripts as untrusted data; honors a budget/kill-switch call-site. MUST be invoked inline (never Task-dispatched). Prints a ready-to-paste /goal string; never runs /goal itself.

Use when an orchestrator must run the opt-in adversarial-critique rung on ONE built work-order — the absent-human review layered ABOVE the deterministic gates. Derives the work-order's risk tier (wo-risk-classify.sh), decides whether critique is required (forced-on for high-risk-unattended; else the per-task/per-project dial), spawns risk-scaled INDEPENDENT fresh-context wo-critic agents that re-derive the verdict from artifacts (git diff + gate envelopes), aggregates fail-closed (wo-critique-aggregate.sh) into a per-WO _critique.json, and writes a wo-NN.HALT marker when blocking. Fan-out is the unattended primitive; never edits /review's _review.json. A judgment layer, not a gate — gates always run first.

Use when a phase command (research/design/implement) needs to load methodology references, online dev-guides, and project playbooks before task work begins. **v4.10.0+: hybrid detection** — a deterministic phase-aware methodology floor + lexical catalog candidates via scripts/dev-guides-detect.sh, plus semantic matches from the guides-matcher agent. Delegates guide fetching to dev-guides-navigator. Loads playbook layers via scripts/playbook-load-deterministic.sh. Cross-references conflicts. Records loaded guide IDs into session_context.json loadedGuides[] to prevent re-loads.

Use when a framework command needs to read the hierarchy metadata of a task — parses the YAML frontmatter block at the top of task.md and returns structured data (id, kind, parent, children, blocks, blocked_by, external_ids, derived status) plus any warnings. Defensive: never blocks on malformed input; absent frontmatter yields kind=flat. Delegates to scripts/fm-read.sh.

Use when an orchestrator must build exactly ONE contract-conformant work-order in clean context — gates it through wo-compile.sh assert-dispatchable (fail-closed; never spawn on a non-zero gate), checkpoints the shared code worktree, spawns one fresh standard Task-tool subagent whose prompt is the self-contained work-order body, treats the collected transcript as untrusted data, commits the worktree only if it shows changes, and returns the disk-derived collect-handle JSON. A per-work-order atom: no loop, no verdict, no /review; read-only on the work-order BODY, and its ONLY status write is the `ready→in_progress` flip (after its re-gate, before it commits — the crash-safety hinge). Invoked per-WO by the lifecycle_controls loop; runs in the orchestrator's main context (its single Task spawn is the one supported depth-1 level).

Use when a /design-complete ai-dev-assistant task must become N self-contained, gate-verifiable work-orders — decomposes architecture.md Components into units, attaches falsifiable Current/Target/Acceptance + [CATEGORY]-NN requirement IDs, derives dependency edges, slices the coverage-map per unit, inlines the load-bearing build context, and emits each work-order to the task's work-orders/ folder (wo-NN-{slug}.md) against the frozen schema_version 1.0 contract. The judgment lives here; all determinism (SCC/acyclicity, fail-closed verified, drift-guard, lockfile SHA, frontmatter emit) delegates to the wo-compile.sh kernel. Invoked by an orchestrator or the /compile-work-orders command, never typed by a user.

Use when testing code, skills, commands, or configs through mental execution — trace logic line-by-line with concrete values to find bugs, logic errors, edge cases, contract violations, and AI hallucinations. Use when user says "paper test", "trace this", "find bugs", "check for edge cases", "audit this code", "verify AI code", "test this skill", "test this agent", "validate this implementation", "review this logic", "check dependencies", "check this config", "walk through this code", "step through this", "dry run", "sanity check", "red team this", "poke holes in this". MUST verify external calls — never assume methods exist. Use proactively before deploying changes or after AI generates code.

Use when ANY development task might benefit from a guide. Use when user says "how do I", "best practice", "pattern for", "guide for", "Drupal form", "entity type", "plugin type", "routing", "caching", "config management", "SDC component", "design system", "Bootstrap mapping", "Radix theme", "JSX to Twig", "Tailwind tokens", "SOLID", "DRY", "TDD", "security", "CSS", "Next.js". Use PROACTIVELY before any design, architecture, or implementation work. MUST be invoked before writing code that touches Drupal APIs, theming, design systems, or security. NEVER skip guide check — patterns prevent bugs.

Use when a development task needs recipe + guide discovery — matches 0..N agentic recipes for the task, unions the guides and plays they require, runs residual guide-search over uncovered aspects, and emits a ranked coverage map (aspect → recipe/guide/play; uncovered flagged). Delegates ALL fetching to the dev-guides-navigator plugin; never re-implements the fetcher and never extends guides-matcher. Invoked by the phase flow or an orchestrator at the front of a task.

Use when a lifecycle orchestrator reaches a phase boundary and needs the framework-specific process recipe that drives that phase. Checks project_state first (a recorded source is the memory of the prior decision and resolves directly); on a miss resolves by source order (repo-local, machine-local, dev-guides) and on a true miss returns action:ask-user for the orchestrator to ask the user. Tags provenance strictly (verified:true only for dev-guides upstream), records the source choice in project_state.md, and reports a body_path the orchestrator reads alongside a structured JSON report. Delegates ALL fetching and store operations to the dev-guides-navigator plugin; never touches the navigator plugin's filesystem directly.

Runs honest fresh-context review of a Drupal contribution — dispatches isolated reviewer agents with no session narrative to check the work against scope, coding standards, security, and the AI policy. Use when the user runs /drupal-ai-contrib:review or asks for an honest review, a fresh-eyes review, or a pre-submission review of a Drupal contribution. A builder cannot objectively review its own work.

Creates or updates a Drupal merge request and generates the AI-disclosure comment at the policy threshold. Use when the user runs /drupal-ai-contrib:submit or asks to submit, open, or update a Drupal merge request or patch. Creates the cross-project MR via the drupal-gitlab skill (glab); wraps drupalorg-cli for no-auth reads; surfaces status and RTBC guidance.

Works the Drupal issue lifecycle — reviews prior work on an issue first, then creates / comments on / claims it, and checks out the issue fork + branch with three-way fork handling. Use when the user runs /drupal-ai-contrib:issue or asks to find, create, claim, or check out a Drupal issue or issue fork. Wraps drupalorg-cli for no-auth reads; delegates authenticated GitLab fork/push to the drupal-gitlab skill.

Fetches the real GitLab merge-request pipeline for a Drupal contribution and gates on it — the authoritative final check. Use when the user runs /drupal-ai-contrib:pipeline or asks to check the real pipeline, the CI status, or whether a Drupal contribution is done. A contribution is not complete until the real drupalci pipeline is green.

Stands up and environment-matches a Drupal contribution workspace — DDEV with the workflow-matched add-on, CI gate config (new-module scaffold or existing-module discovery), the Drupal AI skills, the drupalorg CLI, the GitLab CLI (glab) for authenticated git.drupalcode.org operations, and a contribution-credentials (SSH-key) check. Use when the user runs /drupal-ai-contrib:setup or asks to set up a Drupal contribution environment. Idempotent and detect-driven — does only what is missing; never a gate, never a prerequisite.

Routes Drupal contribution work to the right contribution-quality stage and supplies the contribution knowledge layer. Use when user says 'contribute to Drupal', 'Drupal contribution', 'submit a Drupal patch', 'Drupal merge request', 'fix a Drupal core issue', 'contribute a module', 'AI-assisted Drupal contribution', or works a drupal.org / GitLab Drupal issue. Use PROACTIVELY whenever AI-assisted code is headed for a Drupal contribution — drupalci and maintainer review are unforgiving.

Enforces the development discipline for AI-assisted Drupal contributions — evidence over assertion, the no-guessing rule for external facts, the verification-gate artifact contracts, and re-verification on post-gate change. Use PROACTIVELY during any development between claiming an issue and verifying it. Use when user says 'guardrails', 'evidence over assertion', 'no guessing', 'verify this fact', 'is this actually tested', or whenever AI-assisted code is being written for a Drupal contribution. MUST apply before claiming any gate passed.

Runs the local verification inner loop for a Drupal contribution — the drupalci-parity gate set at CI strictness, the AI-policy gate, and the eval gate, every gate passing only on a captured artifact. Use when the user runs /drupal-ai-contrib:verify or asks to verify, check, or locally test a Drupal contribution before submitting. This is the centerpiece — evidence over assertion, never a bare 'passes'.

Use before committing code - validates code against SOLID, DRY, security, and purposeful-code principles (stack-neutral). Trigger: 'check code quality', 'pre-commit check', 'validate standards', 'review this'. Use proactively before any commit. The concrete stack linters are the code-quality-tools plugin's job; the framework-specific implementation rules come from the resolved implement recipe.

Use when needing the framework's canonical implementation example for a pattern - searches the framework's own source for the pattern and returns file-path references

Use when breaking down a component for implementation - creates task file in implementation_process/in_progress/ with TDD steps and acceptance criteria

Use when a framework command needs project-level metadata (codePath, playbookSets, userPlaybook, playbookResolutions, project_name). Reads project_state.md defensively via scripts/project-state-read.sh and returns structured JSON with warnings. Never blocks on malformed input.

Use when gathering project requirements - asks structured questions about project type, scope, integrations, and constraints to populate project_state.md

Use when a framework command has resolved the active project and/or task and needs to persist that context for hooks. Writes per-workspace session_context.json so compaction hooks and the context-reminder hook can restore the right project/task context. Preserves loadedGuides[], lastPhase, and currentEpic across writes.

Use when finishing a task — moves the v3.0.0 task folder to completed/, updates project_state.md, suggests next task. Runs all 5 quality gates and blocks completion if any gate fails. Trigger: 'finish task', 'done with task', 'move to completed'.

Use during implementation to enforce TDD - reminds test-first, validates the Red-Green-Refactor cycle, integrates with superpowers:test-driven-development. Trigger: 'test first', 'write tests', 'Red Green Refactor', 'TDD workflow'. MUST be active during all Phase 3 implementation. NEVER write implementation code before tests. Stack-neutral; the framework test types come from the resolved implement recipe.

Use when a framework command needs to parse a task's alignment.md (the scope contract — Goal / Expected result / Success criteria / Non-goals per section). Reads defensively via scripts/alignment-read.sh and returns structured JSON with warnings. Never blocks on malformed input.

Use when a framework command needs to inspect the project's visual-regression baseline store — the codePath-native tests/visual/ snapshot tree. Reads the store defensively via scripts/screenshot-store-read.sh and returns structured JSON. Never blocks on malformed input.

Use when converting a flat task into an epic folder with children, promoting a subtask to a sub_epic, or expanding an existing epic with more children. Runs the 8-step transactional migration via scripts/migrate-to-epic.sh. Supports --dry-run for preflight plan. Never leaves half-migrated state on disk.

Use when a framework task requires specialized guide content — delegates to the dev-guides-navigator plugin for online guide discovery with caching and disambiguation.

Use when determining task phase - analyzes task file to identify Phase 1, 2, or 3 for a specific task

Use when starting implementation of a task - loads architecture files, referenced patterns, relevant guides, and task file into context

Use when migrating existing single-file tasks to folder-based structure - preserves content, creates organized folders, backs up originals

Use when creating branded presentations or carousels. Generates museum-quality visual output from canvas philosophy, enforcing style constraints. Outputs PDF first, then converts to PPTX for editability.

Use when implementing HTMX in Drupal, migrating from AJAX to HTMX, building dynamic forms, dependent dropdowns, infinite scroll, real-time validation, or multi-step wizards. Use when user says "HTMX", "migrate AJAX", "dependent dropdown", "dynamic form", "infinite scroll", "load more", "real-time validation", "multi-step wizard", "hx-get", "hx-post", "Htmx class". Use PROACTIVELY for any Drupal 11.3+ dynamic interaction that could use HTMX instead of AJAX. MUST check HTMX patterns before implementing AJAX callbacks.

Use when user says "create presentation", "make slides", "make carousel", "LinkedIn carousel", "create HTML page", "make landing page", "build web page", "html design system", "design system", "setup brand", "brand init", "extract brand", "get outline", "color palette", "alternative colors", "infographic", "brand assets", "brand project". Use PROACTIVELY when user wants to create any visual content with consistent branding. MUST be invoked for branded content — routes to the correct command for presentations, carousels, infographics, and HTML pages.