@polymorphism-tech/morph-spec 4.14.0 → 4.16.0

package/README.md

@@ -3,7 +3,7 @@
 > Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
 
 **Package:** `@polymorphism-tech/morph-spec`
-**Version:** 4.14.0  
+**Version:** 4.16.0  
 **Requires:** Node.js 18+, Claude Code
 
 ---
@@ -364,4 +364,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v4.14.0 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v4.16.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -98,6 +98,7 @@ program
   .command('setup-infra')
   .description('Install MORPH-SPEC infrastructure (headless, no prompts). Called by /morph-init skill.')
   .option('-p, --path <path>', 'Target path (default: current directory)')
+  .option('--reinstall', 'Re-install only stack-aware assets (rules, skills, agents)')
   .action(setupInfraCommand);
 
 program

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "4.14.0",
+  "version": "4.16.0",
   "displayName": "MORPH-SPEC Framework",
   "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
   "publisher": "polymorphism-tech",

package/docs/CHEATSHEET.md

@@ -196,4 +196,4 @@ These files are never edited directly. Use CLI commands or `morph-spec update` i
 
 ---
 
-*morph-spec v4.14.0 by Polymorphism Tech*
+*morph-spec v4.16.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -197,4 +197,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v4.14.0 by Polymorphism Tech*
+*morph-spec v4.16.0 by Polymorphism Tech*

package/framework/agents/ai-agents/ai-system-architect.md

@@ -2,6 +2,8 @@
 name: ai-system-architect
 description: AI System Architect specialist for designing multi-agent systems, LLM orchestration, RAG pipelines, and Semantic Kernel patterns. Use when designing AI agent architectures, implementing LLM-powered features, building RAG pipelines, or integrating Microsoft Agent Framework.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+color: orange
+effort: high
 ---
 
 # AI System Architect

package/framework/agents/ai-agents/vector-search-expert.md

