# `.ai-engineering/`

Local governance root for an ai-engineering workspace. Specs, contexts, runbooks, state, and long-lived AI memory all live here.

See also: [README.md](../README.md) | [Getting Started](../GETTING_STARTED.md)

## Quick Reference

| Flow | Command |
|------|---------|
| Start a session | `/ai-start` |
| Define a feature | `/ai-brainstorm` then `/ai-plan` then `/ai-dispatch` then `/ai-verify` |
| Fix a bug | `/ai-debug` |
| Review changes | `/ai-review` |
| Ship it | `/ai-verify` then `/ai-pr` |
| Autonomous delivery | `/ai-autopilot` or `/ai-run` |
| Framework health | `ai-eng doctor` |

## Installed Shape

```text
.ai-engineering/
├── LESSONS.md          # persistent learning context
├── CONSTITUTION.md     # project constitution (team-managed)
├── manifest.yml        # framework configuration
├── contexts/           # language, framework, and team guidance
│   ├── languages/      # 14 language contexts
│   ├── frameworks/     # 15 framework contexts
│   ├── team/           # team-local conventions
│   ├── cli-ux.md       # shared CLI UX guidance
│   └── mcp-integrations.md
├── runbooks/           # 14 portable automation contracts
├── scripts/            # hook and helper scripts
│   └── hooks/
├── specs/              # active spec + plan workspace
│   ├── spec.md
│   ├── plan.md
│   ├── _history.md     # archived specs
│   └── autopilot/      # multi-spec decomposition
├── state/              # framework runtime state
│   ├── decision-store.json
│   ├── framework-events.ndjson
│   ├── framework-capabilities.json
│   ├── install-state.json
│   └── ownership-map.json
├── runs/               # autonomous execution state (lazy)
├── instincts/          # project instinct store (lazy)
├── reviews/            # review artifacts (lazy)
├── schemas/            # database/schema artifacts (lazy)
└── notes/              # notes from /ai-note (lazy)
```

## Directory Guide

| Path | Lifecycle | Purpose |
|------|-----------|---------|
| `contexts/` | seeded | Language, framework, and team guidance loaded by skills at runtime |
| `runs/` | generated | Autonomous run manifests, per-item specs/plans, and reports created by `/ai-run` |
| `runbooks/` | seeded | Self-contained Markdown automation contracts for intake and operational workflows |
| `scripts/` | seeded | Hook and helper scripts installed by the framework |
| `specs/` | seeded | Active `spec.md`, `plan.md`, history archive, and autopilot sub-specs |
| `state/` | seeded | Decisions, ownership zones, framework events, capability catalog, install metadata |
| `instincts/` | generated | Project-local instinct store regenerated by `/ai-instinct` and onboarding flows |
| `reviews/` | generated | Saved review reports from `/ai-review` workflows |
| `schemas/` | generated | Schema planning and migration artifacts from `/ai-schema` |
| `notes/` | lazy | Notes created by `/ai-note`; directory does not exist until first use |
| `LESSONS.md` | seeded | Persistent learning context updated by `/ai-learn` and user corrections |

## Ownership Model

### Framework-Managed

Refreshed by `ai-eng update`. Mirrors regenerated by `ai-eng sync`. Do not hand-edit these paths -- changes will be overwritten on the next update.

- `contexts/languages/**`
- `contexts/frameworks/**`
- Root contexts: `cli-ux.md`, `mcp-integrations.md`, `evidence-protocol.md`, `session-governance.md`, `spec-schema.md`, `stack-context.md`, `gather-activity-data.md`
- `runbooks/**`
- `scripts/**`

### Team-Managed

Owned by the project team. Never overwritten by framework updates.

- `contexts/team/**`
- `CONSTITUTION.md`
- `specs/**` (active product work)

### System-Generated

Written by the framework at runtime. Read these for observability; do not hand-edit.

- `state/decision-store.json`
- `state/framework-events.ndjson`
- `state/framework-capabilities.json`
- `state/install-state.json`
- `state/ownership-map.json`
- `instincts/**`
- Generated review and schema artifacts

## Context System

