@agentikos/omega-os 0.1.0 → 0.19.5

package/omega/Agentik_SSOT/skills/dxaudit/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: dxaudit
+description: Forensic dx audit — Is the DX SMOOTH — can a new developer go from git clone to first contribution within a day?. Runs the gather (deterministic) + falsify (agentic) pipeline, batches fixes, dispatches capped workers, re-audits, and persists scores. Use when the user says "/dxaudit", "audit dx", or asks to verify the dx health of the project.
+when_to_use: User says /dxaudit, audit dx, check dx, verify dx, is dx healthy.
+argument-hint: "[--scope <path>] [--fix] [--max-workers N]"
+arguments: [args]
+allowed-tools: Bash Read Edit Grep Glob Write
+---
+
+# dxaudit — forensic audit (Agentik OS Quality Arsenal)
+
+> Is the DX SMOOTH — can a new developer go from git clone to first contribution within a day?
+
+You are running the dxaudit forensic audit. Apply the **Gestalt-Popper
+doctrine**: identify the hinge point, scrutinise it 10x, then assume
+every name is a CLAIM and look for the divergence between the claim and
+the reality. Bias toward FAIL. A perfect score is earned by finding zero
+falsifiable claims, never by absence of effort.
+
+## Run
+
+The audit is one engine call — gather (deterministic) + falsify (agentic)
++ optional fix-dispatch (capped) + re-audit. Invoke the unified pipeline:
+
+```bash
+omega audit run dxaudit $args
+```
+
+Common options:
+
+| Flag | Effect |
+|---|---|
+| `--scope <path>` | scope the audit (file or directory) |
+| `--fix` | after analysing, batch findings + dispatch up to N workers + re-audit |
+| `--max-workers N` | cap parallel fix workers (default 3) |
+| `--min-severity high` | only batch + fix findings at or above this severity |
+
+Read-only by default. Add `--fix` to enable the dispatch + re-audit loop.
+
+## Phases under investigation
+
+The agentic pass walks each phase below and emits structured findings
+(claim vs. reality). Every PASS must cite ≥3 concrete checks.
+
+### 1. readme-quality
+
+THE HINGE — README has description, prerequisites, copy-pasteable install/run, env vars, architecture, troubleshooting; can a dev reach a running app in <10 min?
+
+### 2. setup-complexity
+
+THE HINGE — count manual steps from clone to running (target <5); .env.example exists with every var documented; Docker Compose for local services; one-command setup.
+
+### 3. error-messages
+
+Build/runtime errors give actionable guidance — name the missing var/service/dependency and how to fix it, not 'ENOENT' or a raw stack trace.
+
+### 4. typescript-strictness
+
+tsconfig strict:true (or mypy/clippy strict); no widespread 'any'; no @ts-ignore without a comment; explicit return types on exported functions.
+
+### 5. code-documentation
+
+Exported functions have JSDoc/docstrings with params and returns; architecture documented; 'why' comments on non-obvious logic; docs match current code.
+
+### 6. testing-infrastructure
+
+Test runner works with one command; coverage reported; tests deterministic, fast (<5min), independent; watch mode and single-test runnable.
+
+### 7. ci-cd-pipeline
+
+All PRs run CI (lint+typecheck+test+build); CI <10min; CD automated on merge; main branch protected; no flaky CI.
+
+### 8. dependency-management
+
+Lock file committed; no critical vulnerabilities; no abandoned deps (last release >2y); Renovate/Dependabot configured; pinning strategy defined.
+
+### 9. dev-tooling
+
+Linter and formatter configured and run automatically; pre-commit hooks fast (<10s); .editorconfig present; recommended editor extensions documented.
+
+### 10. environment-parity
+
+Dev/staging/prod differences documented; same runtime and DB versions; no hardcoded URLs/ports/credentials; config validated on startup (fail fast).
+
+### 11. debug-tooling
+
+Structured logging with levels; debugger config (launch.json) checked in; source maps work; DB queries and API requests visible in dev.
+
+### 12. monorepo-structure
+
+Workspace config if monorepo with clear package boundaries and build cache; logical feature-organized directory structure; no circular deps; no utils dumping ground.
+
+### 13. migration-changelog
+
+Major-version upgrade guides with breaking changes and fixes; CHANGELOG maintained in Keep-a-Changelog format; reversible versioned DB migrations.
+
+### 14. contribution-guide
+
+CONTRIBUTING.md with bug/feature/PR process, branch and commit conventions; 'good first issue' path; architecture overview for newcomers.
+
+## Falsification rules
+
+The README lies until proven true — follow every setup instruction LITERALLY on a fresh clone; any step that fails, is unclear, or is missing means the README failed. Every PASS must cite at least 3 concrete checks with actual output. Categorise findings as README-vs-REALITY, LOCAL-vs-CI, FIRST-vs-REPEAT, HAPPY-vs-ERROR, or EXPERT-vs-NEWCOMER. "Ask in Slack" is not documentation — if knowledge is not in the repo it does not exist. Bias toward FAIL.
+
+## After the run
+
+The pipeline writes one structured verdict to:
+
+```
+Agentik_Runtime/audits.db    (history — `omega audit history dxaudit`)
+Agentik_Runtime/sessions/${CLAUDE_SESSION_ID}/.done.json   (this turn)
+```
+
+The `.done.json` schema:
+
+```json
+{
+  "status": "done_clean" | "pending" | "failed",
+  "summary": "<one-paragraph verdict>",
+  "artifacts": {
+    "audit": "dxaudit",
+    "score": 0-100,
+    "verified": bool,
+    "findings": [...],
+    "fix_plan": [...],
+    "dispatches": [...],
+    "reaudit_score": 0-100  // only when --fix was used
+  }
+}
+```
+
+## Hard rules (don't break these)
+
+1. **No fake "done".** First Law: only runtime tells the truth. If the
+   gather phase fails or the agentic verdict scores below the threshold,
+   you have NOT verified — set status to `pending` or `failed`.
+2. **Cap parallelism.** ≤ 3 fix workers at a time. The
+   batcher enforces this; do not call out to other dispatch mechanisms.
+3. **No worker per finding.** Findings are clustered by file footprint and
+   severity. One worker handles one disjoint batch.
+4. **Re-audit confirms.** After fixes land, the pipeline re-runs the same
+   gather + agentic phases. If the score did not improve, escalate honestly.
+5. **History is the trend.** `omega audit history dxaudit` shows whether the
+   codebase is improving over time on this dimension. Use it to decide
+   whether to push for `--fix` again.
+
+## Why this audit exists
+
+The 18 forensic audits are the OmegaOS verification layer. Claude's
+"I'm done" claims used to be unverified. With these audits running as
+the gate, completion is **derived from observable facts**, not declared
+by the worker. Run this audit any time someone (human or agent) claims
+the dx dimension is healthy. Insist on the score before you
+accept.
+
+## Reference
+
+Audit definition: `Agentik_SSOT/audits/dxaudit.yaml`
+Engine pipeline:  `omega_engine.audits.pipeline.AuditPipeline`
+Batcher:          `omega_engine.audits.batcher.batch_findings`
+History:          `omega_engine.audits.history`

