arkaos 2.0.0 → 2.0.2

package/core/obsidian/__init__.py

@@ -0,0 +1,6 @@
+"""Obsidian vault integration — write workflow outputs to knowledge base."""
+
+from core.obsidian.writer import ObsidianWriter
+from core.obsidian.templates import build_frontmatter
+
+__all__ = ["ObsidianWriter", "build_frontmatter"]

package/core/obsidian/templates.py

@@ -0,0 +1,76 @@
+"""Obsidian frontmatter templates and conventions."""
+
+from datetime import date, datetime
+from typing import Any
+
+
+def build_frontmatter(
+    department: str = "",
+    agent: str = "",
+    workflow: str = "",
+    tags: list[str] | None = None,
+    extra: dict[str, Any] | None = None,
+) -> str:
+    """Build YAML frontmatter for an Obsidian note.
+
+    Returns:
+        String with opening/closing --- delimiters.
+    """
+    fields: dict[str, Any] = {}
+    fields["created"] = datetime.now().strftime("%Y-%m-%d %H:%M")
+    fields["source"] = "arkaos"
+
+    if department:
+        fields["department"] = department
+    if agent:
+        fields["agent"] = agent
+    if workflow:
+        fields["workflow"] = workflow
+
+    all_tags = ["arkaos"]
+    if department:
+        all_tags.append(f"dept/{department}")
+    if tags:
+        all_tags.extend(tags)
+    fields["tags"] = all_tags
+
+    if extra:
+        fields.update(extra)
+
+    lines = ["---"]
+    for key, value in fields.items():
+        if isinstance(value, list):
+            lines.append(f"{key}:")
+            for item in value:
+                lines.append(f"  - {item}")
+        elif isinstance(value, bool):
+            lines.append(f"{key}: {'true' if value else 'false'}")
+        else:
+            lines.append(f"{key}: {value}")
+    lines.append("---")
+
+    return "\n".join(lines)
+
+
+def resolve_template_vars(path: str, vars: dict[str, str] | None = None) -> str:
+    """Resolve template variables in an Obsidian path.
+
+    Supported variables:
+        {project}, {department}, {agent}, {date}, {number}, {name}
+    """
+    defaults = {
+        "date": date.today().isoformat(),
+        "project": "Default",
+        "department": "general",
+        "agent": "unknown",
+        "number": "001",
+        "name": "untitled",
+    }
+    if vars:
+        defaults.update(vars)
+
+    result = path
+    for key, value in defaults.items():
+        result = result.replace(f"{{{key}}}", value)
+
+    return result

package/core/obsidian/writer.py

