arkaos 2.0.1 → 2.0.2

package/VERSION

@@ -1 +1 @@
-2.0.1
+2.0.2

package/config/constitution.yaml

@@ -118,6 +118,10 @@ enforcement_levels:
       - id: complexity-assessment
         rule: "Assess task complexity before starting. Route to appropriate workflow tier."
 
+      - id: communication-standard
+        rule: "Bottom-line first output. Lead with answer, then why, then how. Confidence tags on assessments."
+        enforcement: "See config/standards/communication.md for full standard"
+
 tier_hierarchy:
   description: "Agent authority levels inspired by SpaceX/Google/Anthropic org structures"
   tiers:

package/config/hooks/user-prompt-submit-v2.sh

@@ -19,7 +19,18 @@ _hook_ms() {
 }
 
 # ─── Paths ───────────────────────────────────────────────────────────────
-ARKAOS_ROOT="${ARKA_OS:-$HOME/.claude/skills/arkaos}"
+# Resolve ARKAOS_ROOT: env var → .repo-path → npm package → fallback
+if [ -n "${ARKAOS_ROOT:-}" ]; then
+  : # already set
+elif [ -f "$HOME/.arkaos/.repo-path" ]; then
+  ARKAOS_ROOT=$(cat "$HOME/.arkaos/.repo-path")
+elif [ -d "$HOME/.arkaos" ]; then
+  ARKAOS_ROOT="$HOME/.arkaos"
+else
+  ARKAOS_ROOT="${ARKA_OS:-$HOME/.claude/skills/arkaos}"
+fi
+export ARKAOS_ROOT
+
 CACHE_DIR="/tmp/arkaos-context-cache"
 CACHE_TTL=300  # Constitution cache: 5 minutes
 
@@ -35,46 +46,17 @@ if [ -z "$user_input" ]; then
   user_input=$(echo "$input" | head -c 2000)
 fi
 
-# ─── Try Python Synapse engine first ─────────────────────────────────────
+# ─── Try Python Synapse bridge first ────────────────────────────────────
 python_result=""
