@polymorphism-tech/morph-spec 4.3.6 → 4.5.0

package/framework/standards/ai-agents/team-orchestration.md

@@ -263,13 +263,13 @@ Each reviewer reports findings to the lead, then synthesize into review.md
 - `CLAUDE.md` (MORPH-SPEC instructions)
 - `.claude/skills/` (all available skills)
 - `.morph/config.json` (project configuration)
-- `framework/standards/` + `.morph/standards/`
+- `framework/standards/` + `.morph/framework/standards/`
 
 **Pass task-specific context in spawn prompt:**
 ```
 Spawn backend teammate with prompt: "Implement scheduled reports feature.
 Active agents: ef-modeler, hangfire-orchestrator, dotnet-senior.
-Read .morph/project/outputs/scheduled-reports/spec.md and contracts.cs.
+Read .morph/features/scheduled-reports/1-design/spec.md and contracts.cs.
 Follow Blazor concurrency patterns from framework/standards/blazor-state.md.
 All background jobs MUST use IDbContextFactory (scoped repository pattern)."
 ```
@@ -357,7 +357,7 @@ rm -rf ~/.claude/teams/scheduled-reports
 ```json
 {
   "dangerouslySkipPermissions": {
-    "allowedPaths": [".morph/project/outputs/**"],
+    "allowedPaths": [".morph/features/**"],
     "allowedCommands": ["morph-spec task done", "morph-spec validate-*"]
   }
 }

package/framework/standards/frontend/nextjs/nextjs-patterns.md

@@ -196,3 +196,20 @@ Components are copied to `components/ui/` -- NOT an npm dependency, your code to
 | `useEffect` for data fetching | React Query `useQuery` | No caching, race conditions |
 | Form validation on submit only | Zod resolver + react-hook-form | Delayed error feedback |
 | shadcn as npm package | `npx shadcn@latest add` | Copy-paste system, not a dependency |
+
+## TypeScript Strict Mode (Required)
+
+Always enable `"strict": true` in `tsconfig.json`. This is non-negotiable for
+agent-assisted development because agents rely on compiler errors to self-correct.
+Without strict mode, type/null errors only surface at runtime where agents cannot observe them.
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true
+  }
+}
+```
+
+Strict mode enables: `strictNullChecks`, `noImplicitAny`, `strictFunctionTypes`, `strictPropertyInitialization`.

package/framework/standards/integration/mcp/mcp-tools.md

