learning_ai_common_plat/AI.dev/PROMPTS/prd-to-implementation.md

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

# <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