@jaimevalasek/aioson 1.6.0 → 1.7.2

package/template/.aioson/skills/marketing/vsl-craft.md

@@ -0,0 +1,385 @@
+---
+name: vsl-craft
+description: Video Sales Letter production skill — script structure, hook formulas, retention techniques, testing methodology, and production specs. Loaded by @copywriter when Mode 5 (VSL) is active.
+---
+
+# VSL Craft — Video Sales Letter Production
+
+## When to load this skill
+
+- User requests a VSL script
+- User requests a video sales page (page with embedded sales video)
+- User requests an advertorial video
+- @copywriter Mode 5 is activated
+- Squad executor with VSL deliverable
+
+---
+
+## 1. What is a VSL?
+
+A Video Sales Letter is a scripted video (typically 10-45 minutes) designed to convert cold traffic into buyers. It replaces the live salesperson with a pre-recorded, optimized sales presentation.
+
+**Key differences from a written sales page:**
+- The viewer can't scan — they must watch sequentially
+- Retention is everything — if they leave at minute 3, the offer at minute 20 never gets seen
+- Audio + visual = two channels to reinforce the message
+- Pacing, pauses, and emotional tone are scripted, not left to chance
+
+---
+
+## 2. VSL formats
+
+### 2.1 Traditional VSL (horizontal)
+- 16:9 format, presenter or slides
+- Duration: 15-45 minutes
+- Best for: sophisticated offers, higher ticket (R$297+), cold traffic from YouTube/Facebook
+- Production: can be "ugly" (slides only) or "cinematic" (B-roll, editing)
+
+### 2.2 Vertical VSL (mobile-native)
+- 9:16 format, looks like organic content
+- Duration: 3-15 minutes
+- Best for: TikTok/Reels traffic, lower ticket, younger audiences
+- Production: phone-filmed, fast cuts, captions mandatory
+
+### 2.3 Hybrid (advertorial + VSL)
+- Written advertorial page with embedded video at the mechanism section
+- The text does Act 1-2, the video does Act 3-5
+- Best for: sophisticated audiences who want to read before watching
+
+---
+
+## 3. The VSL script structure (5 Acts adapted for video)
+
+### Act 1 — The Hook (0:00 to 0:30)
+
+**Goal:** Stop the scroll and keep them watching for the next 30 seconds.
+
+**The 3-second rule:** If the first 3 seconds aren't arresting, the viewer leaves.
+
+**Hook formulas for VSL:**
+
+**Formula 1: The Discovery Hook**
+> "What you're about to see in the next [X] minutes could change the way you [desired outcome] forever. I'm going to show you [specific discovery] that [specific proof]."
+
+**Formula 2: The Proof-First Hook**
+> "[Name], [age], from [city], lost [specific result] in [specific time]. And she did it without [painful thing]. Today I'm going to show you exactly how — and why it works even if [objection]."
+
+**Formula 3: The Paradox Hook**
+> "Why do [specific group] [achieve result] while [audience group] [fail despite effort]? The answer has nothing to do with [obvious thing] — and everything to do with [curiosity element]."
+
+**Formula 4: The Warning Hook**
+> "If you're [doing common thing], stop immediately. A [authority/study] just revealed that [counterintuitive finding] — and it's costing you [consequence]. Stay with me for [time] and I'll show you [solution]."
+
+**Formula 5: The Story Hook**
+> "Last [day], [specific person] sent me this message: [screenshot/quote]. [X time] ago, they were [painful situation]. Today they [desired outcome]. This is their story — and it starts with [curiosity element]."
+
+**Anti-pattern hooks:**
+- "Hey everyone, welcome to my channel..." → Zero curiosity
+- "In this video I'm going to talk about..." → Passive, no hook
+- "So, I've been getting a lot of questions about..." → About you, not them
+
+### Act 2 — The Background (0:30 to 3:00)
+
+**Goal:** Build authority and emotional connection quickly.
+
+**For expert-led VSL:**
+> "[Credentials in one sentence]. But what matters more than my degrees is this: I've helped [specific number] of people [achieve result], and what I discovered along the way is the reason you're watching this video."
+
+**For avatar transformation:**
+> "I know what it's like to [specific pain]. [Time] ago, I was [painful situation — specific details]. I tried [what they've tried]. Nothing worked. Until [discovery moment]."
+
+**Key rule:** Act 2 must be SHORT in a VSL. On a written page, you can have a long background section. On video, 1-2 minutes max. Get to the mechanism fast.
+
+### Act 3 — The Mechanism (3:00 to 12:00)
+
+**Goal:** Create the "Aha!" moment. This is where the One Belief is built.
+
+**Structure:**
+
+**Part A — Why nothing else worked (2-4 minutes)**
+1. Name what they've tried (validate their experience)
+2. Reveal the hidden reason it failed (the enemy — not them)
+3. Use a visual metaphor or diagram to make the concept tangible
+
+**Part B — How [Mechanism Name] works (3-5 minutes)**
+1. Introduce the mechanism by name
+2. Explain it at surface level (simple enough for a 12-year-old)
+3. Show ONE proof point (study, case study, demonstration)
+4. Use B-roll or diagrams to illustrate — never just talk over static slides for more than 30 seconds
+
+**Retention techniques for Act 3:**
+- **Pattern interrupt every 60-90 seconds:** Change the visual, show a diagram, cut to B-roll, display a quote
+- **Open loops:** "In a moment I'll show you the third step — but first you need to understand why..."
+- **Micro-fascinations:** Drop curiosity bullets throughout: "The ingredient I'm about to mention is in 90% of Brazilian homes but nobody knows it does THIS..."
+- **Density escalation:** Each minute should be MORE interesting than the last, not less
+
+### Act 4 — The Offer (12:00 to 18:00)
+
+**Goal:** Transition from education to sale without breaking trust.
+
+**The transition bridge:**
+> "So now you understand WHY [mechanism] works and HOW it produces [result]. The question is: how do YOU implement it? That's exactly why I created [Product Name]."
+
+**VSL-specific offer rules:**
+- Never call it a "course" — use Protocol, System, Blueprint, Accelerator
+- Show each component visually (mockup, icon, or slide)
+- Read the fascinations with enthusiasm — pacing matters
+- Pause after stating the price — let it sink in
+- Show the guarantee prominently (text on screen + verbal)
+
+**Reference:** `.aioson/skills/marketing/references/offer-structure.md`
+
+### Act 5 — The Close (18:00 to 22:00)
+
+**Goal:** Push the fence-sitters over the edge.
+
+**The Two Paths technique (optimized for video):**
+> "Right now, you're at a fork in the road.
+> [Pause — 2 seconds]
+> Path one: you close this video. You go back to [specific pain]. Tomorrow feels the same as today. Next month, same. Next year...
+> [Pause — 3 seconds]
+> Path two: you click the button below. You start [Product Name] today. In [timeframe], you [specific visualizable result].
+> [Pause — 2 seconds]
+> Which path makes more sense?"
+
+**Recovery techniques (the "Kenyan Village" strategy):**
+- **Pause thumbnail:** When the viewer pauses, a thumbnail appears with a hook to resume
+- **Exit-intent popup:** On the page, when cursor moves to close — offer a discount or bonus
+- **Post-VSL autoplay:** After the main VSL, play a shorter 3-minute "for those still deciding" video
+- **SMS/email retargeting:** Capture email early (before VSL starts) and send follow-up sequence
+
+---
+
+## 4. VSL script format
+
+When writing a VSL script, use this format:
+
+```markdown
+# VSL Script: [Product Name]
+
+## Metadata
+- Duration target: [X] minutes
+- Format: Horizontal / Vertical
+- Traffic temperature: Cold / Warm / Hot
+- One Belief: "[New Opportunity] is the key to [Benefit] through [Mechanism]"
+- Awareness level: [1-5]
+
+---
+
+## ACT 1 — HOOK (0:00–0:30)
+
+### VISUAL:
+[What appears on screen]
+
+### AUDIO:
+[What is said — scripted word-for-word]
+
+### NOTES:
+[Production notes: B-roll, text overlay, music cue]
+
+---
+
+## ACT 2 — BACKGROUND (0:30–3:00)
+
+### VISUAL:
+[Screen description]
+
+### AUDIO:
+[Script]
+
+### NOTES:
+[Production notes]
+
+---
+
+## ACT 3 — MECHANISM (3:00–12:00)
+
+### 3A — Why nothing else worked
+
+#### VISUAL:
+[Screen]
+
+#### AUDIO:
+[Script]
+
+#### PATTERN INTERRUPT at [timestamp]:
+[Visual change / diagram / B-roll description]
+
+### 3B — How [Mechanism] works
+
+#### VISUAL:
+[Screen]
+
+#### AUDIO:
+[Script]
+
+#### PROOF POINT:
+[Study / case study / demonstration]
+
+---
+
+## ACT 4 — OFFER (12:00–18:00)
+
+### TRANSITION:
+
+#### AUDIO:
+[Bridge sentence]
+
+### COMPONENT STACK:
+
+#### VISUAL:
+[Mockup / slide of each component]
+
+#### AUDIO:
+[Component name, benefit, value, fascination]
+
+### PRICE REVEAL:
+
+#### VISUAL:
+[Anchoring → crossed out prices → final price]
+
+#### AUDIO:
+[Not paying X. Not even Y. Today: Z. Reason why.]
+
+### GUARANTEE:
+
+#### VISUAL:
+[Guarantee badge / text on screen]
+
+#### AUDIO:
+[Full guarantee statement]
+
+---
+
+## ACT 5 — CLOSE (18:00–22:00)
+
+### TWO PATHS:
+
+#### AUDIO:
+[Path 1 → Path 2 → Which makes more sense?]
+
+### FINAL CTA:
+
+#### VISUAL:
+[Button, URL, QR code on screen]
+
+#### AUDIO:
+[Click the button below / link in description]
+
+### RECOVERY ELEMENTS:
+- Pause thumbnail text: [text]
+- Exit-intent offer: [discount/bonus]
+- Post-VSL summary video: [Y/N]
+```
+
+---
+
+## 5. Testing methodology
+
+### Phase 1 — Validate the thesis (before production)
+Create an "ugly" VSL:
+- White background, black text on slides
+- Presenter reads from teleprompter (or text-to-speech for testing)
+- No B-roll, no editing, no music
+- Duration: 10-15 minutes (condensed version)
+
+Run R$500-R$1,000 in cold traffic. Measure:
+- **Hook retention:** % watching past 30 seconds (target: >50%)
+- **Mechanism retention:** % watching past Act 3 (target: >25%)
+- **Offer conversion:** % who reach offer AND click CTA (target: >2%)
+
+If the ugly version converts → invest in production.
+If it doesn't → rewrite the script before spending on video production.
+
+### Phase 2 — Optimize the hook
+Create 3-5 hook variations (first 30 seconds only).
+Run equal traffic to each. The winning hook gets 2-3x more budget.
+
+**Hook metrics:**
+- 3-second retention rate
+- 15-second retention rate
+- 30-second retention rate
+
+### Phase 3 — Scale with production
+Once the script is validated:
+- Add B-roll and visual elements
+- Professional audio recording
+- Add pattern interrupts and visual variety
+- Consider vertical format for mobile-first traffic
+
+---
+
+## 6. VSL page structure
+
+The page that hosts the VSL should be minimal:
+
+```html
+<!-- Above the fold — ONLY the video -->
+<section class="vsl-hero">
+  <div class="video-container">
+    <!-- Video player (VTurb, Wistia, or custom) -->
+    <!-- CTA button appears ONLY after offer section plays -->
+  </div>
+</section>
+
+<!-- Below the fold — revealed after video plays past offer -->
+<section class="vsl-offer">
+  <!-- Component stack (text version of what's in the video) -->
+  <!-- Guarantee -->
+  <!-- CTA button -->
+  <!-- FAQ -->
+  <!-- Testimonials -->
+</section>
+```
+
+**Key rules:**
+- **No navigation menu** — remove all escape routes
+- **CTA button hidden until the offer section plays** — don't let them see the price before the mechanism
+- **Video auto-plays on mute with captions** — most mobile traffic has sound off
+- **Exit-intent popup** — "Wait! Before you go..." with a discount or bonus
+- **Timer optional** — only if the offer has a real deadline
+
+---
+
+## 7. Production specifications
+
+### Audio
+- Clear, professional recording (condenser mic, treated room)
+- Pacing: 150-170 words per minute (conversational speed)
+- Consider 1.1x-1.3x playback speed for higher engagement
+- Music: subtle background only, never competing with voice
+
+### Video
+- Resolution: minimum 1080p
+- B-roll: 2-3 second clips every 60-90 seconds in Act 3
+- Text overlays: key claims and proof points on screen while spoken
+- Captions: always (auto-generated + manually corrected)
+
+### Hosting
+- VTurb (Brazilian market — best heatmap and button reveal features)
+- Wistia (international — CTA tools built in)
+- Custom player (maximum control — no platform branding)
+
+---
+
+## 8. Conditional reference loading
+
+When writing a VSL script, the @copywriter agent should load:
+
+| Phase | Load |
+|---|---|
+| Research | `pms-research.md` + `market-intelligence.md` |
+| Script — hook | `one-belief.md` + `patterns.md` (headline formulas adapt to hooks) |
+| Script — mechanism | `five-acts.md` (Acts 3 focus) |
+| Script — offer | `offer-structure.md` + `fascinations.md` |
+| Script — validation | `anti-patterns.md` |
+
+---
+
+## 9. Output contract
+
+VSL script saves to: `.aioson/context/vsl-script-{slug}.md`
+VSL page spec saves to: `.aioson/context/vsl-page-{slug}.md` (if page design is needed)
+
+If invoked from @ux-ui: return the page spec for visual implementation.
+If invoked from a squad: save to the squad's output directory.

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

