Aep Calibrate

Calibrate

Human alignment checkpoint. Agents build to spec, but specs are lossy compressions of human intent. This skill pauses execution, lets the human inspect what was built, and captures what "right" actually means in a format agents can consume.

Where this fits:

/aep-reflect (identified alignment gap)
  → /aep-calibrate           (Phase 1: generate dimension-specific brief)
  → human explores       (method varies by type — external tools, conversation, code review)
  → /aep-calibrate capture   (Phase 2: capture decisions into artifact)
  → /aep-dispatch            (stories dispatched with calibration context)

Session: Main, interactive with user Input: Calibration type + product definition from product/index.yaml (split mode) or product-context.yaml (v1 mode) + operational state from product-context.yaml Output: Calibration artifact (standalone or inline) + updated calibration.history

---

Type Detection

Check how the skill was invoked to determine the calibration dimension:

Path A — Explicit: User says /aep-calibrate visual-design or /aep-calibrate api-surface. Type is given directly.

Path B — Routed from `/aep-reflect`: Reflection classified an observation as a calibration need with a specific dimension. The dimension and observation text are passed as context.

Path C — Ambient: User says /aep-calibrate with no type. Determine the type:

1. Check calibration.plan in product-context.yaml (operational file, both modes) — which dimension is next for the current layer? 2. Check stories with calibration_type set in the current .5 layer. 3. If neither applies, ask the user: "What feels off? (visual design / UX flow / API surface / data model / scope direction / copy tone / performance quality)"

---

File Resolution

ls product/index.yaml 2>/dev/null && echo "SPLIT MODE" || echo "V1 MODE"
cat product-context.yaml

• Split mode (product/index.yaml exists): Read quality_dimensions, layers, activities, constraints, success_criteria, failure_model from product/index.yaml. Read calibration.plan, calibration.history, stories, architecture from product-context.yaml.
• V1 mode: Read everything from product-context.yaml.

Write targets by calibration type:

• Heavy (visual-design, ux-flow, copy-tone): Write calibration/<type>.yaml. Append calibration.history + changelog in product-context.yaml.
• Light — architecture (api-surface, data-model): Update architecture.interfaces or architecture.domain_model in product-context.yaml. Append calibration.history + changelog.
• Light — product intent (scope-direction, performance-quality): Update product.goals, product.mvp_boundary, product.layers, product.success_criteria, or product.failure_model in product/index.yaml (split mode) or product-context.yaml (v1 mode). Append calibration.history + changelog in product-context.yaml.

---

Mode Detection

After type is determined, check for existing calibration:

• Establishment mode: No prior entry in calibration.history for this dimension → full brief, create artifact from scratch
• Extension mode: Prior entry exists → delta brief covering only NEW patterns/decisions not in existing calibration

---

The Two Classes of Calibration

Calibration types split into two natural classes:

Heavy Calibrations

External exploration required. The human uses tools outside the agent workflow (design tools, wireframing, copy docs). Produces standalone YAML artifacts in calibration/ directory. Creates .5 alignment layer stories.

Light Calibrations

Conversational. The human reviews current state and makes decisions through structured Q&A. Updates existing sections of product-context.yaml directly. May or may not create .5 layer stories.

---

Phase 1: Generate Brief

Step 1: Read Product Context

cat product-context.yaml

Extract:

• opportunity.bet + product.problem → product identity
• product.persona.description + product.persona.jtbd → target user
• opportunity.why_now → urgency/positioning
• stories where layer matches the active layer → scope of what was built or will be built
• product.constraints.required_stack + preferred_stack → technical constraints
• calibration.history → prior calibration decisions for this dimension (extension mode)

Step 2: Scan Current State

Scan targets vary by calibration type:

Step 3: Generate Brief

Use the type-specific template from references/briefs/<type>.md.

Establishment mode: Generate the full brief template with all sections.

