onx-synapse

v3.1.8

Published

13 days ago

ONX Synapse v3.1.8 - Orquestrador de Desenvolvimento de Epics & Stories para Claude Code

⚡ 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

O que mudou

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

Benefícios da v3.0

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)

Migração de Projetos Existentes

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

# 1. Atualize o agente
npx onx-synapse

# 2. No projeto, reinicialize (migração automática)
@onx-synapse *init @docs/epics.md

O sistema automaticamente:

Detecta arquivos antigos (orchestrator.db, sprint-status.yaml)
Move-os para .onx-synapse/backup/
Cria novo state.json com dados migrados
Registra a migração no state.json

🚀 Quick Start (2 Passos)

Passo 1: Instalar o Agente (uma vez por máquina)

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.

Passo 2: Inicializar o Projeto (uma vez por projeto)

No diretório do seu projeto, abra o Claude Code e execute:

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

Isso cria a estrutura .onx-synapse/ necessária para o funcionamento.

📦 Instalação Detalhada

O que cada método faz

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

Via NPX (recomendado)

npx onx-synapse

Via NPM Global

npm install -g onx-synapse
onx-synapse

Manual

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

# 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

11 Core Steps

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

Categorias de Steps

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

Standards Internos

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:

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

Modo 1: Sequência Completa (Padrão)

@onx-synapse @docs/stories/5.1.story.md

Modo 2: Step Específico

@onx-synapse *diagnose @docs/stories/5.1.story.md

Modo 3: Recovery

@onx-synapse *fix-blocked @docs/stories/5.1.story.md

Modo 4: Utilitário

@onx-synapse *cleanup-branches
@onx-synapse *audit-status

Modo 5: Epic Paralelo

@onx-synapse @epic-6

Modo 6: Inicialização

@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

Publicar no NPM

# 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

Testar Localmente

# Simular instalação via npx
npm link
npx onx-synapse

# Remover link
npm unlink

Estrutura do Pacote

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

Fork o repositório
Crie uma branch (git checkout -b feature/nova-feature)
Commit suas mudanças (git commit -m 'feat: adiciona nova feature')
Push para a branch (git push origin feature/nova-feature)
Abra um Pull Request

Desenvolvido com ⚡ por OrNexus Team