Skip to content

lukedj78/dev-flow / prd-to-tasks

prd-to-tasks

Verified

Break down a PRD.md into a concrete, executable `tasks.md` checklist that a developer or an AI agent can pick up and ship. Reads `.workflow/PRD.md` (and `.workflow/PROJECT.md` for context), produces `.workflow/tasks.md` with one task per checkable bullet, grouped by user story or epic, sized to ~2–8 hours each. Output is compatible with beads, GitHub Issues import, `scrum` (Linear, Jira or GitHub), and ralph-tui task sources. Use when the user says "split this into tasks", "make the issues", "ticket the PRD", "task breakdown", "create the issues from the PRD", or the orchestrator routes here from phase `prd_drafted`. Not for: writing code or implementing the tasks (those run later).

FileKindSize
SKILL.mdskill md8.2 KB
references/contracts.mdmarkdown105.8 KB

references/contracts.md

View on GitHub
# `.workflow/` — Contract between dev-flow skills

This document defines the **canonical contract** that all skills in the dev-flow family must respect. It is the load-bearing piece of the architecture: skills know nothing about each other, but they all read and write `.workflow/` in the same way.

> Living version: this file. Skills that need to consult the contract should read **this exact file** (vendor a copy into their `references/` if standalone) — do not paraphrase from memory.

## Knowledge principle — doc-grounded, never invent (rule zero)

The skills are a **second brain**: authoritative, doc-grounded knowledge of the domains we build in, so we act as **experts and never improvise an API**. This governs how every skill is written and used:

