Prepare Handoff to AI

You have a spec — a UI Spec, a Data Spec, or both — and you want an AI agent to build the actual application. The spec becomes compact, reusable context that the agent can read and follow, instead of rediscovering the app from code and fragmented chat history.

When This Applies

• You are ready to move from exploration to implementation.
• You want to give a coding agent a clear picture of the app — screens, entities, naming, relationships — in one place.
• You are switching between agents or starting a new session and need the agent to pick up context quickly.
• You want to keep the agent aligned with the intended structure across multiple iterations.

What Makes a Good Handoff

A spec works as a handoff artifact because it is compact, structured, and self-describing. An AI agent reading a UI Spec immediately understands what screens exist, what each screen contains, and how blocks relate to each other. A Data Spec adds entities, field types, constraints, and relationships.

Together they give the agent enough context to generate:

• Database schema and migrations
• API endpoints and validation
• Frontend components and layouts
• Data binding and state management
• Navigation and routing

Without a spec, you explain all of this through chat messages — and re-explain it every time the context is lost.

Handoff in Spec Canvas

If you are working in Spec Canvas, the handoff is straightforward.

1. Open your project and make sure the spec reflects your current intent.
2. Copy the UI Spec as YAML (from the header or the actions menu).
3. If you have a Data Spec, copy it as well.
4. Paste both into your coding agent's context — as a chat message, a file, or a system prompt.

The agent reads the spec and can start building. You do not need to explain the format — it is self-describing.

Handoff Outside Spec Canvas

The spec is a plain YAML file. It works anywhere, not just in Spec Canvas.

In an AI chat

Paste the spec into a conversation with Claude, GPT, Gemini, or any other agent. Add a short instruction like "Build this application" or "Implement the dashboard screen." The agent uses the spec as the blueprint.

For ongoing work, keep the spec at the top of the conversation or in a pinned context. When you need changes, send a spec diff instead of re-explaining the full structure. See Spec Diff for details.

In an IDE

Give the spec to Cursor, Windsurf, or any AI-assisted editor. You can:

• Drop the YAML file into the project and reference it in prompts.
• Paste relevant screens or blocks into the chat when asking the agent to build specific components.
• Keep the spec as a living file that evolves alongside the code.

The agent treats the spec as authoritative context — it knows the screen structure, block purposes, and entity relationships without scanning the entire codebase.

In a terminal agent

Pass the spec to Claude Code or a similar CLI tool. A common approach:

1. Place the spec files (ui-spec.yaml, data-spec.yaml) in the project root or a /specs directory.
2. Tell the agent: "Read the specs in /specs and implement the application."
3. The agent scaffolds the full stack — backend, frontend, database — following the spec structure.

For incremental changes, send a spec diff: "Update the dashboard screen to match this change" with the modified block.

In a repository

Store the spec as a versioned file alongside your code. It serves as:

• Living documentation — a compact, readable description of the app that stays up to date.
• Onboarding context — a new agent (or a new developer) reads one file and understands the app structure.
• Change tracking — diff the spec file in git to see how the app structure evolved.

Keeping the Spec in Sync

The spec is most useful when it reflects the current state of the application. Two approaches:

Spec-first. Update the spec before changing code. The spec is the source of truth, and code follows. This works well during active development with AI agents.

Code-first, then sync. Build features in code, then update the spec to match. This works when you are iterating fast and the spec catches up periodically.

In both cases, the spec acts as a verification layer. When the implementation drifts from the intent, point the agent back to the spec. See Spec as Verification Layer for techniques.

Tips

• Send both specs together. When you have a UI Spec and a Data Spec, give the agent both. It generates better code when it understands the full context — interface and data model together.
• Start with one screen. You do not need to implement everything at once. Hand off one screen, get it right, then move to the next.
• Use spec diff for iterations. After the initial handoff, send only the changes. It is faster for you and less ambiguous for the agent.
• Include HTML references when useful. If you generated an HTML implementation in Spec Canvas that you like, include it alongside the spec. Tell the agent: "Match this visual reference." Spec Canvas marks each block in the generated HTML with a ui-spec-block-id attribute, so the agent can map every element in the HTML back to the corresponding block in the spec — no guessing which part is which.

Related

• Patterns & Practices — spec diff, verification layer, integrated specs.
• Explore Product Directions — how to arrive at a spec worth handing off.
• Reconstruct an Existing App — how to create a spec for an app that already exists.