@polymorphism-tech/morph-spec 4.9.0 → 4.10.1

package/framework/rules/morph-workflow.md

@@ -1,86 +1,143 @@
-# MORPH-SPEC Workflow Rules
-
-> Always-active rules for all MORPH-SPEC managed projects.
-
----
-
-## Spec-First Mandate
-
-**NEVER skip to code without a specification.** Every feature must progress through phases:
-
-1. **Proposal** — User story + acceptance criteria (`0-proposal/proposal.md`)
-2. **Design** — Technical spec + C# contracts + decisions (`1-design/`)
-3. **Tasks** — Atomic task list (`3-tasks/tasks.md`)
-4. **Implement** — Code + recap (`4-implement/recap.md`)
-
-UI-heavy features also include **UI/UX** phase (`2-ui/`) between Design and Tasks.
-
----
-
-## Phase Commands
-
-| Command | Purpose |
-|---------|---------|
-| `/morph-proposal {feature}` | Full spec pipeline (phases 1–4, pauses for approval) |
-| `/morph-apply {feature}` | Implement feature (phase 5) |
-| `/morph-status` | Feature dashboard |
-
----
-
-## Output Paths
-
-All outputs go in `.morph/features/{feature}/`:
-
-| Phase | Path |
-|-------|------|
-| Proposal | `0-proposal/proposal.md` |
-| Spec | `1-design/spec.md` |
-| Contracts | `1-design/contracts.cs` |
-| Decisions | `1-design/decisions.md` |
-| UI Design | `2-ui/design-system.md`, `mockups.md`, `components.md`, `flows.md` |
-| Tasks | `3-tasks/tasks.md` |
-| Recap | `4-implement/recap.md` |
-
----
-
-## Checkpoints
-
-Run a checkpoint every 3 completed tasks:
-- Validate architecture compliance
-- Check package versions
-- Scan for security issues
-- Verify design system adherence (UI features)
-
----
-
-## Approval Gates
-
-**Design Gate:** Before moving from Design → Tasks, spec must be approved.
-**Implementation Gate:** Before starting implementation, task list must be approved.
-
-Check approval status: `morph-spec approval-status {feature}`
-
----
-
-## Protected Files
-
-**NEVER directly edit:**
-- `.morph/state.json` — Managed by CLI only
-- `.morph/framework/**` — Read-only framework content
-
----
-
-## Test File Policy
-
-When a test fails, always follow this order:
-
-1. **Analyze first** — determine if the IMPLEMENTATION is wrong or the TEST SPEC is wrong
-2. **Fix implementation first** — the test is the spec; trust it by default
-3. **Only modify a test file if the test expectation itself is incorrect** — wrong expected value, wrong behavior modeled
-4. **Before modifying any test file, explain WHY the test spec is wrong** — what the correct behavior is and why the test doesn't model it
-
-Do not modify test files to make a failing test pass when the implementation is the actual problem.
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+---
+stacks:
+  - "*"
+---
+
+# MORPH-SPEC Workflow Rules
+
+> Always-active rules for all MORPH-SPEC managed projects.
+
+---
+
+## Spec-First Mandate
+
+**NEVER skip to code without a specification.** Every feature must progress through phases:
+
+1. **Proposal** — User story + acceptance criteria (`0-proposal/proposal.md`)
+2. **Design** — Technical spec + C# contracts + decisions (`1-design/`)
+3. **Plan** — Detailed implementation plan (`3-plan/plan.md`)
+4. **Tasks** — Atomic task list (`4-tasks/tasks.md`)
+5. **Implement** — Code + recap (`5-implement/recap.md`)
+
+UI-heavy features also include **UI/UX** phase (`2-ui/`) between Design and Tasks.
+
+---
+
+## Phase Sequence
+
+```
+proposal → setup → [uiux] → design → clarify → plan → tasks → implement → [sync]
+```
+
+Use `morph-spec status {feature}` to see current phase and pending approval gates.
+
+---
+
+## Phase Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/morph-proposal {feature}` | Full spec pipeline (phases 1-4, pauses for approval) |
+| `/morph-apply {feature}` | Implement feature (phase 5) |
+| `/morph-status` | Feature dashboard |
+
+---
+
+## State & Outputs
+
+| Path | Notes |
+|------|-------|
+| `.morph/state.json` | **READ-ONLY** — use `morph-spec` CLI to update |
+| `.morph/features/{feature}/{phase}/` | Feature outputs organized by phase |
+| `.morph/framework/` | **READ-ONLY** — framework files managed by morph-spec |
+| `.morph/config/config.json` | Project configuration (editable) |
+
+### mark-output types
+
+Use `morph-spec state mark-output <feature> <type>` with one of these exact type names:
+
+| Type | Phase | kebab alias |
+|------|-------|-------------|
+| `proposal` | proposal | — |
+| `schemaAnalysis` | design | `schema-analysis` |
+| `spec` | design | — |
+| `contracts` | design | — |
+| `contractsVsa` | design | `contracts-vsa` |
+| `decisions` | design | — |
+| `clarifications` | clarify | — |
+| `plan` | plan | — |
+| `tasks` | tasks | — |
+| `uiDesignSystem` | uiux | `ui-design-system` |
+| `uiMockups` | uiux | `ui-mockups` |
+| `uiComponents` | uiux | `ui-components` |
+| `uiFlows` | uiux | `ui-flows` |
+| `recap` | implement | — |
+
+---
+
+## Output Paths
+
+All outputs go in `.morph/features/{feature}/`:
+
+| Phase | Path |
+|-------|------|
+| Proposal | `0-proposal/proposal.md` |
+| Spec | `1-design/spec.md` |
+| Contracts | `1-design/contracts.cs` |
+| Decisions | `1-design/decisions.md` |
+| UI Design | `2-ui/design-system.md`, `mockups.md`, `components.md`, `flows.md` |
+| Plan | `3-plan/plan.md` |
+| Tasks | `4-tasks/tasks.md` |
+| Recap | `5-implement/recap.md` |
+
+---
+
+## Checkpoints
+
+Run a checkpoint every 3 completed tasks:
+- Validate architecture compliance
+- Check package versions
+- Scan for security issues
+- Verify design system adherence (UI features)
+
+---
+
+## Approval Gates
+
+**Design Gate:** Before moving from Design → Plan, spec must be approved.
+**Plan Gate:** Before moving from Plan → Tasks, plan must be approved.
+**Implementation Gate:** Before starting implementation, task list must be approved.
+
+Check approval status: `morph-spec approval-status {feature}`
+
+---
+
+## Protected Files
+
+**NEVER directly edit:**
+- `.morph/state.json` — Managed by CLI only
+- `.morph/framework/**` — Read-only framework content
+
+---
+
+## Test File Policy
+
+When a test fails, always follow this order:
+
+1. **Analyze first** — determine if the IMPLEMENTATION is wrong or the TEST SPEC is wrong
+2. **Fix implementation first** — the test is the spec; trust it by default
+3. **Only modify a test file if the test expectation itself is incorrect** — wrong expected value, wrong behavior modeled
+4. **Before modifying any test file, explain WHY the test spec is wrong** — what the correct behavior is and why the test doesn't model it
+
+Do not modify test files to make a failing test pass when the implementation is the actual problem.
+
+---
+
+## Context Window Tip
+
+When using 3+ MCPs, add `"experimental": { "mcpCliMode": true }` to `.claude/settings.json`.
+MCP tools load on-demand instead of all at startup — keeps context clean for actual work.
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/rules/nextjs-standards.md

