@polymorphism-tech/morph-spec 4.22.0 → 5.0.1

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

@@ -1,225 +0,0 @@
----
-name: morph-parallel-dispatch
-description: Plan and execute parallel agent dispatch using P-Threads, F-Threads, and squad templates. Covers thread types, file scope isolation, dependency analysis, and conflict resolution for multi-domain features.
-user-invocable: true
-argument-hint: "[feature-name]"
-allowed-tools: Read, Bash, Glob, Grep
----
-
-# Parallel Dispatch — MORPH-SPEC Thread Management
-
-> Orchestrate concurrent agent execution with strict file scope isolation, dependency-aware wave planning, and automatic conflict resolution.
-
-## Thread Types
-
-| Type | Code | Purpose | Lifecycle |
-|------|------|---------|-----------|
-| Base | B-Thread | Default implementation thread | Bounded by feature phase |
-| Parallel | P-Thread | Concurrent isolated execution | Short (1 task scope) |
-| Fusion | F-Thread | Best-of-N competing implementations | Short (1 prompt scope) |
-| Long-Running | L-Thread | Multi-session persistent work | Days/weeks |
-| Zero-Touch | Z-Thread | Fully autonomous execution | Bounded by trust level |
-
-## When to Use Parallel Execution
-
-| Condition | Decision |
-|-----------|----------|
-| 5+ independent tasks | Use P-Threads |
-| Multi-domain (backend + frontend) | Use P-Threads with squad templates |
-| 15+ files to create | Use P-Threads |
-| Tasks have zero dependency overlap | Use P-Threads |
-| Tasks share file scope | Do NOT parallelize |
-| Sequential data flow required | Do NOT parallelize |
-
-## Thread Lifecycle
-
-```
-pending --> running --> completed
-                    --> failed --> (retry) --> running
-                              --> killed
-```
-
-## Parallelization Planning
-
-### Step 1: Dependency Analysis
-
-```bash
-morph-spec detect-workflow $FEATURE_NAME
-
-# Identifies: parallelizable tasks, sequential chains, waves
-# Output:
-#   Parallelizable tasks: T001, T002, T003 (no dependencies)
-#   Sequential: T004 (depends on T001), T005 (depends on T002)
-#   Execution plan:
-#     Wave 1: [T001, T002, T003] (parallel)
-#     Wave 2: [T004, T005] (parallel, after wave 1)
-#     Wave 3: [T006] (sequential)
-```
-
-### Step 2: File Scope Assignment
-
-Assign exclusive file ownership to each parallel worker. No overlap allowed — if overlap is unavoidable, make it sequential.
-
-```
-Worker A (Backend):    Features/, Services/, Endpoints/, DTOs/
-Worker B (Frontend):   app/, components/, hooks/, styles/
-```
-
-**Example — Next.js + .NET VSA feature:**
-
-```
-P-Thread 1 (VSA Backend):
-  src/Features/UserAuth/
-    CreateUser.cs          (endpoint + handler)
-    GetUser.cs             (endpoint + handler)
-    UserValidator.cs       (FluentValidation)
-    Contracts/UserDto.cs   (shared DTOs)
-
-P-Thread 2 (Next.js Frontend):
-  app/users/
-    page.tsx               (route page)
-    layout.tsx             (layout)
-  components/users/
-    user-form.tsx           (shadcn/ui form)
-    user-table.tsx          (data table)
-  hooks/
-    use-users.ts            (React Query hook)
-```
-
-### Step 3: Choose Squad Template
-
-Pre-defined squad configurations for common feature shapes:
-
-| Template | Agents | Use Case |
-|----------|--------|----------|
-| `full-stack` | Backend lead + Frontend lead + Coordinator | Full-stack features |
-| `backend-only` | Backend specialists (3-4 agents) | API-only work |
-| `frontend-only` | Frontend specialists (2-3 agents) | UI-only work |
-
-```bash
-morph-spec squad-template list
-morph-spec squad-template show full-stack
-morph-spec squad-template use full-stack --feature=$FEATURE_NAME
-```
-
-## Execution Flow
-
-```
-Orchestrator
-    |
-    +-- spawn parallel: Worker A (files: Features/, Services/)
-    +-- spawn parallel: Worker B (files: app/, components/)
-    |
-    |   [Workers execute concurrently -- no interaction]
-    |
-    +-- wait-all (poll or explicit sync)
-    |
-    +-- merge results (check for conflicts)
-    +-- run integration validation
-    +-- report consolidated output
-```
-
-## P-Thread Rules
-
-1. **File scope isolation**: Each P-Thread has exclusive write access to its files
-2. **No cross-thread dependencies**: P-Thread tasks are self-contained
-3. **Shared read access**: All P-Threads can read spec.md, standards, contracts
-4. **Merge on completion**: Coordinator merges results after all P-Threads complete
-5. **Max concurrent**: Default 3, max 5 (configurable in llm-interaction.json)
-
-## Parallel vs Fusion
-
-| Aspect | Parallel (P-Thread) | Fusion (F-Thread) |
-|--------|---------------------|-------------------|
-| Goal | Divide scope | Compete on same scope |
-| Output | Different files | Same files, best one wins |
-| Workers collaborate? | No | No |
-| Merge | Combine all files | Select best implementation |
-| Use case | Large features | Design decisions, quality optimization |
-
-## Conflict Resolution
-
-### File Conflicts (two workers wrote same file)
-
-This should NOT happen if scopes are properly defined. If it does:
-
-```bash
-morph-spec agents review aggregate $FEATURE_NAME \
-  --agents=dotnet-senior,nextjs-expert \
-  --strategy=best-of-n
-```
-
-### Interface Mismatches (A expects contract B did not fulfill)
-
-- Document the mismatch in the coordinator report
-- Fix in post-merge sequential step
-- Update shared contracts/DTOs to reflect actual implementation
-
-## Long-Running Threads (L-Threads)
-
-L-Threads run periodic stop hooks every 30 minutes:
-
-```json
-{
-  "stopHooks": {
-    "enabled": true,
-    "interval": 30,
-    "maxRetries": 5,
-    "hooks": ["validate-and-continue", "validate-checkpoints"]
-  }
-}
-```
-
-### Resume Pattern
-
-```bash
-morph-spec bundle load $FEATURE_NAME
-# Load resume context, continue from checkpoint
-```
-
-## Thread State in state.json
-
-```json
-{
-  "threads": {
-    "thread-abc12345": {
-      "id": "thread-abc12345",
-      "type": "parallel",
-      "agent": "dotnet-senior",
-      "feature": "user-auth",
-      "status": "running",
-      "startedAt": "2026-02-19T00:00:00Z",
-      "events": [
-        { "type": "started", "timestamp": "..." },
-        { "type": "checkpoint_passed", "timestamp": "...", "checkpointNum": 1 }
-      ],
-      "metrics": {
-        "tasksCompleted": 3,
-        "checkpointsPassed": 1,
-        "errors": 0
-      }
-    }
-  }
-}
-```
-
-## Monitoring
-
-```bash
-morph-spec threads list $FEATURE_NAME
-morph-spec threads analytics $FEATURE_NAME
-morph-spec threads wait-all $FEATURE_NAME
-morph-spec threads wait-any $FEATURE_NAME
-```
-
-## Configuration
-
-```json
-{
-  "parallelExecution": {
-    "enabled": true,
-    "maxConcurrent": 3,
-    "defaultStrategy": "best-of-n"
-  }
-}
-```

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