@@ -0,0 +1,384 @@
+# Integration Standard: MCP Tools in MORPH Workflows
+
+> Reference for using Model Context Protocol (MCP) tools across morph-spec phases. Each phase benefits from different MCPs depending on what data is needed.
+
+## MCP Availability Detection
+
+Before using any MCP tool, check if it's available in the current session:
+
+```javascript
+// Pattern: Attempt the call — if the tool doesn't exist, Claude Code will report it
+// There is no "list MCPs" command; just try the most common operation
+
+// Supabase MCP
+await mcp__supabase__list_tables();
+
+// GitHub MCP
+await mcp__github__get_repo();
+
+// Context7 (library docs)
+await mcp__context7__resolve_library_id({ libraryName: "react" });
+
+// Playwright (browser automation)
+await mcp__playwright__browser_navigate({ url: "https://example.com" });
+```
+
+**Fallback rule:** If an MCP is not available, every phase has a manual alternative using Claude Code native tools (Read, Grep, Glob, Bash).
+
+---
+
+## MCP Providers by Phase
+
+### Phase 1 (Setup) — Project Discovery
+
+| MCP | Use Case | Example |
+|-----|----------|---------|
+| **GitHub** | Repo info, recent PRs, issues | `mcp__github__get_repo()` |
+| **Filesystem** | Scan project structure | Native Glob/Read preferred |
+
+```javascript
+// Detect project type from repo metadata
+const repo = await mcp__github__get_repo();
+// → language, default_branch, topics
+
+// Fallback: use Glob to detect stack
+// Glob: "**/{package.json,*.csproj,*.sln,go.mod,Cargo.toml}"
+```
+
+### Phase 1.5 (UI/UX) — Design References
+
+| MCP | Use Case | Example |
+|-----|----------|---------|
+| **Figma** | Extract design tokens, components | `mcp__figma__get_file({ fileKey })` |
+| **Playwright** | Navigate, screenshot, inspect live pages | `mcp__playwright__browser_navigate({ url })` |
+| **Context7** | Component library documentation | `mcp__context7__query_docs({ libraryId, query })` |
+
+```javascript
+// Get design tokens from Figma
+const file = await mcp__figma__get_file({ fileKey: "abc123" });
+// → colors, typography, spacing from design file
+
+// Screenshot existing app for design reference
+await mcp__playwright__browser_navigate({ url: "https://app.example.com/dashboard" });
+const screenshot = await mcp__playwright__browser_take_screenshot();
+// → Visual reference for UI/UX design
+
+// Inspect page structure via accessibility tree
+const snapshot = await mcp__playwright__browser_snapshot();
+// → Structured element tree (headings, buttons, inputs, etc.)
+
+// Test responsive layout
+await mcp__playwright__browser_resize({ width: 375, height: 812 });
+const mobileScreenshot = await mcp__playwright__browser_take_screenshot();
+
+// Get MudBlazor component docs for UI specs
+const libId = await mcp__context7__resolve_library_id({
+  libraryName: "mudblazor",
+  query: "data grid with sorting and filtering"
+});
+const docs = await mcp__context7__query_docs({
+  libraryId: libId,
+  query: "DataGrid component props and events"
+});
+
+// Fallback: WebSearch for component documentation
+// WebFetch for specific component API pages
+```
+
+### Phase 2 (Design) — Schema & Architecture
+
+| MCP | Use Case | Example |
+|-----|----------|---------|
+| **Supabase** | Database schema, tables, relationships, RLS | `mcp__supabase__get_table_schema({ table })` |
+| **Database MCPs** | PostgreSQL, MySQL, SQL Server schema | Provider-specific tools |
+| **Context7** | Library docs for architecture decisions | `mcp__context7__query_docs()` |
+| **GitHub** | Check existing code patterns, PRs | `mcp__github__search_code()` |
+
+```javascript
+// === SCHEMA ANALYSIS (Critical for contracts.cs) ===
+
+// 1. List all tables
+const tables = await mcp__supabase__list_tables();
+
+// 2. Get schema for each relevant table
+const schema = await mcp__supabase__get_table_schema({ table: 'leads' });
+// → column_name, data_type, is_nullable, column_default
+
+// 3. Get foreign key relationships
+const rels = await mcp__supabase__get_relationships({ table: 'leads' });
+// → foreign_table, foreign_column, constraint_type
+
+// 4. Run custom query for complex schema info
+const result = await mcp__supabase__query({
+  query: `SELECT column_name, data_type, is_nullable
+          FROM information_schema.columns
+          WHERE table_name = 'leads'
+          ORDER BY ordinal_position`
+});
+
+// 5. Check RLS policies (security-critical)
+const policies = await mcp__supabase__query({
+  query: `SELECT tablename, policyname, cmd, qual
+          FROM pg_policies
+          WHERE tablename = 'leads'`
+});
+```
+
+**Fallback (no Supabase MCP):**
+```
+1. Grep: "\.from\(|\.select\(|SELECT |supabase\.|DbSet<" → find query files
+2. Read each query file → extract table/column names
+3. Glob: "src/**/types/**/*.ts" or "**/Entities/**/*.cs" → find type definitions
+4. Read type files → map properties to database columns
+```
+
+### Phase 3 (Clarify) — Validation & Research
+
+| MCP | Use Case | Example |
+|-----|----------|---------|
+| **Context7** | Verify library capabilities, API limits | `mcp__context7__query_docs()` |
+| **GitHub** | Check issue discussions, known limitations | `mcp__github__search_issues()` |
+
+```javascript
+// Verify if library supports a required feature
+const docs = await mcp__context7__query_docs({
+  libraryId: "/mudblazor/mudblazor",
+  query: "DataGrid server-side pagination with virtual scrolling"
+});
+// → Confirms capability or identifies limitation for spec update
+
+// Fallback: WebSearch for library capabilities
+```
+
+### Phase 4 (Tasks) — Planning & Organization
+
+| MCP | Use Case | Example |
+|-----|----------|---------|
+| **GitHub** | Create issues from tasks, link to milestone | `mcp__github__create_issue()` |
+| **Context7** | Estimate complexity based on library docs | `mcp__context7__query_docs()` |
+
+```javascript
+// Create GitHub issues from tasks.json (if team uses GitHub Projects)
+for (const task of tasks) {
+  await mcp__github__create_issue({
+    title: task.title,
+    body: task.description,
+    labels: [task.category],
+    milestone: featureMilestone
+  });
+}
+
+// Fallback: Bash with gh CLI
+// gh issue create --title "T001: Create Entity Lead" --label "domain"
+```
+
+### Phase 5 (Implement) — Build & Deploy
+
+| MCP | Use Case | Example |
+|-----|----------|---------|
+| **Supabase** | Run migrations, create RLS policies | `mcp__supabase__query()` |
+| **GitHub** | Create PR, push branches | `mcp__github__create_pull_request()` |
+| **Context7** | Look up API usage during coding | `mcp__context7__query_docs()` |
+| **Playwright** | Smoke test deployed features, verify UI | `mcp__playwright__browser_navigate()` |
+| **Azure** | Provision resources, check deployment status | Provider-specific |
+| **Docker** | Build images, manage containers | Provider-specific |
+
+```javascript
+// Run migration after implementing data model
+await mcp__supabase__query({
+  query: `ALTER TABLE leads ADD COLUMN status varchar(20) DEFAULT 'new'`
+});
+
+// Create RLS policy for new feature
+await mcp__supabase__query({
+  query: `CREATE POLICY "Users can view own leads"
+          ON leads FOR SELECT
+          USING (auth.uid() = user_id)`
+});
+
+// Lookup API during implementation
+const docs = await mcp__context7__query_docs({
+  libraryId: "/dotnet/efcore",
+  query: "owned entity types configuration"
+});
+
+// Smoke test deployed feature via browser
+await mcp__playwright__browser_navigate({ url: "https://localhost:5001/leads" });
+const snapshot = await mcp__playwright__browser_snapshot();
+// → Verify page renders correctly, check for errors
+
+// Check for console errors after deploy
+const logs = await mcp__playwright__browser_console_messages();
+// → Catch JavaScript errors, failed API calls
+
+// Screenshot for recap.md documentation
+const screenshot = await mcp__playwright__browser_take_screenshot();
+
+// Fallback: Bash for migrations, gh CLI for PRs
+```
+
+---
+
+## MCP vs Native Tools Decision
+
+| Need | MCP Tool | Native Alternative |
+|------|----------|--------------------|
+| Database schema | Supabase/DB MCP | Grep queries + Read types |
+| Repo metadata | GitHub MCP | Bash `gh` CLI |
+| Design tokens | Figma MCP | Read CSS/SCSS variables |
+| Library docs | Context7 | WebSearch + WebFetch |
+| Live page preview | Playwright MCP | WebFetch URL |
+| Page interaction (click, type, navigate) | Playwright MCP | Manual testing |
+| Responsive layout testing | Playwright MCP (`browser_resize`) | Manual testing |
+| Console error checking | Playwright MCP (`browser_console_messages`) | Browser DevTools |
+| Container ops | Docker MCP | Bash `docker` CLI |
+| Cloud resources | Azure MCP | Bash `az` CLI |
+
+**Rule:** MCP tools provide structured data (JSON responses). Native tools require manual parsing. **Always prefer MCP when available** — fall back to native when not.
+
+---
+
+## Common MCP Patterns
+
+### Browser (Playwright): Page Automation & Analysis
+
+```javascript
+// === SETUP ===
+// Playwright MCP: npx @playwright/mcp@latest
+// Config in .claude/settings.json or claude_desktop_config.json:
+// { "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] } } }
+
+// === NAVIGATION & SNAPSHOT ===
+
+// 1. Navigate to a page
+await mcp__playwright__browser_navigate({ url: "https://app.example.com/dashboard" });
+
+// 2. Take accessibility snapshot (preferred — structured, LLM-friendly)
+const snapshot = await mcp__playwright__browser_snapshot();
+// → Returns accessibility tree with element refs for interaction
+
+// 3. Take visual screenshot (requires --caps vision)
+const screenshot = await mcp__playwright__browser_take_screenshot();
+// → Returns PNG image of current page
+
+// === INTERACTION ===
+
+// 4. Click an element (use ref from snapshot)
+await mcp__playwright__browser_click({ element: "Submit button", ref: "s1e15" });
+
+// 5. Type into an input field
+await mcp__playwright__browser_type({ element: "Search input", ref: "s1e8", text: "query" });
+
+// 6. Fill a form field (replaces existing value)
+await mcp__playwright__browser_fill_form({ ref: "s1e8", value: "new value" });
+
+// 7. Select dropdown option
+await mcp__playwright__browser_select_option({ element: "Status", ref: "s1e12", values: ["active"] });
+
+// 8. Press keyboard key
+await mcp__playwright__browser_press_key({ key: "Enter" });
+
+// === TABS & NAVIGATION ===
+
+// 9. List open tabs
+const tabs = await mcp__playwright__browser_tabs();
+
+// 10. Navigate back
+await mcp__playwright__browser_navigate_back();
+
+// 11. Close current tab
+await mcp__playwright__browser_close();
+
+// === ADVANCED ===
+
+// 12. Evaluate JavaScript in page context
+const result = await mcp__playwright__browser_evaluate({
+  expression: "document.querySelectorAll('.error').length"
+});
+
+// 13. Get console messages (debug)
+const logs = await mcp__playwright__browser_console_messages();
+
+// 14. Get network requests
+const requests = await mcp__playwright__browser_network_requests();
+
+// 15. Handle dialog (alert, confirm, prompt)
+await mcp__playwright__browser_handle_dialog({ accept: true });
+
+// 16. Resize viewport
+await mcp__playwright__browser_resize({ width: 375, height: 812 }); // iPhone viewport
+
+// 17. Save page as PDF (requires --caps pdf)
+await mcp__playwright__browser_pdf_save();
+
+// 18. Upload file
+await mcp__playwright__browser_file_upload({ ref: "s1e20", paths: ["/path/to/file.png"] });
+```
+
+**Use cases by phase:**
+
+| Phase | Use Case | Tool |
+|-------|----------|------|
+| UI/UX (1.5) | Screenshot reference pages for design | `browser_navigate` + `browser_take_screenshot` |
+| UI/UX (1.5) | Inspect existing app structure | `browser_navigate` + `browser_snapshot` |
+| UI/UX (1.5) | Test responsive layouts | `browser_resize` + `browser_take_screenshot` |
+| Clarify (3) | Verify existing UI behavior | `browser_navigate` + `browser_snapshot` |
+| Implement (5) | Smoke test deployed features | `browser_navigate` + `browser_click` + `browser_snapshot` |
+| Implement (5) | Verify form flows end-to-end | `browser_fill_form` + `browser_click` + `browser_snapshot` |
+| Implement (5) | Check console errors after deploy | `browser_navigate` + `browser_console_messages` |
+| Implement (5) | Screenshot for recap.md | `browser_take_screenshot` |
+
+---
+
+### Supabase: Full Schema Discovery
+
+```javascript
+// Complete workflow for Phase 2 schema analysis
+const tables = await mcp__supabase__list_tables();
+
+for (const table of tables.filter(t => isRelevant(t))) {
+  const schema = await mcp__supabase__get_table_schema({ table: table.name });
+  const rels = await mcp__supabase__get_relationships({ table: table.name });
+  // → Write findings to schema-analysis.md
+}
+```
+
+### Context7: Library Research
+
+```javascript
+// Workflow for any phase needing library documentation
+// Step 1: Resolve library ID
+const lib = await mcp__context7__resolve_library_id({
+  libraryName: "fluent-ui-blazor",
+  query: "dialog component with form validation"
+});
+
+// Step 2: Query specific documentation
+const docs = await mcp__context7__query_docs({
+  libraryId: lib.id,
+  query: "FluentDialog component usage with EditForm validation"
+});
+```
+
+### GitHub: Code Search Across Repo
+
+```javascript
+// Find patterns in large codebase during Phase 2
+const results = await mcp__github__search_code({
+  query: "supabase.from leads repo:myorg/myrepo",
+});
+// → Find all places that query the leads table
+```
+
+---
+
+## Security Considerations
+
+- **Never pass secrets** in MCP tool parameters (API keys, tokens, passwords)
+- **Supabase MCP** uses project-level auth — queries run with service role by default
+- **GitHub MCP** inherits the configured token's permissions
+- **Always validate MCP responses** before using in contracts or code generation
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/templates/README.md

