@polymorphism-tech/morph-spec 4.9.0 → 4.10.1

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

@@ -125,13 +125,13 @@ uiLibrary:         shadcn | fluent-ui | mudblazor | null
 monorepo:          true | false
 frontendPath:      src/frontend (if monorepo)
 backendPath:       src/backend (if monorepo)
-architectureStyle: vertical-slice | null   ← novo
+architectureStyle: vertical-slice | null   ← new
 ```
 
-**VSA detection:** `architectureStyle: "vertical-slice"` se qualquer um destes existir:
-- `Abstractions/IHandler.cs` encontrado pelo Glob
-- `Pipelines/ValidationDecorator.cs` encontrado pelo Glob
-- 2+ pastas com sufixo `Feature` em `Features/` (ex: `BookFeature`, `OrderFeature`)
+**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`)
 
 ---
 
@@ -143,9 +143,9 @@ Ask at most 3 questions, only those that apply:
 
 | # | Question | Condition | Purpose |
 |---|----------|-----------|---------|
-| 1 | *"Em uma frase: qual é o objetivo principal do **[ProjectName]**?"* | Always | README.md Overview |
-| 2 | *"Confirmo: frontend em `{frontendPath}`, backend em `{backendPath}`. Correto?"* | Monorepo detected | Validate paths before persisting |
-| 3 | *"Supabase Cloud (managed) ou self-hosted?"* | Supabase detected | MCP URL configuration |
+| 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 | *"Supabase Cloud (managed) or self-hosted?"* | Supabase detected | MCP URL configuration |
 
 Do **not** ask about technology already confirmed by file evidence.
 
@@ -200,7 +200,7 @@ Read `.morph/config/config.json` and merge into `project`:
 }
 ```
 
-**Se `architectureStyle: "vertical-slice"` foi detectado no Step 3**, adicione também:
+**If `architectureStyle: "vertical-slice"` was detected in Step 3**, also add:
 
 ```json
 {
@@ -210,7 +210,7 @@ Read `.morph/config/config.json` and merge into `project`:
 }
 ```
 
-E informe o usuário:
+And inform the user:
 
 ```
 ✓ Detected: Vertical Slice Architecture (IHandler.cs / *Feature folders)
@@ -218,12 +218,12 @@ E informe o usuário:
   → morph-spec will use vsa-architect + contracts-vsa.cs for features
 ```
 
-> Esta key é o que ativa o `vsa-architect` em vez do `domain-architect` durante `/morph-proposal`.
+> This key is what activates `vsa-architect` instead of `domain-architect` during `/morph-proposal`.
 
-**Se o projeto ainda não existe (novo projeto VSA do zero)**, informe também:
+**If the project doesn't exist yet (new VSA project from scratch)**, also inform:
 
 ```
-Para criar um novo projeto VSA:
+To create a new VSA project:
    dotnet new install https://github.com/polymorphism-tech/Morph_Template_VerticalSliceArchitecture
    dotnet new vsa -n MyProject
    cd MyProject && npx morph-spec init
@@ -236,17 +236,43 @@ Para criar um novo projeto VSA:
 For each detected integration with an available MCP:
 
 **Supabase detected:**
-> *"Configure Supabase MCP now? I'll need `SUPABASE_URL` and `SERVICE_ROLE_KEY`."*
-- YES → collect credentials → add to `.claude/settings.local.json` under `mcpServers`
+> *"Configure Supabase MCP? Uses OAuth — no credentials needed."*
+- YES → write remote config to `.claude/settings.local.json`:
+  ```json
+  "supabase": { "type": "http", "url": "https://mcp.supabase.com/mcp" }
+  ```
 - NO → show snippet + `npx morph-spec mcp setup supabase`
 
 **GitHub:**
-> *"Configure GitHub MCP? I'll need a `GITHUB_PERSONAL_ACCESS_TOKEN`."*
-- YES/NO → same pattern
+> *"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 + `npx 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 + `npx morph-spec mcp setup vercel`
 
-Only offer Figma, Docker, Azure if explicitly detected in `.env.example`.
+Only offer Docker, Azure if explicitly detected in `.env.example`.
 
