legacy-squad 1.0.0 → 1.0.1

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 (3) hide show
  1. package/README.md +471 -431
  2. package/README.pt-br.md +471 -431
  3. package/package.json +58 -58
package/README.pt-br.md CHANGED
@@ -1,431 +1,471 @@
1
- <p align="center">
2
- <h1 align="center">Legacy Squad Framework</h1>
3
- <p align="center"><strong>Plataforma de Modernização de Legados com IA</strong></p>
4
- <p align="center"><em>Understand. Plan. Modernize.</em></p>
5
- <p align="center">
6
- <strong>🇧🇷 Português</strong> · <a href="README.md">🇺🇸 English</a>
7
- </p>
8
- </p>
9
-
10
- ---
11
-
12
- Legacy Squad é um framework open-source que se instala dentro do seu projeto legado com um único comando, analisa automaticamente o código-fonte e disponibiliza agentes de IA especializados na sua IDE para produzir um diagnóstico completo — sem alterar uma linha de código.
13
-
14
- ```bash
15
- npx legacy-squad install
16
- ```
17
-
18
- ---
19
-
20
- ## O Problema
21
-
22
- Sistemas legados sustentam processos críticos, mas frequentemente apresentam:
23
-
24
- - Documentação inexistente ou desatualizada
25
- - Credenciais hardcoded em código-fonte
26
- - Regras de negócio escondidas em condicionais que ninguém documentou
27
- - Acoplamento que torna qualquer mudança arriscada
28
- - Medo de alterar código em produção
29
- - Dependência de 1-2 desenvolvedores que "conhecem o sistema"
30
-
31
- Abordagens tradicionais (reescrita total, refatoração sem governança) são caras, lentas e arriscadas.
32
-
33
- ## A Solução
34
-
35
- Legacy Squad combina **análise determinística** (scanner + compliance engine com regras OWASP/CWE) com **agentes de IA especializados** que rodam na sua IDE (Claude Code, Codex, Cursor) para produzir:
36
-
37
- | Artefato | O que faz |
38
- |----------|-----------|
39
- | **Repo Index** | Inventário completo: stack, módulos, dependências, integrações, hotspots |
40
- | **Findings** | Achados de segurança com evidência, impacto, referência OWASP e recomendação |
41
- | **Security Assessment** | Análise profunda de autenticação, secrets, LGPD/GDPR, API security |
42
- | **Architecture Assessment** | Mapeamento C4, acoplamento, riscos estruturais, arquitetura alvo |
43
- | **Legacy Code Assessment** | Hotspots, migração JS→TS, duplicação, cobertura de testes |
44
- | **Business Rules Assessment** | 60+ regras extraídas do código, preservation checklist |
45
- | **Modernization Plan** | Roadmap incremental em fases com rollback e scores |
46
- | **PRS** | Product Refactor Specification — documento consolidado para decision makers |
47
-
48
- ---
49
-
50
- ## Quick Start
51
-
52
- ### Pré-requisitos
53
-
54
- - Node.js ≥ 18
55
- - Uma IDE com IA: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex CLI](https://github.com/openai/codex) ou [Cursor](https://cursor.sh)
56
-
57
- ### Instalação
58
-
59
- ```bash
60
- cd seu-projeto-legado
61
- npx legacy-squad install
62
- ```
63
-
64
- O comando:
65
- 1. Detecta a stack (React Native, PHP, .NET, Java, Node — por manifesto)
66
- 2. Escaneia o repositório e gera o inventário
67
- 3. Roda o Compliance Engine (regras OWASP/CWE)
68
- 4. Gera Context Packs por módulo
69
- 5. Instala agentes como slash commands na IDE
70
- 6. Verifica a instalação (8 checks)
71
-
72
- ### Uso com Claude Code
73
-
74
- ```bash
75
- claude # Abre Claude Code no projeto
76
- /legacy-squad-security # Roda o Security Agent
77
- /legacy-squad-architecture # Roda o Architecture Agent
78
- /legacy-squad-legacy-code # Roda o Legacy Code Agent
79
- /legacy-squad-business-rules # Roda o Business Rules Agent
80
- /legacy-squad-modernization # Roda o Modernization Agent
81
- /legacy-squad-generate-prs # Consolida tudo no PRS final
82
- ```
83
-
84
- ### Uso com Codex CLI
85
-
86
- ```bash
87
- codex # Abre Codex no projeto
88
- # O AGENTS.md na raiz define os agentes disponíveis
89
- @legacy-squad-security # Ativa o Security Agent
90
- ```
91
-
92
- ### Outros Comandos
93
-
94
- ```bash
95
- npx legacy-squad scan # Re-escaneia sem reinstalar agentes
96
- npx legacy-squad doctor # Verifica saúde da instalação
97
- ```
98
-
99
- ---
100
-
101
- ## Como Funciona
102
-
103
- ```
104
- ┌─────────────────────┐
105
- │ npx legacy-squad │
106
- │ install │
107
- └─────────┬───────────┘
108
- │
109
- ┌───────────────┼───────────────┐
110
- ▼ ▼ ▼
111
- ┌──────────┐ ┌────────────┐ ┌────────────┐
112
- │ Scanner │ │ Compliance │ │ Context │
113
- │ (stack, │ │ Engine │ │ Manager │
114
- │ módulos) │ │ (OWASP) │ │ (packs) │
115
- └────┬─────┘ └─────┬──────┘ └─────┬──────┘
116
- │ │ │
117
- ▼ ▼ ▼
118
- ┌──────────────────────────────────────────┐
119
- │ .legacy-squad/memory/ │
120
- │ repo-index.json | findings.json | │
121
- │ context-packs.json │
122
- └──────────────────┬───────────────────────┘
123
- │
124
- ┌────────────┼────────────┐
125
- ▼ ▼ ▼
126
- ┌──────────┐ ┌──────────┐ ┌──────────┐
127
- │ .claude/ │ │ AGENTS.md│ │ .cursor/ │
128
- │ commands/│ │ (Codex) │ │ rules/ │
129
- │ (Claude) │ │ │ │ (Cursor) │
130
- └────┬─────┘ └────┬─────┘ └────┬─────┘
131
- │ │ │
132
- └─────────────┼─────────────┘
133
- │
134
- ┌──────▼──────┐
135
- │ IDE + IA │
136
- │ (Claude Code│
137
- │ Codex, │
138
- │ Cursor) │
139
- └──────┬──────┘
140
- │
141
- ┌──────▼──────┐
142
- │ Assessments │
143
- │ + PRS final │
144
- └─────────────┘
145
- ```
146
-
147
- **O framework prepara os dados e instala os agentes. A IA é executada pela IDE do dev.**
148
-
149
- Zero API key necessária. Zero chamada a servidor externo. Tudo local.
150
-
151
- ---
152
-
153
- ## Estrutura Instalada no Projeto
154
-
155
- Após `npx legacy-squad install`:
156
-
157
- ```
158
- seu-projeto/
159
- ├── .legacy-squad/
160
- │ ├── config/
161
- │ │ └── project.yaml # Configuração detectada
162
- │ ├── memory/
163
- │ │ ├── repo-index.json # Inventário do repositório
164
- │ │ ├── findings.json # Achados do compliance engine
165
- │ │ └── context-packs.json # Contexto por módulo
166
- │ ├── outputs/
167
- │ │ ├── assessments/ # Assessments dos agentes
168
- │ │ └── reports/ # PRS consolidado
169
- │ └── logs/
170
- │ └── install.log
171
- ├── .claude/
172
- │ └── commands/
173
- │ └── legacy-squad/
174
- │ ├── security.md # /legacy-squad-security
175
- │ ├── architecture.md # /legacy-squad-architecture
176
- │ ├── legacy-code.md # /legacy-squad-legacy-code
177
- │ ├── business-rules.md # /legacy-squad-business-rules
178
- │ ├── modernization.md # /legacy-squad-modernization
179
- │ ├── generate-prs.md # /legacy-squad-generate-prs
180
- │ └── scan.md # /legacy-squad-scan
181
- └── AGENTS.md # Compatibilidade Codex
182
- ```
183
-
184
- ---
185
-
186
- ## Agentes
187
-
188
- ### Security Agent (`/legacy-squad-security`)
189
-
190
- Analisa autenticação, secrets, armazenamento inseguro, exposição de PII e conformidade com leis de privacidade (LGPD, GDPR).
191
-
192
- **Referências:** OWASP MASVS V2, OWASP ASVS, CWE Top 25, LGPD, GDPR, NIST SSDF
193
-
194
- ### Architecture Agent (`/legacy-squad-architecture`)
195
-
196
- Mapeia arquitetura atual com diagramas C4, identifica acoplamento, riscos estruturais e propõe arquitetura alvo incremental.
197
-
198
- **Referências:** C4 Model, Clean Architecture, arc42, ADR
199
-
200
- ### Legacy Code Agent (`/legacy-squad-legacy-code`)
201
-
202
- Identifica hotspots, duplicação, progresso de migração JS→TS, cobertura de testes e prioridades de refatoração.
203
-
204
- **Referências:** Clean Code, Sonar Rules, Cognitive Complexity
205
-
206
- ### Business Rules Agent (`/legacy-squad-business-rules`)
207
-
208
- Extrai regras de negócio escondidas no código — validações, permissões, fluxos, magic numbers, regras implícitas em catch blocks.
209
-
210
- **Referências:** DDD, Event Storming
211
-
212
- ### Modernization Agent (`/legacy-squad-modernization`)
213
-
214
- Sintetiza todos os assessments em um plano incremental com fases, rollback, Deployability Score (1-10) e Execution Readiness Score (0-100).
215
-
216
- **Referências:** Strangler Fig, Branch by Abstraction, Progressive Delivery
217
-
218
- ### PRS Generator (`/legacy-squad-generate-prs`)
219
-
220
- Consolida todos os assessments no PRS (Product Refactor Specification) — o documento final para decision makers.
221
-
222
- ---
223
-
224
- ## Stacks Suportadas
225
-
226
- ### Detecção por Manifesto (Camada 1 — determinística)
227
-
228
- | Manifesto | Stack |
229
- |-----------|-------|
230
- | `package.json` | Node.js, React, React Native, Expo, Next.js |
231
- | `composer.json` | PHP, Laravel |
232
- | `.csproj` | C#, .NET |
233
- | `pom.xml` | Java, Spring Boot |
234
-
235
- ### Detecção por Extensão (Camada 2 — heurística)
236
-
237
- TypeScript, JavaScript, PHP, C#, Java, Python, Dart
238
-
239
- ---
240
-
241
- ## Compliance Engine
242
-
243
- O scanner roda automaticamente regras determinísticas baseadas em OWASP e CWE:
244
-
245
- | Regra | Detecta | Referência |
246
- |-------|---------|------------|
247
- | SEC-CRED-001 | Credenciais hardcoded | OWASP MASVS, CWE-798 |
248
- | SEC-CRED-002 | Keystores/certificados no repositório | OWASP MASVS, CWE-312 |
249
- | SEC-LOG-001 | Console.log ativo em produção | CWE-532 |
250
- | SEC-LOG-002 | PII (CPF, SSN, IDs) em logs/serviços externos | CWE-532, LGPD/GDPR |
251
- | SEC-ERR-001 | Catch blocks vazios | CWE-390 |
252
- | SEC-STORE-001 | Token em AsyncStorage | OWASP MASVS |
253
- | CQ-MIX-001 | JS e TS misturados | Clean Code |
254
- | CQ-DEP-001 | Dependências transitivas | Clean Code |
255
-
256
- Todo achado inclui: evidência (arquivo, linha, snippet), impacto, referência técnica e recomendação.
257
-
258
- ---
259
-
260
- ## Princípios
261
-
262
- | Princípio | Descrição |
263
- |-----------|-----------|
264
- | **Install-First** | Um comando instala tudo no projeto. Sem configuração manual. |
265
- | **IDE-Native** | Agentes são slash commands da IDE. A IA vem do ambiente do dev. |
266
- | **Evidence-Driven** | Todo achado tem evidência concreta (arquivo, linha, snippet). |
267
- | **Context-First** | Nenhum LLM recebe o repositório inteiro — apenas context packs. |
268
- | **Read-Only** | O framework não altera código. Apenas lê e gera relatórios. |
269
- | **Production-First** | Toda recomendação assume que o sistema está em produção. |
270
- | **Incremental** | Toda modernização é incremental, reversível e deployável. |
271
-
272
- ---
273
-
274
- ## Validado em Produção
275
-
276
- O framework foi validado contra um **app mobile em produção** (~18k linhas de código, 98 dependências, transações financeiras reais):
277
-
278
- **Compliance Engine (determinístico):** 7 achados por pattern matching
279
-
280
- **Agentes (IA via Claude Code):** +43 achados adicionais, incluindo:
281
- - Credenciais de service account decodificadas de Base64 no código-fonte
282
- - Flag de configuração remota capaz de bypassar toda a autenticação em produção
283
- - Senhas de usuário gravadas em texto plano em banco de dados cloud
284
- - PII usada como chave primária em banco cloud (enumerável)
285
- - Gravação de sessão capturando dados sensíveis sem consentimento
286
- - 63 regras de negócio extraídas do código (11 implícitas, nunca documentadas)
287
- - Bug potencial em cálculo de datas afetando lógica de negócio central
288
-
289
- **Artefatos gerados (4 entregáveis oficiais do V1):**
290
- - **PRS** — Product Refactor Specification consolidando o diagnóstico
291
- - **SDD** — Software Design Document com arquitetura atual/alvo e 8 ADRs
292
- - **MMP** — Modernization Master Plan com roadmap em 4 fases (Emergência → Foundation → Core → Evolution), Execution Readiness Score 38→88/100, scores de deployability por fase e estratégias concretas de rollback
293
- - **37 Execution Specs** — unidades de trabalho atômicas, individualmente deployáveis, com critérios de aceite binários, rollback obrigatório, rastreabilidade de evidências e grafo de dependências
294
-
295
- **Total:** 50 achados + 4 artefatos consolidados + 37 specs executáveis a partir de um único `npx legacy-squad install` seguido de 9 ativações de slash command.
296
-
297
- ---
298
-
299
- ## Open Core
300
-
301
- ### Community Edition (V1) — Open Source
302
-
303
- Foco: **Entender + Planejar**
304
-
305
- - Scanner com detecção multi-stack (PHP/Laravel/Symfony, .NET/ASP.NET, Java/Spring, Node, React Native/Expo)
306
- - Compliance Engine com 14 regras determinísticas (OWASP MASVS, ASVS, CWE Top 25)
307
- - Context Manager (básico)
308
- - **5 agentes de análise** como slash commands: security, architecture, legacy-code, business-rules, modernization
309
- - **4 geradores de artefato** como slash commands: PRS, SDD, MMP, Execution Specs
310
- - Suporte a Claude Code, Codex CLI (Cursor / Gemini CLI no roadmap)
311
-
312
- ### Enterprise Edition (V2) — Em desenvolvimento
313
-
314
- Foco: **Modernizar**
315
-
316
- - Execution Engine (refatoração assistida por IA)
317
- - Pull Request Engine
318
- - QA Gates
319
- - Integração CI/CD
320
- - Custom Rule Packs
321
- - Dashboard + Colaboração em Equipe
322
-
323
- ---
324
-
325
- ## Roadmap
326
-
327
- ### V1 — Discovery Platform (Community Edition) ✅
328
-
329
- - [x] Scanner + Compliance Engine
330
- - [x] Comando install + integração com IDE
331
- - [x] Context Manager (básico)
332
- - [x] Validação end-to-end com projeto real (mobile, ~18k LoC)
333
- - [x] Catálogo de regras multi-stack (PHP, .NET, Java, Node, mobile)
334
- - [x] Templates de agentes language-agnostic (stack-aware analysis)
335
- - [x] 4 artefatos oficiais (PRS, SDD, MMP, Execution Specs)
336
-
337
- ### V1 — Melhorias contínuas
338
-
339
- - [ ] Suporte a Cursor + Gemini CLI
340
- - [ ] Pacotes de regras framework-specific (Eloquent raw queries, EF Core, Hibernate HQL)
341
- - [ ] Scanner baseado em AST (atual é regex)
342
-
343
- ### V2 — Execution Platform (Enterprise Edition) — Em desenvolvimento
344
-
345
- - [ ] Execution Engine (refatoração assistida por IA a partir das Execution Specs)
346
- - [ ] Pull Request Engine
347
- - [ ] QA Gates
348
- - [ ] Integração CI/CD
349
- - [ ] Custom Rule Packs
350
- - [ ] Dashboard + Colaboração em Equipe
351
-
352
- ---
353
-
354
- ## Desenvolvimento
355
-
356
- ```bash
357
- git clone https://github.com/hrpimenta/legacy-squad.git
358
- cd legacy-squad
359
- pnpm install
360
- pnpm approve-builds esbuild
361
-
362
- # Testes
363
- npx vitest run
364
-
365
- # Modo dev (sem build)
366
- npx tsx apps/cli/src/index.ts install -p /caminho/do/projeto
367
-
368
- # Build
369
- node build.mjs
370
-
371
- # Testar versão bundled
372
- node dist/cli.mjs install -p /caminho/do/projeto
373
- ```
374
-
375
- ### Estrutura do Monorepo
376
-
377
- ```
378
- legacy-squad/
379
- ├── packages/
380
- │ ├── core/ # Tipos de domínio, portas (Clean Architecture)
381
- │ ├── scanner/ # Detecção de stack, geração de repo index
382
- │ ├── context/ # Context packs builder
383
- │ ├── rules/ # Compliance engine, catálogo de regras
384
- │ ├── agents/ # Definições de agentes, installer, doctor
385
- │ └── output/ # Gerador de PRS
386
- ├── apps/
387
- │ └── cli/ # Entry point da CLI (Commander.js)
388
- ├── templates/
389
- │ └── claude-commands/ # Templates dos slash commands
390
- └── docs/
391
- └── plans/ # Decisões de arquitetura, planos
392
- ```
393
-
394
- ### Testes
395
-
396
- ```bash
397
- npx vitest run # 28 testes (domínio, scanner, compliance, agentes)
398
- npx vitest --watch # Watch mode
399
- ```
400
-
401
- ---
402
-
403
- ## Contribuindo
404
-
405
- 1. Faça fork do repositório
406
- 2. Crie uma branch (`git checkout -b feature/minha-feature`)
407
- 3. Siga os padrões: TDD (Red→Green→Refactor), SOLID, Clean Architecture
408
- 4. Rode os testes (`npx vitest run`)
409
- 5. Abra um PR
410
-
411
- ### Formas de contribuir
412
-
413
- - Novas regras para o Compliance Engine (PHP, .NET, Java)
414
- - Melhorias nos templates de agentes
415
- - Suporte a novas IDEs
416
- - Documentação e tradução
417
- - Testes e fixtures para outras stacks
418
-
419
- ---
420
-
421
- ## Licença
422
-
423
- MIT — veja [LICENSE](LICENSE) para detalhes.
424
-
425
- ---
426
-
427
- <p align="center">
428
- <strong>Understand. Plan. Modernize.</strong>
429
- <br>
430
- <em>Legacy Squad Framework</em>
431
- </p>
1
+ <p align="center">
2
+ <h1 align="center">Legacy Squad Framework</h1>
3
+ <p align="center"><strong>Plataforma de Modernização de Legados com IA</strong></p>
4
+ <p align="center"><em>Understand. Plan. Modernize.</em></p>
5
+ <p align="center">
6
+ <strong>🇧🇷 Português</strong> · <a href="README.md">🇺🇸 English</a>
7
+ </p>
8
+ </p>
9
+
10
+ ---
11
+
12
+ Legacy Squad é um framework open-source que se instala dentro do seu projeto legado com um único comando, analisa automaticamente o código-fonte e disponibiliza agentes de IA especializados na sua IDE para produzir um diagnóstico completo — sem alterar uma linha de código.
13
+
14
+ ```bash
15
+ npx legacy-squad install
16
+ ```
17
+
18
+ ---
19
+
20
+ ## O Problema
21
+
22
+ Sistemas legados sustentam processos críticos, mas frequentemente apresentam:
23
+
24
+ - Documentação inexistente ou desatualizada
25
+ - Credenciais hardcoded em código-fonte
26
+ - Regras de negócio escondidas em condicionais que ninguém documentou
27
+ - Acoplamento que torna qualquer mudança arriscada
28
+ - Medo de alterar código em produção
29
+ - Dependência de 1-2 desenvolvedores que "conhecem o sistema"
30
+
31
+ Abordagens tradicionais (reescrita total, refatoração sem governança) são caras, lentas e arriscadas.
32
+
33
+ ## A Solução
34
+
35
+ Legacy Squad combina **análise determinística** (scanner + compliance engine com regras OWASP/CWE) com **agentes de IA especializados** que rodam na sua IDE (Claude Code, Codex, Cursor) para produzir:
36
+
37
+ | Artefato | O que faz |
38
+ |----------|-----------|
39
+ | **Repo Index** | Inventário completo: stack, módulos, dependências, integrações, hotspots |
40
+ | **Findings** | Achados de segurança com evidência, impacto, referência OWASP e recomendação |
41
+ | **Security Assessment** | Análise profunda de autenticação, secrets, LGPD/GDPR, API security |
42
+ | **Architecture Assessment** | Mapeamento C4, acoplamento, riscos estruturais, arquitetura alvo |
43
+ | **Legacy Code Assessment** | Hotspots, migração JS→TS, duplicação, cobertura de testes |
44
+ | **Business Rules Assessment** | 60+ regras extraídas do código, preservation checklist |
45
+ | **Modernization Assessment** | Roadmap incremental em fases com rollback e scores |
46
+ | **PRS** | Product Refactor Specification — relatório consolidado de diagnóstico |
47
+ | **SDD** | Software Design Document — arquitetura atual/alvo com ADRs |
48
+ | **MMP** | Modernization Master Plan — roadmap em fases com scores de Execution Readiness e Deployability |
49
+ | **Execution Specs** | Unidades de trabalho atômicas, individualmente deployáveis, com critérios de aceite binários e rollback |
50
+
51
+ ---
52
+
53
+ ## Quick Start
54
+
55
+ ### Pré-requisitos
56
+
57
+ - Node.js ≥ 18
58
+ - Uma IDE com IA: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex CLI](https://github.com/openai/codex) ou [Cursor](https://cursor.sh)
59
+
60
+ ### Instalação
61
+
62
+ ```bash
63
+ cd seu-projeto-legado
64
+ npx legacy-squad install
65
+ ```
66
+
67
+ O comando:
68
+ 1. Detecta a stack (React Native, PHP, .NET, Java, Node — por manifesto)
69
+ 2. Escaneia o repositório e gera o inventário
70
+ 3. Roda o Compliance Engine (regras OWASP/CWE)
71
+ 4. Gera Context Packs por módulo
72
+ 5. Instala agentes como slash commands na IDE
73
+ 6. Verifica a instalação (8 checks)
74
+
75
+ ### Uso com Claude Code
76
+
77
+ ```bash
78
+ claude # Abre Claude Code no projeto
79
+
80
+ # Passo 1 — Análise (5 agentes, rodar em ordem)
81
+ /legacy-squad-security # Security Agent
82
+ /legacy-squad-architecture # Architecture Agent
83
+ /legacy-squad-legacy-code # Legacy Code Agent
84
+ /legacy-squad-business-rules # Business Rules Agent
85
+ /legacy-squad-modernization # Modernization Agent
86
+
87
+ # Passo 2 — Artefatos consolidados (4 geradores, rodar após a análise)
88
+ /legacy-squad-generate-prs # Product Refactor Specification
89
+ /legacy-squad-generate-sdd # Software Design Document
90
+ /legacy-squad-generate-mmp # Modernization Master Plan
91
+ /legacy-squad-generate-specs # Execution Specs (um YAML por unidade de trabalho)
92
+ ```
93
+
94
+ ### Uso com Codex CLI
95
+
96
+ ```bash
97
+ codex # Abre Codex no projeto
98
+ # O AGENTS.md na raiz define os agentes disponíveis
99
+ @legacy-squad-security # Ativa o Security Agent
100
+ ```
101
+
102
+ ### Outros Comandos
103
+
104
+ ```bash
105
+ npx legacy-squad scan # Re-escaneia sem reinstalar agentes
106
+ npx legacy-squad doctor # Verifica saúde da instalação
107
+ ```
108
+
109
+ ---
110
+
111
+ ## Como Funciona
112
+
113
+ ```
114
+ ┌─────────────────────┐
115
+ │ npx legacy-squad │
116
+ │ install │
117
+ └─────────┬───────────┘
118
+ │
119
+ ┌───────────────┼───────────────┐
120
+ ▼ ▼ ▼
121
+ ┌──────────┐ ┌────────────┐ ┌────────────┐
122
+ │ Scanner │ │ Compliance │ │ Context │
123
+ │ (stack, │ │ Engine │ │ Manager │
124
+ │ módulos) │ │ (OWASP) │ │ (packs) │
125
+ └────┬─────┘ └─────┬──────┘ └─────┬──────┘
126
+ │ │ │
127
+ ▼ ▼ ▼
128
+ ┌──────────────────────────────────────────┐
129
+ │ .legacy-squad/memory/ │
130
+ │ repo-index.json | findings.json | │
131
+ │ context-packs.json │
132
+ └──────────────────┬───────────────────────┘
133
+ │
134
+ ┌────────────┼────────────┐
135
+ ▼ ▼ ▼
136
+ ┌──────────┐ ┌──────────┐ ┌──────────┐
137
+ │ .claude/ │ │ AGENTS.md│ │ .cursor/ │
138
+ │ commands/│ │ (Codex) │ │ rules/ │
139
+ │ (Claude) │ │ │ │ (Cursor) │
140
+ └────┬─────┘ └────┬─────┘ └────┬─────┘
141
+ │ │ │
142
+ └─────────────┼─────────────┘
143
+ │
144
+ ┌──────▼──────┐
145
+ │ IDE + IA │
146
+ │ (Claude Code│
147
+ │ Codex, │
148
+ │ Cursor) │
149
+ └──────┬──────┘
150
+ │
151
+ ┌──────▼──────┐
152
+ │ Assessments │
153
+ │ + PRS final │
154
+ └─────────────┘
155
+ ```
156
+
157
+ **O framework prepara os dados e instala os agentes. A IA é executada pela IDE do dev.**
158
+
159
+ Zero API key necessária. Zero chamada a servidor externo. Tudo local.
160
+
161
+ ---
162
+
163
+ ## Estrutura Instalada no Projeto
164
+
165
+ Após `npx legacy-squad install`:
166
+
167
+ ```
168
+ seu-projeto/
169
+ ├── .legacy-squad/
170
+ │ ├── config/
171
+ │ │ └── project.yaml # Configuração detectada
172
+ │ ├── memory/
173
+ │ │ ├── repo-index.json # Inventário do repositório
174
+ │ │ ├── findings.json # Achados do compliance engine
175
+ │ │ └── context-packs.json # Contexto por módulo
176
+ │ ├── outputs/
177
+ │ │ ├── assessments/ # Assessments dos agentes (5 .md)
178
+ │ │ ├── reports/ # PRS.md + PRS.json
179
+ │ │ ├── sdd/ # SDD.md + SDD.json
180
+ │ │ ├── mmp/ # MMP.md + MMP.json
181
+ │ │ └── specs/ # SPEC-*.yaml + INDEX.md
182
+ │ └── logs/
183
+ │ └── install.log
184
+ ├── .claude/
185
+ │ └── commands/
186
+ │ └── legacy-squad/
187
+ │ ├── security.md # /legacy-squad-security
188
+ │ ├── architecture.md # /legacy-squad-architecture
189
+ │ ├── legacy-code.md # /legacy-squad-legacy-code
190
+ │ ├── business-rules.md # /legacy-squad-business-rules
191
+ │ ├── modernization.md # /legacy-squad-modernization
192
+ │ ├── generate-prs.md # /legacy-squad-generate-prs
193
+ │ ├── generate-sdd.md # /legacy-squad-generate-sdd
194
+ │ ├── generate-mmp.md # /legacy-squad-generate-mmp
195
+ │ ├── generate-specs.md # /legacy-squad-generate-specs
196
+ │ └── scan.md # /legacy-squad-scan
197
+ └── AGENTS.md # Compatibilidade Codex
198
+ ```
199
+
200
+ ---
201
+
202
+ ## Agentes
203
+
204
+ ### Security Agent (`/legacy-squad-security`)
205
+
206
+ Analisa autenticação, secrets, armazenamento inseguro, exposição de PII e conformidade com leis de privacidade (LGPD, GDPR).
207
+
208
+ **Referências:** OWASP MASVS V2, OWASP ASVS, CWE Top 25, LGPD, GDPR, NIST SSDF
209
+
210
+ ### Architecture Agent (`/legacy-squad-architecture`)
211
+
212
+ Mapeia arquitetura atual com diagramas C4, identifica acoplamento, riscos estruturais e propõe arquitetura alvo incremental.
213
+
214
+ **Referências:** C4 Model, Clean Architecture, arc42, ADR
215
+
216
+ ### Legacy Code Agent (`/legacy-squad-legacy-code`)
217
+
218
+ Identifica hotspots, duplicação, progresso de migração JS→TS, cobertura de testes e prioridades de refatoração.
219
+
220
+ **Referências:** Clean Code, Sonar Rules, Cognitive Complexity
221
+
222
+ ### Business Rules Agent (`/legacy-squad-business-rules`)
223
+
224
+ Extrai regras de negócio escondidas no código — validações, permissões, fluxos, magic numbers, regras implícitas em catch blocks.
225
+
226
+ **Referências:** DDD, Event Storming
227
+
228
+ ### Modernization Agent (`/legacy-squad-modernization`)
229
+
230
+ Sintetiza todos os assessments em um plano incremental com fases, rollback, Deployability Score (1-10) e Execution Readiness Score (0-100).
231
+
232
+ **Referências:** Strangler Fig, Branch by Abstraction, Progressive Delivery
233
+
234
+ ### PRS Generator (`/legacy-squad-generate-prs`)
235
+
236
+ Consolida todos os assessments no PRS (Product Refactor Specification) — o relatório de diagnóstico para decision makers.
237
+
238
+ ### SDD Generator (`/legacy-squad-generate-sdd`)
239
+
240
+ Produz o Software Design Document com arquitetura atual e alvo (diagramas Mermaid C4), inventário de componentes, integrações, cross-cutting concerns (segurança, observabilidade, tratamento de erros, configuração), restrições e Architecture Decision Records (ADRs) com alternativas avaliadas.
241
+
242
+ **Referências:** C4 Model, arc42, ADR, Clean Architecture
243
+
244
+ ### MMP Generator (`/legacy-squad-generate-mmp`)
245
+
246
+ Produz o Modernization Master Plan com roadmap em fases (Foundation → Core → Evolution, com fase Emergency opcional quando há achados críticos), plano de upgrade de stack, matriz de risco, estratégia de rollback por fase, Execution Readiness Score (0-100) justificado dimensão por dimensão, Deployability Score por fase e métricas de sucesso em segurança, qualidade de código, cobertura de testes e arquitetura.
247
+
248
+ **Referências:** Strangler Fig, Branch by Abstraction, Progressive Delivery
249
+
250
+ ### Execution Specs Generator (`/legacy-squad-generate-specs`)
251
+
252
+ Decompõe o MMP em Execution Specs atômicas — um arquivo YAML por unidade de trabalho, cada uma individualmente deployável, com critérios de aceite binários, estratégia de rollback obrigatória, rastreabilidade de evidências (IDs de findings do compliance + referências aos assessments), grafo de dependências entre specs e flag explícita `human_approval_required` para mudanças de alto risco.
253
+
254
+ **Referências:** FRAMEWORK_SPECIFICATION Section 8 (schema da Execution Spec)
255
+
256
+ ---
257
+
258
+ ## Stacks Suportadas
259
+
260
+ ### Detecção por Manifesto (Camada 1 — determinística)
261
+
262
+ | Manifesto | Stack |
263
+ |-----------|-------|
264
+ | `package.json` | Node.js, React, React Native, Expo, Next.js |
265
+ | `composer.json` | PHP, Laravel |
266
+ | `.csproj` | C#, .NET |
267
+ | `pom.xml` | Java, Spring Boot |
268
+
269
+ ### Detecção por Extensão (Camada 2 — heurística)
270
+
271
+ TypeScript, JavaScript, PHP, C#, Java, Python, Dart
272
+
273
+ ---
274
+
275
+ ## Compliance Engine
276
+
277
+ O scanner roda automaticamente regras determinísticas baseadas em OWASP e CWE:
278
+
279
+ | Regra | Detecta | Stacks | Referência |
280
+ |-------|---------|--------|------------|
281
+ | SEC-CRED-001 | Credenciais hardcoded (senhas, API keys, tokens) | todas | OWASP MASVS, CWE-798 |
282
+ | SEC-CRED-002 | Keystores/certificados commitados no repositório | mobile, todas | OWASP MASVS, CWE-312 |
283
+ | SEC-SQL-001 | SQL injection (concatenação de string em queries) | PHP, .NET, Java, Node | OWASP A03, CWE-89 |
284
+ | SEC-CRYPTO-001 | Criptografia fraca (MD5, SHA1) | PHP, .NET, Java, Node | OWASP A02, CWE-327 |
285
+ | SEC-DESER-001 | Desserialização insegura (BinaryFormatter, `unserialize`, `readObject`) | .NET, PHP, Java | OWASP A08, CWE-502 |
286
+ | SEC-CMD-001 | Command injection (`exec`, `Runtime.exec`, `shell_exec` com input do usuário) | PHP, .NET, Java, Node | OWASP A03, CWE-78 |
287
+ | SEC-PATH-001 | Path traversal (paths de arquivo sem validação) | PHP, .NET, Java, Node | OWASP A01, CWE-22 |
288
+ | SEC-XSS-001 | XSS via output sem escape (`echo $_GET`, `Html.Raw`) | PHP, .NET | OWASP A03, CWE-79 |
289
+ | SEC-LOG-001 | `console.log` ativo em produção | JS/TS, mobile | CWE-532 |
290
+ | SEC-LOG-002 | PII (CPF, SSN, IDs) em logs/serviços externos | todas | CWE-532, LGPD/GDPR |
291
+ | SEC-ERR-001 | Catch blocks vazios | todas | CWE-390 |
292
+ | SEC-STORE-001 | Token em AsyncStorage (storage inseguro) | mobile | OWASP MASVS |
293
+ | CQ-MIX-001 | JS e TS misturados (migração TS incompleta) | JS/TS | Clean Code |
294
+ | CQ-DEPRECATED-001 | APIs deprecadas (`mysql_*`, `ereg`, `Vector`) | PHP, Java | CVE-classified |
295
+
296
+ Todo achado inclui: evidência (arquivo, linha, snippet), impacto, referência técnica e recomendação.
297
+
298
+ ---
299
+
300
+ ## Princípios
301
+
302
+ | Princípio | Descrição |
303
+ |-----------|-----------|
304
+ | **Install-First** | Um comando instala tudo no projeto. Sem configuração manual. |
305
+ | **IDE-Native** | Agentes são slash commands da IDE. A IA vem do ambiente do dev. |
306
+ | **Evidence-Driven** | Todo achado tem evidência concreta (arquivo, linha, snippet). |
307
+ | **Context-First** | Nenhum LLM recebe o repositório inteiro — apenas context packs. |
308
+ | **Read-Only** | O framework não altera código. Apenas lê e gera relatórios. |
309
+ | **Production-First** | Toda recomendação assume que o sistema está em produção. |
310
+ | **Incremental** | Toda modernização é incremental, reversível e deployável. |
311
+
312
+ ---
313
+
314
+ ## Validado em Produção
315
+
316
+ O framework foi validado contra um **app mobile em produção** (~18k linhas de código, 98 dependências, transações financeiras reais):
317
+
318
+ **Compliance Engine (determinístico):** 7 achados por pattern matching
319
+
320
+ **Agentes (IA via Claude Code):** +43 achados adicionais, incluindo:
321
+ - Credenciais de service account decodificadas de Base64 no código-fonte
322
+ - Flag de configuração remota capaz de bypassar toda a autenticação em produção
323
+ - Senhas de usuário gravadas em texto plano em banco de dados cloud
324
+ - PII usada como chave primária em banco cloud (enumerável)
325
+ - Gravação de sessão capturando dados sensíveis sem consentimento
326
+ - 63 regras de negócio extraídas do código (11 implícitas, nunca documentadas)
327
+ - Bug potencial em cálculo de datas afetando lógica de negócio central
328
+
329
+ **Artefatos gerados (4 entregáveis oficiais do V1):**
330
+ - **PRS** — Product Refactor Specification consolidando o diagnóstico
331
+ - **SDD** — Software Design Document com arquitetura atual/alvo e 8 ADRs
332
+ - **MMP** — Modernization Master Plan com roadmap em 4 fases (Emergência → Foundation → Core → Evolution), Execution Readiness Score 38→88/100, scores de deployability por fase e estratégias concretas de rollback
333
+ - **37 Execution Specs** — unidades de trabalho atômicas, individualmente deployáveis, com critérios de aceite binários, rollback obrigatório, rastreabilidade de evidências e grafo de dependências
334
+
335
+ **Total:** 50 achados + 4 artefatos consolidados + 37 specs executáveis a partir de um único `npx legacy-squad install` seguido de 9 ativações de slash command.
336
+
337
+ ---
338
+
339
+ ## Open Core
340
+
341
+ ### Community Edition (V1) — Open Source
342
+
343
+ Foco: **Entender + Planejar**
344
+
345
+ - Scanner com detecção multi-stack (PHP/Laravel/Symfony, .NET/ASP.NET, Java/Spring, Node, React Native/Expo)
346
+ - Compliance Engine com 14 regras determinísticas (OWASP MASVS, ASVS, CWE Top 25)
347
+ - Context Manager (básico)
348
+ - **5 agentes de análise** como slash commands: security, architecture, legacy-code, business-rules, modernization
349
+ - **4 geradores de artefato** como slash commands: PRS, SDD, MMP, Execution Specs
350
+ - Suporte a Claude Code, Codex CLI (Cursor / Gemini CLI no roadmap)
351
+
352
+ ### Enterprise Edition (V2) — Em desenvolvimento
353
+
354
+ Foco: **Modernizar**
355
+
356
+ - Execution Engine (refatoração assistida por IA)
357
+ - Pull Request Engine
358
+ - QA Gates
359
+ - Integração CI/CD
360
+ - Custom Rule Packs
361
+ - Dashboard + Colaboração em Equipe
362
+
363
+ ---
364
+
365
+ ## Roadmap
366
+
367
+ ### V1 — Discovery Platform (Community Edition) ✅
368
+
369
+ - [x] Scanner + Compliance Engine
370
+ - [x] Comando install + integração com IDE
371
+ - [x] Context Manager (básico)
372
+ - [x] Validação end-to-end com projeto real (mobile, ~18k LoC)
373
+ - [x] Catálogo de regras multi-stack (PHP, .NET, Java, Node, mobile)
374
+ - [x] Templates de agentes language-agnostic (stack-aware analysis)
375
+ - [x] 4 artefatos oficiais (PRS, SDD, MMP, Execution Specs)
376
+
377
+ ### V1 — Melhorias contínuas
378
+
379
+ - [ ] Suporte a Cursor + Gemini CLI
380
+ - [ ] Pacotes de regras framework-specific (Eloquent raw queries, EF Core, Hibernate HQL)
381
+ - [ ] Scanner baseado em AST (atual é regex)
382
+
383
+ ### V2 — Execution Platform (Enterprise Edition) — Em desenvolvimento
384
+
385
+ - [ ] Execution Engine (refatoração assistida por IA a partir das Execution Specs)
386
+ - [ ] Pull Request Engine
387
+ - [ ] QA Gates
388
+ - [ ] Integração CI/CD
389
+ - [ ] Custom Rule Packs
390
+ - [ ] Dashboard + Colaboração em Equipe
391
+
392
+ ---
393
+
394
+ ## Desenvolvimento
395
+
396
+ ```bash
397
+ git clone https://github.com/hrpimenta/legacy-squad.git
398
+ cd legacy-squad
399
+ pnpm install
400
+ pnpm approve-builds esbuild
401
+
402
+ # Testes
403
+ npx vitest run
404
+
405
+ # Modo dev (sem build)
406
+ npx tsx apps/cli/src/index.ts install -p /caminho/do/projeto
407
+
408
+ # Build
409
+ node build.mjs
410
+
411
+ # Testar versão bundled
412
+ node dist/cli.mjs install -p /caminho/do/projeto
413
+ ```
414
+
415
+ ### Estrutura do Monorepo
416
+
417
+ ```
418
+ legacy-squad/
419
+ ├── packages/
420
+ │ ├── core/ # Tipos de domínio, portas (Clean Architecture)
421
+ │ ├── scanner/ # Detecção de stack, geração de repo index
422
+ │ ├── context/ # Context packs builder
423
+ │ ├── rules/ # Compliance engine, catálogo de regras
424
+ │ ├── agents/ # Definições de agentes, installer, doctor
425
+ │ └── output/ # Gerador de PRS
426
+ ├── apps/
427
+ │ └── cli/ # Entry point da CLI (Commander.js)
428
+ ├── templates/
429
+ │ └── claude-commands/ # Templates dos slash commands
430
+ └── docs/
431
+ └── plans/ # Decisões de arquitetura, planos
432
+ ```
433
+
434
+ ### Testes
435
+
436
+ ```bash
437
+ npx vitest run # 93 testes (domínio, scanner, compliance, agentes, installer)
438
+ npx vitest --watch # Watch mode
439
+ ```
440
+
441
+ ---
442
+
443
+ ## Contribuindo
444
+
445
+ 1. Faça fork do repositório
446
+ 2. Crie uma branch (`git checkout -b feature/minha-feature`)
447
+ 3. Siga os padrões: TDD (Red→Green→Refactor), SOLID, Clean Architecture
448
+ 4. Rode os testes (`npx vitest run`)
449
+ 5. Abra um PR
450
+
451
+ ### Formas de contribuir
452
+
453
+ - Novas regras para o Compliance Engine (PHP, .NET, Java)
454
+ - Melhorias nos templates de agentes
455
+ - Suporte a novas IDEs
456
+ - Documentação e tradução
457
+ - Testes e fixtures para outras stacks
458
+
459
+ ---
460
+
461
+ ## Licença
462
+
463
+ MIT — veja [LICENSE](LICENSE) para detalhes.
464
+
465
+ ---
466
+
467
+ <p align="center">
468
+ <strong>Understand. Plan. Modernize.</strong>
469
+ <br>
470
+ <em>Legacy Squad Framework</em>
471
+ </p>