director-cli 0.3.0__py3-none-any.whl

director/setup.py

@@ -0,0 +1,101 @@
+"""Install Director's OpenCode agent definitions into a target repo.
+
+Director drives OpenCode with `--agent <role> --model <tier>`; the agent markdown
+supplies the role's system prompt + permissions, and the resolved tier model
+comes from config via `--model`. This module renders the bundled agent templates
+into <repo>/.opencode/agents/ (a.k.a. the `director sync-agents` step).
+
+Provider auth (Bedrock/OpenRouter keys, the LM Studio endpoint) is the operator's
+responsibility — it lives in the user's *global* OpenCode config. We add the
+project-local agent files, a starter opencode.json if the repo has none, and seed
+a ready-to-edit .director/config.toml from the bundled example (if none exists).
+"""
+
+from __future__ import annotations
+
+import importlib.resources as ir
+from pathlib import Path
+
+AGENT_FILES = (
+    "brainstorm.md",
+    "planner.md",
+    "explorer.md",
+    "test-author.md",
+    "executor.md",
+    "reviewer.md",
+)
+
+# A complete, commented example config ships inside the package. sync-agents seeds
+# it to <repo>/.director/config.toml (if missing) so a pip-installed user has a
+# ready-to-edit config rather than nothing.
+CONFIG_EXAMPLE = "config.example.toml"
+
+# Runtime artifacts director writes into <repo>/.director/. These must never be
+# committed: director's own commits use `git add -A` (to capture whatever the
+# executor created in the allowlist), which in a repo without this ignore file
+# would sweep these throwaway files into the job branch — then a later run that
+# rewrites them leaves a dirty TRACKED file, which makes `git checkout` refuse
+# (this bit `director bench` live). config.toml + profiles/ stay tracked.
+_DIRECTOR_GITIGNORE = """\
+# director runtime artifacts (generated per run). config.toml + profiles/ stay tracked.
+state.json
+plan.json
+plan_stage.json
+spec.md
+recon.md
+costs.jsonl
+metrics.jsonl
+logs/
+bench/
+worktrees/
+"""
+
+
+def _template(name: str) -> str:
+    return ir.files("director.agent_templates").joinpath(name).read_text()
+
+
+def _example_config() -> str:
+    return ir.files("director").joinpath(CONFIG_EXAMPLE).read_text()
+
+
+def ensure_director_gitignore(repo: str | Path) -> None:
+    """Seed <repo>/.director/.gitignore so director's `git add -A` commits never
+    sweep its own runtime files into the repo. Idempotent; safe to call on every
+    plan/run. (Does not retroactively untrack files already committed in a repo
+    that ran director before this existed — for those, `git rm --cached` once.)"""
+    fdir = Path(repo) / ".director"
+    fdir.mkdir(parents=True, exist_ok=True)
+    gi = fdir / ".gitignore"
+    current = gi.read_text() if gi.exists() else None
+    if current != _DIRECTOR_GITIGNORE:
+        gi.write_text(_DIRECTOR_GITIGNORE)
+
+
+def sync_agents(repo: str | Path) -> list[str]:
+    """Render agent_templates/*.md into <repo>/.opencode/agents/. Returns the
+    list of files written."""
+    repo = Path(repo)
+    ensure_director_gitignore(repo)
+    agents_dir = repo / ".opencode" / "agents"
+    agents_dir.mkdir(parents=True, exist_ok=True)
+    written = []
+    for name in AGENT_FILES:
+        dest = agents_dir / name
+        dest.write_text(_template(name))
+        written.append(str(dest.relative_to(repo)))
+
+    # Starter opencode.json only if the repo has none (never clobber).
+    oc = repo / ".opencode" / "opencode.json"
+    if not oc.exists():
+        oc.write_text(_template("opencode.json"))
+        written.append(str(oc.relative_to(repo)))
+
+    # Seed a ready-to-edit config from the bundled example — but never clobber an
+    # existing config the user may have edited.
+    cfg = repo / ".director" / "config.toml"
+    if not cfg.exists():
+        cfg.parent.mkdir(parents=True, exist_ok=True)
+        cfg.write_text(_example_config())
+        written.append(str(cfg.relative_to(repo)))
+    return written

director/state.py

