Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 0 additions & 18 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -60,24 +60,6 @@ jobs:
pnpm docs:verify-agent-landing
pnpm --filter @planr/docs verify:agent-markdown

- name: Verify browser interactions and accessibility
run: |
pnpm docs:start > /tmp/planr-docs-server.log 2>&1 &
docs_server_pid=$!
trap 'kill "$docs_server_pid"' EXIT
for attempt in $(seq 1 120); do
if curl --fail --silent http://127.0.0.1:3000/llms.txt >/dev/null; then
break
fi
if ! kill -0 "$docs_server_pid" 2>/dev/null; then
sed -n '1,200p' /tmp/planr-docs-server.log
exit 1
fi
sleep 0.25
done
curl --fail --silent http://127.0.0.1:3000/llms.txt >/dev/null
CHROME_PATH="$(command -v google-chrome)" PLANR_DOCS_URL=http://127.0.0.1:3000 pnpm docs:verify-shell

- name: Verify documented graph semantics against this repository
run: pnpm docs:verify-concepts

Expand Down
2 changes: 1 addition & 1 deletion .planr/plans/product/planr/AI_SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Planr does not need to call AI providers in V1. Its AI role is to coordinate ext
## Model/Provider Strategy

- REQ-AI-001: Planr must not require a specific model provider.
- REQ-AI-002: Planr must support Codex, Claude Code, Cursor, explicitly opted-in Grok Build, and generic MCP clients through shared MCP contracts.
- REQ-AI-002: Planr must support Codex, Claude Code, Cursor, explicitly opted-in Grok Build and Pi, and generic MCP clients through shared CLI/MCP contracts and host-native skills where supported.
- REQ-AI-003: Client-specific runners may exist, but core graph operations must remain provider-neutral.

## Prompt Architecture
Expand Down
24 changes: 20 additions & 4 deletions .planr/plans/product/planr/API_AND_DATA_MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -319,12 +319,12 @@ isProject: false
### Project

