planr 1.5.0 → 1.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Local-first planning and execution coordination for coding agents.",
   "license": "MIT",
   "repository": {
@@ -23,7 +23,30 @@
     "build:native": "cargo build --release",
     "test": "cargo test",
     "pack:check": "npm pack --dry-run",
-    "routing": "cargo run --manifest-path planr-routing/Cargo.toml --"
+    "docs:dev": "pnpm --filter @planr/docs dev",
+    "docs:alchemy:dev": "pnpm --filter @planr/docs alchemy:dev",
+    "docs:build": "pnpm --filter @planr/docs build",
+    "docs:start": "pnpm --filter @planr/docs start",
+    "docs:deploy": "pnpm --filter @planr/docs run deploy",
+    "docs:destroy": "pnpm --filter @planr/docs run destroy",
+    "docs:content": "pnpm --filter @planr/docs content",
+    "docs:typecheck": "pnpm --filter @planr/docs typecheck",
+    "docs:lint": "pnpm --filter @planr/docs lint",
+    "docs:verify-shell": "pnpm --filter @planr/docs verify:shell",
+    "docs:verify-onboarding": "cargo build --bin planr && pnpm --filter @planr/docs verify:onboarding && pnpm --filter @planr/docs verify:agent-recipes",
+    "docs:verify-agent-recipes": "cargo build --bin planr && pnpm --filter @planr/docs verify:agent-recipes",
+    "docs:verify-agent-markdown": "pnpm docs:build && pnpm --filter @planr/docs verify:agent-markdown",
+    "docs:verify-agent-journey": "pnpm --filter @planr/docs verify:agent-journey",
+    "docs:verify-agent-landing": "pnpm --filter @planr/docs verify:agent-landing",
+    "docs:verify-concepts": "cargo build --bin planr && pnpm --filter @planr/docs verify:concepts",
+    "docs:verify-maintenance": "pnpm --filter @planr/docs verify:maintenance",
+    "docs:verify-deployment": "pnpm --filter @planr/docs verify:deployment",
+    "docs:verify-release": "pnpm --filter @planr/docs verify:release",
+    "docs:verify-release-live": "pnpm --filter @planr/docs verify:release-live",
+    "docs:verify-clean-install": "pnpm --filter @planr/docs verify:clean-install",
+    "verify:switchloom-cross-product": "node scripts/verify-switchloom-cross-product.mjs",
+    "docs:reference:generate": "cargo build --bin planr && pnpm --filter @planr/docs reference:generate",
+    "docs:verify-reference": "cargo build --bin planr && pnpm --filter @planr/docs reference:check && pnpm --filter @planr/docs verify:reference"
   },
   "engines": {
     "node": ">=18"

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.5.0",
+  "version": "1.5.2",
   "author": {
     "name": "instructa"
   },

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

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "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",
@@ -19,7 +19,7 @@
     "category": "Productivity",
     "defaultPrompt": [
       "Use $planr to plan a production-ready app from my idea.",
-      "Use $planr-loop to ship one feature with verification until done."
+      "Use $planr to prepare my next feature and tell me the verified next step."
     ]
   }
 }

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

@@ -37,7 +37,7 @@ The stop condition itself is one command: `planr plan audit <plan-id> --json` ev
 
 ## Iteration Shape
 
-Each iteration is one dispatch through the routing skill — never a hand-written prompt:
+Each iteration follows the Planr stage protocols — never a hand-written workflow prompt:
 
 ```text
 1. planr plan audit <plan-id> --json   contract holds -> exit loop ($planr-status for deeper reads)
@@ -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. 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:
+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 host-native subagent roles (see the role files and `docs/GOALS.md` "Cost Tiering"). Pick packets expose provider-neutral `routing.profile`; they do not expose a host-owned `routing.agent_type`. If an external repository declaration has generated a host role whose identifier exactly matches `routing.profile`, dispatch that profile identifier as the host-native role/`agent_type` through the host's subagent wiring. If no matching repository role exists, keep the host's default dispatch contract and treat the profile as advisory evidence only. Model, effort, profile, client, and fallback fields are advisory declarations and evidence labels only; Planr does not choose a model, choose effort, choose a client, choose a fallback, or infer that a host honored any requested value. The host owns whether and how those declarations can be honored. 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`) and attach route observations when available, so host overrides show up in `planr trace item` as evidence instead of being inferred from declarations. Delegate with skill references plus an item id in the message body, nothing more; host-native dispatch arguments still carry the selected role/profile and isolation controls:
 
 - 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.`
@@ -67,7 +67,8 @@ A worker subagent may take several items sequentially instead of being respawned
 
 Host wiring:
 
-- When a repository routing bundle supplies host roles, follow its generated routing skill exactly. Otherwise treat the profile in the pick packet as advisory and use the host's current dispatch contract. Never infer effective model or effort from a declaration alone.
+- When external repository declarations supply host roles matching pick-packet `routing.profile` values, pass the matching profile identifier as the native host role/`agent_type` and follow the generated role instructions exactly. Otherwise treat the profile in the pick packet as advisory and use the host's current dispatch contract. Never infer effective model or effort from a declaration alone.
+- Codex with native multi-agent roles (stable multi-agent or Multi-Agent v2): generated `.codex/config.toml` roles are matching repository roles. The `spawn_agent` tool call itself must include `agent_type` set exactly to the matching `routing.profile`, `fork_turns` set to `none`, a stable lowercase `task_name`, and the dispatch message above. A default-role maker/checker spawn without `agent_type` is invalid for a generated Codex role; do not wait on it or treat it as a fallback. Do not claim role binding is unavailable for generated Codex roles, and do not substitute the role name into `task_name`, prose, worker identity, or the message body as a replacement for `agent_type`; those are not native role-binding evidence.
 - Claude Code: subagents preload via the `skills:` frontmatter field. The Planr plugin registers `planr-worker` and `planr-reviewer` automatically from its `agents/` directory; standalone installs copy them to `.claude/agents/`. The reviewer subagent is read-only except for `planr review` commands.
 - Cursor: project subagents in `.cursor/agents/*.md` (Markdown templates in `agents/` next to this skill; `planr install cursor` provisions them). Dispatch explicitly: `/planr-worker implement item X`, `/planr-reviewer review item X`. Parallel dispatches are safe — the map's pick lease keeps one owner per item.
 - Single-agent hosts: run worker and checker as separate sequential dispatches with a fresh read of map state in between; never carry the worker's self-assessment into the review step. The mode is recorded automatically: `review close` derives `review_mode` (`single_agent`/`independent`) from worker identity.