// Create or refine SPEC.md technical specifications for Ralph AI coding agent. Use when asked to "create spec", "write specification", "define requirements", "plan architecture", or when setting up a new project.
| name | create-spec |
| description | Create or refine SPEC.md technical specifications for Ralph AI coding agent. Use when asked to "create spec", "write specification", "define requirements", "plan architecture", or when setting up a new project. |
| license | MIT |
| metadata | {"author":"chenxin-yan","version":"0.2.0"} |
Create or refine SPEC.md for Ralph — an AI coding agent that reads SPEC.md at the start of every iteration to understand what it's building.
prd.json.prd.json for phased work.# Project Name
> One-line description of the project.
## Overview
[2-3 paragraphs: what you're building, the problem it solves, and who it's for]
## Scope
### Included
- [High-level capability 1]
- [High-level capability 2]
### Excluded
- [What this project will NOT do]
## Technical Stack
- **Language**: [e.g., TypeScript 5.x with strict mode]
- **Framework**: [e.g., Next.js 14 with App Router]
- **Database**: [e.g., PostgreSQL 15 with Prisma ORM]
- **Authentication**: [e.g., NextAuth.js with JWT]
- **Testing**: [e.g., Vitest + Playwright]
- **Other**: [Any other key technologies]
## Architecture
[High-level patterns, system structure, how major components communicate]
## Constraints
- [e.g., All code must pass TypeScript strict mode]
- [e.g., API responses must stay under 200ms p95]
- [e.g., Node.js 18+ required]
## References
- [Links to design mockups, external API docs, or prior art]
Clearly state what the project is, the problem it solves, and the target users. Vagueness here cascades everywhere.
GOOD: "A REST API for managing inventory in small retail stores,
reducing manual stock counting by 80%."
BAD: "A cool app for managing stuff."
List what the project does and doesn't do. Think capabilities, not user stories or acceptance criteria — those belong in prd.json.
GOOD (spec):
- User authentication and role-based access control
- Real-time inventory tracking across multiple locations
BAD (belongs in prd.json):
- User can reset password via email link with 24h expiry token
- POST /api/auth/register returns 201 with JWT
Always include an Excluded section. Without boundaries, the agent will over-build.
Every major technology choice must be explicit. If the agent has to guess, it will guess wrong.
GOOD:
- **Language**: TypeScript 5.x with strict mode
- **Framework**: Next.js 14 with App Router
- **Database**: PostgreSQL 15 with Prisma ORM
BAD:
- Some backend framework
- A database
Include: language, framework, database + access method, infrastructure, key libraries.
Describe the high-level patterns and how components interact. Do NOT document directory structure or file-level organization — the codebase shows that.
GOOD: "Monolithic Express app with layered architecture:
routes → controllers → services → repositories.
All business logic lives in the service layer."
BAD: "src/routes/ contains route files, src/controllers/
contains controller files, src/services/ ..."
Optional for simple projects.
Capture non-functional requirements that guide the agent's decisions. Keep them directional — exact thresholds and metrics belong in prd.json task notes.
Categories: performance, security, compatibility, code quality.
Links to design mockups, API docs, similar projects. Optional — omit if none exist.
| User Intent | Workflow |
|---|---|
| "Create spec", "define requirements", "plan the project" | Create |
| "Review spec", "improve spec", "update spec" | Refine |
| Unclear | Ask the user |
SPEC.md.SPEC.md and evaluate against section rules.prd.json.SPEC.md.prd.json