execforge 0.1.0__py3-none-any.whl

execforge-0.1.0.dist-info/METADATA

@@ -0,0 +1,367 @@
+Metadata-Version: 2.4
+Name: execforge
+Version: 0.1.0
+Summary: Production-minded local CLI for autonomous repo orchestration
+Author: Open Source Contributors
+License: MIT License
+        
+        Copyright (c) 2026 Matt
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12.0
+Requires-Dist: SQLAlchemy>=2.0.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: platformdirs>=4.2.0
+Requires-Dist: rich>=13.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Dynamic: license-file
+
+# Execforge
+
+`execforge` is a local CLI that takes tasks from one repo and applies them to another repo.
+
+## How to think about it
+
+Keep this simple mental model:
+
+- **Prompt source**: where tasks come from (a git repo with task files)
+- **Project repo**: the codebase that gets changed
+- **Agent**: the execution profile that connects the two and runs tasks
+
+That is the whole product loop.
+
+## Install
+
+Choose one:
+
+```bash
+# recommended
+pipx install execforge
+
+# or
+pip install execforge
+
+# local dev
+pip install -e .
+```
+
+Install with Python virtualenv (local dev):
+
+```bash
+# 1) create a virtual environment (Python 3.11+)
+python -m venv .venv
+
+# 2) activate it
+# Windows (PowerShell)
+.venv\Scripts\Activate.ps1
+# Windows (cmd)
+.venv\Scripts\activate.bat
+# macOS/Linux
+source .venv/bin/activate
+
+# 3) upgrade packaging tools (recommended)
+python -m pip install --upgrade pip setuptools wheel
+
+# 4) install this project in editable mode
+pip install -e .
+
+# 5) verify CLI install
+execforge --help
+```
+
+Check install:
+
+```bash
+execforge --help
+```
+
+Aliases also work: `agent-orchestrator`, `orchestrator`, `agent-controlplane`.
+
+## Quick start (workflow-first)
+
+### 1) Initialize
+
+```bash
+execforge init
+```
+
+The init wizard guides setup for first prompt source, project repo, and agent.
+
+### 2) Connect a task source
+
+```bash
+execforge prompt-source add prompts https://github.com/your-org/prompt-repo.git --branch main --folder-scope tasks
+execforge prompt-source sync prompts
+```
+
+If remote branch is missing and you want Execforge to create/push it:
+
+```bash
+execforge prompt-source sync prompts --bootstrap-missing-branch
+```
+
+### 3) Connect a project repo
+
+```bash
+execforge project add app ~/src/my-app
+```
+
+### 4) Create an agent
+
+```bash
+execforge agent add app-agent prompts app --execution-backend multi
+
+# ids also work if you prefer
+execforge agent add app-agent 1 1 --execution-backend multi
+```
+
+### 5) Run the agent
+
+One run:
+
+```bash
+execforge agent run app-agent
+```
+
+Continuous loop:
+
+```bash
+execforge agent loop app-agent
+```
+
+Loop defaults to new prompts only. If you want existing eligible tasks too:
+
+```bash
+execforge agent loop app-agent --all-eligible-prompts
+```
+
+### 6) Inspect results
+
+```bash
+execforge task list
+execforge run list
+execforge status
+```
+
+## Daily workflow
+
+```bash
+execforge status
+execforge prompt-source sync <source-name>
+execforge agent run <agent-name>
+execforge run list
+```
+
+If you want continuous polling:
+
+```bash
+execforge agent loop <agent-name>
+```
+
+## Backends (Claude/Codex/OpenCode/Shell)
+
+Backends are interchangeable execution options for task steps.
+
+- `shell` for explicit commands
+- `claude`, `codex`, `opencode` when those CLIs are installed and enabled
+- `mock` fallback backend for local/dev flows
+
+Tasks can express preferences per step, and Execforge routes each step to an available backend.
+
+## Task format
+
+Tasks can be Markdown with YAML frontmatter or pure YAML.
+
+```markdown
+---
+id: quick-001
+title: Create scaffold
+status: todo
+steps:
+  - id: create
+    type: shell
+    tool_preferences: [shell]
+    command: python -m pytest
+  - id: summarize
+    type: llm_summary
+    tool_preferences: [codex, claude, opencode, mock]
+    model: ollama/llama3.2
+---
+
+Create project scaffold.
+```
+
+For OpenCode steps, `model` maps to `--model <provider/model>`.
+
+Optional task-level git overrides:
+
+```yaml
+git:
+  base_branch: main
+  work_branch: agent/custom/quick-001
+  push_on_success: false
+```
+
+Defaults (when omitted):
+
+- `base_branch`: project repo default branch
+- `work_branch`: `agent/<agent-name>/<task-id>`
+- `push_on_success`: agent push policy
+
+## Managing configs
+
+### App config
+
+```bash
+execforge config                # defaults to config show
+execforge config show
+execforge config keys
+execforge config set log_level DEBUG
+execforge config set --set default_timeout_seconds=120 --set default_allow_push=true
+execforge config reset default_timeout_seconds
+execforge config reset --all
+```
+
+Sensitive values are masked in `config show`.
+
+### Agent config
+
+```bash
+execforge agent                # defaults to agent list
+execforge agent list           # full JSON blocks
+execforge agent update test-agent --set max_steps=40 --set push_policy=on-success
+execforge agent update test-agent --set safety_settings.allow_push=true
+execforge agent delete test-agent --yes
+```
+
+## Commands by workflow
+
+### Setup
+
+- `execforge init`
+- `execforge doctor`
+
+### Prompt sources (task origin)
+
+- `execforge prompt-source add`
+- `execforge prompt-source list`
+- `execforge prompt-source sync`
+
+### Project repos (code targets)
+
+- `execforge project add`
+- `execforge project list`
+
+### Agents (execution profiles)
+
+- `execforge agent add`
+- `execforge agent list`
+- `execforge agent list --compact`
+- `execforge agent update`
+- `execforge agent delete`
+- `execforge agent run <agent-name-or-id>`
+- `execforge agent loop <agent-name-or-id>`
+
+### Task and run inspection
+
+- `execforge task list`
+- `execforge task inspect <task-id>`
+- `execforge task set-status <task-id> <status>`
+- `execforge task retry <task-id>`
+- `execforge run list`
+- `execforge status`
+- `execforge start`
+
+## When nothing runs
+
+If a run ends with noop, Execforge prints the reason and next step.
+
+Common reasons:
+
+- no task files were discovered in the prompt source scope
+- all tasks are already in the current only-new baseline
+- all tasks are already complete
+- tasks exist but none are currently actionable
+
+Useful fixes:
+
+```bash
+execforge prompt-source sync <source-name>
+execforge task list
+execforge agent loop <agent-name> --all-eligible-prompts
+execforge agent loop <agent-name> --reset-only-new-baseline
+```
+
+`--reset-only-new-baseline` applies to the first loop run, then loop returns to normal only-new behavior.
+
+## Where state is stored
+
+Execforge keeps state outside your project repos.
+
+Default location:
+
+- Linux: `~/.local/share/agent-orchestrator/`
+- macOS: `~/Library/Application Support/agent-orchestrator/`
+- Windows: `%LOCALAPPDATA%\agent-orchestrator\agent-orchestrator\`
+
+Override:
+
+```bash
+export AGENT_ORCHESTRATOR_HOME=~/.agent-orchestrator
+```
+
+## More docs
+
+- `docs/USAGE_WALKTHROUGH.md` - practical end-to-end flow
+- `docs/ARCHITECTURE.md` - implementation layout
+
+## CI/CD and PyPI publish
+
+This repo includes GitHub Actions pipelines:
+
+- `.github/workflows/ci.yml` - lint, tests, package build, and `twine check`
+- `.github/workflows/publish-testpypi.yml` - manual publish to TestPyPI
+- `.github/workflows/publish-pypi.yml` - publish to PyPI on release (and manual dispatch)
+
+Required repository secrets:
+
+- `TEST_PYPI_API_TOKEN` for TestPyPI publishing
+- `PYPI_API_TOKEN` for PyPI publishing
+
+Typical release flow:
+
+```bash
+# 1) bump version in pyproject.toml
+# 2) commit and tag
+git tag v0.1.1
+git push origin main --tags
+
+# 3) create/publish a GitHub Release for that tag
+#    -> triggers publish-pypi.yml
+```
+
+## License
+
+MIT (see `LICENSE`).

execforge-0.1.0.dist-info/RECORD

@@ -0,0 +1,44 @@
+execforge-0.1.0.dist-info/licenses/LICENSE,sha256=cvc_iNTDxqu0RnxCLH1kfw5ZN03VGI-mCTNn8YSv298,1061
+orchestrator/__init__.py,sha256=sVTlg8Mreo_-UsTaq3FkULJqoo_lQTRnte8MlRVnbS4,82
+orchestrator/__main__.py,sha256=0mzzNd99pzV8Lre8wuEYl2sJ1nkssz41AMfehCOEqP0,77
+orchestrator/config.py,sha256=eWCk_GFyMBewvsU-2gyWSs9t3mRYILzDgODabPO4Rko,8288
+orchestrator/exceptions.py,sha256=RVSFX35PNDt48f4Wfph0aSddxDks1dAzWFTAa6pdNiE,474
+orchestrator/logging_setup.py,sha256=OG1tKygZ14-xI6-LImoaIJ2nAD-pckJ73H8c4NyfWlk,1588
+orchestrator/backends/__init__.py,sha256=a2z3ZihR1jKmZAOey9NGAR0J05fiHy4oiOoyImAcV7w,41
+orchestrator/backends/base.py,sha256=M3JAe-zzigSpO2R45bQQfpYY9etJ_hckwpwNl3TMyao,714
+orchestrator/backends/factory.py,sha256=D6SabjN-MvvrxKXfW7T4-OeU8q6X1oiWIkCJtO-bxrM,2334
+orchestrator/backends/llm_cli_backend.py,sha256=i5YNSiRjY4DRLVaby_OQgGiO3QYyFypsOlZ16fXr4tM,3433
+orchestrator/backends/mock_backend.py,sha256=6z5txdyZfqUK-aLV2KpG6l2UUWYJb9nzp86M9eDhLL0,1186
+orchestrator/backends/shell_backend.py,sha256=8W_am3a-KsLe1bUJ7O5lSes8CWGCts2DkNbEeEaa-0Q,2004
+orchestrator/cli/__init__.py,sha256=C63yWifzpA0IV7YWDatpAdrhoV8zjqxAKv0xMf09VdM,19
+orchestrator/cli/main.py,sha256=cLJYQfhIXnC6aDG_cb8028hvIdT-oUlAivMIR7e6A48,35253
+orchestrator/domain/__init__.py,sha256=aEZTR2LNKnB0Q_VRUoh4kzbnL5CMWHXq82uDu0rTY9E,38
+orchestrator/domain/types.py,sha256=TKix6w8H9lYwDPvmOk0kFm3Kbkf6XyO6w3L8oJvFLWo,1864
+orchestrator/git/__init__.py,sha256=tcVcTMg1slpazqrZbSsWk0L7UrjnZ861j_t0lONu_5E,32
+orchestrator/git/service.py,sha256=GiBlH4DVZTeY-UVLjYrIMgvcqVF5PgzbPsWbAPmIXts,9409
+orchestrator/prompts/__init__.py,sha256=EZ1sIIbFt6qlcow-dw89fxsRdCNlwW9AEKetDwQuUQY,39
+orchestrator/prompts/parser.py,sha256=bRrza8RMdeoHrEaa34z2S_munsJsjC1KUhvRj_1MvvA,3160
+orchestrator/reporting/__init__.py,sha256=9wpbZKzl2pdXG7C24Cbxm3vvE0jrBK4QPB9gfxzKrjo,57
+orchestrator/reporting/console.py,sha256=q6ihIXj9oYfvAgq3n_jJItlzZAI6PYWxB1l1uKl1-P8,8374
+orchestrator/reporting/events.py,sha256=hbqFFFVxVeIU0yU4Lzikfe_c7RP63RNocbUzP8F9tT0,1272
+orchestrator/reporting/selection_result.py,sha256=Qf_UMHKFrR5IXv6NN5HZDGuBESUdXjPTowvxV1XHB0Q,344
+orchestrator/services/__init__.py,sha256=Sz5tMokf5S97Gjyb7eiPsqTJXf23yyRfsAzhMcX3PAw,33
+orchestrator/services/agent_runner.py,sha256=dop7r1C0OhYsh3wmFeiB9t3PzWP4909x7_6zFO3-nCg,32749
+orchestrator/services/agent_service.py,sha256=rZgUqU1mO8YYcMF2Sz95Xwl5Z3kbNEOA2xrAAgzWUpE,4916
+orchestrator/services/project_service.py,sha256=lT3KvjtwaeMW8dqnRW-MWznxhv3DcurUrn6s7u24QBM,1476
+orchestrator/services/prompt_source_service.py,sha256=OEgdl2xirSTX6A6OeVIVe-vZRgYcgSvQ-ndKuwkUVK8,2222
+orchestrator/services/run_service.py,sha256=Z_HMO22sBrXemVpLGdcSkyYw4nw_--AReA1x8Mr6F9M,1385
+orchestrator/services/step_executor.py,sha256=OFrioHEfrOZYbxNyAAVIFRMLRkbRIWI9WuVa2zqQ7oA,4153
+orchestrator/services/task_service.py,sha256=rcZNBZPsZ6991-S7TeAoqL6NL_NloSI4P_jxUC-bRfs,6003
+orchestrator/storage/__init__.py,sha256=kCNaKkkO_VlrVA7STduJRORDeFWeQo4c-6RpKrV2mqA,36
+orchestrator/storage/db.py,sha256=94QH32-27ETcBqxr5EbHiIe_7Ze2vO2GpWMGhj7lbdU,596
+orchestrator/storage/models.py,sha256=xVjfcve82o7eiaBnitgdbm1dEJx56rYnp9XfagwREwg,5134
+orchestrator/utils/__init__.py,sha256=vTzpzAhwZwhp9xdzSN95SWmf02qgw7Asc0ULXG4aEok,23
+orchestrator/utils/process.py,sha256=r4VAf3j5wQXmfOZxDE5qgDbNFoCa6HKZK2Hy2DSv6QE,1346
+orchestrator/validation/__init__.py,sha256=tkPEbS5j_o_LJ-ysUg3odTtSQl1MUA3o9Tc5YbFaA-U,35
+orchestrator/validation/pipeline.py,sha256=45M6c8G1vhJNlvF8x4tTFxwK2FLOwhoK4GCjEaThiqQ,2203
+execforge-0.1.0.dist-info/METADATA,sha256=4jaYban7pMlceaNcKrj1lsai0CE-768iOULj-3fvFmM,8686
+execforge-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+execforge-0.1.0.dist-info/entry_points.txt,sha256=TyH7qOa2W18eODIdQQ2bn4kXI7i8f8ESb2791SeTtYQ,195
+execforge-0.1.0.dist-info/top_level.txt,sha256=xxQ-0cX7ZiHS5jT83NoSu1MB43Iw3IGXRlLTZrI3QX4,13
+execforge-0.1.0.dist-info/RECORD,,

execforge-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

execforge-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+agent-controlplane = orchestrator.cli.main:main
+agent-orchestrator = orchestrator.cli.main:main
+execforge = orchestrator.cli.main:main
+orchestrator = orchestrator.cli.main:main

execforge-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

execforge-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+orchestrator

orchestrator/__init__.py

@@ -0,0 +1,4 @@
+"""Repo orchestrator package."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

orchestrator/__main__.py

@@ -0,0 +1,5 @@
+from orchestrator.cli.main import app
+
+
+if __name__ == "__main__":
+    app()

orchestrator/backends/__init__.py

@@ -0,0 +1 @@
+"""Execution backend implementations."""

orchestrator/backends/base.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from orchestrator.domain.types import BackendContext, BackendResult, TaskStep
+from orchestrator.storage.models import TaskORM
+
+
+class ExecutionBackend(ABC):
+    name: str
+    supported_step_types: set[str]
+
+    def supports(self, step: TaskStep) -> bool:
+        return step.type in self.supported_step_types
+
+    def is_available(self) -> bool:
+        return True
+
+    @abstractmethod
+    def execute_step(
+        self,
+        step: TaskStep,
+        task: TaskORM,
+        project_path: Path,
+        prompt_root: Path,
+        context: BackendContext,
+    ) -> BackendResult:
+        raise NotImplementedError

orchestrator/backends/factory.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import json
+
+from orchestrator.backends.base import ExecutionBackend
+from orchestrator.backends.llm_cli_backend import LlmCliBackend
+from orchestrator.backends.mock_backend import MockBackend
+from orchestrator.backends.shell_backend import ShellBackend
+from orchestrator.exceptions import ConfigError
+from orchestrator.storage.models import AgentORM
+
+
+def build_backend_registry(agent: AgentORM) -> dict[str, ExecutionBackend]:
+    settings = json.loads(agent.model_settings_json or "{}")
+    safety = json.loads(agent.safety_settings_json or "{}")
+    backends_cfg = settings.get("backends", {})
+
+    registry: dict[str, ExecutionBackend] = {}
+
+    shell_cfg = backends_cfg.get("shell", {})
+    if agent.execution_backend == "shell" or shell_cfg.get("enabled", True):
+        command_template = settings.get("command_template") or shell_cfg.get("command_template")
+        allowed = shell_cfg.get("allowed_commands", safety.get("allowed_commands", []))
+        registry["shell"] = ShellBackend(command_template=command_template, allowed_commands=allowed)
+
+    for tool, defaults in {
+        "claude": {"binary": "claude", "args": ["-p"], "model_arg_name": None},
+        "codex": {"binary": "codex", "args": ["exec", "--prompt"], "model_arg_name": None},
+        "opencode": {"binary": "opencode", "args": ["run"], "model_arg_name": "--model"},
+    }.items():
+        cfg = backends_cfg.get(tool, {})
+        if not cfg.get("enabled", False):
+            continue
+        registry[tool] = LlmCliBackend(
+            name=tool,
+            binary=cfg.get("binary", defaults["binary"]),
+            args=list(cfg.get("args", defaults["args"])),
+            prompt_arg_template=cfg.get("prompt_arg_template", "{prompt}"),
+            requires_binary=bool(cfg.get("requires_binary", True)),
+            model_arg_name=cfg.get("model_arg_name", defaults["model_arg_name"]),
+        )
+
+    registry["mock"] = MockBackend()
+
+    if not registry:
+        raise ConfigError("No execution backends are enabled for this agent")
+    return registry
+
+
+def default_backend_priority(agent: AgentORM) -> list[str]:
+    settings = json.loads(agent.model_settings_json or "{}")
+    priority = list(settings.get("backend_priority", []) or [])
+    return priority or ["codex", "claude", "opencode", "shell", "mock"]

orchestrator/backends/llm_cli_backend.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from pathlib import Path
+import shlex
+import shutil
+
+from orchestrator.backends.base import ExecutionBackend
+from orchestrator.domain.types import BackendContext, BackendResult, TaskStep
+from orchestrator.exceptions import BackendError
+from orchestrator.storage.models import TaskORM
+from orchestrator.utils.process import run_command
+
+
+class LlmCliBackend(ExecutionBackend):
+    supported_step_types = {"llm_plan", "code_edit", "llm_summary"}
+
+    def __init__(
+        self,
+        name: str,
+        binary: str,
+        args: list[str] | None = None,
+        prompt_arg_template: str = "{prompt}",
+        requires_binary: bool = True,
+        model_arg_name: str | None = None,
+    ):
+        self.name = name
+        self.binary = binary
+        self.args = list(args or [])
+        self.prompt_arg_template = prompt_arg_template
+        self.requires_binary = requires_binary
+        self.model_arg_name = model_arg_name
+
+    def execute_step(
+        self,
+        step: TaskStep,
+        task: TaskORM,
+        project_path: Path,
+        prompt_root: Path,
+        context: BackendContext,
+    ) -> BackendResult:
+        if not self.is_available():
+            raise BackendError(f"Backend '{self.name}' unavailable: executable '{self.binary}' not found in PATH")
+
+        prompt = self._resolve_prompt(step, task, prompt_root)
+        cmd = [self.binary, *self.args]
+
+        # Optional per-step model override: step.metadata["model"] = "provider/model"
+        # Example: model: ollama/llama3.2
+        step_model = step.metadata.get("model") if isinstance(step.metadata, dict) else None
+        if step_model and self.model_arg_name and not self._has_arg(self.model_arg_name):
+            cmd.extend([self.model_arg_name, str(step_model)])
+
+        cmd.append(self.prompt_arg_template.format(prompt=prompt))
+        result = run_command(cmd, cwd=project_path, timeout=context.timeout_seconds)
+        summary = f"{self.name} exited with code {result.code}"
+        if result.code == 127:
+            summary = (
+                f"{self.name} executable not found. "
+                f"Install '{self.binary}', disable this backend, or enable mock fallback for the agent"
+            )
+        return BackendResult(
+            success=result.code == 0,
+            summary=summary,
+            stdout=result.stdout,
+            stderr=result.stderr,
+            tool_invocations=[{"tool": self.name, "step": step.id, "command": shlex.join(cmd), "exit_code": result.code}],
+        )
+
+    def is_available(self) -> bool:
+        if not self.requires_binary:
+            return True
+        return shutil.which(self.binary) is not None
+
+    def _resolve_prompt(self, step: TaskStep, task: TaskORM, prompt_root: Path) -> str:
+        if step.prompt_inline:
+            return step.prompt_inline
+        if step.prompt_file:
+            task_file_path = prompt_root / task.source_path
+            candidates = [task_file_path.parent / step.prompt_file, prompt_root / step.prompt_file]
+            for candidate in candidates:
+                if candidate.exists():
+                    return candidate.read_text(encoding="utf-8")
+            raise BackendError(f"Prompt file not found for step '{step.id}': {step.prompt_file}")
+        return task.description
+
+    def _has_arg(self, flag: str) -> bool:
+        return any(arg == flag or arg.startswith(f"{flag}=") for arg in self.args)

orchestrator/backends/mock_backend.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from orchestrator.backends.base import ExecutionBackend
+from orchestrator.domain.types import BackendContext, BackendResult, TaskStep
+from orchestrator.storage.models import TaskORM
+
+
+class MockBackend(ExecutionBackend):
+    name = "mock"
+    supported_step_types = {"llm_plan", "llm_summary", "code_edit", "shell"}
+
+    def execute_step(
+        self,
+        step: TaskStep,
+        task: TaskORM,
+        project_path: Path,
+        prompt_root: Path,
+        context: BackendContext,
+    ) -> BackendResult:
+        marker = project_path / ".orchestrator"
+        marker.mkdir(parents=True, exist_ok=True)
+        task_ref = task.external_id or f"task-{task.id}"
+        out_file = marker / f"{task_ref}-{step.id}.txt"
+        out_file.write_text(
+            f"Completed by mock backend for {task_ref}:{step.id} ({step.type})\n\n{task.description}\n",
+            encoding="utf-8",
+        )
+        return BackendResult(
+            success=True,
+            summary=f"Mock backend completed step {step.id}",
+            tool_invocations=[{"tool": "mock_backend", "step": step.id, "output": str(out_file)}],
+        )