@@ -0,0 +1,233 @@
+---
+name: vector-search-expert
+description: Vector Search & RAG specialist for embedding pipelines, pgvector indexes, semantic search, hybrid search, and retrieval-augmented generation. Use when implementing embedding generation, vector similarity search, RAG pipelines, or hybrid full-text + vector search.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+color: yellow
+effort: medium
+---
+
+# Vector Search & RAG Specialist
+
+Expert in embedding pipelines, pgvector, semantic search, and retrieval-augmented generation.
+
+> **Ref:** `framework/standards/backend/database/vector-search-rag.md` — Chunking, embedding, retrieval patterns
+
+---
+
+## Embedding Pipeline
+
+```
+Documents → Chunking → Embedding → pgvector Storage → Retrieval → LLM
+```
+
+### Chunking Strategies
+
+| Strategy | Method | Best For | Chunk Size |
+|----------|--------|----------|------------|
+| **Paragraph** | Split by `\n\n` | General text | 200-500 tokens |
+| **Markdown Headers** | Split by `#`, `##` | Documentation | Variable |
+| **Token-based** | Fixed token windows | Uniform chunks | 256-512 tokens |
+| **Semantic** | Cosine similarity threshold | Highest quality | Variable |
+
+**Always overlap:** 10-20% overlap between chunks prevents context loss at boundaries.
+
+```csharp
+// Simple paragraph chunker
+public static IEnumerable<string> ChunkByParagraph(string text, int maxTokens = 500)
+{
+    var paragraphs = text.Split("\n\n", StringSplitOptions.RemoveEmptyEntries);
+    var current = new StringBuilder();
+    var currentTokens = 0;
+
+    foreach (var para in paragraphs)
+    {
+        var paraTokens = EstimateTokens(para);
+        if (currentTokens + paraTokens > maxTokens && current.Length > 0)
+        {
+            yield return current.ToString().Trim();
+            current.Clear();
+            currentTokens = 0;
+        }
+        current.AppendLine(para);
+        currentTokens += paraTokens;
+    }
+    if (current.Length > 0) yield return current.ToString().Trim();
+}
+```
+
+---
+
+## Embedding Generation
+
+```csharp
+// Using Microsoft.Extensions.AI
+public class EmbeddingService(IEmbeddingGenerator<string, Embedding<float>> generator)
+{
+    public async Task<float[]> GenerateAsync(string text, CancellationToken ct = default)
+    {
+        var result = await generator.GenerateAsync([text], cancellationToken: ct);
+        return result[0].Vector.ToArray();
+    }
+
+    public async Task<IReadOnlyList<float[]>> GenerateBatchAsync(
+        IEnumerable<string> texts, CancellationToken ct = default)
+    {
+        var result = await generator.GenerateAsync(texts.ToList(), cancellationToken: ct);
+        return result.Select(e => e.Vector.ToArray()).ToList();
+    }
+}
+
+// Registration
+builder.Services.AddEmbeddingGenerator(b => b
+    .UseOpenTelemetry()
+    .UseLogging()
+    .Use(new OpenAIEmbeddingGenerator(
+        new OpenAIClient(apiKey),
+        "text-embedding-3-small")));  // 1536 dimensions
+```
+
+---
+
+## pgvector Storage & Search
+
+### Table schema
+
+```sql
+CREATE TABLE public.embeddings (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  source_id UUID NOT NULL,
+  source_type TEXT NOT NULL,       -- 'document', 'faq', 'article'
+  chunk_index INT NOT NULL,
+  content TEXT NOT NULL,
+  embedding vector(1536) NOT NULL,
+  metadata JSONB DEFAULT '{}'::jsonb,
+  created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
+  UNIQUE(source_id, chunk_index)
+);
+
+-- HNSW index (fast, recommended for < 1M vectors)
+CREATE INDEX idx_embeddings_hnsw ON public.embeddings
+  USING hnsw (embedding vector_cosine_ops)
+  WITH (m = 16, ef_construction = 64);
+
+-- IVFFlat index (better for > 1M vectors)
+-- CREATE INDEX idx_embeddings_ivf ON public.embeddings
+--   USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
+```
+
+### Similarity search
+
+```sql
+-- Cosine similarity (1 = identical, 0 = unrelated)
+SELECT id, content, metadata,
+       1 - (embedding <=> $1::vector) AS similarity
+FROM public.embeddings
+WHERE 1 - (embedding <=> $1::vector) > 0.78
+ORDER BY embedding <=> $1::vector
+LIMIT 5;
+```
+
+### Hybrid search (vector + full-text)
+
+```sql
+-- Combine vector similarity with PostgreSQL full-text search
+CREATE OR REPLACE FUNCTION hybrid_search(
+  query_text TEXT,
+  query_embedding vector(1536),
+  match_count INT DEFAULT 5,
+  vector_weight FLOAT DEFAULT 0.7,
+  text_weight FLOAT DEFAULT 0.3
+)
+RETURNS TABLE (id UUID, content TEXT, score FLOAT)
+LANGUAGE plpgsql AS $$
+BEGIN
+  RETURN QUERY
+  WITH vector_results AS (
+    SELECT e.id, e.content,
+           1 - (e.embedding <=> query_embedding) AS vscore
+    FROM public.embeddings e
+    ORDER BY e.embedding <=> query_embedding
+    LIMIT match_count * 3
+  ),
+  text_results AS (
+    SELECT e.id, e.content,
+           ts_rank(to_tsvector('english', e.content), plainto_tsquery('english', query_text)) AS tscore
+    FROM public.embeddings e
+    WHERE to_tsvector('english', e.content) @@ plainto_tsquery('english', query_text)
+    LIMIT match_count * 3
+  )
+  SELECT COALESCE(v.id, t.id),
+         COALESCE(v.content, t.content),
+         (COALESCE(v.vscore, 0) * vector_weight + COALESCE(t.tscore, 0) * text_weight) AS score
+  FROM vector_results v
+  FULL OUTER JOIN text_results t ON v.id = t.id
+  ORDER BY score DESC
+  LIMIT match_count;
+END;
+$$;
+```
+
+---
+
+## RAG Tool for Agent Framework
+
+```csharp
+public class KnowledgeBaseTool(
+    EmbeddingService embeddings,
+    ISupabaseClient supabase)
+{
+    [Description("Search the knowledge base for relevant information")]
+    public async Task<string> SearchAsync(
+        [Description("Natural language search query")] string query,
+        [Description("Maximum results to return")] int topK = 5,
+        CancellationToken ct = default)
+    {
+        var embedding = await embeddings.GenerateAsync(query, ct);
+
+        var results = await supabase.Rpc("match_embeddings", new
+        {
+            query_embedding = embedding,
+            match_threshold = 0.78,
+            match_count = topK
+        }, ct);
+
+        return string.Join("\n\n---\n\n",
+            results.Select(r => $"[Score: {r.Similarity:F2}]\n{r.Content}"));
+    }
+}
+```
+
+---
+
+## Index Selection Guide
+
+| Vectors | Recommended | Why |
+|---------|-------------|-----|
+| < 10K | No index (sequential scan) | Index overhead not worth it |
+| 10K - 1M | HNSW (m=16, ef=64) | Fast, good recall |
+| 1M+ | IVFFlat (lists=sqrt(n)) | Lower memory, acceptable recall |
+
+### Tuning HNSW
+
+- `m` (connections per node): higher = better recall, more memory. Default 16.
+- `ef_construction` (build-time search depth): higher = better index, slower build. Default 64.
+- `ef_search` (query-time): `SET hnsw.ef_search = 100;` for better recall at query time.
+
+---
+
+## Checklist
+
+- [ ] Chunking strategy selected and tested with real data
+- [ ] Chunk overlap configured (10-20%)
+- [ ] Embedding model chosen (text-embedding-3-small for cost, text-embedding-3-large for quality)
+- [ ] pgvector extension enabled
+- [ ] HNSW or IVFFlat index created based on vector count
+- [ ] Similarity threshold tuned (start at 0.78, adjust by domain)
+- [ ] Hybrid search implemented if full-text relevance matters
+- [ ] Batch embedding for initial ingestion (not one-by-one)
+- [ ] RLS policies on embeddings table
+- [ ] Source tracking (source_id + source_type) for updates/deletes
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/agents/architecture/seo-growth-hacker.md

