planr 1.1.15 → 1.1.16

package/README.md

@@ -28,6 +28,12 @@ Three layers make that work: **Plans** (reviewable Markdown packages), the **Map
 brew install instructa/tap/planr
 ```
 
+Or via npm (ships platform-native binaries, no toolchain needed):
+
+```bash
+npm install -g planr
+```
+
 Or with the release installer:
 
 ```bash

package/docs/CLI_REFERENCE.md

@@ -22,7 +22,7 @@ planr map preview --close <item-id>
 planr map unlocks <item-id>
 planr map lookahead [--from <item-id>] [--limit 10]
 planr item create "title" --description "..." [--after <item-id>] [--timeout-seconds N] [--max-retries N] [--retry-backoff fixed|exponential] [--retry-delay-ms N] [--pre "..."] [--post "..."]
-planr item breakdown <item-id> --into "A, B, C"
+planr item breakdown <item-id> --into "A" --into "B" [--into "C"]
 planr item insert "title" --description "..." --after <item-id> [--before <item-id>] [--preview|--confirm]
 planr item amend <item-id> --note "..." [--tag amendment]
 planr item replan <parent-id> --into "A, B, C" [--preview|--confirm]
@@ -83,6 +83,8 @@ With `--json`, responses follow one convention so agents never guess where data
 
 `map build` chains the created items in plan order with `blocks` links — build plan steps are ordered, so the map inherits that order instead of leaving everything flat. The output lists every created item with its status, the created links, and the next command; adjust order with `planr link add` before picking if execution order differs from document order.
 
+`item breakdown` follows the same contract: each `--into` flag carries one child title (a single value may also pack newline- or comma-separated titles), children are chained with `blocks` links in the given order, and the parent parks as a blocked gate until they settle. The output lists every child with id and status, the chain links, and the next command — across CLI and MCP `planr_item_breakdown`.
+
 `review ingest` accepts hook-compatible JSON and records it as feedback only. It never closes review work and never approves an item by itself.
 
 ```json
@@ -107,11 +109,11 @@ With `--json`, responses follow one convention so agents never guess where data
 
 `trace item` on a review item inlines the target item and its evidence logs under `target`, so a reviewer's first trace already contains what is being audited. The human (non-JSON) mode renders the packet: status, owner, links, logs.
 
-`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. `done`, `close`, and `review close` report what the settlement `unlocked` (id, title, work type of every item that became ready), `done` and `close` echo the item's `post_condition` at completion time, and a `hint` asks for `--cmd`/`--tests` evidence when downstream items depend on an item that closed without any. `done`, `close`, `review close`, and the pick packet include a `remaining` progress snapshot so loop agents can evaluate their stop condition without an extra `map status` call. `remaining.counts` always carries the full status vocabulary (`pending`, `ready`, `picked`, `running`, `in_review`, `blocked`, `failed`, `cancelled`, `closed`, `closed_partial`) with explicit zeros — a missing count never has to be inferred.
+`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`). Without `--next`, the response's `next` field carries the exact follow-up command instead (`planr pick --work-type review --json` after a review request, `planr pick --json` after a close), so every settlement output ends in an action. It chains the same single-owner operations as `log add`, `review request`, `close`, and `pick` — identical evidence, fewer commands. `done`, `close`, and `review close` report what the settlement `unlocked` (id, title, work type of every item that became ready), `done` and `close` echo the item's `post_condition` at completion time, and a `hint` asks for `--cmd`/`--tests` evidence when downstream items depend on an item that closed without any. `done`, `close`, `review close`, and the pick packet include a `remaining` progress snapshot so loop agents can evaluate their stop condition without an extra `map status` call. `remaining.counts` always carries the full status vocabulary (`pending`, `ready`, `picked`, `running`, `in_review`, `blocked`, `failed`, `cancelled`, `closed`, `closed_partial`) with explicit zeros — a missing count never has to be inferred.
 
 `pick --json` returns one flat work packet in which every fact appears exactly once: `item`, `links`, `logs`, `runtime`, `recovery`, `conditions`, `approval`, recall context (`contexts`, `relevant_contexts`, `upstream_handoffs`, `review_history`, `source_links`, `possible_file_conflicts`), `close_effect`, `privacy`, `deeper_reads`, and `remaining`. Worker identity lives in `item.worker_id` and `runtime.worker_id`. Empty collections and inactive gates are omitted — a missing key means "empty". No separate `trace item` call is needed. Evidence written via `log add` or `done` by the pick owner refreshes the runtime heartbeat automatically. The same packet shape is returned by MCP `planr_pick_item`, HTTP `POST /v1/pick`, and `done --next`.
 