Extension mode: Read existing calibration artifact or product-context sections. Identify what's NEW in the current layer that isn't covered by prior calibration. Generate a focused brief: "Here's your current calibrated system. These new [pages/endpoints/entities/etc.] need decisions not yet covered: [list]."

Write the brief to docs/calibration-brief.md and output the full content to terminal.

Step 4: Hand Off

Heavy calibrations (visual-design, ux-flow, copy-tone):

Output exploration instructions and stop. The human explores externally — this is explicitly out of the agent's hands.

Calibration brief written to: docs/calibration-brief.md

Next steps (you do these):

  1. [Type-specific exploration instructions]
  2. Explore variations. Pick what feels right.
  3. Save reference files to docs/calibration-references/ (if applicable)
  4. When ready, come back and run:
     /aep-calibrate capture

For visual-design specifically, point to references/vibe-design-tools.md for tool guidance.

Light calibrations (api-surface, data-model, scope-direction, performance-quality):

Present the brief to the human, then proceed directly to Phase 2. No external exploration needed — the brief frames the conversation.

---

Phase 2: Capture Decisions (/aep-calibrate capture)

Step 1: Interactive Q&A

Ask structured questions from references/capture/<type>.md, one at a time.

Heavy calibration questions (examples):

• visual-design: Direction chosen, palette, typography, components, layout, brand signals, reference files
• ux-flow: Journey decisions, transition feel (instant/guided/deliberate), page map, entry/exit points
• copy-tone: Voice personality, reference products, pattern decisions (headings, buttons, errors, empty states), glossary terms

Light calibration questions (examples):

• api-surface: Naming decisions, grouping, error contract shape, versioning approach
• data-model: Entity names, field names, relationships, invariants, normalization rules
• scope-direction: Gap assessment (what percentage is "right"?), one-thing-to-add, scope gap vs direction gap
• performance-quality: Latency thresholds per action, retry policy, caching strategy, degradation behavior

Step 2: Produce Artifact

Heavy calibrations:

• Establishment mode: Create the artifact YAML from scratch using the schema at references/schemas/<type>-schema.yaml. Fill all sections from Q&A answers.
• Extension mode: Read existing calibration/<type>.yaml. Add new entries for newly covered patterns. Update calibrated_at and calibrated_from_layer. Do not replace existing values — extend them.

Write to calibration/<type>.yaml.

Light calibrations:

Update the relevant section(s) — see File Resolution above for which file to write to per calibration type:

For visual-design specifically: Also update globals.css with the captured palette. Read palette values, convert to oklch if provided in other color spaces, write as CSS custom properties under :root and .dark selectors.

• Establishment mode: Replace the full palette.
• Extension mode: Only add new custom properties if the palette expanded. Do not touch existing values.

Step 3: Update Calibration History

Append to calibration.history in product-context.yaml:

- dimension: <type>
  calibrated_at: "<ISO date>"
  calibrated_from_layer: <layer>
  mode: establishment # or extension
  artifact_path: "calibration/<type>.yaml" # null for light calibrations
  sections_updated: [] # e.g., ["architecture.interfaces"] for light calibrations
  summary: "<one-line summary of what was decided>"

Also append to changelog:

- date: <ISO date>
  type: calibration
  author: human
  summary: "Calibrated <dimension> — <summary of decisions>"
  sections_changed:
    - calibration
    - <any other sections updated>

Step 4: Commit

# Resolve $BASE (integration branch) — see git-ref "Integration Branch" (override → develop → main)
BASE=$(git config --get aep.integration-branch 2>/dev/null || true)
[ -z "$BASE" ] && { git show-ref --verify --quiet refs/heads/develop \
  || git show-ref --verify --quiet refs/remotes/origin/develop; } && BASE=develop
BASE=${BASE:-main}

git pull --ff-only origin "$BASE"
git add calibration/ product-context.yaml
git commit -m "feat: calibrate <dimension> — <brief summary>"
git push origin "$BASE"

---

Type-Specific Reference: visual-design