@@ -43,3 +43,4 @@ Load the file that matches your current context — do not load all at once:
 | `references/hardening-lane.md` | The input is vague, exploratory, or "vibe-style" and needs to be converted |
 | `references/maintenance-and-state.md` | You are writing or reading `spec*.md`, checkpoints, or retaking work |
 | `references/ui-language.md` | You need to present options, status symbols, or checkpoints to the user with consistent visual standards |
+| `references/qa.md` | You are running QA review and need Gate D verification criteria or artifact validation |

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

@@ -0,0 +1,30 @@
+# Spec-Driven Reference — @analyst
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for discovery and feature requirements
+
+### Always load when this skill is active
+
+- `classification-map.md` — use during discovery to score complexity and declare MICRO/SMALL/MEDIUM before any other decision
+- `artifact-map.md` — use to know exactly what artifacts @analyst owns vs what belongs to @architect or @dev
+- `approval-gates.md` — use Gate A criteria to know when requirements are ready to hand off
+
+### Load when input is vague or exploratory
+
+- `hardening-lane.md` — use to detect whether input is still in vibe mode and route accordingly before producing requirements
+
+### Do not load for @analyst
+
+- `maintenance-and-state.md` — this is for execution/continuation sessions, not discovery
+- `ui-language.md` — load only when producing a checkpoint or gate status presentation
+
+## Behavioral notes
+
+- Declare classification (MICRO/SMALL/MEDIUM) early — it controls depth of requirements, AC verbosity, and whether Gate A is blocking
+- Gate A must be explicitly evaluated before handing off to @architect or @dev
+- `requirements-{slug}.md` is @analyst's primary output — see `artifact-map.md` for ownership chain
+
+### Conformance contract (MEDIUM only)
+
+For MEDIUM features, generate `.aioson/context/conformance-{slug}.yaml` alongside `requirements-{slug}.md`. This YAML file structures each AC into machine-readable preconditions, actions, expected outcomes, and negative cases. @qa and @dev consume this for precise verification and test writing.

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

