letsdo 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f15aee491b4d0954c628e52566908e6b7ea35428c347a79822f5781198ea4be9
-  data.tar.gz: 71b47328ea44b224cb250e4bb8d0e58c052ddd054cd950fa1b058c85933f6a91
+  metadata.gz: f6c3ecf1ef07372a4f5b38843faafaf394ca49ee9ea73c48a59034c0c33ed1b9
+  data.tar.gz: 9349a23494802614dcdb7aa27d378b7ca2dae1512a395989678e166b3b68548d
 SHA512:
-  metadata.gz: eab4462fe5a7bec0981c9b2a803a02063d1714cc049f51f5add4053f80c302b917491465dda6d90aa66a59fb668b33a5d2166ea95589d317e1958a3756564f1c
-  data.tar.gz: 5f1b243e5bce00874965683d68bebf22c2c9cec992e6f8ab1e825db3a0796781a47bf51be934b5c8c5409c7ad1cf85a83d8a872c807b8d4e5a6023c888f8ca73
+  metadata.gz: 74a49f0c9d8a27c25acc94205f57a9ba9f5e63ac18a8d97e15c270b02e661e45cd30da84fe998f382d6baaa5945f59148b4edf4e62db8b292150dcb56e4e0ad9
+  data.tar.gz: ca34be59f778f078ab0766088d70acb4fe1935d3021315f98a8d1c402c6897cc2267ff5a525c0e5db6c28d3f71238fb782f8972c3db844282353a263732b604d

data/CHANGELOG.md