Contexts are Markdown files that skills auto-load at Step 0 based on the stacks declared in `manifest.yml`. Three families exist:

| Family | Path | Count | Scope |
|--------|------|-------|-------|
| Languages | `contexts/languages/` | 14 | bash, cpp, csharp, dart, go, java, javascript, kotlin, php, python, rust, sql, swift, typescript |
| Frameworks | `contexts/frameworks/` | 15 | android, api-design, aspnetcore, backend-patterns, bun, claude-api, deployment-patterns, django, flutter, ios, mcp-sdk, nextjs, nodejs, react, react-native |
| Team | `contexts/team/` | user-defined | Project-specific conventions, lessons, and norms |

**Loading precedence** (configured in `manifest.yml`):

```
team > frameworks > languages
```

When conventions conflict across layers, the first layer in the precedence list wins. Team conventions override framework guidance, which overrides language defaults.

Shared root contexts (`cli-ux.md`, `mcp-integrations.md`, etc.) are loaded when relevant to the task -- CLI work loads `cli-ux.md`, MCP/server usage loads `mcp-integrations.md`.

## Runbooks

All 14 runbooks live in `runbooks/`. Each is a single Markdown file with YAML frontmatter declaring `name`, `description`, `type`, and `cadence`.

| Runbook | Type | Cadence | Description |
|---------|------|---------|-------------|
| `triage` | intake | daily | Scan backlog, classify, prioritize |
| `refine` | intake | daily | Gather context, draft acceptance criteria, mark ready |
| `feature-scanner` | operational | daily | Detect spec-vs-code gaps |
| `stale-issues` | operational | daily | Label or close stale issues |
| `dependency-health` | operational | weekly | CVEs, outdated deps, licenses |
| `code-quality` | operational | weekly | Complexity, duplication, tech debt |
| `security-scan` | operational | weekly | Secrets, SAST, compliance |
| `docs-freshness` | operational | weekly | Stale docs, coverage gaps |
| `performance` | operational | weekly | Test and build regressions |
| `governance-drift` | operational | weekly | Framework alignment |
| `architecture-drift` | operational | weekly | Solution-intent deviations |
| `work-item-audit` | operational | weekly | Validate non-functional work items before consolidation |
| `consolidate` | operational | weekly | Group related items into consolidated tasks |
| `wiring-scanner` | operational | weekly | Disconnected code |

**Design principles:**

- **All HITL** -- runbooks prepare work items in the provider. They never touch code and never create PRs.
- **Dry-run by default** -- hosts must explicitly pass `--apply`, `--arm`, or `--live` to make changes.
- **Portable** -- the same runbook runs on Codex App Automation, Claude scheduled tasks, GitHub Agents, and Azure Foundry.
- **No adapter layer** -- each runbook is fully self-contained. No separate adapter files.

## Specs and Plans

`specs/` is the active working buffer for product work.

| File | Purpose |
|------|---------|
| `spec.md` | Active specification -- requirements, acceptance criteria, scope |
| `plan.md` | Execution plan with checkable tasks derived from the spec |
| `_history.md` | Archived specs appended after completion |

**Lifecycle:** `/ai-brainstorm` drafts or refines `spec.md`. `/ai-plan` breaks the approved spec into `plan.md`. `/ai-dispatch` executes the plan. On completion, the spec is archived to `_history.md`.

**Autopilot sub-specs:** When `/ai-autopilot` decomposes a large initiative, it creates:

```text
specs/autopilot/
├── manifest.md
└── sub-*/
    ├── spec.md
    └── plan.md
```

This sub-tree is project memory. It is not regenerated by `ai-eng sync`.

## Runs

`runs/` is created lazily by `/ai-run` for source-driven autonomous backlog execution.

```text
runs/<run-id>/
├── manifest.md
└── items/
    └── <item-id>/
        ├── spec.md
        ├── plan.md
        └── report.md
```

Unlike `specs/`, the `runs/` tree is not the shared human working buffer. It is durable state for autonomous execution, supporting pause and resume across sessions.

## State

All state files live in `state/`. They are system-generated and append-only or update-in-place.