-`pick --work-type <type>` restricts the lease to one work type, so checker agents pick only `review` items and makers only work items. `pick --plan <plan-id>` restricts the lease to one plan's items, so plan-scoped goal runs never pick work outside their contract even when other plans share the board; an unknown plan id is an error, never a silent unscoped pick. Both filters are available on MCP `planr_pick_item` and HTTP `POST /v1/pick` (`work_type`, `plan`). A null pick is never blind: `{"item": null}` carries a `reason` (`empty_map`, `all_settled`, `nothing_ready`, `no_ready_item_in_plan`, `no_ready_item_of_work_type`, `ready_items_not_pickable`) and the `remaining` snapshot. On a review item, `close_effect` previews the full `--close-target` cascade: it lists the work that closing the review (and with it the reviewed item) would unlock.
+`pick --work-type <type>` restricts the lease to one work type, so checker agents pick only `review` items and makers only work items. `pick --plan <plan-id>` restricts the lease to one plan's items, so plan-scoped goal runs never pick work outside their contract even when other plans share the board; an unknown plan id is an error, never a silent unscoped pick. Both filters are available on MCP `planr_pick_item` and HTTP `POST /v1/pick` (`work_type`, `plan`). A null pick is never blind: `{"item": null}` carries a `reason` (`empty_map`, `all_settled`, `nothing_ready`, `ready_items_excluded_by_filter`) and the `remaining` snapshot. When ready work exists but the active filters rejected all of it, `excluded` lists each ready item with the cause (`work_type` mismatch, outside the `--plan` scope, or just requested by this worker) and `repair` carries the exact pick commands that would lease that work — across CLI, MCP, and HTTP. On a review item, `close_effect` previews the full `--close-target` cascade: it lists the work that closing the review (and with it the reviewed item) would unlock.
 
 `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.
 

package/docs/GOALS.md

@@ -63,7 +63,7 @@ planr done <item-id> --summary "..." --cmd "..." --review --next
 planr review close <review-id> --verdict complete --reviewer <id> --close-target
 ```
 
-`--plan` keeps the lease inside the goal contract: when several plans share the board (a parallel feature, leftovers from an aborted prep run), a plan-scoped goal run never picks work outside its own plan. A pick that finds nothing in scope reports `reason: "no_ready_item_in_plan"` instead of silently widening.
+`--plan` keeps the lease inside the goal contract: when several plans share the board (a parallel feature, leftovers from an aborted prep run), a plan-scoped goal run never picks work outside its own plan. A pick that finds nothing in scope never widens silently: it reports `reason: "nothing_ready"` when nothing is ready at all, or `reason: "ready_items_excluded_by_filter"` with the excluded items, the cause per item, and the exact `repair` pick commands when ready work exists outside the filter.
 
 `done`/`close`/`review close` responses and the pick packet include a `remaining` snapshot (`counts` with explicit zeros for every status, `settled`, `total`), so the orchestrator evaluates the stop condition straight from the completion output — no extra `map status` round-trip. The same responses list what each settlement `unlocked`, so the loop sees its next work without re-reading the map. `--next` never hands a worker its own freshly created review, so maker and checker stay separate even in compact loops. The review verdict records `review_mode` (`single_agent` or `independent`) automatically from worker identity — no ceremony note needed.
 

package/docs/INSTALL.md

@@ -27,9 +27,24 @@ Download installs verify `SHA256SUMS` from the same release location by default.
 
 ## Homebrew Tap
 
-Homebrew is the preferred day-to-day package-manager path after the tap is published. The expected command is `brew install instructa/tap/planr`.
+Homebrew is the preferred day-to-day package-manager path:
 
