planr 0.0.1 → 1.1.16

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

@@ -0,0 +1,25 @@
+{
+  "name": "planr",
+  "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",
+    "url": "https://github.com/instructa"
+  },
+  "homepage": "https://github.com/instructa/planr",
+  "repository": "https://github.com/instructa/planr",
+  "license": "MIT",
+  "keywords": ["planning", "task-graph", "agent-loop", "skills"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Planr",
+    "shortDescription": "Plan, loop, verify, and close coding work with evidence",
+    "longDescription": "Planr turns one product idea into a live task graph and drives features to verified completion. $planr routes any request to the right stage skill from live map state; $planr-loop runs work, live verification, and independent review until the map is clean. Requires the planr CLI (brew install instructa/tap/planr).",
+    "developerName": "instructa",
+    "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."
+    ]
+  }
+}

package/plugins/planr/agents/planr-reviewer.md

@@ -0,0 +1,12 @@
+---
+name: planr-reviewer
+description: Independent findings-first reviewer for one Planr item. Audits evidence and closes the review with a verdict. Dispatch with the item id.
+skills:
+  - planr-review
+---
+
+Use the preloaded planr-review skill exactly as written for the single item id you are given.
+You did not write this code; audit it like an owner. Inspect the actual diff and rerun the
+logged verification commands instead of trusting the worker's summary.
+Close the review with `planr review close <review-id> --verdict ...`. Findings must be specific
+and actionable. Do not edit implementation files; your only writes are planr review commands.

package/plugins/planr/agents/planr-worker.md

@@ -0,0 +1,10 @@
+---
+name: planr-worker
+description: Implements exactly one picked Planr map item to evidence-backed completion, then requests review and stops. Dispatch with the item id.
+skills:
+  - planr-work
+---
+
+Use the preloaded planr-work skill exactly as written for the single item id you are given.
+Implement only that item. Log changed files and the real verification commands you ran.
+Request review with `planr review request <item-id>` and stop. Never close reviews or items yourself.

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

@@ -0,0 +1,52 @@
+---
+name: planr
+description: Single entry point for all Planr work. Use for any product, feature, fix, status, review, or summary request when the user has not named a specific Planr skill. Routes to the right Planr skill from live map state so the user never has to remember skill names.
+---
+
+# Planr Router
+
+You are the dispatcher. Do not improvise workflow prompts; route to one Planr skill and follow it exactly. Skills are the prompts.
+
+## Read State First
+
+Routing is decided by live state, not by guessing:
+
+```bash
+planr project show --json
+planr map show --json
+planr review list --open
+planr approval list --open
+```
+
+If no project exists, initialize before anything else:
+
+```bash
+planr project init "Project Name" --client all
+```
+
+Initialization happens once per repository. If a project already exists, never re-init: new features, refactors, and fixes get their own feature-scoped plan (`planr plan new "Feature"`), and `planr map build --from <build-plan-id>` extends the existing map with new linked items.
+
+## Routing Table
+
+Evaluate top to bottom; pick the first row that matches both intent and state:
+
+| Intent | State condition | Route |
+| --- | --- | --- |
+| "set up a goal", "prepare a /goal run", broad long-running goal not yet planned | no plan or contract for that scope | `planr-goal` (prep only, prints the loop starter) |
+| "build until done", "loop", "finish this feature autonomously" | any | `planr-loop` |
+| status, "what's left", "what's blocked" | any | `planr-status` |
+| summary of completed scope | any | `planr-summary` |
+| new idea, PRD, scope, architecture | no plan, or plan needs refinement | `planr-plan` |
+| new feature, refactor, or fix on an existing project | project exists, scope has no plan yet | `planr-plan` (feature-scoped plan, then extend the map) |
+| plan exists but no map / map needs structure, dependencies, breakdown | build plan checked, map missing or stale | `planr-task-graph` |
+| review requested or open review exists | open review on the map | `planr-review` |
+| implement, fix, continue work | ready items exist on the map | `planr-work` |
+| implement, but nothing is ready | all items blocked | `planr-status`, then report blockers to the user |
+
+## Rules
+
+- Route to exactly one skill per dispatch. If the request spans stages (idea -> running feature), route to `planr-loop` and let the loop sequence the stages.
+- Never skip a stage: no map items without a checked build plan, no closure without review, no review verdict without log evidence.
+- When delegating to a subagent, prompt it with a skill reference plus item id (for example: `Use $planr-work on item <id>`), never with a hand-written workflow prompt.
+- The maker never reviews its own work. Reviews run through `planr-review` in a separate agent or subagent whenever the host supports it.
+- If intent is genuinely ambiguous and state allows multiple routes, ask the user one short question instead of guessing.

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

@@ -0,0 +1,69 @@
+---
+name: planr-goal
+description: Prepare a long-running goal for autonomous execution on Planr. Use when the user states a broad goal, wants to start a /goal run, or asks to set up a goal. Compiles intent into a checked plan, a linked map, and a durable goal contract, then prints the starter command for the host's loop driver without implementing anything.
+---
+
+# Planr Goal
+
+Prep only. This skill compiles a goal into durable Planr state and stops. Execution belongs to the host's loop driver — Codex or Claude Code `/goal`, an automation, or repeated `$planr-loop` dispatches. This boundary is strict: goal prep is a board compiler, not a lightweight loop.
+
+## Boundary
+
+During a goal-prep turn, do not implement, refactor, verify, or touch product code — even when the work looks read-only or obviously useful. That work belongs to the loop run. Allowed actions: read Planr state, ask intake questions, create/refine/check plans, build and link the map, store the goal contract, print the starter command.
+
+## Intake
+
+Classify the input before creating anything:
+
+- specific: outcome and proof are clear -> compile directly.
+- vague: ask at most two material questions (which outcome matters most? what proof would convince you it works?), then proceed with labeled assumptions recorded as `plan refine` notes.
+- existing plan: preserve user-provided steps, files, and constraints as `plan refine` notes; validate them, do not rediscover from scratch, and do not discard them.
+- recovery: read `planr map show --json` and `planr recover sweep` first — the board may already exist. Repair state instead of duplicating it.
+
+Always capture the goal oracle: the observable signal that proves the outcome actually runs — a test run, a live browser flow, an executed CLI binary, real API responses. Weak proof creates weak goals. The oracle becomes the live-verification half of the stop condition and maps to the loop's platform verification (`$planr-verify-web` for web, simulator for ios, executed binary for cli, real requests for api).
+
+## Compile The Board
+
+```bash
+planr project show --json                 # init only if no project exists
+planr plan new "<goal>" --platform <p>
+planr plan refine <plan-id> --note "constraint, assumption, or user-provided plan fact"
+planr plan check <plan-id>                # strict: empty required sections fail
+planr map build --from <plan-id>          # idempotent: safe to re-run
+```
+
+`plan refine` appends notes; the plan body is yours to edit. When `plan check` fails, each warning names the exact file and section — edit that file directly, fill the section with real content, and re-run the check. Scaffold sections (`## Scope Decision`, `## Verification`, `## Acceptance Criteria`) are filled by editing the plan markdown, not by more `refine` notes.
+
+`map build` creates one item per plan step and chains them in plan order with `blocks` links; the output lists the created items and links. Review that chain and adjust it only where execution order differs from document order:
+
+```bash
+planr link add <earlier-item> <later-item> --type blocks
+```
+
+## Store The Goal Contract
+
+The contract must survive compaction, session loss, and host switches, so it lives in Planr, not in chat:
+
+```bash
+planr context add "GOAL CONTRACT <plan-id>: DONE when every in-scope map item is closed with log evidence, all reviews closed with verdict complete, no open approvals in scope, and a live verification log exists for <oracle>. Iteration budget: 10." --tag goal-contract
+```
+
+One contract per plan scope. Any agent on any host can recover it with `planr context list` or `planr search "GOAL CONTRACT"`. Never weaken a stored contract mid-run; scope changes go through `$planr-plan` and the user. During the run, workers lease with `planr pick --plan <plan-id>` so the loop never picks items outside this contract, even when other plans share the board. The loop checks the contract with `planr plan audit <plan-id>`, which evaluates exactly these clauses with evidence and answers `holds: true/false`.
+
+## Hand Off
+
+Print the starter command, then stop. Do not start execution yourself; ask whether to start now, refine the plan, or stop.
+
+With a native loop driver (Codex `/goal`, Claude Code `/goal` or `/loop`):
+
+```text
+/goal Use $planr-loop on plan <plan-id>. The loop contract is stored in planr context (tag: goal-contract). Continue until the contract holds or the iteration budget is exhausted.
+```
+
+Without one (Cursor, plain MCP clients, Codex without /goal):
+
+```text
+Use $planr-loop on plan <plan-id>. The loop contract is stored in planr context (tag: goal-contract).
+```
+
+Re-dispatch the same line after any session ends. The map, logs, and stored contract make every iteration resumable from zero context — nothing about the goal lives only in chat.

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

@@ -0,0 +1,114 @@
+---
+name: planr-loop
+description: Drive one feature or scope to verified completion without per-step human prompting. Use when the user says build until done, loop on this, or finish autonomously. Sequences plan, map, work, live verification, and independent review until the map is clean and evidence proves the feature actually runs.
+---
+
+# Planr Loop
+
+A closing loop: the agent prompts itself with Planr skills until a verifiable stop condition holds. The human supplies the goal at the start and reviews at the end; the map is the loop memory between iterations.
+
+This skill is the iteration protocol, not the driver. Whoever re-prompts the next iteration — a native loop primitive like Codex `/goal`, an automation, or a human re-dispatching `$planr-loop` — acts as the orchestrator and follows this protocol verbatim. The protocol is identical on every host; only the re-dispatch mechanism differs (see Loop Drivers).
+
+## Loop Contract
+
+Before iterating, pin the contract:
+
+1. One goal: a single feature, fix scope, or build plan. Refuse multi-goal loops; split them first.
+2. A stop condition that a different agent can check from map state and evidence, not from the worker's claims.
+3. An iteration budget (default: 10 iterations). When exhausted, stop and report honestly instead of grinding.
+
+Stop condition template:
+
+```text
+DONE when: every in-scope map item is closed with log evidence,
+all reviews closed with verdict complete, no open approvals in scope,
+and a live verification log exists for the feature on its target platform.
+```
+
+Store the contract in Planr so it survives compaction, session loss, and host switches — chat memory is not loop memory:
+
+```bash
+planr context add "GOAL CONTRACT <plan-id>: DONE when ... Iteration budget: 10." --tag goal-contract
+```
+
+`$planr-goal` does this during prep; if the loop starts without a stored contract, store it in iteration 1 before picking. Every iteration re-reads the contract from Planr (`planr context list` or `planr search "GOAL CONTRACT"`), never from chat history. `done`, `close`, and `review close` responses and the pick packet include a `remaining` progress snapshot (`counts` with explicit zeros for every status, `settled`, `total`) plus the list of items each settlement `unlocked`, so the orchestrator can evaluate the stop condition from the completion output without an extra `map status` call.
+
+The stop condition itself is one command: `planr plan audit <plan-id> --json` evaluates the contract clause by clause (items settled, reviews complete, approvals clear, verification logged) with evidence and answers `holds: true/false`. Use it at the top of every iteration and as the final audit — never hand-assemble the verdict from separate calls.
+
+## Iteration Shape
+
+Each iteration is one dispatch through the routing skill — never a hand-written prompt:
+
+```text
+1. planr plan audit <plan-id> --json   contract holds -> exit loop ($planr-status for deeper reads)
+2. $planr-plan / $planr-task-graph   only if scope or map structure is missing
+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 --kind verification
+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` (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. `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.
+
+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
+
+When the host supports subagents, 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.`
+
+Host wiring:
+
+- Codex: project agents in `.codex/agents/*.toml` preload the skill via `[[skills.config]]` (TOML templates in `agents/` next to this skill). Spawn explicitly: "spawn the planr_worker agent for item X". Keep `[agents] max_depth = 1`.
+- 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.
+- 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.
+
+## Live Verification By Platform
+
+"Done" means the feature ran, not that it compiles. Pick the verification from the plan's platform (`planr plan new ... --platform <p>`), run it inside step 4, and log the exact command and outcome:
+
+| Platform | Verification |
+| --- | --- |
+| `web` | dispatch `$planr-verify-web`: discovers the host's browser capability, runs the changed flow against the dev server, logs a replayable command |
+| `ios` | build and launch in the simulator (`xcodebuild` + `xcrun simctl`), exercise the changed flow |
+| `cli` | execute the built binary with the real flags the feature added; assert on output |
+| `api`/`backend` | start the service, hit the changed endpoints with real requests, assert responses |
+
+```bash
+planr log add --item <item-id> --kind verification \
+  --summary "live verification on <platform>: <observed outcome>" \
+  --cmd "<exact command actually run>"
+```
+
+`--kind verification` is what `plan audit` checks for its `verification_logged` clause. Log the final passing run; a transient failure you immediately fixed belongs in the summary narrative, not as a separate failure log.
+
+If the needed capability is missing (no simulator, no browser tooling), do not fake it: log the gap as context, request human approval, and pause the loop:
+
+```bash
+planr context add "live verification blocked: <missing capability>" --item <item-id> --tag blocker
+planr approval request <item-id> --reason "manual live verification required"
+```
+
+## Loop Drivers
+
+Prefer the host's loop primitive over a bash while-loop so a separate model checks the stop condition. The driver supplies continuation pressure; Planr supplies everything else (state, evidence, reviews, recovery), so the loop works on every host:
+
+- Codex: `/goal Use $planr-loop on plan <plan-id>. The loop contract is stored in planr context (tag: goal-contract).` — or an Automation with the same prompt. Full workflow: `docs/GOALS.md` in the Planr repository.
+- Claude Code: `/goal` with the same prompt shape, or `/loop` for a fixed cadence.
+- Anywhere else (Cursor, plain MCP clients, hosts without /goal): re-dispatch `Use $planr-loop on plan <plan-id> ...` manually or per session. Nothing is lost except automatic re-prompting.
+
+Recovery is the same in all cases: a fresh session starts at step 1 (`$planr-status`), reads the map and the stored goal-contract, and continues exactly where the last iteration stopped — zero chat context required.
+
+## Hard Rules
+
+- One picked item per iteration. Parallel work needs separate worktrees and separate loop instances.
+- Every iteration must move map state (a log, a review verdict, a closed item, or a recorded blocker). Two iterations without state movement -> stop and report.
+- Never weaken the stop condition mid-loop. Scope changes go through `$planr-plan` and the user.
+- Destructive or out-of-repo side effects (deploys, migrations, infra) always go behind `planr approval request`.
+- On exit — success or budget exhausted — finish with `$planr-summary` so the human gets an evidence-backed account.

package/plugins/planr/skills/planr-loop/agents/planr-reviewer.toml

@@ -0,0 +1,17 @@
+# Copy to .codex/agents/planr-reviewer.toml (project) or ~/.codex/agents/ (user).
+# Adjust the skill path to where the Planr skills are installed.
+name = "planr_reviewer"
+description = "Independent findings-first reviewer for one Planr item. Audits evidence and closes the review with a verdict."
+sandbox_mode = "workspace-write"
+
+developer_instructions = """
+Use the planr-review skill exactly as written for the single item id you are given.
+You did not write this code; audit it like an owner. Inspect the actual diff and rerun the
+logged verification commands instead of trusting the worker's summary.
+Close the review with `planr review close <review-id> --verdict ...`. Findings must be specific
+and actionable. Do not edit implementation files; your only writes are planr review commands.
+"""
+
+[[skills.config]]
+path = "~/.codex/skills/planr-review/SKILL.md"
+enabled = true

package/plugins/planr/skills/planr-loop/agents/planr-worker.toml

@@ -0,0 +1,14 @@
+# Copy to .codex/agents/planr-worker.toml (project) or ~/.codex/agents/ (user).
+# Adjust the skill path to where the Planr skills are installed.
+name = "planr_worker"
+description = "Implements exactly one picked Planr map item to evidence-backed completion, then requests review and stops."
+
+developer_instructions = """
+Use the planr-work skill exactly as written for the single item id you are given.
+Implement only that item. Log changed files and the real verification commands you ran.
+Request review with `planr review request <item-id>` and stop. Never close reviews or items yourself.
+"""
+
+[[skills.config]]
+path = "~/.codex/skills/planr-work/SKILL.md"
+enabled = true

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

@@ -0,0 +1,58 @@
+---
+name: planr-plan
+description: Create or refine Planr product plans and build plans before implementation. Use for app ideas, PRDs, architecture slices, scoped implementation contracts, and converting broad work into map-ready items.
+---
+
+# Planr Plan
+
+Use this when scope, ownership, acceptance criteria, or verification must be defined before implementation.
+
+## Workflow
+
+```bash
+planr project show --json
+planr plan new "App idea" [--platform web] [--ai] [--backend]
+planr plan refine <plan-id> --note "decision, constraint, or assumption"
+planr plan check <plan-id>
+planr plan split <plan-id> --slice "narrow implementation slice"
+planr map build --from <build-plan-id>
+```
+
+## Product Plan Standard
+
+A product plan package must include:
+
+- manifest;
+- product spec;
+- UX flows;
+- design system;
+- architecture;
+- ADRs;
+- AI spec when relevant;
+- safety/privacy/security;
+- API/data model;
+- client and backend implementation specs;
+- observability;
+- QA;
+- release readiness;
+- executable tasks;
+- references.
+
+## Build Plan Standard
+
+A build plan must include:
+
+- source plan;
+- scope decision;
+- ownership target;
+- existing leverage;
+- phases;
+- out of scope;
+- verification;
+- acceptance criteria.
+
+## Done
+
+Planning is complete only when `planr plan check <plan-id>` passes and the next command is clear: split further, build map, or ask the user for a blocking decision.
+
+`plan check` rejects empty scaffolds: build plans must have content in `## Scope Decision`, `## Verification`, and `## Acceptance Criteria`; product plans must have content in `## Problem`, `## Requirements`, and `## Success Criteria` of `PRODUCT_SPEC.md`. Write those sections before checking — do not pad them to satisfy the gate.

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

@@ -0,0 +1,51 @@
+---
+name: planr-review
+description: Review a Planr item or scoped implementation against map state, plan acceptance criteria, logs, changed files, and verification evidence. Use for findings-first audits and review gates.
+---
+
+# Planr Review
+
+Use this when a task needs a correctness and completion audit.
+
+## Workflow
+
+Export your checker identity once per session so the lease attributes to you:
+
+```bash
+export PLANR_WORKER_ID=checker-1
+planr --json pick --work-type review
+```
+
+`--work-type review` leases only review items, so a checker never accidentally takes maker work. Add `--plan <plan-id>` when your dispatch names a plan so the lease stays inside that scope. The pick packet inlines the target item and its evidence logs under `target` — one command is enough to see what is being audited, its status (`in_review` while waiting on you), files, and verification commands. If you already hold a review id, `planr --json trace item <review-id>` returns the same packet. Use `planr log list --item <target-id>` or `planr map show --json` only for deeper reads.
+
+Inspect the actual changed files and re-run the logged verification evidence. Then close the review exactly once:
+
+```bash
+planr review close <review-id> --verdict complete --reviewer <your-id> --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. `--reviewer` records your checker identity on the log, artifact, and event so maker and checker stay distinguishable in the audit trail. A second close of the same review fails with `already_closed` — never retry a close that succeeded.
+
+or:
+
+```bash
+planr review close <review-id> --verdict not-complete --reviewer <your-id> --findings "specific actionable finding"
+```
+
+## Findings Rules
+
+- Findings must be specific and actionable.
+- Missing tests are findings when acceptance criteria need proof.
+- Architecture or ownership drift is a finding when it creates duplicate policy or state owners.
+- If evidence is insufficient, use `--verdict unclear` rather than complete.
+
+## 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.
+
+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
+
+The target item may close only after required review items are closed. Use the map as the source of truth.
+Pending or denied approval is also a close blocker; treat an attempted close through that gate as a finding, not as completion.

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

@@ -0,0 +1,50 @@
+---
+name: planr-status
+description: Report honest Planr project, map, item, or review state without implementing changes. Use when the user asks what is done, what remains, what is blocked, what is ready, or what should be picked next.
+---
+
+# Planr Status
+
+Use read-only Planr commands first:
+
+```bash
+planr project show --json
+planr map show --json
+planr map lane --critical
+planr map pressure
+```
+
+For one item:
+
+```bash
+planr trace item <item-id>
+planr log list --item <item-id>
+```
+
+For active work, include runtime and approval state from `trace item`, `map status`, or:
+
+```bash
+planr approval list --open
+planr pick stale --older-than-seconds 900
+```
+
+## Goal Contract Check
+
+When a loop or `/goal` run asks whether its stop condition holds, use the one-call verdict:
+
+```bash
+planr plan audit <plan-id> --json
+```
+
+It reads the stored contract, evaluates every clause with evidence (items settled, reviews complete, approvals clear, verification logged), and answers `holds: true/false` with the open items listed per clause. Report `contract holds` or `contract open` plus the exact unmet clauses straight from the audit output. Use `planr search "GOAL CONTRACT"` only to read the contract text itself.
+
+## Verdicts
+
+Use one:
+
+- `complete`: closed with evidence and no open required child/review/approval work.
+- `in progress`: concrete work remains and the next step is available.
+- `blocked`: progress needs an external decision or prerequisite.
+- `unclear / partially verified`: evidence is incomplete or inconsistent.
+
+Never treat checked Markdown boxes or optimistic summaries as proof. Map state and log evidence decide.

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

@@ -0,0 +1,28 @@
+---
+name: planr-summary
+description: Summarize a Planr scope after work, review, or status inspection. Use when the user wants what changed, why, what works now, verification evidence, and what remains.
+---
+
+# Planr Summary
+
+Build the summary from current Planr evidence:
+
+```bash
+planr map show --json
+planr trace item <item-id>
+planr log list --item <item-id>
+```
+
+## Output
+
+Include:
+
+- scope;
+- what changed;
+- why;
+- what works now;
+- verification commands and results;
+- open blockers or unverified items;
+- next recommended Planr command.
+
+If completion is not proven, say so directly and recommend `planr-status`, `planr-work`, or `planr-review`.