Prd Creator

PRD Creation Assistant

Transform software ideas into comprehensive PRDs and actionable implementation tasks through a two-part process.

Overview

This skill helps beginner-level developers.

1. Receive an implementation description from the user 2. Create detailed PRD documents through structured questioning 3. Verify implementation prerequisites, including access, MCPs, docs, env variables, and test users 4. Generate implementation task lists in JSON format for developers 5. Write an overall description of the project. An executive summary that gives a high level overview of the app and its main features.

Part 1: Implementation Description

You will receive a lacking implementation description from the user. The main goal is to comprehend the intent and think about the larger architecture and a robust way to implement it, filling in the gaps.

Part 2: PRD Creation

File: PRD.md

You will need to ask clarifying questions to get a clear understanding of the implementation.

When to use: User wants to document a software idea or create feature specifications

What it does:

• Guides structured questioning to gather all requirements
• Verifies project prerequisites before PRD finalization
• Creates/updates .env.local with placeholder values only
• Creates executive summary for validation
• Researches competitive landscape
• Generates comprehensive PRD.md with:
• App overview and objectives
• Target audience
• Success metrics and KPIs
• Competitive analysis
• Core features and user flows
• Technical stack recommendations
• Prerequisites and access
• Security considerations
• Assumptions and dependencies

Process: 1. Ask clarifying questions using AskUserQuestion tool 2. Verify prerequisites and create/update .env.local placeholders 3. Create executive summary for user approval 4. Research competition via WebSearch 5. Generate complete PRD 6. Iterate based on feedback

Read [PRD.md](PRD.md) for complete instructions.

---

Part 3: Implementation Task Generation

File: JSON.md

You will need to analyze the completed PRD and generate a comprehensive task list in JSON format.

When to use: After PRD is complete and approved, or user requests task breakdown

What it does:

• Analyzes the completed PRD
• Generates TASK-1 as mandatory prerequisite verification
• Generates a complete list of implementation tasks in JSON format, covering all features and requirements from the PRD
• Keeps the tasks small and manageable
• Categorizes tasks by type (functional, ui-ux, api-endpoint, security, etc.)
• Defines verification ('pass') steps for each task
• Creates developer-ready checklist

IMPORTANT:

• Each task should be simple enough to be completed in maximum 10 minutes.
• If a task is too complex, it should be split into smaller tasks.

Read [JSON.md](JSON.md) for complete instructions.

Part 4: Overall Description

You will need to read the completed PRD and generate an overall description of the project in PROJECT_ROOT/.agent/prd/SUMMARY.md.

The description should be short, concise and contain:

• An overall description of the project
• The main features of the app
• Key user flows
• A short list of key requirements

Quick Start

If user wants to create a PRD: 1. Read PRD.md 2. Follow the PRD creation workflow 3. Verify prerequisites and create/update .env.local with placeholder values only 4. If needed, update the overall description SUMMARY.md 5. After PRD completion, ask: "Would you like me to generate implementation tasks? See Part 2."

If user wants implementation tasks for an existing PRD: 1. Read JSON.md 2. Read the PRD file 3. Generate comprehensive task list in JSON format, starting with TASK-1 prerequisite verification 4. Save as tasks.json

If user wants both: 1. Complete PRD creation first PRD.md, including prerequisite verification and .env.local placeholders 2. Get user approval on PRD 3. If needed, update the overall description SUMMARY.md 4. Proceed to generate implementation tasks JSON.md

If a user want to update the PRD: 1. Read PRD.md 2. Update the PRD 3. Save as PRD.md 4. If needed, update the overall description SUMMARY.md 5. Ask user if they want to generate implementation tasks

If a user want to update the implementation tasks: 1. Read JSON.md 2. Update the implementation tasks 3. Save as tasks.json 4. Ask user if they want to update the PRD again

If user wants to update both the PRD and the implementation tasks: 1. Update the PRD first PRD.md 2. If needed, update the overall description SUMMARY.md 3. Update the implementation tasks JSON.md 4. Save as PRD.md and tasks.json

After completion

Ensure the required files are present:

• PROJECT_ROOT/.agent/prd/PRD.md
• PROJECT_ROOT/.agent/prd/SUMMARY.md
• PROJECT_ROOT/.agent/tasks.json

If they are not present, warn the user and ask if they would like to create any of them.

Important Constraints

• Do not generate code - focus on documentation and task specification
• Use AskUserQuestion extensively in Part 1 to clarify requirements
• Never write real secret values to PRD, tasks, chat, logs, or .env.local; use placeholder values and tell the user to fill real values manually
• In Part 2, generate comprehensive task lists (50-200+ tasks for typical projects)
• In Part 2, always generate TASK-1 as prerequisite verification before feature work
• Always initialize tasks with "passes": false - never mark tasks complete during generation
• Use available tools: AskUserQuestion, WebSearch, Sequential Thinking, Read

