@agentikos/omega-os 0.1.0 → 0.19.5

package/omega/Agentik_Engine/omega_engine/educators/skill.py

@@ -0,0 +1,69 @@
+"""`skill-educator` — generates new skill specs + maintains the catalog.
+
+The signature: a skill spec is the contract between the engine and a unit of
+capability (a `/command`). It declares: the trigger phrases, the inputs, the
+steps, the artifacts it produces, the verification gate, and the failure modes.
+
+Target SSOT path: ``Agentik_SSOT/skills/<name>.md``.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from omega_engine.educators.base import EducatorProposal, run_education
+from omega_engine.provider import AgentProvider
+
+_INSTRUCTIONS = """\
+Produce ONE skill spec the engine will load as a runnable capability. The spec
+MUST contain, in order, these sections:
+
+  1. Name + one-line purpose (the question the skill answers).
+  2. Trigger phrases (case-insensitive, FR + EN if applicable) — the strings
+     the router matches against. Be exhaustive: a missing trigger means the
+     skill never fires.
+  3. Inputs schema — every parameter, with type + whether it is required +
+     what the default is. No optional-and-undocumented fields.
+  4. Steps — numbered, each step one verb in imperative voice with a verify
+     checkpoint. State the input and output of each step.
+  5. Artifacts produced — the file/path the skill writes, the schema of any
+     structured output.
+  6. Verification gate — which forensic audit(s) (from the Quality Arsenal)
+     run on the artifact, and the minimum score. If none applies, state that
+     and explain why.
+  7. Failure modes — list at least 3 ways the skill can fail and what the
+     engine does in each (retry, escalate, abort).
+
+The spec MUST NOT:
+  - paraphrase another existing skill — state the boundary if related.
+  - omit the audit gate (every skill is auditable, no exceptions).
+  - hand-wave the failure modes.
+
+Format the artifact as Markdown.
+"""
+
+
+class SkillEducator:
+    """Generates skill specs for the SSOT skill catalog."""
+
+    name = "skill"
+    domain = "skills"
+
+    def generate(
+        self,
+        intent: str,
+        context: dict[str, Any],
+        provider: AgentProvider,
+    ) -> EducatorProposal:
+        skill_name = str(context.get("skill_name", "new-skill"))
+        target_path = f"Agentik_SSOT/skills/{skill_name}.md"
+        return run_education(
+            educator_name=self.name,
+            domain=self.domain,
+            intent=intent,
+            target_kind="skill",
+            target_path=target_path,
+            domain_instructions=_INSTRUCTIONS,
+            context={**context, "skill_name": skill_name},
+            provider=provider,
+            artifact_id=skill_name,
+        )

package/omega/Agentik_Engine/omega_engine/envelope.py

@@ -0,0 +1,219 @@
+"""Mission envelope — the bridge between a Task and the provider's request.
+
+The executor used to send the agent ONLY a bare prompt ("subtask 1"). That's
+not how AISB-style orchestration works: an Oracle needs to know who it is,
+what the user asked for verbatim, what its parent already decided, and the
+contract for declaring completion. The envelope is that wrapper.
+
+Two things come out of ``build_envelope``:
+
+* ``system`` — the role's full agent prompt (from ``omega_engine.prompts``)
+  plus the orchestration contract appended at the end. This goes in the
+  provider's ``system`` parameter.
+* ``user`` — the user-visible content: the original intent, the parent
+  context, the plan-so-far, and any role-specific data. This goes in
+  ``messages``.
+
+For programmatic roles (mock, educators, RAG sub-roles), the envelope still
+works but the contract block is skipped — those agents don't dispatch.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+# Roles that DISPATCH (return a plan). They need the dispatcher contract.
+DISPATCHER_ROLES = {
+    "aisb", "oracle", "manager", "architect", "keymaker", "morpheus",
+}
+# Roles that EXECUTE (return artifacts + claimed_done).
+EXECUTOR_ROLES = {"worker", "construct", "link"}
+# Roles that VERIFY (return a verdict).
+VERIFIER_ROLES = {"audit", "verifier", "seraph"}
+# Read-only roles — observe the system, propose, never act.
+READ_ONLY_ROLES = {"pythia", "neo", "niobe", "merovingian", "zion"}
+# Improvement / learning roles — analyse outcomes, propose tuning.
+LEARNER_ROLES = {"smith"}
+
+
+@dataclass
+class EnvelopeContext:
+    """Everything the envelope needs to know about a task's place in the world."""
+
+    role: str
+    intent: str                                              # user prompt verbatim
+    mission_id: str = ""
+    task_id: str = ""
+    parent_role: str | None = None
+    parent_intent: str | None = None
+    plan_so_far: list[dict[str, Any]] = field(default_factory=list)
+    sibling_states: dict[str, str] = field(default_factory=dict)
+    available_tools: list[str] = field(default_factory=list)
+    project: dict[str, Any] | None = None                    # name, slug, path
+    done_json_path: str | None = None                        # where the worker writes done
+    verify_cmd: str | None = None
+    extras: dict[str, Any] = field(default_factory=dict)
+
+
+def _dispatcher_contract() -> str:
+    return (
+        "## ORCHESTRATION CONTRACT (dispatcher)\n\n"
+        "You are a DISPATCHER. You break the mission into atomic subtasks\n"
+        "and respond with a JSON array of child tasks. Format strictly:\n\n"
+        "```json\n"
+        "[\n"
+        '  {"role": "worker", "spec": {\n'
+        '    "task": "<one concrete actionable instruction>",\n'
+        '    "verify_cmd": "<shell command that returns 0 iff the task is truly done>",\n'
+        '    "files_owned": ["<path/glob>", ...],\n'
+        '    "context": {<any extra data the worker will need>}\n'
+        "  }},\n"
+        "  ...\n"
+        "]\n"
+        "```\n\n"
+        "Rules:\n"
+        "1. Preserve the user's intent verbatim — never paraphrase it away.\n"
+        "2. Each subtask MUST be small enough to fit in one worker context.\n"
+        "3. `verify_cmd` is the ground truth — if it exits 0, the worker is done.\n"
+        "4. JSON ONLY — no prose around the array. No code fences except the one above.\n"
+        "5. Your reply IS the plan. The engine will dispatch each child as a task.\n"
+    )
+
+
+def _executor_contract(done_json_path: str | None) -> str:
+    path = done_json_path or "Agentik_Runtime/sessions/<task_id>/.done.json"
+    return (
+        "## ORCHESTRATION CONTRACT (executor / worker)\n\n"
+        "You are a WORKER. You produce concrete artifacts and prove you're done.\n"
+        f"When finished, you WRITE a JSON file at `{path}` with this exact schema:\n\n"
+        "```json\n"
+        "{\n"
+        '  "status": "done_clean" | "pending" | "failed",\n'
+        '  "summary": "<one-paragraph what you did and why>",\n'
+        '  "files_changed": ["<relative path>", ...],\n'
+        '  "artifacts": {"<key>": "<value>", ...},\n'
+        '  "pending_actions": ["<thing the next worker / human should do>", ...],\n'
+        '  "errors": ["<actionable error>", ...]\n'
+        "}\n"
+        "```\n\n"
+        "Rules:\n"
+        "1. NEVER write `done_clean` if a `verify_cmd` would fail. Run it first.\n"
+        "2. `pending` means you did real work but more is needed — list it.\n"
+        "3. `failed` is honest. The engine prefers honesty over fake success.\n"
+        "4. The completion-verification gate reads this file. Lying = REJECTED.\n"
+    )
+
+
+def _verifier_contract() -> str:
+    return (
+        "## ORCHESTRATION CONTRACT (verifier)\n\n"
+        "You are a VERIFIER. The worker has just claimed done. Your job is to\n"
+        "prove or disprove that claim by running real checks (not just reading\n"
+        "code). Respond with a JSON object:\n\n"
+        "```json\n"
+        '{"verified": true|false, "score": 0-100, "confidence": "low|med|high",\n'
+        ' "findings": [{"audit":"...","severity":"low|med|high|crit","msg":"..."}],\n'
+        ' "fix_plan": ["<actionable, ordered>", ...]}\n'
+        "```\n\n"
+        "Rules:\n"
+        "1. Code lies, comments lie — only runtime tells the truth. Run things.\n"
+        "2. Bias toward `false` — earn a `true` with concrete evidence.\n"
+        "3. Every PASS must cite at least 3 concrete checks.\n"
+    )
+
+
+def _section(title: str, body: str | None) -> str:
+    if not body:
+        return ""
+    return f"\n\n## {title}\n\n{body}"
+
+
+def build_envelope(
+    omega_home: str | Path,
+    ctx: EnvelopeContext,
+) -> dict[str, str]:
+    """Return ``{system, user}`` strings ready to pass to a provider.
+
+    The ``system`` part loads the role's prompt from
+    ``Agentik_SSOT/agents/`` and appends the appropriate orchestration
+    contract. If no agent file exists for the role, a minimal generic
+    envelope is built (one line of identity + the contract).
+    """
+    # Local import to avoid cycles.
+    from omega_engine.prompts import load_agent_prompt
+
+    home = Path(omega_home)
+    agent_prompt = load_agent_prompt(home, ctx.role) or (
+        f"You are an Omega OS {ctx.role.upper()} agent."
+    )
+
+    if ctx.role in DISPATCHER_ROLES:
+        contract = _dispatcher_contract()
+    elif ctx.role in EXECUTOR_ROLES:
+        contract = _executor_contract(ctx.done_json_path)
+    elif ctx.role in VERIFIER_ROLES:
+        contract = _verifier_contract()
+    else:
+        # Programmatic / specialised roles use their own internal contract.
+        contract = ""
+
+    system_parts = [agent_prompt]
+    if contract:
+        system_parts.append(f"\n\n{contract}")
+    system = "".join(system_parts).strip()
+
+    # ---- user message ------------------------------------------------------
+    user_blocks: list[str] = []
+
+    user_blocks.append(f"# USER INTENT (verbatim)\n\n{ctx.intent.strip()}")
+
+    if ctx.parent_intent and ctx.parent_role:
+        user_blocks.append(
+            f"## Parent task ({ctx.parent_role})\n\n{ctx.parent_intent.strip()}"
+        )
+
+    if ctx.plan_so_far:
+        user_blocks.append(
+            "## Plan so far\n\n"
+            "```json\n" + json.dumps(ctx.plan_so_far, indent=2) + "\n```"
+        )
+
+    if ctx.sibling_states:
+        user_blocks.append(
+            "## Sibling states\n\n```json\n"
+            + json.dumps(ctx.sibling_states, indent=2)
+            + "\n```"
+        )
+
+    if ctx.available_tools:
+        user_blocks.append(
+            "## Available tools\n\n- " + "\n- ".join(ctx.available_tools)
+        )
+
+    if ctx.project:
+        user_blocks.append(
+            f"## Project context\n\nname: {ctx.project.get('name')}\n"
+            f"slug: {ctx.project.get('slug')}\n"
+            f"path: {ctx.project.get('path')}"
+        )
+
+    if ctx.verify_cmd:
+        user_blocks.append(
+            f"## Verify command\n\n```bash\n{ctx.verify_cmd}\n```"
+        )
+
+    if ctx.done_json_path and ctx.role in EXECUTOR_ROLES:
+        user_blocks.append(
+            f"## Done file\n\nWrite your completion JSON to: `{ctx.done_json_path}`"
+        )
+
+    if ctx.task_id:
+        user_blocks.append(f"## Task id\n\n`{ctx.task_id}`")
+    if ctx.mission_id:
+        user_blocks.append(f"## Mission id\n\n`{ctx.mission_id}`")
+
+    user = "\n\n".join(user_blocks)
+    return {"system": system, "user": user}

