@polymorphism-tech/morph-spec 3.0.0 → 3.1.0

package/stacks/nextjs-supabase/.morph/config/agents.json

@@ -0,0 +1,345 @@
+{
+  "$schema": "./agent-schema.json",
+  "version": "3.0.0-hierarchical",
+  "stack": "nextjs-supabase",
+  "total_agents": 12,
+  "tiers": {
+    "tier_1_orchestrators": 1,
+    "tier_2_leaders": 2,
+    "tier_3_specialists": 8,
+    "tier_4_validators": 1
+  },
+
+  "agents": {
+
+    "_comment_tier_1": "=== TIER 1: ORCHESTRATORS (1) ===",
+
+    "standards-architect": {
+      "tier": 1,
+      "role": "orchestrator",
+      "title": "Chief Architect",
+      "domains": ["architecture", "developer-experience"],
+      "keywords": [],
+      "always_active": true,
+      "validators": ["architecture", "packages"],
+      "relationships": {
+        "reports_to": "user",
+        "coordinates": ["dotnet-senior", "supabase-expert", "nextjs-expert", "testing-specialist", "ui-ux-designer"],
+        "escalates_to": "user",
+        "team_role": "lead"
+      },
+      "standards": ["coding.md", "architecture.md", "nextjs-patterns.md", "supabase-auth.md", "supabase-rls.md"],
+      "teammate": {
+        "role": "Team Lead (Delegate Mode)",
+        "icon": "T",
+        "spawn_prompt": "You are the Chief Architect and Team Lead in delegate mode. Coordinate specialists, resolve conflicts, synthesize results. DO NOT implement code yourself. Escalate conflicts to user when teammates disagree on architecture/tech choices."
+      }
+    },
+
+    "_comment_tier_2": "=== TIER 2: DOMAIN LEADERS (2) ===",
+
+    "dotnet-senior": {
+      "tier": 2,
+      "role": "domain-leader",
+      "title": "Backend Squad Leader",
+      "domains": ["backend"],
+      "keywords": ["backend", "api", "dotnet", ".net", "csharp", "c#", "minimal api", "endpoint", "dapper", "npgsql"],
+      "always_active": true,
+      "validators": ["architecture", "packages"],
+      "relationships": {
+        "reports_to": "standards-architect",
+        "coordinates": ["api-designer", "testing-specialist"],
+        "escalates_to": "standards-architect",
+        "collaborates_with": ["supabase-expert", "nextjs-expert", "container-specialist"],
+        "team_role": "domain_leader"
+      },
+      "standards": ["coding.md", "architecture.md"],
+      "teammate": {
+        "role": "Backend Squad Leader",
+        "icon": "B",
+        "spawn_prompt": "You are the Backend Squad Leader. .NET 10 Minimal API with Npgsql + Dapper (NOT EF Core). Coordinate backend specialists. Validate Supabase JWT tokens in API middleware. Assign tasks, review designs, enforce backend standards. Escalate cross-domain conflicts to standards-architect."
+      }
+    },
+
+    "ui-ux-designer": {
+      "tier": 2,
+      "role": "domain-leader",
+      "title": "UI/UX Squad Leader",
+      "domains": ["frontend-design"],
+      "keywords": ["wireframe", "mockup", "user flow", "ux", "design", "interface design", "user experience", "page", "dashboard", "form", "UI", "screen", "panel"],
+      "always_active": false,
+      "validators": ["design-system", "contrast"],
+      "relationships": {
+        "reports_to": "standards-architect",
+        "coordinates": ["nextjs-expert", "css-specialist"],
+        "escalates_to": "standards-architect",
+        "collaborates_with": ["dotnet-senior"],
+        "team_role": "domain_leader",
+        "active_phases": ["uiux"]
+      },
+      "standards": ["css-naming.md", "nextjs-patterns.md"],
+      "teammate": {
+        "role": "UI/UX Squad Leader",
+        "icon": "U",
+        "spawn_prompt": "You are the UI/UX Squad Leader. Create wireframes, mockups, user flows. Define design system (colors, typography, spacing) using Tailwind CSS tokens. Coordinate with nextjs-expert and css-specialist for implementation. Work is AGNOSTIC (no implementation code)."
+      }
+    },
+
+    "_comment_tier_3": "=== TIER 3: SPECIALISTS (8) ===",
+
+    "nextjs-expert": {
+      "tier": 3,
+      "role": "specialist",
+      "title": "Next.js Development Specialist",
+      "domains": ["frontend-nextjs"],
+      "keywords": ["nextjs", "next.js", "react", "frontend", "shadcn", "server components", "server actions", "app router", "tanstack"],
+      "always_active": false,
+      "validators": ["packages", "css", "design-system"],
+      "relationships": {
+        "reports_to": "ui-ux-designer",
+        "coordinates": [],
+        "escalates_to": "standards-architect",
+        "collaborates_with": ["api-designer", "css-specialist", "supabase-expert"],
+        "team_role": "specialist",
+        "active_phases": ["uiux", "implement"]
+      },
+      "standards": ["coding.md", "nextjs-patterns.md"],
+      "teammate": {
+        "role": "Next.js Development Specialist",
+        "icon": "N",
+        "spawn_prompt": "You are the Next.js 15 Development Specialist. Build App Router pages with shadcn/ui components. Use @supabase/ssr for auth (NOT Clerk). Implement Server Components, Server Actions, Route Handlers. Use TanStack Query for client-side data fetching. Message api-designer for backend endpoints."
+      }
+    },
+
+    "api-designer": {
+      "tier": 3,
+      "role": "specialist",
+      "title": "API Design Specialist",
+      "domains": ["backend-api"],
+      "keywords": ["rest", "api", "openapi", "swagger", "endpoint", "minimal api", "route", "versioning", "rate limiting"],
+      "always_active": false,
+      "validators": ["architecture"],
+      "relationships": {
+        "reports_to": "dotnet-senior",
+        "coordinates": [],
+        "escalates_to": "dotnet-senior",
+        "collaborates_with": ["supabase-expert", "nextjs-expert"],
+        "team_role": "specialist"
+      },
+      "standards": ["coding.md", "architecture.md"],
+      "teammate": {
+        "role": "API Design Specialist",
+        "icon": "A",
+        "spawn_prompt": "You are the API Design Specialist. Design REST APIs using .NET 10 Minimal API (MapGet, MapPost, etc.). Use endpoint groups, typed results, OpenAPI annotations. Implement API versioning, rate limiting. Validate Supabase JWT in middleware."
+      }
+    },
+
+    "supabase-expert": {
+      "tier": 3,
+      "role": "specialist",
+      "title": "Supabase Platform Specialist",
+      "domains": ["platform-supabase"],
+      "keywords": ["supabase", "postgres", "postgresql", "rls", "row level security", "auth", "storage", "realtime", "pgvector", "migration", "database", "policy"],
+      "always_active": true,
+      "validators": ["architecture"],
+      "relationships": {
+        "reports_to": "standards-architect",
+        "coordinates": [],
+        "escalates_to": "standards-architect",
+        "collaborates_with": ["dotnet-senior", "nextjs-expert", "security-expert"],
+        "team_role": "specialist"
+      },
+      "standards": ["supabase-auth.md", "supabase-rls.md", "supabase-storage.md", "supabase-pgvector.md"],
+      "teammate": {
+        "role": "Supabase Platform Specialist",
+        "icon": "S",
+        "spawn_prompt": "You are the Supabase Platform Specialist. Design PostgreSQL schemas (snake_case), write SQL migrations, create RLS policies for multi-tenant security. Configure Supabase Auth (Google + GitHub OAuth), Storage buckets with policies, Realtime subscriptions. Implement pgvector for vector search when needed. Collaborate with security-expert for RLS audit."
+      }
+    },
+
+    "easypanel-deployer": {
+      "tier": 3,
+      "role": "specialist",
+      "title": "EasyPanel Deployment Specialist",
+      "domains": ["infrastructure-deploy"],
+      "keywords": ["easypanel", "deploy", "deployment", "hosting", "ssl", "domain", "vps", "production"],
+      "always_active": false,
+      "validators": ["architecture"],
+      "relationships": {
+        "reports_to": "standards-architect",
+        "coordinates": [],
+        "escalates_to": "standards-architect",
+        "collaborates_with": ["container-specialist", "devops-engineer"],
+        "team_role": "specialist"
+      },
+      "standards": ["easypanel-deploy.md"],
+      "teammate": {
+        "role": "EasyPanel Deployment Specialist",
+        "icon": "E",
+        "spawn_prompt": "You are the EasyPanel Deployment Specialist. Configure EasyPanel services (API + Web), set up GitHub integration for auto-deploy, manage SSL certificates and custom domains. Define environment variables, health check endpoints, resource limits."
+      }
+    },
+
+    "container-specialist": {
+      "tier": 3,
+      "role": "specialist",
+      "title": "Containerization Specialist",
+      "domains": ["infrastructure-containers"],
+      "keywords": ["docker", "container", "dockerfile", "multi-stage", "docker compose", "health check", "image"],
+      "always_active": true,
+      "validators": ["architecture"],
+      "relationships": {
+        "reports_to": "standards-architect",
+        "coordinates": [],
+        "escalates_to": "standards-architect",
+        "collaborates_with": ["easypanel-deployer", "devops-engineer", "dotnet-senior", "nextjs-expert"],
+        "team_role": "specialist"
+      },
+      "standards": ["easypanel-deploy.md"],
+      "teammate": {
+        "role": "Containerization Specialist",
+        "icon": "D",
+        "spawn_prompt": "You are the Containerization Specialist for EasyPanel deployments. Write multi-stage Dockerfiles (.NET API + Next.js), docker-compose.yml for local dev, .dockerignore files. Optimize image sizes, configure health checks (/health endpoint). Target EasyPanel container service format."
+      }
+    },
+
+    "devops-engineer": {
+      "tier": 3,
+      "role": "specialist",
+      "title": "CI/CD Specialist",
+      "domains": ["infrastructure-cicd"],
+      "keywords": ["pipeline", "ci/cd", "github actions", "auto-deploy", "workflow", "continuous integration"],
+      "always_active": false,
+      "validators": ["architecture"],
+      "relationships": {
+        "reports_to": "standards-architect",
+        "coordinates": [],
+        "escalates_to": "standards-architect",
+        "collaborates_with": ["container-specialist", "easypanel-deployer"],
+        "team_role": "specialist"
+      },
+      "standards": ["easypanel-deploy.md"],
+      "teammate": {
+        "role": "CI/CD Specialist",
+        "icon": "C",
+        "spawn_prompt": "You are the CI/CD Specialist. Build GitHub Actions workflows for .NET build/test + Next.js build/test. Configure auto-deploy to EasyPanel via GitHub webhook or API. Implement environment-based deployments (staging, production)."
+      }
+    },
+
+    "css-specialist": {
+      "tier": 3,
+      "role": "specialist",
+      "title": "CSS & Design System Specialist",
+      "domains": ["frontend-css"],
+      "keywords": ["css", "tailwind", "design system", "styling", "theme", "design tokens", "shadcn"],
+      "always_active": false,
+      "validators": ["css", "contrast", "design-system"],
+      "relationships": {
+        "reports_to": "ui-ux-designer",
+        "coordinates": [],
+        "escalates_to": "ui-ux-designer",
+        "collaborates_with": ["nextjs-expert"],
+        "team_role": "specialist",
+        "active_phases": ["implement"]
+      },
+      "standards": ["css-naming.md", "nextjs-patterns.md"],
+      "teammate": {
+        "role": "CSS & Design System Specialist",
+        "icon": "P",
+        "spawn_prompt": "You are the CSS & Design System Specialist. Validate Tailwind CSS follows design system tokens (no off-palette colors), review component styling with shadcn/ui conventions. Ensure no inline styles with hardcoded values. Run design-system, css, contrast validators."
+      }
+    },
+
+    "testing-specialist": {
+      "tier": 3,
+      "role": "specialist",
+      "title": "Testing Specialist",
+      "domains": ["quality-testing"],
+      "keywords": ["test", "testing", "unit", "integration", "e2e", "xunit", "vitest", "testing library", "playwright"],
+      "always_active": false,
+      "validators": ["architecture"],
+      "relationships": {
+        "reports_to": "standards-architect",
+        "coordinates": [],
+        "escalates_to": "standards-architect",
+        "collaborates_with": ["dotnet-senior", "nextjs-expert"],
+        "team_role": "specialist"
+      },
+      "standards": ["coding.md"],
+      "teammate": {
+        "role": "Testing Specialist",
+        "icon": "Q",
+        "spawn_prompt": "You are the Testing Specialist. Write .NET unit tests (xUnit, Moq/NSubstitute, FluentAssertions), .NET integration tests. Write frontend tests with Vitest + Testing Library. E2E with Playwright. Follow Arrange-Act-Assert (AAA) pattern."
+      }
+    },
+
+    "_comment_tier_4": "=== TIER 4: VALIDATORS (1) ===",
+
+    "security-expert": {
+      "tier": 4,
+      "role": "validator",
+      "title": "Security Validator",
+      "domains": ["security"],
+      "keywords": ["sql injection", "xss", "rls", "secrets", "security scan", "vulnerability", "csrf", "owasp", "jwt"],
+      "always_active": true,
+      "validators": ["architecture"],
+      "relationships": {
+        "reports_to": "standards-architect",
+        "coordinates": [],
+        "runs_in": "hooks",
+        "hook_triggers": ["TeammateIdle", "TaskCompleted"],
+        "team_role": "validator"
+      },
+      "standards": ["coding.md", "supabase-auth.md", "supabase-rls.md"],
+      "teammate": null,
+      "hook_behavior": {
+        "validates": [
+          "SQL injection (string concatenation in Dapper queries)",
+          "Hardcoded secrets (API keys, Supabase keys in client code)",
+          "XSS (dangerouslySetInnerHTML in React)",
+          "RLS bypass (missing or permissive RLS policies)",
+          "JWT validation (Supabase JWT not verified in API)"
+        ],
+        "severity": "error",
+        "blocks_on_fail": true
+      }
+    }
+  },
+
+  "squads": {
+    "backend_squad": {
+      "leader": "dotnet-senior",
+      "members": ["api-designer", "supabase-expert"],
+      "domains": ["backend", "backend-api", "platform-supabase"]
+    },
+    "frontend_squad": {
+      "leader": "ui-ux-designer",
+      "members": ["nextjs-expert", "css-specialist"],
+      "domains": ["frontend-design", "frontend-nextjs", "frontend-css"],
+      "active_phases": {
+        "design": ["ui-ux-designer"],
+        "implement": ["nextjs-expert", "css-specialist"]
+      }
+    },
+    "infrastructure_squad": {
+      "leader": "container-specialist",
+      "members": ["easypanel-deployer", "devops-engineer"],
+      "domains": ["infrastructure-containers", "infrastructure-deploy", "infrastructure-cicd"]
+    },
+    "quality_squad": {
+      "leader": "standards-architect",
+      "members": ["testing-specialist", "security-expert"],
+      "domains": ["quality-testing", "security"],
+      "note": "No permanent leader -- standards-architect coordinates directly"
+    }
+  },
+
+  "relationship_types": {
+    "reports_to": "Hierarchical manager relationship",
+    "coordinates": "Manages/leads these agents",
+    "escalates_to": "Where to escalate unresolved issues",
+    "collaborates_with": "Peer agents for cross-domain work",
+    "runs_in": "Execution context (hooks, not teammates)",
+    "team_role": "Role in Agent Teams (lead, domain_leader, specialist, validator)"
+  }
+}

