planr 1.7.3 → 1.8.0

package/README.md

@@ -2,7 +2,7 @@
 
 ![Planr — turn chaotic agent work into a verified task graph](public/planr_banner1.webp)
 
-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, generic MCP clients, and human operators can drive the same work safely — from idea to verified completion.
+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, generic MCP clients, and human operators can drive the same work safely — from idea to verified completion.
 
 [**View the Demo →**](https://x.com/kevinkern/status/2066957434564808884?s=20)
 
@@ -53,7 +53,7 @@ curl -fsSL https://raw.githubusercontent.com/instructa/planr/main/scripts/instal
 > 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:
+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 is a separate explicit opt-in and is not included by `all`:
 
 ```bash
 planr project init "My Product" --client all
@@ -106,6 +106,23 @@ The dry-run also prints a one-click `cursor://` deeplink for user-level MCP inst
 
 </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-plugin-opencode"></a>
 <details>
 <summary><strong>opencode</strong></summary>
@@ -183,6 +200,7 @@ The watcher is likewise a human-only observer. It defaults to the condensed diag
 
 ## What's new
 
+- **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).
@@ -202,7 +220,7 @@ Full documentation lives at [planr.so/docs](https://planr.so/docs).
 - [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)
+- [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)
 - [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)

package/docs/ARCHITECTURE.md

@@ -19,7 +19,9 @@ Planr V1 is a single Rust binary with explicit module ownership. The crate stays
 - `src/main.rs`: process composition root. Owns top-level module wiring, process startup, database opening, error printing, and dispatch into `App`.
 - `src/cli.rs`: CLI contract boundary. Owns `clap` command definitions, option parsing types, value enums, and command DTOs used by app dispatch.
 - `src/app/mod.rs`: application composition boundary. Owns the `App` runtime state, top-level dispatch, shared app-local row helpers, and app submodule wiring.
-- `src/app/commands.rs`: CLI use-case orchestration. Owns project, plan, map, item, link, pick, approval, log, close, review, context, search, doctor, and install command handlers.
+- `src/app/commands.rs`: general CLI use-case orchestration. Owns project, plan, map, item, link, pick, approval, log, close, review, context, search, doctor, and shared install command handlers.
+- `src/app/grok.rs`: Grok-specific install orchestration. Owns safe project TOML reconciliation, repository workflow writes, and the explicit no-hooks result.
+- `src/app/prompts.rs`: CLI, MCP, and HTTP prompt output. Host routing prompt composition remains in `src/app/agents.rs`.
 - `src/app/flow.rs`: compound work-flow boundary. Owns evidence log writing (with heartbeat folding), the close transition core, review-request creation, the pick work packet, and the `done` command that chains them for CLI, HTTP, and MCP surfaces.
 - `src/app/git_review.rs`: Git and PR review evidence boundary. Owns worktree detection, scoped changed-file provenance, PR URL context, and dirty-worktree safety projections.
 - `src/app/mcp.rs`: MCP stdio boundary. Owns MCP protocol request routing, tool calls, resource reads, and prompt responses.
@@ -46,7 +48,8 @@ Planr V1 is a single Rust binary with explicit module ownership. The crate stays
 - `src/route_audit.rs`: provider-neutral run-observation contract. Owns strict requested/resolved/effective route stages, model/effort/fork enforcement confidence, transition provenance, policy/binding versions, and per-dimension metering confidence. It rejects requested-only values in the effective stage rather than inferring host execution.
 - `src/app/agents.rs`: routing application boundary. Owns the `agents` and `item route` command handlers, the shared `*_value` JSON shapes reused by MCP, per-item route facts assembly, and registry-aware role content selection for installs.
 - `src/app/agents_init.rs`: registry bootstrap boundary. Owns `planr agents init` — the static cost-tiering scaffold and, per the agent-pool plan, the flag-spec builder and interactive wizard.
-- `src/integrations.rs`: agent-client integration descriptor boundary. Owns Codex, Claude Code, Cursor, MCP install metadata, MCP tool schemas, MCP resources, and MCP text response wrapping.
+- `src/integrations.rs`: shared agent-client descriptor boundary. Owns MCP install metadata, tool schemas, resources, and text response wrapping.
+- `src/integrations/grok.rs`: document-preserving Grok project MCP configuration and conflict policy.
 - `src/rolefiles.rs`: static host workflow roles and Cursor skill payloads. It does not select or pin models; externally generated routing artifacts stay outside Planr ownership.
 - `src/util.rs`: small CLI-boundary utilities. Owns ids, timestamps, path helpers, output formatting, and safe file writes.
 

package/docs/RELEASE.md

@@ -56,8 +56,12 @@ fixture tree; release verification does not read ignored files from the Planr
 checkout.
 
 Generate the candidate revision with
-`node scripts/verify-release-eval-receipt.mjs --print-candidate-revision`. At
-release time the candidate binary canonicalizes the explicitly supplied suite,
+`node scripts/verify-release-eval-receipt.mjs --print-candidate-revision`. The
+revision hashes every tracked or non-ignored release-source file, including its
+normalized executable mode, so changing any candidate source invalidates the
+receipt. The separate evaluated-subject revision binds the stored model run to
+the five workflow files the benchmark evaluates; changing either the exact
+release source or that evaluated subset invalidates the receipt. At release time the candidate binary canonicalizes the explicitly supplied suite,
 requires a Planr-validated effective route observation (host report, telemetry
 receipt, process exit, or local observation), recomputes the comparison from its
 stored baseline/candidate/policy identities, and gates that fresh result.

package/docs/contracts/GROK_INTEGRATION_V1.md

@@ -0,0 +1,139 @@
+# Grok Build Integration Contract v1
+
+Status: frozen for implementation
+
+Frozen: 2026-07-27
+
+Upstream source probe: `xai-org/grok-build` commit
+`b41c75a578f98bddbd326ab02cd53618451d97ee` (2026-07-26)
+
+This contract is the implementation boundary for first-class Grok Build support.
+It reconciles the public xAI documentation, the locally cloned upstream source,
+and Planr's local-first integration rules. Live authenticated verification is a
+separate maintainer-local release gate; it never runs in CI.
+
+## Frozen artifact and discovery policy
+
+`planr install grok` owns exactly the repository paths in the executable
+contract below. Workflow files are copied byte-for-byte from the canonical
+`plugins/planr` sources. There is no second Grok-specific workflow body.
+
+Planr does **not** emit `.grok/plugins/planr` or a Grok plugin manifest in v1.
+Current Grok source discovers project plugins from `.grok/plugins`, but project
+plugins default to disabled and project `.grok/config.toml` does not merge
+`[plugins].enabled`. A repository-local plugin would therefore require
+user-level enablement and would not satisfy one-command project setup. Native
+`.grok/skills/<name>/` and `.grok/agents/*.md` are documented, directly
+discovered project paths and do not depend on Claude compatibility scanners.
+
+Grok's current manifest lookup is still relevant for troubleshooting: a plugin
+root checks `plugin.json`, then `.grok-plugin/plugin.json`, then
+`.claude-plugin/plugin.json`, and finally convention-based component folders.
+That behavior is observed upstream but deliberately not used by Planr v1.
+
+```json
+{
+  "contract_version": 1,
+  "upstream_revision": "b41c75a578f98bddbd326ab02cd53618451d97ee",
+  "artifacts": [
+    {"target": ".grok/config.toml", "source": "generated:grok_project_config", "kind": "mcp"},
+    {"target": ".grok/agents/planr-reviewer.md", "source": "plugins/planr/agents/planr-reviewer.md", "kind": "agent"},
+    {"target": ".grok/agents/planr-worker.md", "source": "plugins/planr/agents/planr-worker.md", "kind": "agent"},
+    {"target": ".grok/skills/planr-goal/SKILL.md", "source": "plugins/planr/skills/planr-goal/SKILL.md", "kind": "skill"},
+    {"target": ".grok/skills/planr-loop/SKILL.md", "source": "plugins/planr/skills/planr-loop/SKILL.md", "kind": "skill"},
+    {"target": ".grok/skills/planr-loop/agents/planr-reviewer.md", "source": "plugins/planr/skills/planr-loop/agents/planr-reviewer.md", "kind": "skill_asset"},
+    {"target": ".grok/skills/planr-loop/agents/planr-worker.md", "source": "plugins/planr/skills/planr-loop/agents/planr-worker.md", "kind": "skill_asset"},
+    {"target": ".grok/skills/planr-loop/references/host-dispatch.md", "source": "plugins/planr/skills/planr-loop/references/host-dispatch.md", "kind": "skill_asset"},
+    {"target": ".grok/skills/planr-loop/references/recovery-and-verification.md", "source": "plugins/planr/skills/planr-loop/references/recovery-and-verification.md", "kind": "skill_asset"},
+    {"target": ".grok/skills/planr-plan/SKILL.md", "source": "plugins/planr/skills/planr-plan/SKILL.md", "kind": "skill"},
+    {"target": ".grok/skills/planr-review/SKILL.md", "source": "plugins/planr/skills/planr-review/SKILL.md", "kind": "skill"},
+    {"target": ".grok/skills/planr-status/SKILL.md", "source": "plugins/planr/skills/planr-status/SKILL.md", "kind": "skill"},
+    {"target": ".grok/skills/planr-summary/SKILL.md", "source": "plugins/planr/skills/planr-summary/SKILL.md", "kind": "skill"},
+    {"target": ".grok/skills/planr-task-graph/SKILL.md", "source": "plugins/planr/skills/planr-task-graph/SKILL.md", "kind": "skill"},
+    {"target": ".grok/skills/planr-verify-web/SKILL.md", "source": "plugins/planr/skills/planr-verify-web/SKILL.md", "kind": "skill"},
+    {"target": ".grok/skills/planr-work/SKILL.md", "source": "plugins/planr/skills/planr-work/SKILL.md", "kind": "skill"},
+    {"target": ".grok/skills/planr/SKILL.md", "source": "plugins/planr/skills/planr/SKILL.md", "kind": "skill"}
+  ],
+  "mcp": {
+    "table": "mcp_servers.planr",
+    "command": "planr",
+    "args": ["mcp"],
+    "enabled": true,
+    "startup_timeout_sec": 30,
+    "tool_timeout_sec": 6000,
+    "env": {"PLANR_MCP_CLIENT": "grok"},
+    "forbidden_fields": ["XAI_API_KEY", "api_key", "auth", "model", "headers", "url"]
+  },
+  "plugin": {
+    "emitted": false,
+    "project_root": ".grok/plugins",
+    "manifest_precedence": ["plugin.json", ".grok-plugin/plugin.json", ".claude-plugin/plugin.json", "convention"],
+    "project_default": "disabled",
+    "project_config_enabled_merged": false
+  },
+  "hooks": {"supported": false, "artifacts": []},
+  "client_all_includes_grok": false,
+  "headless": {"command": "grok --no-auto-update -p \"<prompt>\" --output-format json"}
+}
+```
+
+The generated `.grok/config.toml` table is therefore:
+
+```toml
+[mcp_servers.planr]
+command = "planr"
+args = ["mcp"]
+enabled = true
+startup_timeout_sec = 30
+tool_timeout_sec = 6000
+env = { PLANR_MCP_CLIENT = "grok" }
+```
+
+`PLANR_MCP_CLIENT=grok` is a narrow adapter marker applied by Grok's MCP
+launcher to the Planr child process. Planr may use the exact value as an
+advisory observed-client signal. It is not authentication, authorization, or a
+general worker identity. Ambient `GROK_*` variables are not accepted as the v1
+signal because the probed Grok MCP launcher does not inject a stable one.
+
+## Merge and overwrite policy
+
+- Missing `.grok/config.toml`: create it with only the Planr MCP table.
+- Existing valid config: perform a document-preserving TOML merge. Preserve
+  every foreign table, key, comment, and order; only `mcp_servers.planr` is
+  owned by Planr.
+- Existing different `mcp_servers.planr`: without `--force`, preserve it and
+  report a conflict; with `--force`, replace only that table.
+- Malformed config: fail with a path-and-parse diagnostic and write nothing,
+  including under `--force`.
+- Workflow target missing: write the canonical source. Existing identical
+  content is unchanged. Existing different content is preserved without
+  `--force` and replaced from the canonical source with `--force`.
+- `--no-mcp` omits `.grok/config.toml` reconciliation. `--no-hooks` is accepted
+  for CLI parity but changes no Grok paths because v1 installs no hooks.
+- Dry-run enumerates the same paths the corresponding write would reconcile.
+
+## Security and CI boundary
+
+Repository artifacts contain no xAI credential, token, auth-file path, model
+selection, endpoint, or absolute maintainer path. Planr never reads or copies
+`~/.grok`, `$GROK_HOME`, session data, `auth.json`, or
+`mcp_credentials.json` while installing.
+
+GitHub Actions and release workflows must not install or invoke Grok, reference
+`XAI_API_KEY`, gate on an xAI secret, or perform live inference. Deterministic
+tests parse and compare generated files without Grok installed. Maintainer-local
+release verification may use an existing login, but recorded evidence is
+limited to redacted discovery/origin, diagnostics, and the disposable Planr
+project identity.
+
+The supported inspection and headless syntax is `grok inspect --json` and
+`grok --no-auto-update -p "<prompt>" --output-format json`; `grok exec` is not part of this contract.
+
+## Sources
+
+- https://docs.x.ai/build/features/skills-plugins-marketplaces
+- https://docs.x.ai/build/settings
+- https://docs.x.ai/build/features/mcp-servers
+- https://docs.x.ai/build/cli/reference
+- https://docs.x.ai/build/cli/headless-scripting
+- https://github.com/xai-org/grok-build/tree/b41c75a578f98bddbd326ab02cd53618451d97ee

package/docs/documentation/COVERAGE.md

@@ -4,14 +4,14 @@ This is the canonical inventory that maps shipped public surfaces to repository
 
 ## Published route inventory
 
-The site currently owns 61 MDX routes. Next.js also emits the landing page and framework support routes during the production build.
+The site currently owns 62 MDX routes. Next.js also emits the landing page and framework support routes during the production build.
 
 | Section | Published routes |
 | --- | --- |
 | Documentation | `/docs` |
 | Getting started | `/docs/getting-started`, `/docs/getting-started/why-planr`, `/docs/getting-started/installation`, `/docs/getting-started/quickstart`, `/docs/getting-started/full-lifecycle`, `/docs/getting-started/choose-your-interface` |
 | For Agents | `/docs/agents`, `/docs/agents/quickstart`, `/docs/agents/prompt-recipes`, `/docs/agents/skills` |
-| Integrations | `/docs/integrations`, `/docs/integrations/codex`, `/docs/integrations/claude-code`, `/docs/integrations/cursor`, `/docs/integrations/generic-mcp`, `/docs/integrations/cli-only` |
+| Integrations | `/docs/integrations`, `/docs/integrations/codex`, `/docs/integrations/claude-code`, `/docs/integrations/cursor`, `/docs/integrations/grok-build`, `/docs/integrations/generic-mcp`, `/docs/integrations/cli-only` |
 | Plugins | `/docs/plugins`, `/docs/plugins/switchloom` |
 | Concepts | `/docs/concepts`, `/docs/concepts/local-first-model`, `/docs/concepts/plans-and-map`, `/docs/concepts/graph-and-readiness`, `/docs/concepts/picks-and-leases`, `/docs/concepts/evidence-and-context`, `/docs/concepts/reviews-and-approvals`, `/docs/concepts/recovery-packages-and-closure` |
 | Guides | `/docs/guides`, `/docs/guides/daily-worker-loop`, `/docs/guides/parallel-coordination`, `/docs/guides/handoff-and-resume`, `/docs/guides/review-and-fix-loops`, `/docs/guides/recover-interrupted-work`, `/docs/guides/packages-and-reuse`, `/docs/guides/recipes` |
@@ -64,6 +64,7 @@ The executable and schema sources decide exact inventory. Editorial pages explai
 | Codex | Codex manifest, generated role/install assets | `/docs/integrations/codex` |
 | Claude Code | Claude manifest, generated role/install assets | `/docs/integrations/claude-code` |
 | Cursor | Cursor manifest, role/skill/install assets | `/docs/integrations/cursor` |
+| Grok Build | Native role/skill assets and portable project MCP config | `/docs/integrations/grok-build` |
 | Generic stdio MCP | MCP server and fixture | `/docs/integrations/generic-mcp` |
 | CLI-only and non-first-class hosts | prompt output and CLI | `/docs/integrations/cli-only` |
 | Privacy, secret handling, localhost boundary | safety spec, `src/app/http.rs`, scrub behavior | `/docs/contributing/security-and-privacy` |
@@ -86,7 +87,7 @@ The executable and schema sources decide exact inventory. Editorial pages explai
 
 ## Audit completion checklist
 
-- [x] All 61 current MDX routes are explicitly inventoried.
+- [x] All 62 current MDX routes are explicitly inventoried.
 - [x] Every public product, CLI, MCP, HTTP, data, client, contributor, and operations surface has a current target and canonical source owner.
 - [x] Generated CLI and MCP inventories are separated from editorial guidance and mechanically checked.
 - [x] Retired aliases are isolated in `apps/docs/redirects.mjs` and resolve to a current route.

package/docs/documentation/INFORMATION_ARCHITECTURE.md

@@ -20,7 +20,7 @@ This file records the implemented route and navigation contract. Routes are publ
 
 ## Implemented route tree
 
-The 61 MDX files below are the current page tree and must agree with every `meta.json` file and `COVERAGE.md`.
+The 62 MDX files below are the current page tree and must agree with every `meta.json` file and `COVERAGE.md`.
 
 ```text
 /docs
@@ -38,6 +38,7 @@ The 61 MDX files below are the current page tree and must agree with every `meta
 │   ├── codex
 │   ├── claude-code
 │   ├── cursor
+│   ├── grok-build
 │   ├── generic-mcp
 │   └── cli-only
 ├── plugins

package/docs/fixtures/mcp-contract.json

@@ -92,16 +92,23 @@
       "\"mcpServers\"",
       "\"planr\"",
       "cursor://anysphere.cursor-deeplink/mcp/install?name=planr&config="
+    ],
+    "grok": [
+      "[mcp_servers.planr]",
+      "args = [\"mcp\"]",
+      "PLANR_MCP_CLIENT = \"grok\"",
+      ".grok/skills/planr/SKILL.md",
+      "hooks: unsupported/no-op"
     ]
   },
   "cli_reference_commands": [
-    "planr install codex|claude|cursor",
+    "planr install codex|claude|cursor|grok",
     "planr prompt cli|mcp|http",
     "planr prompt routing",
     "planr agents init",
     "planr agents init --profile|--skill|--route|--default-route|--interactive",
     "planr prime",
-    "planr install codex|claude|cursor [--dry-run] [--no-mcp] [--force] [--no-hooks]",
+    "planr install codex|claude|cursor|grok [--dry-run] [--no-mcp] [--force] [--no-hooks]",
     "planr mcp",
     "planr review annotate",
     "planr review ingest",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.7.3",
+  "version": "1.8.0",
   "description": "Local-first planning and execution coordination for coding agents.",
   "license": "MIT",
   "repository": {

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

@@ -1,7 +1,7 @@
 {
   "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.7.3",
+  "version": "1.8.0",
   "author": {
     "name": "instructa"
   },

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

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.7.3",
+  "version": "1.8.0",
   "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.",
   "author": {
     "name": "instructa",