# 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/project/outputs/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/project/outputs/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/project/outputs/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/project/outputs/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/project/outputs/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/project/outputs/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/project/outputs/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/project/outputs/scheduled-reports/stories/SR-002.md
cat .morph/project/outputs/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/project/outputs/my-feature/stories/MF-001.md
cat .morph/project/outputs/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/project/outputs/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/project/outputs/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/project/outputs/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/project/outputs/.../stories/XX.md`)
- [ ] Ler spec shard (`.morph/project/outputs/.../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/project/outputs/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*
