@panuwatbas/spec-driven-dev 1.0.2

package/skill/examples/example-design.md

@@ -0,0 +1,287 @@
+# Technical Design: Shopping Cart Management
+
+> **Status:** 🟢 Approved
+>
+> **Requirements:** [requirements.md](./example-requirements.md)
+>
+> **Author:** AI Agent
+>
+> **Created:** 2025-07-24
+>
+> **Last Updated:** 2025-07-24
+
+---
+
+## 1. Overview
+
+Implement a client-side cart with server-side sync for authenticated users.
+Guest users' carts are stored in `localStorage`; logged-in users' carts are
+persisted in PostgreSQL and synced via a REST API. The cart UI is a React component
+with optimistic updates for a snappy user experience.
+
+---
+
+## 2. Architecture
+
+### 2.1 System Diagram
+
+```mermaid
+graph TD
+    A[React Frontend] --> B[Cart Context / Zustand Store]
+    B --> C{User Logged In?}
+    C -->|Yes| D[Cart API - /api/cart]
+    C -->|No| E[localStorage]
+    D --> F[Cart Service]
+    F --> G[(PostgreSQL - cart_items)]
+    F --> H[Inventory Service]
+```
+
+### 2.2 Architectural Pattern
+
+**Client-State + Server-Sync Hybrid**
+
+- Guest users: purely client-side (localStorage + Zustand)
+- Logged-in users: optimistic client updates with background server sync
+- On login: merge localStorage cart into server cart, then clear localStorage
+
+### 2.3 Tech Stack
+
+| Layer | Technology | Justification |
+|-------|-----------|---------------|
+| Frontend | React 18 + TypeScript | Existing project stack |
+| State | Zustand | Lightweight, no boilerplate |
+| Backend | Node.js + Express | Existing API server |
+| Database | PostgreSQL | Existing database, relational model fits cart data |
+| Cache | Redis | Session-level cart caching for performance |
+
+---
+
+## 3. Component Design
+
+### 3.1 CartProvider (Frontend)
+
+- **Responsibility:** Global cart state management and persistence logic
+- **Location:** `src/contexts/CartContext.tsx`
+- **Public Interface:**
+  ```typescript
+  interface CartContextValue {
+    items: CartItem[];
+    totalItems: number;
+    totalPrice: number;
+    addItem: (product: Product, quantity?: number) => void;
+    updateQuantity: (productId: string, quantity: number) => void;
+    removeItem: (productId: string) => void;
+    clearCart: () => void;
+    isLoading: boolean;
+  }
+  ```
+- **State Management:** Zustand store hydrated from localStorage (guest) or API (authenticated)
+
+### 3.2 CartAPI (Backend)
+
+- **Responsibility:** CRUD operations for server-side cart persistence
+- **Location:** `src/server/routes/cart.ts`
+- **Public Interface:**
+  ```typescript
+  // Express routes
+  GET    /api/cart              → Get user's cart
+  POST   /api/cart/items        → Add item to cart
+  PATCH  /api/cart/items/:id    → Update item quantity
+  DELETE /api/cart/items/:id    → Remove item from cart
+  DELETE /api/cart              → Clear entire cart
+  POST   /api/cart/merge        → Merge guest cart on login
+  ```
+- **Error Handling:** Returns structured JSON errors with field-level details
+
+### 3.3 CartService (Backend)
+
+- **Responsibility:** Business logic — stock validation, quantity capping, price calculation
+- **Location:** `src/server/services/CartService.ts`
+- **Dependencies:** InventoryService, ProductRepository
+
+---
+
+## 4. Data Models
+
+### 4.1 CartItem (Frontend)
+
+```typescript
+interface CartItem {
+  productId: string;
+  name: string;
+  price: number;           // Unit price at time of adding
+  quantity: number;
+  maxQuantity: number;     // Stock limit
+  imageUrl: string;
+}
+```
+
+### 4.2 Database Schema
+
+```sql
+CREATE TABLE cart_items (
+  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id     UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  product_id  UUID NOT NULL REFERENCES products(id),
+  quantity    INTEGER NOT NULL CHECK (quantity > 0),
+  added_at    TIMESTAMP DEFAULT NOW(),
+  updated_at  TIMESTAMP DEFAULT NOW(),
+  UNIQUE(user_id, product_id)
+);
+
+CREATE INDEX idx_cart_items_user ON cart_items(user_id);
+```
+
+---
+
+## 5. API Contracts
+
+### 5.1 Add Item to Cart
+
+| Property | Value |
+|----------|-------|
+| Method | `POST` |
+| Path | `/api/cart/items` |
+| Auth | Required (Bearer token) |
+
+**Request:**
+```json
+{
+  "productId": "uuid",
+  "quantity": 1
+}
+```
+
+**Response (201):**
+```json
+{
+  "id": "uuid",
+  "productId": "uuid",
+  "name": "Blue T-Shirt",
+  "quantity": 1,
+  "price": 29.99,
+  "maxQuantity": 10
+}
+```
+
+**Errors:**
+
+| Status | Scenario |
+|--------|----------|
+| 400 | Invalid productId or quantity ≤ 0 |
+| 404 | Product not found |
+| 409 | Quantity exceeds stock (returns `maxQuantity`) |
+
+---
+
+## 6. Sequence Diagrams
+
+### 6.1 Add to Cart (Authenticated User)
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant UI as CartButton
+    participant Store as Zustand Store
+    participant API as Cart API
+    participant Svc as CartService
+    participant Inv as InventoryService
+    participant DB as PostgreSQL
+
+    User->>UI: Click "Add to Cart"
+    UI->>Store: addItem(product, 1)
+    Store->>Store: Optimistic update (add item)
+    Store->>API: POST /api/cart/items
+    API->>Svc: addToCart(userId, productId, qty)
+    Svc->>Inv: checkStock(productId)
+    Inv-->>Svc: stock = 10
+    Svc->>DB: INSERT INTO cart_items
+    DB-->>Svc: OK
+    Svc-->>API: CartItem
+    API-->>Store: 201 Created
+    Store->>UI: Re-render with new item
+    UI-->>User: Toast "Item added to cart"
+```
+
+### 6.2 Cart Merge on Login
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant UI as LoginForm
+    participant Auth as Auth Service
+    participant Store as Zustand Store
+    participant API as Cart API
+
+    User->>UI: Submit credentials
+    UI->>Auth: POST /api/auth/login
+    Auth-->>UI: Token + User
+    UI->>Store: Get localStorage cart items
+    Store->>API: POST /api/cart/merge {localItems}
+    API->>API: Merge logic (server wins on conflict)
+    API-->>Store: Merged cart
+    Store->>Store: Clear localStorage, set server cart
+    Store->>UI: Re-render
+```
+
+---
+
+## 7. Error Handling Strategy
+
+| Error Type | Handling Approach |
+|-----------|-------------------|
+| Stock exceeded | Cap quantity, show warning with max available |
+| Product removed | Remove from cart, show info notification |
+| Network failure | Keep optimistic state, retry with exponential backoff (max 3) |
+| Auth expired | Queue cart operations, redirect to login, replay after auth |
+
+---
+
+## 8. Testing Strategy
+
+| Level | Tool | What to Test |
+|-------|------|-------------|
+| Unit | Vitest | CartService logic, Zustand store actions |
+| Integration | Supertest | API endpoints with test database |
+| E2E | Playwright | Full add-to-cart flow, quantity updates, persistence |
+
+---
+
+## 9. Security Considerations
+
+- [x] Cart API requires authentication (except merge endpoint during login flow)
+- [x] User can only access their own cart (enforced by user_id from JWT)
+- [x] Quantity validated server-side against inventory
+- [x] Price always fetched from server at checkout (not from client state)
+- [x] Rate limiting on cart endpoints (60 req/min per user)
+
+---
+
+## 10. Constraints & Rules
+
+### Forbidden Patterns
+- ❌ Never trust client-side prices for order totals
+- ❌ No direct database access from route handlers (use service layer)
+- ❌ No blocking API calls in the render path
+
+### Naming Conventions
+- Files: `kebab-case.ts`
+- Components: `PascalCase.tsx`
+- API routes: `/api/kebab-case`
+- DB tables: `snake_case`
+
+---
+
+## 11. Open Questions
+
+- [x] Conflict resolution on merge? → Server wins, quantities are summed
+- [ ] Should we add a "recently removed" undo feature?
+
+---
+
+## 12. Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 0.1 | 2025-07-24 | AI Agent | Initial design |
+| 1.0 | 2025-07-24 | AI Agent | Approved after review |

