planr 0.0.1 → 1.1.16

package/docs/planr-spec/TECH_ARCHITECTURE.md

@@ -0,0 +1,143 @@
+# Technical Architecture
+
+## Architecture Goals
+
+- REQ-ARCH-001: Keep item state, picks, worker runtime state, approval gates, links, log, reviews, and events in one local SQLite source of truth.
+- REQ-ARCH-002: Keep rich product and build plan context in repo-local Markdown files that remain useful without Planr installed.
+- REQ-ARCH-003: Support CLI, MCP, and optional HTTP/SSE as lenses over the same core engine.
+- REQ-ARCH-004: Make Codex, Claude Code, Cursor, and generic MCP clients first-class integration targets.
+- REQ-ARCH-005: Avoid provider-specific logic in the core graph engine.
+
+## System Context Diagram
+
+```text
+Developer
+  -> planr CLI
+     -> Core engine
+        -> SQLite graph database
+        -> .planr Markdown project
+        -> Git repository
+
+Agent clients
+  -> MCP stdio / MCP HTTP
+     -> Core engine
+        -> SQLite graph database
+        -> .planr Markdown project
+
+Optional dashboard
+  -> Local HTTP/SSE server
+     -> Core engine
+```
+
+## Component Boundaries
+
+- `core`: map graph operations, state machine, item readiness, worker runtime state, approval gates, log, reviews, contexts, search.
+- `storage`: SQLite schema, schema upgrades, transactions, FTS indexes.
+- `planpack`: `.planr` project pack, plan parsing, Markdown frontmatter, review artifacts.
+- `cli`: user commands and deterministic output.
+- `mcp`: tools, resources, prompts, capability negotiation.
+- `server`: optional local REST/SSE API.
+- `agents`: integration helpers for Codex, Claude Code, Cursor, and generic clients.
+- `git`: worktree, branch, diff, and changed-file log.
+- `recovery`: stale-pick detection, timeout handling, retry policy, and manual condition reporting.
+- `review_workspace`: local browser review HTML and workspace JSON projection.
+- `packages`: reusable JSON export/import packages with plan snapshots, logs, contexts, and review artifacts.
+
+## Client Architecture
+
+- CLI is the primary client and must be scriptable.
+- TUI/dashboard are optional clients over the same API.
+- MCP clients must receive concise, structured responses optimized for LLM context.
+- All client layers must call core services, not mutate database or Markdown directly.
+
+## Backend Architecture
+
+V1 is a local backend packaged into the CLI binary:
+
+- SQLite database at `.planr/planr.sqlite` by default.
+- WAL mode enabled for concurrent readers and serialized writers.
+- Local service optional for dashboards and long-running agent orchestration.
+- Local review workspace is served from the same localhost HTTP boundary as the REST/SSE API.
+- No cloud backend in V1.
+
+## Data Architecture
+
+- Map state, worker heartbeats, progress, stale ownership data, and approval gates: SQLite.
+- Rich product plans, build plans, and project context: `.planr/*.md`.
+- Live status summaries: SQLite.
+- Search: SQLite FTS over items, contexts, plan metadata/frontmatter/headings, logs, and review summaries.
+- Large artifacts: paths and metadata by default; inline content only for small explicitly provided artifacts.
+
+## AI Architecture
+
+Planr does not call model providers by default. It guides external agents through:
+
+- MCP tools for map, plan, log, and review operations.
+- MCP prompts for `plan`, `work`, `review`, `map`, and `summary` workflows.
+- Client-specific install snippets for Codex, Claude Code, and Cursor.
+- Optional runner wrappers for local Codex/Claude/Cursor CLIs when explicitly configured.
+
+## Auth And Identity
+
+- V1 local mode uses OS user access and file permissions.
+- Worker identity is an explicit `worker_id` string, not an auth boundary.
+- HTTP server binds to localhost by default.
+- Remote HTTP mode is post-V1 and must require authentication.
+
+## Integrations
+
+- Codex: CLI instructions, MCP registration, optional `codex exec` runner, optional `codex review` integration.
+- Claude Code: `.mcp.json` or CLI-based MCP registration guidance.
+- Cursor: `.cursor/mcp.json` project config and global config guidance.
+- Generic MCP: stdio first; streamable HTTP optional.
+- Git: worktree isolation and scoped diff log.
+
+## Security Architecture
+
+- No shell hooks by default.
+- Any command runner must show command, cwd, environment policy, and worker id.
+- Secrets must not be stored in database, plans, logs, or analytics.
+- MCP tools that mutate state must be separated from read-only resources/prompts.
+- Destructive graph operations require preview or explicit flags.
+
+## Privacy Architecture
+
+- Local-only by default.
+- No provider telemetry by default.
+- No content logging by default.
+- Export and delete commands must remove Planr database state and `.planr` artifacts when requested.
+
+## Observability
+
+- Local structured event log in SQLite.
+- Optional JSONL debug log with content scrubbing.
+- `planr doctor` for installation, database, MCP, and client integration checks.
+- `planr trace item <id>` for item lifecycle debugging.
+
+## Deployment Environments
+
+- Local development: source checkout and debug binary.
+- Local production: installed binary via package manager or release asset.
+- CI: headless CLI mode with explicit db/path.
+- Hosted/team: out of scope for V1.
+
+## Failure Modes
+
+- Database locked: retry bounded writes, then return actionable diagnostic.
+- Corrupt Markdown plan: preserve file, mark parse status degraded, keep map usable.
+- Missing MCP client support: print manual CLI instructions.
+- Agent run interrupted: keep item picked/running with heartbeat timeout and release/re-pick command.
+- Recovery sweep interrupted: preview is non-mutating; apply mutates only listed recoverable work and records events.
+- Review fails: create fix item chain instead of closing the parent.
+- Package import cancelled: preview leaves database and `.planr` files unchanged.
+
+## Scalability Assumptions
+
+- V1 target: hundreds of projects, tens of thousands of items, thousands of plan files per machine.
+- SQLite and FTS are sufficient for V1.
+- Remote multi-user concurrency is post-V1.
+
+## Open Technical Decisions
+
+- OD-ARCH-001: Whether to implement worktree management in core V1 or as an extension.
+- OD-ARCH-002: Whether dashboard uses server-rendered HTML, TUI, or a small SPA.