@@ -314,13 +314,13 @@ morph-spec template customize dotnet-backend-service --stack blazor-azure --forc
 **Output:**
 ```
 Source: framework/templates/code/dotnet/backend/service.cs
-Destination: stacks/blazor-azure/.morph/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/templates/code/dotnet/backend/service.cs
+     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)
@@ -422,7 +422,7 @@ infrastructure/github/
 
 ### Example: Blazor-Azure CI/CD
 
-**CI Build Workflow** (`stacks/blazor-azure/.morph/templates/infrastructure/github/workflows/ci-build.yml.hbs`):
+**CI Build Workflow** (`stacks/blazor-azure/.morph/framework/templates/infrastructure/github/workflows/ci-build.yml.hbs`):
 ```yaml
 name: CI Build
 
@@ -473,12 +473,12 @@ jobs:
 ### Stack-Specific Overrides
 
 Stack-specific workflow templates in:
-- `stacks/blazor-azure/.morph/templates/infrastructure/github/workflows/`
-- `stacks/nextjs-supabase/.morph/templates/infrastructure/github/workflows/`
+- `stacks/blazor-azure/.morph/framework/templates/infrastructure/github/workflows/`
+- `stacks/nextjs-supabase/.morph/framework/templates/infrastructure/github/workflows/`
 
 **Resolution Order:**