package/omega/Agentik_Engine/omega_engine/executor.py

@@ -49,11 +49,21 @@ class Executor:
         bus: EventBus,
         router: ModelRouter,
         audit: AuditGate,
+        partial_policy: str = "fail_up",
     ) -> None:
+        # partial_policy: how a dispatcher reacts to a PARTIAL scope (a child
+        # FAILED). One of: "fail_up" (default — the dispatcher fails too),
+        # "accept_partial" (the dispatcher completes with the verified children
+        # only), "retry_failed" (one retry pass on failed children, then
+        # fail_up if still PARTIAL). Declared per-topology in
+        # Agentik_Orchestration/topologies/<name>.yaml -> policy.on_partial.
+        if partial_policy not in ("fail_up", "accept_partial", "retry_failed"):
+            raise ValueError(f"unknown partial_policy: {partial_policy}")
         self._store = store
         self._bus = bus
         self._router = router
         self._audit = audit
+        self._partial_policy = partial_policy
         self._tasks: dict[str, Task] = {}
 
     # -- public ---------------------------------------------------------------
@@ -89,8 +99,17 @@ class Executor:
         return reduce_task(self._store.events_for(task_id))
 
     def _run(self, task: Task, mission_id: str) -> None:
-        self._emit(task.id, EventType.CREATED,
-                   {"role": task.role, "kind": task.kind.value, "mission_id": mission_id})
+        # Carry the intent/task description in the CREATED payload so the
+        # event log + semantic memory have something searchable per task.
+        intent = (
+            task.spec.get("intent") or task.spec.get("task") or ""
+        )
+        self._emit(task.id, EventType.CREATED, {
+            "role": task.role,
+            "kind": task.kind.value,
+            "mission_id": mission_id,
+            "spec": {"intent": str(intent)[:500]} if intent else {},
+        })
         self._emit(task.id, EventType.DISPATCHED)
         self._emit(task.id, EventType.STARTED)
         if task.kind is Kind.EXECUTOR:
