Universal Ai Engineer

---
name: universal-ai-engineer
description: >-
  Use when the user invokes /universal-ai-engineer or wants a safe, professional end-to-end
  engineering workflow for ANY software project and OS (Windows/WSL/Linux/macOS) — web apps,
  CLIs, libraries, APIs, services, data pipelines, or AI/RAG/agent systems: start or prepare a
  project,
  auto-install missing tools, set up project-local environments, install dependencies safely,
  refresh official docs/versions, assess an existing folder, recommend architecture, implement a
  feature or bugfix, review
  changes, run a pre-commit ship-check, upgrade this skill, or install other needed skills.
  Modes: preflight, analyze, start-project, prepare-env, implement, review, refresh-docs, ship-check,
  self-upgrade, ensure-skills.
version: 1.7.0
---

# Universal AI Engineer Skill

## Purpose

Turn ad-hoc coding into a professional engineering workflow for any software project — web apps,
CLIs, libraries, APIs, services, data pipelines, and AI/RAG/agent systems — on any OS, any time:

**project setup → environment preparation → safe dependency install → architecture check →
implementation → testing → Codex review → adversarial review → fix confirmed issues → retest →
final summary.**

This file is the always-loaded **core**: dispatch, safety rules, and efficiency rules. Detailed
per-mode playbooks live in `references/` and are loaded **only when that mode runs**
(progressive disclosure keeps token cost low). Optional WhatsApp status updates are available in
any mode via `scripts/notify.py`.

## How to use this skill

1. The first argument is the **mode** (default to asking the user if none/ambiguous).
2. Load **only** the reference file mapped to that mode (see table). Do not load the others.
3. Always apply **Core Safety Rules** and **Token & Context Efficiency** below, in every mode.
4. The human user makes the final decision. When unsure, ask before acting.
5. The skill is for **ongoing iteration** — re-invoke any mode on an existing or finished project to
   extend, fix, or re-assess it (not one-shot).

## Modes & Dispatch

| Mode | Use when | Load reference |
|------|----------|----------------|
| `preflight` | Check/repair tools the project needs (doctor) | `references/environment.md` |
| `analyze` | Survey an existing folder; assess it + propose a plan, change nothing | `references/environment.md` + `references/architecture.md` |
| `start-project` | Start a new project / prepare a clean folder | `references/environment.md` + `references/architecture.md` |
| `prepare-env` | You have a folder; set up env + dependencies | `references/environment.md` |
| `implement` | Build a feature or fix a bug | `references/implementation-review.md` + `references/architecture.md` |
| `review` | Review existing changes before commit | `references/implementation-review.md` |
| `refresh-docs` | Check latest docs/versions/best practices/architecture | `references/architecture.md` |
| `ship-check` | Final gate before commit or PR | `references/ship-and-notify.md` |
| `self-upgrade` | Improve this skill (gated, human-approved) | `references/maintenance-and-skills.md` |
| `ensure-skills` | Install other needed skills (trusted sources) | `references/maintenance-and-skills.md` |

Notifications (any mode): `scripts/notify.py` sends a short status **at each stage**
(plan/env/tests/review/ship/complete) — via WhatsApp (CallMeBot/Twilio/Meta) if set up, else the
**PC** default (printed locally). The number + key are collected **first**, at the start-of-project
setup gate (and `preflight`), with per-project reuse. See `references/ship-and-notify.md`.
Optional **PC visual** of the plan/status (any mode): `scripts/visualize.py` — generates a
**draw.io** diagram (or HTML via `--format html`) and opens it locally, no dependencies. See
`references/ship-and-notify.md`.

## Core Safety Rules

These apply in **every** mode and override convenience:

- **Plan and get approval before editing.** Never edit files before explaining the plan AND
  getting the user's go-ahead. The mode invocation itself is not approval to edit.
- **No destructive changes without approval.** Never delete or overwrite existing project files
  without explicit approval.
- **Never touch secrets.** Never modify `.env`, secrets, credentials, API keys, production
  configs, deployment settings, or banking/client-sensitive files unless explicitly approved.
  Never paste a secret into chat; never read/store/transmit the user's keys.
- **Installs:** auto-install only **project-local** things (e.g. `.venv`, `node_modules`). For
  **global/system** installs (runtimes, global packages, CLIs) **show the command and ask once**
  before running. Never install global dependencies silently.
- **Prefer project-local environments** over global state.
- **Inspect before acting.** Always inspect the project and detect the stack before choosing
  commands or installing anything.
- **Show commands first.** Always show the exact command before running dependency installation
  or any destructive, expensive, global, or network-heavy command — and ask for approval unless
  the user already said to proceed.
- **Fail small.** If a command fails, explain the failure and propose the smallest fix.
- **Review findings critically.** Never blindly accept Claude or Codex findings. Separate real
  issues from false positives from "needs human decision."
- **Notifications stay safe.** Send only a short status *headline* over WhatsApp — never any
  payload (code, diffs, logs, paths, identifiers, customer data, secrets, or keys).

## Token & Context Efficiency (apply while working)

Keep the workflow cheap without hurting quality:

- **Smallest *sufficient* context, not smallest possible.** Never trim hard-reasoning work
  (architecture, security, debugging). Validate that any summarization didn't drop something
  needed.
