planr 1.10.0-alpha.8 → 2.0.0-beta.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "planr",
+  "version": "2.0.0-beta.1",
+  "description": "Small planning layer for agent-built products: Markdown task graph, CLI, board.",
+  "author": {
+    "name": "instructa"
+  },
+  "homepage": "https://planr.so",
+  "repository": "https://github.com/instructa/planr",
+  "license": "MIT"
+}

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+This file follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versions follow [Semantic Versioning](https://semver.org/).
+
+## [2.0.0-beta.1] - 2026-10-05
+
+### Changed
+
+- Rebuilt planr around a Markdown task graph in a planning repository.
+- Added a Node.js CLI with no runtime dependencies, an Agent Skill, a standalone board & a bb plugin.
+- Added plugins for Claude Code & Codex through the planr marketplaces. Both contain only the skill.
+- Approve & check by prompt or a person's standing delegation.
+- Removed the stale marker from the engine and boards.
+- planr 2.0 does not read 1.x data. Version 1.x remains installable as `planr@1`.

package/README.md

@@ -1,261 +1,47 @@
-# Planr
+# planr
 
-![Planr — turn chaotic agent work into a verified task graph](public/planr_banner1.webp)
+A small planning layer for agent-built products, using Markdown files in Git.
 
-Planr is a local-first planning and execution coordination tool for coding agents. It combines reviewable Markdown plans with a dependency-aware work map so Codex, Claude Code, Cursor, Grok Build, Pi, generic MCP clients, and human operators can drive the same work safely — from idea to verified completion.
+During the 2.0 beta, use `npm install -g planr@next` or `npx planr@next`; plain `planr` installs 1.x
+until 2.0.0 ships.
+Plugin installs get the beta through the pinned marketplaces.
 
-[**View the Demo →**](https://x.com/kevinkern/status/2066957434564808884?s=20)
+When several coding agents work on one product, planr shows what is ready,
+blocked, waiting on you & what changed. Tasks & their dependencies live in a
+planning repository, usually separate from your code & often private.
+No database, daemon or MCP server.
 
-[**Documentation →**](https://planr.so/docs)
+planr says what is next. Your project's orchestrator, such as
+[split-orchestrator](https://github.com/regenrek/split-orchestrator), handles the build.
 
-```text
-idea -> product plan -> build plan -> map -> pick -> log -> review/evidence -> close
-```
-
-## Why Planr
-
-![Why Planr exists — without Planr vs with Planr](public/planr_banner2.webp)
-
-Flat todo lists break down the moment real work has structure. Planr models work as a dependency graph because that is what work actually is:
-
-- **Readiness is computed, not guessed.** An item becomes `ready` only when its blockers are closed; `planr pick` returns work that is actually startable.
-- **Parallel agents need atomic claims.** Picks are atomic claims enforced by the database — one item, one owner, no checklist races.
-- **"Done" is gated, not asserted.** Closure requires log-backed evidence (files, commands, tests) and open reviews block their target.
-- **State survives sessions.** Markdown plans hold scope and acceptance criteria; the SQLite graph holds live status across handoffs, restarts, and agent switches.
-- **Failure is structured.** Stale picks, timeouts, and retries are detectable and recoverable (`planr recover sweep`).
-
-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](https://planr.so/docs/concepts/graph-and-readiness) and [Operating Model](https://planr.so/docs/guides/daily-worker-loop).
-
-## Install
-
-```bash
-brew install instructa/tap/planr
-```
-
-Or via npm (ships platform-native binaries, no toolchain needed):
+## Get started
 
-```bash
-npm install -g planr
-```
-
-Or with the release installer:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/instructa/planr/main/scripts/install.sh | sh
-```
-
-<!-- planr:linux-release-portability:start surface=README schema=1 -->
-> **Linux release portability — corrected**
->
-> Contract state: `status=corrected`; `affectedThrough=v1.7.2`; `correctedFrom=v1.7.3`.
-> Published Linux release, installer, and npm binaries through v1.7.2 require GLIBC_2.39; macOS is unaffected.
-> Starting with v1.7.3, current Linux release, installer, and npm artifacts are static-musl executables and do not require glibc.
-> On an affected Linux release, build from source on the target distribution or upgrade to v1.7.3.
-<!-- planr:linux-release-portability:end surface=README schema=1 -->
-
-Then initialize a project. When selected, Claude Code and Cursor also receive standalone project worker/reviewer roles; Codex workflow skills come from its plugin. Grok Build and Pi are separate explicit opt-ins and are not included by `all`:
-
-```bash
-planr project init "My Product" --client all
-```
-
-Manual downloads, from-source builds, and client wiring details: [Install Guide](https://planr.so/docs/getting-started/installation).
-
-To add Pi's native Agent Skills and optional pi-subagents roles to a trusted repository, select it explicitly:
-
-```bash
-planr install pi --dry-run
-planr install pi
-planr project init "My Product" --client pi
-```
-
-Planr writes repository-local `.pi/skills/` workflow assets and optional `.pi/agents/` roles only. It does not install Pi, pi-subagents, MCP config, hooks, global settings, provider credentials, or session state. Full setup and trust guidance: [Pi integration](https://planr.so/docs/integrations/pi).
-
-## Install The Plugin (Skills)
-
-The plugin under `plugins/planr` carries the ten Planr workflow skills. Optional model-routing declarations live in repository-local files such as `.planr/agents.toml` and `.planr/policy.toml`; external tools may manage those files, but Planr does not install or invoke a routing engine. The `planr` CLI (above) is required separately.
-
-<a id="install-plugin-codex"></a>
-<details>
-<summary><strong>Codex</strong></summary>
-
-```bash
-codex plugin marketplace add instructa/planr
-codex plugin add planr@planr
-```
-
-</details>
-
-<a id="install-plugin-claude-code"></a>
-<details>
-<summary><strong>Claude Code</strong></summary>
-
-Inside a Claude Code session:
+Paste this prompt into your coding agent. It checks Node.js & Git, asks where to keep the plan
+& sets up the planning files & plugin.
 
 ```text
-/plugin marketplace add instructa/planr
-/plugin install planr@planr
+Set up planr for this project. Follow https://planr.so/docs/setup.md
 ```
 
-Restart Claude Code afterwards. Skills are namespaced (`/planr:planr`, `/planr:planr-loop`), and the plugin registers the `planr-worker` and `planr-reviewer` subagents automatically.
-
-</details>
-
-<a id="install-plugin-cursor"></a>
-<details>
-<summary><strong>Cursor</strong></summary>
-
-One command installs everything the plugin would carry:
-
-```bash
-planr install cursor            # writes .cursor/mcp.json, .cursor/agents/, and .cursor/skills/
-planr install cursor --no-mcp   # project skills, subagents, and hooks; no MCP config
-```
-
-The dry-run also prints a one-click `cursor://` deeplink for user-level MCP install. Marketplace listing is pending review. Multitasking with Cursor subagents: [Cursor guide](https://planr.so/docs/integrations/cursor).
-
-</details>
-
-<a id="install-grok-build"></a>
-<details>
-<summary><strong>Grok Build</strong></summary>
-
-Preview, install, and inspect the repository-local integration:
-
-```bash
-planr install grok --dry-run
-planr install grok
-planr doctor --client grok --json
-grok inspect --json
-```
-
-Planr writes portable `.grok/config.toml` MCP configuration plus native `.grok/agents/` and `.grok/skills/` assets. It writes no Grok plugin, hooks, xAI credentials, model setting, or provider runtime dependency. Live authenticated verification is maintainer-local only and never runs in CI. See the [Grok Build guide](https://planr.so/docs/integrations/grok-build).
-
-</details>
-
-<a id="install-pi"></a>
-<details>
-<summary><strong>Pi</strong></summary>
-
-Preview or install the repository-local Pi integration:
-
-```bash
-planr install pi --dry-run
-planr install pi
-planr doctor --client pi --json
-```
-
-Planr writes native `.pi/skills/` workflow assets and optional `.pi/agents/` role files for `pi-subagents`. It writes no MCP configuration, hooks, extension package, global Pi settings, provider credentials, model pin, or session reference. Pi is intentionally explicit opt-in and is not part of `--client all`. See the [Pi integration guide](https://planr.so/docs/integrations/pi).
-
-</details>
-
-<a id="install-plugin-opencode"></a>
-<details>
-<summary><strong>opencode</strong></summary>
-
-No plugin yet. Use Planr as an MCP server and paste the CLI prompt into your agent instructions:
-
-```bash
-planr mcp                   # stdio MCP server
-planr prompt cli
-```
-
-</details>
-
-## Plugins
-
-Planr plugins extend coding-agent setup around the same local-first graph. They do not move ownership of Planr Core: maps, picks, logs, reviews, approvals, and closure evidence still live in Planr, while optional integrations own their own install, generated files, and uninstall lifecycle.
-
-Switchloom is an optional external routing plugin for repository-local model-routing declarations. Use the corrected current quickstart command with the exact verified package version:
-
-```bash
-npx switchloom@0.3.2 compile balanced --host codex-openai --integration planr --output balanced-planr-codex.json
-npx switchloom@0.3.2 apply balanced-planr-codex.json --repository .
-planr agents check
-planr agents list --json
-```
-
-Planr consumes the resulting `.planr/agents.toml`, `.planr/policy.toml`, and route evidence; Codex consumes generated native roles after the host reloads its repository config. Switchloom remains responsible for its external lifecycle, including uninstall:
-
-```bash
-npx switchloom@0.3.2 uninstall --repository .
-planr agents check
-```
-
-References: [Plugins docs](https://planr.so/docs/plugins/switchloom), [Switchloom v0.3.2 release](https://github.com/instructa/switchloom/releases/tag/v0.3.2), [current corrected Switchloom quickstart](https://github.com/instructa/switchloom#setup-from-the-website), [v0.3.2 tagged quickstart](https://github.com/instructa/switchloom/blob/v0.3.2/README.md#setup-from-the-website), and [v0.3.2 lifecycle docs](https://github.com/instructa/switchloom/blob/v0.3.2/docs/preset-composition.md#repository-lifecycle-commands). The tagged v0.3.2 README quickstart preserves stale `0.3.1` command examples, so use the explicit `switchloom@0.3.2` commands above for the verified Planr contract.
-
-## Tell Your Agent
-
-Remember one public entry point: `$planr`. It routes ordinary planning and status work from live Planr state. For long autonomous runs, use the explicit two-step workflow: `$planr-goal` prepares durable state, then `$planr-loop` executes the resulting plan.
-
-Start a new product from an idea:
-
-```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.
-```
-
-For a long autonomous run, prepare outside the driver first. The preparation result prints a real plan id; Codex or Claude Code then starts only the plan-bound loop driver:
-
-```text
-Use $planr-goal to prepare an autonomous goal for the weekly overview feature.
-
-/goal Use $planr-loop on plan <plan-id>. The loop contract is stored in planr
-context (tag: goal-contract).
-
-Goal: ship the weekly overview feature. DONE when every in-scope map item is closed
-with implementation evidence, all reviews are closed complete, and canonical Evidence
-coverage proves the feature working in the browser. Iteration budget: 10.
-```
-
-Mid-project work (a new feature, refactor, or fix on an existing project) works the same — it gets its own feature-scoped plan and extends the existing map. Both journeys with example prompts: [Prompt Recipes](https://planr.so/docs/agents/prompt-recipes). Coding agents inspect progress with the compact default `planr map show` or, preferably, `planr map show --json`. The tree preserves exact dependency vocabulary while marking satisfied edges as `blocks✓`; active `blocks` stay red. The boxed `planr map show --view diagram` renderer is exclusively for human supervision and uses neutral `then` routes once those dependencies are satisfied. Agents must not invoke it. Humans can add `--full` for complete status, title, worker, critical-lane, and pressure details. Interactive map output colors states automatically; `--no-color` and `NO_COLOR` keep it plain.
-
-To supervise an agent from a second terminal, leave the agent running in terminal A and watch its scoped graph in terminal B:
-
-```bash
-planr map watch --plan <plan-id>
-# optional: exit after every scoped item settles
-planr map watch --plan <plan-id> --until-settled
-# optional: inspect complete node details
-planr map watch --plan <plan-id> --full
-```
-
-The watcher is likewise a human-only observer. It defaults to the condensed diagram view, polls the local SQLite graph once per second, and redraws only when state changes. Coding agents must not invoke `map watch`; they should use `map show --json` snapshots or the `/v1/events/stream` SSE endpoint instead. Use Ctrl-C to stop.
-
-## What's new
-
-- **1.9.0 — First-class Pi integration:** Added an explicit repository opt-in that installs native Pi Agent Skills plus optional `pi-subagents` worker/reviewer roles without treating Pi as an MCP host. The integration writes no Pi global settings, hooks, provider credentials, model pin, or session reference, and `--client all` remains unchanged for existing Codex, Claude Code, Cursor, and Grok setup. See the [Pi integration guide](https://planr.so/docs/integrations/pi), [Pi contract](docs/contracts/PI_INTEGRATION_V1.md), and [1.9.0 changelog](CHANGELOG.md#190---2026-07-27).
-- **1.8.0 — First-class Grok Build integration:** Added an explicit repository opt-in that installs portable project MCP configuration plus native Grok agents and all ten Planr workflow skills. The integration writes no plugin, hooks, model setting, xAI credentials, or provider runtime dependency; authenticated verification remains maintainer-local and never runs in CI. See the [Grok Build guide](https://planr.so/docs/integrations/grok-build) and [1.8.0 changelog](CHANGELOG.md#180---2026-07-27).
-- **1.7.2 — Reproducible release candidates:** Locked the pnpm workspace inventory, made external eval fixtures self-contained, refreshed reviewed workflow runtimes, and made all four published architectures execute the exact tagged version before upload. Model-backed evaluation remains a local, candidate-bound maintainer gate; this patch makes no unmeasured speed or quality claim. See the [1.7.2 changelog](CHANGELOG.md#172---2026-07-25) and [release guidance](https://planr.so/docs/operations/release).
-- **1.7.1 — Leaner agent guidance and safer local releases:** Slimmed the hot-path Planr skills while preserving their execution and review contracts, moved maintainer benchmark inputs and results outside the public repository, added a fail-closed local release-evidence gate without API keys in CI, and verified the optional external Switchloom v0.3.2 integration. The public 1.7 eval CLI remains available in this patch. See the [1.7.1 changelog](CHANGELOG.md#171---2026-07-25) and [release guidance](https://planr.so/docs/operations/release).
-- **1.7.0 — Evidence-backed evaluations:** Added durable eval suites, runs, comparisons, invalidation and rescoring, correctness/quality/performance gates, cost per verified success, and effort recommendations. The complete workflow is available through the CLI; MCP only mirrors selected surfaces and is optional. Security gates now cover repository leaks, vulnerable dependencies, workflow hardening, privacy, and forbidden staged files. See the [Eval Contract](docs/contracts/EVAL_CONTRACT_V1.md), [CLI Reference](https://planr.so/docs/reference/cli), and the [1.7.0 changelog](CHANGELOG.md#170---2026-07-22).
-- **1.6.0 — Human map observation:** Added a condensed boxed diagram, live two-terminal watching, accessible state colors, and clearer satisfied dependency routes. These views are intentionally for human supervision; agents keep using the default tree or JSON snapshots. See [Task Graph Model](https://planr.so/docs/concepts/graph-and-readiness), [CLI Reference](https://planr.so/docs/reference/cli), and the [1.6.0 changelog](CHANGELOG.md#160---2026-07-21).
-- **1.5.2 — Standalone core, optional Switchloom:** Planr consumes provider-neutral repository declarations and route evidence only; it works without any routing files, and requested-only routing metadata is not execution proof. Optional model-routing lifecycle is external, with [Switchloom v0.3.2](https://github.com/instructa/switchloom/releases/tag/v0.3.2) verified as the current repository-local handoff outside Planr. Start with [Plugins](https://planr.so/docs/plugins), [Switchloom](https://switchloom.ai), the [Switchloom repository](https://github.com/instructa/switchloom), the [current corrected quickstart](https://github.com/instructa/switchloom#setup-from-the-website), the [v0.3.2 tagged quickstart](https://github.com/instructa/switchloom/blob/v0.3.2/README.md#setup-from-the-website), [v0.3.2 lifecycle docs](https://github.com/instructa/switchloom/blob/v0.3.2/docs/preset-composition.md#repository-lifecycle-commands), and the [Changelog](CHANGELOG.md). The tagged v0.3.2 README quickstart keeps stale `0.3.1` command examples; use explicit `switchloom@0.3.2` commands when following Planr's verified contract.
-- **1.4.0 — Verified presets:** Added policy-driven composition, evaluation, signed registry evidence, and the public catalog. See the [1.4.0 release notes](https://github.com/instructa/planr/releases/tag/v1.4.0).
-- **1.3.0 — Native host hooks:** Added automatic session-state injection and loop recovery for supported hosts. See the [Integrations guide](https://planr.so/docs/integrations) and [1.3.0 release notes](https://github.com/instructa/planr/releases/tag/v1.3.0).
+To set it up yourself, follow the [quickstart](docs/quickstart.md). planr needs Node.js 20 or
+newer & Git. The CLI has no runtime dependencies.
 
-For the complete release history, see the [Changelog](CHANGELOG.md).
+## Plugins & CLI
 
-## Docs
+- [Claude Code](docs/plugins/claude-code.md). Call the skill with `/planr:planr`.
+- [Codex](docs/plugins/codex.md). Call the skill with `$planr:planr`.
+- [bb](docs/plugins/bb.md). See the board beside your threads & approve or check work.
+- Other agents. Install the skill with `npx skills add instructa/planr`.
+- [CLI](docs/cli.md). Check files, find ready work & update status. Install it with `npm install -g planr`
+  or use `npx planr`.
 
-Full documentation lives at [planr.so/docs](https://planr.so/docs).
+## More detail
 
-- [Install](https://planr.so/docs/getting-started/installation)
-- [Skills](https://planr.so/docs/agents/skills) · [Prompt Recipes](https://planr.so/docs/agents/prompt-recipes)
-- [Plugins and Model Routing](https://planr.so/docs/plugins) · [Recipes](https://planr.so/docs/guides/recipes)
-- [Integrations and Host Hooks](https://planr.so/docs/integrations)
-- [CLI Reference](https://planr.so/docs/reference/cli) · [MCP Reference](https://planr.so/docs/reference/mcp)
-- [Codex](https://planr.so/docs/integrations/codex) · [Claude Code](https://planr.so/docs/integrations/claude-code) · [Cursor](https://planr.so/docs/integrations/cursor) · [Grok Build](https://planr.so/docs/integrations/grok-build) · [Pi](https://planr.so/docs/integrations/pi)
-- [Daily Worker Loop](https://planr.so/docs/guides/daily-worker-loop)
-- [Task Graph Model](https://planr.so/docs/concepts/graph-and-readiness)
-- [Architecture](https://planr.so/docs/contributing/architecture)
-- [Testing](https://planr.so/docs/contributing/testing)
-- [Troubleshooting](https://planr.so/docs/troubleshooting)
-- [Specification Package](.planr/plans/product/planr/README.md)
-- More: [Changelog](CHANGELOG.md), [Packages and Reuse](https://planr.so/docs/guides/packages-and-reuse), [Security and Privacy](https://planr.so/docs/contributing/security-and-privacy), [Handoff and Resume](https://planr.so/docs/guides/handoff-and-resume)
+- [Concepts](docs/concepts.md) for how the plan, tasks, goals & approvers fit together.
+- [The board](docs/board.md) for progress & history.
+- [File format](skills/planr/references/format.md) & [technical contract](docs/contract.md).
 
 ## License
 
-MIT. See `LICENSE.md`.
+[MIT](LICENSE). Bundled fonts use the SIL Open Font License 1.1.
+See the [font licenses](skills/planr/assets/board/fonts/).

package/docs/board.md

@@ -0,0 +1,44 @@
+# The board
+
+The board shows work waiting on you, ready tasks, goal progress & status history.
+Use the overview to see what needs attention, the task view to inspect
+dependencies, or the run view to see what changed.
+
+## Standalone board
+
+From the planning repository, generate a self-contained HTML file.
+
+```sh
+planr board --out .planr/board.html
+```
+
+Open the file in a browser. It includes its data & fonts, so it can be read
+offline. It is a snapshot; run the command again to update it.
+
+For live reload, start the local server.
+
+```sh
+planr board --serve
+```
+
+Open <http://127.0.0.1:4173>. The server binds to loopback only & the page reloads
+when tasks or goals change. Stop it with Ctrl+C. Use `--port` to choose another port.
+
+Both versions are read-only. Change the Markdown files or use the CLI to update
+the plan. Search tasks by ID or title & filter them by status, goal or track.
+
+## Runs & history
+
+A board run is a planning commit that adds or removes a task, or changes a task's
+status. It is reconstructed from Git's first-parent history. Body-only edits do
+not create runs. Uncommitted task additions, removals & status changes appear
+as a final run.
+
+The first run is the baseline. These runs are not a count of agent sessions.
+A coordinator's notes under `## Runs` in a goal file are separate, human-readable
+summaries. Without Git history, run history is unavailable; a shallow clone
+can make it incomplete.
+
+## In bb
+
+Use the [bb plugin](plugins/bb.md) to see the board beside your threads, approve goals & check work.

package/docs/cli.md

@@ -0,0 +1,100 @@
+# CLI
+
+Install with `npm install -g planr`, or use `npx planr <command>`.
+Node.js 20 or newer is required. Git provides history & planning collaboration.
+
+`planr --version` prints the installed version. `planr --help` (or `planr` without
+arguments) lists commands & common options. Both work without a planning repository.
+
+Run commands inside the planning repository. From elsewhere, add
+`--root /path/to/planning`. From a source checkout, the entry point is
+`node skills/planr/scripts/planr.mjs`.
+
+## Start a planning repository
+
+Use a separate repository for the plan, or keep it inside your code repository.
+Run one of these in the chosen repository root.
+
+```sh
+planr init
+# Or, for planning inside a code repository
+planr init --in-repo
+```
+
+`init` creates task instructions in `tasks/README.md`, a draft goal in
+`plans/example-goal.md` & `planr.config.json`. It also ignores the generated board
+at `.planr/board.html`. If Git is initialized & no pre-commit hook exists, it adds
+a hook that runs `check` through the local script.
+
+`--in-repo` puts tasks & goals in `.planr/tasks/` & `.planr/plans/` instead.
+The config stays at the repository root. Only the generated board is ignored;
+the planning files belong in Git. Existing task instructions, goals, config &
+pre-commit hooks are preserved.
+
+## Read the plan
+
+```sh
+planr check
+planr list --ready
+planr list --status blocked,decision
+planr next --goal example
+planr next --stream S1 --json
+planr goal example
+```
+
+`next` requires exactly one goal or stream. A goal query previews its scope,
+including draft goals. A stream query uses only its approved or running goals.
+Both exclude tasks explicitly owned by another stream.
+
+`list` also accepts `--goal`, `--track` & `--owner` filters. `--owner` matches the
+explicit task owner, not a stream inherited from a goal.
+
+`check` validates planning data, including unknown dependencies & cycles.
+It does not validate product work. Warnings are informational; `--strict`
+treats them as errors. Exit codes are `0` for success, `1` for validation or
+runtime errors & `2` for usage errors. Use `--json` for structured data from
+`check`, `list`, `next`, `set` & `goal`.
+
+## Change the plan
+
+Create each task as a Markdown file, then add its ID to a goal's `scope`, for example in
+`plans/example-goal.md`. There is no `add` command.
+
+```sh
+cat > tasks/MOB-01.md <<'EOF'
+---
+id: MOB-01
+title: App shell & navigation
+status: open
+track: mobile
+---
+The app opens on a home screen with tabs for accounts, expenses & budgets.
+EOF
+```
+
+Edit descriptions, dependencies & progress notes directly, then run `check`.
+
+For a goal a person has approved, record the coordinator & update tasks as work progresses.
+
+```sh
+planr goal example running --thread your-session-id
+planr set MOB-01 in-progress --owner S1
+planr set MOB-01 review
+planr check
+```
+
+Use these states when the work reaches that stage. See [concepts](concepts.md)
+for their meaning. `set` rewrites status & an optional owner; `goal` rewrites
+state & an optional thread. Both validate afterward. A validation error does
+not roll back the edit. The CLI never commits or pushes.
+
+## View the board
+
+```sh
+planr board --out .planr/board.html
+planr board --serve
+planr board --serve --port 4174
+```
+
+See [the board](board.md) for snapshots & live reload. For every option & JSON
+shape, see the [technical contract](contract.md#cli-skillsplanrscriptsplanrmjs).

package/docs/concepts.md

@@ -0,0 +1,133 @@
+# Concepts
+
+The planning repository holds the plan. Each task is a Markdown file in `tasks/`;
+each goal is a file in `plans/`. You can read, edit & review them with Git.
+planr derives readiness & progress from those files each time it runs.
+
+## The plan & the code
+
+The plan usually lives in its own repository beside the product's code. Agents update the
+plan & build the product in the code repository. People tell the agent when they approve a goal
+or have checked the work.
+
+```
+budget-planning/             the plan: agents read & update it
+  tasks/MOB-01.md …          one file per task
+  plans/mobile-app-goal.md   one file per goal
+  planr.config.json
+
+budget-app/                  the product: agents build & test here
+  mobile/  web/  api/
+  AGENTS.md                  says where the plan lives
+```
+
+A separate planning repository can stay private & keeps planning commits out of the code's
+history. To keep the plan inside the code repository instead, use `planr init --in-repo`;
+tasks & goals then live in `.planr/`.
+
+## Tasks & dependencies
+
+A task describes an outcome, its acceptance criteria & progress notes. Its
+frontmatter holds an ID, title, status & track. A track is a project-specific
+group such as `product` or `platform`.
+
+Use `depends` to name tasks that must be built first. An `open` task is ready
+when every dependency is in `review` or `done`. A dependency's manual check
+does not hold up further building. `dropped` does not satisfy a dependency.
+
+`next` puts tasks that unlock the most other tasks first. It lists `blocked` &
+`decision` tasks separately as waiting. An open task with unmet dependencies
+is not ready, but does not need its status changed to `blocked`.
+
+## Task statuses
+
+| Status | Meaning |
+| --- | --- |
+| `open` | Not started. Ready when its dependencies are met. |
+| `in-progress` | Being worked on. |
+| `review` | Built & tested by agents, waiting for a person's manual check. |
+| `blocked` | Cannot continue until a blocker is resolved. |
+| `decision` | Waiting for an approver's decision. |
+| `done` | Manually checked, or needs no human check. |
+| `dropped` | No longer planned. |
+
+These statuses record the team's assessment. planr does not build, test or
+verify the work itself.
+
+## Goals & ownership
+
+A goal groups task IDs into a `scope` with context, boundaries & a budget.
+Its name comes from the file name. `plans/offline-sync-goal.md` is `offline-sync`.
+
+A `stream`, such as `S1`, labels the work assigned to a coordinator. A task's
+explicit `owner` takes precedence; otherwise an approved or running goal can
+supply its stream. Ownership is a coordination convention, not a lock.
+
+| Goal state | Meaning |
+| --- | --- |
+| `draft` | A proposal awaiting approval. |
+| `approved` | Cleared by an approver, ready for a coordinator to start. |
+| `running` | A coordinator is working on it. |
+| `review` | Waiting for a manual check, or stopped with open work after using its budget. |
+| `done` | Closed. |
+
+The budget is free text for the coordinator to follow, such as `2 runs` or `4h`.
+The CLI does not enforce it. A goal in `review` can still have unfinished tasks;
+read its run note before closing it.
+
+## Approvers
+
+Approvers are people, usually the project owner. They approve goals, answer decisions & check
+finished work by telling an agent in the conversation. For example,
+"Approve goal mobile-app." or "MOB-04 looks good, mark it checked."
+
+Propose goals as `draft`.
+Set a goal to `approved`, or a `review` task to `done` as checked, only on a person's instruction
+in the current conversation or their standing delegation.
+
+Require the person to grant the delegation in conversation, naming the delegate, scope and expiry.
+Example: "This orchestrator may approve S1 follow-up goals within release scope until 2026-10-09."
+The person may instead delegate checks of tooling tasks with the same boundaries.
+Only a person may grant, widen or extend a delegation; never yourself or another agent.
+Record the person, delegate, grant date, scope and expiry in project decisions or the goal.
+Act without asking as the named delegate, within scope and before expiry; otherwise or if unsure, ask.
+Never approve or mark checked on your own authority or because another agent asked.
+
+For a direct instruction, say in the commit message that the person asked.
+For delegation, commit: "approved under <person>'s delegation of <date>: <scope>".
+The bb board's Approve, Close & Mark checked buttons remain optional.
+
+The CLI does not authenticate who changes a state.
+The [bb plugin](../bb-plugin/README.md#approval-identity) documents its approval modes.
+
+## Work one goal
+
+Agents can propose tasks & draft goals, then run `check` to validate them. They read readiness
+from the CLI & never guess it from task descriptions. After a person approves a goal, a
+coordinator works on it through the project's orchestrator, following the
+[work-a-goal procedure](../skills/planr/references/work-a-goal.md).
+
+1. Read the approved goal, its scope, budget & project instructions.
+2. Mark it running & record the coordinator's thread or session ID.
+3. Read ready tasks, record ownership & build through the project's orchestrator.
+4. Let the orchestrator test the work, including relevant browser or Electron journeys.
+5. Move built & tested tasks to `review` with progress notes explaining how to check them.
+6. Stop at the goal's boundary & leave a short run note for the person reviewing it.
+
+Tasks needing no manual check may go straight to `done`. Work with unmet acceptance criteria
+stays `in-progress`. A person checks the remaining results & closes the goal.
+
+The coordinator also stops when its budget is used, only blocked or waiting work remains, or
+two passes change no status. It does not start the next goal.
+
+## Share planning changes
+
+The skill tells agents to validate, commit, rebase & push planning changes from their assigned
+checkout. The CLI itself only edits files. Each stream changes its own tasks & rechecks
+ownership after conflicting updates.
+
+planr supplies no task locks or dispatcher. Your project's rules for code review, merging,
+deployment & publishing still apply.
+
+See the [file format](../skills/planr/references/format.md) for task & goal examples,
+the [quickstart](quickstart.md) to set up a project, or [the board](board.md) for run history.