letsdo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3a847d927396a19813b8b643486bddabe1f9264f9ba38c6618110e24cc67b55d
+  data.tar.gz: 6d8ad205231a4e833694d7471efffe40dfd8a1f5bea89c45fdf1babb099fbdfa
+SHA512:
+  metadata.gz: 39ba23f90a1c8c4add2bce03e9443071a7cb57dd0458c64e7be96ec0c803ff098cea7fbd0d4a9d37eb94050aa470e142f7820643d6738be759176424e2387b98
+  data.tar.gz: 6bc4f0e7f03e01963bfb44d305e0ca76082727643a061eb042a58f71f49fce415a4616a4e6374c7461575ec28458f66c51fa864abc81048751367cf2ba4549a8

data/LICENSE

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

data/README.md

@@ -0,0 +1,291 @@
+# letsdo
+
+> A local agent worker for Backlog.md/markdown tasks.
+
+Letsdo turns a plain markdown backlog into a team of autonomous agents.
+Each agent is just a prompt file in `agents/`; run `letsdo <name>` and the
+agent picks up all open tasks assigned to it, one task per run, loops back
+for new ones, and stops cleanly on `Ctrl+C`. No framework code, no hosted
+platform — the backlog folder is the single source of truth.
+
+[![CI](https://github.com/sergio-fry/letsdo/actions/workflows/ci.yml/badge.svg)](https://github.com/sergio-fry/letsdo/actions)
+
+## Table of contents
+
+- [Why letsdo](#why-letsdo)
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Getting started](#getting-started)
+- [Configuration](#configuration)
+- [How it works](#how-it-works)
+- [Guides](#guides)
+- [Development](#development)
+- [Alternatives](#alternatives)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Why letsdo
+
+- **Your backlog already exists.** If you track work in a
+  Backlog.md/markdown project (a `backlog/` folder of markdown tasks), you
+  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
+  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
+  loops: the orchestrator loop assigns the next task only after the current
+  one finishes, and pauses when there is nothing to do.
+- **Local and private.** Everything runs on your machine — `pi` in
+  `--mode json` under the hood. No hosted agents, no task data leaving
+  your project.
+- **Observable.** The stream shows exactly what the agent is doing:
+  agent text on stdout, tool calls with `HH:MM:SS` timestamps and
+  completion durations on stderr.
+
+Use it when you want a local, convention-driven worker that executes
+backlog tasks autonomously: development chores, analysis spikes, doc
+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 =
+  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.
+- **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
+  it (`letsdo <name> --init`).
+- **`--init` scaffold** — `letsdo <name> --init` creates
+  `agents/<name>.md` with the starter default prompt so you can customize
+  it. It never runs the agent and never overwrites an existing file.
+- **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`.
+- **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`), completion with duration
+  (`✓/✖ name: … (3s)`), indented results (trimmed with a summary note
+  when large), and error results marked (`✖ Error: ...`).
+- **`--version` / `--help`** — `Letsdo::VERSION` and usage, exit 0.
+- **Available as a library** — `require "letsdo"` exposes the
+  `Letsdo` module (`Letsdo::VERSION`, `Letsdo::PromptStore`, `Letsdo::Agent`,
+  ...) for embedding or testing.
+
+## Requirements
+
+- Ruby **>= 3.0**.
+- The [pi](https://github.com/earendil-works/pi) agent CLI on
+  `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
+  `LETSDO_BACKLOG_COMMAND`.
+
+Tests and the build use only Ruby's bundled default gems (Minitest, Rake) —
+no `bundle install` needed.
+
+## Installation
+
+The gem is built from the repository:
+
+```sh
+git clone git@github.com:sergio-fry/letsdo.git
+cd letsdo
+gem build letsdo.gemspec
+gem install letsdo-0.1.0.gem
+```
+
+or run it straight from the checkout without installing:
+
+```sh
+cd letsdo
+./bin/letsdo --version
+```
+
+## Getting started
+
+Letsdo works in a Backlog.md project root — a folder that holds the
+`backlog/` tasks and your `agents/` prompts:
+
+```sh
+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
+letsdo developer
+```
+
+The loop prints service messages on stderr (started, which task is being
+run, no open tasks / backlog unavailable, stopped) and streams the agent's
+text on stdout. Stop the loop with `Ctrl+C` — a running agent child is
+terminated and the process exits with code 0.
+
+No prompt file? No problem:
+
+```
+$ letsdo newcomer
+letsdo: no prompt for newcomer at /home/user/backlog-project/agents/newcomer.md
+letsdo: using the built-in default prompt (create a prompt file with 'letsdo newcomer --init')
+```
+
+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`.
+
+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 <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)
+letsdo --version           # gemspec version, exit 0
+letsdo --help              # usage and agent list, exit 0
+letsdo                     # usage and agent list, exit 1
+letsdo --badopt            # "unknown option" + usage, exit 1
+```
+
+`--init` fails with exit 1 and a message on stderr when the file already
+exists (never overwrites) or the agent name is unsafe (contains `/` or `\`,
+or is `.`/`..` — nothing is ever written outside `agents/`).
+
+## Configuration
+
+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). |
+| `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. |
+| `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_BACKLOG_COMMAND` | `backlog` | The Backlog.md CLI command used as the task provider. |
+| `LETSDO_DEBUG` | — | Set to `1` to trace loop decisions on stderr. |
+
+The comprehensive reference — every variable with defaults, precedences,
+examples and where each one is read — lives in the
+[configuration reference](docs/config.md).
+
+## How it works
+
+```
+bin/letsdo ──► Letsdo::CLI ──► Letsdo::Agent ──► Letsdo::PiRunner (pi --mode json)
+                     │                │                    │
+                     │                │              Letsdo::OutputStreamer (stdout/stderr)
+                     ▼                ▼
+             Letsdo::BacklogTasks  Letsdo::AgentLoop
+             (backlog CLI → tasks) (orchestrator loop)
+```
+
+- `Letsdo::CLI` — argument parsing, usage, exit codes; builds the agent, the
+  task provider and the loop.
+- `Letsdo::PromptStore` — access to `agents/<name>.md` prompts; `--init`
+  writes them via `create_agent` (no overwrite, safe names only).
+- `Letsdo::DefaultPrompt` — the built-in default prompt: the single source
+  of truth used both for the fallback run and as the `--init` template.
+- `Letsdo::Agent` — one agent run: the prompt (file or default) + a `pi`
+  child process; returns the pi exit code.
+- `Letsdo::PiRunner` — spawns `pi --mode json <flags> <prompt>`, parses the
+  line-by-line event stream, feeds the streamer, propagates the pi exit
+  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::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).
+
+Multiple agents run as separate processes, each with its own loop and its
+own assignee; they coordinate through the shared backlog — nothing else in
+common. This repository itself is run by letsdo: `agents/developer.md` and
+`agents/analyst.md` are its own workers on the `backlog/` tasks.
+
+## Guides
+
+- [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.
+
+## Development
+
+The gem uses Minitest (bundled with Ruby, plain `assert`/`refute`, no
+external DSLs or mock frameworks), so tests run on a clean Ruby:
+
+```sh
+rake test                                  # all tests
+ruby -Itest -Ilib test/cli_test.rb         # one test file
+```
+
+Test fixtures: `test/fixtures/fake_pi` emulates the `pi --mode json` event
+stream (`FAKE_PI_SCENARIO=default|error|big|stub`); the CLI snapshots the
+spawned fake-pi argv per run, which tests assert on.
+
+Building the gem:
+
+```sh
+gem build letsdo.gemspec
+```
+
+Cleanliness is enforced by the CI workflow
+(`.github/workflows/ci.yml`): gem build + `rake test` on every push,
+Ruby 3.3 (satisfies `required_ruby_version: ">= 3.0"`).
+
+## Alternatives
+
+| Tool | What it is | What's similar | What's different |
+| --- | --- | --- | --- |
+| [Claude Code](https://github.com/anthropics/claude-code) | Anthropic's terminal agent | Local, terminal-driven, works in your repository | Interactive chat sessions you drive; no backlog loop, no one-task-per-run contract, no multi-agent-by-convention |
+| [OpenAI Codex CLI](https://github.com/openai/codex) | OpenAI's terminal coding agent | Local agent on the command line | Same interactive pattern; session-based, not a task-execution worker |
+| [CrewAI](https://github.com/crewAIInc/crewAI) / [AutoGPT](https://github.com/Significant-Gravitas/AutoGPT) | Agent orchestration frameworks (Python) | Multi-agent teams and roles | The team, tools and workflow are code and configuration; no built-in task-tracker loop |
+| [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
+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,
+letsdo is the smallest thing that does it.
+
+## Contributing
+
+Contributions are welcome. The project is small and intentionally so —
+please keep it that way.
+
+- **Language.** All task tracking, prompts, docs and comments are in
+  English (project convention). New code and docs follow suit.
+- **Where the code lives.** `bin/letsdo` (entry point),
+  `lib/letsdo/` (CLI, PromptStore, DefaultPrompt, Agent, PiRunner,
+  OutputStreamer, BacklogTasks, Loop, AgentLoop), `test/` (Minitest +
+  fixtures), `letsdo.gemspec`, `.github/workflows/ci.yml`.
+- **Before opening a PR:** `rake test` must pass with 0 failures and the
+  gem must build (`gem build letsdo.gemspec`) — the same checks CI runs on
+  every push.
+- **Dogfooding.** This repository manages itself with letsdo: new work is
+tracked as Backlog tasks, and `agents/developer.md` / `agents/analyst.md`
+execute them. Every change is a chance to exercise the tool.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/bin/letsdo

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# letsdo — a local agent worker for Backlog.md/markdown tasks.
+#
+# A thin wrapper over Letsdo::CLI: runs an agent by name (prompt from
+# agents/<name>.md in the project root) as an orchestrator loop — all open
+# tasks assigned to the agent 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).
+#
+# Usage:
+#   ./bin/letsdo <name>    # run the <name> agent in the loop (exit 0 on stop)
+#   ./bin/letsdo --version # version, exit 0
+#   ./bin/letsdo --help    # help, exit 0
+#   ./bin/letsdo           # usage and agent list, exit 1
+#   ./bin/letsdo --badopt  # "unknown option" + usage, exit 1
+#
+# Environment:
+#   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>")
+#   LETSDO_WAIT_SECONDS     retry interval when no tasks are open (default 10)
+#   LETSDO_BACKLOG_COMMAND  the backlog CLI command (default "backlog")
+#
+# A new agent = a new agents/<name>.md file, no code changes needed.
+#
+
+require_relative "../lib/letsdo"
+
+exit Letsdo::CLI.run(ARGV)

data/lib/letsdo/agent.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # A single agent run: reads the prompt from agents/<name>.md by agent name
+  # and runs pi with that prompt. Returns the pi exit code.
+  #
+  # This is the logic of one bin/agent run: a prompt store + an output
+  # streamer + a pi runner. The orchestrator (a loop while tasks exist)
+  # lives in Letsdo::Loop.
+  class Agent
+    # @param name [String] agent name (agents/<name>.md)
+    # @param root [String] project root (agents/ lives there)
+    # @param flags [Array<String>] extra pi flags
+    # @param streamer [OutputStreamer] where to print output (by default
+    #        the real stdout/stderr)
+    # @param command [String] the pi command (overridable for tests)
+    def initialize(name:, root:, flags: [], streamer: nil, command: PiRunner::COMMAND)
+      @name = name
+      @root = root
+      @flags = flags
+      @streamer = streamer || OutputStreamer.new
+      @command = command
+    end
+
+    # The runner of the last/current run — lets the orchestrator terminate
+    # a running pi when the loop is stopped.
+    attr_reader :runner
+
+    # Runs the agent once.
+    #
+    # @return [Integer] pi exit code
+    # @raise [UnknownAgentError] if the agent is not in agents/
+    def run
+      prompt = prompt_store.read(@name)
+      @runner = PiRunner.new(prompt: prompt, flags: @flags, streamer: @streamer, command: @command)
+      @runner.run
+    end
+
+    private
+
+    def prompt_store
+      @prompt_store ||= PromptStore.new(root: @root)
+    end
+  end
+end

data/lib/letsdo/agent_loop.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # The orchestrator loop wired to the real environment for `letsdo <name>`:
+  #
+  #   Letsdo::Loop        — while the provider gives open tasks, runs the
+  #                         agent (one run = one task); no tasks (or the
+  #                         backlog is unreadable) — waits and checks again;
+  #   task provider       — open tasks assigned to the agent's handle
+  #                         (Letsdo::BacklogTasks by default);
+  #   agent run           — one Letsdo::Agent run per open task;
+  #   signals             — SIGINT/SIGTERM stop the loop: a running pi child
+  #                         is terminated and the process exits with 0.
+  #
+  # Waiting is interruptible: stop signals are delivered as
+  # Letsdo::Stopped raised from the trap, so the loop unwinds right away
+  # instead of waiting out the retry interval (see #on_signal).
+  #
+  # Service output goes to stderr: started, running <name> for <task>, no
+  # open tasks / backlog unavailable with the retry interval, non-zero agent
+  # exit codes, stopped.
+  class AgentLoop
+    STOP = :letsdo_stop
+
+    # @param name [String] agent name (for messages)
+    # @param handle [String] assignee handle of the agent (e.g. "@developer")
+    # @param agent [Letsdo::Agent, nil] agent to run once per task (its
+    #        current runner is terminated on stop); ignored when run_one is
+    #        given
+    # @param run_one [Proc, nil] callable(task) → agent exit code; by default
+    #        the injected agent's #run
+    # @param task_provider [Proc] callable → Array of open tasks (empty = no
+    #        tasks) or nil (backlog unreadable — pause)
+    # @param wait_seconds [Float] retry interval when there are no tasks
+    # @param sleeper [Proc, nil] callable(Float) → waiting; injectable for
+    #        deterministic stops in tests (throw Letsdo::AgentLoop::STOP)
+    # @param stderr [IO] service output stream
+    # @param metrics [Object, nil] optional header-metrics facade
+    #        (Letsdo::Tui::Metrics in TUI mode): receives provider_result
+    #        on every provider call and run_started/run_finished around
+    #        each agent run; nil in plain mode, so plain behavior is
+    #        byte-identical
+    # @param debug [Boolean, nil] trace [letsdo] lines to stderr; nil = LETSDO_DEBUG
+    def initialize(name:, handle:, agent: nil, run_one: nil, task_provider:,
+                   wait_seconds: 10.0, sleeper: nil, stderr: $stderr, metrics: nil, debug: nil)
+      @name = name
+      @handle = handle
+      @agent = agent
+      @run_one = run_one || ->(_task) { @agent.run }
+      @task_provider = task_provider
+      @wait_seconds = wait_seconds
+      @stderr = stderr
+      @metrics = metrics
+      @debug = debug.nil? ? ENV["LETSDO_DEBUG"] == "1" : debug
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+    end
+
+    # Runs the loop until stopped (SIGINT/SIGTERM).
+    # Runs the loop until stopped (SIGINT/SIGTERM).
+    #
+    # Stopping is done by raising Letsdo::Stopped from the signal handler:
+    # the raise interrupts whatever the main thread is doing (reading pi
+    # output, waiting for new tasks, running the backlog CLI) and unwinds
+    # the loop. The handler itself only sends SIGTERM to a running pi group
+    # (no waits or IO — safe from a trap) and raises.
+    #
+    # @return [Integer] exit code — always 0 when stopped cleanly
+    def run
+      @loop = build_loop
+      install_signal_handlers
+      debug("loop start (agent=#{@name}, handle=#{@handle}, wait=#{@wait_seconds}s)")
+      begin
+        catch(STOP) { @loop.run }
+      rescue Letsdo::Stopped
+        debug("stopped by signal")
+      end
+      debug("loop stopped")
+      @stderr.puts("letsdo: stopped")
+      0
+    ensure
+      restore_signal_handlers
+    end
+
+    def debug(message)
+      warn("[letsdo] loop: #{message}") if @debug
+    end
+
+    # Signal handler: sends SIGTERM to a running pi group and raises
+    # Letsdo::Stopped to interrupt the main thread. Nothing else — no IO,
+    # no sleeps (a trap writing to a busy stream deadlocks; the pi is
+    # reaped by Letsdo::PiRunner#run after the unwind).
+    def on_signal(_signum)
+      runner = @agent&.runner
+      runner&.terminate_now
+      raise Letsdo::Stopped
+    end
+
+    private
+
+    def build_loop
+      @loop = Letsdo::Loop.new(
+        task_provider: wrapped_provider,
+        run_task: wrapped_run,
+        wait_seconds: @wait_seconds,
+        sleeper: @sleeper
+      )
+    end
+
+    # Messages on stderr: open task count before the batch and the wait
+    # reason (no tasks vs unreadable backlog) before every wait.
+    def wrapped_provider
+      lambda do
+        tasks = @task_provider.call
+        @metrics&.provider_result(tasks.nil? ? nil : tasks.length)
+        if tasks.nil?
+          debug("provider: backlog unavailable")
+          @stderr.puts("letsdo: backlog unavailable, retrying in #{@wait_seconds}s")
+        elsif tasks.empty?
+          debug("provider: no open tasks")
+          @stderr.puts("letsdo: no open tasks for #{@name}, retrying in #{@wait_seconds}s")
+        else
+          debug("provider: #{tasks.length} open task(s)")
+          @stderr.puts("letsdo: #{@name} has #{tasks.length} open task(s)")
+        end
+        tasks
+      end
+    end
+
+    # One agent run per task; a non-zero exit code is noted but the loop
+    # continues. Metrics events bracket the run so the TUI can count done
+    # tasks and show the running one with its elapsed time.
+    def wrapped_run
+      lambda do |task|
+        @metrics&.run_started(task_label(task))
+        @stderr.puts("letsdo: running #{@name} for #{task_label(task)}")
+        debug("running agent for task #{task_label(task)}")
+        code = @run_one.call(task)
+        debug("agent run exit #{code}")
+        @stderr.puts("letsdo: #{@name} exited with code #{code}") if code != 0
+      ensure
+        @metrics&.run_finished
+      end
+    end
+
+    # A human-readable label of a task for messages: the id field when
+    # present, the object as-is otherwise.
+    def task_label(task)
+      id = task.respond_to?(:[]) ? task["id"] : nil
+      return id.to_s unless id.nil? || id.to_s.empty?
+
+      task.to_s
+    end
+
+    # The default waiting blocks only for the retry interval: a stop signal
+    # interrupts it as Letsdo::Stopped raised from the trap.
+    def interruptible_sleeper
+      ->(seconds) { sleep(seconds) }
+    end
+
+    def install_signal_handlers
+      Signal.trap("SIGINT", method(:on_signal))
+      Signal.trap("SIGTERM", method(:on_signal))
+    end
+
+    def restore_signal_handlers
+      Signal.trap("SIGINT", "DEFAULT")
+      Signal.trap("SIGTERM", "DEFAULT")
+    end
+  end
+end

data/lib/letsdo/backlog_tasks.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "shellwords"
+
+module Letsdo
+  # Task provider for Letsdo::Loop backed by the real backlog CLI:
+  #
+  #   backlog task list --assignee <handle> --exclude-status Done --json
+  #
+  # Returns the list of open tasks assigned to the handle (an Array, empty
+  # when there are none), or nil when the backlog state is unreadable — the
+  # CLI is not on PATH, failed, or its output is not the expected JSON. The
+  # loop treats nil as "pause and retry, do not run the agent".
+  #
+  # The command runs in the project root (cwd), where the backlog CLI finds
+  # the backlog/ folder — the same context as a single agent run.
+  class BacklogTasks
+    # @param handle [String] assignee handle to filter by (e.g. "@developer")
+    # @param command [String] backlog CLI command (overridable for tests)
+    # @param cwd [String, nil] project root for the CLI; nil = inherit cwd
+    # @param env [Hash, nil] environment for the CLI child (nil = inherit
+    #        the process environment; injected in tests to control the
+    #        fake backlog scenarios)
+    def initialize(handle:, command: "backlog", cwd: nil, env: nil)
+      @handle = handle
+      @command = command
+      @cwd = cwd
+      @env = env
+    end
+
+    # Reads the open tasks once.
+    #
+    # @return [Array<Hash>, nil] open tasks; nil when the backlog is unreadable
+    def call
+      args = @env ? [@env, *command_line] : command_line
+      out, _err, status = Open3.capture3(*args, chdir: @cwd)
+      return nil unless status.success?
+
+      tasks = JSON.parse(out)["tasks"]
+      tasks.is_a?(Array) ? tasks : nil
+    rescue Errno::ENOENT, JSON::ParserError, TypeError
+      nil
+    end
+
+    private
+
+    # [command..., task, list, --assignee <handle>, --exclude-status Done, --json]
+    def command_line
+      [
+        *Shellwords.split(@command),
+        "task", "list",
+        "--assignee", @handle,
+        "--exclude-status", "Done",
+        "--json"
+      ]
+    end
+  end
+end