-if command -v python3 &>/dev/null; then
-  python_result=$(python3 -c "
-import sys, os
-sys.path.insert(0, '${ARKAOS_ROOT}')
-try:
-    from core.synapse.engine import create_default_engine
-    from core.synapse.layers import PromptContext
-    from core.governance.constitution import load_constitution
-    import subprocess
+BRIDGE_SCRIPT="${ARKAOS_ROOT}/scripts/synapse-bridge.py"
 
-    # Load constitution for L0
-    const_path = '${ARKAOS_ROOT}/config/constitution.yaml'
-    compressed = ''
-    if os.path.exists(const_path):
-        c = load_constitution(const_path)
-        compressed = c.compress_for_context()
+if command -v python3 &>/dev/null && [ -f "$BRIDGE_SCRIPT" ]; then
+  bridge_output=$(echo "{\"user_input\":$(echo "$user_input" | python3 -c "import sys,json; print(json.dumps(sys.stdin.read()))" 2>/dev/null || echo '""')}" \
+    | ARKAOS_ROOT="$ARKAOS_ROOT" python3 "$BRIDGE_SCRIPT" --root "$ARKAOS_ROOT" 2>/dev/null)
 
-    # Detect git branch
-    branch = ''
-    try:
-        branch = subprocess.run(['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
-                                capture_output=True, text=True, timeout=2).stdout.strip()
-    except Exception:
-        pass
-
-    # Create engine and inject
-    engine = create_default_engine(constitution_compressed=compressed)
-    ctx = PromptContext(
-        user_input='''${user_input}''',
-        cwd=os.getcwd(),
-        git_branch=branch,
-    )
-    result = engine.inject(ctx)
-    print(result.context_string)
-except Exception as e:
-    print(f'[arkaos:error] {e}', file=sys.stderr)
-    print('')
-" 2>/dev/null)
+  if [ -n "$bridge_output" ]; then
+    python_result=$(echo "$bridge_output" | python3 -c "import sys,json; print(json.loads(sys.stdin.read()).get('context_string',''))" 2>/dev/null)
+  fi
 fi
 
 # ─── Fallback: Bash-only context (if Python unavailable) ────────────────

package/core/budget/__init__.py

@@ -0,0 +1,6 @@
+"""Token budget system — tracking and enforcement for agent operations."""
+
+from core.budget.schema import BudgetConfig, BudgetUsage, BudgetSummary, TierBudget
+from core.budget.manager import BudgetManager
+
+__all__ = ["BudgetConfig", "BudgetUsage", "BudgetSummary", "TierBudget", "BudgetManager"]

package/core/budget/manager.py

@@ -0,0 +1,193 @@
+"""Budget manager — track, enforce, and report on token budgets."""
+
+import json
+from datetime import date, datetime
+from pathlib import Path
+from typing import Optional
+
+from core.budget.schema import BudgetConfig, BudgetSummary, BudgetUsage, TierBudget
+
+
+class BudgetManager:
+    """Manages token budget allocation, tracking, and enforcement.
+
+    Budgets are tier-based with monthly reset. Usage is persisted to JSON.
+    Tier 0 agents have unlimited budgets. Other tiers need Tier 0 approval
+    when usage exceeds the approval threshold (default 80%).
+    """
+
+    def __init__(self, storage_path: str | Path = "", config: BudgetConfig | None = None) -> None:
+        self._config = config or BudgetConfig()
+        self._usages: list[BudgetUsage] = []
+        self._counter: int = 0
+        self._storage_path = Path(storage_path) if storage_path else None
+        if self._storage_path and self._storage_path.exists():
+            self._load()
+
+    def record_usage(
+        self,
+        agent_id: str,
+        tokens: int,
+        tier: int = 2,
+        department: str = "",
+        workflow_id: str = "",
+        task_id: str = "",
+        description: str = "",
+        approved_by: str = "",
+    ) -> BudgetUsage:
+        """Record a token usage event."""
+        self._counter += 1
+        usage = BudgetUsage(
+            id=f"usage-{self._counter:06d}",
+            agent_id=agent_id,
+            department=department,
+            tier=tier,
+            tokens=tokens,
+            workflow_id=workflow_id,
+            task_id=task_id,
+            description=description,
+            timestamp=datetime.now().isoformat(),
+            approved_by=approved_by,
+        )
+        self._usages.append(usage)
+        self._save()
+        return usage
+
+    def get_period_usage(self, tier: int, department: str = "") -> int:
+        """Get total tokens used this billing period for a tier/department."""
+        period_start = self._current_period_start()
+        total = 0
+        for u in self._usages:
+            if u.tier != tier:
+                continue
+            if department and u.department != department:
+                continue
+            if u.timestamp and u.timestamp >= period_start.isoformat():
+                total += u.tokens
+        return total
+
+    def get_remaining(self, tier: int, department: str = "") -> int:
+        """Get remaining tokens for this period. Returns -1 for unlimited."""
+        budget = self._config.get_tier_budget(tier)
+        if budget.is_unlimited:
+            return -1
+        used = self.get_period_usage(tier, department)
+        return max(0, budget.monthly_tokens - used)
+
+    def check_budget(self, tier: int, estimated_tokens: int, department: str = "") -> bool:
+        """Check if there's enough budget for an operation. True = OK."""
+        budget = self._config.get_tier_budget(tier)
+        if budget.is_unlimited:
+            return True
+
+        # Check per-task limit
+        if budget.per_task_max > 0 and estimated_tokens > budget.per_task_max:
+            return False
+
+        # Check remaining monthly budget
+        remaining = self.get_remaining(tier, department)
+        return estimated_tokens <= remaining
+
+    def needs_approval(self, tier: int, department: str = "") -> bool:
+        """Check if usage has exceeded the approval threshold."""
+        budget = self._config.get_tier_budget(tier)
+        if budget.is_unlimited:
+            return False
+        used = self.get_period_usage(tier, department)
+        return used >= (budget.monthly_tokens * budget.approval_threshold)
+
+    def get_summary(self, tier: int, department: str = "") -> BudgetSummary:
+        """Get a complete budget summary for a tier/department."""
+        budget = self._config.get_tier_budget(tier)
+        used = self.get_period_usage(tier, department)
+        period_start = self._current_period_start()
+
+        if budget.is_unlimited:
+            return BudgetSummary(
+                tier=tier,
+                department=department,
+                period_start=period_start.isoformat(),
+                allocated=0,
+                used=used,
+                remaining=-1,
+                percent_used=0,
+                is_unlimited=True,
+                usage_count=self._count_period_usages(tier, department),
+            )
+
+        remaining = max(0, budget.monthly_tokens - used)
+        percent = (used / budget.monthly_tokens * 100) if budget.monthly_tokens > 0 else 0
+        overruns = sum(
+            1 for u in self._usages
+            if u.tier == tier
+            and (not department or u.department == department)
+            and u.timestamp >= period_start.isoformat()
+            and u.is_overrun_approved
+        )
+
+        return BudgetSummary(
+            tier=tier,
+            department=department,
+            period_start=period_start.isoformat(),
+            allocated=budget.monthly_tokens,
+            used=used,
+            remaining=remaining,
+            percent_used=round(percent, 1),
+            is_unlimited=False,
+            needs_approval=self.needs_approval(tier, department),
+            usage_count=self._count_period_usages(tier, department),
+            overruns=overruns,
+        )
+
+    def reset_monthly(self) -> int:
+        """Archive old usages and start a new billing period. Returns archived count."""
+        period_start = self._current_period_start()
+        old = [u for u in self._usages if u.timestamp < period_start.isoformat()]
+        self._usages = [u for u in self._usages if u.timestamp >= period_start.isoformat()]
+        self._save()
+        return len(old)
+
+    def _current_period_start(self) -> date:
+        """Get the start of the current billing period."""
+        today = date.today()
+        day = self._config.billing_start_day
+        if today.day >= day:
+            return date(today.year, today.month, day)
+        # Previous month
+        month = today.month - 1
+        year = today.year
+        if month < 1:
+            month = 12
+            year -= 1
+        return date(year, month, day)
+
+    def _count_period_usages(self, tier: int, department: str = "") -> int:
+        period_start = self._current_period_start()
+        return sum(
+            1 for u in self._usages
+            if u.tier == tier
+            and (not department or u.department == department)
+            and u.timestamp >= period_start.isoformat()
+        )
+
+    def _save(self) -> None:
+        if self._storage_path is None:
+            return
+        self._storage_path.parent.mkdir(parents=True, exist_ok=True)
+        data = {
+            "counter": self._counter,
+            "usages": [u.model_dump(mode="json") for u in self._usages],
+        }
+        with open(self._storage_path, "w") as f:
+            json.dump(data, f, indent=2)
+
+    def _load(self) -> None:
+        if self._storage_path is None or not self._storage_path.exists():
+            return
+        content = self._storage_path.read_text().strip()
+        if not content:
+            return
+        data = json.loads(content)
+        self._counter = data.get("counter", 0)
+        for udata in data.get("usages", []):
+            self._usages.append(BudgetUsage.model_validate(udata))

package/core/budget/schema.py

@@ -0,0 +1,82 @@
+"""Budget schema — token allocation, usage tracking, and summaries."""
+
+from datetime import date, datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class TierBudget(BaseModel):
+    """Token budget for a single agent tier."""
+    tier: int
+    monthly_tokens: int          # 0 = unlimited
+    per_task_max: int            # 0 = unlimited
+    approval_threshold: float = 0.8  # Needs Tier 0 approval at this % used
+
+    @property
+    def is_unlimited(self) -> bool:
+        return self.monthly_tokens == 0
+
+
+# Default tier budgets (configurable via BudgetConfig)
+DEFAULT_TIER_BUDGETS = {
+    0: TierBudget(tier=0, monthly_tokens=0, per_task_max=0),           # Unlimited
+    1: TierBudget(tier=1, monthly_tokens=5_000_000, per_task_max=500_000),
+    2: TierBudget(tier=2, monthly_tokens=2_000_000, per_task_max=200_000),
+    3: TierBudget(tier=3, monthly_tokens=1_000_000, per_task_max=100_000),
+}
+
+
+class BudgetConfig(BaseModel):
+    """Budget configuration for the system."""
+    tier_budgets: dict[int, TierBudget] = Field(default_factory=lambda: dict(DEFAULT_TIER_BUDGETS))
+    billing_start_day: int = 1  # Day of month billing resets
+
+    def get_tier_budget(self, tier: int) -> TierBudget:
+        return self.tier_budgets.get(tier, DEFAULT_TIER_BUDGETS.get(tier, TierBudget(tier=tier, monthly_tokens=1_000_000, per_task_max=100_000)))
+
+
+class BudgetUsage(BaseModel):
+    """A single token usage record."""
+    id: str
+    agent_id: str
+    department: str = ""
+    tier: int = 2
+    tokens: int = 0
+    workflow_id: str = ""
+    task_id: str = ""
+    description: str = ""
+    timestamp: str = ""
+    approved_by: str = ""  # Tier 0 agent who approved overrun
+
+    @property
+    def is_overrun_approved(self) -> bool:
+        return bool(self.approved_by)
+
+
+class BudgetSummary(BaseModel):
+    """Current budget status for a tier or department."""
+    tier: int
+    department: str = ""
+    period_start: str = ""
+    period_end: str = ""
+    allocated: int = 0          # Monthly allocation
+    used: int = 0               # Tokens used this period
+    remaining: int = 0          # Tokens remaining
+    percent_used: float = 0.0   # 0-100
+    is_unlimited: bool = False
+    needs_approval: bool = False  # >80% threshold
+    usage_count: int = 0        # Number of operations this period
+    overruns: int = 0           # Number of approved overruns
+
+    @property
+    def status(self) -> str:
+        if self.is_unlimited:
+            return "UNLIMITED"
+        if self.percent_used >= 100:
+            return "EXCEEDED"
+        if self.needs_approval:
+            return "APPROVAL_REQUIRED"
+        if self.percent_used >= 50:
+            return "MODERATE"
+        return "HEALTHY"

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 = ""

package/core/workflow/engine.py

@@ -48,6 +48,8 @@ class WorkflowEngine:
         on_phase_complete: Optional[Callable[[Phase, PhaseResult], None]] = None,
         on_gate_check: Optional[Callable[[Gate], GateResult]] = None,
         on_visibility: Optional[Callable[[str], None]] = None,
+        budget_manager: Any = None,
+        obsidian_writer: Any = None,
     ):
         """Initialize the workflow engine.
 
@@ -61,6 +63,8 @@ class WorkflowEngine:
         self._on_phase_complete = on_phase_complete
         self._on_gate_check = on_gate_check
         self._on_visibility = on_visibility
+        self._budget_manager = budget_manager
+        self._obsidian_writer = obsidian_writer
         self._history: list[PhaseResult] = []
 
     def announce(self, message: str) -> None:
@@ -144,6 +148,22 @@ class WorkflowEngine:
             if self._on_phase_complete:
                 self._on_phase_complete(phase, result)
 
+            # Save outputs to Obsidian vault (NON-NEGOTIABLE: obsidian-output)
+            if self._obsidian_writer and hasattr(phase, "outputs"):
+                for output in getattr(phase, "outputs", []):
+                    obsidian_path = getattr(output, "obsidian_path", "")
+                    if obsidian_path and result.output:
+                        try:
+                            saved = self._obsidian_writer.save(
+                                obsidian_path=obsidian_path,
+                                content=result.output,
+                                department=workflow.department,
+                                workflow=workflow.id,
+                            )
+                            self.announce(f"Saved to vault: {saved.name}")
+                        except Exception as e:
+                            self.announce(f"Vault save failed: {e}")
+
             self.announce(f"Phase {i}: {phase.name} — COMPLETED")
 
             # Evaluate gate
@@ -189,12 +209,36 @@ class WorkflowEngine:
         if gate.type == GateType.AUTO:
             return GateResult(passed=True, gate_type=GateType.AUTO, message="Auto-pass")
 
+        if gate.type == GateType.BUDGET_CHECK and self._budget_manager:
+            return self._evaluate_budget_gate(gate)
+
         if self._on_gate_check:
             return self._on_gate_check(gate)
 
         # Default: pass
         return GateResult(passed=True, gate_type=gate.type, message="Default pass")
 
+    def _evaluate_budget_gate(self, gate: Gate) -> GateResult:
+        """Evaluate a budget gate using the budget manager."""
+        # Default tier for budget checks (can be overridden via gate metadata)
+        tier = 2
+        estimated_tokens = 50_000  # Default estimate per phase
+
+        if self._budget_manager.check_budget(tier, estimated_tokens):
+            needs_approval = self._budget_manager.needs_approval(tier)
+            msg = "Budget OK"
+            if needs_approval:
+                msg = "Budget OK (>80% used — Tier 0 notified)"
+                self.announce(f"Budget warning: tier {tier} at >80% monthly usage")
+            return GateResult(passed=True, gate_type=GateType.BUDGET_CHECK, message=msg)
+
+        summary = self._budget_manager.get_summary(tier)
+        return GateResult(
+            passed=False,
+            gate_type=GateType.BUDGET_CHECK,
+            message=f"Budget exceeded: {summary.used}/{summary.allocated} tokens used ({summary.percent_used}%). Needs Tier 0 approval.",
+        )
+
     def _evaluate_condition(self, condition: str) -> bool:
         """Evaluate a skip/branch condition.
 

package/core/workflow/schema.py

@@ -27,6 +27,7 @@ class GateType(str, Enum):
     QUALITY_GATE = "quality_gate"       # Marta + Eduardo + Francisca
     AUTO = "auto"                       # Passes automatically if phase succeeds
     CONDITION = "condition"             # Passes if condition evaluates true
+    BUDGET_CHECK = "budget_check"       # Verifies token budget before execution
 
 
 class Gate(BaseModel):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "2.0.1"
+version = "2.0.2"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}