arkaos 2.0.0-alpha.1

package/core/runtime/gemini_cli.py

@@ -0,0 +1,68 @@
+"""Gemini CLI runtime adapter.
+
+Google's Gemini CLI. Uses GEMINI.md for instructions and activate_skill for skills.
+"""
+
+from pathlib import Path
+from os.path import expanduser
+
+from core.runtime.base import RuntimeAdapter, RuntimeConfig, AgentContext, AgentResult
+
+
+class GeminiCliAdapter(RuntimeAdapter):
+    """Adapter for Google's Gemini CLI."""
+
+    def get_config(self) -> RuntimeConfig:
+        home = Path(expanduser("~"))
+        return RuntimeConfig(
+            id="gemini",
+            name="Gemini CLI",
+            config_dir=home / ".gemini",
+            skills_dir=home / ".gemini" / "skills",
+            settings_file=home / ".gemini" / "settings.json",
+            supports_hooks=False,
+            supports_subagents=True,
+            supports_mcp=True,
+            max_context_tokens=1_000_000,
+        )
+
+    def inject_context(self, layers: dict[str, str]) -> str:
+        """Gemini receives context via GEMINI.md instruction file."""
+        parts = []
+        for name, content in layers.items():
+            parts.append(f"## {name}\n{content}")
+        return "\n\n".join(parts)
+
+    def dispatch_agent(self, context: AgentContext) -> AgentResult:
+        return AgentResult(
+            agent_id=context.agent_id,
+            status="dispatched",
+            output=f"Agent {context.agent_id} dispatched via Gemini CLI",
+            metadata={"runtime": "gemini"},
+        )
+
+    def spawn_subagent(self, context: AgentContext) -> AgentResult:
+        return AgentResult(
+            agent_id=context.agent_id,
+            status="dispatched",
+            output=f"Subagent {context.agent_id} spawned via Gemini CLI",
+            metadata={"runtime": "gemini", "pattern": "subagent"},
+        )
+
+    def read_file(self, path: str) -> str:
+        raise NotImplementedError("Use Gemini CLI's native file read")
+
+    def write_file(self, path: str, content: str) -> None:
+        raise NotImplementedError("Use Gemini CLI's native file write")
+
+    def edit_file(self, path: str, old: str, new: str) -> None:
+        raise NotImplementedError("Use Gemini CLI's native file edit")
+
+    def execute_command(self, command: str, timeout: int = 120) -> tuple[str, int]:
+        raise NotImplementedError("Use Gemini CLI's native shell execution")
+
+    def search_files(self, pattern: str, path: str = ".") -> list[str]:
+        raise NotImplementedError("Use Gemini CLI's native file search")
+
+    def search_content(self, pattern: str, path: str = ".") -> list[str]:
+        raise NotImplementedError("Use Gemini CLI's native content search")

package/core/runtime/registry.py

@@ -0,0 +1,86 @@
+"""Runtime registry — maps runtime IDs to adapter instances."""
+
+from core.runtime.base import RuntimeAdapter
+from core.runtime.claude_code import ClaudeCodeAdapter
+from core.runtime.codex_cli import CodexCliAdapter
+from core.runtime.gemini_cli import GeminiCliAdapter
+from core.runtime.cursor import CursorAdapter
+
+_ADAPTERS: dict[str, type[RuntimeAdapter]] = {
+    "claude-code": ClaudeCodeAdapter,
+    "codex": CodexCliAdapter,
+    "gemini": GeminiCliAdapter,
+    "cursor": CursorAdapter,
+}
+
+
+def get_adapter(runtime_id: str) -> RuntimeAdapter:
+    """Get an adapter instance for the given runtime ID.
+
+    Args:
+        runtime_id: One of 'claude-code', 'codex', 'gemini', 'cursor'
+
+    Returns:
+        Instantiated RuntimeAdapter for the runtime.
+
+    Raises:
+        ValueError: If runtime_id is not recognized.
+    """
+    adapter_cls = _ADAPTERS.get(runtime_id)
+    if adapter_cls is None:
+        supported = ", ".join(_ADAPTERS.keys())
+        raise ValueError(f"Unknown runtime: {runtime_id}. Supported: {supported}")
+    return adapter_cls()
+
+
+def detect_runtime() -> str:
+    """Detect which runtime is currently active.
+
+    Checks environment variables and process context to determine
+    which AI runtime is executing this code.
+
+    Returns:
+        Runtime ID string.
+    """
+    import os
+
+    # Check environment variables set by each runtime
+    if os.environ.get("CLAUDE_CODE"):
+        return "claude-code"
+    if os.environ.get("CODEX_CLI"):
+        return "codex"
+    if os.environ.get("GEMINI_CLI"):
+        return "gemini"
+    if os.environ.get("CURSOR_SESSION"):
+        return "cursor"
+
+    # Check for runtime-specific config directories
+    from pathlib import Path
+
+    home = Path.home()
+    if (home / ".claude" / "settings.json").exists():
+        return "claude-code"
+    if (home / ".codex").exists():
+        return "codex"
+    if (home / ".gemini").exists():
+        return "gemini"
+    if (home / ".cursor").exists():
+        return "cursor"
+
+    # Default to claude-code as primary runtime
+    return "claude-code"
+
+
+def list_runtimes() -> list[dict[str, str]]:
+    """List all supported runtimes with their status."""
+    results = []
+    for runtime_id, adapter_cls in _ADAPTERS.items():
+        adapter = adapter_cls()
+        config = adapter.get_config()
+        results.append({
+            "id": runtime_id,
+            "name": config.name,
+            "config_dir": str(config.config_dir),
+            "installed": config.config_dir.exists(),
+        })
+    return results

