director-cli 0.3.0__tar.gz

director_cli-0.3.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+build/
+dist/
+
+# Claude Code local state
+.claude/
+
+# Director dogfooding output in THIS repo (the example profiles ship in the package
+# at director/profiles/; .director/ and .opencode/ here are just `sync-agents`/run
+# artifacts and are regenerated on demand).
+.director/
+.opencode/
+
+# OS / editor
+.DS_Store
+*.swp
+
+# retained locally, not published
+docs/lessons-learned.md

director_cli-0.3.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project are documented here. This file is maintained
+automatically by [python-semantic-release](https://python-semantic-release.readthedocs.io/)
+from [Conventional Commits](https://www.conventionalcommits.org/); the entry below is the
+pre-automation baseline.
+
+<!-- version list -->
+
+## v0.3.0 (2026-06-24)
+
+Initial public baseline (project renamed from its `foreman` codename to **director**).
+
+### Features
+
+- **plan / run / status orchestrator** over OpenCode: a strong planner decomposes a task
+  into an atomic DAG with acceptance tests written first; a cheaper executor implements
+  each node in an isolated git worktree; deterministic gates (tests/lint/typecheck) decide
+  merges, with a per-task escalation ladder.
+- **Approval gates + methodology** (brainstorm/spec gate, plan gate; `--auto` self-critique),
+  two-stage cost-gated code review, and red-green test-hash hardening.
+- **TDD hardening & measurement:** watch-it-fail transcript verification, flake control
+  (re-run node tests on success), a `.director/metrics.jsonl` stream, and `director bench`
+  to compare cost/quality/wall-time across profiles on identical acceptance tests.
+- Three shipped profiles: `local-first`, `cheap-cloud`, `all-frontier`.

director_cli-0.3.0/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.

director_cli-0.3.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,149 @@
+# 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/director/README.md

@@ -0,0 +1,124 @@
+# `director` — the orchestrator (Phase 2 + 2.5 + 3)
+
+A thin CLI that drives OpenCode headlessly to run the decomposition harness.
+Stdlib-only (Python ≥ 3.11). The harness consumes configured OpenAI-compatible
+endpoints; it never manages providers.
+
+```
+director plan "<task>" [--repo .]             # interactive: stops at each approval gate
+director plan --continue                      # resume after editing/approving the gate artifact
+director plan "<task>" --auto                 # planner self-critiques at each gate; no pause
+director plan "<task>" --auto --no-critique   # gates auto-pass, fully hands-off
+director run [--repo .] [--parallel N] [--max-attempts K]
+director status [--repo .]
+director bench "<task>" --profiles all-frontier,cheap-cloud,local-first [--plan-profile P]
+director sync-agents [--repo .]               # (re)install role agents into <repo>/.opencode
+```
+
+## Flow
+
+**plan** — a re-entrant pipeline with two artifact-based approval gates (Phase 2.5).
+A job branch `director/job-<id>` is created and the role agents synced onto it first.
+1. `explorer` (cheap tier) does read-only recon → `.director/recon.md`.
+2. **Stage A — brainstorm/spec.** `brainstorm` (planner tier) does a Socratic
+   refinement pass and writes a readable design spec → `.director/spec.md`.
+   → **Gate 1.**
+3. **Stage B — decompose.** `planner` (planner tier) turns the *approved spec*
+   into a strict-JSON DAG → `.director/plan.json`. Each node: `id, title, spec
+   (junior-engineer standard), files (allowlist), depends_on, test_cmd, tests,
+   estimated_difficulty`. Validated: acyclic, deps resolve, **concurrent nodes
+   have disjoint allowlists**.
+4. **Stage C — test authoring.** `test-author` (frontier tier) writes each node's
+   tests, committed to the job branch; director verifies they **fail first** (red)
+   and **hashes** each test file (the contract is then immutable). → **Gate 2.**
+
+Gates are **artifact-based, not process-blocking**: director writes the artifact and
+exits; the human edits/approves on disk and resumes with `--continue`. `--auto`
+swaps a one-call planner **self-critique** into the same gate (re-read artifact vs.
+the request, revise once); `--no-critique` makes gates auto-pass. Human and
+self-critic are mechanically the same gate — only the approver differs.
+
+**run** — for each node in dependency order (up to `--parallel` at once):
+1. `git worktree add` an isolated task branch off the job branch.
+2. Invoke `executor` (executor tier) with spec + allowlist file contents + the
+   failing test output. (Executor mandate: **watch it fail first**.)
+3. **Deterministic gate** (exit codes only): test files byte-for-byte intact (hash),
+   `node.test_cmd` passes, AND the diff touches only the allowlist. On the pass
+   path, **flake control** (Phase 3) re-runs the tests `flake_runs` times (default
+   2); any mismatch fails the node as flaky.
+4. **Two-stage review** (Phase 2.5), after the deterministic gate, before merge:
+   - *Stage one — spec compliance:* the deterministic gate above, plus an optional
+     advisory explorer-tier check (`review.stage_one_llm`, off by default).
+   - *Stage two — code quality (`reviewer` tier):* **cost-gated** — runs only when
+     the node escalated OR its diff touched > `review.stage_two_file_threshold`
+     files (default 3). Never runs on the cheap/local tier. A `critical` finding
+     blocks the merge and **re-opens the node** (counts against `max_attempts`).
+5. Fail/blocked → feed the gate or review output back, retry up to `max_attempts`
+   (fresh OpenCode context each attempt). Exhausted → retry the SAME node once at
+   the `escalation` tier (never the whole job).
+6. Pass → commit + merge into the job branch; mark done in `.director/state.json`.
+   After all nodes: an **integration gate** runs the repo-wide suite/lint/typecheck.
+
+Each node's transcript is also checked for **watch-it-fail** (Phase 3 §1): did the
+executor run the failing tests *before* its first edit? This is advisory (the
+deterministic gate already enforces the contract) and recorded as a metric —
+`observed` / `not_observed` / `unknown`.
+
+**status** — per-node state, attempts, cost, executor-tier completion rate (the
+falsifiable hypothesis target: >70% of nodes done without escalation), stage-two
+review trigger rate, and watch-it-fail observed count.
+
+## Measurement (Phase 3)
+
+Every `run` appends to **`.director/metrics.jsonl`** — one `kind:"node"` record per
+node (tier/model, attempts, escalation, per-role tokens+cost, wall time,
+watch-it-fail verdict, flake outcome) and one `kind:"run"` summary (the derived
+rates: executor-tier completion, escalation, stage-two trigger, total wall time
+and cost, plus the resolved tier map). This is the falsifiability instrument; it
+is what `director bench` reads.
+
+**bench** — the experiment. Plans the task **once** (under `--plan-profile`,
+default `all-frontier`) so the DAG and acceptance tests are frozen, then runs that
+*same* plan under each `--profiles` profile by forking a fresh job branch off the
+frozen one (every profile faces byte-for-byte identical tests). It diffs cost /
+quality (same acceptance tests) / wall-time and reports each profile's run-cost
+reduction vs the `all-frontier` baseline (target: >80%). The active `config.toml`
+is never touched — each profile's config is loaded directly from its profile TOML.
+Per-profile metrics streams and a `summary.json` land in `.director/bench/`.
+
+## Roles → tiers
+
+Roles bind to `provider/model` strings in `.director/config.toml` (`[tiers]`).
+Code/logs name only roles. `director` passes the resolved model via `opencode run
+--agent <role> --model <tier>`, so **switching executor models is a config edit,
+never a code change.** `sync-agents` seeds `.director/config.toml` from the bundled
+`config.example.toml`; edit it to bind roles to models. For `bench`, create
+`.director/profiles/<name>.toml` variants (copy `config.toml`, change the executor tier).
+
+## Deliberate deviations from the spec
+
+- **Tests live on the job branch**, not a separate `director/tests-<id>` branch
+  (dependent nodes need both the tests and prior nodes' impls; one branch is
+  simpler and equivalent).
+- **The full repo-wide test suite is the *integration* gate, not a per-node gate.**
+  Sibling nodes' tests are intentionally red until their own node runs, so a
+  per-node full-suite gate would always fail mid-DAG. Per node we gate on
+  `node.test_cmd` + allowlist; the full suite/lint/typecheck run once after merge.
+
+## Persistence (`.director/`, all resumable/debuggable)
+
+- `spec.md` — approved design spec (Gate 1).  `recon.md` — explorer summary.
+- `plan_stage.json` — which gate the plan is paused at (drives `--continue`).
+- `plan.json` — the DAG (incl. per-node `test_hashes`).  `state.json` — per-node
+  status/attempts/cost + review trigger info (resume).
+- `costs.jsonl` — every model call tagged with role + resolved model (local = $0).
+- `metrics.jsonl` — per-node + per-run measurement stream (Phase 3).
+- `bench/` — `summary.json` + per-profile `*.metrics.jsonl` from `director bench`.
+- `logs/*.jsonl` — raw OpenCode NDJSON events per call (`.stderr` siblings = logs).
+- `worktrees/` — transient per-node worktrees.
+
+## Limits (config `[limits]`)
+
+`node_timeout_secs` (per call), `cost_ceiling_usd` (abort the run when exceeded;
+local = $0 so local-first never trips it), `max_attempts`, `flake_runs` (Phase 3
+flake control: times to run a node's tests on success; default 2, 1 disables).

director_cli-0.3.0/director/__init__.py

@@ -0,0 +1,10 @@
+"""Director — a model-agnostic decomposition coding harness.
+
+A strong planner tier decomposes a task into atomic, well-specified units with
+acceptance tests written first; a cheaper executor tier implements each unit in
+an isolated git worktree with a fresh context; deterministic gates (tests, lint,
+typecheck, exit codes — never an LLM judge) decide what merges. Roles bind to
+model tiers in `.director/config.toml`; nothing here knows "local" vs "cloud".
+"""
+
+__version__ = "0.3.0"

director_cli-0.3.0/director/__main__.py

@@ -0,0 +1,4 @@
+from director.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

director_cli-0.3.0/director/agent_templates/brainstorm.md

@@ -0,0 +1,44 @@
+---
+description: Socratic spec refinement — turns a raw task into an unambiguous design spec before any decomposition.
+mode: all
+temperature: 0.3
+permission:
+  edit: deny
+  bash: deny
+  webfetch: deny
+  websearch: deny
+---
+
+You are the **planner**, running the brainstorm/spec pass — the first stage,
+before any decomposition. Your job is to turn a raw, possibly-vague task into an
+*unambiguous* design spec. A bad spec here poisons every downstream task, so do
+not rush to a plan.
+
+You are given the raw task and a read-only relevant-files summary from a recon
+pass. Think hard about what the requester actually wants.
+
+Discipline (do not skip):
+1. **Surface ambiguities and name your assumptions.** Where the task is
+   under-specified, state the interpretation you are adopting and why — explicitly,
+   so a human reviewer can correct it at the approval gate.
+2. **Propose a concrete design**, not options: the behavior to build, the public
+   surface (functions/signatures/endpoints), data shapes, error handling, and the
+   edge cases that matter. Reference real files/symbols from the recon summary.
+3. **Call out what is OUT of scope** so the decomposition stays focused.
+4. **List the acceptance criteria** in plain language — the observable behaviors
+   that, once true, mean the task is done. These become the tests later.
+
+Output the spec as readable Markdown in clearly titled sections (not a wall of
+text), in roughly this shape:
+
+# Spec: <task title>
+## Goal
+## Assumptions & decisions
+## Design
+## Out of scope
+## Acceptance criteria
+## Open questions (if any)
+
+Output ONLY the spec Markdown — no preamble, no code fences around the whole
+document. Do NOT decompose into tasks and do NOT write any code or tests yet;
+that happens after this spec is approved.

director_cli-0.3.0/director/agent_templates/executor.md

@@ -0,0 +1,37 @@
+---
+description: Implements exactly one atomic node to make its failing tests pass, touching only the listed files.
+mode: all
+temperature: 0.6
+permission:
+  edit: allow
+  bash: allow
+  webfetch: deny
+  websearch: deny
+---
+
+You are the **executor**. You implement exactly ONE atomic node in an isolated,
+fresh context. You have no memory of any planner reasoning or sibling node —
+everything you need is in this message.
+
+You receive: a self-contained **spec**, an **allowlist of files** you may modify,
+and the **failing test output** that defines success.
+
+Your only success condition: make the provided tests pass while keeping the
+repo-wide gates (full test suite, lint, typecheck) green.
+
+Rules — do not violate:
+1. **Watch it fail first.** Run the provided tests BEFORE writing any
+   implementation and confirm they fail. If they already pass, STOP and report
+   that the task is mis-specified — do not invent work. Only after seeing red do
+   you implement, then re-run to green.
+2. Change **nothing outside the listed files**. Never modify, rename, or delete
+   any file not on the allowlist — and in particular **never modify a test file**.
+   The tests are the contract; if a test seems wrong, STOP and say so.
+3. Make the smallest change that turns the tests green. No unrelated refactors, no
+   new dependencies unless the spec calls for them.
+4. Match the surrounding code's style, naming, and idioms.
+5. When the listed tests pass, stop and report what you changed (file-by-file) and
+   the final test result. Do not claim success without having run the tests green.
+
+If you cannot make the tests pass, say so explicitly and explain the blocker — do
+not paper over it or weaken the tests.

director_cli-0.3.0/director/agent_templates/explorer.md

@@ -0,0 +1,24 @@
+---
+description: Read-only codebase reconnaissance; produces a compact relevant-files summary for the planner.
+mode: all
+temperature: 0.3
+permission:
+  edit: deny
+  bash: deny
+  webfetch: deny
+  websearch: deny
+---
+
+You are the **explorer**. You perform cheap, read-only reconnaissance so the
+(expensive) planner can work from a small, accurate summary instead of the raw
+repo. You may ONLY read, glob, and grep — never edit, write, or run anything.
+
+Given a task, produce a concise structured summary:
+- **Relevant files**: paths most relevant to the task, one line each.
+- **Key symbols**: functions/classes/types the task will touch (`file:line`).
+- **Conventions**: test framework + how tests are laid out, the exact test/lint/
+  typecheck commands you can infer, build/run commands.
+- **Risks / unknowns**: anything ambiguous the planner must resolve.
+
+Keep it tight — this feeds a context-limited planner. Report findings only; do
+not propose a plan or implementation. Never speculate about code you did not read.