@polymorphism-tech/morph-spec 4.3.3 → 4.3.4

package/framework/workflows/docs/STORY-DRIVEN-DEVELOPMENT.md

@@ -0,0 +1,392 @@
+# Story-Driven Development - Guia do Usuário
+
+> **O que você faz quando implementa uma feature usando MORPH-SPEC**
+
+---
+
+## 📋 Você Está Aqui
+
+Você acabou de terminar as fases 0-4 do MORPH:
+- ✅ Criou `spec.md` (especificação técnica)
+- ✅ Criou `contracts.cs` (interfaces/DTOs)
+- ✅ Criou `tasks.json` (lista de tasks)
+- ✅ Aprovou tudo
+
+**Agora você vai implementar. Este guia mostra como.**
+
+---
+
+## 🚀 Passo a Passo Completo
+
+### Cenário: Feature "scheduled-reports" com 10 tasks
+
+```bash
+# ============================================================================
+# ETAPA 1: PREPARAÇÃO (1x por feature)
+# ============================================================================
+
+# 1.1 - Dividir spec.md em partes menores (opcional, mas recomendado)
+morph-spec story shard scheduled-reports
+
+# Isso cria:
+# .morph/features/scheduled-reports/spec/
+# ├── index.md
+# ├── entity-design.md
+# ├── service-layer.md
+# └── ui-components.md
+
+# 1.2 - Criar primeira story
+morph-spec story create scheduled-reports SR-001 \
+  --title "Create ScheduledReport entity" \
+  --tasks "Create entity,Configure EF mapping,Create migration,Write tests"
+
+# Isso cria:
+# .morph/features/scheduled-reports/stories/SR-001.md
+# (arquivo com TODO o contexto que você precisa)
+
+# 1.3 - Criar demais stories
+morph-spec story create scheduled-reports SR-002 \
+  --title "Implement ReportService" \
+  --tasks "Create interface,Implement service,Add DI,Write tests"
+
+morph-spec story create scheduled-reports SR-003 \
+  --title "Create report UI component" \
+  --tasks "Create razor component,Add to router,Style with Fluent UI"
+
+# ... criar SR-004, SR-005, etc.
+
+# 1.4 - Ver todas as stories criadas
+morph-spec story status scheduled-reports show
+
+# Output:
+# 📊 Sprint Status: scheduled-reports
+# Progress: 0% (0/10 stories done)
+# Stories:
+#   ✅ SR-001: Create ScheduledReport entity (ready)
+#   ✅ SR-002: Implement ReportService (ready)
+#   ✅ SR-003: Create report UI component (ready)
+#   ...
+
+
+# ============================================================================
+# ETAPA 2: IMPLEMENTAR STORY SR-001 (repetir para cada story)
+# ============================================================================
+
+# 2.1 - Marcar que você vai começar a trabalhar nela
+morph-spec story status scheduled-reports start SR-001
+
+# 2.2 - Abrir a story
+cat .morph/features/scheduled-reports/stories/SR-001.md
+
+# Você vai ver:
+# - Context (resumo do que fazer)
+# - Dev Notes (dicas automáticas tipo "use Primary Constructor")
+# - Tasks (lista de tarefas)
+# - Acceptance Criteria (como validar se tá certo)
+
+# 2.3 - Ler SÓ a parte relevante do spec (não o spec inteiro)
+cat .morph/features/scheduled-reports/spec/entity-design.md
+
+# 2.4 - Implementar o código
+# (você vai escrever o código da entity, testes, etc.)
+
+# 2.5 - Editar a story para adicionar suas notas
+nano .morph/features/scheduled-reports/stories/SR-001.md
+
+# Procurar a seção "### Dev Notes (Added by Dev Agent)"
+# Adicionar algo tipo:
+### Dev Notes (Added by Dev Agent)
+```
+✅ Implementado ScheduledReport.cs (linha 12)
+✅ EF mapping em ReportDbContext.cs (linha 45)
+✅ Migration: 20251209_AddScheduledReports.cs
+✅ Testes: ScheduledReportTests.cs (12 tests)
+⚠️  RecurrencePattern usa regex complexo
+```
+
+# 2.6 - Marcar que terminou e está pronto para revisar
+morph-spec story status scheduled-reports qa SR-001
+
+# 2.7 - Commitar código
+git add .
+git commit -m "feat(SR-001): create ScheduledReport entity"
+
+
+# ============================================================================
+# ETAPA 3: REVISAR STORY SR-001 (QA)
+# ============================================================================
+
+# 3.1 - Ver status
+morph-spec story status scheduled-reports show
+
+# Output:
+# 👀 SR-001: Create ScheduledReport entity (ready_for_qa)
+
+# 3.2 - Abrir a story (agora com as notas do Dev)
+cat .morph/features/scheduled-reports/stories/SR-001.md
+
+# Você vai ver as Dev Notes que foram adicionadas:
+# "✅ Implementado ScheduledReport.cs (linha 12)"
+# "⚠️ RecurrencePattern usa regex complexo"
+
+# 3.3 - Revisar o código
+cat src/Domain/Entities/ScheduledReport.cs
+cat tests/Unit/ScheduledReportTests.cs
+
+# 3.4 - Se precisar refatorar, refatore
+
+# 3.5 - Editar a story para adicionar notas de revisão
+nano .morph/features/scheduled-reports/stories/SR-001.md
+
+# Procurar a seção "### QA Notes (Added by QA Agent)"
+# Adicionar algo tipo:
+### QA Notes (Added by QA Agent)
+```
+✅ Código OK, segue padrões
+✅ Refatorei ValidateRecurrence() (linha 89)
+✅ Adicionei 3 testes de edge cases
+✅ Todos os acceptance criteria validados
+```
+
+# 3.6 - Marcar como concluída
+morph-spec story status scheduled-reports done SR-001
+
+# Output:
+# ✅ Story SR-001 marked as DONE
+# 📋 Next Story: SR-002
+
+# 3.7 - Commitar mudanças (se fez refactoring)
+git add .
+git commit -m "refactor(SR-001): extract ValidateRecurrence method"
+
+
+# ============================================================================
+# ETAPA 4: PRÓXIMA STORY (SR-002)
+# ============================================================================
+
+# Repetir ETAPA 2 e 3 para SR-002:
+morph-spec story status scheduled-reports start SR-002
+cat .morph/features/scheduled-reports/stories/SR-002.md
+cat .morph/features/scheduled-reports/spec/service-layer.md
+# ... implementar ...
+# ... adicionar Dev Notes ...
+morph-spec story status scheduled-reports qa SR-002
+# ... revisar ...
+# ... adicionar QA Notes ...
+morph-spec story status scheduled-reports done SR-002
+
+# Repetir para SR-003, SR-004, ..., SR-010
+
+
+# ============================================================================
+# ETAPA 5: FINALIZAÇÃO
+# ============================================================================
+
+# Ver progresso geral
+morph-spec story status scheduled-reports show
+
+# Output:
+# 📊 Sprint Status: scheduled-reports
+# Progress: 100% (10/10 stories done)
+# 🎉 All stories completed!
+
+# Pronto! Feature implementada.
+```
+
+---
+
+## 📝 Comandos que Você Usa
+
+### Criar stories (início da feature)
+```bash
+morph-spec story shard <feature-name>
+morph-spec story create <feature-name> <story-id> --title "..." --tasks "..."
+```
+
+### Ver status
+```bash
+morph-spec story status <feature-name> show
+```
+
+### Marcar que vai começar
+```bash
+morph-spec story status <feature-name> start <story-id>
+```
+
+### Marcar que terminou (vai para QA)
+```bash
+morph-spec story status <feature-name> qa <story-id>
+```
+
+### Marcar como concluída
+```bash
+morph-spec story status <feature-name> done <story-id>
+```
+
+### Ver próxima story
+```bash
+morph-spec story status <feature-name> next
+```
+
+---
+
+## 🔄 Seu Dia a Dia
+
+### Segunda-feira: Criar as stories
+```bash
+morph-spec story shard my-feature
+morph-spec story create my-feature MF-001 --title "..." --tasks "..."
+morph-spec story create my-feature MF-002 --title "..." --tasks "..."
+morph-spec story create my-feature MF-003 --title "..." --tasks "..."
+```
+
+### Terça-feira: Implementar MF-001
+```bash
+morph-spec story status my-feature start MF-001
+cat .morph/features/my-feature/stories/MF-001.md
+cat .morph/features/my-feature/spec/entity-design.md
+# [implementar código]
+# [adicionar Dev Notes na story]
+morph-spec story status my-feature qa MF-001
+git commit ...
+```
+
+### Terça à tarde: Revisar MF-001
+```bash
+cat .morph/features/my-feature/stories/MF-001.md  # ver Dev Notes
+# [revisar código]
+# [adicionar QA Notes na story]
+morph-spec story status my-feature done MF-001
+git commit ...
+```
+
+### Quarta-feira: Implementar MF-002
+```bash
+morph-spec story status my-feature start MF-002
+# ... repetir workflow
+```
+
+---
+
+## ❓ Perguntas Comuns
+
+### "Preciso shardar o spec?"
+**Não é obrigatório.** Só recomendado se seu `spec.md` for grande (5+ seções).
+
+Se for pequeno, pule o `shard-spec.js` e vá direto para `create-story.js`.
+
+---
+
+### "Quantas tasks por story?"
+**4-8 tasks** é ideal. Se tiver mais, quebre em sub-stories.
+
+Exemplo:
+- ❌ Ruim: Story com 20 tasks (muito grande)
+- ✅ Bom: Story com 5 tasks (1 dia de trabalho)
+
+---
+
+### "O que são Dev Notes e QA Notes?"
+**Dev Notes:** Você (Dev) escreve o que implementou, para o QA saber.
+
+**QA Notes:** Você (QA) escreve o que revisou/refatorou.
+
+**Exemplo:**
+```markdown
+### Dev Notes (Added by Dev Agent)
+```
+✅ Implementei X.cs na pasta Domain/
+⚠️  Cuidado: usa regex complexo na linha 67
+```
+
+### QA Notes (Added by QA Agent)
+```
+✅ Revisei e está OK
+✅ Refatorei método ValidateX() para ficar mais claro
+```
+```
+
+---
+
+### "Onde adiciono Dev/QA Notes?"
+**No arquivo da story.**
+
+1. Abra: `.morph/features/my-feature/stories/MF-001.md`
+2. Procure a seção `### Dev Notes (Added by Dev Agent)`
+3. Substitua `[VOCÊ VAI PREENCHER AQUI APÓS IMPLEMENTAR]` pelas suas notas
+4. Salve
+
+---
+
+### "E se eu esquecer de adicionar Dev Notes?"
+Sem problema. Edite a story manualmente:
+
+```bash
+nano .morph/features/my-feature/stories/MF-001.md
+# Adicione as notas na seção correta
+# Salve
+```
+
+---
+
+### "Posso implementar várias stories na mesma sessão?"
+**Não recomendado.**
+
+Cada story = nova sessão do Claude (se usar Claude Code).
+
+Por quê? Evita confusão e economiza tokens.
+
+---
+
+## ✅ Checklist Rápido
+
+**No início da feature:**
+- [ ] Roda `shard-spec.js` (opcional)
+- [ ] Roda `create-story.js` para cada story
+- [ ] Roda `show` para ver todas criadas
+
+**Para cada story:**
+- [ ] `start` → Marcar que vai começar
+- [ ] Ler story file (`.morph/features/.../stories/XX.md`)
+- [ ] Ler spec shard (`.morph/features/.../spec/xxx.md`)
+- [ ] Implementar código
+- [ ] Adicionar Dev Notes na story
+- [ ] `qa` → Marcar que terminou
+- [ ] Commit código
+- [ ] Revisar código
+- [ ] Adicionar QA Notes na story
+- [ ] `done` → Marcar como concluída
+- [ ] Commit mudanças
+
+**No final:**
+- [ ] `show` → Ver que 100% completo
+- [ ] Todas stories têm Dev Notes e QA Notes preenchidas
+
+---
+
+## 📚 Referência Rápida
+
+```bash
+# Ver ajuda de qualquer comando
+morph-spec story --help
+morph-spec story shard --help
+morph-spec story create --help
+morph-spec story status --help
+
+# Estrutura de pastas (após criar stories)
+.morph/features/my-feature/
+├── spec/               # Spec dividido em partes
+│   ├── index.md
+│   ├── entity-design.md
+│   └── service-layer.md
+├── stories/            # Stories auto-contidas
+│   ├── MF-001.md
+│   ├── MF-002.md
+│   └── MF-003.md
+└── sprint-status.yaml  # Progresso automático
+```
+
+---
+
+*MORPH-SPEC Framework - Guia do Usuário*
+*Use este guia como referência rápida durante o desenvolvimento*

