letsdo 0.4.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6c3ecf1ef07372a4f5b38843faafaf394ca49ee9ea73c48a59034c0c33ed1b9
-  data.tar.gz: 9349a23494802614dcdb7aa27d378b7ca2dae1512a395989678e166b3b68548d
+  metadata.gz: dc2229c2f963fc9b534a3905752c851b9ffcbf1fad90fb39d3d5620529099ef0
+  data.tar.gz: 31d93968cd32489e09d0f96edeb63fdc8346fb87bcb596ab40a536821163163e
 SHA512:
-  metadata.gz: 74a49f0c9d8a27c25acc94205f57a9ba9f5e63ac18a8d97e15c270b02e661e45cd30da84fe998f382d6baaa5945f59148b4edf4e62db8b292150dcb56e4e0ad9
-  data.tar.gz: ca34be59f778f078ab0766088d70acb4fe1935d3021315f98a8d1c402c6897cc2267ff5a525c0e5db6c28d3f71238fb782f8972c3db844282353a263732b604d
+  metadata.gz: e5b56197ecfd3dfd010f46d6ba21c5731652aa2a47e4b5a3a7b19079793df6394a652def8920bd4b4444044e31538c473197f1f998f3201ccdd6c4a4b4206e10
+  data.tar.gz: 16df1906f7d721e4229c15eb9902c6840b7782b986bbe9cc3caffcfe6b150025531428cf173f46980d27df51d77362d63e6c3e29b86af3a9348331d88c81f2ec

data/CHANGELOG.md

@@ -5,7 +5,96 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.6.1] - 2026-09-18
+
+### Fixed
+
+- Assignee identity is now the bare agent name (`developer`), not an
+  `@`-prefixed handle. The backlog CLI matches `--assignee` by exact
+  string, so the legacy default made letsdo's own view of the queue
+  diverge from every exact-match consumer. Canonical tracker value is the
+  bare name; `@` stays prose-only notation (TASK-96).
+  - `Providers::Backlog` no longer passes `--assignee` on the CLI line and
+    matches the resolved assignee against stored task assignees in Ruby,
+    tolerating the legacy `@` prefix, surrounding whitespace and case; the
+    matched-not-exact values are exposed as `assignee_variants`.
+  - `AgentLoop` prints a once-per-run stderr hint when a batch matched only
+    after normalization, pointing at the tasks to reassign.
+  - `letsdo doctor` gained an assignee check: WARN on a legacy
+    `@`-prefixed `AGENT_ASSIGNEE_HANDLE` override and on `@`-prefixed
+    assignees stored on open tasks (with the reassignment command).
+  - `AGENT_ASSIGNEE_HANDLE` still works verbatim as an escape hatch.
+- Own backlog data migrated: no open task is stored with an `@`-prefixed
+  assignee anymore.
+
+### Changed
+
+- Docs flipped to bare assignees: AGENTS.md team rules (`-a developer`),
+  agent templates (`agents/developer.md`, `agents/analyst.md`), README,
+  docs/config.md, docs/usage.md, docs/prompts.md, docs/task-selection.md.
+  The TUI header keeps `@name` as display-only notation.
+
+## [0.6.0] - 2026-09-17
+
+### Added
+
+- Deterministic task selection: `Providers::Backlog` now requests
+  `--ready --sort priority` from the backlog CLI and re-sorts the normalized
+  batch in the adapter — In Progress first, then priority
+  High > Medium > Low, then ordinal ascending, then id ascending — so the
+  batch letsdo hands to the loop is the authoritative runnable order and the
+  common divergence between what letsdo reads and what the agent picks
+  disappears. Blocked tasks (unfinished dependencies) are never offered, and
+  the normalized `Task` carries the fields selection needs (`ordinal`,
+  `type`, `labels`, `milestone`) while a growing backlog JSON schema still
+  cannot crash the adapter (TASK-95).
+- `docs/task-selection.md` — how letsdo picks the next task today, the
+  missing-data table, and the recommendation roadmap (TASK-86).
+
+### Changed
+
+- Documentation for per-agent model configuration: `docs/config.md`,
+  `docs/prompts.md` and the README now cover the YAML front-matter agent
+  config block (`model:` and friends) and its interaction with
+  `LETSDO_PI_COMMAND` (TASK-89).
+
+## [0.5.0] - 2026-09-13
+
+### Added
+
+- `letsdo doctor` — an environment self-check that prints one line per
+  check with a status tag (`[ OK ]` / `[WARN]` / `[FAIL]` / `[INFO]`) and an
+  actionable hint for every FAIL/WARN, exiting 0 when nothing FAILs and 1
+  otherwise. It checks the Ruby version (`>= 3.3`), the `pi` and `backlog`
+  commands (honoring `LETSDO_PI_COMMAND` / `LETSDO_BACKLOG_COMMAND`),
+  `backlog/tasks/` under `LETSDO_ROOT`, `AGENTS.md`, a non-empty `agents/`,
+  and whether stdout is a TTY. `doctor` is a reserved agent name: it always
+  runs the self-check and never launches an agent (TASK-71).
+- Agent prompts now carry the agent's own identity: on every
+  `letsdo <name>` launch, letsdo prepends an identity block (agent name +
+  backlog assignee handle) to the system prompt, whether the prompt comes
+  from `agents/<name>.md` or the built-in default. The handle is
+  `Config#assignee_handle` (default `@<name>`, overridable with
+  `AGENT_ASSIGNEE_HANDLE`), so the identity an agent reads matches the
+  handle its backlog tasks are assigned to (TASK-85).
+- Plain mode now supports the TUI control keys when stdin is a terminal:
+  `p` pauses/resumes the running agent (SIGSTOP/SIGCONT) and `q` stops it
+  cleanly (exit 0), while the output stays a plain byte stream. With a
+  piped or `/dev/null` stdin the reader is never started, so stopping stays
+  signal-only (`SIGINT`/`SIGTERM`/`SIGHUP`) (TASK-75).
+- Inside tmux, a TUI session now labels its window with the agent name
+  (`letsdo developer` → window `developer`) instead of the process name
+  tmux's automatic-rename derives (`ruby`), so side-by-side agent panes are
+  distinguishable. automatic-rename is disabled for the session and
+  restored, together with the previous window label, on every exit path
+  (quit, stop signal, crash). Outside tmux nothing extra is written and the
+  tmux binary is never invoked (TASK-90).
+
+### Changed
+
+- When the backlog cannot be read, the loop's first "backlog unavailable"
+  message of a run now points at `letsdo doctor`; later retries keep the
+  short line, so a long outage does not repeat the hint forever (TASK-93).
 
 ## [0.4.0] - 2026-09-08
 
