whiletrue 0.1.0__tar.gz → 0.1.1__tar.gz

{whiletrue-0.1.0 → whiletrue-0.1.1}/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.1
+
+- Fixed: parallel interactive items raced to create the tmux session. The loser failed with `duplicate session` and that error was fed to the agent as its previous failure. Session and pane creation now run one at a time, and parallel agents share one window grid.
+- Docs: a new README with a recording of a real run, architecture and flow diagrams, and a step-by-step tutorial (`docs/tutorial.md`).
+
 ## 0.1.0 (first release)
 
 whiletrue runs configurable pipelines of agentic and deterministic steps around coding agents.

whiletrue-0.1.1/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.5
+Name: whiletrue
+Version: 0.1.1
+Summary: Local orchestrator that runs pipelines of agent and deterministic steps around Claude Code, opencode and Codex, with gates, human approval, parallel git worktrees and crash-safe resume.
+Project-URL: Repository, https://github.com/dariussingh/whiletrue
+Project-URL: Changelog, https://github.com/dariussingh/whiletrue/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/dariussingh/whiletrue/tree/main/docs
+Author: Darius Singh
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai-agents,claude-code,codex,coding-agents,git-worktree,human-in-the-loop,opencode,orchestration,pipelines,ralph,tmux
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: common-expression-language<1,>=0.10
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: pyyaml<7,>=6
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="docs/assets/logo.svg" alt="whiletrue logo" width="96" height="96">
+
+# whiletrue
+
+**The loop around your coding agents.**
+
+Run pipelines of agentic and deterministic steps around Claude Code, opencode and Codex, locally, with gates, humans in the loop, and crash-safe resume.
+
+[![PyPI](https://img.shields.io/pypi/v/whiletrue?logo=pypi&logoColor=white)](https://pypi.org/project/whiletrue/)
+[![Python](https://img.shields.io/pypi/pyversions/whiletrue?logo=python&logoColor=white)](https://pypi.org/project/whiletrue/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-docs%2F-informational)](docs/README.md)
+
+</div>
+
+> LangGraph builds the agent; whiletrue runs the loop around agents you already have.
+
+<div align="center">
+
+<img src="docs/assets/demo-real.svg" alt="Recording of a real run: two Claude Code agents work in parallel in tmux panes while a control panel and shell show status, both items pass their pytest gate and park for human approval, then approve and resume finish them" width="900">
+
+<sub>A real run, not a mock-up: two Claude Code agents in parallel, a pytest gate, a human approval and a resume, about $0.23 in total. Captured from the live tmux panes; the two tmux windows are drawn side by side.</sub>
+
+</div>
+
+```bash
+uvx whiletrue init      # scaffold a Ralph loop
+uvx whiletrue run       # agent -> pytest gate -> repeat until green
+```
+
+## Overview
+
+Coding agents are good at one task and bad at finishing a backlog unattended. whiletrue is the orchestrator you put around them. You describe the loop in a single `whiletrue.yaml`: which agent does the work, which deterministic gate checks it, when to retry, when to ask a person. whiletrue validates the config before spending a token, runs it, and records every step so you can inspect, replay or resume it.
+
+- **Pipelines, not prompts.** Agent steps, shell and git steps, and gates compose with `sequence`, `loop`, `map`, `parallel`, `switch`, `retry`, `try` and `human.approve`. Every loop is bounded.
+- **Any backend.** `claude-code-headless`, `claude-code` (the real interactive CLI in a tmux pane you can type into), `opencode` and `codex`. Mix them in one pipeline.
+- **Many items at once.** One item per task or GitHub issue, each in its own git worktree, with `parallel: N` and a cap on live agent sessions.
+- **Humans in the loop.** A gate parks an item until a person approves, rejects or comments; other items keep running. Every review comment gets an answer.
+- **Durable.** State lives in SQLite. Kill the process at any point and `whiletrue resume` replays finished steps instead of redoing them; side effects (PRs, merges, replies) happen exactly once.
+- **Local.** One machine, no server, no account. Everything is a file in your repo plus `.whiletrue/`.
+
+## Contents
+
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [Architecture](#architecture)
+- [Concepts](#concepts)
+- [Examples](#examples)
+- [Backends](#backends)
+- [CLI](#cli)
+- [Documentation](#documentation)
+- [Development](#development)
+- [License](#license)
+
+## Install
+
+Requires Python 3.12+ and at least one agent CLI on your `PATH` ([Claude Code](https://claude.com/claude-code), [opencode](https://opencode.ai) or [Codex](https://github.com/openai/codex)). `git` is needed for worktrees, `tmux` for interactive agents, and `gh` for the GitHub integration.
+
+```bash
+uv tool install whiletrue     # or: pip install whiletrue
+whiletrue --help
+
+uvx whiletrue --help          # or run it without installing
+```
+
+If an agent CLI is not on `PATH`, set `WHILETRUE_CLAUDE_BIN`, `WHILETRUE_OPENCODE_BIN` or `WHILETRUE_CODEX_BIN`.
+
+## Quickstart
+
+```bash
+cd my-project
+whiletrue init        # writes whiletrue.yaml and agents/ralph.md
+whiletrue validate    # config, wiring, limits and safety rules; spends nothing
+whiletrue plan        # prints the expanded step tree; spends nothing
+whiletrue run         # runs it
+whiletrue status      # steps, outcomes and cost of the latest run
+```
+
+The scaffold is a Ralph loop. The agent runs in a fresh context, a deterministic `pytest` gate checks the result, and the loop repeats (at most 5 times) until the gate is green:
+
+```yaml
+# whiletrue.yaml
+name: ralph
+pipeline:
+  loop:
+    max: 5            # every loop is bounded; `max: unbounded` is an explicit opt-out
+    do:
+      - agent: { uses: ./agents/ralph.md }
+      - gate.shell: { run: "pytest" }
+```
+
+```markdown
+---
+# agents/ralph.md
+agent: ralph
+runner: claude-code-headless
+permission_mode: acceptEdits
+tools: [Read, Edit, Write, "Bash(pytest*)", "Bash(git *)"]
+limits: { budget_usd: 2, turns: 40, wall: 20m }
+---
+Work through the next unfinished item in TODO.md. Make the tests pass.
+
+Failure output from the previous attempt (empty on the first try):
+{{iter.previous}}
+```
+
+Every agent must declare `limits`; `validate` refuses the config otherwise.
+
+## Architecture
+
+<img src="docs/assets/architecture.svg" alt="Architecture: whiletrue.yaml and the CLI drive the core engine (loader, scheduler, pipeline runtime, park and resume, plugin registry, SQLite store); built-in plugins connect it to agent CLIs, git, GitHub and tmux" width="900">
+
+The core knows nothing about git, GitHub, tmux or any agent. Every integration is a plugin built on the public plugin API, so you can add your own ([plugins](docs/plugins.md), [architecture](docs/architecture.md)).
+
+## Concepts
+
+| Concept | What it is |
+| --- | --- |
+| **Pipeline** | A list of steps, or one strategy, in `whiletrue.yaml`. |
+| **Step** | An action: `agent`, a shell command, a git or GitHub operation, a gate. Pure, deterministic, agentic or side-effecting. |
+| **Strategy** | Control flow over steps: `sequence`, `tap`, `loop`, `map`, `parallel`, `switch`, `retry`, `try`, `human.approve`. |
+| **Outcome ports** | Every step ends on `ok`, `fail`, `needs_human`, `skip` or `rejected`. `wires:` routes a port to another step; back-wires make loops. |
+| **Item** | One unit of work from a `source:` (`json`, `markdown_tasks`, `github_issues`). Items run in parallel, in dependency order. |
+| **Workspace** | Per-item checkout: `git-worktree`, `dir-copy` or `none`. |
+| **Gate** | A deterministic check, or a human decision, that an item must pass. |
+| **Recipe** | A ready-made composite: `ralph`, `review-pass`, `review-respond`, `issue-loop`. |
+| **Run record** | The SQLite log of steps, parks, effects, comments and cost that makes replay and resume possible. |
+
+Details: [reference](docs/reference.md), [authoring guide](docs/authoring.md), [architecture](docs/architecture.md).
+
+## Examples
+
+### A Ralph loop
+
+<img src="docs/assets/ralph-loop.svg" alt="Ralph loop: agent in a fresh context, then a pytest gate; green ends the loop, red feeds the output back to the agent" width="900">
+
+This is what `whiletrue init` scaffolds. See the YAML under [Quickstart](#quickstart).
+
+### Review loop with a read-only reviewer
+
+```yaml
+pipeline:
+  composite:
+    uses: "recipe:review-pass"
+    params: { reviewer: ./agents/review.md, fixer: ./agents/fix.md, max_rounds: 3 }
+```
+
+### A backlog in parallel worktrees
+
+```yaml
+parallel: 4
+max_agents: 4
+source: { markdown_tasks: { path: TASKS.md } }   # - [ ] Title {#id after=other}
+workspace: { git-worktree: { branch: "wt/{{item.id}}" } }
+pipeline:
+  loop:
+    max: 5
+    do:
+      - agent: { uses: ./agents/implement.md }
+      - gate.shell: { run: "pytest" }
+```
+
+### A human gate on a pull request
+
+```yaml
+- id: review
+  human.approve:
+    what: pr
+    wake: { any: [cli, { github.pr_review: any }] }
+  do:
+    - composite: { uses: "recipe:review-respond", params: { responder: ./agents/respond.md } }
+  wires: { rejected: fix }
+```
+
+```bash
+whiletrue run                         # parks at the gate and exits with code 2
+whiletrue status                      # lists what is waiting
+whiletrue approve 12                  # or: reject 12 --note "what to change"
+whiletrue resume                      # finished steps are replayed, never redone
+```
+
+### The reference pipeline: issues with a human in the loop
+
+[`examples/issue-loop`](examples/issue-loop/README.md) takes every issue in a GitHub milestone from open to merged: implement in a worktree, run the gate, open a PR, answer review comments, merge, close. You review every PR, and every comment you leave gets an answer.
+
+<img src="docs/assets/issue-loop.svg" alt="Issue loop flow: implement with retry and a gate, open a PR, a human review gate with comment replies and a fix branch on rejection, then sync, a merge approval and the merge" width="900">
+
+## Backends
+
+Choose per agent with `runner:`.
+
+| Runner | Runs | Notes |
+| --- | --- | --- |
+| `claude-code-headless` | `claude -p` | Default. Budget, turns and wall limits enforced. |
+| `claude-code` | Interactive Claude Code in a tmux pane | Watch it, type into it (recorded as a *steer*). Submits through a bundled MCP tool and hooks. |
+| `opencode` | `opencode run` | Structured output checked against the step's cap. |
+| `codex` | `codex exec` | Sandbox derived from `permission_mode`. No budget enforcement. |
+
+Structured `outputs:` work on all of them. See [choosing a backend](docs/authoring.md#choosing-a-backend).
+
+## CLI
+
+| Command | Purpose |
+| --- | --- |
+| `init`, `validate`, `plan` | Scaffold, check and preview a pipeline without spending tokens. |
+| `run`, `resume`, `rerun`, `cancel` | Start, continue after a park or crash, redo, or stop items. |
+| `status`, `logs`, `cost`, `replay` | Inspect runs, steps and spend; replay a recorded run. |
+| `approve`, `reject`, `comment` | Decide human gates and talk to waiting items. |
+| `attach`, `panel` | Open the tmux session and the live control panel. |
+| `history`, `learnings` | Audit trail and approved lessons for future agents. |
+| `lock` | Show or clear the run lock. |
+
+Full reference: [docs/cli.md](docs/cli.md). New here? Follow the [tutorial](docs/tutorial.md).
+
+## Documentation
+
+Start at [docs/README.md](docs/README.md).
+
+- [Tutorial](docs/tutorial.md): from an empty folder to your own loop with gates, a reviewer, parallel tasks and a human approval.
+- [Getting started](docs/getting-started.md): a longer walkthrough, including interactive agents, gates and parallel items.
+- [Authoring guide](docs/authoring.md): writing pipelines and agents.
+- [Reference](docs/reference.md): every module, strategy, provider and config key.
+- [CLI](docs/cli.md) and [plugins](docs/plugins.md): the command line and extending whiletrue.
+- [Architecture](docs/architecture.md), [plan](docs/plan.md), [todo](docs/todo.md) and [changelog](CHANGELOG.md).
+
+## Development
+
+Requires [devenv](https://devenv.sh) (or Python 3.12 + [uv](https://docs.astral.sh/uv/)). See [developing.md](docs/developing.md).
+
+```bash
+git clone https://github.com/dariussingh/whiletrue && cd whiletrue
+direnv allow            # or: devenv shell
+poe check               # format check, lint, pyright, tests + coverage, docs check
+whiletrue --help        # installed editable into .devenv/state/venv
+```
+
+Live tests against real agent CLIs are opt-in: `WHILETRUE_LIVE=1 uv run pytest tests/live -v`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

whiletrue-0.1.1/README.md

@@ -0,0 +1,243 @@
+<div align="center">
+
+<img src="docs/assets/logo.svg" alt="whiletrue logo" width="96" height="96">
+
+# whiletrue
+
+**The loop around your coding agents.**
+
+Run pipelines of agentic and deterministic steps around Claude Code, opencode and Codex, locally, with gates, humans in the loop, and crash-safe resume.
+
+[![PyPI](https://img.shields.io/pypi/v/whiletrue?logo=pypi&logoColor=white)](https://pypi.org/project/whiletrue/)
+[![Python](https://img.shields.io/pypi/pyversions/whiletrue?logo=python&logoColor=white)](https://pypi.org/project/whiletrue/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-docs%2F-informational)](docs/README.md)
+
+</div>
+
+> LangGraph builds the agent; whiletrue runs the loop around agents you already have.
+
+<div align="center">
+
+<img src="docs/assets/demo-real.svg" alt="Recording of a real run: two Claude Code agents work in parallel in tmux panes while a control panel and shell show status, both items pass their pytest gate and park for human approval, then approve and resume finish them" width="900">
+
+<sub>A real run, not a mock-up: two Claude Code agents in parallel, a pytest gate, a human approval and a resume, about $0.23 in total. Captured from the live tmux panes; the two tmux windows are drawn side by side.</sub>
+
+</div>
+
+```bash
+uvx whiletrue init      # scaffold a Ralph loop
+uvx whiletrue run       # agent -> pytest gate -> repeat until green
+```
+
+## Overview
+
+Coding agents are good at one task and bad at finishing a backlog unattended. whiletrue is the orchestrator you put around them. You describe the loop in a single `whiletrue.yaml`: which agent does the work, which deterministic gate checks it, when to retry, when to ask a person. whiletrue validates the config before spending a token, runs it, and records every step so you can inspect, replay or resume it.
+
+- **Pipelines, not prompts.** Agent steps, shell and git steps, and gates compose with `sequence`, `loop`, `map`, `parallel`, `switch`, `retry`, `try` and `human.approve`. Every loop is bounded.
+- **Any backend.** `claude-code-headless`, `claude-code` (the real interactive CLI in a tmux pane you can type into), `opencode` and `codex`. Mix them in one pipeline.
+- **Many items at once.** One item per task or GitHub issue, each in its own git worktree, with `parallel: N` and a cap on live agent sessions.
+- **Humans in the loop.** A gate parks an item until a person approves, rejects or comments; other items keep running. Every review comment gets an answer.
+- **Durable.** State lives in SQLite. Kill the process at any point and `whiletrue resume` replays finished steps instead of redoing them; side effects (PRs, merges, replies) happen exactly once.
+- **Local.** One machine, no server, no account. Everything is a file in your repo plus `.whiletrue/`.
+
+## Contents
+
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [Architecture](#architecture)
+- [Concepts](#concepts)
+- [Examples](#examples)
+- [Backends](#backends)
+- [CLI](#cli)
+- [Documentation](#documentation)
+- [Development](#development)
+- [License](#license)
+
+## Install
+
+Requires Python 3.12+ and at least one agent CLI on your `PATH` ([Claude Code](https://claude.com/claude-code), [opencode](https://opencode.ai) or [Codex](https://github.com/openai/codex)). `git` is needed for worktrees, `tmux` for interactive agents, and `gh` for the GitHub integration.
+
+```bash
+uv tool install whiletrue     # or: pip install whiletrue
+whiletrue --help
+
+uvx whiletrue --help          # or run it without installing
+```
+
+If an agent CLI is not on `PATH`, set `WHILETRUE_CLAUDE_BIN`, `WHILETRUE_OPENCODE_BIN` or `WHILETRUE_CODEX_BIN`.
+
+## Quickstart
+
+```bash
+cd my-project
+whiletrue init        # writes whiletrue.yaml and agents/ralph.md
+whiletrue validate    # config, wiring, limits and safety rules; spends nothing
+whiletrue plan        # prints the expanded step tree; spends nothing
+whiletrue run         # runs it
+whiletrue status      # steps, outcomes and cost of the latest run
+```
+
+The scaffold is a Ralph loop. The agent runs in a fresh context, a deterministic `pytest` gate checks the result, and the loop repeats (at most 5 times) until the gate is green:
+
+```yaml
+# whiletrue.yaml
+name: ralph
+pipeline:
+  loop:
+    max: 5            # every loop is bounded; `max: unbounded` is an explicit opt-out
+    do:
+      - agent: { uses: ./agents/ralph.md }
+      - gate.shell: { run: "pytest" }
+```
+
+```markdown
+---
+# agents/ralph.md
+agent: ralph
+runner: claude-code-headless
+permission_mode: acceptEdits
+tools: [Read, Edit, Write, "Bash(pytest*)", "Bash(git *)"]
+limits: { budget_usd: 2, turns: 40, wall: 20m }
+---
+Work through the next unfinished item in TODO.md. Make the tests pass.
+
+Failure output from the previous attempt (empty on the first try):
+{{iter.previous}}
+```
+
+Every agent must declare `limits`; `validate` refuses the config otherwise.
+
+## Architecture
+
+<img src="docs/assets/architecture.svg" alt="Architecture: whiletrue.yaml and the CLI drive the core engine (loader, scheduler, pipeline runtime, park and resume, plugin registry, SQLite store); built-in plugins connect it to agent CLIs, git, GitHub and tmux" width="900">
+
+The core knows nothing about git, GitHub, tmux or any agent. Every integration is a plugin built on the public plugin API, so you can add your own ([plugins](docs/plugins.md), [architecture](docs/architecture.md)).
+
+## Concepts
+
+| Concept | What it is |
+| --- | --- |
+| **Pipeline** | A list of steps, or one strategy, in `whiletrue.yaml`. |
+| **Step** | An action: `agent`, a shell command, a git or GitHub operation, a gate. Pure, deterministic, agentic or side-effecting. |
+| **Strategy** | Control flow over steps: `sequence`, `tap`, `loop`, `map`, `parallel`, `switch`, `retry`, `try`, `human.approve`. |
+| **Outcome ports** | Every step ends on `ok`, `fail`, `needs_human`, `skip` or `rejected`. `wires:` routes a port to another step; back-wires make loops. |
+| **Item** | One unit of work from a `source:` (`json`, `markdown_tasks`, `github_issues`). Items run in parallel, in dependency order. |
+| **Workspace** | Per-item checkout: `git-worktree`, `dir-copy` or `none`. |
+| **Gate** | A deterministic check, or a human decision, that an item must pass. |
+| **Recipe** | A ready-made composite: `ralph`, `review-pass`, `review-respond`, `issue-loop`. |
+| **Run record** | The SQLite log of steps, parks, effects, comments and cost that makes replay and resume possible. |
+
+Details: [reference](docs/reference.md), [authoring guide](docs/authoring.md), [architecture](docs/architecture.md).
+
+## Examples
+
+### A Ralph loop
+
+<img src="docs/assets/ralph-loop.svg" alt="Ralph loop: agent in a fresh context, then a pytest gate; green ends the loop, red feeds the output back to the agent" width="900">
+
+This is what `whiletrue init` scaffolds. See the YAML under [Quickstart](#quickstart).
+
+### Review loop with a read-only reviewer
+
+```yaml
+pipeline:
+  composite:
+    uses: "recipe:review-pass"
+    params: { reviewer: ./agents/review.md, fixer: ./agents/fix.md, max_rounds: 3 }
+```
+
+### A backlog in parallel worktrees
+
+```yaml
+parallel: 4
+max_agents: 4
+source: { markdown_tasks: { path: TASKS.md } }   # - [ ] Title {#id after=other}
+workspace: { git-worktree: { branch: "wt/{{item.id}}" } }
+pipeline:
+  loop:
+    max: 5
+    do:
+      - agent: { uses: ./agents/implement.md }
+      - gate.shell: { run: "pytest" }
+```
+
+### A human gate on a pull request
+
+```yaml
+- id: review
+  human.approve:
+    what: pr
+    wake: { any: [cli, { github.pr_review: any }] }
+  do:
+    - composite: { uses: "recipe:review-respond", params: { responder: ./agents/respond.md } }
+  wires: { rejected: fix }
+```
+
+```bash
+whiletrue run                         # parks at the gate and exits with code 2
+whiletrue status                      # lists what is waiting
+whiletrue approve 12                  # or: reject 12 --note "what to change"
+whiletrue resume                      # finished steps are replayed, never redone
+```
+
+### The reference pipeline: issues with a human in the loop
+
+[`examples/issue-loop`](examples/issue-loop/README.md) takes every issue in a GitHub milestone from open to merged: implement in a worktree, run the gate, open a PR, answer review comments, merge, close. You review every PR, and every comment you leave gets an answer.
+
+<img src="docs/assets/issue-loop.svg" alt="Issue loop flow: implement with retry and a gate, open a PR, a human review gate with comment replies and a fix branch on rejection, then sync, a merge approval and the merge" width="900">
+
+## Backends
+
+Choose per agent with `runner:`.
+
+| Runner | Runs | Notes |
+| --- | --- | --- |
+| `claude-code-headless` | `claude -p` | Default. Budget, turns and wall limits enforced. |
+| `claude-code` | Interactive Claude Code in a tmux pane | Watch it, type into it (recorded as a *steer*). Submits through a bundled MCP tool and hooks. |
+| `opencode` | `opencode run` | Structured output checked against the step's cap. |
+| `codex` | `codex exec` | Sandbox derived from `permission_mode`. No budget enforcement. |
+
+Structured `outputs:` work on all of them. See [choosing a backend](docs/authoring.md#choosing-a-backend).
+
+## CLI
+
+| Command | Purpose |
+| --- | --- |
+| `init`, `validate`, `plan` | Scaffold, check and preview a pipeline without spending tokens. |
+| `run`, `resume`, `rerun`, `cancel` | Start, continue after a park or crash, redo, or stop items. |
+| `status`, `logs`, `cost`, `replay` | Inspect runs, steps and spend; replay a recorded run. |
+| `approve`, `reject`, `comment` | Decide human gates and talk to waiting items. |
+| `attach`, `panel` | Open the tmux session and the live control panel. |
+| `history`, `learnings` | Audit trail and approved lessons for future agents. |
+| `lock` | Show or clear the run lock. |
+
+Full reference: [docs/cli.md](docs/cli.md). New here? Follow the [tutorial](docs/tutorial.md).
+
+## Documentation
+
+Start at [docs/README.md](docs/README.md).
+
+- [Tutorial](docs/tutorial.md): from an empty folder to your own loop with gates, a reviewer, parallel tasks and a human approval.
+- [Getting started](docs/getting-started.md): a longer walkthrough, including interactive agents, gates and parallel items.
+- [Authoring guide](docs/authoring.md): writing pipelines and agents.
+- [Reference](docs/reference.md): every module, strategy, provider and config key.
+- [CLI](docs/cli.md) and [plugins](docs/plugins.md): the command line and extending whiletrue.
+- [Architecture](docs/architecture.md), [plan](docs/plan.md), [todo](docs/todo.md) and [changelog](CHANGELOG.md).
+
+## Development
+
+Requires [devenv](https://devenv.sh) (or Python 3.12 + [uv](https://docs.astral.sh/uv/)). See [developing.md](docs/developing.md).
+
+```bash
+git clone https://github.com/dariussingh/whiletrue && cd whiletrue
+direnv allow            # or: devenv shell
+poe check               # format check, lint, pyright, tests + coverage, docs check
+whiletrue --help        # installed editable into .devenv/state/venv
+```
+
+Live tests against real agent CLIs are opt-in: `WHILETRUE_LIVE=1 uv run pytest tests/live -v`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

{whiletrue-0.1.0 → whiletrue-0.1.1}/docs/README.md

@@ -4,6 +4,7 @@
 | -------------------------------------- | --------------------------------------------------------------------------------- |
 | [architecture.md](architecture.md)     | Full design: core model, runtime, state, agents, human gates, packages            |
 | [getting-started.md](getting-started.md) | User guide: install, first loop, commands, exit codes, safety defaults          |
+| [tutorial.md](tutorial.md)             | Tutorial: install, first loop, then build your own gates, review, parallel and human steps |
 | [authoring.md](authoring.md)           | Authoring guide: pipelines, composites, agents, choosing a backend                |
 | [cli.md](cli.md)                       | CLI reference: every command, option, exit code and environment variable          |
 | [reference.md](reference.md)           | User reference: modules, control flow, expressions, composites, recipes, replay   |

whiletrue-0.1.1/docs/assets/architecture.svg

@@ -0,0 +1,48 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 600" width="960" height="600" role="img" aria-label="whiletrue architecture: CLI and whiletrue.yaml feed the core engine, which uses plugins to drive agent CLIs, git, GitHub and tmux, with state in SQLite">
+  <style>
+    text{font:13px ui-monospace,SFMono-Regular,Menlo,Consolas,'DejaVu Sans Mono',monospace;fill:#d5dbe3}
+    .t{font-size:15px;font-weight:700}.d{fill:#7d8896}.b{fill:#151b23;stroke:#2b3440;stroke-width:1.5}
+    .g{fill:#12251a;stroke:#3f7a50;stroke-width:1.5}.c{fill:#10222b;stroke:#3a7f96;stroke-width:1.5}.o{fill:#2a1f14;stroke:#a8683a;stroke-width:1.5}
+    .l{stroke:#7d8896;stroke-width:1.5;fill:none;marker-end:url(#a)}
+  </style>
+  <defs><marker id="a" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="#7d8896"/></marker></defs>
+  <rect width="960" height="600" rx="10" fill="#0f1419"/>
+
+  <rect class="b" x="30" y="24" width="900" height="64" rx="6"/>
+  <text class="t" x="48" y="50">You</text>
+  <text class="d" x="48" y="72">whiletrue.yaml · agents/*.md · whiletrue CLI (run resume approve status panel)</text>
+
+  <path class="l" d="M480 88V112"/>
+
+  <rect class="g" x="30" y="114" width="900" height="206" rx="6"/>
+  <text class="t" x="48" y="140">whiletrue.core  (knows no git, GitHub, tmux or agent)</text>
+  <rect class="b" x="48" y="156" width="196" height="64" rx="5"/>
+  <text x="62" y="182">Loader + validator</text><text class="d" x="62" y="202">config, wiring, limits</text>
+  <rect class="b" x="260" y="156" width="196" height="64" rx="5"/>
+  <text x="274" y="182">Scheduler</text><text class="d" x="274" y="202">items, parallel, deps</text>
+  <rect class="b" x="472" y="156" width="196" height="64" rx="5"/>
+  <text x="486" y="182">Pipeline runtime</text><text class="d" x="486" y="202">strategies, journal</text>
+  <rect class="b" x="684" y="156" width="228" height="64" rx="5"/>
+  <text x="698" y="182">Park / resume / replay</text><text class="d" x="698" y="202">gates, crash recovery</text>
+  <rect class="b" x="48" y="236" width="420" height="64" rx="5"/>
+  <text x="62" y="262">Plugin API + registry</text><text class="d" x="62" y="282">action modules · strategies · providers · runners</text>
+  <rect class="b" x="484" y="236" width="428" height="64" rx="5"/>
+  <text x="498" y="262">State store (SQLite, .whiletrue/)</text><text class="d" x="498" y="282">steps · parks · effects · comments · cost</text>
+
+  <path class="l" d="M480 320V346"/>
+
+  <rect class="c" x="30" y="348" width="900" height="122" rx="6"/>
+  <text class="t" x="48" y="374">Built-in plugins  (public plugin API only)</text>
+  <rect class="b" x="48" y="388" width="140" height="64" rx="5"/><text x="60" y="414">control</text><text class="d" x="60" y="434">loop map switch</text>
+  <rect class="b" x="200" y="388" width="140" height="64" rx="5"/><text x="212" y="414">basics</text><text class="d" x="212" y="434">agent shell</text>
+  <rect class="b" x="352" y="388" width="140" height="64" rx="5"/><text x="364" y="414">git</text><text class="d" x="364" y="434">worktrees</text>
+  <rect class="b" x="504" y="388" width="140" height="64" rx="5"/><text x="516" y="414">github</text><text class="d" x="516" y="434">issues, PRs</text>
+  <rect class="b" x="656" y="388" width="130" height="64" rx="5"/><text x="668" y="414">claude_code</text><text class="d" x="668" y="434">headless tmux</text>
+  <rect class="b" x="798" y="388" width="114" height="64" rx="5"/><text x="810" y="414">opencode</text><text class="d" x="810" y="434">codex</text>
+
+  <path class="l" d="M480 470V496"/>
+
+  <rect class="o" x="30" y="498" width="900" height="74" rx="6"/>
+  <text class="t" x="48" y="524">Outside world</text>
+  <text class="d" x="48" y="546">claude · opencode · codex CLIs   |   git   |   gh (GitHub)   |   tmux   |   your tests and scripts</text>
+</svg>