| File | Format | Purpose |
|------|--------|---------|
| `decision-store.json` | JSON | Formal decisions and risk acceptances with auto-expiry dates. Used by gate checks to allow accepted risks to pass. |
| `framework-events.ndjson` | NDJSON | Append-only telemetry log. Skill invocations, agent dispatches, gate outcomes, governance events. |
| `framework-capabilities.json` | JSON | Registered agents, skills, contexts, and hooks. Regenerated on install/update. |
| `install-state.json` | JSON | Provider and tool install status. Tracks which providers and tools were installed and their versions. |
| `ownership-map.json` | JSON | File ownership zones mapping paths to framework-managed, team-managed, or system-generated. |

## Reviews, Notes, Instincts

These directories appear lazily -- a project using only a subset of skills should not carry every possible directory up front.

| Directory | Created by | Contents |
|-----------|------------|----------|
| `reviews/` | `/ai-review` | Persisted review reports and review-side artifacts |
| `notes/` | `/ai-note` | Free-form notes captured during development |
| `instincts/` | `/ai-instinct` | Project-local instinct store and bounded context, regenerated over time |

`LESSONS.md` is seeded at install time at the `.ai-engineering/` root. `/ai-learn` writes lessons directly to this file. It persists across sessions and is loaded at session start.

## CLI Commands

Framework maintenance commands. Run from the project root.

| Command | Purpose |
|---------|---------|
| `ai-eng doctor` | Diagnose framework health, fix issues with `--fix` |
| `ai-eng update` | Pull latest framework content (contexts, runbooks, scripts) |
| `ai-eng sync` | Regenerate provider mirrors (`.claude/`, `.codex/`, `.gemini/`, `.github/`) |
| `ai-eng validate` | Validate manifest, state files, and structural integrity |
| `ai-eng gate <phase>` | Run git hook quality gate checks (`pre-commit`, `commit-msg`, `pre-push`, `risk-check`, `all`) |
| `ai-eng spec verify` | Verify spec counters and consistency |
| `ai-eng spec list` | Show current active spec |
| `ai-eng decision list` | List recorded decisions from the decision store |
| `ai-eng decision record` | Record a new decision or risk acceptance |
| `ai-eng decision expire-check` | Check for expired decisions |

## Slash Commands

Day-to-day workflow commands invoked inside your IDE's AI assistant.

| Command | Purpose |
|---------|---------|
| `/ai-start` | Initialize a session -- loads lessons, manifest, decision store |
| `/ai-brainstorm` | Define or refine a spec interactively |
| `/ai-plan` | Break an approved spec into an execution plan |
| `/ai-dispatch` | Execute a single approved plan |
| `/ai-code` | Implement a focused coding task |
| `/ai-test` | Write, run, or plan tests |
| `/ai-debug` | Reproduce, isolate, and fix a bug |
| `/ai-autopilot` | Execute a multi-spec DAG autonomously |
| `/ai-run` | Execute a source-driven autonomous backlog run |
| `/ai-review` | Run multi-agent narrative code review |
| `/ai-verify` | Prove quality, security, and completeness with evidence |
| `/ai-commit` | Stage, validate, and commit changes |
| `/ai-pr` | Create a pull request with structured description |

## Mirrors Outside This Folder

The framework writes provider-specific surfaces next to `.ai-engineering/` in the project root.

| Path | Purpose |
|------|---------|
| `.claude/skills/` and `.claude/agents/` | Claude Code skills and agents |
| `.codex/skills/` and `.codex/agents/` | Codex CLI skills and agents |
| `.gemini/skills/` and `.gemini/agents/` | Gemini CLI skills and agents |
| `.github/skills/` and `.github/agents/` | GitHub Copilot skills and agents |
| `CLAUDE.md` | Claude Code instruction file |
| `AGENTS.md` | Codex / GitHub Copilot instruction file |
| `GEMINI.md` | Gemini CLI instruction file |

These mirrors are generated artifacts. Use `ai-eng sync` to regenerate them after framework changes. Do not hand-edit -- changes will be overwritten on the next sync.
