@polymorphism-tech/morph-spec 4.9.0 → 4.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (124) hide show
  1. package/README.md +2 -2
  2. package/bin/morph-spec.js +30 -0
  3. package/bin/task-manager.js +34 -22
  4. package/claude-plugin.json +1 -1
  5. package/docs/CHEATSHEET.md +1 -1
  6. package/docs/QUICKSTART.md +1 -1
  7. package/framework/CLAUDE.md +99 -98
  8. package/framework/agents.json +37 -7
  9. package/framework/commands/commit.md +166 -0
  10. package/framework/commands/morph-apply.md +13 -2
  11. package/framework/commands/morph-archive.md +8 -2
  12. package/framework/commands/morph-infra.md +6 -0
  13. package/framework/commands/morph-preflight.md +6 -0
  14. package/framework/commands/morph-proposal.md +56 -7
  15. package/framework/commands/morph-status.md +6 -0
  16. package/framework/commands/morph-troubleshoot.md +6 -0
  17. package/framework/hooks/claude-code/notification/approval-reminder.js +3 -2
  18. package/framework/hooks/claude-code/post-tool-use/dispatch.js +154 -31
  19. package/framework/hooks/claude-code/post-tool-use/skill-reminder.js +7 -84
  20. package/framework/hooks/claude-code/post-tool-use/validator-feedback.js +8 -17
  21. package/framework/hooks/claude-code/pre-compact/save-morph-context.js +16 -3
  22. package/framework/hooks/claude-code/pre-tool-use/enforce-phase-writes.js +4 -3
  23. package/framework/hooks/claude-code/pre-tool-use/protect-spec-files.js +3 -2
  24. package/framework/hooks/claude-code/pre-tool-use/task-tracking-guard.js +60 -0
  25. package/framework/hooks/claude-code/session-start/inject-morph-context.js +55 -2
  26. package/framework/hooks/claude-code/session-start/post-compact-restore.js +41 -0
  27. package/framework/hooks/claude-code/stop/validate-completion.js +2 -15
  28. package/framework/hooks/claude-code/user-prompt/enrich-prompt.js +23 -5
  29. package/framework/hooks/shared/compact-restore.js +100 -0
  30. package/framework/hooks/shared/dispatch-helpers.js +116 -0
  31. package/framework/hooks/shared/phase-utils.js +9 -5
  32. package/framework/hooks/shared/state-reader.js +27 -3
  33. package/framework/phases.json +30 -7
  34. package/framework/rules/morph-workflow.md +88 -86
  35. package/framework/skills/level-0-meta/mcp-registry.json +86 -51
  36. package/framework/skills/level-0-meta/{brainstorming → morph-brainstorming}/SKILL.md +13 -16
  37. package/framework/skills/level-0-meta/{code-review → morph-code-review}/SKILL.md +1 -1
  38. package/framework/skills/level-0-meta/{code-review-nextjs → morph-code-review-nextjs}/SKILL.md +2 -2
  39. package/framework/skills/level-0-meta/{frontend-review → morph-frontend-review}/SKILL.md +5 -5
  40. package/framework/skills/level-0-meta/morph-init/SKILL.md +72 -7
  41. package/framework/skills/level-0-meta/{post-implementation → morph-post-implementation}/SKILL.md +9 -9
  42. package/framework/skills/level-0-meta/morph-replicate/SKILL.md +1 -1
  43. package/framework/skills/level-0-meta/{terminal-title → morph-terminal-title}/SKILL.md +1 -1
  44. package/framework/skills/level-0-meta/{tool-usage-guide → morph-tool-usage-guide}/SKILL.md +2 -3
  45. package/framework/skills/level-0-meta/{tool-usage-guide → morph-tool-usage-guide}/references/tools-per-phase.md +1 -2
  46. package/framework/skills/level-0-meta/{verification-before-completion → morph-verification-before-completion}/SKILL.md +1 -1
  47. package/framework/skills/level-0-meta/{verification-before-completion → morph-verification-before-completion}/scripts/check-phase-outputs.mjs +2 -2
  48. package/framework/skills/level-1-workflows/morph-phase-clarify/SKILL.md +238 -0
  49. package/framework/skills/level-1-workflows/{phase-codebase-analysis → morph-phase-codebase-analysis}/SKILL.md +251 -251
  50. package/framework/skills/level-1-workflows/morph-phase-design/SKILL.md +507 -0
  51. package/framework/skills/level-1-workflows/{phase-implement → morph-phase-implement}/SKILL.md +590 -491
  52. package/framework/skills/level-1-workflows/morph-phase-implement/prompts/code-quality-reviewer-prompt.md +50 -0
  53. package/framework/skills/level-1-workflows/morph-phase-implement/prompts/implementer-prompt.md +45 -0
  54. package/framework/skills/level-1-workflows/morph-phase-implement/prompts/spec-reviewer-prompt.md +47 -0
  55. package/framework/skills/level-1-workflows/morph-phase-plan/SKILL.md +254 -0
  56. package/framework/skills/level-1-workflows/{phase-setup → morph-phase-setup}/SKILL.md +237 -194
  57. package/framework/skills/level-1-workflows/{phase-tasks → morph-phase-tasks}/SKILL.md +307 -270
  58. package/framework/skills/level-1-workflows/{phase-tasks → morph-phase-tasks}/scripts/validate-tasks.mjs +3 -3
  59. package/framework/skills/level-1-workflows/{phase-uiux → morph-phase-uiux}/SKILL.md +320 -285
  60. package/framework/skills/level-1-workflows/morph-scope-escalation/SKILL.md +97 -0
  61. package/framework/standards/integration/mcp/mcp-tools.md +25 -7
  62. package/framework/templates/docs/onboarding.md +2 -2
  63. package/package.json +1 -2
  64. package/src/commands/agents/dispatch-agents.js +50 -3
  65. package/src/commands/mcp/mcp-setup.js +39 -2
  66. package/src/commands/phase/phase-reset.js +74 -0
  67. package/src/commands/project/doctor.js +19 -5
  68. package/src/commands/scope/escalate.js +215 -0
  69. package/src/commands/state/advance-phase.js +27 -53
  70. package/src/commands/state/state.js +1 -1
  71. package/src/commands/task/expand.js +100 -0
  72. package/src/core/paths/output-schema.js +4 -3
  73. package/src/core/state/phase-state-machine.js +7 -4
  74. package/src/core/state/state-manager.js +4 -3
  75. package/src/lib/detectors/claude-config-detector.js +93 -347
  76. package/src/lib/detectors/design-system-detector.js +189 -189
  77. package/src/lib/detectors/index.js +155 -57
  78. package/src/lib/generators/context-generator.js +2 -2
  79. package/src/lib/installers/mcp-installer.js +37 -5
  80. package/src/lib/phase-chain/phase-validator.js +22 -16
  81. package/src/lib/scope/impact-analyzer.js +106 -0
  82. package/src/lib/tasks/task-parser.js +1 -1
  83. package/src/lib/validators/shared/emit-validator-dispatch.js +64 -0
  84. package/src/scripts/setup-infra.js +15 -0
  85. package/src/utils/agents-installer.js +32 -12
  86. package/src/utils/file-copier.js +0 -1
  87. package/src/utils/hooks-installer.js +15 -1
  88. package/framework/skills/level-1-workflows/phase-clarify/SKILL.md +0 -216
  89. package/framework/skills/level-1-workflows/phase-design/SKILL.md +0 -383
  90. package/src/commands/project/index.js +0 -8
  91. package/src/core/index.js +0 -10
  92. package/src/core/state/index.js +0 -8
  93. package/src/core/templates/index.js +0 -9
  94. package/src/core/templates/template-data-sources.js +0 -325
  95. package/src/core/workflows/index.js +0 -7
  96. package/src/lib/detectors/config-detector.js +0 -223
  97. package/src/lib/detectors/standards-generator.js +0 -335
  98. package/src/lib/detectors/structure-detector.js +0 -275
  99. package/src/lib/monitor/agent-resolver.js +0 -144
  100. package/src/lib/monitor/renderer.js +0 -230
  101. package/src/lib/orchestration/index.js +0 -7
  102. package/src/lib/orchestration/team-orchestrator.js +0 -404
  103. package/src/sanitizer/context-sanitizer.js +0 -221
  104. package/src/sanitizer/patterns.js +0 -163
  105. package/src/writer/file-writer.js +0 -86
  106. /package/framework/skills/level-0-meta/{brainstorming → morph-brainstorming}/references/proposal-example.md +0 -0
  107. /package/framework/skills/level-0-meta/{code-review → morph-code-review}/references/review-example.md +0 -0
  108. /package/framework/skills/level-0-meta/{code-review → morph-code-review}/references/review-guidelines.md +0 -0
  109. /package/framework/skills/level-0-meta/{code-review → morph-code-review}/scripts/scan-csharp.mjs +0 -0
  110. /package/framework/skills/level-0-meta/{code-review-nextjs → morph-code-review-nextjs}/references/review-example-nextjs.md +0 -0
  111. /package/framework/skills/level-0-meta/{code-review-nextjs → morph-code-review-nextjs}/scripts/scan-nextjs.mjs +0 -0
  112. /package/framework/skills/level-0-meta/{frontend-review → morph-frontend-review}/scripts/scan-accessibility.mjs +0 -0
  113. /package/framework/skills/level-0-meta/{post-implementation → morph-post-implementation}/scripts/detect-dev-server.mjs +0 -0
  114. /package/framework/skills/level-0-meta/{post-implementation → morph-post-implementation}/scripts/detect-stack.mjs +0 -0
  115. /package/framework/skills/level-0-meta/{simulation-checklist → morph-simulation-checklist}/SKILL.md +0 -0
  116. /package/framework/skills/level-0-meta/{terminal-title → morph-terminal-title}/scripts/set_title.sh +0 -0
  117. /package/framework/skills/level-1-workflows/{phase-clarify → morph-phase-clarify}/references/clarifications-example.md +0 -0
  118. /package/framework/skills/level-1-workflows/{phase-design → morph-phase-design}/references/architecture-analysis-guide.md +0 -0
  119. /package/framework/skills/level-1-workflows/{phase-design → morph-phase-design}/references/spec-authoring-guide.md +0 -0
  120. /package/framework/skills/level-1-workflows/{phase-design → morph-phase-design}/references/spec-example.md +0 -0
  121. /package/framework/skills/level-1-workflows/{phase-implement → morph-phase-implement}/references/recap-example.md +0 -0
  122. /package/framework/skills/level-1-workflows/{phase-implement → morph-phase-implement}/references/vsa-implementation-guide.md +0 -0
  123. /package/framework/skills/level-1-workflows/{phase-tasks → morph-phase-tasks}/references/task-planning-patterns.md +0 -0
  124. /package/framework/skills/level-1-workflows/{phase-tasks → morph-phase-tasks}/references/tasks-example.md +0 -0
