Cut per-item CLI overhead with a compound work flow

New src/app/flow.rs owns the compound flow: `planr done` chains
completion log, review request or close, and an optional next pick;
evidence logs refresh the owner heartbeat; `pick --json` includes the
full trace work packet; `review close --close-target` closes the
reviewed item with the review when evidence exists. The next pick
excludes the worker's own freshly requested review so maker and checker
stay separate. Per-item flow drops from ~8 commands to 3 with identical
evidence.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: regenrek

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "planr"
-version = "1.1.5"
+version = "1.1.6"
 edition = "2021"
 license = "MIT"
 description = "Local-first planning and execution coordination for coding agents"

Cargo.toml

@@ -19,6 +19,7 @@ Planr V1 is a single Rust binary with explicit module ownership. The crate stays
 - `src/cli.rs`: CLI contract boundary. Owns `clap` command definitions, option parsing types, value enums, and command DTOs used by app dispatch.
 - `src/app/mod.rs`: application composition boundary. Owns the `App` runtime state, top-level dispatch, shared app-local row helpers, and app submodule wiring.
 - `src/app/commands.rs`: CLI use-case orchestration. Owns project, plan, map, item, link, pick, approval, log, close, review, context, search, doctor, and install command handlers.
+- `src/app/flow.rs`: compound work-flow boundary. Owns evidence log writing (with heartbeat folding), the close transition core, review-request creation, the pick work packet, and the `done` command that chains them for CLI, HTTP, and MCP surfaces.
 - `src/app/git_review.rs`: Git and PR review evidence boundary. Owns worktree detection, scoped changed-file provenance, PR URL context, and dirty-worktree safety projections.
 - `src/app/mcp.rs`: MCP stdio boundary. Owns MCP protocol request routing, tool calls, resource reads, and prompt responses.
 - `src/app/packages.rs`: package import/export boundary. Owns reusable JSON templates, preview-before-import, review artifact package import, and local-first encrypted bundle metadata.

docs/ARCHITECTURE.md