package/stacks/nextjs-supabase/.morph/config/config.template.json

@@ -0,0 +1,92 @@
+{
+  "project": {
+    "name": "MyProject",
+    "description": "Project description",
+    "type": "nextjs-supabase",
+    "repository": "https://github.com/org/repo"
+  },
+  "supabase": {
+    "projectId": "your-project-id",
+    "url": "https://xxx.supabase.co",
+    "region": "us-east-1",
+    "resources": {
+      "database": {
+        "enabled": true,
+        "tier": "Free",
+        "extensions": ["pgvector", "pg_trgm"]
+      },
+      "auth": {
+        "enabled": true,
+        "providers": ["email", "google", "github"],
+        "mfa": false
+      },
+      "storage": {
+        "enabled": true,
+        "maxFileSizeMB": 50
+      },
+      "realtime": {
+        "enabled": false
+      }
+    }
+  },
+  "easypanel": {
+    "domain": "yourdomain.com",
+    "ssl": "letsencrypt",
+    "services": {
+      "api": {
+        "dockerfile": "Dockerfile.api",
+        "port": 8080,
+        "healthCheck": "/health"
+      },
+      "web": {
+        "dockerfile": "Dockerfile.web",
+        "port": 3000,
+        "healthCheck": "/api/health"
+      }
+    },
+    "autoDeploy": {
+      "enabled": true,
+      "branch": "main"
+    }
+  },
+  "github": {
+    "organization": "your-org",
+    "repository": "your-repo",
+    "defaultBranch": "main",
+    "featureBranchPrefix": "feature/"
+  },
+  "agents": {
+    "core": {
+      "standardsArchitect": { "enabled": true },
+      "supabaseExpert": { "enabled": true },
+      "containerSpecialist": { "enabled": true }
+    },
+    "stack": {
+      "dotnetSenior": { "enabled": true },
+      "nextjsExpert": { "enabled": true },
+      "apiDesigner": { "enabled": true }
+    },
+    "specialists": {
+      "easypanelDeployer": { "enabled": true },
+      "cssSpecialist": { "enabled": true },
+      "securityExpert": { "enabled": true }
+    }
+  },
+  "checkpoints": {
+    "afterDesign": true,
+    "afterTasks": true,
+    "everyNTasks": 3,
+    "beforeDeploy": true
+  },
+  "costs": {
+    "limits": {
+      "noApproval": "free-tier",
+      "withApproval": "$25/month",
+      "requiresADR": "above $25/month"
+    },
+    "estimates": {
+      "dev": "$6/month (Supabase Free + VPS $5)",
+      "prod": "$31/month (Supabase Pro $25 + VPS $6)"
+    }
+  }
+}

