@polymorphism-tech/morph-spec 3.0.1 → 3.1.0

package/stacks/nextjs-supabase/CLAUDE.md

@@ -0,0 +1,149 @@
+# MORPH-SPEC - Next.js + Supabase Stack
+
+> by Polymorphism Tech
+
+Spec-driven development system. Specialized agent hub for .NET 10 Minimal API + Next.js 15 + Supabase Cloud, deployed via Docker on EasyPanel.
+
+---
+
+## CRITICAL RULES
+
+### NEVER:
+- Skip to code without a specification
+- Implement without design approval
+- Ignore standards in `.morph/standards/`
+- Create infrastructure manually (use Docker Compose + EasyPanel)
+- Generate code without defined contracts
+
+### ALWAYS:
+- Follow the 5 mandatory phases
+- Generate outputs in `.morph/features/{feature}/`
+- Document decisions in `decisions.md`
+- Checkpoint every 3 implemented tasks
+- Use Infrastructure as Code (Docker Compose, Dockerfiles)
+
+---
+
+## WORKFLOW (5 Phases)
+
+| Phase | Trigger | Actions | Output | Pause? |
+|-------|---------|---------|--------|--------|
+| **1. SETUP** | Feature request | Read project.md, identify stack, activate agents, create folder | proposal.md | No |
+| **2. DESIGN** | Setup done | Spec + contracts + decisions + costs + Docker | spec.md, contracts.cs, contracts.ts, decisions.md | **Yes** |
+| **3. CLARIFY** | Design approved | Ambiguities, questions, edge cases | Updated spec | No |
+| **4. TASKS** | Clarifications resolved | Break into tasks, ordering, checkpoints, dependencies | tasks.md | **Yes** |
+| **5. IMPLEMENT** | Tasks approved | Task by task, checkpoint every 3, recap | Code + recap.md | No |
+
+---
+
+## PROJECT STRUCTURE
+
+```
+project/
+├── CLAUDE.md
+├── .morph/
+│   ├── project.md                  # Context
+│   ├── config/                     # config.json, agents.json
+│   ├── standards/                  # supabase-*, nextjs-patterns, easypanel-deploy
+│   ├── templates/                  # Output templates
+│   ├── specs/                      # ACTIVE specs
+│   ├── features/{feature-name}/    # Features IN DEVELOPMENT
+│   │   ├── proposal.md, spec.md, tasks.md
+│   │   ├── contracts.cs, contracts.ts, decisions.md, recap.md
+│   └── archive/                    # COMPLETED features
+├── .claude/skills/                 # Agent skills
+├── src/
+│   ├── api/                        # .NET 10 Minimal API
+│   └── web/                        # Next.js 15 App Router
+├── supabase/                       # Migrations, seeds, RLS policies
+├── docker-compose.yml              # Local dev environment
+└── Dockerfile.*                    # Production builds
+```
+
+---
+
+## AGENTS
+
+### Core (Always Active)
+
+| Agent | Responsibilities |
+|-------|-----------------|
+| **Standards Architect** | Standards, naming, review |
+| **Supabase Expert** | DB design, RLS, Auth, Storage, Realtime, pgvector |
+| **Container Specialist** | Docker builds, EasyPanel config, health checks |
+
+### Stack, Specialist, Integration, Infra
+
+> **Ref:** `.morph/config/agents.json` for full agent table and keywords.
+
+---
+
+## COST LIMITS
+
+| Level | Limit | Requirement |
+|-------|-------|-------------|
+| No approval | Free tier | None |
+| With approval | Up to $25/month | Confirmation |
+| Above $25 | Justification | ADR |
+
+---
+
+## INFRASTRUCTURE AS CODE
+
+> NEVER create infrastructure manually. Everything via Docker Compose + EasyPanel.
+
+| Resource | Approach |
+|----------|----------|
+| Local dev (DB, API, Web) | Docker Compose |
+| Production containers | Dockerfiles + EasyPanel |
+| Supabase (DB, Auth, Storage) | Supabase Cloud (managed) |
+| CI/CD | GitHub Actions + EasyPanel auto-deploy |
+
+---
+
+## TEMPLATES
+
+> ALWAYS use `bin/render-template.js` to render. NEVER fill placeholders manually.
+
+### Placeholders: `{{PLACEHOLDER}}`
+
+| Placeholder | Example |
+|-------------|---------|
+| `{{FEATURE_NAME}}` | `scheduled-reports` |
+| `{{FEATURE_NAME_PASCAL}}` | `ScheduledReports` |
+| `{{FEATURE_NAME_CAMEL}}` | `scheduledReports` |
+| `{{STACK}}` | `NextjsSupabase` |
+| `{{DATE}}`, `{{AUTHOR}}`, `{{NAMESPACE}}` | Auto from config.json |
+
+### Available Templates
+
+**MORPH outputs:** proposal, spec, contracts.cs, contracts.ts, decisions, tasks, recap
+
+**Code:** service.cs, repository.cs, endpoint.cs
+
+---
+
+## COMMANDS
+
+| Command | Action |
+|---------|--------|
+| `/morph-proposal {feature}` | Full spec pipeline (phases 1-4, auto-continuation with pauses) |
+| `/morph-apply {feature}` | Implement feature (phase 5) |
+| `/morph-status` | Dashboard |
+| `/morph-archive {feature}` | Archive completed feature |
+| `/morph-infra {action}` | Manage Docker/EasyPanel infra |
+| `/morph-preflight` | Pre-deploy validation |
+| `/morph-troubleshoot {error}` | Error troubleshooting |
+
+---
+
+## REFERENCES
+
+- `.morph/project.md` -- Project context
+- `.morph/standards/` -- supabase-auth, supabase-rls, supabase-storage, supabase-pgvector, easypanel-deploy, nextjs-patterns, coding, architecture
+- `.morph/templates/` -- Output templates
+- `.morph/config/agents.json` -- Agents
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/stacks/nextjs-supabase/README.md

