Kilo Code: Mastering Spec-Driven Development (SDD)

Developer: "Add user authentication"
AI: *generates some code*
Developer: "Hmm, not quite. Also add password reset."
AI: *generates more code*
Developer: "Wait, now the login is broken. Fix it."
AI: *patches things*
Developer: "Oh, and we need OAuth too..."
AI: *adds OAuth, breaks something else*

Result: Spaghetti code, inconsistent patterns, hidden bugs

Traditional AI Coding (Vibe):
Prompt → Code → Hope → Debug → More Code → ???

Spec-Driven Development (OpenSpec):
Requirements → Spec → Proposal → Tasks → Code → Verify → Archive → Done

┌─────────────────────────────────────────────────────────────┐
│              SPEC-DRIVEN WORKFLOW (OpenSpec)                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. INITIALIZATION                                          │
│     openspec init                                           │
│     └─→ Creates openspec/ directory structure               │
│                                                             │
│  2. PROPOSAL                                                │
│     /openspec:proposal or /openspec-proposal.md            │
│     └─→ Creates proposal.md, design.md, tasks.md            │
│                                                             │
│  3. APPLY                                                   │
│     /openspec:apply <change-id>                             │
│     └─→ AI implements tasks from tasks.md                   │
│                                                             │
│  4. ARCHIVE                                                 │
│     /openspec:archive <change-id> --yes                     │
│     └─→ Merges spec deltas, cleans workspace                │
│                                                             │
└─────────────────────────────────────────────────────────────┘

project-root/
├── openspec/
│   ├── AGENTS.md              # AI agent instructions
│   ├── project.md             # Project context & tech stack
│   ├── specs/                 # Source of truth (current specs)
│   │   ├── auth-login/
│   │   │   └── spec.md
│   │   └── payment/
│   │       └── spec.md
│   └── changes/               # Active changes
│       ├── add-user-auth/     # Change folders
│       │   ├── proposal.md
│       │   ├── design.md
│       │   ├── tasks.md
│       │   └── specs/         # Spec deltas
│       └── archive/           # Completed changes
│           └── 2026-03-30-add-user-auth/
├── .kilocode/
│   └── workflows/             # Kilo Code workflow definitions
└── .cursor/
    ├── skills/
    └── commands/

# Install OpenSpec globally
npm install -g @fission-ai/openspec@latest

# Verify installation
openspec --version

# Initialize in your project (interactive)
openspec init

# Or initialize with specific tools (non-interactive)
openspec init --tools claude,cursor,kilocode

User: "I want to add a feature to our e-commerce app"

Kilo Code (Spec Mode):
I'll help you define the requirements. Let's start with some questions:

1. What specific feature do you want to add?
   - Product reviews?
   - Wishlist functionality?
   - Recommendation engine?
   - Something else?

2. Who are the primary users of this feature?
   - Customers?
   - Admins?
   - Both?

3. What are the must-have capabilities?
   - Create, read, update, delete?
   - Moderation workflow?
   - Integration with other systems?

4. Any technical constraints?
   - Must use existing database?
   - Performance requirements?
   - Security considerations?

# Feature Requirements: Product Reviews

## 1. Overview
Allow customers to leave reviews and ratings for products they've purchased.

## 2. User Stories

### As a Customer
- I want to leave a review for products I've purchased
- I want to rate products on a 1-5 star scale
- I want to see other customers' reviews before buying
- I want to mark reviews as helpful or not helpful

### As an Admin
- I want to moderate reviews before they're published
- I want to remove inappropriate reviews
- I want to respond to customer reviews
- I want to see review analytics

## 3. Functional Requirements

| ID | Requirement | Priority |
|----|-------------|----------|
| FR-1 | Users can submit reviews with text and rating | Must Have |
| FR-2 | Reviews require purchase verification | Must Have |
| FR-3 | Admins can approve/reject reviews | Must Have |
| FR-4 | Users can edit their own reviews within 24h | Should Have |
| FR-5 | Support image attachments in reviews | Could Have |
| FR-6 | Implement review helpfulness voting | Could Have |