Implementation Task Generation

Transform the completed PRD into simple, concise, actionable and verifiable implementation tasks in JSON format. This creates a comprehensive task list for developers (human or AI) to build and verify the product.

When to Use

After completing PRD creation, ask the user: "Your PRD is complete. Would you like me to generate implementation tasks? I'll create a comprehensive JSON task list that breaks down all features into verifiable development work."

Only proceed after user confirmation.

Task Generation Workflow

You should read the PRD markdown file located in PROJECT_ROOT/.agent/prd/PRD.md. Each task in the PRD will have a unique ID, formatted as TASK-${ID}. Use those IDs to generate the task list, except TASK-1 is always reserved for prerequisite verification.

Copy and track progress:

Task Generation Progress:
- [ ] Analyze the complete PRD
- [ ] Generate mandatory prerequisite verification task first
- [ ] Generate task index in `PROJECT_ROOT/.agent/tasks.json`
- [ ] Generate detailed spec for each task in `PROJECT_ROOT/.agent/tasks/TASK-${ID}.json`
- [ ] Present complete task list to user for review

CRITICAL: If any of the tasks is unclear, interview the user relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide the user's recommended answer. Ask the questions one at a time. If a question can be answered by exploring the codebase, explore the codebase instead.

Mandatory First Task: Prerequisite Verification

Every generated task list must start with TASK-1: Verify project prerequisites and access.

Use the Prerequisites and Access section from PROJECT_ROOT/.agent/prd/PRD.md as the source of truth. This task must verify that implementation can safely begin before feature work starts.

TASK-1 must confirm:

• PROJECT_ROOT/.env.local exists and contains placeholder entries for every required environment variable name from the PRD
• The user has manually filled real local values where needed, without copying those values into the PRD, task specs, logs, or chat
• Database access can be verified or the missing access is explicitly recorded
• Required MCP servers/tools are available and authenticated, or gaps are explicitly recorded
• Required service documentation links are available and relevant
• Required login/test users exist or there are clear steps to create/request them
• Any open prerequisite gaps have a user-approved proceed/block decision from the PRD

All downstream implementation tasks that require these prerequisites must include TASK-1 in dependencies.

Use this exact shape for the first task, adapting names and details to the PRD:

``json:PROJECT_ROOT/.agent/tasks/TASK-1.json { "id": "TASK-1", "title": "Verify project prerequisites and access", "category": "setup", "description": "Verify that required database access, MCPs, service documentation, environment variables, and login/test users are available before implementation begins.", "acceptanceCriteria": [ "PROJECT_ROOT/.env.local exists with placeholder entries for every required environment variable name listed in the PRD", "Real secret values are not written to the PRD, task specs, repository, logs, or chat", "The user has manually filled required local secret values in .env.local where needed", "Database connectivity is verified, or the missing access is recorded with a user-approved proceed/block decision", "Required MCP servers/tools are installed and authenticated, or gaps are recorded with a user-approved proceed/block decision", "Required service documentation links are available to the implementer", "Required login/test users are available or documented with request/create steps, without passwords or secret values" ], "steps": [ { "step": 1, "description": "Read prerequisite requirements from the PRD", "details": "Open PROJECT_ROOT/.agent/prd/PRD.md and review the Prerequisites and Access section. List required database access, MCPs, service docs, environment variable names, login/test users, and any open gaps.", "pass": false }, { "step": 2, "description": "Verify .env.local placeholder names", "details": "Confirm PROJECT_ROOT/.env.local exists and contains every required environment variable name from the PRD. Add missing names with placeholder values only, such as TODO_FILL_MANUALLY`. Do not write real secret values.", "pass": false }, { "step": 3, "description": "Confirm local secret values are filled manually", "details": "Ask the user to confirm they filled real local values where needed. Never print, store, commit, or copy actual passwords, API keys, tokens, or connection strings into generated files or chat.", "pass": false }, { "step": 4, "description": "Verify database and service access", "details": "Run the safest available read-only connectivity checks for the database and required services. If access cannot be verified, record the blocker or user-approved proceed decision before continuing.", "pass": false }, { "step": 5, "description": "Verify MCPs and service documentation", "details": "Confirm required MCP servers/tools are available and authenticated. Confirm required documentation links from the PRD are accessible and sufficient for implementation.", "pass": false }, { "step": 6, "description": "Verify login/test user availability", "details": "Confirm required login/test users exist with the needed roles and permissions, or document the exact steps and owner for creating/requesting them. Do not store passwords or secret values.", "pass": false } ], "dependencies": [], "estimatedComplexity": "low", "technicalNotes": [ "This task gates implementation. Do not start dependent feature tasks until required prerequisites are verified or explicitly approved as gaps.", "Secrets must stay local and must never be committed or copied into PRD/task artifacts." ] }

