Skip to content

sauryadas/prd-spec-assistant

BranchesTags

Repository files navigation

PRD & Spec Assistant

PRD & Spec Assistant is a local-first planning workspace for turning an early product idea into two connected artifacts:

  • a product requirements document (PRD)
  • a technical specification (Spec)

The app is designed for a small team or solo builder who wants a practical, startup-ready planning loop instead of a heavyweight product operations system. It helps a user capture context, generate a first draft, tighten weak sections, and export the result as Markdown.

What This Agent Is

This project is a full-stack Next.js application that acts like a product and engineering planning copilot.

At a high level, the assistant helps with:

  • turning a rough idea into a structured PRD
  • deriving a technical spec from the product context and PRD
  • refining a single weak section without rewriting the whole document
  • preserving planning history through saved chat and document versions
  • exporting the current PRD or spec into Markdown for sharing or repo use

This is not a generic chatbot. The assistant is constrained around a specific workflow:

  1. capture product context
  2. generate planning artifacts
  3. refine sections
  4. export usable docs

Product Goals

The current version is intentionally optimized for:

  • single-user, local/dev usage
  • startup-speed planning rather than enterprise governance
  • editable, practical outputs over rigid templates
  • structured documents that can still be refined conversationally

The app does not currently aim to solve:

  • authentication or multi-user collaboration
  • PDF export
  • approval workflows or formal document review gates
  • project management orchestration such as ticket generation or delivery tracking

Core User Workflow

The primary workflow in the app looks like this:

  1. Create a new project from the home page.
  2. Fill in the product context and guided intake fields.
  3. Save the project context.
  4. Generate the PRD.
  5. Generate the technical spec.
  6. Edit sections manually or refine a single section with AI.
  7. Use chat to ask what is missing or what should be improved next.
  8. Export the PRD or spec as Markdown.

The assistant is designed so that structured input and chat work together:

  • the intake form gives the model stable planning context
  • the documents hold the current draft state
  • the chat history gives extra qualitative direction

What the App Generates

PRD Sections

The PRD is generated with these sections:

  • Overview
  • Problem
  • Goals and Non-Goals
  • Target Users
  • User Stories
  • Requirements
  • Success Metrics
  • Risks and Open Questions

Technical Spec Sections

The technical spec is generated with these sections:

  • System Overview
  • Architecture
  • Data Model
  • API / Server Behavior
  • Client Behavior
  • Edge Cases and Failure Modes
  • Observability
  • Rollout Notes

How the Assistant Works

The assistant operates through three main AI behaviors.

1. Document generation

The app can generate:

  • a PRD from project context, intake fields, and recent chat
  • a technical spec from the same context plus the latest PRD

The prompt builders live in lib/prompts.ts, and the orchestration logic lives in lib/generation.ts.

The generation pipeline expects a structured JSON response so the output can be mapped back onto known sections.

2. Section-level refinement

Instead of forcing the user to regenerate an entire document, the assistant can refine one section at a time.

That flow:

  • finds the current section
  • sends the project context and section content to the model
  • receives updated Markdown for only that section
  • merges the section back into the document without disturbing the rest

This behavior is implemented in lib/documents.ts and lib/generation.ts.

3. Planning chat

The chat panel is not a separate assistant with its own memory system. It uses:

  • current project metadata
  • guided intake fields
  • the latest PRD
  • the latest spec
  • saved chat history

The reply helps the user understand what is weak, missing, or worth refining next. That server route is implemented in app/api/projects/[id]/chat/route.ts.

Model Providers

The app supports both hosted OpenAI and local OpenAI-compatible model servers.

Hosted OpenAI

Use:

OPENAI_API_KEY="your_key"
OPENAI_BASE_URL=""
OPENAI_MODEL="gpt-4.1-mini"

Local model via Ollama

You can run a local Llama-family model through Ollama and point the app at its OpenAI-compatible endpoint.

Example:

ollama pull llama3.1

Then set:

OPENAI_API_KEY="local"
OPENAI_BASE_URL="http://localhost:11434/v1"
OPENAI_MODEL="llama3.1"

The app uses chat completions for provider compatibility, which works better with local OpenAI-compatible servers than the Responses API path.

Fallback Behavior Without A Working Model Provider

