⚡ ONX Synapse

Orquestrador 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.

---

🆕 Versão 3.0.0 - state.json como Fonte Única de Verdade

$3

| 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 |

$3

- 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)

$3

Se você tem projetos usando v2.x com orchestrator.db ou sprint-status.yaml:

``bash


1. Atualize o agente

npx onx-synapse

2. No projeto, reinicialize (migração automática)

@onx-synapse *init @docs/epics.md
`

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.md

Orquestrar um epic inteiro (paralelo)

@onx-synapse @epic-1

Inicializar novo projeto

@onx-synapse *init @docs/epics.md

Ver 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 login

2. Verificar o que será publicado

npm pack --dry-run

3. Publicar

npm publish --access public

4. 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-synapse

Remover 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`)
5. Abra um Pull Request

---

Desenvolvido com ⚡ por OrNexus Team