package/omega/Agentik_SSOT/skills/featureaudit/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: featureaudit
+description: Forensic features audit — Is the product COMPLETE — does everything that SHOULD exist actually exist and run deep?. Runs the gather (deterministic) + falsify (agentic) pipeline, batches fixes, dispatches capped workers, re-audits, and persists scores. Use when the user says "/featureaudit", "audit features", or asks to verify the features health of the project.
+when_to_use: User says /featureaudit, audit features, check features, verify features, is features healthy.
+argument-hint: "[--scope <path>] [--fix] [--max-workers N]"
+arguments: [args]
+allowed-tools: Bash Read Edit Grep Glob Write
+---
+
+# featureaudit — forensic audit (Agentik OS Quality Arsenal)
+
+> Is the product COMPLETE — does everything that SHOULD exist actually exist and run deep?
+
+You are running the featureaudit forensic audit. Apply the **Gestalt-Popper
+doctrine**: identify the hinge point, scrutinise it 10x, then assume
+every name is a CLAIM and look for the divergence between the claim and
+the reality. Bias toward FAIL. A perfect score is earned by finding zero
+falsifiable claims, never by absence of effort.
+
+## Run
+
+The audit is one engine call — gather (deterministic) + falsify (agentic)
++ optional fix-dispatch (capped) + re-audit. Invoke the unified pipeline:
+
+```bash
+omega audit run featureaudit $args
+```
+
+Common options:
+
+| Flag | Effect |
+|---|---|
+| `--scope <path>` | scope the audit (file or directory) |
+| `--fix` | after analysing, batch findings + dispatch up to N workers + re-audit |
+| `--max-workers N` | cap parallel fix workers (default 3) |
+| `--min-severity high` | only batch + fix findings at or above this severity |
+
+Read-only by default. Add `--fix` to enable the dispatch + re-audit loop.
+
+## Phases under investigation
+
+The agentic pass walks each phase below and emits structured findings
+(claim vs. reality). Every PASS must cite ≥3 concrete checks.
+
+### 1. hinge-capability
+
+Identify the ONE capability this product must do better than anything else; is it implemented end-to-end and deep, or shallow?
+
+### 2. prd-compliance
+
+For every feature promised in PRD/VISION/README, find a code trace; PROMISED-vs-BUILT — does it work AS described, not a different interpretation?
+
+### 3. empty-implementation
+
+Stub routes, no-op handlers, buttons that do nothing, handlers returning success but persisting nothing — visible but non-functional.
+
+### 4. feature-depth
+
+For each feature score depth: happy path, edge cases, error handling, configuration, integration — SHALLOW-vs-DEEP.
+
+### 5. edge-case-coverage
+
+The Universal 10 per feature — zero/one/many/overflow states, special chars, long text, concurrent, mobile, offline; does each non-happy input survive?
+
+### 6. partial-crud
+
+For each entity, do all of Create/Read/Update/Delete exist? Partial CRUD, partial export/import, partial search are LABELED-vs-CAPABLE gaps.
+
+### 7. competitive-parity
+
+Table-stakes features all competitors have but this product lacks; differentiators hidden from the UI — MARKETED-vs-DELIVERED.
+
+### 8. discoverability
+
+Clicks from main page to each feature, primary-nav presence, search/command-palette access, onboarding mention — a feature nobody finds is unused.
+
+### 9. feature-coherence
+
+Do features share data and patterns, or are they silos with duplicate data entry and inconsistent interactions?
+
+### 10. api-surface
+
+CRUD coverage, query/filter/sort capability, bulk ops, webhook/event emission — if it is not in the API it does not exist for power users.
+
+### 11. permission-matrix
+
+For every entity x operation x role, is access enforced? Missing permission checks, over-permissive defaults, missing role tiers.
+
+### 12. data-model-gaps
+
+Schema gaps — missing tenancy field, audit trail, soft-delete, version field, indexes on filtered columns.
+
+### 13. scaling-readiness
+
+Features that work now but break at 10x — unpaginated lists, full-table scans, sync ops that should be async, no rate limiting.
+
+### 14. feature-entropy
+
+Terminology drift, verb drift, inconsistent confirm/save patterns, mixed modal/drawer/route for the same flow.
+
+## Falsification rules
+
+The product claims to be ready/launched/v1 — DISPROVE it. Every PASS must cite at least 3 concrete checks with actual output (route renders non-placeholder content, handler persists to real backend, sub-requirements have code branches). Categorise findings as PROMISED-vs-BUILT, VISIBLE-vs-FUNCTIONAL, SHALLOW-vs-DEEP, or LABELED-vs-CAPABLE. TODO comments, "coming soon" strings, permanently-off flags, and routes returning 404/501 are NOT evidence of a feature. Bias toward FAIL — the product is incomplete until proven complete.
+
+## After the run
+
+The pipeline writes one structured verdict to:
+
+```
+Agentik_Runtime/audits.db    (history — `omega audit history featureaudit`)
+Agentik_Runtime/sessions/${CLAUDE_SESSION_ID}/.done.json   (this turn)
+```
+
+The `.done.json` schema:
+
+```json
+{
+  "status": "done_clean" | "pending" | "failed",
+  "summary": "<one-paragraph verdict>",
+  "artifacts": {
+    "audit": "featureaudit",
+    "score": 0-100,
+    "verified": bool,
+    "findings": [...],
+    "fix_plan": [...],
+    "dispatches": [...],
+    "reaudit_score": 0-100  // only when --fix was used
+  }
+}
+```
+
+## Hard rules (don't break these)
+
+1. **No fake "done".** First Law: only runtime tells the truth. If the
+   gather phase fails or the agentic verdict scores below the threshold,
+   you have NOT verified — set status to `pending` or `failed`.
+2. **Cap parallelism.** ≤ 3 fix workers at a time. The
+   batcher enforces this; do not call out to other dispatch mechanisms.
+3. **No worker per finding.** Findings are clustered by file footprint and
+   severity. One worker handles one disjoint batch.
+4. **Re-audit confirms.** After fixes land, the pipeline re-runs the same
+   gather + agentic phases. If the score did not improve, escalate honestly.
+5. **History is the trend.** `omega audit history featureaudit` shows whether the
+   codebase is improving over time on this dimension. Use it to decide
+   whether to push for `--fix` again.
+
+## Why this audit exists
+
+The 18 forensic audits are the OmegaOS verification layer. Claude's
+"I'm done" claims used to be unverified. With these audits running as
+the gate, completion is **derived from observable facts**, not declared
+by the worker. Run this audit any time someone (human or agent) claims
+the features dimension is healthy. Insist on the score before you
+accept.
+
+## Reference
+
+Audit definition: `Agentik_SSOT/audits/featureaudit.yaml`
+Engine pipeline:  `omega_engine.audits.pipeline.AuditPipeline`
+Batcher:          `omega_engine.audits.batcher.batch_findings`
+History:          `omega_engine.audits.history`