-> **Format rule:** Always write MCP entries with `"command": "cmd"` and `"/c"` as the **first element of `"args"`**:
+> **Format rules for MCP configs:**
+>
+> **Remote MCPs** (Supabase, 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",
@@ -254,11 +280,79 @@ Only offer Figma, Docker, Azure if explicitly detected in `.env.example`.
 >   "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
+npx 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 |
+|-------|-----------------|-------------|
+| Node.js CLI (no UI) | `nodejs-cli` (skips uiux/clarify/sync) | `standard` |
+| .NET + Blazor | `standard` (all phases) | — |
+| Next.js | `standard` (all phases) | — |
+
+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.
@@ -271,7 +365,7 @@ Before printing the summary, check `~/.claude/settings.local.json` for `env.CLAU
 ✓ config.json updated
   Stack: [stack]  |  Architecture: [architecture]
   Integrations:   [list]
-✓ MCPs: [configured list]
+✓ MCPs: [configured list] ([N verified] / [M needs restart] / [K failed])
 
 [If CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1":]
 ✓ Agent Teams: enabled

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

@@ -0,0 +1,362 @@
+---
+name: morph:post-implementation
+description: Orchestrates the complete post-implementation flow: stack detection,
+  automated scans (C#/Next.js), tests, validate-feature, smoke test via Playwright
+  (mandatory if dev server active), code review checklist by stack, checkpoint, and
+  recap generation. Use after completing all tasks.
+argument-hint: "[feature-name]"
+user-invocable: true
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Task, AskUserQuestion,
+  mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot,
+  mcp__playwright__browser_take_screenshot, mcp__playwright__browser_console_messages
+---
+
+# Post-Implementation Review
+
+> Post-implementation orchestrator: runs all checks in logical sequence and blocks on failure.
+> Use after completing all implementation tasks, before creating the PR.
+
+---
+
+## Prerequisites
+
+- All tasks marked as done (`morph-spec task done`)
+- Project build compiling without errors
+
+---
+
+## Step 1 — Detect Stack
+
+```bash
+node .claude/skills/morph-post-implementation/scripts/detect-stack.mjs
+```
+
+Output JSON: `{ stack: "DOTNET" | "NEXTJS" | "FULLSTACK" | "UNKNOWN", frontendPath, backendPath, startCommand }`
+
+Priority order (most reliable first):
+1. `.morph/config/config.json` → `config.project.stack` + `frontendPath`/`backendPath`
+2. `.morph/context/README.md` → section `## Tech Stack`
+3. Fallback: Glob for `*.csproj` and `package.json` with dep `"next"`
+
+Store the result — all following steps depend on the detected `stack`.
+
+---
+
+## Step 2 — Automated Scans
+
+Run automated scans based on detected stack.
+
+### If DOTNET or FULLSTACK:
+
+```bash
+node .claude/skills/morph-code-review/scripts/scan-csharp.mjs --diff
+```
+
+### If NEXTJS or FULLSTACK:
+
+```bash
+node .claude/skills/morph-code-review-nextjs/scripts/scan-nextjs.mjs --diff
+```
+
+**🚫 BLOCK if any CRITICAL finding found.**
+
+Fix all CRITICALs before continuing. To review the full checklist:
+- .NET: `/morph:code-review`
+- Next.js: `/morph:code-review-nextjs`
+
+---
+
+## Step 3 — Test Suite
+
+Run tests based on stack.
+
+### DOTNET:
+
+```bash
+dotnet test --verbosity minimal
+```
+
+### NEXTJS:
+
+```bash
+npm test -- --watchAll=false
+```
+
+### FULLSTACK:
+
+Run both in parallel (use Task tool with two independent subagents).
+
+**🚫 BLOCK if tests fail.**
+
+Do not proceed while tests are failing. Fix failures and re-run before continuing.
+
+---
+
+## Step 4 — Framework Validation
+
+```bash
+npx morph-spec validate-feature $ARGUMENTS
+```
+
+**🚫 BLOCK if it fails.**
+
+Read validation output, fix reported issues, and re-run until it passes.
+
+---
+
+## Step 5 — Smoke Test (Playwright MCP)
+
+### 5a. Detect Dev Server
+
+```bash
+node .claude/skills/morph-post-implementation/scripts/detect-dev-server.mjs "<startCommand>"
+```
+
+Pass the `startCommand` returned by detect-stack in Step 1.
+
+The script:
+1. Scans ports `[3000, 3001, 4200, 5000, 5001, 7000, 8000, 8080]` with `fetch()` timeout 500ms
+2. If it finds an active server → returns `{ found: true, url }`
+3. If not found and `startCommand` provided → tries to start automatically and waits 30s
+4. Returns exit code 0 (server available) or 1 (not available after attempt)
+
+### 5b. If dev server available (exit 0):
+
+**Smoke test is MANDATORY.**
+
+1. Read feature `spec.md` to identify critical happy paths (maximum 3 flows, section Functional Requirements)
+2. Run the smoke test via Playwright MCP:
+
+```javascript
+// Navigate to the feature
+await mcp__playwright__browser_navigate({ url: '<detected-url>' });
+
+// Capture page state
+await mcp__playwright__browser_snapshot();
+
+// Check for critical console errors
+await mcp__playwright__browser_console_messages({ level: 'error' });
+
+// Screenshot for documentation
+await mcp__playwright__browser_take_screenshot({
+  type: 'png',
+  filename: '.morph/features/$ARGUMENTS/5-implement/smoke-screenshots/smoke-<timestamp>.png'
+});
+```
+
+For each critical happy path from the spec:
+- Navigate to the flow
+- Verify key elements are visible (`browser_snapshot`)
+- Confirm absence of critical console errors
+- Capture screenshot of final state
+
+**Mandatory checks:**
+- [ ] Page loads without 404/500 error
+- [ ] Main feature elements visible (per spec)
+- [ ] Console without critical errors (level: error)
+- [ ] Main happy path functional
+
+**🚫 BLOCK if any check fails.** Do not create PR with failing smoke test.
+
+### 5c. If dev server NOT available (exit 1):
+
+**⚠️ WARNING: Dev server not found after attempt to start.**
+
+Request explicit user confirmation before skipping smoke test:
+
+```
+Dev server not detected on expected port. Smoke test via Playwright is mandatory
+to ensure the code works in the browser before creating the PR.
+
+Options:
+1. Start the server manually (`npm run dev` / `dotnet run`) and re-run /post-implementation
+2. Explicitly confirm you want to skip the smoke test and why
+
+Cannot proceed to PR creation without smoke test or explicit confirmation.
+```
+
+**Wait for response before continuing.**
+
+---
+
+## Step 6 — Code Review Checklist (CRITICAL + HIGH)
+
+> Before reviewing, read: `.claude/skills/morph-code-review/references/review-guidelines.md` — apply confidence ≥ 75, ignore pre-existing violations, include file:line in each finding.
+
+Review the most important items by stack. For complete review, use the dedicated skills.
+
+### If FULLSTACK:
+
+Dispatch two subagents in parallel (Task tool):
+
+**Subagent 1 — Backend Review:**
+> .NET focused reviewer. Scope: ONLY changed .cs files (git diff main...HEAD).
+> Run: `node .claude/skills/morph-code-review/scripts/scan-csharp.mjs --diff`
+> Then manually review CRITICAL+HIGH checklist items for .NET.
+> Apply review-guidelines.md: confidence ≥ 75, skip pre-existing.
+> Output: findings with file:line, or "✅ No CRITICAL/HIGH in changed backend."
+
+**Subagent 2 — Frontend Review:**
+> Next.js focused reviewer. Scope: ONLY changed .tsx/.ts files (git diff main...HEAD).
+> Run: `node .claude/skills/morph-code-review-nextjs/scripts/scan-nextjs.mjs --diff`
+> Then manually review CRITICAL+HIGH checklist items for Next.js.
+> Apply review-guidelines.md: confidence ≥ 75, skip pre-existing.
+> Output: findings with file:line, or "✅ No CRITICAL/HIGH in changed frontend."
+
+Wait for both. **🚫 BLOCK if either returns unresolved CRITICAL.**
+
+### If DOTNET:
+
+**CRITICAL and HIGH items — .NET:**
+
+```
+[ ] CancellationToken propagated through the entire async chain
+[ ] No .Result / .Wait() (deadlock risk)
+[ ] Domain has zero refs to Infrastructure or Web
+[ ] No circular dependencies
+[ ] No empty catch blocks
+[ ] Background ops use IDbContextFactory + await using
+[ ] Async methods have Async suffix
+[ ] Interfaces prefixed with I
+[ ] No classes > 300 lines
+[ ] DTOs with descriptive names + correct types
+```
+
+> For full list: `/morph:code-review`
+
+### If NEXTJS:
+
+**CRITICAL and HIGH items — Next.js:**
+
+```
+[ ] node .claude/skills/morph-code-review-nextjs/scripts/scan-nextjs.mjs --diff → 0 CRITICAL
+[ ] File names in kebab-case (user-card.tsx, not UserCard.tsx)
+[ ] 'use client' only in components with hooks/event handlers
+[ ] No useEffect for data fetching → Server Component or useQuery
+[ ] Zod schema defined first, type derived with z.infer<>
+[ ] zodResolver connected to useForm, useMutation for submit
+[ ] Query key factory used (userKeys.lists(), not ['users'])
+[ ] Feature public API via features/{name}/index.ts
+[ ] components/ui/ untouched (shadcn CLI only)
+[ ] No any type annotation
+```
+
+> For full list: `/morph:code-review-nextjs`
+
+**🚫 BLOCK if any CRITICAL item is unresolved.**
+
+---
+
+## Step 7 — Checkpoint + Recap
+
+```bash
+# Save post-review checkpoint
+npx morph-spec checkpoint-save $ARGUMENTS --note "post-implementation review"
+
+# Generate final recap
+npx morph-spec generate recap $ARGUMENTS
+```
+
+---
+
+## Step 8 — Finish Worktree
+
+Implementation is complete. If the feature was developed in a morph worktree, finalize it now.
+
+**Check if a worktree exists:**
+```bash
+git worktree list | grep morph/
+```
+
+**If a `morph/{feature}` worktree exists:**
+
+Invoke the finishing-a-development-branch skill:
+```
+Skill(superpowers:finishing-a-development-branch)
+```
+
+This skill will:
+1. Verify tests pass
+2. Present 4 options:
+   - **Merge locally** → merge into base branch + delete worktree
+   - **Push and create PR** → push branch + create GitHub PR (keeps worktree)
+   - **Keep as-is** → no action (worktree preserved for later)
+   - **Discard** → delete branch + worktree (requires typed confirmation)
+3. Clean up worktree for options 1 and 4
+
+**If NOT in a worktree** (legacy mode): skip this step and proceed to Step 9.
+
+> **Note:** If the `superpowers` plugin is not installed, create the PR manually:
+> `gh pr create --title "feat({feature}): <description>" --body "..."`
+
+---
+
+## Step 9 — Pre-PR Compliance Checklist
+
+Before creating the PR, invoke the compliance checklist:
+
+```
+Skill(morph:checklist)
+```
+
+This skill checks: security, SEO, performance, accessibility, and LGPD compliance.
+**🚫 BLOCK if any CRITICAL item is unresolved.**
+
+---
+
+## Step 10 — PR Suggestion
+
+When all steps pass, suggest the PR:
+
+```bash
+gh pr create \
+  --title "feat($ARGUMENTS): <concise feature description>" \
+  --body "$(cat <<'EOF'
+## Summary
+
+- <main implemented changes>
+- <completed tasks>
+
+## Test Results
+
+- Build: ✅ passed
+- Tests: ✅ X tests passing
+- Smoke Test: ✅ happy path verified via Playwright
+
+## Screenshots
+
+<!-- Paste screenshot paths saved in smoke-screenshots/ -->
+
+## Checklist
+
+- [ ] Automated scans: 0 CRITICAL findings
+- [ ] All tests passing
+- [ ] Smoke test via Playwright: ✅
+- [ ] Code review checklist: CRITICAL + HIGH items verified
+- [ ] validate-feature: ✅ passed
+- [ ] Checkpoint saved
+- [ ] recap.md generated
+EOF
+)"
+```
+
+---
+
+## Block Summary
+
+| Step | Block Condition |
+|------|-----------------|
+| Step 2 | Any CRITICAL finding in automated scans |
+| Step 3 | Any test failing |
+| Step 4 | `validate-feature` failing |
+| Step 5 | Dev server active + smoke test failing |
+| Step 5 | Dev server not detected without explicit user confirmation |
+| Step 6 | Any unresolved CRITICAL item in manual checklist |
+| Step 8 | Tests failing in worktree before merge/PR |
+| Step 9 | Unresolved CRITICAL item in `morph:checklist` |
+
+**All BLOCKs must be resolved before creating the PR.**
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*