@@ -0,0 +1,148 @@
+"""Obsidian vault writer — save workflow outputs to knowledge base.
+
+Resolves vault path from:
+1. Constructor argument
+2. knowledge/obsidian-config.json → vault_path
+3. ARKAOS_VAULT environment variable
+4. Fallback: ~/.arkaos/vault/
+"""
+
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Optional
+
+from core.obsidian.templates import build_frontmatter, resolve_template_vars
+
+
+class ObsidianWriter:
+    """Writes markdown files to an Obsidian vault with frontmatter."""
+
+    def __init__(self, vault_path: str | Path | None = None, arkaos_root: str | Path | None = None) -> None:
+        self._vault_path = self._resolve_vault_path(vault_path, arkaos_root)
+
+    def save(
+        self,
+        obsidian_path: str,
+        content: str,
+        department: str = "",
+        agent: str = "",
+        workflow: str = "",
+        tags: list[str] | None = None,
+        template_vars: dict[str, str] | None = None,
+        extra_frontmatter: dict[str, Any] | None = None,
+    ) -> Path:
+        """Save content to the Obsidian vault.
+
+        Args:
+            obsidian_path: Relative path within vault (may contain template vars).
+            content: Markdown content to save.
+            department: Source department.
+            agent: Agent that produced the output.
+            workflow: Workflow that generated this output.
+            tags: Additional tags for frontmatter.
+            template_vars: Variables to resolve in path ({project}, {date}, etc.).
+            extra_frontmatter: Additional frontmatter fields.
+
+        Returns:
+            Absolute path to the saved file.
+        """
+        # Resolve template variables in path
+        resolved_path = resolve_template_vars(obsidian_path, template_vars)
+
+        # Build full path
+        full_path = self._vault_path / resolved_path
+
+        # If path doesn't end with .md, treat as directory and add filename
+        if not full_path.suffix:
+            timestamp = datetime.now().strftime("%Y-%m-%d_%H%M")
+            filename = f"{department or 'output'}-{timestamp}.md"
+            full_path = full_path / filename
+        elif full_path.suffix != ".md":
+            full_path = full_path.with_suffix(".md")
+
+        # Handle duplicate filenames
+        if full_path.exists():
+            stem = full_path.stem
+            timestamp = datetime.now().strftime("%H%M%S")
+            full_path = full_path.with_stem(f"{stem}-{timestamp}")
+
+        # Create directories
+        full_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Build frontmatter
+        frontmatter = build_frontmatter(
+            department=department,
+            agent=agent,
+            workflow=workflow,
+            tags=tags,
+            extra=extra_frontmatter,
+        )
+
+        # Write file
+        file_content = f"{frontmatter}\n\n{content}"
+        full_path.write_text(file_content, encoding="utf-8")
+
+        return full_path
+
+    def ensure_vault(self) -> bool:
+        """Verify the vault directory exists."""
+        return self._vault_path.exists()
+
+    def list_outputs(self, department: str = "", limit: int = 50) -> list[Path]:
+        """List recent ArkaOS outputs in the vault."""
+        if not self._vault_path.exists():
+            return []
+
+        pattern = "**/*.md"
+        files = sorted(self._vault_path.glob(pattern), key=lambda p: p.stat().st_mtime, reverse=True)
+
+        results = []
+        for f in files:
+            if len(results) >= limit:
+                break
+            try:
+                head = f.read_text(encoding="utf-8")[:200]
+                if "source: arkaos" in head:
+                    if not department or f"department: {department}" in head:
+                        results.append(f)
+            except (OSError, UnicodeDecodeError):
+                continue
+
+        return results
+
+    @property
+    def vault_path(self) -> Path:
+        return self._vault_path
+
+    def _resolve_vault_path(self, explicit: str | Path | None, arkaos_root: str | Path | None) -> Path:
+        """Resolve vault path from multiple sources."""
+        # 1. Explicit argument
+        if explicit:
+            return Path(explicit)
+
+        # 2. Config file
+        if arkaos_root:
+            config_path = Path(arkaos_root) / "knowledge" / "obsidian-config.json"
+        else:
+            config_path = Path(__file__).resolve().parent.parent.parent / "knowledge" / "obsidian-config.json"
+
+        if config_path.exists():
+            try:
+                config = json.loads(config_path.read_text())
+                vault = config.get("vault_path", "")
+                if vault and Path(vault).exists():
+                    return Path(vault)
+            except (json.JSONDecodeError, OSError):
+                pass
+
+        # 3. Environment variable
+        env_vault = os.environ.get("ARKAOS_VAULT", "")
+        if env_vault and Path(env_vault).exists():
+            return Path(env_vault)
+
+        # 4. Fallback
+        fallback = Path.home() / ".arkaos" / "vault"
+        fallback.mkdir(parents=True, exist_ok=True)
+        return fallback

package/core/orchestration/__init__.py

@@ -0,0 +1,6 @@
+"""Orchestration protocol — coordination patterns for multi-agent work."""
+
+from core.orchestration.protocol import OrchestrationPattern, PhaseHandoff, OrchestrationPlan
+from core.orchestration.patterns import PATTERNS
+
+__all__ = ["OrchestrationPattern", "PhaseHandoff", "OrchestrationPlan", "PATTERNS"]

package/core/orchestration/patterns.py