package/docs/planr-spec/UX_FLOWS.md

@@ -0,0 +1,235 @@
+# UX Flows
+
+## Navigation Model
+
+Planr V1 is CLI-first with optional TUI/dashboard. Public commands use Planr-native vocabulary:
+
+- `planr project`: setup and integration.
+- `planr plan`: reviewable Markdown plans for product specs, build contracts, and review packages.
+- `planr map`: live graph inspection and mutation.
+- `planr item`: item creation and detail.
+- `planr pick`: atomically pick the next ready item.
+- `planr log`: record files, commands, tests, and handoff proof.
+- `planr review`: review/fix/approval loop.
+- `planr close`: close an item with log.
+- `planr doctor`: diagnostics.
+
+## Screen Map
+
+### CLI
+
+- Project status.
+- Item detail.
+- Ready queue.
+- Critical lane.
+- Plan list/detail.
+- Map summary.
+- Log detail.
+- Doctor report.
+
+### Optional TUI/Dashboard
+
+- Project overview.
+- Graph view.
+- Ready/running/blocked map lanes.
+- Plan viewer.
+- Item detail.
+- Log/review panel.
+- Agent runs panel.
+- Diagnostics panel.
+
+## State Machine
+
+```text
+NO_PROJECT -> INITIALIZED
+Trigger: planr project init
+Guard: repo path writable
+Side effects: create database and .planr pack
+Failure behavior: report blocked path and no partial overwrite
+
+INITIALIZED -> PRODUCT_PLANNED
+Trigger: planr plan new
+Guard: project exists
+Side effects: create product plan package
+Failure behavior: show validation errors
+
+PRODUCT_PLANNED -> BUILD_PLANNED
+Trigger: planr plan split
+Guard: product plan has selectable slice
+Side effects: create focused build plan
+Failure behavior: show missing decisions
+
+BUILD_PLANNED -> MAPPED
+Trigger: planr map build --from <plan>
+Guard: plan acceptance criteria are parseable
+Side effects: create linked map items
+Failure behavior: show unmapped requirements
+
+MAPPED -> ITEM_PICKED
+Trigger: planr pick
+Guard: at least one ready item
+Side effects: atomic pick, start run context
+Failure behavior: show blockers or no-ready status
+
+ITEM_PICKED -> EVIDENCE_RECORDED
+Trigger: planr log add
+Guard: log fields valid
+Side effects: write log and attach to item/run
+Failure behavior: keep item running/blocked with diagnostic
+
+EVIDENCE_RECORDED -> ITEM_CLOSED
+Trigger: planr close
+Guard: required log and reviews are satisfied
+Side effects: close item, promote downstream items
+Failure behavior: keep item running/blocked with diagnostic
+
+ITEM_CLOSED -> REVIEW_READY
+Trigger: review policy requires review
+Guard: code item completed
+Side effects: create or unlock review item
+Failure behavior: parent stays incomplete
+```
+
+## Onboarding Flow
+
+1. User runs `planr project init`.
+2. Planr detects repo, Git state, old `.planr` artifacts, and available agent clients.
+3. Planr creates project pack and database.
+4. Planr offers integration commands:
+   - Codex MCP/config.
+   - Claude Code MCP config.
+   - Cursor `.cursor/mcp.json`.
+5. User runs `planr doctor --client all`.
+
+Acceptance criteria:
+
+- REQ-UX-001: Init output must clearly distinguish created files, detected files, and skipped files.
+- REQ-UX-002: Doctor output must show each agent integration as pass, fail, warning, or not installed.
+
+## Product Plan Flow
+
+1. User runs `planr plan new "App idea"`.
+2. Planr captures product intent, platform, users, data sensitivity, AI, monetization, integrations, and launch constraints.
+3. Planr creates a Markdown plan package: product spec, UX, architecture, ADRs, safety/privacy/security, API/data model, implementation specs, QA, release, and task checklist.
+4. Planr marks assumptions and open decisions explicitly.
+5. User runs `planr plan check`.
+
+Acceptance criteria:
+
+- REQ-UX-010: A created plan must include product, UX, architecture, safety/privacy/security, data/API, QA, release, and task files unless explicitly scoped down.
+- REQ-UX-011: Plan checks must report missing required sections, open decisions, and validation warnings.
+
+## Implementation Plan Flow
+
+1. User or agent runs `planr plan split <plan> --slice "MVP backend"`.
+2. Planr creates a focused Markdown plan with source, scope decision, ownership target, phases, verification, and acceptance criteria.
+3. Planr links the build plan to source product plan requirement IDs.
+4. User runs `planr plan check`.
+
+Acceptance criteria:
+
+- REQ-UX-012: A build plan must be narrow enough to seed executable map items.
+- REQ-UX-013: Plan linking must show source plan id, requirement ids, derived plan path, and relationship.
+
+## Map Seeding Flow
+
+1. User runs `planr map build --from <plan>`.
+2. Planr creates candidate map items and links.
+3. User accepts, edits, or rejects candidates.
+4. Accepted items enter the map as pending/ready.
+
+Acceptance criteria:
+
+- REQ-UX-014: Plan work lists must not silently become live map work without acceptance.
+- REQ-UX-015: Seeded items must retain links to their source product or build plan requirements.
+
+## Agent Execution Flow
+
+1. Agent calls `planr_pick_item` or `planr pick`.
+2. Planr returns item, linked plan context, upstream handoff, relevant contexts, and conflicts.
+3. Agent works in repo.
+4. Agent records log.
+5. Agent closes the item when log and reviews allow it.
+6. Planr promotes downstream items.
+7. If review is required, a review item becomes ready.
+
+Acceptance criteria:
+
+- REQ-UX-020: The pick response must fit in an LLM context window by default and include links for deeper reads.
+- REQ-UX-021: Closure must show unlocked items and remaining blockers.
+- REQ-UX-022: Agents must treat parent gate items as completion gates and work executable child items when a child implementation or test item exists.
+
+## Parent Gate Flow
+
+1. User or agent creates a parent item for the material change.
+2. User or agent breaks the parent into implementation or test child work with `planr item breakdown`.
+3. User or agent requests review on the implementation or test child after evidence exists.
+4. Downstream top-level work depends on the parent gate when review cleanliness matters.
+5. Parent closes only after child work closes and review findings have either passed or been converted into fix/follow-up review work.
+
+Acceptance criteria:
+
+- REQ-UX-025: Parent item detail must make clear whether open children or reviews block closure.
+- REQ-UX-026: Recovery views must show the child implementation, review, logs, and blockers needed to continue safely.
+
+## Review/Fix Flow
+
+1. Review item is picked.
+2. Reviewer inspects linked plan, log, and scoped Git diff.
+3. Reviewer returns verdict:
+   - complete;
+   - not complete with findings;
+   - unclear/partially verified.
+4. Findings create fix item and follow-up review item.
+5. Parent closes only when review chain passes.
+
+Acceptance criteria:
+
+- REQ-UX-030: Review findings must be visible in item detail and log detail.
+- REQ-UX-031: Parent completion must explain which review item blocks it.
+
+## Handoff And Story Flow
+
+1. Agent records proof with `planr log add`.
+2. Agent records reusable discoveries with `planr context add`.
+3. Agent records task-local coordination with `planr note add`.
+4. If the decision chain is too long for logs and contexts, the operator creates or updates a story log.
+
+Acceptance criteria:
+
+- REQ-UX-035: Logs must remain the proof surface for closure.
+- REQ-UX-036: Context entries must be searchable and safe to expose to future agents.
+- REQ-UX-037: Story logs must be documented as narrative memory and must not override map state.
+
+## Error, Empty, Offline, Loading States
+
+- No project: show `planr project init`.
+- No ready item: show blockers and critical lane.
+- Database locked: show retry and owning process if known.
+- Plan parse error: show file path, line if available, and keep graph usable.
+- MCP client missing: show manual config.
+- Agent command failed: record failed run and keep task recoverable.
+
+## Settings, Export, Delete, Account Flows
+
+- No account settings in V1.
+- Settings live in `.planr/config.toml` or user config.
+- Export includes database dump, plan files, reviews, and references.
+- Delete requires explicit project id or path and confirmation.
+
+## Accessibility Behavior
+
+- CLI output must support `--json` and no-color mode.
+- TUI/dashboard must support keyboard navigation, visible focus, screen-reader labels, and reduced motion.
+
+## Localization Behavior
+
+- V1 command output is English.
+- User-authored plan content may be any language.
+- Error codes are stable and machine-readable.
+
+## Acceptance Criteria
+
+- REQ-UX-900: Every primary flow must be executable without a web UI.
+- REQ-UX-901: Every mutation must have a JSON mode for automation.
+- REQ-UX-902: Every blocked state must show the next actionable command or reason.

package/docs/planr-spec/V1_1_DIFFERENTIATION_CONTRACT.md

@@ -0,0 +1,177 @@
+# V1.1 Differentiation Contract
+
+Generated: 2026-06-09
+
+## Purpose
+
+This contract defines the Planr-owned V1.1 acceptance baseline. It turns the remaining product gaps into implementation-ready requirements without relying on external product names, copied command vocabulary, or hidden context.
+
+V1.1 is complete only when Planr can prove these capabilities from its own CLI, MCP, HTTP, local review workspace, docs, tests, and real consumer usage.
+
+## Product Outcome
+
+Planr V1.1 must feel like one coherent product:
+
+```text
+idea -> product plan -> build plan -> map -> pick -> work -> log -> review -> recover -> close
+```
+
+The map remains the source of truth for execution state. Markdown plans remain the source of rich product and implementation context. Review and recovery must be evidence-backed, not optimistic.
+
+## Capability Requirements
+
+### Graph Intelligence
+
+- REQ-V11-GRAPH-001: `planr map lane --critical` must compute a real critical path across blocking graph edges, not just sort open items by priority.
+- REQ-V11-GRAPH-002: `planr map pressure` must report transitive downstream impact, direct blockers, and why each item matters.
+- REQ-V11-GRAPH-003: Map reads must detect and report cycles with enough edge detail for a user or agent to repair the graph.
+- REQ-V11-GRAPH-004: Unlock and lookahead views must explain what becomes ready after closure, what remains blocked, and which blockers are still active.
+- REQ-V11-GRAPH-005: Mutation previews must share one effect engine for close, cancel, insert, replan, and dependency rewires.
+- REQ-V11-GRAPH-006: CLI, MCP, HTTP, and JSON responses must use the same graph-analysis results.
+
+Acceptance:
+
+- A branched fixture with deep dependencies returns the mathematically longest open blocking path.
+- A transitive bottleneck ranks above a shallow item that only blocks one direct child.
+- A cyclic graph is refused or diagnosed before readiness or critical-path output becomes misleading.
+
+### Automatic Pick Recall
+
+- REQ-V11-RECALL-001: `planr pick` and `planr_pick_item` must return a compact task-start package.
+- REQ-V11-RECALL-002: The package must include ranked relevant project contexts, upstream logs or handoffs, linked plan references, active blockers or unlocks, review/fix history, and deeper-read commands.
+- REQ-V11-RECALL-003: Recall ranking must search item title, description, linked plan metadata, contexts, logs, and review summaries.
+- REQ-V11-RECALL-004: Pick recall must be size-bounded and avoid source file content, prompt transcripts, secret-looking values, and large artifacts by default.
+- REQ-V11-RECALL-005: Possible file conflicts must be surfaced from recent logs, artifacts, and active picked/running work when enough path evidence exists.
+
+Acceptance:
+
+- A task with relevant historical decisions receives those decisions without the user running a separate search.
+- Irrelevant contexts are omitted or ranked below relevant ones.
+- The response remains compact enough for an agent handoff and includes deeper-read commands for full detail.
+
+### Recovery Automation
+
+- REQ-V11-RECOVERY-001: Planr must provide a sweeper command and API that inspect interrupted work without silently mutating by default.
+- REQ-V11-RECOVERY-002: Timeouts must be stored on items and evaluated consistently for CLI, MCP, and HTTP flows.
+- REQ-V11-RECOVERY-003: Retry policy must support max attempts, retry count, fixed or exponential delay, and clear terminal state when retries are exhausted.
+- REQ-V11-RECOVERY-004: Stale picks must be reclaimable only through explicit recovery action or a documented sweeper mode.
+- REQ-V11-RECOVERY-005: Item preconditions and postconditions must be visible in pick, trace, review, and close-preview outputs.
+- REQ-V11-RECOVERY-006: Close preview must show unsatisfied conditions, missing evidence, open reviews, open child work, and approval blockers in one gate report.
+
+Acceptance:
+
+- An interrupted picked item is diagnosed, optionally released, and then picked by a later worker without duplicate ownership.
+- A failed retryable item returns to ready only after the documented delay.
+- A postcondition appears in review and close-preview output before the item closes.
+
+### Local Browser Review Workspace
+
+- REQ-V11-REVIEW-UI-001: Planr must ship a local browser workspace reachable from the local HTTP server or an explicit CLI command.
+- REQ-V11-REVIEW-UI-002: The workspace must support plan/package review, plan revision diff, item review detail, inline annotations, and approve/request-changes feedback.
+- REQ-V11-REVIEW-UI-003: When Git evidence is available, the workspace must show scoped file changes or a clear explanation of missing diff context.
+- REQ-V11-REVIEW-UI-004: Feedback must write Planr review annotations, review artifacts, and map-native fix/follow-up review items through existing review rules.
+- REQ-V11-REVIEW-UI-005: The workspace must remain local-first and must not require a hosted account or network service.
+
+Acceptance:
+
+- A reviewer can open a local URL, annotate a plan or item, request changes, and see the map create follow-up work.
+- A clean review can write an artifact and close the review item through Planr state.
+- Browser smoke tests prove the workspace renders and can exercise the annotation flow.
+
+### Scoped Git And PR Review
+
+- REQ-V11-GIT-001: Planr must detect the current Git worktree and record branch, commit, dirty state, and changed-file scope in review evidence.
+- REQ-V11-GIT-002: Review flows must distinguish agent-owned evidence from unrelated dirty files.
+- REQ-V11-GIT-003: Item logs and artifacts must be able to reference changed files and line-level findings without storing full source contents by default.
+- REQ-V11-GIT-004: Optional PR URL review may be implemented when a provider can be queried safely; otherwise V1.1 must clearly document local-only behavior and future PR support.
+- REQ-V11-GIT-005: Review output must tie findings to item id, file path, optional line, evidence source, and next action.
+
+Acceptance:
+
+- A dirty worktree with unrelated files does not let an agent claim broad ownership.
+- Review artifacts show which files were considered and which were excluded.
+- File and line annotations survive export/import.
+
+### Distribution And Client Setup
+
+- REQ-V11-DIST-001: README and install docs must make GitHub Release curl installation the normal user path.
+- REQ-V11-DIST-002: Homebrew instructions must be present as soon as a tap or formula path exists; until then docs must state the release condition clearly.
+- REQ-V11-DIST-003: Cargo and source build instructions must be maintainer/developer paths, not the primary user install story.
+- REQ-V11-DIST-004: `planr install` or equivalent setup commands must cover Codex, Claude Code, Cursor, and generic MCP without editing global configuration unexpectedly.
+- REQ-V11-DIST-005: `planr prompt` or an equivalent command must expose ready-to-use CLI, MCP, and HTTP instructions.
+- REQ-V11-DIST-006: Release artifacts must have checksums and documented verification steps.
+
+Acceptance:
+
+- A fresh machine can install from release assets using only documented commands.
+- A project can configure each supported client from Planr docs or CLI output.
+- Package dry-runs show only intentional files.
+
+### Templates And Review Packages
+
+- REQ-V11-TEMPLATE-001: Export/import must support map items, links, plans, contexts, logs, review artifacts, and metadata.
+- REQ-V11-TEMPLATE-002: Templates must include package requirements metadata, Planr version, creation timestamp, source project name, and optional tags.
+- REQ-V11-TEMPLATE-003: Import must preview what will be created or skipped before mutating existing projects.
+- REQ-V11-TEMPLATE-004: Review packages must preserve annotations, findings, artifacts, and file references.
+- REQ-V11-TEMPLATE-005: Encrypted local bundle sharing may be implemented without hosted infrastructure; if not implemented in V1.1, docs must capture the accepted local-first format and explicit future scope.
+
+Acceptance:
+
+- A proven decomposition can be exported, imported into a fresh project, and picked without losing dependencies.
+- Review annotations survive package export/import.
+- Imports are idempotent or explain conflicts before mutation.
+
+### Documentation And Public Copy
+
+- REQ-V11-DOCS-001: README, CLI reference, MCP contract, operating model, task graph model, install docs, testing docs, and spec files must match implemented V1.1 behavior.
+- REQ-V11-DOCS-002: `docs/planr-spec.zip` must be regenerated after spec changes.
+- REQ-V11-DOCS-003: Docs must use Planr vocabulary: plan, map, item, pick, log, review, context, recovery, package.
+- REQ-V11-DOCS-004: Repo-visible docs and public copy must not mention local comparison products or imply Planr is a fork of another task graph or review tool.
+- REQ-V11-DOCS-005: New commands and APIs must have examples and JSON contract notes where agents rely on them.
+
+Acceptance:
+
+- Docs, fixtures, CLI help, MCP tools, and tests do not drift.
+- A forbidden-reference scrub over public repo paths returns no matches for comparison-product names.
+
+## End-To-End Verification Contract
+
+V1.1 final verification must run from the current worktree and a fresh consumer project at `~/projects/planr-test`.
+
+Required repository checks:
+
+- `cargo fmt --check`
+- `cargo clippy --all-targets -- -D warnings`
+- `cargo test`
+- `scripts/build-release.sh`
+- checksum verification for release assets and packaged files
+- `npm pack --dry-run` when the npm wrapper remains present
+- `scripts/ci-local.sh`
+- MCP stdio contract smoke
+- HTTP/SSE smoke
+- local browser review workspace smoke
+- forbidden-reference scrub over public repo paths
+
+Required consumer checks in `~/projects/planr-test`:
+
+- install or invoke the built Planr binary without relying on source-tree paths except for the selected test binary
+- initialize a project
+- create a product plan or build plan
+- build map items
+- pick one item
+- log files, commands, and tests
+- request review
+- annotate or ingest review feedback
+- close review and target item according to gate rules
+- export and import a package/template
+- run documented examples that are meant to work for users
+
+The final V1.1 review must treat missing, stale, narrow, or indirect evidence as incomplete.
+
+## Out Of Scope For V1.1 Unless Explicitly Added
+
+- Hosted accounts, billing, hosted sync, or team permission models.
+- Uploading private plans, source files, prompts, responses, or review content to a hosted service by default.
+- Full project-management SaaS workflows unrelated to coding-agent execution.
+- Silent global agent-client configuration edits.
+- Claiming PR-provider support that was not verified with a real provider or documented local capability boundary.

