@polymorphism-tech/morph-spec 4.22.0 → 5.0.1

package/framework/skills/level-1-workflows/morph-phase-design/SKILL.md

@@ -1,453 +0,0 @@
----
-name: morph-phase-design
-description: MORPH-SPEC Phase 2 (Design). Schema-first interactive design: reads EF models/Neon PostgreSQL/DB, validates findings with user, then generates VSA Blueprint based on config.architecture.style, producing spec.md, contracts.cs, schema-analysis.md, and decisions.md through a unified quality + clarification loop (score 0-100). Use after proposal phase to create technical specifications grounded in the real database schema.
-argument-hint: "[feature-name]"
-user-invocable: false
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
-cliVersion: "4.22.0"
----
-
-# MORPH Design — Phase 2
-
-> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
-
-Schema-first interactive design: read the real schema, validate with user, generate blueprint, produce artifacts through a quality loop.
-
-## Prerequisites
-
-- [ ] Proposal approved by the user
-- [ ] Phase 2 (UI/UX) completed OR skipped
-
-## Recommended Tools
-
-> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` for full guide.
-> **Ref:** `references/spec-example.md` — filled-in spec.md showing expected output quality.
-> **Ref:** `references/spec-authoring-guide.md` — section structure for spec.md.
-
-| Action | Tool | Alternative |
-|--------|------|-------------|
-| Read proposal + UI specs | **Read** output files | — |
-| **Detect architecture** | **Read** `.morph/config/config.json` → check `architecture.style` | **Bash** `grep` |
-| **Schema: Neon PostgreSQL** | **Bash** `neonctl connection-string` → `pg_dump $(neonctl connection-string)` / `psql <DB_URL>` | **Grep** `.from(` in code |
-| **Schema: EF Core** | **Glob** `**/Entities/**/*.cs` + **Glob** `**/*Context.cs` → **Read** | **Grep** `DbSet<` |
-| **Schema: Next.js/TS** | **Glob** `src/**/types/**/*.ts` + **Grep** `interface\|type.*=` | — |
-| Schema: RLS policies | **Bash** `psql <DB_URL> -c "SELECT ... FROM pg_policies"` | **Read** policy files |
-| Dispatch dotnet-senior | **Agent** `subagent_type="morph-dotnet-senior"` — agent .md file provides the prompt | — |
-| Dispatch tech leads | **Agent** for each active agent from dispatch config | — |
-| Research library | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
-| Render contracts VSA | **Bash** `morph-spec template render dotnet-contracts-vsa ...` | — |
-| Render spec.md | **Bash** `morph-spec template render docs/spec ...` | — |
-| Render decisions.md | **Bash** `morph-spec template render docs/decisions ...` | — |
-| Update state | **Bash** `morph-spec state mark-output $ARGUMENTS <type>` | — |
-
-**Anti-patterns:**
-- Do not generate contracts before reading the real schema — guessed field names corrupt the entire design
-- Do not present a Blueprint without validating with the user first
-- Do not ask questions as plain text — always use `AskUserQuestion`
-- Do not ignore `config.architecture.style` — always detect it before CHECKPOINT 2
-
----
-
-## PRE-FLIGHT
-
-## Pre-flight — Tool Availability
-
-Check session context lines for tool readiness:
-- `neonctl ✓` → Neon CLI method for schema analysis
-- `neonctl ✗` → Static code analysis fallback (Grep/Read)
-- `context7 ✓` → Use for library docs when writing spec.md
-- `context7 ✗` → WebSearch + WebFetch fallback
-
----
-
-## MANDATORY: Session Tasks
-
-> **BEFORE starting any design work**, analyze the workflow below and create session tasks.
->
-> **Rules:** Minimum 3 tasks, typically 5-7. Mark `in_progress` before starting, `completed` after.
->
-> **Typical tasks:** pre-flight validation, schema analysis, architecture blueprint, spec generation, contracts generation, decisions documentation, design approval
-
----
-
-**STEP 0 (BEFORE any reads or writes) — Ensure phase is design:**
-
-```bash
-morph-spec state get $ARGUMENTS
-```
-
-Check the `"phase"` field in the output:
-
-**If `"phase": "design"`** → phase is correct, proceed.
-
-**If `"phase": "proposal"`** → execute in sequence:
-1. `morph-spec state mark-output $ARGUMENTS proposal`
-2. `morph-spec phase advance $ARGUMENTS` (→ design)
-
-**Any other value** → do not proceed — inconsistent state, report to user.
-
-> **Rule:** Never write to `2-design/` while the phase is not `design`. The hook will block and the sequence will be corrupted.
-
----
-
-Read in parallel:
-```
-Read: .morph/features/$ARGUMENTS/0-proposal/proposal.md
-    + Read: .morph/config/config.json          ← detect architecture.style
-    + Read: .morph/context/README.md
-```
-
-**Detect architecture style:**
-
-| Value of `config.architecture.style` | Path |
-|--------------------------------------|------|
-| `"vertical-slice"` | → **VSA** (CHECKPOINT 2-VSA + VSA contracts) |
-| any other value or absent | → **Standard** design flow (no architecture-specific blueprint) |
-
-If scope ≥ 20 tasks or refactor touches ≥ 5 domain files → **EnterPlanMode** before continuing.
-
----
-
-## CHECKPOINT 1 — Real Schema (MANDATORY before any generation)
-
-> **Rule:** Never assume field names. Every generated DTO must have a traceable origin in the schema.
-
-### 1.1 Read real schema
-
-Execute in parallel according to the stack detected in `config.json`:
-
-**Neon PostgreSQL (via Neon CLI):**
-
-> **Neon CLI (`neonctl`):** Run `neonctl connection-string` to get the DB URL.
-> Then use `pg_dump $(neonctl connection-string)` for full schema export, or `psql <DB_URL>` for targeted queries.
-> Cross-reference existing schema with the proposal to avoid duplicating tables or missing foreign keys to existing data.
-> If Neon database is not accessible, rely on EF Core/TypeScript entity scanning as described below.
-
-```
-Bash: neonctl connection-string → extract DB URL
-    + pg_dump $(neonctl connection-string) | grep -A20 "CREATE TABLE relevant_table"
-    + psql <DB_URL> -c "SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name = 'X'"
-    + psql <DB_URL> -c "SELECT tablename, policyname, cmd, qual FROM pg_policies WHERE schemaname = 'public'"
-```
-
-**EF Core (.NET):**
-```
-Glob: **/Entities/**/*.cs  →  Read each entity file
-Glob: **/*DbContext.cs     →  Read to see DbSet<> and relations
-Grep: "DbSet<"             →  confirm mapped entities
-```
-
-**TypeScript/Next.js:**
-```
-Glob: src/**/types/**/*.ts, src/**/models/**/*.ts
-Grep: "export interface|export type" → Read found files
-```
-
-### 1.2 Generate schema-analysis.md
-
-Write `.morph/features/$ARGUMENTS/2-design/schema-analysis.md` with:
-
-```markdown
-# Schema Analysis — {Feature}
-
-## Relevant Entities
-
-### {EntityName}
-| Field | DB Type | C#/TS Type | Nullable | Notes |
-|-------|---------|-----------|----------|-------|
-| id    | uuid    | Guid      | No       | PK    |
-| ...   | ...     | ...       | ...      | ...   |
-
-## Relationships
-- {Entity A} 1—N {Entity B} via {FK field}
-
-## JSONB / Complex Fields
-- {field}: internal structure {known keys}
-
-## Fields Not Referenced in Proposal
-- {field}: present in schema but no reference in the proposal
-```
-
-### 1.3 Validate with user
-
-Use `AskUserQuestion`:
-
-```json
-{
-  "questions": [{
-    "header": "Schema OK?",
-    "question": "Found these entities and fields in the schema. Are they correct before generating contracts?",
-    "multiSelect": false,
-    "options": [
-      { "label": "Confirm and continue", "description": "Schema mapped correctly" },
-      { "label": "I have corrections",   "description": "Use Other to describe what's wrong" }
-    ]
-  }]
-}
-```
-
-- **"Confirm"** → proceed to Checkpoint 2
-- **"I have corrections" / Other** → apply corrections to schema-analysis.md and repeat 1.3
-
----
-
-## CHECKPOINT 2 — Architecture Blueprint (MANDATORY before generating contracts)
-
-> Use the path corresponding to the style detected in PRE-FLIGHT.
-
----
-
-### CHECKPOINT 2-VSA — Vertical Slice Architecture
-
-#### 2-VSA.1 Dispatch dotnet-senior (VSA mode)
-
-```bash
-morph-spec dispatch-agents $ARGUMENTS design
-```
-
-Use the `recommended` field to find the dotnet-senior agent. The agent `.md` file is self-contained. Call:
-
-```
-Agent(subagent_type="morph-dotnet-senior", prompt="Design VSA blueprint for feature {feature}. Read .morph/features/{feature}/0-proposal/proposal.md and schema-analysis.md for context.")
-```
-
-The agent produces a VSA Blueprint with:
-- Entity fields (based on the schema validated in Checkpoint 1)
-- Operations (GetAll, GetById, Create, Update, Delete + custom)
-- Routes (`GET /api/{feature}s`, `POST /api/{feature}s`, etc.)
-- Error types (`{Entity}Errors.NotFound`, `{Entity}Errors.AlreadyExists`, etc.)
-- Validation rules per field
-
-**Parallelize** with other active agents from the dispatch config.
-
-#### 2-VSA.2 Validate Blueprint with user
-
-Present the generated blueprint in a readable format and use `AskUserQuestion`:
-
-```json
-{
-  "questions": [{
-    "header": "Blueprint OK?",
-    "question": "Planned these slices and operations for the feature. Confirm before generating spec and contracts?",
-    "multiSelect": false,
-    "options": [
-      { "label": "Confirm blueprint",  "description": "Generate spec.md and contracts with this blueprint" },
-      { "label": "Need adjustments",   "description": "Use Other to describe what to change" }
-    ]
-  }]
-}
-```
-
-- **"Confirm"** → proceed to VSA generation
-- **"Need adjustments" / Other** → update blueprint and repeat 2-VSA.2
-
----
-
----
-
-## Artifact Generation
-
-With schema validated (Checkpoint 1) and blueprint confirmed (Checkpoint 2):
-
-### Generate spec.md
-
-> Detailed structure: `references/spec-authoring-guide.md`
-
-> **MCP:** Before writing spec.md, use **Context7 MCP** (`resolve-library-id` → `query-docs`) to fetch current API docs for libraries referenced in the proposal (e.g., FluentValidation, MediatR, TanStack Query). This ensures spec references correct method signatures and patterns. If Context7 is not available, use **WebSearch** + **WebFetch** to look up the official documentation.
-
-Read the spec-authoring-guide first, then create `.morph/features/$ARGUMENTS/2-design/spec.md` with:
-- Overview, Functional Requirements (FR001...) with measurable acceptance criteria
-- Non-Functional Requirements, Data Model
-- **VSA:** section `## Architecture Style: Vertical Slice` with slices and operations
-- Infrastructure Requirements (if applicable)
-
-### Generate contracts — VSA
-
-**Mandatory source:** fields from `schema-analysis.md` + operations from the VSA Blueprint.
-
-```bash
-morph-spec template render \
-  dotnet-contracts-vsa \
-  .morph/features/$ARGUMENTS/2-design/contracts.cs \
-  '{
-    "FEATURE_NAME": "$ARGUMENTS",
-    "NAMESPACE": "{ProjectNamespace}",
-    "ROUTE": "/api/{kebabCase FEATURE_NAME}s",
-    "DATE": "{{TODAY}}"
-  }'
-```
-
-After rendering, fill in the `// placeholder:` sections with real fields from schema-analysis.md.
-
-**Mandatory VSA patterns:**
-- `sealed` on handlers, endpoints, validators, records
-- `Guid.CreateVersion7()` for IDs
-- `result.Match()` in endpoints
-- `{Entity}Errors` static shared across all slices
-- CancellationToken in all async methods
-
-### Stack adaptation for contracts
-
-For TypeScript/Next.js projects, generate `contracts.ts` instead of `contracts.cs`. Use TypeScript interfaces with the same VSA patterns adapted to the language (e.g., `readonly` fields, union types for status enums, typed event interfaces).
-
-### Generate decisions.md
-
-```bash
-morph-spec template render docs/decisions \
-  .morph/features/$ARGUMENTS/2-design/decisions.md \
-  '{"FEATURE_NAME": "$ARGUMENTS", "DATE": "{{TODAY}}", "decisions": []}'
-```
-
-Mandatory ADRs: architecture choice (VSA + justification), UI library (if UI/UX phase ran), external integrations, Azure resources with cost estimates.
-
----
-
-## Quality Scoring System
-
-After generating artifacts, evaluate the design with the **Quality Score (0–100)**:
-
-| Dimension | Pts | Maximum score criteria |
-|-----------|-----|----------------------|
-| **Schema fidelity** | 25 | All fields in contracts have traceable origin in schema-analysis.md — zero guessed |
-| **Functional coverage** | 20 | All FRs from the proposal are in spec with measurable acceptance criteria |
-| **Blueprint complete** | 20 | **VSA:** all slices have handler, validator (except GetAll), endpoint and errors |
-| **External integrations** | 20 | APIs/services with payload, error format and retry policy documented |
-| **Infra / costs** | 15 | Azure resources estimated with cost, or "N/A" explicitly documented |
-
-**Thresholds:**
-
-| Score | Action |
-|-------|--------|
-| ≥ 85 | Design satisfactory. Offer to close or optionally refine |
-| 70–84 | Continue. Focus on the weakest dimensions |
-| < 70 | Continue. Open technical questions block implementation |
-
----
-
-## Quality Loop
-
-**Repeat until: score ≥ 85 OR user approves.**
-
-### A. Calculate score
-
-Score each dimension based on the generated artifacts. Identify the most impactful gaps.
-
-### B. Identify open questions
-
-Typical questions by dimension:
-
-| Weak dimension | Example questions |
-|----------------|-------------------|
-| Schema fidelity | "The `metadata` field (JSONB) — what is its structure? Which keys?" |
-| Functional coverage | "FR003 says 'notify user' — by email, push, or both?" |
-| Blueprint VSA | "Should the CreateOrder slice trigger an email job or is it synchronous?" |
-| Integrations | "Does the payment API use webhook or polling to confirm?" |
-| Infra/costs | "Does this feature need Azure storage? Which tier?" |
-
-### C. Ask via AskUserQuestion
-
-Maximum 3 technical questions per call. In the last call of each round, always include:
-
-```json
-{
-  "header": "Continue?",
-  "question": "Continue refining or finalize the design?",
-  "multiSelect": false,
-  "options": [
-    { "label": "Continue refining",   "description": "More open questions identified" },
-    { "label": "Finalize design",     "description": "Proceed to Plan phase with current design" }
-  ]
-}
-```
-
-> If score ≥ 85, adjust: `"Continue (optional)"` with description `"Score {N}/100 — design is satisfactory"`
-
-### D. Incorporate answers
-
-Update spec.md, contracts, and decisions.md with the answers received. Recalculate the score.
-
-### E. Exit condition
-
-- User chose **"Finalize design"** → exit loop
-- Score ≥ 85 AND no new questions → exit loop
-
----
-
-## Post-Loop: Update State
-
-```bash
-morph-spec state mark-output $ARGUMENTS schema-analysis
-morph-spec state mark-output $ARGUMENTS spec
-morph-spec state mark-output $ARGUMENTS contracts
-morph-spec state mark-output $ARGUMENTS decisions
-```
-
-If Azure costs were estimated:
-```bash
-morph-spec state set $ARGUMENTS costs.estimated {X.XX}
-```
-
-## MANDATORY PAUSE
-
-```json
-{
-  "questions": [{
-    "header": "Approval",
-    "question": "Design generated. Approve to continue to Plan?",
-    "multiSelect": false,
-    "options": [
-      { "label": "Approve and continue", "description": "Advance to Plan phase" },
-      { "label": "I have feedback",      "description": "Describe what to change (Other)" }
-    ]
-  }]
-}
-```
-
-- **"Approve and continue"** →
-  ```bash
-  morph-spec approve $ARGUMENTS design
-  morph-spec phase advance $ARGUMENTS
-  ```
-- **"I have feedback" / Other** → apply feedback and repeat PAUSE
-
-## Generated Outputs
-
-- `.morph/features/$ARGUMENTS/2-design/schema-analysis.md` — Real schema mapped and validated
-- `.morph/features/$ARGUMENTS/2-design/spec.md` — Complete technical specification
-- `.morph/features/$ARGUMENTS/2-design/contracts.cs` (or `.ts` for TypeScript projects) — Contracts based on real schema (VSA)
-- `.morph/features/$ARGUMENTS/2-design/decisions.md` — Documented ADRs
-
-## Advancement Criteria
-
-- [x] Architecture style detected from `config.architecture.style`
-- [x] Schema validated by user (Checkpoint 1)
-- [x] Blueprint confirmed by user (Checkpoint 2-VSA)
-- [x] Quality score ≥ 85 OR user finalized
-- [x] All field names in contracts traceable to schema-analysis.md
-- [x] State updated
-- [x] User approved at MANDATORY PAUSE
-
----
-
-<!-- morph-outputs:design -->
-| Output | Caminho |
-|--------|---------|
-| `schemaAnalysis` | `.morph/features/{feature}/2-design/schema-analysis.md` |
-| `spec` | `.morph/features/{feature}/2-design/spec.md` |
-| `contracts` | `.morph/features/{feature}/2-design/contracts.cs` |
-| `contractsTs` | `.morph/features/{feature}/2-design/contracts.ts` |
-| `contractsVsa` | `.morph/features/{feature}/2-design/contracts-vsa.cs` |
-| `decisions` | `.morph/features/{feature}/2-design/decisions.md` |
-<!-- /morph-outputs -->
-
-## Relevant Standards
-
-Before starting the design phase, proactively read standards relevant to the project's stack:
-- Architecture standards: `.morph/framework/standards/architecture/` — especially vertical-slice patterns
-- Backend standards: `.morph/framework/standards/backend/` — for API contracts and patterns
-- Data standards: `.morph/framework/standards/data/` — for database schema and access patterns
-- These standards are also available as rules that auto-load when editing matching file types.
-
----
-
-Continue automatically to Plan phase after approval.

package/framework/skills/level-1-workflows/morph-phase-design/references/architecture-analysis-guide.md

@@ -1,44 +0,0 @@
-# Architecture Analysis Guide — Prompts de Dispatch
-
-> Prompts completos para os agentes de análise de arquitetura dispatch via Task tool.
-> Referenciado pelo Passo 1.5 de `phase-design/SKILL.md`.
-
----
-
-## Caminho: `dotnet-senior` (VSA)
-
-**Quando usar:** Default architecture style (Vertical Slice Architecture).
-
-**Ref:** `framework/standards/architecture/vertical-slice/vertical-slice.md`
-
-**Use o Agent tool com o subagentType do dispatch recommendation:**
-
-```
-Agent(subagent_type="morph-dotnet-senior", prompt="...")
-Prompt (enriquecido com conteúdo da proposta):
-
-Você é o VSA Specialist da feature '$ARGUMENTS'.
-
-Proposta da feature:
-[conteúdo de .morph/features/$ARGUMENTS/0-proposal/proposal.md]
-
-Standards de referência:
-[.morph/framework/standards/architecture/vertical-slice/vertical-slice.md]
-
-Produza um VSA Blueprint:
-1. ENTITY FIELDS: todos os campos com tipos C# corretos (sem AggregateRoot, sem Value Objects)
-2. OPERATIONS: slices necessários (Create, GetAll, GetById, Update, Delete + operações customizadas)
-3. ROUTES: HTTP method + rota por operação (ex: POST /api/products, GET /api/products/{id:guid})
-4. ERROR TYPES: Error factory methods para {Entity}Errors
-5. VALIDATION RULES: regras FluentValidation por campo por operação
-
-Não use AggregateRoot, DomainEvent, CQRS formal, MediatR, Application Service layer.
-```
-
-**Após receber o resultado:** Documente no spec.md (seção `## Architecture Style: Vertical Slice`).
-
----
-
-## Nota sobre Paralelização
-
-Este Task dispatch pode iniciar **simultaneamente** com o Passo 2 (schema analysis), pois ambos são independentes. Use dois Task calls em paralelo quando o schema analysis também for necessário.

package/framework/skills/level-1-workflows/morph-phase-design/references/spec-authoring-guide.md

@@ -1,55 +0,0 @@
-# Spec Authoring Guide — Seções do spec.md
-
-> Guia de referência para estrutura e conteúdo de cada seção do `spec.md`.
-> Referenciado pelo Passo 3 de `phase-design/SKILL.md`.
-
----
-
-## 3.1. Overview
-
-- **Objetivo:** Resumo de 1-2 parágrafos
-- **Usuários afetados:** Quem vai usar?
-- **Problema resolvido:** Qual dor/necessidade?
-
-## 3.2. Functional Requirements
-
-Lista detalhada de requisitos funcionais:
-
-```markdown
-### FR001: {Requisito}
-**Description:** {O que deve fazer}
-**Acceptance Criteria:**
-- [ ] Critério 1
-- [ ] Critério 2
-**Priority:** High/Medium/Low
-```
-
-## 3.3. Non-Functional Requirements
-
-- Performance (tempos de resposta esperados)
-- Segurança (autenticação, autorização)
-- Escalabilidade (volume de dados/usuários)
-- Disponibilidade (uptime esperado)
-
-## 3.4. Technical Architecture
-
-- **Camadas:** (Presentation, Application, Domain, Infrastructure)
-- **Patterns:** (Repository, CQRS, DI, etc.)
-- **Dependências:** Bibliotecas/serviços externos necessários
-
-## 3.5. Data Model
-
-- Entities principais
-- Relacionamentos (1:1, 1:N, N:N)
-- Campos obrigatórios vs opcionais
-- Validações de negócio
-
-## 3.6. Infrastructure Requirements
-
-Se houver recursos Azure:
-- Banco de dados (Azure SQL, Cosmos DB)
-- Storage (Blob Storage)
-- Compute (Container Apps, App Service)
-- Monitoring (App Insights)
-
-> **SEMPRE usar Bicep para infra!**