package/omega/Agentik_SSOT/skills/flowaudit/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: flowaudit
+description: Forensic flows audit — Does the experience WORK — can a user complete every journey without getting lost or stuck?. Runs the gather (deterministic) + falsify (agentic) pipeline, batches fixes, dispatches capped workers, re-audits, and persists scores. Use when the user says "/flowaudit", "audit flows", or asks to verify the flows health of the project.
+when_to_use: User says /flowaudit, audit flows, check flows, verify flows, is flows healthy.
+argument-hint: "[--scope <path>] [--fix] [--max-workers N]"
+arguments: [args]
+allowed-tools: Bash Read Edit Grep Glob Write
+---
+
+# flowaudit — forensic audit (Agentik OS Quality Arsenal)
+
+> Does the experience WORK — can a user complete every journey without getting lost or stuck?
+
+You are running the flowaudit forensic audit. Apply the **Gestalt-Popper
+doctrine**: identify the hinge point, scrutinise it 10x, then assume
+every name is a CLAIM and look for the divergence between the claim and
+the reality. Bias toward FAIL. A perfect score is earned by finding zero
+falsifiable claims, never by absence of effort.
+
+## Run
+
+The audit is one engine call — gather (deterministic) + falsify (agentic)
++ optional fix-dispatch (capped) + re-audit. Invoke the unified pipeline:
+
+```bash
+omega audit run flowaudit $args
+```
+
+Common options:
+
+| Flag | Effect |
+|---|---|
+| `--scope <path>` | scope the audit (file or directory) |
+| `--fix` | after analysing, batch findings + dispatch up to N workers + re-audit |
+| `--max-workers N` | cap parallel fix workers (default 3) |
+| `--min-severity high` | only batch + fix findings at or above this severity |
+
+Read-only by default. Add `--fix` to enable the dispatch + re-audit loop.
+
+## Phases under investigation
+
+The agentic pass walks each phase below and emits structured findings
+(claim vs. reality). Every PASS must cite ≥3 concrete checks.
+
+### 1. hinge-flow
+
+Identify the ONE journey that — if broken — makes the product worthless (signup->activation, purchase->delivery); audit it with 10x scrutiny end-to-end.
+
+### 2. flow-completeness
+
+Every flow has a reachable entry, every step a clear single CTA and visible progress, a confirmed success state, and a sane next action — no flow that starts but cannot finish.
+
+### 3. state-machines
+
+Every entity's lifecycle states are explicit, transitions guarded (no draft->completed skip), invalid transitions rejected not silently corrupting, no entity can get permanently stuck.
+
+### 4. happy-path
+
+Walk each primary journey — data entered in step 1 survives to step 5, every action acknowledged under 100ms, the result is visible afterward in the dashboard/list.
+
+### 5. error-paths
+
+For every flow exercise the dark paths — empty/invalid/boundary input, API failure mid-flow, slow/garbage responses, permission loss, double-submit; each handled gracefully.
+
+### 6. dead-ends
+
+No state with no way out — unclosable modals, error pages with no home link, success pages with no next step, 'Processing...' that never resolves, empty results with no guidance.
+
+### 7. permission-auth-gaps
+
+Every protected route redirects unauthenticated users and denies wrong roles; no IDOR via URL ID tampering; admin checks enforced server-side not just hidden in UI; session expiry handled.
+
+### 8. onboarding
+
+First-run shows a guided path not an empty dashboard; the shortest path to the activation 'aha' action; empty states teach the user to create their first item.
+
+### 9. data-integrity
+
+Input -> storage -> display roundtrip is identical (special chars, emoji, numbers, timezones); data created in flow A visible in flow B; deletes clean up all references.
+
+### 10. cross-session-continuity
+
+Close/reopen browser preserves state, long flows resume rather than restart, real-time sync across tabs/users, active flows survive a deploy or migration.
+
+### 11. error-recovery
+
+After a validation/network/payment error — form values preserved, focus on the errored field, actionable message, retry without double-charge; destructive actions undoable.
+
+### 12. notification-feedback
+
+Every action gets a proportional reaction — no silent success, no silent failure, no state change without notice; progress communicated for long/background operations.
+
+### 13. empty-and-loading-states
+
+Every list/table/dashboard has a designed zero-data state with a CTA, a layout-shaped loading skeleton, a styled error state with retry — never a blank or collapsed layout.
+
+### 14. destructive-actions
+
+Delete/cancel/disconnect have a consequence-explaining confirmation, the confirm button is not the default, reversibility or clear irreversible warning, cascade effects disclosed.
+
+### 15. flow-entropy
+
+Similar flows structured alike, same action same verb everywhere, back always means back, one consistent pattern for success/error/loading, no terminology drift.
+
+## Falsification rules
+
+The user is always lost; every button is a promise — FALSIFY each. Click "Save": was data actually persisted? "Cancel anytime": can you cancel at every point? Every PASS must cite at least 3 concrete checks (the route walked, the state in the DB, the screenshot of the step). Categorise findings as LABEL-vs-ACTION, PROMISE-vs-EXPERIENCE, STATE-vs-DISPLAY, or FEEDBACK-vs-TRUTH. Happy paths are marketing; error paths, edge cases and permission denials are reality — an untested dark path is an untested flow. Bias toward FAIL.
+
+## After the run
+
+The pipeline writes one structured verdict to:
+
+```
+Agentik_Runtime/audits.db    (history — `omega audit history flowaudit`)
+Agentik_Runtime/sessions/${CLAUDE_SESSION_ID}/.done.json   (this turn)
+```
+
+The `.done.json` schema:
+
+```json
+{
+  "status": "done_clean" | "pending" | "failed",
+  "summary": "<one-paragraph verdict>",
+  "artifacts": {
+    "audit": "flowaudit",
+    "score": 0-100,
+    "verified": bool,
+    "findings": [...],
+    "fix_plan": [...],
+    "dispatches": [...],
+    "reaudit_score": 0-100  // only when --fix was used
+  }
+}
+```
+
+## Hard rules (don't break these)
+
+1. **No fake "done".** First Law: only runtime tells the truth. If the
+   gather phase fails or the agentic verdict scores below the threshold,
+   you have NOT verified — set status to `pending` or `failed`.
+2. **Cap parallelism.** ≤ 3 fix workers at a time. The
+   batcher enforces this; do not call out to other dispatch mechanisms.
+3. **No worker per finding.** Findings are clustered by file footprint and
+   severity. One worker handles one disjoint batch.
+4. **Re-audit confirms.** After fixes land, the pipeline re-runs the same
+   gather + agentic phases. If the score did not improve, escalate honestly.
+5. **History is the trend.** `omega audit history flowaudit` shows whether the
+   codebase is improving over time on this dimension. Use it to decide
+   whether to push for `--fix` again.
+
+## Why this audit exists
+
+The 18 forensic audits are the OmegaOS verification layer. Claude's
+"I'm done" claims used to be unverified. With these audits running as
+the gate, completion is **derived from observable facts**, not declared
+by the worker. Run this audit any time someone (human or agent) claims
+the flows dimension is healthy. Insist on the score before you
+accept.
+
+## Reference
+
+Audit definition: `Agentik_SSOT/audits/flowaudit.yaml`
+Engine pipeline:  `omega_engine.audits.pipeline.AuditPipeline`
+Batcher:          `omega_engine.audits.batcher.batch_findings`
+History:          `omega_engine.audits.history`