package/skill/examples/example-requirements.md

@@ -0,0 +1,151 @@
+# Feature: Shopping Cart Management
+
+> **Status:** 🟢 Approved
+>
+> **Author:** AI Agent
+>
+> **Created:** 2025-07-24
+>
+> **Last Updated:** 2025-07-24
+
+---
+
+## Overview
+
+Allow users to add products to a shopping cart, modify quantities, remove items,
+and see a real-time total. The cart persists across browser sessions so users
+don't lose their selections.
+
+---
+
+## User Stories
+
+### US-1: Add Product to Cart
+
+**As a** online shopper,
+**I want to** add products to my shopping cart,
+**so that** I can collect items I intend to purchase.
+
+#### Acceptance Criteria
+
+##### AC-1.1: Successfully add a product
+
+**Given** I am on a product detail page
+**And** the product is in stock
+**When** I click the "Add to Cart" button
+**Then** the product is added to my cart with quantity 1
+**And** the cart icon in the header shows the updated item count
+**And** I see a confirmation toast notification "Item added to cart"
+
+##### AC-1.2: Add a product that is already in the cart
+
+**Given** I have "Blue T-Shirt" in my cart with quantity 1
+**When** I navigate to the "Blue T-Shirt" product page
+**And** I click the "Add to Cart" button
+**Then** the quantity of "Blue T-Shirt" in my cart increases to 2
+**And** no duplicate entry is created
+
+##### AC-1.3: Attempt to add an out-of-stock product
+
+**Given** I am on a product detail page
+**And** the product is out of stock
+**When** I view the page
+**Then** the "Add to Cart" button is disabled
+**And** I see a message "Currently out of stock"
+
+---
+
+### US-2: Update Cart Item Quantity
+
+**As a** online shopper,
+**I want to** change the quantity of items in my cart,
+**so that** I can buy the right number of each product.
+
+#### Acceptance Criteria
+
+##### AC-2.1: Increase item quantity
+
+**Given** I have "Blue T-Shirt" in my cart with quantity 1
+**When** I increase the quantity to 3
+**Then** the item quantity updates to 3
+**And** the cart total updates to reflect 3 × the item price
+
+##### AC-2.2: Decrease item quantity to zero removes the item
+
+**Given** I have "Blue T-Shirt" in my cart with quantity 1
+**When** I decrease the quantity to 0
+**Then** the item is removed from my cart
+**And** I see a confirmation "Item removed from cart"
+
+##### AC-2.3: Quantity cannot exceed stock limit
+
+**Given** I have "Blue T-Shirt" in my cart
+**And** the available stock is 10
+**When** I attempt to set the quantity to 15
+**Then** the quantity is capped at 10
+**And** I see a message "Maximum available quantity is 10"
+
+---
+
+### US-3: Cart Persistence
+
+**As a** online shopper,
+**I want** my cart to persist across browser sessions,
+**so that** I don't lose my selections when I close the browser.
+
+#### Acceptance Criteria
+
+##### AC-3.1: Cart survives page reload
+
+**Given** I have 3 items in my cart
+**When** I refresh the browser page
+**Then** all 3 items are still in my cart with the correct quantities
+
+##### AC-3.2: Cart syncs for logged-in users
+
+**Given** I am logged in and have items in my cart on Device A
+**When** I log in on Device B
+**Then** I see the same cart contents on Device B
+
+---
+
+## Out of Scope
+
+- **Checkout flow** — will be a separate feature spec
+- **Wishlist / Save for Later** — planned for Phase 2
+- **Cart sharing via URL** — not in current roadmap
+
+---
+
+## Dependencies
+
+| Dependency | Type | Status |
+|-----------|------|--------|
+| Product Catalog API | API | Available |
+| User Authentication | Feature | Available |
+| Inventory Service | API | Available |
+
+---
+
+## Non-Functional Requirements
+
+- **Performance:** Cart updates must reflect in < 200ms
+- **Security:** Cart data for logged-in users must be tied to authenticated sessions
+- **Accessibility:** All cart controls must be keyboard-navigable and screen-reader compatible
+- **Browser Support:** Chrome, Firefox, Safari, Edge (latest 2 versions)
+
+---
+
+## Open Questions
+
+- [x] Should guest users have persistent carts? → Yes, via localStorage
+- [ ] What is the maximum number of unique items allowed in a cart?
+
+---
+
+## Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 0.1 | 2025-07-24 | AI Agent | Initial draft |
+| 1.0 | 2025-07-24 | AI Agent | Approved after review |