The app is intentionally usable even if no working model provider is configured.

If the configured provider is missing or fails, the assistant falls back to deterministic local content generation. This means:

  • the UI still works
  • documents are still generated
  • section refinement still works
  • chat still returns helpful guidance

The fallback content is template-driven and less intelligent than model output, but it keeps the app functional for local development and demos.

The provider integration and fail-soft behavior live in lib/openai.ts.

Architecture Overview

Frontend

The frontend uses Next.js App Router and React.

Main UI surfaces:

The workspace is organized into three panes:

  • left: project context and intake
  • center: PRD/spec editing
  • right: assistant chat and version history

Backend

The backend uses Next.js route handlers.

Implemented API routes:

Persistence

The app uses Prisma with SQLite.

Schema file:

Prisma config:

Prisma client setup:

Database helper/orchestration code:

Data Model

The data model is intentionally simple and project-centric.

Project

Stores top-level workspace metadata such as:

  • title
  • product idea
  • audience
  • goals
  • constraints
  • status

ProjectInput

Stores structured intake used to generate better documents:

  • problem
  • users
  • success metrics
  • requirements
  • non-goals
  • rollout notes

Document

Stores the current saved PRD or technical spec:

  • type
  • title
  • summary
  • full Markdown content

DocumentSection

Stores normalized sections for section-level editing and refinement:

  • stable section key
  • heading
  • content
  • order

ChatMessage

Stores project-scoped conversation history.

DocumentVersion

Stores snapshots of saved/generated documents over time for lightweight version history.

Project Structure

app/
  api/projects/...
  globals.css
  layout.tsx
  page.tsx
  projects/[id]/page.tsx
components/
  create-project-form.tsx
  project-workspace.tsx
lib/
  documents.ts
  generation.ts
  openai.ts
  prisma.ts
  project-data.ts
  prompts.ts
  types.ts
  utils.ts
prisma/
  migrations/
  schema.prisma
tests/
  documents.test.ts
  prompts.test.ts

Setup

Requirements

  • Node.js 20+ recommended
  • npm

Installation

npm install

Environment Variables

Create .env.local:

cp .env.example .env.local

Default values:

DATABASE_URL="file:./prisma/dev.db"
OPENAI_API_KEY=""
OPENAI_BASE_URL=""
OPENAI_MODEL="gpt-4.1-mini"

Database Setup

Run the Prisma migration:

npx prisma migrate dev --name init

If you need to regenerate the Prisma client manually:

npx prisma generate

Start the App

npm run dev

Then open http://localhost:3000.

Development Notes

Prisma 7

This repo is configured for Prisma 7:

  • the schema does not include url in the datasource block
  • prisma.config.ts provides the datasource URL
  • the runtime Prisma client uses the SQLite adapter

Postinstall behavior

The project includes a postinstall script that runs prisma generate after dependency installation.

Next.js cache issues

If the dev server gets into a bad state, clear the build output:

rm -rf .next
npm run dev

Full local reset

If install/build artifacts are corrupted, do a clean reset:

rm -rf .next node_modules package-lock.json
npm install
npx prisma generate
npx prisma migrate dev --name init
npm run dev

Testing

The repo currently includes focused unit tests for:

  • document section serialization/parsing
  • section merge behavior during refinement
  • prompt construction
  • section normalization

Run tests with:

npm test

Test files:

Current Limitations

This v1 implementation has a few intentional boundaries:

  • single-user only
  • no authentication
  • no team collaboration
  • no PDF export
  • no rich text editor beyond textarea-based Markdown editing
  • chat suggests next edits but does not automatically apply them
  • no formal approval or review workflow

Future Directions

Good next steps for the product could include:

  • team accounts and shared workspaces
  • richer Markdown preview or split edit/preview mode
  • chat actions that can apply suggested edits directly
  • document diffing between versions
  • stronger quality critique and contradiction detection
  • export to PDF or external tools
  • task breakdown generation from the spec

Summary

PRD & Spec Assistant is a practical planning tool for going from idea to execution-ready documentation. It combines structured intake, document generation, section-level refinement, saved history, and Markdown export in one local-first workspace.

The current implementation is intentionally compact, but the core architecture is already set up to support a stronger multi-step planning agent over time.

About

prd-spec-assistant

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages