planr - npm Package Compare versions

Comparing version 1.7.3 to 1.8.0

docs/contracts/GROK_INTEGRATION_V1.md

+# 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

docs/ARCHITECTURE.md

@@ -22,3 +22,5 @@ # Planr Architecture
 - `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.
@@ -50,3 +52,4 @@ - `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/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.
@@ -53,0 +56,0 @@ - `src/util.rs`: small CLI-boundary utilities. Owns ids, timestamps, path helpers, output formatting, and safe file writes.

docs/documentation/COVERAGE.md

@@ -7,3 +7,3 @@ # Documentation Coverage Matrix
 
-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.
 
@@ -15,3 +15,3 @@ | Section | Published routes |
 | 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` |
@@ -69,2 +69,3 @@ | 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` |
 | 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` |
@@ -92,3 +93,3 @@ | CLI-only and non-first-class hosts | prompt output and CLI | `/docs/integrations/cli-only` |
 
-- [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.
@@ -95,0 +96,0 @@ - [x] Generated CLI and MCP inventories are separated from editorial guidance and mechanically checked.

docs/documentation/INFORMATION_ARCHITECTURE.md

@@ -23,3 +23,3 @@ # Documentation Information Architecture
 
-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`.
 
@@ -42,2 +42,3 @@ ```text
 │   ├── cursor
+│   ├── grok-build
 │   ├── generic-mcp
@@ -44,0 +45,0 @@ │   └── cli-only

docs/fixtures/mcp-contract.json

@@ -95,6 +95,13 @@ {
       "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",
@@ -105,3 +112,3 @@ "planr prompt routing",
     "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",
@@ -108,0 +115,0 @@ "planr review annotate",

docs/RELEASE.md

@@ -59,4 +59,8 @@ # Release
 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
@@ -63,0 +67,0 @@ receipt, process exit, or local observation), recomputes the comparison from its

package.json

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

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

 {
   "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": {
@@ -6,0 +6,0 @@ "name": "instructa"

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

 {
   "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.",
@@ -5,0 +5,0 @@ "author": {

README.md

@@ -5,3 +5,3 @@ # Planr
 
-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.
 
@@ -57,3 +57,3 @@ [**View the Demo →**](https://x.com/kevinkern/status/2066957434564808884?s=20)
 
-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`:
 
@@ -111,2 +111,19 @@ ```bash
 
+<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>
@@ -189,2 +206,3 @@ <details>
 
+- **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).
@@ -209,3 +227,3 @@ - **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).
 - [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)
@@ -212,0 +230,0 @@ - [Task Graph Model](https://planr.so/docs/concepts/graph-and-readiness)

No alert changes

Improved metrics

Total package byte prevSize

31901653

2.22%

Number of package files

37

2.78%

Lines of code

221

3.27%

Number of lines in readme file

235

8.29%

No dependency changes