workflow-agent-cli 1.1.2

package/templates/DEPLOYMENT_STRATEGY.md

@@ -0,0 +1,509 @@
+# Deployment Strategy
+
+> **Purpose**: This document defines the deployment workflow, environment management, database migration strategy, and rollback procedures for ProjectHub.
+
+---
+
+## Table of Contents
+
+1. [Deployment Overview](#deployment-overview)
+2. [Environments](#environments)
+3. [Environment Variables](#environment-variables)
+4. [Deployment Workflow](#deployment-workflow)
+5. [Database Migrations](#database-migrations)
+6. [Preview Deployments](#preview-deployments)
+7. [Production Deployment](#production-deployment)
+8. [Rollback Procedures](#rollback-procedures)
+9. [Monitoring](#monitoring)
+
+---
+
+## Deployment Overview
+
+ProjectHub uses **Vercel** for deployment with the following architecture:
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│   Git Push      │────▶│  Vercel Build    │────▶│  Deployment     │
+│   (GitHub)      │     │  (Next.js)       │     │  (Edge Network) │
+└─────────────────┘     └──────────────────┘     └─────────────────┘
+                                                           │
+                                                           ▼
+                                                 ┌─────────────────┐
+                                                 │   Supabase      │
+                                                 │   (PostgreSQL)  │
+                                                 └─────────────────┘
+```
+
+### Key Components
+
+| Component      | Platform      | Purpose                                     |
+| -------------- | ------------- | ------------------------------------------- |
+| Frontend + API | Vercel        | Next.js app, server actions, edge functions |
+| Database       | Supabase      | PostgreSQL, RLS, real-time subscriptions    |
+| Auth           | Supabase Auth | Session management, OAuth providers         |
+| CDN            | Vercel Edge   | Static assets, caching                      |
+
+---
+
+## Environments
+
+### Environment Types
+
+| Environment | Branch           | Purpose              | URL Pattern                    |
+| ----------- | ---------------- | -------------------- | ------------------------------ |
+| Production  | `main`           | Live application     | `projecthub.vercel.app`        |
+| Preview     | Feature branches | PR previews, testing | `projecthub-<hash>.vercel.app` |
+| Local       | N/A              | Development          | `localhost:3000`               |
+
+### Supabase Projects
+
+| Environment | Supabase Project     | Purpose                |
+| ----------- | -------------------- | ---------------------- |
+| Production  | `projecthub-prod`    | Live data              |
+| Staging     | `projecthub-staging` | Pre-production testing |
+| Local       | Local Docker         | Development            |
+
+---
+
+## Environment Variables
+
+### Required Variables
+
+| Variable                        | Description              | Source                              |
+| ------------------------------- | ------------------------ | ----------------------------------- |
+| `NEXT_PUBLIC_SUPABASE_URL`      | Supabase project URL     | Supabase Dashboard → Settings → API |
+| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase public anon key | Supabase Dashboard → Settings → API |
+
+### Optional Variables
+
+| Variable                    | Description                    | Default                   |
+| --------------------------- | ------------------------------ | ------------------------- |
+| `NEXT_PUBLIC_APP_URL`       | Application URL                | Auto-detected by Vercel   |
+| `SUPABASE_SERVICE_ROLE_KEY` | Server-side Supabase admin key | Only for admin operations |
+
+### Secret Management
+
+1. **Never commit secrets** to the repository
+2. **Use Vercel environment variables** for all secrets
+3. **Scope secrets by environment**:
+   - Production: Only production values
+   - Preview: Staging or development values
+   - Development: Local `.env.local` file
+
+### Setting Environment Variables
+
+```bash
+# Via Vercel CLI
+vercel env add NEXT_PUBLIC_SUPABASE_URL production
+vercel env add NEXT_PUBLIC_SUPABASE_URL preview
+
+# Or via Vercel Dashboard
+# Project → Settings → Environment Variables
+```
+
+---
+
+## Deployment Workflow
+
+### Standard Flow (Feature Branch)
+
+```
+1. Developer creates branch
+   └── feature/tasks/add-reminder
+
+2. Developer pushes changes
+   └── git push origin feature/tasks/add-reminder
+
+3. Vercel creates preview deployment
+   └── https://projecthub-abc123.vercel.app
+
+4. Developer creates PR
+   └── Title: feat(tasks): add reminder functionality
+
+5. Automated checks run
+   ├── Vercel build (Next.js compile)
+   ├── GitHub Actions (if configured)
+   └── Preview URL available
+
+6. Review and approval
+   └── Code review, manual testing on preview
+
+7. Merge to main
+   └── Squash and merge
+
+8. Production deployment
+   └── Automatic on merge to main
+```
+
+### Deployment Triggers
+
+| Trigger                | Environment | Automatic    |
+| ---------------------- | ----------- | ------------ |
+| Push to feature branch | Preview     | ✅ Yes       |
+| PR created/updated     | Preview     | ✅ Yes       |
+| Merge to `main`        | Production  | ✅ Yes       |
+| Manual via CLI         | Any         | ✅ On-demand |
+
+---
+
+## Database Migrations
+
+### Migration File Location
+
+```
+supabase/
+└── migrations/
+    ├── 001_initial_schema.sql
+    ├── 002_add_sprints.sql
+    └── 003_add_notifications.sql
+```
+
+### Creating Migrations
+
+```bash
+# Create new migration file
+touch supabase/migrations/$(date +%Y%m%d%H%M%S)_description.sql
+
+# Or using Supabase CLI
+supabase migration new add_feature_table
+```
+
+### Migration File Format
+
+```sql
+-- supabase/migrations/20260108120000_add_due_date_reminders.sql
+
+-- Description: Add due date reminder functionality
+-- Author: Developer Name
+-- Date: 2026-01-08
+
+-- Up Migration
+CREATE TABLE IF NOT EXISTS task_reminders (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    task_id UUID REFERENCES tasks(id) ON DELETE CASCADE,
+    remind_at TIMESTAMPTZ NOT NULL,
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Enable RLS
+ALTER TABLE task_reminders ENABLE ROW LEVEL SECURITY;
+
+-- RLS Policies
+CREATE POLICY "Users can manage their task reminders"
+ON task_reminders
+FOR ALL
+USING (
+    task_id IN (
+        SELECT id FROM tasks WHERE assignee = auth.uid()
+    )
+);
+
+-- ============================================
+-- ROLLBACK SQL (Keep at bottom of file)
+-- ============================================
+-- DROP POLICY IF EXISTS "Users can manage their task reminders" ON task_reminders;
+-- DROP TABLE IF EXISTS task_reminders;
+```
+
+### Running Migrations
+
+#### Local Development
+
+```bash
+# Start local Supabase
+supabase start
+
+# Run pending migrations
+supabase db push
+
+# Reset database (warning: destroys data)
+supabase db reset
+```
+
+#### Staging/Production
+
+```bash
+# Link to Supabase project
+supabase link --project-ref your-project-ref
+
+# Push migrations to remote
+supabase db push
+
+# Or run manually in SQL Editor (Supabase Dashboard)
+```
+
+### Migration Checklist
+
+Before deploying a migration:
+
+- [ ] **Test locally** with `supabase db push`
+- [ ] **Include rollback SQL** in migration file
+- [ ] **Update types** - regenerate `types/supabase.ts`
+- [ ] **Check RLS policies** - ensure security
+- [ ] **Test with sample data** - verify queries work
+- [ ] **Document breaking changes** - if any
+
+### Dual-Database Migration (REQUIRED)
+
+> **⚠️ MANDATORY**: All migrations MUST be run on both dev and prod databases.
+
+**Preferred Method (Automated):**
+
+```bash
+# Runs dev first, then prod (stops on dev failure)
+./scripts/db.sh migrate-both
+```
+
+**Manual Method (Step-by-Step):**
+
+```bash
+# Step 1: Run on DEV
+./scripts/db.sh link dev
+./scripts/db.sh migrate
+./scripts/db.sh status   # ✓ Verify migration applied
+
+# Step 2: Run on PROD (only if dev succeeded)
+./scripts/db.sh link prod
+./scripts/db.sh migrate
+./scripts/db.sh status   # ✓ Verify migration applied
+```
+
+**Migration Execution Checklist:**
+
+- [ ] DEV migration executed successfully
+- [ ] DEV migration status verified (`./scripts/db.sh status`)
+- [ ] PROD migration executed successfully
+- [ ] PROD migration status verified (`./scripts/db.sh status`)
+
+---
+
+## Preview Deployments
+
+### Automatic Preview URLs
+
+Every PR gets an automatic preview deployment:
+
+```
+https://projecthub-<hash>-<team>.vercel.app
+```
+
+### Preview Environment Configuration
+
+Preview deployments use:
+
+- **Preview environment variables** (from Vercel)
+- **Staging Supabase project** (recommended) OR
+- **Production Supabase** with read-only access
+
+### Testing on Preview
+
+1. Click preview URL in PR
+2. Test the specific feature
+3. Verify no regressions
+4. Check mobile responsiveness
+5. Test authentication flow
+
+### Preview Deployment Limitations
+
+- Preview deployments expire after inactivity
+- Database changes require separate staging environment
+- Real-time features may behave differently
+
+---
+
+## Production Deployment
+
+### Pre-Deployment Checklist
+
+Before merging to `main`:
+
+- [ ] All tests pass (`pnpm test`)
+- [ ] TypeScript compiles (`pnpm typecheck`)
+- [ ] Linting passes (`pnpm lint`)
+- [ ] PR approved by required reviewers
+- [ ] Preview deployment tested
+- [ ] Database migrations tested (if any)
+- [ ] Environment variables set in Vercel
+- [ ] No breaking changes (or documented)
+
+### Deployment Process
+
+```bash
+# Automatic: Just merge PR to main
+# Vercel automatically deploys on merge
+
+# Manual: Using Vercel CLI
+vercel --prod
+
+# Manual: Using GitHub
+# 1. Go to Actions tab
+# 2. Run "Deploy to Production" workflow
+```
+
+### Post-Deployment Verification
+
+After deployment:
+
+- [ ] Verify production URL is accessible
+- [ ] Test critical paths (login, create task, etc.)
+- [ ] Check Vercel function logs for errors
+- [ ] Monitor Supabase dashboard for issues
+- [ ] Verify real-time subscriptions work
+
+---
+
+## Rollback Procedures
+
+### When to Rollback
+
+- Critical bug affecting all users
+- Security vulnerability discovered
+- Database corruption
+- Performance degradation
+
+### Application Rollback (Vercel)
+
+#### Via Dashboard
+
+1. Go to Vercel Dashboard → Project → Deployments
+2. Find the last working deployment
+3. Click "..." menu → "Promote to Production"
+
+#### Via CLI
+
+```bash
+# List recent deployments
+vercel ls
+
+# Rollback to specific deployment
+vercel rollback <deployment-url>
+```
+
+### Database Rollback
+
+#### If Migration Included Rollback SQL
+
+```sql
+-- Run the rollback SQL from the migration file
+-- Usually commented at the bottom
+
+DROP POLICY IF EXISTS "Users can manage their task reminders" ON task_reminders;
+DROP TABLE IF EXISTS task_reminders;
+```
+
+#### If No Rollback SQL (Emergency)
+
+1. **Restore from backup** (Supabase Dashboard → Settings → Backups)
+2. Or **manually reverse changes** using SQL Editor
+
+### Rollback Checklist
+
+- [ ] Identify the issue and scope
+- [ ] Notify team of rollback
+- [ ] Execute rollback (app and/or database)
+- [ ] Verify rollback successful
+- [ ] Document what went wrong
+- [ ] Create fix and re-deploy
+
+---
+
+## Monitoring
+
+### Vercel Monitoring
+
+| Metric            | Location         | Action Threshold |
+| ----------------- | ---------------- | ---------------- |
+| Build Time        | Deployments tab  | > 5 minutes      |
+| Function Duration | Functions tab    | > 10 seconds     |
+| Function Errors   | Functions → Logs | Any error        |
+| Edge Latency      | Analytics        | > 500ms          |
+
+### Supabase Monitoring
+
+| Metric             | Location              | Action Threshold |
+| ------------------ | --------------------- | ---------------- |
+| Database Size      | Settings → Billing    | 80% of limit     |
+| Active Connections | Database → Roles      | 80% of limit     |
+| API Requests       | Settings → Billing    | Unusual spikes   |
+| Auth Events        | Authentication → Logs | Failed attempts  |
+
+### Recommended Integrations
+
+| Service          | Purpose                       |
+| ---------------- | ----------------------------- |
+| Sentry           | Error tracking, stack traces  |
+| Vercel Analytics | Web vitals, performance       |
+| Supabase Logs    | Database queries, auth events |
+
+### Setting Up Error Alerts
+
+```bash
+# Add Sentry (optional)
+pnpm add @sentry/nextjs
+
+# Configure in sentry.client.config.ts
+# Configure in sentry.server.config.ts
+# Add SENTRY_DSN to environment variables
+```
+
+---
+
+## Quick Reference
+
+### Deploy Commands
+
+```bash
+# Local development
+pnpm dev
+
+# Build locally
+pnpm build
+
+# Deploy to preview
+vercel
+
+# Deploy to production
+vercel --prod
+
+# Check deployment status
+vercel ls
+```
+
+### Migration Commands
+
+```bash
+# Start local Supabase
+supabase start
+
+# Run migrations locally
+supabase db push
+
+# Generate types
+supabase gen types typescript --local > types/supabase.ts
+
+# Link to remote project
+supabase link --project-ref <ref>
+
+# Push migrations to remote
+supabase db push
+```
+
+### Rollback Commands
+
+```bash
+# Rollback to previous deployment
+vercel rollback
+
+# Rollback to specific deployment
+vercel rollback <deployment-url>
+```
+
+---
+
+## Related Documents
+
+- [VERCEL_DEPLOYMENT_GUIDE.md](../VERCEL_DEPLOYMENT_GUIDE.md) - Initial setup guide
+- [BRANCHING_STRATEGY.md](BRANCHING_STRATEGY.md) - Branch and PR workflow
+- [TESTING_STRATEGY.md](TESTING_STRATEGY.md) - Testing requirements
+- [SINGLE_SOURCE_OF_TRUTH.md](SINGLE_SOURCE_OF_TRUTH.md) - Service locations

package/templates/Guidelines.md

@@ -0,0 +1,62 @@
+**Add your own guidelines here**
+
+<!--
+
+System Guidelines
+
+Use this file to provide the AI with rules and guidelines you want it to follow.
+This template outlines a few examples of things you can add. You can add your own sections and format it to suit your needs
+
+TIP: More context isn't always better. It can confuse the LLM. Try and add the most important rules you need
+
+# General guidelines
+
+Any general rules you want the AI to follow.
+For example:
+
+* Only use absolute positioning when necessary. Opt for responsive and well structured layouts that use flexbox and grid by default
+* Refactor code as you go to keep code clean
+* Keep file sizes small and put helper functions and components in their own files.
+
+--------------
+
+# Design system guidelines
+Rules for how the AI should make generations look like your company's design system
+
+Additionally, if you select a design system to use in the prompt box, you can reference
+your design system's components, tokens, variables and components.
+For example:
+
+* Use a base font-size of 14px
+* Date formats should always be in the format “Jun 10”
+* The bottom toolbar should only ever have a maximum of 4 items
+* Never use the floating action button with the bottom toolbar
+* Chips should always come in sets of 3 or more
+* Don't use a dropdown if there are 2 or fewer options
+
+You can also create sub sections and add more specific details
+For example:
+
+
+## Button
+The Button component is a fundamental interactive element in our design system, designed to trigger actions or navigate
+users through the application. It provides visual feedback and clear affordances to enhance user experience.
+
+### Usage
+Buttons should be used for important actions that users need to take, such as form submissions, confirming choices,
+or initiating processes. They communicate interactivity and should have clear, action-oriented labels.
+
+### Variants
+* Primary Button
+  * Purpose : Used for the main action in a section or page
+  * Visual Style : Bold, filled with the primary brand color
+  * Usage : One primary button per section to guide users toward the most important action
+* Secondary Button
+  * Purpose : Used for alternative or supporting actions
+  * Visual Style : Outlined with the primary color, transparent background
+  * Usage : Can appear alongside a primary button for less important actions
+* Tertiary Button
+  * Purpose : Used for the least important actions
+  * Visual Style : Text-only with no border, using primary color
+  * Usage : For actions that should be available but not emphasized
+-->