SethGammon/prd

/prd — Product Requirements Document Generator

When to Use

Don't use when: architecture is already defined and you need implementation (use /architect then /archon); adding a small feature to an existing app (use /marshal directly).

• User describes an app or feature to build (greenfield or feature mode)
• Before any Archon campaign for a new project or feature

Mode Detection

Before starting, determine the mode:

Greenfield mode: No existing source files, or user explicitly says "new app" / "from scratch." Produces a full PRD as described below.

Feature mode: The project already has source files (check for src/, app/, lib/, package.json with dependencies, or similar). The user describes a feature to add, not a whole app ("add auth", "add a dashboard", "add payment processing").

In feature mode:

• Read the existing file tree and package.json/equivalent before asking questions
• The existing stack is a given — don't recommend alternatives
• "Architecture" section describes integration points with existing code, not standalone shape
• End conditions MUST include regression checks: "existing tests still pass", "typecheck has no new errors"
• "Out of Scope" is relative to the feature, not the whole app
• Technical Decisions only covers decisions the feature introduces (new dependencies, new patterns)

The PRD template below works for both modes. Feature mode just scopes it tighter.

Protocol

Step 1: UNDERSTAND

Determine mode (greenfield vs feature). Identify core functionality, target user, and success criteria (greenfield) or integration points and existing stack (feature). Ask up to 3 questions — only those that would change the architecture. Do not ask about tech stack in greenfield mode; in feature mode, the stack is already decided.

Step 2: RESEARCH (Optional)

If the concept has well-known implementations, run /research to identify 2-3 reference apps and common expected features. Skip for simple concepts (landing page, personal tool, CRUD).

Step 3: DEFINE

Produce a structured PRD. Write to .planning/prd-{slug}.md:

# PRD: {App Name or Feature Name}

> Description: {One sentence}
> Author: {user}
> Date: {ISO date}
> Status: draft
> Mode: {greenfield | feature}

## Problem
{What problem does this solve? Why does the user want it?}

## Users
{Who uses this? One or two user types max.}

## Core Features
{Numbered list. Maximum 5 for v1. Each feature is one sentence.}
1. {Feature}: {what it does}
2. ...

## Out of Scope (v1)
{Things the user might expect but should NOT be built yet.
Being explicit about what's out prevents scope creep.}

## Technical Decisions
- **Frontend**: {recommendation with reasoning}
- **Backend**: {recommendation with reasoning, or "none" for static apps}
- **Database**: {recommendation with reasoning, or "none"}
- **Auth**: {recommendation, or "none" if no user accounts}
- **Deployment**: {recommendation}

{In feature mode, only list decisions the feature introduces.
Existing stack decisions are inherited, not re-evaluated.}

## Architecture
{High-level description. 3-5 sentences max. How the pieces connect.
NOT a file tree. NOT implementation details. Just the shape.}

{In feature mode: describe integration points with existing code.
"The new auth middleware hooks into the existing Express router at
src/routes/index.ts. User model extends the existing Prisma schema."}

## Integration Points (feature mode only)
{Skip this section in greenfield mode.}
- **Existing files modified**: {list of files the feature will touch}
- **New files created**: {list of new files}
- **Dependencies added**: {new packages, if any}
- **Patterns followed**: {existing patterns in the codebase this feature should match}

## End Conditions (Definition of Done)
{Machine-verifiable conditions that mean the feature/app is complete.}
- [ ] {condition 1: e.g., "Landing page renders at localhost:3000"}
- [ ] {condition 2: e.g., "User can create account and log in"}
- [ ] {condition 3: e.g., "Core feature X works end-to-end"}

{In feature mode, ALWAYS include these regression conditions:}
- [ ] Existing tests pass with 0 new failures
- [ ] Typecheck passes with 0 new errors

## Open Questions
{Anything the PRD author couldn't decide. These become questions
for the user before the campaign starts.}

Step 4: REVIEW

Present: core features, tech stack decisions, out of scope, end conditions. Ask if it matches. On approval: PRD is ready for Archon. On changes: update and re-present changed sections only.

Contextual Gates

Disclosure: "Generating PRD for [description]. Creates .planning/prd-{name}.md." Reversibility: green — creates .planning/prd-{slug}.md only; undo by deleting the file. Trust gates:

• Any: full PRD generation, clarifying questions, review cycle.

Quality Gates

• Every Core Feature is one sentence
• Every technical decision has a reasoning ("because")
• End conditions are machine-verifiable
• Out of Scope has at least 2 items
• No more than 5 core features for v1

Fringe Cases

Vague description: Ask up to 3 clarifying questions. Never produce a PRD with placeholder end conditions.

Feature mode but no existing code: Confirm with the user — switch to greenfield if confirmed.

User says "skip the PRD": Even a minimal PRD is needed. Offer a 1-page express PRD (Tier 4 style).

If .planning/ does not exist: Create it before writing. If not possible, present inline and suggest /do setup.

Exit Protocol

---HANDOFF---
- PRD: {app name}
- Document: .planning/prd-{slug}.md
- Status: {approved | needs-revision}
- Next: Run `/do build {app name}` or `/archon` with the PRD as direction
- Reversibility: green — delete .planning/prd-{slug}.md to undo
---

Stack Selection Principles

Make opinionated recommendations with reasoning. Defaults: Next.js + Tailwind + shadcn/ui for web; Node/Express for JS backends, FastAPI for Python; SQLite for simple, PostgreSQL for multi-user; simplest auth for the stack. Always explain why.

Deployment defaults: static → Vercel/Netlify; full-stack with DB → Railway; API only → Railway or Fly.io; not deploying yet → local only. See .planning/_templates/deploy/ for platform details.