```bash
planr project init [--client codex|claude|cursor|grok|all] [--force]
planr project init [--client codex|claude|cursor|grok|pi|all] [--force]
planr project show [--json]
planr project list [--json]
planr doctor [--client codex|claude|cursor|grok|all]
planr install codex|claude|cursor|grok [--dry-run]
planr prompt cli|mcp|http [--client codex|claude|cursor|grok|all]
planr doctor [--client codex|claude|cursor|grok|pi|all]
planr install codex|claude|cursor|grok|pi [--dry-run]
planr prompt cli|mcp|http|routing [--client codex|claude|cursor|grok|pi|all]
planr mcp
planr serve --port 7526
planr import <file> [--preview] [--confirm]
Expand Down Expand Up @@ -470,6 +470,22 @@ The exact `PLANR_MCP_CLIENT=grok` child-process marker may populate
advisory evidence, never authentication or worker identity. Grok v1 writes no
hooks and remains outside the legacy `--client all` expansion.

## Pi Project Contract

`planr install pi` reconciles the canonical Planr skill tree under
`.pi/skills/` and Pi-specific optional `pi-subagents` roles under
`.pi/agents/`. It writes no MCP configuration, extension, hook, prompt,
settings file, package metadata, credential, provider, model, or global state.

Pi project resources load only after the operator trusts the repository.
Interactive Pi owns the trust prompt; intentional non-interactive runs pass
`--approve`. Planr never writes the Pi trust store. Pi's exact
`PI_CODING_AGENT=true` child-process marker may populate
`runs.observed_client=pi`; other Pi environment values may not. The marker is
advisory evidence, never authentication, worker identity, model proof, or proof
that `pi-subagents` is installed. Pi remains outside the legacy
`--client all` expansion.

## HTTP API

HTTP is optional in V1 and localhost-only by default.
Expand Down
16 changes: 9 additions & 7 deletions .planr/plans/product/planr/PRODUCT_SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Planr turns broad product ideas and coding work into a coherent flow: product pl
## Target Users

- Individual developers running one or more coding agents locally.
- Power users coordinating Codex, Claude Code, Cursor, Grok Build, Gemini CLI, or custom MCP agents in the same repo.
- Power users coordinating Codex, Claude Code, Cursor, Grok Build, Pi, Gemini CLI, or custom MCP agents in the same repo.
- Teams that want repo-local planning artifacts before adopting a hosted workflow.
- Agent builders who need a small coordination primitive for local or CI-based agent workers.

Expand All @@ -28,7 +28,7 @@ Planr turns broad product ideas and coding work into a coherent flow: product pl
- Local first: the repository plus a local database should be enough.
- Product plans capture intent, build plans capture implementation context, and the map coordinates live work.
- Log over optimism: completion is proven, not declared.
- Cross-agent by default: Codex, Claude Code, Cursor, Grok Build, and MCP clients are peers.
- Cross-agent by default: Codex, Claude Code, Cursor, Grok Build, Pi, and MCP clients are peers.
- Hard-cut bias: avoid duplicate sources of truth and transitional shells.
- Human-readable artifacts: all important plans and decisions must be inspectable without a proprietary UI.

Expand All @@ -37,9 +37,9 @@ Planr turns broad product ideas and coding work into a coherent flow: product pl
- A `planr` CLI.
- A local SQLite map graph with items, links, picks, contexts, artifacts, logs, reviews, runs, and events.
- A `.planr/` repo pack for plans, project context, review artifacts, and skill/prompt templates.
- MCP server exposing tools, resources, and prompts for Claude Code, Cursor, Codex, Grok Build, and compatible clients.
- MCP server exposing tools, resources, and prompts for Claude Code, Cursor, Codex, Grok Build, and compatible MCP clients; Pi uses native Agent Skills and the CLI because its core intentionally omits MCP.
- Optional HTTP/SSE local server for dashboard and automation clients.
- Codex, Claude Code, Cursor, and explicitly opted-in Grok Build install/config helpers.
- Codex, Claude Code, Cursor, and explicitly opted-in Grok Build and Pi install/config helpers.
- Import of existing `.planr` data.
- Export/import of map graph and Markdown plan packs.
- Explicit recovery sweeps for stale, timed-out, and retryable work.
Expand Down Expand Up @@ -96,7 +96,7 @@ idea -> product plan -> build plan -> map -> pick -> log -> review/evidence -> r

## Core User Journeys

- Initialize Planr in a repo and configure Codex, Claude Code, Cursor, or Grok Build.
- Initialize Planr in a repo and configure Codex, Claude Code, Cursor, Grok Build, or Pi.
- Create a plan from a broad app idea or PRD request.
- Convert product plan slices into build plans.
- Seed map items from a plan.
Expand All @@ -114,8 +114,9 @@ idea -> product plan -> build plan -> map -> pick -> log -> review/evidence -> r
### Initialization

- REQ-PROD-010: `planr project init` must create `.planr/`, `.planr/project/`, `.planr/plans/`, `.planr/reviews/`, and a local database without overwriting user content unless `--force` is provided.
- REQ-PROD-011: `planr project init --client codex|claude|cursor|grok|all` must print or apply integration instructions for the selected client; the legacy `all` selection excludes Grok so adoption remains explicit.
- REQ-PROD-011: `planr project init --client codex|claude|cursor|grok|pi|all` must print or apply integration instructions for the selected client; the legacy `all` selection excludes Grok and Pi so adoption remains explicit.
- REQ-PROD-013: `planr install grok` must write only repository-local native Grok skills, agents, and portable MCP configuration; it must not install hooks, credentials, provider SDKs, or a project plugin.
- REQ-PROD-014: `planr install pi` must write only repository-local native Pi skills and optional `pi-subagents` roles; it must not install MCP, extensions, hooks, settings, packages, credentials, or provider SDKs.
- REQ-PROD-012: Initialization must detect existing `.planr` data and offer import commands.

### Product Plans
Expand All @@ -142,7 +143,7 @@ idea -> product plan -> build plan -> map -> pick -> log -> review/evidence -> r

### Agent Execution

- REQ-PROD-050: Planr must provide agent-specific prompts or MCP prompts for Codex, Claude Code, Cursor, and Grok Build.
- REQ-PROD-050: Planr must provide agent-specific prompts or MCP prompts for Codex, Claude Code, Cursor, Grok Build, and Pi.
- REQ-PROD-051: Runs must record worker id, client, model/profile when available, item id, command surface, start/end time, and result status.
- REQ-PROD-052: Item closure must require or allow a log entry with files changed, tests run, commands run, result summary, and blocked/unverified items.
- REQ-PROD-053: Review findings must create fix items rather than failing ordinary code items.
Expand All @@ -167,6 +168,7 @@ idea -> product plan -> build plan -> map -> pick -> log -> review/evidence -> r
- Claude Code MCP project/user configuration.
- Cursor MCP project/global configuration.
- Grok Build native repository skills/agents and portable `.grok/config.toml`; no hooks in v1.
- Pi native repository skills and optional `pi-subagents` roles; no MCP, extension, settings, or hooks in v1.
- Generic MCP clients via stdio and optional streamable HTTP.
- Git worktrees and Git diff logs.
- Optional CI invocation for verification tasks.
Expand Down
4 changes: 2 additions & 2 deletions .planr/plans/product/planr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Generated: 2026-06-09

## Purpose

This package defines Planr as a production-grade, local-first planning and execution coordination tool for coding agents. Planr combines product plans, build plans, and a live dependency-aware map with reviewable logs and integration surfaces for Codex, Claude Code, Cursor, explicitly opted-in Grok Build, and other MCP-capable agents.
This package defines Planr as a production-grade, local-first planning and execution coordination tool for coding agents. Planr combines product plans, build plans, and a live dependency-aware map with reviewable logs and integration surfaces for Codex, Claude Code, Cursor, explicitly opted-in Grok Build and Pi, and other CLI- or MCP-capable agents.

## Package Contents

Expand All @@ -30,7 +30,7 @@ Two frozen contracts were split out of this package because CI gates them direct

- V1 is a local-first developer tool, not a hosted SaaS.
- The first implementation may be a Rust CLI and local daemon using SQLite.
- Codex, Claude Code, Cursor, and explicitly opted-in Grok Build should all work through standard CLI and MCP integration paths.
- Codex, Claude Code, Cursor, and explicitly opted-in Grok Build and Pi should work through standard native, CLI, or MCP integration paths as their runtimes support.
- Existing `.planr` data may be imported, but the V1 CLI, data model, and docs define the final product API.
- Planr should ship with its own name, code, docs, and architecture.

Expand Down
12 changes: 7 additions & 5 deletions .planr/plans/product/planr/TASKS.md
Original file line number Diff line number Diff line change
Expand Up @@ -237,7 +237,7 @@ Requirements:
- Keep release curl install as the primary user path.
- Add Homebrew-ready path or explicit tap-publication condition.
- Keep Cargo/source as maintainer workflow.
- Add or document client setup for Codex, Claude Code, Cursor, explicitly opted-in Grok Build, and generic MCP.
- Add or document client setup for Codex, Claude Code, Cursor, explicitly opted-in Grok Build and Pi, and generic MCP.
- Add prompt/config output for CLI, MCP, and HTTP workflows.
- Document checksum verification.

Expand Down Expand Up @@ -638,7 +638,7 @@ Goal:
Expose Planr tools, resources, and prompts over MCP.

Context:
Primary cross-agent integration for Codex, Claude Code, Cursor, and explicitly opted-in Grok Build.
Primary cross-agent integration for Codex, Claude Code, Cursor, explicitly opted-in Grok Build, and generic MCP clients. Pi deliberately uses native skills and the CLI rather than MCP.

Requirements:
- `planr mcp` starts stdio server.
Expand Down Expand Up @@ -695,7 +695,7 @@ Dependencies:
Do not do:
- Do not copy prompt text from another product.

### TASK-CLIENT-001: Add Codex, Claude Code, And Cursor Install Helpers
### TASK-CLIENT-001: Add First-Class Client Install Helpers

Goal:
Make first-run integration practical for all target clients.
Expand All @@ -708,6 +708,8 @@ Requirements:
- `planr install codex --dry-run`.
- `planr install claude --dry-run`.
- `planr install cursor --dry-run`.
- `planr install grok --dry-run`.
- `planr install pi --dry-run`.
- Print project-scoped config examples.

Files or areas likely involved:
Expand Down Expand Up @@ -849,7 +851,7 @@ Files or areas likely involved:
- `src/observability/`.

Acceptance criteria:
- Doctor reports database, `.planr`, Git, MCP, Codex, Claude Code, Cursor, and explicitly selected Grok Build.
- Doctor reports database, `.planr`, Git, MCP, Codex, Claude Code, Cursor, and explicitly selected Grok Build or Pi.
- Debug bundle is reviewable before sharing.

Tests:
Expand Down Expand Up @@ -894,7 +896,7 @@ Dependencies:
- TASK-SEC-001.

Do not do:
- Do not rely on live Codex/Claude/Cursor/Grok Build for core CI tests.
- Do not rely on live Codex/Claude/Cursor/Grok Build/Pi for core CI tests.

### TASK-REL-001: Package And Release V1

Expand Down
9 changes: 5 additions & 4 deletions .planr/plans/product/planr/TECH_ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Eval Contract v1 is frozen in [EVAL_CONTRACT_V1.md](EVAL_CONTRACT_V1.md). Eval i
- 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, Grok Build, and generic MCP clients first-class integration targets.
- REQ-ARCH-004: Make Codex, Claude Code, Cursor, Grok Build, Pi, and generic MCP clients first-class integration targets.
- REQ-ARCH-005: Avoid provider-specific logic in the core graph engine.

## System Context Diagram
Expand Down Expand Up @@ -39,7 +39,7 @@ Optional dashboard
- `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, Grok Build, and generic clients.
- `agents`: integration helpers for Codex, Claude Code, Cursor, Grok Build, Pi, 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.
Expand Down Expand Up @@ -76,7 +76,7 @@ Planr does not call model providers by default. It guides external agents throug

