@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/.env.example +18 -0
- package/LICENSE +127 -0
- package/README.md +662 -0
- package/install.js +323 -0
- package/package.json +111 -0
- package/sync-version.js +186 -0
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
|
+
[](https://github.com/OrNexus-AI/synapse_cli/packages)
|
|
662
|
+
[](./LICENSE)
|