## 4. Non-Functional Requirements

| ID | Requirement | Target |
|----|-------------|--------|
| NFR-1 | Review submission latency | < 500ms |
| NFR-2 | Review display latency | < 200ms |
| NFR-3 | Support 10,000 reviews per product | Scale |
| NFR-4 | Prevent spam and abuse | Security |

## 5. Constraints
- Must use existing PostgreSQL database
- Must integrate with current user authentication
- Must comply with GDPR (data deletion)

openspec/changes/add-product-reviews/
├── proposal.md          # Feature overview & requirements
├── design.md            # Technical architecture
├── tasks.md             # Implementation tasks
└── specs/               # Spec deltas
    └── product-reviews/
        └── spec.md      # New spec (delta: ADDED)

# Proposal: Product Reviews System

## 1. Overview
Allow customers to leave reviews and ratings for products they've purchased.

## 2. User Stories

### As a Customer
- I want to leave a review for products I've purchased
- I want to rate products on a 1-5 star scale
- I want to see other customers' reviews before buying

### As an Admin
- I want to moderate reviews before they're published
- I want to remove inappropriate reviews
- I want to see review analytics

## 3. Functional Requirements

| ID | Requirement | Priority |
|----|-------------|----------|
| FR-1 | Users can submit reviews with text and rating | Must Have |
| FR-2 | Reviews require purchase verification | Must Have |
| FR-3 | Admins can approve/reject reviews | Must Have |
| FR-4 | Users can edit their own reviews within 24h | Should Have |

## 4. Non-Functional Requirements

| ID | Requirement | Target |
|----|-------------|--------|
| NFR-1 | Review submission latency | < 500ms |
| NFR-2 | Review display latency | < 200ms |
| NFR-3 | Support 10,000 reviews per product | Scale |

# Design: Product Reviews System

## 1. System Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Frontend  │────▶│  API Layer  │────▶│   Review    │
│   (React)   │     │  (Express)  │     │   Service   │
└─────────────┘     └─────────────┘     └─────────────┘
                                              │
                                              ▼
                                       ┌─────────────┐
                                       │  PostgreSQL │
                                       │  Database   │
                                       └─────────────┘

-- Reviews table
CREATE TABLE reviews (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id),
    product_id UUID NOT NULL REFERENCES products(id),
    rating INTEGER NOT NULL CHECK (rating >= 1 AND rating <= 5),
    title VARCHAR(200),
    content TEXT NOT NULL,
    status VARCHAR(20) DEFAULT 'pending',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    CONSTRAINT unique_user_product_review UNIQUE (user_id, product_id)
);

-- Review helpfulness votes
CREATE TABLE review_votes (
    review_id UUID REFERENCES reviews(id),
    user_id UUID REFERENCES users(id),
    helpful BOOLEAN NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    PRIMARY KEY (review_id, user_id)
);

-- Indexes for performance
CREATE INDEX idx_reviews_product ON reviews(product_id, status);
CREATE INDEX idx_reviews_user ON reviews(user_id);
CREATE INDEX idx_reviews_created ON reviews(created_at DESC);

POST /api/reviews
{
  "productId": "uuid-here",
  "rating": 5,
  "title": "Great product!",
  "content": "I love this product. Highly recommended."
}

Response: 201 Created
{
  "id": "review-uuid",
  "status": "pending",
  "message": "Review submitted for moderation"
}

const reviewSchema = {
  productId: { type: 'uuid', required: true },
  rating: { type: 'integer', min: 1, max: 5, required: true },
  title: { type: 'string', max: 200, optional: true },
  content: { type: 'string', min: 10, max: 5000, required: true }
};

# Tasks: Product Reviews

## Implementation Plan

### Phase 1: Foundation (Day 1-2)

**Task 1.1: Database Migration**
- [ ] Create migration file for reviews table
- [ ] Create migration file for review_votes table
- [ ] Add indexes for performance
- [ ] Write migration tests
- Acceptance: Migration runs successfully, tables created correctly

