@jaimevalasek/aioson 1.30.2 → 1.36.0

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/briefing-expansion-scout/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: briefing-expansion-scout
-description: "Briefing process skill for early feature expansion scouting. Use in @briefing or @briefing-refiner when an idea may have a rich surface and the user wants to explore whether it is worth pursuing before PRD: tools, workflows, generators, dashboards, editors, collaboration, automation, templates, media outputs, or Trello/CRM/Kanban-like systems."
+description: "Briefing process skill for early feature expansion and operational surface scouting. Use in @briefing or @briefing-refiner when an idea may have a rich surface and the user wants to explore whether it is worth pursuing before PRD: tools, workflows, generators, dashboards, editors, collaboration, automation, templates, media outputs, workspace/board/card systems, operational CRUD, or Trello/CRM/Kanban-like systems."
 ---
 
 # Briefing Expansion Scout
@@ -22,11 +22,25 @@ Also read existing expansion artifacts when present:
 Run only when one is true:
 
 - user asks to explore, expand, evaluate, or pressure-test an idea
-- the idea has a rich surface: workflow, collaboration, editor/builder, generator, dashboard, automation, templates, media output, repeated operational use
+- the idea has a rich surface: workflow, collaboration, editor/builder, generator, dashboard, automation, templates, media output, repeated operational use, workspaces, boards, operational CRUD, or admin/management surfaces
 - briefing-refiner detects that an existing briefing feels too thin for team discussion
 
 If the idea is a tiny bugfix or a one-field CRUD addition, skip and say the normal briefing path is enough.
 
+## Operational Surface Scout
+
+Before writing the artifact, build the Operational Surface Map from `.aioson/docs/feature-expansion-taxonomy.md`.
+
+Treat this as discovery pressure, not committed PRD scope:
+
+- Name the likely Core objects and their parent/owner relationships.
+- For each Core object, identify the minimum management surface that must exist if the product ships.
+- Flag missing create/edit/delete/archive/restore paths as gaps, not optional polish.
+- For Trello/Kanban/CRM-style ideas, assume workspace/account home, board/list index, main work surface, item detail, empty states, and permission boundaries are relevant unless evidence says otherwise.
+- Keep speculative objects in Recommended MVP / Optional / V2 buckets until the user approves them.
+
+If the plan says "Trello-like", "board", "card", "workspace", "pipeline", "CRM", "dashboard", "admin", or "manage X", the scout must explicitly answer: where does the user create/manage each object, and what happens when there are none?
+
 ## Output
 
 Write `.aioson/briefings/{slug}/expansion-scout.md`.
@@ -44,6 +58,13 @@ Use this structure:
 | Lens | Useful possibilities | Why it matters | Risk |
 |---|---|---|---|
 
+## Operational Surface Map
+| Object | Parent / owner | Lifecycle states | Required actions | Management surface | Empty / error states | Bucket |
+|---|---|---|---|---|---|---|
+
+## Missing Management Surfaces
+- ...
+
 ## Likely MVP Shape
 - Core:
 - Recommended MVP:
@@ -67,6 +88,7 @@ Proceed to product definition? yes / no / only after questions.
 - Mark assumptions explicitly.
 - Separate attractive ideas from useful ideas.
 - Prefer 3-7 high-signal possibilities over exhaustive lists.
+- Do not let "simple MVP" mean "core object exists but cannot be managed."
+- A Core object without add/edit/list/archive behavior is a blocking gap in the briefing, not a V2 suggestion.
 - Do not approve V2 ideas; park them.
 - Do not modify the PRD.
-