@@ -135,7 +224,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Minitest tests; CI (GitHub Actions) builds the gem and runs tests on every push.
 - Local executable `letsdo`.
 
-[Unreleased]: https://github.com/sergio-fry/letsdo/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/sergio-fry/letsdo/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/sergio-fry/letsdo/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/sergio-fry/letsdo/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/sergio-fry/letsdo/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/sergio-fry/letsdo/compare/v0.1.0...v0.2.0

data/README.md

@@ -32,8 +32,9 @@ platform — the backlog folder is the single source of truth.
   already have everything letsdo needs. The tasks are the instructions;
   letsdo only executes them.
 - **Zero-config team.** A new agent is a new file: `agents/<name>.md`
-  with the agent's instructions. The assignee handle is derived from the
-  name (`@developer` ↔ `developer`), so the agent automatically works on
+  with the agent's instructions. The assignee is derived from the
+  name (`developer` the agent ↔ `developer` the assignee; `@developer`
+  is prose notation only), so the agent automatically works on
   the tasks already assigned to it. No code, no schemas, no setup.
 - **One task per run — honest work.** Each run picks up exactly one open
   task and completes it before the next. No context-switching, no runaway
@@ -53,11 +54,15 @@ generation, any repeatable task flow you can express as assignee + prompt.
 ## Features
 
 - **One-command agent run** — `letsdo <name>` starts the loop: all open
