@polymorphism-tech/morph-spec 4.21.0 → 5.0.1

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

@@ -1,537 +0,0 @@
----
-name: morph-init
-description: >
-  LLM-powered project initialization. Installs morph-spec infrastructure if
-  needed, auto-installs required plugins (superpowers, context7), analyzes any
-  project structure intelligently, generates rich context/README.md and
-  config.json, and configures MCPs. Use once per project after installing
-  @polymorphism-tech/morph-spec. Re-run with /morph-init refresh to update
-  context as the project evolves.
-argument-hint: "[refresh]"
-user-invocable: true
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
----
-
-# morph-init — LLM-Powered Project Initialization
-
-> Run once after `npm install @polymorphism-tech/morph-spec`.
-> Re-run as `/morph-init refresh` when your project evolves.
-
----
-
-## Step 0 — Resolve CLI
-
-Before running any `morph-spec` command, detect how to invoke the CLI:
-
-```bash
-# Try local first (project dependency), then global
-morph-spec --version
-```
-
-- If `morph-spec --version` succeeds → use `morph-spec` as the CLI prefix for all commands.
-- If it fails → try `morph-spec --version` (global install). If that works → use `morph-spec`.
-- If both fail → **STOP** and show:
-  ```
-  morph-spec CLI not found. Install it first:
-    npm install @polymorphism-tech/morph-spec
-  ```
-
-Use the resolved CLI prefix (e.g. `morph-spec`) for ALL bash commands in the following steps.
-
----
-
-## Step 1 — Required Plugins
-
-Check for required Claude Code plugins: **superpowers**, **context7**, and **playwright**.
-
-Read `~/.claude/plugins/installed_plugins.json` and check for:
-- `superpowers@claude-plugins-official`
-- `context7@claude-plugins-official`
-- `playwright@claude-plugins-official`
-
-For each missing plugin, run:
-
-```bash
-claude plugin install superpowers@claude-plugins-official
-claude plugin install context7@claude-plugins-official
-claude plugin install playwright@claude-plugins-official
-```
-
-**If the command succeeds:** `✓ {plugin} installed. Restart Claude Code after /morph-init completes.`
-
-**If the command fails:** Show this and **STOP** — do not continue:
-
-```
-Plugin {plugin} could not be installed automatically.
-Run manually and restart Claude Code:
-  claude plugin install {plugin}
-Then re-run /morph-init.
-```
-
-All three plugins are required. Do not continue if any is missing.
-
----
-
-## Step 2 — Infrastructure
-
-Check if `.morph/` exists in the current directory.
-
-**If MISSING:**
-```bash
-morph-spec setup-infra
-```
-Output confirms: `✓ MORPH-SPEC infrastructure installed.`
-
-**If EXISTS and argument is `refresh`:**
-Re-run setup-infra to update framework files, then continue with context/config refresh:
-```bash
-morph-spec setup-infra
-```
-
-**If EXISTS and no argument:**
-Ask: *"MORPH already initialized. Refresh context and config? (y/n)"*
-If `y` → re-run `morph-spec setup-infra` then continue.
-If `n` → STOP.
-
----
-
-## Step 3 — Analyze Project
-
-Gather evidence to build a stack map. Run these in parallel:
-
-| Tool | Pattern | Signal |
-|------|---------|--------|
-| `Glob` | `**/package.json` | Detect next, neon, @neondatabase/auth, stripe in deps |
-| `Glob` | `**/*.csproj` | .NET projects at any depth |
-| `Glob` | `**/next.config.{js,ts,mjs}` | Next.js in any subdirectory |
-| `Glob` | `**/components.json` | shadcn/ui |
-| `Glob` | `**/docker-compose*.yml` | Container services |
-| `Glob` | `database/migrations/**` | Database migrations |
-| `Grep` | `DATABASE_URL\|NEON_\|neonctl` | Neon database config |
-
-| `Glob` | `**/Abstractions/IHandler.cs` | VSA pattern (KanaiyaKatarmal) |
-| `Glob` | `**/Pipelines/ValidationDecorator.cs` | VSA pipeline |
-| `Glob` | `**/Features/**/*Feature` | VSA feature folder suffix |
-| `Read` | `.env.example` | Env vars reveal integrations |
-| `Read` | `README.md` | Existing project description |
-| `Grep` | `@neondatabase/serverless` | Neon dep in any package.json |
-| `Grep` | `@neondatabase/auth\|auth0\|nextauth` | Auth provider |
-| `Grep` | `stripe\|asaas` | Payment provider |
-
-Read each found `package.json` for dependency names. Build an **evidence map**:
-
-```
-stack:             [nextjs, dotnet, ...]
-integrations:      [neon, docker, neon-auth, ...]
-uiLibrary:         shadcn | null
-monorepo:          true | false
-frontendPath:      src/frontend (if monorepo)
-backendPath:       src/backend (if monorepo)
-architectureStyle: vertical-slice | null   ← new
-```
-
-**VSA detection:** `architectureStyle: "vertical-slice"` if any of these exist:
-- `Abstractions/IHandler.cs` found by Glob
-- `Pipelines/ValidationDecorator.cs` found by Glob
-- 2+ folders with `Feature` suffix in `Features/` (e.g., `BookFeature`, `OrderFeature`)
-
----
-
-## Step 4 — Ask Targeted Questions
-
-**Rule: only ask what cannot be inferred with ≥90% confidence from files.**
-
-Ask at most 3 questions, only those that apply:
-
-| # | Question | Condition | Purpose |
-|---|----------|-----------|---------|
-| 1 | *"In one sentence: what is the main purpose of **[ProjectName]**?"* | Always | README.md Overview |
-| 2 | *"Confirmed: frontend at `{frontendPath}`, backend at `{backendPath}`. Correct?"* | Monorepo detected | Validate paths before persisting |
-| 3 | *"Neon (cloud PostgreSQL) or self-hosted Postgres?"* | Neon detected | Database configuration |
-
-Do **not** ask about technology already confirmed by file evidence.
-
----
-
-## Step 4.5 — Scaffold Design System
-
-### 4.5.0 — Check if DS already exists
-
-```
-Read: .morph/context/design-system.md
-```
-
-**If the file EXISTS with non-TODO content in the Aesthetic Direction section:**
-→ Skip steps 4.5.1–4.5.2. Print: `✓ Design system found — .morph/context/design-system.md`
-
-### 4.5.1 — ALWAYS scan for existing CSS tokens
-
-Search for existing CSS custom properties across the project's frontend directories.
-
-Glob these patterns (exclude `node_modules/`, `.next/`, `dist/`, `build/`):
-```
-wwwroot/**/*.css
-wwwroot/**/*.scss
-styles/**/*.css
-src/styles/**/*.css
-src/**/*.css
-src/**/*.scss
-src/**/*.module.css
-public/**/*.css
-```
-
-For each CSS/SCSS file found, Grep for `:root {` blocks containing `--` custom properties.
-
-Track:
-- `cssTokensFound` (bool)
-- `tokenCount` (int — total number of `--variable` lines found)
-- `sourceFiles` (array of file paths that had tokens)
-
-### 4.5.2 — Decision tree
-
-**Case A: CSS tokens found (existing project)**
-
-1. Create `.morph/context/design-system.md` from scanned tokens:
-   - `## Color Tokens` → `:root { }` block with all found color variables (preserve exact variable names from CSS)
-   - `## Typography` → found font-family values (map to `--font-display` / `--font-body` by variable name heuristic)
-   - `## Spacing Tokens` → found spacing variables
-   - `## Aesthetic Direction` → `#TODO` (requires user judgment — fill in during `/morph-phase-uiux`)
-   - `## Changelog` → `- [today's date] [morph-init] Auto-generated from CSS scan ([N] tokens from [files])`
-
-2. Skip the `AskUserQuestion` for direction/brand color — the project has established colors
-
-3. Print:
-   ```
-   ✓ Design system scaffolded from existing CSS
-     Source: [file list]
-     Tokens: [N] colors, [M] font families, [K] spacing values
-     Note: Aesthetic Direction is TODO — fill in during /morph-phase-uiux
-   ```
-
-4. Continue to Step 5.
-
-**Case B: No CSS tokens found (greenfield project)**
-
-1. Copy the template:
-   ```bash
-   cp .morph/framework/templates/context/design-system.md .morph/context/design-system.md
-   ```
-   *(The template is at `framework/templates/context/design-system.md` in the installed framework)*
-
-2. Ask 3 quick questions using `AskUserQuestion`:
-
-```json
-{
-  "questions": [
-    {
-      "header": "Design System Setup",
-      "question": "Let's set up your project's design system. What is the aesthetic direction for [ProjectName]?",
-      "multiSelect": false,
-      "options": [
-        { "label": "Minimal Refined", "description": "Luxurious and precise — elegant serif + light sans, monochromatic + 1 sharp accent" },
-        { "label": "Editorial", "description": "Magazine-grade, opinionated — strong display font + high contrast, dramatic reveals" },
-        { "label": "Soft Professional", "description": "Warm and trustworthy — rounded sans + warm pastels, gentle micro-interactions" },
-        { "label": "Industrial", "description": "Technical and direct — monospace/condensed + neutral colors, minimal motion" },
-        { "label": "Modern Luxury", "description": "Exclusive and refined — italic display + dark background + gold/copper accent" },
-        { "label": "Skip for now", "description": "Leave as TODO — fill in manually later" }
-      ]
-    }
-  ]
-}
-```
-
-3. **If user chose a direction (not "Skip for now")**, ask a follow-up:
-
-```json
-{
-  "questions": [
-    {
-      "header": "Brand Color",
-      "question": "What is your approximate dominant/primary color? (You can adjust exact values later)",
-      "multiSelect": false,
-      "options": [
-        { "label": "Deep blue/navy", "description": "Professional, trustworthy" },
-        { "label": "Rich green", "description": "Growth, sustainability" },
-        { "label": "Warm orange/red", "description": "Energy, urgency" },
-        { "label": "Cool purple/violet", "description": "Creative, premium" },
-        { "label": "True black/dark", "description": "Minimal, premium, editorial" },
-        { "label": "I'll specify manually", "description": "Leave as TODO" }
-      ]
-    }
-  ]
-}
-```
-
-4. Fill in the design-system.md with user responses:
-
-| User answered | What to update |
-|--------------|----------------|
-| Direction chosen | Replace `[Minimal Refined / Editorial / ...]` with chosen direction. Update Font Pair with the correct fonts: Minimal Refined → Cormorant Garamond + DM Sans; Editorial → Playfair Display + Source Sans 3; Soft Professional → Nunito + Inter; Industrial → JetBrains Mono + IBM Plex Sans; Modern Luxury → Bodoni Moda + Sora |
-| Color chosen | Replace `--color-primary: #TODO` with a reasonable hex for that color family: deep blue → #1e3a5f, rich green → #065f46, warm orange → #c2410c, purple → #6d28d9, black → #0a0a0a. Add note: "Adjust exact values to match your brand" |
-| "Skip for now" | Leave all TODOs in place |
-
-5. Update the Changelog in design-system.md:
-   Add entry: `- [today's date] [morph-init] Initial scaffold from morph-init`
-
-6. Print confirmation:
-   ```
-   ✓ Design system scaffolded — .morph/context/design-system.md
-     Direction: [chosen direction or "TODO — fill in manually"]
-     Edit to refine exact token values before the UI/UX phase.
-   ```
-
-7. Continue to Step 5.
-
----
-
-## Step 5 — Generate `context/README.md`
-
-Write `.morph/context/README.md`:
-
-```markdown
-# [ProjectName] — Project Context
-
-## Overview
-[Answer from question 1]
-
-## Tech Stack
-| Layer      | Technology | Location |
-|------------|-----------|----------|
-[One row per detected layer — frontend, backend, database, UI library, auth, payments]
-
-## Architecture
-[monorepo / single-stack / etc — describe layers and responsibilities]
-
-## Key Integrations
-[Per integration: service → purpose → detected via: evidence file/dep]
-
-## Agent Notes
-[Patterns from eslint/tsconfig/.editorconfig, important paths,
- project-specific conventions for MORPH agents]
-```
-
----
-
-## Step 6 — Update `config.json`
-
-Read `.morph/config/config.json` and merge into `project`:
-
-```json
-{
-  "framework": "global",
-  "frameworkVersion": "[current version]",
-  "project": {
-    "name": "[ProjectName]",
-    "description": "[answer from question 1]",
-    "stack": "[stacks joined with +, e.g. nextjs+dotnet]",
-    "architecture": "[monorepo | single-stack | detected pattern]",
-    "uiLibrary": "[detected or null]",
-    "integrations": ["neon", "docker", "neon-auth"],
-    "frontendPath": "[path if monorepo, else omit]",
-    "backendPath": "[path if monorepo, else omit]"
-  }
-}
-```
-
-**If `architectureStyle: "vertical-slice"` was detected in Step 3**, also add:
-
-```json
-{
-  "architecture": {
-    "style": "vertical-slice"
-  }
-}
-```
-
-And inform the user:
-
-```
-✓ Detected: Vertical Slice Architecture (IHandler.cs / *Feature folders)
-  → config.json: architecture.style = "vertical-slice"
-  → morph-spec will use dotnet-senior + contracts-vsa.cs for features
-```
-
-> This key is what activates `dotnet-senior` (VSA mode) during `/morph-proposal`.
-
-**If the project doesn't exist yet (new VSA project from scratch)**, also inform:
-
-```
-To create a new VSA project:
-   dotnet new install https://github.com/polymorphism-tech/Morph_Template_VerticalSliceArchitecture
-   dotnet new vsa -n MyProject
-   cd MyProject && morph-spec init
-```
-
----
-
-## Step 6.5 — Reinstall Stack-Filtered Assets
-
-Now that config.json has the correct `project.stack` and `project.integrations`,
-re-install stack-aware assets (rules, skills, agents) with the correct stack tags:
-
-```bash
-morph-spec setup-infra --reinstall
-```
-
-This re-runs only the stack-aware installation steps (rules, skills, tier 1-4 agents,
-domain agents) using projectTags derived from the updated config.json.
-Infrastructure steps (directory creation, framework copy, hooks) are skipped.
-
-Output confirms: `✓ setup-infra (reinstall): complete.`
-
----
-
-## Step 7 — Configure MCPs
-
-For each detected integration with an available MCP:
-
-**Neon detected:**
-> *"Neon database detected. Use `neonctl` for branch management and `psql` for direct database operations."*
-> No MCP configuration needed — CLI is the primary tool for Neon interaction.
-
-**GitHub:**
-> *"Configure GitHub MCP? Requires Docker + a `GITHUB_PERSONAL_ACCESS_TOKEN`."*
-- YES → collect token → write Docker config:
-  ```json
-  "github": {
-    "command": "docker",
-    "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
-    "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "<token>" }
-  }
-  ```
-- NO → show snippet + `morph-spec mcp setup github`
-
-**Vercel detected** (vercel.json exists OR stack is nextjs):
-> *"Configure Vercel MCP? Uses OAuth — no credentials needed."*
-- YES → write remote config:
-  ```json
-  "vercel": { "type": "http", "url": "https://mcp.vercel.com" }
-  ```
-- NO → show snippet + `morph-spec mcp setup vercel`
-
-**Asaas detected** (integrations includes "asaas"):
-> *"Configure Asaas MCP? Provides API docs, schemas, and code examples for the Asaas payments API."*
-- YES → write config to `.claude/settings.local.json`:
-  ```json
-  "asaas": { "type": "http", "url": "https://docs.asaas.com/mcp" }
-  ```
-- NO → skip (use WebFetch on https://docs.asaas.com for API docs)
-
-Only offer Docker, Azure if explicitly detected in `.env.example`.
-
-> **Format rules for MCP configs:**
->
-> **Remote MCPs** (Vercel) — no credentials, OAuth-based:
-> ```json
-> "mcp-name": { "type": "http", "url": "https://mcp.example.com" }
-> ```
->
-> **Stdio MCPs** (Context7, Playwright) — local process with `cmd /c` on Windows:
-> ```json
-> "mcp-name": {
->   "command": "cmd",
->   "args": ["/c", "npx", "-y", "@package/mcp-server"],
->   "env": { "KEY": "VALUE" }
-> }
-> ```
->
-> **Docker MCPs** (GitHub) — Docker container:
-> ```json
-> "mcp-name": {
->   "command": "docker",
->   "args": ["run", "-i", "--rm", "-e", "TOKEN_VAR", "ghcr.io/org/image"],
->   "env": { "TOKEN_VAR": "<value>" }
-> }
-> ```
->
-> **Never** use `"command": "cmd /c"` (space-separated string) — that is invalid and will fail.
-> **Never** use `"command": "npx"` directly — it also fails on Windows without `cmd`.
-
----
-
-## Step 7.5 — Validate MCP Connections
-
-For each MCP configured in Step 7, run a health check to verify it actually works.
-
-**Read the registry:** `framework/skills/level-0-meta/mcp-registry.json` → for each configured MCP, get its `healthCheck` object.
-
-**For each configured MCP:**
-
-1. **Find available tool:** Search your available tools for one matching `healthCheck.toolPattern` (substring match — e.g., tool name contains "context7")
-2. **If tool found → execute the test call:** Follow `healthCheck.testCall` using `healthCheck.testParams`
-3. **Evaluate result:**
-
-| Result | Action |
-|--------|--------|
-| **Success** (matches `healthCheck.successIndicator`) | Print `✓ {MCP} — connection verified` |
-| **Tool not found** (no tool matching `toolPattern`) | Print `○ {MCP} — needs restart to activate` (MCP configured but tools not yet loaded) |
-| **Error** (tool found but call fails) | → **AskUserQuestion** (see below) |
-
-**On error — ask user with 3 options:**
-
-Use `AskUserQuestion` with header `"{MCP} failed"` and these options:
-- **Reconfigure credentials** — Loop back to Step 7 for this specific MCP. Maximum 2 retries per MCP. After 2 failures, force option 2.
-- **Continue without {MCP}** — Show the `fallback` field from the registry (e.g., "WebSearch + WebFetch for library documentation") and proceed.
-- **Stop init** — Abort initialization. User must fix MCP configuration manually and re-run `/morph-init`.
-
-**Retry tracking:** Keep a counter per MCP. On the 2nd failure for the same MCP, skip the "Reconfigure" option and only offer "Continue without" or "Stop".
-
----
-
-## Step 7.7 — Run Doctor
-
-After all configuration is complete, run the health check to verify everything is properly installed:
-
-```bash
-morph-spec doctor
-```
-
-This validates: config.json integrity, agents.json presence, hooks installation, skills distribution, required command files, and state.json schema version. Fix any reported issues before proceeding.
-
----
-
-## Step 7.8 — Workflow Selection
-
-If the project stack suggests a non-standard workflow, ask the user:
-
-| Stack | Default Workflow | Alternative |
-|-------|-----------------|-------------|
-| Simple feature | `fast-track` (proposal → tasks → implement) | `standard` |
-| Medium feature | `standard` (proposal → design → plan → tasks → implement) | `full` |
-| Complex feature | `full` (all phases including uiux + sync) | — |
-
-For Node.js CLI projects, update config:
-```json
-{ "workflow": "nodejs-cli" }
-```
-
----
-
-## Step 8 — Final Output
-
-Before printing the summary, check `~/.claude/settings.local.json` for `env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`. If set to `"1"`, mark Agent Teams as enabled; otherwise show the warning.
-
-**Important:** Report the `morph-spec doctor` output verbatim. Do NOT fabricate or reinterpret warnings about missing agents — the doctor check is authoritative. If doctor reports no issues, do not add your own warnings.
-
-```
-✓ Plugins:       superpowers ✓   context7 ✓   playwright ✓
-✓ Infrastructure: .morph/ structure, hooks, agents, rules, skills
-✓ Agents:        [N] total ([T1] orchestrators, [T2] domain leaders, [S] specialists)
-✓ context/README.md generated
-✓ config.json updated
-  Stack: [stack]  |  Architecture: [architecture]
-  Integrations:   [list]
-✓ MCPs: [configured list] ([N verified] / [M needs restart] / [K failed])
-
-[If CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1":]
-✓ Agent Teams: enabled
-
-[If CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is NOT set:]
-⚠ Agent Teams not enabled. Multi-agent workflows require:
-  ~/.claude/settings.local.json → {"env": {"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"}}
-
-[If any plugin was newly installed:]
-○ Restart Claude Code to activate newly installed plugins.
-
-Next: /morph-proposal [feature-name]
-```