@@ -0,0 +1,23 @@
+# Spec-Driven Reference — @architect
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for architecture work
+
+### Always load when this skill is active
+
+- `classification-map.md` — use to determine architecture depth: MICRO skips most of this, MEDIUM requires full `architecture.md`
+- `approval-gates.md` — Gate B criteria define what @architect must produce before @dev can start; Gate A must already be passed before @architect begins
+- `artifact-map.md` — use to confirm which artifacts @architect owns (`architecture.md`, `design-doc*.md`) and which feed into it
+
+### Do not load for @architect
+
+- `hardening-lane.md` — input is expected to be already past vibe mode when @architect is activated
+- `maintenance-and-state.md` — this is for execution/continuation sessions
+
+## Behavioral notes
+
+- Classification depth from `classification-map.md` controls whether `architecture.md` is required, selective, or skippable
+- Gate B is the handoff signal — @dev must not start implementation without Gate B passing (MEDIUM) or being explicitly waived (SMALL)
+- Decision rationale is mandatory for non-obvious choices — `approval-gates.md` Gate B checklist item applies
+- `design-doc*.md` is @architect's scope-specific decision document — see `artifact-map.md`

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

@@ -0,0 +1,47 @@
+# Spec-Driven Reference — @dev
+
+> 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
+
+### 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
+
+### Load when resuming or checking artifact chain
+
+- `artifact-map.md` — use to verify which upstream artifacts exist and which @dev should read before implementing
+
+### Do not load for @dev
+
+- `hardening-lane.md` — @dev activates after hardening; if the spec is still in vibe mode, stop and route back
+- `ui-language.md` — load only when producing a checkpoint or gate status presentation for the user
+
+## Spec drift detection
+
+At session start, after reading `spec-{slug}.md`:
+
+1. Compare `spec_version` in `spec-{slug}.md` with the version recorded in `dev-state.md` (`last_spec_version` field)
+2. If versions differ:
+   > "⚠ Spec changed since last session (version {old} → {new}). Reading the changes before continuing."
+   - Read the diff (Key decisions, Entities added, Edge cases sections)
+   - Update `dev-state.md` with new `last_spec_version`
+3. If versions match: proceed normally
+
+Additionally, at session start for SMALL/MEDIUM:
+4. Check if any `AC-{slug}-{N}` from `requirements-{slug}.md` has 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.
+
+## 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
+- Gate D verification must happen before marking a phase complete — not just "I think it works"
+- If `phase_gates.plan` is `pending` and classification is SMALL/MEDIUM, suggest generating an implementation plan before proceeding

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

