# Welcome to `ai-engineering`

Thanks for installing ai-engineering. This is your post-install manual: a
simple, complete reference to everything the framework can do, so you always
know what each capability is for and can reach the right one fast.

ai-engineering installs a governance layer into this repository as ordinary
versioned files — specs, plans, skills, agents, runbooks, hooks, and an audit
trail. Nothing is hidden in a hosted control plane. You drive it from your IDE
agent surface with `/ai-<name>` skills.

`53 skills · 9 agents · 6 surfaces · 1 governed flow`

See also: [root README](../README.md) | [AGENTS.md](../AGENTS.md) | [CONSTITUTION.md](../CONSTITUTION.md) | [persistence doctrine](../docs/persistence-doctrine.md)

## Quick wins

The fastest path to value. Start here, then move through the governed chain.

```text
/ai-start
```

- `/ai-start` — orient in any repository: it reads the project, reports state,
  and tells you the safe next command. Run it first in a new session.

The canonical delivery chain takes work from idea to merged PR with governance
at every step. Reach for it whenever a change touches product behavior,
framework behavior, security posture, public docs, or release state.

```text
/ai-brainstorm → /ai-plan → /ai-build → /ai-pr
```

- `/ai-brainstorm` — interrogate the design and produce an approved spec. Run
  it before writing code for anything non-trivial; the spec becomes the
  contract for everything downstream.
- `/ai-plan` — turn the approved spec into a phased, patch-ready plan and pick
  the executor route (`/ai-build` or `/ai-autopilot`).
- `/ai-build` — execute the plan: stack-aware implementation, TDD
  self-validation per task, and a final quality loop before the PR.
- `/ai-pr` — run the verify + review + commit pipeline and open the pull
  request, watching CI until it is green.

`/ai-commit` stays available for work-in-progress checkpoints; it is not part of
the canonical chain.

## Everything you can do

The catalog below lists every skill and agent with a one-line summary. It is
generated from the skill and agent files (regenerated by `ai-eng dev sync`), so
it always matches what is installed — do not edit it by hand.

<!-- catalog:start -->

_Generated by `scripts/gen_capability_catalog.py` — 53 skills, 9 agents. Do not edit by hand; run `ai-eng dev sync`._

### Skills (53)

Invoke a skill with `/ai-<name>` in your IDE agent surface.

