@jaimevalasek/aioson 1.30.2 → 1.33.1

package/template/.aioson/docs/feature-expansion-taxonomy.md

@@ -5,12 +5,12 @@ agents: [briefing, briefing-refiner, product, sheldon]
 modes: [planning, executing]
 task_types: [feature-expansion, product-discovery, prd-enrichment, briefing-refinement]
 load_tier: trigger
-triggers: [feature expansion, rich surface, MVP options, product scope, capability map, Trello, generator, dashboard, workflow, editor, collaboration]
+triggers: [feature expansion, rich surface, MVP options, product scope, capability map, operational surface, CRUD surface, management surface, Trello, Kanban, CRM, workspace, board, dashboard, workflow, editor, collaboration]
 ---
 
 # Feature Expansion Taxonomy
 
-Use this shared vocabulary when a feature has a rich surface: workflow tools, collaboration, editors/builders, generators, media outputs, dashboards, CRM/Kanban-style systems, automation, templates, customization, or repeated operational use.
+Use this shared vocabulary when a feature has a rich surface: workflow tools, collaboration, editors/builders, generators, media outputs, dashboards, CRM/Kanban-style systems, automation, templates, customization, workspaces, boards, operational CRUD, or repeated operational use.
 
 Expansion is not approval. It reveals options, classifies value and risk, and makes scope easier to choose.
 
@@ -41,13 +41,41 @@ Check only lenses relevant to the feature:
 - Integrations and automation: imports, exports, webhooks, scheduled jobs, simple rules.
 - Implementation leverage: framework-native features, low-cost libraries, existing modules.
 
+## Operational Surface Map
+
+For rich-surface products, expansion is incomplete until the main objects have an operational surface map.
+
+Use this table shape:
+
+| Object | Parent / owner | Lifecycle states | Required actions | Management surface | Empty / error states | Permissions / roles |
+|---|---|---|---|---|---|---|
+| Workspace | owner / members | active, archived | create, switch, edit, archive, invite | workspace switcher + workspace settings | no workspaces, invite failed | owner, member |
+
+Rules:
+
+- A named Core object is not real scope until its create, list/view, edit, delete/archive, and restore behavior is either covered or explicitly deferred.
+- Every Core object needs a management surface: page, panel, modal, drawer, inline action, settings screen, or command. If there is no place to manage it, the product is underspecified.
+- Parent/child relationships must be explicit. For Trello-like systems, cards imply lists/columns, boards, workspaces, members, and at least basic role boundaries.
+- A user flow that says "manage cards" is too thin unless it names how the user adds, edits, moves, archives, restores, and sees validation feedback.
+- Empty states and failure states are Core for first-use products, admin surfaces, and repeated-use operational tools.
+- Deferred lifecycle actions must be visible in Out of scope, not silently omitted.
+
+Minimum expected surfaces for Trello/Kanban/CRM/workspace-like products:
+
+- Workspace or account home: create/select workspace, invite/manage members, edit settings.
+- Board/list/index surface: create/select/search/archive boards or pipelines.
+- Main work surface: view columns/lists/status groups, create/move/edit/archive primary items.
+- Item detail surface: edit content, metadata, assignee/owner, labels/status, comments/notes when in scope.
+- Empty/error surfaces: no workspace, no board, no items, permission denied, validation failure.
+
 ## Required Trace
 
 Every expansion artifact should state:
 
 - whether prior expansion artifacts were found
 - which bucket each suggestion belongs to
+- which Core objects were mapped in the operational surface map
+- which management surfaces are required for those Core objects
 - which ideas need explicit user approval
 - which ideas are intentionally deferred
 - how the expansion affects project classification or delivery risk
-

package/template/.aioson/docs/prototype-contract.md