- 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, Cursor, and Grok Build.
- Client-specific install snippets for Codex, Claude Code, Cursor, Grok Build, and Pi.
- Optional runner wrappers for local Codex/Claude/Cursor CLIs when explicitly configured.

## Auth And Identity
Expand All @@ -92,12 +92,13 @@ Planr does not call model providers by default. It guides external agents throug
- Claude Code: `.mcp.json` or CLI-based MCP registration guidance.
- Cursor: `.cursor/mcp.json` project config and global config guidance.
- Grok Build: native `.grok/skills/` and `.grok/agents/` plus a document-preserving project `.grok/config.toml` MCP merge. Grok is explicit opt-in, has no Planr hooks in v1, and introduces no provider runtime dependency.
- Pi: native `.pi/skills/` plus optional `pi-subagents` roles under `.pi/agents/`. Pi is explicit opt-in, uses CLI-backed skills because core Pi intentionally omits MCP, has no Planr hooks/extensions/settings in v1, and introduces no runtime dependency.
- Generic MCP: stdio first; streamable HTTP optional.
- Git: worktree isolation and scoped diff log.

## Security Architecture

- Host hooks are repository-local and optional where supported; Grok Build has no Planr hook contract in v1.
- Host hooks are repository-local and optional where supported; Grok Build and Pi have no Planr hook contract in v1.
- 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.
Expand Down
5 changes: 1 addition & 4 deletions apps/docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,13 +35,10 @@ pnpm docs:verify-maintenance
pnpm docs:verify-deployment # direct Cloudflare static artifact
pnpm docs:verify-release
pnpm docs:verify-clean-install # release-readiness gate
pnpm docs:verify-shell # with the dev server running
```

All commands run through the root workspace scripts; no global Fumadocs or Next.js installation is required.

`docs:verify-shell` drives an installed Chrome through the DevTools protocol, exercises the responsive shell and core interactions, captures screenshots under `.planr/artifacts/docs-shell`, and runs axe against representative routes. Set `CHROME_PATH` only when Chrome is not installed in the standard macOS location; set `PLANR_DOCS_URL` when the dev server uses another origin.

`docs:verify-onboarding` first builds `target/debug/planr`, asserts that its version exactly matches both the root `package.json` and `Cargo.toml`, and replays the documented lifecycle in a fresh temporary project. It never falls back to a global `planr` on `PATH`. To test another explicit build of this same repository, run `PLANR_BIN=/absolute/path/to/planr pnpm --filter @planr/docs verify:onboarding`; the version parity assertion still applies.

`docs:verify-concepts` builds the same repository binary, checks the source-level readiness predicates, and replays focused graph fixtures. It asserts that both `blocks` and `hands_to` gate readiness, only `closed`/`closed_partial` upstream items unlock them, cancellation stays blocking, plain `done` closes directly, and `done --review` enters the review branch.
Expand All @@ -58,7 +55,7 @@ All commands run through the root workspace scripts; no global Fumadocs or Next.

## Retired routes

`redirects.mjs` is the executable inventory of retired public documentation URLs. Add a unique source and current destination there, add the same mapping to `docs/documentation/INFORMATION_ARCHITECTURE.md`, repair internal links, then run `pnpm docs:verify-maintenance` and the production browser verifier. Redirects are permanent; repository `docs/*.md` paths are source files rather than website aliases.
`redirects.mjs` is the executable inventory of retired public documentation URLs. Add a unique source and current destination there, add the same mapping to `docs/documentation/INFORMATION_ARCHITECTURE.md`, repair internal links, then run `pnpm docs:verify-maintenance` and `pnpm docs:verify-release`. Redirects are permanent; repository `docs/*.md` paths are source files rather than website aliases.

## Content and generated files

Expand Down
5 changes: 3 additions & 2 deletions apps/docs/components/agent-setup-panel.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -100,8 +100,9 @@ export function AgentSetupPanel() {
<div className="agent-setup-noscript">
JavaScript is not required for setup guidance. Open the permanent recipe for
{' '}<Link href="/docs/integrations/codex">Codex</Link>,
{' '}<Link href="/docs/integrations/claude-code">Claude Code</Link>, or
{' '}<Link href="/docs/integrations/cursor">Cursor</Link>.
{' '}<Link href="/docs/integrations/claude-code">Claude Code</Link>,
{' '}<Link href="/docs/integrations/cursor">Cursor</Link>, or
{' '}<Link href="/docs/integrations/pi">Pi</Link>.
</div>
</noscript>

Expand Down
Loading