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
32 changes: 11 additions & 21 deletions apps/docs/content/docs/agents/quickstart.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,33 +3,23 @@ title: Agent Quickstart
description: Let Codex, Claude Code, Cursor, Pi, or explicitly opted-in Grok Build set up Planr safely and reach the first public Planr prompt.
---

This path delegates installation and project integration to your coding agent while keeping every mutation previewable and project-scoped. Choose exactly one client setup below, use its recipe or linked explicit guide, and wait for the receipt before asking for product work.
This path delegates installation and project integration to your coding agent while keeping every mutation previewable and project-scoped. Choose exactly one client setup guide below, use its complete recipe, and wait for the receipt before asking for product work.

<Callout type="info" title="Start with the right entry">
After setup, start ordinary Planr requests with `$planr`. Pi uses its native `/skill:planr` spelling instead. For bounded autonomous delivery, use the runtime-specific Planr Goal prompt first and then its generated Planr Loop handoff.
</Callout>

## Codex setup
## Choose a setup guide

<AgentRecipe client="codex" />
Each integration page owns its complete setup recipe, expected artifacts, reload or trust guidance, and first prompt.

## Claude Code setup

<AgentRecipe client="claude" />

## Cursor setup

<AgentRecipe client="cursor" />

## Pi setup

<AgentRecipe client="pi" />

Pi setup is an explicit repository opt-in rather than part of `--client all`.

## Grok Build setup

Grok setup is an explicit repository opt-in rather than part of `--client all`. Follow the [Grok Build integration](/docs/integrations/grok-build) to preview and install the native project assets, then return here for the shared receipt and first `$planr` request.
<Cards>
<Card title="Codex" href="/docs/integrations/codex" description="Use the Codex recipe for project MCP, skills, and hooks." />
<Card title="Claude Code" href="/docs/integrations/claude-code" description="Use the Claude Code recipe for plugin skills, roles, hooks, and project MCP." />
<Card title="Cursor" href="/docs/integrations/cursor" description="Use the Cursor recipe for project MCP, agents, skills, and hooks." />
<Card title="Grok Build" href="/docs/integrations/grok-build" description="Use the explicit Grok Build opt-in guide for native skills, agents, and MCP." />
<Card title="Pi" href="/docs/integrations/pi" description="Use the explicit Pi opt-in guide for native Agent Skills and optional roles." />
</Cards>

## Verify the setup receipt

Expand All @@ -39,7 +29,7 @@ The setup is complete only when `planr project show --json` reads the project an

## Start your first request

Reload the client if the receipt says to, open a fresh session, and paste the recipe's exact first prompt. For Codex, Claude Code, Cursor, and Grok Build that prompt is:
Reload the client if the receipt says to, open a fresh session, and paste the integration guide's exact first prompt. For Codex, Claude Code, Cursor, and Grok Build that prompt is:

<PromptBlock prompt="first" label="First Planr request" />

Expand Down
10 changes: 10 additions & 0 deletions apps/docs/content/docs/integrations/grok-build.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -55,4 +55,14 @@ Grok has no Planr hooks in v1. `--no-hooks` is accepted for CLI parity but chang

Deterministic tests and CI never install or invoke Grok and never receive xAI credentials. A maintainer may perform a local authenticated release check with an existing Grok login in a disposable repository. Record only redacted discovery/origin, diagnostics, and the disposable Planr project identity—never tokens, auth files, prompts, responses, transcripts, or private content.

## Copy/paste first prompt

After setup, paste this first prompt into Grok Build:

```text
Use $planr. Inspect this repository and tell me the verified next step.
```

This request is intentionally read-first. It lets Planr inspect the local graph, active reviews, and stored evidence before choosing whether the next move is planning, mapped work, review, recovery, or status.

