@eskoubar95/spec 0.1.0 → 0.1.2

package/template/.cursor/rules/11-design.mdc

@@ -0,0 +1,129 @@
+---
+title: Design Foundations
+description: Framework-agnostic design system and UI patterns - applies to design tasks
+owner: sdd-system
+severity: warn
+globs: "**/*"
+alwaysApply: false
+activation:
+  projectTypes: [web-app, mobile-app]
+  projectSizes: [small, medium, large, enterprise]
+  projectPhases: [initialization, expansion, maintenance, migration, legacy]
+  technologies: []
+  requires: []
+---
+
+# Design Foundations
+
+## Purpose
+
+Framework-agnostic design system patterns, UI components, and visual consistency guidelines. These patterns apply to all design tasks regardless of styling framework.
+
+## Design System Reference
+
+**Always reference project design system if it exists:**
+- Check for `spec/07-design-system.md`
+- Follow established color, typography, spacing systems
+- Maintain visual consistency with existing design
+
+## Principles
+
+- **Consistency**: Visual consistency across all UI
+- **Accessibility First**: WCAG AA minimum, aim for AAA
+- **Responsive by Default**: Mobile-first approach
+- **Clear Visual Hierarchy**: Guide user attention effectively
+
+## Component Design
+
+**Reusable, Composable UI Components:**
+- Build components from primitives
+- Components are self-contained
+- Components are composable
+- Components follow design system tokens
+
+**Accessibility Requirements:**
+- Semantic HTML elements
+- Correct ARIA roles and labels
+- Visible focus states
+- Keyboard navigation support
+- Screen reader support
+- Color contrast (WCAG AA minimum)
+
+**Responsive Design:**
+- Mobile-first approach
+- Breakpoints: mobile (320px+), tablet (768px+), desktop (1024px+)
+- Fluid typography and spacing
+- Flexible layouts (flexbox, grid)
+
+## Visual Consistency
+
+**Color System:**
+- Use design system color tokens
+- Semantic colors (success, error, warning, info)
+- Consistent color usage across components
+
+**Typography:**
+- Use design system typography scale
+- Consistent font families, weights, sizes
+- Proper line heights and spacing
+
+**Spacing:**
+- Use design system spacing scale
+- Consistent margins and padding
+- Visual rhythm and alignment
+
+## UI Patterns
+
+**Card Layouts:**
+- Consistent card styling
+- Proper spacing and shadows
+- Responsive card grids
+
+**Button Styles:**
+- Primary, secondary, outline variants
+- Consistent sizing and spacing
+- Proper disabled states
+- Loading states
+
+**Form Inputs:**
+- Consistent input styling
+- Proper labels and placeholders
+- Error states and validation feedback
+- Accessible form controls
+
+**Navigation Patterns:**
+- Consistent navigation structure
+- Clear active states
+- Mobile-friendly navigation
+- Breadcrumbs where appropriate
+
+## Framework-Specific Extensions
+
+This rule provides foundation patterns. For framework-specific patterns, see:
+- Tailwind CSS: `[tailwind]-*.mdc` (if Tailwind detected)
+- CSS Modules: `[css-modules]-*.mdc` (if CSS Modules detected)
+- Styled Components: `[styled-components]-*.mdc` (if detected)
+- Other styling: `[styling]-*.mdc` (if detected)
+
+## Accessibility Checklist
+
+- [ ] Semantic HTML elements used
+- [ ] ARIA roles and labels correct
+- [ ] Visible focus states
+- [ ] Keyboard navigation works
+- [ ] Screen reader tested
+- [ ] Color contrast meets WCAG AA
+- [ ] Images have meaningful alt text
+- [ ] Forms are accessible
+- [ ] Interactive elements are keyboard accessible
+
+## Responsive Design Checklist
+
+- [ ] Mobile layout tested (320px+)
+- [ ] Tablet layout tested (768px+)
+- [ ] Desktop layout tested (1024px+)
+- [ ] No horizontal scrolling
+- [ ] Touch targets are adequate size (44x44px minimum)
+- [ ] Typography scales appropriately
+- [ ] Images are responsive
+- [ ] Navigation works on all screen sizes

package/template/.cursor/rules/12-business.mdc

@@ -0,0 +1,132 @@
+---
+title: Business Analysis Foundations
+description: Business analysis patterns - applies to business and requirements tasks
+owner: sdd-system
+severity: warn
+globs: "**/*"
+alwaysApply: false
+activation:
+  projectTypes: [web-app, api-service, mobile-app]
+  projectSizes: [small, medium, large, enterprise]
+  projectPhases: [initialization, expansion]
+  technologies: []
+  requires: []
+---
+
+# Business Analysis Foundations
+
+## Purpose
+
+Business analysis patterns for requirements gathering, user stories, business logic, and domain models. These patterns apply to business-focused tasks and requirements definition.
+
+## Principles
+
+- **User-Centric**: Focus on user value and outcomes
+- **Clear Requirements**: Explicit, testable requirements
+- **Domain-Driven**: Business logic reflects domain understanding
+- **Value-Focused**: Prioritize features by business value
+
+## Requirements Gathering
+
+**Ask the Right Questions:**
+- What problem are we solving?
+- Who is the user?
+- What value does this deliver?
+- What does success look like?
+- What are the constraints?
+
+**Document Requirements:**
+- User stories with acceptance criteria
+- Business rules and logic
+- Success metrics
+- Constraints and limitations
+
+## User Stories
+
+**Format:**
+- As a [user type]
+- I want [goal]
+- So that [benefit]
+
+**Acceptance Criteria:**
+- Given [context]
+- When [action]
+- Then [outcome]
+
+**Example:**
+```
+As a customer
+I want to save items to my wishlist
+So that I can purchase them later
+
+Acceptance Criteria:
+- Given I am logged in
+- When I click "Save to Wishlist" on a product
+- Then the product is added to my wishlist
+- And I can view my wishlist later
+- And I can remove items from my wishlist
+```
+
+## Business Logic
+
+**Domain Models:**
+- Represent business entities
+- Contain business rules
+- Are framework-agnostic
+- Reflect real-world concepts
+
+**Business Rules:**
+- Explicit rules, not implicit
+- Documented in spec or code
+- Testable and verifiable
+- Can be changed as business evolves
+
+**Value Proposition:**
+- Clear value to users
+- Measurable outcomes
+- Business impact
+- Success metrics
+
+## Domain-Driven Design
+
+**Domain Models:**
+- Entities: Things with identity (User, Order, Product)
+- Value Objects: Things without identity (Money, Address)
+- Aggregates: Clusters of entities (Order with OrderItems)
+- Services: Operations that don't fit entities
+
+**Business Logic Location:**
+- Domain models contain business rules
+- Services orchestrate business operations
+- Repositories handle data access
+- Keep business logic out of UI/API layers
+
+## Success Metrics
+
+**Define Measurable Outcomes:**
+- User engagement metrics
+- Business value metrics
+- Performance metrics
+- Quality metrics
+
+**Track Progress:**
+- Baseline measurements
+- Target goals
+- Current status
+- Improvement over time
+
+## Requirements Traceability
+
+**Link Requirements to Implementation:**
+- Requirements → Spec → Plan → Tasks → Code
+- Track which code implements which requirement
+- Verify requirements are met
+- Update requirements as needed
+
+## Business Rules Documentation
+
+**Document Business Rules:**
+- In spec files (spec/05-decisions.md)
+- In code comments (for complex logic)
+- In domain model documentation
+- Keep rules explicit and testable

package/template/.cursor/rules/20-nextjs.mdc

@@ -0,0 +1,146 @@
+---
+title: Next.js Patterns
+description: Next.js App Router patterns - applies when Next.js is detected
+owner: sdd-system
+severity: warn
+globs: "app/**, src/app/**"
+alwaysApply: false
+activation:
+  projectTypes: [web-app]
+  projectSizes: [small, medium, large, enterprise]
+  projectPhases: [initialization, expansion, maintenance, migration, legacy]
+  technologies: [nextjs]
+  requires: [10-engineering]
+---
+
+# Next.js Patterns
+
+## Purpose
+
+Next.js App Router patterns for server components, Server Actions, API routes, file structure, routing, and data fetching. Only activates when Next.js is detected.
+
+## Component Types
+
+**Server Components (Default):**
+- Server components by default
+- No "use client" directive needed
+- Can use async/await for data fetching
+- Cannot use browser APIs or hooks
+
+**Client Components:**
+- Use "use client" directive only when interactivity required
+- Can use browser APIs, hooks, event handlers
+- Keep business logic out of client components
+- Prefer server components when possible
+
+## Data Fetching
+
+**Server Components:**
+- Use async/await for data fetching
+- Fetch data in server components
+- Pass data as props to client components
+- Centralize API calls in `lib/services/*`
+
+**Server Actions:**
+- Handle mutations via Server Actions
+- Return `{ ok: true, data? }` or `{ ok: false, error: { code, message } }`
+- Validate input server-side
+- Handle errors gracefully
+
+**API Routes:**
+- API routes in `app/api/v1/...`
+- Use Next.js route handlers
+- Return standard JSON responses
+- Handle authentication server-side
+
+## Caching and Revalidation
+
+**Cache Strategy:**
+- `cache` for public, slow-changing data
+- `revalidate` for ISR (Incremental Static Regeneration)
+- `no-store` for user/checkout data
+- Avoid double-fetch
+
+**Revalidation:**
+- Use `export const revalidate = <seconds>` for ISR
+- Revalidate on-demand when needed
+- Cache public data, don't cache user-specific data
+
+## Routing and Structure
+
+**App Router Structure:**
+- Organize by features/segments
+- Keep nesting shallow
+- Use `next/link` for internal navigation
+- Route groups with `(groupName)` for organization
+
+**API Routes:**
+- `app/api/v1/jerseys/route.ts` for GET/POST
+- `app/api/v1/jerseys/[id]/route.ts` for GET/PATCH/DELETE
+- Use standard HTTP methods
+- Follow RESTful conventions
+
+## File Structure
+
+**Recommended Structure:**
+```
+app/
+  (app)/              # Route group
+    page.tsx          # Home page
+    layout.tsx        # App layout
+    blog/
+      page.tsx        # Blog listing
+      [slug]/
+        page.tsx      # Blog post
+  api/
+    v1/
+      jerseys/
+        route.ts      # API routes
+lib/
+  services/           # Business logic
+  repositories/       # Data access
+  utils/              # Utilities
+components/           # Shared components
+```
+
+## Performance
+
+**Optimizations:**
+- Prefer streamed SSR
+- Lazy-load large components with `Suspense`
+- Keep client bundle slim
+- Use dynamic imports for heavy modules
+- Optimize images with `next/image`
+
+## Integrations
+
+**Supabase:**
+- Server-side: `lib/supabase-server.ts` with service role
+- Client-side: `lib/supabase-client.ts` with anon key
+- Never expose service role key to client
+
+**Auth (Clerk/NextAuth):**
+- Use `@clerk/nextjs` for frontend auth
+- Use `@clerk/backend` for API route verification
+- Protect routes with middleware
+
+## State Management
+
+**Server State:**
+- TanStack Query for client-side data management
+- Server components for initial data
+- Server Actions for mutations
+
+**Client State:**
+- React Hook Form + Zod for forms
+- Context API for minimal global UI state
+- Avoid global state when possible
+
+## DoD (Definition of Done)
+
+- No client-only secrets
+- Server Actions/API routes for mutations
+- No duplicate fetch
+- LCP (Largest Contentful Paint) optimized
+- Accessibility checks pass
+- API routes follow RESTful patterns

package/template/.cursor/rules/21-api-design.mdc

@@ -0,0 +1,176 @@
+---
+title: API Design Patterns
+description: API design patterns - applies when API work is detected
+owner: sdd-system
+severity: warn
+globs: "app/api/**, src/api/**, routes/**, api/**"
+alwaysApply: false
+activation:
+  projectTypes: [web-app, api-service]
+  projectSizes: [small, medium, large, enterprise]
+  projectPhases: [initialization, expansion, maintenance, migration, legacy]
+  technologies: [nextjs, express, fastapi, flask]
+  requires: [10-engineering]
+---
+
+# API Design Patterns
+
+## Purpose
+
+API design patterns for REST, GraphQL, RPC patterns, error handling, pagination, and versioning. Applies when API work is detected (API routes, Express, FastAPI, etc.).
+
+## Principles
+
+- **Resource-First Design**: Design around resources, not actions
+- **Stable IDs**: Use stable, predictable resource IDs
+- **Explicit Versioning**: Version APIs explicitly (`/api/v1`)
+- **Consistent Errors**: Standard error format across all endpoints
+- **Idempotency**: Mutations should be idempotent where applicable
+
+## API Structure
+
+**RESTful Endpoints:**
+- `GET /api/v1/jerseys` - List resources
+- `GET /api/v1/jerseys/:id` - Get single resource
+- `POST /api/v1/jerseys` - Create resource
+- `PATCH /api/v1/jerseys/:id` - Update resource
+- `DELETE /api/v1/jerseys/:id` - Delete resource
+
+**Route Organization:**
+- Group by resource type
+- Use nested routes for relationships
+- Keep routes shallow (max 2-3 levels)
+
+## Error Handling
+
+**Standard Error Format:**
+```json
+{
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "Jersey not found",
+    "details": null
+  }
+}
+```
+
+**Error Codes:**
+- `NOT_FOUND` - Resource doesn't exist
+- `VALIDATION_ERROR` - Input validation failed
+- `UNAUTHORIZED` - Authentication required
+- `FORBIDDEN` - Insufficient permissions
+- `CONFLICT` - Resource conflict
+- `INTERNAL_ERROR` - Server error
+
+**Status Codes:**
+- `200` - Success
+- `201` - Created
+- `204` - No Content
+- `400` - Bad Request
+- `401` - Unauthorized
+- `403` - Forbidden
+- `404` - Not Found
+- `409` - Conflict
+- `500` - Internal Server Error
+
+## Pagination
+
+**Cursor-Based Pagination (Preferred):**
+```
+GET /api/v1/jerseys?limit=20&cursor=abc123
+
+Response:
+{
+  "items": [...],
+  "nextCursor": "def456",
+  "hasMore": true
+}
+```
+
+**Offset Pagination (If Needed):**
+```
+GET /api/v1/jerseys?limit=20&offset=40
+
+Response:
+{
+  "items": [...],
+  "total": 100,
+  "limit": 20,
+  "offset": 40
+}
+```
+
+**Why Cursor-Based:**
+- Stable under concurrent writes
+- Better performance
+- No duplicate/missing items
+
+## Authentication
+
+**Protected Routes:**
+- Verify authentication in all protected routes
+- Extract user ID from token
+- Check permissions before operations
+- Return 401 if unauthenticated, 403 if unauthorized
+
+**Token Verification:**
+- Verify JWT tokens server-side
+- Never trust client-provided user IDs
+- Check token expiration
+- Validate token signature
+
+## Authorization
+
+**Ownership Checks:**
+- Verify user owns resource before operations
+- Check `owner_id === currentUserId`
+- Enforce at service layer, not just API layer
+
+**Permission Checks:**
+- Role-based access control (RBAC) if needed
+- Permission-based access control (PBAC) if needed
+- Document permission requirements
+
+## Response Formats
+
+**Success Responses:**
+- Direct JSON object (no envelope for simplicity)
+- Include all relevant resource data
+- Consistent field naming
+
+**Error Responses:**
+- Standard error format
+- Never leak internal errors
+- Include helpful error messages
+- No stack traces in production
+
+## Versioning
+
+**URL Versioning:**
+- `/api/v1/...` for version 1
+- `/api/v2/...` for version 2
+- Maintain backward compatibility when possible
+- Document breaking changes
+
+## Idempotency
+
+**Idempotent Operations:**
+- Use idempotency keys for mutations
+- Return same result for duplicate requests
+- Handle idempotency at service layer
+
+## Rate Limiting
+
+**Implement Rate Limiting:**
+- Per-user rate limits
+- Per-IP rate limits
+- Return 429 (Too Many Requests) when exceeded
+- Include rate limit headers
+
+## Documentation
+
+**API Documentation:**
+- Document all endpoints
+- Include request/response examples
+- Document error codes
+- Include authentication requirements