@@ -2,6 +2,8 @@
 paths:
   - "**/*.tsx"
   - "**/*.ts"
+stacks:
+  - nextjs
 ---
 
 # Next.js Standards

package/framework/rules/testing-standards.md

@@ -4,6 +4,9 @@ paths:
   - "**/*.test.*"
   - "**/*.spec.*"
   - "**/*Tests.cs"
+stacks:
+  - dotnet
+  - blazor
 ---
 
 # Testing Standards

package/framework/skills/level-0-meta/mcp-registry.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.0.0",
+  "version": "4.0.0",
   "description": "Centralized MCP registry with phase relevance and install configuration for morph-spec workflows",
   "mcps": {
     "context7": {
@@ -8,8 +8,16 @@
       "detection": "enabledPlugins includes context7 or mcpServers includes context7",
       "fallback": "WebSearch + WebFetch for library documentation",
       "usage": "Library documentation lookups, API reference, implementation patterns",
+      "healthCheck": {
+        "toolPattern": "context7",
+        "testCall": "Call resolve-library-id with libraryName 'react' and query 'react hooks'",
+        "testParams": { "libraryName": "react", "query": "react hooks" },
+        "successIndicator": "Returns a library ID (e.g., /facebook/react)",
+        "failureHint": "Context7 MCP not responding. Check that @upstash/context7-mcp is installed and the MCP server is running. Try restarting Claude Code."
+      },
       "install": {
         "autoInstall": true,
+        "transport": "stdio",
         "config": {
           "command": "cmd",
           "args": ["/c", "npx", "-y", "@upstash/context7-mcp@latest"]
@@ -27,8 +35,16 @@
       "detection": "mcpServers includes playwright",
       "fallback": "WebFetch for read-only page content, manual testing",
       "usage": "UI preview, smoke testing, page inspection, responsive testing, screenshot capture",
+      "healthCheck": {
+        "toolPattern": "playwright",
+        "testCall": "Call browser_navigate with url 'about:blank'",
+        "testParams": { "url": "about:blank" },
+        "successIndicator": "Page navigates successfully (no error thrown)",
+        "failureHint": "Playwright MCP not responding. Ensure @playwright/mcp is installed and browser binaries are available. Run 'npx playwright install' if needed."
+      },
       "install": {
         "autoInstall": true,
+        "transport": "stdio",
         "config": {
           "command": "cmd",
           "args": ["/c", "npx", "-y", "@playwright/mcp@latest"]
@@ -46,34 +62,25 @@
       "detection": "mcpServers includes supabase",
       "fallback": "Grep query files + Read type definitions for schema inference",
       "usage": "Schema analysis, migrations, RLS policies, data operations",
+      "healthCheck": {
+        "toolPattern": "supabase",
+        "testCall": "Call list_tables with no parameters",
+        "testParams": {},
+        "successIndicator": "Returns a list of tables (even if empty)",
+        "failureHint": "Supabase MCP not responding. If using remote mode, re-authenticate via /mcp in Claude Code. If using local mode, verify SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY in .claude/settings.local.json."
+      },
       "install": {
         "autoInstall": false,
+        "transport": "http",
         "config": {
-          "command": "cmd",
-          "args": ["/c", "npx", "-y", "@supabase/mcp-server-supabase"],
-          "env": {
-            "SUPABASE_URL": "",
-            "SUPABASE_SERVICE_ROLE_KEY": ""
-          }
+          "type": "http",
+          "url": "https://mcp.supabase.com/mcp"
         },
-        "credentials": [
-          {
-            "name": "Supabase Project URL",
-            "envVar": "SUPABASE_URL",
-            "secret": false,
-            "helpUrl": "https://supabase.com/dashboard/project/_/settings/api"
-          },
-          {
-            "name": "Service Role Key",
-            "envVar": "SUPABASE_SERVICE_ROLE_KEY",
-            "secret": true,
-            "helpUrl": "https://supabase.com/dashboard/project/_/settings/api"
-          }
-        ],
+        "credentials": [],
         "prerequisites": [],
         "stackRelevance": ["nextjs-supabase", "supabase", "nextjs"],
-        "warnings": ["NEVER connect to PRODUCTION databases. Use local/dev environment only."],
-        "setupGuide": null
+        "warnings": ["Uses OAuth — you will be prompted to authenticate via browser when first connecting.", "NEVER connect to PRODUCTION databases. Use local/dev environment only."],
+        "setupGuide": "Run: claude mcp add --transport http supabase https://mcp.supabase.com/mcp"
       }
     },
     "github": {
@@ -82,11 +89,19 @@
       "detection": "mcpServers includes github",
       "fallback": "Bash `gh` CLI commands",
       "usage": "Repo metadata, code search, issue creation, PR management",
+      "healthCheck": {
+        "toolPattern": "github",
+        "testCall": "Call any read-only GitHub tool (e.g., search_repositories or get_repo) to verify connectivity",
+        "testParams": {},
+        "successIndicator": "Returns repository data or search results without auth errors",
+        "failureHint": "GitHub MCP not responding. If using Docker, ensure Docker Desktop is running. Verify GITHUB_PERSONAL_ACCESS_TOKEN env var is set. Ensure the token has not expired and has the required scopes (repo, read:org)."
+      },
       "install": {
         "autoInstall": false,
+        "transport": "stdio",
         "config": {
-          "command": "cmd",
-          "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-github"],
+          "command": "docker",
+          "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
           "env": {
             "GITHUB_PERSONAL_ACCESS_TOKEN": ""
           }
@@ -99,39 +114,43 @@
             "helpUrl": "https://github.com/settings/tokens"
           }
         ],
-        "prerequisites": [],
+        "prerequisites": [
+          {
+            "name": "Docker",
+            "checkCommand": "docker --version",
+            "installUrl": "https://docs.docker.com/get-docker/"
+          }
+        ],
         "stackRelevance": ["*"],
         "warnings": [],
-        "setupGuide": null
+        "setupGuide": "Official GitHub MCP Server (github/github-mcp-server). Requires Docker."
       }
     },
-    "figma": {
-      "phases": ["uiux"],
-      "tools": ["get_file"],
-      "detection": "mcpServers includes figma",
-      "fallback": "Read CSS/SCSS files for existing design tokens",
-      "usage": "Design token extraction, component specs, color/typography from Figma files",
+    "vercel": {
+      "phases": ["implement"],
+      "tools": ["search_docs", "list_projects", "get_deployments", "get_deployment_logs", "manage_env_vars"],
+      "detection": "mcpServers includes vercel",
+      "fallback": "Bash `vercel` CLI commands",
+      "usage": "Deployment monitoring, project management, environment variables, log analysis",
+      "healthCheck": {
+        "toolPattern": "vercel",
+        "testCall": "Call search_docs with a query to verify connectivity",
+        "testParams": { "query": "deployments" },
+        "successIndicator": "Returns documentation search results without auth errors",
+        "failureHint": "Vercel MCP not responding. Re-authenticate via /mcp in Claude Code. Ensure you have authorized the Vercel OAuth connection."
+      },
       "install": {
         "autoInstall": false,
+        "transport": "http",
         "config": {
-          "command": "cmd",
-          "args": ["/c", "npx", "-y", "@anthropic/mcp-server-figma"],
-          "env": {
-            "FIGMA_ACCESS_TOKEN": ""
-          }
+          "type": "http",
+          "url": "https://mcp.vercel.com"
         },
-        "credentials": [
-          {
-            "name": "Figma Access Token",
-            "envVar": "FIGMA_ACCESS_TOKEN",
-            "secret": true,
-            "helpUrl": "https://www.figma.com/developers/api#access-tokens"
-          }
-        ],
+        "credentials": [],
         "prerequisites": [],
-        "stackRelevance": ["blazor", "nextjs", "react", "vue"],
-        "warnings": [],
-        "setupGuide": null
+        "stackRelevance": ["nextjs", "nextjs-supabase", "vercel"],
+        "warnings": ["Uses OAuth — you will be prompted to authenticate via browser when first connecting."],
+        "setupGuide": "Run: claude mcp add --transport http vercel https://mcp.vercel.com"
       }
     },
     "docker": {
@@ -140,8 +159,16 @@
       "detection": "mcpServers includes docker",
       "fallback": "Bash `docker` CLI commands",
       "usage": "Container management, build and run containers",
+      "healthCheck": {
+        "toolPattern": "docker",
+        "testCall": "Call any read-only Docker tool to verify Docker daemon connectivity",
+        "testParams": {},
+        "successIndicator": "Tool responds without connection errors (Docker daemon is reachable)",
+        "failureHint": "Docker MCP not responding. Ensure Docker Desktop is running and the Docker daemon is accessible. Run 'docker info' to verify."
+      },
       "install": {
         "autoInstall": false,
+        "transport": "stdio",
         "config": {
           "command": "cmd",
           "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-docker"]
@@ -165,8 +192,16 @@
       "detection": "mcpServers includes azure",
       "fallback": "Bash `az` CLI commands",
       "usage": "Cloud resource management, deployment",
+      "healthCheck": {
+        "toolPattern": "azure",
+        "testCall": "Call any read-only Azure tool to verify credentials and connectivity",
+        "testParams": {},
+        "successIndicator": "Tool responds without authentication or subscription errors",
+        "failureHint": "Azure MCP not responding. Verify AZURE_SUBSCRIPTION_ID in .claude/settings.local.json and ensure 'az login' has been run. Check that Azure CLI is installed with 'az --version'."
+      },
       "install": {
         "autoInstall": false,
+        "transport": "stdio",
         "config": {
           "command": "cmd",
           "args": ["/c", "npx", "-y", "@azure/mcp-server"],
@@ -198,10 +233,10 @@
   "phaseMatrix": {
     "proposal": ["context7"],
     "setup": ["github"],
-    "uiux": ["playwright", "figma", "context7"],
+    "uiux": ["playwright", "context7"],
     "design": ["supabase", "context7", "github"],
     "clarify": ["context7", "github"],
     "tasks": ["context7", "github"],
-    "implement": ["supabase", "context7", "playwright", "github", "docker", "azure"]
+    "implement": ["supabase", "context7", "playwright", "github", "vercel", "docker", "azure"]
   }
 }

package/framework/skills/level-0-meta/morph-brainstorming/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: morph:brainstorming
+description: Morph-spec-aware brainstorming that loads project context, explores multiple design approaches, asks clarifying questions, and produces proposal.md or decisions.md. Use before designing a feature, when facing architectural decisions with multiple valid approaches, or when a feature needs requirements exploration before committing to a direction.
+user-invocable: true
+argument-hint: "[feature-name or topic]"
+allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
+---
+
+# Brainstorming — MORPH-SPEC Integrated
+
+> Explore context, ask questions, generate multiple approaches, and produce a design document before committing to implementation.
+>
+> **Example:** `references/proposal-example.md` — filled-in proposal.md showing expected quality.
+
+## When to Use
+
+- **Phase 0 (Proposal):** Explore the feature request before writing `proposal.md`
+- **Phase 2 (Design):** Explore architectural alternatives before writing `spec.md`
+- **Any phase:** When facing a decision with multiple valid approaches
+
+## Recommended Tools
+
+| Action | Tool | Alternative |
+|--------|------|-------------|
+| Load feature state | **Bash** `npx morph-spec state get $ARGUMENTS` | — |
+| Read project config | **Read** `.morph/config/config.json` | — |
+| Scan existing code | **Glob** / **Grep** | — |
+| Research libraries | **Context7 MCP** `query_docs()` | **WebSearch** |
+| Ask clarifying questions | **AskUserQuestion** (never plain text) | — |
+| Render proposal template | **Bash** `npx morph-spec template render docs/proposal ...` | — |
+
+---
+
+## Workflow
+
+### Step 1: Explore Context
+
+Gather information before generating ideas. This step is what makes morph-aware brainstorming different from generic brainstorming — it grounds your thinking in the actual project state and constraints.
+
+1. **Read state** — `npx morph-spec state get $ARGUMENTS` → current phase, active agents, existing outputs, task history
+2. **Read config** — `.morph/config/config.json` → stack, architecture style (VSA vs standard), project name, integrations
+3. **Check architecture** — `cat .morph/config/config.json | grep -A3 architecture` → determines which agents and patterns apply
+4. **Read existing outputs** — proposal.md, spec.md, decisions.md (if they exist from prior work)
+5. **Check active agents** — `npx morph-spec dispatch-agents $ARGUMENTS design --table` → which specialists are available
+6. **Scan codebase** — use Glob/Grep to understand existing patterns, domain models, and service boundaries relevant to the feature
+7. **Check MCP tools** — if Context7, GitHub, or other MCPs are available, use them for research
+
+### Step 2: Ask Clarifying Questions
+
+Use `AskUserQuestion` to collect responses — **NEVER list questions as plain text**.
+
+- Maximum 4 questions per call. If you need 5+, make sequential calls (Q1-Q4, then Q5).
+- Each question needs 2-4 representative options (the user can type a free response via "Other").
+- **Wait for the tool response before proceeding to Step 3.**
+
+Starter questions to adapt to the feature context:
+
+| Header (<=12 chars) | Question | Suggested Options |
+|--------------------|----------|------------------|
+| `Scope` | What's the minimum viable version of this feature? | Basic MVP / Full version / Open-ended |
+| `Constraints` | Any performance, budget, or timeline constraints? | No constraints / Performance-critical / Budget-limited |
+| `Integration` | Does this need to integrate with existing features/systems? | Yes, integrates with X / Isolated feature / TBD |
+| `Users` | Who are the primary users? | End-users / Admins / Internal system |
+| `Success` | How will we know this feature works correctly? | Defined metrics / Acceptance tests / User feedback |
+
+> Adapt the options to the actual feature context — these are starting points, not a fixed template.
+
+### Step 3: Generate 2-3 Approaches
+
+For each approach, document:
+
+```markdown
+## Approach A: {Name}
+
+**Description:** {1-2 sentences}
+
+**Pros:**
+- Pro 1
+- Pro 2
+
+**Cons:**
+- Con 1
+- Con 2
+
+**Complexity:** Low / Medium / High
+**Estimated Tasks:** ~N
+**Key Dependencies:** {list}
+```
+
+### Step 4: Recommend and Document
+
+1. **Recommend** the best approach with clear reasoning
+2. **Write output** to the appropriate location based on the current phase:
+
+   **Phase 0 (Proposal):**
+   ```bash
+   npx morph-spec template render docs/proposal ".morph/features/$ARGUMENTS/0-proposal/proposal.md" '{"FEATURE_NAME":"...", "DATE":"..."}'
+   ```
+   Then edit the rendered file to add the brainstorming results.
+
+   **Phase 2 (Design):**
+   Write the decision as an ADR (Architecture Decision Record) in `.morph/features/$ARGUMENTS/1-design/decisions.md`.
+
+3. **Update state** (mandatory — do not skip):
+   ```bash
+   npx morph-spec state mark-output $ARGUMENTS proposal    # Phase 0
+   npx morph-spec state mark-output $ARGUMENTS decisions    # Phase 2
+   ```
+   Then verify the output was recorded:
+   ```bash
+   npx morph-spec state get $ARGUMENTS
+   ```
+
+---
+
+## Integration with Superpowers
+
+> Available when the `superpowers` plugin is installed.
+
+This skill replaces `superpowers:brainstorming` within morph-spec workflows. It adds:
+- Automatic context loading from `.morph/` state and config
+- Template rendering for outputs (proposal.md, decisions.md)
+- State tracking via `morph-spec state mark-output`
+- MCP integration for research (Context7, GitHub)
+
+For brainstorming **outside** morph-spec workflows, the original `superpowers:brainstorming` skill remains available.
+
+---
+
+## Anti-patterns
+
+- Skipping brainstorming for features with multiple valid approaches — exploring alternatives prevents tunnel vision
+- Committing to an approach without documenting alternatives — future decisions need context on what was considered
+- Brainstorming without loading project context first — leads to approaches that don't fit the existing architecture
+- Writing code before completing the brainstorming output — premature implementation before agreement
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*