@polymorphism-tech/morph-spec 4.7.1 → 4.7.2

package/.morph/framework/templates/README.md

@@ -0,0 +1,814 @@
+# MORPH-SPEC Template System
+
+> **Technology-Based Organization for Multi-Stack Reusability**
+
+## Overview
+
+The MORPH-SPEC template system provides **57 production-ready templates** organized by **technology** (not by stack) to enable maximum reusability across current and future stacks.
+
+**Key Principle:** Templates are grouped by the **technology they use** (dotnet, typescript, sql, azure, docker), allowing new stacks like `vue-firebase` or `angular-mongodb` to reuse existing templates for .NET, TypeScript, SQL, etc.
+
+---
+
+## 📁 Directory Structure
+
+```
+framework/templates/
+├── docs/              # Universal documentation templates
+│   ├── proposal.md    # Feature proposal (required)
+│   └── spec.md        # Technical specification (required)
+│
+├── feature/           # Feature management
+│   ├── tasks.md       # Implementation tasks (required)
+│   ├── decisions.md   # Architecture Decision Records (required)
+│   └── recap.md       # Post-implementation summary (required)
+│
+├── context/           # Context generation
+│   ├── CONTEXT.md            # Project-level context
+│   └── CONTEXT-FEATURE.md    # Feature-level context
+│
+├── code/              # Code templates organized by technology
+│   ├── dotnet/
+│   │   ├── backend/
+│   │   │   ├── service.cs          # Service layer
+│   │   │   ├── repository.cs       # Data access layer
+│   │   │   └── test.cs             # Unit tests
+│   │   ├── frontend/
+│   │   │   └── component.razor     # Blazor components
+│   │   ├── database/
+│   │   │   └── migration.cs        # EF Core migrations
+│   │   ├── jobs/
+│   │   │   ├── job.cs              # Hangfire background jobs
+│   │   │   └── agent.cs            # MS Agent Framework agents
+│   │   └── contracts/
+│   │       ├── contracts.cs        # Base contracts
+│   │       ├── Commands.cs         # CQRS commands
+│   │       ├── Queries.cs          # CQRS queries
+│   │       ├── Entities.cs         # Domain entities
+│   │       ├── api-contracts.cs    # API contracts
+│   │       └── README.md           # Contracts documentation
+│   │
+│   ├── typescript/
+│   │   └── contracts.ts            # TypeScript type definitions
+│   │
+│   └── sql/
+│       ├── supabase-migration.sql          # Basic migration
+│       ├── supabase-migration.template.sql # Enhanced migration
+│       └── rls-policy.sql                  # Row-level security
+│
+├── infrastructure/
+│   ├── azure/         # Azure Bicep templates
+│   │   ├── main.bicep              # Main orchestration (required)
+│   │   ├── container-app.bicep     # Container Apps
+│   │   ├── container-app-env.bicep # Container environment
+│   │   ├── app-service.bicep       # App Service
+│   │   ├── sql-database.bicep      # Azure SQL
+│   │   ├── storage.bicep           # Storage Account
+│   │   ├── key-vault.bicep         # Key Vault
+│   │   ├── app-insights.bicep      # Application Insights
+│   │   ├── parameters.dev.json     # Dev parameters
+│   │   ├── parameters.staging.json # Staging parameters
+│   │   ├── parameters.prod.json    # Prod parameters
+│   │   ├── deploy.ps1              # PowerShell deploy
+│   │   ├── deploy.sh               # Bash deploy
+│   │   ├── deploy-checklist.md     # Pre-deploy checklist
+│   │   ├── azure-pipelines-deploy.yml # Azure DevOps
+│   │   ├── Dockerfile.example      # Dockerfile example
+│   │   └── README.md               # Infrastructure docs
+│   │
+│   ├── docker/        # Docker & EasyPanel
+│   │   ├── dockerfile-api.dockerfile       # .NET API
+│   │   ├── dockerfile-web.dockerfile       # Next.js web
+│   │   ├── Dockerfile.template             # Generic
+│   │   ├── docker-compose.template.yml     # Compose
+│   │   └── easypanel.template.json         # EasyPanel config
+│   │
+│   └── github/        # GitHub Actions CI/CD
+│       ├── workflows/                      # Reusable workflow templates
+│       │   ├── dotnet-build.yml.hbs       # .NET restore, build, test
+│       │   ├── docker-build-push.yml.hbs  # Docker build & push
+│       │   ├── deploy-azure-app-service.yml.hbs  # Azure App Service deployment
+│       │   └── deploy-easypanel.yml.hbs   # EasyPanel deployment
+│       │
+│       ├── actions/                        # Composite action templates
+│       │   ├── docker-build-push/action.yml.hbs
+│       │   ├── health-check/action.yml.hbs
+│       │   └── azure-auth/action.yml.hbs
+│       │
+│       └── README.md                       # GitHub Actions docs
+│
+├── integrations/      # Platform-agnostic integrations
+│   ├── asaas-client.cs           # Asaas financial API
+│   ├── asaas-webhook.cs          # Asaas webhooks
+│   ├── azure-identity-config.cs  # Azure AD/Entra
+│   └── clerk-config.cs           # Clerk auth
+│
+├── ui/                # Design systems
+│   ├── design-system.css         # CSS tokens
+│   ├── FluentDesignTheme.cs      # Fluent UI theme
+│   └── MudTheme.cs               # MudBlazor theme
+│
+├── saas/              # Multi-tenant patterns
+│   ├── subscription.cs           # Subscription model
+│   └── tenant.cs                 # Tenant model
+│
+├── examples/          # Reference implementations
+│   ├── spec-examples.md          # Example specs
+│   └── design-system-examples.md # Design system examples
+│
+└── REGISTRY.json      # Template metadata registry
+```
+
+---
+
+## 🏗️ Technology-Based Architecture
+
+**Why organize by technology instead of by stack?**
+
+| Organization | Pros | Cons | Best For |
+|--------------|------|------|----------|
+| **By Stack** (old v1) | Stack-specific optimizations | Duplicate templates, hard to reuse | Single-stack projects |
+| **By Technology** (new v2) | Reusable, DRY, future-proof | Requires stack override mechanism | Multi-stack frameworks |
+
+**Example:** A `.NET service.cs` template works for both `blazor-azure` and `nextjs-supabase` stacks (both use .NET backend). No need to duplicate!
+
+**Future-proof:** When we create `vue-firebase` stack, we can reuse:
+- `code/typescript/` templates
+- `infrastructure/docker/` templates
+- `integrations/` templates (Clerk, etc.)
+
+**Only create NEW templates for Vue-specific code.**
+
+---
+
+## ⚙️ Template Engine: Handlebars
+
+All templates use **Handlebars** with **20+ custom helpers**.
+
+### Basic Syntax
+
+```handlebars
+# Feature: {{titleCase FEATURE_NAME}}
+
+Namespace: {{pascalCase FEATURE_NAME}}
+
+Created: {{DATE}}
+```
+
+### Available Helpers
+
+| Helper | Input | Output | Usage |
+|--------|-------|--------|-------|
+| `{{pascalCase str}}` | `user-profile` | `UserProfile` | Class names |
+| `{{camelCase str}}` | `user-profile` | `userProfile` | Variable names |
+| `{{snakeCase str}}` | `user-profile` | `user_profile` | SQL tables |
+| `{{upperSnakeCase str}}` | `user-profile` | `USER_PROFILE` | Constants |
+| `{{titleCase str}}` | `user-profile` | `User Profile` | Titles |
+| `{{kebabCase str}}` | `User Profile` | `user-profile` | URLs |
+| `{{pluralize str}}` | `user` | `users` | Collections |
+| `{{singularize str}}` | `users` | `user` | Entities |
+| `{{eq a b}}` | `"blazor" "blazor"` | `true` | Conditionals |
+| `{{or a b}}` | `false true` | `true` | Logical OR |
+| `{{and a b}}` | `true false` | `false` | Logical AND |
+| `{{default val fallback}}` | `null "default"` | `"default"` | Defaults |
+
+### Conditional Logic
+
+```handlebars
+{{#if (eq STACK "blazor-azure")}}
+// Azure-specific code
+{{else if (eq STACK "nextjs-supabase")}}
+// Supabase-specific code
+{{else}}
+// Generic code
+{{/if}}
+```
+
+### Deprecated: Pre-computed Variables
+
+**❌ Old (v1):**
+```handlebars
+{{pascalCase FEATURE_NAME}}  <!-- Pre-computed in bin/render-template.js -->
+```
+
+**✅ New (v2):**
+```handlebars
+{{pascalCase FEATURE_NAME}}  <!-- Computed via Handlebars helper -->
+```
+
+---
+
+## 🛠️ CLI Commands
+
+### List All Templates
+
+```bash
+# List all templates
+morph-spec template list
+
+# Filter by category
+morph-spec template list --category code
+morph-spec template list --category infrastructure
+
+# Filter by phase
+morph-spec template list --phase implement
+
+# Filter by stack applicability
+morph-spec template list --stack blazor-azure
+
+# Show only required templates
+morph-spec template list --required
+```
+
+**Output:**
+```
+📦 Universal Templates (9)
+  proposal             Feature Proposal          [REQUIRED] [UNIVERSAL] [HBS]
+  spec                 Technical Specification   [REQUIRED] [UNIVERSAL] [HBS]
+  tasks                Implementation Tasks      [REQUIRED] [UNIVERSAL] [HBS]
+  ...
+
+📦 Technology-Based Templates (48)
+  dotnet-backend-service    .NET Service Class          [UNIVERSAL] [HBS] (dotnet)
+  typescript-contracts      TypeScript Contracts        [UNIVERSAL] [HBS] (typescript)
+  azure-bicep-main          Main Bicep Orchestration    [REQUIRED] [UNIVERSAL] [HBS] (bicep)
+  ...
+```
+
+### Show Template Details
+
+```bash
+# Show metadata
+morph-spec template show dotnet-backend-service
+
+# Show with file preview
+morph-spec template show dotnet-backend-service --preview
+
+# Show with resolved path
+morph-spec template show dotnet-backend-service --show-path
+```
+
+**Output:**
+```
+Template: dotnet-backend-service
+
+📋 Metadata
+  ID: dotnet-backend-service
+  Name: .NET Service Class
+  Path: code/dotnet/backend/service.cs
+  Location: framework
+  Category: code
+  Phase: implement
+  Required: No
+  Technology: dotnet
+  Applicable Stacks: blazor-azure, nextjs-supabase
+
+📝 Description
+  C# service class template with dependency injection and interface pattern
+
+🔑 Variables
+  {{FEATURE_NAME}}
+  {{NAMESPACE}}
+
+📄 Output Name
+  {FeatureName}Service.cs
+
+💡 Usage Hint
+  morph-spec template render dotnet-backend-service output.cs '{"FEATURE_NAME":"user-auth","NAMESPACE":"MyApp"}'
+```
+
+### Render Template
+
+```bash
+# Render to file
+morph-spec template render dotnet-backend-service UserAuthService.cs '{
+  "FEATURE_NAME": "user-auth",
+  "NAMESPACE": "MyApp.Services"
+}'
+
+# Dry run (preview only)
+morph-spec template render dotnet-backend-service output.cs '{"FEATURE_NAME":"test"}' --dry-run
+
+# Auto-resolve path (searches framework → stack override)
+morph-spec template render proposal proposal.md '{"FEATURE_NAME":"auth"}' --resolve-path
+```
+
+**Default Variables (auto-injected):**
+- `DATE`: `2026-02-17`
+- `YEAR`: `2026`
+- `TIMESTAMP`: `2026-02-17T19:38:00.000Z`
+
+### Customize Template (Stack Override)
+
+```bash
+# Copy to stack-specific directory (override framework version)
+morph-spec template customize dotnet-backend-service --stack blazor-azure
+
+# Copy to project-local (cross-stack override)
+morph-spec template customize dotnet-backend-service --local
+
+# Force overwrite if exists
+morph-spec template customize dotnet-backend-service --stack blazor-azure --force
+```
+
+**Output:**
+```
+Source: framework/templates/code/dotnet/backend/service.cs
+Destination: stacks/blazor-azure/.morph/framework/templates/code/dotnet/backend/service.cs
+
+✅ Template copied for customization
+
+📝 Next Steps
+  1. Edit the template file:
+     stacks/blazor-azure/.morph/framework/templates/code/dotnet/backend/service.cs
+
+  2. Template will now be used instead of framework version
+     (Stack-specific templates take precedence)
+
+  3. Test rendering:
+     morph-spec template render dotnet-backend-service output.cs '{"FEATURE_NAME":"test"}'
+
+⚠️  Customized templates won't receive framework updates
+   To get updates: delete customized version and re-run this command
+```
+
+---
+
+## 🔄 GitHub Actions Templates
+
+The framework provides reusable GitHub Actions workflows and composite actions for CI/CD automation.
+
+### Structure
+
+```
+infrastructure/github/
+├── workflows/                      # Reusable workflow templates
+│   ├── dotnet-build.yml.hbs       # .NET restore, build, test
+│   ├── docker-build-push.yml.hbs  # Docker build & push
+│   ├── deploy-azure-app-service.yml.hbs  # Azure App Service deployment
+│   └── deploy-easypanel.yml.hbs   # EasyPanel deployment
+│
+└── actions/                        # Composite action templates
+    ├── docker-build-push/action.yml.hbs
+    ├── health-check/action.yml.hbs
+    └── azure-auth/action.yml.hbs
+```
+
+### Reusable Workflows vs Composite Actions
+
+| Type | Purpose | Location | Usage |
+|------|---------|----------|-------|
+| **Reusable Workflows** | Complete CI/CD pipelines (multi-job) | `workflows/*.yml.hbs` | Called via `uses:` from stack workflows |
+| **Composite Actions** | Reusable step logic (single responsibility) | `actions/*/action.yml.hbs` | Called via `uses:` in workflow steps |
+
+### Deployment Strategy Difference
+
+**Blazor-Azure:** Direct .NET publish to Azure App Service (no Docker)
+- `dotnet publish` → `azure/webapps-deploy@v2`
+- Bicep deploys App Service Plan + App Service
+- Authentication: OIDC (Federated Identity)
+
+**NextJS-Supabase:** Docker containers to EasyPanel
+- `docker build` → `docker push` → EasyPanel webhook
+- Multi-service deployment (API + Web)
+- Registry: GitHub Container Registry (ghcr.io)
+
+### Template Rendering
+
+**GitHub Actions Constraint:**
+- ❌ GitHub Actions CANNOT reference parent directories (`../../../../framework/`)
+- ✅ Solution: Framework templates are **rendered** into each stack's `.github/` directory
+- Rendered `.yml` files are **committed** to repos (not `.yml.hbs` templates)
+
+**Rendering Process:**
+```bash
+# Render all GitHub Actions templates for a stack (manual for now)
+# Future: morph-spec template render github-workflows --stack blazor-azure
+```
+
+### Handlebars Variables
+
+- `{{APP_NAME}}` - Application name from config.json
+- `{{DOTNET_VERSION}}` - .NET SDK version
+- `{{GITHUB_OWNER}}` - GitHub organization/user
+- `{{kebabCase APP_NAME}}` - Docker image name format
+- `${{{{ inputs.* }}}}` - GitHub Actions runtime syntax (escaped with `{{{{raw}}}}`)
+
+### Authentication & Secrets
+
+**Azure (Blazor-Azure):**
+```yaml
+# OIDC (Federated Identity) - Recommended
+- uses: azure/login@v1
+  with:
+    client-id: ${{{{ secrets.AZURE_CLIENT_ID }}}}
+    tenant-id: ${{{{ secrets.AZURE_TENANT_ID }}}}
+    subscription-id: ${{{{ secrets.AZURE_SUBSCRIPTION_ID }}}}
+```
+
+**Docker Registry (NextJS-Supabase):**
+```yaml
+# GitHub Container Registry (ghcr.io)
+- uses: docker/login-action@v3
+  with:
+    registry: ghcr.io
+    username: ${{{{ github.actor }}}}
+    password: ${{{{ secrets.GITHUB_TOKEN }}}}
+```
+
+**GitHub Secrets to Configure:**
+- Blazor-Azure: `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_SUBSCRIPTION_ID`
+- NextJS-Supabase: `GITHUB_TOKEN` (auto), `EASYPANEL_API_TOKEN`
+
+### Example: Blazor-Azure CI/CD
+
+**CI Build Workflow** (`stacks/blazor-azure/.morph/framework/templates/infrastructure/github/workflows/ci-build.yml.hbs`):
+```yaml
+name: CI Build
+
+on:
+  pull_request:
+    branches: [main, staging]
+
+jobs:
+  build:
+    uses: ./.github/workflows/dotnet-build.yml  # Framework template (rendered)
+    with:
+      dotnet-version: '{{DOTNET_VERSION}}'
+      run-tests: true
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check vulnerable packages
+        run: dotnet list package --vulnerable --include-transitive
+```
+
+**Production Deployment** (`cd-prod.yml.hbs`):
+```yaml
+name: Deploy to Production
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  build:
+    uses: ./.github/workflows/dotnet-build.yml
+    with:
+      dotnet-version: '{{DOTNET_VERSION}}'
+    secrets: inherit
+
+  deploy:
+    needs: build
+    uses: ./.github/workflows/deploy-azure-app-service.yml
+    with:
+      environment: 'production'
+      resource-group: 'rg-{{kebabCase APP_NAME}}-prod'
+      app-service-name: 'app-{{kebabCase APP_NAME}}-prod'
+    secrets: inherit
+```
+
+### Stack-Specific Overrides
+
+Stack-specific workflow templates in:
+- `stacks/blazor-azure/.morph/framework/templates/infrastructure/github/workflows/`
+- `stacks/nextjs-supabase/.morph/framework/templates/infrastructure/github/workflows/`
+
+**Resolution Order:**
+1. Project-local: `.morph/framework/templates/infrastructure/github/workflows/ci-build.yml.hbs`
+2. Stack default: `stacks/{stack}/.morph/framework/templates/infrastructure/github/workflows/ci-build.yml.hbs`
+3. Framework fallback: `framework/templates/infrastructure/github/workflows/dotnet-build.yml.hbs`
+
+---
+
+## 🔀 Stack Override Mechanism
+
+**Resolution Order:**
+
+1. **Stack-specific override** (highest priority)
+   - `stacks/{stack}/.morph/framework/templates/code/dotnet/backend/service.cs`
+
+2. **Project-local override** (medium priority)
+   - `.morph/framework/templates/code/dotnet/backend/service.cs`
+
+3. **Framework template** (fallback)
+   - `framework/templates/code/dotnet/backend/service.cs`
+
+**Use Cases for Overrides:**
+
+| Scenario | Override Location | Example |
+|----------|-------------------|---------|
+| Stack-specific tweak | `stacks/{stack}/.morph/framework/templates/` | Blazor uses different DI pattern |
+| Project-wide customization | `.morph/framework/templates/` | Company-specific code style |
+| Use framework default | None (no override) | Standard templates work fine |
+
+**Example:**
+
+```bash
+# Create stack override for Blazor
+morph-spec template customize dotnet-backend-service --stack blazor-azure
+
+# Edit the override
+code stacks/blazor-azure/.morph/framework/templates/code/dotnet/backend/service.cs
+
+# Now all renders for blazor-azure will use the override
+morph-spec template render dotnet-backend-service UserService.cs '...' --stack blazor-azure
+```
+
+---
+
+## 📊 Template Registry (REGISTRY.json)
+
+The `REGISTRY.json` file is the **single source of truth** for all template metadata.
+
+### Schema
+
+```json
+{
+  "version": "2.0.0",
+  "templates": [
+    {
+      "id": "dotnet-backend-service",
+      "name": ".NET Service Class",
+      "path": "code/dotnet/backend/service.cs",
+      "location": "framework",
+      "category": "code",
+      "phase": "implement",
+      "required": false,
+      "technology": "dotnet",
+      "applicableStacks": ["blazor-azure", "nextjs-supabase"],
+      "engine": "handlebars",
+      "placeholders": ["FEATURE_NAME", "NAMESPACE"],
+      "outputName": "{FeatureName}Service.cs",
+      "deprecated": false
+    }
+  ]
+}
+```
+
+### Discovery API
+
+```javascript
+import {
+  getAllTemplates,
+  getTemplateById,
+  getTemplatesByCategory,
+  getTemplatesByTechnology,
+  resolveTemplatePathById
+} from '../src/lib/template-registry.js';
+
+// Get all templates
+const all = getAllTemplates();
+
+// Get specific template
+const service = getTemplateById('dotnet-backend-service');
+
+// Filter by category
+const codeTemplates = getTemplatesByCategory('code');
+
+// Filter by technology
+const dotnetTemplates = getTemplatesByTechnology('dotnet');
+
+// Resolve path with fallback
+const path = resolveTemplatePathById('dotnet-backend-service', '/project', 'blazor-azure');
+// Returns: framework/templates/code/dotnet/backend/service.cs
+// Or: stacks/blazor-azure/.morph/framework/templates/code/dotnet/backend/service.cs (if override exists)
+```
+
+---
+
+## 🚀 Creating New Templates
+
+### 1. Create Template File
+
+```bash
+# For .NET templates
+touch framework/templates/code/dotnet/backend/my-template.cs
+
+# For infrastructure templates
+touch framework/templates/infrastructure/azure/my-resource.bicep
+```
+
+### 2. Add Handlebars Placeholders
+
+```handlebars
+namespace {{pascalCase NAMESPACE}};
+
+public class {{pascalCase FEATURE_NAME}}Service
+{
+    // TODO: Implement {{titleCase FEATURE_NAME}} logic
+}
+```
+
+### 3. Register in REGISTRY.json
+
+```json
+{
+  "id": "dotnet-backend-my-template",
+  "name": "My Custom Template",
+  "path": "code/dotnet/backend/my-template.cs",
+  "location": "framework",
+  "category": "code",
+  "phase": "implement",
+  "required": false,
+  "technology": "dotnet",
+  "applicableStacks": ["blazor-azure"],
+  "engine": "handlebars",
+  "placeholders": ["FEATURE_NAME", "NAMESPACE"],
+  "outputName": "{FeatureName}MyTemplate.cs",
+  "deprecated": false
+}
+```
+
+### 4. Test Rendering
+
+```bash
+morph-spec template render dotnet-backend-my-template output.cs '{
+  "FEATURE_NAME": "user-auth",
+  "NAMESPACE": "MyApp.Services"
+}'
+```
+
+---
+
+## 📦 Migration Guide: v1 → v2
+
+### What Changed
+
+| Aspect | v1 (Stack-Based) | v2 (Technology-Based) |
+|--------|------------------|----------------------|
+| **Location** | `stacks/{stack}/.morph/framework/templates/` | `framework/templates/{technology}/` |
+| **Organization** | By stack (blazor-azure, nextjs-supabase) | By technology (dotnet, azure, docker) |
+| **Duplication** | High (proposal.md × 2, decisions.md × 2) | Low (shared templates in framework) |
+| **Template Engine** | 3 engines (custom, Handlebars, mixed) | 1 engine (Handlebars with helpers) |
+| **Pre-computed Variables** | `{{pascalCase FEATURE_NAME}}` | `{{pascalCase FEATURE_NAME}}` (helpers) |
+| **Registry** | None (hardcoded paths) | `REGISTRY.json` (centralized metadata) |
+| **CLI** | None | `morph-spec template list/show/render/customize` |
+| **Future Stacks** | Must copy templates | Reuse existing technology templates |
+
+### Breaking Changes
+
+**1. Template Paths**
+
+```diff
+- stacks/blazor-azure/.morph/framework/templates/service.cs
++ framework/templates/code/dotnet/backend/service.cs
+
+- stacks/blazor-azure/.morph/framework/templates/infra/main.bicep
++ framework/templates/infrastructure/azure/main.bicep
+
+- stacks/nextjs-supabase/.morph/framework/templates/dockerfile-web.dockerfile
++ framework/templates/infrastructure/docker/dockerfile-web.dockerfile
+```
+
+**2. Pre-computed Variables**
+
+```diff
+- {{pascalCase FEATURE_NAME}}
++ {{pascalCase FEATURE_NAME}}
+
+- {{camelCase FEATURE_NAME}}
++ {{camelCase FEATURE_NAME}}
+
+- {{snakeCase FEATURE_NAME}}
++ {{snakeCase FEATURE_NAME}}
+```
+
+**3. Template Resolution**
+
+```javascript
+// Old (v1)
+const templatePath = join(resolveTemplatesDir(projectPath), 'service.cs');
+
+// New (v2)
+const templatePath = resolveTemplatePath(projectPath, 'code/dotnet/backend/service.cs', stackId);
+// Automatically falls back: stack override → framework
+```
+
+### Migration Steps
+
+**Step 1:** Update code to use `resolveTemplatePath()`
+
+```javascript
+import { resolveTemplatePath } from '../lib/stack-resolver.js';
+
+// Before
+const path = join(resolveTemplatesDir(process.cwd()), 'service.cs');
+
+// After
+const path = resolveTemplatePath(process.cwd(), 'code/dotnet/backend/service.cs', 'blazor-azure');
+```
+
+**Step 2:** Update template syntax to Handlebars
+
+```handlebars
+<!-- Before -->
+namespace {{NAMESPACE}};
+public class {{pascalCase FEATURE_NAME}}Service { }
+
+<!-- After -->
+namespace {{pascalCase NAMESPACE}};
+public class {{pascalCase FEATURE_NAME}}Service { }
+```
+
+**Step 3:** Use CLI commands instead of hardcoded paths
+
+```bash
+# Before (hardcoded)
+cp framework/templates/proposal.md .morph/features/user-auth/proposal.md
+
+# After (CLI)
+morph-spec template render proposal .morph/features/user-auth/proposal.md '{
+  "FEATURE_NAME": "user-auth"
+}'
+```
+
+---
+
+## 🎯 Best Practices
+
+### 1. **Use Helpers, Not Pre-computed Variables**
+
+```handlebars
+✅ GOOD:
+{{pascalCase FEATURE_NAME}}Service
+
+❌ BAD:
+{{pascalCase FEATURE_NAME}}Service  // Deprecated, won't work
+```
+
+### 2. **Keep Templates Technology-Agnostic**
+
+```handlebars
+✅ GOOD: code/dotnet/backend/service.cs
+  Works for: blazor-azure, nextjs-supabase, future-dotnet-stack
+
+❌ BAD: code/blazor/service.cs
+  Locked to Blazor only
+```
+
+### 3. **Use Stack Conditionals for Differences**
+
+```handlebars
+{{#if (eq STACK "blazor-azure")}}
+// Azure-specific implementation
+{{else if (eq STACK "nextjs-supabase")}}
+// Supabase-specific implementation
+{{else}}
+// Generic implementation
+{{/if}}
+```
+
+### 4. **Document Applicability in Registry**
+
+```json
+{
+  "technology": "dotnet",
+  "applicableStacks": ["blazor-azure", "nextjs-supabase"],
+  "description": "Works with any .NET backend stack"
+}
+```
+
+### 5. **Override Only When Necessary**
+
+```bash
+# Only customize if framework template doesn't meet needs
+morph-spec template customize dotnet-backend-service --stack blazor-azure
+
+# Otherwise, use framework version (gets updates automatically)
+morph-spec template render dotnet-backend-service output.cs '...'
+```
+
+---
+
+## 📚 References
+
+- **Template Registry API:** [`src/lib/template-registry.js`](../../src/lib/template-registry.js)
+- **Template Renderer:** [`src/lib/template-renderer.js`](../../src/lib/template-renderer.js)
+- **Stack Resolver:** [`src/lib/stack-resolver.js`](../../src/lib/stack-resolver.js)
+- **CLI Commands:** [`src/commands/template-*.js`](../../src/commands/)
+- **Handlebars Docs:** https://handlebarsjs.com/
+
+---
+
+## 🤝 Contributing
+
+### Adding New Technology
+
+1. Create directory: `framework/templates/code/{technology}/`
+2. Add templates with Handlebars syntax
+3. Register in `REGISTRY.json` with `"technology": "{technology}"`
+4. Test with `morph-spec template render`
+5. Document in this README
+
+### Deprecating Templates
+
+1. Add `"deprecated": true` to `REGISTRY.json`
+2. Add `"deprecationReason": "Reason here"`
+3. Keep file for backward compatibility or remove after major version bump
+
+---
+
+**MORPH-SPEC Template System v2.0** - Technology-Based, Future-Proof, DRY ✨