| Name | What it does |
| --- | --- |
| `/ai-advise` | Proactive governance advisor — checks standards, decisions, and quality trends during development. |
| `/ai-analyze-permissions` | 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. |
| `/ai-animation` | Designs motion, transitions, and micro-interactions for UI components: spring animations, gestures, easing, staggers — taste-driven detail compounding. |
| `/ai-autopilot` | Delivers large multi-concern specs and backlog runs autonomously: decomposes specs into sub-specs (or normalizes work items into a backlog DAG), deep-plans with parallel agents, builds a dependency DAG, implements in waves, runs a single final quality loop with one bounded quality-remediation pass (verify+guard+review on full changeset), delivers via PR. |
| `/ai-board` | 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. |
| `/ai-brainstorm` | Forces rigorous design interrogation BEFORE any code: explores approaches, surfaces ambiguity, gathers evidence, produces an approved spec that becomes the contract for /ai-plan. |
| `/ai-branch-cleanup` | 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. |
| `/ai-build` | 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 with one bounded quality-remediation pass on the full changeset before /ai-pr. |
| `/ai-code` | Writes production code that satisfies stack-context standards on the first pass: interface-first design, backward-compatibility checks, lightweight self-review. |
| `/ai-commit` | Runs the governed commit pipeline: auto-branches from protected, stages selectively, formats and lints, scans for secrets, gates docs, composes a conventional message, pushes. |
| `/ai-constitution` | Interviews the operator to produce a project-identity CONSTITUTION.md (Mission / Stakeholders / Vocabulary / Prohibitions / Compliance gates / Anti-goals / Boundaries / Escalation / Language / Lifecycle phase). |
| `/ai-debug` | Diagnoses broken behavior systematically with a 4-phase root-cause loop: test failures, runtime errors, crashes, regressions. |
| `/ai-design` | Designs user interfaces and design systems for web, mobile, CLI, and documentation-heavy experiences: aesthetic direction, color palettes, typography, spatial composition, information architecture. |
| `/ai-docs` | Manages the documentation lifecycle: CHANGELOG, README, solution-intent architecture docs, external docs portals, and documentation quality gates. |
| `/ai-engineering-issue` | 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. |
| `/ai-explain` | Explains code, concepts, patterns, and architecture with engineer-grade depth: 3-tier control (brief/standard/deep), ASCII diagrams, execution traces, anchored to real file:line references. |
| `/ai-explore` | Codebase-only read-only research dispatcher. |
| `/ai-governance` | Validates framework compliance, ownership boundaries, risk acceptance lifecycle, and manifest integrity for regulated environments. |
| `/ai-ide-audit` | Audits an IDE end-to-end (instruction surface, hooks, skills, agents, installer wiring) using strict file-evidence — never assumptions. |
| `/ai-issue` | Creates a project work-item (issue / task / story) on the user's configured board: routes by manifest `work_items.provider` (GitHub Projects v2 or Azure DevOps), composes title + body + labels, attaches to the active board, and confirms a clickable link. |
| `/ai-learn` | Extracts lessons from merged PR review feedback by analyzing what reviewers caught, identifying missed checks, and writing entries directly to LESSONS.md. |
| `/ai-marketing` | Drives go-to-market execution and marketing content: blog posts for distribution, social crossposts, investor materials, market research, outreach campaigns, X/Twitter automation. |
| `/ai-mcp-audit` | Audits MCP servers and skills on demand using LLM coherence analysis to catch capability drift and rug-pulls. |
| `/ai-media` | Generates images, videos, and audio via AI models (fal-ai MCP): cheap iteration models, expensive production finals, cost-estimate before generation. |
| `/ai-note` | Saves persistent technical discoveries (debugging insights, non-obvious behaviors, workarounds, integration gotchas) and searches them across sessions. |
| `/ai-onboard` | Onboards humans to a project: architecture tours, topic search, decision archaeology, structured new-team-member orientation. |
| `/ai-pipeline` | Generates, evolves, and validates CI/CD pipelines for GitHub Actions or Azure Pipelines, enforcing SHA pinning, timeouts, secret handling, and concurrency policy. |
| `/ai-plan` | Decomposes an approved spec into a phased execution plan with bite-sized tasks, agent assignments, and gate criteria — the contract /ai-build executes. |
| `/ai-postmortem` | Documents production incidents, outages, degradations, and near-misses using the DERP format (Detection, Escalation, Recovery, Prevention) with targeted interview questions per phase. |
| `/ai-pr` | Creates and updates pull requests with governance: runs the commit pipeline, enforces pre-push gates, generates structured PR body from spec, watches and fixes CI until merged. |
| `/ai-prompt-tune` | Optimizes prompts, system messages, and skill descriptions using explicit-over-implicit, show-do-not-tell, and rationale-embedding techniques. |
| `/ai-prose` | Writes content (blog posts, pitch decks, sprint review summaries, architecture board reports, solution intent documents) with automatic audience targeting (developer/manager/executive). |
| `/ai-reliability-eval` | Measures AI system reliability over time by defining pass/fail criteria before implementation, running capability checks, and tracking regression via pass@k metrics. |
| `/ai-research` | External evidence with citations via a 4-tier escalation (local → free MCPs → web/Exa → NotebookLM autonomous deep research, launched first / harvested last). |
| `/ai-resolve-conflicts` | Resolves git conflicts intent-aware: categorizes by type (lock files, migrations, generated, config, code), regenerates or merges per category, never blindly accepts. |
| `/ai-review` | Reviews code changes with human-quality judgment: PR reviews, file reviews, diff analysis, architecture feedback. |
| `/ai-scaffold` | Creates new ai-engineering skills or agents end-to-end: scaffold, TDD pressure-test, optimize description, register in manifest, sync mirrors. |
| `/ai-schema` | Designs schemas, plans safe migrations with rollback scripts, optimizes slow queries with index recommendations, defines data retention and GDPR right-to-erasure policies. |
| `/ai-security` | Runs security gates: SAST with OWASP/CWE mapping, dependency vulnerability scans, secret detection, SBOM generation for compliance, pre-release security verdict. |
| `/ai-session-watch` | Observes session corrections, recoveries, and workflow patterns silently, then consolidates them into project-local observations on demand. |
| `/ai-simplify` | On-demand code simplification — guard clauses, method extraction, nesting flattening, dead code removal, conditional simplification. |
| `/ai-simplify-sweep` | Sweeps stale code complexity weekly via a scheduled /ai-simplify wrapper, gates the diff, and opens a draft PR for human review. |
| `/ai-skill-improve` | Improves an existing skill based on real project pain (prior eval corpora under .ai-engineering/evals/, Engram cross-session observations, LESSONS.md, decision-store, instincts, proposals) by analysing the failure pattern, rewriting SKILL.md, and emitting the proposed delta as a PR comment only — no auto-merge. |
| `/ai-slides` | Generates zero-dependency self-contained HTML presentations with keyboard/touch navigation and viewport-safe layout. |
| `/ai-spec-draft` | Produces a 14-section spec brief in `.ai-engineering/specs/drafts/<topic>-brief.md` so an operator can hand off a fully-researched problem statement to `/ai-brainstorm`. |
| `/ai-sprint` | Manages sprint lifecycle: plans a new sprint from backlog, runs data-driven retros comparing planned vs shipped, checks mid-sprint goal status, generates sprint review presentations. |
| `/ai-standup` | Generates standup notes and status updates from actual git commits and PRs — never reconstructed from memory. |
| `/ai-start` | Bootstraps a coding session: loads project context, activates session observation, displays a welcome dashboard with recent activity, board items, and available commands. |
| `/ai-support` | Investigates customer-reported issues with structure: reproduces, traces to code, documents resolution, builds a searchable knowledge base organized by ticket ID. |
| `/ai-test` | Writes tests, enforces TDD (RED-GREEN-REFACTOR), analyzes coverage gaps, defines test strategy across Python, TypeScript, .NET, Rust, Go. |
| `/ai-verify` | Use when verification with evidence is needed — not assumptions. |
| `/ai-video-editing` | Edits real video footage: cuts recordings into highlights, transcribes and structures raw footage, runs FFmpeg operations (trim, concat, reframe, normalize audio), creates Remotion overlays, prepares social-platform cuts. |
| `/ai-visual` | Produces static visual design artifacts (posters, banners, flyers, branding pieces, cover art, identity compositions) by composing aesthetic philosophies into HTML/SVG and rendering to PDF/PNG. |