-Until the tap is published, use the GitHub Release installer or manual release asset download.
+```bash
+brew install instructa/tap/planr
+```
+
+The tap formula is regenerated automatically on every release.
+
+## npm
+
+Published npm versions bundle platform-native binaries (`darwin-arm64`, `darwin-x86_64`, `linux-x86_64`, `linux-arm64`), so no Rust toolchain is needed and nothing is downloaded at install time:
+
+```bash
+npm install -g planr
+planr --version
+```
+
+Details and publishing flow: [npm Package](NPM.md).
 
 ## Manual GitHub Release Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.1.15",
+  "version": "1.1.16",
   "description": "Local-first planning and execution coordination for coding agents.",
   "license": "MIT",
   "repository": {

package/plugins/planr/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "planr",
   "description": "Skill-driven planning and execution loop for coding agents: one planr entry point, an autonomous planr-loop, and evidence-backed task graph skills powered by the planr CLI.",
-  "version": "1.1.15",
+  "version": "1.1.16",
   "author": {
     "name": "instructa"
   },

package/plugins/planr/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.1.15",
+  "version": "1.1.16",
   "description": "Skill-driven planning and execution loop for coding agents: one $planr entry point, an autonomous $planr-loop, and evidence-backed task graph skills powered by the planr CLI.",
   "author": {
     "name": "instructa",

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

@@ -48,11 +48,13 @@ Each iteration is one dispatch through the routing skill — never a hand-writte
 6. repeat             fix items are just the next ready items
 ```
 
-The short path per item is three commands: `planr pick --json` (one flat work packet; makers add `--work-type code`), `planr done <item-id> --summary ... --cmd ... --review [--next]`, and the reviewer's `planr --json pick --work-type review` followed by `planr review close <review-id> --verdict complete --reviewer <id> --close-target` — run exactly once. Parent gates roll up automatically. When the loop runs against one plan (every `/goal` run does), add `--plan <plan-id>` to every pick so the lease never leaves the goal contract, even when other plans share the board; an empty scope reports `reason: "no_ready_item_in_plan"`.
+The short path per item is three commands: `planr pick --json` (one flat work packet; makers add `--work-type code`), `planr done <item-id> --summary ... --cmd ... --review [--next]`, and the reviewer's `planr --json pick --work-type review` followed by `planr review close <review-id> --verdict complete --reviewer <id> --close-target` — run exactly once. Parent gates roll up automatically. When the loop runs against one plan (every `/goal` run does), add `--plan <plan-id>` to every pick so the lease never leaves the goal contract, even when other plans share the board. A null pick explains itself: when filters excluded ready work, `reason: "ready_items_excluded_by_filter"` names each excluded item, the cause (work_type or plan mismatch), and the exact `repair` pick command — run the repair instead of guessing.
 
-`map build` chains created items in plan order with `blocks` links automatically and prints the created items and links. In step 2, verify that chain against real execution-order dependencies and adjust with `planr link add` only where document order and execution order differ.
+`map build` chains created items in plan order with `blocks` links automatically and prints the created items and links. In step 2, verify that chain against real execution-order dependencies and adjust with `planr link add` only where document order and execution order differ. `item breakdown` works the same way: pass one `--into` per child title (or one value with newline-separated titles), and the output lists the chained children plus the next command.
 
-The loop never closes its own reviews when the host supports a second agent. Maker and checker stay separate.
+Request reviews where they carry signal: implementation slices and anything user-facing finish with `done --review`. Trivial inspection, baseline, or setup items close with plain `done` (evidence still required) — a review that can only confirm "the repo was empty" adds ceremony, not safety.
+
+The loop never closes its own reviews when the host supports a second agent. Maker and checker stay separate. One agent instance keeps one `PLANR_WORKER_ID` for the whole session — never export a second identity inside the same instance to make reviews look `independent`; an honest `single_agent` stamp beats a fake `independent` one.
 
 ## Skills Are The Prompts
 

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

@@ -41,7 +41,9 @@ planr review close <review-id> --verdict not-complete --reviewer <your-id> --fin
 
 ## Single-Agent Mode
 
-When no independent reviewer instance is available (single-agent host), do not pretend a second instance reviewed the work. Re-read the diff, logs, and evidence with fresh eyes, then close normally. The review mode is recorded automatically: `review close` compares your identity against the maker's lease and stamps `review_mode: single_agent | independent | unattributed` on the close response, review log, artifact, and event. No extra context note is needed — honesty is derived from recorded identity. To run an honest independent review on a multi-instance host, export a distinct `PLANR_WORKER_ID` before picking.
+When no independent reviewer instance is available (single-agent host), do not pretend a second instance reviewed the work. Re-read the diff, logs, and evidence with fresh eyes, then close normally. The review mode is recorded automatically: `review close` compares your identity against the maker's lease and stamps `review_mode: single_agent | independent | unattributed` on the close response, review log, artifact, and event. No extra context note is needed — honesty is derived from recorded identity.
+
+Identity honesty rule: one agent instance keeps one `PLANR_WORKER_ID` for its whole session. Never export a second identity (e.g. `maker-x` and `checker-x`) inside the same instance to make a review look independent — that stamps `independent` on a review that was not, which is worse than an honest `single_agent`. `independent` is only real when a separate agent process (a subagent, another terminal, another client) picks the review under its own identity.
 
 ## Completion Rule
 

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

@@ -135,7 +135,7 @@ parent gate
 Rules:
 
 - create a parent item for the change;
-- use `planr item breakdown <parent-id> --into "Implement, Verify"` to create child work under that parent;
+- use `planr item breakdown <parent-id> --into "Implement" --into "Verify"` (one `--into` per child; a single value may also pack newline- or comma-separated titles) to create chained child work under that parent — the output lists every child with id and status plus the next pick command;
 - request review on the implementation or test child after evidence exists;
 - if review finds issues, let Planr create fix and follow-up review work from the review verdict;
 - make later top-level work depend on the parent gate, not only the first child.
@@ -157,7 +157,7 @@ Readiness comes from graph links and item state, not Markdown checkboxes.
 Use:
 
 ```bash
-planr item breakdown <item-id> --into "Trace owner, Implement, Verify"
+planr item breakdown <item-id> --into "Trace owner" --into "Implement" --into "Verify"
 planr link remove <from-item> <to-item> --type blocks
 ```
 

package/plugins/planr/skills/planr-work/SKILL.md

@@ -16,7 +16,7 @@ export PLANR_WORKER_ID=maker-1
 planr pick --json
 ```
 
-The pick output is one flat work packet — item, links, logs, runtime, recovery, conditions, recall context (`upstream_handoffs`, `relevant_contexts`, `review_history`), and `remaining` progress. Each fact appears once; a missing key means "empty". No separate `trace item` call needed. Add `--work-type code` to skip review items when checker agents work the same board, and `--plan <plan-id>` when your dispatch names a plan so the lease stays inside that scope. A null pick explains itself: `{"item": null}` carries a `reason` (`all_settled`, `nothing_ready`, `no_ready_item_in_plan`, ...) plus the `remaining` snapshot. Read the linked plan/context, implement the smallest correct slice, then finish the step in one command:
+The pick output is one flat work packet — item, links, logs, runtime, recovery, conditions, recall context (`upstream_handoffs`, `relevant_contexts`, `review_history`), and `remaining` progress. Each fact appears once; a missing key means "empty". No separate `trace item` call needed. Add `--work-type code` to skip review items when checker agents work the same board, and `--plan <plan-id>` when your dispatch names a plan so the lease stays inside that scope. A null pick explains itself: `{"item": null}` carries a `reason` (`all_settled`, `nothing_ready`, `ready_items_excluded_by_filter`) plus the `remaining` snapshot; when filters excluded ready work, `excluded` names each item and cause and `repair` carries the exact pick command to run instead. Read the linked plan/context, implement the smallest correct slice, then finish the step in one command:
 
 ```bash
 planr done <item-id> --summary "what changed" --files path-a --files path-b --cmd "exact verification command" --tests "exact test command" --review