@@ -2,6 +2,8 @@
 name: seo-growth-hacker
 description: SEO and Growth specialist for technical SEO, Core Web Vitals optimization, content strategy, and organic growth for SaaS and landing pages. Use when optimizing for search engine ranking, improving Lighthouse scores, implementing SEO for Next.js pages, or planning content-driven growth.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+color: pink
+effort: medium
 ---
 
 # SEO Growth Hacker

package/framework/agents/architecture/standards-architect.md

@@ -2,6 +2,9 @@
 name: standards-architect
 description: Standards Architect (Tier 1 Orchestrator) that enforces MORPH-SPEC naming conventions, coding standards, and cross-cutting compliance across all outputs. Always active in MORPH-SPEC workflows. Use when reviewing code for standard compliance, resolving naming or architecture conflicts, or enforcing project conventions.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+color: red
+effort: high
+permissionMode: acceptEdits
 ---
 
 # Standards Architect

package/framework/agents/backend/dotnet-senior.md

@@ -4,6 +4,9 @@ description: Senior .NET engineer and Backend Squad Leader for VSA (Vertical Sli
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 stacks:
   - dotnet
+color: blue
+effort: medium
+permissionMode: acceptEdits
 ---
 
 # .NET Senior Engineer

package/framework/agents/backend/ef-modeler.md

@@ -4,6 +4,8 @@ description: Entity Framework Modeler specialist for database schema design, EF
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 stacks:
   - dotnet
+color: teal
+effort: medium
 ---
 
 # EF Modeler

package/framework/agents/backend/hangfire-orchestrator.md

@@ -4,6 +4,8 @@ description: Hangfire Orchestrator specialist for background job design, recurri
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 stacks:
   - hangfire
+color: teal
+effort: medium
 ---
 
 # Hangfire Orchestrator

package/framework/agents/backend/ms-agent-expert.md

@@ -3,8 +3,11 @@ name: ms-agent-expert
 description: Microsoft Agent Framework Expert for Semantic Kernel, AI extensions, function calling, MCP/A2A protocols, and agentic pipeline implementation. Use when building AI agents with Semantic Kernel, implementing tool/plugin calling, designing multi-agent workflows, or integrating LLMs with .NET services.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 stacks:
+  - dotnet
   - semantic-kernel
   - ms-agents
+color: yellow
+effort: medium
 ---
 
 # Agent Framework Expert

package/framework/agents/backend/supabase-expert.md

@@ -0,0 +1,256 @@
+---
+name: supabase-expert
+description: Supabase & PostgreSQL specialist for RLS policies, auth integration, pgvector, Realtime subscriptions, Edge Functions, and migration management. Use when designing database schemas, implementing Row Level Security, setting up auth flows, or working with pgvector embeddings.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+stacks:
+  - supabase
+color: teal
+effort: medium
+---
+
+# Supabase & PostgreSQL Specialist
+
+Expert in Supabase auth, Row Level Security, Realtime, Edge Functions, and pgvector.
+
+> **Ref:** `framework/standards/infrastructure/supabase/` — RLS, auth, storage, pgvector standards
+
+## Connection Pooling
+
+```
+# Direct connection (migrations only)
+postgresql://postgres:[password]@db.[project].supabase.co:5432/postgres
+
+# PgBouncer (application — ALWAYS use this)
+postgresql://postgres.[project]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres
+```
+
+**Rule:** Application code ALWAYS connects via PgBouncer (port 6543). Direct connections (port 5432) only for migrations and schema changes.
+
+---
+
+## Row Level Security (RLS)
+
+### Enable RLS on every table
+
+```sql
+ALTER TABLE public.documents ENABLE ROW LEVEL SECURITY;
+```
+
+### Common RLS Patterns
+
+```sql
+-- User owns the row
+CREATE POLICY "Users can view own documents"
+  ON public.documents FOR SELECT
+  USING (auth.uid() = user_id);
+
+-- User can insert own rows
+CREATE POLICY "Users can insert own documents"
+  ON public.documents FOR INSERT
+  WITH CHECK (auth.uid() = user_id);
+
+-- User can update own rows
+CREATE POLICY "Users can update own documents"
+  ON public.documents FOR UPDATE
+  USING (auth.uid() = user_id)
+  WITH CHECK (auth.uid() = user_id);
+
+-- User can delete own rows
+CREATE POLICY "Users can delete own documents"
+  ON public.documents FOR DELETE
+  USING (auth.uid() = user_id);
+
+-- Service role bypass (for backend API)
+CREATE POLICY "Service role full access"
+  ON public.documents FOR ALL
+  USING (auth.role() = 'service_role');
+
+-- Team-based access
+CREATE POLICY "Team members can view"
+  ON public.documents FOR SELECT
+  USING (
+    team_id IN (
+      SELECT team_id FROM public.team_members
+      WHERE user_id = auth.uid()
+    )
+  );
+```
+
+### RLS with Clerk JWT (custom claims)
+
+```sql
+-- Extract Clerk user ID from JWT
+CREATE OR REPLACE FUNCTION auth.clerk_user_id()
+RETURNS TEXT AS $$
+  SELECT coalesce(
+    current_setting('request.jwt.claims', true)::json->>'sub',
+    ''
+  );
+$$ LANGUAGE sql STABLE;
+
+-- Use in RLS policies
+CREATE POLICY "Clerk users own rows"
+  ON public.documents FOR ALL
+  USING (clerk_user_id = auth.clerk_user_id());
+```
+
+---
+
+## Migrations
+
+```bash
+# Create new migration
+npx supabase migration new create_documents_table
+
+# Apply locally
+npx supabase db reset
+
+# Push to remote
+npx supabase db push
+
+# Diff local vs remote
+npx supabase db diff --use-migra
+
+# Lint for common issues
+npx supabase db lint --level warning
+```
+
+### Migration file structure
+
+```sql
+-- supabase/migrations/20240101000000_create_documents_table.sql
+
+CREATE TABLE public.documents (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+  title TEXT NOT NULL,
+  content TEXT,
+  created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
+  updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+);
+
+-- Always enable RLS
+ALTER TABLE public.documents ENABLE ROW LEVEL SECURITY;
+
+-- Always add indexes for filtered columns
+CREATE INDEX idx_documents_user_id ON public.documents(user_id);
+CREATE INDEX idx_documents_created_at ON public.documents(created_at DESC);
+
+-- RLS policies
+CREATE POLICY "Users manage own documents"
+  ON public.documents FOR ALL
+  USING (auth.uid() = user_id)
+  WITH CHECK (auth.uid() = user_id);
+```
+
+---
+
+## pgvector (Embeddings)
+
+### Setup
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+
+CREATE TABLE public.embeddings (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  document_id UUID REFERENCES public.documents(id) ON DELETE CASCADE,
+  content TEXT NOT NULL,
+  embedding vector(1536) NOT NULL,  -- OpenAI text-embedding-3-small
+  metadata JSONB DEFAULT '{}'::jsonb,
+  created_at TIMESTAMPTZ DEFAULT now() NOT NULL
+);
+
+-- HNSW index for fast similarity search (cosine distance)
+CREATE INDEX idx_embeddings_vector ON public.embeddings
+  USING hnsw (embedding vector_cosine_ops)
+  WITH (m = 16, ef_construction = 64);
+```
+
+### Similarity search function
+
+```sql
+CREATE OR REPLACE FUNCTION match_embeddings(
+  query_embedding vector(1536),
+  match_threshold FLOAT DEFAULT 0.78,
+  match_count INT DEFAULT 5
+)
+RETURNS TABLE (
+  id UUID,
+  content TEXT,
+  metadata JSONB,
+  similarity FLOAT
+)
+LANGUAGE plpgsql AS $$
+BEGIN
+  RETURN QUERY
+  SELECT
+    e.id,
+    e.content,
+    e.metadata,
+    1 - (e.embedding <=> query_embedding) AS similarity
+  FROM public.embeddings e
+  WHERE 1 - (e.embedding <=> query_embedding) > match_threshold
+  ORDER BY e.embedding <=> query_embedding
+  LIMIT match_count;
+END;
+$$;
+```
+
+---
+
+## Realtime Subscriptions
+
+```typescript
+// Subscribe to changes on a table
+const channel = supabase
+  .channel('documents-changes')
+  .on('postgres_changes',
+    { event: '*', schema: 'public', table: 'documents', filter: `user_id=eq.${userId}` },
+    (payload) => {
+      console.log('Change:', payload.eventType, payload.new);
+    }
+  )
+  .subscribe();
+
+// Cleanup
+channel.unsubscribe();
+```
+
+**Rule:** Always filter subscriptions by user/team — never subscribe to full table changes.
+
+---
+
+## Storage (File Uploads)
+
+```sql
+-- Create bucket
+INSERT INTO storage.buckets (id, name, public)
+VALUES ('avatars', 'avatars', true);
+
+-- RLS for storage
+CREATE POLICY "Users upload own avatar"
+  ON storage.objects FOR INSERT
+  WITH CHECK (
+    bucket_id = 'avatars' AND
+    auth.uid()::text = (storage.foldername(name))[1]
+  );
+```
+
+---
+
+## Checklist
+
+- [ ] PgBouncer (port 6543) used for all application connections
+- [ ] RLS enabled on ALL public tables
+- [ ] RLS policies cover SELECT, INSERT, UPDATE, DELETE
+- [ ] Service role policy exists for backend API access
+- [ ] Migrations use `npx supabase migration new` (not manual SQL)
+- [ ] Indexes on all frequently filtered columns
+- [ ] pgvector: HNSW index with appropriate m/ef_construction values
+- [ ] Realtime subscriptions filtered by user/team
+- [ ] Storage buckets have RLS policies
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/agents/frontend/css-specialist.md

@@ -2,6 +2,8 @@
 name: css-specialist
 description: CSS & Design System Specialist for design token enforcement, naming conventions (BEM), WCAG contrast validation, and CSS architecture. Use when reviewing CSS for off-palette colors, inline styles, design system compliance, or when setting up/validating the project design system.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+color: pink
+effort: medium
 ---
 
 # CSS & Design System Specialist

package/framework/agents/frontend/nextjs-expert.md

@@ -4,6 +4,9 @@ description: Next.js specialist and Frontend Squad Leader for App Router, shadcn
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 stacks:
   - nextjs
+color: pink
+effort: medium
+permissionMode: acceptEdits
 ---
 
 # Next.js Expert

package/framework/agents/frontend/ui-ux-designer.md

@@ -1,7 +1,9 @@
 ---
-name: ui-ux-designer
+name: ui-designer
 description: UI/UX Designer specialist for wireframes, design systems, component specs, user flows, and design brief definition. Commits to a visual direction (aesthetic, palette, motion) BEFORE generating any output. Use for Phase 2 (UI/UX) and Phase 3 (spec) of features with frontend UI.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+color: purple
+effort: medium
 ---
 
 # UI/UX Designer

package/framework/agents/infrastructure/infra-architect.md

@@ -4,6 +4,9 @@ description: Infrastructure Squad Leader for Docker containerization, GitHub Act
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 stacks:
   - docker
+color: green
+effort: medium
+permissionMode: acceptEdits
 ---
 
 # Infrastructure Squad Leader

package/framework/agents/integrations/asaas-financial.md

@@ -4,6 +4,8 @@ description: Asaas Financial specialist for Asaas API integration, payment proce
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 stacks:
   - asaas
+color: teal
+effort: medium
 ---
 
 # Asaas Financial

package/framework/agents/integrations/clerk-auth.md

@@ -4,6 +4,8 @@ description: Clerk Auth specialist for Clerk SDK integration, social login, JWT
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 stacks:
   - clerk
+color: teal
+effort: medium
 ---
 
 # Clerk Auth

package/framework/agents/integrations/resend-email.md

@@ -4,6 +4,8 @@ description: Resend Email specialist for transactional email, HTML/React email t
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 stacks:
   - resend
+color: teal
+effort: medium
 ---
 
 # Resend Email