package/skill/examples/example-tasks.md

@@ -0,0 +1,189 @@
+# Implementation Tasks: Shopping Cart Management
+
+> **Status:** 🔵 In Progress
+>
+> **Requirements:** [requirements.md](./example-requirements.md)
+>
+> **Design:** [design.md](./example-design.md)
+>
+> **Created:** 2025-07-24
+>
+> **Last Updated:** 2025-07-24
+
+---
+
+## Progress Overview
+
+| Phase | Status | Tasks | Completed |
+|-------|--------|-------|-----------|
+| Phase 1: Database & Models | ✅ Done | 4/4 | 100% |
+| Phase 2: Backend API | 🔵 In Progress | 2/5 | 40% |
+| Phase 3: Frontend UI | ⬜ Not Started | 0/5 | 0% |
+| Phase 4: Testing & Polish | ⬜ Not Started | 0/4 | 0% |
+
+---
+
+## Phase 1: Database & Models
+
+> **Goal:** Set up the cart data layer — database schema, models, and data access
+>
+> **Traces to:** US-1, US-3 (persistence) from requirements.md
+
+- [x] **Task 1.1:** Create cart_items database migration
+  - File(s): `src/server/migrations/003_create_cart_items.sql`
+  - Details: Create table with UUID PK, user_id FK, product_id FK, quantity check, unique constraint, and index
+
+- [x] **Task 1.2:** Create CartItem TypeScript model
+  - File(s): `src/shared/types/cart.ts`
+  - Details: Define `CartItem`, `AddToCartPayload`, `UpdateQuantityPayload` interfaces
+
+- [x] **Task 1.3:** Create CartRepository data access layer
+  - File(s): `src/server/repositories/CartRepository.ts`
+  - Details: Implement `findByUserId`, `upsertItem`, `updateQuantity`, `removeItem`, `clearCart`
+
+- [x] **Task 1.4 (Verify):** Run verification for Phase 1
+  - [x] Migration runs without errors
+  - [x] Repository methods tested against test database
+  - [x] TypeScript types compile without errors
+
+---
+
+## Phase 2: Backend API
+
+> **Goal:** Build the cart service and REST API endpoints
+>
+> **Traces to:** US-1 (AC-1.1, AC-1.2, AC-1.3), US-2 (AC-2.1, AC-2.2, AC-2.3) from requirements.md
+
+- [x] **Task 2.1:** Implement CartService business logic
+  - File(s): `src/server/services/CartService.ts`
+  - Details: 
+    - [x] `addToCart()` — validate stock, handle existing item (increment qty)
+    - [x] `updateQuantity()` — cap at stock limit, remove if qty = 0
+    - [x] `removeItem()` — remove single item
+    - [x] `getCart()` — return full cart with computed totals
+    - [x] `mergeCart()` — merge guest items on login
+
+- [x] **Task 2.2:** Create cart API routes
+  - File(s): `src/server/routes/cart.ts`
+  - Details:
+    - [x] `GET /api/cart` — get user's cart
+    - [x] `POST /api/cart/items` — add item
+    - [x] `PATCH /api/cart/items/:id` — update quantity
+    - [x] `DELETE /api/cart/items/:id` — remove item
+    - [x] `POST /api/cart/merge` — merge guest cart
+
+- [/] **Task 2.3:** Add input validation middleware
+  - File(s): `src/server/middleware/validate-cart.ts`
+  - Details: Validate productId format, quantity range, request body structure
+
+- [ ] **Task 2.4:** Add authentication guard to cart routes
+  - File(s): `src/server/middleware/auth.ts`
+  - Details: Ensure all cart endpoints require valid JWT (except during merge flow)
+
+- [ ] **Task 2.5 (Verify):** Run verification for Phase 2
+  - [ ] All endpoints return correct status codes
+  - [ ] Stock limit enforcement works (AC-2.3)
+  - [ ] Duplicate item handling works (AC-1.2)
+  - [ ] Out-of-stock rejection works (AC-1.3)
+  - [ ] Integration tests pass
+
+---
+
+## Phase 3: Frontend UI
+
+> **Goal:** Build the cart UI components with state management
+>
+> **Traces to:** US-1 (AC-1.1), US-2 (AC-2.1, AC-2.2), US-3 (AC-3.1) from requirements.md
+
+- [ ] **Task 3.1:** Create Zustand cart store
+  - File(s): `src/store/useCartStore.ts`
+  - Details:
+    - [ ] Define store with `items`, `totalItems`, `totalPrice` computed
+    - [ ] Implement `addItem`, `updateQuantity`, `removeItem`, `clearCart` actions
+    - [ ] Add localStorage persistence middleware for guests
+    - [ ] Add API sync middleware for authenticated users
+
+- [ ] **Task 3.2:** Build CartButton header component
+  - File(s): `src/components/CartButton.tsx`
+  - Details: Shows cart icon with item count badge, links to cart page
+
+- [ ] **Task 3.3:** Build AddToCartButton product component
+  - File(s): `src/components/AddToCartButton.tsx`
+  - Details:
+    - [ ] Enabled state: shows "Add to Cart"
+    - [ ] Disabled state: shows "Out of Stock" (AC-1.3)
+    - [ ] Loading state during API call
+    - [ ] Toast notification on success (AC-1.1)
+
+- [ ] **Task 3.4:** Build CartPage with item management
+  - File(s): `src/pages/CartPage.tsx`
+  - Details:
+    - [ ] List all cart items with image, name, price, quantity
+    - [ ] Quantity +/- controls with stock limit enforcement (AC-2.3)
+    - [ ] Remove item button
+    - [ ] Cart total display
+    - [ ] Empty cart state
+
+- [ ] **Task 3.5 (Verify):** Run verification for Phase 3
+  - [ ] Cart updates reflect in < 200ms (NFR)
+  - [ ] Cart persists across page reload (AC-3.1)
+  - [ ] All controls keyboard-accessible (NFR)
+  - [ ] Responsive on mobile and desktop
+
+---
+
+## Phase 4: Testing & Polish
+
+> **Goal:** Comprehensive testing and final quality pass
+
+- [ ] **Task 4.1:** Write end-to-end tests
+  - File(s): `tests/e2e/cart.spec.ts`
+  - Details:
+    - [ ] Test: Add product to empty cart
+    - [ ] Test: Add duplicate product (quantity increment)
+    - [ ] Test: Update quantity and verify total
+    - [ ] Test: Remove item from cart
+    - [ ] Test: Cart persistence across reload
+    - [ ] Test: Stock limit enforcement
+
+- [ ] **Task 4.2:** Write unit tests for CartService
+  - File(s): `tests/unit/CartService.test.ts`
+  - Details:
+    - [ ] Test stock validation logic
+    - [ ] Test quantity capping
+    - [ ] Test merge cart conflict resolution
+    - [ ] Test price calculation
+
+- [ ] **Task 4.3:** Accessibility audit
+  - [ ] All interactive elements have ARIA labels
+  - [ ] Tab order is logical
+  - [ ] Screen reader announces cart updates
+  - [ ] Color contrast meets WCAG AA
+
+- [ ] **Task 4.4 (Final Verify):** Complete acceptance criteria check
+  - [ ] AC-1.1 ✓ Add product to cart
+  - [ ] AC-1.2 ✓ Duplicate product handling
+  - [ ] AC-1.3 ✓ Out-of-stock behavior
+  - [ ] AC-2.1 ✓ Increase quantity
+  - [ ] AC-2.2 ✓ Decrease to zero removes item
+  - [ ] AC-2.3 ✓ Stock limit cap
+  - [ ] AC-3.1 ✓ Cart persists on reload
+  - [ ] AC-3.2 ✓ Cart syncs across devices
+
+---
+
+## Task Status Legend
+
+| Symbol | Meaning |
+|--------|---------|
+| `- [ ]` | Not started |
+| `- [/]` | In progress |
+| `- [x]` | Completed |
+| `- [!]` | Blocked / Needs attention |
+
+---
+
+## Notes
+
+- 2025-07-24: Decided to use Zustand over React Context for cart state — smaller bundle, simpler API
+- 2025-07-24: Merge strategy on login = sum quantities, cap at stock limit, server wins on price conflicts