@@ -0,0 +1,136 @@
+"""Built-in orchestration patterns.
+
+Four patterns adapted from claude-skills orchestration protocol,
+mapped to ArkaOS department/agent/skill system.
+"""
+
+from core.orchestration.protocol import OrchestrationPattern, PatternType
+
+
+SOLO_SPRINT = OrchestrationPattern(
+    type=PatternType.SOLO_SPRINT,
+    name="Solo Sprint",
+    description="One department lead drives a multi-phase sprint, pulling skills from their squad. Fast, focused execution.",
+    when_to_use=[
+        "Single-domain task with clear scope",
+        "Time-constrained delivery (< 1 week)",
+        "One department has all required expertise",
+    ],
+    structure="Lead → Phase 1 (skills A,B) → Phase 2 (skills C,D) → Quality Gate → Deliver",
+    example=(
+        "Objective: Launch MVP landing page\n"
+        "Lead: Ines (Landing)\n"
+        "Phase 1: /landing copy-framework + /landing funnel-design\n"
+        "Phase 2: /landing page-build + /landing seo-optimize\n"
+        "Phase 3: Quality Gate → Ship"
+    ),
+    anti_patterns=[
+        "Using for cross-department work (use Multi-Agent Handoff instead)",
+        "Skipping Quality Gate because 'it's just one department'",
+    ],
+)
+
+DOMAIN_DEEP_DIVE = OrchestrationPattern(
+    type=PatternType.DOMAIN_DEEP_DIVE,
+    name="Domain Deep-Dive",
+    description="One agent, multiple stacked skills for thorough analysis. Deep expertise over breadth.",
+    when_to_use=[
+        "Complex technical audit or review",
+        "Due diligence or compliance assessment",
+        "Research requiring depth in one area",
+    ],
+    structure="Agent → Skill 1 (foundation) → Skill 2 (analysis) → Skill 3 (recommendations) → Report",
+    example=(
+        "Objective: Full security assessment\n"
+        "Agent: Bruno (Security Engineer)\n"
+        "Skills stacked:\n"
+        "  1. /dev security-audit (OWASP scan)\n"
+        "  2. /dev dependency-audit (CVE check)\n"
+        "  3. /dev red-team (attack simulation)\n"
+        "  4. /dev ai-security (LLM-specific risks)\n"
+        "Output: Consolidated security report with severity rankings"
+    ),
+    anti_patterns=[
+        "Stacking unrelated skills (each skill should build on previous)",
+        "Skipping the foundational skill and going straight to advanced",
+        "No consolidated output (each skill reports independently)",
+    ],
+)
+
+MULTI_AGENT_HANDOFF = OrchestrationPattern(
+    type=PatternType.MULTI_AGENT_HANDOFF,
+    name="Multi-Agent Handoff",
+    description="Work flows between departments with structured handoffs. Each department adds its expertise.",
+    when_to_use=[
+        "Cross-department projects (product launch, brand + marketing)",
+        "Sequential expertise needed (strategy → dev → marketing)",
+        "Each phase requires different domain knowledge",
+    ],
+    structure="Dept A → Handoff → Dept B → Handoff → Dept C → Quality Gate → Deliver",
+    example=(
+        "Objective: Launch new SaaS product\n"
+        "Phase 1: Tomas (Strategy) → /strat bmc + /strat five-forces\n"
+        "  Handoff: Market validation, pricing strategy, competitive position\n"
+        "Phase 2: Paulo (Dev) → /dev spec + /dev feature\n"
+        "  Handoff: MVP built, deployed to staging\n"
+        "Phase 3: Luna (Marketing) → /mkt growth-plan + /mkt email-sequence\n"
+        "  Handoff: Landing page, email funnel, launch plan\n"
+        "Phase 4: Quality Gate → Launch"
+    ),
+    anti_patterns=[
+        "No handoff context (next department starts from zero)",
+        "Too many departments (>4 phases becomes unwieldy)",
+        "Skipping departments that should review (e.g., security for a public launch)",
+    ],
+)
+
+SKILL_CHAIN = OrchestrationPattern(
+    type=PatternType.SKILL_CHAIN,
+    name="Skill Chain",
+    description="Sequential procedural skills with no specific agent identity. Pure execution pipeline.",
+    when_to_use=[
+        "Procedural work with well-defined inputs/outputs",
+        "Automated pipelines (generate → validate → publish)",
+        "No judgment calls needed, just execution",
+    ],
+    structure="Skill A (input) → Skill B (transform) → Skill C (output) → Done",
+    example=(
+        "Objective: Content production pipeline\n"
+        "Chain:\n"
+        "  1. /content hook-write → 10 headline options\n"
+        "  2. python scripts/tools/headline_scorer.py → scored + ranked\n"
+        "  3. /content viral-design → full post with winning hook\n"
+        "  4. /mkt social-strategy → distribution plan\n"
+        "No persona needed — pure skill execution"
+    ),
+    anti_patterns=[
+        "Using for work that needs judgment (use Solo Sprint or Handoff)",
+        "Long chains with no validation checkpoints",
+        "Mixing judgment skills with procedural skills",
+    ],
+)
+
+
+PATTERNS = {
+    PatternType.SOLO_SPRINT: SOLO_SPRINT,
+    PatternType.DOMAIN_DEEP_DIVE: DOMAIN_DEEP_DIVE,
+    PatternType.MULTI_AGENT_HANDOFF: MULTI_AGENT_HANDOFF,
+    PatternType.SKILL_CHAIN: SKILL_CHAIN,
+}
+
+
+def select_pattern(
+    departments_involved: int,
+    needs_judgment: bool,
+    is_sequential: bool,
+) -> PatternType:
+    """Recommend an orchestration pattern based on task characteristics."""
+    if departments_involved == 1 and needs_judgment:
+        return PatternType.SOLO_SPRINT
+    if departments_involved == 1 and not needs_judgment:
+        return PatternType.SKILL_CHAIN
+    if departments_involved > 1 and is_sequential:
+        return PatternType.MULTI_AGENT_HANDOFF
+    if departments_involved == 1:
+        return PatternType.DOMAIN_DEEP_DIVE
+    return PatternType.MULTI_AGENT_HANDOFF

