arkaos 2.0.1 → 2.0.3

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/runtime/subagent.py

@@ -102,6 +102,11 @@ class SubagentDispatcher:
     The dispatcher creates HandoffArtifacts from agent definitions
     and task descriptions, then delegates to the runtime adapter
     for actual execution.
+
+    Nesting policy: Maximum 1 level of nesting (agent -> subagent).
+    Sub-subagent dispatch is not recommended -- creates context fragmentation
+    and debugging complexity. If a subagent needs help, it should escalate
+    to its squad lead rather than spawning another subagent.
     """
 
     def __init__(self) -> None:

package/core/squads/schema.py

@@ -35,6 +35,9 @@ class SquadMember(BaseModel):
     borrowed: bool = False           # Borrowed from another department?
     source_department: str = ""      # Original department if borrowed
     availability: float = 1.0        # 0.0-1.0, for shared agents
+    # Tier 2 agents can collaborate directly within project squads
+    # without requiring Tier 1 approval for each interaction.
+    can_collaborate_directly: bool = True
 
 
 class SquadWorkflow(BaseModel):

package/core/squads/templates/project-squad.yaml

@@ -0,0 +1,28 @@
+# Project Squad Template
+# Copy and customize for cross-department projects
+id: project-{name}
+name: "{Project Name} Squad"
+description: "Cross-department squad for {project description}"
+department: ""  # No single department — cross-cutting
+squad_type: project
+topology: stream-aligned
+
+members:
+  # Borrow from department squads
+  - agent_id: "{lead-agent-id}"
+    role: "Project Lead"
+    is_lead: true
+    borrowed: true     # Borrowed from department squad
+    availability: 0.5  # 50% allocation
+
+  - agent_id: "{specialist-id}"
+    role: "Technical Implementation"
+    borrowed: true
+    availability: 0.3
+
+# Project squads:
+# - Created by COO (Sofia) or any Squad Lead
+# - Agents are borrowed, not moved
+# - Max 10 members (Two-Pizza Team)
+# - Dissolved when project completes
+# - Quality Gate still mandatory

package/core/synapse/engine.py

@@ -10,6 +10,7 @@ Design goals:
 
 import time
 from dataclasses import dataclass, field
+from typing import Any
 
 from core.synapse.layers import Layer, LayerResult, PromptContext
 from core.synapse.cache import LayerCache
@@ -152,6 +153,7 @@ def create_default_engine(
     constitution_compressed: str = "",
     commands: list[dict] | None = None,
     agents_registry: dict[str, dict] | None = None,
+    vector_store: Any = None,
 ) -> SynapseEngine:
     """Create a SynapseEngine with all 8 default layers.
 
