@polymorphism-tech/morph-spec 4.21.0 → 5.0.1

package/framework/skills/core/morph-plan/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: morph-plan
+description: Guia a produção dos três artefatos de planejamento de uma feature
+version: core
+when-to-invoke: ao iniciar a fase plan de uma feature, após o gate 1 (proposal aprovado)
+user-invokable: true
+---
+
+# morph-plan
+
+## Objetivo
+Produzir spec.md, mandate.md e tasks.md com qualidade suficiente para abrir o Gate 2.
+Os três artefatos juntos definem o quê, o como e o quanto da feature.
+
+## Quando invocar
+Ao iniciar a fase plan — após o proposal.md ser aprovado e antes de qualquer implementação.
+
+## O que fazer
+
+1. Leia o `proposal.md` em `.morph/features/{feature}/0-proposal/` para entender escopo e critérios de aceite.
+2. Produza `spec.md` em `.morph/features/{feature}/2-plan/`:
+   - Arquitetura da solução: quais componentes, como se conectam, fluxos de dados principais.
+   - Edge cases identificados e como serão tratados.
+   - Integrações externas e contratos esperados.
+3. Produza `mandate.md` em `.morph/features/{feature}/2-plan/`:
+   - Stack exata do projeto (leia do CLAUDE.md → campo Stack).
+   - Standards obrigatórios: liste os IDs relevantes de `framework/standards/STANDARDS.json`.
+   - Patterns proibidos — inclua sempre os defaults abaixo mais qualquer específico da feature:
+     - `Guid.NewGuid()` → usar `Guid.CreateVersion7()`
+     - Classes não-sealed sem justificativa documentada
+     - Exceptions como fluxo de controle → usar result pattern com `result.Match()`
+     - Repository pattern / `IRepository<T>` → handlers VSA acessam DbContext diretamente
+   - Checklist de done com critérios verificáveis por tarefa.
+4. Produza `tasks.md` em `.morph/features/{feature}/2-plan/`:
+   - Liste cada tarefa com ID único (T1, T2...).
+   - Para cada tarefa: descrição, dependências, estimativa de esforço, critério de done.
+   - Ordene por dependências — tarefas sem dependências primeiro.
+5. Apresente o Gate 2 ao usuário usando exatamente este formato:
+
+   ```
+   ## Gate 2 — Plano pronto para revisão
+
+   **Spec:** {1 frase do problema} → {1 frase da solução técnica}
+   **Mandate:** Stack: {stack} | Standards: {N obrigatórios} | Proibido: {padrões proibidos listados}
+   **Tasks:** {N tarefas} | Estimativa: {X horas/dias} | Caminho crítico: {IDs das tarefas sem dependências paralelas}
+
+   Decisões de arquitetura:
+   - {decisão 1} — alternativa descartada: {alternativa}
+   {adicione apenas se houver decisões não triviais}
+
+   Aprovado? Responda "pode implementar" para avançar.
+   ```
+
+   Aguarde resposta explícita. Se o usuário pedir ajustes, aplique e reapresente o gate completo antes de avançar.
+
+## Output esperado
+- `.morph/features/{feature}/2-plan/spec.md` — especificação técnica completa
+- `.morph/features/{feature}/2-plan/mandate.md` — contrato de implementação
+- `.morph/features/{feature}/2-plan/tasks.md` — lista de tarefas ordenada
+
+## Referências
+- `framework/MORPH.md` — seções 2 (Fases), 3 (Contratos de Output), 5 (Gates)
+- `framework/standards/STANDARDS.json` — para identificar standards relevantes ao mandate
+- `.morph/features/{feature}/0-proposal/proposal.md` — escopo da feature