package/core/orchestration/protocol.py

@@ -0,0 +1,96 @@
+"""Orchestration protocol schemas.
+
+Defines the structure for multi-agent coordination across departments.
+Four patterns: Solo Sprint, Domain Deep-Dive, Multi-Agent Handoff, Skill Chain.
+"""
+
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class PatternType(str, Enum):
+    SOLO_SPRINT = "solo_sprint"
+    DOMAIN_DEEP_DIVE = "domain_deep_dive"
+    MULTI_AGENT_HANDOFF = "multi_agent_handoff"
+    SKILL_CHAIN = "skill_chain"
+
+
+class PhaseHandoff(BaseModel):
+    """Context passed between orchestration phases."""
+    phase_number: int
+    phase_name: str
+    decisions: list[str] = Field(default_factory=list)
+    artifacts: list[str] = Field(default_factory=list)
+    open_questions: list[str] = Field(default_factory=list)
+    next_department: str = ""
+    next_agent: str = ""
+    next_skills: list[str] = Field(default_factory=list)
+
+    def to_context(self) -> str:
+        """Render handoff as context string for next phase."""
+        lines = [f"Phase {self.phase_number} ({self.phase_name}) complete."]
+        if self.decisions:
+            lines.append(f"Decisions: {', '.join(self.decisions)}")
+        if self.artifacts:
+            lines.append(f"Artifacts: {', '.join(self.artifacts)}")
+        if self.open_questions:
+            lines.append(f"Open questions: {', '.join(self.open_questions)}")
+        if self.next_department:
+            lines.append(f"Next: {self.next_department}/{self.next_agent}")
+        return "\n".join(lines)
+
+
+class OrchestrationPhase(BaseModel):
+    """A single phase in an orchestration plan."""
+    number: int
+    name: str
+    department: str
+    agent_id: str
+    skills: list[str] = Field(default_factory=list)
+    objective: str = ""
+    outputs: list[str] = Field(default_factory=list)
+    gate: str = "user_approval"  # user_approval, auto, quality_gate
+
+
+class OrchestrationPlan(BaseModel):
+    """A complete orchestration plan spanning multiple departments."""
+    objective: str
+    pattern: PatternType
+    constraints: list[str] = Field(default_factory=list)
+    success_criteria: list[str] = Field(default_factory=list)
+    phases: list[OrchestrationPhase] = Field(default_factory=list)
+    current_phase: int = 0
+
+    def next_phase(self) -> Optional[OrchestrationPhase]:
+        """Get the next phase to execute."""
+        if self.current_phase < len(self.phases):
+            return self.phases[self.current_phase]
+        return None
+
+    def advance(self, handoff: PhaseHandoff) -> Optional[OrchestrationPhase]:
+        """Record handoff and advance to next phase."""
+        self.current_phase += 1
+        return self.next_phase()
+
+    @property
+    def is_complete(self) -> bool:
+        return self.current_phase >= len(self.phases)
+
+    @property
+    def progress_percent(self) -> int:
+        if not self.phases:
+            return 0
+        return int((self.current_phase / len(self.phases)) * 100)
+
+
+class OrchestrationPattern(BaseModel):
+    """Definition of a coordination pattern."""
+    type: PatternType
+    name: str
+    description: str
+    when_to_use: list[str] = Field(default_factory=list)
+    structure: str = ""
+    example: str = ""
+    anti_patterns: list[str] = Field(default_factory=list)

package/core/tasks/schema.py

@@ -47,6 +47,12 @@ class Task(BaseModel):
     output_data: dict[str, Any] = Field(default_factory=dict)
     output_path: str = ""             # File path for output
 
+    # Budget
+    tokens_estimated: int = 0         # Pre-execution estimate
+    tokens_actual: int = 0            # Post-execution actual
+    budget_approved: bool = True      # True if within budget or approved
+    approved_by: str = ""             # Tier 0 agent who approved overrun
+
     # Progress
     progress_percent: int = 0         # 0-100
     progress_message: str = ""