package/template/.aioson/skills/process/design-hybrid-forge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design-hybrid-forge
-description: Process skill that creates project-local hybrid design skills by fusing exactly two primary AIOSON design skills, with optional limited modifiers. When activated, guides you through pair selection, identity synthesis, crossover spec, skill generation, preview creation, metadata, and optional promotion.
+description: Process skill that creates project-local hybrid design skills by fusing exactly two primary design parents — each a local AIOSON design skill or an external DESIGN.md source (refero.design md-example or similar) — with optional limited modifiers. When activated, guides you through pair selection, identity synthesis, crossover spec, skill generation, preview creation, metadata, and optional promotion.
 activation: |
   You are now running the design-hybrid-forge process. Begin by asking the user for the names of the two primary AIOSON design skills they want to combine, then ask whether they want optional modifiers. Use up to two modifiers by default, or up to three only when the active variation preset or the user explicitly enables advanced mode. Follow the phases described in this skill.
 ---
@@ -88,8 +88,8 @@ Each phase must complete before the next begins. Do not skip phase 2 and 3 — t
 ## Input contract
 
 ```
-primary_a: {skill-name}            # e.g. "cognitive-core-ui"
-primary_b: {skill-name}            # e.g. "glassmorphism-ui"
+primary_a: {skill-name}            # local AIOSON skill (e.g. "cognitive-core-ui") OR external:{DESIGN.md} (e.g. "external:linear")
+primary_b: {skill-name}            # local AIOSON skill (e.g. "glassmorphism-ui") OR an external DESIGN.md source (refero.design md-example / similar)
 modifiers: {optional 0..2}         # e.g. ["bold-editorial-ui"] or ["threejs-spatial"]
                                   # threejs-spatial is a special modifier: it layers WebGL/Three.js
                                   # on any primary pair, adding particle/3D scene as visual substrate
@@ -130,6 +130,7 @@ The hybrid must satisfy ALL of the following:
 | `references/output-contract.md` | Running phases 4 and 5 (file generation) |
 | `references/naming-registry.md` | Naming the hybrid and checking for conflicts |
 | `references/quality-gates.md` | Validating the hybrid before shipping (distribution / promotion gates) |
+| `references/external-source-ingestion.md` | Ingesting an external DESIGN.md (refero.design md-example or similar) as a parent or modifier |
 
 ## Non-negotiable rules
 
@@ -145,3 +146,4 @@ The hybrid must satisfy ALL of the following:
 10. Project-local generation goes to `.aioson/installed-skills/` by default. Promotion to core is a separate, explicit step.
 11. `design-hybrid:options` creates a temporary preset in `.aioson/context/design-variation-preset.md`; after successful generation, archive or remove the active preset and preserve the history snapshot.
 12. **`threejs-spatial` modifier rules:** It is NOT a primary parent. It layers WebGL/Three.js as a visual enhancement on the chosen primary pair. It does not own substrate (CSS gradient is still the base), does not own structure (HTML layout is CSS), and does not own tokens. Accent colors from primary parents MUST flow through Three.js parameters. Three.js CDN (no npm install) is the only supported delivery mode.
+13. **External DESIGN.md sources:** A primary parent or modifier may be an external DESIGN.md (refero.design md-example or similar). Normalize it to parent DNA via `references/external-source-ingestion.md`, record its provenance under `sources[]` in `.skill-meta.json`, and keep the anti-clone rule — the hybrid is a new identity: never reproduce the source's brand, logo, trademark, or exact palette 1:1, and never name the hybrid after the source.

package/template/.aioson/skills/process/design-hybrid-forge/references/external-source-ingestion.md

@@ -0,0 +1,89 @@
+# External Source Ingestion
+
+> Load this reference when a primary parent or a modifier is an **external DESIGN.md source**
+> (a refero.design md-example, or a similar portable design spec extracted from a real site)
+> instead of a local AIOSON design skill.
+
+The hybrid model is unchanged: **exactly 2 primary parents**, optional modifiers. This reference only
+widens where a parent can come from — a parent may now be local (an AIOSON design skill) or external
+(a DESIGN.md source). Everything downstream (crossover protocol, output contract, quality gates) runs the
+same, operating on the normalized DNA produced here.
+
+## What an external DESIGN.md is
+
+A DESIGN.md is a portable, prose+token description of a real product's visual system — e.g. refero.design
+publishes curated examples (Apple, Linear, Stripe, Mercury, Superhuman, Raycast, …). It typically carries:
+
+- color palette
+- typography
+- spacing / layout rhythm
+- component patterns
+- overall visual tone / feel
+
+It is the "system behind the screenshot", meant to be **pasted as context**, not copied pixel for pixel.
+
+## Accepted forms
+
+Take the source in whichever form the user has:
+
+1. **Pasted content** — the user pastes the DESIGN.md text into the conversation.
+2. **Local file** — the user saved it at `.aioson/context/design-sources/{source}.design.md`.
+3. **URL** — the user gives a link (refero.design or similar). Fetch it; if the page is JS-heavy or the
+   fetch returns little, ask the user to paste the DESIGN.md text instead. Never block on a flaky fetch.
+
+## Normalize to parent DNA
+
+Map the source onto the same DNA dimensions the crossover protocol expects from a local parent:
+
+| Dimension | Pull from the source |
+|---|---|
+| Substrate / background model | base background, surface model, depth/elevation approach |
+| Structure / layout | layout rhythm, density, grid/spacing scale |
+| Tokens | color palette, typography, spacing, radius, shadow/depth |
+| Components | the component patterns described (buttons, cards, nav, inputs, …) |
+| Motion / feel | transitions, easing, the stated tone/feel |
+| Signature | the one or two moves that make it recognizable |
+
+If a dimension is missing in the source, mark it `not provided` — the **other** (local) parent or the
+modifiers fill it. Do not invent brand-specific detail the source did not state.
+
+## Eligibility: primary parent vs modifier
+
+- **Primary parent** requires at least: a clear substrate/background model **and** a token system
+  (color + typography) **and** a handful of components.
+- A source that only yields accent, motion, or typographic flavor is a **modifier**, not a primary parent
+  (modifiers never own substrate or structure — same rule as local modifiers).
+
+## Provenance (mandatory)
+
+Record every external source in `.skill-meta.json` under `sources[]`:
+
+```json
+"sources": [
+  { "type": "local",    "name": "cognitive-core-ui" },
+  { "type": "external", "name": "linear", "url": "https://styles.refero.design/...",
+    "retrieved_at": "{ISO-date}", "license": "unspecified — reference only",
+    "note": "refero.design md-example; used as reference, not copied" }
+]
+```
+
+refero.design and similar sites publish these as **references, not templates**, with no explicit license.
+Treat them accordingly: use the system, attribute the source in metadata, do not redistribute the source
+file as your own.
+
+## Anti-clone (hard)
+
+An external source contributes DNA exactly like a local parent — the crossover still synthesizes a
+distinct third identity. Therefore:
+
+- Never reproduce the source's brand name, logo, wordmark, or trademarked assets.
+- Never copy the source's exact palette or type ramp 1:1 — the hybrid accent must be a genuine fusion
+  (the existing accent rule), not the source's accent.
+- Never name the hybrid after the source brand (no `linear-hybrid`, no `stripe-core`).
+- The hybrid's `## Hybrid DNA` section names the source as a parent and states what it contributed and
+  what is new — same explicitness required of local parents.
+
+## Hand-off
+
+Once normalized and validated, treat the external source as an ordinary parent/modifier and continue with
+`references/crossover-protocol.md` (identity synthesis + crossover spec) exactly as for local parents.