package/stacks/nextjs-supabase/.morph/docs/easypanel-setup.md

@@ -0,0 +1,169 @@
+# EasyPanel Setup Guide
+
+> Deploy .NET API + Next.js to VPS via EasyPanel
+
+## Prerequisites
+
+- VPS with EasyPanel installed (Ubuntu 22.04+ recommended)
+- GitHub repository with Dockerfiles
+- Domain name (optional, EasyPanel provides subdomains)
+
+## 1. GitHub Integration
+
+### Create Personal Access Token (PAT)
+
+1. GitHub > Settings > Developer Settings > Personal Access Tokens > Fine-grained
+2. Repository access: select your repo
+3. Permissions: Contents (read), Metadata (read)
+4. Copy token for EasyPanel
+
+### Connect in EasyPanel
+
+1. EasyPanel Dashboard > Settings > Git
+2. Add GitHub provider with PAT
+3. Test connection
+
+## 2. Create Project
+
+```
+EasyPanel Dashboard > Projects > Create Project
+Name: my-saas-app
+```
+
+## 3. Configure Services
+
+### API Service (.NET)
+
+| Setting | Value |
+|---------|-------|
+| Type | App |
+| Source | GitHub |
+| Repository | your-org/your-repo |
+| Branch | main |
+| Build Path | . |
+| Dockerfile | Dockerfile.api |
+| Port | 8080 |
+
+### Web Service (Next.js)
+
+| Setting | Value |
+|---------|-------|
+| Type | App |
+| Source | GitHub |
+| Repository | your-org/your-repo |
+| Branch | main |
+| Build Path | . |
+| Dockerfile | Dockerfile.web |
+| Port | 3000 |
+
+## 4. Environment Variables
+
+### API (.NET)
+
+```
+ASPNETCORE_ENVIRONMENT=Production
+SUPABASE_URL=https://xxx.supabase.co
+SUPABASE_SERVICE_ROLE_KEY=eyJ...
+SUPABASE_JWT_SECRET=your-jwt-secret
+ASPNETCORE_URLS=http://+:8080
+```
+
+### Web (Next.js)
+
+```
+NODE_ENV=production
+NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
+NEXT_PUBLIC_API_URL=https://api.yourdomain.com
+```
+
+CRITICAL: Never commit secrets. Use EasyPanel env vars panel only.
+
+## 5. Domain + SSL
+
+### Custom Domain
+
+1. Service > Domains > Add Domain
+2. Enter: `api.yourdomain.com` (for API) or `app.yourdomain.com` (for web)
+3. DNS: Add A record pointing to VPS IP
+4. SSL: Enable "Let's Encrypt" (auto-renews)
+
+### EasyPanel Subdomain (free)
+
+Format: `service-project.server.easypanel.host`
+SSL included automatically.
+
+## 6. Auto-Deploy
+
+### GitHub Webhook
+
+1. Service > Settings > Enable "Auto Deploy"
+2. EasyPanel generates webhook URL
+3. GitHub repo > Settings > Webhooks > Add webhook
+4. Payload URL: (from EasyPanel)
+5. Content type: application/json
+6. Events: Push events only
+7. Branch filter: main
+
+Pushes to `main` now trigger automatic builds.
+
+## 7. Health Checks
+
+### API Health Check
+
+```
+Path: /health
+Port: 8080
+Interval: 30s
+Timeout: 5s
+Retries: 3
+```
+
+.NET endpoint:
+```csharp
+app.MapGet("/health", () => Results.Ok(new { status = "healthy" }));
+```
+
+### Web Health Check
+
+```
+Path: /api/health
+Port: 3000
+Interval: 30s
+```
+
+Next.js route handler:
+```typescript
+// app/api/health/route.ts
+export function GET() {
+  return Response.json({ status: 'healthy' });
+}
+```
+
+## 8. Monitoring
+
+### Logs
+
+EasyPanel Dashboard > Service > Logs (real-time streaming)
+
+### Resource Usage
+
+EasyPanel Dashboard > Service > Metrics (CPU, Memory, Network)
+
+### Recommended VPS Sizing
+
+| Workload | RAM | CPU | Storage |
+|----------|-----|-----|---------|
+| Dev/MVP | 2GB | 1 vCPU | 40GB |
+| Small prod | 4GB | 2 vCPU | 80GB |
+| Medium prod | 8GB | 4 vCPU | 160GB |
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Build fails | Check Dockerfile paths, ensure multi-stage layers correct |
+| Port conflict | Verify service ports don't overlap |
+| SSL not working | Wait 5 min for Let's Encrypt propagation, check DNS |
+| Auto-deploy not triggering | Verify webhook URL and branch filter |
+| Container OOM | Increase VPS RAM or optimize app memory usage |