arkaos 2.0.0-alpha.1

package/core/registry/generator.py

@@ -0,0 +1,199 @@
+"""Commands registry generator.
+
+Scans all SKILL.md files, extracts command tables, and generates
+a machine-readable JSON registry for /do routing and Synapse L5.
+"""
+
+import json
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+
+# Keywords map: department → common keywords users might type
+DEPARTMENT_KEYWORDS: dict[str, list[str]] = {
+    "dev": ["build", "code", "feature", "deploy", "test", "review", "scaffold", "debug",
+            "refactor", "api", "migration", "implement", "fix", "bug", "database", "architecture"],
+    "marketing": ["social", "content", "campaign", "post", "instagram", "linkedin", "twitter",
+                  "tiktok", "seo", "marketing", "ads", "email", "growth", "analytics"],
+    "brand": ["brand", "logo", "colors", "palette", "mockup", "identity", "naming",
+              "positioning", "voice", "guidelines", "ux", "wireframe", "design", "ui"],
+    "finance": ["budget", "invoice", "revenue", "forecast", "profit", "financial", "invest",
+                "valuation", "cashflow", "expense", "pitch", "model", "scenario"],
+    "strategy": ["strategy", "brainstorm", "market", "swot", "competitor", "roadmap",
+                 "position", "blue ocean", "five forces", "tam", "moat", "growth"],
+    "ecom": ["store", "product", "shop", "shopify", "ecommerce", "catalog", "cart",
+             "checkout", "pricing", "marketplace", "rfm", "conversion", "cro"],
+    "kb": ["learn", "persona", "knowledge", "youtube", "transcribe", "research",
+           "zettelkasten", "note", "moc", "taxonomy", "source"],
+    "ops": ["automate", "workflow", "process", "sop", "bottleneck", "integration",
+            "zapier", "n8n", "dashboard", "lean", "gtd"],
+    "pm": ["sprint", "backlog", "standup", "retro", "scrum", "kanban", "story",
+           "estimate", "roadmap", "agile", "discover", "shape"],
+    "saas": ["saas", "micro-saas", "plg", "freemium", "churn", "mrr", "arr",
+             "subscription", "onboarding", "metrics", "validate", "niche", "benchmark"],
+    "landing": ["landing", "funnel", "copy", "headline", "offer", "launch", "affiliate",
+                "webinar", "conversion", "sales page", "persuade", "cro"],
+    "content": ["viral", "hook", "script", "repurpose", "youtube", "tiktok", "reels",
+                "shorts", "newsletter", "creator", "thumbnail", "platform", "content system"],
+    "community": ["community", "group", "membership", "discord", "telegram", "skool",
+                  "circle", "gamification", "engagement", "moderate", "event"],
+    "sales": ["pipeline", "proposal", "discovery", "objection", "negotiate", "deal",
+              "close", "prospect", "spin", "challenger", "forecast"],
+    "lead": ["leadership", "delegation", "1on1", "feedback", "culture", "hiring",
+             "performance review", "team build", "conflict", "okr"],
+    "org": ["org design", "hiring plan", "onboarding", "remote", "meeting",
+            "compensation", "decision", "team assess", "sop"],
+}
+
+
+def extract_commands_from_skill(skill_path: Path) -> list[dict]:
+    """Extract commands from a SKILL.md file's command table.
+
+    Parses markdown tables with | Command | Description | format.
+    """
+    if not skill_path.exists():
+        return []
+
+    text = skill_path.read_text()
+    commands = []
+
+    # Find command tables (lines with | `/ ... ` | description | ...)
+    for line in text.split("\n"):
+        match = re.match(r"\|\s*`([^`]+)`\s*\|\s*([^|]+)\|", line)
+        if match:
+            command = match.group(1).strip()
+            description = match.group(2).strip()
+            if not command.startswith("/") or "Description" in description or description.startswith("-"):
+                continue
+            commands.append({
+                "command": command,
+                "description": description,
+            })
+
+    return commands
+
+
+def determine_department(skill_path: Path) -> str:
+    """Determine department from the skill file's directory."""
+    # departments/dev/SKILL.md → dev
+    # arka/SKILL.md → arka
+    parent = skill_path.parent.name
+    return parent
+
+
+def extract_tier(description: str) -> int:
+    """Guess command tier from description keywords."""
+    desc_lower = description.lower()
+    if any(w in desc_lower for w in ["full", "enterprise", "comprehensive", "complete"]):
+        return 1
+    if any(w in desc_lower for w in ["audit", "analysis", "strategy", "design"]):
+        return 2
+    return 3
+
+
+def generate_commands_registry(
+    base_dir: str | Path,
+    output_path: str | Path,
+) -> dict:
+    """Generate commands-registry-v2.json from all SKILL.md files.
+
+    Args:
+        base_dir: Project root directory.
+        output_path: Where to write the JSON registry.
+
+    Returns:
+        The registry dict.
+    """
+    base_dir = Path(base_dir)
+    output_path = Path(output_path)
+
+    all_commands = []
+
+    # v2 department directories (exclude v1 legacy dirs)
+    v2_departments = {
+        "dev", "marketing", "brand", "finance", "strategy", "ecom", "kb",
+        "ops", "pm", "saas", "landing", "content", "community", "sales",
+        "leadership", "org", "quality",
+    }
+
+    # Scan department SKILL.md files
+    for skill_file in sorted(base_dir.glob("departments/*/SKILL.md")):
+        if skill_file.parent.name not in v2_departments:
+            continue
+        dept = determine_department(skill_file)
+        raw_commands = extract_commands_from_skill(skill_file)
+        keywords = DEPARTMENT_KEYWORDS.get(dept, [])
+
+        for cmd in raw_commands:
+            command_text = cmd["command"]
+            # Generate ID: /dev feature → dev-feature
+            cmd_id = command_text.lstrip("/").replace(" ", "-").split("<")[0].rstrip("-")
+
+            # Determine if code-modifying
+            modifies_code = dept == "dev" and any(
+                w in command_text for w in ["feature", "api", "debug", "refactor", "db", "scaffold"]
+            )
+
+            all_commands.append({
+                "id": cmd_id,
+                "command": command_text,
+                "department": dept,
+                "description": cmd["description"],
+                "keywords": keywords[:8],
+                "tier": extract_tier(cmd["description"]),
+                "modifies_code": modifies_code,
+                "requires_branch": modifies_code,
+            })
+
+    # Scan orchestrator SKILL.md
+    arka_skill = base_dir / "arka" / "SKILL.md"
+    if arka_skill.exists():
+        raw_commands = extract_commands_from_skill(arka_skill)
+        for cmd in raw_commands:
+            command_text = cmd["command"]
+            cmd_id = command_text.lstrip("/").replace(" ", "-").split("<")[0].rstrip("-")
+            all_commands.append({
+                "id": cmd_id,
+                "command": command_text,
+                "department": "arka",
+                "description": cmd["description"],
+                "keywords": [],
+                "tier": 3,
+                "modifies_code": False,
+                "requires_branch": False,
+            })
+
+    # Build department summary
+    dept_counts: dict[str, int] = {}
+    for cmd in all_commands:
+        d = cmd["department"]
+        dept_counts[d] = dept_counts.get(d, 0) + 1
+
+    registry = {
+        "_meta": {
+            "version": "2.0.0",
+            "generated": datetime.now().isoformat(),
+            "total_commands": len(all_commands),
+            "generator": "core/registry/generator.py",
+            "departments": dept_counts,
+        },
+        "commands": all_commands,
+    }
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(output_path, "w") as f:
+        json.dump(registry, f, indent=2, ensure_ascii=False)
+
+    return registry
+
+
+if __name__ == "__main__":
+    base = Path(__file__).parent.parent.parent
+    reg = generate_commands_registry(
+        base,
+        base / "knowledge" / "commands-registry-v2.json",
+    )
+    print(f"Generated: {reg['_meta']['total_commands']} commands")
+    print(f"Departments: {reg['_meta']['departments']}")