package/core/runtime/subagent.py

@@ -0,0 +1,201 @@
+"""Subagent Pattern — fresh agent instances per task.
+
+Each subagent gets a fresh context window, preventing context pollution
+between tasks. The orchestrator uses only 10-15% of its context to
+dispatch and collect results.
+
+Pattern: Orchestrator compacts task description + relevant context into
+a brief, dispatches to a subagent, and receives a structured result.
+
+Context budget:
+- Orchestrator: 10-15% of context window for dispatch + collection
+- Subagent: Full context window for task execution
+- Handoff artifact: ~379 tokens per agent switch (compacted persona + task)
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional, Any
+
+from core.agents.schema import Agent
+
+
+class SubagentStatus(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    TIMEOUT = "timeout"
+
+
+@dataclass
+class HandoffArtifact:
+    """Compacted context passed from orchestrator to subagent.
+
+    This is the ~379-token artifact that carries everything
+    the subagent needs to start working without full history.
+    """
+    task_id: str
+    task_description: str
+    agent_id: str
+    agent_role: str
+    agent_disc: str                  # Compact DISC label
+    department: str
+    relevant_files: list[str] = field(default_factory=list)
+    context_summary: str = ""        # Compacted prior context
+    constraints: list[str] = field(default_factory=list)
+    expected_output: str = ""
+    quality_criteria: list[str] = field(default_factory=list)
+
+    def to_prompt(self) -> str:
+        """Convert to a prompt string for the subagent."""
+        parts = [
+            f"# Task: {self.task_description}",
+            f"Agent: {self.agent_id} ({self.agent_role}, {self.agent_disc})",
+            f"Department: {self.department}",
+        ]
+        if self.context_summary:
+            parts.append(f"\n## Context\n{self.context_summary}")
+        if self.relevant_files:
+            parts.append(f"\n## Relevant Files\n" + "\n".join(f"- {f}" for f in self.relevant_files))
+        if self.constraints:
+            parts.append(f"\n## Constraints\n" + "\n".join(f"- {c}" for c in self.constraints))
+        if self.expected_output:
+            parts.append(f"\n## Expected Output\n{self.expected_output}")
+        if self.quality_criteria:
+            parts.append(f"\n## Quality Criteria\n" + "\n".join(f"- {q}" for q in self.quality_criteria))
+        return "\n".join(parts)
+
+    @property
+    def estimated_tokens(self) -> int:
+        """Estimate token count of this artifact."""
+        return len(self.to_prompt().split())
+
+
+@dataclass
+class SubagentResult:
+    """Result returned by a subagent."""
+    task_id: str
+    agent_id: str
+    status: SubagentStatus
+    output: str = ""
+    files_modified: list[str] = field(default_factory=list)
+    tokens_used: int = 0
+    duration_ms: int = 0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_summary(self, max_tokens: int = 200) -> str:
+        """Compact the result for the orchestrator's context.
+
+        The orchestrator doesn't need the full output, just a summary
+        to decide next steps.
+        """
+        words = self.output.split()
+        if len(words) <= max_tokens:
+            return self.output
+        return " ".join(words[:max_tokens]) + "..."
+
+
+class SubagentDispatcher:
+    """Dispatches tasks to fresh subagent instances.
+
+    The dispatcher creates HandoffArtifacts from agent definitions
+    and task descriptions, then delegates to the runtime adapter
+    for actual execution.
+    """
+
+    def __init__(self) -> None:
+        self._pending: dict[str, HandoffArtifact] = {}
+        self._results: dict[str, SubagentResult] = {}
+        self._task_counter: int = 0
+
+    def create_handoff(
+        self,
+        agent: Agent,
+        task_description: str,
+        relevant_files: list[str] | None = None,
+        context_summary: str = "",
+        constraints: list[str] | None = None,
+        expected_output: str = "",
+    ) -> HandoffArtifact:
+        """Create a handoff artifact for a subagent dispatch.
+
+        Args:
+            agent: The agent to dispatch to.
+            task_description: What the subagent should do.
+            relevant_files: File paths the subagent should read.
+            context_summary: Compacted context from prior work.
+            constraints: Boundaries for the subagent.
+            expected_output: What format/content is expected back.
+
+        Returns:
+            HandoffArtifact ready for dispatch.
+        """
+        self._task_counter += 1
+        task_id = f"task-{self._task_counter}"
+
+        disc_label = agent.behavioral_dna.disc.label
+        quality = []
+        if agent.tier <= 1:
+            quality.append("Enterprise-grade quality expected")
+        quality.append("Follow SOLID principles")
+        quality.append("Human-readable output, no AI patterns")
+
+        artifact = HandoffArtifact(
+            task_id=task_id,
+            task_description=task_description,
+            agent_id=agent.id,
+            agent_role=agent.role,
+            agent_disc=disc_label,
+            department=agent.department,
+            relevant_files=relevant_files or [],
+            context_summary=context_summary,
+            constraints=constraints or [],
+            expected_output=expected_output,
+            quality_criteria=quality,
+        )
+
+        self._pending[task_id] = artifact
+        return artifact
+
+    def record_result(self, result: SubagentResult) -> None:
+        """Record a subagent's result."""
+        self._results[result.task_id] = result
+        self._pending.pop(result.task_id, None)
+
+    def get_result(self, task_id: str) -> Optional[SubagentResult]:
+        """Get a subagent's result by task ID."""
+        return self._results.get(task_id)
+
+    def get_pending(self) -> list[HandoffArtifact]:
+        """Get all pending (undispatched) handoffs."""
+        return list(self._pending.values())
+
+    def get_all_results(self) -> list[SubagentResult]:
+        """Get all collected results."""
+        return list(self._results.values())
+
+    @property
+    def pending_count(self) -> int:
+        return len(self._pending)
+
+    @property
+    def completed_count(self) -> int:
+        return len(self._results)
+
+    def orchestrator_context_usage(self) -> dict:
+        """Estimate how much context the orchestrator is using.
+
+        Target: 10-15% of context window for dispatch + collection.
+        """
+        dispatch_tokens = sum(a.estimated_tokens for a in self._pending.values())
+        result_tokens = sum(
+            len(r.to_summary().split()) for r in self._results.values()
+        )
+        total = dispatch_tokens + result_tokens
+        return {
+            "dispatch_tokens": dispatch_tokens,
+            "result_summary_tokens": result_tokens,
+            "total_orchestrator_tokens": total,
+            "tasks_dispatched": self._task_counter,
+        }

