planr 1.2.0-alpha.1 → 1.3.0-alpha.1

package/README.md

@@ -22,6 +22,30 @@ Flat todo lists break down the moment real work has structure. Planr models work
 
 Three layers make that work: **Plans** (reviewable Markdown packages), the **Map** (live dependency graph with picks, reviews, logs), and **Agent loops** (skills, CLI, and MCP workflows for every major coding agent). Full model: [Task Graph Model](docs/TASK_GRAPH_MODEL.md) and [Operating Model](docs/OPERATING_MODEL.md).
 
+## New in 1.2.0: Model Routing
+
+Declare once which model handles which work — every task then carries its own routing, and your agents delegate automatically:
+
+```toml
+# .planr/agents.toml  (write it with `planr agents init`)
+[profiles.frontender]
+client = "cursor"
+model = "opus"
+skill = "frontend-design"
+
+[[routes]]
+match = { work_type = "frontend" }
+profile = "frontender"
+fallbacks = ["driver"]
+```
+
+- **Routing travels in the pick packet** — `planr pick --json` hands the worker its profile, model, and paired skill; `planr pick --peek` lets dispatching drivers read it without taking the lease.
+- **Rendered into your hosts' native config** — `planr install codex|claude|cursor` writes the subagent role files with model pins from the registry, in each host's exact vocabulary.
+- **Declared vs. actual, with receipts** — workers report the profile they ran on, runs record the observed host, and `planr trace item` shows deviations as advisory markers.
+- **Use-case pools** — free-form work types (`frontend`, `backend`, ...) declared right in the plan's task list (`### TASK-001 (backend): ...`), plus per-item pins via `planr item route`.
+
+Routing is advisory by design: Planr never dispatches models and never blocks a pick — hosts stay the authority. Full guide: [Model Routing](docs/MODEL_ROUTING.md) · replayable walkthrough: [Worked Example: Web App](docs/EXAMPLE_WEBAPP.md) · [Release notes](https://github.com/instructa/planr/releases/tag/v1.2.0).
+
 ## Install
 
 ```bash
@@ -137,6 +161,7 @@ Mid-project work (a new feature, refactor, or fix on an existing project) works
 - [Skills](docs/SKILLS.md)
 - [Long-Running Goals](docs/GOALS.md)
 - [Model Routing](docs/MODEL_ROUTING.md) · [Worked Example: Web App](docs/EXAMPLE_WEBAPP.md)
+- [Host Hooks](docs/HOOKS.md)
 - [CLI Reference](docs/CLI_REFERENCE.md)
 - [MCP Guide](docs/MCP_GUIDE.md)
 - [Codex](docs/CODEX.md) · [Claude Code](docs/CLAUDE_CODE.md) · [Cursor](docs/CURSOR.md)

package/docs/CLI_REFERENCE.md

@@ -27,9 +27,11 @@ planr item insert "title" --description "..." --after <item-id> [--before <item-
 planr item amend <item-id> --note "..." [--tag amendment]
 planr item replan <parent-id> --into "A, B, C" [--preview|--confirm]
 planr item update <item-id> [--title "..."] [--description "..."] [--work-type <type>]
+# plan task lists can declare work types inline: `### TASK-001 (backend): ...` / `- [ ] (frontend) ...` seed map build directly
 planr item route <item-id> [--set <profile>|--clear]
 planr link add <from-item> <to-item> --type blocks
-planr pick
+planr prime [--hook-json]
+planr pick [--work-type <type>] [--plan <plan-id>] [--peek]
 planr pick release <item-id> [--force]
 planr pick heartbeat [item-id]
 planr pick progress <item-id> --percent 0..100 [--note "..."]
@@ -47,6 +49,7 @@ planr artifact list [--item <item-id>]
 planr event list [--item <item-id>] [--limit 50]
 planr debug bundle [--item <item-id>] --preview
 planr log add --item <item-id> --summary "..." [--files a --files b | --files a,b] [--cmd "..."] [--kind completion|progress|verification] [--profile <id>]
+# machine consumers: --cmd writes the `commands` field in log JSON; --tests writes `tests`
 planr review request <item-id>
 planr review annotate <item-id> --message "..." [--severity info|warning|blocking] [--file path] [--line N] [--author "..."]
 planr review ingest <item-id> (--from feedback.json|--stdin)
@@ -63,7 +66,7 @@ planr agents init --profile|--skill|--route|--default-route|--interactive
 planr agents list [--json]
 planr agents check
 planr doctor [--client codex|claude|cursor|all]
-planr install codex|claude|cursor [--dry-run] [--no-mcp] [--force]
+planr install codex|claude|cursor [--dry-run] [--no-mcp] [--force] [--no-hooks]
 planr prompt cli|mcp|http [--client codex|claude|cursor|all]
 planr prompt routing [--client codex|claude|cursor|all]
 planr mcp
@@ -125,7 +128,9 @@ With `--json`, responses follow one convention so agents never guess where data
 
 `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`.
+`prime` prints the compact state block host hooks inject at session start and after context compaction (project, map counts, held items with log status, goal contract, registry presence, next command); `--hook-json` emits the Claude Code SessionStart envelope. In a repo without a Planr database it exits silently and creates nothing — hooks must never break a session. Installs wire it into the host's hook system by default (`--no-hooks` skips; existing hook files are merged additively, never overwritten). Full guide: [Host Hooks](HOOKS.md).
+
+`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 --peek` (MCP: `"peek": true`) returns the same packet for the next pickable item *without* leasing it — no lease, heartbeat, or pick event is written, and the packet carries `"peek": true` with the item still `ready`. Built for dispatching drivers: read the routing block, dispatch the worker, and let the worker take the lease under its own identity — replacing the pick → `pick release --force` → re-pick sequence.
 
 `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.
 

package/docs/HOOKS.md

@@ -0,0 +1,34 @@
+# Host Hooks
+
+`planr install codex|claude|cursor` wires Planr into the host's native hook system **by default** — skip it with `--no-hooks`. The hooks solve one problem: loop state must survive the moments context is created or destroyed. Every new session and every context compaction gets the map state injected automatically via `planr prime`, so recovery stops being discipline and becomes mechanism.
+
+## What gets installed
+
+| Host | File | Events | Runs |
+| --- | --- | --- | --- |
+| Cursor | `.cursor/hooks.json` | `sessionStart` | `planr prime --cursor-json` |
+| | | `subagentStop` | `.cursor/hooks/planr-evidence-guard.sh` |
+| Claude Code | `.claude/settings.json` | `SessionStart` (matcher `startup\|resume\|compact`) | `planr prime --hook-json` |
+| Codex CLI | `.codex/hooks.json` | `SessionStart` | `planr prime` |
+
+`planr prime` prints one compact, bounded state block (project, map counts, your held items with log status, the goal contract, registry presence, and the next command) — deterministic and read-only. `--hook-json` wraps it in the Claude Code SessionStart envelope (`hookSpecificOutput.additionalContext`); `--cursor-json` emits Cursor's `additional_context` shape.
+
+Only session-start events are wired, deliberately: they are the one place all three hosts inject hook output as context, and Claude's `compact` source plus post-compaction session starts cover the compaction case. Pre/post-compaction events (`preCompact`, `PreCompact`, `PostCompact`) cannot restore model context and are not used.
+
+The evidence guard is advisory and identity-scoped: a Cursor subagent that stops while *its own* pick (matched via `PLANR_WORKER_ID`/`PLANR_SESSION_ID`) has no completion log gets one follow-up message naming the item and the two ways out (`planr done ...` or `planr pick release ...`). Without an explicit worker identity it stays silent rather than steering the wrong agent toward foreign items. It never blocks.
+
+## Design rules
+
+- **Fail open, always.** Every hook command ends in `|| true` with a 10-second timeout; a missing, broken, or uninitialized planr never blocks a session. In a repo without a Planr database, `planr prime` exits silently and creates nothing.
+- **Additive merge, planr owns only its own entries.** Existing hook files keep every foreign entry; planr entries are reconciled on re-install (current ones untouched, outdated ones upgraded in place, entries under retired events removed) — so `planr install <client>` after an update also refreshes the hooks. A file planr cannot parse as a JSON object is left untouched with a note in the install output — add the snippet manually in that case.
+- **Default, not mandatory.** `--no-hooks` skips hook installation entirely; deleting the planr entries from the hook files removes the behavior with no other effect.
+
+## Codex trust model
+
+Codex requires reviewing hooks before they run: after installing, open `/hooks` in the Codex TUI once and trust the planr entries. Codex records trust against the hook definition's hash, so if a future planr version changes the hook commands, Codex will ask again — that is the host working as intended.
+
+## Removing hooks
+
+Delete the planr entries from `.cursor/hooks.json` / `.claude/settings.json` / `.codex/hooks.json` (and `.cursor/hooks/planr-evidence-guard.sh`). Nothing else depends on them.
+
+See also: [Model Routing](MODEL_ROUTING.md), [Goals](GOALS.md), [CLI Reference](CLI_REFERENCE.md).

package/docs/MODEL_ROUTING.md

@@ -126,6 +126,10 @@ Every host has a silent override path — the `CLAUDE_CODE_SUBAGENT_MODEL` env v
 
 Everything here is advisory (ADR-001): mismatches never fail logging, reviews, or closes. No profile reported, no run recorded, or no registry means no comparison and no event.
 
+One legitimate mismatch source to know: a driver adding a live-verification log to a routed item runs on the driver profile by design, which emits a `route_mismatch_observed` event. The payload carries `log_kind`, so audit consumers can discount `verification` entries and alarm only on `completion` mismatches.
+
+For single-host pools (e.g. all-Cursor), declare the host's *exact* model slugs (`claude-opus-4-8-thinking-high`, not `opus`): dispatch APIs resolve slugs, not aliases, and a driver forced to map `fable-5` onto the nearest slug at dispatch time is a silent translation the audit cannot see.
+
 ## Failure Behavior
 
 - **No registry file**: nothing changes. Pick packets simply have no `routing` key.
@@ -171,6 +175,8 @@ Create items with the use-case work type (`planr item create ... --work-type fro
 
 Declare the `client` you will actually dispatch on. A loop running inside one host dispatches that host's subagents — an in-Cursor driver that dispatches Cursor subagents with per-dispatch models is running `client = "cursor"` profiles in practice, even when the model matches. A `client = "codex"` profile is only honest when the driver really spawns a Codex process (`codex exec ...`). This matters for the audit: workers report the *profile id*, so a profile whose declared client differs from the real dispatch host passes the mismatch check on the model alone — the client deviation stays invisible.
 
+When do you actually need more than one client? Hosts with a full model catalog (Cursor) can serve an entire pool natively — an all-`cursor` registry with different models per profile is the normal case there. Cross-client profiles exist for two real situations: vendor-locked hosts (Claude Code dispatches only Anthropic models, Codex CLI only OpenAI models — a Claude-Code driver that wants a GPT implementer must process-dispatch via `codex exec`), and subscription economics (the same model can bill differently per host, so routing backend work through a flat-rate CLI subscription instead of the driver host's quota is a legitimate cost decision).
+
 ## Host Matrix
 
 Where each host reads its model configuration from, and what silently defeats a pin there (state of July 2026):

package/docs/fixtures/mcp-contract.json

@@ -88,6 +88,8 @@
     "planr prompt routing",
     "planr agents init",
     "planr agents init --profile|--skill|--route|--default-route|--interactive",
+    "planr prime",
+    "planr install codex|claude|cursor [--dry-run] [--no-mcp] [--force] [--no-hooks]",
     "planr mcp",
     "planr review annotate",
     "planr review ingest",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.2.0-alpha.1",
+  "version": "1.3.0-alpha.1",
   "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.2.0-alpha.1",
+  "version": "1.3.0-alpha.1",
   "author": {
     "name": "instructa"
   },

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

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.2.0-alpha.1",
+  "version": "1.3.0-alpha.1",
   "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-goal/SKILL.md

@@ -42,7 +42,7 @@ Before `map build`, expand the plan's task list: the scaffold ships a single pla
 planr link add <earlier-item> <later-item> --type blocks
 ```
 
-If `planr agents list --json` shows routes with use-case `work_type` selectors (e.g. `frontend`, `backend`), retag the built items to match their work (`planr item update <id> --work-type frontend`) so every pick packet carries the declared profile and paired skill — this is prep-agent work, never a question for the user.
+If `planr agents list --json` shows routes with use-case `work_type` selectors (e.g. `frontend`, `backend`), declare them in the plan's task list before building — `### TASK-00n (backend): ...` headings and `- [ ] (frontend) ...` items seed with that work type directly. For maps already built without annotations, retag (`planr item update <id> --work-type frontend`). Either way this is prep-agent work, never a question for the user.
 
 ## Store The Goal Contract
 

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

@@ -58,7 +58,7 @@ The loop never closes its own reviews when the host supports a second agent. Mak
 
 ## Skills Are The Prompts
 
-When the host supports subagents, the driver never implements: it dispatches, audits, and synthesizes. Driver tokens go into `plan audit`, dispatch decisions, and conflict resolution — implementation and review run in the subagent roles, which the host wiring can pin to a cheaper tier (see the role files and `docs/GOALS.md` "Cost Tiering"). When the pick packet carries a `routing` block, dispatch on it: run the worker on the named profile's client and model, and move down the `fallbacks` chain when the primary hits a rate limit or is unavailable — the chain is ordered, so no mid-run registry edits. Workers report the profile they actually ran on (`done --profile <id>` or `PLANR_PROFILE`), so a host that silently overrode the pin shows up in `planr trace item` instead of staying invisible. Delegate with skill references plus an item id, nothing more:
+When the host supports subagents, the driver never implements: it dispatches, audits, and synthesizes. Driver tokens go into `plan audit`, dispatch decisions, and conflict resolution — implementation and review run in the subagent roles, which the host wiring can pin to a cheaper tier (see the role files and `docs/GOALS.md` "Cost Tiering"). When the pick packet carries a `routing` block, dispatch on it: run the worker on the named profile's client and model, and move down the `fallbacks` chain when the primary hits a rate limit or is unavailable — the chain is ordered, so no mid-run registry edits. As the dispatching driver, read the packet with `planr pick --peek [--plan <id>]` — it returns the same packet without leasing, so the worker picks under its own identity and the maker/checker audit stays clean (never pick-and-release as the driver). Workers report the profile they actually ran on (`done --profile <id>` or `PLANR_PROFILE`), so a host that silently overrode the pin shows up in `planr trace item` instead of staying invisible. Delegate with skill references plus an item id, nothing more:
 
 - Worker dispatch: `Use $planr-work on item <item-id>. Stop after requesting review.`
 - Checker dispatch: `Use $planr-review on item <item-id>. Close the review with a verdict.`

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

@@ -53,15 +53,16 @@ A build plan must include:
 
 ## Route-Aware Tagging
 
-Before `map build`, check whether the project declares model routing: `planr agents list --json`. If routes exist, their `work_type` selectors are the project's use-case vocabulary (e.g. `frontend`, `backend`, `design`) — and tagging is your job, not the user's; never ask a human to name work types. `map build` seeds every item as `code`, so after building the map, retag each item whose work matches a declared route:
+Before writing the task list, check whether the project declares model routing: `planr agents list --json`. If routes exist, their `work_type` selectors are the project's use-case vocabulary (e.g. `frontend`, `backend`, `design`) — and tagging is your job, not the user's; never ask a human to name work types.
 
-```bash
-planr agents list --json          # route selectors = the use-case vocabulary
-planr map build --from <build-plan-id>
-planr item update <item-id> --work-type frontend   # per item that matches a route
+Declare the use case in the task list itself — `map build` seeds annotated tasks with that work type directly:
+
+```markdown
+### TASK-001 (backend): REST API for todos
+- [ ] (frontend) Build the form and list view
 ```
 
-Match by the item's actual work (UI/components/styling -> a `frontend` route, API/server/storage -> `backend`, and so on). Items matching no route keep `code` — the default route covers them. The payoff: every pick packet then carries the right profile, model, and paired skill for its use case, so dispatch needs no human routing knowledge.
+Match by the task's actual work (UI/components/styling -> a `frontend` route, API/server/storage -> `backend`, and so on); unannotated tasks stay `code`, which the default route covers. For maps that were already built without annotations, retag instead: `planr item update <item-id> --work-type frontend`. The payoff: every pick packet then carries the right profile, model, and paired skill for its use case, so dispatch needs no human routing knowledge.
 
 ## Done
 

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

@@ -30,6 +30,8 @@ Live verification (browser flow, executed binary, real requests) gets its own lo
 planr log add --item <item-id> --kind verification --summary "verified <flow>: <observed outcome>" --cmd "<exact command>"
 ```
 
+The `--cmd` value must be copy-paste replayable: a real shell command (or a small script you committed), never a prose transcript like "start server; curl /; check stats". A reviewer replays your command verbatim — if it cannot run, the verification cannot be independently confirmed.
+
 Log persistent evidence, not transient noise: a failure you immediately fixed belongs in the final log's narrative, not as a standalone failure log. Only record a failure separately when it blocks the item.
 
 Evidence logging refreshes the heartbeat automatically — a separate `planr pick heartbeat` is only needed for long silent stretches without logs.