# How to Use `/visual-plan` and `/visual-recap` Slash Commands with Coding Agents in Agent-Native

> Master Agent-Native's visual-plan and visual-recap slash commands. Generate structured MDX plans and recaps for safer, traceable, and collaborative coding workflows with MCP tools.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: how-to-guide
- Published: 2026-06-27

---

**Agent-Native provides `/visual-plan` and `/visual-recap` slash commands that enable coding agents to generate structured MDX-based visual plans and concise recaps through canonical MCP tools, ensuring safe, traceable, and collaborative software design workflows.**

Coding agents in BuilderIO/agent-native can architect complex software visually using specialized slash commands that transform textual requirements into rich, diagrammatic artifacts. These commands expose a controlled lifecycle for creating, reading, and modifying visual plans through the Model-Control-Protocol (MCP) tool surface. This guide explains the MDX artboard architecture, safety constraints, and implementation patterns for leveraging `/visual-plan` and `/visual-recap` in your agent workflows.

## Understanding the Visual Planning Commands

Agent-Native exposes two canonical entry points that govern how agents interact with software design documents:

**`/visual-plan`** generates a structured visual plan containing diagrams, wireframes, data-model tables, and annotated code snippets. When invoked, the agent triggers the MCP tool `create-visual-plan`, which writes a fresh MDX file (`plan.mdx`) to the plan folder and renders it to HTML and JSON for UI consumption.

**`/visual-recap`** produces a concise summary of an existing visual plan, highlighting top-level decisions, diff-tabs, and key wireframes. This command invokes `create-visual-recap`, which reads the current plan through `get-visual-plan` and writes a `recap.mdx` file suitable for chat UI display or PR attachment.

Both commands are **canonical** entry points—as implemented in BuilderIO/agent-native, the skill definition explicitly forbids agents from calling low-level plan-creation APIs directly. Agents must route through these slash commands to guarantee safety and auditability.

## The Visual Plan Lifecycle

The visual-plan system manages a complete CRUD lifecycle for MDX artboards, with each operation exposed as a typed MCP tool.

### Creation and Initialization

When an agent invokes `/visual-plan`, the system executes `create-visual-plan` to initialize the MDX source. This tool accepts a `planText` parameter containing Markdown and JSX components that define wireframes, data models, and architecture diagrams.

```typescript
// Creating a visual plan for a new API endpoint
await runMcpTool('create-visual-plan', {
  planText: `

# API Design – User Service

\`\`\`wireframe
GET /api/users/:id → returns user profile
\`\`\`

## Data Model

\`\`\`datamodel
type User {
  id: string
  name: string
  email: string
}
\`\`\`
`,
});

```

The initial creation writes to `plan.mdx` in the designated plan folder. According to the skill definition in [`.agents/skills/visual-plan/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/.agents/skills/visual-plan/SKILL.md), this file serves as the single source of truth for the visual artboard.

### Reading and Rendering

To consume a plan in the UI or agent context, use `get-visual-plan`. This tool returns the structured plan in multiple formats (HTML, JSON, and raw MDX) by invoking the Plan Renderer located in [`packages/frame/src/server.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/frame/src/server.ts).

```typescript
// Reading the current visual plan for UI display
const { html, json, mdx } = await runMcpTool('get-visual-plan', {
  planId: 'user-service-plan',
});

```

The HTML output renders React components server-side, while the JSON provides structured data for programmatic consumption.

### Updates and Incremental Patches

Visual plans support two mutation strategies. **Human-in-the-loop edits** use `update-visual-plan`, which merges human feedback comments back into the MDX source. **AST-level edits** use `patch-visual-plan-source`, which operates on stable semantic block IDs to keep diffs clean for version control.

```typescript
// Patching a specific block after architecture changes
await runMcpTool('patch-visual-plan-source', {
  planId: 'user-service-plan',
  patches: [
    {
      blockId: 'wireframe-1',
      newContent: 'GET /api/users/:id → returns user profile (with avatar URL)',
    },
  ],
});

```

Each mutation fires a `plan.updated` event recorded in the audit-log system (`skills/audit-log`), tying changes back to the originating agent or human actor.

## Architecture and Safety Model

The visual-plan system enforces strict architectural boundaries to prevent data corruption and ensure collaborative integrity.

### MDX Artboards and Semantic Block IDs

Visual plans are built on **MDX artboards**—one MDX file per plan that contains typed blocks such as `WireframeBlock`, `DataModelBlock`, and `CodeBlock`. Each block receives a stable semantic ID, making incremental patches reliable and source-control friendly.

As documented in [`templates/plan/.agents/skills/visual-plan/references/canvas.md`](https://github.com/BuilderIO/agent-native/blob/main/templates/plan/.agents/skills/visual-plan/references/canvas.md), these block IDs persist across edit sessions, allowing `patch-visual-plan-source` to target specific architectural elements without rewriting the entire document.

### MCP Tool Constraints and Safety

The skill definition in [`.agents/skills/visual-plan/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/.agents/skills/visual-plan/SKILL.md) explicitly blocks direct access to low-level APIs. Agents **must not** call `create-visual-plan`, `import-visual-plan-source`, or `update-visual-plan` outside the slash-command flow. This constraint guarantees:

- **Safety**: Only the approved tool set can mutate plans, preventing accidental overwrites
- **Traceability**: Every mutation logs as a `plan.updated` event with full provenance
- **Collaboration**: Human feedback captured via comments integrates seamlessly via `update-visual-plan`

When operating in *local-files privacy mode*, the system avoids hosted feedback APIs, relying solely on MDX file edits for complete offline operation.

## Working with Visual Recaps

The `/visual-recap` command provides a read-only summary operation that aids in handoffs and status updates.

When invoked, `create-visual-recap` internally calls `get-visual-plan` to read the current state, then generates a `recap.mdx` file highlighting key decisions and architectural changes. This recap can be attached to pull requests or displayed inline in chat interfaces.

```typescript
// Generating a recap of an existing plan for stakeholders
await runMcpTool('create-visual-recap', {
  planId: 'user-service-plan',
});

```

Unlike the planning commands, recaps do not mutate the source plan; they create derivative documents that reference the canonical MDX artboard.

## Key Source Files and References

Understanding the implementation requires familiarity with these authoritative files:

- **[`.agents/skills/visual-plan/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/.agents/skills/visual-plan/SKILL.md)**: Full definition of the `/visual-plan` command, MCP tools, and safety guidelines
- **[`.agents/skills/visual-recap/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/.agents/skills/visual-recap/SKILL.md)**: Definition of the `/visual-recap` command and its interaction with existing plans
- **[`templates/plan/.agents/skills/visual-plan/references/canvas.md`](https://github.com/BuilderIO/agent-native/blob/main/templates/plan/.agents/skills/visual-plan/references/canvas.md)**: Architecture of the MDX artboard structure, blocks, and export formats
- **[`templates/plan/.agents/skills/visual-plan/references/exemplar.md`](https://github.com/BuilderIO/agent-native/blob/main/templates/plan/.agents/skills/visual-plan/references/exemplar.md)**: Worked example of a backend visual plan implementation
- **[`packages/frame/src/server.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/frame/src/server.ts)**: Server-side rendering engine for MDX-to-HTML/JSON conversion
- **[`actions/read-visual-plan-source.ts`](https://github.com/BuilderIO/agent-native/blob/main/actions/read-visual-plan-source.ts)**: Backend action exposing plan data to frontend components

## Summary

- **Use `/visual-plan`** to generate structured MDX artboards containing diagrams, wireframes, and data models through the canonical `create-visual-plan` MCP tool
- **Use `/visual-recap`** to produce concise summaries of existing plans via `create-visual-recap`, which reads the current state through `get-visual-plan`
- **Respect the safety model** by never calling low-level APIs directly; always route through slash commands to ensure auditability and prevent overwrites
- **Leverage `patch-visual-plan-source`** for fine-grained edits using stable block IDs, keeping diffs clean for version control
- **Reference the skill definitions** in [`.agents/skills/visual-plan/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/.agents/skills/visual-plan/SKILL.md) and [`.agents/skills/visual-recap/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/.agents/skills/visual-recap/SKILL.md) for authoritative tool schemas and constraints

## Frequently Asked Questions

### What is the difference between `/visual-plan` and `/visual-recap`?

`/visual-plan` creates and manages the canonical MDX artboard containing the full software design, including wireframes and data models. `/visual-recap` generates a derivative summary document that highlights key decisions and changes without modifying the original plan. While the plan command manages the source of truth, the recap command produces consumable summaries for stakeholders.

### Can agents call `create-visual-plan` directly without using the slash command?

No. The skill definition explicitly forbids agents from calling low-level plan-creation APIs directly. Agents must use the canonical `/visual-plan` or `/visual-recap` entry points. This enforcement guarantees safety by preventing accidental mutations and ensures every change is logged through the `plan.updated` audit event system.

### How does `patch-visual-plan-source` maintain version control compatibility?

`patch-visual-plan-source` operates on **stable semantic block IDs** rather than line numbers or raw text offsets. Each block in the MDX artboard (such as `WireframeBlock` or `DataModelBlock`) retains a consistent ID across edit sessions. This allows the patching system to generate clean, targeted diffs that merge cleanly in version control systems without creating large, noisy change sets.

### What file format stores the visual plans in Agent-Native?

Visual plans persist as **MDX files** (Markdown with JSX), typically named `plan.mdx` or `recap.mdx`. These files reside in the plan folder and contain typed blocks that render as diagrams and wireframes. The system converts these MDX files to HTML and JSON on demand through the Plan Renderer in [`packages/frame/src/server.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/frame/src/server.ts), enabling both human-readable documentation and programmatic consumption.