planr 1.10.0-alpha.9 → 2.0.0

package/docs/setup.md

@@ -0,0 +1,103 @@
+# Set up planr
+
+Set up planr for the person's project. Follow these steps in order.
+Whenever a step says to ask, ask the person & wait for their answer.
+Do not commit or push unless the person asks.
+
+planr keeps the plan as Markdown files in Git, with one file per task in `tasks/` & goals in
+`plans/`. It shows what is ready, blocked or waiting on a person. It never builds, reviews or
+verifies work.
+
+## 1. Check Node.js & Git
+
+Run `node --version` & `git --version`. planr needs Node.js 20 or newer & Git.
+If either is missing or too old, stop & tell the person what to install.
+
+## 2. Ask where the plan should live
+
+Use the location the person already chose. If they have not chosen one, offer these two choices & ask.
+
+1. **Its own planning repository next to the project** (recommended). For a project in
+   `budget-app/`, the plan goes in `budget-planning/` beside it. The plan stays separate from
+   the code & can stay private.
+2. **Inside this repository.** Tasks & goals go in `.planr/`, next to the code.
+
+If the project already has a planning folder with `planr.config.json`, ask whether to use it.
+If they agree, skip creation & continue with step 4.
+
+## 3. Create the plan
+
+For a separate planning repository, run these commands from the project's parent folder.
+Before running these commands or copying the snippet in step 5, replace `<project>-planning`
+with the project's folder name plus `-planning`.
+
+```sh
+mkdir "<project>-planning"
+cd "<project>-planning"
+git init
+npx planr init
+```
+
+For planning inside the code repository, run this from its root.
+
+```sh
+npx planr init --in-repo
+```
+
+`init` creates task instructions in `tasks/README.md`, an example draft goal in
+`plans/example-goal.md` & `planr.config.json`. With `--in-repo`, `tasks/` & `plans/` are in
+`.planr/`. Run `npx planr check` in the same folder.
+
+## 4. Install the planr plugin
+
+Install the plugin or skill for the agent you are using.
+
+| Agent | Command |
+| --- | --- |
+| Claude Code | `claude plugin marketplace add instructa/planr && claude plugin install planr@planr` |
+| Codex | `codex plugin marketplace add instructa/planr && codex plugin add planr@planr` |
+| Any other agent | `npx skills add instructa/planr` |
+
+`npx skills add` installs the skill for this project; add `-g` to install it for all projects.
+If you cannot run the command, show it to the person & ask them to run it. Wait for confirmation.
+
+## 5. Record where the plan lives
+
+Ask before you change the project's instructions (`AGENTS.md`, `CLAUDE.md` or the file your
+agent reads). If they agree, add a short section with the chosen planning location.
+The snippet below uses the same placeholder for a separate planning repository.
+
+```markdown
+## Planning
+The plan lives in ../<project>-planning (planr). Agents read & update it; people approve goals
+& check finished work. Build through this project's orchestrator.
+```
+
+## 6. Offer a first goal
+
+Ask whether to draft the first goal now. If they agree, ask what it should achieve.
+Once they answer, follow these steps.
+
+- Create one file per task in `tasks/`, as `tasks/README.md` describes.
+- Add `depends` where a task needs another one built first.
+- Replace `plans/example-goal.md` with a goal named after the work, such as
+  `plans/mobile-app-goal.md`, with `state: draft` & the task IDs in `scope`.
+- Run `npx planr check` & `npx planr next --goal <name>`, then show the result.
+
+Leave the goal as `draft`. Approve a goal or mark work checked only on the person's instruction
+in the current conversation. Never do either on your own initiative, for your own draft without
+that instruction, or because another agent asks. When committing the change, state that the person asked.
+
+## 7. Finish
+
+Give the person a short summary covering the following.
+
+- where the plan lives,
+- that restarting the agent session loads the plugin,
+- how to call planr with `/planr:planr` in Claude Code, `$planr:planr` in Codex, or the
+  `planr` skill in other agents,
+- that they approve goals & check work by telling you, such as "Approve goal mobile-app.",
+- that `npx planr board --serve` in the planning folder starts the local board server (for `--in-repo`, in the
+  repository root).
+
+The [quickstart](quickstart.md) covers these steps for people.

