Writing Specs with spec-kit

# Generate a PRD with AI assistance
specc create prd --name "notification-system" \
  --ai \
  --context "Real-time notification system supporting
  email, SMS, and push notifications with user
  preference management and rate limiting"

---
title: Notification Service Technical Spec
type: tech-spec
status: review
related_prd: notification-system
---

# Notification Service

## Architecture
The notification service uses an event-driven
architecture with a message queue (RabbitMQ) for
reliable delivery across channels.

## Components
### NotificationRouter
Routes notifications to appropriate channel
handlers based on user preferences and message type.

### ChannelHandlers
- **EmailHandler**: SMTP integration via SendGrid
- **SMSHandler**: Twilio API integration
- **PushHandler**: Firebase Cloud Messaging

## Data Model
```sql
CREATE TABLE notifications (
  id UUID PRIMARY KEY,
  user_id UUID NOT NULL,
  channel VARCHAR(20) NOT NULL,
  status VARCHAR(20) DEFAULT 'pending',
  payload JSONB NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);
```

## API Endpoints
- POST /api/notifications - Send notification
- GET  /api/notifications/:id - Get status
- PUT  /api/preferences - Update user preferences

# Generate API spec from description
specc create api-spec --name "notifications-api" \
  --ai \
  --context "REST API for sending and managing
  notifications across email, SMS, and push channels"

# Generate from existing route files
specc create api-spec --name "notifications-api" \
  --scan src/routes/notifications.ts

---
title: Use RabbitMQ for Message Queue
type: adr
status: accepted
date: 2026-03-14
decision_makers:
  - jane.doe
  - bob.smith
---

# ADR-003: Use RabbitMQ for Message Queue

## Context
We need a reliable message queue for the
notification service to handle async delivery.

## Decision
We will use RabbitMQ over Kafka and SQS.

## Rationale
- Supports complex routing patterns we need
- Team has existing expertise
- Lower operational overhead than Kafka
- Better for our message volume (10K/min)

## Consequences
- Need to manage RabbitMQ cluster
- Must implement dead letter queues
- Team training on RabbitMQ management

# Generate user stories from a PRD
specc generate stories --from prds/notification-system.md

# Output:
Generated 8 user stories:
1. As a user, I want to receive email notifications
   so that I stay informed about important updates.
2. As a user, I want to manage my notification
   preferences so that I only receive relevant alerts.
3. As an admin, I want to set rate limits so that
   users are not overwhelmed with notifications.
...

# Generate acceptance criteria for a user story
specc generate criteria \
  --story "As a user, I want to receive push
  notifications so that I get real-time alerts"

# Output:
Acceptance Criteria:
- [ ] Push notification appears within 5 seconds
- [ ] Notification includes title and body text
- [ ] Tapping notification opens the relevant screen
- [ ] Notifications respect device Do Not Disturb
- [ ] Failed deliveries are retried up to 3 times
- [ ] User can dismiss notifications

# Generate data model documentation
specc create data-model --name "notification-schema" \
  --ai \
  --context "Notification system with users,
  preferences, channels, and delivery logs"

# Scan existing database schema
specc create data-model --name "notification-schema" \
  --scan prisma/schema.prisma