@jaimevalasek/aioson 1.33.1 → 1.37.0

package/template/.aioson/docs/verify-artifact-gates.md

@@ -0,0 +1,91 @@
+---
+description: "Artifact done-gates (verify:artifact) — build-free, model-agnostic completeness/integrity checks for the non-code artifacts the specialized agents produce before they register done."
+agents: [setup, genome, profiler-researcher, profiler-enricher, profiler-forge, discover, orache, design-hybrid-forge, site-forge, copywriter, committer, squad]
+task_types: [verification, configuration]
+triggers: [verify:artifact, artifact gate, done gate, artifact done-gate, placeholder gate, kind=]
+---
+
+# Artifact done-gates — `aioson verify:artifact`
+
+The periphery analog of the code pipeline's `SG-*` / `RG-*` harness gates: a
+build-free **"done = proven, not asserted"** check for the **non-code artifacts**
+the specialized agents produce. Where `audit:code` scans code quality and the
+harness contract gates a feature, `verify:artifact` proves a produced artifact is
+complete and well-formed before the agent calls `agent:done`.
+
+The failure mode it closes is the one the runtime smoke gate closed for code: an
+agent self-declaring done with no proof — a `project.context.md` with an invalid
+enum, a genome missing its manifest, a research report with an unfilled
+`[Full Name]`, a generated site that never built.
+
+```bash
+aioson verify:artifact . --kind=<kind> [--slug=<slug>] [--file=<path>] [--advisory] [--strict]
+```
+
+A `kind` routes to either an **existing validator** or a declarative **SG-\***
+**ruleset** over the shared static-criteria engine — pure `fs` + `RegExp` +
+`JSON.parse` / `node --check` (no shell, no build, cross-platform by
+construction). Adding a gate to a new agent is a registry entry plus one
+done-gate line, not a bespoke implementation.
+
+| kind | agent | backed by | default |
+|---|---|---|---|
+| `project-context` | `@setup` | `validateProjectContextFile` (required fields, enums, frontmatter parse) | blocking |
+| `genome` | `@genome`, `@profiler-forge` | `genome:doctor` (manifest/references/anchor/Track-4.3 quality) | blocking |
+| `research-report` | `@profiler-researcher` | ruleset (frontmatter + inventory/extracted/gaps sections, no template token) | blocking |
+| `enriched-profile` | `@profiler-enricher` | ruleset (exec summary / psychometric / operational method / trait interactions) | blocking |
+| `bootstrap` | `@discover` | ruleset (all 4 cold-start files exist with real frontmatter, no placeholder) | blocking |
+| `orache-report` | `@orache` | ruleset, resolved via `--file` (7 dimensions + impact + source) | blocking |
+| `hybrid-skill` | `@design-hybrid-forge` | ruleset (`.skill-meta.json` parses + sources, SKILL.md, both previews) | blocking |
+| `site` | `@site-forge` | static floor + `npm run build` on the real stack | blocking |
+| `copy` | `@copywriter` | ruleset (placeholder / Lorem / TODO / unfilled-token scan) | advisory |
+| `commit-message` | `@committer` | subject heuristics (`--file` draft or HEAD commit) | advisory |
+
+## Contract
+
+- Every gate returns a uniform `{ ok, issues[], warnings[] }`, persists
+  `.aioson/context/verify-artifact-<kind>.json`, and sets **exit 1** on a hard
+  failure — **unless `--advisory`** (warn-only, always exit 0). `--strict`
+  promotes warnings to blocking issues.
+- `--slug` resolves a slug-keyed artifact path; `--file` resolves a
+  caller-known / date-stamped path. A kind that needs one fails with a clean
+  usage error instead of probing a `null/` path.
+- `--no-build` (kind=`site`) runs the static floor only — a fast mid-work
+  re-check that skips the `npm run build` runtime floor.
+
+## Auto-fire at `agent:done`
+
+These gates do not depend on each agent remembering to run its `## Done gate`
+line. `aioson agent:done` resolves the calling agent to its artifact kind
+(`src/artifact-kinds.js`) and runs the matching `verify:artifact --advisory`
+itself — so the check fires at the one call every agent already makes at session
+end (and rides on `agent:epilogue`, which wraps `agent:done`):
+
+- **Self-resolving kinds** (`setup`→`project-context`, `discover`→`bootstrap`,
+  `committer`→`commit-message`) run with no extra input — fully deterministic,
+  no markdown dependency.
+- **Locator-keyed kinds** run when the agent threads its locator into that same
+  call (`--slug` / `--file` / `--dir`, which the agent's Observability line now
+  carries); without it, `agent:done` surfaces a one-line hint naming the exact
+  command, so the gate is visible rather than silently skipped.
+
+Always advisory at this layer: a failed or skipped check is surfaced but never
+flips the session-end result. The explicit per-agent `## Done gate` stays as the
+agent-facing "check and FIX" step; this is the deterministic engine net beneath
+it — the periphery analog of how `audit:code` auto-fires in `agent:epilogue`.
+
+## `@squad` is gated separately
+
+A squad ships through its own `aioson squad:validate` (structural: manifest
+schema, required files, every declared executor file exists, no duplicate slugs,
+canonical paths) plus its source-grounded multi-model **eval-gate** — both
+promoted from opt-in into the default `validate` step. See `@squad`'s Done gate.
+
+## Why this shape
+
+Same philosophy as the `audit_code` gate in `verification-config.md`: build-free,
+model-agnostic, deterministic, and cheap enough to run at **every** agent's done
+gate. It does not judge subjective quality (resonance, voice, persuasiveness) —
+those stay with each agent's own checklist. It proves the artifact is *there*,
+*structured*, and *not a placeholder*, which is exactly what self-asserted "done"
+was silently skipping.

