Use when Claude Code keeps asking to approve commands you have already approved, when settings.local.json has grown large, or when you want to consolidate permission grants into wildcard patterns. Trigger for 'too many permission prompts', 'clean up permissions', 'audit my settings', 'consolidate allow rules'. Claude Code only — not available in GitHub Copilot.

Use when adding motion, transitions, or micro-interactions to UI components. Trigger for 'animate this', 'add transitions', 'micro-interactions for', 'spring animation', 'gesture design', 'swipe to dismiss', 'review the motion', 'easing for this', 'stagger animation', 'stagger the', 'animar esto', 'transicion para'. Not for design systems or aesthetic direction (use /ai-design), visual art (use /ai-canvas), testing animation code (use /ai-test), or debugging broken animations (use /ai-debug).

Use after /ai-brainstorm approval when a spec is large (3+ independent concerns or 10+ files) and needs autonomous end-to-end delivery. Decomposes into sub-specs, plans with parallel agents, builds a dependency DAG, implements in waves, runs quality convergence loops, and delivers via PR. Invocation is the approval gate — no further confirmation requested. Not for small tasks — use /ai-dispatch.

Operates the project board (GitHub Projects v2 or Azure DevOps): discovers configuration after install (fields, state mappings, process templates) and syncs work-item state at lifecycle transitions. Trigger for 'set up the board', 'configure our ADO board', 'discover board fields', 'move this issue to in-review', 'update the board', 'mark as in progress', 'sync the work item state'. Two subcommands: `discover` (post-install configuration write) and `sync` (lifecycle state transitions). Auto-invoked via `sync` by /ai-brainstorm, /ai-build, and /ai-pr; fail-open. Not for backlog execution; use /ai-autopilot --backlog instead.

Use to discover and configure project board integration after framework install, when board config is missing or stale, or when the team switches projects. Trigger for 'set up the board', 'board sync isn't working', 'we moved to a new GitHub project', 'configure our ADO board', 'the work item states don't match'. Detects GitHub Projects v2 or Azure DevOps fields and writes atomic config to manifest.yml.

Use to update work item state on the project board at lifecycle phase transitions. Automatically invoked by /ai-brainstorm (refinement, ready), /ai-dispatch (in_progress), and /ai-pr (in_review). Also invoke manually for 'move this issue to in-review', 'update the board', 'mark as in progress', 'sync the work item state'. Fail-open: never blocks the calling workflow.

Use when the user wants to think through a problem before coding: designing a feature, exploring approaches, defining requirements, or resolving ambiguity. Trigger for 'let's add X', 'how should we handle Y', 'what's the best approach', 'I'm thinking about', or any work item lacking an approved spec. Not for existing specs — use /ai-plan instead. Produces a reviewed spec; no code until user approves.

Cleans branches safely: switches to the default branch, prunes merged and squash-merged branches, syncs to remote, sweeps stale specs, rotates `.ai-engineering/runtime/` per retention policy. Trigger for 'tidy up', 'tidy branches', 'sync to main', 'delete old branches', 'start fresh', 'rotate runtime'. Auto-invoked by /ai-pr after merge. Not for committing changes; use /ai-commit instead. Not for code-level dead-code removal; use /ai-simplify instead.

Canonical implementation gateway: reads approved plan.md, resolves stack from manifest, deterministic-routes each task to its adapter, dispatches the build agent in an isolated worktree, runs TDD self-validation per task, then a single final quality loop on the full changeset before /ai-pr. Trigger for 'go', 'start building', 'execute the plan', 'implement it', 'lets do this', 'build the plan', 'resume', 'continue'. Not without an approved plan; run /ai-plan first. Not for multi-concern specs needing decomposition; use /ai-autopilot instead.