## Root task list format

Each task must follow this exact structure:

{ "id": "TASK-${ID}", "title": "Clear, concise title of the task", "category": "category-name", "specFilePath": ".agent/tasks/TASK-${ID}.json", "passes": false }

**Field Requirements:**

- `id`: Unique identifier for the task, formatted as `TASK-${ID}`
- `title`: A title that gives a high level overview of the task
- `category`: Classification of task type (see categories below)
- `title`: A title that gives a high level overview of the task.
- `specFilePath`: Path to the individual task specification file, formatted as `PROJECT_ROOT/.agent/tasks/TASK-${ID}.json`
- `passes`: Always initialize to `false` - only developers update this after completion

## Individual JSON Task Format

Each task specification file provides comprehensive details for implementation. This is where the real detail lives - the root `tasks.json` is just an index.

{ "id": "TASK-${ID}", "title": "Clear, concise title of the task", "category": "category-name", "description": "In-depth specification including expected behavior, user flow, and output", "acceptanceCriteria": [ "List of specific, verifiable conditions that must be true when task is complete", ], "steps": [ // List of complete steps to complete the task { "step": 1, "description": "Short description of what to do", "details": "Detailed explanation of HOW to do it, including specific code, commands, or techniques", "pass": false }, // ... continue until you cover all steps in the task ], "dependencies": ["TASK-${ID1}", "TASK-${ID2}", ...], // List of task IDs that must be completed before this task "estimatedComplexity": "medium", // One of: "low", "medium", "high", "very high" "technicalNotes": [ "List of technical notes, implementation hints, or technical constraints developers should know", ] }

### Required Fields

| Field                | Type                  | Description                                                                     |
| -------------------- | --------------------- | ------------------------------------------------------------------------------- |
| `id`                 | string                | Unique identifier, formatted as `TASK-${ID}`                                    |
| `title`              | string                | High-level overview of the task (same as in tasks.json)                         |
| `category`           | string                | Classification of task type (see categories below)                              |
| `description`        | string                | In-depth specification including expected behavior, user flow, and output       |
| `acceptanceCriteria` | array of strings      | List of specific, verifiable conditions that must be true when task is complete |
| `steps`              | array of step objects | Sequential implementation steps (see step format below)                         |

### Optional Fields

| Field                 | Type             | Description                                                                      |
| --------------------- | ---------------- | -------------------------------------------------------------------------------- |
| `dependencies`        | array of strings | Task IDs that must be completed before this task (e.g., `["TASK-5", "TASK-12"]`) |
| `estimatedComplexity` | string           | One of: `"low"`, `"medium"`, `"high"`, `"very high"` - helps with planning       |
| `technicalNotes`      | array of strings | Implementation hints, gotchas, or technical constraints developers should know   |

### Step Object Format

Each step in the `steps` array must be an object with these fields:

{ "step": 1, "description": "Short description of what to do", "details": "Detailed explanation of HOW to do it, including specific code, commands, or techniques", "pass": false }

| Field         | Type    | Description                                                                          |
| ------------- | ------- | ------------------------------------------------------------------------------------ |
| `step`        | number  | Sequential step number (1, 2, 3...)                                                  |
| `description` | string  | Brief summary of the step (what to do)                                               |
| `details`     | string  | Comprehensive implementation guidance (how to do it)                                 |
| `pass`        | boolean | Always initialize to `false` - only update to `true` after step is verified complete |

### Writing Good Acceptance Criteria

Acceptance criteria define WHAT must be true when the task is done. They should be:

- **Specific**: "Button shows loading spinner while API call is in progress"
- **Verifiable**: Can be checked with a clear yes/no answer
- **Independent**: Each criterion stands alone
- **Complete**: Together they fully define "done"

**Good acceptance criteria:**

"acceptanceCriteria": [ "Login form validates email format before submission", "Invalid email shows error message 'Please enter a valid email'", "Submit button is disabled while form is invalid", "Successful login redirects to /dashboard", "Failed login shows error message from API response" ]

**Bad acceptance criteria:**

"acceptanceCriteria": [ "Login works correctly", "Form validation is good", "Handles errors properly" ]

### Writing Good Steps

Steps define HOW to implement the task. They should be:

- **Sequential**: Each step builds on the previous
- **Detailed**: Include specific code patterns, function names, file paths
- **Atomic**: Each step is a single, focused piece of work
- **Trackable**: The `pass` field lets developers mark progress

**Good steps:**

"steps": [ { "step": 1, "description": "Create the LoginForm component file", "details": "Create src/components/LoginForm.tsx with a functional component that accepts onSubmit and onError props. Use React Hook Form for form state management.", "pass": false }, { "step": 2, "description": "Add email validation", "details": "Use zod schema to validate email format. Schema should check for: non-empty, valid email regex, max 255 characters. Display validation error below input field.", "pass": false } ]

**Bad steps:**

"steps": [ { "step": 1, "description": "Build the form", "details": "Create the login form", "pass": false } ]

### Using Dependencies

The `dependencies` field helps establish task order and prevents starting work before prerequisites are complete.

"dependencies": ["TASK-5", "TASK-12"]

Use dependencies when:
- A task requires functionality from another task
- A task builds on data structures defined elsewhere
- A task needs UI components created in another task

### Using Technical Notes

Technical notes capture implementation knowledge that isn't obvious from the description or steps.

"technicalNotes": [ "Bash associative arrays require declare -A and Bash 4.0+", "Use $(date +%s) for timestamp tracking", "This function is called from a subshell, so it cannot modify parent variables directly" ]

Include notes about:
- Language/framework version requirements
- Non-obvious gotchas or edge cases
- Performance considerations
- Security implications
- Links to relevant documentation

## Task Categories

Organize tasks into these categories. All examples use the full task spec format with step objects.

> **IMPORTANT**: Examples below show 2 steps for brevity. Real tasks should include ALL steps needed to complete the task - typically 3-10 steps depending on complexity. Never truncate steps to fit a pattern.
> In real generated task lists, `TASK-1` is always reserved for prerequisite verification.

**0. setup** - Project readiness, access, environment variables, MCPs, and service documentation

Use this category for the mandatory first task only unless the PRD requires additional setup tasks.

**1. functional** - Core feature implementation and behavior

{ "id": "TASK-2", "title": "User can create an account with email and password", "category": "functional", "description": "Implement user registration flow allowing new users to create accounts using email and password credentials.", "acceptanceCriteria": [ "Registration form accepts email and password", "Email validation prevents invalid formats", "Password must be at least 8 characters", "Success message displayed after registration", "User can log in with new credentials immediately" ], "steps": [ { "step": 1, "description": "Create registration API endpoint", "details": "Create POST /api/auth/register endpoint that accepts email and password in request body. Validate inputs, hash password with bcrypt, store in users table, return success response.", "pass": false }, { "step": 2, "description": "Build registration form component", "details": "Create RegistrationForm component with email and password fields. Use React Hook Form for validation. Show inline errors for invalid inputs.", "pass": false } ], "dependencies": ["TASK-1"], "estimatedComplexity": "medium" }

**2. ui-ux** - User interface and experience requirements

{ "id": "TASK-3", "title": "Dashboard displays user's recent activity in a card layout", "category": "ui-ux", "description": "Show user's recent activity on the dashboard using a responsive card layout that works on desktop and mobile.", "acceptanceCriteria": [ "Activity cards display on dashboard after login", "Cards show activity type, timestamp, and status", "Layout is responsive - stacks on mobile, grid on desktop", "Empty state shown when no activity exists" ], "steps": [ { "step": 1, "description": "Create ActivityCard component", "details": "Create src/components/ActivityCard.tsx that accepts activity object as prop. Display type icon, formatted timestamp (use date-fns), and status badge with appropriate color.", "pass": false }, { "step": 2, "description": "Implement responsive grid layout", "details": "Use CSS Grid with grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)) for responsive behavior. Add gap of 1rem between cards.", "pass": false } ], "estimatedComplexity": "low" }

**3. data-model** - Database schema, data structures, and relationships

{ "id": "TASK-4", "title": "User profile table with required fields and relationships", "category": "data-model", "description": "Create users table with proper schema, constraints, and relationships to support authentication and profile features.", "acceptanceCriteria": [ "Users table exists with: id, email, name, avatar_url, created_at", "Email field has unique constraint", "Foreign key relationship to auth table exists", "Indexes exist on email and created_at fields" ], "steps": [ { "step": 1, "description": "Create users table migration", "details": "Create migration file with CREATE TABLE users statement. Include columns: id (UUID primary key), email (VARCHAR 255 UNIQUE NOT NULL), name (VARCHAR 255), avatar_url (TEXT), created_at (TIMESTAMP DEFAULT NOW()).", "pass": false }, { "step": 2, "description": "Add indexes for query performance", "details": "Add CREATE INDEX statements for email (for login lookups) and created_at (for sorting). Use btree index type.", "pass": false } ], "dependencies": ["TASK-1"], "technicalNotes": [ "Use UUID v4 for primary keys to avoid sequential ID enumeration" ], "estimatedComplexity": "low" }

**4. api-endpoint** - Backend API endpoints and responses

{ "id": "TASK-5", "title": "POST /api/auth/login endpoint authenticates users", "category": "api-endpoint", "description": "Implement login endpoint that validates credentials and returns JWT token for authenticated sessions.", "acceptanceCriteria": [ "Endpoint accepts POST with email and password", "Valid credentials return 200 with JWT token", "Token contains user ID and email claims", "Invalid credentials return 401 with error message" ], "steps": [ { "step": 1, "description": "Create login route handler", "details": "Create POST /api/auth/login handler. Extract email and password from request body. Query users table for matching email. Compare password hash using bcrypt.compare().", "pass": false }, { "step": 2, "description": "Implement JWT token generation", "details": "Use jsonwebtoken library to sign token with user ID and email as payload. Set expiration to 24h. Use RS256 algorithm with private key from environment variable.", "pass": false } ], "dependencies": ["TASK-4"], "technicalNotes": [ "Never log passwords, even in error cases", "Use constant-time comparison for password to prevent timing attacks" ], "estimatedComplexity": "medium" }

**5. integration** - Third-party service integrations and external dependencies

{ "id": "TASK-6", "title": "Stripe payment processing integration works end-to-end", "category": "integration", "description": "Integrate Stripe for payment processing including checkout flow, webhook handling, and order status updates.", "acceptanceCriteria": [ "Checkout creates Stripe PaymentIntent", "User can complete payment with test card", "Webhook receives payment.succeeded event", "Order status updates to 'paid' on success" ], "steps": [ { "step": 1, "description": "Set up Stripe SDK and API keys", "details": "Install @stripe/stripe-js and stripe packages. Add STRIPE_SECRET_KEY and STRIPE_PUBLISHABLE_KEY to environment. Create stripe client instance in lib/stripe.ts.", "pass": false }, { "step": 2, "description": "Implement webhook handler", "details": "Create POST /api/webhooks/stripe endpoint. Verify webhook signature using stripe.webhooks.constructEvent(). Handle payment_intent.succeeded event to update order status.", "pass": false } ], "dependencies": ["TASK-4", "TASK-5"], "technicalNotes": [ "Always verify webhook signatures to prevent spoofed events", "Test with Stripe CLI: stripe listen --forward-to localhost:3000/api/webhooks/stripe" ], "estimatedComplexity": "high" }

**6. security** - Security features, authentication, authorization

{ "id": "TASK-7", "title": "API endpoints enforce role-based access control", "category": "security", "description": "Implement middleware that enforces role-based access control on protected API endpoints.", "acceptanceCriteria": [ "Admin endpoints return 403 for regular users", "Endpoints without auth token return 401", "JWT signature is validated on every request", "Expired tokens are rejected with 401" ], "steps": [ { "step": 1, "description": "Create auth middleware", "details": "Create middleware/auth.ts that extracts Bearer token from Authorization header, verifies JWT signature, attaches decoded user to request object. Return 401 if token missing or invalid.", "pass": false }, { "step": 2, "description": "Create role-checking middleware", "details": "Create middleware/requireRole.ts that accepts required role as parameter. Check req.user.role against required role, return 403 if insufficient permissions.", "pass": false } ], "dependencies": ["TASK-5"], "technicalNotes": [ "Log failed auth attempts for security monitoring", "Consider rate limiting on auth endpoints to prevent brute force" ], "estimatedComplexity": "medium" }

**7. documentation** - Technical documentation, API docs, user guides

{ "id": "TASK-8", "title": "API documentation covers all endpoints with examples", "category": "documentation", "description": "Create comprehensive API documentation using OpenAPI/Swagger that covers all endpoints with request/response examples.", "acceptanceCriteria": [ "All endpoints documented in OpenAPI spec", "Each endpoint has description, parameters, and responses", "Interactive docs accessible at /api/docs", "Authentication flow clearly documented" ], "steps": [ { "step": 1, "description": "Set up OpenAPI documentation", "details": "Install swagger-jsdoc and swagger-ui-express. Create openapi.config.ts with API info, servers, and security schemes. Add JSDoc comments to route handlers.", "pass": false }, { "step": 2, "description": "Document authentication endpoints", "details": "Add OpenAPI annotations to /api/auth/register and /api/auth/login. Include request body schemas, response schemas for success and error cases, and example values.", "pass": false } ], "estimatedComplexity": "low" }

## Task Generation Guidelines

### Be Comprehensive

Generate tasks that cover the entire PRD. Break down every feature into small, manageable tasks.
Keep the main task list JSON concise and go into detail in the individual task files.

**Example**: For "User Authentication" feature, generate tasks for:
- User table schema
- Registration endpoint
- Login endpoint
- Password reset endpoint
- JWT token generation
- Session management
- Registration UI
- Login UI
- Password reset UI
- Security testing (password hashing, rate limiting)
- Unit tests for all auth functions
- End to end tests for auth flow

### Make Steps Verifiable

Each step must be:
- **Specific**: "Verify email field has unique constraint" not "Check database"
- **Actionable**: Can be executed by a developer
- **Measurable**: Has clear pass/fail criteria
- **Sequential**: Steps build on each other

**Good steps:**

"steps": [ { "step": 1, "description": "Create user via API", "details": "Send POST request to /api/users with valid data: { email: 'test@example.com', password: 'secure123', name: 'Test User' }", "pass": false }, { "step": 2, "description": "Verify API response", "details": "Check response status is 201 and body contains user object with id, email, name (password should NOT be in response)", "pass": false }, { "step": 3, "description": "Confirm database record", "details": "Query users table and verify record exists with matching email. Confirm password field contains bcrypt hash (starts with $2b$), not plaintext.", "pass": false } ]

**Bad steps:**

"steps": [ { "step": 1, "description": "Test the endpoint", "details": "Test it", "pass": false }, { "step": 2, "description": "Make sure it works", "details": "Check everything is correct", "pass": false } ]

**Important:**

Acceptance criteria must be verifiable, not vague. "Works correctly" is bad. "Button shows confirmation dialog before deleting" is good.

For any story with UI changes: Always include "Verify in browser using playwright" as acceptance criteria. This ensures visual verification of frontend work.

**Important:**
End to end tests or unit tests are individual steps (verification criteria) in a task, but *CANNOT* be tasks themselves.

### Initialize All Tasks to `"passes": false`

**CRITICAL**: Never mark tasks as complete during generation. The `passes` field should ALWAYS be `false` initially.

> It is unacceptable to remove or edit items in the task list because this could lead to missing or buggy functionality

Only developers should update `passes: true` after verifying all steps are complete.

## Output Format

Save the complete task list as `PROJECT_ROOT/.agent/tasks.json`:

[ { "id": "TASK-1", "title": "Verify project prerequisites and access", "category": "setup", "specFilePath": ".agent/tasks/TASK-1.json", "passes": false }, { "id": "TASK-2", "title": "User table with authentication fields", "category": "data-model", "specFilePath": ".agent/tasks/TASK-2.json", "passes": false }, { "id": "TASK-3", "title": "POST /api/auth/register creates new user account", "category": "api-endpoint", "specFilePath": ".agent/tasks/TASK-3.json", "passes": false } // ... continue until you cover all features in the PRD ]

**Important:**
When outputting tasks, create them sequentially. Output them one by one so the user can review each.
Each task output must include the `id` field first, exactly in the form `"id": "TASK-${ID}"`. `TASK-1` is reserved for prerequisite verification.
If you output multiple tasks in one review iteration, every task object must include its own `id` field.
*DO NOT* output in parallel.
*DO NOT* use background agents.
*DO NOT* use subagents.

## After Generation

Present the tasks to the user:

"I've generated [NUMBER] implementation tasks based on your PRD, organized into [NUMBER] categories. These tasks provide a complete checklist for building and verifying every feature.

The tasks are saved in `PROJECT_ROOT/.agent/tasks.json`. Developers should:
1. Work through tasks in order (setup → data-model → api-endpoint → ui-ux, etc.)
2. Complete all verification steps for each task
3. Only mark `passes: true` after all steps verified
4. Never remove or skip tasks

Would you like me to adjust the task breakdown or add more detail? Otherwise, I can save the tasks and move on to writing the overall description of the project and finalizing the process."

## Example: Complete Task Generation

For a simple "Todo List App" PRD with features: user auth, create/read/update/delete todos, mark complete, the task list should include approximately 40-60 tasks covering:

- Prerequisite verification and access check (1 task, always first)
- User table schema (1 task)
- Todo table schema (1 task)
- Auth endpoints: register, login, logout (3 tasks)
- Todo CRUD endpoints (4 tasks)
- Auth UI: registration, login pages (2 tasks)
- Todo UI: list view, create form, edit form (3 tasks)
- User can only access their own todos (1 security task)
- OAuth integration with Google (2 integration tasks)
- API documentation (1 documentation task)

Note: Unit tests and E2E tests are verification steps within feature tasks, not separate tasks.

Generate similar comprehensive breakdowns for any PRD.

PRD Creation Through Structured Questioning

Help beginner-level developers transform software ideas into comprehensive PRD.md files through structured questioning.

Conversation Flow

1. Introduce yourself briefly and explain you'll ask clarifying questions before creating a PRD 2. Ask questions one at a time conversationally 3. Focus 70% on understanding the concept, 30% on educating about options 4. Keep tone friendly and supportive, use plain language 5. Track assumptions throughout - they'll go in the PRD

CRITICAL: Interview the user relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide the user's recommended answer. Ask the questions one at a time. If a question can be answered by exploring the codebase, explore the codebase instead.

Topics to Cover

Gather information on these aspects:

1. Core features and functionality 2. Target audience 3. Platform (web, mobile, desktop) 4. User flows (how users move through the app) 5. UI/UX concepts 6. Data storage and management 7. Authentication (if relevant) and security 8. Third-party integrations (if relevant) 9. [optional] Wireframes or diagrams 10. [optional] Competitive landscape 11. Execution prerequisites: database access, service access, MCPs, documentation, environment variables, and login/test users 12. Dependencies

Questioning Patterns

• Start broad: "Tell me about your app idea at a high level"
• Core features: "What are the 3-5 core features that make this valuable?"
• Priorities: "Which features are must-haves for the initial version?"
• User journeys: "Walk me through what a user does from opening the app to completing their main goal"
• Competition: "What similar products exist? What should yours do differently?"
• Assumptions: "What are you assuming about your users, technology, or market?"
• Wireframes: "Can you explain the flow and what happens when users interact with each screen?"
• Reflective: "So if I understand correctly, you're building [summary]. Is that accurate?"

Technology Discussions

• Provide 3-4 options with pros/cons
• Give your best recommendation with brief reasoning
• Stay conceptual, not deeply technical
• Proactively suggest technologies the idea requires
• If the user provides technology preferences, use them to guide your recommendations
• Use AskUserQuestion tool to ask about a11y

NB: only include a11y tasks if the user request it. Keep in mind what they build might not have a UI or be a prototype.

• Use AskUserQuestion tool to ask about performance considerations

NB: only include performance tasks if the user request it. Keep in mind what they build might not have a UI or be a prototype.

Example: "For this app, you could use React Native (cross-platform, faster development) or native development (better performance, device integration). Given your need for camera integration and offline support, I'd recommend native development."

PRD Creation Workflow

CRITICAL: Don't create the PRD until you have all necessary information, including needed libraries, frameworks, 3rd party integrations, etc. Use AskUserQuestion tool multiple times to clarify specs, technology choices, and requirements.

Copy and track progress through these steps:

PRD Progress:
- [ ] Gather all required information via questioning
- [ ] Verify project prerequisites and create `.env.local` placeholders
- [ ] Create executive summary for user validation
- [ ] Get user confirmation to proceed
- [ ] Research competitive landscape (if not done)
- [ ] Generate comprehensive PRD
- [ ] Present and gather feedback
- [ ] Iterate based on feedback

Step 1: Gather Information and Verify Prerequisites

Use AskUserQuestion tool repeatedly to clarify:

• Core features that are unclear
• Technology options and user preferences
• Priorities between conflicting requirements
• Any assumptions that could significantly impact the PRD

Ask related questions per tool call for efficiency. Provide 3-4 clear options per question with trade-off descriptions. Mark recommended options with "(Recommended)".

Mandatory Prerequisite Gate

Before finalizing Step 1 or moving to executive summary validation, verify what the implementation needs to run and be tested.

Explore the repository first when possible. Look for .env, .env.example, .env.local, config files, package dependencies, database clients, migrations/schema files, SDK imports, auth routes, README setup instructions, and existing test credentials or seed data. If a question can be answered by exploring the codebase, explore the codebase instead of asking the user.

Collect and document:

• Database access requirements and whether the agent/user can verify connectivity
• Required MCP servers/tools and whether they are installed and authenticated
• Required third-party service accounts, API dashboards, CLIs, SDKs, or docs
• Required environment variable names, where they are written, and what each variable is used for
• Login/test user requirements, including role, permissions, and how to create or request the user
• Any local setup commands needed before implementation or verification

Create or update PROJECT_ROOT/.env.local during this step with placeholder values for every required environment variable name discovered. Never write real secret values, passwords, API keys, tokens, or connection strings. If .env.local already exists, preserve existing values and append missing variable names with placeholders only. Make it clear to the user that they must add real values manually.

In the PRD, record environment variable names and the target file path only. Do not include secret values or real credentials. Example:

- `STRIPE_SECRET_KEY`: required for Stripe server API calls; written to `PROJECT_ROOT/.env.local`; value must be filled manually by the user.

If any prerequisite cannot be verified, ask the user case-by-case whether to block PRD finalization until it is resolved or proceed with an explicit prerequisite gap. Record the decision in the PRD.

Step 2: Executive Summary Validation

Before writing the full PRD: 1. Summarize in 2-3 paragraphs: problem solved, target users, core value proposition, key features, key user flows 2. List main assumptions you're making 3. Ask: "Does this accurately capture your vision? Should I proceed with the full PRD?" 4. Only continue after confirmation

Step 3: Competitive Research

If this is a commercial app with a potential revenue model, you should research the competitive landscape to identify differentiators and opportunities.

Use WebSearch to:

• Find similar products: "[app category] apps 2026", "best [problem space] tools"
• Identify differentiators
• Use the findings to further refine the PRD
• For each identified differentiator, use the AskUserQuestion tool to clarify if it should be included in the PRD

Step 4: Generate PRD

Create PRD containing all identified requirements and use an ID to track each requirement, formatted as TASK-${ID}. Reserve TASK-1 for prerequisite verification in the generated implementation tasks. Start feature and implementation requirement IDs at TASK-2.

Include the following sections:

• App overview, objectives and success criteria
• Short summary of target audience
• (for commercial apps): Competitive landscape and differentiation
• Core features and functionality
• Key user flows and journeys
• Technical stack recommendations
• Prerequisites and access
• Conceptual data model
• UI design principles (include wireframe analysis if provided)
• Security considerations
• Development phases/milestones
• Assumptions and dependencies

The Prerequisites and Access section must include:

• Database access status
• Required MCPs and authentication status
• Required service documentation links
• Required environment variable names and the target file path where placeholders were written
• Login/test user requirements without passwords or secret values
• Open prerequisite gaps and the user's proceed/block decision for each gap

Save as: PROJECT_ROOT/.agent/prd/PRD.md

Step 5: Iterate

Ask specific questions about sections rather than general feedback. Use Sequential Thinking for systematic feedback processing. Present revised version with change explanations.

Developer Handoff Guidelines

Optimize for handoff to engineers (human or AI):

• Include implementation details without prescriptive code
• Define clear acceptance criteria per feature
• Use terminology mappable to code components
• Structure data models with explicit field names, types, relationships
• Specify technical constraints and API integration points
• Organize features in logical sprint groupings
• Include pseudocode for complex features
• Link to relevant technology documentation

Specification Examples

Feature Specification:

User Authentication Feature:
- Support email/password and OAuth 2.0 (Google, Apple) login methods
- Implement JWT token-based session management
- Required user profile fields: email (string, unique), name (string), avatar (image URL)
- Acceptance criteria: Users can create accounts, log in via both methods, recover passwords, and maintain persistent sessions across app restarts

User Flow:

Content Creation Flow:
1. User clicks 'Create' button on dashboard
2. User selects content type (text post, image, video)
3. User fills in content details (title, description, tags)
4. User previews content before publishing
5. User clicks 'Publish' → Content appears in their profile feed
6. User can share via native share sheet (iOS/Android) or copy link (Web)
- Error states: Handle upload failures, size limits exceeded, network timeouts

Wireframe Analysis

When users provide wireframes or mockups:

1. Use Read tool to view image files 2. For each screen, identify:

• UI components (buttons, forms, navigation)
• User interactions (taps, swipes, submissions)
• State changes on interaction
• Navigation flow between screens
• Data sources

3. Ask clarifying questions via AskUserQuestion tool:

• "What happens when the user clicks [element]?"
• "Where does [data/content] come from?"
• "What error states should we handle?"

4. Include insights in PRD's "UI Design Principles" section 5. Map to user flows in "Key User Flows" section

After PRD Completion

Once the PRD is complete and approved, inform the user: "Your PRD is complete and saved. Would you like me to proceed to the next step and generate implementation tasks for developers? See JSON.md."

CRITICAL: Make the plan extremely concise. Sacrifice grammar for the sake of concision.

---

Checklist

Before saving the PRD:

• [ ] Asked clarifying questions with lettered options
• [ ] Incorporated user's answers
• [ ] Verified prerequisites before executive summary validation
• [ ] Created or updated PROJECT_ROOT/.env.local with placeholder values only
• [ ] Documented required environment variable names without secret values
• [ ] User stories are small and specific
• [ ] Functional requirements are numbered and unambiguous
• [ ] Non-goals section defines clear boundaries
• [ ] Saved to PROJECT_ROOT/.agent/prd/PRD.md