@ornexus/synapse-cli 4.2.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.
package/README.md ADDED
@@ -0,0 +1,662 @@
1
+ # ⚡ Synapse
2
+
3
+ **Orquestrador de Desenvolvimento de Epics & Stories - Multi-Platform**
4
+
5
+ Synapse e um framework standalone que automatiza o ciclo completo de desenvolvimento de software - do setup de branch ate o merge do PR - atraves de 12 steps estruturados com implementacao dual-mode inteligente. Suporta 6 plataformas com uma arquitetura core/targets unificada.
6
+
7
+ ---
8
+
9
+ ## Supported Platforms
10
+
11
+ Synapse suporta 6 plataformas organizadas em 4 tiers de suporte:
12
+
13
+ | Platform | Tier | Install Command | Key Features | README |
14
+ |---|---|---|---|---|
15
+ | **Claude Code** | Tier 1 (Full Pipeline) | `npx @ornexus/synapse-cli` | 12-step pipeline, YOLO mode, parallel epics, state machine | [targets/claude-code/](targets/claude-code/README.md) |
16
+ | **Cursor IDE** | Tier 2 (CLI Pipeline) | `./install.sh --targets cursor` | .mdc rules, slash commands, pipeline via runner | [targets/cursor/](targets/cursor/README.md) |
17
+ | **Gemini CLI** | Tier 2 (CLI Pipeline) | `./install.sh --targets gemini-cli` | TOML commands, GEMINI.md, headless execution, 1M context | [targets/gemini-cli/](targets/gemini-cli/README.md) |
18
+ | **Codex CLI** | Tier 2 (CLI Pipeline) | `./install.sh --targets codex` | Named profiles, `exec resume`, OS sandbox, self-as-MCP | [targets/codex/](targets/codex/README.md) |
19
+ | **VSCode/Copilot** | Tier 3 (Agent-Directed) | `./install.sh --targets vscode` | .instructions.md, prompt files, per-file standards | [targets/vscode/](targets/vscode/README.md) |
20
+ | **Antigravity** | Tier 3 (Agent-Directed) | `./install.sh --targets antigravity` | SKILL.md, rules, workflows, `// turbo` | [targets/antigravity/](targets/antigravity/README.md) |
21
+
22
+ ### Tier Support Matrix
23
+
24
+ | Capability | Tier 1 (Full) | Tier 2 (CLI) | Tier 3 (Agent) | Tier 4 (Manual) |
25
+ |---|---|---|---|---|
26
+ | Quality standards | Native | Native | Native | Reference only |
27
+ | Skills marketplace | Yes | Yes | Yes | No |
28
+ | MCP integration | Yes | Yes | Yes | No |
29
+ | Individual step execution | Yes | Yes | Via prompts | Manual |
30
+ | Full 12-step pipeline | Native | Via Portable Runner | No | No |
31
+ | YOLO mode | Native | Via Runner | No | No |
32
+ | State machine (state.json) | Native | Via Runner | No | No |
33
+ | Parallel epic orchestration | Yes | No | No | No |
34
+ | **Platforms** | Claude Code | Cursor, Gemini, Codex | VSCode, Antigravity | (future) |
35
+
36
+ ### Multi-Target Installation
37
+
38
+ The installer supports selecting multiple targets in a single run:
39
+
40
+ ```bash
41
+ # Interactive selection (checkbox UI)
42
+ npx @ornexus/synapse-cli
43
+
44
+ # Specific targets via flag
45
+ ./install.sh --targets claude-code,cursor,vscode
46
+
47
+ # Legacy mode (Claude Code only, backward compatible)
48
+ ./install.sh --yes
49
+ ```
50
+
51
+ ---
52
+
53
+ ## 🆕 Versao 3.4.1 - Guardrails de Terminacao de Workflow
54
+
55
+ ### Novidades da v3.4.1
56
+
57
+ #### STOP Boundary Enforcement nos Pontos Terminais
58
+
59
+ Guardrails explicitos nos pontos terminais de cada workflow para impedir que o LLM execute acoes alem do escopo:
60
+
61
+ | Ponto Terminal | Guardrail Adicionado |
62
+ |----------------|---------------------|
63
+ | `step-c-12-merge-pr` | Bloco `STOP OBRIGATORIO` proibindo acoes pos-pipeline |
64
+ | `step-p-03-generate-epic` | Bloco `STOP OBRIGATORIO` proibindo auto-implementacao de stories |
65
+ | `isolated-step-prompt.md` | Constraint 6: `TERMINATE AFTER RETURN` para subagentes |
66
+ | `isolated-step-executor.md` | DO NOT list expandida com proibicoes pos-pipeline |
67
+
68
+ **Problema resolvido:** Antes, o LLM podia "improvisar" apos concluir um workflow (ex: iniciar implementacao apos `*create-epic`, ou fazer refactors apos merge). Agora, cada ponto terminal tem instrucoes explicitas de PARAR.
69
+
70
+ ---
71
+
72
+ ## Versao 3.4.0 - Enforcement Programatico de Sequencia
73
+
74
+ ### Novidades da v3.4.0
75
+
76
+ #### Enforcement Real nos 12 Core Steps (Epic 11)
77
+
78
+ Todos os core steps agora possuem **gates programaticos reais** que impedem execucao fora de ordem — replicando o padrao robusto dos planning steps:
79
+
80
+ | Antes (v3.3.x) | Agora (v3.4.0) |
81
+ |----------------|----------------|
82
+ | Core steps dependiam do LLM seguir instrucoes Markdown | Core steps tem pre-check programatico com `jq` + `exit 1` |
83
+ | `validation.require_previous_step` era flag inerte | Flags do step-registry.json sao lidos e enforceados em runtime |
84
+ | `validate_step_sequence()` era documentacao em MD | `scripts/validate-step.sh` e executavel POSIX-compatible (202 linhas) |
85
+ | Sem validacao pos-step no orquestrador | Orquestrador valida state.json apos cada step completar |
86
+ | steps_completed podia ter gaps/duplicatas | Deteccao automatica de gaps e duplicatas com mensagens descritivas |
87
+
88
+ **Arquitetura de Defesa em Profundidade:**
89
+
90
+ ```
91
+ Pre-Check (lado do step) Post-Check (lado do orquestrador)
92
+ ═══════════════════════ ═════════════════════════════════
93
+ validate-step.sh Phase 4.1 + validate_post_step()
94
+ ├── Status correto? ├── Status atualizado corretamente?
95
+ ├── Step anterior completo? ├── step_id no steps_completed?
96
+ ├── Sem gaps? ├── Sem duplicatas? (auto-dedup)
97
+ └── exit 1 se falhar └── Marcar como blocked se falhar
98
+ ```
99
+
100
+ **Arquivos criados:** `scripts/validate-step.sh`
101
+ **Arquivos modificados:** Todos os 12 `steps-c/*.md`, `templates/isolated-step-prompt.md`, `data/state-utils.md`, `data/step-registry.json`
102
+
103
+ ---
104
+
105
+ ## Versao 3.3.1 - Pipeline Auto-Suficiente
106
+
107
+ ### Novidades da v3.3.1
108
+
109
+ #### Remocao da Dependencia do ONX Sentinel
110
+
111
+ O pipeline agora e **totalmente auto-suficiente** - sem dependencias externas quebradas:
112
+
113
+ | Antes (v3.3.0) | Agora (v3.3.1) |
114
+ |----------------|----------------|
115
+ | `*diagnose` chamava `/onx-sentinel *diagnose` | `*diagnose` usa Prompt Enricher + deep-analysis diretamente |
116
+ | `*research` chamava `/onx-sentinel *research` | `*research` usa Context7 + WebSearch diretamente |
117
+ | Sentinel nao tinha implementacao real | Pipeline executa 100% da logica internamente |
118
+ | Fallback manual necessario | Zero dependencias externas |
119
+
120
+ #### Documentacao de `*create-epic`
121
+
122
+ Pipeline de 3 steps: `diagnose idea` -> `research` -> `generate epic + stories`
123
+
124
+ ---
125
+
126
+ ## Versao 3.3.0 - Implementacao Inteligente Dual-Mode
127
+
128
+ ### Novidades da v3.3.0
129
+
130
+ #### Epic 10: Sistema de Implementacao Inteligente (principal)
131
+
132
+ O `*implement` agora escolhe **autonomamente** entre dois modos de execucao:
133
+
134
+ | Modo | Quando | O que faz |
135
+ |------|--------|-----------|
136
+ | **implement-tasks** | Stories simples (1-2 task groups, 1 dominio) | Delegacao direta a 1 implementer subagent |
137
+ | **orchestrate-tasks** | Stories complexas (3+ task groups, multi-dominio) | Orquestracao com subagentes especializados por task group |
138
+
139
+ **Como funciona:**
140
+
141
+ ```
142
+ *implement invocado
143
+ |
144
+ v
145
+ [FASE 0: Complexity Analyzer] ← 6 criterios ponderados
146
+ |
147
+ +---> Score < 1.5 --> implement-tasks (1 subagent)
148
+ |
149
+ +---> Score >= 1.5 --> orchestrate-tasks (multi-agent)
150
+ |
151
+ v (ambos convergem)
152
+ [PHASE 3: Implementation Verifier] ← agente independente, fresh eyes
153
+ |
154
+ v
155
+ [final-verification.md gerado]
156
+ ```
157
+
158
+ **Features do sistema dual-mode:**
159
+ - **Complexity Analyzer**: Scoring com 6 criterios (task groups, dominios, subtasks, dependencias, arquitetura, arquivos novos)
160
+ - **Threshold configuravel**: Default 1.5, ajustavel no `step-registry.json`
161
+ - **Override manual**: Via frontmatter da story (`implementMode: "orchestrate-tasks"`)
162
+ - **orchestration.yml**: Gerado automaticamente com subagentes e standards por task group
163
+ - **Implementation Verifier**: Agente independente com spot-check, test suite completa e report formal
164
+ - **final-verification.md**: Report estruturado com Executive Summary, Tasks, Docs, Tests
165
+
166
+ #### Epic 9: Fidelidade Total ao Agent-OS
167
+
168
+ Todos os steps do pipeline foram alinhados ao processo original do agent-os:
169
+ - **create-tasks**: Standards expandidos de 5 para 15, linguagem de compliance mandatoria
170
+ - **review-pr**: Standards e compliance language expandidos
171
+ - **sync-main, commit-push, create-pr**: IDs de step corrigidos e paths normalizados
172
+ - **state.json**: IDs corrigidos em todas as stories
173
+
174
+ #### Epic 8: Standards no Write-Spec
175
+
176
+ - Step `write-spec` agora referencia todos os 15 standards (era 5)
177
+ - Linguagem de compliance mandatoria ("MUST", "SHALL") em vez de sugestiva ("considerar")
178
+
179
+ ### Conformidade com Agent-OS
180
+
181
+ | Componente | v3.2.8 | v3.3.0 |
182
+ |-----------|--------|--------|
183
+ | `implement-tasks.md` | 80% | **98%** |
184
+ | `orchestrate-tasks.md` | 0% | **95%** |
185
+ | `implementation-verifier.md` | 20% | **95%** |
186
+ | Standards coverage | 5/15 | **15/15** |
187
+ | Compliance language | Sugestiva | **Mandatoria** |
188
+
189
+ ---
190
+
191
+ ### Versao 3.0.0 - state.json como Fonte Unica de Verdade
192
+
193
+ | Antes (v2.x) | Agora (v3.0+) |
194
+ |--------------|--------------|
195
+ | `orchestrator.db` (SQLite) | `state.json` (JSON) |
196
+ | `sprint-status.yaml` (YAML) | `state.json` (JSON) |
197
+ | SQLite3 como dependencia | jq como dependencia |
198
+ | Locking por transacoes SQL | File-based locking com noclobber |
199
+
200
+ **Beneficios:**
201
+ - Fonte Unica de Verdade em `state.json`
202
+ - Sem dependencia de SQLite (apenas `jq`)
203
+ - Paralelizacao segura com file-based locking
204
+ - Migracao automatica de projetos v2.x via `*init`
205
+
206
+ ---
207
+
208
+ ## 🚀 Quick Start (3 Passos)
209
+
210
+ ### Passo 1: Autenticar no GitHub Packages (uma vez por máquina)
211
+
212
+ ```bash
213
+ # Login no registry do GitHub
214
+ npm login --registry=https://npm.pkg.github.com
215
+ # Username: seu_usuario_github
216
+ # Password: seu_token_PAT (ghp_xxx)
217
+ # Email: seu_email
218
+
219
+ # Configurar registry
220
+ echo "@ornexus:registry=https://npm.pkg.github.com" >> ~/.npmrc
221
+ ```
222
+
223
+ > Veja a seção [Via GitHub Packages](#via-github-packages-recomendado) para criar o token PAT.
224
+
225
+ ### Passo 2: Instalar o Agente (uma vez por máquina)
226
+
227
+ ```bash
228
+ npx @ornexus/synapse-cli
229
+ ```
230
+
231
+ Isso instala os arquivos do agente em `~/.claude/agents/synapse-cli/`.
232
+ Quando perguntado "Deseja inicializar Synapse neste projeto?", responda **N** se quiser apenas instalar o agente.
233
+
234
+ ### Passo 3: Inicializar o Projeto (uma vez por projeto)
235
+
236
+ No diretório do seu projeto, abra o Claude Code e execute:
237
+
238
+ ```bash
239
+ @synapse-cli *init @docs/epics.md
240
+ ```
241
+
242
+ Isso cria a estrutura `.synapse-cli/` necessária para o funcionamento.
243
+
244
+ ---
245
+
246
+ ## 📦 Instalação
247
+
248
+ ### Pré-requisitos
249
+ - Node.js >= 18.0.0
250
+ - Git
251
+ - GitHub CLI (`gh`)
252
+ - jq
253
+ - Claude Code CLI (para MCPs)
254
+
255
+ ---
256
+
257
+ ## MCPs (Model Context Protocol)
258
+
259
+ O Synapse utiliza MCPs para estender as capacidades do Claude Code:
260
+
261
+ ### MCPs Utilizados
262
+
263
+ | MCP | Proposito | Instalacao Automatica |
264
+ |-----|-----------|----------------------|
265
+ | **Playwright** | Analise visual de codebase (projetos web) | Sim |
266
+ | **Context7** | Pesquisa de documentacao de bibliotecas | Sim (requer API key) |
267
+
268
+ ### Configuracao do Context7
269
+
270
+ O MCP Context7 requer uma API key para funcionar. Para obter:
271
+
272
+ 1. Acesse [context7.com](https://context7.com)
273
+ 2. Crie uma conta ou faca login
274
+ 3. Gere uma API key no dashboard
275
+
276
+ ### Instalacao com Context7
277
+
278
+ **Linux/macOS:**
279
+ ```bash
280
+ export CONTEXT7_API_KEY="ctx7sk-xxxx-xxxx-xxxx"
281
+ npx synapse-cli
282
+ ```
283
+
284
+ **Windows (PowerShell):**
285
+ ```powershell
286
+ $env:CONTEXT7_API_KEY = "ctx7sk-xxxx-xxxx-xxxx"
287
+ npx synapse-cli
288
+ ```
289
+
290
+ ### Instalacao Manual de MCPs
291
+
292
+ Se preferir instalar manualmente:
293
+
294
+ ```bash
295
+ # Playwright
296
+ claude mcp add playwright npx @playwright/mcp@latest
297
+
298
+ # Context7
299
+ claude mcp add --transport http context7 https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY: sua-chave-aqui"
300
+ ```
301
+
302
+ ### Verificar MCPs Instalados
303
+
304
+ ```bash
305
+ claude mcp list
306
+ ```
307
+
308
+ ### Troubleshooting
309
+
310
+ **Claude CLI nao encontrado:**
311
+ - Instale o Claude Code: `npm install -g @anthropic-ai/claude-code`
312
+ - Ou os MCPs serao instalados na primeira execucao do Claude Code
313
+
314
+ **MCP Playwright falhou:**
315
+ - Verifique se Node.js esta instalado
316
+ - Tente instalar manualmente: `claude mcp add playwright npx @playwright/mcp@latest`
317
+
318
+ **MCP Context7 nao instalado:**
319
+ - Verifique se CONTEXT7_API_KEY esta definida
320
+ - A API key deve comecar com `ctx7sk-`
321
+
322
+ **Workflows funcionando com fallbacks:**
323
+ - O Synapse funciona mesmo sem MCPs
324
+ - Playwright fallback: Analise estatica via Task tool
325
+ - Context7 fallback: WebSearch para documentacao
326
+
327
+ ---
328
+
329
+ ### Via GitHub Packages (recomendado)
330
+
331
+ O pacote está hospedado no GitHub Packages como `@ornexus/synapse-cli`.
332
+
333
+ #### Passo 1: Criar Personal Access Token (PAT)
334
+
335
+ 1. Acesse: https://github.com/settings/tokens
336
+ 2. Clique em **"Generate new token (classic)"**
337
+ 3. Marque a permissão: `read:packages`
338
+ 4. Clique em **"Generate token"**
339
+ 5. **Copie o token** (formato: `ghp_xxxxxxxxxxxx`) - ele não será mostrado novamente!
340
+
341
+ #### Passo 2: Autenticar no GitHub Packages
342
+
343
+ Execute no terminal:
344
+
345
+ ```bash
346
+ npm login --registry=https://npm.pkg.github.com
347
+ ```
348
+
349
+ Quando solicitado, informe:
350
+
351
+ | Campo | Valor |
352
+ |-------|-------|
353
+ | **Username** | Seu usuário do GitHub (ex: `joaosilva`) |
354
+ | **Password** | O token PAT copiado (ex: `ghp_abc123...`) |
355
+ | **Email** | Seu email do GitHub |
356
+
357
+ > **Nota:** A senha é o **token PAT**, não sua senha do GitHub!
358
+
359
+ #### Passo 3: Configurar Registry
360
+
361
+ ```bash
362
+ echo "@ornexus:registry=https://npm.pkg.github.com" >> ~/.npmrc
363
+ ```
364
+
365
+ #### Passo 4: Instalar
366
+
367
+ ```bash
368
+ npx @ornexus/synapse-cli
369
+ ```
370
+
371
+ Isso instala o agente em `~/.claude/agents/synapse-cli/`.
372
+
373
+ #### Verificar Instalação
374
+
375
+ ```bash
376
+ ls ~/.claude/agents/synapse-cli/
377
+ ```
378
+
379
+ Deve mostrar: `synapse-cli.md`, `steps-c/`, `steps-e/`, `steps-p/`, etc.
380
+
381
+ ### Via Git (alternativa)
382
+ ```bash
383
+ git clone https://github.com/OrNexus-AI/synapse_cli ~/.claude/agents/synapse-cli
384
+ cd ~/.claude/agents/synapse-cli
385
+ ./install.sh
386
+ ```
387
+
388
+ ### O que cada método faz
389
+
390
+ | Método | O que instala | Onde |
391
+ |--------|---------------|------|
392
+ | `npm install @ornexus/synapse-cli` | Agente `@synapse-cli` | `~/.claude/` (usuário) |
393
+ | `@synapse-cli *init` | Configuração do projeto | `.synapse-cli/` (projeto) |
394
+
395
+ ---
396
+
397
+ ## ⚠️ Importante: Dois Níveis de Instalação
398
+
399
+ ```
400
+ ~/.claude/ ← AGENTE (compartilhado entre projetos)
401
+ └── agents/synapse-cli/
402
+ ├── synapse-cli.md
403
+ ├── steps-c/*.md
404
+ └── ...
405
+
406
+ /seu/projeto/ ← DADOS (específico do projeto)
407
+ ├── .synapse-cli/
408
+ │ ├── config.yaml ← Configurações do projeto
409
+ │ └── state.json ← Estado das stories/epics (fonte única de verdade)
410
+ └── docs/
411
+ ├── epics.md ← Definição dos epics
412
+ └── stories/ ← Arquivos de story
413
+ ```
414
+
415
+ **Sem executar `@synapse-cli *init` no projeto**, o agente não funcionará porque não encontrará os arquivos de configuração.
416
+
417
+ ---
418
+
419
+ ## Uso
420
+
421
+ ```bash
422
+ # Processar uma story específica
423
+ @synapse-cli @docs/stories/1.1.story.md
424
+
425
+ # Orquestrar um epic inteiro (paralelo)
426
+ @synapse-cli @epic-1
427
+
428
+ # Criar epic a partir de uma ideia
429
+ @synapse-cli *create-epic "COMO dev, QUERO X, PARA Y"
430
+
431
+ # Modo YOLO (sem confirmacoes)
432
+ @synapse-cli *yolo @docs/stories/5.1.story.md
433
+
434
+ # Inicializar novo projeto
435
+ @synapse-cli *init @docs/epics.md
436
+
437
+ # Ver status do pipeline
438
+ @synapse-cli *status
439
+ ```
440
+
441
+ ## Arquitetura
442
+
443
+ ### 12 Core Steps
444
+
445
+ | # | Step | Status Apos | Descricao |
446
+ |---|------|-------------|-----------|
447
+ | 01 | setup-branch | `branch-ready` | Criar branch e worktree |
448
+ | 02 | diagnose | `diagnose` | Analisar requisitos |
449
+ | 03 | research | `research` | Pesquisar solucoes |
450
+ | 04 | write-spec | `write-spec` | Escrever especificacao |
451
+ | 05 | create-tasks | `create-tasks` | Criar lista de tasks |
452
+ | 06 | implement-tasks | `implemented` | Implementar codigo (dual-mode: implement-tasks / orchestrate-tasks) |
453
+ | 07 | update-memory | `memory-updated` | Atualizar CLAUDE.md com padroes |
454
+ | 08 | commit-push | `committed` | Commit e push |
455
+ | 09 | sync-main | `synced` | Sincronizar com main |
456
+ | 10 | create-pr | `pr-created` | Criar Pull Request |
457
+ | 11 | review-pr | `pr-reviewed` | Code review |
458
+ | 12 | merge-pr | `done` | Merge e cleanup |
459
+
460
+ ### Categorias de Steps
461
+
462
+ - **Core (`steps-c/`)**: Sequencia principal de 12 steps
463
+ - **Planning (`steps-p/`)**: Criacao de epics a partir de ideias (3 steps: diagnose, research, generate)
464
+ - **Epic (`steps-e/`)**: Orquestracao paralela de epics
465
+ - **Recovery (`steps-r/`)**: Tratamento de bloqueios
466
+ - **Utility (`steps-u/`)**: Manutencao standalone
467
+
468
+ ### Standards Internos
469
+
470
+ O framework inclui 15 arquivos de standards para garantir qualidade:
471
+
472
+ ```
473
+ standards/
474
+ ├── backend/
475
+ │ ├── api.md
476
+ │ ├── migrations.md
477
+ │ ├── models.md
478
+ │ └── queries.md
479
+ ├── frontend/
480
+ │ ├── accessibility.md
481
+ │ ├── components.md
482
+ │ ├── css.md
483
+ │ └── responsive.md
484
+ ├── global/
485
+ │ ├── coding-style.md
486
+ │ ├── commenting.md
487
+ │ ├── conventions.md
488
+ │ ├── error-handling.md
489
+ │ ├── tech-stack.md
490
+ │ └── validation.md
491
+ └── testing/
492
+ └── test-writing.md
493
+ ```
494
+
495
+ ## Configuração
496
+
497
+ Após instalar, o arquivo `.synapse-cli/config.yaml` controla o comportamento:
498
+
499
+ ```yaml
500
+ project:
501
+ name: "Meu Projeto"
502
+ default_branch: "main"
503
+
504
+ git:
505
+ worktree_base: ".worktrees"
506
+ epic_branch_pattern: "epic-{epic_id}"
507
+ story_branch_pattern: "story-{story_id}"
508
+
509
+ orchestration:
510
+ max_parallel_stories: 3
511
+ yolo_mode: false # Auto-retry sem confirmações
512
+ auto_merge: false
513
+ ```
514
+
515
+ ## Modos de Execução
516
+
517
+ ### Modo 1: Sequência Completa (Padrão)
518
+ ```bash
519
+ @synapse-cli @docs/stories/5.1.story.md
520
+ ```
521
+
522
+ ### Modo 2: Step Específico
523
+ ```bash
524
+ @synapse-cli *diagnose @docs/stories/5.1.story.md
525
+ ```
526
+
527
+ ### Modo 3: Recovery
528
+ ```bash
529
+ @synapse-cli *fix-blocked @docs/stories/5.1.story.md
530
+ ```
531
+
532
+ ### Modo 4: Utilitário
533
+ ```bash
534
+ @synapse-cli *cleanup-branches
535
+ @synapse-cli *audit-status
536
+ ```
537
+
538
+ ### Modo 5: Epic Paralelo
539
+ ```bash
540
+ @synapse-cli @epic-6
541
+ ```
542
+
543
+ ### Modo 6: Inicialização
544
+ ```bash
545
+ @synapse-cli *init @docs/epics.md
546
+ ```
547
+
548
+ ### Modo 7: Criar Epic
549
+ ```bash
550
+ @synapse-cli *create-epic "COMO dev, QUERO autenticacao JWT, PARA proteger rotas da API"
551
+ ```
552
+
553
+ ## YOLO Mode
554
+
555
+ O modo YOLO (`yolo_mode: true`) permite execução sem confirmações, com auto-retry em stories bloqueadas (até 3x).
556
+
557
+ **⚠️ IMPORTANTE:** YOLO mode NÃO pula steps - todos os 12 steps são sempre executados.
558
+
559
+ ## Requisitos
560
+
561
+ - Claude Code CLI
562
+ - Git
563
+ - GitHub CLI (`gh`)
564
+ - jq (para manipulação de JSON)
565
+
566
+ ## Estrutura de Arquivos
567
+
568
+ ```
569
+ synapse-cli/
570
+ ├── synapse-cli.md # Agente principal
571
+ ├── synapse-cli.agent.yaml # Configuração do agente
572
+ ├── workflow.md # Documentação do workflow
573
+ ├── install.sh # Script de instalação
574
+ ├── package.json # Metadados npm
575
+ ├── README.md # Este arquivo
576
+ ├── scripts/ # Scripts executaveis
577
+ │ └── validate-step.sh # Gate de validacao de sequencia (POSIX)
578
+ ├── steps-c/ # 12 core steps (com pre-check programatico)
579
+ ├── steps-p/ # 3 planning steps (create-epic)
580
+ ├── steps-e/ # Steps de epic
581
+ ├── steps-r/ # Steps de recovery
582
+ ├── steps-u/ # Steps utilitarios
583
+ ├── standards/ # 15 arquivos de standards
584
+ └── data/ # Templates e dados
585
+ ```
586
+
587
+ ## Para Desenvolvedores
588
+
589
+ ### Publicar no GitHub Packages
590
+
591
+ ```bash
592
+ # 1. Configurar token (primeira vez)
593
+ export NPM_TOKEN=ghp_seu_token_com_write_packages
594
+
595
+ # 2. Verificar o que será publicado
596
+ npm pack --dry-run
597
+
598
+ # 3. Publicar
599
+ npm publish
600
+
601
+ # 4. Atualizar versão e republicar
602
+ npm version patch # 3.1.9 → 3.1.10
603
+ npm version minor # 3.1.9 → 3.2.0
604
+ npm version major # 3.1.9 → 4.0.0
605
+ npm publish
606
+ ```
607
+
608
+ ### Testar Localmente
609
+
610
+ ```bash
611
+ # Simular instalação
612
+ npm link
613
+ synapse-cli
614
+
615
+ # Remover link
616
+ npm unlink
617
+ ```
618
+
619
+ ### Estrutura do Pacote
620
+
621
+ ```
622
+ @ornexus/synapse-cli
623
+ ├── bin: synapse-cli → install.sh
624
+ ├── files: 66 arquivos (steps, standards, data)
625
+ ├── engines: node >= 18.0.0
626
+ └── publishConfig: restricted, registry npm.pkg.github.com
627
+ ```
628
+
629
+ ## Licença
630
+
631
+ Este projeto é licenciado sob a **Functional Source License, Version 1.1 (FSL-1.1)** com Delayed Open Source Publication (DOSP).
632
+
633
+ ### O que isso significa?
634
+
635
+ | Aspecto | Detalhe |
636
+ |---------|--------|
637
+ | **Licença atual** | FSL-1.1 — uso permitido para qualquer finalidade, exceto competir diretamente com os produtos comerciais da OrNexus AI |
638
+ | **Data de mudança** | 20 de fevereiro de 2029 |
639
+ | **Licença futura** | MIT — após a data de mudança, o código será disponibilizado sob a licença MIT, sem restrições |
640
+ | **Uso pessoal** | ✅ Totalmente permitido |
641
+ | **Uso comercial interno** | ✅ Permitido (desde que não seja um produto concorrente) |
642
+ | **Redistribuição** | ✅ Permitida com a mesma licença |
643
+ | **Produto concorrente** | ❌ Requer permissão explícita da OrNexus AI |
644
+
645
+ Para detalhes completos, consulte o arquivo [LICENSE](./LICENSE).
646
+
647
+ Para mais informações sobre a Functional Source License: [fsl.software](https://fsl.software/) | [fair.io](https://fair.io/)
648
+
649
+ ## Contribuindo
650
+
651
+ 1. Fork o repositório
652
+ 2. Crie uma branch (`git checkout -b feature/nova-feature`)
653
+ 3. Commit suas mudanças (`git commit -m 'feat: adiciona nova feature'`)
654
+ 4. Push para a branch (`git push origin feature/nova-feature`)
655
+ 5. Abra um Pull Request
656
+
657
+ ---
658
+
659
+ Desenvolvido com ⚡ por OrNexus Team
660
+
661
+ [![GitHub Package](https://img.shields.io/badge/GitHub%20Packages-@ornexus--ai%2Fonx--synapse-blue)](https://github.com/OrNexus-AI/synapse_cli/packages)
662
+ [![License: FSL-1.1](https://img.shields.io/badge/License-FSL--1.1-green.svg)](./LICENSE)