package/template/.aioson/skills/process/product-scope-expansion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: product-scope-expansion
-description: "Product process skill for controlled scope expansion before writing or updating a PRD. Use in @product when a feature has a rich surface, when a briefing expansion scout exists, or when the user asks for a more complete MVP without turning the feature into an oversized V2."
+description: "Product process skill for controlled scope expansion and operational completeness before writing or updating a PRD. Use in @product when a feature has a rich surface, when a briefing expansion scout exists, when the user asks for a more complete MVP, or when the product implies workspaces, boards, cards, pipelines, operational CRUD, admin/management surfaces, or Trello/CRM/Kanban-like behavior without turning the feature into an oversized V2."
 ---
 
 # Product Scope Expansion
@@ -27,6 +27,23 @@ When the feature is not obviously rich, ask a short choice:
 
 When a scout artifact exists or the user explicitly asks for richer product thinking, run the skill without re-asking unless expansion would materially change classification or timeline.
 
+## Operational Completeness Gate
+
+Before writing or updating the PRD, build the Operational Surface Map from `.aioson/docs/feature-expansion-taxonomy.md`.
+
+This is not optional for rich-surface products. A Core object is incomplete until the PRD accounts for:
+
+- parent/owner relationship
+- lifecycle states
+- create, list/view, edit, delete/archive, and restore behavior, or an explicit deferral
+- the page, panel, modal, drawer, inline action, settings screen, or command where the user manages it
+- first-use empty state and validation/error state
+- basic role/permission boundary when ownership or collaboration exists
+
+If any Core object lacks a management surface or add/edit path, do not finalize the PRD as-is. Either ask one owner-level decision, choose the smallest defensible default, or put the missing behavior in `## Open questions` and keep it out of "ready for dev" handoff.
+
+For Trello/Kanban/CRM/workspace-like products, treat workspace/account home, board/pipeline index, main work surface, item detail, and empty/error surfaces as expected Core surfaces unless explicitly excluded.
+
 ## Output
 
 Write `.aioson/context/features/{slug}/scope-expansion.md`.
