Planning Artifacts

Step 1: Draft the PRD

Open materials/templates/prd-template.md. This is the same template you used for Yasmine's project, but the terrain is different. Marco's system spans three layers: what the user sees, what the API provides, and what the database stores.

Open materials/first-contact.md alongside the template. Direct Claude to draft a PRD from Marco's email. Be specific about what the PRD needs to cover:

Draft a PRD from the client email in materials/first-contact.md using the template in materials/templates/prd-template.md. The system has three layers: a PostgreSQL database, Next.js API routes, and a Next.js frontend. Every requirement must trace to at least one database table, one API route, and one page.

Review the draft. Does the PRD address all five of Marco's requirements? Does it name specific tables (farms, batches, products, orders), specific API endpoints (GET inventory, POST orders), and specific pages (inventory dashboard, order form, order status)? If the PRD stays at a high level -- "an inventory management system" -- without naming the concrete pieces, push Claude to be specific. The PRD is the contract between what Marco asked for and what you'll build. Vague contracts produce vague systems.

One constraint to specify now: the frontend uses Next.js with App Router, not Pages Router. If you don't specify this, Claude will generate internally consistent code using whichever pattern it defaults to -- and switching later is expensive. The same applies to server components vs client components. The inventory dashboard fetches live data from the database, so it's a server component. The order form needs client-side interactivity (state, validation, submission), so it's a client component. Record these decisions in the PRD. If you don't specify them here, you'll be undoing architectural decisions during the build.

Step 2: Cross-model review

This is new. Open a second AI -- a different model from the one that wrote the PRD. Give it Marco's email and the PRD draft, and ask it to review:

Review this PRD against the client's email. List every client requirement and whether the PRD addresses it. List anything the PRD adds that the email doesn't mention. Flag any gaps.

The second AI has no context about why those choices were made. It reads the PRD and the email with fresh eyes. That fresh perspective is the point. The first AI produced the output; the second checks it. Different models have different failure modes -- a gap that the first model normalized might be obvious to the second.

Read the review. If it flags genuine gaps, update the PRD. If it flags things that are intentional design decisions (adding a status field the client didn't mention, for example), that's fine -- note why in the PRD.

Step 3: Design decisions

Open materials/templates/design-decisions-template.md. This template has a new section you didn't see in P2: Data Layer. Full-stack systems require decisions about the database that shape everything downstream.

Direct Claude to draft the design decisions document. The key choices:

Framework: Next.js with App Router for multi-page routing and mixed SSR/SSG. The inventory dashboard needs SSR for fresh data. A static marketing page (if any) could use SSG.

Database: PostgreSQL for relational data. Marco's data has clear relationships -- farms to batches to products to orders. Relational databases handle these naturally.

Styling: Tailwind CSS. Same as P2.

Server vs client components: Document which pages are server components (data-fetching pages like the inventory dashboard) and which are client components (interactive pages like the order form). Record the reasoning -- not just what the decision is, but why. A future developer or AI session that opens this file needs to understand the constraint, not guess at it.

Step 4: Draft the architecture

Direct Claude to draft the architecture document: database tables, API route structure, and page structure. The three layers should be visible side by side.

graph TD
    subgraph Frontend["Next.js Pages"]
        P1[Inventory Dashboard]
        P2[Order Form]
        P3[Order Status]
    end
    subgraph API["API Routes"]
        A1["GET /api/inventory"]
        A2["GET /api/inventory/:id"]
        A3["PUT /api/inventory/:id"]
        A4["POST /api/orders"]
        A5["GET /api/orders"]
        A6["PUT /api/orders/:id"]
    end
    subgraph DB["PostgreSQL Tables"]
        T1[farms]
        T2[batches]
        T3[products]
        T4[orders]
    end
    P1 --> A1
    P1 --> A2
    P2 --> A4
    P2 --> A1
    P3 --> A5
    P3 --> A6
    A1 --> T1
    A1 --> T2
    A1 --> T3
    A2 --> T1
    A2 --> T2
    A2 --> T3
    A3 --> T2
    A4 --> T3
    A4 --> T4
    A5 --> T4
    A5 --> T3
    A6 --> T4

Review the architecture. Every requirement from the PRD should trace to at least one table, one API route, and one page. If a requirement doesn't map to all three layers, the architecture has a gap. The database stores the data. The API serves it. The frontend displays it. A missing link in any layer means that requirement won't work.

Step 5: Create the CLAUDE.md governance file

You've done this before. Create the CLAUDE.md for this project -- the governance file that gives Claude everything it needs to work on any ticket. The content is more complex than P2 because it spans three layers: database tables, API routes, and frontend pages all appear in the ticket list.

Direct Claude to draft CLAUDE.md. Review it against materials/CLAUDE.md for structure reference. Does the ticket list cover all three layers? Does each ticket have acceptance criteria? Does the tech stack section list everything -- Next.js, PostgreSQL, Prisma, React Testing Library, Vitest, Tailwind, Sentry, Vercel?

Step 6: Create the ticket breakdown

Open materials/templates/ticket-template.md. Full-stack tickets need sequencing. The order matters more than it did for Yasmine's frontend-only project.

Schema first. The database tables must exist before anything can query them. API routes second -- they depend on the schema. Frontend pages third -- they depend on the API. Tests alongside each layer. This sequencing isn't a rule you memorize; it follows from the dependencies. If you write a frontend page before the API route exists, you're building against an imaginary contract.

Direct Claude to create the ticket breakdown with explicit ordering. Review the sequence: can each ticket be completed without depending on a ticket that comes later?