package/core/runtime/__init__.py

@@ -0,0 +1,6 @@
+"""Runtime adapters for multi-framework support."""
+
+from core.runtime.base import RuntimeAdapter, RuntimeConfig
+from core.runtime.registry import get_adapter, detect_runtime
+
+__all__ = ["RuntimeAdapter", "RuntimeConfig", "get_adapter", "detect_runtime"]

package/core/runtime/base.py

@@ -0,0 +1,143 @@
+"""Abstract runtime adapter interface.
+
+Every AI runtime (Claude Code, Codex CLI, Gemini CLI, Cursor) must implement
+this interface. The adapter translates ArkaOS operations into runtime-specific
+commands and configurations.
+
+Design: Strategy pattern. The orchestrator calls adapter methods without
+knowing which runtime is active. Each adapter handles the translation.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class RuntimeConfig:
+    """Configuration for a specific runtime environment."""
+
+    id: str
+    name: str
+    config_dir: Path
+    skills_dir: Path
+    settings_file: Path
+    supports_hooks: bool = True
+    supports_subagents: bool = True
+    supports_mcp: bool = False
+    max_context_tokens: int = 200_000
+
+
+@dataclass
+class AgentContext:
+    """Context passed to an agent for execution."""
+
+    agent_id: str
+    task: str
+    department: str
+    tier: int
+    tools: list[str] = field(default_factory=list)
+    files: list[str] = field(default_factory=list)
+    context_layers: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class AgentResult:
+    """Result returned by an agent after execution."""
+
+    agent_id: str
+    status: str  # "completed", "failed", "needs_review"
+    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)
+
+
+class RuntimeAdapter(ABC):
+    """Abstract base class for runtime adapters.
+
+    Each supported AI runtime implements this interface to translate
+    ArkaOS operations into runtime-specific actions.
+    """
+
+    @abstractmethod
+    def get_config(self) -> RuntimeConfig:
+        """Return runtime configuration."""
+
+    @abstractmethod
+    def inject_context(self, layers: dict[str, str]) -> str:
+        """Inject context layers into the runtime.
+
+        Args:
+            layers: Dict of layer_name -> context_string
+
+        Returns:
+            The formatted context string for this runtime.
+        """
+
+    @abstractmethod
+    def dispatch_agent(self, context: AgentContext) -> AgentResult:
+        """Dispatch a task to an agent.
+
+        Args:
+            context: The agent context with task, tools, and files.
+
+        Returns:
+            AgentResult with output and metadata.
+        """
+
+    @abstractmethod
+    def spawn_subagent(self, context: AgentContext) -> AgentResult:
+        """Spawn a fresh subagent for isolated task execution.
+
+        Each subagent gets a fresh context window (the subagent pattern).
+
+        Args:
+            context: The agent context for the subagent.
+
+        Returns:
+            AgentResult from the subagent.
+        """
+
+    @abstractmethod
+    def read_file(self, path: str) -> str:
+        """Read a file through the runtime."""
+
+    @abstractmethod
+    def write_file(self, path: str, content: str) -> None:
+        """Write a file through the runtime."""
+
+    @abstractmethod
+    def edit_file(self, path: str, old: str, new: str) -> None:
+        """Edit a file through the runtime (find and replace)."""
+
+    @abstractmethod
+    def execute_command(self, command: str, timeout: int = 120) -> tuple[str, int]:
+        """Execute a shell command through the runtime.
+
+        Returns:
+            Tuple of (output, exit_code).
+        """
+
+    @abstractmethod
+    def search_files(self, pattern: str, path: str = ".") -> list[str]:
+        """Search for files matching a glob pattern."""
+
+    @abstractmethod
+    def search_content(self, pattern: str, path: str = ".") -> list[str]:
+        """Search file contents for a regex pattern."""
+
+    def supports_feature(self, feature: str) -> bool:
+        """Check if the runtime supports a specific feature.
+
+        Features: hooks, subagents, mcp, parallel_agents, worktrees
+        """
+        config = self.get_config()
+        feature_map = {
+            "hooks": config.supports_hooks,
+            "subagents": config.supports_subagents,
+            "mcp": config.supports_mcp,
+        }
+        return feature_map.get(feature, False)

package/core/runtime/claude_code.py

@@ -0,0 +1,104 @@
+"""Claude Code runtime adapter.
+
+Claude Code is the primary and most capable runtime for ArkaOS.
+It supports hooks, subagents (Agent tool), MCP servers, and worktrees.
+"""
+
+from pathlib import Path
+from os.path import expanduser
+
+from core.runtime.base import RuntimeAdapter, RuntimeConfig, AgentContext, AgentResult
+
+
+class ClaudeCodeAdapter(RuntimeAdapter):
+    """Adapter for Anthropic's Claude Code CLI."""
+
+    def get_config(self) -> RuntimeConfig:
+        home = Path(expanduser("~"))
+        return RuntimeConfig(
+            id="claude-code",
+            name="Claude Code",
+            config_dir=home / ".claude",
+            skills_dir=home / ".claude" / "skills",
+            settings_file=home / ".claude" / "settings.json",
+            supports_hooks=True,
+            supports_subagents=True,
+            supports_mcp=True,
+            max_context_tokens=1_000_000,
+        )
+
+    def inject_context(self, layers: dict[str, str]) -> str:
+        """Claude Code receives context via UserPromptSubmit hook.
+
+        The hook script concatenates all layers into a single
+        additionalContext string that Claude sees in system-reminder tags.
+        """
+        parts = []
+        for name, content in layers.items():
+            parts.append(f"[{name}] {content}")
+        return " ".join(parts)
+
+    def dispatch_agent(self, context: AgentContext) -> AgentResult:
+        """In Claude Code, agents are dispatched via the Agent tool.
+
+        The orchestrator provides the agent type via subagent_type parameter.
+        Claude Code handles the actual execution.
+        """
+        # This is a specification of intent — actual execution happens
+        # through Claude Code's native Agent tool
+        return AgentResult(
+            agent_id=context.agent_id,
+            status="dispatched",
+            output=f"Agent {context.agent_id} dispatched for: {context.task}",
+            metadata={
+                "runtime": "claude-code",
+                "subagent_type": context.agent_id,
+                "department": context.department,
+            },
+        )
+
+    def spawn_subagent(self, context: AgentContext) -> AgentResult:
+        """Spawn a fresh Claude Code subagent.
+
+        Uses the Agent tool with a complete task description.
+        Each subagent gets a fresh 1M token context window.
+        """
+        return AgentResult(
+            agent_id=context.agent_id,
+            status="dispatched",
+            output=f"Subagent {context.agent_id} spawned for: {context.task}",
+            metadata={
+                "runtime": "claude-code",
+                "pattern": "subagent",
+                "fresh_context": True,
+            },
+        )
+
+    def read_file(self, path: str) -> str:
+        """Claude Code uses the Read tool natively."""
+        # This maps to the Read tool in Claude Code
+        raise NotImplementedError("Use Claude Code's native Read tool")
+
+    def write_file(self, path: str, content: str) -> None:
+        """Claude Code uses the Write tool natively."""
+        raise NotImplementedError("Use Claude Code's native Write tool")
+
+    def edit_file(self, path: str, old: str, new: str) -> None:
+        """Claude Code uses the Edit tool natively."""
+        raise NotImplementedError("Use Claude Code's native Edit tool")
+
+    def execute_command(self, command: str, timeout: int = 120) -> tuple[str, int]:
+        """Claude Code uses the Bash tool natively."""
+        raise NotImplementedError("Use Claude Code's native Bash tool")
+
+    def search_files(self, pattern: str, path: str = ".") -> list[str]:
+        """Claude Code uses the Glob tool natively."""
+        raise NotImplementedError("Use Claude Code's native Glob tool")
+
+    def search_content(self, pattern: str, path: str = ".") -> list[str]:
+        """Claude Code uses the Grep tool natively."""
+        raise NotImplementedError("Use Claude Code's native Grep tool")
+
+    def supports_feature(self, feature: str) -> bool:
+        """Claude Code supports all features."""
+        return True