package/npm/bin/planr.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(here, "..", "..");
+
+function platformTarget() {
+  const osName = { darwin: "darwin", linux: "linux" }[os.platform()];
+  const arch = { arm64: "arm64", x64: "x86_64" }[os.arch()];
+  if (!osName || !arch) {
+    return null;
+  }
+  return `${osName}-${arch}`;
+}
+
+const target = platformTarget();
+const candidates = [
+  process.env.PLANR_NATIVE_BIN,
+  // Published package: per-platform binaries bundled at release time.
+  target && path.join(here, "..", "native", target, "planr"),
+  // Repository checkout: local cargo builds.
+  path.join(packageRoot, "target", "release", "planr"),
+  path.join(packageRoot, "target", "debug", "planr"),
+].filter(Boolean);
+
+const binary = candidates.find(candidate => fs.existsSync(candidate));
+
+if (!binary) {
+  if (!target) {
+    console.error(`Planr has no native binary for ${os.platform()}-${os.arch()}.`);
+    console.error("Supported platforms: darwin-arm64, darwin-x86_64, linux-x86_64, linux-arm64.");
+  } else {
+    console.error("Planr native binary was not found.");
+    console.error("Build it with: cargo build --release");
+    console.error("Or set PLANR_NATIVE_BIN=/absolute/path/to/planr");
+  }
+  process.exit(127);
+}
+
+const result = spawnSync(binary, process.argv.slice(2), {
+  stdio: "inherit",
+  env: process.env,
+});
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 0);

