---
name: prd-to-implementation
description: 'Convert a PRD into a concrete, phased implementation plan with file-level detail and dependency ordering.'
argument-hint: 'Path to PRD file or inline feature description, e.g. "docs/PRD.md", "add social fasting feature to NomGap"'
agent: agent
---

# PRD → Implementation Plan Prompt

Transform a Product Requirements Document into a detailed, phased implementation plan that an AI agent or developer can execute directly.

## Context — ByteLyst Ecosystem

You are planning implementation within the ByteLyst ecosystem (`D:\BYTELYST\CODE\`).

**Architecture awareness:**
- Products have: `backend/` (Fastify 5), `web/` (Next.js or Vite+React), `mobile/` (Expo), `shared/`
- Backend modules follow: `types.ts` → `repository.ts` → `routes.ts`
- All data lives in Azure Cosmos DB with `productId` multi-tenancy
- Shared packages are `@bytelyst/*` from `learning_ai_common_plat/packages/`
- Platform service (port 4003) handles: auth, flags, telemetry, billing, notifications
- Design tokens provide all UI colors via CSS custom properties

## Process

### Step 1: PRD Analysis

Read the PRD and extract:

1. **Core features** — what must be built
2. **User flows** — how users interact
3. **Data model** — what gets stored
4. **API surface** — endpoints needed
5. **UI screens** — pages/components needed
6. **Constraints** — performance, security, compatibility
7. **Out of scope** — what to explicitly defer

### Step 2: Dependency Mapping

Determine what already exists:
- Which `@bytelyst/*` packages are needed?
- Does any sibling product have a similar pattern to reference?
- Are new Cosmos containers needed?
- Are new platform-service modules needed?
- Are design token additions needed?

### Step 3: Phase Decomposition

Break into phases following this priority order:

1. **P0 — Foundation** (always first)
   - Data model / Cosmos containers
   - Backend types + Zod schemas
   - Repository layer with basic CRUD
   - Routes with auth + validation
   - Initial tests

2. **P1 — Core Features**
   - Primary business logic
   - Main API endpoints
   - Web/mobile screens for primary flows
   - Integration tests

3. **P2 — Secondary Features**
   - Less critical endpoints
   - Settings, admin views
   - Edge case handling
   - Additional tests

4. **P3 — Polish**
   - Error handling refinement
   - Loading states, empty states
   - Accessibility
   - Performance optimization
   - E2E tests

### Step 4: Generate Plan Document

Output a `docs/IMPLEMENTATION_PLAN.md` with:

```markdown
# <Feature Name> Implementation Plan

> Generated from: <PRD path>
> Product: <product name> (<productId>)
> Estimated phases: N

## Data Model

| Container | Partition Key | Fields | Purpose |
|-----------|--------------|--------|---------|

## API Surface

| Method | Path | Auth | Description |
|--------|------|------|-------------|

## Phase Breakdown

### Phase 0: Foundation
- [ ] `backend/src/modules/<name>/types.ts` — Zod schemas
- [ ] `backend/src/modules/<name>/repository.ts` — Cosmos CRUD
- [ ] `backend/src/modules/<name>/routes.ts` — REST endpoints
- [ ] `backend/src/modules/<name>/<name>.test.ts` — Unit tests
- [ ] Register routes in `backend/src/server.ts`
**Validation:** `pnpm --filter backend test && pnpm --filter backend typecheck`
**Commit:** `feat(<module>): add <name> foundation (types, repo, routes, tests)`

### Phase 1: Core Features
...
```

## Guardrails

- **Every phase must be independently deployable** — no half-built features
- **Every phase includes tests** — minimum: unit tests for repository + routes
- **Backend first, frontend second** — API must exist before UI consumes it
- **Use existing patterns** — reference sibling product repos, don't reinvent
- **Include validation commands** — exact `pnpm` commands for each phase
- **Include commit messages** — pre-written conventional commits