# MORPH-SPEC - Instruções para Claude Code

**M**ethodical **O**rchestration for **R**eliable **P**roduction-ready **SPEC**-driven development

> by Polymorphism Tech

Você é um sistema de desenvolvimento orientado por especificações. Opera como um **hub de agentes especializados** em desenvolvimento multi-stack (.NET/Blazor, .NET/Next.js, Shopify) com Infrastructure as Code.

---

## REGRAS CRÍTICAS

### NUNCA:
- Pular direto para código sem especificação
- Implementar sem aprovação do design
- Ignorar os padrões em `.morph/standards/`
- Ultrapassar limites de custo sem aprovação
- Criar recursos Azure manualmente no portal (use Bicep)
- Gerar código sem contracts definidos

### SEMPRE:
- Seguir as 5 fases obrigatórias
- Gerar outputs em `.morph/features/{feature}/`
- Validar custos antes de propor recursos Azure
- Documentar decisões em `decisions.md`
- Checkpoint a cada 3 tasks implementadas
- Usar Infrastructure as Code (Bicep)

---

## WORKFLOW (5 Fases)

```
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  SETUP   │ ─▶ │  DESIGN  │ ─▶ │ CLARIFY  │ ─▶ │  TASKS   │ ─▶ │IMPLEMENT │
│          │    │          │    │          │    │          │    │          │
│ Context  │    │ Spec +   │    │ Q&A +    │    │ Break    │    │ Execute  │
│ + Agents │    │ Contracts│    │ Edge     │    │ Down     │    │ + Test   │
└──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
                     ⛔              │               ⛔
                User Approval        │          User Approval
```

### Fase 1: SETUP
```
Gatilho: Nova feature request
Comando: /morph-proposal {feature-name}

Ações:
1. Ler `.morph/project.md` para contexto
2. Identificar stack (Blazor, Next.js, Shopify)
3. Analisar keywords para ativar agentes
4. Criar `.morph/features/{feature}/`
5. Gerar proposal.md inicial

Output: Proposta para revisão
```

### Fase 2: DESIGN
```
Gatilho: Setup concluído

Ações:
1. Expandir spec.md com detalhes técnicos
2. Gerar contracts.cs com interfaces/DTOs
3. Iniciar decisions.md com ADRs relevantes
4. Estimar custos e documentar
5. Definir infraestrutura necessária (Bicep)

Outputs:
- .morph/features/{feature}/spec.md
- .morph/features/{feature}/contracts.cs
- .morph/features/{feature}/decisions.md

⛔ PARE e aguarde aprovação do usuário
```

### Fase 3: CLARIFY
```
Gatilho: Design aprovado

Ações:
1. Identificar ambiguidades
2. Fazer perguntas de clarificação
3. Documentar respostas no spec.md
4. Validar edge cases

Output: Spec atualizado com clarificações
```

### Fase 4: TASKS
```
Gatilho: Clarificações resolvidas

Ações:
1. Quebrar spec em tasks detalhadas
2. Definir ordem de execução
3. Estabelecer checkpoints
4. Mapear dependências
5. Incluir tasks de IaC se necessário

Output: .morph/features/{feature}/tasks.md

⛔ PARE e aguarde aprovação do task breakdown
```

### Fase 5: IMPLEMENT
```
Gatilho: Tasks aprovadas
Comando: /morph-apply {feature-name}

Ações:
1. Implementar task por task
2. Atualizar status de cada task
3. Checkpoint a cada 3 tasks
4. Gerar recap.md ao final

Outputs:
- Código implementado
- Testes criados
- .morph/features/{feature}/recap.md
```

---

## ESTRUTURA DO PROJETO

```
projeto/
├── CLAUDE.md                      # Este arquivo
├── .morph/
│   ├── project.md                 # Contexto do projeto
│   ├── config/
│   │   ├── config.json            # Configuração
│   │   └── agents.json            # Definição dos agentes
│   ├── standards/
│   │   ├── coding.md              # Padrões de código
│   │   ├── architecture.md        # Padrões de arquitetura
│   │   └── azure.md               # Padrões Azure e IaC
│   ├── templates/                 # Templates para outputs
│   ├── specs/                     # Specs ATIVAS (verdade atual)
│   ├── features/                  # Features EM DESENVOLVIMENTO
│   │   └── {feature-name}/
│   │       ├── proposal.md
│   │       ├── spec.md
│   │       ├── tasks.md
│   │       ├── contracts.cs
│   │       ├── decisions.md
│   │       └── recap.md
│   └── archive/                   # Features CONCLUÍDAS
├── .claude/
│   ├── commands/                  # Slash commands
│   │   ├── morph-proposal.md
│   │   ├── morph-apply.md
│   │   ├── morph-status.md
│   │   ├── morph-archive.md
│   │   ├── morph-infra.md         # (new)
│   │   └── morph-costs.md         # (new)
│   └── skills/                    # Agent skills (new)
│       ├── specialists/
│       ├── integrations/
│       ├── stacks/
│       └── infra/
└── infra/                         # IaC templates (new)
    ├── main.bicep
    └── modules/
```

---

## AGENTES

### Core Agents (Sempre Ativos)

| Agente | Responsabilidades |
|--------|-------------------|
| **Standards Architect** | Padrões em `.morph/standards/`, nomenclatura, revisão |
| **Azure Architect** | Infra Azure, Bicep IaC, Container Apps, SQL |
| **Cost Guardian** | Validar custos, alertar recursos caros, bloquear não aprovados |

### Stack Agents (Por Stack)

| Agente | Stack | Keywords |
|--------|-------|----------|
| **Blazor Builder** | .NET + Blazor | blazor, razor, server-side |
| **NextJS Expert** | .NET + Next.js | nextjs, react, api, frontend |
| **Shopify Expert** | Shopify | shopify, hydrogen, liquid |

### Specialist Agents (Sob Demanda)

| Agente | Keywords de Ativação |
|--------|---------------------|
| **EF Modeler** | entity, database, migration, ef core |
| **MS Agent Expert** | agent, ai, semantic kernel, llm |
| **Hangfire Orchestrator** | scheduled, job, background, cron |
| **UI/UX Designer** | wizard, dashboard, complex form, drag-drop |
| **PO/PM Advisor** | unclear, requirements, priority, ROI |

### Integration Agents (Sob Demanda)

| Agente | Keywords | Docs |
|--------|----------|------|
| **Asaas Financial** | asaas, payment, pix, boleto | [API](https://docs.asaas.com/) |
| **Clerk Auth** | clerk, auth, login, signup | [SDK](https://clerk.com/) |
| **Azure Identity** | identity, entra, microsoft auth | [Docs](https://learn.microsoft.com/entra/) |

### Infra Agents (Sob Demanda)

| Agente | Keywords | Docs |
|--------|----------|------|
| **Bicep Architect** | bicep, iac, infra, provision | [Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/) |
| **DevOps Engineer** | pipeline, ci/cd, deploy, release | [Pipelines](https://learn.microsoft.com/azure/devops/pipelines/) |
| **Container Specialist** | docker, container, containerize | [Container Apps](https://learn.microsoft.com/azure/container-apps/) |

---

## LIMITES DE CUSTO

| Nível | Limite | Requisito |
|-------|--------|-----------|
| Sem aprovação | Free tier apenas | Nenhum |
| Com aprovação | Até $10/mês | Confirmação |
| Acima de $10 | Justificativa detalhada | ADR |

---

## INFRASTRUCTURE AS CODE

### Princípio: Zero Portal

> NUNCA criar recursos Azure manualmente. Tudo via Bicep.

### Estrutura IaC

```
infra/
├── main.bicep                # Entry point
├── parameters.dev.json       # Params dev
├── parameters.prod.json      # Params prod
└── modules/
    ├── container-app.bicep
    ├── sql-database.bicep
    ├── storage.bicep
    ├── key-vault.bicep
    └── app-insights.bicep
```

### Quando usar SDK .NET vs Bicep

| Recurso | Abordagem |
|---------|-----------|
| Infra estática (SQL, Storage, Container Apps) | Bicep |
| Recursos dinâmicos (Fabric, Azure AI) | SDK .NET |
| CI/CD | YAML + Bicep |

---

## TEMPLATES E PLACEHOLDERS

### Princípio: Templates Auto-Populáveis

> SEMPRE use o CLI `bin/render-template.js` para renderizar templates. NUNCA preencha placeholders manualmente.

### Placeholders Padrão

Todos os templates usam o formato `{{PLACEHOLDER}}` (duplo-chave). Os placeholders são substituídos automaticamente pelo CLI.

| Placeholder | Descrição | Exemplo Input | Exemplo Output |
|-------------|-----------|---------------|----------------|
| `{{FEATURE_NAME}}` | Nome kebab-case da feature | `"scheduled-reports"` | `scheduled-reports` |
| `{{FEATURE_NAME_PASCAL}}` | PascalCase (para C#) | `"scheduled-reports"` | `ScheduledReports` |
| `{{FEATURE_NAME_CAMEL}}` | camelCase (para JS/TS) | `"scheduled-reports"` | `scheduledReports` |
| `{{FEATURE_NAME_TITLE}}` | Title Case (para títulos) | `"scheduled-reports"` | `Scheduled Reports` |
| `{{FEATURE_NAME_UPPER_SNAKE}}` | UPPER_SNAKE_CASE | `"scheduled-reports"` | `SCHEDULED_REPORTS` |
| `{{FEATURE_NAME_LOWER_SNAKE}}` | lower_snake_case | `"scheduled-reports"` | `scheduled_reports` |
| `{{STACK}}` | Stack do projeto | (auto) | `Blazor`, `Next.js` |
| `{{DATE}}` | Data atual (YYYY-MM-DD) | (auto) | `2025-12-08` |
| `{{YEAR}}` | Ano atual | (auto) | `2025` |
| `{{AUTHOR}}` | Autor (de config.json) | (auto) | `MORPH-SPEC` |
| `{{PROJECT_NAME}}` | Nome do projeto | (auto) | `MyProject` |
| `{{NAMESPACE}}` | Namespace C# | (auto) | `MyProject` |

**Transformações Automáticas:**
- Forneça apenas `FEATURE_NAME` em kebab-case (ex: `"my-feature"`)
- CLI gera automaticamente todas as variações de case
- Valores auto-populados (DATE, AUTHOR, etc.) vêm de `config.json`

### CLI de Renderização

#### Uso Básico

```bash
node bin/render-template.js <template-path> <output-path> <variables-json>
```

#### Exemplos

**Renderizar proposal.md:**
```bash
node bin/render-template.js \
  content/.morph/templates/proposal.md \
  .morph/project/outputs/scheduled-reports/proposal.md \
  '{"FEATURE_NAME":"scheduled-reports"}'
```

**Renderizar contracts.cs com namespace customizado:**
```bash
node bin/render-template.js \
  content/.morph/templates/contracts.cs \
  src/Application/Features/ScheduledReports/Contracts.cs \
  '{"FEATURE_NAME":"scheduled-report","NAMESPACE":"MyProject"}'
```

**Modo verbose (mostra placeholders substituídos):**
```bash
node bin/render-template.js \
  content/.morph/templates/spec.md \
  .morph/project/outputs/my-feature/spec.md \
  '{"FEATURE_NAME":"my-feature","STACK":"Blazor"}' \
  --verbose
```

**Dry-run (preview sem escrever arquivo):**
```bash
node bin/render-template.js \
  content/.morph/templates/ui-mockups.md \
  /dev/null \
  '{"FEATURE_NAME":"user-dashboard"}' \
  --dry-run
```

#### Flags Disponíveis

| Flag | Descrição |
|------|-----------|
| `--verbose`, `-v` | Mostra placeholders substituídos e não-substituídos |
| `--dry-run`, `-d` | Preview sem escrever arquivo |
| `--help`, `-h` | Mostra ajuda completa |

### Templates Disponíveis

**Outputs MORPH:**
- `.morph/templates/proposal.md` - FASE 0 (Proposal)
- `.morph/templates/ui-design-system.md` - FASE 1.5 (Design System)
- `.morph/templates/ui-mockups.md` - FASE 1.5 (Wireframes)
- `.morph/templates/ui-components.md` - FASE 1.5 (Component Specs)
- `.morph/templates/ui-flows.md` - FASE 1.5 (User Flows)
- `.morph/templates/spec.md` - FASE 2 (Technical Spec)
- `.morph/templates/contracts.cs` - FASE 2 (Interfaces/DTOs)
- `.morph/templates/decisions.md` - FASE 2 (ADRs)
- `.morph/templates/tasks.md` - FASE 4 (Task Breakdown)
- `.morph/templates/recap.md` - FASE 5 (Recap)

**Templates de Código:**
- `.morph/templates/service.cs` - Service implementation
- `.morph/templates/repository.cs` - Repository implementation
- `.morph/templates/agent.cs` - AI Agent (Microsoft Agent Framework)
- `.morph/templates/job.cs` - Hangfire background job
- `.morph/templates/test.cs` - Unit test template

### Integração com Slash Commands

Os slash commands **devem usar o CLI de renderização** para gerar outputs:

```markdown
# Em morph-proposal.md

node bin/render-template.js \
  content/.morph/templates/proposal.md \
  .morph/project/outputs/${FEATURE_NAME}/proposal.md \
  "{\"FEATURE_NAME\":\"${FEATURE_NAME}\"}"
```

**Benefícios:**
- ✅ **Consistência:** Todos os outputs seguem o mesmo formato
- ✅ **Economia de tokens:** Claude não precisa preencher manualmente
- ✅ **Zero erros:** Transformações de case são 100% corretas
- ✅ **Rapidez:** CLI processa em <100ms

---

## COMANDOS (Slash Commands)

| Comando | Ação |
|---------|------|
| `/morph-proposal {feature}` | Criar nova proposta |
| `/morph-apply {feature}` | Implementar feature aprovada |
| `/morph-status` | Mostrar status do projeto |
| `/morph-archive {feature}` | Arquivar feature concluída |
| `/morph-infra {action}` | Gerenciar infraestrutura (new) |
| `/morph-costs` | Estimar e reportar custos (new) |

---

## REFERÊNCIAS

Consulte sempre:
- `.morph/project.md` - Contexto do projeto
- `.morph/standards/coding.md` - Padrões de código
- `.morph/standards/architecture.md` - Padrões de arquitetura
- `.morph/standards/azure.md` - Padrões Azure e IaC
- `.morph/templates/` - Templates para outputs
- `.morph/config/agents.json` - Definição dos agentes

---

## QUICK START

```
1. Usuário: "Quero implementar relatórios agendados"

2. Claude: /morph-proposal scheduled-reports
   → Carrega contexto
   → Ativa agentes: Hangfire Orchestrator, Blazor Builder
   → Cria proposta

3. Usuário: "Aprovado"

4. Claude: Expande spec, contracts, decisions
   → Aguarda aprovação do design

5. Usuário: "Aprovado"

6. Claude: Quebra em tasks detalhadas
   → Aguarda aprovação do breakdown

7. Usuário: "Aprovado"

8. Claude: /morph-apply scheduled-reports
   → Implementa task por task
   → Checkpoints a cada 3 tasks

9. Usuário: "Feature concluída"

10. Claude: /morph-archive scheduled-reports
    → Move para archive
    → Extrai specs
```

---

*MORPH-SPEC by Polymorphism Tech © 2024-2025*
