ai-engineering-review

Codex compatibility note:

• Invoke $skill-name: load the registered .agents/skills/<name>/SKILL.md and execute it with Codex tools; no separate Skill tool or Claude mode switch is needed. Author .claude/**; mirrors are generated.
• Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.
• Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.
• Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required spawn_agent subagent(s) for that task.
• Preserve protocol order unless the user approves a deviation. Workflows use $start-workflow: gates stay fixed; other steps may flex with logged reasons and evidence.

Quick Summary

Review modes: For review/audit work, standalone defaults to --review-only (--report-only alias); --fix-loop enables review → validate → authorized fix → fresh re-review, default cap 3. --fix-loop --loop-owner=caller returns a read-only pass to the caller that owns fixes/re-review. Create triage, review, validation and re-review todo tasks first; apply the carried review-policy contract for LOW deferral and user-approved bounded extensions. Non-review modes and terminal findings validation keep their own dispatch.

Goal: Review a plan or a change that calls a model — LLM calls, prompts, agents, tool use, RAG, MCP, evals, guardrails, fine-tuned or classical ML — against the AI-engineering protocol, and report evidence-backed findings ranked by real consequence. Skip when nothing in scope touches a model.

Summary:

• Load protocols and project policy → detect AI surfaces and skip when none → map kind, autonomy, data, sinks and trifecta legs.
• Check framing (AF-1–AF-6) → nine focused engineering passes (AE-1.1–AE-9.4) → conditional RAG / agent / ML sweeps → verify provider facts from current docs.
• Write the AI Gate Report → validate findings with $why-review → report, or repair and freshly re-review under standalone --fix-loop. Code and plan modes share this authority rule.

[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. Inside a workflow run, $start-workflow → Workflow-step mode bounds this rule. [BLOCKING] Before each step or sub-skill call, update todo tracking: set in_progress when step starts, set completed when step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

Default scope: The change set under review — uncommitted changes (staged + unstaged) by default, or the branch / PR range when a review base exists (--base <the review base>) — that the AI-signal scan or the signal-grep fallback marks as an AI surface, expanded from each file to the whole surface it belongs to (call site → prompt → tools → sinks → data sources). Override: specify files, directories, a surface, or a plan path.

Modes: --mode=code (default) reviews source, prompts, tool schemas, config and tests · --mode=plan reviews a plan, spec or design against AF-1–AF-6 and returns plan gaps plus REQUIRED plan additions. Both default to read-only; standalone --fix-loop authorizes scoped repairs followed by fresh review.

CONDITIONAL — SKIP when no AI-feature surface is in scope. In workflow context this skill is SKIPPED when Phase 1 finds no AI surface. Standalone with no AI surface → announce No AI-feature surface detected — ai-engineering-review skipped and report clean; never run an AI review to manufacture coverage.