Use when creating visual design artifacts: posters, banners, flyers, branding pieces, marketing materials, cover art, identity compositions, or any static visual output (PDF/PNG). Trigger for 'create a poster', 'design a banner', 'visual composition for', 'branding piece', 'marketing visual', 'cover art for', 'promotional graphic', 'cartel para', 'material de comunicacion visual', 'diseño visual para'. Not for UI interfaces (use /ai-design), animation (use /ai-animation), presentation decks (use /ai-slides), or AI-generated images (use /ai-media).

Use after merging a PR, at session start, or to tidy up branches. Trigger for 'tidy up', 'clean up branches', 'sync to main', 'get back to main', 'delete old branches', 'what branches do I have', 'start fresh'. Also automatically invoked by /ai-pr after merge. Safely switches to default branch, prunes merged and squash-merged branches, produces per-branch status report.

Use when writing new production code: implementing features, adding functions, creating modules, or building approved plan tasks. Trigger for 'implement this', 'write the code for', 'add X to Y', 'build this function', 'make this work'. Loads language/framework context, applies interface-first design and backward-compatibility checks. Not for tests (/ai-test), debugging (/ai-debug), or refactoring (/ai-simplify).

Use when committing, saving, or pushing code to git. Trigger for 'commit my changes', 'save my work', 'push this to remote', 'stage these files', 'I'm done with this task', 'ship it'. Runs governed pipeline: auto-branch from protected branches, selective staging, ruff format+lint, gitleaks secret scan, documentation gate, conventional commit message, and push. Use /ai-pr instead when a pull request is the goal.

Use when adding a new slash command, building a new agent role, or extending the ai-engineering framework with a capability it does not yet have. Trigger for 'create a new skill', 'add a slash command', 'the framework needs a capability for X', 'build a new agent'. Covers skill scaffold, TDD pressure testing, description optimization, registration, and mirror sync.

Use when something is broken and you need to find out why: test failures, runtime errors, crashes, regressions, or unexpected behavior. Trigger for 'it's not working', 'something broke', 'this used to work', 'I'm getting an error', 'CI is failing', 'the output is wrong', or 'why is X happening'. Systematic 4-phase diagnosis — never patches symptoms without finding the root cause.

Use when designing or building user interfaces, creating design systems, choosing aesthetic direction, defining color palettes, typography, or spatial composition for web or mobile. Trigger for 'design this page', 'create a design system', 'what style should we use', 'UI for this feature', 'color palette for', 'typography for', 'diseña la interfaz', 'estilo para'. Not for animation-specific work (use /ai-animation) or visual art/posters/banners (use /ai-canvas).

Use when an approved plan.md exists and execution should begin. Trigger for 'go', 'start building', 'execute the plan', 'implement it', 'let's do this', 'run the plan', 'resume', or 'continue' after interruption. Not without an approved plan — run /ai-plan first. Orchestrates subagents per task with two-stage review, progress tracking, and automated delivery.

Use for documentation lifecycle: updating CHANGELOG.md, refreshing README files, scaffolding or syncing solution intent architecture docs, pushing to external docs portals, and verifying documentation coverage. Also invoked automatically by /ai-pr. Trigger for 'update the changelog', 'the README is stale', 'document this feature', 'docs portal needs updating', 'did we document all changes'.

Files an upstream bug or improvement report against `arcasilesgroup/ai-engineering` (the framework repo) with strict seven-vector redaction, mandatory human confirmation, and an archived sanitized copy. Trigger for 'report this upstream', 'file an ai-engineering bug', 'this looks like a framework bug', 'tell anthropic / arcasiles about this'. Not for your own project's board (use /ai-issue); not for security disclosure (use the private channel listed in CONSTITUTION.md).

Use when measuring AI system reliability over time: defining pass/fail criteria before implementation, running capability checks, detecting regressions after prompt or model changes, or tracking pass@k metrics. Trigger for 'how reliable is this', 'did my changes break anything', 'measure AI performance', 'define success criteria', 'eval this'. Distinct from /ai-test (code correctness) and /ai-verify (quality gates) — evals measure AI task completion consistency.