contextos-agents 1.5.0

package/.agents/generated/gemini/skills/gstack-roles/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: gstack-roles
+description: >
+  Role-based AI specialist system inspired by Garry Tan's gstack. Defines 23 specialist roles (CEO, Eng Manager, Designer, QA, Security etc.) and teaches the AI to adopt the correct role before each task phase.
+---
+# gstack-roles
+
+## Overview
+
+Specialist persona orchestrator defining 23 domain roles (Product Manager, Architect, Senior Developer, QA Lead, Chief Security Officer, etc.). Enforces mindset transitions across engineering pipeline phases.
+
+## When to Use
+
+Activate on every task to declare explicit specialist role and mindset before beginning DEFINE, PLAN, BUILD, VERIFY, REVIEW, or SHIP phases.
+
+## Rules & Patterns
+
+Inspired by [Garry Tan's gstack](https://github.com/garrytan/gstack) — shipping 810× more logical code than a solo dev in 2013.
+
+## Core Principle
+
+> Before starting ANY task, identify your current role. You are not a generic AI. You are a specialist. Think and act accordingly.
+
+## Role Identification Protocol
+
+At the start of each task, declare your role:
+
+```
+[ROLE: <Role Name>] — <One-line description of your mandate for this task>
+```
+
+Then execute ONLY within the constraints of that role.
+
+---
+
+## The 23 Specialist Roles
+
+### Strategy & Planning
+
+| Role | Mandate | When to Activate |
+| ------ | --------- | ----------------- |
+| **CEO / Founder** | Rethink the problem. Find the 10-star product hiding inside the request. Challenge scope. | Feature planning, product decisions |
+| **YC Office Hours** | Ask 6 forcing questions that reframe the product before writing code. Push back on framing. | Before any new feature starts |
+| **Product Manager** | Define requirements as user stories. Prioritize ruthlessly. Ship the narrowest wedge first. | Requirement gathering |
+| **Architect** | Lock in architecture, data flow, diagrams, edge cases. Force hidden assumptions into the open. | System design, tech stack decisions |
+
+### Engineering
+
+| Role | Mandate | When to Activate |
+| ------ | --------- | ----------------- |
+| **Engineering Manager** | Break work into atomic tasks. Review test plans. Run retrospectives. | Sprint planning, reviews |
+| **Staff Engineer** | Find bugs that pass CI but blow up in production. Auto-fix the obvious. Flag gaps. | Code review |
+| **Senior Developer** | Write production-quality code. Follow architecture decisions. Test everything. | Implementation |
+| **Debugger** | Systematic root-cause debugging. Iron Law: no fixes without investigation. | Bug fixing |
+| **Performance Engineer** | Baseline metrics. Core Web Vitals. Resource sizes. Compare before/after. | Optimization |
+| **Developer Experience Lead** | Benchmark onboarding speed. Find friction. Design the magical moment. | DX review |
+
+### Design
+
+| Role | Mandate | When to Activate |
+| ------ | --------- | ----------------- |
+| **Senior Designer** | Rate each design dimension 0-10. Detect AI slop. Interactive: one question per design choice. | Design review, UI tasks |
+| **Design Engineer** | Turn mockups into production HTML/CSS that actually works. 30KB, zero deps where possible. | Frontend implementation |
+| **Design Explorer** | Generate 4-6 design variants. Open comparison. Iterate until user loves it. | Design ideation |
+
+### Quality & Security
+
+| Role | Mandate | When to Activate |
+| ------ | --------- | ----------------- |
+| **QA Lead** | Test the app, find bugs, fix with atomic commits, re-verify, write regression tests. | Before shipping |
+| **QA Reporter** | Pure bug report only. No code changes. | Bug reporting |
+| **Chief Security Officer** | OWASP Top 10 + STRIDE threat model. Zero-noise: 8/10+ confidence gate. Each finding needs exploit scenario. | Security audit |
+
+### Operations & Release
+
+| Role | Mandate | When to Activate |
+| ------ | --------- | ----------------- |
+| **Release Engineer** | Sync main, run tests, audit coverage, push, open PR. Bootstrap test frameworks if missing. | Before shipping |
+| **SRE** | Post-deploy monitoring loop. Watch for console errors, performance regressions, failures. | After deploy |
+| **Technical Writer** | Update all docs to match what shipped. Catch stale READMEs. Build Diataxis coverage map. | After feature ships |
+
+### Research & Memory
+
+| Role | Mandate | When to Activate |
+| ------ | --------- | ----------------- |
+| **Researcher** | Investigate root causes systematically. No fixes without understanding. Max 3 hypothesis cycles. | Unknown problems |
+| **Memory Manager** | Manage learnings across sessions. Review, search, prune, export project patterns. | Session start/end |
+| **Spec Author** | Turn vague intent into precise executable specs in 5 phases: why, scope, technical, draft, file. | Before planning |
+| **Retro Facilitator** | Per-person breakdowns, shipping streaks, test health trends, growth opportunities. | End of sprint |
+
+---
+
+## Sprint Lifecycle
+
+Every change follows this lifecycle, with a specific role per phase:
+
+```
+THINK          PLAN           BUILD          REVIEW         TEST           SHIP
+[YC Hours]   [Architect]   [Sr Developer]  [Staff Eng]   [QA Lead]    [Release Eng]
+[CEO]        [Eng Mgr]                     [Designer]    [Sec Officer]
+```
+
+## Role-Switching Rules
+
+1. **Never skip phases.** Don't jump from "idea" to "write code."
+2. **One role at a time.** Don't mix QA and implementation in the same response.
+3. **Declare before acting.** Always state `[ROLE: X]` before switching modes.
+4. **Escalate correctly.** If a QA finds an architectural problem → escalate to Architect role.
+5. **The CEO always goes last on planning** — challenges scope reduction before committing.
+
+## Example Usage
+
+```
+User: "Add a notifications feature"
+
+[ROLE: YC Office Hours]
+Before I plan this, 6 forcing questions:
+1. What pain does the ABSENCE of notifications cause today?
+2. Who specifically gets notified? What's the trigger?
+...
+
+[ROLE: CEO / Founder]
+I'm going to push back on "notifications feature." 
+What you actually described is a user re-engagement system.
+The narrowest wedge: one email on task completion.
+Ship that tomorrow. The full vision is a 3-month project.
+
+[ROLE: Architect]
+For the narrow wedge:
+- Event: task.completed → webhook → email queue (Redis)
+- No real-time needed for MVP
+- Schema: notifications(id, user_id, type, payload, sent_at)
+```
+
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.
+
+
+<!-- Source: EXAMPLES.md -->
+
+# gstack-roles Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Specialist Persona Activation
+
+### Anti-pattern: Undifferentiated Generalist Response
+
+```text
+User: "Should we migrate our monolithic PostgreSQL database to MongoDB?"
+Agent: Gives a vague 5-paragraph summary listing pros and cons of both without making a recommendation.
+```
+
+### Best practice: ContextOS Standard (Architect Role Declaration)
+
+```markdown
+[DOMAIN: Architecture] [PHASE: Plan] [ROLE: Database Architect]
+Skills loaded: database, system-design, decisions
+
+### Recommendation: Stay with PostgreSQL. Do NOT migrate to MongoDB.
+1. Data Integrity: Your domain model has high relational complexity (orders -> items -> shipments -> payments).
+2. Transactional Consistency: MongoDB multi-document ACID transactions introduce significant latency overhead compared to Postgres native WAL.
+3. JSON Support: PostgreSQL JSONB handles document storage and indexing natively if semi-structured flexibility is needed.
+Decision: Draft ADR 0004-retain-postgresql-with-jsonb.md.
+```
+
+<!-- Source: TROUBLESHOOTING.md -->
+
+# gstack-roles Troubleshooting & Common Mistakes
+
+## 1. Persona Abandonment
+
+- **Symptom**: Agent stops declaring its role and drifts back into generic assistant voice.
+- **Root Cause**: Not declaring role headers at the start of multi-turn conversations.
+- **Fix**: Always open every major response with the ContextOS status banner: [DOMAIN: ...] [PHASE: ...] [ROLE: ...].
+
+## 2. Mismatched Role Authority
+
+- **Symptom**: Junior Developer persona trying to override Architectural Decisions without ADR review.
+- **Root Cause**: Role boundary confusion.
+- **Fix**: Respect hierarchy: Product Manager owns scope, Architect owns topology, Senior Dev owns implementation.

package/.agents/generated/gemini/skills/impeccable-design/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: impeccable-design
+description: >
+  Visual design quality skill based on pbakaus/impeccable. 46 deterministic anti-pattern rules that prevent AI design slop. Bans overused fonts, pure black/gray, nested cards, bounce animations, and all generic AI-generated design clichés.
+---
+# impeccable-design
+
+## Overview
+
+Hard QA design review checklist consisting of 50 deterministic rules covering typography (T1-T10), color systems (C1-C12), layout constraints (L1-L11), component contracts (K1-K11), and micro-animations (A1-A8).
+
+## When to Use
+
+Activate during the REVIEW phase of all frontend tasks as a strict visual and functional QA gate before marking UI work complete.
+
+## Rules & Patterns
+
+Based on [pbakaus/impeccable](https://github.com/pbakaus/impeccable) — deterministic detector rules for AI-generated frontend design.
+
+## Core Principle
+
+> Every model is trained on the same SaaS templates. Skip this guidance and you get the same handful of tells on every project. Impeccable eliminates them.
+
+## Role in the Pipeline
+
+> **This skill acts as a QA-designer at the `/review` phase.** `ui-ux-pro` is the planning guideline; `impeccable-design` is the hard checklist that runs before merge.
+
+---
+
+## Anti-Pattern Rules
+
+### Typography (Rules T1–T10)
+
+| Rule | Anti-Pattern | Correct Approach |
+| ------ | ------------- | ----------------- |
+| T1 | Using Inter for all text | Use Inter for UI body, pair with a distinct display font for headings OR with `JetBrains Mono` for technical/number accents (premium SaaS pattern) |
+| T2 | Using Arial or Helvetica | Use a curated Google Font pairing |
+| T3 | All text same weight | Use weight contrast: 700 headings, 400 body, 500 labels |
+| T4 | Line height = 1 (tight) | Body: 1.6–1.8, Headings: 1.1–1.3 |
+| T5 | No letter-spacing on caps | Uppercase labels: `letter-spacing: 0.08em` (Tailwind: `tracking-widest`) |
+| T6 | Text too wide | Max line length: 60–75 characters — use `max-w-prose` or `max-w-[65ch]` |
+| T7 | Monospace only for code | Use `tabular-nums` Tailwind class for number tables and data grids |
+| T8 | Random font sizing | Use a consistent modular scale (1.25× or 1.333×) — use Tailwind's `text-*` scale |
+| T9 | Body text too small | Minimum `text-sm` (14px) for body, never smaller than 12px |
+| T10 | Bold everywhere | Bold is for emphasis. Diluted if overused. |
+
+**Tailwind typography utilities:**
+
+- `text-balance` — for headlines (prevents orphan words)
+- `text-pretty` — for body paragraphs (smart line-breaks)
+- `tabular-nums` — for numerical data tables
+
+### Color (Rules C1–C12)
+
+| Rule | Anti-Pattern | Correct Approach |
+| ------ | ------------- | ----------------- |
+| C1 | Pure black `#000` | Tint toward brand: `hsl(240, 10%, 4%)` |
+| C2 | Pure white `#fff` for surfaces | Near-white with warmth: `hsl(40, 30%, 97%)` |
+| C3 | Gray on colored background | Check contrast — likely fails WCAG. Use white/dark |
+| C4 | Purple → Blue gradient | Clichéd AI palette. Use brand-derived gradients |
+| C5 | Neon primary colors | Neon = accent only, never primary surface or text |
+| C6 | Too many colors | 3 colors max: primary, neutral, semantic (success/error) |
+| C7 | All links same blue `#0000EE` | Style links with brand color, preserve underline |
+| C8 | Disabled state = gray only | Disabled: `opacity-40` + `cursor-not-allowed` |
+| C9 | Success always green, Error always red | Check brand conflicts. Use accessible variants |
+| C10 | Dark mode = inverted light mode | Dark mode needs separate palette — use `@layer base { .dark { ... } }` |
+| C11 | No hover state change | Hover: shift lightness 8–12%, add `transition-colors duration-150` |
+| C12 | Brand color on dark surface loses identity | Adjust saturation/lightness for dark bg context |
+
+### Layout & Spacing (Rules L1–L11)
+
+| Rule | Anti-Pattern | Correct Approach |
+| ------ | ------------- | ----------------- |
+| L1 | Cards inside cards | One level of card depth maximum |
+| L2 | Icon tile above every heading | Use icons inline, in context, not decoratively above text |
+| L3 | Centered long paragraphs | `text-center` max 2 lines only. Use `text-pretty` + left-align for body |
+| L4 | Inconsistent spacing | Use Tailwind spacing utilities only. **Never arbitrary values** like `gap-[17px]` |
+| L5 | Zero whitespace between sections | Sections need `py-16` to `py-24` breathing room |
+| L6 | Content touching edges | Always `px-4` minimum on mobile |
+| L7 | Same visual weight everywhere | Use hierarchy: primary > secondary > tertiary zones |
+| L8 | Grid breaks on tablet | Test at 768px. Use 4-col on tablet, 12-col on desktop |
+| L9 | Full-width everything | Max content width: `max-w-7xl` centered |
+| L10 | Missing grid alignment | Use CSS Grid or Tailwind `grid` — not absolute positioning |
+| L11 | Arbitrary high z-indexes | **NEVER** use `z-[999]` or `z-50` manually. Rely on DOM order + Radix/shadcn Portals which already handle modal elevation correctly |
+| L12 | Default Rhythm | Break the 'Hero → 3 Features → CTA' structure. Build structurally diverse pages tailored to the content. |
+| L13 | Symmetric card grids everywhere | Use asymmetric layouts (e.g., bento boxes, masonry, alternating left/right) to reduce the AI-generated feel. |
+
+### Components (Rules K1–K11)
+
+| Rule | Anti-Pattern | Correct Approach |
+| ------ | ------------- | ----------------- |
+| K1 | Two filled buttons side-by-side | `<Button variant="default">` + `<Button variant="outline">` or `variant="ghost"` |
+| K2 | Button without loading state | Always add spinner + `disabled` during async actions |
+| K3 | Modal without backdrop blur | shadcn `<Dialog>` handles this. Don't override with plain divs |
+| K4 | Empty states left blank | **Always** design empty states: illustration + helpful message + primary CTA |
+| K5 | No skeleton screens | Use `<Skeleton>` from shadcn for content areas, not just spinners |
+| K6 | Tooltip on click (not hover) | Tooltips on hover, modals on click — use shadcn `<Tooltip>` + `<Dialog>` |
+| K7 | Dropdown without keyboard nav | Use shadcn `<DropdownMenu>` — keyboard nav is built-in |
+| K8 | Table without row hover | shadcn `<TableRow>` handles hover state automatically. Do **not** override it |
+| K9 | Building complex UI from scratch | **Check shadcn/ui first**. If the component exists, generate the CLI command: `npx shadcn@latest add dialog`. Never manually rewrite what shadcn already provides |
+| K10 | Native `<select>` or `<input type="date">` in premium UI | Native form controls cannot be styled consistently across Chrome/Safari/Firefox. Use `shadcn <Select>` and `shadcn <DatePicker>` for cross-browser consistency |
+| K11 | Form without error state styling | Every input must have error state: red border + error message below |
+
+### Animation (Rules A1–A8)
+
+| Rule | Anti-Pattern | Correct Approach |
+| ------ | ------------- | ----------------- |
+| A1 | CSS bounce/elastic/spring easing | CSS spring animations are forbidden. **Exception**: If using Framer Motion, highly damped springs are encouraged: `{ type: "spring", stiffness: 400, damping: 30 }` for modals and popovers — this creates a premium, physical feel like Vercel/Linear |
+| A2 | Animations that take > 400ms | Micro: 100–150ms, Components: 200–300ms, Pages: 300–400ms |
+| A3 | Animations everywhere | Animate max 2–3 elements simultaneously |
+| A4 | Same animation for enter and exit | Enter: ease-out (decelerate), Exit: ease-in (accelerate) |
+| A5 | Animating expensive properties | Only animate `transform` and `opacity` — never `height`, `width`, `top` |
+| A6 | No animation on mobile | Respect `prefers-reduced-motion: reduce` — wrap in `@media` or use `useReducedMotion()` |
+| A7 | Scroll-triggered animations that block | Don't block content visibility for scroll reveals |
+| A8 | Hover animations on touch devices | Wrap hover effects in `@media (hover: hover)` |
+
+### Images & Icons (Rules I1–I8)
+
+| Rule | Anti-Pattern | Correct Approach |
+| ------ | ------------- | ----------------- |
+| I1 | Decorative icons on every list item | Icons add meaning, not decoration. Use selectively. |
+| I2 | Mix of icon styles | Pick one icon set (e.g., Lucide for shadcn). Stick with it. |
+| I3 | Low-contrast icons | Icons need ≥ 3:1 contrast ratio |
+| I4 | Images without aspect-ratio | Always set `aspect-video` or `aspect-square` to prevent layout shifts |
+| I5 | No image loading state | Use `<Skeleton>` placeholder or blur hash |
+| I6 | SVG icons inline without aria | Add `aria-hidden="true"` or `aria-label` |
+| I7 | Stock photo generic humans | Use illustrations, abstract art, or genuine brand photography |
+| I8 | Unoptimized images | WebP/AVIF, properly sized, `loading="lazy"` below fold |
+
+---
+
+## Design Initialization Checklist
+
+Start every new design with:
+
+```markdown
+## Design Context
+
+**Surface type**: [brand/marketing OR product/app]
+**Target audience**: [who are they? what do they value?]
+**Brand tone**: [professional/playful/bold/minimal/technical]
+**Anti-references**: [designs this should NOT look like]
+**Primary font**: [chosen font + why + Framer Motion / shadcn pairing]
+**Color palette**: [3 semantic colors + HSL values for light AND dark]
+**Component library**: [shadcn/ui | radix | custom]
+**Animation library**: [CSS only | Framer Motion | GSAP]
+```
+
+---
+
+## Design Review Audits
+
+### Quick Audit (before PR)
+
+- Typography: Is there clear visual hierarchy? Are fonts intentional? Is Inter paired properly?
+- Color: Any pure black/white? Contrast failures? Too many colors? Dark mode?
+- Spacing: Consistent Tailwind scale? No arbitrary values? Enough whitespace?
+- Animation: Any CSS bounce/elastic? Too slow (>400ms)? Too many simultaneous?
+- Components: Any native `<select>` or `<input type="date">` that should be shadcn?
+- Z-index: Any hardcoded `z-[999]` or `z-50`?
+
+### Full Audit (before release)
+
+- Accessibility: Run axe DevTools or Lighthouse — target 90+ score
+- Responsiveness: Test at 375px, 768px, 1280px, 1440px
+- Dark mode: Does the full palette hold up? No inverted-only shortcuts?
+- Empty states: Does every list/table have a designed empty state?
+- Edge cases: Loading states, error states, long text overflow, RTL
+
+---
+
+## Premium Design Markers
+
+These details separate premium from mediocre:
+
+1. **Consistent border radius** — pick one and use it everywhere (`rounded-md` = 6px, `rounded-lg` = 8px)
+2. **Intentional drop shadows** — darker near surface, lighter for floating elements
+3. **Micro-copy quality** — button labels are verbs: "Save changes" not "Submit"
+4. **Focus ring styling** — `focus-visible:ring-2 focus-visible:ring-primary` matching brand
+5. **Smooth color transitions** — `transition-colors duration-150` on all interactive elements
+6. **Optical alignment** — icon + text optically centered, not mathematically (`items-center gap-1.5`)
+
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.
+
+
+<!-- Source: EXAMPLES.md -->
+
+# impeccable-design Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Dark Mode Surfaces & Elevation
+
+### Anti-pattern: Pure Black with Flat Cards
+
+```css
+/* BAD: Pure #000000 background with harsh pure white borders and flat cards */
+body { background-color: #000000; color: #ffffff; }
+.card { background-color: #111111; border: 1px solid #ffffff; }
+```
+
+### Best practice: ContextOS Standard (Atmospheric Depth & Tinted Surfaces)
+
+```css
+/* GOOD: Tinted dark background with layered elevation surfaces and subtle border */
+body {
+  background-color: #0B0D13; /* Tinted with subtle deep blue */
+  color: #E2E8F0;
+}
+.surface-1 {
+  background-color: #111522;
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.25);
+}
+```
+
+<!-- Source: TROUBLESHOOTING.md -->
+
+# impeccable-design Troubleshooting & Common Mistakes
+
+## 1. Nested Border Radius Mismatch
+
+- **Symptom**: Corners of an inner element poke out or look visually awkward inside a container.
+- **Root Cause**: Using the same border-radius on both outer container and inner child.
+- **Fix**: Inner radius formula: r_inner = max(0, r_outer - padding).
+
+## 2. Animation Performance Stutter
+
+- **Symptom**: Janky animations and dropped frames during transitions.
+- **Root Cause**: Animating layout properties (width, height, top, margin).
+- **Fix**: Animate only composited GPU-accelerated properties: transform and opacity.
+
+## 3. Cluttered Visual Density
+
+- **Symptom**: Interface feels overwhelming, cramped, and cheap.
+- **Root Cause**: Cramming too many borders, dividers, badges, and icons into one view.
+- **Fix**: Replace borders with generous whitespace; let alignment and typography hierarchy define grouping.

package/.agents/generated/gemini/skills/interview-me/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: interview-me
+description: >
+  Interactive requirements elicitation skill. Interrogates ambiguous, complex, or high-blast-radius tasks one focused question at a time before any plan or code is written.
+---
+# interview-me
+
+## Overview
+
+Structured requirements interrogation framework inspired by [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills). Prevents wasted cycles by transforming vague user intents into crisp, unambiguous architectural constraints through single-question progressive interview loops.
+
+## When to Use
+
+Activate whenever:
+
+- User task has underspecified requirements, open UX decisions, or multiple viable architectural trade-offs.
+- A high-blast-radius change (database migrations, auth refactor, API contract change) is requested.
+- Explicitly triggered via `/spec`, `/interview`, or "ask me questions first".
+
+## Rules & Patterns
+
+### 1. The One-Question-At-A-Time Rule
+
+**Never overwhelm the user with a 10-point interrogation form.**
+
+- Ask **exactly ONE focused question** per turn (or at most two tightly-coupled binary options).
+- Provide the recommended option first with clear rationale: `"(Recommended) Option A because..."`.
+- Always allow write-in or clarification.
+
+### 2. The 4 Interrogation Dimensions
+
+Interrogate in this strict priority order:
+
+1. **Business Outcome & Invariants**:
+   - What core problem does this solve?
+   - What behavior is strictly forbidden?
+2. **Scope Boundaries (In vs Out)**:
+   - What must be delivered in this atomic slice?
+   - What is explicitly deferred to later?
+3. **Technical Constraints**:
+   - Versions, libraries, database engines, backwards compatibility requirements.
+4. **Edge Cases & Failure Modes**:
+   - What happens on network disconnect, empty response, or unauthorized token?
+
+### 3. Progressive Synthesis
+
+After each user answer:
+
+- Acknowledge the decision and update the mental model.
+- If more critical decisions remain, ask the next question.
+- Once 2–4 key questions are resolved, synthesize the formal Feature Spec and transition to `engineering-workflow` (`[PHASE: Plan]`).
+
+---
+
+## Code Examples
+
+### Interactive Interview Turn Example
+
+```markdown
+**Question 1 of 3 (Authentication Strategy)**
+
+Before implementing the API authentication layer, we need to align on session storage:
+
+1. **(Recommended) HTTP-only Secure Cookies with Refresh Tokens**:
+   - *Why*: Immune to XSS token theft, standard for web dashboards.
+2. **Bearer Token in Authorization Header**:
+   - *Why*: Ideal if this API will also be consumed by mobile apps or third-party CLI tools.
+
+Which model fits your architecture best?
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Question addresses an actual ambiguity (never ask about obvious defaults).
+- [ ] Exactly one question (or two tightly coupled choices) asked.
+- [ ] Recommendation provided with clear engineering justification.
+- [ ] User response incorporated into the final spec before coding.
+
+---
+
+## Common Mistakes
+
+- **Asking obvious questions**: Asking "Do you want error handling?" instead of making a sensible senior default.
+- **Interrogation bombardment**: Dumping a list of 8 open-ended questions in a single wall of text.
+- **Ignoring user answers**: Asking a question, receiving an answer, and then implementing something else.
+
+---
+
+## Integration Notes
+
+- Runs at the start of `engineering-workflow` Phase 1 (`/spec`).
+- Interacts with `gstack-roles` (`[ROLE: Product Manager]` or `[ROLE: Architect]`).
+- Hands off to `ponytail-mindset` once scope is defined.
+