Visual design is the most fully developed calibration type and serves as the reference implementation for others.

Phase 1 Specifics

• Design brief template: references/briefs/visual-design.md
• Design directions: Generate 3 directions spanning a spectrum from "maximum technical" to "maximum approachable". Name 2-3 reference products per direction as visual mood board anchors.
• Vibe design tool guide: references/vibe-design-tools.md — covers Google Stitch, Pencil.dev, and alternatives.

Phase 2 Specifics

• Schema: references/schemas/visual-design-schema.yaml
• Artifact: calibration/visual-design.yaml — palette (oklch), typography, spacing, layout, components, brand signals, reference designs
• Companion artifact: Updated globals.css with CSS custom properties from captured palette
• Three concerns, three artifacts: calibration/visual-design.yaml documents decisions (why), globals.css enacts them (what), reference files in docs/design-references/ show the visual target (how it looks).

Mode Detection

• Establishment mode: calibration/visual-design.yaml does not exist → full calibration (palette, typography, layout, everything)
• Extension mode: File exists → focused brief covering only NEW UI patterns not in the existing design context

---

Key Principles

• Agents optimize for correctness against spec. But specs are lossy compressions of human intent. Calibration corrects the loss.
• The human decides. The skill generates options, frames choices, and captures decisions. It does not make choices.
• Heavy calibrations pause; light calibrations flow. Visual design needs external tools and hours. API naming needs a 30-minute conversation. Both are calibration.
• Extension mode covers only the delta. No full redesign on subsequent calibrations — just new patterns that prior calibration didn't cover.
• Machine-readable artifacts. Agents query calibration artifacts for specific values (palette.dark.primary, components.border_radius, voice.personality). Prose descriptions are not queryable.
• `.5` layers are human alignment layers. Not just "UI polish." Any dimension where agent output diverges from human intent.

API Surface Brief: [project name]

Product Identity

• What: [from opportunity.bet + product.problem]
• For whom: [from product.persona.description]
• Consumers: [who calls this API — internal frontend, external developers, other services]

Current API Shape

[from architecture.interfaces, grouped by module boundary]

Naming/Grouping Concerns

[from /aep-reflect observation or ambient detection]

• Naming inconsistency: [examples — mixed conventions, unclear verbs, ambiguous nouns]
• Grouping issue: [examples — related endpoints spread across modules, unrelated endpoints grouped]
• Error contract: [current error shape vs. what consumers expect]

Conventions Observed in Codebase

[scan existing route/controller files for patterns already in use]

• Naming convention: [e.g., kebab-case paths, camelCase params]
• Error format: [e.g., { error: { code, message } } or { status, detail }]
• Versioning: [current approach or none]

Questions for Calibration

1. When you think about [resource], what verb do you reach for? 2. These endpoints do related things — should they be grouped under [X] or [Y]? 3. Error response: machine-readable codes, human-readable messages, or both? 4. Versioning: path-based (/v1/), header-based, or none for now? 5. Pagination: cursor-based, offset-based, or not needed? 6. Should any endpoints be renamed, merged, or split?

---

Extraction Map

Copy/Tone Brief: [project name]

Product Identity

• What: [from opportunity.bet + product.problem]
• For whom: [from product.persona.description]
• Core job: [from product.persona.jtbd]

Product Voice (Inferred)

[from product.persona — infer the voice the product should have for this audience]

• Audience technical level: [from persona description]
• Context of use: [when/where do they interact with this product?]
• Expected tone: [formal/casual/technical/friendly — inferred from persona + domain]

Sample UI Text (Current)

[scan components for actual text content]

Tone Mismatch

[from /aep-reflect observation or ambient detection]

• Current feel: [how the product reads now]
• Expected feel: [how it should read]
• Specific examples: [texts that feel wrong and why]

Questions for Calibration

1. Pick 3 products whose voice you'd steal for this product. 2. Pick 1 product whose voice you'd actively avoid. 3. This error message: "[current]" — how would you rewrite it? 4. Button says "[current label]" — is that what a user would look for? 5. Empty state: what should it say? Encouraging? Instructional? Minimal? 6. How formal should headings be? (e.g., "Dashboard" vs "Your Dashboard" vs "Here's what's happening") 7. Technical jargon: embrace it (audience expects it) or translate it?

---

Extraction Map

Data Model Brief: [project name]

Product Identity

• What: [from opportunity.bet + product.problem]
• Domain: [the real-world domain this models]

Current Domain Model

[from architecture.domain_model, listed with key fields]

Language Mismatch

[from /aep-reflect observation or ambient detection]

• Code says: [term] → Team says: [term]
• Entity [X] has fields [a, b, c] → but the domain concept is really [...]
• Relationship confusion: [X] owns [Y]? Or [Y] references [X]?

Schema/Migration State

[scan ORM models, migration files, or schema definitions]

• Current ORM: [from product.constraints]
• Migration count: [approximate]
• Known schema debt: [any migrations that feel wrong]

Questions for Calibration

1. When you talk about [entity] in conversation, what word do you use? 2. Does [field_name] mean what you think it means? What would you call it? 3. Are [Entity A] and [Entity B] actually the same thing with different lifecycle stages? 4. What's the relationship between [X] and [Y] — ownership, reference, or derivation? 5. Are there domain terms the code doesn't model yet but should? 6. What invariants must always hold? (e.g., "A completed [entity] always has a non-null [field]")

---

Extraction Map

Performance/Quality Brief: [project name]

Product Identity

• What: [from opportunity.bet + product.problem]
• For whom: [from product.persona.description]
• Infrastructure: [from product.constraints.infrastructure]

Current Tolerances

[from product.success_criteria.non_functional]

Current Failure Model

[from product.failure_model]

• Failure classes: [list from failure_model.classes]
• Degraded operation: [from failure_model.degraded_operation]

Observed Behavior

[from /aep-reflect observation, error logs, cost data, or user complaints]

• Performance: [what's slow, what's fast enough]
• Reliability: [what fails, how often, what recovers]
• Resource usage: [what's expensive, what's efficient]

Questions for Calibration

1. Is [X]ms latency acceptable for [action]? What's the threshold where users notice? 2. Should [operation] retry on failure? How many times? With what backoff? 3. Should we cache [resource]? For how long? What's the staleness tolerance? 4. When [external service] is down, should the feature degrade gracefully or block entirely? 5. What's the cost ceiling per [unit]? (e.g., per API call, per user, per month) 6. Are there operations that must be synchronous vs. can be async? 7. What SLAs do we promise (or plan to promise) to users?

---

Extraction Map

Scope/Direction Brief: [project name]

Product Identity

• What: [from opportunity.bet + product.problem]
• For whom: [from product.persona.description]
• Core job: [from product.persona.jtbd]

What Was Built (Current Layer)

[from stories with status: completed in current layer, summarized]

• Layer [N] delivered: [list of capabilities, one per line]
• Layer [N] intended: [from product.layers[N].user_can]

The Gap

