planr 0.0.1 → 1.1.16

package/plugins/planr/skills/planr-task-graph/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: planr-task-graph
+description: Use Planr as the live local task graph for coding-agent coordination. Trigger when work needs project planning, build-plan splitting, map creation, dependency links, picking, log-backed closure, review gates, handoff context, interruption recovery, or multi-client coordination.
+---
+
+# Planr Task Graph
+
+Use `planr` as the canonical local coordination system for this repository.
+
+Planr has two first-class layers:
+
+- Markdown plans for product context, build scope, verification, and narrative decisions.
+- SQLite map state for items, links, picks, runtime heartbeats, approvals, contexts, logs, reviews, runs, and closure.
+
+The map is the source of truth for live state. Markdown explains scope and acceptance.
+
+## Start Here
+
+Inspect the project and map before changing work:
+
+```bash
+planr project show --json
+planr map show --json
+planr map lane --critical
+planr map pressure
+```
+
+If no project exists:
+
+```bash
+planr project init "Project Name" --client all
+planr doctor --client all
+```
+
+## Core Loop
+
+Use one item at a time. The short path is two commands per step:
+
+```bash
+planr pick --json
+planr done <item-id> --summary "what changed" --files a --files b --cmd "exact verification command" --tests "exact test command" --review [--next]
+```
+
+`pick --json` returns one flat work packet (item, links, logs, runtime, recovery, conditions, recall context, `remaining` progress); empty collections are omitted. `done` writes the completion log (test runs belong in `--tests`, build/serve commands in `--cmd`), requests review (`--review`, which moves the item to `in_review`) or closes directly, and `--next` picks the following item. Evidence logs refresh the heartbeat automatically.
+
+For longer work, keep the live claim visible:
+
+```bash
+planr pick progress <item-id> --percent 50 --note "tests running"
+planr pick pause <item-id> --note "waiting for human input"
+planr pick resume <item-id>
+```
+
+Capture decisions and discoveries another agent may need:
+
+```bash
+planr context add "decision or discovery" --item <item-id> --tag discovery
+```
+
+Record evidence before review:
+
+```bash
+planr log add --item <item-id> \
+  --summary "what changed" \
+  --files file-a,file-b \
+  --cmd "exact verification command"
+```
+
+Granular alternative: request review, close review, then close the item:
+
+```bash
+planr review request <item-id>
+planr review close <review-id> --verdict complete --close-target
+planr close <item-id> --summary "Verified with evidence"
+```
+
+`--close-target` closes the reviewed item together with the review when the verdict is complete and a completion log exists; the separate `planr close` is then unnecessary.
+
+If human approval is part of the gate, request it and do not close until it is approved:
+
+```bash
+planr approval request <item-id> --reason "release approval"
+planr approval list --open
+```
+
+If review finds issues:
+
+```bash
+planr review close <review-id> \
+  --verdict not-complete \
+  --findings "specific actionable finding"
+planr map show --json
+planr pick --json
+```
+
+Planr creates fix and follow-up review work instead of pretending the parent item is done.
+
+## Planning Flow
+
+For broad app or product work:
+
+```bash
+planr plan new "App idea" --platform web --ai --backend
+planr plan refine <plan-id> --note "Assumption or decision"
+planr plan split <plan-id> --slice "MVP implementation"
+planr plan check <build-plan-id>
+planr map build --from <build-plan-id>
+```
+
+Product plan work lists are candidates. They become live commitments only after `planr map build --from ...`.
+
+`map build` creates items without ordering: everything starts ready. Linking is mandatory before the first pick — add a `blocks` link for every real execution dependency:
+
+```bash
+planr link add <earlier-item> <later-item> --type blocks
+planr map lane --critical
+```
+
+Do not pick from a freshly built map that has zero links unless the items are genuinely independent.
+
+## Parent Gate Pattern
+
+Model material changes as parent gates. The parent is the completion gate; linked children do the work.
+
+Default shape:
+
+```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 a parent item for the change;
+- use `planr item breakdown <parent-id> --into "Implement" --into "Verify"` (one `--into` per child; a single value may also pack newline- or comma-separated titles) to create chained child work under that parent — the output lists every child with id and status plus the next pick command;
+- 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;
+- make later top-level work depend on the parent gate, not only the first child.
+
+Parent gates roll up on their own: when every child is settled, the gate auto-closes unless a review or approval on the gate itself is still open. Do not pick a parent gate as work; `planr pick` skips them.
+
+## Dependencies
+
+Create ordering explicitly:
+
+```bash
+planr item create "Design API" --description "Define endpoints and data ownership."
+planr item create "Implement API" --description "Build endpoints after design is closed."
+planr link add <design-item> <implementation-item> --type blocks
+```
+
+Readiness comes from graph links and item state, not Markdown checkboxes.
+
+Use:
+
+```bash
+planr item breakdown <item-id> --into "Trace owner" --into "Implement" --into "Verify"
+planr link remove <from-item> <to-item> --type blocks
+```
+
+## Handoff Evidence
+
+Every closure must be evidence-backed:
+
+- changed files through `--files`;
+- commands through `--cmd`;
+- tests through `--tests`;
+- remaining risks through context, notes, or findings;
+- review outcome through `planr review ...`.
+
+Use task-local notes for nearby handoff:
+
+```bash
+planr note add "Reviewer asked for an extra package dry-run before closure." --item <item-id>
+```
+
+Use contexts for reusable project knowledge:
+
+```bash
+planr context add "Do not edit global client config without explicit operator approval." --tag constraint
+```
+
+Use a story log only when map state, logs, and contexts are too thin to preserve the decision chain. Story logs are narrative memory, not status authority.
+
+## Recovery
+
+After interruption or handoff:
+
+```bash
+git status --short
+planr project show --json
+planr map show --json
+planr map lane --critical
+planr map pressure
+```
+
+Then inspect the item:
+
+```bash
+planr trace item <item-id>
+planr log list --item <item-id>
+planr context list --item <item-id>
+```
+
+If a stale pick must be reset:
+
+```bash
+planr pick stale --older-than-seconds 900
+planr pick stale --older-than-seconds 900 --release
+planr pick release <item-id> --force
+```
+
+## Completion Rule
+
+Do not call work complete until:
+
+- required child and review items are closed;
+- approval gates are approved or absent;
+- log evidence exists;
+- verification commands were actually run;
+- review findings are closed or converted into follow-up work;
+- `planr map show --json` shows no in-scope blocker;
+- the user-facing summary matches map, logs, and review state.
+
+For release-grade scopes, rerun the full verification ladder from the repository testing guide.

package/plugins/planr/skills/planr-verify-web/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: planr-verify-web
+description: Live verification for web features. Use when a web map item needs proof it actually runs in a browser before review, including planr-loop step 4. Discovers the host's existing browser capability, runs the changed flow against the dev server, and logs replayable evidence. Ships no browser tooling of its own.
+---
+
+# Planr Verify Web
+
+Prove the feature runs. Planr owns the evidence contract; the host owns the browser tooling. Never install or configure browser infrastructure on behalf of this skill.
+
+## Capability Discovery
+
+Check project memory first:
+
+```bash
+planr context list
+```
+
+If a `capability`-tagged entry records a web verification tool, use it. Otherwise discover what the host has, strongest first:
+
+1. A browser skill the host already provides (for example browser-harness): drive the real flow, screenshot the result.
+2. A browser MCP already configured (Playwright, chrome-devtools, native browser tools): same.
+3. The system browser over CDP: launch the installed Chrome/Chromium with `--remote-debugging-port=<port> --user-data-dir=<tmp>` and drive it via the DevTools protocol. This is the standard rescue when a browser tool exists but its bundled browser is missing — the tool's download step is not a dependency, the protocol is.
+4. A scriptable fallback when Node is available: a one-off headless check via `npx playwright` whose exit code is the signal.
+5. HTTP-level checks (`curl` against rendered routes or endpoints): weakest tier, only for SSR/API-shaped changes, and the log must say "HTTP-level only, not browser-verified".
+
+If a tier fails for an environmental reason (missing download, sandbox restriction), drop to the next tier and record what actually worked — do not log the environmental failure as item evidence.
+
+Record the decision once so later iterations and other agents reuse it instead of re-discovering:
+
+```bash
+planr context add "web verification: <tool>, invoke via <how>" --tag capability
+```
+
+A human may pin the capability upfront with the same command; a pinned context always wins over discovery.
+
+## Dev Server
+
+Detect a running dev server before anything else and use it. Never start a second instance. Only start one (in the background, and stop it afterwards) when none is running and the loop is unattended.
+
+## Run The Verification
+
+Exercise the flow the item changed — not the homepage. Interact, assert on rendered output, capture a screenshot when the tier supports it.
+
+Then log evidence on the item:
+
+```bash
+planr log add --item <item-id> --kind verification \
+  --summary "live verification (<tier>): <what was exercised and observed>" \
+  --cmd "<exact replayable command>"
+```
+
+`--kind verification` marks the log as live-verify evidence; `planr plan audit` checks for it when a goal contract exists.
+
+Attach screenshots or traces as artifacts on the item:
+
+```bash
+planr artifact add "verify-web screenshot" --item <item-id> --path <screenshot-path> --kind screenshot
+```
+
+The replay command is mandatory. The reviewer reruns it instead of trusting this run; a verification that cannot be replayed is not evidence.
+
+## When Verification Is Impossible
+
+No capability, no Node, no reachable server: do not fake it and do not downgrade silently.
+
+```bash
+planr context add "live verification blocked: <missing capability>" --item <item-id> --tag blocker
+planr approval request <item-id> --reason "manual live verification required"
+```
+
+Then pause (or let `planr-loop` pause) until a human resolves it.
+
+## Outcome
+
+- Pass: evidence logged, proceed to `planr review request <item-id>`.
+- Fail: the feature does not work — log the failing command and observed behavior, then fix under the same item before requesting review. A failed live run is a finding against the implementation, never a reason to weaken the check.

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

@@ -0,0 +1,68 @@
+---
+name: planr-work
+description: Execute one Planr map item to evidence-backed completion. Use after a task has been picked or when the next step is implementation, docs, tests, scripts, integration work, or a fix item.
+---
+
+# Planr Work
+
+Use this for one picked item at a time.
+
+## Workflow
+
+Export your worker identity once per session so picks, logs, and heartbeats attribute to you instead of `client:host:user`:
+
+```bash
+export PLANR_WORKER_ID=maker-1
+planr pick --json
+```
+
+The pick output is one flat work packet — item, links, logs, runtime, recovery, conditions, recall context (`upstream_handoffs`, `relevant_contexts`, `review_history`), and `remaining` progress. Each fact appears once; a missing key means "empty". No separate `trace item` call needed. Add `--work-type code` to skip review items when checker agents work the same board, and `--plan <plan-id>` when your dispatch names a plan so the lease stays inside that scope. A null pick explains itself: `{"item": null}` carries a `reason` (`all_settled`, `nothing_ready`, `ready_items_excluded_by_filter`) plus the `remaining` snapshot; when filters excluded ready work, `excluded` names each item and cause and `repair` carries the exact pick command to run instead. Read the linked plan/context, implement the smallest correct slice, then finish the step in one command:
+
+```bash
+planr done <item-id> --summary "what changed" --files path-a --files path-b --cmd "exact verification command" --tests "exact test command" --review
+```
+
+Put build/serve commands in `--cmd` and test runs in `--tests` — both are recorded as evidence. `done --review` writes the completion log, requests the review, and moves the item to `in_review` (you keep ownership; it is waiting on the gate, not abandoned); add `--next` to pick the following item in the same call. Without `--review` it closes the item directly (only for items that need no review gate). The response reports what your settlement `unlocked`, echoes the item's post condition, and hints when downstream work depends on an item closed without command/test evidence.
+
+Live verification (browser flow, executed binary, real requests) gets its own log kind so `plan audit` can find it:
+
+```bash
+planr log add --item <item-id> --kind verification --summary "verified <flow>: <observed outcome>" --cmd "<exact command>"
+```
+
+Log persistent evidence, not transient noise: a failure you immediately fixed belongs in the final log's narrative, not as a standalone failure log. Only record a failure separately when it blocks the item.
+
+Evidence logging refreshes the heartbeat automatically — a separate `planr pick heartbeat` is only needed for long silent stretches without logs.
+
+The granular commands remain available when you need them:
+
+```bash
+planr log add --item <item-id> --summary "..." --files a --files b --cmd "..."
+planr review request <item-id>
+planr close <item-id> --summary "Verified"
+```
+
+For longer work, keep runtime state current:
+
+```bash
+planr pick progress <item-id> --percent 50 --note "tests running"
+planr pick pause <item-id> --note "waiting for human input"
+planr pick resume <item-id>
+```
+
+If a human approval gate is required, request it before close and wait for an approved decision:
+
+```bash
+planr approval request <item-id> --reason "release approval"
+planr approval list --open
+```
+
+## Rules
+
+- Do not work on multiple picked items unless the user explicitly asks.
+- Do not close without evidence.
+- Do not treat a failed review as failure of the original item; let Planr create the fix and follow-up review chain.
+- Do not close items with pending or denied approval.
+- Use `planr context add ... --item <item-id>` for discoveries another client needs.
+- Use `planr pick stale --older-than-seconds 900` before resetting abandoned ownership.
+- Use `planr pick release <item-id> --force` only when ownership must be reset.