1. **Never invent.** Do not guess an API, flag, config shape, file path, or command. If the skill states it, it must be **grounded in the official documentation** (or the installed source, e.g. `node_modules/<pkg>`), not memory.
2. **Prefer the version-matched source the tool itself gives you.** Upstreams increasingly ship their docs *to* the agent: `next dev` writes and maintains a version-matched `AGENTS.md` block pointing at the docs bundled in `node_modules`, and eve ships its docs at `node_modules/eve/docs/`. Read those first — they match the installed version, which a web page may not. (Vercel retired its own doc-shipping skills once this landed; the lesson for us is that **a skill must encode workflow and conventions, never a frozen copy of someone's documentation** — that part rots.) ⚠️ **Don't clobber that block**: `next dev` upserts it into the project's `AGENTS.md` *and* `CLAUDE.md` between `<!-- BEGIN:nextjs-agent-rules -->` markers and preserves everything outside them — so any dev-flow bootstrap file **merges**, never overwrites, and never edits inside the markers. (`create-next-app` generates both files; `agentRules: false` opts out.)
3. **If we don't have the knowledge, get it.** When a skill says "use library X", it must also document **how** — the real setup + usage from X's official docs — so we don't scaffold something wrong and redo it later. A bare "use X" without the how-to is an incomplete skill. When the knowledge isn't in the skill yet, consult the official online docs *before* writing code, then capture what you learned back into the skill.
4. **Mark the moving surface `[VERIFY]`.** Any identifier from a fast-moving or beta upstream (eve, next-intl, shadcn CLI, Expo SDK, Motion, Stripe apiVersion, …) carries a `[VERIFY]` note to check against the installed version — because docs move (e.g. **Next 16** deprecated `middleware.ts` in favour of `proxy.ts` — and note it was *Next*, not next-intl: the `next-intl/middleware` subpath never renamed, which is exactly the kind of misattribution a `[VERIFY]` is meant to catch). **And when the `[VERIFY]` is about a *default* or about *what leaves the machine*, verify it against the shipped artefact, not the page**: `npm pack <pkg>@<version>` needs no install and carries the compiled `dist`, the `.d.ts`, `engines`, `peerDependencies`, the `exports` map and usually the `CHANGELOG`. A page states the intent; the `dist` states the behaviour, and the `dist` is what reaches the customer. Measured on 2026-10-04: a documented "exports by default" turned out to be metadata-only, because the content ceiling lived in a type comment two pages from the sentence — see `dev-flow/references/before-you-build.md` §Shipped source outranks the prose.
5. **Update periodically.** Upstreams change; the knowledge base must keep pace. Run the ecosystem watch (`docs/vercel-changelog-watch.md` and the per-skill audit recipes) on a cadence, apply what changed, and log it. Stale docs-grounding is a bug.

Reference material (`references/*.md`) exists to satisfy #3 — every "use X" default in this contract points at a doc-grounded how-to, not just a name. **`docs/knowledge-index.md` is the map of them all**: which domains we're expert in, where each how-to lives, and which upstream to re-verify when it moves. Read it before wiring a library; walk it when running a periodic refresh; **add a row whenever you introduce a new "use X" default**.

## Golden rules (all projects, all stacks)

Three non-negotiable rules every dev-flow skill follows, regardless of the user's or team's spoken language. They are not checked the same way, and each says how: **rule 3 is enforced by tools** (the design lint, the write-time guard, `set-phase`); **rules 1 and 2 are checked in review** — `spec-review`'s Standards axis — and no tool catches a breach of either. (This line used to say every skill *enforces* all three.)

1. **Code is written in English.** Every code identifier — functions, variables, constants, types, enums, file/folder names, DB columns, API field names, commit messages — **and all code comments** are in English, always. This holds even when the user converses in another language (e.g. Italian): the conversation language and the code language are independent. English code stays portable, greppable, and consistent across contributors and tools. The one thing that is *not* English-by-default is **user-facing copy** — that goes through i18n (rule 2), never hardcoded.
   - **Checked by:** review only (`spec-review`, Standards axis). No lint rule enforces it: an identifier or a comment in another language passes every tool dev-flow installs.

2. **Every frontend ships i18n from day one.** No user-facing string is ever hardcoded; all visible copy (labels, buttons, errors, empty states, emails) routes through i18n keys. The minimum locale set is **English + Italian** (`stack.locales = ["en", "it"]`, default locale `en`); a project may declare more, decided per project. The library:
   - **Web (Next.js App Router)** → **[next-intl](https://next-intl.dev/)** (`stack.i18n = "next-intl"`), the canonical default. **The doc-grounded how-to is `design-md-to-app/references/i18n-next-intl.md`** (routing vs no-routing modes, `routing.ts`/`navigation.ts`/`proxy.ts`/`request.ts`, `[locale]` layout with `setRequestLocale` + `generateStaticParams`, `messages/{en,it}.json`, server vs client usage) — read it, don't reinvent the setup. Wired at scaffold time by `design-md-to-app`; the `forms` skill routes all form copy through it.
   - **Mobile (Expo/RN)** → the RN i18n stack (e.g. `i18next` + `expo-localization`) — next-intl is web-only.
   Record both `stack.i18n` and `stack.locales` in `meta.json`. Adding i18n later touches every screen, so it is set up **at scaffold**, not deferred.
   - **Checked by:** the scaffold, which wires the i18n library and records `stack.i18n` / `stack.locales`, then review (`spec-review`, Standards axis). No lint rule catches a hardcoded string — the design-lint preset does not include one (`react/jsx-no-literals` or an equivalent) — so a literal in JSX passes the lint.

3. **UI is composed only from the chosen library's primitives.** For shadcn: components installed with the shadcn CLI into `components/ui/`, customised only through DESIGN.md tokens and `cva` variants. Domain components are compositions of those primitives. Never hand-roll a primitive the library already ships (sidebar, dialog, sheet, tooltip, popover, combobox, date picker, table, tabs, toast, skeleton, empty state, field/input…), never add a second component library, never fork a primitive's behaviour. If no primitive fits, compose existing ones; a truly new primitive requires an explicit, recorded exception (ADR or `meta.json` note) with the reason. Same rule for MUI, Base UI standalone, Coss/UI and, on mobile, the RN/NativeWind component stack declared in `meta.json#stack`.
   - **Before writing a component, look for the primitive.** Search `components/ui/` (in a shadcn monorepo `packages/ui/src/components/`; MUI and standalone Base UI: the library's component list; mobile: React Native / Expo core components plus what `meta.json#stack` declares, and `components/shared/`) for one that covers the pattern. If it is there, use it; if two together cover it, compose them.
   - **Primitives are installed at `scaffolded`, all of them** — `shadcn add --all` (Coss/UI: its full `@coss/*` set, via `coss-ui`), so "the primitive isn't installed" is never a reason to write one. A primitive missing later is added with the library's CLI, never re-created by hand. ⚠️ **`--all` means "all that the index lists", which is not all that ships** — verified 2026-10-17, the index carries 61 `registry:ui` items while `trace`, `code-block` and `use-highlighted-code` install by name and are absent from it. So the rule stands with one extra step: **before writing a component by hand, ask the registry by name** (`pnpm dlx shadcn@latest view <name>`) rather than trusting that `--all` would have brought it. `design-md-to-app` tops the scaffold up with the known gap; a missing primitive is still never a reason to hand-roll one.
   - **`components/ui/` files change only in their `cva` variants and token classes** — not their markup, handlers, state or accessibility wiring. That is where a primitive is tuned to the design; a behaviour change there is a fork.
   - **The primitive renders the design.** Every piece of UI is a primitive from `components/ui/`. When the board (wireframe, screenshot, Figma) or a screen the user already approved differs from the primitive — a radius, a border instead of a ring, a hover tint, a selected background, a font weight, a padding — **the primitive is tuned**: its `cva` variants and the DESIGN.md tokens it reads change until it renders the design, **verified pixel by pixel**. A visual drift is never accepted, an element is never written by hand, and the look is never rebuilt with classes at the call site. A new variant goes into DESIGN.md first, then into the primitive's `cva`. **The board changes only when the user decides to change the design.**
   - **Why the primitive is tuned and not the board (smart-travel, 2026-10-12):** the first version of this rule said «the primitive wins, the board is corrected». Converting the 238 hand-made elements below to primitives used as they ship changed the screens — radii, selected backgrounds, weights, padding — and the user rejected them. The approved design is the target; the primitive is how it gets rendered.
   - **Converting existing screens proves parity.** Before a screen is converted to primitives (a retrofit, a hand-made element replaced), screenshot it at every width and state the board has; after, screenshot it again and **diff the two pixel by pixel** with `design-md-to-app/scripts/pixel_diff.py before.png after.png` — stdlib only, nothing to install, exit 1 on any changed pixel, and it **refuses two screenshots of different sizes instead of scaling them**, because a screen that grew taller is the regression a retrofit causes and scaling hides it. (`pixelmatch` or ImageMagick `compare -metric AE` do the same job if they are already in the project.) A non-zero diff is fixed by tuning the primitive — never accepted, never patched with call-site classes. A diff that the user wants is a design change, and the board changes with it.
   - **A hand-made element is a violation even with no import at all.** A `<button>`, `<label>`, `<input>`, `<a>`, `<hr>`, `<img>`, `<details>`, `<table>` written in app code, a hand-written ARIA role (`tab`, `radio`, `menu`, `switch`…), or a `<div>`/`<span>` whose classes redraw a Card, Badge, Alert or Separator, breaks this rule exactly as importing a second library does. Allowed raw, and only these: an element passed as a primitive's `render` (or the child of `asChild`); an `<a>` styled by `buttonVariants` (download, `tel:`, `mailto:`); a hidden or file input; an `sr-only` data table; a file that renders no DOM (`next/og`, react-email, react-pdf); an exception recorded in the preset's `designExceptions` with its reason (e.g. map marks drawn inside MapLibre).
   - **A missing variant is added, not worked around.** When no existing variant renders the design, add one: first in DESIGN.md (`components` block), then in the primitive's `cva`, and say in the report which variant was added. When no primitive covers the pattern at all, or rendering the design would need a change to the primitive's markup or behaviour (a fork), the agent **stops and asks the user**. A missing variant never authorises an element by hand, a restyle with classes at the call site, or an `eslint-disable`. Pattern → primitive table: `design-md-to-app/references/primitives-first.md`, read before writing any component.
   - **Every web project with a Tailwind UI (shadcn, base-ui, coss) has the write-time guard**: Claude Code hooks in `.claude/settings.json` running `scripts/guard/primitives-guard.mjs`, which refuse a Write/Edit that adds hand-made UI (PreToolUse), report it right after a shell command that wrote it (Pre/PostToolUse on Bash, checking only the files the command touched), and stop an agent or subagent that added it through the shell (Stop / SubagentStop). Installed at scaffold by `design-md-to-app` (`setup_design_lint.py`, which calls `setup_primitives_guard.py`), recorded as `stack.primitives_guard`. A project already started gets it with the same one command (the retrofit).
   - **Why (smart-travel, 2026-10-12):** three days of building behind a green lint produced 238 hand-made elements where a primitive existed — 84 div-cards, 62 `<button>`, 34 `<label>`, 22 alert boxes, 14 `<a>`, 11 span-badges. The rule existed only as text; a raw element imports nothing, so the import bans could not see it; `shadcn/no-restyle` made writing the element by hand the easiest way around a board that did not match a variant (tuning the variant was the way); 57 of 71 buttons came in one night of parallel agents copying the neighbouring file; `meta.json#phase` was still `design_extracted`, so no check was ever proposed; and every verification was visual. **A green lint and a screenshot that matches the board are not proof of conformity** — a hand-made button identical to the board passes both. Conformity needs both halves: `design/no-handmade-ui` at zero, and the pixel diff at zero.
   - **The exception record.** An ADR in `docs/adr/` or an entry in `meta.json#stack_config.primitive_exceptions`: `{ "component": "<Name>", "path": "<file>", "reason": "<why no primitive or composition fits>", "recorded_at": "<ISO-8601>" }`, mirrored in the preset's `designExceptions` when it turns the rule off for a file. An exception without a reason is not an exception.
   - **Enforced by:** the design-system lint — `design/no-handmade-ui` at `error` (raw elements, hand-written roles, classes that redraw a primitive, each with the primitive to use) and `design/no-card-in-card`, plus `no-restricted-imports` on undeclared component libraries and on the primitives' headless bases (`radix-ui`, `@base-ui/react`, `cmdk`, `vaul`…) outside `components/ui/`, all written by `design-md-to-app/scripts/setup_design_lint.py`; the **write-time guard** above; `update_meta.py set-phase`, which refuses `scaffolded` **and every later phase** without the rule and the guard; `spec-review`'s Standards axis on every diff (four checks, the fourth a lint/grep for raw elements); `shadscan`'s gate; and — for the second half, which until 2026-11-11 was a sentence with no tool behind it — `pixel_diff.py`.
   - **Open gap — mobile (`expo-rn`, NativeWind):** no equivalent rule or guard exists yet. A hand-made `Pressable` + `View` styled as a button, or a `View` with NativeWind classes drawn as a card, is the same violation and nothing catches it. It has to be built (the same guard over the RN component set); until then, `spec-review` checks it by reading.

Rules 1–2 are recorded in the `stack` block (`i18n`, `locales`) and treated as defaults, not questions — skip asking; only confirm extra locales beyond en/it. Rule 3 is recorded through `stack.ui` (and `ui_base`, `shadcn_preset`): the library a project declares is the only one it composes.

### Recommended default libraries (ecosystem-first)

When a project needs one of these capabilities, reach for the default below instead of hand-rolling or picking ad-hoc — the same ecosystem-first rule used everywhere in dev-flow. Not every project needs them; these are the defaults **when** it does.

| Capability | Web default | Mobile default |
|---|---|---|
| **Maps** | **[mapcn](https://mapcn.dev/)** — MapLibre GL, shadcn-registry. How-to: `design-md-to-app/references/maps-mapcn.md` (⚠️ CARTO default tiles need an Enterprise license for commercial use). `stack.maps = "mapcn"`. | **[mapcn-rn](https://mapcn-rn.dev/)** — MapLibre/Mapbox RN + NativeWind. How-to: `rn-components-apis/references/maps-mapcn-rn.md` (⚠️ native modules → dev build, not Expo Go). `stack.maps = "mapcn-rn"`. |
| **File / blob storage** | **Vercel Blob** (`@vercel/blob`) when deploying to Vercel — same platform, one less sub-processor. UploadThing / S3 only on request. How-to: `module-add/references/module-storage.md`. `stack.storage = "vercel-blob"`. | provider-side (`supabase` / `firebase` / custom) via `rn-module-add` |
| **Illustration / spot art** | **[Koboyo](https://koboyo.com/icons)** — 71k hand-drawn SVGs, free commercially, found via its MCP server. ⚠️ **Use sparingly and only when DESIGN.md admits it**; the licence forbids products where the art *is* the feature. How-to: `design-md-to-app/references/illustrations.md`. | same source, vendored as SVG |
| **Animated icons** | `animated-icons` (skill) | `rn-animations-gestures` |
| **Motion** | `transitions` + `module-add motion` | `rn-animations-gestures` |
| **Node graphs** | **[React Flow](https://reactflow.dev)** (`@xyflow/react`, MIT) — only for a graph the user acts on; nodes from shadcn primitives or React Flow UI (via `registry-intake`). How-to: `design-md-to-app/references/react-flow.md`. `stack.graphs = "react-flow"` | — (no RN equivalent) |
| **WebGPU shaders** | `vgpu-shaders` (`stack.shaders`) — `transitions`' Tier 4, MIT, first-party skill for the API | — (no WebGPU rung on RN) |
| **Documents → Markdown** | [`anydoc`](https://github.com/firecrawl/anydoc) (Firecrawl, MIT) — `.docx`/`.pptx`/`.xlsx`/`.pdf`/ODF/RTF/EPUB/CSV, **converted locally**; first-party skill `npx skills add firecrawl/anydoc`. ⚠️ `--ocr hosted` sends the **whole** document to a third party — an R3 transfer decision, not a flag | same CLI |
| **Forms** | `forms` (`stack.forms`) | RN form stack |
| **Design-system lint** | **[`@shadcn/lint`](https://github.com/shadcn-ui/lint)** (`stack.design_lint`) — errors that name the token or variant to use; `error` from day one on a scaffold. How-to: `design-md-to-app/references/design-system-lint.md`. | — (no RN equivalent) |
| **EU data residency** | `dev-flow/references/eu-data-sovereignty.md` — per service: default, EU region to set, European alternative, with sources and dates. `stack.data_residency`; register in `docs/compliance/subprocessors.md` | same reference (Supabase / Firebase regions, push relay, purchases) |
| **Third-party registries** | `registry-intake` (`stack.registry_intake`) — allowlist, review, hashed snapshot, PreToolUse hook; wired at scaffold, checked by `set-phase`. Covers every shadcn-format registry (pdfcn, emailcn, mcpcn, agentcn, evex…) and `eve add @ns/…` | — (RN has no shadcn registry) |
| **Measurement (opt-in)** | three levels, each on request: **traffic** = Vercel Web Analytics + Speed Insights; **product** = own-database events + activation/D7/D30 SQL; **advanced** = PostHog EU, or OpenPanel for `eu-sovereign`. Vercel Analytics and Plausible cannot do D7/D30 retention. How-to: `module-add/references/module-analytics.md`. `stack.analytics` | no traffic level; product per backend, advanced with `posthog-react-native` via `rn-module-add analytics` |
| **Content / headless CMS** | **Sanity** via `next-sanity` — `module-add cms`; how-to `module-add/references/module-cms.md`. The hosted Studio is the editors' admin panel. `stack.cms = "sanity"` | **Sanity** over the HTTP Query API (plain `fetch`, no SDK in the bundle) — `rn-module-add cms`; how-to `rn-module-add/references/module-cms-sanity.md`. Same `cms/` Studio package as web in a monorepo |

Per the **Knowledge principle**, each of these defaults must ship (or point at) a **doc-grounded how-to** — not just a name — before it's used to scaffold; `[VERIFY]` install command + license + API against the official site each time (docs move). These are starting defaults; a project may override with a documented reason.

## Folder layout

A "dev-flow project" is a **standard codebase root** (the directory that contains `package.json`, your framework files, your git repo) with a `.workflow/` overlay holding planning + design metadata. The codebase lives at the top, not nested inside `.workflow/`.

```
<project-root>/                   # ← standard codebase root (Next/Vite/Remix/etc.)
├── .workflow/                    # ← planning + design metadata only
│   ├── meta.json                 # required, machine-readable state
│   ├── PROJECT.md                # high-level idea, audience, success criteria
│   ├── PRD.md                    # product requirements
│   ├── tasks.md                  # task breakdown, beads/issues compatible
│   ├── DESIGN.md                 # design system per Google design.md spec
│   ├── screenshots/              # raw or annotated UI references
│   │   └── *.{png,jpg}
│   ├── founder/                  # only on the founder path (founder-intelligence), absent otherwise
│   │   ├── founder-playbook.md   # the strategic document the founder approves
│   │   ├── sources.md            # evidence register: URL, date read, what it supports, decisions that depend on it
│   │   ├── interviews/NN-<who>.md  # notes of real interviews, written or pasted by the founder
│   │   └── handoff.md            # existing projects only: proposed PRD/scope/metric changes for dev-flow
│   └── decisions/                # ADR-style decisions, one per file (optional)
│       └── 0001-stack.md
├── docs/wireframes/              # ← screen-inventory.md + png/<ID>-{desktop,phone}.png (wireframe-canvas)
├── package.json                  # ← codebase lives at the root
├── app/, components/, lib/       # ← framework conventions, untouched
├── registry.json                 # ← shadcn registry (when applicable), at root
├── drizzle.config.ts             # ← config files at root
├── cms/                          # ← Sanity Studio package when stack.cms = "sanity" (own package.json; excluded from the app's bundler)
└── ...                           # ← anything else the framework expects
```

**Rules**:
- `.workflow/` is the **only** dev-flow-owned directory. Everything outside it is the framework's territory — skills modify framework files only when their scope says so (e.g., `design-md-to-app` writes `package.json` and `app/`, but doesn't put anything in `.workflow/` except updating `meta.json`).
- The codebase is at the project root. **No `app/` inside `.workflow/`.** This means `cd <project-root> && pnpm dev` works the way every developer expects.
- Files are written incrementally. A skill writes only the files in its scope. It must **not** delete files written by other skills.
- `meta.json` is the single source of truth for the project's current state. Every skill that runs must read `meta.json` first and update it last.
- All file names are case-sensitive and exact: `PROJECT.md` (not `project.md`), `PRD.md`, `DESIGN.md` (uppercase per Google spec), `tasks.md`, `meta.json`.

### Bootstrapping order

The codebase doesn't exist until `design-md-to-app` runs. Until then, the project root contains only `.workflow/` (and possibly a `.git/` if the user initialized one). When `design-md-to-app` runs `pnpm create next-app .` (or equivalent) it scaffolds **into the project root**, alongside `.workflow/`. `.workflow/` does not interfere with framework scaffolders because no file there clashes with their expected entry-points (`package.json`, `app/`, `src/`, `vite.config.ts`, etc.).

## `meta.json` schema

```json
{
  "project_slug": "aetherfield",
  "project_name": "Aetherfield",
  "created_at": "2026-04-25T14:00:00Z",
  "updated_at": "2026-04-25T15:30:00Z",
  "phase": "design_extracted",
  "contract_version": 1,
  "meta_digest": { "sha256": "9f2c…", "checked_phase": "design_extracted" },
  "stack": {
    "framework": "next",
    "ui": "shadcn",
    "auth": "better-auth",
    "db": "neon-drizzle",
    "payments": null,
    "deploy": "vercel",
    "agent": null
  },
  "artifacts": {
    ".workflow/DESIGN.md": {
      "sha256": "abc123…",
      "produced_by": "figma-to-design-md",
      "produced_at": "2026-04-25T14:30:00Z"
    },
    "registry.json": {
      "sha256": "def456…",
      "produced_by": "design-md-to-app",
      "produced_at": "2026-04-25T15:30:00Z",
      "derived_from": [
        { "path": ".workflow/DESIGN.md", "sha256": "abc123…" }
      ]
    }
  },
  "history": [
    {
      "skill": "prd-from-idea",
      "ran_at": "2026-04-25T14:00:00Z",
      "outputs": ["PROJECT.md", "PRD.md"],
      "phase_before": "empty",
      "phase_after": "prd_drafted"
    },
    {
      "skill": "figma-to-design-md",
      "ran_at": "2026-04-25T14:30:00Z",
      "inputs": {"figma_url": "https://..."},
      "outputs": ["DESIGN.md", "screenshots/"],
      "phase_before": "prd_drafted",
      "phase_after": "design_extracted"
    }
  ]
}
```

### `artifacts` field

Tracks every contract-shaped file with its content hash and provenance. The model is content-addressed: an artifact entry says "skill X wrote this file with this exact content at time T". When the on-disk hash later differs from the recorded one, the artifact is **stale** and the producing skill (or the user) needs to decide what to do.

Each entry:
- `sha256` — hex digest of the file's bytes at write time.
- `produced_by` — the skill name that last wrote (or rewrote) this file.
- `produced_at` — ISO-8601 timestamp.
- `derived_from` (optional) — list of `{path, sha256}` pairs. Each entry is an upstream input the skill used to derive this artifact, snapshotted at the version it was at when this artifact was produced. Used by `check_drift.py` to detect upstream-stale artifacts (output file is unchanged on disk but a `derived_from` input has drifted — common case: user edited `DESIGN.md` after `design-md-to-app` ran, so `registry.json` is now derived from a stale snapshot).

Skills update this via `dev-flow/scripts/update_meta.py record-artifact …`. The `check_drift.py` script reports which artifacts are fresh / self-drift / upstream-stale / missing — diagnostic only, never mutating.

The `artifacts` field is the foundation for resumability and drift detection: re-running a skill is safe if all its inputs are fresh; necessary if any are stale.

### `tracker` and `scrum` fields (optional, owned by `scrum`)

The project's tracker — chosen at design time by `prd-from-idea` (`provider` alone), filled by the `scrum` skill at
Setup. Written only by `scrum/scripts/meta_tracker.py` (through `meta_io`'s lock) and `scrum/scripts/github_sync.py`;
other skills read it and must not write it.

```json
"tracker": {
  "provider": "linear | jira | github",
  "project": { "team_id": "…", "team_name": "…", "project_id": "…" },
  "url": "…",
  "issue_map": { "<task_key>": "LUC-123 | ABC-123 | #123" },
  "unmatched": { "<old title>": "#45" },
  "last_synced_at": "<ISO-8601 UTC>"
},
"scrum": {
  "cadence_weeks": 2, "estimate_scale": "fibonacci", "velocity_target": null,
  "states": { "backlog": "Backlog", "todo": "Todo", "in_progress": "In Progress",
              "in_review": "In Review", "done": "Done", "blocked_label": "blocked" },
  "labels": { "web": "frontend", "agent": "agent-eve", "scaffold": "setup" },
  "severity_labels": { "S1": "severity: S1", "S2": "severity: S2", "S3": "severity: S3", "S4": "severity: S4" },
  "bug_label": "bug"
}
```

`project` holds the tracker's own ids: `team_id` / `team_name` / `project_id` (Linear), `site` / `project_key` /
`board_id` (Jira), `repo` (GitHub). `issue_map` keys are `task_key()` digests of `tasks.md` lines (see
`scrum/scripts/task_key.py`) so re-syncing never duplicates issues; `unmatched` keeps old title-keyed entries whose
title is no longer in `tasks.md`. The tracker is the source of truth for status/ordering/estimates after Setup;
`tasks.md` stays the append-only intake for new work; bugs go straight to the tracker (`scrum` Triage, severity
S1–S4). On GitHub a sprint is a milestone named by its goal and every issue carries `priority: Pn`.

**Older shapes** — the `linear` block written by the former `linear-scrum`, and hand-written blocks with `kind`, `repo`, a map
keyed by task title (inline or in `.workflow/github-issues.json`) or a nested `scrum` — stay readable and are
migrated by `meta_tracker.py migrate` without dropping a key; `show_state.py` notes them until then. A migrated block keeps its other keys verbatim (`map`, `bodies`, `issues`, a `linear` opt-out note, …), and a
`linear` block found under another provider is kept apart in `legacy_linear`.

### `wireframes` field (optional, owned by `wireframe-canvas`)

Every project with a UI draws all its screens before any code is scaffolded (the user's standing rule, 2026-10-10): a screen inventory mapped to the PRD's `US-N` stories, then one desktop (1440) and one phone (390) artboard per screen on a claude.ai Design canvas, reviewed area by area and approved by the user. Written only through `wireframe-canvas/scripts/wireframes.py`:

```json
"wireframes": {
  "canvas_url": "https://claude.ai/…", "inventory": "docs/wireframes/screen-inventory.md",
  "screens": 24, "artboards": 48,
  "approved_at": "<ISO-8601 UTC>", "approved_by_user": true, "approval_quote": "<the user's words>",
  "screenshots_posted_at": "<ISO-8601 UTC>" | null
}
```

The opt-out is `{ "skipped": true, "reason": "<sentence>" }`; a skip without a reason does not count. **`update_meta.py set-phase` (and `append-history --phase-after`) refuses to cross into `monorepo_initialized` or `scaffolded` while the block is missing, unapproved, short of two artboards per screen, or pointing at an inventory that is not on disk** (`dev-flow/scripts/wireframes_gate.py`). Projects already past that point are not blocked; `show_state.py` flags them, and flags an approved canvas whose screenshots are not yet on the issues. Agent-only projects (`framework: "agent"`) are not affected. After approval the PNGs live in `docs/wireframes/png/<ID>-desktop.png` / `<ID>-phone.png` and are commented on every tracker issue whose story maps to the screen.

### `inventory` field (owned by `dev-flow/scripts/inventory.py`)

"Does this already exist?" answered before any PRD: in the house, in tools already paid for, in the Claude ecosystem, outside (`dev-flow/references/before-you-build.md`). Written only through `inventory.py record`:

```json
"inventory": {
  "verdict": "have-it | adapts | halfway | build | skipped",
  "summary": "<one paragraph>", "searched": ["<channel or query>", "..."], "not_covered": ["<channel not reached>"],
  "reason": "<required when skipped>", "ran_at": "<ISO-8601 UTC>"
}
```

A verdict other than `skipped` needs a non-empty `searched`; `skipped` needs a `reason`. **`update_meta.py set-phase` (and `append-history --phase-after`) refuses to cross into `prd_drafted` without it** (`dev-flow/scripts/inventory_gate.py`). On the founder path, `founder-intelligence` records this verdict at its feasibility stage, so the gate is the same on both paths.

### `founder` field (optional, owned by `founder-intelligence`)

For a commercial idea whose market is not settled, the founder path replaces the inventory step: research, customer discovery, competitors, business model and MVP scope, collected in a Playbook the founder approves before any PRD (the user's decision, 2026-10-17; `docs/superpowers/specs/2026-10-17-founder-intelligence-design.md`). Written only through `founder-intelligence/scripts/founder.py`:

```json
"founder": {
  "mode": "new | existing",
  "research": "in_progress | complete",
  "decision": "pending | approved | approved_experiment | revise | stop | bypassed",
  "playbook": ".workflow/founder/founder-playbook.md",
  "version": 3, "playbook_sha256": "<sha256 of the Playbook as approved>",
  "open_hypotheses": ["H2", "H5"],
  "approved_at": "<ISO-8601 UTC>", "approved_by_user": true, "approval_quote": "<the founder's words>",
  "experiment": { "scope": "…", "objective": "…", "constraints": "…", "acceptance": "…" },
  "reason": "<why revise, stop or bypassed>"
}
```

Research and decision are two axes, because a Playbook can be approved with hypotheses still open. The labels people read are derived from them (`show_state.py`, `founder.py status`):

| Label | When |
|---|---|
| `RESEARCH_COMPLETE` | `research = complete` |
| `NEEDS_VALIDATION` | `open_hypotheses` not empty (shown alongside the others) |
| `READY_FOR_FOUNDER_APPROVAL` | `research = complete` and `decision = pending` |
| `APPROVED_FOR_DEVFLOW` | `decision = approved` or `approved_experiment` |
| `REVISE_OR_STOP` | `decision = revise` or `stop` |

**Applies only when present.** A project without the field is on the direct path and nothing here concerns it. With `mode: "new"`, **`update_meta.py set-phase` (and `append-history --phase-after`) refuses to cross into `prd_drafted` unless the decision is `approved` or `approved_experiment` with the founder's quote and a Playbook whose sha256 still matches, or `bypassed` with a reason** (`dev-flow/scripts/founder_gate.py`). A Playbook edited after approval needs a new `founder.py approve`. With `mode: "existing"` (invoked on a project already past the PRD) the gate does not apply; the result is `handoff.md`, applied with `prd-from-idea` / `prd-to-tasks` once the founder agrees. Approval is not product-market fit: open hypotheses stay listed.

### `verification` field (owned by `app-verification`)

A project's manual for proving its features on the real app — `.claude/skills/verify-<app>/`, with launch, doctor, drive, evidence, cleanup and isolation, and one feature file per PRD story seeded from the wireframe inventory (`docs/superpowers/specs/2026-10-18-app-verification-design.md`). Written by `app-verification` after it has proven the manual live once:

```json
"verification": {
  "skill": ".claude/skills/verify-web",
  "features": 12,
  "source": "wireframes | routes",
  "proven_at": "<ISO-8601 UTC>", "proven_feature": "US-1",
  "evidence": ".verification/evidence/<timestamp>/",
  "maintained_at": "<ISO-8601 UTC>" | null, "maintain_outcome": "clean | changed | blocked" | null
}
```

In a monorepo `skill` is a list, one manual per surface (web, mobile, agent, api, cli, other — `dev-flow/scripts/surfaces.py` decides, for every skill). `source` says whether the map came from the screen inventory, the routes, or an agent's tools. Written by `verify_map.py record`, through `meta_io`'s lock. A shared package in `packages/*` is not a surface unless **`stack_config.verification_surfaces`** lists its path (an array of paths relative to the root). Never bumps `phase`; always a `history` entry. The manual and its evidence stay in the project's working tree — `.verification/` is git-ignored, and nothing is committed on the user's behalf. `show_state.py` notes a project past its first screen without a manual, and a manual older than the last material change.

### `security` field (owned by `app-security`)

The fifth pre-deploy gate — **can someone use this app to read or change what is not theirs?** Written by `app-security` after each run (`docs/superpowers/specs/2026-10-18-app-security-design.md`):

```json
"security": {
  "last_run_at": "<ISO-8601 UTC>",
  "tools": { "deps": "osv-scanner | pnpm-audit | npm-audit | not-run", "secrets": "gitleaks | not-run",
             "static": "semgrep | not-run" },
  "findings": { "open": 3, "fixed": 5, "accepted": [{ "check": "…", "reason": "…" }] },
  "dynamic": { "ran_at": "…", "tool": "strix", "proven": 1 } | null
}
```

`tools` records which scanner answered for each area; `not-run` means the area was **not checked**, never that it was clean. `accepted` carries the user's reason for each risk they keep, so the next run does not raise it as new. `dynamic` is `null` until the user asks for a Strix run (`app-security/references/dynamic.md`). Reports, never blocks, never bumps `phase`; always a `history` entry.

A project whose session helpers have other names declares them in **`stack_config.security_session_calls`** (an array of function names, e.g. `["requireMember", "withOrg"]`), added to the defaults `getSession`, `getCurrentUserId`, `getCurrentTenantId`, `requireUser`, `verifySession` and `auth(`. Only a call inside a Server Action or route handler's body counts as a session check.

### `debt_audit` field (owned by dev-flow's debt audit)

Every audit the project has, plus a test check, in one ordered list — written by `dev-flow/scripts/debt_audit.py
collect` (`docs/superpowers/specs/2026-10-18-debt-audit-design.md`), through `meta_io`'s lock:

```json
"debt_audit": {
  "last_run_at": "<ISO-8601 UTC>",
  "bands": { "before_release": 2, "with_features": 11, "later": 7 },
  "to_confirm": 4,
  "not_checked": ["coverage", "shadscan"],
  "sources": { "app-security": "fresh", "shadscan": "stale", "vercel-doctor": "missing" },
  "new": 3, "closed": 1, "report": "docs/debt/debt-audit.md"
}
```

`bands` count **confirmed** findings only; `to_confirm` counts the scanners' signals (app-security, compliance,
shadscan `fix` / `verify`) not yet reviewed in `.workflow/debt/reviewed.json`. `not_checked` lists the sources that could not see, or saw only in
part — never clean. `sources` is `fresh | partial | stale | missing | not checked | not applicable` per source;
`partial` is a scanner that ran but reported areas it could not check (gitleaks missing inside app-security). Never bumps `phase`; always a
`history` entry (`{skill: "dev-flow", action: "debt-audit"}`). `show_state.py` proposes it from `deployed`, and again
after a material change. How-to `dev-flow/references/debt-audit.md`.

### `spec_review` field (owned by `spec-review`)

The review of a **change** — three axes, never merged — and, when one pass was not enough, the cycle
that iterated on it. Written only through `spec-review/scripts/findings.py` (the cycle) and by the
skill itself (the axes' results), through `meta_io`'s lock:

```jsonc
"spec_review": {
  "last_run_at": "<ISO-8601 UTC>",
  "fixed_point": "main",              // what HEAD was compared against
  "commits": 7,
  "spec_sources": ["tasks.md#T12-T15", "PRD.md#3.2"],
  "spec_findings": { "missing": 1, "scope_creep": 2, "wrong": 0 },
  "standards_findings": { "hard": 1, "judgement": 4 },
  "risk": {                           // the third axis; verdicts are ⚠️/👀/✅, never a score
    "verdicts": { "alignment": "✅", "impact": "👀", "verification": "⚠️",
                  "rollback": "⚠️", "error_detection": "✅" },
    "one_way_doors": ["migration drops client_choice", "vendored into 7 projects"],
    "sixth_question": "<the answer, or the sentence saying it is empty>",
    "accepted": { "verification": "12 orphan rows a year, accepted by luca on the PR" }
  },
  "level": 3,                         // §Intervention levels — who can check, not how clean
  "axes_not_run": [],                 // e.g. ["spec"] with no PRD — say so, never infer it

  // The cycle. Absent on a single-pass review, which is the default and the common case.
  "head_sha": "abc1234…",             // the commit the review actually looked at — what `show_state.py`
                                      // counts from, and without it nothing can see what landed since
  "skipped": { "at": "<ISO>", "head_sha": "…", "quote": "<the user's words>", "reason": "…" },
  "profile": "light | standard | strict",   // review DEPTH (1 / 3 / 5 rounds) — never subtracts a check
  "max_iterations": 3, "iteration": 2,
  "reopened": 1,                      // a finding that came back after being closed
  "rounds": [{ "round": 1, "closed_at": "<ISO>", "found": 4, "resolved": 3, "open_at_close": 1 }],
  "findings": [{
    "id": "F3", "fingerprint": "9f2c1a…",    // (axis, category, file, line, summary) — not the wording
    "axis": "spec | standards | risk", "severity": "critical | high | medium | low | info",
    "category": "rollback", "file": "lib/db/schema.ts", "line": 42,
    "summary": "…", "evidence": "…", "impact": "…", "suggestion": "…",
    "confidence": "high | medium | low",      // separate from severity: consequence vs certainty
    "needs_human": true,                      // a round cannot close while this is open
    "resolution": "open | fixed | rejected | accepted | deferred",
    "resolution_note": "…",                   // required to reject
    "resolution_quote": "<the user's words>", // required to accept
    "resolution_sha": "abc1234",
    "found_in_round": 1, "resolved_in_round": 2, "reopen_count": 0
  }]
}
```

**The three axes are never merged into one verdict**, and the third exists because the first two can
both pass on a change that should not be merged (§Intervention levels records the measurement). An
**unrun axis and a clean axis must never look the same**: `axes_not_run` says which, and nothing infers
a pass from silence.

**The cycle's three refusals are in code, not in prose** (`findings.py`): `iterate` refuses while any
open finding has `needs_human`, because a disagreement about a product decision or an ambiguous
requirement is the user's and inventing a resolution is the failure it guards; `iterate` refuses past
`max_iterations` and sends the open findings to the user with the level, because a review that has not
converged in three rounds has found something a fourth will not settle; and a resolved finding that
reappears is **restored and counted** in `reopened` rather than filed again, which is how a reviewer
re-reporting what the implementer argued away becomes visible instead of infinite. `close --level 1|2`
refuses while a `critical` or `high` finding is open — levels 1 and 2 mean the agent merges. `accepted`
requires the user's own words; `rejected` requires a reason.

**A skipped review is recorded, never inferred.** `findings.py skip --user-said` writes `skipped` with the user's own words and the sha that was not read, and clears `level`. Relying on the agent to remember to write that down is what left archistudio with 200 unreviewed PRs and a healthy-looking state report. `show_state.py` reports, from `page_generated` on: a project where no review ever ran, a last review that was skipped, and more than `stack_config.review_staleness_commits` commits since `head_sha`. It reports and never blocks.

**`profile` is depth, never subtraction.** It sets rounds and brief depth; it does not drop an axis,
lower a severity or skip a check because a diff is small — a level is defined by *who can check a
finding*, which a diff's size cannot change. Never bumps `phase`; always a `history` entry. How-to
`spec-review/SKILL.md`; the cycle `spec-review/references/review-cycle.md`; the PR body
`spec-review/references/pr-documentation.md`; the review's own measurement `evals/review-quality/`.

### `release` field (optional, owned by `release-intelligence`)

The stretch between "the code is done" and "production is healthy": a Release Manifest per release,
its measured risk floor, the exposure it has reached and who agreed to it. Written only through
`release-intelligence/scripts/release.py`, through `meta_io`'s lock:

```json
"release": {
  "enabled": true,
  "autonomy": "disabled | advisory | assisted | automated",
  "flag_provider": "launchdarkly | openfeature | edge-config | posthog | …" | null,
  "observability_provider": "sentry | glitchtip | vercel" | null,
  "deploy_provider": "vercel" | null, "scm_provider": "github" | null,
  "rollout_strategy": { "stages": [1, 5, 25, 50, 100] },
  "thresholds": { "error_rate_pct": 1.0, "p95_ms": 1200, "min_observation_minutes": 30, "rollback_multiple": 2.0 },
  "risk_policy": { "paths": { "api": "high", "ci": null }, "size_bands": { "medium": 30, "high": 120 } },
  "required_approvals": { "rollout_advance": "approval" },
  "cleanup_policy": { "min_days_at_100": 7 },
  "migration_policy": "expand-contract",
  "releases": [{
    "id": "REL-2026-11-06-01", "feature": "US-7", "environment": "production",
    "commit": "abc1234", "pr": 42,
    "risk": "low | medium | high | critical", "risk_floor": "<the measured level>",
    "risk_raised": { "from": "low", "to": "high", "reason": "…" } | null,
    "risk_signals": ["auth", "size"], "not_checked": ["…"],
    "reversible_by_deployment_rollback": true, "destructive_migration": false,
    "approval": { "required": true, "granted_by_user": true, "quote": "<the user's words>", "at": "<ISO-8601 UTC>" },
    "flag": { "key": "us-7-new-checkout", "provider": "launchdarkly", "created": false } | null,
    "rollout": { "stages": [1, 5, 25, 50, 100], "current_percent": 25,
                 "steps": [{ "at": "…", "to_percent": 25, "verdict": "continue", "why": "…", "evidence": {} }] },
    "status": "planned | approved | rolling | paused | complete | rolled_back | abandoned",
    "planned_at": "<ISO-8601 UTC>", "verified_at": "<ISO-8601 UTC>" | null,
    "events": [{ "at": "…", "event": "approved | paused | rollback:flag | stage_refused:insufficient | verified", "…": "…" }]
  }]
}
```

**Applies only when present and `enabled`.** A project without the field — every project until
someone runs `release.py enable` — is untouched: no gate applies, nothing is proposed, and every
other skill behaves exactly as before. `release.py disable` lifts the gate and leaves the decision in
the file.

`risk` is a **floor** measured by `release-intelligence/scripts/risk.py` from the diff and from what
`security`, `debt_audit` and `spec_review` already recorded. The agent may **raise** it with a reason
(`risk_raised`); nothing lowers it. `not_checked` lists what the scan could not see and is never a
pass — a release graded `low` because nothing could be read is the failure mode the field exists to
make visible.

**Two rules no configuration relaxes** (`release-intelligence/scripts/policy.py`): pausing and
aborting a rollout are automatic in every mode, because a safety control that waits for a sleeping
human is not one; and a destructive database migration, a flag deletion and a production data change
are **never** automatic at any risk level — `required_approvals` may only tighten a row, and an entry
that would loosen one is ignored and reported.

**`update_meta.py set-phase` (and `append-history --phase-after`) refuses to cross into `deployed`**,
on an enabled project, without a Release Manifest covering production — and refuses a `high` or
`critical` release whose `approval.granted_by_user` is not `true` with the user's own words
(`dev-flow/scripts/release_gate.py`). Never bumps `phase`; always a `history` entry. How-to:
`release-intelligence/SKILL.md`.

### `phase` enum (canonical)

The `phase` field tracks the project's progress through the pipeline. Every skill must set this correctly.

**All phase values are `snake_case` strings**. The canonical list below is the complete enum; skills MUST NOT use values outside it. Unknown values are treated as `empty` (forward-compatibility).

| `phase` value | Stacks | When set | Ready for next skill |
|---|---|---|---|
| `empty` | all | `.workflow/` was just created, only `meta.json` exists | `prd-from-idea` |
| `idea_captured` | all | `PROJECT.md` exists | `prd-from-idea` (to expand into PRD) or scaffold (skip if simple) |
| `prd_drafted` | all | `PRD.md` exists | `prd-to-tasks`, `figma-to-design-md`, `image-to-design-md`, or scaffold |
| `tasks_split` | all | `tasks.md` exists | `figma-to-design-md`, `image-to-design-md`, or scaffold |
| `design_extracted` | all | `DESIGN.md` + (optional) `screenshots/` exist | `wireframe-canvas` (every screen on a Design canvas, approved by the user — the gate into the scaffold), then scaffold (`design-md-to-app` for web, `rn-bootstrap` for mobile, `monorepo-bootstrap` for monorepo) |
| `monorepo_initialized` | **monorepo only** | turborepo root exists (`pnpm-workspace.yaml` + `turbo.json`), before the apps are scaffolded | `monorepo-bootstrap` continues — scaffolds `apps/web` (`design-md-to-app`), `apps/mobile` (`rn-bootstrap`), and/or `apps/agent` (`eve-agent`) |
| `scaffolded` | all | `app/` exists with framework + UI library installed — **every primitive of it** (`shadcn add --all`), so golden rule 3 always has something to compose | next-stack-skill (`screenshot-to-page` web / `rn-add-screen` mobile) or `module-add` / `rn-module-add` |
| `page_generated` | all | At least one route is implemented from a screenshot or PRD | `module-add` / `rn-module-add`, more screen-gen runs |
| `module_added` | all | Auth/DB/payments/etc. wired up | iterative — repeat as needed; leads to `feature_complete` when the build is done (all stacks) |
| `feature_complete` | all | All planned features built and tested; ready to ship | pre-deploy gates — `compliance-audit` and `app-security` (any stack), plus `vercel-doctor`, `shadscan` and `launch-audit` for web — then deploy: web → `vercel-deploy`, mobile → `rn-eas-deploy`, agent → `eve deploy` |
| `deployed` | all | Live in production (web on Vercel / mobile on App Store + Play Store / agent via `eve deploy`) | maintenance loop (web: `screenshot-to-page` / `module-add`; mobile: `rn-add-screen` / `rn-eas-build-submit-update`; re-run `compliance-audit` after material changes) |

**Notes**:
- All values are `snake_case` (e.g., `module_added` NOT `module-added`). Skills that use the kebab-case variant are non-conforming and should be migrated.
- The `feature_complete` and `deployed` phases are **cross-stack** (web, mobile, agent, monorepo). A web or agent project stays iterating at `module_added` and advances to `feature_complete` when the user declares the build done — at which point dev-flow proposes the `compliance-audit` pre-deploy gate and then the stack's deploy skill. `monorepo_initialized` is **monorepo-only** (a mid-`monorepo-bootstrap` checkpoint before the apps are scaffolded).
- **Phase progression is monotonic** — a skill should never set `phase` to an earlier value than what it found. If a skill is re-run (e.g., user re-extracts design from a new Figma), it appends to `history` but keeps the phase ≥ the current one.
- **The phase must not fall behind the code.** Routes in `app/` or components in `components/` while `phase` is still before `scaffolded` / `page_generated` means every check keyed on the phase (spec-review, shadscan, the set-phase gates) is silently off — smart-travel built for three days at `design_extracted`. `show_state.py` reports it as **PHASE BEHIND THE CODE** and routes to realignment (retrofit golden rule 3, `set-phase page_generated`, then spec-review + shadscan on what was built). Independently of the phase, `spec-review` runs whenever a piece of work lands.
- The `deployed` phase is terminal in the sense that future runs stay there; subsequent EAS Update or new-feature work appends to `history` without phase regression.

## Intervention levels — who can check, not how clean it looks

When a piece of work is finished and the user is asked whether to merge it, the review
(`spec-review`, three axes) closes with **one level**. The level says who decides, and it is derived
from **who is able to check a finding** — never from the agent's impression of the diff.

| Level | What it means | When it applies |
|---|---|---|
| **1** | the agent merges on its own | **every** acceptance criterion in `tasks.md` was verified by running a command whose output is shown to the user; CI green; the gate scripts green; **zero** findings on Spec, Standards and Risk. If any criterion needed a human eye, the work is not level 1 — by definition, not by judgement |
| **2** | the agent says what it found and merges unless the user objects | findings only of the mechanical kind, and already fixed on the branch (a primitive used instead of a raw element, a string routed through i18n) |
| **3** | the agent asks specific questions and waits | any finding the agent cannot settle: a one-way door, a missing before/after, a scope question, an accepted trade that needs to be written down |
| **4** | the agent stops | the diff does something the spec does not say, or a risk it cannot size |

**Why level 1 is defined by commands and not by cleanliness.** A level the agent grants itself on its
own verdict authorises exactly the cases it cannot see. Measured, 2026-10-20: every commit of that
day's ask-gate work would have scored ✅ on all five Risk categories — small diff, tests added, suite
green, one-line revert — and two of them were the worst defects of the day (a gate asking on a fifth
of all commands; a hook walking `/usr` before every command). Both were invisible to the diff and
visible in one measurement. So level 1 requires **shown output**, which the user can re-run, and any
judgement finding at all drops the work to 3.

**What drops a work item out of level 1**, each of these on its own: an acceptance criterion phrased
as an opinion rather than a command (*"i valori sembrano corretti"*); a line touched in code that
decides something (a norm verdict, a permission, a price); any migration, however small; the sixth
Risk question left unanswered — an empty answer there is a finding of its own kind, not a pass.

**Level 2 means the contract already decided, not that the agent felt sure.** "Mechanical" is a
property of the finding, not of the confidence: `<Button>` instead of `<button>`, a string through
`next-intl`, a token instead of a hex value — each has exactly one correct fix, written down
somewhere. **If fixing a finding requires *choosing* anything** — which variant to add, whether to
change an API, whether a trade is worth it — it is not level 2, by definition. Every time an agent
has "chosen" alone in the name of tidiness in this repo, it opened something: 2026-10-20 has seven
instances in one file.

**At level 3 every answer goes to one of exactly two places**: a fix in the code, or a line written
into the PR. There is no third place. An acceptance given out loud is, a month later,
indistinguishable from something nobody noticed — so the written line names what was accepted, who
accepted it, and the command that could re-check it if there is one.

**The verdicts recorded in `meta.json` are the final ones, not the opening ones.** All ✅ with
`"level": 3` is not a contradiction: it says *this diff is sound, and it got there because the user
settled four things*. The level is the memory of **who decided**, never a score on the code.

**Level 4 is not "level 3 with more findings."** The test is where the answers live: at level 3 the
questions can be settled inside the project; at level 4 at least one needs something that is not in
the repository — a supplier's region, a contract, a commercial decision — or a risk the agent cannot
size. Then the work does not wait on a list: it goes back to the spec through
`prd-from-idea/references/scope-check.md`, because the specification was incomplete.

Recorded as `meta.json#spec_review.level`. The level **never** bumps `phase` and never blocks a
gate: it decides who presses merge.

### `stack` field

Captures user choices that downstream skills need. Keys:

- `framework`: `"next"` | `"vite-react"` | `"remix"` | `"astro"` | `"sveltekit"` | `"expo-rn"` | `"monorepo"` (planned) | `"agent"` | string

  `"agent"` is the **agent-only topology** (shape ③ in `dev-flow/references/stack-decisions.md` §Topology policy): an eve agent at the repo root with **no web app**, whose surfaces are elsewhere — Slack, email, GitHub, Linear. Always paired with `agent: "eve"`; `ui`, `forms`, `nextjs_version`, `locales` stay `null` (there is no frontend, so golden rule ② does not apply — agent *output* is localised by instructions, not by an i18n bundle).

  **The 17 skills that guard on `framework` need no change: refusing is the correct answer.** `forms`, `data-fetching`, `design-md-to-app`, `shadscan` and the rest exist to build and audit a web UI, and an agent-only project has none. The only skills that apply are `eve-agent` (which owns the whole repo root here, not `apps/agent/`), `eve-registry-porting`, `compliance-audit`, `prd-from-idea` / `prd-to-tasks` / `scrum`, and `vercel-deploy` only insofar as `eve deploy` is the ship step.
- `ui`: `"shadcn"` | `"base-ui"` | `"coss"` | `"mui"` | `"ui-sdk"` | `"chakra"` | `"radix-vanilla"` | `"nativewind"` (mobile) | string. **Note**: `"base-ui"` here means *standalone* Base UI (headless library, no shadcn CLI). With shadcn CLI v4 you can also run shadcn **on top of** Base UI — that is `ui="shadcn"` + `ui_base="base"` (below), and is usually the better way to get "shadcn philosophy on Base UI" because you keep the shadcn component set + blocks. `"coss"` = **Coss/UI** (the Cal.com design system on Base UI, installed via the shadcn `@coss/*` registry; implies `ui_base="base"`, requires Tailwind v4) — owned by the `coss-ui` skill. `"ui-sdk"` = **UI SDK** (`@ui-sdk/core` + a framework adapter) — no CLI and no copied source, so it behaves like `"base-ui"` standalone: you import from `@ui-sdk/react/select`, and `components/ui/` holds *your* compositions rather than a vendored kit. ⚠️ **Beta** (`0.1.0-beta.x`, first published 2026-11-12, under Vercel's public-beta terms), so it is never the default and never a silent upgrade: `design-md-to-app/references/library-choice.md` has the two signals that earn it — a product that must run on more than one framework, or an interface an agent drives through `createAgent`. On every other project the answer stays `"shadcn"`.
- `ui_base` (web, only when `ui="shadcn"`): `"radix"` | `"base"` | `"aria"`. The primitive library shadcn builds on (`shadcn create --base`). **Default `"base"`** (Base UI — shadcn's default for new projects since 2026-07). `"radix"` is the long-standing base (still fully supported); `"aria"` = React Aria (`--base aria`, Adobe's a11y-first primitives, first-class since 2026-07). Every shadcn block/component ships in all variants; `shadcn add` pulls the matching one.
- `shadcn_preset` (web, optional, only when `ui="shadcn"`): a **shadcn preset code** (short string, e.g. `"b5owWMfJ8l"`) built on <https://ui.shadcn.com/create>. Encodes style, base color, theme, chart palette, icon library, fonts (body/heading), and radius — the whole shadcn visual system in one token, designed to hand off to coding agents. When set, the **preset is the source of truth for the shadcn visual layer** (passed as `--preset`), and the DESIGN.md token-first install (`registry.json`) is **skipped** for the visual layer — preset XOR DESIGN.md-tokens, never both. `null`/unset → DESIGN.md-first (default). Decode/inspect with `shadcn preset decode <code>`; `ui_base` is still set separately (the preset may not encode the primitive base).
- `base_color` (web, only when `ui="shadcn"`): `"neutral"` | `"gray"` | `"zinc"` | `"stone"` | `"slate"`. The shadcn base color. Default `"neutral"`. In dev-flow mode the **DESIGN.md tokens override** the actual palette — this is only the scaffold starting point.
- `ui_theme` (web, only when `ui="shadcn"`): `"vega"` | `"nova"` | `"maia"` | `"lyra"` | `"mira"` | `null`. The shadcn create starting theme. Default `null` (plain). DESIGN.md tokens override.
- `icon_library` (web): `"lucide"` | `"radix-icons"` | `"tabler"` | `"hugeicons"` | `"phosphor"` | string. Default `"lucide"`. **`"phosphor"` was promoted 2026-10-09 for the same reason as `"hugeicons"`: the enum could not express a value the toolchain itself chooses** — shadcn's `lyra` style ships `@phosphor-icons/react` (MIT, 2.1.10, 1,512 icons, **six weights per icon** — thin, light, regular, bold, fill, duotone — 31.5 MB installed, tree-shakeable), so a `lyra` scaffold set a library the contract had to record as a bare string. **The style decides this key**: read it from `shadcn info --json` after `init` rather than assuming the default (`design-md-to-app/references/shadcn-styles.md`). ⚠️ `animated-icons` has registries for heroicons and hugeicons only, so an animated-icon request on a `phosphor` project needs a different answer.
- `illustrations` (frontend, optional): `"koboyo"` | string | `null`. **Default `null` — the honest value for most products.** Spot art / illustration for *moments* (empty states, onboarding, 404), distinct from `icon_library` (UI icons). Set it only when DESIGN.md's visual language actually admits illustration; how-to + the restraint rules + the licence boundary are in `design-md-to-app/references/illustrations.md`.
- `data_residency` (all stacks): `"eu"` | `"eu-sovereign"` | `"none"` | `null`. **Decided at the stack decision, before any module wires a provider**, by `dev-flow/scripts/data_residency.py decide` from four answers — EU data subjects, sensitive categories, sector residency obligations, CLOUD Act exposure to avoid — kept in `stack_config.data_residency_answers` (with `override_reason` when the choice departs from the suggestion). `"eu"` = every service in an EU region where one exists; `"eu-sovereign"` = EU region **and** a vendor not under US control where a European alternative exists; `"none"` = no EU constraint. **`update_meta.py set-phase` refuses `scaffolded` while it is `null`** — and that is all it refuses: a provider with no EU region is **flagged** in the sub-processor register with its transfer basis and never blocks a module or a phase. How-to, the service table and the regulations: `dev-flow/references/eu-data-sovereignty.md`.
- `design_lint` (web): `"shadcn-lint"` | `"none"` | `null`. Written by `design-md-to-app/scripts/setup_design_lint.py` once `@shadcn/lint` is installed, wired and capped. `"none"` is an **explicit opt-out** and requires `stack_config.design_lint_reason` (a sentence; an opt-out without one does not count). **`null` means undecided, and `update_meta.py set-phase` refuses to move a Next web app on a Tailwind UI (shadcn, base-ui, coss) into `scaffolded` while it is undecided or not wired — and, since 2026-10-12, any later phase too while the preset lacks `design/no-handmade-ui` or the write-time guard (`primitives_guard`).** `show_state.py` flags projects already past it and proposes the one-command retrofit. MUI, mobile and agent-only projects are not affected. Retrofitting an existing app starts at `warn` with a measured `--max-warnings`, never straight to `error`.
- `primitives_guard` (web): `"installed"` | `"none"` | `null`. The write-time guard of golden rule 3 (`.claude/settings.json` hooks + `scripts/guard/`), written by `design-md-to-app/scripts/setup_primitives_guard.py` (called by `setup_design_lint.py`). `"none"` is an explicit opt-out and requires `stack_config.primitives_guard_reason`; a reasoned `design_lint: "none"` takes the guard with it (no rule to run). **`update_meta.py set-phase` refuses `scaffolded` and every later phase on a Next web app with a Tailwind UI while it is missing or the preset lacks `design/no-handmade-ui` at `error`**; `show_state.py` flags it and proposes the retrofit (`setup_design_lint.py <root>`, one command: rule + guard + AGENTS.md section). Mobile is not covered yet (golden rule 3, open gap).
- `lint` (optional): `"eslint"` | `"biome"` | `"eslint+biome"` | `null`. Which **code** linter the project runs — a different question from `design_lint`, which is the shadcn design-system lint and is wired by a script of ours. **The repository is the truth and this key is a cache of it**: the operative facts are the `lint` script in `package.json`, the config file on disk and the dependency, and every skill that lints reads those. `show_state.py` reports a declaration the repository contradicts. **Written 2026-10-10 after a survey of 36 projects found it declared in two of them and wrong in both** — one said `biome` with no biome anywhere (it runs ESLint and Prettier), the other said `eslint` while carrying both. A key nothing writes, nothing reads and nothing checks does not stay true; this one is now checked, which is the only reason to keep it. **`design_lint = "shadcn-lint"` needs ESLint**: `@shadcn/lint` is an ESLint plugin, so a biome-only project cannot run the design lint and must record `design_lint: "none"` with its reason. ⚠️ In a monorepo the toolchain lives in `apps/*`, not at the root — a check that reads only the root package.json reports six healthy projects as broken, which is how this paragraph was nearly written wrong.
- `registry_intake` (web on a Tailwind UI, and eve agents): `"enforced"` | `"none"` | `null`. Written by `registry-intake/scripts/registry_intake.py setup`, which creates `registry-lock.json` (allowlisted registries with their reason, approved items with snapshot hash, reviewer and accepted findings), `vendor/registry/` and the PreToolUse hook in `.claude/settings.json`. **`update_meta.py set-phase` refuses `scaffolded` while `registry_intake.py check` fails**, unless `"none"` is recorded with `stack_config.registry_intake_reason`. From then on a component from any registry other than shadcn's own is installed only through `review → approve → install`; `@coss` is the one registry trusted live, and only when `ui = "coss"`.
- `test`: a **string, never an array** — the test layers joined by `+`, in this canonical order: `vitest` · `jest-expo` · `rntl` · `playwright` · `maestro` · `e2e`. Unit layers first, end-to-end layers last, no repeats. `"vitest+playwright"` is the web default, `"jest-expo+rntl"` the mobile one, `"jest-expo+rntl+maestro"` mobile with end-to-end flows, `"vitest"` unit only; `null` is undecided. **The grammar is validated rather than a fixed list of whole strings**, because a list cannot express a legitimate combination — the first project to add a layer would be told its honest value is wrong. `e2e` is the agentic runner (tester-army, Apache-2.0): **read, not adopted**, and `write-tests/references/e2e-agentic.md` is the one copy of how it is used, what it costs per run and which gates it passes first — `rn-write-tests` reads the mobile half from the same file. Written by `module-add test` (web) and `rn-bootstrap` (mobile) at scaffold; read by `write-tests` and `rn-write-tests` to pick the framework and to follow the mocking patterns already in the repo. `null` means undecided, and nothing refuses it: a project may ship without tests, and recording that honestly beats a value nobody wired. **This enum was written 2026-10-10, after the key had been free text since the first contract.** Eleven projects had drifted into four spellings, and one of them held an **array** — `write-tests` reads `stack.test` as the name of a framework, so `["vitest", "playwright"]` is a framework called `['vitest', 'playwright']`, which matches nothing and fails silently by writing tests in whatever style the sibling files happen to use. A new layer joins this enum deliberately; it is not invented at a call site.
- `css_variables` (web): `true` | `false`. shadcn `--css-variables`. Default `true` (required for token-driven theming from DESIGN.md).
- `rtl` (web, optional): `true` | `false`. shadcn `--rtl` (right-to-left support). Default `false`.
- `auth`: `"better-auth"` | `"next-auth"` | `"clerk"` | `"supabase"` | `"supabase-auth"` | `"firebase"` | `"custom-rest"` | `"trpc"` | `null`
- `db`: `"neon-drizzle"` | `"supabase"` | `"firebase"` | `"planetscale-prisma"` | `"custom-rest"` | `"trpc"` | `null`
- `payments`: `"stripe"` | `"lemon-squeezy"` | `"revenuecat"` (mobile IAP) | `null`
- `deploy`: `"vercel"` | `"fly"` | `"cloudflare-pages"` | `"eas"` (mobile) | `null`
- `storage` (optional — file/blob storage): **web** → `"vercel-blob"` (**default** when `deploy = "vercel"` — same platform, no extra vendor/sub-processor; how-to `module-add/references/module-storage.md`) | `"uploadthing"` | `"s3"`; **mobile** → `"supabase"` | `"firebase"` | `"custom-rest"`; `null` when the product stores no files.
- `realtime` (mobile, optional): `"supabase"` | `"firebase"` | `"custom-rest"` | `null`
- `analytics` (optional — only when the user asks to measure usage; never asked twice): a list of the active levels, any of `"traffic"` (Vercel Web Analytics + Speed Insights; web only) | `"product"` (an `analytics_events` table in the project's own database, server-side `track()`, activation and D7/D30 retention as SQL — no new sub-processor) | `"advanced"` (funnels, replay, dashboards from a provider, on request). Absent or `[]` = not requested: no skill and no check treats that as a gap. Can be switched on at any phase, a level at a time. How-to: `module-add/references/module-analytics.md` (web), `rn-module-add/references/module-analytics.md` (Expo).
- `analytics_provider` (only with `"advanced"` in `analytics`): `"posthog"` (PostHog Cloud EU, host written explicitly) | `"openpanel"` (the `eu-sovereign` default, self-hosted). Registered with `data_residency.py add`.
- `observability` (web and Expo; proposed before the first production deploy, never a block): a list of the active levels, any of `"errors"` (every client and server exception to a tracker, with the release and no personal data) | `"logs"` (`lib/log.ts` structured lines with `x-request-id`; a drain on Vercel Pro) | `"uptime"` (`/api/health` and an external monitor). Absent or `[]` = none yet: `show_state.py` notes it from `feature_complete` and `vercel-deploy` offers it. How-to `module-add/references/module-observability.md` (web), `rn-module-add/references/module-observability.md` (Expo); checked by `module-add/scripts/observability_check.py`.
- `flags` (optional, web only — the feature-flag provider a project actually installed): **`"vercel"` (the default)** | `"edge-config"` | `"launchdarkly"` | `"posthog"` | `"openfeature"` | `"statsig"` | `"growthbook"` | `"hypertune"` | `"optimizely"` | `"split"` | `null`. 🔴 **`"vercel"` unless there is a reason against it**: `vercelAdapter()` reads **zero environment variables** (OIDC from the deployment, verified in its shipped `dist` 2026-11-07), adds **no sub-processor** (same vendor as the deploy, same DPA — which settles it alone when `data_residency` is `eu` or `eu-sovereign`), and Vercel's build bundles the flag definitions into the deployment as a runtime fallback. LaunchDarkly earns a project only for its provider-enforced approval requests, its `migration-safety-issues` pre-flight, or its stale-flag detection. Written by `module-add flags`, which installs `flags` (the Vercel Flags SDK) plus one `@flags-sdk/*` adapter — so changing provider is one line at one call site. `null` means the project declares no flags, which is the normal case and never a gap. Distinct from **`release.flag_provider`**, which records the provider a release *plans* to use: `release-intelligence` decides which flag a release needs, `module-add flags` installs the library. 🔴 `FLAGS_SECRET` must be **32 bytes base64url** — `precompute`/`serialize` throw without it, so a missing secret silently turns a flagged static page dynamic. How-to `module-add/references/module-flags.md`; checked by `module-add/scripts/flags_check.py`. No Expo equivalent: React Native uses the provider's own SDK.
- `observability_provider` (with `observability`): `{ "errors": "sentry" | "glitchtip", "logs": "axiom" | "betterstack" | "none", "uptime": "sentry" | "betterstack" }`. With `data_residency` `eu`/`eu-sovereign` the errors DSN is the Frankfurt org's (`*.ingest.de.sentry.io`) or GlitchTip's; registered with `data_residency.py add`.
- `cms` (optional — content a non-developer edits and the product only *reads*: catalogue, pages, articles, FAQs): `"sanity"` (**default when the product needs one** — the hosted Sanity Studio is the admin panel, so no admin CRUD and no admin roles are built into `db`; how-to `module-add/references/module-cms.md` for web, `rn-module-add/references/module-cms-sanity.md` for mobile) | `"payload"` | `"contentful"` | `null`. User-owned data (accounts, orders, bookings) never goes here — it stays in `db` behind RLS.
- `push` (mobile, optional): `"expo-notifications"` | `null`
- `route_groups` (web/monorepo, optional): array of `"(marketing)"` | `"(auth)"` | `"(app)"` | `"(tabs)"` (mobile). E.g. `["(marketing)", "(auth)", "(app)"]` for SaaS, `["(auth)", "(app)"]` for internal tool, `["(marketing)"]` for marketing site. Written by `prd-from-idea` based on deduction from the PRD; can be overridden by user later.
- `i18n` (frontend, **golden rule 2**): `"next-intl"` (web canonical default) | `"i18next"` | `"react-i18next"` | `null`. Every frontend has i18n — do not leave `null` for a frontend. Web new projects default to `"next-intl"`; mobile uses the RN i18n stack.
- `locales` (frontend, **golden rule 2**): array of BCP-47 codes, first entry = default locale. **Minimum `["en", "it"]`**; a project may add more (e.g. `["en", "it", "fr"]`). Set at scaffold, not asked.
- `maps` (frontend, optional — only when the product shows maps): `"mapcn"` (web, MapLibre GL — how-to `design-md-to-app/references/maps-mapcn.md`) | `"mapcn-rn"` (mobile, MapLibre/Mapbox RN — how-to `rn-components-apis/references/maps-mapcn-rn.md`) | `null`. Ecosystem-first default when a project needs a map. `null` when the product has no maps.
- `review_policy` (all stacks, optional): `"on_merge"` | `"on_request"` | `null`. **Who starts the review.** `"on_merge"` — the agent runs `spec-review` as part of performing a merge, without asking first; the user can stop it, and the skip is recorded with their words. `"on_request"` (the historical behaviour, and the default when the field is absent) — the agent proposes and asks. **The field exists because the question *"run the full review?"* only makes sense when the person being asked is the one merging**: where the agent merges, asking permission to check its own work has one cheap answer, and archistudio is the measurement (200 merged PRs, 94 branches, `spec-review` never run once). Decided once, like the tracker. It changes **who starts** the review and nothing else: `spec-review` still never blocks a merge, a phase or a deploy (the user's decision, 2026-11-06).
- `review_staleness_commits` (all stacks, optional): an integer, default **20**. How many commits may land after the last recorded review before `show_state.py` says so. A starting point, not a truth — a repo that commits in small steps wants a higher number. The note reports and never blocks.
- `graphs` (web, optional — only when a screen is an interactive node graph): `"react-flow"` | `null`. How-to `design-md-to-app/references/react-flow.md`. A read-only diagram that fits the screen is not a reason to set it. If the project hides React Flow's attribution, `stack_config.react_flow_subscription` records the subscription that allows it.
- `shaders` (web, optional — only when a WebGPU shader actually ships): `"vgpu"` | `null`. [`vgpu`](https://vgpu.sh) (Vercel Labs, MIT) as the **Tier 4** rung of `transitions` — how-to `vgpu-shaders`. ⚠️ Set it only when a shader renders in production: it commits the project to a GPU device, a compile step and a render loop. Record alongside it how the **reduced-motion** path is served and what a **no-WebGPU** visitor sees; neither has a default, and the library documents neither.
- `monorepo` (only when `framework = "monorepo"`): the per-side sub-object. `monorepo.web.*` and `monorepo.mobile.*` are defined in `dev-flow/references/stack-monorepo.md` (the canonical monorepo reference); the contract adds one key here because it is not per-side:
  - `monorepo.services` (optional): array of non-JS apps living in `apps/`, each `{ "name", "runtime", "framework", "path", "package_manager" }` — e.g. `{ "name": "ml", "runtime": "python", "framework": "fastapi", "path": "apps/ml", "package_manager": "uv" }`. Written by `monorepo-add-python-service`, which owns those apps the way `eve-agent` owns `apps/agent/`. An entry here tells every other skill that a directory under `apps/` is **not** a JS app: the web skills (`design-md-to-app`, `screenshot-to-page`, `forms`, `shadscan`, …) must never be proposed for it, and **golden rule 2 does not apply** to it — a service that returns JSON has no UI to localise.
- `canvas` (web, optional — only when the product ships a pan/zoom workspace): `"iframe-live"` | `"iframe-snapshot"` | `"single-live"` | `"rendered"` | `null`. Which canvas architecture was chosen, and therefore which constraints the rest of the editor is built under — owned by `iframe-canvas`. The value matters more than most: it decides how many browsing contexts the tab pays for, and changing it later invalidates the camera, the overlays and the protocol at once.
- `launch_audit` (web, optional — written by the `launch-audit` gate, not a stack choice): `{ ran_at, findings[], dismissed{} }`. The fourth pre-deploy gate — **can a stranger find this, trust it, and buy from it?** `dismissed` carries a *reason* per rejected finding so the next run does not re-litigate it. Reports, never blocks, never scores; how-to `launch-audit/SKILL.md`.
- `mcp` (web, optional — only when the product is published as an MCP server): `"better-auth"` | `null`. The app exposes `/mcp` over `@modelcontextprotocol/sdk`, guarded by its own OAuth server (`@better-auth/mcp`) — owned by `module-add mcp`; how-to `module-add/references/module-mcp.md`. Requires `auth` with its MCP section. **Not the same as an eve agent published as MCP** (`mcpChannel()` on `eve/channels/mcp`), which publishes the *agent*; this publishes the *product*.
- `pdf` (web, optional — only when the product generates documents): `"forme"` | `"takumi"` | `null`. The PDF renderer under the [pdfcn](https://www.pdfcn.dev) component registry — owned by `module-add pdf`. Both engines are **pre-1.0 on the PDF path** (2026-09-10); the components are copied into the repo shadcn-style, so a breaking change arrives as a diff you own rather than an upgrade you take.
- `forms` (web/monorepo, optional): `"tanstack-form"` | `"react-hook-form"` | `null`. The form-handling library. Defaults to `"tanstack-form"` for new Next.js 16 App Router projects (aligned with `nextjs-forms` skill from `lusentis/next-skills`). `"react-hook-form"` is supported for legacy projects or teams with strong preference. Written by `prd-from-idea` Q8 or set at scaffold time by `design-md-to-app`.
- `agent` (optional): `"eve"` | `null`. An **optional product component** — the agent engine, owned exclusively by the `eve-agent` skill, in `agent/` beside the app, `apps/agent/` in a monorepo, or `agent/` at the root (the topologies below). Opted into at stack-decision time or later on demand (not a pipeline phase). `null`/unset → no agent (or `eve-agent` will scaffold one when opted in); `"eve"` → an eve agent exists and `eve-agent` runs in capability mode. Setting it to `"eve"` does **not** dictate a repo shape. Three topologies are valid and the **project** picks — see `dev-flow/references/stack-decisions.md` §Topology policy for the decision, which proposes them in this order: **① single web app** with the agent inside it (the default — the product *is* the interface), **② monorepo** `apps/web` + `apps/agent` (the agent has its own deploy cadence, channels, or a second consumer), **③ agent only** (every surface is elsewhere and nothing needs rendering). Shape ③ is real, not theoretical: Vercel Labs' [`kody-eve-template`](https://github.com/vercel-labs/kody-eve-template) is a single-package repo whose `agent/` sits at the root and whose surfaces are GitHub, Linear and **email**. Pick by the product, not by habit, and **say which shape you are proposing** — ① and ② are different projects, not two spellings of one. Shape ③ is recorded as **`framework: "agent"`** (see the `framework` enum above): `eve-agent` owns the repo root instead of `apps/agent/`, and the web skills that refuse it are behaving correctly — there is no frontend for them to touch. What must not happen: scaffolding a Next.js app to satisfy a schema. A web app that exists only to host a chat box is worse than the email thread the users already have. `eve-agent` writes this key and appends to `history` but does **not** bump `phase` — the agent has its own capability cadence, separate from the web app's linear build.

  ⚠️ **One exception, and it follows from the reasoning above.** In the agent-only topology (`framework: "agent"`) there *is* no web app whose linear build the agent runs alongside, so nothing would ever advance the phase and the project would sit at `prd_drafted` forever. There, `eve-agent` **is** the bootstrap skill — the counterpart of `design-md-to-app` for web and `rn-bootstrap` for mobile — and bumps `phase` to `scaffolded` once the agent exists, exactly as they do. It still does not bump on subsequent capability additions (a tool, a channel, a skill); those append to `history` only. The meaningful phase path for this topology is `empty → idea_captured → prd_drafted → scaffolded → feature_complete → deployed`: `design_extracted`, `page_generated` and `module_added` are web concepts and are simply never reached.
- `nextjs_version` (web only, optional): `"16"` | string. The Next.js major version. **Canonical default for new projects = `"16"`** (App Router, RSC, async `searchParams`, `use(promise)`, `revalidatePath`, `revalidateTag`). Pages Router (`pages/` dir) is explicitly NOT supported by the dev-flow skill set — use only App Router. If an existing project is Pages Router or pre-16, the web skills refuse to apply. **Next 16.3 is stable** (released 2026-08-03; `latest` on npm) and every Next 16 project should upgrade — most of it is zero-config (dev memory, build cache, native Node streams, TS 7 type checking). **Instant Navigations** is the opt-in part (`cacheComponents` + `partialPrefetching`): it doesn't change this pin, and is adopted deliberately per `data-fetching/SKILL.md` §Instant Navigations.

  ⚠️ **Next.js now has support lines and a scheduled security cadence — the patch digit is not cosmetic.** Since 2026-07-13 Vercel publishes **pre-announced security releases roughly monthly** on the Next.js blog, each naming the highest anticipated severity so teams can plan the upgrade. Two lines are maintained, and **which line is Active LTS moves**: as of **2026-11-05** it is **16.4.x**, with **15.5.x = Maintenance LTS**. Re-read the line labels on every pass; don't cache them — and read them off the *patches*, not off a label, because the label is what goes stale first.

  🔴 **The 16.3 line is dead, and that is how this pass found a live critical.** The 2026-10-14 RCEs are ranged `> 16.0.0 <= 16.4.0` and fixed in **16.4.1**; `16.3.8` (2026-09-30) is the last release the 16.3 line ever got, and **no `16.3.9` exists**. So a project on the previous floor is unpatched against an *unauthenticated* RCE, with nowhere to go on its own line. The predecessor pattern repeats exactly: 16.2 stopped at `16.2.12` and was retired the same silent way. **A line is maintained only while it keeps receiving patches, and the proof is a published version — not a page calling it LTS.**

  **Security floor: `16.4.5` (Active LTS) or `15.5.29` (Maintenance LTS) — moved 2026-11-05, read from the GitHub Security Advisory database for `vercel/next.js` and the npm registry. The previous record, `16.3.8`/`15.5.27` of 2026-10-03, is ten advisories out of date and sits on a retired line: two of those advisories are *critical unauthenticated RCEs* with no fix on 16.3 at all. Both new sets are below.** The 2026-07-20 release fixed **9 CVEs — 4 high, 5 medium** — and several land squarely on what these skills prescribe:
  - **CVE-2026-64641** (high, DoS) and **CVE-2026-64646** (medium, unbounded payload) hit *any* App Router app with **at least one Server Action** — i.e. every project we scaffold.
  - **CVE-2026-64642** (high, middleware/proxy bypass) needs Turbopack **and a single entry in `config.i18n.locales`**. Golden rule ② (ship `en` + `it` minimum) means a conforming project has ≥2 locales and is not exposed — one of the rare cases where a style rule is also a security control. A single-locale project must patch.
  - **CVE-2026-64645** / **CVE-2026-64649** (high, SSRF/open redirect) apply when `rewrites()`/`redirects()` or a Server Action build an outbound destination from request-controlled input.
  - **CVE-2026-64643** (medium) discloses Server Action and **`use cache`** endpoint IDs — relevant wherever `data-fetching` recommends `use cache`.
  - **CVE-2026-64647/64648** (medium) are `fetch` **cache confusion**: a response body can be served for a *different* request to the same URL, for calls shaped `fetch(new Request(init), aDifferentInit)`.

  **2026-08-25 — two CRITICAL unauthenticated RCEs, and the release was moved forward for the second.** Both are worth reading because each is neutralised by a rule this contract already imposes, which is the second time that has happened:

- **AVIF image optimization → unauthenticated RCE** ([GHSA-2xp9-vwfh-vxw4](https://github.com/vercel/next.js/security/advisories/GHSA-2xp9-vwfh-vxw4), via `libheif` under `sharp`). Triggered when Next.js optimises an **attacker-controlled AVIF image**. The patch **disables AVIF optimization outright** until upstream fixes it — so a project that configured `formats: ['image/avif']` loses that format silently on upgrade, and one that never enabled it was never exposed. We have never recommended AVIF anywhere; leave it that way until the upstream fix lands.
- **Windows-hosted RCE** ([CVE-2026-75604](https://www.cve.org/CVERecord?id=CVE-2026-75604)) — requires **both Pages Router and App Router** in the same app, without Cache Components, on a **Windows filesystem**. Linux and macOS are unaffected, and **there is no workaround** for affected Windows hosts. A dev-flow project cannot be in this position: the web skills refuse Pages Router outright, so "App Router only" is a security control as well as a style rule — exactly like golden rule ② and CVE-2026-64642.

  **2026-09 — a critical RCE, then eight more CVEs eight days later. This is the pass where the floor had drifted furthest.** Read from the advisory database on 2026-10-03; note several of the September advisories carry a literal `16.3.?` placeholder in their patched-version field, so the floor is taken from the newest patch on the line (`16.3.8`, 2026-09-30) rather than from the advisory text.

- **`next/og` ImageResponse → RCE** ([GHSA-vcvr-r3jv-pc5j](https://github.com/vercel/next.js/security/advisories/GHSA-vcvr-r3jv-pc5j), CVE-2026-94545, **critical**, published 2026-09-22): affects `>= 16.2.0 < 16.3.6`, fixed in **16.3.6**. No dev-flow skill prescribes `next/og`, so a conforming project is unlikely to reach it — but it is a *critical* in a package a designer adds for an OG image without telling anyone, so check `app/**/opengraph-image.tsx` rather than assuming.
- **SSRF in Image Optimization** ([GHSA-cjq9-62q9-8jv4](https://github.com/vercel/next.js/security/advisories/GHSA-cjq9-62q9-8jv4), CVE-2026-94483, **high**): an allow-listed remote URL whose DNS an attacker controls reaches private IPs during optimization. **Conditional on `images.remotePatterns` being configured at all** — with none, the app is not affected — and the stated workaround is to audit those hosts for DNS you do not trust. Any project pulling images from a CMS or an S3-alike is in scope.
- **Cache leak across root param values in nested `'use cache'`** ([GHSA-h694-7cp9-m8p3](https://github.com/vercel/next.js/security/advisories/GHSA-h694-7cp9-m8p3), CVE-2026-103004, medium, **no known workaround**): with `cacheComponents: true`, a `'use cache'` function calling another that reads a **root param** can be keyed without that param, so one entry is written once and reused for *every* value of it. **This is our exact shape, not a hypothetical**: golden rule ② puts `[locale]` in the root segment and `design-md-to-app`'s i18n branch reads it with `next/root-params`, so on an affected version a cached page can be served in the wrong language — and shared cache headers let a CDN spread it. The leaked values are not attacker-chosen; which one wins is whichever invocation wrote first. Only reachable with Cache Components on, which `data-fetching` adopts deliberately for Instant Navigation.
- **Draft Mode content leaking out of a pending `'use cache'` fill** ([GHSA-3w37-wq28-93x7](https://github.com/vercel/next.js/security/advisories/GHSA-3w37-wq28-93x7), CVE-2026-94544, medium): same `cacheComponents` precondition, and it lands on `module-add cms` — a CMS preview is exactly what Draft Mode is for, and the unpublished draft can end up in a regular response or a persisted page.
- **Cache poisoning of SSG/ISR via a root-level catch-all** ([GHSA-mcj8-r9mp-w47p](https://github.com/vercel/next.js/security/advisories/GHSA-mcj8-r9mp-w47p), CVE-2026-94484, medium): a **single unauthenticated crafted request** poisons the shared response cache, giving cross-user content substitution and a persistent DoS. Conditional on a **root-level catch-all page** alongside static or ISR routes — a `[locale]` dynamic segment is not one, but an `app/[[...slug]]` CMS catch-all is, which is a shape `module-add cms` can produce.
- **Metadata image routes ignore `dynamicParams`** ([GHSA-f87g-xv8r-7p7x](https://github.com/vercel/next.js/security/advisories/GHSA-f87g-xv8r-7p7x), CVE-2026-94485, medium): `opengraph-image` / `twitter-image` serve segments deliberately excluded from `generateStaticParams()`. **Conditional on a webpack build** — our scaffolds are Turbopack, so this one is normally out of scope, which is worth knowing before anyone adds a webpack config "just for one plugin".
- **Pages Router SSG/ISR cache poisoning, self-hosted** ([GHSA-4jqv-mc3x-m676](https://github.com/vercel/next.js/security/advisories/GHSA-4jqv-mc3x-m676), CVE-2026-94543, medium): a page's cache entry is replaced with another route's content for every visitor until revalidation. **Pages Router only, self-hosted only** — Vercel-deployed apps are explicitly unaffected, and the web skills refuse Pages Router. That is the **third** time an App-Router-only rule has doubled as a security control (after CVE-2026-64642 and CVE-2026-75604); it is no longer a coincidence worth remarking on so much as a reason the rule exists.
- **Dev-server MCP endpoint information disclosure** ([GHSA-39w2-rjm5-chcv](https://github.com/vercel/next.js/security/advisories/GHSA-39w2-rjm5-chcv), CVE-2026-94486, low): the development server only. Low severity and not a production exposure — but it is a dev-server endpoint an agent may be talking to, so patch rather than reason about it.

**2026-10-14 — two CRITICAL unauthenticated RCEs and a HIGH DoS, and this is the set that retired the 16.3 line.** All three are ranged `> 16.0.0 <= 16.4.0` → **16.4.1**, and `<= 15.5.27` → **15.5.28** where the 15.5 line is affected. There is no 16.3 patch.

- **Image Optimization with SVG → unauthenticated RCE** ([CVE-2026-96889](https://github.com/vercel/next.js/security/advisories/GHSA-2464-fhr4-w9xw), **critical**): a memory bug in an **upstream library under `sharp`**, reachable when Next.js optimises images on **glibc-based Linux**. The advisory's own workaround is to force **`sharp >= 0.35.5`**, which is the useful detail: upgrading Next.js only helps because the package manager then resolves a fixed `sharp`, so a lockfile pinning an older `sharp` stays vulnerable on a patched Next. Check the resolved `sharp`, not just the Next version. Our deploy target is Vercel (glibc Linux), so "we don't self-host" is not an exemption.
- **`use cache` returning typed arrays → unauthenticated RCE** ([GHSA-673q-mjm6-r5xr](https://github.com/vercel/next.js/security/advisories/GHSA-673q-mjm6-r5xr), **critical**): App Router with Cache Components and a `'use cache'` function returning **multiple typed arrays**. **No known workaround**, and the advisory says to upgrade *"even if your application does not have similar functions"* — so this one is not to be reasoned about per-project. It lands on `data-fetching` §Instant Navigations, the one place we turn `cacheComponents` on deliberately.
- **DoS in App Router with Server Actions** ([GHSA-p3m5-59mp-jv5r](https://github.com/vercel/next.js/security/advisories/GHSA-p3m5-59mp-jv5r), **high**): crafted requests burn CPU and block every other request in the process. Conditional on **at least one Server Action**, and *"applications using Pages Router or not using Server Actions are not vulnerable"* — which makes this the **counter-example** to a pattern this file had started to treat as a rule. Three times (CVE-2026-64642, CVE-2026-75604, CVE-2026-94543) an App-Router-only, multi-locale contract turned out to be a security control. Here it is the opposite: `forms` mandates Server Actions for every mutation, so **every project we scaffold is in scope and none can opt out**. A conforming project is not a safe project by construction; the floor is the control.

**2026-11-03 — seven MEDIUM, five of them on the `use cache` / image surfaces we prescribe.** Fixed in **16.4.5** and **15.5.29**, both published that same day; several advisories leave `patched_versions` **empty**, so the floor is taken from the newest release on each line rather than from the field. Four of the seven have ranges ending at `<= 16.4.2` / `<= 15.5.28`, which is the independent confirmation that the fix is later than those.

- **Cross-user cache disclosure and poisoning with binary `use cache` arguments** ([CVE-2026-119349](https://github.com/vercel/next.js/security/advisories/GHSA-rhh4-g77r-r9qj)): passing a **`Uint8Array` or `Blob`** to a `'use cache'` function produces **identical cache keys for distinct arguments**, so one user's cached result is served to another. This is the one to read on any product that caches per-file work — exactly the shape of an OCR or document pipeline, where the argument *is* the bytes.
- **HttpOnly cookie exposure on Edge runtime routes** ([CVE-2026-119346](https://github.com/vercel/next.js/security/advisories/GHSA-f3mh-rxg3-f5g2)): cookies set through `NextResponse` on an **Edge** route handler (or a Pages Router Edge API route) leak into a public `x-middleware-set-cookie` header, duplicating the value and its attributes — so an **HttpOnly session token becomes readable by same-origin JavaScript**. It lands on `module-add auth`: better-auth sets exactly that kind of cookie, and the exposure follows from the route's runtime, not from the auth library. A session cookie set on an Edge route defeats the one flag that was protecting it.
- **Information disclosure across root params via `unstable_cache()`** ([CVE-2026-119790](https://github.com/vercel/next.js/security/advisories/GHSA-mfr8-8qww-v76h)) and **cache leak across root params in nested `'use cache'`** ([CVE-2026-119351](https://github.com/vercel/next.js/security/advisories/GHSA-vc7v-qv4w-wrv8), fixed `16.4.2`): the **third and fourth** instance of the root-param × `use cache` class after CVE-2026-103004, and the same reason it keeps landing on us — golden rule ② puts `[locale]` in the root segment. 119790 has a **complete workaround**: do not nest `'use cache'` inside `unstable_cache()`, which already throws outside the race, so avoiding it closes the hole entirely.
- **Cache poisoning of shared fallback shells in Cache Components** ([CVE-2026-119350](https://github.com/vercel/next.js/security/advisories/GHSA-vvgp-ww4w-46vf)): request-supplied **placeholder route params** poison a blocking fallback shell. The workaround is the detail worth keeping — **`partialPrefetching: true`** — because `data-fetching` presents that flag as the *performance* half of Instant Navigations. It is now also a mitigation, which means the two halves of that feature are no longer independently optional.
- **SVG rejection bypass in image optimization** ([CVE-2026-119347](https://github.com/vercel/next.js/security/advisories/GHSA-7qx7-33qx-rqx2)): on **self-hosted** deployments `/_next/image` can be made to parse an attacker-supplied SVG **even with `dangerouslyAllowSVG: false`**, the default — i.e. the setting we rely on is bypassable, which pairs with the 10-14 `sharp` critical rather than standing alone.
- **Cross-client response injection, self-hosted** ([CVE-2026-119348](https://github.com/vercel/next.js/security/advisories/GHSA-pc58-hwjq-p385)): a route handler returning a fetched upstream response **unchanged** can emit mismatched framing; behind an HTTP/1.1 reverse proxy that queues pipelined responses, clients get each other's responses. Self-hosted only, and conditional on proxying a response through verbatim — a shape `module-add` recipes should not produce, but worth knowing before someone writes a pass-through handler.

**A platform mitigation is not a patch.** For the earlier CVE-2026-23869 Vercel deployed global WAF rules for all hosted projects and still stated the protection "should not be considered a complete substitute for upgrading to a fixed release". Being on Vercel does not exempt a project from the version floor; self-hosted projects have no such net at all. `vercel-deploy` checks this floor before shipping.

Use `null` (not `"none"`) when not yet decided. For `route_groups`, an empty array `[]` means "no route groups, flat routing".

## Asking the user — a choice is asked as a choice

Measured 2026-11-17: **`AskUserQuestion` appears nowhere in these 57 skills.** Every decision in the
flow — the platform, the UI library, the form library, the tracker, the deploy target, the payments
provider — is written in prose (*"Which UI library — shadcn/ui, Base UI, MUI, or Coss/UI?"*), so an
agent reading it writes a sentence. Whether the reader ever sees a selectable list is left to that
agent's mood, which is why it is inconsistent: the same run produced one multiple-choice question and
three paragraphs.

**When a question has a known, closed set of answers, ask it with `AskUserQuestion`.** Not as a
courtesy — a sentence listing four options invites a fifth, an ambiguous one, or a "whatever you
think", and the flow then records a `stack` value nobody actually chose.

- **The recommendation goes inside the options, first and marked**, never implied in the prose around
  them: `"shadcn/ui (consigliata)"` as option one, with the one-line reason in its description. An
  agent that knows the answer and asks neutrally is making the user guess what it already knows.
- **One question per decision**, with its own options. Three decisions in one widget is a form.
- **Open questions stay open.** *"What problem do they have right now?"* has no option list, and
  giving it one turns a product question into a checklist — which is exactly how an interview drifts
  from the problem to the solution.
- **Multi-select only when the answers really compose** (which modules, which locales), never to dodge
  a decision that has one answer.
- A question the user already answered in their paste is not asked again, in any form.
- 🔴 **"Propose the default" is not permission to skip the question.** It means the recommended option
  goes first inside the widget, marked, with its reason. Measured 2026-11-18: the tracker question was
  written as *"propose the default … otherwise Linear"* and a real run put Linear in the plan without
  anyone choosing it. Any line in any skill that says *propose*, *suggest* or *default to* for a
  closed set still asks; only an autonomous run — where nobody can answer — takes the default, and
  then it is written down as `Assumed: <answer> — because <source>`.

## Folder structure conventions

Skills that scaffold a codebase (`design-md-to-app`, `rn-bootstrap`, `monorepo-bootstrap`) MUST generate the canonical folder structure documented in `docs/superpowers/specs/2026-06-06-folder-structure-refactor.md`. Key rules:

- **Co-location via `_components/`**: page-private components live in `app/<route>/_components/`. The underscore prefix is Next.js convention for non-routable folders. **Web only** — this applies to Next.js (`stack.framework ∈ {next, monorepo}` web side). **Expo Router (`stack.framework = "expo-rn"`) has NO private-folder convention** — every file under `app/` becomes a route, so on mobile screen-private components live in `components/<feature>/` **outside** `app/`, not in `app/<route>/_components/` (see `rn-add-screen` / `promote-component`).
- **Shared components by domain**: cross-route-group shared business components live in `components/shared/<dominio>/<Component>.tsx`. The domain folder name is the business domain (post/, user/, billing/), never generic ("shared"/"common"/"global").
- **UI primitives separate**: shadcn/Base UI/MUI primitives live in `components/ui/`. Never mixed with business components, and never authored there by hand (golden rule 3).
- **Theme system explicit**: ThemeProvider + ModeToggle live in `components/theme/`, NOT loose in `components/`.
- **No `src/` directory**: code lives at project root, alongside config files. Aligned with Vercel commerce, Cal.com, and shadcn templates.
- **Route groups opt-in via `route_groups`**: scaffold only the route groups listed in `stack.route_groups`. Never create empty `(marketing)/` for a project that doesn't need it.
- **Rule of Three for promotion**: components stay at the lowest level until used 3+ times. The `promote-component` skill handles the move + import updates.
- **Cross-platform sharing (monorepo)**: only types, Zod schemas, and pure logic in `packages/shared/`. NEVER JSX. Web and mobile UI are separate (each app has its own `components/`).

## File-format conventions

### `compliance` field (owned by `compliance-audit`, fed from the stack decision and every module)

- `data_categories`: array from `"identity-documents"` | `"tax"` | `"health"` | `"biometric"` | `"minors"` | `"financial"` | `"location"` | `"criminal"` | `"special-category-other"` | `"contact"` | `"usage"`. Written by `data_residency.py decide`.
- `sub_processors`: array of `{ name, service, data, region, region_class ("eu" | "adequacy" | "non-eu" | "global" | "unknown"), transfer ("none" | "adequacy" | "dpf" | "scc" | "bcr" | "derogation" | "unknown"), dpa, us_controlled, eu_alternative, flags[], added_by, updated_at }`. Written by `data_residency.py add` — called by `module-add`, `rn-module-add`, `eve-agent` and `compliance-audit` — and rendered to **`docs/compliance/subprocessors.md`** between markers (text outside them is kept). One register, customer-facing; there is no second copy in `.workflow/`.
- `last_audit_at`, `findings`, `remediated`, `flagged`, `high_risk`, `residency_verified_at`: written by `compliance-audit` (its SKILL.md §`meta.json#compliance` block).

### `PROJECT.md`
Free-form prose, one h1 (the project name). Sections expected: **Overview**, **Audience**, **Problem & current alternatives**, **Value proposition**, **Success criteria**, **Out of scope** (optional). Written by `prd-from-idea`.

### `PRD.md`
Free-form prose. Conventional sections: **Problem**, **Solution overview**, **User stories** (`As a … I want …`), **Measurement** (only when the user chose to measure: the activation event, D7/D30 targets, false positives, events to instrument — read by `module-add analytics` and `launch-audit`), **Non-goals**, **Technical constraints**, **Open questions**. Written by `prd-from-idea`.

### `tasks.md`
A checklist compatible with beads / GitHub Issues / Linear import. Each task is a `## ` heading with body, plus a `- [ ]` line for status. Written by `prd-to-tasks`.

### `DESIGN.md`
Strictly conformant to the Google design.md spec — see `figma-to-design-md/references/spec.md`. Written by `figma-to-design-md`, `image-to-design-md`, or by hand (downstream skills consume it).

### `screenshots/`
Raw screenshots of the UI for reference. Filenames should be slugged page names (`home-hero.png`, `pricing-comparison.png`). Written by `figma-to-design-md` and `image-to-design-md`, consumable by `screenshot-to-page`.

### Codebase (project root)
The actual codebase lives at `<project-root>/` (NOT inside `.workflow/`). It's owned by `design-md-to-app` (which scaffolds it) and modified by `screenshot-to-page` and `module-add`. Skills must **not** edit codebase files unless that's their explicit job — the orchestrator routes to the right specialist.

Specifically:
- `<project-root>/package.json`, `<project-root>/app/`, `<project-root>/components/`, `<project-root>/lib/`, etc. — owned by the codebase skills (`design-md-to-app`, `screenshot-to-page`, `module-add`).
- `<project-root>/.workflow/` — owned by the planning skills and by `meta.json` updates from any skill.

These two zones never overlap in writes. If a skill edits both (e.g., `design-md-to-app` writes the codebase AND updates `meta.json`), the contract is: codebase files at root, then `.workflow/meta.json` at end.

## Project slug

`project_slug` is derived from `project_name` by lowercasing, replacing non-alphanumeric with hyphens, and trimming. It must be filesystem-safe (used for things like the `app/` directory name in some templates and for git branch names).

## Project root location

Skills do **not** decide where the project lives. The user (via `dev-flow`) chooses an absolute path; skills receive it as input. The user's current shell `cwd` is *not* assumed to be the project root — verify by checking for `.workflow/meta.json`.

## Backwards compatibility

If a skill encounters a `meta.json` with an unknown `phase` value, it must not crash — it logs a warning and treats it as `empty` for routing purposes. New phases can be added to this contract; old skills will simply skip them.

If a skill encounters fields in `meta.json` it doesn't recognize, preserve them verbatim when rewriting the file.

**`contract_version`** (integer) is the contract version the file conforms to, stamped by every write
through `meta_io.py` (`CONTRACT_VERSION`, today `1`). A file without it predates the field and is
version-1 compatible; it gains the field on its next write. It changes only with a **breaking** contract
change, and then together with the migration that brings older files up to it — additive changes (a new
optional field, a phase appended to the enum) leave it alone. A script never rewrites a file whose
version is higher than the one it knows: it refuses with exit 2 and leaves the file untouched, since it
would save back fields whose meaning it does not have. Reading such a file is allowed, with a warning
(`show_state.py`).

**`meta_digest`** (`{ "sha256", "checked_phase" }`) is stamped by every write through `meta_io.py`, so a
direct edit — allowed as a fallback — can be told from a scripted write. `sha256` hashes the document's
values without the digest (key order and layout ignored, so reformatting is not an edit); when it no
longer matches, `show_state.py` says the file was changed outside the scripts. `checked_phase` is the
last phase the phase gates checked: only `update_meta.py`, after they pass, moves it forward, and every
other writer carries it over. When `phase` is ahead of it, the phase was set by hand: `show_state.py`
names it, and `set-phase` / `append-history --phase-after` check the gates **from `checked_phase`**, so
a phase typed into the file cannot skip them. A file without the field predates it and is trusted as it
is until its next write.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall