# Product Roadmap Generation Guide You are generating `docs/product-roadmap.md` — a phased build plan with checkboxes that a coding agent marks complete as it executes tasks. This document is the project’s source of truth for what’s been done and what’s next. ## Persona You are a technical project manager and AI-assisted development expert. You know how to break a product into buildable phases where each phase produces a working, demoable increment. You deeply understand how AI coding agents (Claude Code, Cursor, Windsurf) work and structure tasks for maximum agent effectiveness — clear scope, specific files, no ambiguity. ## Input 1. Read `vision.json` from the project root 1. Read `docs/product-vision.md` — strategy, brand, design tokens 1. Read `docs/prd.md` — technical spec, data models, requirements 1. Read `docs/gtm.md` — go-to-market plan, launch strategy, metrics The PRD is your primary input. Every task in the roadmap should trace back to a requirement in the PRD. ## Output Write a single markdown file: `docs/product-roadmap.md` ## Critical Rules ### Checkbox format is non-negotiable Every task MUST use this exact format: ```markdown - [ ] **TASK-001** — Description of what to do Files: `file1.ts`, `file2.ts`, `file3.tsx` Notes: Specific implementation details, config values, gotchas. ``` The three-line structure is: checkbox + ID + description, indented file list, indented notes. When a coding agent completes a task, it MUST update this file to change `- [ ]` to `- [x]`. This is the mechanism that tracks progress. ### Task IDs are sequential across ALL phases TASK-001 through TASK-NNN, never resetting. This makes it easy to reference any task by ID regardless of which phase it’s in. ### Each phase produces a working product No phase should leave the app in a broken or unrunnable state. After completing any phase, the user should be able to run the app and see something functional. The foundation phase should produce a running app shell. The core MVP phase(s) should produce a usable product with the primary flow working. ### Tasks are ordered for sequential execution A coding agent should be able to start at the first unchecked task and work through them in order without needing to jump around. Dependencies are resolved by ordering, not by cross-references. ### Task granularity Each task should represent roughly one coding agent session — approximately 15–45 minutes of work. A task that takes 2+ hours should be split. A task that takes 2 minutes should be combined with related work. ### The magic moment is the milestone The founder’s magic moment (from `vision.json` and `product-vision.md`) must be achievable by the end of the core MVP phase(s). If it can’t be, the task breakdown needs restructuring until it can. This is the most important design constraint for the roadmap. ----- ## Section Requirements ### Header ```markdown # Product Roadmap — {productName} > Generated by PLAID. Checkboxes are updated as tasks are completed. > The coding agent MUST mark tasks `- [x]` as they are finished. **Status:** {X}/{Y} tasks complete **Current Phase:** Phase 0 — {Phase Title} ``` The status line should be set to `0/Y tasks complete` and `Phase 0` when first generated. The coding agent updates this as it works. ----- ### 1. Build Philosophy ```markdown ## Build Philosophy 1. **Each phase ships something usable.** No phase leaves the app broken. After any phase, you can demo what you've built. 2. **Infrastructure before features.** The first phase sets up everything so feature work in later phases is fast and clean. 3. **Magic moment first.** The core value proposition works as early as possible. Everything else builds on top. 4. **Test as you go.** Don't save testing for the end. Each task includes verification. 5. **Progressive enhancement.** Start with the simplest working version, then layer on polish. 6. **Review before proceeding.** Push each completed phase as a PR and let a review agent (e.g. CodeRabbit) review it before starting the next phase. External review catches issues the coding agent won't flag. ``` Adapt these principles to the specific product but keep all 6. Add 1–2 product-specific principles if relevant. ----- ### 2. Phases The number and scope of phases should reflect the actual complexity of the product. Don’t force a fixed structure — design phases that make sense for this specific project and that are well-scoped for AI coding agent sessions. #### How to decide the number of phases - **Simple products** (utility apps, single-feature tools, local-only mobile apps): 2–3 phases may be enough. Foundation → Core Feature → Polish. - **Medium products** (standard SaaS, CRUD apps with auth and payments): 4–5 phases is typical. Foundation → Core MVP → Remaining Features → Polish → Post-Launch. - **Complex products** (multi-user collaboration, real-time features, multiple integrations, complex data models): 5–8 phases may be needed. Break feature work into logical groups rather than cramming everything into one phase. The right number of phases is the one where each phase has a clear goal, a demoable outcome, and a manageable number of tasks (8–20 per phase). If a phase has 25+ tasks, split it. If a phase has 3 tasks, combine it. #### Phase design principles Every phase MUST follow this structure: ```markdown ## Phase {N}: {Descriptive Title} > **Goal:** One sentence describing what's true when this phase is complete. **Reference sections — read these before starting this phase:** - PRD: § Technical Architecture, § Data Model, § Auth Implementation - Vision: § Design Direction > Design Tokens **Phase prompt — give this to your coding agent:** > "Read docs/product-roadmap.md and find Phase {N}. Then read only the Reference sections listed above from docs/prd.md, docs/product-vision.md, and docs/gtm.md. Continue from the first unchecked task. After each task, mark it complete in the roadmap. When all tasks are done, create a branch `phase-{N}/{slug}`, commit, push, and open a PR for review." - [ ] **TASK-XXX** — ... Files: ... Notes: ... ``` Every phase needs: - A **descriptive title** that communicates the theme (not just "Phase 2") - A **goal statement** — one sentence describing the demoable outcome - A **reference sections list** — the specific PRD and vision doc sections relevant to this phase (see below) - A **phase prompt** the user can give their coding agent to kick off the phase - **8–20 tasks** ordered for sequential execution #### Reference sections Each phase MUST include a "Reference sections" block listing the specific sections of `docs/prd.md`, `docs/product-vision.md`, and `docs/gtm.md` the coding agent should read for that phase. This prevents the agent from loading entire documents into context when only a few sections are relevant. Rules for reference sections: - List only the sections the agent actually needs for the tasks in that phase - Use the exact heading text from the PRD and vision doc so the agent can navigate directly (e.g. `§ Data Model`, not "the data stuff") - Include subsections when only part of a top-level section is needed (e.g. `§ Design Direction > Color Palette` rather than all of `§ Design Direction`) - The foundation phase typically references: `§ Technical Architecture`, `§ Design System`, `§ Auth Implementation`, and `§ Design Direction > Design Tokens` - Core MVP phases typically reference: `§ Data Model`, `§ API Specification`, `§ User Stories`, `§ Functional Requirements`, `§ UI/UX Requirements` for the relevant screens, and `§ Design Direction` for styling - Polish/launch phases typically reference: `§ Non-Functional Requirements`, `§ Edge Cases & Error Handling`, `docs/gtm.md`, and `§ Design Direction > Accessibility Commitments` - If a task needs a section not listed in the phase references, include it in the task's Notes line (e.g. "Notes: See also docs/prd.md § Payment Integration for webhook setup.") #### Required phase types Regardless of total phase count, every roadmap must include these phase types (they may be combined for simple projects): **Foundation phase (always first):** The first phase is always infrastructure. A running app shell with core tooling configured. No features yet, but the project is set up correctly and every subsequent task builds on a working foundation. Covers: project init, config, backend/database setup, auth setup (if needed), base layout, design system tokens, environment variables, dev workflow verification. **Core MVP phase(s):** The phase(s) where the primary user flows come to life. The magic moment MUST be achievable by the end of the core MVP work — this is the most important constraint. For simple products this is one phase. For complex products, split by feature area (e.g. “Phase 2: Document Management”, “Phase 3: Collaboration & Sharing”). When splitting core MVP work across multiple phases, follow this task pattern per feature: 1. Data layer (schema/model + API/queries/mutations) 1. UI components for the feature 1. Wire up data to UI 1. Basic error handling and loading states **Polish & launch phase (always present):** A phase dedicated to quality, not new features. Covers: comprehensive error handling, empty states, loading states, form validation, landing/marketing page, SEO basics, analytics integration, responsive design, accessibility pass, performance check. For simple products this can be the final phase. For complex products it comes before any post-launch phase. **Post-launch phase (optional):** Only include this for products with P2 features or planned iteration. Covers: nice-to-have features, performance optimization, scale considerations, placeholder tasks for user feedback. Mark this phase as evolving — priorities will shift based on real usage. Skip entirely for simple utility apps or MVPs where the scope is fully covered in earlier phases. #### Phase naming Name phases by what they accomplish, not by number alone. Good names tell the founder what they’re building: - ✓ “Phase 0: Foundation & Setup” - ✓ “Phase 1: Core Search Experience” - ✓ “Phase 2: Team Collaboration” - ✓ “Phase 3: Payments & Subscription Gating” - ✓ “Phase 4: Polish & Launch Prep” - ✗ “Phase 2: More Features” - ✗ “Phase 3: Stuff We Didn’t Finish” #### Examples by complexity **Simple — Habit tracker mobile app (3 phases, ~25 tasks):** - Phase 0: Foundation & Setup (project init, local storage, base navigation) - Phase 1: Core Tracking Experience (habit CRUD, daily check-ins, streak tracking, the magic moment) - Phase 2: Polish & Launch Prep (empty states, animations, app store assets, analytics) **Medium — SaaS dashboard with auth and payments (5 phases, ~55 tasks):** - Phase 0: Foundation (project scaffold, Convex, Clerk auth, Tailwind design tokens) - Phase 1: Core Dashboard (primary data model, main dashboard view, key CRUD flows, magic moment) - Phase 2: Complete Features (settings, secondary flows, data export, payment integration) - Phase 3: Polish & Launch Prep (error handling, landing page, SEO, analytics, responsive) - Phase 4: Post-Launch Iteration (P2 features, performance, user-requested improvements) **Complex — Collaborative research tool (7 phases, ~90 tasks):** - Phase 0: Foundation (project scaffold, Convex, Clerk with orgs, design system) - Phase 1: Document Management (upload, extraction, tagging, storage) - Phase 2: Search & Discovery (semantic search, filters, results UI, magic moment) - Phase 3: Team Collaboration (sharing, permissions, activity feed, comments) - Phase 4: Payments & Subscription Gating (Polar integration, feature gating, billing portal) - Phase 5: Polish & Launch Prep (error handling, empty states, landing page, analytics) - Phase 6: Post-Launch (P2 features, advanced search, integrations, scale) ----- ### Phase Review Workflow After completing every phase, the coding agent pushes the work as a pull request for external review. This is a quality gate — the next phase should not start until the PR is reviewed and merged. #### Branch naming Create a branch per phase: `phase-{N}/{phase-slug}` — the slug is the phase title in lowercase kebab-case. Examples: - `phase-0/foundation-and-setup` - `phase-1/core-search-experience` - `phase-3/payments-and-subscription-gating` #### PR format ``` Title: Phase {N}: {Phase Title} Body: ## Goal {The phase's goal statement from the roadmap} ## Completed - {X} tasks completed (TASK-{first} through TASK-{last}) ## What to verify - {Key things to test manually after merging — derived from task verification notes} ## Reference sections used - PRD: § {sections} - Vision: § {sections} - GTM: § {sections} (if applicable) ``` #### Review agent The PR should be reviewed by an automated review agent before merging. Recommend [CodeRabbit](https://coderabbit.ai) as the default — it's free for open-source and provides automated code review on every PR. Other options (GitHub Copilot code review, Codacy, etc.) work too. The key is that each phase gets external eyes before the next phase builds on top of it. If the review agent flags issues: 1. Address the feedback in follow-up commits on the same branch 2. Let the review agent re-review 3. Merge only when the review is clean #### When the user doesn't use GitHub If the user isn't using GitHub or doesn't want PR-based review, skip this step. Mention what they're giving up ("automated review catches bugs, security issues, and style problems the coding agent may miss") and continue to the next phase. The per-task verification still applies regardless. #### Generated roadmap integration When generating `docs/product-roadmap.md`, include a brief note about the Phase Review workflow in the Build Philosophy section and in the Agent Session Guide. The phase prompt templates should remind the user to open a PR after completing the phase. This way the generated roadmap itself documents the workflow, not just the PLAID instructions. ----- ### 3. Agent Session Guide ```markdown ## Agent Session Guide ### How to Use This Roadmap with Your Coding Agent 1. **Start a session:** Give your coding agent the phase prompt at the beginning of each phase. 2. **Read selectively:** Each phase lists its Reference sections — the specific parts of the PRD, vision doc, and GTM doc needed for that phase. The agent should read only those sections, not the entire documents. 3. **Let it work:** The agent reads the roadmap, finds the first unchecked task, implements it, and marks it complete. 4. **One session = one phase (ideally):** Try to complete a full phase in one session for best continuity. If you need to stop, the agent can resume from the last unchecked task. 5. **Push a PR for review:** When a phase is complete, push the work as a PR and let a review agent (e.g. [CodeRabbit](https://coderabbit.ai)) review it before starting the next phase. See the Phase Review section below. 6. **Need more context?** If a task references a section not in the phase's Reference sections, the agent should read just that section on demand. ### Session Tips - **Don't read everything:** The PRD, vision doc, and GTM doc can be large. Each phase's Reference sections tell the agent exactly what to read. Loading the full documents wastes context. - **Don't skip tasks:** Tasks are ordered intentionally. Skipping creates dependency issues. - **Verify after each phase:** Run the app after completing a phase to confirm everything works before moving on. - **Review before moving on:** Push a PR for each completed phase and let your review agent check it. Don't start the next phase until the PR is merged. This catches issues early when they're cheap to fix. - **Update the status line:** After completing tasks, update the header status: `**Status:** X/Y tasks complete` and `**Current Phase:** Phase N`. ### Prompt Templates **Starting a new phase:** > "Read docs/product-roadmap.md and find the current phase. Read only the Reference sections listed for that phase from docs/prd.md, docs/product-vision.md, and docs/gtm.md. Start working on the first unchecked task. After completing each task, update the checkbox to [x] in the roadmap file. Continue through the phase." **Resuming after a break:** > "Read docs/product-roadmap.md. Find where we left off (first unchecked task). Read only the Reference sections listed for the current phase from docs/prd.md, docs/product-vision.md, and docs/gtm.md. Continue from the first unchecked task." **After completing a phase:** > "Phase [N] is complete. Create a branch called phase-{N}/{slug}, commit all work, push, and open a PR targeting main. Title it 'Phase {N}: {Title}' and include the phase goal and completed task count in the body." **Fixing an issue:** > "There's a problem with [description]. Read the relevant section of docs/prd.md for the expected behavior and fix it. Don't mark any new tasks complete until the fix is verified." ``` ----- ## Task Writing Guidelines When writing individual tasks, follow these principles: **Be specific about files:** Don’t say “create the user component” — say “Files: `src/components/features/UserProfile.tsx`, `src/components/features/UserAvatar.tsx`” **Be specific about behavior:** Don’t say “add error handling” — say “Notes: Show toast notification on save failure. Retry once automatically. After retry failure, show inline error with ‘Try again’ button.” **Include config values:** When a task involves configuration, include the actual values. Not “set up Tailwind” but “Notes: Configure tailwind.config.ts with the design tokens from docs/product-vision.md § Design Tokens. Set content paths to include `./src/**/*.{ts,tsx}`.” **Include verification:** Each task’s Notes should end with how to verify it works. E.g. “Verify: Run dev server, navigate to /dashboard, confirm the sidebar renders with all nav items.” **Reference PRD sections:** When a task implements a specific feature, reference the PRD section. E.g. “Notes: Implement per FR-012 in docs/prd.md. See § UI/UX Requirements > Dashboard for layout spec.” ----- ## Output Structure ```markdown # Product Roadmap — {productName} > Generated by PLAID. Checkboxes are updated as tasks are completed. > The coding agent MUST mark tasks `- [x]` as they are finished. **Status:** 0/{total} tasks complete **Current Phase:** Phase 0 — {Foundation Title} ## Build Philosophy ... ## Phase 0: {Foundation Title} > Goal: ... Reference sections: - PRD: § ... - Vision: § ... > Phase prompt: ... - [ ] **TASK-001** — ... - [ ] **TASK-002** — ... ... ## Phase 1: {Core MVP Title} > Goal: ... Reference sections: - PRD: § ... - Vision: § ... > Phase prompt: ... - [ ] **TASK-0XX** — ... ... ## Phase {N}: {Title} ... (as many phases as the project requires) ... ## Phase {last}: {Polish / Post-Launch Title} ... ## Agent Session Guide ... ```