package/core/specs/__init__.py

@@ -0,0 +1,10 @@
+"""Living Specs — bidirectional spec/code sync.
+
+Specs are never stale. They track implementation status, record deltas,
+and build a reusable library of validated specifications.
+"""
+
+from core.specs.schema import Spec, SpecStatus, SpecSection, SpecDelta
+from core.specs.manager import SpecManager
+
+__all__ = ["Spec", "SpecStatus", "SpecSection", "SpecDelta", "SpecManager"]

package/core/specs/manager.py

@@ -0,0 +1,164 @@
+"""Spec manager — lifecycle management for Living Specs."""
+
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+from core.specs.schema import (
+    Spec, SpecStatus, SpecSection, SpecDelta,
+    AcceptanceCriterion, SpecMetadata, SectionStatus,
+)
+
+
+class SpecManager:
+    """Manages the lifecycle of Living Specs.
+
+    Handles creation, loading, saving, status transitions,
+    and the reusable spec library.
+    """
+
+    def __init__(self, specs_dir: str | Path = "") -> None:
+        self._specs: dict[str, Spec] = {}
+        self._specs_dir = Path(specs_dir) if specs_dir else None
+
+    def create(
+        self,
+        spec_id: str,
+        title: str,
+        description: str = "",
+        project: str = "",
+        department: str = "",
+        sections: list[dict] | None = None,
+    ) -> Spec:
+        """Create a new spec."""
+        from datetime import datetime
+
+        spec_sections = []
+        for s in (sections or []):
+            criteria = [
+                AcceptanceCriterion(id=f"ac-{i+1}", description=c)
+                for i, c in enumerate(s.get("acceptance_criteria", []))
+            ]
+            spec_sections.append(SpecSection(
+                id=s.get("id", f"section-{len(spec_sections)+1}"),
+                title=s.get("title", ""),
+                content=s.get("content", ""),
+                acceptance_criteria=criteria,
+            ))
+
+        spec = Spec(
+            id=spec_id,
+            title=title,
+            description=description,
+            status=SpecStatus.DRAFT,
+            metadata=SpecMetadata(
+                project=project,
+                department=department,
+                created_at=datetime.now().isoformat(),
+            ),
+            sections=spec_sections,
+        )
+
+        self._specs[spec_id] = spec
+        return spec
+
+    def get(self, spec_id: str) -> Optional[Spec]:
+        """Get a spec by ID."""
+        return self._specs.get(spec_id)
+
+    def approve(self, spec_id: str, approved_by: str = "") -> bool:
+        """Approve a spec for implementation."""
+        spec = self._specs.get(spec_id)
+        if spec is None or spec.status not in (SpecStatus.DRAFT, SpecStatus.REVIEW):
+            return False
+        spec.status = SpecStatus.APPROVED
+        spec.metadata.approved_by = approved_by
+        from datetime import datetime
+        spec.metadata.approved_at = datetime.now().isoformat()
+        return True
+
+    def start_implementation(self, spec_id: str) -> bool:
+        """Mark spec as in-progress."""
+        spec = self._specs.get(spec_id)
+        if spec is None or spec.status != SpecStatus.APPROVED:
+            return False
+        spec.status = SpecStatus.IN_PROGRESS
+        return True
+
+    def complete(self, spec_id: str) -> bool:
+        """Mark spec as completed."""
+        spec = self._specs.get(spec_id)
+        if spec is None or spec.status != SpecStatus.IN_PROGRESS:
+            return False
+        spec.status = SpecStatus.COMPLETED
+        return True
+
+    def list_all(self, status: Optional[SpecStatus] = None) -> list[Spec]:
+        """List all specs, optionally filtered by status."""
+        if status:
+            return [s for s in self._specs.values() if s.status == status]
+        return list(self._specs.values())
+
+    def save_to_yaml(self, spec_id: str, path: str | Path) -> bool:
+        """Save a spec to a YAML file."""
+        spec = self._specs.get(spec_id)
+        if spec is None:
+            return False
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        data = spec.model_dump(mode="json")
+        with open(path, "w") as f:
+            yaml.dump(data, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
+        return True
+
+    def load_from_yaml(self, path: str | Path) -> Spec:
+        """Load a spec from a YAML file."""
+        path = Path(path)
+        if not path.exists():
+            raise FileNotFoundError(f"Spec file not found: {path}")
+        with open(path) as f:
+            data = yaml.safe_load(f)
+        spec = Spec.model_validate(data)
+        self._specs[spec.id] = spec
+        return spec
+
+    def extract_patterns(self, spec_id: str) -> list[str]:
+        """Extract reusable patterns from a completed spec.
+
+        Patterns are sections or approaches that worked well and
+        can be reused in future specs.
+        """
+        spec = self._specs.get(spec_id)
+        if spec is None or spec.status != SpecStatus.COMPLETED:
+            return []
+
+        patterns = []
+        for section in spec.sections:
+            if section.status == SectionStatus.IMPLEMENTED and not section.implementation_notes:
+                patterns.append(f"[{spec.metadata.department}] {section.title}: {section.content[:100]}")
+            elif section.status == SectionStatus.MODIFIED:
+                delta = next((d for d in spec.deltas if d.section_id == section.id), None)
+                if delta:
+                    patterns.append(
+                        f"[{spec.metadata.department}] {section.title}: "
+                        f"Originally '{delta.original[:50]}', changed to '{delta.actual[:50]}' "
+                        f"because: {delta.reason[:50]}"
+                    )
+
+        spec.patterns = patterns
+        return patterns
+
+    @property
+    def total_specs(self) -> int:
+        return len(self._specs)
+
+    def summary(self) -> dict:
+        """Summary of all specs."""
+        by_status = {}
+        for spec in self._specs.values():
+            by_status[spec.status.value] = by_status.get(spec.status.value, 0) + 1
+        return {
+            "total": self.total_specs,
+            "by_status": by_status,
+        }