package/framework/skills/core/morph-review/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: morph-review
+description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
+version: core
+when-to-invoke: ao iniciar a fase review, após todas as tarefas de implementação serem concluídas
+user-invokable: true
+---
+
+# morph-review
+
+## Objetivo
+Verificar se a implementação atende ao mandate.md e produzir um review-report.md
+claro o suficiente para que o usuário tome a decisão de aprovação ou rejeição.
+
+## Quando invocar
+Ao iniciar a fase review — após todas as tarefas do tasks.md estarem com status Done
+e o recap.md estar atualizado.
+
+## O que fazer
+
+1. Leia o mandate.md em `.morph/features/{feature}/2-plan/mandate.md`.
+   Liste os critérios de done, standards obrigatórios e patterns proibidos.
+
+2. Leia o recap.md em `.morph/features/{feature}/3-implement/recap.md`.
+   Verifique se todas as tarefas têm entrada e se os problemas foram resolvidos.
+
+3. Para cada critério do mandate.md, verifique se foi atendido:
+   - Se atendido: registre como "aprovado" com evidência (arquivo ou comportamento).
+   - Se não atendido: registre como "bloqueante" com descrição do gap.
+   - Se parcialmente atendido: registre como "pendência" com o que falta.
+
+4. Execute morph-eval na implementação completa (fase, não tarefa) para obter scores por dimensão.
+
+5. Produza `review-report.md` em `.morph/features/{feature}/4-review/` com:
+   - Scores por dimensão (arquitetura, contratos, qualidade, cobertura)
+   - Score composto final
+   - Lista de itens bloqueantes (se houver) — com descrição e critério de resolução
+   - Lista de melhorias recomendadas (não bloqueantes)
+   - Recomendação final: Aprovado / Rejeitar com condições / Reprovar
+
+6. Se houver itens bloqueantes (score < 6 em qualquer dimensão bloqueante), corrija antes
+   de apresentar o review-report.md ao usuário. Não abra o Gate 3 com bloqueantes em aberto.
+
+7. Finalize o trace de execução em `.morph/traces/YYYY-MM-DD-{feature}-implement.json`:
+   - Preencha `phase_summary.tasks_completed`, `tasks_failed`, `avg_eval_score`
+   - Calcule `standards_most_used` a partir das entradas em `tasks[].standards_consulted`
+   - Preencha `sub_agents_dispatched` com a contagem de tasks onde `sub_agent_dispatched: true`
+   - Preencha `completed_at` com o timestamp atual
+
+8. Apresente o relatório ao usuário e aguarde o Gate 3.
+
+## Output esperado
+- `.morph/features/{feature}/4-review/review-report.md` com scores e recomendação
+- Trace da fase com `phase_summary` preenchido
+- Gate 3 apresentado ao usuário para aprovação
+
+## Referências
+- `framework/MORPH.md` — seção 5 (Gate 3) e seção 1 (papel Evaluator)
+- `framework/skills/core/morph-eval/SKILL.md` — para calcular scores por dimensão
+- `framework/evals/trace-schema.md` — formato canônico do trace
+- `.morph/features/{feature}/2-plan/mandate.md` — critérios de done da feature
+- `.morph/features/{feature}/3-implement/recap.md` — registro de execução

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: morph-stack-scan
+description: Varre o codebase existente, detecta stack atual, compara com o stack padrão e gera migration-plan.md se houver desvios
+version: core
+when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
+user-invokable: true
+---
+
+# morph-stack-scan
+
+## Objetivo
+Identificar o estado real do codebase antes de planejar qualquer feature — garantindo que a implementação não adicione inconsistência a um projeto já existente.
+
+## Quando invocar
+Quando o projeto já tem código existente e você precisa entender o estado atual antes de propor uma feature. Normalmente invocado pelo morph-brainstorming, mas pode ser invocado diretamente.
+
+## Stack padrão de referência
+
+| Camada | Esperado |
+|--------|----------|
+| Runtime | .NET 10 |
+| Arquitetura | VSA — feature-folder: `{Feature}/` com Handler, Validator, Endpoint, Errors, Tests |
+| ORM | EF Core + Neon (Postgres) |
+| IDs | `Guid.CreateVersion7()` |
+| Classes | `sealed` por padrão |
+| Erros | Result pattern (`result.Match()`), não exceptions não tratadas |
+| IA | Microsoft Agent Framework (MAF) |
+| Frontend | Next.js App Router + Tailwind + Framer Motion + Shadcn |
+| Jobs | Hangfire (apenas quando necessário) |
+
+**Padrões proibidos:** `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, Repository pattern, `IRepository<T>`.
+
+## O que fazer
+
+1. Despache um `Explore` subagent para varrer o codebase:
+
+   ```
+   Varredura de stack compliance — morph-stack-scan.
+
+   Leia os seguintes arquivos/pastas e reporte o que encontrar:
+
+   BACKEND:
+   - Todos os .csproj: qual TargetFramework? Quais PackageReferences relevantes?
+   - Procure por: Guid.NewGuid() vs Guid.CreateVersion7(), sealed classes, result pattern vs exceptions
+   - Estrutura de src/: segue feature-folder (VSA)? Tem Controllers? Tem IRepository<T>?
+   - Migrations/: qual ORM? Neon/Postgres ou outro banco?
+   - Microsoft.Agents.* ou Microsoft.Extensions.AI nos PackageReferences?
+
+   FRONTEND:
+   - package.json: Next.js? Tailwind? Framer Motion? Shadcn/ui?
+   - Estrutura de app/ ou pages/: App Router ou Pages Router?
+
+   JOBS:
+   - Hangfire nos PackageReferences?
+
+   Para cada item acima, responda: presente/ausente, e se presente qual versão ou padrão.
+   Não faça sugestões — apenas reporte o que existe.
+   ```
+
+2. Com os resultados da varredura, compare com o stack padrão item por item e classifique cada desvio:
+
+   | Severidade | Critério |
+   |------------|---------|
+   | **Bloqueante** | Runtime diferente (.NET 8 ou anterior), ORM diferente (Dapper puro sem EF Core), banco diferente (MySQL, SQL Server) |
+   | **Alto** | `Guid.NewGuid()` generalizado, Repository pattern em toda a codebase, exceptions como fluxo de controle |
+   | **Médio** | Classes não-sealed, Pages Router em vez de App Router, biblioteca de UI diferente |
+   | **Baixo** | Versões de pacotes desatualizadas mas compatíveis |
+
+3. Produza `stack-scan.md` em `.morph/features/{feature}/0-proposal/`:
+
+   ```markdown
+   # Stack Scan — {feature}
+
+   ## Resultado
+   {Em compliance / Desvios detectados}
+
+   ## Stack detectado
+   | Camada | Detectado | Esperado | Status |
+   |--------|-----------|----------|--------|
+   | Runtime | .NET X | .NET 10 | ✓ / ✗ |
+   ...
+
+   ## Desvios
+   ### Bloqueantes
+   - {desvio}: {onde foi encontrado} — impacto: {o que quebra se não migrar}
+
+   ### Não bloqueantes
+   - {desvio}: {onde foi encontrado} — migração: {como resolver}
+
+   ## Recomendação
+   {Em compliance — prosseguir para morph-brainstorming}
+   {ou: Migração necessária antes de prosseguir — veja migration-plan.md}
+   ```
+
+4. Se houver desvios bloqueantes ou altos, produza `migration-plan.md` em `.morph/features/{feature}/0-proposal/` com:
+   - Lista de desvios ordenados por severidade
+   - Para cada desvio: o que migrar, como migrar, estimativa de esforço, ordem sugerida
+   - Pergunta única via `AskUserQuestion`: "Esta migração deve ser incluída na feature atual ou tratada numa feature separada?"
+
+5. Se não houver desvios (ou apenas baixos): informe "codebase em compliance com o stack padrão" e prossiga para morph-brainstorming ou morph-plan conforme o contexto.
+
+## Output esperado
+- `.morph/features/{feature}/0-proposal/stack-scan.md` — resultado da varredura
+- `.morph/features/{feature}/0-proposal/migration-plan.md` — apenas se houver desvios altos/bloqueantes
+- Decisão documentada: incluir migração nesta feature ou separar
+
+## Referências
+- `framework/MORPH.md` — seção 4 (Standards), seção 2 (Fases)
+- `framework/skills/core/morph-brainstorming/SKILL.md` — fluxo greenfield/brownfield

package/framework/skills/core/morph-standards/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: morph-standards
+description: Localiza e carrega um standard específico do STANDARDS.json sob demanda
+version: core
+when-to-invoke: quando precisar consultar um standard específico durante a implementação
+user-invokable: true
+---
+
+# morph-standards
+
+## Objetivo
+Encontrar o standard certo para a situação atual e carregar apenas esse arquivo no contexto.
+Nunca carregue todos os standards — o custo de token não compensa.
+
+## Quando invocar
+Quando durante a implementação surgir uma dúvida de padrão arquitetural, de contrato, de qualidade
+ou de teste — e o mandate.md não for suficiente para resolver.
+
+## O que fazer
+
+1. Abra `framework/standards/STANDARDS.json`.
+
+2. Filtre por `category` primeiro (valores típicos: "architecture", "contracts", "testing", "frontend", "backend").
+
+3. Dentro da categoria, filtre por `tags` que correspondam ao stack do projeto
+   (ex: "dotnet", "nextjs", "blazor", "typescript").
+
+4. Se dois standards parecerem relevantes e houver conflito, adote o mais específico ao stack.
+   Registre o conflito no `decisions.md` da feature.
+
+5. Leia o arquivo `.md` do standard selecionado — o path está no campo `path` do JSON.
+
+6. Aplique o standard na tarefa atual.
+
+7. Registre no `recap.md`: qual standard foi consultado e como foi aplicado.
+
+## Quando não há standard adequado
+Registre no `decisions.md` que nenhum standard cobre o caso.
+Descreva o critério adotado e sinalize para revisão futura.
+Não invente um standard — padrões não documentados são dívida técnica.
+
+## Output esperado
+- Standard identificado e lido no contexto
+- Critério de implementação claro para a tarefa atual
+- Entrada no recap.md registrando o standard consultado
+
+## Referências
+- `framework/standards/STANDARDS.json` — índice completo com id, name, path, category, tags
+- `framework/MORPH.md` — seção 4 (Como consultar Standards)

package/framework/standards/STANDARDS.json

@@ -1097,6 +1097,38 @@
       "stacks": [
         "*"
       ]
+    },
+    {
+      "id": "frontend-design-system-ai-image-generation",
+      "name": "AI Image Generation",
+      "path": "frontend/design-system/ai-image-generation.md",
+      "category": "frontend",
+      "subcategory": "design-system",
+      "tags": [
+        "image",
+        "gemini",
+        "asset",
+        "ai-generation",
+        "placeholder",
+        "mcp"
+      ],
+      "aliases": [
+        "Image Generation",
+        "AI Assets",
+        "Gemini Images"
+      ],
+      "anchors": {
+        "when-to-use": "#when-to-use-ai-generated-images",
+        "prompt-patterns": "#prompt-engineering-patterns",
+        "aspect-ratios": "#aspect-ratio-guide",
+        "assets-md": "#assetsmd-format",
+        "edit-workflows": "#iterative-editing-workflows"
+      },
+      "digest": "Guidelines for generating project images with Gemini Image MCP — prompt patterns, aspect ratios, design-system-aware prompts, iterative editing, and assets.md format.",
+      "stacks": [
+        "nextjs",
+        "next"
+      ]
     }
   ]
 }

package/framework/standards/frontend/design-system/ai-image-generation.md

@@ -0,0 +1,244 @@
+# AI Image Generation
+
+> **Scope:** nextjs
+> **Layer:** 1 (load when relevant)
+> **Keywords:** image, gemini, asset, ai-generation, placeholder, mcp, next/image
+> **Load When:** feature has UI components requiring image assets
+
+## When to Use AI-Generated Images
+
+| Use Case | Approach | Examples |
+|----------|----------|---------|
+| **AI generation** | Gemini Image MCP | Hero images, brand illustrations, feature-specific visuals, empty states, background panels |
+| **Stock photos** | External sources | Generic content (people in offices, nature scenes, stock portraits) |
+| **SVG/CSS** | Code-based | Icons, patterns, gradients, geometric shapes, loading animations |
+| **Skip** | Other tools | Screenshots (Playwright), diagrams (Mermaid), logos (vector tools) |
+
+**Decision rule:** If the image is unique to the project's brand/aesthetic and doesn't exist as stock, use AI generation. If it's generic and widely available, use stock. If it's geometric or icon-based, use SVG/CSS.
+
+## Gemini Image MCP API
+
+```javascript
+// Generate a new image
+mcp__gemini_image_mcp__generate_image({
+  prompt: string,           // Text description (max 5000 chars, narrative style)
+  aspectRatio?: "1:1" | "2:3" | "3:2" | "3:4" | "4:3" | "9:16" | "16:9",
+  outputPath?: string,      // File path to save (e.g., "public/images/feature/hero.png")
+  model?: string,           // Default: gemini-2.5-flash-image
+})
+
+// Edit an existing image
+mcp__gemini_image_mcp__edit_image({
+  imageSource: string,      // Path to image or image ID
+  prompt: string,           // Short, targeted edit instructions (1-2 sentences)
+  outputPath?: string,
+})
+
+// Continue editing last image
+mcp__gemini_image_mcp__continue_editing({
+  prompt: string,           // One adjustment at a time
+})
+
+// List generated images
+mcp__gemini_image_mcp__list_images({
+  type?: "generated" | "edited" | "all",
+  limit?: number,
+})
+
+// Get image details
+mcp__gemini_image_mcp__get_image_info({
+  imageId?: string,         // Defaults to last image
+})
+```
+
+## Prompt Engineering Patterns
+
+### Design-System-Aware Prompts
+
+Read `design-system.md` or `globals.css` to extract project tokens. Inject into prompts:
+
+- **Background color** → use as image background
+- **Primary/accent colors** → use as highlight colors
+- **Font pair** → mention for text elements
+- **Aesthetic direction** → "Modern Luxury", "Kinetic Atelier", etc.
+
+```
+"{subject description}. Dark charcoal background (#10131a) with copper (#D2802D)
+and gold (#FFB779) accent colors. {style modifiers}. Premium luxury aesthetic.
+{composition rules}."
+```
+
+### Component-Contextual Prompts
+
+Describe what the image will BE in the UI, not just the subject:
+
+- **Hero image** → "floating tablet showing app dashboard on dark background" (not just "fitness dashboard")
+- **Auth background** → "gym equipment with moody lighting" (matches brand feel)
+- **Empty state** → "artistic wireframe body silhouette" (matches feature context)
+
+### Narrative Style
+
+Gemini responds best to coherent paragraphs. Build prompts by layering:
+
+1. **Subject** — hyper-specific description
+2. **Environment** — foreground, mid-ground, background (layered for depth)
+3. **Lighting** — multiple sources with different colors/directions
+4. **Style** — photography terms ("85mm portrait lens") or art style ("cel-shaded")
+5. **Color palette** — dominant colors and contrast relationships
+6. **Composition** — camera angle, framing, negative space
+
+**Never:** keyword spam ("beautiful, stunning, 4k, masterpiece"), JSON prompts, negative prompts ("no cars").
+
+## Iterative Editing Workflows
+
+**Cardinal rule: generation demands depth; editing demands restraint.**
+
+### Adding / Removing Elements
+One sentence. Don't describe how to integrate — the model handles that.
+```
+"Add a knitted wizard hat to the cat."
+```
+
+### Background Replacement
+State the new background simply. Don't over-describe.
+```
+"Replace the background with a tropical beach at sunset."
+```
+
+### Inpainting (Targeted Changes)
+Name what changes and what stays in one line.
+```
+"Change the blue sofa to a brown leather chesterfield. Keep everything else."
+```
+
+### Style Transfer
+Name the target style.
+```
+"Transform this into Van Gogh's Starry Night style."
+```
+
+### Iterative Refinement with `continue_editing`
+One change at a time:
+- "Make the lighting warmer"
+- "More contrast in the shadows"
+- "Zoom out a bit"
+- "More serious expression"
+
+### Text Rendering
+The model frequently misspells words. After generating any image with text:
+1. View the result
+2. If text is wrong: `continue_editing` with "Fix the text — it should read '{correct text}' exactly. Keep everything else."
+3. Expect 2-3 iterations for correct text
+
+## Aspect Ratio Guide
+
+| Use Case | Ratio | Examples |
+|----------|-------|---------|
+| Hero / banner | `16:9` | Landing page hero, YouTube thumbnail, desktop wallpaper |
+| Card / blog header | `3:2` | Feature cards, blog post headers, landscape photo |
+| Avatar / icon | `1:1` | Profile pictures, social media posts, square icons |
+| Auth panel / sidebar | `3:4` | Login brand image, Pinterest-style, portrait poster |
+| Portrait | `2:3` | Book cover, tall illustration, portrait photo |
+| Story / reel | `9:16` | Mobile wallpaper, social story, vertical banner |
+| Standard display | `4:3` | Documentation, slides, standard display |
+
+## File Naming & Directory
+
+**Convention:** `public/images/{feature}/{purpose}.png`
+
+- Lowercase, kebab-case, descriptive names
+- Group by feature, not by type
+- Examples:
+  - `public/images/ui-redesign/hero-mockup.png`
+  - `public/images/ui-redesign/gym-equipment.png`
+  - `public/images/ui-redesign/body-analysis.png`
+
+## Next.js Image Integration
+
+```tsx
+import Image from 'next/image';
+
+// Above-the-fold hero image (priority for LCP)
+<Image
+  src="/images/{feature}/hero-mockup.png"
+  alt="AI fitness analysis dashboard"
+  width={1440}
+  height={810}
+  priority
+  sizes="100vw"
+/>
+
+// Card image with responsive sizing
+<Image
+  src="/images/{feature}/card-image.png"
+  alt="Feature card illustration"
+  width={600}
+  height={400}
+  sizes="(max-width: 768px) 100vw, 50vw"
+  className="rounded-lg"
+/>
+
+// Background image with fill
+<div className="relative h-full">
+  <Image
+    src="/images/{feature}/auth-background.png"
+    alt=""
+    fill
+    className="object-cover"
+    priority={false}
+  />
+</div>
+```
+
+## `assets.md` Format
+
+The `assets.md` file is created during the UI/UX phase (Step 4.5) and consumed by the implement phase.
+
+```markdown
+# Image Assets — {feature}
+
+## Design Context
+- Aesthetic: {from design-system.md}
+- Primary: {--color-primary value}
+- Background: {--color-background value}
+- Accent: {--color-accent value}
+- Font pair: {display + body fonts}
+
+## Assets
+
+### IMG-001: {Descriptive Name}
+- **Purpose:** {What this image represents in the UI}
+- **Route:** {App route where it appears}
+- **Component:** {React component name}
+- **Aspect Ratio:** {1:1 | 3:2 | 16:9 | etc.}
+- **Output Path:** `public/images/{feature}/{kebab-name}.png`
+- **Prompt:** "{Narrative prompt with design system colors and aesthetic direction injected}"
+- **Priority:** {high | medium | low}
+```
+
+**Example entry:**
+
+```markdown
+### IMG-001: Hero Mockup
+- **Purpose:** App dashboard floating on dark background for landing page hero
+- **Route:** /
+- **Component:** HeroSection
+- **Aspect Ratio:** 16:9
+- **Output Path:** `public/images/ui-redesign/hero-mockup.png`
+- **Prompt:** "A floating tablet showing a modern AI fitness analysis dashboard on a dark charcoal background (#10131a). Copper (#D2802D) and gold (#FFB779) accent lighting creates warm rim highlights around the device edges. The screen displays body metrics with glassmorphism cards. Premium luxury aesthetic, photorealistic, cinematic lighting with a key light from the left and cool blue fill from the right."
+- **Priority:** high
+```
+
+## Quality Checklist
+
+- [ ] Colors match design system tokens (no random colors in prompts)
+- [ ] No text artifacts or misspellings (if text in image)
+- [ ] Correct aspect ratio for intended use
+- [ ] Appropriate file size (< 500KB for web, < 200KB for cards)
+- [ ] Descriptive alt text written for accessibility
+- [ ] `<Image>` component with proper width/height dimensions
+- [ ] `priority` prop set for above-the-fold images
+- [ ] Build compiles after integration (`npm run build`)
+- [ ] Image visible in dev server at correct route
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/integration/mcp/mcp-tools.md

@@ -81,6 +81,53 @@ const docs = await mcp__context7__query_docs({
 // WebFetch for specific component API pages
 ```
 
+### Gemini Image MCP — AI Image Generation
+
+> Available in: **UI/UX** (preview generation), **Implement** (production assets)
+
+| Tool | Use Case | Example |
+|------|----------|---------|
+| `generate_image` | Create new image from text prompt | `mcp__gemini-image-mcp__generate_image({ prompt, aspectRatio, outputPath })` |
+| `edit_image` | Modify existing image | `mcp__gemini-image-mcp__edit_image({ imageSource, prompt })` |
+| `continue_editing` | Iterate on last generated/edited image | `mcp__gemini-image-mcp__continue_editing({ prompt })` |
+| `list_images` | Browse image generation history | `mcp__gemini-image-mcp__list_images({ type: "all" })` |
+| `get_image_info` | Get metadata about a specific image | `mcp__gemini-image-mcp__get_image_info({ imageId })` |
+
+```javascript
+// Generate a hero image using design system tokens
+// Read design-system.md first to get project colors and aesthetic direction
+const image = await mcp__gemini_image_mcp__generate_image({
+  prompt: "A floating tablet showing a modern dashboard interface on a dark charcoal background with copper and gold accent lighting. Premium luxury aesthetic, photorealistic, cinematic lighting with warm rim light.",
+  aspectRatio: "16:9",
+  outputPath: "public/images/my-feature/hero-mockup.png"
+});
+
+// Edit an existing image (keep edits short and targeted)
+await mcp__gemini_image_mcp__edit_image({
+  imageSource: "public/images/my-feature/hero-mockup.png",
+  prompt: "Make the lighting warmer and add a subtle copper glow around the tablet edges."
+});
+
+// Iterate with continue_editing (one change at a time)
+await mcp__gemini_image_mcp__continue_editing({
+  prompt: "More contrast in the shadows."
+});
+
+// Fallback: Manual image creation, stock photos, or placeholder divs
+```
+
+**Use cases by phase:**
+
+| Phase | Use Case | Tool |
+|-------|----------|------|
+| UI/UX (2) | Generate preview images for design approval | `generate_image` |
+| Implement (7) | Generate production assets from assets.md specs | `generate_image` + `edit_image` |
+| Implement (7) | Iterate on generated images for quality | `continue_editing` |
+
+> **Standard:** See `frontend/design-system/ai-image-generation.md` for prompt engineering patterns, aspect ratio guide, and `assets.md` format.
+
+---
+
 ### Phase 3 (Design) — Schema & Architecture
 
 | Tool | Use Case | Example |
@@ -246,6 +293,7 @@ await mcp__vercel__manage_env_vars({
 | Container ops | Docker CLI (`docker ps`, `docker logs`, `docker compose`) | — |
 | Cloud resources | Azure CLI (`az resource`, `az deployment`) | — |
 | Vercel deployments | Vercel MCP | Bash `vercel` CLI |
+| AI image generation | Gemini Image MCP | Manual creation or stock photos |
 
 **Rule:** MCP tools provide structured data (JSON responses). Native tools require manual parsing. **Always prefer MCP when available** — fall back to native when not. **Exceptions:** Neon, Docker, and Azure always use their respective CLIs directly — never MCP.
 

package/framework/templates/CLAUDE.md.core.guide.md

@@ -0,0 +1,29 @@
+# Guia de uso — CLAUDE.md.core.template
+
+Este template é o ponto de entrada do harness para um projeto morph-spec.
+Preencha cada campo uma vez, no setup. Não modifique a estrutura.
+
+## Campos
+
+**Nome do Projeto** — nome curto e identificável do sistema.
+
+**Domínio** — 1-2 frases. O que o sistema faz, para quem, e qual o principal constraint (ex: multi-tenant, LGPD, tempo real).
+
+**Stack** — não alterar. O harness assume o stack padrão. Se o projeto desvia (ex: Blazor em vez de Next.js), edite e documente o desvio aqui.
+
+**Harness** — não alterar. Esta seção instrui o modelo a:
+1. Ler `MORPH.md` ao iniciar a sessão
+2. Ler `state.json` para identificar feature ativa
+3. Assumir o papel correspondente sem aguardar instrução
+
+**Standards do projeto** — opcional. Apenas se algum standard específico do projeto desvia do default do stack. Default já injetado pelo morph-plan.
+
+**Slash commands** — não alterar. Os dois entry points oficiais.
+
+## Regras
+
+- Mantenha < 60 linhas — conteúdo acima não cabe em contexto comprimido.
+- Não adicione regras condicionais (sem "se dotnet, então...").
+- Não inline conteúdo de standards — aponte por ID, nunca copie.
+- Não adicione campo "Feature ativa" estático — Claude lê state.json.
+- Este arquivo pertence ao projeto. Versione no git.