@polymorphism-tech/morph-spec 7.2.0 → 7.3.0

package/framework/templates/README.md

@@ -1,709 +1,708 @@
-# 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, 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
-│   │   ├── 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/
-│       ├── postgresql-migration.sql          # Basic migration
-│       ├── postgresql-migration.template.sql # Enhanced migration
-│       └── postgresql-rls-policy.sql                  # Row-level security
-│
-├── infrastructure/
-│   ├── 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-easypanel.yml.hbs   # EasyPanel deployment
-│       │
-│       ├── actions/                        # Composite action templates
-│       │   ├── docker-build-push/action.yml.hbs
-│       │   └── health-check/action.yml.hbs
-│       │
-│       └── README.md                       # GitHub Actions docs
-│
-├── integrations/      # Platform-agnostic integrations
-│   ├── asaas-client.cs           # Asaas financial API
-│   ├── asaas-webhook.cs          # Asaas webhooks
-│   └── neon-auth-config.cs       # Neon Auth (Better Auth)
-│
-├── ui/                # Design systems
-│   └── design-system.css         # CSS tokens
-│
-├── saas/              # Multi-tenant patterns
-│
-├── 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 `dotnet-nextjs` and `nextjs-neon` 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 (Neon Auth, 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}}` | `"nextjs" "nextjs"` | `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 "nextjs-neon")}}
-// Neon-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 dotnet-nextjs
-
-# 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)
-  ...
-```
-
-### 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: dotnet-nextjs, nextjs-neon
-
-📝 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 dotnet-nextjs
-
-# 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 dotnet-nextjs --force
-```
-
-**Output:**
-```
-Source: framework/templates/code/dotnet/backend/service.cs
-Destination: stacks/dotnet-nextjs/.morph/framework/templates/code/dotnet/backend/service.cs
-
-✅ Template copied for customization
-
-📝 Next Steps
-  1. Edit the template file:
-     stacks/dotnet-nextjs/.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-easypanel.yml.hbs   # EasyPanel deployment
-│
-└── actions/                        # Composite action templates
-    ├── docker-build-push/action.yml.hbs
-    └── health-check/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
-
-**NextJS-Neon:** 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 dotnet-nextjs
-```
-
-### 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
-
-**Docker Registry (NextJS-Neon):**
-```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:**
-- NextJS-Neon: `GITHUB_TOKEN` (auto), `EASYPANEL_API_TOKEN`
-
-### Stack-Specific Overrides
-
-Stack-specific workflow templates in:
-- `stacks/nextjs-neon/.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/` | Stack 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
-morph-spec template customize dotnet-backend-service --stack dotnet-nextjs
-
-# Edit the override
-code stacks/dotnet-nextjs/.morph/framework/templates/code/dotnet/backend/service.cs
-
-# Now all renders for dotnet-nextjs will use the override
-morph-spec template render dotnet-backend-service UserService.cs '...' --stack dotnet-nextjs
-```
-
----
-
-## 📊 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": ["dotnet-nextjs", "nextjs-neon"],
-      "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', 'dotnet-nextjs');
-// Returns: framework/templates/code/dotnet/backend/service.cs
-// Or: stacks/dotnet-nextjs/.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/docker/my-resource.dockerfile
-```
-
-### 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": ["dotnet-nextjs"],
-  "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 (dotnet-nextjs, nextjs-neon) | By technology (dotnet, 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/dotnet-nextjs/.morph/framework/templates/service.cs
-+ framework/templates/code/dotnet/backend/service.cs
-
-- stacks/nextjs-neon/.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', 'dotnet-nextjs');
-```
-
-**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: dotnet-nextjs, nextjs-neon, future-dotnet-stack
-
-❌ BAD: code/stack-specific/service.cs
-  Locked to one stack only
-```
-
-### 3. **Use Stack Conditionals for Differences**
-
-```handlebars
-{{#if (eq STACK "nextjs-neon")}}
-// Neon-specific implementation
-{{else}}
-// Generic implementation
-{{/if}}
-```
-
-### 4. **Document Applicability in Registry**
-
-```json
-{
-  "technology": "dotnet",
-  "applicableStacks": ["dotnet-nextjs", "nextjs-neon"],
-  "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 dotnet-nextjs
-
-# 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 ✨
+# 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, 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
+│   ├── 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
+│   │   ├── 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/
+│       ├── postgresql-migration.sql          # Basic migration
+│       ├── postgresql-migration.template.sql # Enhanced migration
+│       └── postgresql-rls-policy.sql                  # Row-level security
+│
+├── infrastructure/
+│   ├── 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-easypanel.yml.hbs   # EasyPanel deployment
+│       │
+│       ├── actions/                        # Composite action templates
+│       │   ├── docker-build-push/action.yml.hbs
+│       │   └── health-check/action.yml.hbs
+│       │
+│       └── README.md                       # GitHub Actions docs
+│
+├── integrations/      # Platform-agnostic integrations
+│   ├── asaas-client.cs           # Asaas financial API
+│   ├── asaas-webhook.cs          # Asaas webhooks
+│   └── neon-auth-config.cs       # Neon Auth (Better Auth)
+│
+├── ui/                # Design systems
+│   └── design-system.css         # CSS tokens
+│
+├── saas/              # Multi-tenant patterns
+│
+├── 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 `dotnet-nextjs` and `nextjs-neon` 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 (Neon Auth, 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}}` | `"nextjs" "nextjs"` | `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 "nextjs-neon")}}
+// Neon-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 dotnet-nextjs
+
+# 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)
+  ...
+```
+
+### 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: dotnet-nextjs, nextjs-neon
+
+📝 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 dotnet-nextjs
+
+# 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 dotnet-nextjs --force
+```
+
+**Output:**
+```
+Source: framework/templates/code/dotnet/backend/service.cs
+Destination: stacks/dotnet-nextjs/.morph/framework/templates/code/dotnet/backend/service.cs
+
+✅ Template copied for customization
+
+📝 Next Steps
+  1. Edit the template file:
+     stacks/dotnet-nextjs/.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-easypanel.yml.hbs   # EasyPanel deployment
+│
+└── actions/                        # Composite action templates
+    ├── docker-build-push/action.yml.hbs
+    └── health-check/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
+
+**NextJS-Neon:** 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 dotnet-nextjs
+```
+
+### 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
+
+**Docker Registry (NextJS-Neon):**
+```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:**
+- NextJS-Neon: `GITHUB_TOKEN` (auto), `EASYPANEL_API_TOKEN`
+
+### Stack-Specific Overrides
+
+Stack-specific workflow templates in:
+- `stacks/nextjs-neon/.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/` | Stack 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
+morph-spec template customize dotnet-backend-service --stack dotnet-nextjs
+
+# Edit the override
+code stacks/dotnet-nextjs/.morph/framework/templates/code/dotnet/backend/service.cs
+
+# Now all renders for dotnet-nextjs will use the override
+morph-spec template render dotnet-backend-service UserService.cs '...' --stack dotnet-nextjs
+```
+
+---
+
+## 📊 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": ["dotnet-nextjs", "nextjs-neon"],
+      "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', 'dotnet-nextjs');
+// Returns: framework/templates/code/dotnet/backend/service.cs
+// Or: stacks/dotnet-nextjs/.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/docker/my-resource.dockerfile
+```
+
+### 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": ["dotnet-nextjs"],
+  "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 (dotnet-nextjs, nextjs-neon) | By technology (dotnet, 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/dotnet-nextjs/.morph/framework/templates/service.cs
++ framework/templates/code/dotnet/backend/service.cs
+
+- stacks/nextjs-neon/.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', 'dotnet-nextjs');
+```
+
+**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: dotnet-nextjs, nextjs-neon, future-dotnet-stack
+
+❌ BAD: code/stack-specific/service.cs
+  Locked to one stack only
+```
+
+### 3. **Use Stack Conditionals for Differences**
+
+```handlebars
+{{#if (eq STACK "nextjs-neon")}}
+// Neon-specific implementation
+{{else}}
+// Generic implementation
+{{/if}}
+```
+
+### 4. **Document Applicability in Registry**
+
+```json
+{
+  "technology": "dotnet",
+  "applicableStacks": ["dotnet-nextjs", "nextjs-neon"],
+  "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 dotnet-nextjs
+
+# 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 ✨