### Agents (9)

Agents run in their own context window; dispatched by the skills above.

| Name | What it does |
| --- | --- |
| `ai-advise` | Proactive governance advisor. |
| `ai-autopilot` | Autonomous 6-phase orchestrator. |
| `ai-build` | Implementation coordinator. |
| `ai-explore` | Codebase-only read-only research. |
| `ai-onboard` | Project onboarding and teaching. |
| `ai-plan` | Relentless interrogator. |
| `ai-review` | Code review orchestrator. |
| `ai-simplify` | Code simplification and complexity reduction. |
| `ai-verify` | Evidence-first verification orchestrator. |

<!-- catalog:end -->

## Maintainer reference

This manual is the operator surface. The framework's internal contracts live in
their own canonical homes — read these when you need the plumbing, not the
day-to-day usage:

- [docs/persistence-doctrine.md](../docs/persistence-doctrine.md) — where every
  datum lives (the canonical three-tier, files-only persistence model) and the
  rebuild semantics for derived caches.
- [CONSTITUTION.md](../CONSTITUTION.md) — project identity, ownership
  boundaries, and the hard prohibitions every change must respect.
- [manifest.yml](manifest.yml) — the configuration source of truth (stacks,
  surfaces, retention, telemetry consent).

Update canonical sources, then regenerate the derived surfaces:

```bash
ai-eng dev sync
ai-eng dev sync --check
```