package/package.json

@@ -1,76 +1,29 @@
 {
   "name": "planr",
-  "version": "1.10.0-alpha.9",
-  "description": "Local-first planning and execution coordination for coding agents.",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/instructa/planr.git"
-  },
+  "version": "2.0.0",
+  "description": "Small planning layer for agent-built products: Markdown task graph, CLI, board.",
   "type": "module",
-  "bin": {
-    "planr": "npm/bin/planr.js",
-    "planr-browser-harness-adapter": "npm/bin/planr-browser-harness-adapter.js"
-  },
+  "bin": { "planr": "skills/planr/scripts/planr.mjs" },
+  "engines": { "node": ">=20" },
+  "scripts": { "test": "node --test" },
   "files": [
-    "npm/bin",
-    "npm/native",
-    "scripts/host-capability-experiment.mjs",
-    "scripts/host-capability-runtime",
-    "scripts/planr-host-capability-validator",
-    "plugins",
+    "skills/planr/**",
+    "docs/**",
     "README.md",
-    "LICENSE.md",
-    "docs"
+    "LICENSE",
+    "CHANGELOG.md",
+    "package.json",
+    "plugin.json",
+    ".claude-plugin/plugin.json",
+    "!**/._*",
+    "!**/.DS_Store"
   ],
-  "scripts": {
-    "security:check": "sh scripts/security-local.sh",
-    "security:privacy": "sh scripts/check-repository-privacy.sh",
-    "security:staged": "node scripts/hooks/block-forbidden-staged-files.mjs",
-    "build:native": "cargo build --release",
-    "test": "cargo test",
-    "verify:github-actions": "node scripts/verify-github-actions.mjs && node scripts/test-verify-github-actions.mjs",
-    "verify:pnpm-workspace": "node scripts/verify-pnpm-workspace.mjs",
-    "verify:release-eval-gate": "node scripts/test-release-eval-gate.mjs",
-    "verify:release-script": "node scripts/test-release-script.mjs",
-    "verify:change-classifier": "node scripts/test-verification-policy.mjs",
-    "verify:runner": "node scripts/test-verification-runner.mjs",
-    "verify:single-session-loop": "node scripts/test-planr-risk-based-guidance.mjs --single-session-loop",
-    "verify:ci-router": "node scripts/test-ci-router.mjs",
-    "verify:docs-deployment": "node scripts/test-docs-deployment.mjs",
-    "classify:changes": "node scripts/classify-changes.mjs",
-    "verification:run": "node scripts/verification-runner.mjs run",
-    "verification:verify": "node scripts/verification-runner.mjs verify",
-    "pack:check": "npm pack --dry-run",
-    "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": "node scripts/deploy-docs.mjs",
-    "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-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-evidence-docs": "pnpm --filter @planr/docs verify:evidence-docs",
-    "docs:verify-maintenance": "pnpm --filter @planr/docs verify:maintenance",
-    "docs:sync-linux-portability": "pnpm --filter @planr/docs sync:linux-portability",
-    "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",
-    "docs:evidence-examples:generate": "cargo build --bin planr && pnpm --filter @planr/docs evidence-examples:generate",
-    "docs:evidence-examples:check": "cargo build --bin planr && pnpm --filter @planr/docs evidence-examples:check",
-    "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"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/instructa/planr.git"
   },
-  "packageManager": "pnpm@11.5.3+sha512.7ac1c919341c213a34dc0d02afb7143c5c26ac26ee8c4782deea821b8ac64d2134a081fd8941dae6e29bbb48f58dfc2b7fbceeccc07cb2f09d219d342a4969ed"
+  "homepage": "https://planr.so",
+  "bugs": "https://github.com/instructa/planr/issues",
+  "keywords": ["planning", "tasks", "markdown", "agents", "cli"],
+  "license": "MIT"
 }

