Creates a concise engineering implementation plan saved to specs/, then generates one information-rich, thematically-consistent diagram image per section (hero + per-H2) to aid planning of the engineering work. Use when the user says "vspec", asks for a visual/illustrated implementation plan, a spec with diagrams, or wants an engineering plan whose sections are each backed by an architecture/flow/data-model image.
Creates a concise engineering implementation plan saved to specs/, then generates one information-rich, thematically-consistent diagram image per section (hero + per-H2) to aid planning of the engineering work. Use when the user says "vspec", asks for a visual/illustrated implementation plan, a spec with diagrams, or wants an engineering plan whose sections are each backed by an architecture/flow/data-model image.
argument-hint
[user prompt]
vspec
Purpose
Produce a written engineering implementation plan, then add a
visual layer: a hero image plus one diagram per section. Each image is an
information-rich, compressed, visual artifact — architecture, nodes, communication
flow, data models, lifecycles — not a rendered wall of text. The images are
thematically consistent across the whole spec and are linked back into the markdown so
the plan reads like an illustrated blueprint.
Two phases, in order:
Plan phase — build and save the raw markdown plan.
Image phase — after the plan exists, generate and embed one image per section.
The image phase always runs after the raw plan is written.
IMPORTANT: If no USER_PROMPT is provided, stop and ask the user to provide it.
Carefully analyze the user's requirements provided in the USER_PROMPT variable.
Determine the task type (chore|feature|refactor|fix|enhancement) and complexity (simple|medium|complex).
Think deeply (ultrathink) about the best approach to implement the requested functionality or solve the problem.
Explore the codebase to understand existing patterns and architecture.
Follow the Plan Format below to create a comprehensive implementation plan.
Include all required sections and conditional sections based on task type and complexity.
Generate a descriptive, kebab-case filename based on the main topic of the plan.
Save the complete implementation plan to PLAN_OUTPUT_DIRECTORY/<descriptive-name>.md.
Ensure the plan is detailed enough that another developer could follow it to implement the solution.
Include code examples or pseudo-code where appropriate to clarify complex concepts.
Consider edge cases, error handling, and scalability concerns.
Image phase (the vspec addition)
Run the image phase only after the markdown plan is fully written and saved.
Generate exactly one hero image for the whole plan, plus one image per ## (H2) section that materially benefits from a visual. Skip purely administrative sections (e.g. "Notes", "Validation Commands") unless a visual genuinely aids comprehension.
Keep the total image count to 10 or fewer image targets. If there are more than ~9 H2 sections, merge or pick the sections where a diagram adds the most planning value.
Each image is a picture, not a document. Visually emphasize the architecture, the nodes, the components, the communication/data flow, the state transitions — the structure and meaning, not prose.
Each image prompt must contain no more than MAX_TEXT_LABELS_PER_IMAGE (10) text labels. Treat each label as one "set of words". List the exact label strings explicitly in the prompt and tell the model these are the complete set with no other words. Never ask the model to render paragraphs, captions, code blocks, or lorem ipsum.
All images in one spec must share one visual language: same palette (with hex codes), background, line weight, typography, node/arrow style, and the same negation list. Write the shared style brief once and prepend it verbatim to every image prompt — do not paraphrase between images, or the set will drift.
Assign recurring elements (e.g. "client", "cache", "store", "queue") a fixed color + shape across all images so the same concept looks the same in every diagram.
Use the bundled generator at IMAGE_GENERATOR for every image. Do not call, reference, or depend on any other image skill — this skill is fully self-contained.
Generate the images in parallel, never one at a time. Each image is an independent gpt-image-2 call that takes many seconds; firing them sequentially is the single biggest thing that makes this skill slow. Launch them all concurrently — background bash jobs in one shell with wait, or parallel Bash tool calls in a single turn.
Default to wide 2048x1152; use 1024x1024 (square) or 1152x2048 (tall) only when a section's diagram clearly needs it (e.g. a tall lifecycle, a square matrix).
Save images beside the plan in a same-named subdirectory and insert idempotent markdown references back into the plan.
Workflow
Phase 1 — Build the plan
Analyze Requirements — THINK HARD and parse the USER_PROMPT to understand the core problem and desired outcome.
Explore Codebase — Understand existing patterns, architecture, and relevant files.
Design Solution — Develop the technical approach including architecture decisions and implementation strategy.
Document Plan — Structure a comprehensive markdown document following the Plan Format.
Generate Filename — Create a descriptive kebab-case filename based on the plan's main topic (e.g. in-memory-ttl-lru-cache).
Save Plan — Write the plan to PLAN_OUTPUT_DIRECTORY/<filename>.md.
Phase 2 — Generate the visual layer
Prerequisite key check — Verify the OpenAI key is available before generating anything:
The generator reads OPENAI_API_KEY from the environment or a .env in the current working directory. If the key is missing, stop and ask the user to set it.
Create the image directory — Beside the plan, using the plan basename without extension:
Re-read the saved plan and extract: the H1 title, every ## H2 section and its content, and any architecture/protocol/flow/state/data-model details that suggest a diagram type.
Select image targets (≤ 10 total):
One hero target for the whole plan.
One target per H2 section that benefits from a visual. Prefer sections describing architecture, solution approach, data flow, lifecycle, phases, data model, testing strategy, or acceptance criteria.
Choose the diagram type per target: architecture map, dataflow, sequence, lifecycle timeline, swimlane, state machine, matrix, dependency map, or data model.
Write the shared style brief once. One paragraph that locks: visual register (clean vector technical diagram, dark documentation aesthetic), exact palette hex codes, background, line weight, typography feel, node/arrow conventions, the recurring-element color/shape mapping, and the full negation list (NO 3D, NO photoreal, NO decorative filler, NO icons except as labeled, NO paragraphs/captions). This paragraph is prepended verbatim to every prompt.
Draft per-image prompts using the brief + this pattern (style is global, composition is local):
[SHARED STYLE BRIEF — identical in every prompt]
Purpose: [what this one image communicates].
Composition: [specific spatial layout — left/right, top/bottom, central hub, layers, timeline, arrows].
Visual elements: [nodes, arrows, containers, badges, lanes] and how they connect.
Exact text labels, complete set, no other words: "Label 1", "Label 2", ... (max 10).
Output role: technical spec illustration embedded in markdown.
Plan Format
Follow this format when creating implementation plans:
# Plan: <taskname>## Task Description<describethetaskindetailbasedontheprompt>## Objective<clearlystatewhatwillbeaccomplishedwhenthisplaniscomplete><iftask_typeisfeatureorcomplexityismedium/complex, includethesesections:>## Problem Statement<clearlydefinethespecificproblemoropportunitythistaskaddresses>## Solution Approach<describetheproposedsolution >
Use these files to complete the task:
IMPORTANT: Execute every step in order, top to bottom.
Execute these commands to validate the task is complete:
Example: - Test to ensure the code compiles
Generate ALL images in parallel with the bundled generator, using deterministic filenames (00-hero.png, 01-<section-slug>.png, 02-<section-slug>.png, …). The image calls are independent and each takes many seconds — do not run them one after another.
Primary method — parallel bash calls. Fire every generate_image.py call at once as background jobs in a single shell invocation, then wait for all of them:
GEN=~/.claude/skills/vspec/scripts/generate_image.py
DIR=specs/<plan-name>
uv run "$GEN""<shared brief + hero composition>""$DIR/00-hero.png" &
uv run "$GEN""<shared brief + section-1 composition>""$DIR/01-architecture.png" &
uv run "$GEN""<shared brief + section-2 composition>""$DIR/02-lifecycle.png" &
uv run "$GEN""<shared brief + section-3 composition>""$DIR/03-data-model.png" --size 1024x1024 &
wait# block until every image finishesecho"all images done"
The bundled generator creates parent directories itself, so every job can start simultaneously. wide (2048x1152) is the default; append --size 1024x1024 (or 1152x2048) only for a section that needs square/tall.
Equivalently, if you can issue multiple tool calls in one turn, run each generate_image.py as a separate Bash tool call in the same message so they execute concurrently. For very large sets you may also split the batch across subagents — but the default and simplest path is parallel background jobs in one shell.
After wait, verify every file exists and is non-empty. If a section image failed, regenerate just that one (a single background job is fine). If the hero image failed, stop and report.
Insert markdown references into the plan using idempotent HTML markers, so re-running vspec replaces rather than duplicates. Use relative paths from the plan file. Preserve all existing prose and heading order.
Write a manifest at specs/<plan-name>/vspec-manifest.md containing: source plan path, timestamp, each target's section/filename/labels/full prompt, and success/failure status — so the set is repeatable.
Verify: every referenced image exists, all references are relative and point inside the image dir, no prompt used more than 10 labels, and the manifest exists. Then follow the Report Format.