package/framework/workflows/docs/design-impl.md

@@ -0,0 +1,37 @@
+# Workflow: DESIGN IMPLEMENTATION (Protótipo → Código)
+
+> **Layer:** 1 | **Load:** on-keyword | **Keywords:** prototipo, prototype, figma, html para, converter design, replicar, from design
+
+## Critérios
+
+- Protótipo HTML existente (pasta com arquivos .html) ou mockups/screenshots
+- Conversão de design visual para código Blazor funcional
+
+## Fases
+
+### 1. ANÁLISE DO PROTÓTIPO
+- Ler todos os arquivos HTML do protótipo
+- Extrair padrões: cores, fontes, espaçamentos, componentes
+- Mapear HTML classes → CSS classes do Design System
+- **PAUSA:** Confirmar mapeamento
+
+### 2. TASKS (lista de telas)
+- Gerar lista de telas para implementar com ordem de dependências
+- **PAUSA:** Aprovar lista
+
+### 3. IMPLEMENT (por tela)
+- Ler HTML do protótipo + arquivo .razor atual (se existir)
+- Reescrever .razor usando Fluent UI/MudBlazor
+- Adicionar CSS ao design-system.css
+- Build para validar + `morph-spec validate-css`
+
+## Outputs
+recap.md, código .razor implementado, CSS atualizado
+
+## Fases Puladas
+Proposal, Design técnico, Clarify, Sync
+
+## Exemplos
+- "Implementar telas baseado no protótipo em /prototipo/"
+- "Converter HTML do Figma para Blazor"
+- "Replicar design do mockup"