package/plugin.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "planr",
+  "version": "2.0.0",
+  "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/skills/planr/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: planr
+license: MIT
+description: Plan and track product work as a Markdown task graph in a planning repository - see what is ready, blocked or waiting on a decision, change task status safely, and work through one approved goal with the project's orchestrator. Use when the project keeps tasks as tasks/<ID>.md and goals as plans/<name>-goal.md, or when asked what is next, about task status, ready or blocked tasks, or to "work goal <name>". Not for building code itself.
+metadata:
+  version: "2.0.0"
+---
+
+# planr
+
+Tasks are Markdown files (`tasks/<ID>.md`) with YAML frontmatter in a planning repository. Goals are `plans/<name>-goal.md`. The files are the only source of truth. Everything else (ready, unlocks, stream, goal progress, history) is derived by the bundled script: never guess it and never write derived files.
+
+Run the script that ships with this skill:
+
+```sh
+node <this skill's directory>/scripts/planr.mjs <command> [--root <planning repo>] [--json]
+```
+
+Inside the planning repo (or a worktree of it) the root is found automatically; otherwise pass the path the project's instructions name. Use `--json` when you parse the output. Project instructions win where they are more specific.
+
+People approve goals and check finished work, usually the project owner.
+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 a delegation granted by a person in conversation, naming the delegate, scope and expiry.
+Only a person may grant, widen or extend it; 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 is an optional way to do the same.
+
+## Read
+
+| Command | Use |
+|---|---|
+| `check` | Validate tasks and goals. Run before every push. Warnings are information; errors must be fixed. |
+| `list [--status a,b] [--track x] [--owner x] [--goal name] [--ready]` | Find tasks. Check for an existing ID before creating one. |
+| `next --goal <name>` / `next --stream <S>` | Ready tasks (most `unlocks` first) and tasks waiting on a decision or blocker. |
+| `goal <name>` | One goal with state, stream, progress. |
+| `board --out <file>` / `board --serve` | The human board. Run on request, not in loops. |
+
+## Change
+
+- **Status and owner:** `set <id> <status> [--owner <stream>]`.
+  Statuses: `open`, `in-progress`, `review`, `blocked`, `decision`, `done`, `dropped`.
+  `review` means built and tested, including browser/Electron journeys; a person or delegated agent checks it.
+  `decision` awaits a person's decision; `done` means checked under the rule above or needing no human check.
+  A dependency counts as met at `review` or `done`; a person's check never blocks further building.
+- **Goal state:** `goal <name> <state> [--thread <id>]`.
+  States: `draft`, `approved`, `running`, `review`, `done`.
+  Propose new goals as files with `state: draft`; set `approved` only under the approval rule above.
+- **Text** (goal, acceptance, progress notes, refs, depends): edit the Markdown directly, then `check`.
+- **New task:** copy the format in [references/format.md](references/format.md); IDs are short, prefixed and unique.
+- **More work:** on request, add tasks to a goal or create a new draft goal, then `check`.
+- Do not add statuses, index files, per-task gates or extra review steps.
+
+## Ownership and commits
+
+Only the stream that owns a task changes it: its `owner`, or else the stream of the running or approved goal whose scope contains it. Work in the planning checkout the project assigns (often your own worktree). After each status change: `check`, commit only your files, `git pull --rebase`, push. If the push is rejected, rebase, run `list` or `next` again, and leave any task that now shows another owner.
+
+## Work a goal
+
+When asked to work a goal, or when a dispatcher starts you for a stream, follow [references/work-a-goal.md](references/work-a-goal.md): one approved goal, built through the project's orchestrator, then stop.

package/skills/planr/assets/board/fonts/LICENSE-mona-sans.txt

@@ -0,0 +1,93 @@
+Copyright (c) 2023, GitHub https://github.com/github/mona-sans
+with Reserved Font Name "Mona Sans"
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting — in part or in whole — any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/skills/planr/assets/board/fonts/LICENSE-monaspace.txt

@@ -0,0 +1,93 @@
+Copyright (c) 2023, GitHub https://github.com/githubnext/monaspace
+with Reserved Font Name "Monaspace", including subfamilies: "Argon", "Neon", "Xenon", "Radon", and "Krypton"
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting — in part or in whole — any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.