package/omega/Agentik_SSOT/skills/genesis/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: genesis
+description: Start a new project from zero — the programmatic, isolated-per-project replacement for /new + /vision + /prd + /planner. Walks 7 deterministic phases (stack → vision → market 5 files → branding 3 files → PRD 9 files → features N with depends_on → handoff to /plan). All artefacts land under $OMEGA_HOME/Agentik_Coding/projects/<slug>/ with strict isolation; PROJECT.yaml is the state machine. Resume-safe. Use when the user says "/genesis", "new project", "start from scratch", "fais un nouveau projet", "creer un projet", "build from nothing", "from idea to plan".
+when_to_use: User wants to start a brand-new project (no existing code) and needs the full upstream docs tree + a DAG-aware feature backlog ready for the /plan executor. For existing projects, use /build instead.
+allowed-tools: Bash Read Write
+argument-hint: "<slug> <intent>"
+arguments: [slug, intent]
+---
+
+# /genesis — programmatic project genesis
+
+You are running the OmegaOS Genesis pipeline. Unlike the legacy `/new`,
+this is a programmatic walker — the engine writes deterministic file
+skeletons; **your job is to FILL the `<!-- TODO -->` blocks with real
+content based on the operator's intent**, then advance to the next phase.
+
+## Phases (run in order — the engine enforces it)
+
+| # | Phase | Files | What you do |
+|---|---|---|---|
+| 0 | stack | — | Pick the technical + programmatic stack via `omega genesis questions` |
+| 1 | vision | `docs/00-VISION.md` | Fill the 7 sections from the intent + a Socratic interview |
+| 2 | market | `docs/10-market/{11..15}-*.md` | 5 files: competitors, ICP, pricing, GTM channels, positioning |
+| 3 | branding | `docs/20-brand/{21..23}-*.md` | 3 files: brand identity, design system, motion language |
+| 4 | prd | `docs/30-prd/{31..39}-*.md` | 9 files: PRD, tech arch, design detail, layouts, data model, agent playbook, testing, changelog, glossary |
+| 5 | features | `docs/40-features/F-*.md` + `plan/DAG.json` | N features with explicit `depends_on`, `wave`, `estimated_minutes`, `files_owned`, `verify_cmd`, `skill` |
+| 6 | plan | `docs/GENESIS-COMPLETE.md` | Handoff doc → `omega plan build <slug>` |
+
+## Strict isolation — non-negotiable
+
+Every artefact lands under:
+
+    $OMEGA_HOME/Agentik_Coding/projects/<slug>/
+
+The engine **refuses** to write outside this root. Two genesis runs on
+two different slugs cannot leak into each other.
+
+## Stack picker (phase 0)
+
+Default = OmegaOS canonical stack:
+
+    type=web  frontend=nextjs  backend=convex  deploy=vercel
+    payments=stripe  ui_kit=shadcn  auth=clerk  extras=[framer-motion]
+
+**Ask the operator** if the brief calls for anything else (mobile,
+desktop, iPhone-native, Mac-native, library, CLI, …). Use:
+
+```bash
+omega genesis questions --intent "<the brief>"
+```
+
+…to get the 5-question form. Apply answers via `--stack-<key>` flags on
+`omega genesis new`.
+
+## Design-discipline skills (mandatory when filling branding + features)
+
+The branding phase + every UI feature MUST be filled by invoking these
+skills (already installed globally on this Claude Code host):
+
+| Skill | Use for |
+|---|---|
+| `/emil-design-eng` | Design engineering discipline; tactile, motion-aware |
+| `/impeccable` | Pixel-level craft — no half-baked components |
+| `/taste-skill` | Taste calibration across typography / colour / hierarchy |
+| `/shadcn-ui` | Every component from ui.shadcn.com/docs/components |
+| `/frontend-design` | High-quality production-grade frontend code |
+
+When phase 5 emits a feature with `skill: "/shadcn-ui + /taste-skill"`,
+the worker MUST invoke those skills — not paraphrase them.
+
+## How to run
+
+```bash
+# 1. Initialise the project (Q1-Q5 picker if no flags)
+omega genesis new <slug> --intent "<one-line brief>"
+
+# 2. Advance through every phase
+omega genesis run <slug>
+
+# 3. (resume after a clear / crash)
+omega genesis status <slug>      # see where you are
+omega genesis run <slug>          # picks up at the next phase
+
+# 4. Hand off to the plan executor
+omega plan build <slug>
+omega plan next <slug>             # → the worker's brief
+```
+
+## After Genesis completes
+
+The pipeline ends with `docs/GENESIS-COMPLETE.md`. The next step is the
+**v0.19 Plan executor** (`/plan` skill). The plan executor reads
+`plan/DAG.json`, loads it into a per-project SQLite store, and refuses
+to mark a task done until every `depends_on` is VERIFIED. The agent
+NEVER sees the full backlog — only the next eligible task.
+
+## What this skill does NOT do
+
+- It does NOT write features in markdown freehand — the structure is
+  generated by `phases.py` in deterministic order; you fill the TODOs.
+- It does NOT touch any project other than `<slug>` — no shared CWD.
+- It does NOT skip phases. The state machine enforces order.
+
+## When something goes wrong
+
+- `omega genesis status <slug>` → see where the pipeline stopped.
+- A phase failed mid-way? Re-run `omega genesis run <slug>` — the
+  orchestrator only re-runs phases that aren't marked done.
+- Want to redo a phase? `omega genesis run <slug> --phase market`.
+- Want to start over? `omega genesis delete <slug> --yes && omega genesis new <slug>`.
+
+---
+
+**Argument: `$slug` (kebab-case)**, optional **`$intent`** (one-line brief).
+The slug becomes the directory name AND the Telegram topic name AND the
+git repo name. Pick well.