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

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.

// 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, 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.

// 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.

// 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, 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 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.

// 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: Full definition of the /visual-plan command, MCP tools, and safety guidelines
• .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: Architecture of the MDX artboard structure, blocks, and export formats
• templates/plan/.agents/skills/visual-plan/references/exemplar.md: Worked example of a backend visual plan implementation
• packages/frame/src/server.ts: Server-side rendering engine for MDX-to-HTML/JSON conversion
• 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 and .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, enabling both human-readable documentation and programmatic consumption.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}