@@ -0,0 +1,81 @@
+---
+name: prototype-contract
+agents: [product, ux-ui, analyst, architect, pm, orchestrator, dev, validator, sheldon]
+modes: [planning, executing]
+task_types: [prd, ui-spec, discovery, requirements, architecture, implementation, validation]
+load_tier: trigger
+triggers: [prototype, prototype.html, prototype reference, app-shell, clickable prototype, casca]
+---
+
+# Prototype Contract
+
+When a feature has a clickable prototype from `prototype-forge` (`@briefing-refiner`), that prototype is the
+authoritative reference for the feature's screens, navigation, and interactions. This doc defines how each
+role uses it so the prototype is honored end-to-end, not lost after refinement.
+
+## Where it lives
+
+- `.aioson/briefings/{slug}/prototype.html` — the clickable app-shell.
+- `.aioson/briefings/{slug}/prototype-manifest.md` — screen inventory, Core interactions demonstrated,
+  `design_skill` used, and lock status.
+
+It is **mock-only**: no backend, refresh resets. Reproduce its behavior against the real stack — never copy
+its mock persistence.
+
+## The PRD pointer
+
+When a prototype exists, `@product` adds a `## Prototype reference` section to the PRD:
+
+```
+## Prototype reference
+- prototype: .aioson/briefings/{slug}/prototype.html
+- manifest: .aioson/briefings/{slug}/prototype-manifest.md
+- status: draft | locked-at: {ref}
+- Treat as the authoritative screen/interaction reference for this feature.
+```
+
+The PRD is the carrier: every downstream agent that reads the PRD discovers the prototype through this section.
+
+## Lock (draft → locked)
+
+The prototype is `draft` while scope is open. When `@product`/`@sheldon` freeze scope, the prototype is
+re-synced to match the final PRD and marked `locked-at: {ref}`. The locked version is what implementation
+reproduces and what acceptance criteria are derived from. If the PRD and a `draft` prototype diverge at lock,
+the approved PRD wins and the prototype is updated to match.
+
+## Role usage
+
+- **@product** — write the `## Prototype reference` section; keep the PRD consistent with the prototype; mark
+  it `locked` at scope freeze.
+- **@sheldon** — when enriching a PRD that carries a `## Prototype reference`, keep the enrichment and any
+  phased plan consistent with the prototype's screens and Core interactions; do not silently enrich away a
+  demonstrated interaction. Co-own the `draft → locked` scope freeze with `@product`; if enrichment must
+  change a prototyped behavior, record it as an explicit scope decision in the PRD, not a silent drop.
+- **@ux-ui** — the prototype is the concrete realization of the design direction. Use it as the authoritative
+  screen/interaction/visual reference; the `ui-spec` must not contradict it. Refine visual detail on top of
+  it, never around it.
+- **@analyst** — turn the prototype's Core screens and interactions into explicit acceptance criteria in
+  `requirements-{slug}.md` (e.g. "add card persists and re-renders", "board has a management surface"). This
+  is how the prototype reaches `@validator` — as binary criteria, not as a file it reads.
+- **@architect / @pm / @orchestrator** — read the prototype + manifest as the reference for screens, flows,
+  entities, and scope when planning; do not plan a Core surface the prototype omits without saying so.
+- **@dev** — the prototype is the development source for UI and interactions. Reproduce its screens and Core
+  interactions against the real stack. Never ship a Core action the prototype demonstrates (e.g. "add card",
+  "create board", "manage members") while the build lacks it.
+- **@validator** — verifies prototype-derived acceptance criteria as part of the normal binary contract in
+  `harness-contract.json`. It does **not** read the prototype directly (its context sandbox forbids
+  PRDs/artifacts); the criteria authored by `@analyst` are what it checks.
+
+## Completeness
+
+A feature with a prototype is not "ready for done" until every Core screen and interaction the prototype
+demonstrates is either built and verified, or explicitly deferred in the PRD's `## Out of scope`.
+
+## Deterministic guard
+
+Run `aioson prototype:check . --feature={slug}` once `@analyst` has written `requirements-{slug}.md`. It is the
+deterministic backstop for this otherwise prose-only contract and fails on: a dangling `## Prototype reference`
+(prototype or manifest file missing), a missing requirements bridge, or Core interactions listed in the manifest
+that no acceptance criterion echoes (`fail` = none covered, `warn` = some uncovered). It matches interaction
+names as folded substrings, so the AC must echo the manifest's interaction name (EN or pt-BR). The check never
+reads the prototype's behavior — only that the contract's structural links exist end to end.

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,92 @@
+---
+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.
+
+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/sheldon-expansion-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sheldon-expansion-audit
-description: "Sheldon process skill for auditing a PRD against prior feature expansion artifacts and expected product richness. Use in @sheldon when expansion-scout.md or scope-expansion.md exists, or when a PRD for a rich-surface feature looks too thin, too inflated, or lacks acceptance criteria for enriched capabilities."
+description: "Sheldon process skill for auditing a PRD against prior feature expansion artifacts, expected product richness, and operational surface completeness. Use in @sheldon when expansion-scout.md or scope-expansion.md exists, or when a PRD for a rich-surface feature looks too thin, too inflated, lacks acceptance criteria for enriched capabilities, or implies workspaces, boards, cards, pipelines, operational CRUD, admin/management surfaces, or Trello/CRM/Kanban-like behavior."
 ---
 
 # Sheldon Expansion Audit
@@ -20,6 +20,22 @@ Read available inputs:
 
 If no prior expansion artifact exists, perform only a lightweight inferred expansion and label it clearly.
 
+## Operational Surface Audit
+
+Before recommending enrichment, audit the PRD against the Operational Surface Map in `.aioson/docs/feature-expansion-taxonomy.md`.
+
+Flag as **critical** when a Core object exists in scope but lacks:
+
+- parent/owner relationship
+- create, list/view, edit, delete/archive, or restore handling
+- a management surface where the user performs those actions
+- empty state and validation/error behavior
+- role/permission boundary for owner/member/admin scenarios
+
+For Trello/Kanban/CRM/workspace-like PRDs, missing workspace management, board/pipeline CRUD, primary item creation/editing, or the main work surface is a blocking product gap, not optional enrichment.
+
+Do not allow generic phrases like "manage cards", "manage boards", or "workspace support" to pass unless the PRD names the surfaces and flows that make those capabilities usable.
+
 ## Output
 
 Write `.aioson/context/features/{slug}/expansion-audit.md`.
@@ -43,6 +59,10 @@ Use this structure:
 - Missing user states/actions:
 - Missing acceptance criteria:
 
+## Operational Surface Audit
+| Object | Expected surface | Missing action/state | Severity | Required PRD patch |
+|---|---|---|---|---|
+
 ## Too Large Check
 - V2 items pulled into MVP:
 - Optional items without approval:
@@ -61,7 +81,8 @@ Proceed / enrich PRD first / return to product for decision.
 
 - Prefer evidence from prior expansion artifacts over inventing new ideas.
 - Flag when a rich-surface PRD has only generic fields or thin CRUD.
+- Treat missing Core management surfaces and create/edit flows as critical gaps.
+- For Trello-like products, workspace/board management and card creation/editing are Core unless explicitly excluded in the PRD.
 - Flag when V2 ideas entered MVP without explicit rationale.
 - Convert accepted expansion items into acceptance-criteria gaps.
 - Do not rewrite Product-owned Vision, Problem, or Users.
-