@@ -49,8 +49,9 @@ planr review annotate <item-id> --message "..." [--severity info|warning|blockin
 planr review ingest <item-id> (--from feedback.json|--stdin)
 planr review artifact <review-item-id> [--out .planr/reviews/custom.review.md]
 planr review evidence <item-id> [--pr-url https://...]
-planr review close <review-item-id> --verdict complete|not-complete|unclear
+planr review close <review-item-id> --verdict complete|not-complete|unclear [--close-target]
 planr close [item-id] --summary "..." [--next]
+planr done [item-id] --summary "..." [--files a --files b] [--cmd "..."] [--tests "..."] [--review] [--next]
 planr context add "text" [--item <item-id>] [--tag discovery]
 planr search "query"
 planr doctor [--client codex|claude|cursor|all]
@@ -94,7 +95,11 @@ With `--json`, responses follow one convention so agents never guess where data
 }
 ```
 
-`review close` writes `.planr/reviews/<review-item-id>.review.md` and registers it as a review artifact. A `not-complete` or `unclear` verdict creates fix and follow-up review work.
+`review close` writes `.planr/reviews/<review-item-id>.review.md` and registers it as a review artifact. A `not-complete` or `unclear` verdict creates fix and follow-up review work. With `--close-target` (complete verdicts only) the reviewed item is closed in the same command, provided it already has a completion log.
+
+`done` is the compound worker command: it writes a completion log, then requests a review (`--review`) or closes the item, and optionally picks the next ready item (`--next`). It chains the same single-owner operations as `log add`, `review request`, `close`, and `pick` — identical evidence, fewer commands.
+
+`pick --json` returns the full work packet: the item, recall `context`, and a `trace` object (links, logs, runtime, recovery, conditions, approval), so no separate `trace item` call is needed. Evidence written via `log add` or `done` by the pick owner refreshes the runtime heartbeat automatically.
 
 `review evidence` reports Git worktree status scoped to files named by item logs or artifacts. Dirty files without item provenance are listed as unrelated and are not treated as agent-owned evidence. `--pr-url` records an item-scoped PR reference before returning the evidence package.
 

docs/CLI_REFERENCE.md

@@ -49,14 +49,15 @@ Product-plan task lists are candidates. Work becomes a live commitment only afte
 
 ## Daily Agent Loop
 
-Agents should work one map item at a time:
+Agents should work one map item at a time. The short path is:
 
 ```bash
 planr pick --json
-planr trace item <item-id>
-planr pick heartbeat <item-id>
+planr done <item-id> --summary "what changed" --files a --files b --cmd "exact verification command" --review [--next]
 ```
 
+`pick --json` returns the item with recall context and the full `trace` work packet, so no separate `trace item` call is needed. `done` writes the completion log, then requests review (`--review`) or closes directly, and `--next` picks the following item. Evidence logging refreshes the heartbeat, so explicit `pick heartbeat` calls are only needed during long silent stretches.
+
 For longer work, update runtime state instead of relying on chat history:
 
 ```bash
@@ -98,10 +99,11 @@ planr review request <item-id>
 planr review annotate <item-id> --message "review note" --severity warning
 planr review evidence <item-id> --pr-url https://example.invalid/pr/123
 planr review ingest <item-id> --from .planr/tmp/review-feedback.json
-planr review close <review-id> --verdict complete
-planr close <item-id> --summary "Verified with evidence"
+planr review close <review-id> --verdict complete --close-target
 ```
 
+With `--close-target` a complete verdict also closes the reviewed item (it must already carry a completion log); otherwise finish with `planr close <item-id> --summary "Verified with evidence"`.
+
 `review evidence` records Git branch, commit, dirty state, item-scoped changed-file provenance, and optional PR URL context without treating unrelated dirty files as proof. Review ingestion records hook-compatible JSON feedback as contexts and logs only. It does not close the review, approve the item, or unblock downstream work.
 
 For a browser-based local review pass:

docs/OPERATING_MODEL.md

@@ -65,7 +65,7 @@ Picking is the concurrency boundary:
 planr pick --json
 ```
 
-One ready item should be picked by one worker. Picked work records `worker_id`, `pick_token`, `picked_at`, and `last_heartbeat_at`. Worker identity is stable per client, host, and user, so heartbeats keep working across the many short-lived processes of an agent session. Parallel workers on the same machine must set `PLANR_SESSION_ID` to distinct values. Active agents should keep the claim fresh and make progress visible:
+One ready item should be picked by one worker. The pick output includes recall context and the full `trace` work packet. Picked work records `worker_id`, `pick_token`, `picked_at`, and `last_heartbeat_at`. Worker identity is stable per client, host, and user, so heartbeats keep working across the many short-lived processes of an agent session. Parallel workers on the same machine must set `PLANR_SESSION_ID` to distinct values. Evidence written via `log add` or `done` by the owner refreshes the heartbeat automatically; the explicit runtime commands cover long silent stretches:
 
 ```bash
 planr pick heartbeat [item-id]

docs/TASK_GRAPH_MODEL.md

@@ -30,12 +30,14 @@ Each iteration is one dispatch through the routing skill — never a hand-writte
 ```text
 1. $planr-status      read honest state; if stop condition holds -> exit loop
 2. $planr-plan / $planr-task-graph   only if scope or map structure is missing
-3. $planr-work        pick exactly one ready item, implement, log evidence
+3. $planr-work        pick exactly one ready item, implement, finish with planr done --review
 4. live verify        run the platform verification (below), log it with planr log add --cmd
-5. $planr-review      independent audit; complete -> close, findings -> Planr creates fix items
+5. $planr-review      independent audit; complete -> review close --close-target, findings -> Planr creates fix items
 6. repeat             fix items are just the next ready items
 ```
 
+The short path per item is three commands: `planr pick --json` (includes the trace work packet), `planr done <item-id> --summary ... --cmd ... --review [--next]`, and the reviewer's `planr review close <review-id> --verdict complete --close-target`. Parent gates roll up automatically.
+
 After any `planr map build`, dependency linking is part of step 2, not optional: add `blocks` links for every execution-order dependency before the first pick. An unlinked map makes the loop pick items in arbitrary order.
 
 The loop never closes its own reviews when the host supports a second agent. Maker and checker stay separate.

plugins/planr/skills/planr-loop/SKILL.md

@@ -18,9 +18,11 @@ planr map show --json
 Inspect the actual changed files and verification evidence. Then close the review:
 
 ```bash
-planr review close <review-id> --verdict complete
+planr review close <review-id> --verdict complete --close-target
 ```
 
+`--close-target` also closes the reviewed item when the verdict is complete and a completion log exists — the worker does not need a separate close round-trip. Omit it when the worker should close explicitly.
+
 or:
 
 ```bash

plugins/planr/skills/planr-review/SKILL.md

@@ -34,14 +34,15 @@ planr doctor --client all
 
 ## Core Loop
 
-Use one item at a time:
+Use one item at a time. The short path is two commands per step:
 
 ```bash
 planr pick --json
-planr trace item <item-id>
-planr pick heartbeat <item-id>
+planr done <item-id> --summary "what changed" --files a --files b --cmd "exact verification command" --review [--next]
 ```
 
+`pick --json` includes the full work packet (`trace`: links, logs, runtime, conditions, approval). `done` writes the completion log, requests review (`--review`) or closes directly, and `--next` picks the following item. Evidence logs refresh the heartbeat automatically.
+
 For longer work, keep the live claim visible:
 
 ```bash
@@ -65,14 +66,16 @@ planr log add --item <item-id> \
   --cmd "exact verification command"
 ```
 
-Request review, close review, then close the item:
+Granular alternative: request review, close review, then close the item:
 
 ```bash
 planr review request <item-id>
-planr review close <review-id> --verdict complete
+planr review close <review-id> --verdict complete --close-target
 planr close <item-id> --summary "Verified with evidence"
 ```
 
+`--close-target` closes the reviewed item together with the review when the verdict is complete and a completion log exists; the separate `planr close` is then unnecessary.
+
 If human approval is part of the gate, request it and do not close until it is approved:
 
 ```bash

plugins/planr/skills/planr-task-graph/SKILL.md

@@ -11,21 +11,23 @@ Use this for one picked item at a time.
 
 ```bash
 planr pick --json
-planr trace item <item-id>
-planr pick heartbeat <item-id>
 ```
 
-Read the linked plan/context, implement the smallest correct slice, then record evidence:
+The pick output already contains the full work packet (`trace`: links, logs, runtime, conditions, approval) plus recall context — no separate `trace item` call needed. Read the linked plan/context, implement the smallest correct slice, then finish the step in one command:
 
 ```bash
-planr log add --item <item-id> --summary "what changed" --files path-a --files path-b --cmd "exact verification command"
-planr review request <item-id>
+planr done <item-id> --summary "what changed" --files path-a --files path-b --cmd "exact verification command" --review
 ```
 
-Only close after review is complete:
+`done --review` writes the completion log and requests the review; add `--next` to pick the following item in the same call. Without `--review` it closes the item directly (only for items that need no review gate).
+
+Evidence logging refreshes the heartbeat automatically — a separate `planr pick heartbeat` is only needed for long silent stretches without logs.
+
+The granular commands remain available when you need them:
 
 ```bash
-planr review close <review-id> --verdict complete
+planr log add --item <item-id> --summary "..." --files a --files b --cmd "..."
+planr review request <item-id>
 planr close <item-id> --summary "Verified"
 ```