@@ -1,401 +0,0 @@
----
-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`
-
-### Asset Completeness Check (if assets.md exists):
-
-If `.morph/features/{feature}/1-ui/assets.md` exists:
-
-1. **Read assets.md** and list all IMG-NNN entries with their `Output Path` values.
-2. **Check each output path exists:**
-   ```bash
-   test -f {outputPath} && echo "✓ {IMG-ID}" || echo "✗ {IMG-ID} MISSING: {outputPath}"
-   ```
-3. **Check for broken Image references:**
-   ```bash
-   grep -rn 'src="/images/' src/ --include="*.tsx" --include="*.jsx" | while read line; do
-     path=$(echo "$line" | grep -oP 'src="(/images/[^"]+)"' | sed 's/src="//;s/"//');
-     test -f "public$path" || echo "⚠️  Broken ref: $line → public$path not found";
-   done
-   ```
-
-**⚠️  ADVISORY** — missing assets produce warnings, not blocks. Some images may be intentionally deferred or optional.
-
----
-
-## 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
-morph-spec validate-feature $ARGUMENTS
-```
-
-**🚫 BLOCK if it fails.**
-
-Read validation output, fix reported issues, and re-run until it passes.
-
----
-
-### Step 4b — Verify RLS Policies (Neon/PostgreSQL projects)
-
-> **Neon CLI (`neonctl`):** If the project uses Neon/PostgreSQL, verify RLS policies on the database:
->
-> 1. Get DB URL: `neonctl connection-string`
-> 2. Query: `psql <DB_URL> -c "SELECT tablename, policyname, cmd, qual FROM pg_policies WHERE schemaname = 'public'"`
-> 3. For each table modified in this feature, verify:
->    - [ ] RLS is enabled (`ALTER TABLE ... ENABLE ROW LEVEL SECURITY`)
->    - [ ] SELECT policy exists for authenticated users
->    - [ ] INSERT/UPDATE/DELETE policies match feature requirements
-> 4. If any table is missing RLS → **flag as CRITICAL** (blocks PR)
->
-> If Neon database is not accessible, check for RLS policy files in the `migrations/` directory and verify they cover modified tables. If no Neon/PostgreSQL in the stack, skip this step.
-
----
-
-## Step 5 — Smoke Test (Playwright MCP)
-
-> **Docker CLI:** Before smoke testing, verify local services are running: `docker ps --format "table {{.Names}}\t{{.Status}}"` — all expected containers should show "Up".
-
-> **MCP:** Smoke testing via **Playwright MCP** is the primary method. If Playwright MCP is not available, fall back to `curl`/`WebFetch` for endpoint verification (limited — cannot test JS-rendered pages or interactions).
-
-### 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
-morph-spec checkpoint-save $ARGUMENTS --note "post-implementation review"
-
-# Generate final recap
-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*