planr - npm Package Compare versions

Comparing version 1.2.0 to 1.3.0-alpha.1

docs/HOOKS.md

+# 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).

docs/CLI_REFERENCE.md

@@ -33,2 +33,3 @@ # CLI Reference
 planr link add <from-item> <to-item> --type blocks
+planr prime [--hook-json]
 planr pick [--work-type <type>] [--plan <plan-id>] [--peek]
@@ -69,3 +70,3 @@ planr pick release <item-id> [--force]
 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]
@@ -132,2 +133,4 @@ planr prompt routing [--client codex|claude|cursor|all]
 
+`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.
@@ -134,0 +137,0 @@

docs/fixtures/mcp-contract.json

@@ -91,2 +91,4 @@ {
     "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",
@@ -93,0 +95,0 @@ "planr review annotate",

package.json

 {
   "name": "planr",
-  "version": "1.2.0",
+  "version": "1.3.0-alpha.1",
   "description": "Local-first planning and execution coordination for coding agents.",
@@ -5,0 +5,0 @@ "license": "MIT",

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

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

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

 {
   "name": "planr",
-  "version": "1.2.0",
+  "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.",
@@ -5,0 +5,0 @@ "author": {

README.md

@@ -25,2 +25,26 @@ # Planr
 
+## 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
@@ -141,2 +165,3 @@
 - [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)
@@ -143,0 +168,0 @@ - [MCP Guide](docs/MCP_GUIDE.md)

New alerts

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Improved metrics

Total package byte prevSize

23992076

0.83%

Number of package files

67

1.52%

Lines of code

188

1.08%

Number of lines in readme file

179

16.23%

Worsened metrics

Number of low quality alerts

2

100%

No dependency changes