@@ -102,9 +121,8 @@ class Executor:
     def _run_dispatcher(self, task: Task, mission_id: str) -> None:
         provider = self._router.resolve(task.role)
         prompt = task.spec.get("intent") or task.spec.get("task") or task.role
-        result = provider.run(
-            AgentRequest(role=task.role, prompt=str(prompt), context=task.spec)
-        )
+        result = provider.run(self._build_request(task, mission_id, str(prompt)))
+        self._emit_usage(task, provider, result, mission_id)
         children: list[Task] = []
         for item in result.plan:
             child_role = item.get("role", "worker")
@@ -119,29 +137,59 @@ class Executor:
             children.append(child)
 
         status = scope_status([self._state(c.id) for c in children])
-        if status is ScopeStatus.JOINABLE:
+
+        # Per-topology PARTIAL policy
+        if status is ScopeStatus.PARTIAL and self._partial_policy == "retry_failed":
+            # one retry pass for every FAILED child — children are re-spawned as
+            # fresh tasks, each with their own budget. If they all pass, the
+            # scope becomes JOINABLE; otherwise we fall through to fail_up.
+            failed_children = [c for c in children
+                               if self._state(c.id) is TaskState.FAILED]
+            for failed in failed_children:
+                replacement = self._new_task(
+                    kind=failed.kind, role=failed.role,
+                    spec=failed.spec, parent_id=task.id, mission_id=mission_id,
+                )
+                self._run(replacement, mission_id)
+                children.append(replacement)
+            status = scope_status([self._state(c.id) for c in children])
+
+        accept_partial = (
+            status is ScopeStatus.PARTIAL
+            and self._partial_policy == "accept_partial"
+        )
+
+        if status is ScopeStatus.JOINABLE or accept_partial:
             # the barrier resolved — the dispatcher may now close
