@avesta-hq/prevention 0.5.0 → 0.6.0-pre.11

package/.avesta/docs/user-story-map/GROUP-0-LEARNINGS.md

@@ -0,0 +1,292 @@
+# Group 0 Dogfood Learnings
+
+> **Source**: Manual walkthrough of `/avesta-shape` on the Prevention product itself, 2026-04-10, as the first step of the shape phase implementation per `docs/SHAPE-PHASE-IMPLEMENTATION-PLAN.md` §10.
+>
+> **Purpose**: Validate the schema, flow, template, and brand approach before writing any agent code. These learnings feed directly into Groups 1–8 of the implementation.
+>
+> **Artifacts produced**:
+> - `brand.yml` — AvestaHQ brand configuration extracted from `Avesta_BrandGuide_V1.pdf`
+> - `story-map.yml` — 144 stories across 14 backbone phases, 3 personas, 4 releases
+> - `story-map.html` — rendered HTML visually verified against the GTPCL reference design
+> - `fonts/Nohemi-*.woff2` — 4 self-hosted weights (Regular, Medium, SemiBold, Bold)
+> - `scripts/render-story-map-dogfood.mjs` — throwaway renderer (the production version comes in Group 2)
+
+---
+
+## Summary
+
+13 concrete learnings surfaced during the dogfood. Each has a specific fix location in the implementation plan or a new fast-follow item. None of the learnings invalidate the overall approach — they refine the agent prompt, the schema, and the render strategy.
+
+---
+
+## Learnings
+
+### #1 — Agent must glob for vision docs, not hardcode the canonical path
+
+**What happened**: The agent prompt in `SHAPE-PHASE-IMPLEMENTATION-PLAN.md` §5.15 instructs the agent to read `.avesta/docs/vision/PRODUCT-VISION.md` as pre-flight. But Prevention's vision lives at `docs/PREVENTION-VISION-NARRATIVE.md` and `docs/PREVENTION-PRODUCT-SPEC.md` — paths that exist in most brownfield projects but not at the canonical `.avesta/docs/vision/` location.
+
+**Fix location**: `src/mcp/prompts/avesta-shape.md` (Group 5, §5.15). Update the pre-flight step to:
+1. First look at `.avesta/docs/vision/PRODUCT-VISION.md`
+2. If not found, glob for `**/vision*.md`, `**/*VISION*.md`, `**/PRODUCT-SPEC*.md`
+3. If multiple candidates, ask the user which to use
+4. If none, offer to run `/avesta-vision` first
+
+---
+
+### #2 — `brand.yml` schema needs font source type and face array
+
+**What happened**: The plan's §5.4 brand schema assumed all fonts come from Google Fonts. The AvestaHQ brand uses Nohemi (paid, self-hosted) + Work Sans (Google Fonts) + DM Mono (Google Fonts). Self-hosted fonts need `@font-face` declarations with weight-specific file paths — not just a `google_fonts_import` URL.
+
+**Fix location**: `src/mcp/templates/brand.schema.yaml` (Group 2, §5.4). Add to typography section:
+
+```yaml
+typography:
+  font_display: "'Nohemi', 'Space Grotesk', sans-serif"
+  font_display_source: local | google_fonts | cdn
+  font_display_faces:          # only when source = local
+    - { family, weight, file }
+  font_body: "..."
+  font_body_source: ...
+  google_fonts_import: "..."    # only when one or more sources = google_fonts
+```
+
+The render script must handle all three source types and emit `@font-face` rules for local fonts.
+
+---
+
+### #3 — `brand.default.yaml` values in the plan are wrong
+
+**What happened**: The default brand values in `SHAPE-PHASE-IMPLEMENTATION-PLAN.md` §5.4 were copied from the reference GTPCL HTML, which used **desaturated approximations** of the AvestaHQ brand for web-safety. The authentic brand guide specifies different values:
+
+| Plan said | Brand guide says |
+|---|---|
+| `#F47852` (coral) | `#FE6A3A` (Avesta Coral) |
+| `#224241` (teal) | `#224242` (Deep Teal) |
+| Instrument Serif | Nohemi |
+| DM Sans | Aktiv Grotesk (or Work Sans as web fallback) |
+
+**Fix location**: `src/mcp/templates/brand.default.yaml` (Group 2, §5.6). Replace the entire file with the authentic AvestaHQ values lifted from `Avesta_BrandGuide_V1.pdf`. Use the dogfood `brand.yml` in this directory as the canonical reference.
+
+---
+
+### #4 — Schema needs both Soft Beige and Warm Beige backgrounds
+
+**What happened**: The AvestaHQ brand guide distinguishes **Soft Beige** (`#FFFDF4`, page 31, "Key Hue on the Web" — the digital canvas background) from **Warm Beige** (`#F4F1DE`, brand cream — used for panels, sections, cards). The plan's schema only had `bg_primary` and `bg_secondary` without clarifying which is which.
+
+**Fix location**: `src/mcp/templates/brand.schema.yaml` (Group 2, §5.4). Rename/clarify:
+- `bg_primary` — digital canvas (Soft Beige for AvestaHQ)
+- `bg_secondary` — panels and sections (Warm Beige for AvestaHQ)
+- Add explanatory comments in the schema so brands with different background conventions can map correctly
+
+---
+
+### #5 — Persona slots should support 4 personas, not 3
+
+**What happened**: The plan's §5.4 schema had three persona slots (primary, secondary, tertiary). The AvestaHQ secondary palette has four distinct color families: Deep Teal, Mineral Green, Cloud Blue, Carnation Pink. Supporting four slots gives shape workshops more flexibility and avoids forcing persona merges when there are four legitimate distinct personas.
+
+**Fix location**: `src/mcp/templates/brand.schema.yaml` (Group 2, §5.4). Add `quaternary` persona slot. The render script must support the 4th slot in story card rendering.
+
+**Note**: Prevention's story map uses 3 personas (Priya, Arjun, Ravi), so this isn't exercised in the dogfood fixture. But the schema must support 4 for products with richer persona sets.
+
+---
+
+### #6 — Backbone needs to work for both CLI and dashboard/email personas
+
+**What happened**: The plan's §5.3 schema implicitly assumed all personas share the same surface area (CLI). Prevention has **CLI personas** (Priya, Arjun — run commands daily) and **dashboard/email personas** (Ravi — never touches CLI, reads reports). Both need to be on the same backbone because they're part of the same product journey in time, just entering at different phases and via different surfaces.
+
+**Fix location**:
+- `src/mcp/templates/story-map.schema.yaml` (Group 2, §5.3). Add optional `surface` field to each persona: `cli | dashboard | email | mixed`.
+- `src/mcp/prompts/avesta-shape.md` (Group 5, §5.15). Add guidance: *"Backbone is organized by time. Different phases may have different primary personas. A persona's stories can appear in any phase where they act. Buyer personas (dashboard/email) typically act at the start (evaluate) and the end (observe, renew)."*
+
+---
+
+### #7 — Agent must accept feedback on earlier rounds at any time
+
+**What happened**: During the dogfood, the user provided feedback on Round 0 and Round 1 while Round 2 was in progress. The correct response was to pause Round 2, process the feedback, and resume — not defer to the end. Patton's talk-then-map-then-talk-more principle: corrections compound if held.
+
+**Fix location**: `src/mcp/prompts/avesta-shape.md` (Group 5, §5.15). Add explicit rule:
+
+> At the start of each round, invite the user to revise anything from earlier rounds. Never refuse to go back. If feedback arrives mid-round, pause the current round, process the feedback, capture any new learnings, and resume.
+
+---
+
+### #8 — Brand guidelines should be LAST in the flow, not FIRST
+
+**What happened**: The plan's §5.15 had brand as Step 0 (before Round 1). This was wrong — brand is a rendering concern, so asking about hex codes before any content exists feels bureaucratic and creates friction at the start. Brand naturally fits right before rendering, when the user has the content and asks "how should this look?"
+
+**Fix location**: `src/mcp/prompts/avesta-shape.md` (Group 5, §5.15). Reorder the steps:
+
+| Was | Corrected |
+|---|---|
+| Step 0: Brand | Step 0: **Framing message** (see #11) |
+| Step 1: Round 1 (Who & Why) | Step 1: Round 1 (Who & Why) |
+| Step 2: Round 2 (Journey & Backbone) | Step 2: Round 2 (Journey & Backbone) |
+| Step 3: Round 3 (Stories & Slices) | Step 3: Round 3 (Stories & Slices) |
+| Step 4: Validate | Step 4: Validate content |
+| Step 5: Render | Step 5: **Brand guidelines** ("before I render, how should this look?") |
+| Step 6: Confirm | Step 6: Render |
+| — | Step 7: Confirm and approve |
+
+---
+
+### #9 — Agent must NOT mention external authors in facilitation
+
+**What happened**: The initial draft of the agent prompt and facilitation conversation repeatedly cited "Patton's rule" and "Patton's method." Prevention should own the methodology in the user-facing conversation — no attribution to Jeff Patton, Kent Beck, Dave Farley, Michael Feathers, or other external sources.
+
+**Applies to**: agent facilitation output (`src/mcp/prompts/avesta-shape.md` and any runtime conversation).
+**Does not apply to**: internal skill files in `docs/rules/*.md` — those are developer-facing reference docs and can cite sources for internal methodology grounding.
+
+**Fix location**: `src/mcp/prompts/avesta-shape.md` (Group 5, §5.15). Add explicit rule:
+
+> **Never cite external authors in facilitation.** No Jeff Patton, no Kent Beck, no Dave Farley, no Michael Feathers, no Clayton Christensen. When enforcing a rule, state the rule as the rule — not as someone's quoted rule. Example: instead of *"Patton's rule is the map is not the point"*, say *"One rule I'll keep enforcing: the map is not the point, the conversation around it is."*
+
+**Alignment with existing guidance**: This is consistent with the AvestaHQ voice rules in `.claude/memory/` that content must be original AvestaHQ voice.
+
+---
+
+### #10 — Agent must not narrate meta-commentary during facilitation
+
+**What happened**: The initial facilitation had lines like *"I'm going to ask you directly, one focused question at a time"* and *"In Patton's method we..."* — the agent telling the user how it's about to behave instead of just behaving that way.
+
+**Fix location**: `src/mcp/prompts/avesta-shape.md` (Group 5, §5.15). Add explicit rules:
+
+> - **Don't** say things like *"I'm going to ask you X"* — just ask
+> - **Don't** announce rules mid-conversation — apply them
+> - **Don't** explain the framework during rounds — explain it once in the opening framing (Step 0), then facilitate silently
+> - **Do** enforce rules crisply: state the rule, cite the consequence, move on
+
+---
+
+### #11 — Agent must start with a framing message
+
+**What happened**: The plan's §5.15 jumped straight into Round 0 without explaining to the user *why* the workshop exists, *how long* it takes, *what value* it creates, and *why it's required*. Users need to know the ROI of their time before investing 60-90 minutes in a facilitated workshop.
+
+**Fix location**: `src/mcp/prompts/avesta-shape.md` (Group 5, §5.15). Add explicit "Step 0: Framing" with a templated opening message. Canonical version (developed during dogfood):
+
+> ## `/avesta-shape` — building shared understanding of what to build
+>
+> This is the **shape** phase. I'm going to facilitate a User Story Mapping workshop with you.
+>
+> ### Why we're doing this
+>
+> Most teams skip the conversation between *"why this product exists"* (your vision) and *"how we build the next feature"* (your plan). That skipped conversation is where product fails — engineering builds well-crafted features for the wrong users in the wrong order, product builds roadmaps disconnected from what engineering can ship, and nobody agrees on what the MVP actually is.
+>
+> A story map fills the gap. When we finish, you'll have a single visual artifact showing:
+>
+> - **Who** your users are and what jobs they're hiring your product for
+> - The **end-to-end journey** they take to get value (the backbone)
+> - **Every story** you might build, stacked vertically by priority
+> - Which stories belong in the **MVP** — the smallest walkable skeleton that delivers real value end-to-end
+> - Which stories belong in R2, R3, R4 — named by the **outcome** they add, not the features
+> - What you're **explicitly NOT building** (as important as what you are)
+>
+> This becomes the bridge between product and engineering. Without it, `/avesta-plan` operates in a vacuum — you'll get well-engineered features for the wrong product.
+>
+> ### Why this is required, not optional
+>
+> Prevention is built on one thesis: **build the product right, ship value fast, learn continuously**. You cannot "build the product right" if product and engineering don't share a picture of what the product *is*. The story map isn't documentation you produce to satisfy a gate — it's the working artifact that keeps the team aligned for the entire life of the product. Every feature planning session will pull from it. Every release will close out stories on it. Every quarterly review will revisit it.
+>
+> That's why it's a hard gate before `/avesta-plan` for new features. Bug fixes and tech debt bypass the gate because they work below the map level.
+>
+> ### What it takes
+>
+> Three focused rounds of conversation. Budget ~60–90 minutes for a first product, longer for complex ones. You can pause and resume — I save progress as we go.
+>
+> 1. **Who & Why** (~15 min) — personas and the jobs they're hiring your product to do
+> 2. **Journey & Backbone** (~30 min) — the time-ordered path they take to get value
+> 3. **Stories & Slices** (~45 min) — what you'll build, prioritised vertically and sliced horizontally into releases
+>
+> I'll ask focused questions and push back when answers are hand-wavy.
+>
+> **One rule I'll keep enforcing**: *the map is not the point — the conversation around it is.* If you try to treat this as a form to fill out, I'll stop you.
+>
+> ### Output
+>
+> - `.avesta/docs/user-story-map/story-map.yml` — canonical source of truth
+> - `.avesta/docs/user-story-map/story-map.html` — shareable visual for stakeholders
+> - `.avesta/docs/user-story-map/brand.yml` — visual brand config for the HTML (covered at the end, right before rendering)
+>
+> ### Ready?
+>
+> I'll start Round 1 with the person your product is most obviously for.
+
+---
+
+### #12 — Render script should use `yaml` not `js-yaml`
+
+**What happened**: The plan's §5.7 specified `js-yaml` as the YAML parser for the render script. The Prevention repo already has `yaml` (eemeli/yaml) as a dependency in `package.json`. Adding `js-yaml` would create a redundant dependency.
+
+**Fix location**: `docs/SHAPE-PHASE-IMPLEMENTATION-PLAN.md` §5.7 — update to use `yaml` package. `scripts/render-story-map.mjs` (Group 2) — use `import YAML from 'yaml'; YAML.parse(...)`.
+
+---
+
+### #13 — Backlog stories need an explicit rendering decision
+
+**What happened**: The schema supports `release: backlog` for stories that are captured but not yet slotted into any release. The throwaway renderer excludes backlog stories from the HTML output because there's no "backlog" release line. This means the rendered HTML shows 140 of 144 stories — the 4 backlog items exist in YAML but are invisible on the map.
+
+**Fix location**: `src/mcp/templates/story-map.html.hbs` (Group 2, §5.5) + `scripts/render-story-map.mjs` (Group 2, §5.7). Choose one of three options:
+
+- **(a)** Implicit backlog release line at the bottom — gray, no label, just shows stories
+- **(b)** "Parking lot" section below the Not-in-scope card — visually distinct, labeled *"Parking Lot — captured but not yet scoped"*
+- **(c)** Keep current behaviour — backlog stories live in YAML only, not rendered
+
+**Recommendation**: Option (b) — a parking lot is visually distinct and makes "we haven't decided where this goes yet" explicit, which is honest and prevents the stories from being forgotten.
+
+---
+
+## Schema additions surfaced during dogfood
+
+Beyond the numbered learnings, the dogfood surfaced schema fields that were useful in practice but weren't in the original §5.3 schema:
+
+1. `product_description` — the 2-sentence description rendered as the header subtitle. Essential for the HTML header. Add to story-map.schema.yaml.
+2. `personas[].surface` — `cli | dashboard | email | mixed` for backbone rendering decisions. See learning #6.
+3. `personas[].trigger_moment` — narrative description of the specific moment a persona decides to adopt the product. Useful for the agent's walking-skeleton validation (if the trigger moment doesn't walk through the MVP stories, the MVP is wrong).
+4. `stories[].notes` — optional free-text for stories that need context (already in the schema, used for backlog items to document *why* they're backlog).
+5. `releases[].color_key` — reference to `brand.yml` release slots instead of inline hex codes. Already in the schema; dogfood confirmed this indirection works cleanly.
+
+---
+
+## Flow learnings not captured as numbered items
+
+These are softer observations from the dogfood that shape how the agent should behave:
+
+1. **Strawman-first is cheaper than cold questions for experienced product owners.** When facilitating a user who already knows their product deeply, proposing a strawman (persona, backbone, story set) and letting them edit is faster than asking cold questions. The agent should detect this: if the user has an existing vision doc, codebase, or prior product experience, lean strawman-first. If the user is pre-product or unclear, lean cold-questions.
+
+2. **User feedback on earlier rounds compounds value.** The dogfood surfaced 4 corrections on Rounds 0 and 1 while Round 2 was in progress. Each correction improved the final artifact meaningfully. Design the agent to welcome this.
+
+3. **The user/buyer split is critical for B2B products.** The dogfood surfaced that Ravi (CTO) is both an indirect beneficiary (experiences Priya's improved DORA metrics) AND a direct user via a different surface (dashboard, email, renewal flow). This is not a Patton-specific point — it's a B2B product design point — but the agent must handle it. For B2B products, MVP must have a **walking skeleton for the buyer persona too**, even if thin (4-6 stories).
+
+4. **Recursive phases work.** The shape phase appears on Prevention's own backbone as phase 6 (shape the solution). Self-referential but not circular. The agent should be OK with this and not flag it as an error.
+
+---
+
+## Files produced by this dogfood
+
+| File | Size | Purpose |
+|---|---|---|
+| `brand.yml` | 4.7 KB | AvestaHQ brand config — canonical reference for `brand.default.yaml` in Group 2 |
+| `story-map.yml` | 37 KB | Full story map schema example — canonical test fixture for Group 2 render script tests |
+| `story-map.html` | 46 KB | Rendered HTML — visually verified against GTPCL reference design |
+| `fonts/Nohemi-Regular.woff2` | 20 KB | Self-hosted brand font |
+| `fonts/Nohemi-Medium.woff2` | 20 KB | Self-hosted brand font |
+| `fonts/Nohemi-SemiBold.woff2` | 20 KB | Self-hosted brand font |
+| `fonts/Nohemi-Bold.woff2` | 19 KB | Self-hosted brand font |
+| `scripts/render-story-map-dogfood.mjs` | 16 KB | Throwaway renderer — to be replaced by production version in Group 2 |
+| `GROUP-0-LEARNINGS.md` | this file | Feeds Groups 1–8 |
+
+---
+
+## What happens next
+
+With Group 0 complete, implementation proceeds in dependency order:
+
+1. **Group 1** — Skills (`docs/rules/user-story-mapping.md`, `docs/rules/persona-jtbd.md`). Skill content is informed by dogfood learnings #6, #7, #8, #9, #10, #11.
+2. **Group 2** — Schema, template, render script (§5.3 – §5.9). Uses Group 0 fixtures as test inputs. Incorporates learnings #2, #3, #4, #5, #12, #13.
+3. **Group 3** — Core types and gate state machine (§5.10 – §5.12).
+4. **Group 4** — Framework catalog (§5.13, §5.14).
+5. **Group 5** — Agent files (§5.15 – §5.17). Agent prompt encodes learnings #1, #6, #7, #8, #9, #10, #11.
+6. **Group 6** — Planner integration (§5.18, §5.19).
+7. **Group 7** — Tests (§5.20 – §5.24). Render test uses Group 0 fixtures.
+8. **Group 8** — Documentation (§5.25 – §5.27).
+
+Each group should cross-reference this file to ensure the relevant learnings are applied.

package/.avesta/docs/user-story-map/brand.yml

@@ -0,0 +1,105 @@
+schema_version: "1.0"
+name: "AvestaHQ"
+source: user
+# Extracted from Avesta_BrandGuide_V1.pdf during Group 0 dogfood workshop.
+# Colors from pages ~25-30 of the brand guide. Typography from pages ~31-34.
+# Work Sans is explicitly named in the brand guide as the open-source web
+# equivalent to Aktiv Grotesk — used here for body because Aktiv Grotesk
+# web fonts are not available in the brand asset pack (OTF only).
+
+typography:
+  # Headings — self-hosted Nohemi (brand primary display typeface).
+  # .woff2 files copied from /home/av19/Projects/AvestaHQ Branding/.../Nohemi/Web-TT/
+  font_display: "'Nohemi', 'Space Grotesk', 'Inter', sans-serif"
+  font_display_source: local
+  font_display_faces:
+    - { family: "Nohemi", weight: 400, file: "fonts/Nohemi-Regular.woff2" }
+    - { family: "Nohemi", weight: 500, file: "fonts/Nohemi-Medium.woff2" }
+    - { family: "Nohemi", weight: 600, file: "fonts/Nohemi-SemiBold.woff2" }
+    - { family: "Nohemi", weight: 700, file: "fonts/Nohemi-Bold.woff2" }
+
+  # Body — Work Sans from Google Fonts (brand-sanctioned alternate to
+  # Aktiv Grotesk, named explicitly in the brand guide as the web equivalent).
+  font_body: "'Work Sans', -apple-system, system-ui, sans-serif"
+  font_body_source: google_fonts
+
+  # Mono — DM Mono from Google Fonts (not in brand guide; matches the
+  # reference story map aesthetic for small labels and persona tags).
+  font_mono: "'DM Mono', ui-monospace, monospace"
+  font_mono_source: google_fonts
+
+  google_fonts_import: "https://fonts.googleapis.com/css2?family=Work+Sans:wght@400;500;600;700&family=DM+Mono:wght@400;500&display=swap"
+
+colors:
+  # Primary — Avesta Coral + Warm Beige (from brand guide pages 24-25)
+  accent_primary: "#FE6A3A"          # Avesta Coral — warmth, momentum
+  accent_primary_dark: "#E55F34"     # darker tint from the coral scale
+  bg_warm_beige: "#F4F1DE"           # Warm Beige — brand cream
+
+  # Primary digital background (Soft Beige — page 31, "Key Hue on the Web")
+  bg_primary: "#FFFDF4"              # Soft Beige — calm, neutral digital canvas
+  bg_secondary: "#F4F1DE"            # Warm Beige — used for panels and sections
+
+  # Text
+  text_primary: "#181816"            # near-black from the cream scale
+  text_secondary: "#5C5850"          # mid-neutral
+  text_muted: "#9C978A"              # light-neutral
+  text_on_dark: "#F4F1DE"            # warm beige on teal backgrounds
+  text_on_dark_muted: "#A8BDB5"
+
+  # Borders
+  border: "#DDD8C8"                  # light warm neutral
+  border_dark: "#3A5B59"             # teal-shifted border
+
+  # Secondary palette — the full AvestaHQ secondary colour set
+  # (page 26 of the brand guide)
+  deep_teal: "#224242"               # Depth • Experience — dominant secondary
+  deep_teal_mid: "#2D5654"           # slightly lighter for backbone mid
+  deep_teal_light: "#3A6B69"         # lighter for accents
+  deep_teal_dark: "#1f3b3b"          # darker shade from scale
+  mineral_green: "#377D71"           # Stability • Process
+  cloud_blue: "#8FB9F8"              # Product Sense
+  carnation_pink: "#FFA3BE"          # Open • Culture
+
+persona_slots:
+  # Each persona gets a background tint (card background) and dark variant
+  # (text color). Light tints are derived from the tint scales in the brand
+  # guide (pages 25-27). Assignments match the AvestaHQ secondary palette.
+  primary:
+    # Deep Teal persona (most common — the primary user)
+    name_hint: "Deep Teal family"
+    bg: "#D4E8E4"                    # light teal tint (derived)
+    text: "#0D2B2A"                  # deep teal dark
+    accent: "#224242"
+  secondary:
+    # Mineral Green persona
+    name_hint: "Mineral Green family"
+    bg: "#D9EBE7"                    # light mineral green tint
+    text: "#1E4A42"                  # mineral dark
+    accent: "#377D71"
+  tertiary:
+    # Cloud Blue persona
+    name_hint: "Cloud Blue family"
+    bg: "#DCE8FC"                    # light cloud blue tint
+    text: "#1B3A6B"                  # cloud dark
+    accent: "#8FB9F8"
+  quaternary:
+    # Carnation Pink persona
+    name_hint: "Carnation Pink family"
+    bg: "#FFE0E8"                    # light pink tint
+    text: "#6B1F35"                  # pink dark
+    accent: "#FFA3BE"
+  quinary:
+    # Warm Amber persona (5th slot — for products with 5 personas)
+    name_hint: "Warm Amber family"
+    bg: "#F1E4C5"                    # soft amber tint
+    text: "#5A4418"                  # deep amber brown
+    accent: "#B8862C"                # muted gold
+
+release_slots:
+  # Release lines use the coral for MVP (brand primary — warmth, momentum)
+  # and secondary palette for later releases.
+  mvp: "#FE6A3A"                     # Avesta Coral — the drive to ship
+  r2: "#377D71"                      # Mineral Green — stability, process
+  r3: "#8FB9F8"                      # Cloud Blue — product sense
+  r4: "#FFA3BE"                      # Carnation Pink — culture, openness

package/.avesta/docs/user-story-map/personas/arjun.md

@@ -0,0 +1,58 @@
+# Arjun — Junior Dev on Priya's team
+
+*Color slot: secondary* · *Surface: cli* · *Frequency: daily*
+
+## Jobs to be done
+
+### Functional
+> When I use AI to write code, I want to know it's right before I push, so my PR doesn't end up in Priya's queue with 15 review comments.
+
+### Emotional
+Feel confident he's learning, not just accepting AI suggestions uncritically. The fear underneath: "am I actually getting better at this, or am I just a Claude Code conduit?"
+
+### Social
+Be seen by Priya as someone who ships clean work without hand-holding. Be seen by his peers (other juniors) as the one who figured out how to use AI well. Not be the junior Priya sighs about in her 1:1 with the CTO.
+
+## Pains
+- "AI suggests code I don't fully understand and I'm not sure if it's right."
+- "Tests pass but I'm not sure they prove what I think they prove."
+- "My PRs come back with architecture comments I didn't know to check for."
+- "Worried I'm building bad habits by accepting AI output uncritically."
+
+## Current workarounds
+- Accept AI suggestions and hope PR review catches issues
+- Ask Priya in Slack before committing anything non-trivial ("hey is this the right way to...")
+- Read skill docs (Clean Architecture, TDD) but not systematically
+- Sometimes paste AI output into ChatGPT for a second opinion
+
+## Trigger moment
+
+Arjun's PR from last week came back with 12 comments from Priya. Most were "this tests the implementation, not the behaviour" — a phrase he'd never heard in bootcamp. He fixed them but didn't understand *why* the original tests were wrong. The fix felt like cargo-culting Priya's comments.
+
+Today's standup, Priya mentioned Prevention and said "Arjun, try it on your next ticket." That's the trigger — not a moment of dread, but a moment of guarded optimism. "Maybe this will teach me what Priya means when she says 'behaviour not implementation'."
+
+## Evidence
+
+This persona is composited from junior developers I've talked to in the TS/Node bootcamp-graduate community. The specific tension (AI makes them faster but they feel like they're not learning) appears repeatedly. The "12 PR review comments" scenario is pattern-matched from multiple real-world Slack conversations.
+
+## Day in the life
+
+**9:30** — Standup. Assigned a new ticket: "Add promo code validation to checkout."
+
+**10:00** — Opens Claude Code. Types "add promo code validation to checkout.ts". Gets a working implementation in 30 seconds.
+
+**10:05** — Runs the tests locally. They pass. Commits.
+
+**10:10** — Thinks: "wait, should I run Prevention on this? Priya said try it." Opens Claude Code and types `/avesta-red`.
+
+**10:15** — Prevention refuses to write the test Arjun wants, explains why (it's testing the implementation, not the behaviour), and suggests the test that SHOULD exist. Arjun reads the explanation twice. The lightbulb goes on.
+
+**10:30** — With Prevention's guardrails, he writes the test first, sees it fail, writes the minimal code to pass. Refactors. Ships. The PR review comes back with 1 comment (a style nit) instead of 12.
+
+**11:00** — Pings Priya: *"hey that Prevention thing is actually really good. I get it now."*
+
+## Notes
+
+- Arjun is an ICP for adoption velocity: if Prevention teaches juniors while gating them, it self-sells.
+- He's NOT the buyer, NOT the champion, but he's the critical mass — if the junior rank rejects the tool, Priya gives up.
+- He'll use Prevention's explanations as learning material more than his teammates. The "agent refuses and explains why" pattern is the onboarding mechanism for behavior-first testing.

package/.avesta/docs/user-story-map/personas/priya.md

@@ -0,0 +1,75 @@
+# Priya — Tech Lead
+
+*Color slot: primary* · *Surface: cli* · *Frequency: daily*
+
+## Jobs to be done
+
+### Functional
+> When my team ships AI-assisted code, I want confidence it won't break production, so I can stop being the last line of defence.
+
+### Emotional
+Feel in control of quality without personally reviewing every line of every PR. Stop dreading Monday mornings because something shipped on Friday might blow up.
+
+### Social
+Be seen by her CTO as the TL whose team ships fast AND clean — not the one whose team ships slop. Be seen by her juniors as the mentor who gave them guardrails, not roadblocks. Be the TL other TLs ask about how to adopt AI coding agents without losing quality.
+
+## Pains
+- "AI-generated code looks right in PR review, then breaks in production two days later."
+- "Our test coverage went up but I don't trust the tests — they feel decorative. AI writes tests that mirror the implementation instead of the behaviour."
+- "I've become the bug firefighter. My calendar is full of 'can you look at this prod issue' since we adopted AI agents."
+- "Our QA cycle got longer, not shorter, because nobody trusts the AI output and QA has to catch what PR review misses."
+- "My CTO is starting to ask why we're paying for Claude Code licences when production incidents are up."
+- "Juniors commit AI slop without understanding it — I can't tell if they learned anything or just accepted the suggestion."
+
+## Current workarounds
+- Claude Code / Cursor / Codex for generation — daily, multiple times per day
+- Manual PR review catches some issues, misses others
+- QA manual testing as a safety net that's been expanding since AI agent adoption
+- Fix → QA → fix → QA loop before every prod release
+- Customer-reported bugs as the final (and costly) safety net
+
+## Trigger moment
+
+Tuesday morning, standup: Arjun (junior on her team) says he shipped his PR end-of-day Monday — Claude Code wrote the whole thing, PR review passed, merge went clean. Priya marks it complete on the board.
+
+Wednesday afternoon: checkout starts returning 500s for ~8% of sessions. Customer support pings engineering. Priya drops into debug mode.
+
+Thursday: 3-hour root-cause hunt. The Monday PR added a new validation rule to checkout that the tests asserted "correctly" (they tested what the code did, not what checkout should do). The AI wrote mirror-image tests. The bug was in the spec itself — but nobody wrote the spec, AI inferred it.
+
+Friday morning: Priya's CTO pulls her into a 1:1. *"Our incident rate is up since we rolled out Claude Code. I can't defend the spend to the board if this continues. Help me understand — should we pull back?"*
+
+Friday afternoon: Priya opens her laptop and starts searching for *"how to make AI coding agents actually safe"*.
+
+## Evidence
+
+This persona is composited from multiple real conversations I've had with tech leads at small-to-mid TS/Node/Next.js startups who adopted Claude Code/Cursor in the last 6-12 months. The specific pain points (decorative tests, AI slop, QA cycle expansion) appear repeatedly across:
+
+- Twitter/X discussions in the TS + AI-coding community
+- HackerNews threads on Cursor/Claude Code rollout outcomes
+- Direct conversations with early AvestaHQ design partners
+
+The trigger moment scenario is directly modeled on a real incident pattern I've heard described three times in different companies.
+
+## Day in the life
+
+**9:00** — Standup. Team reports 4 PRs merged Friday + weekend, all AI-assisted. Priya notes them mentally — she'll check CI signal but trusts the merge gate to have done its job.
+
+**9:30** — Opens Slack. Customer support has a thread about checkout failures from Sunday. Drops in.
+
+**10:00** — Pulls the checkout PR from Friday. Reads the diff, reads the tests, reads the spec... wait, what spec? Scrolls up to find it. There's no spec — the commit message says "add promo code validation" and the description is one sentence. The tests check `validatePromo()` returns `false` for expired codes. Priya thinks "OK but what happens when the user enters a valid code?" — and finds the happy path test doesn't exist.
+
+**11:00** — Writes the missing happy-path test locally. It fails. Finds the bug: a new branch in the validator returns `false` when `new Date(code.expires) > new Date()` instead of `<`. Sign inverted. Claude Code wrote both the bug and the asserting test.
+
+**14:00** — Fix is in, rolled out, checkout recovers. Slack thanks. Priya writes a post-mortem explaining what happened and drafts a "we need better testing discipline" memo for the team.
+
+**16:00** — Drafts a Slack message to her CTO: *"I think we need to talk about how we're using Claude Code."*
+
+**17:30** — Leaving for the day. Opens HN on the train. Sees a post about Prevention. Stops scrolling.
+
+## Notes
+
+- Priya is NOT a QA person who got promoted. She's a former IC who leads through technical judgment.
+- Her team has no dedicated QA — QA is whoever has the least context on the PR.
+- She uses Cursor for her own work AND reviews Claude Code output from juniors. Both generation and review failure modes hit her.
+- She's already tried "we'll write better tests" and "we'll review more carefully" — both failed because human discipline doesn't scale past the third PR of the day.
+- She's the buying ICP's most common surface — if Priya adopts, Ravi (her CTO) asks "how's it going?" at month 1 and at renewal.

package/.avesta/docs/user-story-map/personas/ravi.md

@@ -0,0 +1,66 @@
+# Ravi — CTO / Engineering Manager (the buyer)
+
+*Color slot: tertiary* · *Surface: mixed* · *Frequency: weekly*
+
+## Jobs to be done
+
+### Functional
+> When I report to the board, I want to show AI adoption is paying off — not costing us more than it saves.
+
+### Emotional
+Feel confident the engineering investment is producing business value. Stop defending the Claude Code line item in every quarterly review.
+
+### Social
+Be seen by the board as a CTO who picked winning tools. Be seen by the team as someone who buys them what they actually need, not just what's trending on HackerNews. Be the CTO other CTOs ask "how did you roll out AI coding safely?"
+
+## Pains
+- AI tool spend going up quarter over quarter, production incident rate also going up
+- Board asking for evidence AI adoption is producing ROI, not anecdotes
+- Cannot distinguish "the team is working hard" from "the team is producing value"
+- No shared view of team output — only anecdotes from 1:1s with tech leads
+- Every DORA-style metric he tracks is a manually assembled spreadsheet
+
+## Current workarounds
+- Quarterly DORA spreadsheet built by Ravi or a staff engineer, by hand
+- Weekly status updates from tech leads in 1:1s
+- Reading PRs to spot-check quality (doesn't scale past ~20 PRs/week)
+- Trusting tech leads' gut feel on whether tooling is working
+
+## Trigger moment
+
+Ravi's quarterly board review is in 3 weeks. Last quarter the board asked: *"Your engineering headcount is flat, your tool spend is up 40%, your production incident count is up 15%. What's the ROI story on AI tooling?"*
+
+He didn't have a good answer. He's been losing sleep about it since.
+
+Today, Priya pings him: *"I found something that might help. Can we talk for 15 minutes?"*
+
+That's the trigger. Ravi doesn't run CLI commands — he books the 15-minute meeting, listens to Priya, and says "if this gets me a real ROI story for the board, buy it. What tier do we need?"
+
+## Evidence
+
+Composited from CTO/EM conversations at small-to-mid startups (~20-100 engineers) post-AI-coding-tool adoption. The specific pattern — *board asking for ROI evidence, CTO having only anecdotes* — appears in every conversation. The trigger moment (Priya pings Ravi after finding something) is the classic champion-led B2B buy motion.
+
+## Day in the life
+
+**9:00** — Ravi's morning routine: coffee, open laptop, scan Slack for overnight fires. One prod incident from Sunday, already fixed. Notes it for the weekly incident report.
+
+**9:30** — Opens the Prevention dashboard (after Priya installed it two weeks ago). Sees:
+- 14 features shipped last week with all gates green
+- DORA trend: deploy frequency up 30%, change failure rate down 8%, lead time flat
+- 2 gate violations caught pre-merge
+
+**9:35** — Screenshots the dashboard. Drops it into the draft board deck in the "Engineering ROI" section.
+
+**10:00** — Pings Priya: *"This Prevention thing — do you have a story I can take to the board about how it changed your team's workflow?"*
+
+**13:00** — Priya sends him a 3-paragraph summary. Ravi pastes it into the deck.
+
+**17:00** — Before leaving, Ravi submits the renewal for Prevention. He also upgrades the tier from free to pro because he wants his other two teams on it by next quarter.
+
+## Notes
+
+- Ravi NEVER runs CLI commands. His interaction surface is dashboards, emails, and weekly summaries.
+- The MVP story for Ravi is NOT "full DORA dashboard" — it's *"one number I can put in the board deck."*
+- He's the buying ICP but NOT the user. The product must walk BOTH skeletons — Priya's daily loop AND Ravi's buy-validate-renew cycle.
+- If Prevention fails for Ravi, it gets cancelled at renewal no matter how much Priya loves it.
+- Ravi's "aha" moment is seeing the DORA trend with his own eyes, not hearing Priya say "it's working."