Visual Plan Skill

Turn ordinary coding plans into interactive review artifacts with real diagrams, validated blocks, and a hard approval gate before code changes.

visual-plan is a Codex skill for non-trivial implementation work. It pushes planning into a structured artifact with diagrams, file maps, open questions, annotated code, and optional UI/prototype review instead of leaving the plan buried in chat.

Recent update: the public skill now includes stricter guidance for valid structured blocks, safer Mermaid fallback handling, and explicit checks that rendered plan blocks are actually fixed instead of just hidden behind markdown fallbacks.

What it does

• Converts normal implementation planning into a reviewable Agent-Native Plan
• Chooses the right surface for the job: document-only, canvas, prototype, or mixed
• Forces concrete planning grounded in real files, symbols, data shapes, and validation
• Gives the agent a quality bar for diagrams, wireframes, annotations, and open questions
• Keeps planning read-only until the user approves the direction

Why this is useful

Most agent plans are either too short to be useful or too long to review quickly. This skill makes the output scannable without lowering the technical bar.

It is especially useful for:

• multi-file changes
• architecture or API work
• ambiguous product work
• UI changes that need alignment before implementation
• tasks where a reviewer should comment on the plan itself

Repo contents

• SKILL.md: the installable skill
• agent-native-skill.json: portable Agent-Native metadata
• references/document-quality.md: document quality bar
• references/canvas.md: canvas and artboard rules
• references/wireframe.md: HTML wireframe rules
• references/exemplar.md: good vs bad plan examples

Install

1. Copy this folder into your Codex skills directory as visual-plan.
2. Make sure the Agent-Native Plan connector is available in your client.
3. Use visual-plan when a task needs a real approval artifact before code changes.

Example:

Use visual-plan for this dashboard refactor before you change any files.

Connector note

This skill assumes the Agent-Native Plan tools are available. If the connector is missing in Codex Desktop, the skill currently points users to:

npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex

Then start a new Codex session so the tools reload.

Audience

This repo is most useful if you already work with Codex or Claude Code and want a repeatable planning layer before implementation.

License

MIT