@@ -0,0 +1,27 @@
+# Spec-Driven Reference — @deyvin
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for continuation and resume flows
+
+### Always load when this skill is active
+
+- `maintenance-and-state.md` — @deyvin's primary job is resumption; use this to read `phase_gates`, `last_checkpoint`, and `pending_review` correctly before any action
+- `approval-gates.md` — use to check which gates are already approved before proceeding; never advance past a gate that is not yet passed
+
+### Load when the continuation context is unclear
+
+- `artifact-map.md` — use to quickly orient which artifacts exist and which are missing when resuming a session with incomplete context
+
+### Do not load for @deyvin
+
+- `hardening-lane.md` — by the time @deyvin is active, the spec pack should already be hardened
+- `classification-map.md` — classification was set in the spec and should not be re-evaluated during continuation
+- `ui-language.md` — load only when producing a checkpoint or gate status presentation for the user
+
+## Behavioral notes
+
+- `last_checkpoint` in `spec-{slug}.md` is the first thing @deyvin reads — see `maintenance-and-state.md` for format
+- Do not re-read the full spec pack unless `last_checkpoint` is null or contradictory
+- `phase_gates` from `approval-gates.md` defines what is locked — @deyvin does not re-open locked decisions
+- `pending_review` items must be surfaced to the user before proceeding past them