[from /aep-reflect observation or user's own assessment]

• Built: [what exists right now]
• Expected: [what the PM/developer imagined]
• Delta: [specific capabilities missing, divergent, or unwanted]

Gap Type Assessment

Is this a scope gap (missing features within the right direction) or a direction gap (features built in the wrong direction)?

• Scope gap indicators: "It does the right things, just not enough of them"
• Direction gap indicators: "It does things I didn't ask for" or "It works but it's not what I meant"

Release Line Assessment

[from product.layers — show upcoming layers and their stories]

• Next layer: Layer [N+1] — [user_can description]
• Stories: [count] ([S/M/L breakdown])
• Estimated effort: [complexity summary]
• Essential for next release: [stories that must ship]
• Nice-to-have: [stories that could defer to a later layer]

Questions for Calibration

1. Looking at what exists, is this 70% right or 30% right? 2. What one thing, if added, would make you say "yes, this is what I meant"? 3. Is the gap in scope (missing features) or direction (wrong features)? 4. Should we adjust the next layer to close this gap, or revise the current layer? 5. Are there completed stories that should be undone or significantly reworked? 6. Looking at upcoming layers, what is the absolute minimum to ship a useful release? Should any stories move between layers? 7. Has the persona or JTBD shifted since /aep-envision?

---

Extraction Map

UX Flow Brief: [project name]

Product Identity

• What: [from opportunity.bet + product.problem]
• For whom: [from product.persona.description]
• Core job: [from product.persona.jtbd]

Current Journey

[from product.activities, ordered left-to-right as a narrative]

1. [Activity name] — [description] 2. [Activity name] — [description] 3. [...]

What Was Built

[from stories with status: completed in current/recent layer, summarized by page/route]

Observed Friction

[from /aep-reflect observation that triggered this calibration]

• Where in the journey: [activity or transition]
• What feels wrong: [description — confusing navigation, dead ends, wrong information density, etc.]
• User expectation vs. reality: [the gap]

Flow Options

Option A: "[Name]"

[Restructured flow — reordered steps, combined/split pages, changed transitions] Tradeoff: [what improves, what gets harder]

Option B: "[Name]"

[Alternative restructured flow] Tradeoff: [what improves, what gets harder]

Questions for Exploration

1. Walk through Option A mentally. Where do you hesitate? 2. Walk through Option B. Where do you hesitate? 3. Is there a step in the current flow that users skip or fight against? 4. What's the one transition that must feel instant/seamless? 5. Should any pages be combined? Should any be split?

---

Extraction Map

Design Brief: [project name]

Product Identity

• What: [from opportunity.bet + product.problem]
• For whom: [from product.persona.description]
• Core job: [from product.persona.jtbd]
• Why now: [from opportunity.why_now]

Pages to Design

1. [Page name] ([route])

• Purpose: [from story description]
• Content blocks: [inferred from story acceptance criteria]
• Key interactions: [from activity definition]

2. [Page name] ([route])

[repeat for each page in the .5 layer]

Design Directions

Direction A: "[Name]"

[Description of the visual direction — mood, color family, layout approach] Reference products: [2-3 existing products as mood board anchors] Strengths: [what this direction does well for the persona] Risks: [where it could miss]

Direction B: "[Name]"

[...]

Direction C: "[Name]"

[...]

Technical Constraints

• Stack: [from product.constraints.required_stack + preferred_stack]
• Current theme: [extracted from globals.css — color space, font, radius, etc.]
• Available components: [list from packages/ui/src/components/]
• Requirements: Responsive, light + dark mode

Deliverable

Explore the directions. Produce designs for all pages listed above. The goal is to establish: color palette, typography, component styling, layout patterns, and overall brand feel for the product.

---

Extraction Map

Calibration Types

Overview of the 7 calibration dimensions supported by /aep-calibrate. Each dimension addresses a specific gap between "works correctly" and "feels right" that agents cannot judge.

---

Heavy Calibrations

External exploration required. Produces standalone YAML artifacts in calibration/ directory. Typically creates .5 alignment layer stories.

visual-design

Brand identity, color palette, typography, layout patterns, component styling. Nearly always needed for user-facing products. The most developed calibration type — includes design brief with 3 spectrum-based directions, vibe design tool workflow (Stitch, Pencil.dev), and globals.css integration.

Artifact: calibration/visual-design.yaml + updated globals.css

ux-flow

User journey, information architecture, page transitions, navigation patterns. Needed when screens exist but the flow between them doesn't feel right — dead ends, wrong information density, confusing navigation, or mismatched transition pacing.

Artifact: calibration/ux-flow.yaml

copy-tone

Brand voice, error messages, button labels, empty states, heading style, technical jargon policy. Needed when the product reads wrong — too formal, too casual, inconsistent terminology, or generic AI-generated text.

Artifact: calibration/copy-tone.yaml

---

Light Calibrations

Conversational. The human reviews current state and makes decisions through structured Q&A. Updates product-context.yaml sections directly. May or may not create .5 layer stories.

api-surface

Endpoint naming, grouping, error contracts, versioning, pagination conventions. Needed when the API works but naming doesn't match domain language, grouping feels arbitrary, or error responses are inconsistent.

Updates: architecture.interfaces in product-context.yaml

data-model

Entity naming, field semantics, relationships, invariants, normalization rules. Needed when the schema is functional but doesn't match the domain language the team actually uses in conversation.

Updates: architecture.domain_model in product-context.yaml

scope-direction

Mid-build intent correction. Needed when what was built doesn't match what the PM/developer imagined — either missing features (scope gap) or wrong features (direction gap). Most common when PM and builder are different people.

Updates: product.goals, product.mvp_boundary, product.layers in product-context.yaml

performance-quality

Latency thresholds, retry behavior, caching strategy, degradation behavior, cost ceilings. Needed when the system works but tolerances haven't been explicitly decided — agents default to generic retry/timeout patterns that may not match actual requirements.

Updates: product.success_criteria.non_functional, product.failure_model in product-context.yaml

API Surface — Capture Questions

Ask these questions one at a time during /aep-calibrate capture for api-surface.

Questions

1. Naming convention: What convention should all endpoints follow? (e.g., kebab-case paths, camelCase body params, snake_case query params) 2. Resource naming: For each resource, what's the canonical name? (e.g., "session" vs "connection", "rule" vs "guardrail" vs "policy") 3. Grouping: Which endpoints should be grouped together? Under what path prefix? 4. Error contract: What should error responses look like? (shape, codes, messages, include stack traces in dev?) 5. Versioning: Path-based (/v1/), header-based, or none for now? 6. Pagination: Cursor-based, offset-based, or not needed? Default page size? 7. Authentication: How should API auth work? (Bearer token, API key, session cookie)

Output

Update architecture.interfaces in product-context.yaml with calibrated naming, grouping, and error contracts.

Copy/Tone — Capture Questions

Ask these questions one at a time during /aep-calibrate capture for copy-tone.

Questions

1. Voice personality: In one sentence, how should this product "sound"? (e.g., "confident but not cocky, technical but accessible") 2. Reference products: Which 2-3 products have a voice you'd want to emulate? Which 1-2 would you avoid? 3. Heading style: How formal should headings be? (e.g., "Dashboard" vs "Your Dashboard" vs "Here's what's happening") 4. Button labels: What convention? (verb + noun: "Create Project", verb only: "Create", noun only: "New Project") 5. Error messages: What pattern? (what went wrong + how to fix it? Just the fix? Apologetic or matter-of-fact?) 6. Empty states: Encouraging ("Get started by..."), instructional ("No items yet. Create one."), or minimal ("No items.")? 7. Technical jargon: Embrace it (audience expects it) or translate it (make accessible)? 8. Glossary terms: List terms that should be used consistently. For each: the canonical term, when to use it, and what to avoid.

Output Artifact

Write to calibration/copy-tone.yaml using schema at references/schemas/copy-tone-schema.yaml.

Data Model — Capture Questions

Ask these questions one at a time during /aep-calibrate capture for data-model.

Questions

1. Entity naming: For each entity, what's the name the team actually uses in conversation? Map code name → human name. 2. Field naming: For fields that feel wrong, what should they be called? (provide old name → new name) 3. Relationships: For each entity pair, what's the relationship? (owns, references, derives from, contains) 4. Lifecycle stages: Are there entities that represent the same concept at different stages? Should they be unified or kept separate? 5. Invariants: What must always be true? (e.g., "A completed X always has a non-null Y", "An X cannot exist without a parent Z") 6. Normalization rules: How should values be compared and stored? (e.g., "identifiers lowercased", "dates always UTC") 7. Missing entities: Are there domain concepts the code doesn't model yet but should?

Output

Update architecture.domain_model in product-context.yaml with calibrated entity names, fields, relationships, and invariants.

Performance/Quality — Capture Questions

Ask these questions one at a time during /aep-calibrate capture for performance-quality.

Questions

1. Latency thresholds: For each key user action, what's the maximum acceptable latency? (e.g., "page load < 2s", "API response < 200ms", "search results < 500ms") 2. Retry policy: For each external dependency, should failures retry? How many times? With what backoff? (exponential, fixed, none) 3. Caching strategy: What should be cached? For how long? What's the staleness tolerance? (e.g., "user profile: 5 min", "dashboard data: 30s", "config: until restart") 4. Degradation behavior: When [service X] is down, should the feature: degrade gracefully (show stale data), show an error, or block entirely? 5. Cost ceilings: What's the acceptable cost per [unit]? (per request, per user/month, total monthly) 6. Sync vs async: Which operations must complete before the user sees a response? Which can happen in the background? 7. SLA commitments: What uptime/performance guarantees do you plan to make? (or "none for MVP")

Output

Update product.success_criteria.non_functional and product.failure_model in product-context.yaml with calibrated thresholds, retry policies, and degradation behaviors.

Scope/Direction — Capture Questions

Ask these questions one at a time during /aep-calibrate capture for scope-direction.

Questions

1. Alignment score: On a scale of 0-100, how close is what was built to what you imagined? What accounts for the gap? 2. Gap type: Is this a scope gap (right direction, missing features) or a direction gap (wrong features or wrong approach)? 3. Keep list: What was built that you want to keep exactly as-is? 4. Change list: What was built that needs to change? For each item: what's wrong and what should it be? 5. Add list: What's missing that would make you say "this is what I meant"? Prioritize: which one thing matters most? 6. Remove list: Was anything built that should be removed entirely? 7. Layer impact: Should these changes happen in the current layer (rework) or the next layer (iterate forward)? 8. Release line cutting: Looking at upcoming layers, what is the absolute minimum to ship a useful release? Which features are essential vs. nice-to-have? Should any stories move between layers to hit a viable release point sooner? 9. Framing check: Has the persona, JTBD, or opportunity hypothesis shifted? (If yes, route to /aep-envision instead)

Output

Update product.goals, product.mvp_boundary, and/or product.layers in product-context.yaml with calibrated scope and direction. Create new stories or modify existing ones as needed.

For release line cutting: update stories[].layer assignments to reflect the new release boundary. Move essential stories earlier and nice-to-have stories later. This implements Jeff Patton's "release line is a pencil line" philosophy — release boundaries shift based on what you learn about scope and direction.

UX Flow — Capture Questions

Ask these questions one at a time during /aep-calibrate capture for ux-flow.

Questions

1. Journey decision: Did you change the activity order? Which activities moved, merged, or split? 2. Page changes: Are there new pages, removed pages, or combined pages compared to what was built? 3. Transition feel: For each major transition, how should it feel? (instant / guided with animation / deliberate with confirmation) 4. Entry points: How does the user arrive at each key page? (direct navigation, redirect after action, deep link) 5. Exit points: Where does each page send the user next? Are there dead ends to eliminate? 6. Information density: For each page, is it too sparse, too dense, or right? 7. Mobile flow: Does the journey change on mobile? Which pages adapt vs. which are desktop-only?

Output Artifact

Write to calibration/ux-flow.yaml using schema at references/schemas/ux-flow-schema.yaml.

Visual Design — Capture Questions

Ask these questions one at a time during /aep-calibrate capture for visual-design.

Questions

1. Direction: Which direction did you choose? (or describe the hybrid) 2. Palette: Primary, secondary, accent, destructive, muted colors (any format — hex, rgb, hsl — the skill converts to oklch for globals.css) 3. Typography: Font family changes? Size scale adjustments? Weight usage patterns? 4. Components: Recurring patterns observed? Card styles, button variants, spacing rhythm? 5. Layout: Max-width, grid vs flex, sidebar vs top-nav, content density? 6. Brand signals: What visual cues communicate "this is [product name]"? 7. Reference files: Did you save HTML/CSS/screenshots to docs/design-references/? List them.

Output Artifact

Write to calibration/visual-design.yaml using schema at references/schemas/visual-design-schema.yaml. Also update globals.css with captured palette (convert to oklch).

Design Brief: [project name]

Product Identity

• What: [from opportunity.bet + product.problem]
• For whom: [from product.persona.description]
• Core job: [from product.persona.jtbd]
• Why now: [from opportunity.why_now]

Pages to Design

1. [Page name] ([route])

• Purpose: [from story description]
• Content blocks: [inferred from story acceptance criteria]
• Key interactions: [from activity definition]

2. [Page name] ([route])

[repeat for each page in the .5 layer]

Design Directions

Direction A: "[Name]"

[Description of the visual direction — mood, color family, layout approach] Reference products: [2-3 existing products as mood board anchors] Strengths: [what this direction does well for the persona] Risks: [where it could miss]

Direction B: "[Name]"

[...]

Direction C: "[Name]"

[...]

Technical Constraints

• Stack: [from product.constraints.required_stack + preferred_stack]
• Current theme: [extracted from globals.css — color space, font, radius, etc.]
• Available components: [list from packages/ui/src/components/]
• Requirements: Responsive, light + dark mode

Deliverable

Explore the directions. Produce designs for all pages listed above. The goal is to establish: color palette, typography, component styling, layout patterns, and overall brand feel for the product.

---

Extraction Map

Vibe Design Tool Guide

Tools for human-driven design exploration during /aep-calibrate Phase 1 → Phase 2 interlude.

---

Google Stitch

• What: AI design tool from Google Labs, powered by Gemini
• Input: Text prompts (natural language or structured markdown), hand-drawn sketches, wireframes, screenshots, voice
• Output: Interactive UI mockups, Figma files, HTML/CSS code
• Export: Direct to Figma or HTML/CSS
• Cost: Free
• Best for: Rapid exploration of multiple directions, visual brainstorming
• Workflow: Paste design brief → generate designs → iterate via conversation → export HTML/CSS or Figma for chosen direction

Pencil.dev

• What: AI design tool that runs inside VS Code / Cursor
• Input: Text prompts, Figma imports, manual canvas editing
• Output: .pen JSON design files (stored in /aep-design folder), pixel-perfect React/HTML/CSS code
• Export: React code, HTML/CSS, committed directly to Git
• Cost: Free in early access (requires Claude Code subscription)
• Best for: Design-to-code integration, Git-native design files, IDE workflow
• Workflow: Open Pencil in IDE → paste brief → design on canvas → .pen files saved to repo → Claude Code generates code from specs

Other Tools

• Galileo AI (now part of Stitch) — text-to-UI, Figma export
• Uizard — fast browser-based prototyping, interactive prototypes
• Banani — generates style variations (minimalist, enterprise, playful, sleek)
• Framer AI — text-to-website, complete layouts with interactions

---

What to Save

After exploring, save reference files to docs/design-references/:

docs/design-references/
├── landing.html          <- HTML/CSS from Stitch (or screenshot)
├── auth.html             <- HTML/CSS from Stitch
├── dashboard.html        <- HTML/CSS from Stitch
├── landing.png           <- screenshot alternative
└── notes.md              <- human notes on what they liked and why

These files are committed to Git and referenced in calibration/visual-design.yaml. Agents read them as visual guidance — they translate the reference into the project's component system, not copy code verbatim.

Format Note

A single structured markdown design brief works for both Stitch and Pencil.dev. No tool-specific rewrites needed — both tools handle structured markdown well. Copy the full brief or relevant sections into the tool.