package/core/runtime/codex_cli.py

@@ -0,0 +1,71 @@
+"""Codex CLI runtime adapter.
+
+OpenAI's Codex CLI. Supports sandboxed execution and file operations.
+More limited than Claude Code: no native hooks, no MCP servers.
+"""
+
+from pathlib import Path
+from os.path import expanduser
+
+from core.runtime.base import RuntimeAdapter, RuntimeConfig, AgentContext, AgentResult
+
+
+class CodexCliAdapter(RuntimeAdapter):
+    """Adapter for OpenAI's Codex CLI."""
+
+    def get_config(self) -> RuntimeConfig:
+        home = Path(expanduser("~"))
+        return RuntimeConfig(
+            id="codex",
+            name="Codex CLI",
+            config_dir=home / ".codex",
+            skills_dir=home / ".codex" / "skills",
+            settings_file=home / ".codex" / "settings.json",
+            supports_hooks=False,
+            supports_subagents=True,
+            supports_mcp=False,
+            max_context_tokens=200_000,
+        )
+
+    def inject_context(self, layers: dict[str, str]) -> str:
+        """Codex receives context via AGENTS.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:
+        """Codex dispatches agents via its native agent system."""
+        return AgentResult(
+            agent_id=context.agent_id,
+            status="dispatched",
+            output=f"Agent {context.agent_id} dispatched via Codex",
+            metadata={"runtime": "codex"},
+        )
+
+    def spawn_subagent(self, context: AgentContext) -> AgentResult:
+        """Codex supports subagents with fresh context."""
+        return AgentResult(
+            agent_id=context.agent_id,
+            status="dispatched",
+            output=f"Subagent {context.agent_id} spawned via Codex",
+            metadata={"runtime": "codex", "pattern": "subagent"},
+        )
+
+    def read_file(self, path: str) -> str:
+        raise NotImplementedError("Use Codex CLI's native file read")
+
+    def write_file(self, path: str, content: str) -> None:
+        raise NotImplementedError("Use Codex CLI's native file write")
+
+    def edit_file(self, path: str, old: str, new: str) -> None:
+        raise NotImplementedError("Use Codex CLI's native file edit")
+
+    def execute_command(self, command: str, timeout: int = 120) -> tuple[str, int]:
+        raise NotImplementedError("Use Codex CLI's native shell execution")
+
+    def search_files(self, pattern: str, path: str = ".") -> list[str]:
+        raise NotImplementedError("Use Codex CLI's native file search")
+
+    def search_content(self, pattern: str, path: str = ".") -> list[str]:
+        raise NotImplementedError("Use Codex CLI's native content search")

package/core/runtime/cursor.py

@@ -0,0 +1,71 @@
+"""Cursor runtime adapter.
+
+Cursor AI IDE. Uses .cursorrules for project instructions and .cursor/rules for global rules.
+Supports agent mode with tool execution.
+"""
+
+from pathlib import Path
+from os.path import expanduser
+
+from core.runtime.base import RuntimeAdapter, RuntimeConfig, AgentContext, AgentResult
+
+
+class CursorAdapter(RuntimeAdapter):
+    """Adapter for Cursor AI IDE."""
+
+    def get_config(self) -> RuntimeConfig:
+        home = Path(expanduser("~"))
+        return RuntimeConfig(
+            id="cursor",
+            name="Cursor",
+            config_dir=home / ".cursor",
+            skills_dir=home / ".cursor" / "skills",
+            settings_file=home / ".cursor" / "settings.json",
+            supports_hooks=False,
+            supports_subagents=False,
+            supports_mcp=True,
+            max_context_tokens=200_000,
+        )
+
+    def inject_context(self, layers: dict[str, str]) -> str:
+        """Cursor receives context via .cursorrules files."""
+        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:
+        """Cursor agent mode handles dispatch internally."""
+        return AgentResult(
+            agent_id=context.agent_id,
+            status="dispatched",
+            output=f"Agent {context.agent_id} dispatched via Cursor",
+            metadata={"runtime": "cursor"},
+        )
+
+    def spawn_subagent(self, context: AgentContext) -> AgentResult:
+        """Cursor does not support native subagents."""
+        return AgentResult(
+            agent_id=context.agent_id,
+            status="unsupported",
+            output="Cursor does not support subagent spawning. Using single-agent mode.",
+            metadata={"runtime": "cursor", "fallback": "single-agent"},
+        )
+
+    def read_file(self, path: str) -> str:
+        raise NotImplementedError("Use Cursor's native file read")
+
+    def write_file(self, path: str, content: str) -> None:
+        raise NotImplementedError("Use Cursor's native file write")
+
+    def edit_file(self, path: str, old: str, new: str) -> None:
+        raise NotImplementedError("Use Cursor's native file edit")
+
+    def execute_command(self, command: str, timeout: int = 120) -> tuple[str, int]:
+        raise NotImplementedError("Use Cursor's native terminal")
+
+    def search_files(self, pattern: str, path: str = ".") -> list[str]:
+        raise NotImplementedError("Use Cursor's native file search")
+
+    def search_content(self, pattern: str, path: str = ".") -> list[str]:
+        raise NotImplementedError("Use Cursor's native content search")