-  tasks assigned to `@<name>` are done one after another (one agent run =
+  tasks assigned to `<name>` are done one after another (one agent run =
   one task), then the loop waits for new ones until stopped with
   `SIGINT/SIGTERM` (clean exit, code 0).
 - **Agents as prompt files** — `agents/<name>.md` is the whole identity of
-  an agent: role, rules, workflow. Add a file, get an agent.
+  an agent: role, rules, workflow. Add a file, get an agent. letsdo injects
+  the agent's name and backlog assignee handle into the prompt on every
+  launch, so the template only needs role and rules. An optional YAML
+  front-matter block in the same file sets per-agent launch settings —
+  today `model:` selects the pi model for that agent.
 - **Built-in default prompt** — an agent starts even without a prompt file:
   it runs on the built-in default prompt (process-only instructions), and
   letsdo announces once where the prompt was looked for and how to create
@@ -68,6 +73,11 @@ generation, any repeatable task flow you can express as assignee + prompt.
 - **Orchestrator loop** — retries every 10 s (configurable) when there are
   no open tasks, pauses when the backlog is unreadable instead of crashing,
   and stops instantly on `Ctrl+C`.
+- **Pause/quit in plain mode** — when stdin is still a terminal (e.g.
+  `letsdo developer > run.log`), `p` pauses/resumes the running agent and
+  `q` stops it cleanly, exactly like the TUI keys; the byte stream itself
+  stays plain. With a piped stdin the control keys are unavailable and
+  stopping stays signal-only (`Ctrl+C`/`SIGTERM`/`SIGHUP`).
 - **Streaming output** — agent text streams to stdout as it is generated;
   service and tool lines go to stderr with a shared `HH:MM:SS` prefix:
   tool start (`⚙ name: args`) and completion with duration
@@ -85,7 +95,9 @@ generation, any repeatable task flow you can express as assignee + prompt.
   `PATH` — this is the AI backend that runs the agent (`pi --mode json`).
   The command is configurable via `LETSDO_PI_COMMAND`.
 - The Backlog.md CLI (`backlog`) on `PATH` — the task provider reads open
-  tasks via `backlog task list --assignee <handle>`. Configurable via
+  tasks via `backlog task list --exclude-status Done --ready --sort
+  priority --json` and matches the agent's assignee on them.
+  Configurable via
   `LETSDO_BACKLOG_COMMAND`.
 
 Tests and the build use only Ruby's bundled default gems (Minitest, Rake) —
@@ -128,9 +140,18 @@ cd your-backlog-project
 # create an agent prompt (once)
 letsdo developer --init        # writes agents/developer.md, never runs the agent
 
-# or write agents/developer.md by hand — the file is the agent's instructions
-
-# run the agent: it works through all open tasks assigned to @developer
+# or write agents/developer.md by hand — the file is the agent's instructions.
+# It can start with an optional YAML front-matter block that sets per-agent
+# launch settings — today, the pi model:
+#
+#   ---
+#   model: anthropic/claude-sonnet-4-5
+#   ---
+#
+# Without model:, pi's own default model is used. A --model in
+# LETSDO_PI_FLAGS overrides the file.
+
+# run the agent: it works through all open tasks assigned to developer
 letsdo developer
 ```
 
@@ -151,12 +172,34 @@ The agent still runs — on the built-in default prompt. The notification is
 printed once per process. The looked-up path is exactly
 `<LETSDO_ROOT>/agents/<name>.md`.
 
+Not sure what is broken in the environment? Run the self-check:
+
+```
+$ letsdo doctor
+[ OK ] ruby 4.0.2 (>= 3.3)
+[ OK ] pi command found: pi
+[ OK ] backlog command found: backlog
+[ OK ] project root /home/user/backlog-project has backlog/tasks/
+[ OK ] AGENTS.md present at /home/user/backlog-project/AGENTS.md
+[ OK ] agents/ present with 1 prompt(s)
+[INFO] stdout is not a TTY - plain mode
+```
+
+One line per check with a status tag (`[ OK ]`, `[WARN]`, `[FAIL]`,
+`[INFO]`); every FAIL and WARN carries an actionable hint. It exits 1 when a
+check FAILs (0 otherwise, warnings included), so it can gate scripts.
+`doctor` is a reserved agent name — it always runs the self-check and never
+launches an agent. When the loop cannot read the backlog, its first
+`backlog unavailable` message of a run points at `letsdo doctor`, so the
+cause is one command away.
+
 For the full walkthrough — install, session anatomy (plain and TUI), the
 loop/waiting model, exit codes — see the [usage guide](docs/usage.md).
 
 CLI reference:
 
 ```
+letsdo doctor              # environment self-check, exit 0 unless a check FAILs
 letsdo <name>              # run the <name> agent in the loop (exit 0 on stop)
 letsdo <name> --init       # create agents/<name>.md, never run the agent (exit 0)
 letsdo --init <name>       # same as above (flag-first form)
@@ -177,19 +220,100 @@ All knobs are environment variables:
 | Variable | Default | Purpose |
 | --- | --- | --- |
 | `LETSDO_ROOT` | current folder | Project root where `agents/` lives (and where the `backlog` CLI finds `backlog/`). |
-| `LETSDO_PI_FLAGS` | — | Extra pi flags, e.g. `--model anthropic/claude-sonnet-4-5` (split on whitespace). |
+| `LETSDO_PI_FLAGS` | — | Extra pi flags, e.g. `--model anthropic/claude-sonnet-4-5` (split on whitespace). A `--model` here overrides the agent's front-matter `model:`. |
 | `AGENT_PI_FLAGS` | — | Fallback for `LETSDO_PI_FLAGS` (compatibility with the old `bin/agent`). |
 | `LETSDO_PI_COMMAND` | `pi` | The pi command used to run agents; overridable for tests / fake pi. |
-| `AGENT_ASSIGNEE_HANDLE` | `@<name>` | The agent's backlog assignee handle. The one rule: handle = name. |
+| `AGENT_ASSIGNEE_HANDLE` | `<name>` | The agent's backlog assignee. The one rule: assignee = name, stored bare (`@` is prose-only notation). Also the assignee injected into the agent's prompt identity. |
 | `LETSDO_WAIT_SECONDS` | 10 | Retry interval when there are no open tasks. |
 | `AGENT_WAIT_SECONDS` | — | Fallback for `LETSDO_WAIT_SECONDS` (`bin/agent-loop` compatibility). |
+| `LETSDO_MAX_RETRIES` | 3 | Max consecutive failed runs of the same task before giving up for the session. |
+| `LETSDO_RETRY_BASE` | = `LETSDO_WAIT_SECONDS` | Base backoff seconds; doubles per failure, capped by `LETSDO_RETRY_CAP`. |
+| `LETSDO_RETRY_CAP` | 300 | Maximum backoff seconds between attempts. |
 | `LETSDO_BACKLOG_COMMAND` | `backlog` | The Backlog.md CLI command used as the task provider. |
+| `LETSDO_PROVIDER` | `backlog` | Task provider name used by the loop (currently only `backlog`). |
+| `LETSDO_BACKEND` | `pi` | AI backend that runs each agent (only `pi` today; `LETSDO_PI_COMMAND`/`LETSDO_PI_FLAGS` keep working as before). |
+| `LETSDO_METRICS_FILE` | — | Append session metrics as JSON Lines (`session_start`, one `run_finished` per task, `session_stop`) to this path. Unset disables the file. |
+| `LETSDO_TASK_TIME_COMMENT` | unset (off) | Set to `1` to append a `letsdo: completed in <time>` comment to each completed task's backlog record at stop (see the stop summary below). Off by default: no task file is modified and no extra backlog subprocess runs. |
 | `LETSDO_DEBUG` | — | Set to `1` to trace loop decisions on stderr. |
 
+On stop, letsdo prints a session summary to stderr — done / failed /
+interrupted counts, open tasks left, total session time, time inside runs,
+the derived waiting time, the average done-run duration, and up to ten
+per-task lines (`TASK-42 done in 2m 10s`):
+
+```
+letsdo: session: 3 done, 1 failed, 0 interrupted, 4 left open, 12m 30s (8m 10s in runs, 4m 20s waiting, avg 2m 43s)
+letsdo:   TASK-12 done in 3m 5s
+letsdo:   TASK-13 failed in 1m 2s
+```
+
+The same summary prints in TUI mode after the terminal is restored, so a
+TUI session leaves the identical record on stderr. With
+`LETSDO_METRICS_FILE` set, the recorder also appends one JSON object per
+event — `session_start`, `run_finished` (`{task, exit, outcome,
+ elapsed_s, ts}`) and `session_stop` — flushing each line as it is written.
+An unwritable path only warns on stderr; the run continues without the
+file. `waiting` is a derived approximation (session time minus run time):
+it also covers polling and backlog reads, not only idle waiting.
+
+### Per-task elapsed in the task record (opt-in)
+
+With `LETSDO_TASK_TIME_COMMENT=1`, letsdo writes the elapsed time back into
+the task record at stop. The write-back is batched after every agent run
+has ended (so it cannot race the agent's own closing edit), re-queries the
+provider once, and comments only exit-0 runs whose task is **no longer
+open** — a task still open after its run is skipped, because calling it
+completed would be wrong. The comment is authored as `@letsdo`:
+
+```
+letsdo: completed in 4m 12s
+```
+
+It runs the configured `LETSDO_BACKLOG_COMMAND` in the project root
+(`backlog task edit <id> --comment '...' --comment-author @letsdo`). A
+missing or renamed task, or a failing command, warns once per task
+(`letsdo: cannot write task time comment for TASK-12: ...`) and the summary
+reports `N comments not written`; the stop path and the exit code are
+unaffected. The flag is off by default, so a normal session never touches
+task files and never spawns an extra backlog process.
+
 The comprehensive reference — every variable with defaults, precedences,
 examples and where each one is read — lives in the
 [configuration reference](docs/config.md).
 
+## Failure handling
+
+When an agent run fails, the loop avoids hammering the same task and
+instead backs off, then gives up for the session:
+
+- **Non-zero exit** (including a task killed by a signal, exit 128+):
+  counts as a failure of that task.
+- **Exit 0 but the task is still open** on the next provider poll:
+  also counts as a failure — the agent ended without closing the task.
+- **Task gone from the provider** after a run: counts as success and
+  clears the task's retry state.
+
+Failing tasks are retried with exponential backoff: after the *n*
+failure the task is skipped from the attempt batches until
+`now >= now + min(LETSDO_RETRY_BASE * 2^(n-1), LETSDO_RETRY_CAP)`
+seconds have elapsed (default: 10s, 20s, 40s, capped at 300s).
+
+After `LETSDO_MAX_RETRIES` (default 3) consecutive failures the loop
+stops attempting that task for the rest of the session, logs
+`letsdo: giving up on <TASK> after N failed runs — task stays open,
+next session will retry it` to stderr, and keeps processing other
+open tasks. A fresh `letsdo` session starts with no failure state,
+so a temporarily-failing task is retried next session.
+
+**Backend missing**: when the AI backend binary cannot be started
+(`LETSDO_PI_COMMAND` points at a nonexistent or non-executable file),
+letsdo prints a clear message and exits with code 2 — no Ruby
+backtrace.
+
+The loop's stop semantics are unchanged: `SIGINT`/`SIGTERM` during a
+backoff cooldown exits promptly with code 0, and a started run is
+always terminated (TERM then KILL after a grace period) and reaped.
+
 ## How it works
 
 ```
@@ -214,10 +338,13 @@ bin/letsdo ──► Letsdo::CLI ──► Letsdo::Agent ──► Letsdo::PiRun
   code (including 128+signal).
 - `Letsdo::OutputStreamer` — routes agent text to stdout and service/tool
   lines to stderr with `HH:MM:SS` prefixes and durations.
-- `Letsdo::BacklogTasks` — the task provider: open tasks for a handle via
-  `backlog task list --assignee <handle> --exclude-status Done --json`;
-  `nil` when the backlog is unreadable (the loop pauses instead of running
-  the agent).
+- `Letsdo::BacklogTasks` — the task provider: runnable open tasks for the
+  assignee via `backlog task list --exclude-status Done --ready --sort
+  priority --json` with the assignee matched in Ruby (tolerating the
+  legacy `@` notation), returned in the authoritative run order
+  (In Progress first, then priority High > Medium > Low, then ordinal, then
+  id); `nil` when the backlog is unreadable (the loop pauses instead of
+  running the agent).
 - `Letsdo::Loop` / `Letsdo::AgentLoop` — the orchestrator: tasks → one run
   each → wait → repeat; stopped from outside via `SIGINT/SIGTERM` (the
   running pi child is terminated, exit 0).
@@ -232,9 +359,14 @@ common. This repository itself is run by letsdo: `agents/developer.md` and
 - [Usage guide](docs/usage.md) — install, first run, loop semantics,
   the interactive TUI and its keys, exit codes.
 - [Prompt-authoring guide](docs/prompts.md) — what makes a good agent
-  prompt: must-haves, anti-patterns, worked examples.
-- [Configuration reference](docs/config.md) — every environment variable,
-  its default, precedence and where it is read.
+  prompt: must-haves, anti-patterns, per-agent front-matter config, worked
+  examples.
+- [Configuration reference](docs/config.md) — every environment variable
+  and the per-agent YAML front-matter block, their defaults, precedence and
+  where they are read.
+- [Task selection](docs/task-selection.md) — how the next task is chosen,
+  the selection criteria and the deterministic-ordering behavior of the
+  provider batch.
 
 ## Development
 
@@ -270,7 +402,7 @@ Ruby 3.3 and 4.0 (satisfies `required_ruby_version: ">= 3.3"`).
 | [aider](https://github.com/Aider-AI/aider) | Pair-programming CLI | Local AI pair for code changes | Focused on interactive coding pairs, not executing a tracked backlog |
 
 What none of them do out of the box: take an existing markdown backlog,
-derive the team from the assignee handles, and execute the tasks one per
+derive the team from the assignees, and execute the tasks one per
 run with an observable loop. That is letsdo's niche — a thin convention
 layer instead of a framework. If your project is tracked in Backlog.md
 format and you want a local, observable, multi-agent worker on top of it,

data/bin/letsdo

@@ -16,6 +16,8 @@
 # so the prompt can be customized before the first run).
 #
 # Usage:
+#   ./bin/letsdo doctor       # environment self-check, exit 0 unless a check FAILs;
+#                             #   'doctor' is reserved -- it never runs an agent
 #   ./bin/letsdo <name>       # run the <name> agent in the loop (exit 0 on stop)
 #   ./bin/letsdo <name> --init # create agents/<name>.md with the starter
 #                               #   default prompt, never run the agent (exit 0)
@@ -29,9 +31,14 @@
 #   LETSDO_ROOT             project root with agents/ (default — current folder)
 #   LETSDO_PI_FLAGS         extra pi flags (e.g. "--model anthropic/claude-sonnet-4-5")
 #   AGENT_PI_FLAGS          the same, for bin/agent compatibility if LETSDO_PI_FLAGS is unset
-#   AGENT_ASSIGNEE_HANDLE   the agent's backlog assignee handle (default "@<name>")
+#   AGENT_ASSIGNEE_HANDLE   the agent's backlog assignee (default <name>,
+#                           the bare name; a legacy '@<name>' value is warned
+#                           about by `letsdo doctor`)
 #   LETSDO_WAIT_SECONDS     retry interval when no tasks are open (default 10)
 #   LETSDO_BACKLOG_COMMAND  the backlog CLI command (default "backlog")
+#   LETSDO_PROVIDER         task provider name (default "backlog")
+#   LETSDO_BACKEND          AI backend that runs each agent (default "pi";
+#                           unknown values fail fast with exit code 1)
 #
 # A new agent = a new agents/<name>.md file, no code changes needed.
 #

data/docs/config.md

@@ -0,0 +1,176 @@
+# letsdo — configuration reference
+
+Configuration comes from two places: environment variables (everything in
+this reference) and an optional YAML front-matter block at the top of an
+agent's prompt file, `agents/<name>.md` — see
+[Per-agent configuration](#per-agent-configuration-yaml-front-matter).
+Nothing else is configured in files.
+
+## Project layout
+
+```
+LETSDO_ROOT  (default: the current working directory)
+├── backlog/            # the Backlog.md tasks — the task provider reads them
+├── agents/<name>.md    # one prompt file per agent
+└── bin/letsdo          # the executable (or the installed letsdo command)
+```
+
+- `LETSDO_ROOT` — project root: `agents/` lives there, and the `backlog`
+  CLI resolves `backlog/` there. Default: the folder letsdo was started
+  from.
+- The agent's assignee is `<name>` by default — the agent works on tasks
+  assigned to that name. The tracker stores bare names; `@<name>` is
+  prose-only notation (`letsdo doctor` warns about legacy `@`-prefixed
+  data).
+
+## Environment variables
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `LETSDO_ROOT` | current directory | Project root where `agents/` lives (and where the `backlog` CLI finds `backlog/`). |
+| `LETSDO_PI_FLAGS` | unset (no flags) | Extra pi flags, split on whitespace, e.g. `--model anthropic/claude-sonnet-4-5`. A `--model` here overrides the agent's front-matter `model:` (see [Per-agent configuration](#per-agent-configuration-yaml-front-matter)). |
+| `AGENT_PI_FLAGS` | unset | Fallback for `LETSDO_PI_FLAGS` when it is blank (compatibility with the old `bin/agent`). |
+| `LETSDO_PI_COMMAND` | `pi` | The pi command used to run agents; overridable for tests / fake pi. |
+| `AGENT_ASSIGNEE_HANDLE` | `<name>` | The agent's backlog assignee (used verbatim when set; the bare name is canonical, a legacy `@`-prefixed value still matches but `letsdo doctor` warns). Also injected as the agent's identity in its prompt. |
+| `LETSDO_WAIT_SECONDS` | `10` | Retry interval (seconds) when there are no open tasks. |
+| `AGENT_WAIT_SECONDS` | `10` (via fallback) | Fallback for `LETSDO_WAIT_SECONDS` when it is blank (`bin/agent-loop` compatibility). |
+| `LETSDO_MAX_RETRIES` | `3` | Max consecutive failed runs of the same task before giving up for the session. |
+| `LETSDO_RETRY_BASE` | = `LETSDO_WAIT_SECONDS` | Base backoff seconds; doubles per failure, capped by `LETSDO_RETRY_CAP`. |
+| `LETSDO_RETRY_CAP` | `300` | Maximum backoff seconds between attempts. |
+| `LETSDO_BACKLOG_COMMAND` | `backlog` | The Backlog.md CLI command used as the task provider. |
+| `LETSDO_PROVIDER` | `backlog` | Task provider name used by the loop (currently only `backlog`). |
+| `LETSDO_BACKEND` | `pi` | AI backend that runs each agent (only `pi` today; `LETSDO_PI_COMMAND`/`LETSDO_PI_FLAGS` keep working as before). |
+| `LETSDO_DEBUG` | unset | Set to `1` to trace loop and runner decisions (`[letsdo] loop: ...`) on stderr. |
+| `LETSDO_TASK_TIME_COMMENT` | unset (off) | Set to `1` to append a `letsdo: completed in <time>` comment to each completed task's backlog record at session stop. Off by default: no task file is modified and no extra backlog subprocess runs. |
+
+### Precedence rules
+
+- `LETSDO_PI_FLAGS` → `AGENT_PI_FLAGS`: the flags are read from
+  `LETSDO_PI_FLAGS`; when it is blank/absent, `AGENT_PI_FLAGS` is used. A
+  blank result means no flags.
+- `LETSDO_WAIT_SECONDS` → `AGENT_WAIT_SECONDS`: same pattern, falling back
+  to the default `10`. A non-numeric value also falls back to `10`.
+- `LETSDO_RETRY_BASE` → `LETSDO_WAIT_SECONDS`: when
+  `LETSDO_RETRY_BASE` is blank or non-numeric, the backoff base falls back
+  to the effective `LETSDO_WAIT_SECONDS` value.
+- `LETSDO_MAX_RETRIES`: an invalid (non-integer) value falls back to `3`.
+- `LETSDO_RETRY_CAP`: an invalid (non-numeric) value falls back to `300`.
+- `AGENT_ASSIGNEE_HANDLE`: used as-is when set and non-blank; otherwise the
+  one rule: assignee = `<name>` (the bare name). The resolved value is both
+  the assignee the loop matches backlog tasks by and the assignee letsdo
+  injects into the agent's prompt identity. The match tolerates the legacy
+  `@` prefix, whitespace and case, so old data keeps working — but the
+  canonical stored value is the bare name, and deviations trigger a
+  once-per-run warning plus a `letsdo doctor` WARN.
+- Agent `model` → `LETSDO_PI_FLAGS`/`AGENT_PI_FLAGS`: a `--model` in the
+  flags wins; the agent's front-matter `model:` is used only when the flags
+  carry no `--model`. See
+  [Per-agent configuration](#per-agent-configuration-yaml-front-matter).
+
+### Examples
+
+```sh
+# Point letsdo at a project from anywhere
+export LETSDO_ROOT=/srv/projects/acme-backlog
+
+# Choose the pi model
+export LETSDO_PI_FLAGS="--model anthropic/claude-sonnet-4-5"
+
+# Less chatty backlog polling
+export LETSDO_WAIT_SECONDS=30
+export LETSDO_DEBUG=1        # trace loop decisions when diagnosing
+
+# Non-standard installations
+export LETSDO_PI_COMMAND=/opt/pi/bin/pi
+export LETSDO_BACKLOG_COMMAND=~/.local/bin/backlog
+```
+
+## Per-agent configuration (YAML front matter)
+
+A prompt file may start with a YAML front-matter block that carries launch
+settings for that one agent. The block is optional: a file without it
+behaves exactly as before.
+
+```markdown
+---
+model: anthropic/claude-sonnet-4-5
+---
+
+# Developer agent (developer)
+You are a developer agent named developer.
+...
+```
+
+Rules:
+
+- The block must be the *very first* thing in `agents/<name>.md`: a `---`
+  line, the YAML keys, a closing `---` line. The rest of the file stays the
+  prompt.
+- The front matter is stripped before the file is handed to the agent, so it
+  never appears in the system prompt.
+- `model` is the only key consumed today:
+  - `model: <name>` is passed to pi as `--model <name>` for that agent.
+  - Absent → no `--model` is added and pi uses its own default model.
+  - A missing file, no front matter, or invalid YAML is treated the same as
+    absent: the block is ignored and the run continues.
+- Precedence: a `--model` coming from `LETSDO_PI_FLAGS`/`AGENT_PI_FLAGS`
+  wins over the file's `model:`. If you set a global `--model`, every agent
+  uses it and the front matter is ignored — leave `--model` out of the
+  global flags to select the model per agent.
+- The block is extensible: unknown keys (e.g. `tags:`) are parsed and
+  ignored, so new parameters can be added later without breaking existing
+  prompt files.
+
+Read by `Letsdo::PromptStore#config` (`lib/letsdo/prompt_store.rb`), passed
+to the backend by `Letsdo::Agent#run` (`lib/letsdo/agent.rb`) and applied in
+`Letsdo::Backends::Pi#initialize` (`lib/letsdo/backends/pi.rb`).
+
+## TERM and TUI selection
+
+The interactive TUI is engaged only when **all** of these hold:
+
+1. stdout is a TTY, and
+2. stdin is a TTY, and
+3. `TERM` is not `dumb`.
+
+Otherwise letsdo prints the plain line-stream output — byte-identical to
+the pre-TUI behavior, with no escape codes. Set `TERM=dumb` (or pipe stdout
+through something) to force the plain mode explicitly, e.g. in scripts or
+CI.
+
+## Where each variable is read
+
+- `LETSDO_ROOT` — `Letsdo::CLI#initialize` (`lib/letsdo/cli.rb`).
+- `LETSDO_PI_FLAGS` / `AGENT_PI_FLAGS` — `Letsdo::CLI#parse_pi_flags`
+  (`lib/letsdo/cli.rb`).
+- `LETSDO_PI_COMMAND` — `Letsdo::CLI#pi_command` (`lib/letsdo/cli.rb`),
+  default `PiRunner::COMMAND` (`lib/letsdo/pi_runner.rb`).
+- `AGENT_ASSIGNEE_HANDLE` — `Letsdo::CLI#assignee_handle`
+  (`lib/letsdo/cli.rb`).
+- `LETSDO_WAIT_SECONDS` / `AGENT_WAIT_SECONDS` — `Letsdo::CLI#wait_seconds`
+  (`lib/letsdo/cli.rb`).
+- `LETSDO_BACKLOG_COMMAND` — `Letsdo::CLI#backlog_command`
+  (`lib/letsdo/cli.rb`).
+- `LETSDO_PROVIDER` — `Letsdo::Config#provider` and
+  `Letsdo::CLI::Builder#resolve_provider!` (unknown values fail fast with
+  `letsdo: unknown task provider: <name>`, exit code 1).
+- `LETSDO_BACKEND` — `Letsdo::Config#backend` and
+  `Letsdo::CLI::Builder#resolve_backend!` (unknown values fail fast with
+  `letsdo: unknown AI backend: <name>`, exit code 1).
+- `LETSDO_DEBUG` — `Letsdo::AgentLoop#initialize` (`lib/letsdo/agent_loop.rb`)
+  and `Letsdo::PiRunner#initialize` (`lib/letsdo/pi_runner.rb`); enabled when
+  the value is exactly `"1"`.
+- `LETSDO_TASK_TIME_COMMENT` — `Letsdo::Config#task_time_comment?`
+  (`lib/letsdo/config.rb`); enabled only when the value is exactly `"1"`.
+  Consumed by `Letsdo::CLI::Builder#finish_session`, which runs
+  `Letsdo::TaskTimeWriteback` at stop.
+- `TERM` — `Letsdo::CLI#tui?` (`lib/letsdo/cli.rb`).
+
+## External Requirements (not configurable)
+
+- The **pi CLI** is a runtime requirement of letsdo — an external binary,
+  not a rubygem dependency. `LETSDO_PI_COMMAND` only replaces the command
+  name. See the [usage guide](usage.md) prerequisites.
+- Test-only environment variables (`FAKE_PI_*`, `FAKE_BACKLOG_*`) belong to
+  the test fixtures (`test/fixtures/`) and are not part of the runtime
+  configuration.