-            self._emit(task.id, EventType.SCOPE_JOINABLE, {"children": len(children)})
+            self._emit(task.id, EventType.SCOPE_JOINABLE,
+                       {"children": len(children),
+                        "partial_accepted": accept_partial})
             self._emit(task.id, EventType.CLAIMED_DONE)
             self._emit(task.id, EventType.VERIFYING)
-            self._emit(task.id, EventType.VERIFIED, {"reason": "all children verified"})
+            self._emit(task.id, EventType.VERIFIED,
+                       {"reason": "partial accepted" if accept_partial
+                        else "all children verified"})
             self._emit(task.id, EventType.COMPLETED)
         else:
-            # PARTIAL — a child failed. on_partial = fail_up (children already
-            # retried within their own budget). Honest partial failure.
+            # PARTIAL or RUNNING under fail_up. RUNNING here means recursion
+            # left non-terminal children — that is a real bug. PARTIAL under
+            # fail_up is honest failure.
             failed = [c.id for c in children
                       if self._state(c.id) is TaskState.FAILED]
             self._emit(task.id, EventType.FAILED,
-                       {"reason": "partial scope", "failed_children": failed})
+                       {"reason": "partial scope" if status is ScopeStatus.PARTIAL
+                        else "scope unresolved",
+                        "failed_children": failed,
+                        "policy": self._partial_policy})
 
     def _run_worker(self, task: Task) -> None:
         provider = self._router.resolve(task.role)