- **Progressive disclosure.** Load only the reference file for the active mode; load others only
  if the task truly crosses into them.
- **Explore cheaply.** Use Grep/Glob and targeted reads (offset/limit). Don't cat whole files,
  and don't re-read a file you just edited.
- **Subagents for heavy reads/analysis** (their context stays out of the main thread) — but
  **not** for tiny shell/git tasks, where overhead outweighs savings.
- **Model tiering.** Use a small model (e.g. Haiku) for mechanical subagent tasks (reading logs,
  boilerplate), a mid model (Sonnet) as default, and a top model (Opus) for architecture, tricky
  multi-file bugs, and security review.
- **Session hygiene.** Keep the project's `CLAUDE.md` lean (a lookup table, not a brain dump);
  use `/clear` between unrelated tasks and `/compact` *early* (not when the window is full);
  lower thinking effort on simple tasks.
- **Batch** independent tool calls; reuse prior findings; keep tool output concise (use search
  head limits); never dump large logs into context.

## Coding best practices (summary — full rules in `references/architecture.md`)

Smallest correct change; match existing style; no unrelated refactors. Clear names, no dead
code. Validate inputs and handle errors explicitly. No secrets in code. Add/update tests for new
logic. Type hints + comments that explain *why*. Security basics: least privilege, parameterized
queries, sanitize untrusted input, pin and audit dependencies. Small commits with conventional
messages; review before merge. Prefer clarity over cleverness; avoid premature abstraction.

## Example Usage

```
/universal-ai-engineer preflight
/universal-ai-engineer analyze ~/projects/existing-project
/universal-ai-engineer start-project ~/projects/my-agent-app
/universal-ai-engineer prepare-env ~/projects/my-agent-app
/universal-ai-engineer refresh-docs for this project
/universal-ai-engineer implement login validation
/universal-ai-engineer review current changes
/universal-ai-engineer ship-check before commit
/universal-ai-engineer ensure-skills for this project
/universal-ai-engineer self-upgrade
```

## CHANGELOG

- **1.7.0** — Start-of-project **setup gate now runs first and actively prompts** (`codex login`,
  collect the WhatsApp number+key, `git init`) — with **defaults so nothing blocks** (no WhatsApp →
  PC updates; no Codex → built-in reviewers; no git → proceed without it), and "add it later"
  persists. Notifications now fire **at each stage** (plan/env/tests/review/ship/complete);
  `notify.py` gained a `pc` channel that's the default when no WhatsApp provider is set.
- **1.6.0** — WhatsApp-only (removed the ntfy provider). The WhatsApp number + key are set up at
  **project start** (`start-project`/`prepare-env`), reuse-or-new. New **External Prerequisites**
  check flags accounts/subscriptions/API keys/services the code needs but the repo lacks, and asks
  the user. Documented that the skill supports ongoing edits to existing/finished projects.
- **1.5.0** — Added **first-run setup**: prompts `codex login` when unauthenticated and sets up
  WhatsApp notifications (CallMeBot) persisted per device (`setx`/shell profile), with a
  **per-project reuse-or-new** prompt for the number.
- **1.4.0** — `visualize.py` draw.io output now matches a clean **container-group house style**
  (titled tinted groups + white nodes + classic arrows, modeled on a real draw.io reference). New
  `groups`+`edges` input renders **architecture** diagrams (the default look); `steps` still
  renders a status board.
- **1.3.0** — `visualize.py` now outputs a **draw.io** diagram by default (color-coded step
  flowchart + section notes; open in draw.io Desktop / the VS Code Draw.io extension /
  app.diagrams.net). HTML board still available via `--format html`.
- **1.2.1** — Corrected the Codex review step to call the real `codex` CLI (`codex review` /
  `codex exec` / `codex login`, verified against `codex --help`) instead of the non-existent
  `/codex:*` slash commands; noted the `codex mcp-server` option. Confirmed during live install
  (codex-cli 0.142.0).
- **1.2.0** — Added `scripts/visualize.py`: render a plan/status board as a self-contained HTML
  page and open it on the PC (stdlib-only, cross-platform). Documented the PC-visual + WhatsApp-text
  pairing in `references/ship-and-notify.md`.
- **1.1.0** — Added `analyze` mode (read-only: survey a folder → Project Assessment + proposed
  plan, no changes), large-repo sampling guidance, binary/unreadable-file handling, and non-git
  checkpoint polish.
- **1.0.2** — Broadened positioning: description and Purpose now state the skill applies to ANY
  software project (web/CLI/library/API/service/data pipeline as well as AI/RAG/agent). No
  functional change; AI guidance remains additive.
- **1.0.1** — QA hardening from subagent testing: stronger secret-scan patterns
  (Stripe/GitHub/modern-OpenAI/AWS-secret/JWT) and fixed keyword-regex precedence; tightened
  plan-approval and Codex-install gates; `notify.py` HTTP-error reporting + PowerShell-safe
  command; `implement` now includes a summary step; `ensure-skills` discovery-path + supply-chain
  fixes.
- **1.0.0** — Initial release: 9 modes, cross-platform (Windows/WSL/Linux/macOS), self-bootstrapping
  Preflight (ask-once before global installs), Codex-optional review with built-in fallback,
  optional WhatsApp notifications, progressive-disclosure layout, gated self-upgrade, and
  trusted-source ensure-skills.