@@ -0,0 +1,43 @@
+"""Resumable run state persisted to .director/state.json."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from pathlib import Path
+
+from director.models import DONE, PENDING, NodeState
+
+
+class RunState:
+    def __init__(self, path: Path, job_id: str):
+        self.path = Path(path)
+        self.job_id = job_id
+        self.nodes: dict[str, NodeState] = {}
+
+    @classmethod
+    def load_or_init(cls, repo: Path, plan) -> RunState:
+        path = Path(repo) / ".director" / "state.json"
+        rs = cls(path, plan.job_id)
+        if path.exists():
+            d = json.loads(path.read_text())
+            if d.get("job_id") == plan.job_id:
+                rs.nodes = {k: NodeState(**v) for k, v in d.get("nodes", {}).items()}
+        for n in plan.nodes:
+            rs.nodes.setdefault(n.id, NodeState(id=n.id, status=PENDING))
+        return rs
+
+    def save(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(
+            json.dumps(
+                {"job_id": self.job_id, "nodes": {k: asdict(v) for k, v in self.nodes.items()}},
+                indent=2,
+            )
+        )
+
+    def done_ids(self) -> set[str]:
+        return {k for k, v in self.nodes.items() if v.status == DONE}
+
+    def __getitem__(self, node_id: str) -> NodeState:
+        return self.nodes[node_id]

director_cli-0.3.0.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: director-cli
+Version: 0.3.0
+Summary: Model-agnostic decomposition coding harness — a thin orchestrator over OpenCode
+Project-URL: Homepage, https://github.com/manziman/director
+Project-URL: Repository, https://github.com/manziman/director
+Project-URL: Issues, https://github.com/manziman/director/issues
+Project-URL: Changelog, https://github.com/manziman/director/blob/main/CHANGELOG.md
+Author-email: Christopher Manzi <chris@minimus.tech>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,cli,code-generation,coding-agent,decomposition,llm,opencode,orchestration,tdd
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# director
+
+**A model-agnostic decomposition coding harness — a thin orchestrator over [OpenCode](https://opencode.ai).**
+
+director tests one hypothesis:
+
+> A strong **planner** model decomposes a coding task into small, atomic, well-specified
+> units with acceptance tests written *first*. A cheaper **executor** model — local or
+> low-cost cloud — implements each unit in an isolated, fresh context. **Deterministic
+> gates** (tests, lint, typecheck — exit codes, never an LLM's opinion) decide what
+> merges. This cuts token cost dramatically with minimal quality loss.
+
+It is **model-agnostic by construction**: roles (`planner`, `executor`, `reviewer`, …)
+bind to `provider/model` strings in config. Switching the executor from a local 27B to
+a frontier model — or anything in between — is a one-line config edit, never a code
+change. director drives OpenCode headlessly, so it inherits OpenCode's 75+ providers.
+
+> **Status:** beta. Validated end-to-end (plan → run → bench) under local, cheap-cloud,
+> and all-frontier executor tiers.
+
+---
+
+## Install
+
+director is a pure-standard-library Python CLI (no dependencies), so it installs anywhere
+Python 3.11+ runs:
+
+```bash
+uv tool install director-cli      # recommended
+# or
+pipx install director-cli
+# or
+pip install director-cli
+```
+
+### Prerequisites (runtime)
+
+director orchestrates other tools rather than replacing them, so it needs:
+
+- **Python ≥ 3.11**
+- **git** on `PATH` (isolation is real git worktrees + branches)
+- **[OpenCode](https://opencode.ai)** on `PATH` (the agent runtime director drives)
+- **Provider auth** configured in OpenCode (`opencode auth`): your planner/executor
+  model providers — e.g. Anthropic/Bedrock, OpenRouter, or a local OpenAI-compatible
+  endpoint such as LM Studio for the `local-first` profile.
+
+director never manages provider keys itself — that lives in your OpenCode config.
+
+---
+
+## Quickstart
+
+```bash
+cd your-repo
+
+# 1. Install director's role agents into .opencode/ and seed .director/config.toml
+director sync-agents
+
+# 2. Edit .director/config.toml — bind roles to models, set your gate commands.
+#    (sync-agents seeded it from the bundled, fully-commented example.)
+$EDITOR .director/config.toml
+
+# 3. Plan: brainstorm → spec → test-gated task DAG (two approval gates)
+director plan "Add a --json flag to the export command"
+
+#    …review .director/spec.md, then continue; review the plan, then continue:
+director plan --continue            # after approving the spec
+director plan --continue            # after approving the plan + failing tests
+
+# 4. Run the DAG: isolated worktree per node, deterministic gates, auto-merge
+director run
+
+# 5. Inspect
+director status
+```
+
+Unattended? Let the planner self-critique at each gate instead of pausing for you:
+
+```bash
+director plan "…" --auto              # planner self-critiques at each gate
+director plan "…" --auto --no-critique  # gates auto-pass, fully hands-off
+director run
+```
+
+---
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `director plan "<task>" [--auto] [--no-critique] [--continue]` | Brainstorm → spec → test-gated task DAG, with two artifact-based approval gates. |
+| `director run [--parallel N] [--max-attempts K]` | Execute the DAG: each node in an isolated git worktree, gated by tests/lint/typecheck, auto-merged on pass; escalates a stuck node one tier up. |
+| `director status` | Per-node progress, attempts, cost, and the executor-tier completion rate. |
+| `director bench "<task>" --profiles a,b,c` | Run the **same** task (same frozen acceptance tests) across profile variants and diff cost / quality / wall-time. |
+| `director sync-agents` | (Re)install the role agents into `<repo>/.opencode` and seed `.director/config.toml`. |
+
+All state lives under `.director/` (resumable, debuggable): `plan.json`, `state.json`,
+`costs.jsonl`, `metrics.jsonl`, per-call `logs/`, and `bench/`.
+
+## Configuration
+
+`director sync-agents` seeds `.director/config.toml` from a complete, commented example
+(also at [`director/config.example.toml`](director/config.example.toml)). A config is
+just roles → `provider/model` strings, the deterministic gate commands, per-model
+pricing, and run limits — the example shows how to bind the executor tier to a local
+model (≈ $0 implementation), a low-cost cloud model (zero local infra), or a frontier
+model (the expensive baseline). See [`director/README.md`](director/README.md) for the
+full architecture (gates, two-stage review, red-green hardening, metrics).
+
+### Comparing setups with `bench`
+
+`director bench` plans a task once, then runs the **same** frozen acceptance tests under
+several config variants to compare cost/quality/wall-time. Create the variants as
+`.director/profiles/<name>.toml` (copy your `config.toml` and change the executor tier in
+each), then:
+
+```bash
+director bench "<task>" --profiles all-frontier,cheap-cloud,local-first
+```
+
+## For agents & scripting
+
+director is built to be driven by humans *or* by another agent:
+
+- **Deterministic, non-interactive:** `--auto --no-critique` runs plan→run with no
+  prompts; every merge decision is an exit code, never a chat.
+- **Machine-readable output:** `.director/metrics.jsonl` (per-node + per-run records)
+  and `.director/bench/summary.json` are stable JSON for downstream tooling.
+- **Resumable:** re-running `plan --continue` / `run` picks up from `.director/` state.
+
+---
+
+## Development
+
+```bash
+uv sync                       # create the dev environment
+uv run python -m unittest discover -s tests -q   # tests
+uvx ruff check . && uvx ruff format --check .     # lint + format
+uv build                      # build the wheel/sdist
+```
+
+Releases are automated with [python-semantic-release](https://python-semantic-release.readthedocs.io/)
+on merge to `main` (conventional-commit messages drive the version bump, changelog, and
+PyPI publish via Trusted Publishing). See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE) © Christopher Manzi. The ported TDD/review *discipline* is adapted from
+[obra/superpowers](https://github.com/obra/superpowers) (MIT).

director_cli-0.3.0.dist-info/RECORD

@@ -0,0 +1,32 @@
+director/README.md,sha256=YaLAJhNewVOt2eLCfo2Ijd2_58VcyaNlBkCa8Q0dUL4,7542
+director/__init__.py,sha256=UAIGy5FwtqPhiOgKgylft5WAzMG5s8IhpV3j4KRkmQg,490
+director/__main__.py,sha256=vYft2_c7dl5XuL8T5xQw5z07YLZKsyVLtXebblBKJro,87
+director/bench.py,sha256=RUU8m6S9g2T8MijnZzYMWOKq6gYCREeszjHUrCaFi80,9158
+director/cli.py,sha256=5dl3_GvZU6dOJXilSSbZd50noJS_YE7Pcp762GY2v28,4856
+director/config.example.toml,sha256=5CM4kqCLJn3NqyAwn30i5FeByplR9Bs2tBHPfgkn5A0,3744
+director/config.py,sha256=T44fhI_5VXYcUJicjyuGaAvooaiLKxGM1owRXY4Oe2w,4236
+director/cost.py,sha256=Y7e22DRohIAcDU8xuc2fXseNa87gZhn9M3_d1SSkMFg,2495
+director/dag.py,sha256=vaFYDrYeJzdaRj41TK6u4Gi3eWdaDD4GdOFCpGrbYR8,3800
+director/gates.py,sha256=uqi3DZixTCkuDQVL3CzSFZ__YVjrAvOHSBF8h1DE0jU,5405
+director/gitutil.py,sha256=t_Os0dNrvxOiE9v05vOCDQSWzp51f9vNeMDLrE6dd1A,2744
+director/metrics.py,sha256=OIPfAip_2gzBwhicGsr0b7AgrgpF2iNcz6EH0S83x-Y,1684
+director/models.py,sha256=t286U_vWion-bOF9qpselDu8FzAQmti2NhTX0qQGcX4,3933
+director/opencode.py,sha256=0RKBH1GEZBNFZCRBpGWHBYRcXvgGzZxBFYlorNjAnjc,8371
+director/plan.py,sha256=mJetHGObCqAs4IRFFDtb4igOEAkFAYhsOojU11iwZM0,19316
+director/report.py,sha256=WSvU-FfrwyMV9aBgZjQwJ9djE0FzqpRklxZhHWVm17k,4275
+director/review.py,sha256=dXMG344m1xuyPOVt2JmW0JdS3zR89C6yK4hKp7MVO24,5948
+director/run.py,sha256=LvrotO8kR5q4-SOg_o8Wje0ECLvTI3ZlvCyBrpYs3mc,17907
+director/setup.py,sha256=H8yDL31KVwsBLYMIB7DC7d2NEDnDeYKrSUyHa1AOwA0,3824
+director/state.py,sha256=mow0zZa2Hh75mk-3V0P271oNu-fzn13sBEyCaZ2ockk,1371
+director/agent_templates/brainstorm.md,sha256=xArLZukX6WOqHlqDSzDOBv0g05aej_QqLfpuTDXhynU,1784
+director/agent_templates/executor.md,sha256=gxNpxq8f94NomthbraqP0Djc_lqx6hfW2r4mkH1X4Ms,1713
+director/agent_templates/explorer.md,sha256=tmQ5zdm78W7vPgwJaqB72itbR93cQScVsDCORcUkncM,1024
+director/agent_templates/opencode.json,sha256=w27_6OEZfYBVhVhiOExlrZFerBr0eKbJLHO7nt_w3Yg,858
+director/agent_templates/planner.md,sha256=yzeszZoOlsqD1MYHFYnxdbs-NwkQuhCjCX7IrCokxAw,3044
+director/agent_templates/reviewer.md,sha256=szFV2YQ8LrULGVfjEYM7xAAFFzUDbRsnhVApLY4dHQ4,1928
+director/agent_templates/test-author.md,sha256=nn_dBAHyrKj9jBZsgpz_vKIoMQ4zDOg5rOnD4xdm7gQ,1240
+director_cli-0.3.0.dist-info/METADATA,sha256=ZuR3SPbevt07EB3tDPVNNor7n6VMIg_15hne9k_LwU4,7301
+director_cli-0.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+director_cli-0.3.0.dist-info/entry_points.txt,sha256=TsqsEJcOoXZdwdG6Lh9COffQwHYkYsZKimPt8TFk2mA,47
+director_cli-0.3.0.dist-info/licenses/LICENSE,sha256=8kYT3veTsiC6QImfym_6HdBTqNUct_mEkd2C3saQJpw,1074
+director_cli-0.3.0.dist-info/RECORD,,

director_cli-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

director_cli-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+director = director.cli:main

director_cli-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christopher Manzi
+
+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.