+        prompt = str(task.spec.get("task", task.role))
+        mission_id = task.spec.get("mission_id", "")
         for attempt in range(task.budget.max_iterations):
-            result = provider.run(AgentRequest(
-                role=task.role,
-                prompt=str(task.spec.get("task", task.role)),
-                context=task.spec,
-            ))
+            result = provider.run(self._build_request(task, mission_id, prompt))
+            self._maybe_persist_done(task, result)
+            self._emit_usage(task, provider, result, mission_id)
             self._emit(task.id, EventType.CLAIMED_DONE, {"attempt": attempt + 1})
             self._emit(task.id, EventType.VERIFYING)
             verdict = self._audit.verify({
@@ -151,6 +199,7 @@ class Executor:
                 "changed": result.artifacts.get("files", []),
                 "path": str(task.spec.get("path", ".")),
             })
+            self._attach_audit_to_done(task.id, verdict)
             if verdict.verified:
                 self._emit(task.id, EventType.VERIFIED, {
                     "score": verdict.score,
@@ -165,3 +214,133 @@ class Executor:
                 self._emit(task.id, EventType.STARTED)
         # budget exhausted — honest failure, the deadman clause terminates it
         self._emit(task.id, EventType.FAILED, {"reason": "audit budget exhausted"})
+
+    # ---- envelope + done.json plumbing -------------------------------------
+
+    def _build_request(self, task: Task, mission_id: str, prompt: str) -> AgentRequest:
+        """Build a request enriched with the role's system prompt + context.
+
+        Failures here MUST NOT crash the executor — the engine has always
+        worked with a bare prompt, and old test providers don't read
+        ``request.system``. So we fall back to the legacy AgentRequest if
+        the envelope build fails for any reason.
+        """
+        try:
+            import os
+            from pathlib import Path
+            from omega_engine.envelope import (
+                EnvelopeContext, build_envelope,
+            )
+            from omega_engine.done_signal import done_path
+
+            omega_home = Path(os.environ.get(
+                "OMEGA_HOME", str(Path.home() / "Omega"),
+            ))
+            parent = self._tasks.get(task.parent_id or "")
+            parent_role = parent.role if parent else None
+            parent_intent = (
+                parent.spec.get("intent") if parent else None
+            ) or (parent.spec.get("task") if parent else None)
+
+            ctx = EnvelopeContext(
+                role=task.role,
+                intent=prompt,
+                mission_id=mission_id,
+                task_id=task.id,
+                parent_role=parent_role,
+                parent_intent=parent_intent,
+                verify_cmd=task.spec.get("verify_cmd"),
+                done_json_path=str(done_path(omega_home, task.id)),
+                project=task.spec.get("project"),
+            )
+            env = build_envelope(omega_home, ctx)
+            return AgentRequest(
+                role=task.role, prompt=env["user"], context=task.spec,
+                system=env["system"],
+            )
+        except Exception:  # noqa: BLE001
+            return AgentRequest(
+                role=task.role, prompt=prompt, context=task.spec,
+            )
+
+    def _emit_usage(
+        self, task: Task, provider, result, mission_id: str,
+    ) -> None:
+        """Emit a ``task.usage`` event so the BillingAggregator sees real
+        per-account cost — only when the provider returned non-zero usage.
+
+        ClaudeMaxProvider returns a ``cost_usd`` from Claude Code's own
+        billing computation; we propagate it as-is. Provider id is the
+        ``account_id`` fallback when the operator hasn't pinned this task
+        to a specific account.
+        """
+        try:
+            usage = dict(getattr(result, "usage", {}) or {})
+            if not usage:
+                return
+            if not usage.get("account_id"):
+                # Best-effort: use the provider id as the account label.
+                # When the operator wires multiple Claude Max accounts,
+                # whatever picks one explicitly should also set
+                # account_id on the AgentResult.usage.
+                usage["account_id"] = getattr(provider, "id", "default")
+            self._emit(task.id, EventType.HEARTBEAT, {
+                "kind": "usage", "mission_id": mission_id,
+                "usage": usage, "role": task.role,
+            })
+        except Exception:  # noqa: BLE001 — usage emit must never break the loop
+            pass
+
+    def _maybe_persist_done(self, task: Task, result) -> None:
+        """If the provider returned a structured artifact and no done file
+        exists yet, write one so the audit gate / AISB always have something
+        to read."""
+        try:
+            import os
+            from pathlib import Path
+            from omega_engine.done_signal import (
+                DoneSignal, done_path, read_done, write_done,
+            )
+            omega_home = Path(os.environ.get(
+                "OMEGA_HOME", str(Path.home() / "Omega"),
+            ))
+            # If the worker (or the provider stub) already wrote the file,
+            # respect it.
+            existing = None
+            try:
+                existing = read_done(omega_home, task.id)
+            except Exception:  # noqa: BLE001
+                existing = None
+            if existing is not None:
+                return
+            # Build a synthetic done from the provider result.
+            arts = getattr(result, "artifacts", None) or {}
+            signal = DoneSignal(
+                status="done_clean" if getattr(result, "claimed_done", False)
+                else "failed",
+                summary=str(arts.get("summary") or getattr(result, "text", "")),
+                files_changed=list(arts.get("files") or []),
+                artifacts=arts,
+            )
+            write_done(omega_home, task.id, signal)
+        except Exception:  # noqa: BLE001
+            pass
+
+    def _attach_audit_to_done(self, task_id: str, verdict) -> None:
+        try:
+            import os
+            from pathlib import Path
+            from omega_engine.done_signal import attach_audit_to_done
+            omega_home = Path(os.environ.get(
+                "OMEGA_HOME", str(Path.home() / "Omega"),
+            ))
+            attach_audit_to_done(omega_home, task_id, {
+                "verified": bool(getattr(verdict, "verified", False)),
+                "score": int(getattr(verdict, "score", 0) or 0),
+                "findings": [
+                    getattr(f, "audit", str(f))
+                    for f in getattr(verdict, "findings", []) or []
+                ],
+            })
+        except Exception:  # noqa: BLE001
+            pass

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

@@ -0,0 +1,134 @@
+"""Genesis — programmatic project genesis pipeline.
+
+The Genesis module owns the *upstream half* of a new project: from a one-line
+intent ("a SaaS for X") through to a complete docs tree + DAG-aware feature
+backlog ready for the v0.19 Plan executor to run for days.
+
+Why a programmatic pipeline, not a markdown skill
+-------------------------------------------------
+
+The pre-v0.18 ``/new`` / ``/prd`` / ``/planner`` skills were prompt-only.
+That worked for one-off demos but broke at scale:
+
+  * No isolation between concurrent projects (shared CWD heuristics).
+  * No state machine — the agent re-did already-done phases on restart.
+  * No DAG on features — chronological order was implicit in the markdown
+    filename, easily violated by a context-saturated agent.
+  * No quality gate — a half-written PRD landed in the same folder as a
+    finished one.
+
+Genesis fixes the four root causes:
+
+  1. **Strict project isolation.** Every file lands under
+     ``$OMEGA_HOME/Agentik_Coding/projects/<slug>/`` and nowhere else.
+     There is no ambient CWD leakage — every helper takes ``slug``
+     explicitly.
+  2. **State machine in PROJECT.yaml.** Phases are recorded; ``resume``
+     reads the file and picks up where the previous run stopped.
+  3. **DAG with explicit ``depends_on``.** Features carry a real
+     dependency graph; the v0.19 Plan reducer enforces it.
+  4. **Verified completion per phase.** Each phase has a verify_command;
+     the orchestrator refuses to advance the state until it passes.
+
+Phases
+------
+
+  Phase 0  Stack       — pick the technical + programmatic stack
+  Phase 1  Vision      — one-page product identity
+  Phase 2  Market      — 5 research files (competitors, ICP, pricing,
+                          channels, positioning)
+  Phase 3  Branding    — 3 files (identity, design system, motion)
+  Phase 4  PRD         — 9 files (PRD, tech, design, layouts, data,
+                          agent playbook, testing, changelog, glossary)
+  Phase 5  Features    — N files with explicit ``depends_on`` + wave +
+                          estimated_minutes + files_owned + verify_cmd
+  Phase 6  Plan        — handoff to v0.19 ``omega plan build``
+
+Output tree (per project, strictly isolated)
+--------------------------------------------
+
+::
+
+    $OMEGA_HOME/Agentik_Coding/projects/<slug>/
+      PROJECT.yaml                       state machine + stack config
+      HANDOFF.md                         created by v0.15 handoff
+      docs/
+        00-VISION.md
+        10-market/
+          11-COMPETITORS.md
+          12-ICP.md
+          13-PRICING-STRATEGY.md
+          14-GTM-CHANNELS.md
+          15-POSITIONING.md
+        20-brand/
+          21-BRAND-IDENTITY.md
+          22-DESIGN-SYSTEM.md
+          23-MOTION-LANGUAGE.md
+        30-prd/
+          31-PRD.md
+          32-TECH-ARCHITECTURE.md
+          33-DESIGN-SYSTEM-DETAIL.md
+          34-LAYOUTS.md
+          35-DATA-MODEL.md
+          36-AGENT-PLAYBOOK.md
+          37-TESTING-STRATEGY.md
+          38-CHANGELOG.md
+          39-GLOSSARY.md
+        40-features/
+          F-001-<slug>.md
+          F-002-<slug>.md
+          ...
+      plan/
+        DAG.json                         features → DAG for v0.19
+
+Public API
+----------
+
+  * :class:`GenesisState` — the dataclass mirroring PROJECT.yaml
+  * :func:`init_project` — create the skeleton + PROJECT.yaml
+  * :func:`load_state` / :func:`save_state` — atomic read/write of state
+  * :class:`GenesisOrchestrator` — runs phases sequentially with verify
+  * :func:`project_root` — strict resolver for the per-project directory
+
+The CLI surface lives in :mod:`omega_engine.cli` as ``omega genesis``.
+"""
+from __future__ import annotations
+
+from omega_engine.genesis.state import (
+    PHASES,
+    GenesisState,
+    StackConfig,
+    init_project,
+    load_state,
+    project_root,
+    save_state,
+)
+from omega_engine.genesis.stack import (
+    Stack,
+    StackQuestion,
+    default_stack,
+    pick_stack,
+    stack_questions,
+)
+from omega_engine.genesis.orchestrator import (
+    GenesisOrchestrator,
+    PhaseResult,
+)
+
+
+__all__ = [
+    "PHASES",
+    "GenesisState",
+    "StackConfig",
+    "Stack",
+    "StackQuestion",
+    "GenesisOrchestrator",
+    "PhaseResult",
+    "init_project",
+    "load_state",
+    "save_state",
+    "project_root",
+    "pick_stack",
+    "stack_questions",
+    "default_stack",
+]