@@ -0,0 +1,142 @@
+# Changelog
+
+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.4.0] - 2026-09-08
+
+### Changed
+
+- `Letsdo::CLI::Builder` extracted from `CLI` — all component assembly
+  (agent, provider, loop, TUI setup) now lives in Builder; `CLI` keeps only
+  argv parsing and delegates to Builder. The former `CLILaunch` module is
+  deleted. New `test/cli_builder_test.rb` covers Builder assembly and TUI
+  detection. Zero behavioral change.
+- The gemspec now has a user-facing description (what letsdo does and why)
+  instead of an internal class inventory; `required_ruby_version` is
+  narrowed from `>= 3.0` to `>= 3.3` to match what CI actually tests
+  (Ruby 3.0–3.2 are end-of-life); `bug_tracker_uri` and `documentation_uri`
+  metadata are added; and `spec.files` ships `CHANGELOG.md` and the gemspec
+  itself alongside the code, README and LICENSE.
+
+### Fixed
+
+- The documented Ruby 4.0.x install workaround now leads with fixing the
+  environment (`gem install rbs -v '>= 4.0.0'`), with `--no-document` as a
+  fallback — the rbs upgrade actually makes the plain `gem install letsdo`
+  post-install RDoc hook succeed instead of just skipping it. The CI
+  "Verify install" step now installs the built gem without `--no-document`,
+  repairs a broken rdoc/rbs pair when `require "rdoc"` fails, runs on Ruby
+  4.0 as well as 3.3, and checks `letsdo --version` — so the exact plain
+  install path a user runs (including the RDoc hook) is guarded against the
+  rdoc/rbs conflict crashing it again.
+
+## [0.3.0] - 2026-09-07
+
+### Added
+
+- `Letsdo::Watcher` — OS file-change watching of the backlog folder via
+  inotify (Linux, through Fiddle with no external gem) with a self-pipe
+  polling fallback; the orchestrator loop now wakes on a backlog change
+  instead of waiting out the full `LETSDO_WAIT_SECONDS` interval. The wake
+  replaces the idle-phase wait only — the startup check and the re-check
+  after each finished task stay immediate provider queries.
+
+### Fixed
+
+- An explicitly injected control/stop sleeper is honored over the watcher
+  idle path, so a CLI test that injects a sleeper completes normally even
+  with the loop watcher enabled — `rake test` no longer hangs in an infinite
+  idle wait.
+- `Letsdo::Capture` runs its child in its own process group and terminates
+  the whole group when the capture is interrupted, so a stopped capture can
+  no longer leave an orphaned grandchild holding the stdout/stderr pipes.
+- Quitting the TUI no longer leaves the terminal in raw mode: raw-mode entry
+  moved to the main thread, so the saved termios (echo + canonical line
+  editing) is restored on every quit path — the shell in a tmux pane stays
+  usable.
+- A tool-only agent run after a text run no longer writes a spurious blank
+  line on stdout (`OutputStreamer#finish` resets its last-char state).
+- `require "letsdo"` no longer eagerly loads `tty-cursor` (or any tty-* gem),
+  so `rake test` runs on a clean Ruby without the gem installed; the TUI
+  still loads its gems lazily on the interactive path.
+- Documented a Ruby 4.0.x install note: the post-install RDoc hook can crash
+  on a mismatched rdoc/rbs pair — install with `--no-document`.
+
+## [0.2.0] - 2026-09-04
+
+### Added
+
+- `letsdo <name> --init` (and the flag-first form `letsdo --init <name>`)
+  creates `agents/<name>.md` with the starter default prompt
+  (`Letsdo::DefaultPrompt::TEXT`) so the prompt can be customized — the
+  agent is never started. An already existing file or an unsafe name
+  (contains `/` or `\`, or is `.`/`..`) is refused with a message on
+  stderr and exit 1; nothing is ever written outside `agents/`
+  (`Letsdo::PromptStore#create_agent`).
+- Built-in default prompt (`Letsdo::DefaultPrompt::TEXT`): `letsdo <name>`
+  starts the agent even without `agents/<name>.md` — the run falls back to
+  the built-in process-only prompt, and letsdo announces once on stderr
+  the exact path checked (`<root>/agents/<name>.md`) plus the
+  `letsdo <name> --init` placement hint. `UnknownAgentError` is removed:
+  with the fallback there are no unknown agents, the base `Letsdo::Error`
+  remains the package error surface.
+- Real pause semantics for the TUI 'p' key: mid-run the pi group is
+  suspended at the kernel level (SIGSTOP via `Letsdo::PiRunner#pause`,
+  resume via SIGCONT); between runs a shared `Letsdo::Control::PauseGate`
+  holds new runs until resume. The footer flips between `p pause` and
+  `p resume`.
+- `SIGHUP` (terminal closed) stops the loop the same way as `SIGINT`/
+  `SIGTERM`.
+- Prompt stop of a paused pi: `PiRunner#terminate` now reaps the child
+  during its grace wait (WNOHANG) instead of polling the process table,
+  so a signal-killed child's zombie state can no longer stall the stop
+  for the full grace period.
+- Gemspec metadata: `homepage`, `homepage_uri`, `source_code_uri`,
+  `changelog_uri`, `allowed_push_host`.
+- `CHANGELOG.md`.
+- Default RuboCop 1.77 as a development dependency; CI fails the build
+  on style violations.
+
+### Changed
+
+- Tool result bodies (indented stdout/stderr blocks, truncation notes,
+  `✖ Error:` markers) are no longer printed to the aux output; the stream
+  shows only tool invocations (`HH:MM:SS ⚙ name: args`) and a one-line
+  completion with duration (`✓/✖ name: done/error (Ns)`).
+- `Session#quit` sets the stop flag before raising `Letsdo::Stopped`, so
+  the input thread renders no frames during teardown.
+
+### Fixed
+
+- `rake test` no longer prints `Open3.capture3` reader-thread dumps
+  (`IOError: stream closed in another thread`): `Letsdo::BacklogTasks` now
+  captures the backlog CLI output through `Letsdo::Capture`, whose reader
+  threads tolerate the pipes being closed when a stop (TUI quit, signal)
+  interrupts an in-flight backlog call and whose cleanup reaps the child
+  even then.
+- CLI tests no longer collide on a shared `/tmp` “tasks already served”
+  marker after Minitest reseeds `Kernel.srand` per test class.
+
+## [0.1.0] - 2026-09-04
+
+### Added
+
+- Initial release of letsdo — a local agent worker for Backlog.md/markdown tasks.
+- OOP structure: `Letsdo::PromptStore` (agents/), `Letsdo::OutputStreamer` and
+  `Letsdo::PiRunner` (pi --mode json), `Letsdo::Agent` (one run), `Letsdo::Loop`
+  (orchestrator loop), `Letsdo::CLI`.
+- Interactive TUI (header metrics, scrollable stream) in TTY mode; plain
+  line-stream mode for pipes/CI/tests.
+- 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
+[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
+[0.1.0]: https://github.com/sergio-fry/letsdo/releases/tag/v0.1.0

data/README.md

@@ -80,7 +80,7 @@ generation, any repeatable task flow you can express as assignee + prompt.
 
 ## Requirements
 
-- Ruby **>= 3.0**.
+- Ruby **>= 3.3**.
 - 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`.
@@ -105,9 +105,10 @@ gem install letsdo-0.3.0.gem
 > **Ruby 4.0.x note.** Some Ruby 4.0.x builds ship default gems out of sync —
 > rdoc 8.0.0 declares `rbs >= 4.0.0` while rbs 3.x is bundled — so the
 > post-install RDoc hook can raise `Gem::ConflictError` even though the gem
-> files are already installed. Install without documentation to skip the
-> hook (`gem install letsdo-0.3.0.gem --no-document`), or install a matching
-> rbs first (`gem install rbs -v '>= 4.0.0'`).
+> files are already installed. Fix the environment by installing a matching
+> rbs first (`gem install rbs -v '>= 4.0.0'`); if that is not possible,
+> install the gem without documentation to skip the hook
+> (`gem install letsdo-0.3.0.gem --no-document`).
 
 or run it straight from the checkout without installing:
 
@@ -257,7 +258,7 @@ 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"`).
+Ruby 3.3 and 4.0 (satisfies `required_ruby_version: ">= 3.3"`).
 
 ## Alternatives
 

data/letsdo.gemspec

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "lib/letsdo/version"
+
+Gem::Specification.new do |spec|
+  spec.name    = "letsdo"
+  spec.version = Letsdo::VERSION
+  spec.authors = ["Sergei O. Udalov"]
+  spec.email   = ["udalov.x@mail.ru"]
+
+  spec.summary     = "A local agent worker for Backlog.md/markdown tasks"
+  spec.description = "letsdo turns a plain markdown backlog into a team of " \
+                     "autonomous local agents. Each agent is just a prompt " \
+                     "file in agents/; run `letsdo <name>` and it works " \
+                     "through every open task assigned to that agent, one " \
+                     "task per run, and stops cleanly on Ctrl+C. No " \
+                     "framework, no hosted platform — the backlog folder is " \
+                     "the single source of truth and task data never leaves " \
+                     "your machine."
+  spec.license = "MIT"
+
+  # Supported Ruby floor matches what CI actually tests (3.3 and 4.0).
+  # Ruby 3.0/3.1/3.2 are end-of-life, so claiming support for them while
+  # never testing them would be dishonest packaging.
+  spec.required_ruby_version = ">= 3.3"
+
+  # Runtime dependencies: the interactive TUI. Required lazily inside the
+  # tui classes so the plain line-stream mode (pipes/CI/tests) works with
+  # zero extra gems.
+  spec.add_runtime_dependency "tty-screen", "~> 0.8"
+  spec.add_runtime_dependency "tty-cursor", "~> 0.7"
+  spec.add_runtime_dependency "tty-reader", "~> 0.9"
+  spec.add_runtime_dependency "unicode-display_width", ">= 2.0"
+
+  # Development dependency: style checks (default RuboCop config, enforced
+  # in CI). Not installed by the CI workflow via bundler — the workflow
+  # installs the same constraint with `gem install` on a clean Ruby.
+  spec.add_development_dependency "rubocop", "~> 1.77.0"
+
+  # The AI backend is the external `pi` CLI (default, overridable via
+  # LETSDO_PI_COMMAND) — a runtime *requirement*, not a rubygem, so it is
+  # documented in the README rather than declared as a dependency.
+  spec.files         = Dir["lib/**/*.rb", "README.md", "LICENSE",
+                           "CHANGELOG.md", "letsdo.gemspec"]
+  spec.bindir        = "bin"
+  spec.executables   = ["letsdo"]
+  spec.require_paths = ["lib"]
+
+  spec.homepage = "https://github.com/sergio-fry/letsdo"
+
+  # source_code_uri shares the homepage URL on purpose (the source *is* the
+  # project home); homepage_uri is deliberately not duplicated in metadata
+  # because an identical homepage_uri + source_code_uri pair makes
+  # `gem build` warn.
+  spec.metadata["source_code_uri"]       = "https://github.com/sergio-fry/letsdo"
+  spec.metadata["bug_tracker_uri"]       = "https://github.com/sergio-fry/letsdo/issues"
+  spec.metadata["changelog_uri"]         = "https://github.com/sergio-fry/letsdo/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"]     = "https://github.com/sergio-fry/letsdo/blob/main/README.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+  spec.metadata["allowed_push_host"]     = "https://rubygems.org"
+end