package/package.json

@@ -1,12 +1,31 @@
 {
   "name": "planr",
-  "version": "0.0.1",
-  "description": "A simple planr for cursor",
-  "license": "ISC",
-  "author": "",
-  "type": "commonjs",
-  "main": "index.js",
+  "version": "1.1.16",
+  "description": "Local-first planning and execution coordination for coding agents.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/instructa/planr.git"
+  },
+  "type": "module",
+  "bin": {
+    "planr": "npm/bin/planr.js"
+  },
+  "files": [
+    "npm/bin/planr.js",
+    "npm/native",
+    "plugins",
+    "README.md",
+    "LICENSE.md",
+    "docs"
+  ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  }
+    "build:native": "cargo build --release",
+    "test": "cargo test",
+    "pack:check": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "pnpm@11.5.3+sha512.7ac1c919341c213a34dc0d02afb7143c5c26ac26ee8c4782deea821b8ac64d2134a081fd8941dae6e29bbb48f58dfc2b7fbceeccc07cb2f09d219d342a4969ed"
 }

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

@@ -0,0 +1,11 @@
+{
+  "name": "planr",
+  "description": "Skill-driven planning and execution loop for coding agents: one planr entry point, an autonomous planr-loop, and evidence-backed task graph skills powered by the planr CLI.",
+  "version": "1.1.16",
+  "author": {
+    "name": "instructa"
+  },
+  "homepage": "https://github.com/instructa/planr",
+  "repository": "https://github.com/instructa/planr",
+  "license": "MIT"
+}