# `.ai/` — Second Brain

This folder is your project's persistent memory for the `flow` plugin. Plans, decisions, reviews, snapshots, and scenario evidence live here. Commands read from it; subagents write to it.

## Top-level layout

| Folder | Owner command | Purpose |
| ------ | ------------- | ------- |
| `state/` | `/flow:status`, `/flow:pause`, `/flow:resume` | Single source of truth for current workflow phase. `STATE.md` is durable; `HANDOFF.md` is transient (created on pause, deleted on resume). |
| `plans/` | `/flow:plan`, `/flow:execute` | Feature plans with task lists. `archive/` holds completed plans. |
| `decisions/` | `/flow:record-ddr` | Design Decision Records. Append-only, numbered, never deleted. |
| `reviews/` | `/flow:review-code`, `/flow:record-retro` | Code review snapshots and retrospective notes from completed work. |
| `scenarios/` | `/flow:scenario` | Cross-platform UI scenario specs + per-run report folders (screenshots, evidence). `_lib/` holds shared helpers. |
| `logs/` | `/flow:validate`, `/flow:maintain-ai-health` | System-level audit logs (validation runs, infrastructure reviews). |
| `dev-logs/` | manual | Dev journal — free-form notes, links, scratchpad. Optional. |
| `browser/` | `agent-browser` skill | Web automation evidence — DOM snapshots, HAR captures. |
| `device/` | `agent-device` skill | Native device automation evidence — accessibility snapshots, screenshots, traces. |
| `context/` | `/flow:setup-codebase-map`, `/flow:setup-context` | Living snapshots of codebase architecture (auto-generated, refresh periodically). |
| `business/` | manual | Domain knowledge, glossary, stakeholders, personas. Hand-curated. |
| `docs/` | manual | Internal design docs, patterns, ADR-adjacent prose. |
| `design-import/` | `/design:handoff` (design plugin) | Canvas artifacts in transit from `.design/` to production code. |
| `templates/` | manual | Copy-paste starters for plans, reviews, etc. |

## Per-project files

These live at the root of `.ai/` (not in subfolders) and are referenced by `workflows.config.json` → `paths`:

- `<name>-prd.md` — product requirements / brief
- `<name>-design-system.md` — design system reference (look & feel, tokens, density)
- `workflows.config.json` — config consumed by all flow commands and skills. The optional top-level `quality` map (lint / format / typecheck / tests / build → shell command) is **not** scaffolded here — run `maude doctor --fix` once your `package.json` scripts exist and it detects + adds them (additive, never overwrites your edits).

## Conventions

- **Append-only history.** Decisions, reviews, scenario reports — never delete, only supersede.
- **Filename = identity.** Match the slug of the work (e.g. `plans/onboarding-flow.md`, `decisions/DDR-007-edge-runtime.md`).
- **Date-stamped reports.** Scenario runs go in `scenarios/<scenario-id>/<YYYY-MM-DD-HHMM>/report.md`.
- **`<project>` placeholder.** Commands resolve `<project>` from `workflows.config.json` → `name`.

## Bootstrapping

Run `maude init` from your repo root to scaffold this skeleton (idempotent — never overwrites). Then run Anthropic's built-in `/init` to generate `CLAUDE.md` (conventions, build commands, project rules — auto-loaded every session), and create `.ai/<name>-prd.md` with your product brief.

> Note: `maude init` does not write `CLAUDE.md` itself — that's `/init`'s job. The split:
>
> - **`CLAUDE.md`** — prose Claude reads every session (conventions, gotchas, "always do X"). Generated by `/init`. Target under 200 lines.
> - **`.ai/workflows.config.json`** — structured machine-readable knobs. Scaffolded by `maude init`. Populated further by `/flow:init`.