Universal ai engineer

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.