@@ -51,6 +68,15 @@ Use this structure:
 | V2 / Later | ... | ... | yes, future |
 | Cut List | ... | ... | no |
 
+## Operational Surface Map
+| Object | Parent / owner | Lifecycle states | Required actions | Management surface | Empty / error states | PRD destination |
+|---|---|---|---|---|---|---|
+
+## Core Capability Closure
+- Complete:
+- Missing / needs decision:
+- Explicitly deferred:
+
 ## Recommended Product Shape
 - Include in PRD:
 - Keep as optional:
@@ -71,4 +97,5 @@ Use this structure:
 - Do not silently include Optional V1, Delight, or V2 items.
 - If expansion raises classification, surface that before finalizing.
 - Preserve "small project, small solution": a rich feature can still have a small first release.
-
+- Core operational surfaces must appear in `## MVP scope`, `## User flows`, `## Out of scope`, or `## Open questions`; never leave them only in `scope-expansion.md`.
+- Do not route to implementation while a Core object's create/manage flow is undefined.

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

@@ -0,0 +1,98 @@
+---
+name: prototype-forge
+description: "Process skill for generating a clickable, self-contained HTML app-shell prototype from an operational surface map. Use in @briefing-refiner (optional visual refinement) when a rich-surface product — workspaces, boards, cards, pipelines, CRM/Kanban, dashboards, editors/builders, admin/management surfaces, repeated-use CRUD — needs its screens, navigation, and CRUD interactions validated before the PRD. Delegates all visual language to the selected design_skill; owns structure, behavior, and state."
+---
+
+# Prototype Forge
+
+Generate a clickable, self-contained HTML **app-shell prototype** that materializes a product's
+operational surface map — every screen, navigation path, and CRUD interaction — so completeness and
+interaction are validated *visually* before the PRD, not discovered later as gaps in a broken first build.
+
+This is an **app** prototype skill. It is not the landing-page guide
+(`.aioson/skills/static/static-html-patterns.md`, which `skip_if: app dashboard, admin panel`).
+
+## When to run
+
+Optional and user-invoked, inside `@briefing-refiner`. Run when a rich-surface product would benefit
+from seeing its screens and interactions before committing scope: workspaces, boards, cards, pipelines,
+CRM/Kanban, dashboards, editors/builders, admin/management surfaces, repeated-use CRUD.
+
+Skip for tiny single-screen features, one-field CRUD, or pure content/marketing pages.
+
+## Division of labor (do not blur)
+
+- **prototype-forge owns** structure + behavior + state: which screens exist, navigation/routing,
+  seeded mock data, client-side CRUD, and the empty/loading/error/permission state matrix.
+- **The selected `design_skill` owns visuals**: tokens, component anatomy, page composition, motion.
+  Read `design_skill` from `.aioson/context/project.context.md` and compose from that skill's
+  components. Never invent a second visual system. (e.g. `cognitive-core-ui` already ships `modal`,
+  `table`, `list-detail`, `settings`, and a `CRM` dashboard preset — compose from those.)
+
+The "add card doesn't work" and "no board-management screen" failures live in **this** skill's layer,
+not in the design skill's.
+
+## Inputs (read in this order)
+
+1. The operational surface map: `.aioson/briefings/{slug}/solution-options.md` (the chosen shape) or
+   `.aioson/briefings/{slug}/expansion-scout.md`, falling back to the Operational Surface Map in
+   `.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.
+
+## Build contract (enforceable)
+
+1. **Single self-contained file** — one `prototype.html`, inline CSS + JS, no build, no external
+   services, opens in a browser. (Mirrors `review.html`.)
+2. **Seeded realistic mock state** — plausible data for every Core object (e.g. 2-3 workspaces, a few
+   boards, several cards), never lorem ipsum. Enough to look real *and* to toggle the empty state. When
+   the product is authenticated, seed the logged-in app chrome too: a working account/user menu
+   (profile, settings, switch account, sign out) and any always-present chrome (search, notifications)
+   the product implies — a bare avatar with no menu is incomplete.
+3. **Navigational completeness** — every Core object in the surface map gets a reachable screen via
+   in-file routing (hash routes/tabs): a list/index surface, a detail surface, and its management
+   surface (page, panel, modal, drawer, or settings screen). A surface-map object with no reachable
+   screen is a **blocking gap**, not a backlog item.
+4. **Real client-side CRUD** — create/edit/delete/archive/restore mutate in-memory state and re-render.
+   "Add card"-class actions must actually add and persist for the session. Use modals/drawers/toasts
+   for feedback. A button that does nothing is a failure. Never use native `alert()`/`confirm()`/
+   `prompt()` — every create/edit/delete and every confirmation is an in-system modal, drawer, or
+   inline form styled by the `design_skill` (a destructive confirm is a styled dialog, not `confirm()`).
+   Native browser dialogs break visual fidelity and leave @dev with no spec for that surface.
+5. **State matrix** — empty, loading, error, populated, and permission-denied are each renderable and
+   toggleable, not only the happy path.
+6. **Visual fidelity** — all look-and-feel comes from the `design_skill`; honor its quality and
+   stability gates (tokens first, no nested cards, responsive grid constraints, prefers-reduced-motion).
+7. **Prototype as reference** — it is the downstream development reference. Record its lock status in
+   the manifest (`draft` until @product/@sheldon freeze scope, then re-synced and locked).
+
+## Output
+
+Write to `.aioson/briefings/{slug}/`:
+
+- `prototype.html` — the clickable app-shell.
+- `prototype-manifest.md` — the screen inventory (one row per Core object: screens + management
+  surface); a `## Core interactions` section listing every demonstrated interaction as a backtick token,
+  one per line (e.g. `` - `add card` — adds a card to a list ``), so `aioson prototype:check` can verify each
+  one is later echoed by an acceptance criterion; the `design_skill` used, an explicit
+  "mock only — refresh resets, no backend" note, and lock status (`draft` / `locked-at: {ref}`).
+
+## Completeness gate (before handing back)
+
+- Every Core object is reachable **and** manageable (create/list/edit/archive/restore, or an explicit defer).
+- Every Core action named in the surface map works against mock state and re-renders.
+- Empty and error states are visible, not implied.
+- No action falls back to a native browser dialog; every create/edit/delete/confirm is an in-system surface.
+- When the product is authenticated, the account/user menu is present and functional, not a dead avatar.
+- The visual is faithful to the `design_skill`, not generic.
+- If any Core object cannot be managed in the prototype, report it as a blocking gap — never hand back a
+  prototype that looks complete but cannot manage its own objects.

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.