Best Practices

​

TLDR

1. Start with a clear outline — Be specific about what to build, include constraints, and reference existing patterns.
2. Let the agent research — Don’t try to write perfect tasks yourself. Give the agent your intent and let it research the codebase.
3. Review before launching — Read through the agent’s proposed tasks and implementation steps. Catch issues early.

​

Plan structure

A good plan follows this structure:

1. Summary — One or two paragraphs describing what you’re building and why.
2. Relevant Files — Key files the agent should read to understand the existing codebase patterns.
3. Relevant Docs — Links to external documentation, API references, or design specs.
4. Tasks — Each task has:
   • A clear title
   • Implementation steps (specific enough that an agent can follow them)
   • Verification criteria (how to confirm the task is done correctly)

​

Tips for writing good outlines

Be specific about what to build. “Add dark mode” is vague. “Add a dark mode toggle to the settings page that persists the user’s preference in localStorage and applies a dark theme using our existing Tailwind dark: classes” gives the agent something to work with. Include constraints. If there are libraries you want to use (or avoid), performance requirements, or compatibility needs, say so up front. Reference existing patterns. If your codebase has conventions, point to an example. “Follow the same pattern as UserSettings.tsx for the new component” saves a lot of back-and-forth.

​

Iterative refinement

Plans are collaborative documents. Use comments in the chat panel to:

• Ask the agent to dig deeper into a specific area
• Request changes to the task breakdown
• Add context you forgot in the initial outline
• Get the agent to update tasks based on what you learned during implementation

​

When to use multiple plans vs. multiple tasks

Multiple tasks in one plan when the work is part of a single coherent feature or change. The tasks share context and should be understood together. Multiple plans when the work is independent. Different features, different areas of the codebase, or different timelines. Each plan is self-contained.

​

Using Manual tool topics

Ref’s agent has built-in knowledge about plan structure and workflows. You can use these topics in the chat panel via the Manual tool:

• structure-a-plan — Ask the agent to organize your rough notes into a well-structured plan
• update-a-plan — Ask the agent to revise the plan based on new information or progress
• read-code-or-docs — Guidance on researching code and documentation using Ref tools before writing or updating plans

​

Role-based topics

These topics are primarily used by the system during multi-agent orchestration, but you can reference them directly too:

• role-orchestrator — Workflow guidance for orchestrator agents managing teams of implementation and review agents. Covers how to launch agents, coordinate via messaging, and update the plan after merges.
• role-implementer — Workflow guidance for coding agents creating PRs. Covers rules for implementation agents: focus on code, message parent with PR URL when done, don’t update the plan.
• role-reviewer — Workflow guidance for agents reviewing PRs. Covers how to use GitHub tools (ReadPR, ReviewPR, MergePR) to review diffs, approve, and report results to the orchestrator.

​

Install the MCP server in all your agents

For the best results, install the Ref Plans MCP server in every coding agent you use — Cursor, Claude Code, Devin, and any others. This ensures:

• Full plan context — Agents can read the plan directly instead of relying on a pasted prompt snippet
• Progress updates — Agents can update the plan with progress and mark tasks complete as they work
• Built-in guidance — Agents can use the Manual tool for workflow guidance
• Orchestration support — Agents can communicate with the orchestrator via SendMessage during multi-agent workflows

Without the MCP server, agents only see the initial prompt you send them. With it, they have access to the full plan, can report back, and can coordinate with other agents. See the installation guide for setup instructions for each agent.