data/lib/letsdo/agent_loop.rb

@@ -56,7 +56,7 @@ module Letsdo
     def assign_control_opts(opts)
       @metrics = opts[:metrics]
       @pause_gate = opts[:pause_gate]
-      @debug = opts[:debug].nil? ? ENV['LETSDO_DEBUG'] == '1' : opts[:debug]
+      @debug = resolve_debug(opts)
       @watcher = opts[:watcher] || (Watcher.new(path: opts[:watch_path]) if opts[:watch_path])
       # Precedence is deliberate: an explicitly injected sleeper always wins
       # over the watcher idle path — tests inject a stop/control sleeper that
@@ -64,6 +64,12 @@ module Letsdo
       @sleeper = opts[:sleeper] || watcher_sleeper || ->(seconds) { sleep(seconds) }
     end
 
+    def resolve_debug(opts)
+      return opts[:debug] unless opts[:debug].nil?
+
+      (opts[:config] || Config.new).debug?
+    end
+
     def watcher_sleeper
       @watcher && ->(seconds) { @watcher.wait(seconds) }
     end

data/lib/letsdo/cli/builder.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Letsdo
+  class CLI
+    # TUI component assembly used by Letsdo::CLI::Builder. Kept in its own
+    # module so Builder stays within the class-length limit; mirrors the
+    # CLILaunch/CLIInit split pattern.
+    module BuilderTui
+      def run_tui(name)
+        ctx = tui_context(name)
+        session = Tui::Session.new(**ctx[:session])
+        session.run { ctx[:loop].run }
+      end
+
+      def tui_context(name)
+        parts = tui_parts(name)
+        {
+          loop: tui_loop(name, parts),
+          session: tui_session_args(name, **parts)
+        }
+      end
+
+      def tui_parts(name)
+        clock = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        handle = assignee_handle(name)
+        log = Tui::LogBuffer.new
+        {
+          clock: clock, handle: handle, log: log,
+          metrics: tui_metrics(name, handle, clock, log),
+          agent: agent_for(name, OutputStreamer.new(log: log)),
+          provider: provider_for(handle),
+          pause_gate: Control::PauseGate.new
+        }
+      end
+
+      def tui_loop(name, parts)
+        agent_loop(name, nil, agent: parts[:agent], provider: parts[:provider],
+                              handle: parts[:handle], stderr: parts[:log],
+                              metrics: parts[:metrics], pause_gate: parts[:pause_gate])
+      end
+
+      def tui_metrics(name, handle, clock, log)
+        Tui::Metrics.new(name: name, handle: handle, clock: clock,
+                         on_run_start: ->(_label) { log.divider })
+      end
+
+      def tui_session_args(name, **parts)
+        {
+          name: name, handle: parts[:handle], log: parts[:log], metrics: parts[:metrics],
+          terminal: Tui::Terminal.new(stream: @stdout),
+          input: Tui::Input.new(stdin: @stdin),
+          refresh: -> { parts[:provider].call },
+          wait_seconds: wait_seconds, clock: parts[:clock],
+          pause_gate: parts[:pause_gate], runner: -> { parts[:agent].runner }
+        }
+      end
+    end
+
+    # Owns all component assembly for running an agent (TASK-54): builds the
+    # streamer, agent, backlog provider, orchestrator loop and the whole TUI,
+    # and decides plain vs TUI mode via stdout/stdin TTY + TERM. Parsing stays
+    # in Letsdo::CLI (TASK-54); this class is the wiring half — independently
+    # testable and free to grow with provider/backend selection (TASK-51/52)
+    # without bloating the parser.
+    class Builder
+      include BuilderTui
+
+      def initialize(env:, stdout:, stderr:, stdin: $stdin, sleeper: nil)
+        @env = env
+        @stdout = stdout
+        @stderr = stderr
+        @stdin = stdin
+        @sleeper = sleeper
+        @config = Config.new(env: env)
+        @root = @config.root
+      end
+
+      # Runs <name> in plain or TUI mode; returns the process exit code.
+      def run(name)
+        store = PromptStore.new(root: @root)
+        announce_default_prompt(name, store) if store.read(name).nil?
+        tui? ? run_tui(name) : run_plain(name)
+      end
+
+      private
+
+      def run_plain(name)
+        streamer = OutputStreamer.new(stdout: @stdout, stderr: @stderr)
+        agent_loop(name, streamer, stderr: @stderr).run
+      end
+
+      def agent_for(name, streamer)
+        Agent.new(name: name, root: @root, flags: parse_pi_flags, streamer: streamer,
+                  command: pi_command)
+      end
+
+      def provider_for(handle)
+        BacklogTasks.new(handle: handle, command: backlog_command, cwd: @root,
+                         env: ENV.to_h.merge(@env))
+      end
+
+      def agent_loop(name, streamer, **opts)
+        handle = opts[:handle] || assignee_handle(name)
+        agent = opts[:agent] || agent_for(name, streamer)
+        provider = opts[:provider] || provider_for(handle)
+        AgentLoop.new(name: name, handle: handle, agent: agent,
+                      task_provider: -> { provider.call },
+                      wait_seconds: wait_seconds, sleeper: @sleeper, stderr: opts[:stderr],
+                      metrics: opts[:metrics], pause_gate: opts[:pause_gate],
+                      watcher: backlog_watcher)
+      end
+
+      def backlog_watcher
+        Watcher.new(path: File.join(@root, 'backlog'), poll_seconds: wait_seconds)
+      end
+
+      # One-time fallback notification (before the first loop message): names
+      # the exact path checked and the placement hint. The agent still starts
+      # — Letsdo::Agent falls back to the built-in default prompt itself.
+      def announce_default_prompt(name, store)
+        @stderr.puts("letsdo: no prompt for #{name} at #{store.agent_path(name)}")
+        @stderr.puts("letsdo: using the built-in default prompt (create a prompt file with 'letsdo #{name} --init')")
+      end
+
+      def tui?
+        @stdout.tty? && @stdin.tty? && @env['TERM'].to_s != 'dumb'
+      end
+
+      def assignee_handle(name)
+        @config.assignee_handle(name)
+      end
+
+      def backlog_command
+        @config.backlog_command
+      end
+
+      def wait_seconds
+        @config.wait_seconds
+      end
+
+      def pi_command
+        @config.pi_command
+      end
+
+      def parse_pi_flags
+        @config.pi_flags
+      end
+    end
+  end
+end