package/template/.aioson/docs/workflow-lean-lane.md

@@ -0,0 +1,129 @@
+---
+name: workflow-lean-lane
+agents: [setup, product, sheldon, dev, qa, validator, neo, orchestrator]
+modes: [planning]
+task_types: [workflow, routing, configuration]
+load_tier: trigger
+triggers: [lean lane, workflow.config.json, fewer agents, menos é mais, lean pipeline]
+---
+
+# Workflow Lean Lane (SMALL default; opt-in for MEDIUM)
+
+SMALL features now run the **lean chain by default**, and MEDIUM runs the **`@orchestrator` maestro lane**
+(`@product → @orchestrator → @dev → @pentester → @qa`), where `@orchestrator` fans out to
+`@analyst`/`@architect`/`@pm` (+ `@ux-ui` when UI-heavy) as sub-agents and consolidates one gated spec
+package, with `@scope-check`, `@discovery-design-doc`, and `@ux-ui` available as opt-in detours. The older heavy chain (`product → analyst → scope-check → architect →
+discovery-design-doc → pm → dev → qa`) is no longer a built-in default, but its spec hops can be opted
+back in. The bottleneck was never "too few design documents", it was the absence of a gate that runs the
+real app (now fixed: see `.aioson/docs/sheldon/harness-contract.md` §2c and `@qa`'s Runtime smoke gate).
+
+The **lean lane** removes the intermediate hops and makes `@sheldon` the single spec authority:
+
+```
+product (PRD) → sheldon (enrich + ACs + design + plan + harness-contract) → dev → qa → (validator detour)
+```
+
+`@sheldon` runs in **Lean lane mode (RF-LEAN)** and produces, in one pass, what analyst/architect/
+discovery-design-doc/pm would have produced (requirements + ACs, design-doc + readiness, implementation plan,
+and the §2c runtime-gated harness contract). `@dev` implements from that plan using the project's design skill;
+`@qa` runs the Runtime smoke gate; `@validator` runs as a detour when a harness contract exists.
+
+## When to use which lane
+
+| Use the **lean lane** when… | Opt into the **full chain** when… |
+|---|---|
+| Most features — bounded scope, a single product surface, a clear prototype | Genuinely large or multi-domain scope |
+| You want velocity and one spec authority | Sensitive surface (money, multi-tenant ownership, regulated data) that wants independent architecture + scope-check + adversarial review as distinct gates |
+| The team trusts `@sheldon` to own the bridge | You want the readiness/scope-check checkpoints to be separate agents |
+
+The **runtime smoke gate is mandatory in both lanes** for every runtime surface the framework can prove from
+local artifacts. The CLI blocks detectable runtime features (prototype manifest or migration/Prisma evidence)
+without a valid `RG-*` contract; `@validator` still owns the target-app-only `has_api` judgment.
+
+## How to opt in
+
+SMALL already ships lean — no config needed. Use this preset to extend the lean shape to MEDIUM (or to pin it
+explicitly). Drop this file at `.aioson/context/workflow.config.json` (the CLI's `readWorkflowConfig` merges it over the
+built-in defaults — per-classification arrays replace the defaults). Then run `aioson workflow:next .` as usual.
+
+A ready-to-copy preset lives at `.aioson/docs/presets/workflow.config.lean.json`:
+
+```json
+{
+  "version": 1,
+  "feature": {
+    "MICRO": ["product", "dev", "qa"],
+    "SMALL": ["product", "sheldon", "dev", "qa"],
+    "MEDIUM": ["product", "sheldon", "dev", "qa"]
+  },
+  "project": {
+    "MICRO": ["setup", "dev"],
+    "SMALL": ["setup", "product", "sheldon", "dev", "qa"],
+    "MEDIUM": ["setup", "product", "sheldon", "dev", "qa"]
+  },
+  "rules": { "required": ["dev"], "allowDetours": true }
+}
+```
+
+`allowDetours: true` keeps `@validator` (harness contract present) and `@tester`/`@pentester` (fired by `@qa`'s
+triggers) available as detours — they are not in the static sequence in either lane.
+
+Autopilot (`auto_handoff: true`) drives only the **post-dev** cycle (`@dev → @qa → …`) in the lean lane:
+`@product`/`@sheldon` always hand off manually (upstream-agent policy), so there is nothing to auto-chain before
+`@dev`. This matches the MEDIUM maestro lane, whose `@product`/`@orchestrator` pre-dev handoffs are also manual —
+so the lean lane loses no automation it was ever supposed to have.
+
+Running the agents by hand (slash commands) is equivalent: activate `@product → @sheldon → @dev → @qa` and skip
+analyst/architect/discovery-design-doc/pm. No config file is needed for the manual path.
+
+## Full-merged chain (heavier, opt-in)
+
+The lean/maestro defaults are enough for most work. When a project genuinely wants the heavier multi-agent
+chain back — independent `@analyst`, `@architect`, and `@pm` as distinct gates — drop the **full-merged**
+preset at `.aioson/context/workflow.config.json` (ready-to-copy at
+`.aioson/docs/presets/workflow.config.full-merged.json`): it is that chain with `discovery-design-doc`
+removed. On this full-merged detour, when the active sequence routes `@architect` → `@dev` while omitting
+`@discovery-design-doc`, `@architect` runs in **merged mode** (see `agents/architect.md` → *Architect merged
+mode*) and produces the design-doc + readiness + dev-state itself, then hands off to `@dev`. Merging `@architect` +
+`@discovery-design-doc` keeps the readiness gate (the cheap, valuable part) while dropping the redundant
+second file-level-plan hop; it is a velocity change, not a correctness one — the runtime gate is what
+prevents the green-but-broken outcome.
+
+```json
+{
+  "version": 1,
+  "feature": {
+    "MICRO": ["product", "dev", "qa"],
+    "SMALL": ["product", "analyst", "scope-check", "architect", "dev", "qa"],
+    "MEDIUM": ["product", "analyst", "architect", "pm", "scope-check", "dev", "pentester", "qa"]
+  },
+  "project": {
+    "MICRO": ["setup", "dev"],
+    "SMALL": ["setup", "product", "analyst", "scope-check", "architect", "dev", "qa"],
+    "MEDIUM": ["setup", "product", "analyst", "architect", "ux-ui", "pm", "orchestrator", "scope-check", "dev", "qa"]
+  },
+  "rules": { "required": ["dev"], "allowDetours": true }
+}
+```
+
+## What this does NOT change
+
+- The override mechanism is unchanged — `readWorkflowConfig` still merges `workflow.config.json` over the
+  built-in defaults (per-classification arrays replace the defaults). Only the built-in default *shape* changed
+  (SMALL ships lean, MEDIUM ships the `@orchestrator` maestro lane); the lean lane stays a project-level config +
+  agent capability, not a different engine.
+- The runtime safety gates are unchanged: `@qa`'s Runtime smoke gate, the §2c `RG-*` criteria, the CLI
+  contract-integrity backstop, and `@validator`'s target-app judgment apply identically in both lanes.
+
+## What the lean lane DOES change about the gates
+
+Removing `@analyst`/`@pm` removes the agents that produced `spec-{slug}.md` and approved the process gates
+A (requirements), B (design) and C (plan). Those gates still fire under `aioson workflow:next` — `@dev`'s
+completion checks **Gate C** against `spec-{slug}.md`, and `@qa`'s checks **Gate D** against the same file — so
+the lean lane would dead-end at `@dev` if nothing produced them. In the lean lane **`@sheldon` owns that**: its
+RF-LEAN pass writes `spec-{slug}.md` with `gate_requirements`/`gate_design`/`gate_plan: approved` and an
+`implementation-plan-{slug}.md` with `status: approved` (the hops it collapsed, after the user confirms its
+spec-authority output). Gate D / execution stays with `@qa`, which writes the `## QA sign-off` PASS into the same
+file after the Runtime smoke gate. If you run the lane by hand (slash
+commands, untracked), the gate frontmatter is informational — but writing it keeps the manual and tracked paths
+identical.

package/template/.aioson/skills/design/interface-design/SKILL.md

@@ -28,6 +28,23 @@ It helps the agent make strong decisions when the user wants a deliberate, high-
 - Do not combine it with any other design skill.
 - Use it when the user wants strong design craft but has not asked for a very specific visual system.
 
+## Identity resolution (run FIRST, before any visual decision)
+
+Resolve an `identity.md` in this order: `.aioson/briefings/{slug}/identity.md` (feature scope) →
+`.aioson/context/identity.md` (project brand) → none.
+
+- **If one exists, it is the identity source of truth this engine APPLIES**: take palette,
+  typography, spacing/layout, radius & depth, motion, design pillars, and signature moves from it as
+  the token layer, and feed its `## Component structure notes` into component/screen decisions. It is
+  extracted **data** (from the user's reference images via `reference-identity-extract`) that
+  parameterizes this one engine — never a second design skill, and never a license to skip the
+  quality gates below.
+- **If none exists**, run intent-first: choose the surface type, domain palette, and signature move
+  yourself per the references. Do not fabricate an `identity.md`.
+
+Every consumer of this package (ux-ui, prototype-forge, dev builds) inherits this step by loading
+this SKILL — see `.aioson/docs/reference-identity.md`.
+
 ## Loading guide
 
 | Task | Load |

package/template/.aioson/skills/design/interface-design/references/intent-and-domain.md

@@ -19,6 +19,8 @@ If `.interface-design/system.md` exists, treat it as the visual source of truth:
 - Respect it unless the user explicitly wants a redesign.
 - Update it when you introduce a reusable pattern, token rule, or layout decision.
 
+If an `identity.md` exists (`.aioson/briefings/{slug}/identity.md`, else `.aioson/context/identity.md`), treat it as the visual source of truth too — it is the **extracted-from-references** form of `system.md`, distilled once from the user's own reference images (see `.aioson/docs/reference-identity.md`). Load its token sections and `## Component structure notes` before choosing a direction, and **apply** them rather than re-deriving a generic one. It is an input you apply, not a separate design system.
+
 If the file does not exist and the task covers more than one screen or component family, create it with:
 - Product context and UI intent
 - Chosen design direction and anti-goals

package/template/.aioson/skills/process/aioson-spec-driven/SKILL.md

@@ -5,15 +5,15 @@
 
 ## When to use
 
-Load this skill when:
-- starting spec work for a new feature or project (any agent)
-- deciding phase depth based on classification (MICRO / SMALL / MEDIUM)
-- preparing a clean handoff to the next agent
-- retaking work after a session break (check `last_checkpoint` + `phase_gates` first)
-
-Do not load this skill for `@deyvin` activation-only recovery. A bare `@deyvin` activation is status recovery, not spec work; run Deyvin's fast path and stop before opening this file.
-
-Do NOT load the entire `references/` folder. Load only the file matching your current need.
+Load this skill when:
+- starting spec work for a new feature or project (any agent)
+- deciding phase depth based on classification (MICRO / SMALL / MEDIUM)
+- preparing a clean handoff to the next agent
+- retaking work after a session break (check `last_checkpoint` + `phase_gates` first)
+
+Do not load this skill for `@deyvin` activation-only recovery. A bare `@deyvin` activation is status recovery, not spec work; run Deyvin's fast path and stop before opening this file.
+
+Do NOT load the entire `references/` folder. Load only the file matching your current need.
 
 ## What phases exist
 
@@ -21,9 +21,9 @@ Do NOT load the entire `references/` folder. Load only the file matching your cu
 |-------|----------------|---------------|-------|-------|--------|
 | Specify | `prd*.md` | @product | lite | full | full |
 | Research/Discuss | `sheldon-enrichment*.md` | @sheldon | optional | recommended | required |
-| Requirements | `requirements-{slug}.md` | @analyst | skip | required | required |
-| Alignment Check | `scope-check*.md` | @scope-check | skip | early | final before dev |
-| Design | `architecture.md`, `design-doc*.md` | @architect | skip | selective | required |
+| Requirements | `requirements-{slug}.md` | @analyst | skip | required | required |
+| Alignment Check | `scope-check*.md` | @scope-check (detour) | skip | opt-in detour | opt-in detour |
+| Design | `architecture.md`, `design-doc*.md` | @architect | skip | selective | required |
 | Tasks/Plan | `implementation-plan*.md` | @dev | optional | recommended | required |
 | Execute | code, commits, spec updates | @dev, @deyvin | — | — | — |
 | State/Resume | `spec*.md`, runtime | @dev, @deyvin | — | — | — |
@@ -31,8 +31,10 @@ Do NOT load the entire `references/` folder. Load only the file matching your cu
 ## Phase depth by classification
 
 - **MICRO**: Specify (lite) + Execute. Skip Requirements, Design, Plan unless complexity warrants it.
-- **SMALL**: Specify + Requirements + scope check + selective Design + Plan. @sheldon recommended before downstream.
-- **MEDIUM**: Full pack — all phases, all artifacts, @sheldon validation before @analyst, final scope check before @dev, implementation plan required.
+- **SMALL**: lean by default — Specify (`@product`) + `@sheldon` as the single spec authority (requirements + ACs, design-doc + readiness, plan, and harness contract in one pass) → `@dev` → `@qa`. The heavier multi-agent chain (`@analyst` + selective Design + `@scope-check` detour) is an opt-in escape hatch.
+- **MEDIUM**: `@orchestrator` maestro — `@product → @orchestrator → @dev → @pentester → @qa` (feature). `@orchestrator` is the single spec authority: it fans out to `@analyst` + `@architect` + `@pm` (+ `@ux-ui` when UI-heavy) as sub-agents, then consolidates/verifies/redoes their output into one gated spec package (requirements + spec[Gates A/B/C] + design-doc + readiness + implementation-plan + harness-contract) for `@dev` — the horizontal counterpart to `@sheldon`'s lean lane. `@analyst`, `@architect`, `@pm`, `@discovery-design-doc`, `@scope-check`, and `@ux-ui` are no longer default hops (sub-agents the orchestrator invokes) and remain opt-in detours; `@architect`'s merged mode survives only for the opt-in full-chain detour. The deterministic drift check (`spec:analyze`) runs at the `@dev`/`@qa` done gate, not as a separate scope-check hop. Implementation plan required.
+
+**Lean lane (SMALL default; opt-in for MEDIUM):** `@product → @sheldon → @dev → @qa`, where `@sheldon` runs **Lean lane mode (RF-LEAN)** and produces the requirements/ACs, design-doc + readiness, implementation plan, and §2c runtime-gated harness contract in one pass — replacing the analyst/architect/discovery-design-doc/pm hops. SMALL runs this by default; MEDIUM opts in via `.aioson/context/workflow.config.json`. See `.aioson/docs/workflow-lean-lane.md`. The runtime smoke gate is mandatory in both lanes.
 
 ## References available
 

package/template/.aioson/skills/process/aioson-spec-driven/references/approval-gates.md

@@ -5,7 +5,7 @@
 
 ## Gate A — Requirements approval
 
-**Before leaving @product / @analyst → @scope-check, @architect, or @dev**
+**Before leaving @product / @analyst → @architect or @dev (`@scope-check` only when its opt-in detour is in the sequence)**
 
 Required for the gate to pass:
 - [ ] Objectives are clear and unambiguous
@@ -54,7 +54,7 @@ Required for the gate to pass:
 Required for the gate to pass:
 - [ ] Execution sequence is defined
 - [ ] Checkpoints are listed with criteria of done
-- [ ] Context package is listed as a short primary activation package plus phase-triggered loads (which files to read before each phase, and why)
+- [ ] Context package is listed as a short primary activation package plus phase-triggered loads (which files to read before each phase, and why)
 - [ ] Review / QA requirements are noted
 - [ ] Decisions marked "pre-taken" are FINAL — @dev does not re-discuss
 

package/template/.aioson/skills/process/aioson-spec-driven/references/classification-map.md

@@ -7,10 +7,10 @@
 | Phase | MICRO (0–1) | SMALL (2–3) | MEDIUM (4–6) |
 |-------|-------------|-------------|--------------|
 | Specify (PRD) | 1 conversation, lite template | Full PRD conversation | Full PRD + `## Specify depth` section |
-| Research (@sheldon) | Skip unless links/external sources provided | Recommended — run before @analyst | Required — run Modo C (full validation) |
-| Requirements (@analyst) | Skip — go @product → @dev | Required — `requirements-{slug}.md` | Required — with requirement IDs + ACs |
-| Design (@architect) | Skip unless auth or external integration | Selective — only if new architecture pattern | Required — full `architecture.md` |
-| Plan (implementation-plan) | Optional — suggest only if @dev asks | Recommended | Required — with gate approval + verification criteria |
+| Research (@sheldon) | Skip unless links/external sources provided | Required — `@sheldon` is the single spec authority (lean default) | Required — folded into the `@orchestrator` maestro fan-out (consolidated, not a separate `@sheldon` hop) |
+| Requirements (@analyst) | Skip — go @product → @dev | From `@sheldon` in the lean default; `@analyst` only on the full-chain detour | Required — produced via the `@orchestrator` maestro fan-out (`@analyst` sub-agent), with requirement IDs + ACs |
+| Design (@architect) | Skip unless auth or external integration | From `@sheldon` in the lean default; `@architect` only on the full-chain detour | Required — produced via the `@orchestrator` maestro fan-out (`@architect` sub-agent), design-doc + `architecture.md` |
+| Plan (implementation-plan) | Optional — suggest only if @dev asks | Recommended | Required — produced via the `@orchestrator` maestro fan-out (`@pm` sub-agent), with gate approval + verification criteria |
 | Execute (@dev) | Direct from PRD | From requirements + spec | From approved plan only |
 | State (@dev, @deyvin) | Minimal `spec.md` note | `spec-{slug}.md` with phase_gates | Full spec pack — phase_gates + checkpoints + maintenance notes |
 

package/template/.aioson/skills/process/aioson-spec-driven/references/dev.md

@@ -2,15 +2,15 @@
 
 > Router file. Do not duplicate logic from the generic references — load those directly.
 
-## Which references to load for implementation
-
-### Always load when this skill is active
-
-- `maintenance-and-state.md` — use to write and update `spec-{slug}.md` correctly: `phase_gates`, `last_checkpoint`, `pending_review`, and `Key decisions` format
-- `approval-gates.md` — Gate C (plan approval) must be checked before executing a significant batch; Gate D (execution verification) defines done criteria for each phase
-- For SMALL/MEDIUM work, confirm `.aioson/context/design-doc*.md` and `.aioson/context/readiness*.md` were produced by `@discovery-design-doc` before implementation starts. Load them only when `dev-state.md`, readiness, the plan, or touched paths require their details.
-
-### Load when starting a new feature with classification context
+## Which references to load for implementation
+
+### Always load when this skill is active
+
+- `maintenance-and-state.md` — use to write and update `spec-{slug}.md` correctly: `phase_gates`, `last_checkpoint`, `pending_review`, and `Key decisions` format
+- `approval-gates.md` — Gate C (plan approval) must be checked before executing a significant batch; Gate D (execution verification) defines done criteria for each phase
+- For SMALL/MEDIUM work, confirm `.aioson/context/design-doc*.md` and `.aioson/context/readiness*.md` exist before implementation starts — produced by `@orchestrator` (maestro mode) on MEDIUM, by `@sheldon` on the SMALL lean lane, or by `@architect` (merged mode) / `@discovery-design-doc` when those detours are in the sequence. Load them only when `dev-state.md`, readiness, the plan, or touched paths require their details.
+
+### Load when starting a new feature with classification context
 
 - `classification-map.md` — use to confirm whether an implementation plan is optional (MICRO), recommended (SMALL), or required (MEDIUM) before starting
 
@@ -35,7 +35,7 @@ At session start, after reading `spec-{slug}.md`:
 3. If versions match: proceed normally
 
 Additionally, at session start for SMALL/MEDIUM:
-4. Run `aioson ac:test-audit . --feature={slug}` when a feature slug exists, or manually check that each `AC-*` from `requirements-{slug}.md` appears in a corresponding test file
+4. Run `aioson ac:test-audit . --feature={slug}` when a feature slug exists, or manually check that each `AC-*` from `requirements-{slug}.md` appears in a corresponding test file
 5. If coverage is < 50%:
    > "⚠ AC coverage is low ({N}/{M} ACs have tests). Consider writing missing tests before adding new behavior."
    This is informational, not blocking.
@@ -43,8 +43,8 @@ Additionally, at session start for SMALL/MEDIUM:
 ## Behavioral notes
 
 - `spec-{slug}.md` must be updated at the end of every implementation session — see `maintenance-and-state.md` for format
-- Gate C from `approval-gates.md` means the implementation plan is locked — do not re-discuss pre-taken decisions
-- Treat `dev-state.md` as the primary activation package and `implementation-plan-{slug}.md` as the source for phase-triggered context loads
-- Gate D verification must happen before marking a phase complete — not just "I think it works". The deterministic floor is `aioson ac:test-audit . --feature={slug}` plus the real test command.
-- If `phase_gates.plan` is `pending` and classification is SMALL/MEDIUM, suggest generating an implementation plan before proceeding
-- If `design-doc.md` or `readiness.md` is missing for SMALL/MEDIUM, route to `@discovery-design-doc` instead of coding first
+- Gate C from `approval-gates.md` means the implementation plan is locked — do not re-discuss pre-taken decisions
+- Treat `dev-state.md` as the primary activation package and `implementation-plan-{slug}.md` as the source for phase-triggered context loads
+- Gate D verification must happen before marking a phase complete — not just "I think it works". The deterministic floor is `aioson ac:test-audit . --feature={slug}` plus the real test command.
+- If `phase_gates.plan` is `pending` and classification is SMALL/MEDIUM, suggest generating an implementation plan before proceeding
+- If `design-doc.md` or `readiness.md` is missing for SMALL/MEDIUM, route back to their producer instead of coding first — `@orchestrator` (maestro mode) on MEDIUM, `@sheldon` on the SMALL lean lane, or `@architect` (merged mode) / `@discovery-design-doc` when those detours are active

package/template/.aioson/skills/process/prototype-forge/SKILL.md

@@ -39,6 +39,12 @@ not in the design skill's.
    `.aioson/docs/feature-expansion-taxonomy.md`.
 2. `.aioson/briefings/{slug}/briefings.md` for problem, users, and the chosen direction.
 3. `design_skill` from `.aioson/context/project.context.md`; load that skill before any layout.
+4. When `design_skill: interface-design`, resolve an `identity.md` — `.aioson/briefings/{slug}/identity.md`,
+   else `.aioson/context/identity.md`. If one exists it is the visual source of truth the engine **applies**:
+   tokens come from its `## Palette` / `## Typography` / `## Spacing & layout` / `## Radius & depth` /
+   `## Motion` sections, and its `## Component structure notes` augment the surface map (input 1) with
+   per-component regions, anatomy, and states. `identity.md` overlays the one engine — it is **not** a
+   second visual system. If none exists, `interface-design` runs intent-first.
 
 If no operational surface map exists, build one first — it is the screen inventory, and without it the
 prototype cannot be complete.

package/template/.aioson/skills/process/reference-identity-extract/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: reference-identity-extract
+description: "Process skill that distills user-provided reference images — a brand/visual-identity set and an optional component/structure set — into a single text identity.md (token system + per-component structure notes) ONCE, so the build consumes text, not images. Use inside @briefing-refiner (or @setup for project-wide brand) when the user wants a specific, premium look driven by their own references instead of a fixed preset. Pairs with the interface-design engine: identity.md is the extracted-from-references form of its system.md. Owns extraction + the identity record; never owns the build."
+---
+
+# Reference Identity Extract
+
+Turn **reference images** into a **text identity record** that the `interface-design` engine
+applies. The user drops images — their brand, a product they admire, a screen they want — and this
+skill reads them **once** (vision) and writes `identity.md`: real tokens (palette, type, spacing,
+depth, motion, signature moves) plus per-component **structure notes**. Every later build reads the
+**text**, never the images.
+
+Why text, not images on every build: the build then runs on any harness (a vision-less harness still
+reads the record), the user can **correct** the extracted palette, the record is **gateable**
+(`verify:artifact --kind=identity`), and two extractions can't silently disagree — the frozen text is
+the source of truth.
+
+This generalizes what AIOSON already does when it extracts a real website into a token spec: same
+idea, but the **source** is images and the **lifetime** is per-briefing (or per-project brand), not a
+frozen preset.
+
+## Division of labor (do not blur)
+
+- **This skill owns** extraction + the `identity.md` record: tokens from identity images, structure
+  notes from component/screen images.
+- **`interface-design` owns the build**: it *applies* `identity.md` as its identity source-of-truth.
+  `identity.md` is an INPUT that parameterizes the one engine — never a second design skill.
+- **`prototype-forge` owns** screens/navigation/CRUD/state; it reads `identity.md`'s
+  `## Component structure notes` to seed its surface map.
+
+## Two image roles (keep them separate)
+
+| role | folder | feeds |
+|---|---|---|
+| **Visual identity** (brand: color, type, texture, feel) | `references/identity/` | the token sections |
+| **Component / structure** (a board, a table, a screen) | `references/structure/` | `## Component structure notes` → the surface map |
+
+Synthesis = **apply the identity to the structure**. A component image contributes layout/structure
+*only* — its own colors/fonts are ignored; the look comes from the identity images.
+
+## Scope & paths (resolve before writing)
+
+- **Per-briefing (default):** record `.aioson/briefings/{slug}/identity.md`; images in
+  `.aioson/briefings/{slug}/references/identity/` and `.../references/structure/`.
+- **Project brand:** record `.aioson/context/identity.md`; images in
+  `.aioson/context/brand-references/identity/` and `.../brand-references/structure/`.
+
+Read order used by every consumer (`@ux-ui`, `prototype-forge`): per-briefing → project brand → none.
+The **text record is canonical and committed**; the images are raw source and may be `.gitignore`d —
+extraction is one-time, so the build never needs them again.
+
+## Inputs (read in this order)
+
+1. Scope + target path (briefing `{slug}`, or `brand`).
+2. Every file under `references/identity/` and `references/structure/` for that scope.
+3. `.aioson/context/project.context.md` for `design_skill` / domain (and to confirm interface-design).
+
+## Build contract (enforceable)
+
+1. **One vision pass, then text only.** Read each image once. Identity images →
+   palette/type/spacing/radius/depth/motion/signature/anti-goals. Structure images → one
+   `### {component}` block each (regions, anatomy, state matrix, interactions). After this pass the
+   build never touches images again.
+2. **Real values, never placeholders.** Emit concrete hex, named font stacks, numeric scales. Do not
+   leave `#RRGGBB`, `{hex}`, `{token}`, `TODO`, `Lorem ipsum`, or any unfilled token — the gate
+   rejects them.
+3. **Map to interface-design token families.** Palette → foreground/background/border/brand/semantic;
+   type → display/body/mono + scale; spacing/radius/depth → the engine's families. Pick **exactly one**
+   depth strategy (`borders-only` | `subtle-shadows` | `layered-surfaces`).
+4. **Anti-sameness anchors are mandatory.** `## Design pillars` (2–3) and `## Signature moves` (1–3,
+   something that could only belong to THIS product) must be present and specific — they are what
+   defeat the generic look.
+5. **Structure notes drive the surface map.** Each `### {component}` lists regions, anatomy, the
+   empty/loading/error/populated/permission states, and the interactions. If no structure images were
+   given, write `None — identity-only` under `## Component structure notes`.
+6. **Self-gate before handing back.** Run
+   `aioson verify:artifact . --kind=identity --file=<path> --advisory 2>/dev/null || true` and fix any
+   reported gap before returning.
+7. **Generic provenance.** `## Provenance` describes the sources by type only (e.g. "3 identity
+   images, 1 board screenshot"). Never name an external product, brand, site, or tool in any field.
+
+## identity.md schema (write exactly these headers)
+
+```markdown
+---
+kind: identity
+scope: briefing            # briefing | brand
+slug: {slug}               # briefing slug, or "project" for brand scope
+source: references         # references (from images) | intent (image-less fallback)
+generated_by: reference-identity-extract
+generated_at: {YYYY-MM-DD}
+confidence: high           # high | medium | low — how well the images pinned each token
+theme: light-dark          # light | dark | light-dark
+base_unit: 4px
+---
+
+## Design pillars
+- <2–3 specific pillars; the primary anti-sameness anchor>
+
+## Palette
+- foreground/primary: #RRGGBB   ← real hex only
+- foreground/secondary: #RRGGBB
+- background/base: #RRGGBB
+- background/surface: #RRGGBB
+- border/default: rgba(…)
+- brand/primary: #RRGGBB
+- semantic/success | warning | danger | info: #…, #…, #…, #…
+
+## Typography
+- display / body / mono: "<family>", <fallback stack>
+- scale: page <px/weight>, section <px/weight>, body <px/weight/line-height>, meta <px/weight>
+
+## Spacing & layout
+- base: 4px — scale: 4, 8, 12, 16, 24, 32
+- breakpoints: mobile <px> / tablet <px> / desktop <px>
+- grid: <cols>-col, gutter <px>
+
+## Radius & depth
+- radius ladder: sharp <px> / medium <px> / large <px>
+- depth strategy: borders-only        ← exactly ONE of borders-only | subtle-shadows | layered-surfaces
+
+## Motion
+- posture: <duration/easing>; entrances <description>
+- reduced-motion: honor prefers-reduced-motion
+
+## Signature moves
+- <1–3 moves that could only belong to THIS product; second anti-sameness anchor>
+
+## Anti-goals
+- <3 generic defaults this identity explicitly replaces>
+
+## Component structure notes
+<one ### block per structure image, or "None — identity-only">
+
+### Board
+- regions: <…>
+- anatomy: <…>
+- states: empty, loading, error, populated, permission-denied
+- interactions: <add / move / edit / archive / …>
+
+## Provenance
+- Generic only. e.g. "identity references: 3 images; structure references: 1 board screenshot."
+```
+
+## Image-less fallback (no references given)
+
+Do **not** fabricate a palette. Either:
+- **(default)** write nothing and let `interface-design` run its own Phase 0 (intent-first) — its
+  domain palette + signature move already defeat sameness; or
+- if the user wants a **persisted** system anyway, run interface-design Phase 0 yourself and write
+  `identity.md` with `source: intent` and the same schema (still no placeholders).
+
+## Cross-harness note
+
+A vision-less harness cannot run the extraction pass. There, either run extraction once on a
+vision-capable harness, or hand-author `identity.md` from the schema above — the gate then proves it
+is complete. The build is identical in both cases because it only ever reads the text.
+
+## Output
+
+- The `identity.md` record at the resolved path (briefing or project scope).
+- Nothing else. This skill never builds UI, never edits `briefings.md`, and never becomes canonical
+  feedback — it produces the identity record the build consumes.

package/template/.aioson/skills/static/multi-agent-patterns.md

@@ -28,11 +28,11 @@ When Evaluator finds issues:
 
 ### Session isolation
 
-Each role should run from a compact operational handoff:
-- Planner sessions: produce artifacts, then /compact for same-feature continuation
-- Generator sessions: read spec pack + implement, then /compact for same-feature continuation
-- Evaluator sessions: read code + spec + verify, then /compact for same-feature continuation
-- Use /clear only for a hard reset, feature switch, polluted context, or security-sensitive reset
+Each role should run from a compact operational handoff:
+- Planner sessions: produce artifacts, then /compact for same-feature continuation
+- Generator sessions: read spec pack + implement, then /compact for same-feature continuation
+- Evaluator sessions: read code + spec + verify, then /compact for same-feature continuation
+- Use /clear only for a hard reset, feature switch, polluted context, or security-sensitive reset
 
 Cross-role communication happens through artifacts on disk, not conversation history.