@@ -166,7 +168,7 @@ def create_default_engine(
     from core.synapse.layers import (
         ConstitutionLayer, DepartmentLayer, AgentLayer,
         ProjectLayer, BranchLayer, CommandHintsLayer,
-        QualityGateLayer, TimeLayer,
+        QualityGateLayer, TimeLayer, KnowledgeRetrievalLayer,
     )
 
     engine = SynapseEngine()
@@ -176,6 +178,8 @@ def create_default_engine(
     engine.register_layer(DepartmentLayer())
     engine.register_layer(AgentLayer(agents_registry=agents_registry))
     engine.register_layer(ProjectLayer())
+    if vector_store is not None:
+        engine.register_layer(KnowledgeRetrievalLayer(vector_store=vector_store))
     engine.register_layer(BranchLayer())
     engine.register_layer(CommandHintsLayer(commands=commands))
     engine.register_layer(QualityGateLayer())

package/core/synapse/layers.py

@@ -1,17 +1,18 @@
-"""Synapse layer definitions — the 8 context layers.
+"""Synapse layer definitions — the 9 context layers.
 
 Each layer extracts a specific type of context and compresses it
 for injection into the prompt. Layers are pluggable and ordered.
 
 Layer Architecture:
-  L0: Constitution  — Compressed governance rules (TTL: 300s)
-  L1: Department    — Detected department from input (no cache)
-  L2: Agent         — Agent profile + last gotchas (TTL: 30s)
-  L3: Project       — Active project context (TTL: 30s)
-  L4: Branch        — Current git branch (no cache)
-  L5: Command Hints — Matching commands from registry (TTL: 30s)
-  L6: Quality Gate  — QG status and last verdicts (TTL: 60s)
-  L7: Time          — Time-of-day signal (no cache)
+  L0:   Constitution       — Compressed governance rules (TTL: 300s)
+  L1:   Department         — Detected department from input (no cache)
+  L2:   Agent              — Agent profile + last gotchas (TTL: 30s)
+  L3:   Project            — Active project context (TTL: 30s)
+  L3.5: KnowledgeRetrieval — Semantic search from vector DB (TTL: 30s)
+  L4:   Branch             — Current git branch (no cache)
+  L5:   Command Hints      — Matching commands from registry (TTL: 30s)
+  L6:   Quality Gate       — QG status and last verdicts (TTL: 60s)
+  L7:   Time               — Time-of-day signal (no cache)
 """
 
 import re
@@ -439,3 +440,88 @@ class TimeLayer(Layer):
             layer_id=self.id, tag=tag, content=period,
             tokens_est=1, compute_ms=ms, cached=False,
         )
+
+
+# --- L3.5: Knowledge Retrieval ---
+
+class KnowledgeRetrievalLayer(Layer):
+    """L3.5: Semantic knowledge retrieval from vector DB.
+
+    Searches the local vector store for chunks relevant to the user's
+    input and injects them as context. Gracefully skips if vector store
+    is unavailable or empty.
+    """
+
+    def __init__(self, vector_store: Any = None, max_chunks: int = 3, max_tokens: int = 400) -> None:
+        self._store = vector_store
+        self._max_chunks = max_chunks
+        self._max_tokens = max_tokens
+
+    @property
+    def id(self) -> str:
+        return "L3.5"
+
+    @property
+    def name(self) -> str:
+        return "KnowledgeRetrieval"
+
+    @property
+    def cache_ttl(self) -> int:
+        return 30
+
+    @property
+    def priority(self) -> int:
+        return 35
+
+    def compute(self, ctx: PromptContext) -> LayerResult:
+        start = time.time()
+
+        if not self._store or not ctx.user_input:
+            return LayerResult(
+                layer_id=self.id, tag="", content="",
+                tokens_est=0, compute_ms=0, cached=False,
+            )
+
+        try:
+            results = self._store.search(ctx.user_input, top_k=self._max_chunks)
+        except Exception:
+            return LayerResult(
+                layer_id=self.id, tag="", content="",
+                tokens_est=0, compute_ms=0, cached=False,
+            )
+
+        if not results:
+            ms = int((time.time() - start) * 1000)
+            return LayerResult(
+                layer_id=self.id, tag="", content="",
+                tokens_est=0, compute_ms=ms, cached=False,
+            )
+
+        # Build compact knowledge context
+        snippets = []
+        total_tokens = 0
+        for r in results:
+            text = r["text"][:200].replace("\n", " ").strip()
+            tokens = len(text.split())
+            if total_tokens + tokens > self._max_tokens:
+                break
+            source = r.get("source", "").split("/")[-1] if r.get("source") else ""
+            snippet = f"{source}: {text}" if source else text
+            snippets.append(snippet)
+            total_tokens += tokens
+
+        if not snippets:
+            ms = int((time.time() - start) * 1000)
+            return LayerResult(
+                layer_id=self.id, tag="", content="",
+                tokens_est=0, compute_ms=ms, cached=False,
+            )
+
+        content = " | ".join(snippets)
+        tag = f"[knowledge:{len(snippets)} chunks]"
+        ms = int((time.time() - start) * 1000)
+
+        return LayerResult(
+            layer_id=self.id, tag=tag, content=content,
+            tokens_est=total_tokens, compute_ms=ms, cached=False,
+        )

package/core/tasks/schema.py

@@ -29,6 +29,7 @@ class TaskType(str, Enum):
     RESEARCH = "research"             # Background research
     GENERATION = "generation"         # AI content/image generation
     EXPORT = "export"                 # Export to external system
+    KB_INDEX = "kb_index"           # Index documents into vector store
     CUSTOM = "custom"
 
 
@@ -47,6 +48,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/departments/dev/agents/research-assistant.yaml

@@ -0,0 +1,51 @@
+id: research-assistant
+name: Maria
+role: Research Assistant
+department: dev
+tier: 3
+
+behavioral_dna:
+  disc:
+    primary: C
+    secondary: S
+    communication_style: "Thorough, detail-oriented, presents findings systematically"
+    under_pressure: "Digs deeper into data before responding"
+    motivator: "Understanding the full picture"
+  enneagram:
+    type: 5
+    wing: 6
+    core_motivation: "To understand and be competent"
+    core_fear: "Being ignorant or uninformed"
+    subtype: social
+  big_five:
+    openness: 90
+    conscientiousness: 85
+    extraversion: 30
+    agreeableness: 70
+    neuroticism: 35
+  mbti:
+    type: INTP
+
+authority:
+  veto: false
+  approve_budget: false
+  approve_architecture: false
+  approve_quality: false
+  block_release: false
+  block_delivery: false
+  orchestrate: false
+  delegates_to: []
+  escalates_to: tech-lead-paulo
+
+expertise:
+  domains: ["research", "documentation", "analysis", "literature-review"]
+  frameworks: ["Systematic Review", "PRISMA", "Research Methodology"]
+  depth: proficient
+  years_equivalent: 5
+
+communication:
+  language: en
+  tone: "Precise and informative"
+  vocabulary_level: specialist
+  preferred_format: "Structured reports with citations"
+  avoid: ["assumptions without evidence", "vague conclusions"]

package/departments/kb/agents/data-collector.yaml

@@ -0,0 +1,51 @@
+id: data-collector
+name: Tomas Jr
+role: Data Collector
+department: kb
+tier: 3
+
+behavioral_dna:
+  disc:
+    primary: C
+    secondary: D
+    communication_style: "Data-driven, factual, structured"
+    under_pressure: "Relies on systematic data collection"
+    motivator: "Complete and accurate data"
+  enneagram:
+    type: 6
+    wing: 5
+    core_motivation: "To have reliable information"
+    core_fear: "Making decisions on incomplete data"
+    subtype: self-preservation
+  big_five:
+    openness: 70
+    conscientiousness: 88
+    extraversion: 35
+    agreeableness: 65
+    neuroticism: 40
+  mbti:
+    type: ISTJ
+
+authority:
+  veto: false
+  approve_budget: false
+  approve_architecture: false
+  approve_quality: false
+  block_release: false
+  block_delivery: false
+  orchestrate: false
+  delegates_to: []
+  escalates_to: kb-lead-clara
+
+expertise:
+  domains: ["data-collection", "web-scraping", "API-integration", "data-validation"]
+  frameworks: ["ETL", "Data Quality Framework"]
+  depth: proficient
+  years_equivalent: 4
+
+communication:
+  language: en
+  tone: "Factual and precise"
+  vocabulary_level: specialist
+  preferred_format: "Data tables with quality scores"
+  avoid: ["subjective interpretations", "unverified claims"]