-1. Project-local: `.morph/templates/infrastructure/github/workflows/ci-build.yml.hbs`
-2. Stack default: `stacks/{stack}/.morph/templates/infrastructure/github/workflows/ci-build.yml.hbs`
+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`
 
 ---
@@ -488,10 +488,10 @@ Stack-specific workflow templates in:
 **Resolution Order:**
 
 1. **Stack-specific override** (highest priority)
-   - `stacks/{stack}/.morph/templates/code/dotnet/backend/service.cs`
+   - `stacks/{stack}/.morph/framework/templates/code/dotnet/backend/service.cs`
 
 2. **Project-local override** (medium priority)
-   - `.morph/templates/code/dotnet/backend/service.cs`
+   - `.morph/framework/templates/code/dotnet/backend/service.cs`
 
 3. **Framework template** (fallback)
    - `framework/templates/code/dotnet/backend/service.cs`
@@ -500,8 +500,8 @@ Stack-specific workflow templates in:
 
 | Scenario | Override Location | Example |
 |----------|-------------------|---------|
-| Stack-specific tweak | `stacks/{stack}/.morph/templates/` | Blazor uses different DI pattern |
-| Project-wide customization | `.morph/templates/` | Company-specific code style |
+| 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:**
@@ -511,7 +511,7 @@ Stack-specific workflow templates in:
 morph-spec template customize dotnet-backend-service --stack blazor-azure
 
 # Edit the override
-code stacks/blazor-azure/.morph/templates/code/dotnet/backend/service.cs
+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
@@ -574,7 +574,7 @@ 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/templates/code/dotnet/backend/service.cs (if override exists)
+// Or: stacks/blazor-azure/.morph/framework/templates/code/dotnet/backend/service.cs (if override exists)
 ```
 
 ---
@@ -639,7 +639,7 @@ morph-spec template render dotnet-backend-my-template output.cs '{
 
 | Aspect | v1 (Stack-Based) | v2 (Technology-Based) |
 |--------|------------------|----------------------|
-| **Location** | `stacks/{stack}/.morph/templates/` | `framework/templates/{technology}/` |
+| **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) |
@@ -653,13 +653,13 @@ morph-spec template render dotnet-backend-my-template output.cs '{
 **1. Template Paths**
 
 ```diff
-- stacks/blazor-azure/.morph/templates/service.cs
+- stacks/blazor-azure/.morph/framework/templates/service.cs
 + framework/templates/code/dotnet/backend/service.cs
 
-- stacks/blazor-azure/.morph/templates/infra/main.bicep
+- stacks/blazor-azure/.morph/framework/templates/infra/main.bicep
 + framework/templates/infrastructure/azure/main.bicep
 
-- stacks/nextjs-supabase/.morph/templates/dockerfile-web.dockerfile
+- stacks/nextjs-supabase/.morph/framework/templates/dockerfile-web.dockerfile
 + framework/templates/infrastructure/docker/dockerfile-web.dockerfile
 ```