diff --git a/docs.json b/docs.json index 4addf78..9fd2952 100644 --- a/docs.json +++ b/docs.json @@ -119,7 +119,7 @@ "group": "Getting Started", "pages": [ "plans/getting-started/intro", - "plans/getting-started/quick-start", + "plans/getting-started/your-first-plan", "plans/getting-started/best-practices" ] }, @@ -284,6 +284,8 @@ { "source": "/examples/case-studies", "destination": "/context/getting-started/intro" }, { "source": "/examples/multi-repo", "destination": "/context/getting-started/intro" }, { "source": "/examples/vibe-code-sleep-training", "destination": "/context/getting-started/intro" }, - { "source": "/plans/beta", "destination": "/plans/getting-started/intro" } + { "source": "/plans/beta", "destination": "/plans/getting-started/intro" }, + { "source": "/plans/getting-started/quick-start", "destination": "/plans/getting-started/your-first-plan" }, + { "source": "/plans/getting-started/get-started", "destination": "/plans/getting-started/your-first-plan" } ] } diff --git a/images/your-first/ref1-empty-editor.png b/images/your-first/ref1-empty-editor.png new file mode 100644 index 0000000..7819474 Binary files /dev/null and b/images/your-first/ref1-empty-editor.png differ diff --git a/images/your-first/ref2-repos-list.png b/images/your-first/ref2-repos-list.png new file mode 100644 index 0000000..d5cab5a Binary files /dev/null and b/images/your-first/ref2-repos-list.png differ diff --git a/images/your-first/ref3-thinking.png b/images/your-first/ref3-thinking.png new file mode 100644 index 0000000..07a7f14 Binary files /dev/null and b/images/your-first/ref3-thinking.png differ diff --git a/images/your-first/ref4-agent-writing-plan.png b/images/your-first/ref4-agent-writing-plan.png new file mode 100644 index 0000000..2ed1d3c Binary files /dev/null and b/images/your-first/ref4-agent-writing-plan.png differ diff --git a/images/your-first/ref5-comment.png b/images/your-first/ref5-comment.png new file mode 100644 index 0000000..de2eaa4 Binary files /dev/null and b/images/your-first/ref5-comment.png differ diff --git a/images/your-first/ref6-many-cursor-threads.png b/images/your-first/ref6-many-cursor-threads.png new file mode 100644 index 0000000..32faedd Binary files /dev/null and b/images/your-first/ref6-many-cursor-threads.png differ diff --git a/images/your-first/ref7-many-devin-threads.png b/images/your-first/ref7-many-devin-threads.png new file mode 100644 index 0000000..1222a22 Binary files /dev/null and b/images/your-first/ref7-many-devin-threads.png differ diff --git a/index.mdx b/index.mdx index 132b9dd..a22cf16 100644 --- a/index.mdx +++ b/index.mdx @@ -12,5 +12,5 @@ Search public and private documentation from any MCP-compatible coding agent. ## Ref Plans Write, iterate, and collaborate on plans for coding agents. Orchestrate agents to implement them. -Overview of what Ref Plans is and how it works. -Create your first plan and send it to an agent. +Overview of what Ref Plans is and how it works. +Create your first plan and send it to an agent. diff --git a/plans/getting-started/intro.mdx b/plans/getting-started/intro.mdx index 04514a0..90df97b 100644 --- a/plans/getting-started/intro.mdx +++ b/plans/getting-started/intro.mdx @@ -1,5 +1,5 @@ --- -title: "Intro to Ref Plans" +title: "Overview" description: "Ref Plans in one page." --- @@ -30,8 +30,8 @@ Instead of ephemeral chat sessions that disappear when you close a tab, Plans gi - **Web-based and mobile-friendly** — Start a plan on your laptop, review it on your phone, launch agents from anywhere. - -Create your first plan in minutes. + +Create your first plan and send it to an agent. How to write plans that get great results. diff --git a/plans/getting-started/quick-start.mdx b/plans/getting-started/quick-start.mdx deleted file mode 100644 index eb1932e..0000000 --- a/plans/getting-started/quick-start.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: "Quick Start" -description: "Steps to get started with Ref Plans." ---- - -## 1. Sign up - -Sign up at [ref.tools/signup](https://ref.tools/signup) to create your account. - -## 2. Connect your repos (optional) - -Connect your GitHub and add repos at [ref.tools/resources](https://ref.tools/resources?tab=github). This lets Ref's agent research your codebase when building out plans. - -## 3. Create your first plan - -Visit [plan.ref.tools](https://plan.ref.tools) and click **New Plan**. Give it a title and start writing. - -You can start with: -- A rough outline of what you want to build -- A link to a Linear ticket or GitHub issue -- Just a sentence describing the feature or bug - -## 4. Research and structure with AI - -Use the chat panel to ask Ref's agent to research your codebase and break your outline into structured tasks. For example: - -``` -Research the codebase and break this into tasks with implementation steps and verification criteria. -``` - -The agent will read relevant files, understand existing patterns, and produce a structured plan. - -## 5. Send tasks to a coding agent - -When a task looks good, click **Launch Agent** to send it to your coding agent of choice — Claude Code, Cursor Background Agents, Devin, or others. The agent will report progress back to Ref as it works. - -## Next steps - - -How to write plans that get great results. - diff --git a/plans/getting-started/your-first-plan.mdx b/plans/getting-started/your-first-plan.mdx new file mode 100644 index 0000000..d089993 --- /dev/null +++ b/plans/getting-started/your-first-plan.mdx @@ -0,0 +1,158 @@ +--- +title: "Your First Plan" +description: "Get Ref Plans running at full power in about ten minutes." +--- + +Get Ref Plans running at full power in about ten minutes. + + + + Create an account at [plan.ref.tools](https://plan.ref.tools). You'll land on a blank doc — your space to think through what you want to build. + + + The plan editor immediately after creating a new plan — empty document titled 'Untitled Plan', the chat panel on the right with quick actions, and a banner prompting you to connect GitHub. + + + + + Link a GitHub repo so Ref can read your code and write plans that match your architecture. + + 1. Go to [ref.tools/resources](https://ref.tools/resources?tab=github) + 2. Click **Connect GitHub** and authorize Ref + 3. Select the repos you want to index and click **Add to Ref** + + Once indexed, Ref can read files, find existing patterns, and reference them when structuring your tasks. + + + The Your Resources page with the Repos tab selected, showing a list of GitHub repositories with branch selectors and 'Add to Ref' buttons. + + + + + Choose which coding agent Ref should use to implement your tasks. + + 1. Open **Settings** (gear icon) + 2. Click the **Agents** tab + 3. Select an agent and enter its API key (or follow the launcher flow for agents that don't use one) + + + + Paste your **Cursor** API key. Get one from [cursor.com/dashboard](https://cursor.com/dashboard?tab=cloud-agents) under the **Cloud Agents** tab. + + + The Agents settings tab configured for Cursor — API key entered, repo and branch selectors visible. + + + + Paste your **Devin** API key. Get one from [app.devin.ai/settings/api-keys](https://app.devin.ai/settings/api-keys). + + + Paste your **Warp API key** (starts with `wk-...`). In the Warp desktop app, open **Settings > Platform** and create an API key. + + - **Environment ID** (optional) — most users with a single environment can leave this blank. + + + These work as **launcher** agents — Ref generates a prompt with embedded webhook commands. You paste it into the agent yourself, and it reports progress back via the webhooks. No API key needed. + + Supported launchers: + - Claude Code Web + - Codex (Cloud and Desktop) + - Conductor + - Factory + - Windsurf + - Zed + - GitHub Copilot + - Cursor Desktop + + + + + **Giving agents access to your plans via MCP** — Cloud agents (Cursor, Devin) are launched and tracked automatically via their API keys — they don't need MCP access for basic task execution. However, if you want an agent to read, write, or collaborate on plan documents, or message other agents, you can install the [Ref Plans MCP server](/plans/install/index) in that agent's environment. This is optional for single-agent workflows but required for multi-agent orchestration. + + + + + No need for perfect formatting — just get your ideas down: + + - A rough description of the feature or bug + - Links to a Linear ticket or GitHub issue + - A schema, API shape, or data model + - Bullet points, stream of consciousness, whatever gets it across + + This is your thinking space. Get everything important out of your head and onto the page. + + If you want to pull in context from Linear, Asana, or GitHub Issues, you'll need to connect those first — see the [Integrations guide](/plans/integrations/overview) for setup. + + + + Open the chat panel and ask Ref to turn your notes into tasks. For example: + + ``` + Research the codebase and break this into tasks with + implementation steps and verification criteria. + ``` + + Ref will: + - Read relevant files from your indexed repos + - Identify existing patterns (auth, DB models, API routes) + - Structure your notes into tasks with file paths and verification steps + + Go back and forth — ask it to split a task, add detail, or reconsider an approach. Use comments to leave notes for yourself or teammates. + + + Split view showing rough notes in the plan editor on the left, and the chat panel on the right where Ref is researching the codebase and writing tasks. + + +
+ + + A comment thread on a task — the author leaving feedback, and the chat panel showing Ref addressing the comment and updating the plan. + + + + + When your tasks are ready, tell Ref to start implementing. You can pick specific tasks or hand off the whole plan: + + ``` + Implement tasks 1-3. + ``` + + ``` + Implement the plan. + ``` + + Ref spins up a separate coding agent for each task, pre-loaded with the task details, file references, and repo context. Multiple tasks run in parallel, each on its own branch. + + You can keep working while implementation runs. Progress flows back automatically — watch status updates come in, and continue refining upcoming tasks. + + When a task finishes, a PR appears directly in your plan. You can provide higher-level feedback as work progresses, or enable **auto-merge** to let Ref review and merge PRs on your behalf. + + + + + Manage multiple agents directly from Ref. + + + Manage multiple agents directly from Ref. + + + + + + +## What's next? + + + + Learn how to write plans that get great results. + + + Set up fully automated multi-agent orchestration. + + + Connect Linear or GitHub issues for richer context. + + + Using Claude Code, Codex, or another local agent? Install the MCP server to connect them to Ref. + + diff --git a/style.css b/style.css index 7b9d299..01c6886 100644 --- a/style.css +++ b/style.css @@ -15,9 +15,9 @@ div { letter-spacing: -0.02em; } -.border-b { - border-bottom: none; -} +/* Do not add a global `.border-b { border-bottom: none }` here. Mintlify's + (and other UI) use Tailwind's border-b for the active tab underline; stripping + it site-wide makes tabs look like plain text with no selection state. */ /* .relative.hidden.items-center.flex-1.justify-center { display: none;