@@ -1,216 +0,0 @@
1
- ---
2
- name: morph:phase-clarify
3
- description: MORPH-SPEC Phase 3 (Clarify). Reviews spec.md for ambiguities, generates 3-7 targeted clarification questions, waits for user answers, then updates spec with edge cases and clarification sections. Use after design approval to eliminate spec ambiguities before task breakdown begins.
4
- argument-hint: "[feature-name]"
5
- user-invocable: false
6
- allowed-tools: Read, Write, Edit, Bash, Glob, Grep
7
- cliVersion: "4.9.0"
8
- ---
9
-
10
- # MORPH Clarify - FASE 3
11
-
12
- > INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
13
-
14
- Identifique ambiguidades na especificação e faça perguntas de clarificação para garantir que todos os edge cases estão cobertos.
15
-
16
- ## Pré-requisitos
17
-
18
- - [ ] FASE 2 (Design) concluída
19
- - [ ] `spec.md` aprovado pelo usuário
20
- - [ ] `contracts.cs` definidos
21
-
22
- ## Ferramentas Recomendadas
23
-
24
- > **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
25
- > **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
26
- > **Example:** `references/clarifications-example.md` — filled-in clarifications.md showing expected Q&A format.
27
-
28
- | Ação | Ferramenta | Alternativa |
29
- |------|------------|-------------|
30
- | Ler spec.md completo | **Read** spec.md | — |
31
- | Ler contracts.cs | **Read** contracts.cs | — |
32
- | Ler schema-analysis.md | **Read** schema-analysis.md | — |
33
- | Verificar viabilidade de requisito | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
34
- | Verificar issues/limitações conhecidas | **GitHub MCP** `search_issues()` | **Bash** `gh issue list --search "..."` |
35
- | Pesquisar edge cases externos | **WebSearch** | — |
36
- | Verificar comportamento UI existente | **Playwright MCP** `browser_navigate()` + `browser_snapshot()` | **WebFetch** URL |
37
- | Atualizar spec com clarificações | **Edit** spec.md | — |
38
- | Criar clarifications.md | **Bash** `npx morph-spec template render docs/clarifications .morph/features/$ARGUMENTS/2-clarify/clarifications.md` | — |
39
- | Atualizar state | **Bash** `npx morph-spec state mark-output $ARGUMENTS clarifications` | — |
40
-
41
- **MCPs desta fase:** Context7 (validar viabilidade), GitHub (issues conhecidas), Playwright (verificar UI existente).
42
-
43
- **Anti-padrões:**
44
- - ❌ Task agent para ler spec (use Read direto)
45
- - ❌ Reescrever spec do zero (use Edit para atualizar seções)
46
- - ❌ Pular cross-reference com schema-analysis.md (crítico para precisão)
47
-
48
- ---
49
-
50
- ## Workflow
51
-
52
- ### Passo 1: Analisar Spec
53
-
54
- Leia `.morph/features/$ARGUMENTS/1-design/spec.md` em detalhes e identifique:
55
-
56
- #### 1.1. Ambiguidades
57
- - Requisitos vagos ou genéricos
58
- - Termos sem definição clara
59
- - Comportamentos não especificados
60
-
61
- #### 1.2. Edge Cases Não Documentados
62
- - O que acontece se...?
63
- - Como lidar com entradas inválidas?
64
- - Comportamento em caso de erro?
65
- - Estados intermediários (loading, empty)
66
-
67
- #### 1.3. Requisitos Conflitantes
68
- - Duas funcionalidades que parecem incompatíveis
69
- - Prioridades não claras (o que vem primeiro?)
70
-
71
- #### 1.4. Dados Faltantes
72
- - Validações de negócio não especificadas
73
- - Limites e constraints (tamanhos, quantidades)
74
- - Formatos de dados (datas, moedas, etc.)
75
-
76
- ### Passo 2: Gerar Perguntas de Clarificação
77
-
78
- Com base na análise, gere **3-7 perguntas** focadas e específicas:
79
-
80
- **Formato de pergunta:**
81
- ```markdown
82
- ### Q{N}: {Categoria} - {Título}
83
-
84
- **Context:** {Por que esta pergunta é importante}
85
-
86
- **Question:** {Pergunta clara e objetiva}
87
-
88
- **Options (if applicable):**
89
- - A) {Opção 1}
90
- - B) {Opção 2}
91
- - C) {Deixar em aberto/usuário decidir}
92
-
93
- **Impact:** {Como a resposta afeta a implementação}
94
- ```
95
-
96
- ### Passo 3: Categorizar Perguntas
97
-
98
- Organize perguntas por categoria:
99
-
100
- | Categoria | Descrição | Exemplos |
101
- |-----------|-----------|----------|
102
- | **Validação** | Regras de negócio, constraints | Limites de tamanho, formatos aceitos |
103
- | **Comportamento** | O que acontece quando... | Error handling, estados vazios |
104
- | **Prioridade** | O que é must-have vs nice-to-have | MVP vs futuras iterações |
105
- | **Integração** | Como interage com sistemas externos | APIs, webhooks, formato de dados |
106
- | **Performance** | Requisitos de velocidade/volume | Quantos registros? Tempo de resposta? |
107
- | **UX** | Experiência do usuário | Feedback visual, mensagens de erro |
108
-
109
- ### Passo 4: Apresentar Perguntas ao Usuário via AskUserQuestion
110
-
111
- Use o tool `AskUserQuestion` para coletar as respostas — **NUNCA liste perguntas como texto simples**.
112
-
113
- **Regras:**
114
- - `AskUserQuestion` aceita **1-4 perguntas por chamada**
115
- - Se houver 5-7 perguntas, faça **2 chamadas sequenciais** (ex: Q1-Q4 → Q5-Q7)
116
- - Cada pergunta deve ter `header` (≤12 chars), `question` clara e 2-4 `options`
117
- - Se a pergunta for aberta sem opções fixas, defina 2-3 opções representativas (o usuário pode usar "Other" para resposta livre)
118
- - Use `multiSelect: true` quando múltiplas respostas forem igualmente válidas
119
- - Aguarde o retorno do tool antes de prosseguir para qualquer próximo passo
120
-
121
- **Exemplo de estrutura:**
122
- ```json
123
- {
124
- "questions": [
125
- {
126
- "header": "Validação",
127
- "question": "Qual o limite de tamanho para o campo Nome?",
128
- "multiSelect": false,
129
- "options": [
130
- { "label": "100 chars", "description": "Padrão comum para nomes curtos" },
131
- { "label": "255 chars", "description": "Máximo típico de banco de dados" },
132
- { "label": "Sem limite fixo", "description": "Apenas validação no frontend" }
133
- ]
134
- }
135
- ]
136
- }
137
- ```
138
-
139
- **IMPORTANTE:** Não prossiga para o Passo 5 até receber respostas de TODAS as perguntas!
140
-
141
- ### Passo 5: Atualizar `spec.md` com Respostas
142
-
143
- Após receber respostas do usuário, atualize o spec com:
144
-
145
- 1. **Seção de Clarificações** no início do spec:
146
- ```markdown
147
- ## Clarifications (FASE 3)
148
-
149
- ### Q1: {Título}
150
- **Answer:** {Resposta do usuário}
151
- **Date:** {YYYY-MM-DD}
152
- ```
153
-
154
- 2. **Atualizar seções relevantes** com detalhes adicionados
155
-
156
- ### CHECKPOINT: Validar Respostas Completas
157
-
158
- **⏸️ PAUSE - Antes de atualizar spec:**
159
-
160
- - [ ] Todas as perguntas foram respondidas pelo usuário?
161
- - [ ] Nenhuma resposta é ambígua ou contraditória?
162
- - [ ] Respostas são consistentes com `contracts.cs` existente?
163
- - [ ] Respostas são consistentes com `schema-analysis.md`?
164
-
165
- **❌ Se alguma checkbox NÃO estiver marcada:**
166
- → Voltar e pedir esclarecimento adicional ao usuário
167
-
168
- **✅ Se TODAS as checkboxes estiverem marcadas:**
169
- → Prosseguir para atualizar spec.md
170
-
171
- ### Passo 6: Validar Edge Cases
172
-
173
- Documente no spec como lidar com cada edge case identificado:
174
-
175
- ```markdown
176
- ## Edge Cases
177
-
178
- ### EC001: {Nome do Edge Case}
179
- **Scenario:** {Quando acontece}
180
- **Expected Behavior:** {Como o sistema deve reagir}
181
- **Implementation Notes:** {Dicas para implementação}
182
- ```
183
-
184
- ### Passo 7: Atualizar State
185
-
186
- ## Outputs Gerados/Atualizados
187
-
188
- - `.morph/features/$ARGUMENTS/1-design/spec.md` - Atualizado com:
189
- - Seção "Clarifications" com perguntas e respostas
190
- - Edge cases documentados
191
- - Requisitos mais específicos
192
- - `.morph/features/$ARGUMENTS/2-clarify/clarifications.md` - Novo arquivo com Q&A estruturado
193
-
194
- ## Critérios de Avanço
195
-
196
- - [x] Perguntas de clarificação identificadas (3-7)
197
- - [x] Perguntas apresentadas ao usuário
198
- - [x] Respostas do usuário recebidas
199
- - [x] `spec.md` atualizado com clarificações
200
- - [x] Edge cases documentados
201
- - [x] State atualizado
202
- - [x] Nenhuma ambiguidade crítica remanescente
203
-
204
- ---
205
-
206
- ## Integração com Superpowers
207
-
208
- > Disponível quando o plugin `superpowers` está instalado.
209
-
210
- | Skill | Quando Usar | Invocação |
211
- |-------|-------------|-----------|
212
- | `systematic-debugging` | Para investigar ambiguidades técnicas complexas | `Skill(superpowers:systematic-debugging)` |
213
-
214
- ---
215
-
216
- Continuar automaticamente para FASE 4 (Tasks) após clarificações resolvidas.
@@ -1,383 +0,0 @@
1
- ---
2
- name: morph:phase-design
3
- description: MORPH-SPEC Phase 2 (Design). Analyzes codebase/schema, then produces spec.md, contracts.cs (contracts-vsa.cs for VSA or contracts-level{N}.cs for DDD), schema-analysis.md, and decisions.md for the feature. Use after setup phase to create a full technical specification with C# contracts based on the real database schema and architecture decision records.
4
- argument-hint: "[feature-name]"
5
- user-invocable: false
6
- allowed-tools: Read, Write, Edit, Bash, Glob, Grep
7
- cliVersion: "4.9.0"
8
- ---
9
-
10
- # MORPH Design - FASE 2
11
-
12
- > INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
13
-
14
- Expanda a proposta em especificação técnica completa, contracts, decisões arquiteturais e estimativa de custos.
15
-
16
- ## Pré-requisitos
17
-
18
- - [ ] FASE 1 (Setup) concluída
19
- - [ ] FASE 1.5 (UI/UX) concluída OU pulada (se não houver front-end)
20
- - [ ] Proposta aprovada pelo usuário
21
-
22
- ## Ferramentas Recomendadas
23
-
24
- > **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
25
- > **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
26
- > **Example:** `references/spec-example.md` — filled-in spec.md showing expected output quality.
27
-
28
- | Ação | Ferramenta | Alternativa |
29
- |------|------------|-------------|
30
- | Ler proposal + UI specs | **Read** output files | — |
31
- | Obter dispatch config | **Bash** `npx morph-spec dispatch-agents $ARGUMENTS design` | Agentes a disparar + prompts de task |
32
- | **Dispatch domain-architect** (paralelo) | **Agent** `subagent_type=domain-architect` (ou `vsa-architect`) + `prompt=agent.taskPrompt` do dispatch config | Análise de complexidade independente |
33
- | **Dispatch tech leads ativos** (paralelo) | **Agent** `subagent_type=<agent.id>` para cada agente ativo — o `id` do dispatch config é o `name` do subagente nativo em `.claude/agents/` | Análise de domínio independente |
34
- | Obter schema do banco | **Supabase MCP** `list_tables()`, `get_table_schema()` | **Grep** queries + **Read** types |
35
- | Obter relacionamentos de FK | **Supabase MCP** `get_relationships()` | **Grep** JOIN/FK no código |
36
- | Obter políticas RLS | **Supabase MCP** `query()` com pg_policies | **Read** arquivos de políticas |
37
- | Encontrar arquivos de query (fallback) | **Grep** `\.from\(` em `*.ts,*.tsx,*.js,*.cs` | — |
38
- | Encontrar definições de tipo (fallback) | **Glob** `src/**/types/**/*.ts` ou `**/Entities/**/*.cs` | — |
39
- | Ler arquivos de query/tipos (fallback) | **Read** cada arquivo encontrado | — |
40
- | Pesquisar biblioteca para ADR | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
41
- | Buscar padrões no código | **GitHub MCP** `search_code()` | **Grep** padrões no projeto |
42
- | Renderizar template contracts (VSA) | **Bash** `npx morph-spec template render code/dotnet/contracts/contracts-vsa.cs ...` | — |
43
- | Renderizar template contracts (DDD nível detectado) | **Bash** `npx morph-spec template render code/dotnet/contracts/contracts-level{N}.cs ...` onde N = nível detectado no Passo 1.5 | — |
44
- | Renderizar template spec.md | **Bash** `npx morph-spec template render docs/spec ...` | — |
45
- | Renderizar template decisions.md | **Bash** `npx morph-spec template render docs/decisions ...` | — |
46
- | Criar schema-analysis.md | **Write** no diretório de outputs | — |
47
- | Atualizar state | **Bash** `npx morph-spec state mark-output ...` | — |
48
-
49
- **MCPs desta fase:** Supabase (schema analysis — **PRIORITÁRIO**), Context7 (research), GitHub (code search).
50
-
51
- **Anti-padrões:**
52
- - ❌ Adivinhar nomes de campos sem verificar schema (use MCP ou Grep primeiro!)
53
- - ❌ Task agent para ler um único arquivo spec (use Read direto)
54
- - ❌ WebSearch para schema do banco (use Supabase MCP ou análise de código)
55
- - ❌ Escrever contracts-level{N}.cs do zero (use template render)
56
- - ❌ Executar análise de domínio e análise de schema sequencialmente (são independentes — paralelize!)
57
- - ❌ Fazer análise de domínio inline no contexto principal quando 2+ agentes estão ativos (use Task dispatch)
58
-
59
- ---
60
-
61
- ## ✅ PRÉ-VOO OBRIGATÓRIO (antes de gerar qualquer artefato)
62
-
63
- ### 1. Verificar contexto injetado pelo SessionStart
64
-
65
- O hook já injetou o estado atual. Confirme que você leu:
66
- - Feature ativa, fase, status de approvals
67
- - Task progress e pending gates
68
- - Spec snippet (se disponível)
69
-
70
- ### 2. Ler todos os prerequisitos em PARALELO
71
-
72
- ```
73
- # Uma única chamada, não sequencial:
74
- Read: .morph/features/{feature}/0-proposal/proposal.md
75
- + Read: .morph/config/config.json (→ architecture.style)
76
- + Read: .morph/context/README.md (→ project context)
77
- + Read: framework/agents.json (→ activeAgents do feature)
78
- ```
79
-
80
- ### 3. Avaliar escopo → EnterPlanMode se necessário
81
-
82
- Se QUALQUER uma das condições abaixo for verdadeira:
83
- - [ ] Refactor toca ≥5 arquivos existentes de domínio
84
- - [ ] Estimativa de tasks ≥20
85
- - [ ] Mudança de arquitetura (ex: migrar de DDD Level 1 → Level 2)
86
-
87
- → **USE EnterPlanMode** antes de gerar contratos. Explore o codebase, apresente opções, aguarde aprovação.
88
-
89
- ### 4. Dispatch paralelo de subagents para artefatos independentes
90
-
91
- Os 4 artefatos de design são **independentes entre si**. Obtenha o config de dispatch e despache em paralelo:
92
-
93
- ```bash
94
- npx morph-spec dispatch-agents {feature} design --table
95
- ```
96
-
97
- Para cada agente em `config.agents` (excluindo o arquiteto já despachado no Passo 1.5), use o `id` como `subagent_type` no Agent tool:
98
-
99
- ```
100
- # Exemplo com agentes típicos detectados (uma mensagem, múltiplos Agent tool calls):
101
- Agent(subagent_type=dotnet-senior, prompt=<agent.taskPrompt>) # → spec.md + contracts.cs
102
- Agent(subagent_type=nextjs-expert, prompt=<agent.taskPrompt>) # → frontend spec
103
- Agent(subagent_type=standards-architect, prompt=<agent.taskPrompt>) # → decisões + ADRs
104
- ```
105
-
106
- > **Regra de mapeamento:** `agent.id` do dispatch config = `name:` no frontmatter do arquivo em `.claude/agents/` = `subagent_type` do Agent tool. Ex: `id: "nextjs-expert"` → `Agent(subagent_type=nextjs-expert)`.
107
-
108
- **Se `config.shouldDispatch === false`** (1 agente ou nenhum): execute os passos abaixo diretamente, sem dispatch.
109
-
110
- ### 5. Criar tasks de sessão para visibilidade
111
-
112
- ```
113
- TaskCreate: "Gerar spec.md" → activeForm: "Gerando spec.md"
114
- TaskCreate: "Gerar contracts.cs" → activeForm: "Gerando contracts.cs"
115
- TaskCreate: "Gerar decisions.md" → activeForm: "Gerando decisions.md"
116
- TaskCreate: "Avanço de fase" → activeForm: "Avançando fase"
117
- ```
118
-
119
- ---
120
-
121
- ## Workflow
122
-
123
- ### Passo 1: Carregar Contexto, Agentes e Dispatch Config
124
-
125
- **Obtenha feature state e dispatch config:**
126
-
127
- ```bash
128
- npx morph-spec state get $ARGUMENTS
129
- npx morph-spec dispatch-agents $ARGUMENTS design
130
- ```
131
-
132
- O primeiro comando retorna `activeAgents`. O segundo retorna os agentes a disparar e seus prompts de task.
133
-
134
- **Leia outputs existentes em paralelo (Read direto):**
135
- 1. `.morph/features/$ARGUMENTS/0-proposal/proposal.md` - Proposta inicial
136
- 2. `.morph/features/$ARGUMENTS/2-ui/*.md` - UI/UX specs (se existirem)
137
-
138
- **Standards context** (carregue para o contexto principal os standards dos agentes ativos):
139
- - Paths dos standards em `agents.json[activeAgent].standards[]`
140
- - Prioridade: `.morph/context/*.md` > `.morph/framework/standards/` > `framework/standards/`
141
- - Architecture standards → guiam Technical Architecture section
142
- - Coding standards → definem contracts-level{N}.cs patterns
143
-
144
- ### Passo 1.5: Análise de Domínio via Task Dispatch
145
-
146
- **⚠️ OBRIGATÓRIO:** Execute antes de gerar qualquer contrato. Use **Task tool** para isolar esta análise do contexto principal.
147
-
148
- > Para os prompts completos de análise de arquitetura, veja `references/architecture-analysis-guide.md`
149
-
150
- O arquiteto ativo (lido do dispatch config no Passo 1) pode ser `domain-architect` (DDD) ou `vsa-architect` (VSA) — o prompt vem do dispatch config retornado por `dispatch-agents`.
151
-
152
- **Paralelização:** Este Task dispatch pode iniciar SIMULTANEAMENTE com o Passo 2 (schema analysis).
153
-
154
- #### Caminho A: `domain-architect` ativo (DDD)
155
-
156
- Use o `taskPrompt` do dispatch config (enriquecido com o conteúdo da proposta). Chame o Agent tool usando o `id` do dispatch config como `subagent_type`:
157
-
158
- ```
159
- # agent.id do dispatch config = subagent_type do Agent tool
160
- Agent(subagent_type=domain-architect, prompt=<agent.taskPrompt + conteúdo de proposal.md>)
161
- ```
162
-
163
- O agente responde às 5 perguntas de complexidade DDD e retorna o nível (1, 2 ou 3) com justificativa.
164
-
165
- **Após receber o resultado:**
166
- - Documente no spec.md (seção `## Domain Complexity`)
167
- - **Para Nível 2+:** Preencha o `## Aggregate Blueprint` no spec.md
168
- - **Para Nível 3:** Adicione `BOUNDED_CONTEXT` como variável ao renderizar o template
169
-
170
- #### Caminho B: `vsa-architect` ativo (VSA)
171
-
172
- Use o `taskPrompt` do dispatch config (enriquecido com o conteúdo da proposta). Chame o Agent tool:
173
-
174
- ```
175
- Agent(subagent_type=vsa-architect, prompt=<agent.taskPrompt + conteúdo de proposal.md>)
176
- ```
177
-
178
- O agente produz um VSA Blueprint com entity fields, operations, routes, error types e validation rules.
179
-
180
- **Após receber o resultado:** Documente no spec.md (seção `## Architecture Style: Vertical Slice`).
181
-
182
- ---
183
-
184
- ### Passo 2: Analisar Código Existente (CRÍTICO - FAZER ANTES DE CONTRACTS!)
185
-
186
- **⚠️ ATENÇÃO:** Este passo é OBRIGATÓRIO antes de gerar `contracts-level{N}.cs`. Previne geração de DTOs com nomes de campos errados.
187
-
188
- **Delegate para skill dedicada:**
189
-
190
- > **Ref:** `framework/skills/level-1-workflows/phase-codebase-analysis/SKILL.md` — workflow completo de análise de schema (MCP Supabase → fallback análise estática → SCHEMA-ANALYSIS.md → checkpoint de aprovação)
191
-
192
- Execute o workflow de `phase-codebase-analysis.md` para:
193
- 1. Detectar se análise é necessária
194
- 2. Tentar MCP Supabase (preferencial) ou análise estática (fallback)
195
- 3. Mapear field name mismatches e type mismatches
196
- 4. Gerar `schema-analysis.md` com findings reais
197
- 5. Apresentar checkpoint ao usuário e aguardar aprovação
198
-
199
- **Pule se:**
200
- - Feature é 100% nova (sem dependências em código existente)
201
- - Não há banco de dados ou APIs envolvidas
202
-
203
- ### Passo 3: Gerar `spec.md`
204
-
205
- > Para estrutura detalhada de cada seção, veja `references/spec-authoring-guide.md`
206
-
207
- Crie `.morph/features/$ARGUMENTS/1-design/spec.md` com as seções: Overview, Functional Requirements (FR001...), Non-Functional Requirements, Technical Architecture, Data Model, e Infrastructure Requirements (se aplicável).
208
-
209
- ### Passo 4: Gerar `contracts.cs` (BASEADO NO SCHEMA REAL!)
210
-
211
- **⚠️ IMPORTANTE:** Use `schema-analysis.md` (do Passo 2) para gerar DTOs/campos corretos!
212
-
213
- **Selecione o template baseado no arquiteto ativo:**
214
-
215
- | Arquiteto ativo | Template |
216
- |-----------------|---------|
217
- | `vsa-architect` | `code/dotnet/contracts/contracts-vsa.cs` |
218
- | `domain-architect` (Nível 1) | `code/dotnet/contracts/contracts-level1.cs` |
219
- | `domain-architect` (Nível 2) | `code/dotnet/contracts/contracts-level2.cs` |
220
- | `domain-architect` (Nível 3) | `code/dotnet/contracts/contracts-level3.cs` |
221
-
222
- **Renderizar template:**
223
-
224
- ```bash
225
- # Para projetos VSA:
226
- npx morph-spec template render \
227
- dotnet-contracts-vsa \
228
- .morph/features/$ARGUMENTS/1-design/contracts.cs \
229
- '{
230
- "FEATURE_NAME": "$ARGUMENTS",
231
- "NAMESPACE": "{ProjectNamespace}",
232
- "ROUTE": "/api/{kebabCase FEATURE_NAME}s",
233
- "DATE": "{{DATE}}"
234
- }'
235
-
236
- # Para projetos DDD (substituir N pelo nível detectado):
237
- npx morph-spec template render \
238
- code/dotnet/contracts/contracts-level{N}.cs \
239
- .morph/features/$ARGUMENTS/1-design/contracts.cs \
240
- '{
241
- "FEATURE_NAME": "$ARGUMENTS",
242
- "NAMESPACE": "{ProjectNamespace}",
243
- "dtos": [...],
244
- "interfaces": [...],
245
- "enums": [...],
246
- "valueObjects": [...]
247
- }'
248
- ```
249
-
250
- **Após renderizar (VSA):** Preencha os campos marcados com `// placeholder:` no template gerado com os campos reais da entidade, validators e mapeamentos do VSA Blueprint (Passo 1.5 Caminho B).
251
-
252
- **Padrões obrigatórios (DDD — já incluídos no template):**
253
- - Records para DTOs (immutable)
254
- - Interfaces para serviços
255
- - CancellationToken em métodos async
256
- - Nullable reference types habilitados
257
- - **USAR NOMES DE CAMPOS REAIS DO SCHEMA** (NÃO assumir!)
258
- - XML documentation comments
259
- - Value objects para complex types
260
-
261
- **Padrões obrigatórios (VSA — já incluídos no template):**
262
- - Request + Response records no mesmo arquivo do Handler
263
- - `sealed` em handlers, endpoints, validators, records
264
- - `Guid.CreateVersion7()` para IDs
265
- - `result.Match()` nos endpoints
266
- - `{Entity}Errors` estático compartilhado por todos os slices da feature
267
-
268
- **⚠️ CHECKPOINT: Verificar contra schema-analysis.md**
269
- - [ ] Todos os field names correspondem ao schema real?
270
- - [ ] Tipos de dados corretos (JSONB → JsonObject, não string)?
271
- - [ ] Nullability correta (campo opcional no banco → nullable no DTO)?
272
- - [ ] Relacionamentos mapeados corretamente?
273
- - [ ] Template foi renderizado corretamente?
274
-
275
- ### Passo 5: Iniciar `decisions.md`
276
-
277
- **Renderizar template:**
278
-
279
- ```bash
280
- # Use o template de decisions:
281
- Read: .morph/framework/templates/feature/decisions.md
282
-
283
- # OU renderize via CLI:
284
- npx morph-spec template render \
285
- feature/decisions \
286
- .morph/features/$ARGUMENTS/1-design/decisions.md \
287
- '{
288
- "FEATURE_NAME": "$ARGUMENTS",
289
- "DATE": "{{DATE}}",
290
- "decisions": []
291
- }'
292
- ```
293
-
294
- **Template contém estrutura para ADRs (Architecture Decision Records):**
295
- - Status, Context, Decision, Consequences
296
- - Pros/Cons analysis
297
- - Alternatives Considered section
298
- - Date tracking
299
-
300
- **ADRs obrigatórios:**
301
- - Escolha de biblioteca UI (se FASE 1.5 executou)
302
- - Padrões arquiteturais (CQRS, Repository, etc.)
303
- - Recursos Azure (se houver infra)
304
- - Integrações externas (APIs, webhooks, etc.)
305
- - Análise de custos (se houver recursos pagos)
306
-
307
- ### Passo 6: Estimar Custos
308
-
309
- Se houver recursos Azure na spec:
310
-
311
- **Limites configuráveis** (em config.json):
312
- - `costs.limits.freeTierOnly`: $0 (apenas free tier)
313
- - `costs.limits.withApproval`: $10 (requer confirmação do usuário)
314
- - `costs.limits.requiresADR`: $10 (requer ADR documentado)
315
-
316
- Documente custos em `decisions.md` e atualize state:
317
-
318
- ```bash
319
- npx morph-spec state set $ARGUMENTS costs.estimated {X.XX}
320
- npx morph-spec state set $ARGUMENTS costs.approved {true/false}
321
- ```
322
-
323
- ### Passo 7: Atualizar State
324
-
325
- ```bash
326
- npx morph-spec state mark-output $ARGUMENTS schema-analysis
327
- npx morph-spec state mark-output $ARGUMENTS spec
328
- npx morph-spec state mark-output $ARGUMENTS contracts
329
- npx morph-spec state mark-output $ARGUMENTS decisions
330
- ```
331
-
332
- ## Outputs Gerados
333
-
334
- - `.morph/features/$ARGUMENTS/1-design/schema-analysis.md` - **NOVO!** Análise do schema real
335
- - `.morph/features/$ARGUMENTS/1-design/spec.md` - Especificação técnica completa
336
- - `.morph/features/$ARGUMENTS/1-design/contracts.cs` - Interfaces, DTOs, Enums (baseados no schema real!)
337
- - `.morph/features/$ARGUMENTS/1-design/decisions.md` - ADRs (novo ou atualizado)
338
- - State atualizado com custos estimados
339
-
340
- ## PAUSA OBRIGATÓRIA
341
-
342
- Apresente ao usuário 3 ações sugeridas:
343
-
344
- 1. **Aprovar design e continuar para clarificação**
345
- 2. **Ajustar escopo/complexidade** - Revisar spec.md
346
- 3. **Modificar contracts** - Ajustar interfaces/DTOs
347
-
348
- ## Critérios de Avanço
349
-
350
- - [x] `spec.md` completo com todos os requisitos
351
- - [x] `contracts-level{N}.cs` com interfaces e DTOs
352
- - [x] `decisions.md` com ADRs relevantes
353
- - [x] Custos estimados e documentados (se houver infra)
354
- - [x] State atualizado
355
- - [x] Usuário aprovou design
356
-
357
- ---
358
-
359
- ## Integração com Superpowers
360
-
361
- > Disponível quando o plugin `superpowers` está instalado.
362
-
363
- | Skill | Quando Usar | Invocação |
364
- |-------|-------------|-----------|
365
- | `writing-plans` | Após spec aprovado, para estruturar abordagem de implementação | `Skill(superpowers:writing-plans)` |
366
- | `brainstorming` | Para explorar alternativas de arquitetura (use morph-spec version) | Use `brainstorming` (morph-spec version) |
367
-
368
- ---
369
-
370
- ## Outputs desta Fase
371
-
372
- <!-- morph:outputs:design -->
373
- | Output | Caminho |
374
- |--------|---------|
375
- | `schemaAnalysis` | `.morph/features/{feature}/1-design/schema-analysis.md` |
376
- | `spec` | `.morph/features/{feature}/1-design/spec.md` |
377
- | `contracts` | `.morph/features/{feature}/1-design/contracts.cs` |
378
- | `decisions` | `.morph/features/{feature}/1-design/decisions.md` |
379
- <!-- /morph:outputs -->
380
-
381
- ---
382
-
383
- Continuar automaticamente para FASE 3 (Clarify) após aprovação.
@@ -1,8 +0,0 @@
1
- /**
2
- * Project-Level Commands
3
- */
4
- export { initCommand } from './init.js';
5
- export { doctorCommand } from './doctor.js';
6
- export { updateCommand } from './update.js';
7
- export { tutorialCommand } from './tutorial.js';
8
- export { monitorCommand } from './monitor.js';
package/src/core/index.js DELETED
@@ -1,10 +0,0 @@
1
- /**
2
- * Core Framework Logic
3
- *
4
- * Central hub for state management, templates, and workflows.
5
- * Separated from shared libraries (lib/) for clear architectural boundaries.
6
- */
7
-
8
- export * from './state/index.js';
9
- export * from './templates/index.js';
10
- export * from './workflows/index.js';
@@ -1,8 +0,0 @@
1
- /**
2
- * Core State Management
3
- *
4
- * State management and phase state machine for MORPH-SPEC workflow.
5
- */
6
-
7
- export { StateManager } from './state-manager.js';
8
- export { PhaseStateMachine, PHASES, validatePhase } from './phase-state-machine.js';
@@ -1,9 +0,0 @@
1
- /**
2
- * Core Template System
3
- *
4
- * Template registry, rendering, and data sources for code generation.
5
- */
6
-
7
- export { TemplateRegistry } from './template-registry.js';
8
- export { TemplateRenderer } from './template-renderer.js';
9
- export { TemplateDataSources } from './template-data-sources.js';