Release Planr 1.8.0 with first-class Grok Build integration

.cursor-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",

.planr/plans/product/planr/ADRS.md

@@ -72,7 +72,7 @@ Status: Accepted
 
 ### Context
 
-Codex, Claude Code, and Cursor all have MCP integration paths, while their native skill/plugin systems differ.
+Codex, Claude Code, Cursor, and explicitly opted-in Grok Build all have MCP integration paths, while their native skill/plugin systems differ.
 
 ### Decision
 

.planr/plans/product/planr/AI_SPEC.md

@@ -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, and generic MCP clients through shared MCP contracts.
+- 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-003: Client-specific runners may exist, but core graph operations must remain provider-neutral.
 
 ## Prompt Architecture

.planr/plans/product/planr/API_AND_DATA_MODEL.md

@@ -183,6 +183,7 @@ item_id TEXT NOT NULL
 worker_id TEXT NOT NULL
 client TEXT NOT NULL
 profile TEXT
+observed_client TEXT
 command TEXT
 cwd TEXT
 worktree_path TEXT
@@ -198,6 +199,7 @@ Clients:
 - codex
 - claude-code
 - cursor
+- grok
 - generic-mcp
 - human
 - ci
@@ -317,12 +319,12 @@ isProject: false
 ### Project
 
 ```bash
-planr project init [--client codex|claude|cursor|all] [--force]
+planr project init [--client codex|claude|cursor|grok|all] [--force]
 planr project show [--json]
 planr project list [--json]
-planr doctor [--client codex|claude|cursor|all]
-planr install codex|claude|cursor [--dry-run]
-planr prompt cli|mcp|http [--client codex|claude|cursor|all]
+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 mcp
 planr serve --port 7526
 planr import <file> [--preview] [--confirm]
@@ -447,6 +449,27 @@ planr map pressure
 - `planr-map`
 - `planr-summary`
 
+## Grok Build Project Contract
+
+`planr install grok` reconciles one portable project MCP table and native
+repository workflow assets. The MCP process inherits the repository working
+directory, so the config intentionally contains no absolute `--db` path:
+
+```toml
+[mcp_servers.planr]
+command = "planr"
+args = ["mcp"]
+enabled = true
+startup_timeout_sec = 30
+tool_timeout_sec = 6000
+env = { PLANR_MCP_CLIENT = "grok" }
+```
+
+The exact `PLANR_MCP_CLIENT=grok` child-process marker may populate
+`runs.observed_client`; ambient `GROK_*` variables may not. The marker is
+advisory evidence, never authentication or worker identity. Grok v1 writes no
+hooks and remains outside the legacy `--client all` expansion.
+
 ## HTTP API
 
 HTTP is optional in V1 and localhost-only by default.

.planr/plans/product/planr/CLIENT_IMPLEMENTATION_SPEC.md

@@ -5,7 +5,7 @@
 - CLI: primary V1 interface.
 - MCP client: primary agent integration.
 - Optional TUI/dashboard: local visual inspection.
-- Install helpers: client-specific setup for Codex, Claude Code, Cursor.
+- Install helpers: client-specific setup for Codex, Claude Code, Cursor, and explicitly opted-in Grok Build.
 
 ## CLI Requirements
 
@@ -114,6 +114,6 @@ Errors must include:
 - CLI golden output tests.
 - JSON schema output tests.
 - MCP tool discovery tests.
-- Config-generation fixture tests for Codex, Claude Code, and Cursor.
+- Config-generation fixture tests for Codex, Claude Code, Cursor, and Grok Build.
 - Prompt output tests for CLI, MCP, HTTP, and per-client wording.
 - Browser workspace smoke tests against localhost.

.planr/plans/product/planr/PRODUCT_SPEC.md

@@ -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, Gemini CLI, or custom MCP agents in the same repo.
+- Power users coordinating Codex, Claude Code, Cursor, Grok Build, 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.
 
@@ -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, and MCP clients are peers.
+- Cross-agent by default: Codex, Claude Code, Cursor, Grok Build, 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.
 
@@ -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, and compatible clients.
+- MCP server exposing tools, resources, and prompts for Claude Code, Cursor, Codex, Grok Build, and compatible clients.
 - Optional HTTP/SSE local server for dashboard and automation clients.
-- Codex, Claude Code, and Cursor install/config helpers.
+- Codex, Claude Code, Cursor, and explicitly opted-in Grok Build 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.
@@ -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, and Cursor.
+- Initialize Planr in a repo and configure Codex, Claude Code, Cursor, or Grok Build.
 - Create a plan from a broad app idea or PRD request.
 - Convert product plan slices into build plans.
 - Seed map items from a plan.
@@ -114,7 +114,8 @@ 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|all` must print or apply integration instructions for the selected client.
+- 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-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-012: Initialization must detect existing `.planr` data and offer import commands.
 
 ### Product Plans