**Task 1.2: Review Model**
- [ ] Create Review model/ORM class
- [ ] Add validation logic
- [ ] Add instance methods (calculateHelpfulness, etc.)
- [ ] Add static methods (findByProduct, findByUser)
- Acceptance: Model passes all unit tests

**Task 1.3: Review Service Layer**
- [ ] Create review service class
- [ ] Implement createReview() with purchase verification
- [ ] Implement getReviews() with pagination
- [ ] Implement updateReview() with time window check
- [ ] Implement deleteReview() with cascade handling
- Acceptance: Service layer has 90% test coverage

### Phase 2: API Implementation (Day 3-4)

**Task 2.1: Review Routes**
- [ ] Create Express routes for all endpoints
- [ ] Add authentication middleware
- [ ] Add request validation
- [ ] Add error handling
- Acceptance: All routes return correct status codes

**Task 2.2: Response Formatting**
- [ ] Create response transformers
- [ ] Add pagination metadata
- [ ] Add HATEOAS links
- Acceptance: Consistent API response format

**Task 2.3: Admin Endpoints**
- [ ] Create moderation endpoints
- [ ] Add admin authorization
- [ ] Implement bulk operations
- Acceptance: Admins can moderate reviews

### Phase 3: Frontend Integration (Day 5-6)

**Task 3.1: Review Components**
- [ ] Create ReviewList component
- [ ] Create ReviewCard component
- [ ] Create ReviewForm component
- [ ] Create StarRating component
- Acceptance: Components render correctly

**Task 3.2: State Management**
- [ ] Create review slice (Redux/Zustand)
- [ ] Add async thunks for API calls
- [ ] Add loading and error states
- Acceptance: State updates correctly

**Task 3.3: Product Page Integration**
- [ ] Add reviews section to product page
- [ ] Add review submission form
- [ ] Add review filtering and sorting
- Acceptance: Full user flow works end-to-end

### Phase 4: Testing & Polish (Day 7)

**Task 4.1: Comprehensive Testing**
- [ ] Run full test suite
- [ ] Fix any failing tests
- [ ] Add integration tests
- [ ] Perform load testing
- Acceptance: All tests pass, p95 latency < 500ms

**Task 4.2: Documentation**
- [ ] Update API documentation
- [ ] Add component documentation
- [ ] Write user guide
- Acceptance: Docs are complete and accurate

**Task 4.3: Code Review & Cleanup**
- [ ] Address code review feedback
- [ ] Remove debug code
- [ ] Optimize queries
- Acceptance: Code approved for merge

---

Total Estimated Time: 7 days
Critical Path: Database → Model → Service → API → Frontend

# Get enriched instructions for applying tasks
openspec instructions apply --change add-product-reviews

'use strict';

