planr 0.0.1 → 1.1.15

package/docs/OPERATING_MODEL.md

@@ -0,0 +1,250 @@
+# Planr Operating Model
+
+Planr coordinates coding-agent work through two durable surfaces:
+
+- the Markdown plan package for product, build, architecture, verification, and narrative context;
+- the SQLite map for item state, links, picks, reviews, logs, contexts, and closure.
+
+The map is the source of truth for live state. Markdown explains why the work exists and what good completion means.
+
+## Operator Start
+
+Start every session by reading the current project and graph state:
+
+```bash
+planr project show --json
+planr map show --json
+planr map lane --critical
+planr map pressure
+```
+
+If the repository has no Planr project yet:
+
+```bash
+planr project init "Project Name" --client all
+planr doctor --client all
+```
+
+Use `--db <path>` for isolated runs and tests.
+
+## Canonical Flow
+
+The default product flow is:
+
+```text
+idea -> product plan -> build plan -> map -> pick -> log -> review/evidence -> recovery/package -> close
+```
+
+Use product and build plans for broad scope:
+
+```bash
+planr plan new "App idea" --platform web --ai --backend
+planr plan refine <plan-id> --note "decision or assumption"
+planr plan split <plan-id> --slice "MVP implementation"
+planr plan check <build-plan-id>
+planr map build --from <build-plan-id>
+```
+
+Product-plan task lists are candidates. Work becomes a live commitment only after it is in the map.
+
+## Daily Agent Loop
+
+Agents should work one map item at a time. The short path is:
+
+```bash
+planr pick --json
+planr done <item-id> --summary "what changed" --files a --files b --cmd "exact verification command" --review [--next]
+```
+
+`pick --json` returns one flat work packet (item, links, logs, runtime, recovery, conditions, recall context, `remaining` progress), so no separate `trace item` call is needed. `pick --work-type review` (or `code`) keeps checker and maker leases separate, and a null pick always carries a `reason` plus the `remaining` snapshot. `done` writes the completion log, then requests review (`--review`) or closes directly, and `--next` picks the following item. Evidence logging refreshes the heartbeat, so explicit `pick heartbeat` calls are only needed during long silent stretches.
+
+For longer work, update runtime state instead of relying on chat history:
+
+```bash
+planr pick progress <item-id> --percent 50 --note "implementation done, tests running"
+planr pick pause <item-id> --note "waiting for human decision"
+planr pick resume <item-id>
+```
+
+If a previous worker disappears, inspect stale picks before taking over:
+
+```bash
+planr pick stale --older-than-seconds 900
+planr pick stale --older-than-seconds 900 --release
+planr recover sweep --older-than-seconds 900
+planr recover sweep --older-than-seconds 900 --apply
+```
+
+Use `pick stale --release` for a targeted stale-claim reset. Use `recover sweep --apply` when you also want timed-out work and retryable failed work handled in the same explicit recovery pass.
+
+Record discoveries that future work needs:
+
+```bash
+planr context add "decision or discovery" --item <item-id> --tag discovery
+```
+
+Record completion evidence before asking for review:
+
+```bash
+planr log add --item <item-id> \
+  --summary "what changed" \
+  --files path-a,path-b \
+  --cmd "exact verification command"
+```
+
+Request and close review:
+
+```bash
+planr review request <item-id>
+planr review annotate <item-id> --message "review note" --severity warning
+planr review evidence <item-id> --pr-url https://example.invalid/pr/123
+planr review ingest <item-id> --from .planr/tmp/review-feedback.json
+planr review close <review-id> --verdict complete --close-target
+```
+
+With `--close-target` a complete verdict also closes the reviewed item (it must already carry a completion log); otherwise finish with `planr close <item-id> --summary "Verified with evidence"`.
+
+`review evidence` records Git branch, commit, dirty state, item-scoped changed-file provenance, and optional PR URL context without treating unrelated dirty files as proof. Review ingestion records hook-compatible JSON feedback as contexts and logs only. It does not close the review, approve the item, or unblock downstream work.
+
+For a browser-based local review pass:
+
+```bash
+planr serve --port 7526
+open http://127.0.0.1:7526/review
+```
+
+The review workspace shows review queues, linked plans, item evidence, diff-safe Git evidence, annotations, and approve/request-changes actions over the same local HTTP API.
+
+Use approvals when a human decision must block closure:
+
+```bash
+planr approval request <item-id> --reason "release approval"
+planr approval approve <item-id> --by "human reviewer"
+```
+
+Pending or denied approval blocks `planr close`; use `planr map preview --close <item-id>` to inspect the gate before mutating state.
+
+If review finds issues:
+
+```bash
+planr review close <review-id> \
+  --verdict not-complete \
+  --findings "specific actionable finding"
+planr review artifact <review-id>
+planr map show --json
+planr pick --json
+```
+
+Review findings create follow-up work and write a `.planr/reviews/*.review.md` artifact. Do not mark the original item complete by summarizing the finding away.
+
+## Parent Gate Pattern
+
+Model material changes as parent gates. The parent is not the work package; its linked children are.
+
+```text
+parent gate
+`- implementation or test child
+   `- review item linked to that child
+      |- pass -> child can close -> parent gate auto-closes
+      `- findings -> fix item -> follow-up review -> ...
+```
+
+Rules:
+
+- create one parent item for the change;
+- use `planr item breakdown <parent-id> --into "Implement, Verify"` to create child work under the parent;
+- 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;
+- downstream top-level work should depend on the parent gate, not on the first implementation child.
+
+This keeps later work blocked until review is actually clean.
+
+Parent gates roll up automatically: once every child is closed or cancelled, the gate becomes ready and auto-closes when no review or approval on the gate itself is open (a cancelled or partially closed child rolls up as `closed_partial`). Parent gates are never returned by `planr pick`; the children are the work.
+
+## Notes, Contexts, Logs, And Stories
+
+Use the smallest durable surface that fits the information:
+
+- `planr log add`: proof that work happened, including files, commands, tests, review results, and handoff facts.
+- `planr context add`: a project or item discovery that another future item may need.
+- `planr note add`: a short task-local note when a human or agent needs nearby context.
+- Story logs: longer narrative history when graph state and short contexts are too thin.
+
+Story logs are narrative memory, not status authority. The map remains authoritative for state.
+
+See [HANDOFFS_AND_STORIES.md](HANDOFFS_AND_STORIES.md) for file placement and contents.
+
+## Recovery
+
+After interruption, compaction, or agent handoff:
+
+```bash
+git status --short
+planr project show --json
+planr map show --json
+planr map lane --critical
+planr map pressure
+```
+
+Then inspect the current item:
+
+```bash
+planr trace item <item-id>
+planr log list --item <item-id>
+planr context list --item <item-id>
+```
+
+If ownership must be reset:
+
+```bash
+planr pick stale --older-than-seconds 900
+planr pick release <item-id> --force
+```
+
+Use force only when the prior owner is gone or the operator intentionally resets the claim.
+
+For broad interruption recovery, prefer the explicit sweeper:
+
+```bash
+planr recover sweep --older-than-seconds 900
+planr recover sweep --older-than-seconds 900 --apply
+```
+
+The preview reports stale picks, timed-out work, retryable failures, retry delays, and manual pre/post conditions. The apply mode mutates only the listed recoverable work and records recovery events.
+
+## Packages And Sharing
+
+Use packages for local backups and reusable templates:
+
+```bash
+planr export --include-plans --include-logs --template-name "Backend slice" --tag api --out planr-package.json
+planr import planr-package.json --preview
+planr import planr-package.json --confirm
+```
+
+Import is preview-first. Confirmed import restores graph items, links, contexts, logs, plan file snapshots, and review artifacts into the current project. Encrypted sharing can wrap the JSON package with a local tool such as `age` or `gpg`; Planr does not require a hosted share service.
+
+## Agent Prompts
+
+Use prompt output when configuring agents without editing global config:
+
+```bash
+planr prompt cli --client codex
+planr prompt mcp --client all
+planr prompt http
+```
+
+Prompt commands print ready-to-use setup and operating instructions and report that global config was not edited.
+
+## Completion Rule
+
+Do not call a scope complete until all of these are true:
+
+- required child and review items are closed;
+- log evidence records exact files and commands;
+- verification commands were actually run;
+- review findings are closed or converted into follow-up work;
+- `planr map show --json` has no in-scope blocker;
+- the summary matches the map, logs, and review state.
+
+For release-grade scopes, rerun the full verification ladder in [TESTING.md](TESTING.md).

package/docs/RELEASE.md

@@ -0,0 +1,140 @@
+# Release
+
+Planr V1 releases are built from the Rust binary, public docs, skills, and public assets. The canonical public release source is `https://github.com/instructa/planr`.
+
+The v1 repository-owned public install order is:
+
+1. GitHub Release curl installer.
+2. Manual GitHub Release asset download.
+3. Homebrew after the tap/formula is published.
+4. npm (`npm install -g planr`) with bundled platform binaries.
+5. Cargo/source builds for maintainers and contributors.
+
+Published npm versions bundle platform-native binaries; see `docs/NPM.md`.
+
+## Version Bump
+
+`scripts/release.sh` is the only supported release path. The version lives in one source (`Cargo.toml`) and four distribution manifests must carry it: `Cargo.toml`, `package.json`, `plugins/planr/.codex-plugin/plugin.json`, and `plugins/planr/.claude-plugin/plugin.json`. Manual tagging skips the manifest sync and ships stale plugin versions.
+
+```bash
+scripts/release.sh 1.2.0 "one-line release summary"
+```
+
+The script enforces, in order:
+
+1. branch is `main`, worktree is clean, `CHANGELOG.md` already has a committed `## [x.y.z]` section, and the tag does not exist;
+2. the version is written into all four manifests plus `Cargo.lock`;
+3. gates: `cargo test` (includes the manifest drift guard in `tests/e2e.rs`), `npm pack --dry-run`, and `scripts/security-local.sh` (betterleaks + trivy leak gate);
+4. one mechanical commit `release x.y.z: <summary>`, tag `vx.y.z`, and a single push of branch plus tag.
+
+Two independent gates back the script:
+
+- `cargo test` fails on every push when any manifest version drifts from `Cargo.toml`.
+- The release workflow's `Verify release versions are consistent` step refuses the tag when the tag, any manifest, or the `CHANGELOG.md` section disagree.
+
+## Automated Release Pipeline
+
+Pushing a tag `vX.Y.Z` runs `.github/workflows/release.yml`:
+
+1. `create-release` verifies the tag against `Cargo.toml`, all distribution manifests, and the changelog section, then creates a draft GitHub Release.
+2. `build` compiles and packages `planr-<os>-<arch>.tar.gz` for `darwin-arm64`, `darwin-x86_64`, `linux-x86_64`, and `linux-arm64`, then uploads each asset to the draft release.
+3. `finalize` downloads all uploaded assets, writes one aggregated `SHA256SUMS` covering every tarball, uploads it, and publishes the release.
+4. `npm-publish` downloads the release assets, verifies them against `SHA256SUMS`, bundles the four platform binaries into `npm/native/`, smoke-tests the wrapper, and publishes to npm via Trusted Publishing (OIDC). Runs only when the repository variable `NPM_PUBLISH_ENABLED` is `true`; requires the one-time Trusted Publisher setup described in `docs/NPM.md`.
+5. `homebrew-tap` regenerates `Formula/planr.rb` with `scripts/generate-formula.sh` and pushes it to `instructa/homebrew-tap` (installed as `brew install instructa/tap/planr`).
+
+## Changelog
+
+`CHANGELOG.md` at the repository root is the persistent release log ([Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format). Maintain it continuously, not at release time only:
+
+- Every user-visible change (CLI surface, JSON envelope, skills, MCP/HTTP contract, install paths) lands in the `[Unreleased]` section in the same PR or commit that makes the change.
+- Before pushing a release tag, rename `[Unreleased]` to the new version with the release date, add a fresh empty `[Unreleased]` section, and update the compare links at the bottom. The tag must not ship with a non-empty `[Unreleased]` section describing its own changes.
+- The version section is the source for the GitHub Release notes body.
+
+The Homebrew job only runs when the repository variable `HOMEBREW_TAP_ENABLED` is `true` and requires a `TAP_GITHUB_TOKEN` secret with write access to `instructa/homebrew-tap`. The tap repository must exist before enabling it.
+
+## Preflight
+
+Run:
+
+```bash
+scripts/ci-local.sh
+scripts/security-local.sh
+```
+
+The external consumer E2E suite must pass when available on the release machine.
+
+## Build Artifact
+
+Create the local release artifact:
+
+```bash
+scripts/build-release.sh
+cat dist/planr-*/SHA256SUMS
+```
+
+The artifact contains:
+
+- `planr`
+- `README.md`
+- `LICENSE.md`
+- `SHA256SUMS`
+
+The GitHub Release upload asset is:
+
+- `dist/planr-<os>-<arch>.tar.gz`
+
+The tarball checksum is written to `dist/SHA256SUMS`.
+
+The release installer downloads and verifies `SHA256SUMS` from the same release URL unless `PLANR_SKIP_CHECKSUM=1` is set for a development mirror.
+
+## npm Dry-Run
+
+Verify npm package contents as a development-package check:
+
+```bash
+npm pack --dry-run
+```
+
+The package must include:
+
+- `npm/bin/planr.js`
+- `docs/`
+- `docs/MCP_CONTRACT.md`
+- `docs/fixtures/mcp-contract.json`
+- `plugins/`
+- `README.md`
+- `LICENSE.md`
+
+`npm/native/` platform binaries exist only in the `npm-publish` CI job; the local dry-run does not include them.
+
+## Install Smoke
+
+After building:
+
+```bash
+node npm/bin/planr.js --version
+PREFIX="$(mktemp -d)" scripts/install.sh
+PLANR_BIN="$(find dist -path '*/planr' -type f | head -n 1)" PREFIX="$(mktemp -d)" scripts/install.sh
+```
+
+Then run:
+
+```bash
+PLANR_BIN=planr npm run test:npm-planr
+```
+
+from the external consumer E2E project.
+
+## Release Notes Checklist
+
+Before publishing, record:
+
+- `CHANGELOG.md` updated: `[Unreleased]` rolled into the tagged version section;
+- exact commit or source snapshot;
+- `cargo test` result;
+- consumer E2E result;
+- `npm pack --dry-run` file list;
+- release artifact checksum;
+- GitHub Release asset name and checksum;
+- security/leak scan result;
+- known risks or intentionally unsupported platforms.

package/docs/SECURITY.md

@@ -0,0 +1,8 @@
+# Security And Privacy
+
+- Planr is local-first and stores V1 data in the configured SQLite database and `.planr` files.
+- No content telemetry is emitted by default.
+- Shell commands are not run by Planr unless the user explicitly runs them outside Planr or records them as evidence.
+- HTTP binds to `127.0.0.1`.
+- Destructive operations require confirmation or preview flags.
+- Logs, contexts, and inline artifact content are checked by `planr scrub` for common secret-looking patterns. `planr scrub --confirm` rewrites flagged values in place with `[REDACTED]` markers, updates the search index, and records a `secret_scrubbed` event per rewritten row.

package/docs/SKILLS.md

@@ -0,0 +1,278 @@
+# Planr Skills
+
+Planr ships agent-facing skill templates under `plugins/planr/skills/`.
+
+The repository ships an installable plugin under `plugins/planr` for Codex, Claude Code, and Cursor, so the skills can be installed as one package instead of copied by hand. Marketplace manifests at the repo root (`.agents/plugins/marketplace.json`, `.claude-plugin/marketplace.json`) point at that subdirectory — Codex silently ignores marketplaces whose plugin source is the repo root itself. The plugin only carries skills and agent roles; the `planr` CLI must be installed separately (`brew install instructa/tap/planr`).
+
+## Install As Plugin (preferred)
+
+Codex:
+
+```bash
+codex plugin marketplace add instructa/planr
+# then install "planr" from the plugin directory picker, or:
+codex plugin add planr@planr
+```
+
+Claude Code:
+
+```text
+/plugin marketplace add instructa/planr
+/plugin install planr@planr
+```
+
+Skills are namespaced in Claude Code: `/planr:planr`, `/planr:planr-loop`. The plugin also registers the `planr-worker` and `planr-reviewer` subagents from the plugin's `agents/` directory.
+
+Cursor: pending marketplace review; until listed, use MCP plus the CLI prompt (below).
+
+opencode: no plugin yet; use `planr mcp` as an MCP server (below). A JS plugin wrapping the CLI as custom tools is a possible follow-up.
+
+## Included Skills
+
+Entry points (what users invoke):
+
+- `planr`: master router. One entry point for any request; reads live map state and dispatches to the right skill. Users do not need to remember skill names.
+- `planr-goal`: goal prep compiler for long-running runs. Turns a broad goal into a checked plan, a linked map, and a durable goal contract (`planr context --tag goal-contract`), then prints the starter command for the host's loop driver (Codex/Claude Code `/goal`, or manual re-dispatch). Prep only — see [Long-Running Goals](GOALS.md).
+- `planr-loop`: autonomous closing loop. Drives one feature to verified completion — work, live verification, independent review, fix items — until the map is clean or the iteration budget runs out. Ships subagent templates under `plugins/planr/skills/planr-loop/agents/`.
+
+Capability skills (dispatched by the loop's live-verification step):
+
+- `planr-verify-web`: proves a web feature runs in a browser. Discovers the host's existing browser capability (browser skill, browser MCP, `npx playwright`, HTTP checks as last resort), records the choice as a `capability` context, and logs replayable evidence. Ships no browser tooling itself.
+
+Stage skills (what the router and loop dispatch to; also directly invocable):
+
+- `planr-task-graph`: active task graph coordination with plans, parent gates, map items, picks, runtime state, approvals, logs, reviews, handoffs, stories, and recovery.
+- `planr-plan`: product and build planning.
+- `planr-work`: one picked item to evidence-backed completion.
+- `planr-review`: findings-first review gates.
+- `planr-status`: honest read-only status.
+- `planr-summary`: evidence-backed summaries.
+
+## Cheat Sheet
+
+Default usage needs two skills:
+
+```text
+$planr        any request -> routed to the right stage skill from live map state
+$planr-loop   one feature -> loop work/verify/review/fix until done or budget exhausted
+$planr-goal   broad goal -> plan + map + durable contract + starter for /goal or manual loops
+```
+
+The stage order the router follows for a new app:
+
+```text
+$planr-plan        idea -> product plan -> build plan
+$planr-task-graph  build plan -> map -> dependencies -> critical lane
+$planr-work        pick one ready item -> implement -> log evidence -> request review
+$planr-review      audit evidence -> complete or create fix work
+$planr-work        pick generated fix work when review finds issues
+$planr-status      report honest state, blockers, and next ready work
+$planr-summary     summarize completed scope with evidence
+```
+
+Example first prompt for a Habit Tracker:
+
+```text
+Use $planr.
+
+Create a production-ready Habit Tracker web app plan. Include habits, daily check-ins,
+streaks, weekly overview, local-first persistence, tests, privacy, and release readiness.
+Create the product plan, split an MVP build plan, check it, then build the Planr map.
+Do not implement yet. End with the build plan id, critical lane, and first ready items.
+```
+
+Example autonomous feature loop:
+
+```text
+Use $planr-loop.
+
+Goal: ship the weekly overview feature. DONE when every in-scope map item is closed with
+log evidence, all reviews are closed complete, and a live verification log shows the
+overview rendering real check-in data in the browser. Iteration budget: 10.
+```
+
+Example single implementation step (human-in-the-loop):
+
+```text
+Use $planr-work.
+
+Pick exactly one ready Habit Tracker item. Implement only that item, keep Planr runtime
+state current, log changed files and real verification commands, then request review.
+Do not close the item until review is complete.
+```
+
+## Two Journeys: New Project vs. Existing Project
+
+Both journeys use the same entry point (`$planr` or `$planr-loop`). What differs is the state the router finds, and what kind of plan the work gets.
+
+### Journey 1 — start a project from an idea
+
+Initialize once per repository, then hand the idea to the router:
+
+```bash
+planr project init "Habit Tracker" --client all
+```
+
+```text
+Use $planr.
+
+Create a production-ready Habit Tracker web app plan. Create the product plan,
+split an MVP build plan, check it, then build the Planr map. Do not implement yet.
+```
+
+The router runs the full stage order: product plan -> build plan -> map -> work. From there, `$planr-loop` or `$planr-work` executes against the map.
+
+### Journey 2 — mid-project: add a feature, refactor, or fix
+
+Never re-run `project init`; the project and map already exist. Every new scope — a feature like an auth system, a refactor, a non-trivial fix — gets its own feature-scoped plan on the same map:
+
+```text
+Use $planr.
+
+Add an auth system (email+password, sessions, protected routes) to this app.
+Create a feature plan for it, record what existing code it builds on, split a
+narrow build slice, check it, and extend the map with linked items. Do not implement yet.
+```
+
+What the router does with that, and why:
+
+1. `$planr-plan` creates a new plan scoped to the feature (`planr plan new "Auth system" ...`), not a new project. Refine notes capture constraints from the existing codebase; the build plan's "existing leverage" field records what is reused instead of rebuilt.
+2. `$planr-task-graph` extends the existing map: new items, plus `blocks` links to anything already on the map that must land first.
+3. Execution is identical to journey 1: `$planr-loop` for autonomous, `$planr-work` / `$planr-review` for human-in-the-loop.
+
+Or autonomous in one prompt:
+
+```text
+Use $planr-loop.
+
+Goal: ship an auth system (email+password, sessions, protected routes).
+DONE when every auth map item is closed with log evidence, all reviews are closed
+complete, and a live verification log shows login and a protected route working
+in the browser. Iteration budget: 10.
+```
+
+Rules that hold in both journeys:
+
+- No map items without a checked build plan — even a small fix gets a minimal slice (`plan new` -> `plan split` with a tiny scope). This keeps closure evidence and reviews attached to a contract.
+- Plans accumulate: `planr plan list` shows the project's history of scopes; the map stays the single live source of item status.
+- Status, review, and summary requests (`$planr-status`, `$planr-review`, `$planr-summary`) work the same at any point in either journey.
+
+## Loop Roles
+
+`planr-loop` keeps maker and checker separate. Hosts with subagents get dedicated roles that are prompted with skills, not hand-written prompts.
+
+The CLI provisions the role files automatically — no manual copying:
+
+```bash
+planr project init "My Product" --client all   # writes .codex/agents/*.toml and .claude/agents/*.md
+planr install codex                            # provisions roles for an existing project
+```
+
+Codex needs these project-scoped files because its plugin system carries skills only; the Claude Code plugin registers the same roles automatically, so the provisioned `.claude/agents/` copies only matter for standalone (non-plugin) installs. Existing role files are never overwritten.
+
+Dispatches stay one line: `Use $planr-work on item <id>` and `Use $planr-review on item <id>`. The map and logs are the loop memory, so any iteration can resume from zero context.
+
+## Install For Codex
+
+Copy the Planr skills into Codex's local skill directory:
+
+```bash
+mkdir -p ~/.codex/skills
+cp -R plugins/planr/skills/* ~/.codex/skills/
+```
+
+If Planr was installed from an npm package that includes `skills/`, copy from the package location instead:
+
+```bash
+PLANR_PKG="$(npm root -g)/planr"
+mkdir -p ~/.codex/skills
+cp -R "$PLANR_PKG"/plugins/planr/skills/* ~/.codex/skills/
+```
+
+Do not present `npx planr` as the primary install path until the npm artifact ships platform-native Planr binaries. Today the normal user path is the GitHub Release installer; npm is a development and consumer-test wrapper.
+
+Then run Codex from a repository where `planr` is installed and initialized:
+
+```bash
+planr project init "Example Product" --client codex
+planr doctor --client codex
+```
+
+Codex can also use Planr through MCP:
+
+```bash
+planr install codex --dry-run
+planr prompt mcp --client codex
+```
+
+## Install For Claude Code
+
+Claude Code loads project skills from `.claude/skills/`:
+
+```bash
+mkdir -p .claude/skills .claude/agents
+cp -R plugins/planr/skills/* .claude/skills/
+cp plugins/planr/agents/*.md .claude/agents/
+```
+
+Then add MCP and the Planr workflow prompt to project instructions when needed:
+
+```bash
+planr project init "Example Product" --client claude
+planr install claude --dry-run
+planr prompt mcp --client claude
+planr prompt cli --client claude
+```
+
+`planr install claude` writes a project-scoped `.mcp.json` when not run as a dry-run.
+
+## Install For Cursor
+
+Cursor should use Planr through MCP plus the CLI prompt:
+
+```bash
+planr project init "Example Product" --client cursor
+planr install cursor --dry-run
+planr prompt mcp --client cursor
+planr prompt cli --client cursor
+```
+
+`planr install cursor` writes `.cursor/mcp.json` when not run as a dry-run. Use `planr serve --port 7526` and `planr prompt http --client cursor` if a Cursor workflow should inspect the local HTTP/review workspace.
+
+## MCP-Only Clients
+
+Any MCP-capable coding agent can run:
+
+```bash
+planr mcp
+```
+
+Use these commands for setup text without editing global config:
+
+```bash
+planr prompt mcp --client all
+planr prompt cli --client all
+planr prompt http --client all
+```
+
+## What The Skills Do
+
+The skills are client-neutral and use only Planr-owned commands:
+
+```bash
+planr project show --json
+planr plan new "App idea"
+planr map build --from <plan-id>
+planr pick --json
+planr done <item-id> --summary "..." --files a --files b --cmd "..." --review --next
+planr review close <review-id> --verdict complete --close-target
+planr approval list --open
+```
+
+The granular commands (`log add`, `review request`, `close`, `pick heartbeat`) remain available; `done` chains them with identical evidence.
+
+See also:
+
+- [Operating Model](OPERATING_MODEL.md)
+- [Task Graph Model](TASK_GRAPH_MODEL.md)
+- [Handoffs And Stories](HANDOFFS_AND_STORIES.md)