ONX Synapse v3.1.8 - Orquestrador de Desenvolvimento de Epics & Stories para Claude Code
npm install onx-synapseOrquestrador de Desenvolvimento de Epics & Stories para Claude Code
ONX Synapse é um framework standalone que automatiza o ciclo completo de desenvolvimento de software - do setup de branch até o merge do PR - através de 11 steps estruturados.
---
| Antes (v2.x) | Agora (v3.0) |
|--------------|--------------|
| orchestrator.db (SQLite) | state.json (JSON) |
| sprint-status.yaml (YAML) | state.json (JSON) |
| SQLite3 como dependência | jq como dependência |
| Locking por transações SQL | File-based locking com noclobber |
- Fonte Única de Verdade: Todo o estado em um único arquivo state.json
- Sem Dependência de SQLite: Apenas jq é necessário para manipulação de JSON
- Paralelização Segura: Sistema de lock baseado em arquivo para execução paralela de stories
- Migração Automática: Projetos existentes são migrados automaticamente ao executar *init
- Transparência: Estado legível em texto (JSON vs banco binário)
Se você tem projetos usando v2.x com orchestrator.db ou sprint-status.yaml:
``bash1. Atualize o agente
npx onx-synapse
O sistema automaticamente:
1. Detecta arquivos antigos (
orchestrator.db, sprint-status.yaml)
2. Move-os para .onx-synapse/backup/
3. Cria novo state.json com dados migrados
4. Registra a migração no state.json---
🚀 Quick Start (2 Passos)
$3
`bash
npx onx-synapse
`Isso instala os arquivos do agente em
~/.claude/ (nível de usuário).
Quando perguntado "Deseja inicializar ONX Synapse neste projeto?", responda N se quiser apenas instalar o agente.$3
No diretório do seu projeto, abra o Claude Code e execute:
`bash
@onx-synapse *init @docs/epics.md
`Isso cria a estrutura
.onx-synapse/ necessária para o funcionamento.---
📦 Instalação Detalhada
$3
| Método | O que instala | Onde |
|--------|---------------|------|
|
npx onx-synapse | Agente @onx-synapse | ~/.claude/ (usuário) |
| @onx-synapse *init | Configuração do projeto | .onx-synapse/ (projeto) |$3
`bash
npx onx-synapse
`$3
`bash
npm install -g onx-synapse
onx-synapse
`$3
`bash
git clone https://github.com/ornexus-ai/onx-synapse ~/.claude/agents/onx-synapse
cd ~/.claude/agents/onx-synapse
./install.sh
`---
⚠️ Importante: Dois Níveis de Instalação
`
~/.claude/ ← AGENTE (compartilhado entre projetos)
└── agents/onx-synapse/
├── onx-synapse.md
├── steps-c/*.md
└── .../seu/projeto/ ← DADOS (específico do projeto)
├── .onx-synapse/
│ ├── config.yaml ← Configurações do projeto
│ └── state.json ← Estado das stories/epics (fonte única de verdade)
└── docs/
├── epics.md ← Definição dos epics
└── stories/ ← Arquivos de story
`Sem executar
@onx-synapse *init no projeto, o agente não funcionará porque não encontrará os arquivos de configuração.---
Uso
`bash
Processar uma story específica
@onx-synapse @docs/stories/1.1.story.mdOrquestrar um epic inteiro (paralelo)
@onx-synapse @epic-1Inicializar novo projeto
@onx-synapse *init @docs/epics.mdVer status do pipeline
@onx-synapse *status
`Arquitetura
$3
| # | Step | Status Após | Descrição |
|---|------|-------------|-----------|
| 01 | setup-branch |
branch-ready | Criar branch e worktree |
| 02 | diagnose | diagnose | Analisar requisitos |
| 03 | research-fix | research-fix | Pesquisar soluções |
| 04 | write-spec | write-spec | Escrever especificação |
| 05 | create-tasks | create-tasks | Criar lista de tasks |
| 06 | implement-tasks | implemented | Implementar código |
| 07 | commit-push | committed | Commit e push |
| 08 | sync-main | synced | Sincronizar com main |
| 09 | create-pr | pr-created | Criar Pull Request |
| 10 | review-pr | pr-reviewed | Code review |
| 11 | merge-pr | done | Merge e cleanup |$3
- Core (
steps-c/): Sequência principal de 11 steps
- Epic (steps-e/): Orquestração paralela de epics
- Recovery (steps-r/): Tratamento de bloqueios
- Utility (steps-u/): Manutenção standalone$3
O framework inclui 15 arquivos de standards para garantir qualidade:
`
standards/
├── backend/
│ ├── api.md
│ ├── migrations.md
│ ├── models.md
│ └── queries.md
├── frontend/
│ ├── accessibility.md
│ ├── components.md
│ ├── css.md
│ └── responsive.md
├── global/
│ ├── coding-style.md
│ ├── commenting.md
│ ├── conventions.md
│ ├── error-handling.md
│ ├── tech-stack.md
│ └── validation.md
└── testing/
└── test-writing.md
`Configuração
Após instalar, o arquivo
.onx-synapse/config.yaml controla o comportamento:`yaml
project:
name: "Meu Projeto"
default_branch: "main"git:
worktree_base: ".worktrees"
epic_branch_pattern: "epic-{epic_id}"
story_branch_pattern: "story-{story_id}"
orchestration:
max_parallel_stories: 3
yolo_mode: false # Auto-retry sem confirmações
auto_merge: false
`Modos de Execução
$3
`bash
@onx-synapse @docs/stories/5.1.story.md
`$3
`bash
@onx-synapse *diagnose @docs/stories/5.1.story.md
`$3
`bash
@onx-synapse *fix-blocked @docs/stories/5.1.story.md
`$3
`bash
@onx-synapse *cleanup-branches
@onx-synapse *audit-status
`$3
`bash
@onx-synapse @epic-6
`$3
`bash
@onx-synapse *init @docs/epics.md
`YOLO Mode
O modo YOLO (
yolo_mode: true) permite execução sem confirmações, com auto-retry em stories bloqueadas (até 3x).⚠️ IMPORTANTE: YOLO mode NÃO pula steps - todos os 12 steps são sempre executados.
Requisitos
- Claude Code CLI
- Git
- GitHub CLI (
gh)
- jq (para manipulação de JSON)Estrutura de Arquivos
`
onx-synapse/
├── onx-synapse.md # Agente principal
├── onx-synapse.agent.yaml # Configuração do agente
├── workflow.md # Documentação do workflow
├── install.sh # Script de instalação
├── package.json # Metadados npm
├── README.md # Este arquivo
├── steps-c/ # 12 core steps
├── steps-e/ # Steps de epic
├── steps-r/ # Steps de recovery
├── steps-u/ # Steps utilitários
├── standards/ # 15 arquivos de standards
└── data/ # Templates e dados
`Para Desenvolvedores
$3
`bash
1. Login no NPM (primeira vez)
npm login2. Verificar o que será publicado
npm pack --dry-run3. Publicar
npm publish --access public4. Atualizar versão e republicar
npm version patch # 2.2.0 → 2.2.1
npm version minor # 2.2.0 → 2.3.0
npm version major # 2.2.0 → 3.0.0
npm publish
`$3
`bash
Simular instalação via npx
npm link
npx onx-synapseRemover link
npm unlink
`$3
`
onx-synapse
├── bin: onx-synapse → install.sh
├── files: 50+ arquivos (steps, standards, data)
├── engines: node >= 18.0.0
└── publishConfig: public, registry npmjs.org
`Licença
MIT
Contribuindo
1. Fork o repositório
2. Crie uma branch (
git checkout -b feature/nova-feature)
3. Commit suas mudanças (git commit -m 'feat: adiciona nova feature')
4. Push para a branch (git push origin feature/nova-feature`)---
Desenvolvido com ⚡ por OrNexus Team