module.exports = {
  async up(queryInterface, Sequelize) {
    // Create reviews table
    await queryInterface.createTable('reviews', {
      id: {
        type: Sequelize.UUID,
        defaultValue: Sequelize.literal('gen_random_uuid()'),
        primaryKey: true
      },
      user_id: {
        type: Sequelize.UUID,
        allowNull: false,
        references: {
          model: 'users',
          key: 'id'
        },
        onDelete: 'CASCADE'
      },
      product_id: {
        type: Sequelize.UUID,
        allowNull: false,
        references: {
          model: 'products',
          key: 'id'
        },
        onDelete: 'CASCADE'
      },
      rating: {
        type: Sequelize.INTEGER,
        allowNull: false,
        validate: {
          min: 1,
          max: 5
        }
      },
      title: {
        type: Sequelize.STRING(200),
        allowNull: true
      },
      content: {
        type: Sequelize.TEXT,
        allowNull: false
      },
      status: {
        type: Sequelize.STRING(20),
        defaultValue: 'pending',
        validate: {
          isIn: [['pending', 'approved', 'rejected']]
        }
      },
      created_at: {
        type: Sequelize.DATE,
        defaultValue: Sequelize.literal('CURRENT_TIMESTAMP')
      },
      updated_at: {
        type: Sequelize.DATE,
        defaultValue: Sequelize.literal('CURRENT_TIMESTAMP')
      }
    });

    // Add unique constraint
    await queryInterface.addConstraint('reviews', {
      fields: ['user_id', 'product_id'],
      type: 'unique',
      name: 'unique_user_product_review'
    });

    // Create review_votes table
    await queryInterface.createTable('review_votes', {
      review_id: {
        type: Sequelize.UUID,
        allowNull: false,
        references: {
          model: 'reviews',
          key: 'id'
        },
        onDelete: 'CASCADE'
      },
      user_id: {
        type: Sequelize.UUID,
        allowNull: false,
        references: {
          model: 'users',
          key: 'id'
        },
        onDelete: 'CASCADE'
      },
      helpful: {
        type: Sequelize.BOOLEAN,
        allowNull: false
      },
      created_at: {
        type: Sequelize.DATE,
        defaultValue: Sequelize.literal('CURRENT_TIMESTAMP')
      }
    });

    // Add primary key constraint for review_votes
    await queryInterface.addConstraint('review_votes', {
      fields: ['review_id', 'user_id'],
      type: 'primary key',
      name: 'review_votes_pkey'
    });

    // Create indexes for performance
    await queryInterface.addIndex('reviews', ['product_id', 'status'], {
      name: 'idx_reviews_product'
    });

    await queryInterface.addIndex('reviews', ['user_id'], {
      name: 'idx_reviews_user'
    });

    await queryInterface.addIndex('reviews', ['created_at'], {
      order: ['DESC'],
      name: 'idx_reviews_created'
    });
  },

  async down(queryInterface, Sequelize) {
    await queryInterface.dropTable('review_votes');
    await queryInterface.dropTable('reviews');
  }
};

const { sequelize } = require('../../src/config/database');
const { QueryInterface } = require('sequelize');

describe('Migration: Create Reviews Tables', () => {
  it('should create reviews table with correct structure', async () => {
    const table = await queryInterface.describeTable('reviews');
    
    expect(table.id).toBeDefined();
    expect(table.user_id).toBeDefined();
    expect(table.product_id).toBeDefined();
    expect(table.rating).toBeDefined();
    expect(table.status.defaultValue).toBe('pending');
  });

  it('should create review_votes table', async () => {
    const table = await queryInterface.describeTable('review_votes');
    
    expect(table.review_id).toBeDefined();
    expect(table.user_id).toBeDefined();
    expect(table.helpful).toBeDefined();
  });

  it('should have required indexes', async () => {
    const indexes = await queryInterface.showIndex('reviews');
    
    const indexNames = indexes.map(idx => idx.name);
    expect(indexNames).toContain('idx_reviews_product');
    expect(indexNames).toContain('idx_reviews_user');
    expect(indexNames).toContain('idx_reviews_created');
  });
});

$ npm run db:migrate

== 20260330-create-reviews-table: migrating =======
== 20260330-create-reviews-table: migrated (0.042s)

✓ Reviews table created
✓ Review votes table created
✓ Indexes created

$ npm test -- Review.test.js

  Review Model
    ✓ should create valid review instance (12ms)
    ✓ should validate rating between 1-5 (8ms)
    ✓ should reject invalid status values (5ms)
    ✓ should prevent duplicate user-product reviews (15ms)
    ✓ should calculate helpfulness percentage (7ms)
    ✓ should sanitize content on save (6ms)

  6 passing (53ms)
  Coverage: 94%

$ npm test:integration -- reviews

  Review Integration
    ✓ should create review via service (45ms)
    ✓ should fetch reviews by product (32ms)
    ✓ should update review within time window (28ms)
    ✓ should reject update after 24h (22ms)
    ✓ should delete review and cascade votes (38ms)

  5 passing (165ms)

$ npm run lint:reviews

✓ No ESLint errors
✓ No TypeScript errors
✓ Security scan: No issues