⚡ Neocortex

Orquestrador de Desenvolvimento de Epics & Stories - Multi-Platform

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

Supported Platforms

Neocortex suporta 6 plataformas organizadas em 4 tiers de suporte:

| Platform | Tier | Install Command | Key Features | README | |---|---|---|---|---| | Claude Code | Tier 1 (Full Pipeline) | npx @ornexus/neocortex-cli | 12-step pipeline, YOLO mode, parallel epics, state machine | targets/claude-code/ | | Cursor IDE | Tier 2 (CLI Pipeline) | ./install.sh --targets cursor | .mdc rules, slash commands, pipeline via runner | targets/cursor/ | | Gemini CLI | Tier 2 (CLI Pipeline) | ./install.sh --targets gemini-cli | TOML commands, GEMINI.md, headless execution, 1M context | targets/gemini-cli/ | | Codex CLI | Tier 2 (CLI Pipeline) | ./install.sh --targets codex | Named profiles, exec resume, OS sandbox, self-as-MCP | targets/codex/ | | VSCode/Copilot | Tier 3 (Agent-Directed) | ./install.sh --targets vscode | .instructions.md, prompt files, per-file standards | targets/vscode/ | | Antigravity | Tier 3 (Agent-Directed) | ./install.sh --targets antigravity | SKILL.md, rules, workflows, // turbo | targets/antigravity/ |

Tier Support Matrix

| Capability | Tier 1 (Full) | Tier 2 (CLI) | Tier 3 (Agent) | Tier 4 (Manual) | |---|---|---|---|---| | Quality standards | Native | Native | Native | Reference only | | Skills marketplace | Yes | Yes | Yes | No | | MCP integration | Yes | Yes | Yes | No | | Individual step execution | Yes | Yes | Via prompts | Manual | | Full 12-step pipeline | Native | Via Portable Runner | No | No | | YOLO mode | Native | Via Runner | No | No | | State machine (state.json) | Native | Via Runner | No | No | | Parallel epic orchestration | Yes | No | No | No | | Platforms | Claude Code | Cursor, Gemini, Codex | VSCode, Antigravity | (future) |

Multi-Target Installation

The installer supports selecting multiple targets in a single run:

# Interactive selection (checkbox UI)
npx @ornexus/neocortex-cli

# Specific targets via flag
./install.sh --targets claude-code,cursor,vscode

# Legacy mode (Claude Code only, backward compatible)
./install.sh --yes

🆕 Versao 3.4.1 - Guardrails de Terminacao de Workflow

Novidades da v3.4.1

STOP Boundary Enforcement nos Pontos Terminais

Guardrails explicitos nos pontos terminais de cada workflow para impedir que o LLM execute acoes alem do escopo:

| Ponto Terminal | Guardrail Adicionado | |----------------|---------------------| | step-c-12-merge-pr | Bloco STOP OBRIGATORIO proibindo acoes pos-pipeline | | step-p-03-generate-epic | Bloco STOP OBRIGATORIO proibindo auto-implementacao de stories | | isolated-step-prompt.md | Constraint 6: TERMINATE AFTER RETURN para subagentes | | isolated-step-executor.md | DO NOT list expandida com proibicoes pos-pipeline |

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.

Versao 3.4.0 - Enforcement Programatico de Sequencia

Novidades da v3.4.0

Enforcement Real nos 12 Core Steps (Epic 11)

Todos os core steps agora possuem gates programaticos reais que impedem execucao fora de ordem — replicando o padrao robusto dos planning steps:

| Antes (v3.3.x) | Agora (v3.4.0) | |----------------|----------------| | Core steps dependiam do LLM seguir instrucoes Markdown | Core steps tem pre-check programatico com jq + exit 1 | | validation.require_previous_step era flag inerte | Flags do step-registry.json sao lidos e enforceados em runtime | | validate_step_sequence() era documentacao em MD | scripts/validate-step.sh e executavel POSIX-compatible (202 linhas) | | Sem validacao pos-step no orquestrador | Orquestrador valida state.json apos cada step completar | | steps_completed podia ter gaps/duplicatas | Deteccao automatica de gaps e duplicatas com mensagens descritivas |

Arquitetura de Defesa em Profundidade:

Pre-Check (lado do step)        Post-Check (lado do orquestrador)
═══════════════════════         ═════════════════════════════════
validate-step.sh                Phase 4.1 + validate_post_step()
  ├── Status correto?           ├── Status atualizado corretamente?
  ├── Step anterior completo?   ├── step_id no steps_completed?
  ├── Sem gaps?                 ├── Sem duplicatas? (auto-dedup)
  └── exit 1 se falhar          └── Marcar como blocked se falhar

