buildwright 0.1.0__tar.gz

buildwright-0.1.0/.env.example

@@ -0,0 +1,15 @@
+# --- buildwright: role -> model (registry ids; defaults to the package's models.yaml) ---
+# BW_MODELS_FILE=./models.yaml   # project-local registry (optional)
+BW_ROLE_PLANNER=local/qwen3
+BW_ROLE_WORKER=remote/gpt-4o-mini
+BW_ROLE_REVIEWER=local/qwen3
+
+# --- provider keys (only the ones you use) ---
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+LITELLM_API_KEY=
+
+# --- Langfuse (optional: without keys, tracing is disabled) ---
+LANGFUSE_PUBLIC_KEY=
+LANGFUSE_SECRET_KEY=
+LANGFUSE_HOST=http://localhost:3000

buildwright-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv python install 3.11
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run mypy src
+      - run: uv run pytest -q

buildwright-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,18 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Trusted publishing: cap token d'API; PyPI valida el workflow + repo + tag
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

buildwright-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+.env
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+*.egg-info/

buildwright-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jordi Marçal Poy
+
+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.

buildwright-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: buildwright
+Version: 0.1.0
+Summary: Per-agent model routing for AI agents: LangGraph orchestration, PydanticAI agents, LiteLLM-ready registry, Langfuse tracing
+Project-URL: Homepage, https://github.com/jordimarsal/buildwright
+Project-URL: Repository, https://github.com/jordimarsal/buildwright
+Project-URL: Issues, https://github.com/jordimarsal/buildwright/issues
+Author: Jordi Marçal Poy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,langfuse,langgraph,litellm,llm,model-routing,pydantic-ai,spec-driven-development
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: langfuse>=3.0
+Requires-Dist: langgraph>=1.0
+Requires-Dist: pydantic-ai-slim[openai]>=1.0
+Requires-Dist: pydantic-settings>=2.4
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# buildwright
+
+*The craftsman who builds per the spec* — one model per agent: mechanical steps
+go to the **local** model (cheap, fast), important decisions to the **remote**
+one (strong). The role→model mapping is configuration, not code — switching
+models touches zero lines of pipeline.
+
+## Install
+
+```bash
+uv tool install buildwright      # once published to PyPI
+# or for development:
+uv sync
+```
+
+## Division of roles (one tool, one job)
+
+| Piece | Role | Where it lives |
+|---|---|---|
+| **LangGraph** | the ORDER of the steps (graph, state, retries) | `graph.py` |
+| **PydanticAI** | EACH STEP (agent with structured output) | `agents.py` |
+| **LiteLLM** | WHO serves the model (optional proxy, fallbacks) | `litellm/config.yaml` |
+| **Langfuse** | WHETHER IT WORKED (traces, scores) | `observability.py` |
+
+## The pipeline
+
+```
+START → plan (local)  →  execute (remote)  →  review (local)  →  END
+        Plan struct.      final answer        Review struct.
+```
+
+Each node is a PydanticAI agent; the model is decided by the **role** in
+`Settings` (`BW_ROLE_*`), resolved against the `models.yaml` registry.
+
+## Quickstart
+
+```bash
+uv sync
+cp .env.example .env          # adjust BW_ROLE_* and keys
+
+uv run buildwright models     # list local and remote models
+uv run buildwright roles      # role -> model mapping
+uv run buildwright ask "write a snake game in python with pygame"
+```
+
+With no endpoints available, `ask` fails naming the exact model and the missing
+env var.
+
+## Local and remote models
+
+The whole registry speaks **OpenAI-compatible** (`models.yaml`):
+
+- **local/qwen3** → Ollama at `localhost:11434/v1`
+- **local/llamacpp** → `llama-server` at `localhost:8080/v1` (your GGUF)
+- **remote/gpt-4o-mini, gpt-4o** → OpenAI (key via `OPENAI_API_KEY`)
+- **remote/claude-sonnet** → Anthropic's OpenAI-compat layer
+- **litellm/*** → via the LiteLLM proxy (see `docker-compose.yml`)
+
+Registry resolution: `BW_MODELS_FILE` > project-local `./models.yaml` > the
+`models.yaml` bundled with the package. Adding a model = adding 5 lines.
+Reassigning one to an agent = changing a `BW_ROLE_*` in `.env`.
+
+## Optional full stack (LiteLLM + Langfuse + Ollama)
+
+With Docker, `docker compose up -d` brings up LiteLLM (routing/fallbacks),
+Langfuse (traces) and Ollama. Langfuse keys show up in its admin UI; copy them
+to `.env` and tracing turns itself on (without keys, the tracer is a no-op).
+
+## Publishing to PyPI
+
+Trusted publishing — no API tokens:
+
+1. Create `github.com/jordimarsal/buildwright` and push `main`.
+2. On pypi.org: *Add a pending publisher* → owner `jordimarsal`, repo
+   `buildwright`, workflow `release.yml`, environment `pypi`.
+3. `git tag v0.1.0 && git push --tags` → the workflow runs `uv build` and
+   publishes.
+
+## Tests
+
+```bash
+uv run pytest        # offline: pydantic-ai's TestModel, zero network
+```
+
+## Anti-mess rules
+
+1. Everything speaks OpenAI protocol; PydanticAI never imports litellm.
+2. One agent = one node = one job. No agents inside agents.
+3. Tracing registered exactly once (`observability.py`); never scattered.
+4. Offline evals in CI rule; Langfuse is production monitoring.
+5. Each piece joins when it has a real trigger (fallbacks→LiteLLM,
+   non-linear flow→LangGraph is already in).

buildwright-0.1.0/README.md

@@ -0,0 +1,92 @@
+# buildwright
+
+*The craftsman who builds per the spec* — one model per agent: mechanical steps
+go to the **local** model (cheap, fast), important decisions to the **remote**
+one (strong). The role→model mapping is configuration, not code — switching
+models touches zero lines of pipeline.
+
+## Install
+
+```bash
+uv tool install buildwright      # once published to PyPI
+# or for development:
+uv sync
+```
+
+## Division of roles (one tool, one job)
+
+| Piece | Role | Where it lives |
+|---|---|---|
+| **LangGraph** | the ORDER of the steps (graph, state, retries) | `graph.py` |
+| **PydanticAI** | EACH STEP (agent with structured output) | `agents.py` |
+| **LiteLLM** | WHO serves the model (optional proxy, fallbacks) | `litellm/config.yaml` |
+| **Langfuse** | WHETHER IT WORKED (traces, scores) | `observability.py` |
+
+## The pipeline
+
+```
+START → plan (local)  →  execute (remote)  →  review (local)  →  END
+        Plan struct.      final answer        Review struct.
+```
+
+Each node is a PydanticAI agent; the model is decided by the **role** in
+`Settings` (`BW_ROLE_*`), resolved against the `models.yaml` registry.
+
+## Quickstart
+
+```bash
+uv sync
+cp .env.example .env          # adjust BW_ROLE_* and keys
+
+uv run buildwright models     # list local and remote models
+uv run buildwright roles      # role -> model mapping
+uv run buildwright ask "write a snake game in python with pygame"
+```
+
+With no endpoints available, `ask` fails naming the exact model and the missing
+env var.
+
+## Local and remote models
+
+The whole registry speaks **OpenAI-compatible** (`models.yaml`):
+
+- **local/qwen3** → Ollama at `localhost:11434/v1`
+- **local/llamacpp** → `llama-server` at `localhost:8080/v1` (your GGUF)
+- **remote/gpt-4o-mini, gpt-4o** → OpenAI (key via `OPENAI_API_KEY`)
+- **remote/claude-sonnet** → Anthropic's OpenAI-compat layer
+- **litellm/*** → via the LiteLLM proxy (see `docker-compose.yml`)
+
+Registry resolution: `BW_MODELS_FILE` > project-local `./models.yaml` > the
+`models.yaml` bundled with the package. Adding a model = adding 5 lines.
+Reassigning one to an agent = changing a `BW_ROLE_*` in `.env`.
+
+## Optional full stack (LiteLLM + Langfuse + Ollama)
+
+With Docker, `docker compose up -d` brings up LiteLLM (routing/fallbacks),
+Langfuse (traces) and Ollama. Langfuse keys show up in its admin UI; copy them
+to `.env` and tracing turns itself on (without keys, the tracer is a no-op).
+
+## Publishing to PyPI
+
+Trusted publishing — no API tokens:
+
+1. Create `github.com/jordimarsal/buildwright` and push `main`.
+2. On pypi.org: *Add a pending publisher* → owner `jordimarsal`, repo
+   `buildwright`, workflow `release.yml`, environment `pypi`.
+3. `git tag v0.1.0 && git push --tags` → the workflow runs `uv build` and
+   publishes.
+
+## Tests
+
+```bash
+uv run pytest        # offline: pydantic-ai's TestModel, zero network
+```
+
+## Anti-mess rules
+
+1. Everything speaks OpenAI protocol; PydanticAI never imports litellm.
+2. One agent = one node = one job. No agents inside agents.
+3. Tracing registered exactly once (`observability.py`); never scattered.
+4. Offline evals in CI rule; Langfuse is production monitoring.
+5. Each piece joins when it has a real trigger (fallbacks→LiteLLM,
+   non-linear flow→LangGraph is already in).

buildwright-0.1.0/docker-compose.yml

@@ -0,0 +1,46 @@
+# Optional stack: LiteLLM (gateway) + Langfuse (traces) + Ollama (local models).
+# The app works without it (direct models via .env); this is for when you want
+# fallbacks, budgets and production traces.
+services:
+  litellm:
+    image: ghcr.io/berriai/litellm:main-stable
+    ports: ["4000:4000"]
+    environment:
+      LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY:-sk-master}
+      OPENAI_API_KEY: ${OPENAI_API_KEY:-}
+      LANGFUSE_PUBLIC_KEY: ${LANGFUSE_PUBLIC_KEY:-}
+      LANGFUSE_SECRET_KEY: ${LANGFUSE_SECRET_KEY:-}
+      LANGFUSE_HOST: http://langfuse:3000
+    volumes:
+      - ./litellm/config.yaml:/app/config.yaml:ro
+    command: ["--config", "/app/config.yaml", "--port", "4000"]
+    depends_on: [ollama]
+
+  ollama:
+    image: ollama/ollama:latest
+    ports: ["11434:11434"]
+    volumes:
+      - ollama:/root/.ollama
+
+  langfuse-db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: langfuse
+      POSTGRES_PASSWORD: langfuse
+      POSTGRES_DB: langfuse
+    volumes:
+      - langfuse-db:/var/lib/postgresql/data
+
+  langfuse:
+    image: langfuse/langfuse:2
+    ports: ["3000:3000"]
+    environment:
+      DATABASE_URL: postgresql://langfuse:langfuse@langfuse-db:5432/langfuse
+      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET:-change-me}
+      SALT: ${SALT:-change-me}
+      NEXTAUTH_URL: http://localhost:3000
+    depends_on: [langfuse-db]
+
+volumes:
+  ollama:
+  langfuse-db:

buildwright-0.1.0/docs/specs/2026-10-27-harness-runtime-design.md

@@ -0,0 +1,196 @@
+# Design — buildwright as a Harness runtime
+
+**Date:** 2026-10-27
+**Status:** draft (pre-implementation)
+**Scope:** `buildwright` — new `harness/` package. No changes required in `harness-standard` to start.
+
+---
+
+## 1. Context
+
+`harness-standard` today is a **protocol** (agents, SDD workflow, gates, batching,
+verification) executed *inside* a coding-agent TUI (OpenCode / Claude Code). The
+protocol is enforced by prose ("NEVER skip the spec phase") plus scripts
+(`init.sh`, `check-traceability.py`, `audit-security.sh`). The leader is an LLM
+reading a decision table. Discipline exists because LLMs drift.
+
+`buildwright` today is a per-agent model router: LangGraph orchestration,
+PydanticAI agents with structured outputs, local/remote model registry, Langfuse.
+
+**Idea:** buildwright becomes a third *host* of the harness protocol — the
+unattended one. OpenCode is the interactive host (human drives). buildwright is
+the production-line host (protocol drives, human approves at gates). Same
+artifacts, same status machine, same gates.
+
+Notably, the harness protocol already anticipates this host. `leader.md` says:
+*"dispatch one read-only subagent … (**cheap model if the runtime allows
+per-dispatch model choice**)"*. buildwright is the runtime that allows it.
+
+## 2. Core insight — the graph IS the leader
+
+The leader's decision table is a state machine; LangGraph is a state machine.
+The LLM leader disappears; the graph assumes its table:
+
+| Leader mandate (prose today) | buildwright runtime (structural) |
+|---|---|
+| "NEVER launch implementer when a feature is `pending`" | no `pending → in_progress` edge exists |
+| Human approval gate at `spec_ready` | LangGraph `interrupt()` — the process parks; state persisted in a checkpointer |
+| "One feature at a time" | state guard: only one `in_progress` slot in the graph state |
+| Batching 2–4 tasks, never 5+ | deterministic batch builder slices `tasks.md`; the number 5 is unrepresentable |
+| "Verify on disk after every batch" | code: stat files, parse `- [x]`, run gates — no chat claim is even possible |
+| Stall recovery ("Nothing was written…", 2 stalls → fresh session) | stall counter in state → re-dispatch with exact message → new agent instance |
+| Context ~70% → fresh session | token counter per agent instance → rotate instance |
+| Anti-telephone-cord (results to files) | structured outputs are written to disk by the runtime; there is no chat |
+| Effort scaling table | complexity = cheap classifier node (structured output), overridable at the spec gate |
+
+What stays LLM-driven is exactly what needs judgment: **spec-author**
+(writes specs), **implementer** (writes code), **reviewer** (judges semantics),
+**gauntlet passes** (adversarial checklists), **log-reader**. Everything
+mechanical becomes edges and validators that cannot forget, skip, or improvise.
+
+## 3. Constraint enforcement map
+
+Harness constraints, soft→hard migration:
+
+| Constraint | TUI era | buildwright |
+|---|---|---|
+| SDD workflow order | prose | graph topology (**hard**) |
+| `harness/init.sh` green before done | implementer told to run it | subprocess gate; exit ≠ 0 or final line ≠ `[OK]` → loop back (**hard**) |
+| Feature list schema | `validate-feature-list.py` | Pydantic model at load & write (**hard**) |
+| Traceability R⟷test | reviewer + script | run `check-traceability.py` as gate node; reviewer semantic pass on top (**hard + soft**) |
+| `audit_level` basic/standard/strict | reviewer reads config | code reads config, runs `audit-security.sh` / `bench.sh`, rejects on non-zero (**hard**) |
+| Conventional Commits | `commit-msg` hook | same hook; runtime commits via git tool (**hard**, unchanged) |
+| Architecture & conventions docs | instructions + reviewer | injected as instructions from `docs/*.md` + reviewer checklist (**soft**, as today) |
+| Approbation record (`APPROVAL`) | implementer writes it after human msg | runtime writes it only after completion-gate `approve` (**hard**) |
+
+Rule of thumb: **if harness already has a script for it, it becomes a gate
+node; if it only has prose, it becomes instructions + a structured-output
+checklist for the reviewer.**
+
+## 4. Role → model routing (the original buildwright value)
+
+```
+[roles.harness]
+spec-author   = remote/claude-sonnet    # highest-leverage text in the pipeline
+implementer   = remote/gpt-4o           # or big local coder model
+reviewer      = remote/gpt-4o-mini      # semantic pass, medium model
+gauntlet-g*   = local/qwen3             # mechanical checklists, high volume
+log-reader    = local/qwen3             # as leader.md explicitly anticipates
+```
+
+Langfuse gives the missing feedback loop: per feature — cost per role, cycles,
+stalls, review verdicts. The `retro: <n> dispatches · <s> stalls · <r> restarts`
+line becomes machine-generated, plus `· $<cost> · <model per role>`.
+
+`harness/runtime.yaml` is per-project, so **language routing needs no extra
+mechanism**: the Java project pins `implementer: remote/claude-sonnet`, the
+Python project pins a python-strong model — each in its own file, which is the
+hard source of truth. buildwright `BW_ROLE_*` stay as global defaults; the
+project file always wins.
+
+## 5. Graph sketch
+
+```
+load_project → select_feature(pending) → classify_complexity(cheap)
+    → spec_author → spec_gate ⏈ interrupt(approve/reject)
+    → [approved] mark in_progress
+    → implement_batch(next batch from tasks.md, with tools, in worktree)
+    → verify_on_disk  ── fail ──→ implement_batch (stall/cycle counters)
+    → reviewer        ── CHANGES_REQUESTED (≤2) ──→ implement_batch
+    → traceability_gate (check-traceability.py) ── fail → implement_batch
+    → audits (audit_level) ── fail → implement_batch
+    → completion_gate ⏈ interrupt(approve/reject)
+    → finalize: APPROVAL record, status done, history.md, retro line
+```
+
+Tools per agent mirror the frontmatter the templates already declare
+(`reviewer.md` / `leader.md`: `tools: write: false`) — **the runtime parses that
+frontmatter and wires tool availability accordingly.** The templates become config.
+
+- `implementer`: `read_file`, `write_file`, `edit_file`, `run_command` (allowlist)
+- `reviewer`, `gauntlet`, `log-reader`, `spec-author`: read-only + `run_command`
+  (gates/scripts only)
+- `run_command`: cwd pinned to the feature worktree, command allowlist read from
+  **`harness/runtime.yaml`** — project-owned, hard source of truth; safe built-in
+  defaults when absent — plus timeouts and output > ~20 lines → archived to
+  `harness/logs/<feature>/T<n>.log`, returns path + tail (the existing
+  big-outputs protocol, now enforced by the tool itself)
+
+Isolation: one **git worktree per feature**; the completion gate decides
+merge-or-discard. Mirrors OpenCode's own worktree strategy.
+
+## 6. Artifacts are the interface
+
+buildwright reads and writes **exactly** the harness artifacts — no fork:
+
+- `harness/feature_list.json` (schema-validated), `harness/specs/<name>/{requirements,design,tasks}.md`
+- `harness/progress/{current,history,impl_<name>,review_<name>}.md`, `CHECKPOINTS.md`, `APPROVAL`, `harness/logs/`
+
+Consequences: a feature can be specced interactively in OpenCode and implemented
+overnight by buildwright; or specced by buildwright, approved by a human, and
+implemented in OpenCode. `harness-standard` stays runtime-agnostic — buildwright
+is just a second, stricter interpreter of the same protocol.
+
+Source of truth for specs remains **markdown** (`tasks.md` checkboxes). The
+runtime parses it (reusing `check-traceability.py` conventions). A machine
+readable `tasks.json` mirror is a possible future harness evolution — explicitly
+*not* a requirement, to avoid forking the protocol.
+
+## 7. CLI surface
+
+```
+buildwright harness status                 # board + role→model plan (read-only)
+buildwright harness run [--feature F3] [--max-batches N]
+buildwright harness approve [comments]     # resumes the parked graph (checkpointer)
+buildwright harness reject "comments"      # back to spec_author / implement_batch
+```
+
+LangGraph sqlite checkpointer ⇒ gates survive process restarts; `run` is
+resumable, like the harness "Interrupted session" case in the leader table.
+
+## 8. Requirements (EARS)
+
+- WHEN a feature is `pending` THE SYSTEM SHALL route it to `spec_author` and SHALL NOT grant write tools to any agent before the spec gate approves.
+- WHEN `harness/init.sh` exits non-zero or its last line is not `[OK]` THE SYSTEM SHALL return control to `implement_batch` with the log path, up to a configured cycle cap.
+- WHEN a batch produces no file changes THE SYSTEM SHALL count a stall, re-dispatch with `Nothing was written: <paths>…`, and after 2 stalls start a fresh agent instance.
+- WHEN the reviewer issues `CHANGES_REQUESTED` twice THE SYSTEM SHALL park the feature `blocked` at a human gate.
+- WHEN a human gate is reached THE SYSTEM SHALL persist graph state and wait; `approve`/`reject` resumes it.
+- THE SYSTEM SHALL NOT write status `done` unless an `APPROVAL` record exists, written after an explicit completion-gate approval.
+- WHEN `audit_level` is `standard`/`strict` THE SYSTEM SHALL run the corresponding scripts and reject on non-zero exit.
+- WHEN `"parallel": true` THE SYSTEM MAY run independent features concurrently, maintaining exactly one `in_progress` per worktree and honoring `depends_on`.
+
+## 9. Risks & honest limits
+
+1. **Agency = blast radius.** File writes + shell on a real repo. → worktree isolation, allowlisted commands, gates decide merge-or-discard, human completion gate before touching `main`.
+2. **Not for ambiguous work.** Taste, UX, exploratory refactors stay in the TUI with a human driving. buildwright executes *specified* work; the human gates exist to catch wrong specs.
+3. **Cycle cost.** implement→verify→review loops burn tokens. → cheap/local models on high-frequency nodes, cycle caps, Langfuse cost telemetry per feature.
+4. **Spec parsing fragility.** Markdown conventions are parseable but not contractual (mitigated by reusing `check-traceability.py` logic and by schema-validating everything that *is* JSON).
+5. **Leader judgment gaps.** Complexity classification and slicing are approximated by a cheap classifier node; the spec gate is the human override point.
+
+## 10. Phases
+
+| Phase | Deliverable | Risk |
+|---|---|---|
+| **0** | `buildwright harness status` — detect harness project, schema-validate `feature_list.json`, show board + planned role→model mapping. Read-only. | none |
+| **1** | Single batch, supervised: implementer with tools in a worktree → `verify_on_disk` → diff report. Human reviews every step. | low |
+| **2** | Full feature loop: batching queue, stall detection, reviewer + audits + traceability gate, human gates via checkpointer, APPROVAL/history/retro written by runtime. | medium |
+| **3** | Multi-feature & parallel mode (`depends_on`), gauntlet as cheap-local nodes, wekan mirror if configured. | medium |
+| **4** | Feedback: cost/quality per role-model from Langfuse, golden fixtures (harness `evals-fixtures/`) as regression tests for the runtime itself, routing tuned by measured pass-rate per node. | low |
+
+## 11. Decisions (2026-10-27)
+
+- **D1 — Allowlist config: `harness/runtime.yaml`.** Accepted as the project-level
+  hard source of truth: command allowlist, timeouts, and role→model overrides.
+  buildwright `BW_ROLE_*` remain global defaults; the project file always wins.
+- **D2 — Per-language implementer routing.** No dedicated mechanism needed: the
+  *target* project declares its stack-appropriate implementer model in its own
+  `runtime.yaml` (Java project → java-strong model, Python project → python-strong).
+  Revisit only if Langfuse telemetry shows language-specific failure patterns.
+- **D3 — Packaging: standalone installable tool.** Not a harness module (hosts
+  install once globally, like OpenCode itself — heavy deps don't belong in every
+  target repo) and not primarily a compose stack. A `docker-compose` stays as an
+  optional deployment mode for unattended/overnight runs; `harness-standard`
+  gets a docs pointer only, so the contract remains artifacts-only.
+  Name (decided 2026-10-27): **buildwright** — "the craftsman who builds per the
+  spec" (PyPI free, no notable GitHub project). License: MIT, matching
+  harness-standard. Hosted on GitHub (portfolio, Pages, trusted publishing).

buildwright-0.1.0/litellm/config.yaml

@@ -0,0 +1,20 @@
+# Optional LiteLLM proxy: centralized routing, fallbacks and budgets.
+# App code never talks to it directly: it speaks OpenAI protocol against
+# http://localhost:4000/v1 (the litellm/* entry in models.yaml).
+model_list:
+  - model_name: gpt-4o-mini
+    litellm_params:
+      model: openai/gpt-4o-mini
+      api_key: os.environ/OPENAI_API_KEY
+
+  - model_name: qwen3
+    litellm_params:
+      model: ollama/qwen3:8b
+      api_base: http://ollama:11434
+
+litellm_settings:
+  # traces of EVERY call sent to Langfuse, without touching app code:
+  success_callback: ["langfuse"]
+
+general_settings:
+  master_key: os.environ/LITELLM_MASTER_KEY

buildwright-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "buildwright"
+version = "0.1.0"
+description = "Per-agent model routing for AI agents: LangGraph orchestration, PydanticAI agents, LiteLLM-ready registry, Langfuse tracing"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Jordi Marçal Poy" }]
+requires-python = ">=3.11"
+keywords = [
+    "llm",
+    "agents",
+    "model-routing",
+    "langgraph",
+    "pydantic-ai",
+    "litellm",
+    "langfuse",
+    "spec-driven-development",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "pydantic-ai-slim[openai]>=1.0",
+    "langgraph>=1.0",
+    "langfuse>=3.0",
+    "pydantic-settings>=2.4",
+    "PyYAML>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/jordimarsal/buildwright"
+Repository = "https://github.com/jordimarsal/buildwright"
+Issues = "https://github.com/jordimarsal/buildwright/issues"
+
+[project.scripts]
+buildwright = "buildwright.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "types-PyYAML>=6.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/buildwright"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]

buildwright-0.1.0/src/buildwright/__init__.py

@@ -0,0 +1,3 @@
+"""Per-agent model routing: cada agent amb el seu model, local o remot."""
+
+__version__ = "0.1.0"