data/lib/letsdo/cli.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-require 'shellwords'
-require_relative 'cli/launch'
 require_relative 'cli/init'
+require_relative 'cli/builder'
 
 module Letsdo
   # Command-line argument parsing and running an agent orchestrator loop.
@@ -21,12 +20,10 @@ module Letsdo
   #   letsdo --init <name>         — same, flag-first form;
   #   letsdo <unknown option>      — "letsdo: unknown option: X" + usage, exit 1.
   class CLI
-    include CLILaunch
     include CLIInit
 
     USAGE = 'Usage: letsdo <agent_name>'
     AGENTS_HEADER = 'Available agents:'
-    DEFAULT_WAIT_SECONDS = 10.0
 
     def self.run(argv, **opts)
       new(env: opts.fetch(:env, ENV), stdout: opts.fetch(:stdout, $stdout),
@@ -35,12 +32,11 @@ module Letsdo
     end
 
     def initialize(env:, stdout:, stderr:, stdin: $stdin, sleeper: nil)
-      @env = env
       @stdout = stdout
       @stderr = stderr
-      @stdin = stdin
-      @sleeper = sleeper
-      @root = env.fetch('LETSDO_ROOT', Dir.pwd)
+      @root = Config.new(env: env).root
+      @builder = Builder.new(env: env, stdout: stdout, stderr: stderr,
+                             stdin: stdin, sleeper: sleeper)
     end
 
     def run(argv)
@@ -51,7 +47,7 @@ module Letsdo
       return init_command(argv) if argv.include?('--init')
       return unknown_option(arg) if arg.start_with?('-')
 
-      run_agent(arg)
+      @builder.run(arg)
     end
 
     private
@@ -85,47 +81,6 @@ module Letsdo
       1
     end
 
-    def run_agent(name)
-      store = PromptStore.new(root: @root)
-      announce_default_prompt(name, store) if store.read(name).nil?
-      tui? ? run_agent_tui(name) : run_agent_plain(name)
-    end
-
-    # One-time fallback notification (before the first loop message): names
-    # the exact path checked and the placement hint. The agent still starts
-    # — Letsdo::Agent falls back to the built-in default prompt itself.
-    def announce_default_prompt(name, store)
-      @stderr.puts("letsdo: no prompt for #{name} at #{store.agent_path(name)}")
-      @stderr.puts("letsdo: using the built-in default prompt (create a prompt file with 'letsdo #{name} --init')")
-    end
-
-    def tui?
-      @stdout.tty? && @stdin.tty? && @env['TERM'].to_s != 'dumb'
-    end
-
-    def assignee_handle(name)
-      env_handle = @env['AGENT_ASSIGNEE_HANDLE']
-      env_handle && !env_handle.strip.empty? ? env_handle : "@#{name}"
-    end
-
-    def backlog_command
-      @env.fetch('LETSDO_BACKLOG_COMMAND', 'backlog')
-    end
-
-    def wait_seconds
-      value = @env['LETSDO_WAIT_SECONDS'].to_s.strip
-      value = @env['AGENT_WAIT_SECONDS'].to_s.strip if value.empty?
-      return DEFAULT_WAIT_SECONDS if value.empty?
-
-      Float(value)
-    rescue ArgumentError, TypeError
-      DEFAULT_WAIT_SECONDS
-    end
-
-    def pi_command
-      @env.fetch('LETSDO_PI_COMMAND', PiRunner::COMMAND)
-    end
-
     def print_usage(stream)
       stream.puts(USAGE)
       print_agents
@@ -135,13 +90,5 @@ module Letsdo
       @stdout.puts(AGENTS_HEADER)
       PromptStore.new(root: @root).list.each { |name| @stdout.puts("  #{name}") }
     end
-
-    def parse_pi_flags
-      value = @env['LETSDO_PI_FLAGS'].to_s
-      value = @env['AGENT_PI_FLAGS'].to_s if value.strip.empty?
-      return [] if value.strip.empty?
-
-      Shellwords.split(value)
-    end
   end
 end

data/lib/letsdo/config.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module Letsdo
+  # The single place where every LETSDO_*/AGENT_* environment variable is
+  # read, with exactly the defaults and precedence the CLI, PiRunner and
+  # AgentLoop used to apply inline. Giving env policy one home makes it
+  # testable in one place and gives future knobs (provider/backend
+  # selection) a single spot to add a variable.
+  #
+  # The env hash is injectable for tests and defaults to the process ENV.
+  class Config
+    DEFAULT_WAIT_SECONDS = 10.0
+    DEFAULT_PI_COMMAND = 'pi'
+    DEFAULT_BACKLOG_COMMAND = 'backlog'
+
+    def initialize(env: ENV)
+      @env = env
+    end
+
+    # Project root with agents/ (and where the backlog CLI finds backlog/).
+    def root
+      @env.fetch('LETSDO_ROOT', Dir.pwd)
+    end
+
+    # Extra pi flags, split on whitespace. LETSDO_PI_FLAGS wins; when empty,
+    # AGENT_PI_FLAGS is the fallback (bin/agent-loop compatibility).
+    def pi_flags
+      value = @env['LETSDO_PI_FLAGS'].to_s
+      value = @env['AGENT_PI_FLAGS'].to_s if value.strip.empty?
+      return [] if value.strip.empty?
+
+      Shellwords.split(value)
+    end
+
+    # The agent's backlog assignee handle. Default: @<name> (handle = name);
+    # a blank override also falls back to the derived handle.
+    def assignee_handle(name)
+      handle = @env['AGENT_ASSIGNEE_HANDLE']
+      handle && !handle.strip.empty? ? handle : "@#{name}"
+    end
+
+    # Retry interval when no tasks are open. LETSDO_WAIT_SECONDS wins, then
+    # AGENT_WAIT_SECONDS; an invalid value falls back to the default.
+    def wait_seconds
+      value = @env['LETSDO_WAIT_SECONDS'].to_s.strip
+      value = @env['AGENT_WAIT_SECONDS'].to_s.strip if value.empty?
+      return DEFAULT_WAIT_SECONDS if value.empty?
+
+      Float(value)
+    rescue ArgumentError, TypeError
+      DEFAULT_WAIT_SECONDS
+    end
+
+    # The pi command used to run agents (same literal as PiRunner::COMMAND).
+    def pi_command
+      @env.fetch('LETSDO_PI_COMMAND', DEFAULT_PI_COMMAND)
+    end
+
+    # The Backlog.md CLI used as the task provider.
+    def backlog_command
+      @env.fetch('LETSDO_BACKLOG_COMMAND', DEFAULT_BACKLOG_COMMAND)
+    end
+
+    # Whether [letsdo] traces are enabled in PiRunner and AgentLoop.
+    def debug?
+      @env['LETSDO_DEBUG'] == '1'
+    end
+  end
+end

data/lib/letsdo/pi_runner.rb

@@ -30,7 +30,7 @@ module Letsdo
       @command = opts.fetch(:command, COMMAND)
       @pending_tools = {}
       @reaped_status = nil
-      @debug = opts[:debug].nil? ? ENV['LETSDO_DEBUG'] == '1' : opts[:debug]
+      @debug = opts[:debug].nil? ? (opts[:config] || Config.new).debug? : opts[:debug]
     end
 
     def run

data/lib/letsdo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Letsdo
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

data/lib/letsdo.rb

@@ -22,6 +22,7 @@
 
 require_relative 'letsdo/version'
 require_relative 'letsdo/errors'
+require_relative 'letsdo/config'
 require_relative 'letsdo/prompt_store'
 require_relative 'letsdo/default_prompt'
 require_relative 'letsdo/output_streamer'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: letsdo
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Sergei O. Udalov
@@ -79,10 +79,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.77.0
-description: 'letsdo — a local agent worker for Backlog.md/markdown tasks. OOP structure:
-  Letsdo::PromptStore (agents/), Letsdo::OutputStreamer and Letsdo::PiRunner (pi --mode
-  json), Letsdo::Agent (one run), Letsdo::Loop (orchestrator loop), Letsdo::CLI. Minitest
-  tests. Will later be split into a separate repository.'
+description: letsdo turns a plain markdown backlog into a team of autonomous local
+  agents. Each agent is just a prompt file in agents/; run `letsdo <name>` and it
+  works through every open task assigned to that agent, one task per run, and stops
+  cleanly on Ctrl+C. No framework, no hosted platform — the backlog folder is the
+  single source of truth and task data never leaves your machine.
 email:
 - udalov.x@mail.ru
 executables:
@@ -90,9 +91,11 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - bin/letsdo
+- letsdo.gemspec
 - lib/letsdo.rb
 - lib/letsdo/agent.rb
 - lib/letsdo/agent_loop.rb
@@ -100,8 +103,9 @@ files:
 - lib/letsdo/backlog_tasks.rb
 - lib/letsdo/capture.rb
 - lib/letsdo/cli.rb
+- lib/letsdo/cli/builder.rb
 - lib/letsdo/cli/init.rb
-- lib/letsdo/cli/launch.rb
+- lib/letsdo/config.rb
 - lib/letsdo/control.rb
 - lib/letsdo/default_prompt.rb
 - lib/letsdo/errors.rb
@@ -127,9 +131,10 @@ homepage: https://github.com/sergio-fry/letsdo
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/sergio-fry/letsdo
   source_code_uri: https://github.com/sergio-fry/letsdo
+  bug_tracker_uri: https://github.com/sergio-fry/letsdo/issues
   changelog_uri: https://github.com/sergio-fry/letsdo/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/sergio-fry/letsdo/blob/main/README.md
   rubygems_mfa_required: 'true'
   allowed_push_host: https://rubygems.org
 rdoc_options: []
@@ -139,7 +144,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/letsdo/cli/launch.rb

@@ -1,87 +0,0 @@
-# frozen_string_literal: true
-
-module Letsdo
-  # Builds the agent, provider, and orchestrator loop for CLI run paths.
-  module CLILaunch
-    private
-
-    def run_agent_plain(name)
-      streamer = OutputStreamer.new(stdout: @stdout, stderr: @stderr)
-      agent_loop(name, streamer, stderr: @stderr).run
-    end
-
-    def run_agent_tui(name)
-      ctx = tui_context(name)
-      session = Tui::Session.new(**ctx[:session])
-      session.run { ctx[:loop].run }
-    end
-
-    def tui_context(name)
-      parts = tui_parts(name)
-      {
-        loop: tui_loop(name, parts),
-        session: tui_session_args(name, **parts)
-      }
-    end
-
-    def tui_parts(name)
-      clock = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
-      handle = assignee_handle(name)
-      log = Tui::LogBuffer.new
-      {
-        clock: clock, handle: handle, log: log,
-        metrics: tui_metrics(name, handle, clock, log),
-        agent: agent_for(name, OutputStreamer.new(log: log)),
-        provider: provider_for(handle),
-        pause_gate: Control::PauseGate.new
-      }
-    end
-
-    def tui_loop(name, parts)
-      agent_loop(name, nil, agent: parts[:agent], provider: parts[:provider],
-                            handle: parts[:handle], stderr: parts[:log],
-                            metrics: parts[:metrics], pause_gate: parts[:pause_gate])
-    end
-
-    def tui_metrics(name, handle, clock, log)
-      Tui::Metrics.new(name: name, handle: handle, clock: clock,
-                       on_run_start: ->(_label) { log.divider })
-    end
-
-    def tui_session_args(name, **parts)
-      {
-        name: name, handle: parts[:handle], log: parts[:log], metrics: parts[:metrics],
-        terminal: Tui::Terminal.new(stream: @stdout),
-        input: Tui::Input.new(stdin: @stdin),
-        refresh: -> { parts[:provider].call },
-        wait_seconds: wait_seconds, clock: parts[:clock],
-        pause_gate: parts[:pause_gate], runner: -> { parts[:agent].runner }
-      }
-    end
-
-    def agent_for(name, streamer)
-      Agent.new(name: name, root: @root, flags: parse_pi_flags, streamer: streamer,
-                command: pi_command)
-    end
-
-    def provider_for(handle)
-      BacklogTasks.new(handle: handle, command: backlog_command, cwd: @root,
-                       env: ENV.to_h.merge(@env))
-    end
-
-    def agent_loop(name, streamer, **opts)
-      handle = opts[:handle] || assignee_handle(name)
-      agent = opts[:agent] || agent_for(name, streamer)
-      provider = opts[:provider] || provider_for(handle)
-      AgentLoop.new(name: name, handle: handle, agent: agent,
-                    task_provider: -> { provider.call },
-                    wait_seconds: wait_seconds, sleeper: @sleeper, stderr: opts[:stderr],
-                    metrics: opts[:metrics], pause_gate: opts[:pause_gate],
-                    watcher: backlog_watcher)
-    end
-
-    def backlog_watcher
-      Watcher.new(path: File.join(@root, 'backlog'), poll_seconds: wait_seconds)
-    end
-  end
-end