Arquivos criados: scripts/validate-step.sh Arquivos modificados: Todos os 12 steps-c/*.md, templates/isolated-step-prompt.md, data/state-utils.md, data/step-registry.json

Versao 3.3.1 - Pipeline Auto-Suficiente

Novidades da v3.3.1

Remocao da Dependencia do ONX Sentinel

O pipeline agora e totalmente auto-suficiente - sem dependencias externas quebradas:

| Antes (v3.3.0) | Agora (v3.3.1) | |----------------|----------------| | *diagnose chamava /onx-sentinel *diagnose | *diagnose usa Prompt Enricher + deep-analysis diretamente | | *research chamava /onx-sentinel *research | *research usa Context7 + WebSearch diretamente | | Sentinel nao tinha implementacao real | Pipeline executa 100% da logica internamente | | Fallback manual necessario | Zero dependencias externas |

Documentacao de *create-epic

Pipeline de 3 steps: diagnose idea -> research -> generate epic + stories

Versao 3.3.0 - Implementacao Inteligente Dual-Mode

Novidades da v3.3.0

Epic 10: Sistema de Implementacao Inteligente (principal)

O *implement agora escolhe autonomamente entre dois modos de execucao:

| Modo | Quando | O que faz | |------|--------|-----------| | implement-tasks | Stories simples (1-2 task groups, 1 dominio) | Delegacao direta a 1 implementer subagent | | orchestrate-tasks | Stories complexas (3+ task groups, multi-dominio) | Orquestracao com subagentes especializados por task group |

Como funciona:

*implement invocado
       |
       v
[FASE 0: Complexity Analyzer]  ← 6 criterios ponderados
       |
       +---> Score < 1.5 --> implement-tasks (1 subagent)
       |
       +---> Score >= 1.5 --> orchestrate-tasks (multi-agent)
       |
       v (ambos convergem)
[PHASE 3: Implementation Verifier]  ← agente independente, fresh eyes
       |
       v
[final-verification.md gerado]

Features do sistema dual-mode:

• Complexity Analyzer: Scoring com 6 criterios (task groups, dominios, subtasks, dependencias, arquitetura, arquivos novos)
• Threshold configuravel: Default 1.5, ajustavel no step-registry.json
• Override manual: Via frontmatter da story (implementMode: "orchestrate-tasks")
• orchestration.yml: Gerado automaticamente com subagentes e standards por task group
• Implementation Verifier: Agente independente com spot-check, test suite completa e report formal
• final-verification.md: Report estruturado com Executive Summary, Tasks, Docs, Tests

Epic 9: Fidelidade Total ao Agent-OS

Todos os steps do pipeline foram alinhados ao processo original do agent-os:

• create-tasks: Standards expandidos de 5 para 15, linguagem de compliance mandatoria
• review-pr: Standards e compliance language expandidos
• sync-main, commit-push, create-pr: IDs de step corrigidos e paths normalizados
• state.json: IDs corrigidos em todas as stories

Epic 8: Standards no Write-Spec

• Step write-spec agora referencia todos os 15 standards (era 5)
• Linguagem de compliance mandatoria ("MUST", "SHALL") em vez de sugestiva ("considerar")

Conformidade com Agent-OS

| Componente | v3.2.8 | v3.3.0 | |-----------|--------|--------| | implement-tasks.md | 80% | 98% | | orchestrate-tasks.md | 0% | 95% | | implementation-verifier.md | 20% | 95% | | Standards coverage | 5/15 | 15/15 | | Compliance language | Sugestiva | Mandatoria |

Versao 3.0.0 - state.json como Fonte Unica de Verdade

| Antes (v2.x) | Agora (v3.0+) | |--------------|--------------| | orchestrator.db (SQLite) | state.json (JSON) | | sprint-status.yaml (YAML) | state.json (JSON) | | SQLite3 como dependencia | jq como dependencia | | Locking por transacoes SQL | File-based locking com noclobber |

Beneficios:

• Fonte Unica de Verdade em state.json
• Sem dependencia de SQLite (apenas jq)
• Paralelizacao segura com file-based locking
• Migracao automatica de projetos v2.x via *init

🚀 Quick Start (3 Passos)

Passo 1: Autenticar no GitHub Packages (uma vez por máquina)

# Login no registry do GitHub
npm login --registry=https://npm.pkg.github.com
# Username: seu_usuario_github
# Password: seu_token_PAT (ghp_xxx)
# Email: seu_email

# Configurar registry
echo "@ornexus:registry=https://npm.pkg.github.com" >> ~/.npmrc

Veja a seção Via GitHub Packages para criar o token PAT.

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

npx @ornexus/neocortex-cli

Isso instala os arquivos do agente em ~/.claude/agents/neocortex-cli/. Quando perguntado "Deseja inicializar Neocortex neste projeto?", responda N se quiser apenas instalar o agente.

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

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

@neocortex-cli *init @docs/epics.md

Isso cria a estrutura .neocortex-cli/ necessária para o funcionamento.

📦 Instalação

Pré-requisitos

• Node.js >= 18.0.0
• Git
• GitHub CLI (gh)
• jq
• Claude Code CLI (para MCPs)

MCPs (Model Context Protocol)

O Neocortex utiliza MCPs para estender as capacidades do Claude Code:

MCPs Utilizados

| MCP | Proposito | Instalacao Automatica | |-----|-----------|----------------------| | Playwright | Analise visual de codebase (projetos web) | Sim | | Context7 | Pesquisa de documentacao de bibliotecas | Sim (requer API key) |

Configuracao do Context7

O MCP Context7 requer uma API key para funcionar. Para obter:

1. Acesse context7.com
2. Crie uma conta ou faca login
3. Gere uma API key no dashboard

Instalacao com Context7

Linux/macOS:

export CONTEXT7_API_KEY="ctx7sk-xxxx-xxxx-xxxx"
npx neocortex-cli

Windows (PowerShell):

$env:CONTEXT7_API_KEY = "ctx7sk-xxxx-xxxx-xxxx"
npx neocortex-cli

Instalacao Manual de MCPs

Se preferir instalar manualmente:

# Playwright
claude mcp add playwright npx @playwright/mcp@latest

# Context7
claude mcp add --transport http context7 https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY: sua-chave-aqui"

Verificar MCPs Instalados

claude mcp list

Troubleshooting

Claude CLI nao encontrado:

• Instale o Claude Code: npm install -g @anthropic-ai/claude-code
• Ou os MCPs serao instalados na primeira execucao do Claude Code

MCP Playwright falhou:

• Verifique se Node.js esta instalado
• Tente instalar manualmente: claude mcp add playwright npx @playwright/mcp@latest

MCP Context7 nao instalado:

• Verifique se CONTEXT7_API_KEY esta definida
• A API key deve comecar com ctx7sk-

Workflows funcionando com fallbacks:

• O Neocortex funciona mesmo sem MCPs
• Playwright fallback: Analise estatica via Task tool
• Context7 fallback: WebSearch para documentacao

Via GitHub Packages (recomendado)

O pacote está hospedado no GitHub Packages como @ornexus/neocortex-cli.

Passo 1: Criar Personal Access Token (PAT)

1. Acesse: https://github.com/settings/tokens
2. Clique em "Generate new token (classic)"
3. Marque a permissão: read:packages
4. Clique em "Generate token"
5. Copie o token (formato: ghp_xxxxxxxxxxxx) - ele não será mostrado novamente!

Passo 2: Autenticar no GitHub Packages

Execute no terminal:

npm login --registry=https://npm.pkg.github.com

Quando solicitado, informe:

| Campo | Valor | |-------|-------| | Username | Seu usuário do GitHub (ex: joaosilva) | | Password | O token PAT copiado (ex: ghp_abc123...) | | Email | Seu email do GitHub |

Nota: A senha é o token PAT, não sua senha do GitHub!

Passo 3: Configurar Registry

echo "@ornexus:registry=https://npm.pkg.github.com" >> ~/.npmrc

Passo 4: Instalar

npx @ornexus/neocortex-cli

Isso instala o agente em ~/.claude/agents/neocortex-cli/.

Verificar Instalação

ls ~/.claude/agents/neocortex-cli/

Deve mostrar: neocortex-cli.md, steps-c/, steps-e/, steps-p/, etc.

Via Git (alternativa)

git clone https://github.com/OrNexus-AI/neocortex-cli ~/.claude/agents/neocortex-cli
cd ~/.claude/agents/neocortex-cli
./install.sh

O que cada método faz

| Método | O que instala | Onde | |--------|---------------|------| | npm install @ornexus/neocortex-cli | Agente @neocortex-cli | ~/.claude/ (usuário) | | @neocortex-cli *init | Configuração do projeto | .neocortex-cli/ (projeto) |

⚠️ Importante: Dois Níveis de Instalação

~/.claude/                          ← AGENTE (compartilhado entre projetos)
└── agents/neocortex-cli/
    ├── neocortex-cli.md
    ├── steps-c/*.md
    └── ...

/seu/projeto/                       ← DADOS (específico do projeto)
├── .neocortex-cli/
│   ├── 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 @neocortex-cli *init no projeto, o agente não funcionará porque não encontrará os arquivos de configuração.

Uso

# Processar uma story específica
@neocortex-cli @docs/stories/1.1.story.md

# Orquestrar um epic inteiro (paralelo)
@neocortex-cli @epic-1

# Criar epic a partir de uma ideia
@neocortex-cli *create-epic "COMO dev, QUERO X, PARA Y"

# Modo YOLO (sem confirmacoes)
@neocortex-cli *yolo @docs/stories/5.1.story.md

# Inicializar novo projeto
@neocortex-cli *init @docs/epics.md

# Ver status do pipeline
@neocortex-cli *status

Arquitetura

12 Core Steps

| # | Step | Status Apos | Descricao | |---|------|-------------|-----------| | 01 | setup-branch | branch-ready | Criar branch e worktree | | 02 | diagnose | diagnose | Analisar requisitos | | 03 | research | research | Pesquisar solucoes | | 04 | write-spec | write-spec | Escrever especificacao | | 05 | create-tasks | create-tasks | Criar lista de tasks | | 06 | implement-tasks | implemented | Implementar codigo (dual-mode: implement-tasks / orchestrate-tasks) | | 07 | update-memory | memory-updated | Atualizar CLAUDE.md com padroes | | 08 | commit-push | committed | Commit e push | | 09 | sync-main | synced | Sincronizar com main | | 10 | create-pr | pr-created | Criar Pull Request | | 11 | review-pr | pr-reviewed | Code review | | 12 | merge-pr | done | Merge e cleanup |

Categorias de Steps

• Core (steps-c/): Sequencia principal de 12 steps
• Planning (steps-p/): Criacao de epics a partir de ideias (3 steps: diagnose, research, generate)
• Epic (steps-e/): Orquestracao paralela de epics
• Recovery (steps-r/): Tratamento de bloqueios
• Utility (steps-u/): Manutencao 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 .neocortex-cli/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)

@neocortex-cli @docs/stories/5.1.story.md

Modo 2: Step Específico

@neocortex-cli *diagnose @docs/stories/5.1.story.md

Modo 3: Recovery

@neocortex-cli *fix-blocked @docs/stories/5.1.story.md

Modo 4: Utilitário

@neocortex-cli *cleanup-branches
@neocortex-cli *audit-status

Modo 5: Epic Paralelo

@neocortex-cli @epic-6

Modo 6: Inicialização

@neocortex-cli *init @docs/epics.md

Modo 7: Criar Epic

@neocortex-cli *create-epic "COMO dev, QUERO autenticacao JWT, PARA proteger rotas da API"

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

neocortex-cli/
├── neocortex-cli.md          # Agente principal
├── neocortex-cli.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
├── scripts/                # Scripts executaveis
│   └── validate-step.sh    # Gate de validacao de sequencia (POSIX)
├── steps-c/                # 12 core steps (com pre-check programatico)
├── steps-p/                # 3 planning steps (create-epic)
├── steps-e/                # Steps de epic
├── steps-r/                # Steps de recovery
├── steps-u/                # Steps utilitarios
├── standards/              # 15 arquivos de standards
└── data/                   # Templates e dados

Para Desenvolvedores

Publicar no GitHub Packages

# 1. Configurar token (primeira vez)
export NPM_TOKEN=ghp_seu_token_com_write_packages

# 2. Verificar o que será publicado
npm pack --dry-run

# 3. Publicar
npm publish

# 4. Atualizar versão e republicar
npm version patch  # 3.1.9 → 3.1.10
npm version minor  # 3.1.9 → 3.2.0
npm version major  # 3.1.9 → 4.0.0
npm publish

Testar Localmente

# Simular instalação
npm link
neocortex-cli

# Remover link
npm unlink

Estrutura do Pacote

@ornexus/neocortex-cli
├── bin: neocortex-cli → install.sh
├── files: 66 arquivos (steps, standards, data)
├── engines: node >= 18.0.0
└── publishConfig: restricted, registry npm.pkg.github.com

Licença

Este projeto é licenciado sob a Functional Source License, Version 1.1 (FSL-1.1) com Delayed Open Source Publication (DOSP).

O que isso significa?

| Aspecto | Detalhe | |---------|--------| | Licença atual | FSL-1.1 — uso permitido para qualquer finalidade, exceto competir diretamente com os produtos comerciais da OrNexus AI | | Data de mudança | 20 de fevereiro de 2029 | | Licença futura | MIT — após a data de mudança, o código será disponibilizado sob a licença MIT, sem restrições | | Uso pessoal | ✅ Totalmente permitido | | Uso comercial interno | ✅ Permitido (desde que não seja um produto concorrente) | | Redistribuição | ✅ Permitida com a mesma licença | | Produto concorrente | ❌ Requer permissão explícita da OrNexus AI |

Para detalhes completos, consulte o arquivo LICENSE.

Para mais informações sobre a Functional Source License: fsl.software | fair.io

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