@agentikos/omega-os 0.2.0 → 0.19.5

package/omega/Agentik_Engine/omega_engine/genesis/phases.py

@@ -0,0 +1,950 @@
+"""Phase content generators — produce the docs for each Genesis phase.
+
+Each phase is a pure function ``(state) -> list[FileSpec]`` where
+:class:`FileSpec` is a ``(path, content)`` pair anchored to the project
+root. The orchestrator persists every spec to disk inside the per-project
+``docs/`` tree, then flips the state machine.
+
+The content of each file is a **structured template** the orchestrator
+fills with what it knows (slug, name, intent, stack). The template
+intentionally LEAVES sections marked ``<!-- TODO: ... -->`` for the
+worker agent to fill — Genesis writes the skeleton; the workers (Layer 5)
+do the deep research.
+
+Why a structured template instead of "ask the LLM to write it"
+--------------------------------------------------------------
+
+The pre-v0.18 ``/prd`` skill called the LLM to author every file from
+scratch. Three problems:
+
+  1. **Non-deterministic file shape.** Two re-runs produced different
+     section layouts → downstream skills couldn't grep reliably.
+  2. **No per-section worker dispatch.** When a section was bad, you had
+     to regen the whole file.
+  3. **No depends_on graph.** Features came out in random order.
+
+This module solves all three: the file STRUCTURE is deterministic Python
+code; only the per-section CONTENT is filled by workers. Each worker can
+target ``31-PRD.md#section-3`` instead of "rewrite the PRD".
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from omega_engine.genesis.state import GenesisState
+
+
+@dataclass
+class FileSpec:
+    """One file to write under the project's docs tree."""
+
+    rel_path: str       # relative to project_root, e.g. "docs/00-VISION.md"
+    content: str        # full file body (markdown)
+
+
+# ---------------------------------------------------------------------------
+# Section helpers — every phase uses the same skeleton style
+# ---------------------------------------------------------------------------
+
+
+def _frontmatter(state: GenesisState, *, kind: str) -> str:
+    """YAML frontmatter on every doc — machine-readable provenance."""
+    return (
+        f"---\n"
+        f"slug: {state.slug}\n"
+        f"name: {state.name}\n"
+        f"kind: {kind}\n"
+        f"phase: {state.phase}\n"
+        f"stack:\n"
+        f"  type: {state.stack.type}\n"
+        f"  frontend: {state.stack.frontend}\n"
+        f"  backend: {state.stack.backend}\n"
+        f"  ui_kit: {state.stack.ui_kit}\n"
+        f"generated_at: {state.updated_at}\n"
+        f"---\n\n"
+    )
+
+
+def _todo(label: str) -> str:
+    return f"<!-- TODO: {label} -->"
+
+
+# ---------------------------------------------------------------------------
+# PHASE 1 — Vision
+# ---------------------------------------------------------------------------
+
+
+def phase_vision(state: GenesisState) -> list[FileSpec]:
+    """One file: docs/00-VISION.md — product identity + emotional positioning."""
+    body = _frontmatter(state, kind="vision") + f"""# Vision — {state.name}
+
+> **One-line intent (operator brief):**
+> {state.intent or _todo("operator did not provide an intent — capture it during the vision interview")}
+
+## Why this product exists
+
+{_todo("3-5 sentences. What void does this fill? Who hurts today, and how?")}
+
+## The user we're building for
+
+- **Primary persona:**  {_todo("1-line role + 1-line stage of life/work")}
+- **Pain we end:**      {_todo("the concrete pain, in their words")}
+- **Win we deliver:**   {_todo("the concrete win, measurable in minutes / dollars / confidence")}
+
+## The 1-second pitch (5-year-old version)
+
+{_todo("If you told a 5-year-old what this product does in one sentence, what would you say?")}
+
+## What this product is NOT
+
+- {_todo("the most likely confusion — and why we're not that")}
+- {_todo("the adjacent market we will not serve")}
+
+## Internal compass — 3 principles we will not betray
+
+1. {_todo("principle 1 — concrete, verifiable in product decisions")}
+2. {_todo("principle 2 — concrete, verifiable in product decisions")}
+3. {_todo("principle 3 — concrete, verifiable in product decisions")}
+
+## Emotional positioning
+
+| Adjective | Why it matters here |
+|---|---|
+| {_todo("adjective 1")} | {_todo("why")} |
+| {_todo("adjective 2")} | {_todo("why")} |
+| {_todo("adjective 3")} | {_todo("why")} |
+
+## Success — what 'working' looks like 12 months from launch
+
+- **User win:**    {_todo("a specific user outcome we'd celebrate")}
+- **Business win:** {_todo("a specific revenue / retention / activation number")}
+- **Team win:**    {_todo("the team's pride moment, what they'd brag about")}
+
+---
+
+**Next:** ``omega genesis run {state.slug}`` to advance to the **market** phase.
+"""
+    return [FileSpec("docs/00-VISION.md", body)]
+
+
+# ---------------------------------------------------------------------------
+# PHASE 2 — Market (5 files)
+# ---------------------------------------------------------------------------
+
+
+def phase_market(state: GenesisState) -> list[FileSpec]:
+    fm = _frontmatter(state, kind="market-research")
+    return [
+        FileSpec("docs/10-market/11-COMPETITORS.md", fm + f"""# Competitors — {state.name}
+
+> Direct, indirect, and adjacent players. We name them so we can decide
+> how we differ — not to copy them.
+
+## Direct competitors
+
+| Player | URL | Stage | Pricing | Where they win | Where we beat them |
+|---|---|---|---|---|---|
+| {_todo("Player A")} | {_todo("url")} | {_todo("seed/A/B/scale")} | {_todo("from $X")} | {_todo("their strength")} | {_todo("our advantage")} |
+| {_todo("Player B")} | {_todo("url")} | {_todo("stage")} | {_todo("pricing")} | {_todo("strength")} | {_todo("advantage")} |
+
+## Indirect / adjacent
+
+- {_todo("adjacent player — what they solve that overlaps ~30%")}
+
+## Open positioning gap (the wedge)
+
+{_todo("one paragraph: the specific job-to-be-done nobody owns yet")}
+
+## Switching cost — how a user leaves a competitor for us
+
+{_todo("the concrete migration path: what they export, what we import, what we promise during onboarding")}
+"""),
+
+        FileSpec("docs/10-market/12-ICP.md", fm + f"""# Ideal Customer Profile — {state.name}
+
+## ICP — Tier 1 (the bullseye)
+
+- **Role / Title:**       {_todo("e.g. 'Head of Growth at a 50-200 ARR B2B SaaS'")}
+- **Company stage:**      {_todo("series A-B, profitable, 50-200 employees")}
+- **Geography:**          {_todo("EU / US / global / French-speaking-only")}
+- **Trigger event:**      {_todo("the moment they suddenly need this — funding round, churn spike, hiring freeze")}
+- **Where they hang out:** {_todo("Twitter circles, Slack groups, LinkedIn niches")}
+- **Budget signal:**      {_todo("they already pay $X/mo for Y product")}
+
+## ICP — Tier 2 (the spillover, lower ACV but volume)
+
+{_todo("same shape, secondary segment")}
+
+## Anti-ICP (we'd refuse this customer)
+
+- {_todo("anti-pattern 1 — why we'd say no even at full price")}
+
+## Job-to-be-done
+
+> When **{_todo("situation")}**, I want to **{_todo("verb + outcome")}**, so I can **{_todo("higher-level goal")}**.
+"""),
+
+        FileSpec("docs/10-market/13-PRICING-STRATEGY.md", fm + f"""# Pricing strategy — {state.name}
+
+## Pricing axis (what we charge for)
+
+{_todo("seats / events / API calls / outcomes / tier features — pick ONE primary axis and one secondary at most")}
+
+## Tiers (initial)
+
+| Tier | Price | Limits | Who | Why we drew the line here |
+|---|---|---|---|---|
+| Free | $0/mo | {_todo("limits")} | {_todo("who")} | {_todo("rationale")} |
+| Pro  | ${_todo("X")} /mo | {_todo("limits")} | {_todo("who")} | {_todo("rationale")} |
+| Team | ${_todo("X")} /mo | {_todo("limits")} | {_todo("who")} | {_todo("rationale")} |
+| Enterprise | custom | unlimited | {_todo("who")} | {_todo("rationale")} |
+
+## Willingness to pay signals (from competitor + ICP research)
+
+- {_todo("they currently pay $X for Y — anchor")}
+- {_todo("survey / interview / public pricing reference")}
+
+## Stripe Connect configuration
+
+- **Mode:** {_todo("destination charges | direct charges | subscriptions")}
+- **Currency:** {_todo("USD / EUR / multi")}
+- **Tax handling:** {_todo("Stripe Tax / Avalara / manual")}
+- **Webhooks we MUST handle:** ``checkout.session.completed``, ``invoice.payment_failed``, ``customer.subscription.*``
+
+## Pricing experiments we will run
+
+1. {_todo("test 1 — what we change, what we measure")}
+2. {_todo("test 2")}
+"""),
+
+        FileSpec("docs/10-market/14-GTM-CHANNELS.md", fm + f"""# Go-to-market channels — {state.name}
+
+## Rank-ordered channels (top 5 we will lean on)
+
+| Rank | Channel | Why this one | Owner | First experiment |
+|---|---|---|---|---|
+| 1 | {_todo("channel")} | {_todo("fit with ICP + cost")} | {_todo("who runs it")} | {_todo("week-1 test")} |
+| 2 | {_todo("channel")} | {_todo("rationale")} | {_todo("who")} | {_todo("test")} |
+| 3 | {_todo("channel")} | {_todo("rationale")} | {_todo("who")} | {_todo("test")} |
+| 4 | {_todo("channel")} | {_todo("rationale")} | {_todo("who")} | {_todo("test")} |
+| 5 | {_todo("channel")} | {_todo("rationale")} | {_todo("who")} | {_todo("test")} |
+
+## Channels we explicitly reject
+
+- {_todo("channel + why it doesn't fit the ICP")}
+
+## Distribution moat — what compounds
+
+{_todo("the thing that gets cheaper / better the longer we run it (SEO, community, viral loop, integrations)")}
+"""),
+
+        FileSpec("docs/10-market/15-POSITIONING.md", fm + f"""# Positioning — {state.name}
+
+## The one-sentence positioning statement
+
+> For **{_todo("ICP")}** who struggle with **{_todo("pain")}**,
+> **{state.name}** is the **{_todo("product category")}** that
+> **{_todo("unique benefit")}** —
+> unlike **{_todo("alternative")}**, we **{_todo("how we differ")}**.
+
+## Category we play in
+
+- **Existing category:**  {_todo("e.g. 'sales engagement'")}
+- **Our framing:**         {_todo("how we re-name the category to favour our shape (e.g. 'AI sales rooms')")}
+
+## Three messages, ranked
+
+1. **Lead message:**    {_todo("the line on the hero")}
+2. **Proof message:**   {_todo("the line that closes a skeptic")}
+3. **Differentiator:**  {_todo("the line that makes us memorable")}
+
+## Anti-positioning — what we will NEVER claim
+
+- {_todo("a tempting positioning we will refuse for integrity")}
+"""),
+    ]
+
+
+# ---------------------------------------------------------------------------
+# PHASE 3 — Branding (3 files, wired to the design-discipline skills)
+# ---------------------------------------------------------------------------
+
+
+def phase_branding(state: GenesisState) -> list[FileSpec]:
+    fm = _frontmatter(state, kind="branding")
+    ui_kit = state.stack.ui_kit
+    # The 3 design skills the operator already has installed globally
+    # are referenced here so the worker that fills these files knows
+    # which skills to invoke.
+    design_skills_block = (
+        "## Design discipline — skills the worker MUST invoke when filling this\n\n"
+        "- **`/emil-design-eng`** (https://github.com/emilkowalski/skill) — "
+        "Emil Kowalski's design engineering discipline; bias toward subtle, "
+        "tactile, motion-aware interfaces.\n"
+        "- **`/impeccable`** (https://github.com/pbakaus/impeccable) — "
+        "Pixel-level craft. No half-baked components, no inconsistent spacing.\n"
+        "- **`/taste-skill`** (https://www.tasteskill.dev) — taste calibration "
+        "across typography, colour, hierarchy, motion.\n"
+        "- **`/shadcn-ui`** — every component from "
+        "https://ui.shadcn.com/docs/components is in scope by default.\n\n"
+    )
+    return [
+        FileSpec("docs/20-brand/21-BRAND-IDENTITY.md", fm + f"""# Brand identity — {state.name}
+
+{design_skills_block}
+
+## Personality (5-7 adjectives, ranked)
+
+1. {_todo("adjective 1")}
+2. {_todo("adjective 2")}
+3. {_todo("adjective 3")}
+
+## Voice rules
+
+- **We sound like:**  {_todo("1 sentence describing the voice — e.g. 'a senior engineer who respects your time'")}
+- **We never sound:** {_todo("anti-pattern — e.g. 'hype, exclamation marks, AI-marketing-ese'")}
+
+## Tone matrix
+
+| Context | Tone | Example phrase |
+|---|---|---|
+| Onboarding | {_todo("welcoming | direct")} | "{_todo("phrase")}" |
+| Error | {_todo("clear | accountable")} | "{_todo("phrase")}" |
+| Success | {_todo("understated | warm")} | "{_todo("phrase")}" |
+| Marketing | {_todo("confident | specific")} | "{_todo("phrase")}" |
+
+## Visual mood (mood-board references)
+
+- {_todo("ref 1 — Linear, Vercel, Stripe, Things, …")}
+- {_todo("ref 2")}
+- {_todo("ref 3 — and ONE we explicitly want to be NOT like")}
+
+## Logo direction
+
+- **Mark:**       {_todo("wordmark | symbol+wordmark | letter mark")}
+- **Energy:**     {_todo("static | kinetic | playful | severe")}
+- **Constraint:** {_todo("monochrome-first / colour-first / both")}
+"""),
+
+        FileSpec("docs/20-brand/22-DESIGN-SYSTEM.md", fm + f"""# Design system — {state.name}
+
+{design_skills_block}
+
+## Foundation
+
+- **UI kit:**           ``{ui_kit}``
+- **shadcn theme:**     {_todo("oklch palette name + 1-line justification")}
+- **Type scale:**       {_todo("modular scale ratio (1.125 / 1.250 / 1.333)")}
+- **Radius:**           {_todo("rounded-md by default | sharp | very rounded")}
+- **Spacing unit:**     {_todo("4px / 8px / Tailwind default")}
+
+## Colour tokens (oklch, light + dark)
+
+| Token | Light | Dark | Used on |
+|---|---|---|---|
+| bg | {_todo("L 100% C 0 H 0")} | {_todo("L 8% C 0 H 0")} | page backgrounds |
+| fg | {_todo("L 14% C 0.02 H 250")} | {_todo("L 96% C 0.02 H 250")} | primary text |
+| primary | {_todo("L 60% C 0.18 H 250")} | {_todo("L 65% C 0.18 H 250")} | CTAs |
+| accent | {_todo("L 70% C 0.20 H 30")} | {_todo("L 70% C 0.20 H 30")} | highlights |
+
+## Typography pairings
+
+- **Display:** {_todo("font + weight + tracking")}
+- **Body:**    {_todo("font + weight + line-height")}
+- **Mono:**    {_todo("font for code/numbers")}
+
+## Component inventory we will ship in v1
+
+(from https://ui.shadcn.com/docs/components — pick + extend)
+
+- {_todo("button: 4 variants + 3 sizes")}
+- {_todo("card, input, select, dialog, sheet, tabs")}
+- {_todo("toast, tooltip, dropdown")}
+- {_todo("app-specific: chat-bubble | data-card | flow-canvas")}
+
+## Components we will NOT use
+
+- {_todo("e.g. carousel — never tells the story we want")}
+"""),
+
+        FileSpec("docs/20-brand/23-MOTION-LANGUAGE.md", fm + f"""# Motion language — {state.name}
+
+{design_skills_block}
+
+## Motion principles (Emil Kowalski + Impeccable)
+
+1. **Purpose first.** Motion is only allowed when it serves comprehension
+   or feedback. Decorative motion is rejected.
+2. **Spring physics, not curves.** Use Framer Motion springs with
+   ``stiffness`` 300-500 + ``damping`` 25-40 — easing only for transforms
+   tied to user gestures.
+3. **150-250ms.** Anything outside this window feels broken (too fast
+   feels jittery, too slow feels slow).
+4. **Mass + drag.** Heavy elements move slower; light elements snap.
+5. **Reduced-motion compliance.** Every transition checks
+   ``prefers-reduced-motion`` and disables the spring.
+
+## Motion catalogue we will ship
+
+| Event | Spec | Why |
+|---|---|---|
+| Page enter | {_todo("fade + 8px translateY, 200ms spring")} | {_todo("reason")} |
+| Modal open | {_todo("scale 0.96→1 + fade, 180ms")} | {_todo("reason")} |
+| Hover affordance | {_todo("y -2px, instant on touch")} | {_todo("reason")} |
+| Tab switch | {_todo("layoutId + 200ms spring")} | {_todo("reason")} |
+| Toast | {_todo("slide-in 250ms, auto-dismiss 4s")} | {_todo("reason")} |
+
+## Library
+
+- **Primary:** ``framer-motion`` (matches React + shadcn)
+- **For complex orchestration:** ``gsap`` (only when framer-motion can't, with rationale per use)
+- **For 3D / WebGL:** ``three.js`` + ``@react-three/fiber`` (only for hero / brand moments)
+"""),
+    ]
+
+
+# ---------------------------------------------------------------------------
+# PHASE 4 — PRD suite (9 files)
+# ---------------------------------------------------------------------------
+
+
+def phase_prd(state: GenesisState) -> list[FileSpec]:
+    fm = _frontmatter(state, kind="prd")
+    s = state.stack
+    return [
+        FileSpec("docs/30-prd/31-PRD.md", fm + f"""# Product Requirements Document — {state.name}
+
+## 1. Problem
+
+{_todo("3-5 sentences. Same problem as VISION but here with concrete user behaviours that prove the pain.")}
+
+## 2. Goals (v1 — what we MUST ship)
+
+| Goal | Measurable success | Owner |
+|---|---|---|
+| {_todo("goal")} | {_todo("metric + threshold")} | {_todo("role")} |
+
+## 3. Non-goals (for v1)
+
+- {_todo("explicit feature we WILL NOT build in v1")}
+- {_todo("audience we WILL NOT serve in v1")}
+
+## 4. Personas
+
+(See ``docs/10-market/12-ICP.md`` for full ICPs.)
+
+## 5. Top user stories — v1 scope
+
+| ID | Story | Acceptance |
+|---|---|---|
+| US-01 | As a {_todo("role")}, I want to {_todo("verb + object")}, so I can {_todo("higher-level goal")} | {_todo("verifiable criterion")} |
+| US-02 | … | … |
+
+## 6. Feature list
+
+See ``docs/40-features/F-*.md`` — each feature has its own spec with
+``depends_on`` (the DAG the v0.19 plan executor uses).
+
+## 7. Constraints
+
+- **Stack:**      {s.frontend} + {s.backend} + {s.deploy} + {s.payments}
+- **Compliance:** {_todo("GDPR / SOC2 / HIPAA / none")}
+- **Performance budget:** {_todo("LCP <2.5s, CLS <0.1, bundle <X KB")}
+
+## 8. Risks + mitigations
+
+| Risk | Mitigation |
+|---|---|
+| {_todo("risk 1")} | {_todo("mitigation")} |
+| {_todo("risk 2")} | {_todo("mitigation")} |
+"""),
+
+        FileSpec("docs/30-prd/32-TECH-ARCHITECTURE.md", fm + f"""# Technical architecture — {state.name}
+
+## Stack lock
+
+| Layer | Choice | Version policy |
+|---|---|---|
+| Frontend | ``{s.frontend}`` | latest LTS — fetched via Context7 at install |
+| Backend | ``{s.backend}`` | latest stable |
+| Deploy | ``{s.deploy}`` | — |
+| Payments | ``{s.payments}`` | latest API |
+| Auth | ``{s.auth}`` | — |
+| UI kit | ``{s.ui_kit}`` | latest |
+| Extras | {", ".join(s.extras) or "—"} | per-lib best practice |
+
+## Repo shape (monorepo or single?)
+
+{_todo("single-repo / Turborepo / pnpm workspaces — and why")}
+
+## Folder structure
+
+```
+{state.slug}/
+├── apps/
+│   └── web/                        # Next.js App Router
+│       ├── app/
+│       ├── components/
+│       └── lib/
+├── packages/                       # if monorepo
+├── convex/                         # backend functions (if convex)
+├── docs/                           # Genesis output (this tree)
+├── plan/                           # v0.19 plan store
+└── .env.local
+```
+
+## Deployment topology
+
+- **Web:**     {_todo("Vercel project name + region")}
+- **Backend:** {_todo("Convex deployment name + region")}
+- **DNS:**     {_todo("apex domain + subdomain plan")}
+
+## Observability
+
+- **Errors:**       Sentry
+- **Analytics:**    {_todo("PostHog | Plausible | Mixpanel — and one reason")}
+- **Performance:**  Vercel Analytics + Speed Insights
+"""),
+
+        FileSpec("docs/30-prd/33-DESIGN-SYSTEM-DETAIL.md", fm + f"""# Design system — implementation detail
+
+(High-level system in ``docs/20-brand/22-DESIGN-SYSTEM.md``.)
+
+## Tailwind v4 config
+
+{_todo("the @theme block with the oklch palette, font stack, radius, spacing")}
+
+## shadcn theme
+
+{_todo("the components.json baseColor + the per-token override block")}
+
+## Component conventions
+
+- Every shadcn component MUST be in ``components/ui/<name>.tsx``.
+- App-specific components go in ``components/<feature>/<Name>.tsx``.
+- NEVER edit shadcn primitives in-place — wrap and extend.
+
+## Accessibility floor
+
+- WCAG 2.1 AA on every page.
+- ``/a11yaudit`` MUST score ≥ 85 on every PR.
+"""),
+
+        FileSpec("docs/30-prd/34-LAYOUTS.md", fm + f"""# Layouts — {state.name}
+
+## Top-level routes
+
+| Route | Purpose | Auth required | Layout |
+|---|---|---|---|
+| ``/`` | Marketing landing | no | marketing |
+| ``/sign-in`` | Auth | no | minimal |
+| ``/dashboard`` | App home | yes | app |
+| ``/dashboard/{_todo("...")}`` | feature | yes | app |
+| ``/settings`` | Account | yes | app |
+
+## App-shell layout
+
+```
+┌─────────────────────────────────────────────┐
+│  top-bar (logo · search · profile)          │
+├──────┬──────────────────────────────────────┤
+│ side │  main content                         │
+│ nav  │                                       │
+│      │                                       │
+└──────┴──────────────────────────────────────┘
+```
+
+## Marketing layout
+
+{_todo("hero, social proof, features grid, pricing, footer — order + one-line each")}
+"""),
+
+        FileSpec("docs/30-prd/35-DATA-MODEL.md", fm + f"""# Data model — {state.name}
+
+## Entities (Convex tables / Postgres tables)
+
+| Entity | Fields | Indexed by | Relationships |
+|---|---|---|---|
+| users | id, email, name, createdAt, planTier | byEmail | 1-to-many → projects |
+| {_todo("entity")} | {_todo("fields")} | {_todo("indexes")} | {_todo("relationships")} |
+
+## Convex schema (schema.ts)
+
+```typescript
+{_todo("import { defineSchema, defineTable } from convex/server; …")}
+```
+
+## Migrations strategy
+
+- Every schema change carries a migration script in ``convex/migrations/``.
+- ``omega plan build`` REJECTS a feature whose ``depends_on`` includes a
+  schema change that hasn't been verified by ``/dataaudit``.
+
+## PII + secrets
+
+- {_todo("which fields are PII — and where they're encrypted at rest")}
+- {_todo("which fields are secrets — and the vault path that holds them")}
+"""),
+
+        FileSpec("docs/30-prd/36-AGENT-PLAYBOOK.md", fm + f"""# Agent playbook — {state.name}
+
+> This file is read by every worker the v0.19 plan executor dispatches.
+> It tells the worker WHAT IT MUST RESPECT, project-wide.
+
+## Stack contract
+
+- Frontend: ``{s.frontend}`` — App Router, Server Components by default.
+- Backend: ``{s.backend}`` — queries + mutations only; no ad-hoc REST.
+- Auth: ``{s.auth}`` — use the official middleware. Never roll your own.
+- Payments: ``{s.payments}`` — webhook verification is non-negotiable.
+
+## Skills the workers MUST invoke when the task touches their domain
+
+| Worker domain | Skill |
+|---|---|
+| UI / pages | ``/shadcn-ui`` + ``/emil-design-eng`` + ``/impeccable`` + ``/taste-skill`` |
+| Convex queries / mutations | ``/convex`` + ``/convex-best-practices`` |
+| Stripe integration | ``/stripe-best-practices`` |
+| Vercel deploy | ``/vl-deploy-to-vercel`` |
+| Forms | ``/mk-form-cro`` |
+| SEO surfaces | ``/seoaudit`` + ``/mk-schema-markup`` |
+| Performance | ``/perfaudit`` |
+| Accessibility | ``/a11yaudit`` |
+| Motion | ``/motionaudit`` |
+
+## Non-negotiables (worker MUST refuse the task if it violates these)
+
+1. **No inline styles** unless the design system needs an escape hatch — and even then, document it.
+2. **Server Components by default** in Next.js — ``"use client"`` only when state/effects/event handlers are needed.
+3. **All routes auth-checked** via Clerk middleware. A page without a Clerk check is a security bug.
+4. **Convex calls only from Server Components or via ``useQuery``** — never raw fetch().
+5. **Every PR runs ``/perfaudit`` + ``/a11yaudit`` + ``/codeaudit`` before merge.**
+
+## Verify per task
+
+Each task has a ``verify_cmd`` set by the v0.19 plan builder. It's
+non-negotiable: the worker writes ``.done.json`` with ``status=done_clean``
+ONLY when verify_cmd exits 0. If it doesn't, status=pending — and the
+worker explains in ``pending_actions`` what blocked it.
+"""),
+
+        FileSpec("docs/30-prd/37-TESTING-STRATEGY.md", fm + f"""# Testing strategy — {state.name}
+
+## Test pyramid
+
+| Layer | What | Tool | Run when |
+|---|---|---|---|
+| Unit | Pure functions, utils | Vitest | every save |
+| Component | shadcn-derived components | Vitest + Testing Library | every save |
+| Integration | Convex query+mutation flow | Vitest + convex-test | pre-commit |
+| E2E auth flow | Sign-in → Dashboard → core action | Playwright + Clerk sign-in-token | on PR |
+| Forensic | Full ``/e2e`` skill | OmegaOS Quality Arsenal | pre-launch |
+
+## E2E auth — the Clerk sign-in-token + ticket strategy
+
+(Documented in ``/e2e`` skill — bypasses 2FA in CI safely.)
+
+## Snapshot policy
+
+- Component snapshots on every PR.
+- Pixel-level visual regression via Playwright screenshots for the top 10 routes.
+
+## CI integration
+
+- Pre-commit: lint + unit + component tests.
+- PR: integration + e2e on changed surfaces.
+- Pre-merge: ``/codeaudit`` + ``/perfaudit`` + ``/a11yaudit`` GREEN.
+"""),
+
+        FileSpec("docs/30-prd/38-CHANGELOG.md", fm + f"""# Changelog — {state.name}
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Added
+- {_todo("feature")}
+
+### Changed
+- {_todo("change")}
+
+### Fixed
+- {_todo("fix")}
+
+---
+
+## [0.0.1] — {state.created_at[:10]}
+
+### Added
+- Project genesis tree created by ``omega genesis`` (this run).
+"""),
+
+        FileSpec("docs/30-prd/39-GLOSSARY.md", fm + f"""# Glossary — {state.name}
+
+| Term | Definition | Source of truth |
+|---|---|---|
+| {_todo("term")} | {_todo("definition")} | {_todo("file / link")} |
+"""),
+    ]
+
+
+# ---------------------------------------------------------------------------
+# PHASE 5 — Features (N files with explicit DAG)
+# ---------------------------------------------------------------------------
+
+
+def _default_feature_skeleton(state: GenesisState) -> list[dict[str, Any]]:
+    """A starter feature DAG every web project needs.
+
+    Each dict is the metadata the orchestrator writes into the feature
+    file's frontmatter PLUS the YAML stored in ``plan/DAG.json``.
+    Topological order: F-001 → F-002 → … with explicit depends_on.
+    """
+    return [
+        {
+            "id": "F-001", "slug": "foundation",
+            "title": "Foundation — Next.js app + Convex backend + Clerk auth",
+            "depends_on": [],
+            "wave": 1, "estimated_minutes": 90,
+            "files_owned": [
+                "package.json", "next.config.ts", "tsconfig.json",
+                "app/layout.tsx", "app/page.tsx",
+                "convex/schema.ts", "middleware.ts",
+            ],
+            "verify_cmd": "pnpm build && pnpm test -- --run",
+            "skill": "/convex + /vercel-react-best-practices",
+        },
+        {
+            "id": "F-002", "slug": "design-system",
+            "title": "Design system — Tailwind v4 + shadcn theme + 12 base components",
+            "depends_on": ["F-001"],
+            "wave": 1, "estimated_minutes": 60,
+            "files_owned": [
+                "app/globals.css", "components.json",
+                "components/ui/*.tsx",
+            ],
+            "verify_cmd": "pnpm build && pnpm test -- components/ui",
+            "skill": "/shadcn-ui + /design-system + /taste-skill",
+        },
+        {
+            "id": "F-003", "slug": "auth-flow",
+            "title": "Auth flow — sign-in / sign-up / sign-out + ClerkProvider",
+            "depends_on": ["F-001", "F-002"],
+            "wave": 1, "estimated_minutes": 45,
+            "files_owned": [
+                "app/sign-in/page.tsx", "app/sign-up/page.tsx",
+                "components/auth/*.tsx",
+            ],
+            "verify_cmd": "pnpm test -- e2e/auth.spec.ts",
+            "skill": "/emil-design-eng + /impeccable",
+        },
+        {
+            "id": "F-004", "slug": "marketing-landing",
+            "title": "Marketing landing — hero, features grid, pricing teaser, footer",
+            "depends_on": ["F-002"],
+            "wave": 2, "estimated_minutes": 90,
+            "files_owned": [
+                "app/page.tsx", "components/marketing/*.tsx",
+            ],
+            "verify_cmd": "pnpm test -- marketing && pnpm exec playwright test e2e/landing.spec.ts",
+            "skill": "/shadcn-ui + /taste-skill + /copyaudit + /seoaudit",
+        },
+        {
+            "id": "F-005", "slug": "dashboard-shell",
+            "title": "Dashboard shell — top bar + side nav + protected layout",
+            "depends_on": ["F-003"],
+            "wave": 2, "estimated_minutes": 60,
+            "files_owned": [
+                "app/(app)/layout.tsx", "app/(app)/dashboard/page.tsx",
+                "components/app-shell/*.tsx",
+            ],
+            "verify_cmd": "pnpm test -- e2e/dashboard.spec.ts",
+            "skill": "/shadcn-ui + /impeccable",
+        },
+        {
+            "id": "F-006", "slug": "billing-stripe-connect",
+            "title": "Billing — Stripe subscription + webhook + customer portal",
+            "depends_on": ["F-001", "F-003"],
+            "wave": 2, "estimated_minutes": 120,
+            "files_owned": [
+                "app/api/stripe/webhook/route.ts",
+                "convex/billing/*.ts",
+                "app/(app)/settings/billing/page.tsx",
+            ],
+            "verify_cmd": "pnpm test -- billing",
+            "skill": "/stripe-best-practices",
+        },
+        # Operator-specific features go from F-007 onwards. The
+        # orchestrator's feature-phase output emits this skeleton + a
+        # TODO block calling out the operator to add the product-specific
+        # features in the correct topological order.
+    ]
+
+
+def phase_features(state: GenesisState) -> list[FileSpec]:
+    """Emit:
+      * one ``F-NNN-<slug>.md`` per default feature (with frontmatter
+        carrying ``depends_on``, ``wave``, ``estimated_minutes``,
+        ``files_owned``, ``verify_cmd``, ``skill``).
+      * one ``F-TEMPLATE.md`` for the operator to copy when adding their
+        product-specific features.
+      * one ``DAG.json`` under ``plan/`` that the v0.19 plan builder
+        consumes.
+    """
+    fm = _frontmatter(state, kind="feature-spec")
+    skeleton = _default_feature_skeleton(state)
+    specs: list[FileSpec] = []
+
+    # Feature files (one per F-NNN)
+    for f in skeleton:
+        body = f"""---
+slug: {state.slug}
+feature_id: {f['id']}
+feature_slug: {f['slug']}
+title: {f['title']}
+depends_on: {f['depends_on']}
+wave: {f['wave']}
+estimated_minutes: {f['estimated_minutes']}
+files_owned: {f['files_owned']}
+verify_cmd: "{f['verify_cmd']}"
+skill: "{f['skill']}"
+generated_at: {state.updated_at}
+---
+
+# {f['id']} — {f['title']}
+
+## Why this exists
+
+{_todo("1-2 sentences: what user pain or business win this directly serves.")}
+
+## Acceptance criteria (verifiable by `{f['verify_cmd']}`)
+
+- [ ] {_todo("checkbox 1")}
+- [ ] {_todo("checkbox 2")}
+- [ ] {_todo("checkbox 3")}
+
+## Files this feature owns
+
+{chr(10).join(f"- ``{p}``" for p in f['files_owned'])}
+
+## Depends on
+
+{(chr(10).join(f"- {d}" for d in f['depends_on'])) if f['depends_on'] else "_(none — first wave)_"}
+
+## How the worker should approach this
+
+1. Read this file.
+2. Read every file in ``files_owned`` (most don't exist yet → that's OK).
+3. Read ``docs/30-prd/36-AGENT-PLAYBOOK.md`` and respect EVERY non-negotiable.
+4. Invoke the skill: ``{f['skill']}``.
+5. Implement, then run ``{f['verify_cmd']}``.
+6. Write ``.done.json`` only when the verify command exits 0.
+
+## Skill block
+
+The worker spawn injects this skill list into the system prompt:
+``{f['skill']}``.
+"""
+        specs.append(FileSpec(
+            f"docs/40-features/{f['id']}-{f['slug']}.md", body,
+        ))
+
+    # Template for operator-authored features
+    template = fm + """# F-TEMPLATE — Copy this file when adding a new feature
+
+> Rename to ``F-NNN-<slug>.md`` (NNN strictly increasing, no gaps).
+> The v0.19 plan builder reads every file matching ``F-[0-9]+-*.md`` and
+> sorts by id, but enforces order via the ``depends_on`` DAG — NOT by
+> filename.
+
+Frontmatter required:
+
+```yaml
+---
+slug: <project-slug>
+feature_id: F-NNN
+feature_slug: <kebab-case>
+title: <one-line title>
+depends_on: [F-XXX, F-YYY]
+wave: 2
+estimated_minutes: 45
+files_owned:
+  - apps/web/app/<route>/page.tsx
+  - convex/<feature>/*.ts
+verify_cmd: "pnpm test -- e2e/<feature>.spec.ts"
+skill: "/shadcn-ui + /taste-skill"
+---
+```
+"""
+    specs.append(FileSpec("docs/40-features/F-TEMPLATE.md", template))
+
+    # DAG.json — the machine-readable view the v0.19 plan builder consumes
+    import json as _json
+    dag = {
+        "slug": state.slug,
+        "generated_at": state.updated_at,
+        "features": skeleton,
+    }
+    specs.append(FileSpec("plan/DAG.json", _json.dumps(dag, indent=2)))
+
+    return specs
+
+
+# ---------------------------------------------------------------------------
+# PHASE 6 — Plan (handoff to v0.19)
+# ---------------------------------------------------------------------------
+
+
+def phase_plan(state: GenesisState) -> list[FileSpec]:
+    """Final phase — emits the handoff doc that tells the operator how to
+    move from Genesis to the v0.19 Plan executor."""
+    fm = _frontmatter(state, kind="genesis-handoff")
+    body = fm + f"""# Genesis complete — ready for `omega plan`
+
+The Genesis pipeline has finished. Every doc is in place under
+``docs/``; the feature DAG is at ``plan/DAG.json``.
+
+## What you have now
+
+- ``docs/00-VISION.md``                          — product identity
+- ``docs/10-market/{{11..15}}-*.md``               — 5 market files
+- ``docs/20-brand/{{21..23}}-*.md``                — 3 brand files
+- ``docs/30-prd/{{31..39}}-*.md``                  — 9 PRD files
+- ``docs/40-features/F-001..F-006*.md``           — starter feature DAG
+- ``plan/DAG.json``                              — machine-readable DAG
+
+## The next step
+
+```bash
+omega plan build {state.slug}        # ingests DAG.json into the v0.19 plan store
+omega plan next  {state.slug}        # returns the next eligible task (1 at a time)
+omega plan run   {state.slug}        # multi-day autonomous loop with FSM-enforced ordering
+```
+
+## What still needs operator attention
+
+- Fill the `<!-- TODO -->` blocks in every doc. Most will be picked up by
+  the v0.19 plan executor when it dispatches worker briefs, but some
+  (especially Vision §3 personas, Market §11 competitors) benefit from
+  a single human pass first.
+- Add your product-specific features beyond F-006. Copy
+  ``docs/40-features/F-TEMPLATE.md``, increment the id, list
+  ``depends_on``.
+- Re-run ``omega plan build {state.slug}`` after editing the DAG — it's
+  idempotent and re-validates the topological order.
+
+## Stack summary (for the workers)
+
+| | |
+|---|---|
+| Type | ``{state.stack.type}`` |
+| Frontend | ``{state.stack.frontend}`` |
+| Backend | ``{state.stack.backend}`` |
+| Deploy | ``{state.stack.deploy}`` |
+| Payments | ``{state.stack.payments}`` |
+| UI kit | ``{state.stack.ui_kit}`` |
+| Auth | ``{state.stack.auth}`` |
+| Extras | {", ".join(state.stack.extras) or "—"} |
+"""
+    return [FileSpec("docs/GENESIS-COMPLETE.md", body)]