Continue with the shared [Daily Worker Loop](/docs/guides/daily-worker-loop) or generate Grok-specific host guidance with `planr prompt routing --client grok`.
2 changes: 1 addition & 1 deletion apps/docs/lib/agent-recipes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -231,7 +231,7 @@ const recipes = {
id: 'pi',
displayName: 'Pi',
logoPath: '/agents/pi.svg',
logoAlt: 'Pi monogram',
logoAlt: 'Pi badge',
cardSummary: 'Native Agent Skills and optional pi-subagents roles',
invocationLabel: '/skill:planr',
pluginRequired: false,
Expand Down
12 changes: 6 additions & 6 deletions apps/docs/public/agents/README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Coding agent brand assets

These SVGs are used only to identify supported coding-agent integrations on the Planr landing page. They are stored unchanged with transparent backgrounds.
These SVGs are used only to identify supported coding-agent integrations on the Planr landing page. They are stored unchanged from their recorded sources.

- `codex.svg`: OpenAI monochrome Blossom from `https://developers.openai.com/assets/OpenAI-black-monoblossom.svg`
- `claude.svg`: Claude Spark (Clay) from Anthropic's official press kit at `https://www.anthropic.com/press-kit`
- `cursor.svg`: Cursor 2D Cube (Light) from Cursor's official brand kit at `https://cursor.com/brand`
- `pi.svg`: Planr-owned neutral pi monogram used to identify the Pi integration without redistributing a third-party brand asset
- `codex.svg`: OpenAI monochrome Blossom from `https://developers.openai.com/assets/OpenAI-black-monoblossom.svg`; retrieved on 2026-07-17.
- `claude.svg`: Claude Spark (Clay) from Anthropic's official press kit at `https://www.anthropic.com/press-kit`; retrieved on 2026-07-17.
- `cursor.svg`: Cursor 2D Cube (Light) from Cursor's official brand kit at `https://cursor.com/brand`; retrieved on 2026-07-17.
- `pi.svg`: Pi badge downloaded byte-for-byte from `https://pi.dev/favicon.svg`, linked as the Badge SVG in the official Pi press kit at `https://pi.dev/press-kit`; retrieved on 2026-07-28.

Retrieved on 2026-07-17. The three third-party marks remain the property of their respective owners and must be used according to those owners' current brand guidelines; the neutral Pi monogram is original Planr artwork.
These marks remain the property of their respective owners and must be used according to those owners' current brand guidelines.
24 changes: 20 additions & 4 deletions apps/docs/public/agents/pi.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
13 changes: 10 additions & 3 deletions apps/docs/scripts/verify-agent-journey.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -55,8 +55,15 @@ for (const route of ['/docs/agents/quickstart', '/docs/agents/prompt-recipes', '
}

const quickstart = await read('agents/quickstart.mdx');
for (const client of ['codex', 'claude', 'cursor', 'pi']) {
assert(quickstart.includes(`<AgentRecipe client="${client}" />`));
assert(!quickstart.includes('<AgentRecipe'), 'Agent Quickstart must link to integration recipes instead of duplicating them');
for (const route of [
'/docs/integrations/codex',
'/docs/integrations/claude-code',
'/docs/integrations/cursor',
'/docs/integrations/grok-build',
'/docs/integrations/pi',
]) {
assert(quickstart.includes(route), `Agent Quickstart omits integration link ${route}`);
}
assert(quickstart.includes('<PromptBlock prompt="first"'));
assert.match(quickstart, /Start with the right entry/);
Expand Down Expand Up @@ -96,4 +103,4 @@ for (const file of await collectMdx()) {
assert(!forbiddenUnscopedDriver.test(content), `${path.relative(contentRoot, file)} recommends an unscoped host driver`);
}

console.log(`agent_journey_contract=passed prompts=${Object.keys(agentPrompts).length} pages=4 clients=4`);
console.log(`agent_journey_contract=passed prompts=${Object.keys(agentPrompts).length} pages=4 integration_links=5`);
14 changes: 11 additions & 3 deletions apps/docs/scripts/verify-agent-markdown.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -127,11 +127,19 @@ async function main() {

const agentQuickstart = await (await fetch(`${baseUrl}/docs/agents/quickstart.md`)).text();
assert.match(agentQuickstart, /Use \$planr\. Inspect this repository/);
for (const route of [
'/docs/integrations/codex',
'/docs/integrations/claude-code',
'/docs/integrations/cursor',
'/docs/integrations/grok-build',
'/docs/integrations/pi',
]) {
assert.match(agentQuickstart, new RegExp(route.replaceAll('/', '\\/')));
}
for (const client of ['codex', 'claude', 'cursor', 'pi']) {
assert.match(agentQuickstart, new RegExp(`planr install ${client} --dry-run`));
assert.doesNotMatch(agentQuickstart, new RegExp(`planr install ${client} --dry-run`));
}
assert.match(agentQuickstart, /\/docs\/integrations\/grok-build/);
assert.match(agentQuickstart, /Use \/skill:planr\. Inspect this repository/);
assert.doesNotMatch(agentQuickstart, /Copyable setup prompt/);
assert(!agentQuickstart.includes('<PromptBlock'));

const promptRecipes = await (await fetch(`${baseUrl}/docs/agents/prompt-recipes.md`)).text();
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/scripts/verify-agent-recipes.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@ const normalizedSnapshot = JSON.stringify(agentRecipes);
const snapshotHash = createHash('sha256').update(normalizedSnapshot).digest('hex');
assert.equal(
snapshotHash,
'dbf208af3f6dd8ec00b4c917b6c4cb8f5636be90c817fae32eb3fe0aa75e8c5b',
'0dd353a783a65e3846ec5b7866c2e1e32986dd062e9eba543550730839db5d04',
`agent recipe snapshot changed (${snapshotHash}); inspect the full client contract before accepting it`,
);

Expand Down
6 changes: 6 additions & 0 deletions apps/docs/scripts/verify-grok-inventory.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,17 @@ const required = new Map([
['apps/docs/content/docs/faq.mdx', ['explicitly opted-in Grok Build']],
['apps/docs/content/docs/getting-started/full-lifecycle.mdx', ['explicitly opted-in Grok Build']],
['apps/docs/content/docs/agents/index.mdx', ['explicitly opted-in Grok Build']],
['apps/docs/content/docs/agents/quickstart.mdx', [
'/docs/integrations/grok-build',
'Use the explicit Grok Build opt-in guide',
]],
['apps/docs/content/docs/getting-started/why-planr.mdx', ['explicitly opted-in Grok Build']],
['apps/docs/content/docs/concepts/local-first-model.mdx', ['explicitly opted-in Grok Build']],
['apps/docs/content/docs/integrations/grok-build.mdx', [
'not included by `--client all`',
'Grok has no Planr hooks in v1',
'## Copy/paste first prompt',
'Use $planr. Inspect this repository and tell me the verified next step.',
]],
['apps/docs/scripts/verify-release-readiness.mjs', [
'explicitly opted-in Grok Build',
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/scripts/verify-maintenance.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -264,7 +264,7 @@ const sourceChecks = [
['apps/docs/alchemy.run.ts', ['planr.so', 'Cloudflare.Website.StaticSite', 'AdoptPolicy.adopt(true)', 'outdir: "out"']],
['apps/docs/app/page.tsx', ['Works with your coding agent', "agentRecipeList.map((recipe) =>"]],
['apps/docs/lib/agent-recipes.ts', ['/agents/codex.svg', '/agents/claude.svg', '/agents/cursor.svg', 'satisfies Record<AgentClientId, AgentRecipe>']],
['apps/docs/public/agents/README.md', ['developers.openai.com/assets/OpenAI-black-monoblossom.svg', 'anthropic.com/press-kit', 'cursor.com/brand']],
['apps/docs/public/agents/README.md', ['developers.openai.com/assets/OpenAI-black-monoblossom.svg', 'anthropic.com/press-kit', 'cursor.com/brand', 'pi.dev/press-kit']],
['apps/docs/public/agents/codex.svg', ['<svg', 'fill="black"']],
['apps/docs/public/agents/claude.svg', ['<svg', 'fill="#D97757"']],
['apps/docs/public/agents/cursor.svg', ['<svg', 'fill: #26251e']],
Expand Down
15 changes: 13 additions & 2 deletions apps/docs/scripts/verify-pi-inventory.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,8 @@ const required = new Map([
['apps/docs/content/docs/getting-started/full-lifecycle.mdx', ['explicitly opted-in Grok Build or Pi']],
['apps/docs/content/docs/agents/index.mdx', ['/skill:planr']],
['apps/docs/content/docs/agents/quickstart.mdx', [
'<AgentRecipe client="pi" />',
'Pi setup is an explicit repository opt-in',
'/docs/integrations/pi',
'Use the explicit Pi opt-in guide',
]],
['apps/docs/content/docs/getting-started/why-planr.mdx', ['explicitly opted-in Grok Build and Pi']],
['apps/docs/content/docs/concepts/local-first-model.mdx', ['explicitly opted-in Grok Build and Pi']],
Expand All @@ -50,6 +50,17 @@ const required = new Map([
"projectInstallerCommand: 'planr install pi'",
"integrationUrl: '/docs/integrations/pi'",
"invocationLabel: '/skill:planr'",
"logoAlt: 'Pi badge'",
]],
['apps/docs/public/agents/README.md', [
'https://pi.dev/press-kit',
'https://pi.dev/favicon.svg',
'Pi badge',
]],
['apps/docs/public/agents/pi.svg', [
'viewBox="0 0 800 800"',
'fill="#09090b"',
'M165.29 165.29',
]],
['apps/docs/components/agent-setup-panel.tsx', [
'href="/docs/integrations/pi">Pi</Link>',
Expand Down