feat: initial bootstrap — structure, task_brief, blackboard, adapter bases, escalation, prompts

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

adapters/base/llm.py

@@ -0,0 +1,50 @@
+"""
+adapters/base/llm.py
+Abstract base class for all LLM adapters.
+"""
+from abc import ABC, abstractmethod
+
+
+class LLMAdapter(ABC):
+    """
+    Contract that every LLM provider adapter must fulfil.
+
+    Capability strings
+    ------------------
+    "reasoning-heavy"  — tasks requiring deep chain-of-thought (e.g. T1, T2)
+    "capable"          — general-purpose capable model (e.g. T3, T4)
+    "fast-cheap"       — high-volume, low-latency tasks (e.g. T5 quick checks)
+    """
+
+    @abstractmethod
+    def complete(self, prompt: str, capability: str, context: dict) -> str:
+        """
+        Send a prompt to the model and return the text response.
+
+        Parameters
+        ----------
+        prompt      : The full prompt string (system + user combined or just user).
+        capability  : One of "reasoning-heavy" | "capable" | "fast-cheap".
+        context     : Arbitrary key/value bag passed to the adapter (e.g. system
+                      prompt override, temperature, max_tokens).
+
+        Returns
+        -------
+        The model's text completion as a plain string.
+        """
+        ...
+
+    @abstractmethod
+    def resolve_model(self, capability: str) -> str:
+        """
+        Map a capability string to the concrete model identifier for this provider.
+
+        Parameters
+        ----------
+        capability : One of "reasoning-heavy" | "capable" | "fast-cheap".
+
+        Returns
+        -------
+        Model identifier string (e.g. "claude-opus-4-6", "gpt-4o").
+        """
+        ...

adapters/base/notify.py

@@ -0,0 +1,21 @@
+"""
+adapters/base/notify.py
+Abstract base class for all notification adapters.
+"""
+from abc import ABC, abstractmethod
+
+
+class NotifyAdapter(ABC):
+    """Contract that every notification provider adapter must fulfil."""
+
+    @abstractmethod
+    def send(self, message: str, context: dict) -> None:
+        """
+        Dispatch a notification.
+
+        Parameters
+        ----------
+        message : Human-readable message text.
+        context : Arbitrary metadata (e.g. channel, severity, run_id, brief_id).
+        """
+        ...

adapters/base/runtime.py

@@ -0,0 +1,64 @@
+"""
+adapters/base/runtime.py
+Abstract base class for all agent-runtime adapters.
+"""
+from abc import ABC, abstractmethod
+
+
+class RuntimeAdapter(ABC):
+    """
+    Contract that every agent runtime adapter must fulfil.
+
+    A "runtime" is responsible for dispatching a task to an actual agent
+    (e.g. an OpenClaw worker, a Claude Code sub-agent, a local subprocess)
+    and retrieving its result.
+    """
+
+    @abstractmethod
+    def spawn(self, task: str, capability: str, context: dict) -> str:
+        """
+        Start an agent to work on the given task.
+
+        Parameters
+        ----------
+        task       : Natural-language description of the work to perform.
+        capability : Capability hint — "reasoning-heavy" | "capable" | "fast-cheap".
+        context    : Arbitrary key/value bag (e.g. files, constraints, brief payload).
+
+        Returns
+        -------
+        A provider-specific agent_id string that can be used to poll for results.
+        """
+        ...
+
+    @abstractmethod
+    def get_result(self, agent_id: str, timeout_s: int) -> dict:
+        """
+        Block until the agent completes or the timeout elapses.
+
+        Parameters
+        ----------
+        agent_id  : The id returned by spawn().
+        timeout_s : Maximum seconds to wait before raising TimeoutError.
+
+        Returns
+        -------
+        A dict containing at minimum:
+            {
+                "status":   "done" | "failed" | "partial" | "blocked",
+                "output":   <str or dict>,
+                "artifacts": [...],   # optional
+            }
+        """
+        ...
+
+    @abstractmethod
+    def kill(self, agent_id: str) -> None:
+        """
+        Terminate a running agent unconditionally.
+
+        Parameters
+        ----------
+        agent_id : The id returned by spawn().
+        """
+        ...

adapters/base/vcs.py

@@ -0,0 +1,69 @@
+"""
+adapters/base/vcs.py
+Abstract base class for all Version Control System adapters.
+"""
+from abc import ABC, abstractmethod
+
+
+class VCSAdapter(ABC):
+    """Contract that every VCS provider adapter must fulfil."""
+
+    @abstractmethod
+    def create_branch(self, name: str) -> None:
+        """
+        Create a new branch with the given name.
+
+        Parameters
+        ----------
+        name : Branch name (e.g. "feat/webhook-ingestion").
+        """
+        ...
+
+    @abstractmethod
+    def commit(self, files: list[str], message: str) -> str:
+        """
+        Stage the given files and create a commit.
+
+        Parameters
+        ----------
+        files   : List of file paths to stage (relative to repo root).
+        message : Commit message.
+
+        Returns
+        -------
+        The commit SHA as a string.
+        """
+        ...
+
+    @abstractmethod
+    def create_pr(self, title: str, body: str, head: str, base: str) -> str:
+        """
+        Open a pull request.
+
+        Parameters
+        ----------
+        title : PR title.
+        body  : PR description / body markdown.
+        head  : Head branch name.
+        base  : Base branch name (e.g. "main").
+
+        Returns
+        -------
+        The URL of the created pull request.
+        """
+        ...
+
+    @abstractmethod
+    def get_pr_status(self, pr_id: str) -> str:
+        """
+        Fetch the current status of a pull request.
+
+        Parameters
+        ----------
+        pr_id : Provider-specific PR identifier (number, node-id, or URL).
+
+        Returns
+        -------
+        One of: "open" | "merged" | "closed".
+        """
+        ...