# v0.dev Agent Collaboration Protocol

> A comprehensive guide for LLM agents on how to effectively collaborate with the `v0.dev` agent. This protocol focuses on understanding the architectural patterns of `v0.dev`-generated applications (Next.js, Tailwind CSS, shadcn/ui) and provides a framework for prompting, validating, and integrating its output.

**Version**: 1.0
**Document ID**: llms-vercel-v0.dev-agent-collaboration.txt
**Last Updated**: 2025-09-30
**Content Source**: Synthesized from analysis of `v0.dev` agent behavior, comparison of scaffolded projects, and user-provided context.
**Attribution**: This protocol is designed to complement `llms-vercel-build-integrity.gemini.md`.

---

## 1. Core Principle: The `v0.dev` Agent as an Implementation Partner

The `v0.dev` agent is a powerful collaborator specializing in the **implementation** of web UIs and full-stack applications from natural language prompts. It is not a black box but a skilled partner. Our role as strategic agents (Mia, Miette) is to provide it with clear, structurally sound specifications and then to validate its output.

> **Key Takeaway**: Our primary function is to be the **Architect and Validator**. The `v0.dev` agent is the **Builder**. We design the blueprint; it lays the bricks.

## 2. Architectural Hallmarks of `v0.dev` Projects

Applications generated by `v0.dev` have a distinct and consistent technical DNA. Understanding this structure is critical for effective collaboration.

*   **Framework**: **Next.js with the App Router**. This is the default. All prompts and validation must assume this structure.
    *   **Server vs. Client Components**: Be highly aware of this distinction. `v0.dev` may generate components that need the `"use client"` directive if they use hooks (`useState`, `useEffect`). This is a common source of build failures that we must validate.
    *   **File-based Routing**: New pages are created by adding directories and `page.tsx` files within the `app/` directory.

*   **Styling**: **Tailwind CSS** and **`shadcn/ui`**.
    *   UI generation prompts should describe layouts using Tailwind CSS utility classes.
    *   When requesting standard UI elements (buttons, cards, modals), reference `shadcn/ui` components to leverage the existing design system (e.g., "Create a Card component from shadcn/ui...").

*   **Key Architectural Pattern: Backend-for-Frontend (BFF)**: `v0.dev` often implements a BFF pattern by creating API routes within the Next.js application (e.g., in `app/api/...`).
    *   **Security**: This is done to protect sensitive information, such as API keys, by keeping them on the server-side.
    *   **Separation of Concerns**: The frontend makes `fetch` requests to these internal API routes, which then handle the communication with external services (like the Gemini API).
    *   **Implication for Us**: When requesting features that involve external APIs, we should specify that the API calls should be handled in a backend route.

*   **Project Structure**:
    *   `app/`: Contains all routes, including API routes.
    *   `components/`: Often contains UI components, especially those from `shadcn/ui`.
    *   `lib/`: For utility functions.
    *   `public/`: For static assets.

*   **Deployment**: Tightly integrated with **Vercel**. This reinforces the mandate from `llms-vercel-build-integrity.gemini.md`: a successful `npm run build` is the only true measure of completion.

## 3. The Collaboration Workflow: A Three-Phase Protocol

Our interaction with `v0.dev` follows a clear, structured process that leverages our respective strengths.

### Phase 1: Specification & Prompting (Our Role)
Before `v0.dev` is invoked, our responsibility is to define the **Desired Outcome**.
1.  **Architect (Mia's Role)**: Define the component's required functionality, props, and structural relationship to the rest of the application.
2.  **Narrate (Miette's Role)**: Describe the desired user experience, look, and feel.
3.  **Forge the Prompt**: Combine the architectural and narrative requirements into a single, clear, and actionable prompt for the `v0.dev` agent.

### Phase 2: Generation (`v0.dev`'s Role)
The `v0.dev` agent takes our prompt and generates the necessary files (`.tsx`, `.css`, etc.). It has the capability to perform agentic actions like web searches and error correction during its process.

### Phase 3: Validation & Integration (Our Role)
Once `v0.dev` has completed its work and the code has been pulled into our local environment, our role resumes.
1.  **Structural Analysis (Mia's Role)**:
    *   Review the generated files.
    *   Verify that the code adheres to the architectural specification.
    *   **Crucially, run `npm run build` locally** to ensure there are no build errors, as detailed in `llms-vercel-build-integrity.gemini.md`.
2.  **Integration**:
    *   Import the new components into the main application.
    *   Wire up state and props as required.
    *   Ensure the new code integrates seamlessly with existing structures.
3.  **Narrative Review (Miette's Role)**:
    *   Does the final result *feel* right?
    *   Does it align with the desired user experience?

## 4. Prompting `v0.dev`: Best Practices

Crafting effective prompts is the key to successful collaboration.

*   **Be Explicit**: State the desired frameworks and libraries directly.
    *   *Good*: "Using Next.js and Tailwind CSS, create a responsive pricing page..."
*   **Reference the Design System**: Leverage `shadcn/ui` to ensure consistency.
    *   *Good*: "Add a `shadcn/ui` Button with a 'default' variant..."
*   **Specify Logic Location**: Clearly state whether logic should be on the client or server.
    *   *Good*: "Create a new API route at `/api/chat` to handle the backend logic for the chat component."
    *   *Good*: "The component should be a client component (`'use client'`) that fetches data from the `/api/data` endpoint."
*   **Describe, Don't Prescribe (Too Much)**: Describe the desired UI and behavior in natural language. Let the agent handle the precise implementation.
    *   *Good*: "The card should have a prominent title, a paragraph of descriptive text, and a call-to-action button at the bottom."
    *   *Less Good*: "Create a div with flex-direction column, then an h2, then a p, then another div with a button..."
*   **Provide Context**: If modifying an existing component, provide the relevant code and clearly state the desired changes.

## 5. Future Vision: API-Driven Collaboration

The current workflow involves a manual hand-off to the `v0.dev` agent. The desired future state is a seamless, API-driven integration.

*   **Goal**: To be able to programmatically call a `v0.dev` API endpoint from our own agentic tools.
*   **Workflow**:
    1.  Our agent formulates a high-fidelity prompt based on its analysis.
    2.  It makes a tool call to a `v0_dev_generate` tool, passing the prompt.
    3.  The `v0.dev` agent generates the code in a separate branch.
    4.  Our agent is notified upon completion and automatically pulls the changes to begin the validation phase.
*   **Impact**: This will create a fully autonomous `Specification -> Implementation -> Validation` loop, dramatically accelerating development velocity while maintaining architectural integrity.

## 7. Learnings from Debugging `v0.dev` Output

This section captures critical insights gained from debugging `v0.dev`-generated code. These are common structural pitfalls that can lead to build failures or unexpected runtime behavior.

*   **Missing `"use client"` Directive**: Client-side components using React hooks (`useState`, `useEffect`, etc.) must explicitly include `"use client"` at the top of the file. Failure to do so results in server-side rendering errors.
*   **Incorrect `randomUUID` Usage**: In Next.js API routes and services, `randomUUID` from Node.js's `crypto` module must be explicitly imported (`import { randomUUID } from 'crypto';`) and called directly as `randomUUID()`, not `crypto.randomUUID()`.
*   **Type Mismatch between Mock Data/API Responses and Interfaces**: Ensure that mock data and actual API responses strictly adhere to their corresponding TypeScript interfaces. Discrepancies in field names, types, or optionality can cause runtime errors during serialization or consumption.
*   **Insufficient `browser_wait_for` Timeouts**: When testing AI generation features, even with mock services, ensure `browser_wait_for` calls have sufficiently long timeouts (e.g., 10-15 seconds). AI generation, even mocked, can introduce delays that exceed default timeouts.
*   **API Route and Environment Variable Verification**: Always confirm that API routes are correctly implemented (e.g., `route.ts` exists and is correctly configured) and that all necessary environment variables (e.g., `API_KEY`) are properly set and accessible in the server environment.

These learnings are crucial for transforming oscillating debugging patterns into an advancing pattern of efficient collaboration with `v0.dev`.

*   **`llms-vercel-build-integrity.gemini.md`**: This protocol is the mandatory companion to the collaboration workflow. All code generated by `v0.dev` **must** pass the pre-flight checks outlined in this document.
