@agentikos/omega-os 0.2.0 → 0.19.5

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",
+]

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

@@ -0,0 +1,262 @@
+"""Genesis orchestrator — walks the state machine, writes the files,
+flips PROJECT.yaml after each phase.
+
+Why this lives in a separate file from ``state.py`` + ``phases.py``
+-------------------------------------------------------------------
+
+  * ``state.py`` is pure data + atomic IO (testable without phases).
+  * ``phases.py`` is pure content generation (testable without IO).
+  * ``orchestrator.py`` is the boring glue that sequences them with
+    proper error handling, resume semantics, and progress reporting.
+
+Resume semantics
+----------------
+
+Every call to :meth:`GenesisOrchestrator.run` reads PROJECT.yaml first,
+picks the next unfinished phase via :func:`GenesisState.next_phase`,
+runs it, persists the artifacts atomically, then flips the state. If
+any phase raises, the state is NOT flipped — re-running picks up at the
+same phase. This makes Genesis idempotent and crash-safe.
+"""
+from __future__ import annotations
+
+import os
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+from omega_engine.genesis.state import (
+    GenesisState,
+    PHASES,
+    load_state,
+    project_root,
+    save_state,
+)
+from omega_engine.genesis import phases as _phases
+
+
+# Phase → callable mapping. Each callable returns a list[FileSpec].
+_PHASE_FUNCS: dict[str, Callable[[GenesisState], list[_phases.FileSpec]]] = {
+    # "stack" is handled separately because it needs operator answers,
+    # not deterministic content. The orchestrator calls into stack.pick_stack
+    # before this map is consulted.
+    "vision": _phases.phase_vision,
+    "market": _phases.phase_market,
+    "branding": _phases.phase_branding,
+    "prd": _phases.phase_prd,
+    "features": _phases.phase_features,
+    "plan": _phases.phase_plan,
+}
+
+
+# ---------------------------------------------------------------------------
+# Phase result
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class PhaseResult:
+    phase: str
+    files_written: list[str] = field(default_factory=list)
+    elapsed_s: float = 0.0
+    skipped: bool = False           # phase was already done, we no-op'd
+    error: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return not self.error
+
+
+# ---------------------------------------------------------------------------
+# Atomic write helper — same pattern as state.py
+# ---------------------------------------------------------------------------
+
+
+def _atomic_write(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(
+        path.suffix + f".tmp.{os.getpid()}.{threading.get_ident()}"
+    )
+    fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o644)
+    with os.fdopen(fd, "w") as fh:
+        fh.write(content)
+        fh.flush()
+        try:
+            os.fsync(fh.fileno())
+        except OSError:
+            pass
+    os.replace(tmp, path)
+
+
+# ---------------------------------------------------------------------------
+# Orchestrator
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class GenesisOrchestrator:
+    """Drives a Genesis pipeline for one project.
+
+    Construct with the slug + optional ``omega_home`` (defaults to
+    ``$OMEGA_HOME``). Then call :meth:`run` to advance one phase or
+    :meth:`run_all` to walk to completion.
+
+    The orchestrator is single-project — to drive multiple, create one
+    orchestrator per slug. Per-project isolation is enforced by the
+    :func:`project_root` resolver in ``state.py``.
+    """
+
+    slug: str
+    omega_home: str | Path | None = None
+
+    # ----- runtime helpers ------------------------------------------------
+
+    def _state(self) -> GenesisState:
+        return load_state(self.slug, omega_home=self.omega_home)
+
+    def _persist(self, state: GenesisState) -> None:
+        save_state(state, omega_home=self.omega_home)
+
+    def _root(self) -> Path:
+        return project_root(self.slug, omega_home=self.omega_home)
+
+    # ----- single-phase runner --------------------------------------------
+
+    def run(self, *, only: str | None = None) -> PhaseResult:
+        """Advance ONE phase.
+
+        ``only`` (optional) forces the orchestrator to run that specific
+        phase — even if it's already marked done. Useful for "regen the
+        PRD after I changed the vision".
+
+        Returns a :class:`PhaseResult`. On error, ``error`` is set and
+        the state is NOT flipped (the next call retries the same phase).
+        """
+        import time as _t
+        started = _t.time()
+        state = self._state()
+        phase = only or state.next_phase()
+        if phase is None:
+            return PhaseResult(phase="(complete)", elapsed_s=0.0, skipped=True)
+
+        # Sanity: phase must be one of the known phases
+        if phase not in PHASES:
+            return PhaseResult(
+                phase=phase, error=f"unknown phase {phase!r}",
+            )
+
+        # Stack phase is special — it has no doc output; it just records
+        # the operator's stack choice (already done at init_project time
+        # OR via `omega genesis stack`). We just mark it done.
+        if phase == "stack":
+            if not state.is_phase_done("stack"):
+                state.mark_phase_done("stack")
+                self._persist(state)
+            return PhaseResult(
+                phase="stack",
+                files_written=[],
+                elapsed_s=round(_t.time() - started, 3),
+                skipped=False,
+            )
+
+        fn = _PHASE_FUNCS.get(phase)
+        if fn is None:
+            return PhaseResult(
+                phase=phase, error=f"no generator for phase {phase!r}",
+            )
+
+        try:
+            specs = fn(state)
+        except Exception as exc:  # noqa: BLE001
+            return PhaseResult(
+                phase=phase, error=f"generator raised: {exc!r}",
+                elapsed_s=round(_t.time() - started, 3),
+            )
+
+        root = self._root()
+        written: list[str] = []
+        for spec in specs:
+            dest = root / spec.rel_path
+            try:
+                _atomic_write(dest, spec.content)
+            except OSError as exc:
+                return PhaseResult(
+                    phase=phase,
+                    error=f"failed to write {dest}: {exc}",
+                    files_written=written,
+                    elapsed_s=round(_t.time() - started, 3),
+                )
+            written.append(spec.rel_path)
+
+        # Flip state ATOMICALLY only after every file was written.
+        state.mark_phase_done(phase)
+        self._persist(state)
+
+        return PhaseResult(
+            phase=phase,
+            files_written=written,
+            elapsed_s=round(_t.time() - started, 3),
+            skipped=False,
+        )
+
+    # ----- multi-phase runner ---------------------------------------------
+
+    def run_all(
+        self,
+        *,
+        max_phases: int | None = None,
+        stop_at: str | None = None,
+    ) -> list[PhaseResult]:
+        """Walk forward through every undone phase.
+
+        ``max_phases`` caps the loop (useful for tests). ``stop_at`` stops
+        AFTER finishing the named phase (e.g. "branding" to halt before
+        PRD generation).
+        """
+        out: list[PhaseResult] = []
+        steps = 0
+        while True:
+            res = self.run()
+            if res.skipped and res.phase == "(complete)":
+                break
+            out.append(res)
+            if not res.ok:
+                break
+            steps += 1
+            if max_phases is not None and steps >= max_phases:
+                break
+            if stop_at and res.phase == stop_at:
+                break
+        return out
+
+    # ----- read-only helpers ----------------------------------------------
+
+    def status(self) -> dict[str, Any]:
+        """Snapshot of where this project is in the pipeline."""
+        try:
+            state = self._state()
+        except FileNotFoundError:
+            return {
+                "slug": self.slug,
+                "exists": False,
+                "phase": None,
+                "completed_phases": [],
+                "remaining_phases": list(PHASES),
+            }
+        return {
+            "slug": state.slug,
+            "name": state.name,
+            "exists": True,
+            "intent": state.intent,
+            "phase": state.phase,
+            "completed_phases": state.completed_phases,
+            "remaining_phases": [
+                p for p in PHASES if p not in state.completed_phases
+            ],
+            "stack": state.stack.to_dict(),
+            "repo": state.repo.to_dict(),
+            "created_at": state.created_at,
+            "updated_at": state.updated_at,
+            "root": str(self._root()),
+        }