SDLC AI Development Prompts

## PHASE 2.1: DATABASE SCHEMA DESIGN ## NourSky CRM — PostgreSQL (Neon Serverless) # ROLE: Senior Database Architect + PostgreSQL Expert # TASK: Design complete schema for a Notion-style block-based CRM system DESIGN PRINCIPLES: → Everything is a BLOCK — workspace, database, page, and content are all blocks → Use JSONB for flexible, schema-less block properties (CRM custom fields) → Apply GIN indexes on JSONB columns for sub-millisecond CRM filtering → Design for horizontal sharding from day 1 (partition by workspace_id) → Use UUID v4 for all primary keys (globally unique, shard-safe) REQUIRED TABLES: 1. workspaces — id, name, slug, theme JSONB, plan, created_at 2. users — id, clerk_user_id, email, display_name, avatar_url 3. workspace_members — workspace_id, user_id, role, joined_at (composite PK) 4. blocks — CORE TABLE (see schema below) 5. templates — id, name, category, blocks_json JSONB, is_public 6. workflow_automations— trigger_type, trigger_config JSONB, action_type, action_config JSONB 7. block_permissions — block_id, subject_type, subject_id, permission_level 8. activity_log — workspace_id, user_id, action, target_block_id, metadata JSONB CORE BLOCKS TABLE SPECIFICATION: CREATE TABLE blocks ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), workspace_id UUID NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE, parent_id UUID REFERENCES blocks(id) ON DELETE CASCADE, type TEXT NOT NULL, -- paragraph|heading_1|page|child_database|... properties JSONB NOT NULL DEFAULT '{}', content UUID[] DEFAULT '{}', -- Ordered array of child block UUIDs created_by UUID NOT NULL REFERENCES users(id), last_edited_by UUID REFERENCES users(id), created_at TIMESTAMPTZ DEFAULT NOW(), updated_at TIMESTAMPTZ DEFAULT NOW(), is_archived BOOLEAN DEFAULT FALSE, is_in_trash BOOLEAN DEFAULT FALSE, cover_url TEXT, icon TEXT -- Emoji or URL ); REQUIRED INDEXES (for performance): → GIN index on blocks.properties (JSONB filtering for CRM views) → BTREE on blocks.workspace_id (all workspace queries) → BTREE on blocks.parent_id (tree traversal) → BTREE on blocks.type (block type filtering) → BTREE on blocks.created_at (sorting by date) POSTGRESQL VIEWS REQUIRED: → v_database_records — Flattens JSONB properties into relational columns → v_kanban_view — Groups records by status property → v_calendar_view — Extracts date properties for calendar rendering → v_workspace_activity — Joins blocks + users for activity feed DELIVERABLE: Write the complete schema.sql migration file with: - All CREATE TABLE statements in dependency order - All indexes (GIN + BTREE) - All PostgreSQL views with ON SELECT DO INSTEAD rules - All ON DELETE CASCADE / SET NULL rules - Seed data: 1 demo workspace, 3 demo users, 10 demo blocks - Comment every column with its purpose Output: /db/migrations/001_initial_schema.sql

## PHASE 2.2: API CONTRACT DESIGN (tRPC + Next.js) # ROLE: Backend API Architect # TASK: Design all tRPC routers and procedures for NourSky CRM TECH STACK: - tRPC v11 with Next.js 14 App Router - Drizzle ORM for type-safe PostgreSQL queries - Clerk middleware for authentication on every procedure - Zod schemas for all input/output validation ROUTER SPECIFICATIONS: workspaceRouter: → create(name, slug) → Workspace → getBySlug(slug) → Workspace + members → updateTheme(workspaceId, theme) → void → inviteMember(workspaceId, email, role) → void → removeMember(workspaceId, userId) → void → getActivityLog(workspaceId, cursor) → paginated ActivityEvent[] blockRouter: → getPage(pageId) → Block tree (recursive) → create(parentId, type, properties, afterId?) → Block → update(blockId, properties) → Block → delete(blockId, permanent?) → void → move(blockId, newParentId, afterId?) → void → duplicate(blockId) → Block → restore(blockId) → void (from trash) → search(workspaceId, query) → Block[] databaseRouter: → getRecords(dbId, view, filters, sorts) → Block[] (paginated) → addProperty(dbId, property) → void → updateProperty(dbId, propId, config) → void → deleteProperty(dbId, propId) → void → updateRecord(recordId, properties) → Block → getKanbanView(dbId, groupBy) → KanbanColumn[] templateRouter: → list(workspaceId, category?) → Template[] → apply(templateId, parentId) → Block (new page) → create(pageId, name, category) → Template → delete(templateId) → void automationRouter: → list(workspaceId) → Automation[] → create(config) → Automation → toggle(automationId, isActive) → void → testRun(automationId) → AutomationResult FOR EACH PROCEDURE, GENERATE: 1. TypeScript function signature with Zod input/output schemas 2. Drizzle ORM query implementation 3. Permission check (Clerk + RBAC middleware) 4. Error handling (404, 403, 500 with typed TRPCError) 5. JSDoc comment Output files: - /server/routers/workspace.ts - /server/routers/block.ts - /server/routers/database.ts - /server/routers/template.ts - /server/routers/automation.ts - /server/root.ts (merge all routers)

## PHASE 3: PROJECT ARCHITECTURE SETUP ## NourSky CRM Workspace — Full Stack Scaffold # ROLE: Senior DevOps + Full-Stack Architecture Engineer # TASK: Initialize the complete project from zero. Execute all terminal commands. STEP 1 — Initialize Next.js App: npx create-next-app@latest noursky-workspace \ --typescript --tailwind --eslint --app --src-dir \ --import-alias "@/*" STEP 2 — Install ALL Dependencies: # Editor npm install @blocknote/react @blocknote/core @blocknote/mantine npm install yjs @hocuspocus/provider y-protocols # UI npm install @mantine/core @mantine/hooks @mantine/dates @mantine/notifications npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities npm install recharts date-fns lucide-react # Backend npm install @trpc/server @trpc/client @trpc/react-query @tanstack/react-query npm install drizzle-orm drizzle-kit @neondatabase/serverless npm install zod superjson # Auth npm install @clerk/nextjs @clerk/backend # State npm install zustand immer # Dev tools npm install -D @hocuspocus/server ws @types/ws npm install -D prettier eslint-config-prettier husky lint-staged npm install -D @playwright/test vitest @vitejs/plugin-react STEP 3 — Project Directory Structure (create exactly this): src/ ├── app/ │ ├── (auth)/sign-in/page.tsx │ ├── (auth)/sign-up/page.tsx │ ├── (workspace)/layout.tsx │ ├── (workspace)/[workspaceSlug]/page.tsx │ ├── (workspace)/[workspaceSlug]/settings/page.tsx │ ├── (workspace)/[workspaceSlug]/themes/page.tsx │ ├── (workspace)/[workspaceSlug]/templates/page.tsx │ ├── (workspace)/[workspaceSlug]/crm/[dbId]/page.tsx │ ├── (workspace)/[workspaceSlug]/page/[pageId]/page.tsx │ └── api/trpc/[trpc]/route.ts ├── components/ │ ├── editor/ (BlockNote editor components) │ ├── crm/ (Table, Kanban, Calendar, Gallery, Timeline) │ ├── sidebar/ (Navigation, workspace switcher) │ ├── theme/ (Theme editor, preset selector) │ └── ui/ (Shared Mantine-based components) ├── server/ │ ├── routers/ (tRPC routers: workspace, block, database, template) │ ├── root.ts (Merge all routers) │ └── trpc.ts (Context + middleware) ├── db/ │ ├── schema.ts (Drizzle schema definitions) │ ├── migrations/ (SQL migration files) │ └── index.ts (Neon connection) ├── lib/ │ ├── auth.ts (Clerk helpers) │ ├── permissions.ts (RBAC logic) │ └── utils.ts └── store/ (Zustand stores) STEP 4 — Configure Environment Variables: Create .env.local with all required variables (DB, Clerk, R2, Redis, WS_URL). Create .env.example with placeholder values — no real secrets. STEP 5 — Configure Drizzle ORM: - Write src/db/schema.ts matching the PostgreSQL schema from Phase 2 - Run: npx drizzle-kit generate:pg - Run: npx drizzle-kit push:pg STEP 6 — Configure Clerk Middleware: - Create middleware.ts at project root with Clerk auth on all workspace routes - Set up Clerk webhook endpoint at /api/webhooks/clerk to sync users to DB STEP 7 — Quality Gates: - Configure ESLint with @typescript-eslint/recommended - Configure Prettier (semi: true, singleQuote: true, tabWidth: 2) - Set up Husky pre-commit hook: lint-staged runs ESLint + Prettier on staged files - Configure path aliases: "@/*" → "src/*" VERIFY SUCCESS: → npm run dev → app loads at localhost:3000 → Clerk sign-in page renders correctly → npx drizzle-kit studio → DB browser opens → npm run lint → zero errors Output: Working Next.js 14 app with all dependencies and DB connected.

## PHASE 4.1: BLOCK EDITOR + REAL-TIME COLLABORATION # ROLE: Senior Frontend Engineer (BlockNote + Yjs Expert) # TASK: Implement the complete block editor with multiplayer sync 4.1.A — Custom Block Schema Registration: Create src/components/editor/schema.ts: - Import defaultBlockSpecs from @blocknote/core - Define 5 custom CRM block types using createReactBlockSpec: crm_lead_card: propSchema { contactName, email, phone, leadScore, status, assignedTo } crm_kanban_embed: propSchema { databaseId, groupByProperty } crm_relation_chip: propSchema { targetBlockId, targetTitle, targetIcon } crm_property_viewer: propSchema { blockId, visibleProperties[] } crm_metric_card: propSchema { label, value, trend, color } - Each block renders as a styled React component using Mantine - Export as: BlockNoteSchema.create({ blockSpecs: { ...defaultBlockSpecs, ...customBlocks } }) 4.1.B — Hocuspocus WebSocket Server: Create server/hocuspocus.ts: - Initialize HocuspocusServer with: - onAuthenticate: validate Clerk JWT from WebSocket handshake header - onConnect: log connection, check workspace membership - onDisconnect: clean up user presence - onChange: persist YDoc snapshot to blocks table via tRPC - Export as Cloudflare Worker compatible handler 4.1.C — Main Editor Component: Create src/components/editor/BlockEditor.tsx: - HocuspocusProvider connection to process.env.NEXT_PUBLIC_WS_URL - useCreateBlockNote with collaboration: { provider, fragment, user } - BlockNoteView with: - formattingToolbar: true - slashMenu: true (add custom CRM blocks to slash menu) - sideMenu: true (drag handle) - imageToolbar: true - Handle provider.status: show connecting/connected/offline indicator - Auto-save: debounced 500ms on onChange → trpc.block.update.mutate() 4.1.D — Presence Cursors: - Read provider.awareness to get all connected users - Render colored cursor overlays with user names - Assign unique colors from a predefined palette per user 4.1.E — Page Shell Component: Create src/components/editor/PageEditor.tsx: - Editable page title (large input, synced as block property) - Editable page icon (emoji picker on click) - Cover image upload (Cloudflare R2 presigned URL) - Last edited info (user + relative time) - Render BlockEditor below the title TESTING CHECKPOINT: → Open same page in 2 browser tabs → Type in tab 1 → text appears in tab 2 within 100ms → Both cursors visible with correct user colors → Disconnect tab 1 → type → reconnect → changes merge correctly Output files: schema.ts, BlockEditor.tsx, PageEditor.tsx, hocuspocus.ts

## PHASE 4.2: CRM DATABASE VIEWS (Kanban + Table + Calendar) # ROLE: Senior React Engineer specializing in data visualization # TASK: Build all CRM database views with full interactivity 4.2.A — Kanban Board (src/components/crm/KanbanView.tsx): → Use @dnd-kit/core + @dnd-kit/sortable for drag-and-drop → Fetch records via trpc.database.getKanbanView.useQuery(dbId, groupBy) → Render columns from Select property options (e.g. New/In Progress/Won/Lost) → Each card shows: title, assignee avatar, date, tag chips, priority badge → Drag card across columns → optimistic UI update → trpc.database.updateRecord.mutate() → "Add record" button at bottom of each column → Column header: option name + count chip + color dot → Click card → open record detail drawer (side panel) 4.2.B — Table View (src/components/crm/TableView.tsx): → Virtualized rows using @tanstack/react-virtual (handles 10k+ records) → Resizable columns using CSS resize handle → Inline cell editing: click cell → renders appropriate input by property type → Multi-row select via checkbox column → Header click → sort (ASC/DESC toggle) → "Filter" button → opens filter panel (property + operator + value) → "Group by" button → groups rows with collapsible headers → "+" column header → open "Add property" modal → Row click → open record detail drawer 4.2.C — Calendar View (src/components/crm/CalendarView.tsx): → Monthly/weekly/daily toggle tabs → Plot records using their Date property → Color-code events by Select property (e.g. status) → Drag event to new date → update Date property → Click day slot → create new record with that date pre-filled → Click event → open record detail drawer 4.2.D — Record Detail Drawer: → Slide-in panel from right (400px wide) → Top: editable title + icon + cover image → Properties section: render all schema properties with correct input types → Below properties: embedded BlockNote editor for record notes/content → Relations section: show linked records as chips with link → Activity timeline: last edits, comments, automation events 4.2.E — Property Editor Modal: → "+" → Add property modal: type selector (14 types with icons) → Each type shows its specific config (Select: add/edit/reorder/color options) → Saves to database block's properties JSONB schema field Output files: KanbanView.tsx, TableView.tsx, CalendarView.tsx, RecordDrawer.tsx, PropertyEditor.tsx

## PHASE 5: E2E TEST SUITE — Playwright ## QA Agent: Execute all tests against preview deployment URL # ROLE: QA Automation Engineer (Playwright Expert) # TASK: Write and run comprehensive E2E test suite for NourSky CRM SETUP: npx playwright install --with-deps chromium firefox webkit BASE_URL = process.env.PLAYWRIGHT_BASE_URL || 'http://localhost:3000' TEST SUITE 1 — Authentication (tests/auth.spec.ts): → test: User can sign up with email/password → test: User can sign in with existing credentials → test: Protected routes redirect unauthenticated users to /sign-in → test: User is redirected to workspace after successful login → test: Sign out clears session and redirects to homepage TEST SUITE 2 — Block Editor (tests/editor.spec.ts): → test: New page renders empty editor with placeholder text → test: User types text and it saves automatically (debounced) → test: Slash (/) menu opens on "/" keypress and lists all block types → test: Inserting H1 block renders with correct heading styling → test: Drag handle appears on block hover → test: Image upload block — uploads file and renders preview → test: To-do block — clicking checkbox marks it complete → test: Toggle block — click expands/collapses children TEST SUITE 3 — Real-Time Sync (tests/collaboration.spec.ts): → Use 2 browser contexts (simulating 2 users) → test: User A types "Hello" → appears in User B's editor within 500ms → test: User A's cursor is visible in User B's editor with correct color → test: User A goes offline → types → reconnects → changes merge in User B → test: Simultaneous edits on same block do not cause data loss TEST SUITE 4 — CRM Kanban (tests/kanban.spec.ts): → test: CRM database renders Kanban view with columns from Select property → test: Drag card from "New" column to "In Progress" → status updates → test: Click card → Record drawer opens with correct data → test: Edit property in drawer → saves and Kanban card updates → test: Add new record via column "+" button → appears in correct column → test: Filter by assignee → only matching cards visible TEST SUITE 5 — Theming (tests/theme.spec.ts): → test: Toggle dark mode → background color changes correctly → test: Apply "Deep Ocean" preset → primary color CSS var updated → test: Custom theme: set primaryColor to #FF0000 → buttons turn red → test: Theme persists after page reload (stored in DB) TEST SUITE 6 — Templates (tests/templates.spec.ts): → test: Template library shows all 8 built-in templates → test: Apply "Client Onboarding Pipeline" → new page with blocks appears → test: Save current page as template → appears in template library PERFORMANCE AUDIT: npx playwright test --project=chromium tests/perf.spec.ts → Run Lighthouse audit via playwright-lighthouse → Assert: Performance score ≥ 90 → Assert: FCP < 1500ms → Assert: LCP < 2500ms → Assert: CLS < 0.1 → Assert: TBT < 300ms FINAL REPORT: Generate HTML test report: npx playwright show-report All tests must PASS before triggering deployment pipeline. On failure: output failing test name + screenshot + error to STDOUT. Output: tests/ directory with all .spec.ts files + playwright.config.ts

## PHASE 6: PRODUCTION DEPLOYMENT ## NourSky CRM Workspace — Vercel + Cloudflare # ROLE: DevOps / Platform Engineer # TASK: Deploy complete system to production. Execute all commands. STEP 1 — Vercel Deployment (Next.js Frontend): npm install -g vercel vercel login vercel --prod Configure in Vercel Dashboard: → Project name: noursky-workspace → Framework: Next.js → Build command: npm run build → Output directory: .next → Node.js version: 20.x → Add ALL environment variables from .env.local → Custom domain: workspace.noursky.com (if available) Enable Vercel features: → Vercel Analytics: ON (Core Web Vitals tracking) → Image Optimization: ON → Preview Deployments: ON (auto-deploy every PR) → Speed Insights: ON STEP 2 — Cloudflare Worker (Hocuspocus WebSocket): npm install -g wrangler wrangler login Create wrangler.toml: name = "noursky-sync" main = "server/hocuspocus.worker.ts" compatibility_date = "2025-01-01" [vars] HOCUSPOCUS_SECRET = "..." wrangler deploy → Worker URL: https://noursky-sync.workers.dev → Update NEXT_PUBLIC_WS_URL in Vercel env vars to this URL Enable Cloudflare features: → WebSocket support: ON (automatic with Workers) → Durable Objects: for per-document state if needed STEP 3 — Neon Database Production Config: → Create production branch in Neon dashboard → Run all migrations: npx drizzle-kit push:pg --env production → Enable connection pooling (PgBouncer mode in Neon) → Set max connections: 100 → Enable point-in-time recovery (30 days) STEP 4 — GitHub Actions CI/CD Pipeline: Create .github/workflows/deploy.yml: on: push: branches: [main] jobs: test: - npm ci - npm run lint - npm run type-check - npm run test:unit - npx playwright test (against preview URL) - lighthouse-ci (assert thresholds) deploy: needs: test - vercel --prod --token $VERCEL_TOKEN - wrangler deploy --env production STEP 5 — Monitoring & Observability: → Sentry.io: npm install @sentry/nextjs - Capture frontend errors + tRPC errors - Set alert: error rate > 1% → email + Slack → Uptime monitoring: BetterUptime or Checkly - Ping /api/health every 60s - Alert on downtime > 30s → Neon monitoring: enable query insights dashboard STEP 6 — Post-Deploy Verification Checklist: → ✓ Production URL loads in < 2s → ✓ Clerk auth flow works on production domain → ✓ Create new workspace → saves to Neon DB → ✓ Open page in 2 browsers → real-time sync works → ✓ Upload image → appears from Cloudflare R2 CDN URL → ✓ Sentry captures a test error event → ✓ Lighthouse score ≥ 90 on production URL Result: Live web application at workspace.noursky.com

## MAINTENANCE: BUG FIX PROTOCOL ## NourSky CRM — [Replace with actual bug description] # ROLE: Senior Debugging Engineer # TASK: Investigate, fix, and verify the reported bug BUG REPORT: Title: [Bug title — e.g. "Kanban cards disappear after drag on Safari"] Severity: [Critical / High / Medium / Low] Reported by: [User role — e.g. "Admin user"] Steps to reproduce: 1. [Step 1] 2. [Step 2] 3. [Step 3 — observed behavior] Expected: [What should happen] Actual: [What actually happens] Environment: [Browser + OS + user's workspace slug] Sentry ID: [Error ID from Sentry dashboard] INVESTIGATION PROTOCOL: → Step 1: Reproduce the bug locally using exact steps above → Step 2: Check Sentry for full stack trace and affected user count → Step 3: Identify root cause (frontend / backend / database / network) → Step 4: Write a failing unit test that captures the bug → Step 5: Implement the fix in minimum lines of code → Step 6: Verify the previously failing test now passes → Step 7: Run full Playwright test suite — zero regressions allowed → Step 8: Deploy fix to Vercel preview URL for manual QA verification → Step 9: Merge to main → auto-deploy to production OUTPUT FORMAT: Root Cause: [1-2 sentence explanation of what caused the bug] Fix Applied: [File(s) changed and what changed] Test Added: [Test file and test name that covers the fix] Regression Risk: [Low/Medium/High — explain why] ## FEATURE ADDITION PROMPT TEMPLATE: NEW FEATURE REQUEST: Feature: [e.g. "Add CSV import to CRM Table View"] Priority: [Must Have / Should Have / Nice to Have] Context: [Why the team needs this feature] AGENT INSTRUCTIONS: → Write user stories + acceptance criteria for this feature → Design the technical implementation (API changes, DB changes, UI) → Implement in a new git branch: feature/[feature-name] → Write Playwright tests for all acceptance criteria → Open PR with description: what changed, why, how to test → All tests must pass before requesting merge ## DATABASE MIGRATION TEMPLATE: SAFE MIGRATION PROTOCOL (zero-downtime): 1. Write migration SQL in /db/migrations/00X_description.sql 2. Test migration on Neon staging branch first 3. Use only additive changes: ADD COLUMN, CREATE INDEX CONCURRENTLY 4. NEVER: DROP COLUMN, RENAME COLUMN without a multi-step migration 5. Run: npx drizzle-kit push:pg --env staging → verify no data loss 6. Run: npx drizzle-kit push:pg --env production during low-traffic window Standing rule: All maintenance changes must pass full Playwright suite before merge.