lemming-cli 0.3.3__tar.gz → 0.4.0__tar.gz

{lemming_cli-0.3.3 → lemming_cli-0.4.0}/.gitignore

@@ -5,6 +5,7 @@ dist/
 build/
 *.egg-info/
 tasks.yml
+tasks.yml.corrupt*
 *.swp
 node_modules/
 .biome/

{lemming_cli-0.3.3 → lemming_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: lemming-cli
-Version: 0.3.3
+Version: 0.4.0
 Summary: An autonomous, iterative task runner for AI coding agents.
 Project-URL: Homepage, https://github.com/owahltinez/lemming
 Project-URL: Repository, https://github.com/owahltinez/lemming
@@ -15,7 +15,7 @@ Requires-Dist: fastapi>=0.124.4
 Requires-Dist: markdownify>=0.14.1
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: pyyaml>=6.0.3
-Requires-Dist: readability-cli>=0.5.0
+Requires-Dist: readability-cli>=0.7.0
 Requires-Dist: requests>=2.32.3
 Requires-Dist: uvicorn>=0.33.0
 Description-Content-Type: text/markdown
@@ -102,6 +102,71 @@ lemming run -- --model claude-3-5-sonnet
 
 ---
 
+## One-Off Tasks Without a Roadmap
+
+`lemming exec` runs a single task and exits. It is the same agent-CLI
+normalization the orchestrator uses, addressable on its own: name a task and a
+runner, and the agent's closing message comes back on stdout.
+
+```bash
+# Delegate one task to a different agent, e.g. to spare another's quota
+lemming exec "Fix the flaky test in runner_test.py" --runner codex
+
+# Pipe a longer handoff instead of fighting shell quoting
+cat handoff.md | lemming exec -f - --runner agy
+```
+
+With no description there is nothing for a task runner to do, so only the
+reviews run — against work that already exists.
+
+```bash
+# Review uncommitted work before opening a pull request
+lemming exec --review readability
+
+# Review someone else's branch, checked out in a worktree
+lemming exec -C ../review-worktree --review testing --scope main...HEAD
+
+# Do the work, then gate it
+lemming exec "Add pagination to the tasks API" --review all
+```
+
+`--scope` takes paths, which pass through untouched, or a git revision range,
+which is resolved to the files it changed. It defaults to uncommitted work, or
+to the whole tree outside a git repository.
+
+Each run is self-contained: nothing is read from the project's roadmap or its
+local hooks, one agent run is attempted, and the run's state directory is
+removed unless it failed — in which case it is kept, and its path printed, so
+the log can be read. Kept directories live in `~/.local/lemming/exec-*` and
+are retired automatically a week later, so a recent failure is always still
+there to inspect. Stdout carries the agent's message alone and everything
+else goes to stderr, so the output can be consumed directly.
+
+Note that the agent runs unattended (`--yolo` by default), so it does not
+inherit the permission prompts of whatever launched it.
+
+### Teaching Your Agent to Use It
+
+Lemming ships an Agent Skill so that an agent already running — Claude Code,
+Gemini CLI, Cursor — can reach any other agent CLI without knowing how each
+one spells its flags. Install it once:
+
+```bash
+# Cross-tool location (~/.agents/skills), and report any tool-specific ones
+lemming skill install
+
+# Cover every agent tool detected on this machine
+lemming skill install --all
+
+# This repository only
+lemming skill install --to .agents/skills
+```
+
+`lemming skill uninstall` reverses it. Both refuse to touch a directory that
+does not hold this skill, so a mistyped `--to` fails instead of deleting work.
+
+---
+
 ## The Web Dashboard
 
 Lemming includes a modern, fast Web UI to monitor your projects.
@@ -244,16 +309,36 @@ See [docs/EVALS.md](docs/EVALS.md) for details.
 
 ## Command Reference
 
+### Global Options
+
+These come before the subcommand and apply to all of them.
+
+- **`-C, --project-dir <dir>`**: Run as if invoked from `<dir>`, addressing
+  that project's roadmap. Relative paths in other options resolve against it.
+  See [Working across projects](#working-across-projects).
+- **`--tasks-file <path>`**: Point at a specific tasks file instead of the one
+  derived from the current directory.
+- **`-v, --verbose`**: Show verbose output.
+
 ### Roadmap Management
 
 - **`status [<id>]`**: Queue/history overview or deep-dive into a specific
-  task, including supersession lineage and runner/orchestrator-hook execution
-  times. Superseded and failed history stays visible in the default overview;
-  `--verbose` also shows routine completed/cancelled history.
+  task, including supersession lineage, the last resolved runner command, and
+  runner/orchestrator-hook execution times. Superseded and failed history
+  stays visible in the default overview; `--verbose` also shows routine
+  completed/cancelled history.
+  - `--json`: Emit machine-readable JSON instead of formatted text, so
+    scripts never have to parse the internal state file.
+  - `--brief`: Omit task descriptions, which otherwise dominate the output.
 - **`goal [<text>]`**: Set or view the long-term goal shared by all tasks.
   Supports `-f/--file`.
-- **`add <desc>`**: Append a new task. Supports `--index` and `--runner`.
-- **`edit <id>`**: Modify a task's description, runner, or position.
+- **`add <desc>`**: Append a new task. Supports `--index`, `--runner`, and
+  `--model`.
+- **`edit <id>`**: Modify a task's description, runner, model, or position.
+- **`brief <id> [text]`**: View or set a task's long-form brief. Unlike the
+  description it has no length cap, and it is appended to the runner prompt
+  automatically — the right home for measured timings, exact failing
+  selectors, or why a previous attempt was wrong. Supports `-f/--file`.
 - **`delete <id>`**: Remove an unstarted task while retaining its runner log.
   Tasks with execution history require `--force`; autonomous restructuring
   should use `supersede`. Supports `--all` and `--completed` for bulk cleanup,
@@ -265,9 +350,11 @@ See [docs/EVALS.md](docs/EVALS.md) for details.
   - `add <id> <finding>`: Record a new technical detail.
   - `edit <id> <index> <text>`: Modify an existing progress entry.
   - `delete <id> <index>`: Remove a progress entry.
-- **`config`**: Manage project configuration (runner, retries).
+- **`config`**: Manage project configuration (runner, model, retries,
+  time limit).
   - `list`: View current configuration.
-  - `set <key> <value>`: Update a setting.
+  - `set <key> <value>`: Update a setting. `set model default` clears a
+    pinned model without touching the runner.
 - **`hooks`**: Manage orchestrator hooks.
   - `list`: View available and active hooks.
   - `install`: Install built-in hooks to the global directory.
@@ -295,6 +382,7 @@ See [docs/EVALS.md](docs/EVALS.md) for details.
 - **`logs [<id>]`**: Print a task's execution log to stdout, including retained
   logs for removed tasks. If no ID is provided, it defaults to the active or
   most recent task. Orchestrator hook output is automatically appended.
+  Supports `--json` to wrap the log with its task ID and path.
 
 ### Execution
 
@@ -303,7 +391,39 @@ See [docs/EVALS.md](docs/EVALS.md) for details.
   - `--yolo`: Run the runner in auto-approve mode (default: True).
   - `--env`: Set environment variables for the runner (e.g., `--env KEY=VALUE`).
   - `--no-defaults`: Skip default flag injection for known runners.
-  - `--`: Use `--` to pass any flag directly to the underlying runner.
+  - `--`: Use `--` to pass any flag directly to the underlying runner. A
+    per-task `--runner`/`--model` overrides anything passed here.
+- **`exec [<description>]`**: Run one task, or one set of reviews, outside any
+  roadmap. Prints the agent's closing message to stdout and everything else to
+  stderr. Exits non-zero if the task did not complete. See
+  [One-off tasks](#one-off-tasks-without-a-roadmap).
+  - `-f/--file`: Read the description from a file, or `-` for stdin. Unlike
+    `add`, there is no length cap.
+  - `--review <names>`: Reviews to run after the task, comma-separated or
+    repeated; `all` selects every one. With no description, only the reviews
+    run. Hooks that revise the roadmap cannot be selected.
+  - `--scope <path|range>`: What the reviews look at. Paths pass through; a
+    git revision range is resolved to the files it changed. Defaults to
+    uncommitted work, or the whole tree outside a repository.
+  - `--runner`, `--model`: Which agent CLI and model to use.
+  - `--time-limit`: Minutes before the agent is killed (default 60, 0 for no
+    limit).
+  - `--yolo/--no-yolo`: Run the agent unattended (default: True).
+  - `--keep`: Keep the run's state directory even when it succeeds.
+- **`skill install`**: Install the packaged Agent Skill so agents discover
+  Lemming. Writes to `~/.agents/skills` by default and names any tool-specific
+  directories it found.
+  - `--to <dir>`: Install into a specific skills directory.
+  - `--all`: Also cover every detected tool's own skills directory.
+  - `--link`: Symlink instead of copying, so upgrades take effect immediately.
+  - `--force`: Replace an existing installation of this skill.
+  - `--dry-run`: Print what would happen, refusals included.
+- **`skill uninstall`**: Remove it again. Same `--to`, `--all`, and
+  `--dry-run`.
+- **`stop`**: Stop the running loop and its runner.
+  - `--after-current-task`: Drain instead — let the running task finish, then
+    stop before claiming another. This is the safe way to change the runner
+    or model without stranding work in flight.
 - **`serve`**: Launch the interactive Web UI.
   - `--port`: The port to bind the server to (default: 8999).
   - `--host`: The host address to bind the server to (default: 127.0.0.1).
@@ -314,6 +434,36 @@ See [docs/EVALS.md](docs/EVALS.md) for details.
 
 ---
 
+## Working across projects
+
+When work on one project turns up something that belongs to another — a bug in
+a dependency you also maintain, a doc fix in a sibling repo — file it directly
+on that project's roadmap with `-C` instead of routing it through an external
+issue tracker:
+
+```bash
+# From inside project A, queue work on project B
+lemming -C ~/src/other-project add "check --fix drops the trailing newline"
+
+# Attach the evidence; the brief has no length cap
+lemming -C ~/src/other-project brief <id> --file repro.md
+
+# Read the other project's roadmap without leaving yours
+lemming -C ~/src/other-project status
+```
+
+`-C` works whether or not the target keeps a `tasks.yml` in its repo, so you
+never have to know where its isolated state lives. Because it changes the
+working directory, everything else follows too: the target's `.env`, its
+`.lemming/hooks`, and the directory the runner executes in.
+
+When an agent files a task this way from inside a `lemming run`, the new task
+records the task it came from via `parent` and `parent_tasks_file`. The
+downstream runner then sees a **Parent Task Context** section in its prompt
+describing why the work was requested, so the report doesn't lose its origin.
+
+---
+
 ## Advanced: Runner Customization
 
 Lemming uses **fuzzy matching** to automatically inject the correct "YOLO"
@@ -326,17 +476,53 @@ Lemming uses **fuzzy matching** to automatically inject the correct "YOLO"
 - **Codex**: Runs non-interactively via `codex exec`, adds `--json`, and, in
   YOLO mode, adds `--dangerously-bypass-approvals-and-sandbox`
 
+### Choosing a model
+
+The model is a first-class setting, separate from the runner, so switching
+provider does not silently discard it:
+
+```bash
+lemming config set model gemini-3.6-flash-high   # project default
+lemming add "Fix the flaky test" --model fast    # just this task
+lemming config set model default                 # let the runner decide
+```
+
+Precedence, highest first: an explicit `--model` inside a runner string, the
+task's `--model`, the project's `config model`, then anything passed after
+`lemming run --`. A per-task setting always wins over the loop-wide
+passthrough — the conflicting global flag is dropped rather than duplicated
+on the command line.
+
+### Runner strings
+
+A runner is not limited to a binary name: any extra arguments in the string
+are appended to the command, which is another way to pin per-task behaviour.
+
+```bash
+lemming add "Try the fast model" --runner "agy --model fast"
+```
+
 You can disable default flag injection with `--no-defaults` (`codex exec`
 remains the Codex execution interface), or use a **template** to fully control
 the command layout:
 
 ```bash
-lemming run --runner "my-tool --input={{prompt}} --json"
+lemming config set runner "my-tool --input={{prompt}} --json"
 ```
 
 When `{{prompt}}` is present in the runner string, Lemming replaces it with the
 prompt text and skips all default flag injection.
 
+### Knowing what actually ran
+
+Each attempt records the command it launched, with the prompt elided, so the
+runner and model behind a finished task stay recoverable:
+
+```bash
+lemming status <id>          # includes "Last Command:"
+lemming status --json        # same data, machine-readable
+```
+
 ---
 
 ## Releasing

{lemming_cli-0.3.3 → lemming_cli-0.4.0}/README.md

@@ -80,6 +80,71 @@ lemming run -- --model claude-3-5-sonnet
 
 ---
 
+## One-Off Tasks Without a Roadmap
+
+`lemming exec` runs a single task and exits. It is the same agent-CLI
+normalization the orchestrator uses, addressable on its own: name a task and a
+runner, and the agent's closing message comes back on stdout.
+
+```bash
+# Delegate one task to a different agent, e.g. to spare another's quota
+lemming exec "Fix the flaky test in runner_test.py" --runner codex
+
+# Pipe a longer handoff instead of fighting shell quoting
+cat handoff.md | lemming exec -f - --runner agy
+```
+
+With no description there is nothing for a task runner to do, so only the
+reviews run — against work that already exists.
+
+```bash
+# Review uncommitted work before opening a pull request
+lemming exec --review readability
+
+# Review someone else's branch, checked out in a worktree
+lemming exec -C ../review-worktree --review testing --scope main...HEAD
+
+# Do the work, then gate it
+lemming exec "Add pagination to the tasks API" --review all
+```
+
+`--scope` takes paths, which pass through untouched, or a git revision range,
+which is resolved to the files it changed. It defaults to uncommitted work, or
+to the whole tree outside a git repository.
+
+Each run is self-contained: nothing is read from the project's roadmap or its
+local hooks, one agent run is attempted, and the run's state directory is
+removed unless it failed — in which case it is kept, and its path printed, so
+the log can be read. Kept directories live in `~/.local/lemming/exec-*` and
+are retired automatically a week later, so a recent failure is always still
+there to inspect. Stdout carries the agent's message alone and everything
+else goes to stderr, so the output can be consumed directly.
+
+Note that the agent runs unattended (`--yolo` by default), so it does not
+inherit the permission prompts of whatever launched it.
+
+### Teaching Your Agent to Use It
+
+Lemming ships an Agent Skill so that an agent already running — Claude Code,
+Gemini CLI, Cursor — can reach any other agent CLI without knowing how each
+one spells its flags. Install it once:
+
+```bash
+# Cross-tool location (~/.agents/skills), and report any tool-specific ones
+lemming skill install
+
+# Cover every agent tool detected on this machine
+lemming skill install --all
+
+# This repository only
+lemming skill install --to .agents/skills
+```
+
+`lemming skill uninstall` reverses it. Both refuse to touch a directory that
+does not hold this skill, so a mistyped `--to` fails instead of deleting work.
+
+---
+
 ## The Web Dashboard
 
 Lemming includes a modern, fast Web UI to monitor your projects.
@@ -222,16 +287,36 @@ See [docs/EVALS.md](docs/EVALS.md) for details.
 
 ## Command Reference
 
+### Global Options
+
+These come before the subcommand and apply to all of them.
+
+- **`-C, --project-dir <dir>`**: Run as if invoked from `<dir>`, addressing
+  that project's roadmap. Relative paths in other options resolve against it.
+  See [Working across projects](#working-across-projects).
+- **`--tasks-file <path>`**: Point at a specific tasks file instead of the one
+  derived from the current directory.
+- **`-v, --verbose`**: Show verbose output.
+
 ### Roadmap Management
 
 - **`status [<id>]`**: Queue/history overview or deep-dive into a specific
-  task, including supersession lineage and runner/orchestrator-hook execution
-  times. Superseded and failed history stays visible in the default overview;
-  `--verbose` also shows routine completed/cancelled history.
+  task, including supersession lineage, the last resolved runner command, and
+  runner/orchestrator-hook execution times. Superseded and failed history
+  stays visible in the default overview; `--verbose` also shows routine
+  completed/cancelled history.
+  - `--json`: Emit machine-readable JSON instead of formatted text, so
+    scripts never have to parse the internal state file.
+  - `--brief`: Omit task descriptions, which otherwise dominate the output.
 - **`goal [<text>]`**: Set or view the long-term goal shared by all tasks.
   Supports `-f/--file`.
-- **`add <desc>`**: Append a new task. Supports `--index` and `--runner`.
-- **`edit <id>`**: Modify a task's description, runner, or position.
+- **`add <desc>`**: Append a new task. Supports `--index`, `--runner`, and
+  `--model`.
+- **`edit <id>`**: Modify a task's description, runner, model, or position.
+- **`brief <id> [text]`**: View or set a task's long-form brief. Unlike the
+  description it has no length cap, and it is appended to the runner prompt
+  automatically — the right home for measured timings, exact failing
+  selectors, or why a previous attempt was wrong. Supports `-f/--file`.
 - **`delete <id>`**: Remove an unstarted task while retaining its runner log.
   Tasks with execution history require `--force`; autonomous restructuring
   should use `supersede`. Supports `--all` and `--completed` for bulk cleanup,
@@ -243,9 +328,11 @@ See [docs/EVALS.md](docs/EVALS.md) for details.
   - `add <id> <finding>`: Record a new technical detail.
   - `edit <id> <index> <text>`: Modify an existing progress entry.
   - `delete <id> <index>`: Remove a progress entry.
-- **`config`**: Manage project configuration (runner, retries).
+- **`config`**: Manage project configuration (runner, model, retries,
+  time limit).
   - `list`: View current configuration.
-  - `set <key> <value>`: Update a setting.
+  - `set <key> <value>`: Update a setting. `set model default` clears a
+    pinned model without touching the runner.
 - **`hooks`**: Manage orchestrator hooks.
   - `list`: View available and active hooks.
   - `install`: Install built-in hooks to the global directory.
@@ -273,6 +360,7 @@ See [docs/EVALS.md](docs/EVALS.md) for details.
 - **`logs [<id>]`**: Print a task's execution log to stdout, including retained
   logs for removed tasks. If no ID is provided, it defaults to the active or
   most recent task. Orchestrator hook output is automatically appended.
+  Supports `--json` to wrap the log with its task ID and path.
 
 ### Execution
 
@@ -281,7 +369,39 @@ See [docs/EVALS.md](docs/EVALS.md) for details.
   - `--yolo`: Run the runner in auto-approve mode (default: True).
   - `--env`: Set environment variables for the runner (e.g., `--env KEY=VALUE`).
   - `--no-defaults`: Skip default flag injection for known runners.
-  - `--`: Use `--` to pass any flag directly to the underlying runner.
+  - `--`: Use `--` to pass any flag directly to the underlying runner. A
+    per-task `--runner`/`--model` overrides anything passed here.
+- **`exec [<description>]`**: Run one task, or one set of reviews, outside any
+  roadmap. Prints the agent's closing message to stdout and everything else to
+  stderr. Exits non-zero if the task did not complete. See
+  [One-off tasks](#one-off-tasks-without-a-roadmap).
+  - `-f/--file`: Read the description from a file, or `-` for stdin. Unlike
+    `add`, there is no length cap.
+  - `--review <names>`: Reviews to run after the task, comma-separated or
+    repeated; `all` selects every one. With no description, only the reviews
+    run. Hooks that revise the roadmap cannot be selected.
+  - `--scope <path|range>`: What the reviews look at. Paths pass through; a
+    git revision range is resolved to the files it changed. Defaults to
+    uncommitted work, or the whole tree outside a repository.
+  - `--runner`, `--model`: Which agent CLI and model to use.
+  - `--time-limit`: Minutes before the agent is killed (default 60, 0 for no
+    limit).
+  - `--yolo/--no-yolo`: Run the agent unattended (default: True).
+  - `--keep`: Keep the run's state directory even when it succeeds.
+- **`skill install`**: Install the packaged Agent Skill so agents discover
+  Lemming. Writes to `~/.agents/skills` by default and names any tool-specific
+  directories it found.
+  - `--to <dir>`: Install into a specific skills directory.
+  - `--all`: Also cover every detected tool's own skills directory.
+  - `--link`: Symlink instead of copying, so upgrades take effect immediately.
+  - `--force`: Replace an existing installation of this skill.
+  - `--dry-run`: Print what would happen, refusals included.
+- **`skill uninstall`**: Remove it again. Same `--to`, `--all`, and
+  `--dry-run`.
+- **`stop`**: Stop the running loop and its runner.
+  - `--after-current-task`: Drain instead — let the running task finish, then
+    stop before claiming another. This is the safe way to change the runner
+    or model without stranding work in flight.
 - **`serve`**: Launch the interactive Web UI.
   - `--port`: The port to bind the server to (default: 8999).
   - `--host`: The host address to bind the server to (default: 127.0.0.1).
@@ -292,6 +412,36 @@ See [docs/EVALS.md](docs/EVALS.md) for details.
 
 ---
 
+## Working across projects
+
+When work on one project turns up something that belongs to another — a bug in
+a dependency you also maintain, a doc fix in a sibling repo — file it directly
+on that project's roadmap with `-C` instead of routing it through an external
+issue tracker:
+
+```bash
+# From inside project A, queue work on project B
+lemming -C ~/src/other-project add "check --fix drops the trailing newline"
+
+# Attach the evidence; the brief has no length cap
+lemming -C ~/src/other-project brief <id> --file repro.md
+
+# Read the other project's roadmap without leaving yours
+lemming -C ~/src/other-project status
+```
+
+`-C` works whether or not the target keeps a `tasks.yml` in its repo, so you
+never have to know where its isolated state lives. Because it changes the
+working directory, everything else follows too: the target's `.env`, its
+`.lemming/hooks`, and the directory the runner executes in.
+
+When an agent files a task this way from inside a `lemming run`, the new task
+records the task it came from via `parent` and `parent_tasks_file`. The
+downstream runner then sees a **Parent Task Context** section in its prompt
+describing why the work was requested, so the report doesn't lose its origin.
+
+---
+
 ## Advanced: Runner Customization
 
 Lemming uses **fuzzy matching** to automatically inject the correct "YOLO"
@@ -304,17 +454,53 @@ Lemming uses **fuzzy matching** to automatically inject the correct "YOLO"
 - **Codex**: Runs non-interactively via `codex exec`, adds `--json`, and, in
   YOLO mode, adds `--dangerously-bypass-approvals-and-sandbox`
 
+### Choosing a model
+
+The model is a first-class setting, separate from the runner, so switching
+provider does not silently discard it:
+
+```bash
+lemming config set model gemini-3.6-flash-high   # project default
+lemming add "Fix the flaky test" --model fast    # just this task
+lemming config set model default                 # let the runner decide
+```
+
+Precedence, highest first: an explicit `--model` inside a runner string, the
+task's `--model`, the project's `config model`, then anything passed after
+`lemming run --`. A per-task setting always wins over the loop-wide
+passthrough — the conflicting global flag is dropped rather than duplicated
+on the command line.
+
+### Runner strings
+
+A runner is not limited to a binary name: any extra arguments in the string
+are appended to the command, which is another way to pin per-task behaviour.
+
+```bash
+lemming add "Try the fast model" --runner "agy --model fast"
+```
+
 You can disable default flag injection with `--no-defaults` (`codex exec`
 remains the Codex execution interface), or use a **template** to fully control
 the command layout:
 
 ```bash
-lemming run --runner "my-tool --input={{prompt}} --json"
+lemming config set runner "my-tool --input={{prompt}} --json"
 ```
 
 When `{{prompt}}` is present in the runner string, Lemming replaces it with the
 prompt text and skips all default flag injection.
 
+### Knowing what actually ran
+
+Each attempt records the command it launched, with the prompt elided, so the
+runner and model behind a finished task stay recoverable:
+
+```bash
+lemming status <id>          # includes "Last Command:"
+lemming status --json        # same data, machine-readable
+```
+
 ---
 
 ## Releasing

lemming_cli-0.4.0/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: lemming
+description: Delegate a single coding task to another AI agent CLI (agy, claude, codex) through one interface, or run a code review — readability, testing, UX — over changed files, a PR branch, or a path. Use when handing work to a different agent to spare a quota or play to its strengths, or when reviewing a diff before opening a pull request. Not for driving a multi-task project; that is a roadmap.
+license: MIT
+---
+
+# lemming
+
+One interface over several agent CLIs. You do not need to know how `agy`,
+`claude`, or `codex` spell their flags — only `lemming exec`.
+
+## Delegate one task
+
+```sh
+lemming exec "Fix the flaky heartbeat test in src/runner_test.py" --runner codex
+```
+
+The agent's closing message comes back on **stdout**; progress and the event
+trace go to stderr. Exit code is 0 only if the task completed. That message is
+the return value — read it instead of hunting through logs.
+
+Pipe a longer handoff rather than fighting shell quoting. There is no length
+limit, unlike a roadmap task description:
+
+```sh
+cat handoff.md | lemming exec -f - --runner agy
+```
+
+Delegate when another agent's quota, price, or strengths suit the work better
+than yours. Give the task everything it needs: it starts with an empty context
+and sees nothing of your conversation.
+
+## Run a review
+
+With no description there is nothing for a task runner to do, so only the
+reviews run — against work that already exists.
+
+```sh
+lemming exec --review readability          # uncommitted work
+lemming exec --review testing --scope main...HEAD
+lemming exec --review all --scope src/api/
+lemming exec "Add pagination" --review all # do the work, then gate it
+```
+
+`--scope` takes paths, which pass through untouched, or a git revision range,
+which is resolved to the files it changed. It defaults to uncommitted work.
+A clean tree stops the run rather than reviewing everything.
+
+Reviews **edit the workspace**: readability applies fixes and reruns checks.
+That is the point — but it means a review is not read-only.
+
+## Reviewing someone else's branch
+
+Check it out in a worktree so your own tree is untouched, and point `-C` at it:
+
+```sh
+git worktree add /tmp/pr-123 && (cd /tmp/pr-123 && gh pr checkout 123)
+lemming -C /tmp/pr-123 exec --review testing --scope main...HEAD
+```
+
+## What to know before running it
+
+- **The agent runs unattended.** `--yolo` is the default, so it does not
+  inherit the permission prompts of whatever launched it. Treat `lemming exec`
+  as granting an agent unsupervised write access to the working directory.
+- **One agent run, no retry.** A failure is final; it does not silently try
+  again. `--time-limit` caps the wall clock (default 60 minutes).
+- **Interrupting leaves partial edits.** The workspace is not restored, so
+  there is no atomicity to rely on.
+- **Failures keep their log.** The state directory path is printed on stderr;
+  read it with `lemming logs` pointed at that tasks file.
+
+## Running several at once
+
+Concurrent runs in one checkout will interleave their edits. Give each write
+task its own worktree and address it with `-C`. Read-only work parallelizes
+safely as-is.
+
+## When not to use it
+
+`exec` is for one unit of work. Anything needing more context than a single
+agent run can hold — a migration across a large codebase, a multi-step feature
+— belongs on a roadmap: `lemming add`, then `lemming run`. In particular,
+`--scope .` over a large repository *samples*; it does not cover.
+
+Run `lemming exec --help` for the full flag list.

{lemming_cli-0.3.3 → lemming_cli-0.4.0}/docs/HOOKS.md

@@ -158,6 +158,9 @@ Your hook template can use the following placeholders:
   description, recent progress, and a recent execution-log excerpt capped at
   16 KiB).
 - `{{finished_task_id}}`: The ID of the task that just finished.
+- `{{scope}}`: What the hook should look at, and how broadly. Under `lemming
+  run` this names the work the finished task left behind; under `lemming exec
+  --review` it is whatever `--scope` resolved to.
 - `{{tasks_file_name}}`: The filename of the tasks YAML file.
 - `{{tasks_file_path}}`: The full path to the tasks YAML file.
 
@@ -166,6 +169,12 @@ over older completed history. Readability, testing, and UX hooks receive a
 smaller roadmap summary because their primary context is the finished task and
 the workspace.
 
+A review hook should take its breadth from `{{scope}}` rather than narrowing
+itself in prose. Hardcoding "the files changed in the last task" makes the hook
+unusable outside the orchestrator loop, where there is no last task. Depth
+limits are different and belong in the prompt: "verification, not a security
+audit" describes the kind of review, not its extent.
+
 ## Developer Ergonomics
 
 ### Listing Hooks