@@ -0,0 +1,112 @@
+# Stack: Next.js + Supabase
+
+> MORPH-SPEC stack for .NET 10 Minimal API + Next.js 15 + Supabase Cloud + EasyPanel (VPS)
+
+## When to Use This Stack
+
+| Criteria | This Stack | Blazor+Azure Stack |
+|----------|------------|-------------------|
+| Frontend | React/Next.js (SSR + CSR) | Blazor Server (C# only) |
+| Database | Supabase Cloud (PostgreSQL) | Azure SQL |
+| Auth | Supabase Auth (built-in) | Azure Identity / Clerk |
+| Deploy | VPS + EasyPanel (Docker) | Azure Container Apps |
+| Cost (dev) | ~$6/month | ~$15/month |
+| Cost (prod) | ~$31/month | ~$50+/month |
+| Best for | MVPs, SaaS, AI apps (pgvector) | Enterprise, full-.NET teams |
+| Realtime | Supabase Realtime (PostgreSQL) | SignalR |
+| Vector search | pgvector (native) | Azure AI Search |
+
+## Architecture
+
+```
+Browser
+  |
+  v
+Next.js 15 (App Router)          Supabase Cloud
+  |-- Server Components --------> Auth (JWT validation)
+  |-- Client Components --------> PostgREST (direct queries via RLS)
+  |-- Route Handlers (BFF) -----> .NET 10 API --> PostgreSQL + pgvector
+  |                                              Storage
+  v                                              Realtime
+EasyPanel (VPS)
+  |-- Next.js Container (:3000)
+  |-- .NET API Container (:8080)
+  |-- Nginx reverse proxy (:443)
+```
+
+## Quick Start
+
+### 1. Copy stack to your project
+
+```bash
+cp -r stacks/nextjs-supabase/.morph/ your-project/.morph/
+cp -r stacks/nextjs-supabase/.claude/ your-project/.claude/
+cp stacks/nextjs-supabase/CLAUDE.md your-project/CLAUDE.md
+```
+
+### 2. Configure
+
+Edit `.morph/project.md` with your project details.
+
+### 3. Start developing
+
+```bash
+/morph-proposal my-feature
+```
+
+## Directory Structure
+
+```
+stacks/nextjs-supabase/
+├── CLAUDE.md                           # Stack-specific Claude instructions
+├── README.md                           # This file
+├── .morph/
+│   ├── project.md                      # Project template
+│   ├── config/
+│   │   └── agents.json                 # 12 agents configured
+│   ├── standards/                      # 6 standards
+│   │   ├── supabase-auth.md
+│   │   ├── supabase-rls.md
+│   │   ├── supabase-storage.md
+│   │   ├── supabase-pgvector.md
+│   │   ├── easypanel-deploy.md
+│   │   └── nextjs-patterns.md
+│   ├── templates/                      # 11 templates
+│   ├── examples/                       # 2 reference examples
+│   │   ├── crud-nextjs-supabase/
+│   │   └── saas-nextjs-supabase/
+│   └── docs/                           # Setup guides
+│       ├── supabase-mcp-setup.md
+│       └── easypanel-setup.md
+└── .claude/
+    └── skills/                         # 4 agent skills
+        └── level-2-domains/
+            ├── integrations/supabase-expert.md
+            ├── infrastructure/easypanel-deployer.md
+            ├── backend/dotnet-supabase.md
+            └── frontend/nextjs-supabase.md
+```
+
+## Key Differences from Blazor+Azure
+
+| Aspect | Blazor+Azure | Next.js+Supabase |
+|--------|-------------|-----------------|
+| IaC | Bicep templates | Dockerfiles + Docker Compose |
+| ORM | EF Core (LINQ) | Npgsql + Dapper (SQL) |
+| Migrations | C# EF Migrations | SQL (Supabase CLI) |
+| Auth middleware | Azure Identity | @supabase/ssr + JWT |
+| RLS | Application-level | Database-level (PostgreSQL RLS) |
+| File storage | Azure Blob Storage | Supabase Storage |
+| Deploy | Azure Container Apps | EasyPanel (VPS Docker) |
+
+## Shared with Blazor+Azure
+
+- MORPH-SPEC 5-phase workflow (Setup > Design > Clarify > Tasks > Implement)
+- Framework standards: coding.md, architecture.md
+- CLI commands: /morph-proposal, /morph-apply, /morph-status
+- Validation pipeline and checkpoint system
+- .NET 10 backend patterns (C# 14, sealed records, CancellationToken)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*