package/skill/scripts/init-spec.bat

@@ -0,0 +1,70 @@
+@echo off
+REM ============================================================================
+REM init-spec.bat — Initialize a new spec directory for a feature (Windows)
+REM
+REM Usage:
+REM   .specs\scripts\init-spec.bat <feature-name>
+REM
+REM Examples:
+REM   .specs\scripts\init-spec.bat user-authentication
+REM ============================================================================
+
+setlocal enabledelayedexpansion
+
+set "SPECS_DIR=.specs"
+set "FEATURE_NAME=%~1"
+
+if "%FEATURE_NAME%"=="" (
+    echo ❌ Error: Feature name is required.
+    echo.
+    echo Usage: %~nx0 ^<feature-name^>
+    echo.
+    echo Example: %~nx0 user-authentication
+    exit /b 1
+)
+
+set "SPEC_PATH=%SPECS_DIR%\%FEATURE_NAME%"
+
+if exist "%SPEC_PATH%" (
+    echo ⚠️  Spec directory already exists: %SPEC_PATH%
+    exit /b 1
+)
+
+mkdir "%SPEC_PATH%"
+echo 📁 Created: %SPEC_PATH%\
+
+REM --- Try to find and copy templates ---
+set "SKILL_DIR="
+for %%D in (
+    ".gemini\skills\spec-driven-dev\templates"
+    "skills\spec-driven-dev\templates"
+    ".cursor\skills\spec-driven-dev\templates"
+) do (
+    if exist "%%~D" (
+        set "SKILL_DIR=%%~D"
+        goto :found_templates
+    )
+)
+
+:found_templates
+if defined SKILL_DIR (
+    copy "%SKILL_DIR%\requirements.template.md" "%SPEC_PATH%\requirements.md" >nul
+    copy "%SKILL_DIR%\design.template.md" "%SPEC_PATH%\design.md" >nul
+    copy "%SKILL_DIR%\tasks.template.md" "%SPEC_PATH%\tasks.md" >nul
+    echo 📄 Copied templates from %SKILL_DIR%
+) else (
+    echo # Feature: %FEATURE_NAME% > "%SPEC_PATH%\requirements.md"
+    echo # Technical Design: %FEATURE_NAME% > "%SPEC_PATH%\design.md"
+    echo # Implementation Tasks: %FEATURE_NAME% > "%SPEC_PATH%\tasks.md"
+    echo 📄 Created minimal spec files (templates not found^)
+)
+
+echo.
+echo ✅ Spec initialized for: %FEATURE_NAME%
+echo.
+echo 📋 Next steps:
+echo    1. Edit %SPEC_PATH%\requirements.md — Define WHAT to build
+echo    2. Edit %SPEC_PATH%\design.md       — Define HOW to build it
+echo    3. Edit %SPEC_PATH%\tasks.md        — Define the execution plan
+
+endlocal