package/template/.aioson/skills/process/aioson-spec-driven/references/maintenance-and-state.md

@@ -57,6 +57,41 @@ Good example:
 
 The reason is what makes the decision useful in 6 months.
 
+## spec_version field
+
+- Seeded at `1` by @analyst when creating the skeleton
+- Incremented by any agent that modifies the spec body (entities, decisions, edge cases — NOT just `last_checkpoint` or `pending_review`)
+- @dev checks at session start: if version changed since last `dev-state.md` update, read the spec diff before continuing
+- @qa checks at review: if version doesn't match what @dev reported, flag as potential drift
+
+## Unified resumption fields
+
+Every agent that produces or updates a persistent artifact should include these fields in the artifact's frontmatter or closing section:
+
+### In frontmatter (machine-readable):
+- `last_agent: {agent-name}` — who was here last
+- `last_session: {ISO-date}` — when
+- `session_result: completed | interrupted | blocked` — what happened
+
+### In closing section (human-readable):
+```
+## Session close — {ISO-date}
+Agent: @{name}
+Result: {completed | interrupted | blocked}
+Next: {clear instruction for next agent or next session}
+```
+
+### Which artifact each agent updates:
+| Agent | Primary artifact |
+|-------|-----------------|
+| @product | `prd.md` or `prd-{slug}.md` |
+| @sheldon | `sheldon-enrichment-{slug}.md` |
+| @analyst | `discovery.md` or `requirements-{slug}.md` |
+| @architect | `architecture.md` |
+| @dev | `dev-state.md` (already does this) |
+| @deyvin | `dev-state.md` or `spec-{slug}.md` |
+| @qa | QA report file |
+
 ## How @deyvin should use this file
 
 1. Read `phase_gates` first — know which phases are locked

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