@@ -141,7 +142,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, and Cursor.
+- REQ-PROD-050: Planr must provide agent-specific prompts or MCP prompts for Codex, Claude Code, Cursor, and Grok Build.
 - 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.
@@ -165,6 +166,7 @@ idea -> product plan -> build plan -> map -> pick -> log -> review/evidence -> r
 - Codex CLI and Codex MCP configuration.
 - 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.
 - Generic MCP clients via stdio and optional streamable HTTP.
 - Git worktrees and Git diff logs.
 - Optional CI invocation for verification tasks.

.planr/plans/product/planr/README.md

@@ -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, 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 other MCP-capable agents.
 
 ## Package Contents
 
@@ -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, and Cursor should all work through standard CLI and MCP integration paths.
+- Codex, Claude Code, Cursor, and explicitly opted-in Grok Build should all work through standard CLI and MCP integration paths.
 - 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.
 

.planr/plans/product/planr/REFERENCES.md

@@ -20,7 +20,7 @@
 
 ## Source Freshness Notes
 
-- MCP and coding-agent client behavior changes frequently. Re-check Codex, Claude Code, Cursor, and MCP docs before implementing install helpers or promising exact config commands.
+- MCP and coding-agent client behavior changes frequently. Re-check Codex, Claude Code, Cursor, Grok Build, and MCP docs before implementing install helpers or promising exact config commands.
 - The spec intentionally prefers stable integration concepts over vendor-specific hidden config internals.
 
 ## Product Independence Notes

.planr/plans/product/planr/RELEASE_READINESS.md

@@ -87,7 +87,7 @@ Before public release:
 ## Launch Criteria
 
 - All regression reviews pass.
-- Docs cover first-run setup for Codex, Claude Code, and Cursor.
+- Docs cover first-run setup for Codex, Claude Code, Cursor, and explicitly opted-in Grok Build.
 - `planr doctor --client all` produces actionable output.
 - `planr prompt cli|mcp|http` prints actionable instructions without editing config.
 - Fresh consumer E2E passes in `~/projects/planr-test`.

.planr/plans/product/planr/TASKS.md

@@ -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, and generic MCP.
+- Add or document client setup for Codex, Claude Code, Cursor, explicitly opted-in Grok Build, and generic MCP.
 - Add prompt/config output for CLI, MCP, and HTTP workflows.
 - Document checksum verification.
 
@@ -638,7 +638,7 @@ Goal:
 Expose Planr tools, resources, and prompts over MCP.
 
 Context:
-Primary cross-agent integration for Codex, Claude Code, and Cursor.
+Primary cross-agent integration for Codex, Claude Code, Cursor, and explicitly opted-in Grok Build.
 
 Requirements:
 - `planr mcp` starts stdio server.
@@ -849,7 +849,7 @@ Files or areas likely involved:
 - `src/observability/`.
 
 Acceptance criteria:
-- Doctor reports database, `.planr`, Git, MCP, Codex, Claude Code, Cursor.
+- Doctor reports database, `.planr`, Git, MCP, Codex, Claude Code, Cursor, and explicitly selected Grok Build.
 - Debug bundle is reviewable before sharing.
 
 Tests:
@@ -894,7 +894,7 @@ Dependencies:
 - TASK-SEC-001.
 
 Do not do:
-- Do not rely on live Codex/Claude/Cursor for core CI tests.
+- Do not rely on live Codex/Claude/Cursor/Grok Build for core CI tests.
 
 ### TASK-REL-001: Package And Release V1
 

.planr/plans/product/planr/TECH_ARCHITECTURE.md

@@ -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, and generic MCP clients first-class integration targets.
+- REQ-ARCH-004: Make Codex, Claude Code, Cursor, Grok Build, and generic MCP clients first-class integration targets.
 - REQ-ARCH-005: Avoid provider-specific logic in the core graph engine.
 
 ## System Context Diagram
@@ -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, and generic clients.
+- `agents`: integration helpers for Codex, Claude Code, Cursor, Grok Build, 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.
@@ -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, and Cursor.
+- Client-specific install snippets for Codex, Claude Code, Cursor, and Grok Build.
 - Optional runner wrappers for local Codex/Claude/Cursor CLIs when explicitly configured.
 
 ## Auth And Identity
@@ -91,12 +91,13 @@ Planr does not call model providers by default. It guides external agents throug
 - 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.
+- 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.
 - Generic MCP: stdio first; streamable HTTP optional.
 - Git: worktree isolation and scoped diff log.
 
 ## Security Architecture
 
-- No shell hooks by default.
+- Host hooks are repository-local and optional where supported; Grok Build has 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.

CHANGELOG.md

@@ -6,6 +6,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [1.8.0] - 2026-07-27
+
+### Added
+
+- Add first-class Grok Build support through the explicit `planr install grok` and `--client grok` flows, with document-preserving project MCP configuration, native Planr worker/reviewer agents, all ten canonical workflow skills, dry-run previews, and Grok-specific doctor diagnostics.
+- Add Grok-aware project initialization, host prompts, observed-client evidence, documentation, frozen integration contracts, deterministic inventory checks, and local disposable-repository verification guidance.
+
+### Compatibility
+
+- Keep Grok outside the legacy `--client all` selection so existing Codex, Claude Code, and Cursor setup remains unchanged. Grok v1 installs no project plugin or hooks; `--no-hooks` is accepted as an explicit no-op for CLI parity.
+
+### Security
+
+- Keep Planr provider-neutral: generated Grok configuration contains no xAI credential, auth-file path, model, endpoint, or absolute database path. CI uses deterministic synthetic coverage only; authenticated Grok verification remains a redacted maintainer-local release gate.
+
 ## [1.7.3] - 2026-07-26
 
 ### Fixed
@@ -518,7 +533,8 @@ Initial Planr product release.
 - Tag-driven release pipeline with multi-target builds (darwin/linux, arm64/x86_64) and Homebrew tap automation.
 - Skill workflow documentation for Codex, Claude Code, Cursor, and MCP-only clients.
 
-[Unreleased]: https://github.com/instructa/planr/compare/v1.7.3...HEAD
+[Unreleased]: https://github.com/instructa/planr/compare/v1.8.0...HEAD
+[1.8.0]: https://github.com/instructa/planr/compare/v1.7.3...v1.8.0
 [1.7.3]: https://github.com/instructa/planr/compare/v1.7.2...v1.7.3
 [1.7.2]: https://github.com/instructa/planr/compare/v1.7.1...v1.7.2
 [1.7.1]: https://github.com/instructa/planr/compare/v1.7.0...v1.7.1

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "planr"
-version = "1.7.3"
+version = "1.8.0"
 edition = "2024"
 license = "MIT"
 description = "Local-first planning and execution coordination for coding agents"
@@ -27,6 +27,7 @@ sha2 = "0.10"
 slug = "0.1"
 time = { version = "0.3", features = ["formatting"] }
 toml = "0.8"
+toml_edit = "0.22"
 uuid = { version = "1", features = ["v4"] }
 
 [lints.rust]