@@ -0,0 +1,25 @@
+# Spec-Driven Reference — @product
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for PRD and feature scoping
+
+### Always load when this skill is active
+
+- `classification-map.md` — use to declare MICRO/SMALL/MEDIUM at the start of scoping; classification controls PRD depth, whether a `## Specify depth` section is required, and which downstream phases are mandatory
+- `artifact-map.md` — use to understand what @product's PRD feeds into downstream; helps scope the PRD correctly without over-specifying what belongs to @analyst or @architect
+
+### Load when input is still ambiguous or exploratory
+
+- `hardening-lane.md` — use to detect if the request is still in vibe mode and needs more discovery before a PRD can be written
+
+### Do not load for @product
+
+- `approval-gates.md` — @product produces the PRD; Gate A is evaluated by @analyst after @product hands off
+- `maintenance-and-state.md` — this is for execution/continuation sessions
+
+## Behavioral notes
+
+- Classification (MICRO/SMALL/MEDIUM) from `classification-map.md` must be declared in the PRD — it is the signal that controls all downstream process depth
+- @product does not write requirements (`requirements-{slug}.md`) — those belong to @analyst; see `artifact-map.md` for the boundary
+- If classification is MEDIUM, the PRD must include a `## Specify depth` section per `classification-map.md`

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

@@ -0,0 +1,30 @@
+# Spec-Driven Reference — @qa
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for quality verification
+
+### Always load when this skill is active
+
+- `approval-gates.md` — Gate D (execution verification) defines done criteria; @qa is the external verifier of Gate D claims
+- `artifact-map.md` — use to verify that all artifacts claimed by upstream agents actually exist and are substantive
+
+### Load when evaluating AC coverage
+
+- `classification-map.md` — use to calibrate verification depth: MICRO gets happy path + auth only; MEDIUM gets full checklist + invariant tests
+
+### Load when investigating failures or forensics
+
+- `maintenance-and-state.md` — use to read `phase_gates`, `last_checkpoint`, and `pending_review` from `spec-{slug}.md` during forensics mode
+
+### Do not load for @qa
+
+- `hardening-lane.md` — @qa activates after implementation; hardening is not relevant
+- `ui-language.md` — @qa produces structured reports, not interactive checkpoints
+
+## Behavioral notes
+
+- @qa is the external verifier of @dev's Gate D self-certification — "I think it works" from @dev is not evidence until @qa confirms
+- Gate D verification from `approval-gates.md` maps directly to @qa's adversarial probe protocol: truths = behavior tests, artifacts = file existence checks, key_links = wiring verification
+- For MEDIUM projects, @qa should verify that `spec_version` in `spec-{slug}.md` matches the version that @dev was working from — if not, flag as potential drift
+- AC coverage mapping in the QA report should use the same `AC-{slug}-{N}` format from `requirements-{slug}.md`

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

@@ -0,0 +1,25 @@
+# Spec-Driven Reference — @sheldon
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for enrichment and validation
+
+### Always load when this skill is active
+
+- `hardening-lane.md` — @sheldon's primary job is to move input from Lane 1 (exploration) to Lane 2 (spec hardening); use this to identify vibe signals and what is missing
+- `classification-map.md` — use to determine enrichment depth: MEDIUM requires Modo C (full validation), MICRO/SMALL have lighter enrichment expectations
+
+### Load when evaluating PRD readiness for handoff
+
+- `approval-gates.md` — use Gate A criteria as the readiness checklist @sheldon applies before recommending @analyst activation
+
+### Do not load for @sheldon
+
+- `maintenance-and-state.md` — enrichment is a pre-execution phase; spec state is not relevant yet
+- `artifact-map.md` — load only if @sheldon needs to verify that the right PRD artifact exists before enriching
+
+## Behavioral notes
+
+- @sheldon activates before @analyst — its output (`sheldon-enrichment-{slug}.md`) feeds @analyst
+- Vibe detection from `hardening-lane.md` determines whether to proceed with enrichment or route back to @product
+- MEDIUM classification triggers Modo C: @sheldon must validate completeness more strictly than MICRO/SMALL

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

@@ -90,7 +90,9 @@ Each phase must complete before the next begins. Do not skip phase 2 and 3 — t
 ```
 primary_a: {skill-name}            # e.g. "cognitive-core-ui"
 primary_b: {skill-name}            # e.g. "glassmorphism-ui"
-modifiers: {optional 0..2}         # e.g. ["bold-editorial-ui"]
+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
 variation_overlay: {optional}      # selected via conversation or `aioson design-hybrid:options`
 modifier_policy: {optional}        # "up_to_2_modifiers" by default, "up_to_3_modifiers" in advanced mode
 name_suggestion: {optional}        # e.g. "aurora-command-ui" or leave blank
@@ -142,3 +144,4 @@ The hybrid must satisfy ALL of the following:
 9. Every hybrid ships with both previews and a `.skill-meta.json`. No preview = not done.
 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.