Aurum Cortex

CLI local para orquestração de agentes, documentação viva, backlog técnico e execução assistida por ferramentas externas de desenvolvimento.

Objetivo

Aurum Cortex funciona como uma camada acima de ferramentas como Claude Code, OpenCode, Cursor, Codex e outros executores. Ele prepara contexto, documentação, histórias, critérios de aceite e prompts de execução; depois dispara o executor configurado ou gera um pacote para execução manual.

Instalação global Preview

npm install -g @aurumsoltec/aurumcortex@latest

Depois:

aurumcortex --version
aurumcortex about
acx menu

Validade da versão preview

Esta versão preview é válida até 30/06/2026. Após essa data, comandos operacionais serão bloqueados até atualização ou ativação futura (comandos como --version, about, preview e update continuam disponíveis).

A versão atual ainda não possui licenciamento online. O sistema de licença/ativação será implementado em fase posterior.

O que o pacote npm publica

O pacote npm publica dist/, README.md, as licenças (LICENSE, LICENSE-PREVIEW.md, LICENSE-COMMERCIAL.md), a camada de instalação (install.js, install.ps1, install.sh, postinstall.js), docs/install/, targets-stubs/ e o package.json. O repositório privado, o código-fonte TypeScript em src/, os testes e os arquivos internos não são publicados. Como em toda CLI local, o JavaScript distribuído em dist/ fica disponível no computador do usuário.

Distribuição npm Preview

O pacote npm inclui uma camada de distribuição com:

• postinstall.js — mensagem pós-instalação (apenas imprime próximos passos)
• install.js — helper local de instalação/diagnóstico (verifica Node >= 20)
• install.ps1 — helper Windows (-DryRun / -Yes)
• install.sh — helper Linux/macOS (--dry-run / --yes)
• docs/install/ — documentação de instalação (Windows, Linux/macOS, OpenCode, troubleshooting, checklist)
• targets-stubs/ — stubs/roadmap para agentes/ambientes (OpenCode, Claude Code, Cursor, Codex, VS Code)

O bin principal continua direto:

aurumcortex about
acx menu

O helper de instalação é opcional:

aurumcortex-install

A validação de publicação pode ser executada localmente com npm run validate:publish.

Reforçando:

• o licenciamento real (online) ainda não está implementado;
• a versão preview expira em 30/06/2026;
• dist/ é distribuído; src/, test/, arquivos internos e segredos não são publicados.

Instalação local

npm install
npm run build
npm link

Depois:

aurum-cortex --help
acx --help

Workflow principal

acx arch-plan "descrição detalhada"
acx commit
acx create-epic "COMO desenvolvedor, QUERO criar todos os épicos e histórias da arquitetura completa descrita em @docs/architecture/, PARA construir o projeto inteiro a partir do plano de arquitetura"
acx yolo @docs/epics/EPIC-01-core-foundation.md
acx commit
acx status

1. arch-plan é a porta de entrada: planeja (projeto novo) ou mapeia (projeto existente) a arquitetura em docs/architecture/ + docs/02-ARCHITECTURE.md.
2. create-epic cria o backlog file-based: um arquivo por épico (docs/epics/) e por história (docs/stories/), com índices docs/06-EPICS.md/docs/07-STORIES.md.
3. yolo aceita caminho @docs/... (ex.: acx yolo @docs/epics/EPIC-01-core-foundation.md) além de EPIC-01/STORY-001.
4. commit é etapa oficial do workflow: roda o doctor, bloqueia segredos (.env, *.pem, *.key, node_modules/**) e faz git add/git commit (push só com --push).
5. doctor valida a segurança antes da execução real.

Para projeto existente, comece com acx arch-plan "Mapear projeto existente: ...".

Os diferenciais técnicos do AurumCortex continuam disponíveis: doctor, checkpoints, execution-report, review --story, story-status, story-done, backlog reindex --safe e yoloop seguro.

Fluxo inicial (técnico/avançado)

acx init
acx status
acx scan
acx architecture
acx epics
acx stories EPIC-01
acx run STORY-001 --dry-run
acx review --story STORY-001
acx story-done STORY-001
acx docs-sync

acx status funciona mesmo antes da inicialização e sempre indica o próximo passo recomendado.

Ciclo de vida das histórias

O Aurum Cortex mantém o status de cada história em .aurum-cortex/memory/stories.json (planned → active → review → done) e o avanço entre elas:

acx run STORY-001 --dry-run        # marca a história como active
acx review --story STORY-001       # marca a história como review e grava last-review.json
acx story-status STORY-001 review  # define o status manualmente (planned|active|review|done)
acx story-done STORY-001           # marca a história como done e aponta a próxima planned

acx story-status STORY-001 review (aliases: acx set-story-status, acx status-story) define o status diretamente, validando o valor e mostrando antes/depois. acx story-done (aliases: acx done, acx complete) conclui a história e continua sendo uma confirmação humana — nada é marcado como done automaticamente. acx status mostra a contagem por status, a próxima história recomendada e o último review.

Revisão com validação de escopo

acx review analisa o diff atual e gera um relatório em docs/10-REVIEW-REPORTS/ e um resumo reutilizável em .aurum-cortex/runtime/last-review.json (consumido pelo gate de segurança). Com --story, ele valida os arquivos alterados contra allowedFiles/forbiddenFiles da história:

acx review                       # revisão básica (sem validação de escopo)
acx review --story STORY-001     # valida escopo, classifica risco e registra lastReview

Execução assistida (orquestração, não execução cega)

acx yolo e acx yoloop preparam pacotes de execução em .aurum-cortex/runtime/ por padrão (dry-run). Nada é executado de verdade sem --execute explícito.

acx yolo STORY-001
acx yoloop EPIC-01 --limit 1

yoloop resolve apenas as histórias do épico, prioriza active/review antes de planned, ignora as que estão done e respeita --limit (padrão 1) para nunca rodar de forma ilimitada.

Ciclo iterativo controlado (--execute)

Com --execute, o yoloop roda um ciclo iterativo com checkpoint por história:

acx yoloop EPIC-01 --limit 1 --execute --auto-review

Para cada história ele: cria checkpoint before-run, aplica o gate de segurança, executa (reutilizando o fluxo de run), cria checkpoint after-run e — com --auto-review — roda o review automático e cria checkpoint after-review.

• Não marca done automaticamente. A conclusão é manual via acx story-done (a menos que você use --auto-complete, que só conclui após um review limpo).
• Os checkpoints ficam em .aurum-cortex/runtime/checkpoints/.
• Sem --auto-review, o review é apenas recomendado (registrado em checkpoint).

Kill-switch

O kill-switch fica ativado por padrão e interrompe o loop imediatamente quando: o gate falha, o último review tem score alto, há violação de forbiddenFiles, a execução falha ou não há história candidata. Use --no-kill-switch para relaxar a parada por score alto, mas forbiddenFiles sempre bloqueia.

Gate de segurança para execução real

Antes de qualquer execução real (--execute), run e yoloop aplicam um gate de segurança que bloqueia a execução se:

• a história não existir;
• a história não tiver acceptanceCriteria;
• a história não tiver allowedFiles;
• houver violação de forbiddenFiles no diff atual;
• o último review (last-review.json) tiver score alto;
• o último review tiver forbiddenHits.

O modo --dry-run (padrão) nunca é bloqueado, e forbiddenFiles sempre bloqueia mesmo com --no-kill-switch.

Reindexar o backlog

acx backlog reindex (ou acx backlog-reindex) reconstrói epics.json/stories.json a partir de docs/epics/ e docs/stories/, detectando o épico de cada história por frontmatter epicId ou linhas como Epic: EPIC-01 / Épico: EPIC-01. Ele preserva o status e os campos existentes e cria um backup em .aurum-cortex/memory/backups/ antes de sobrescrever.

acx backlog reindex

Reindex seguro (preview)

--safe não altera epics.json/stories.json. Ele cria um backup e grava uma prévia em .aurum-cortex/runtime/reindex-preview.json, mostrando quantas mudanças seriam aplicadas. Depois, --apply-preview aplica a prévia (com backup):

acx backlog reindex --safe           # gera a prévia, sem alterar o backlog
acx backlog reindex --apply-preview  # aplica a última prévia

Rastreabilidade de execução

Cada execução real grava um ExecutorResult estruturado em .aurum-cortex/runs/STORY-001-<timestamp>/execution-result.json (status, exitCode, stdout/stderr, duração), além de executor-output.log e execution-package.json. O project-state.json e a story passam a registrar lastRunStatus (success | failed | dry-run). Se o executor falhar, run retorna exit code 1 e o yoloop para o loop com um checkpoint blocked.

Checkpoints

Liste a trilha de execução de uma história (criada durante yoloop --execute):

acx checkpoints STORY-001            # lista legível (before-run, after-run, after-review, ...)
acx checkpoints STORY-001 --latest   # apenas o último checkpoint
acx checkpoints STORY-001 --json     # saída em JSON

Execution report

Gera um relatório consolidado (story, status, último run, último review, checkpoints, riscos e próximo passo) em docs/10-REVIEW-REPORTS/EXECUTION-REPORT-STORY-001-<timestamp>.md:

acx execution-report STORY-001       # aliases: acx report / acx story-report

Diagnóstico com doctor

acx doctor diagnostica a saúde do projeto sem alterar nada: estrutura, git (repo, branch, alterações pendentes, arquivos proibidos modificados), backlog (stories sem allowedFiles/ acceptanceCriteria/epic, IDs duplicados/inválidos) e runtime (checkpoints, runs, último review). Use-o antes de yoloop --execute.

acx doctor

Ele retorna exit code para CI: 0 (OK), 1 (ATENÇÃO), 2 (CRÍTICO). Em uso local interativo o exit code é informativo; em pipelines ele permite falhar a etapa quando o estado é crítico.

Fluxo recomendado

acx doctor
acx status
acx yoloop EPIC-01 --limit 1 --execute --auto-review --executor dry-run
acx checkpoints STORY-001
acx execution-report STORY-001
acx story-done STORY-001

Execução segura

Por padrão, run trabalha em modo seguro. Para executar um adaptador externo, use --execute explicitamente. O comando final é configurável em .aurum-cortex/config.json.

Compatibilidade

A primeira versão nasce com adaptadores configuráveis para:

• claude
• opencode
• shell
• dry-run

Como CLIs externas mudam com frequência, os comandos são templates editáveis no arquivo de configuração local.

Runner local do projeto

O Aurum Cortex cria um runner local dentro de cada projeto inicializado para evitar dependência de PATH global (problema comum no OpenCode).

O que é criado

Após aurumcortex init ou aurumcortex install-opencode:

• .aurum-cortex/bin/aurumcortex.cmd — Windows CMD runner
• .aurum-cortex/bin/aurumcortex.ps1 — Windows PowerShell runner
• .aurum-cortex/bin/aurumcortex — POSIX runner (Linux/Mac)

Como funciona

O runner local aponta para o Node.js e o entrypoint da CLI instalada globalmente. Dentro do OpenCode, em vez de chamar acx diretamente (que pode não estar no PATH do OpenCode), o roteador usa o runner local:

.\.aurum-cortex\bin\aurumcortex.cmd scan

No Linux/Mac:

./.aurum-cortex/bin/aurumcortex scan

Por que isso é necessário

O OpenCode não herda necessariamente o PATH global do Windows. Se acx não for encontrado, o comando falha. O runner local resolve isso porque está dentro do diretório do projeto e é chamado com caminho relativo.

OpenCode usage

O Aurum Cortex fornece uma integração autossuficiente com OpenCode via o arquivo aurumcortex.md. Após a instalação, o agente reconhece automaticamente comandos no formato @acx *comando.

Menções de agente

O AurumCortex aceita três menções (todas equivalentes), com @acx como recomendada:

• @acx (recomendada)
• @aurumcortex (compatível)
• @aurum-cortex (compatível)

Terminal usage:

acx status
acx arch-plan "..."
acx commit

Agent usage (OpenCode):

@acx *status
@acx *arch-plan "..."
@acx *commit

Dentro do agente/OpenCode, nunca execute acx global diretamente — o roteador usa o runner local do projeto (.\.aurum-cortex\bin\aurumcortex.cmd no Windows, ./.aurum-cortex/bin/aurumcortex no POSIX).

Instalação

A bridge é instalada automaticamente durante acx init:

acx init --type web

Ou manualmente em um projeto existente:

acx install-opencode

O que é criado

• aurumcortex.md — arquivo principal reconhecido pelo OpenCode
• .aurum-cortex/opencode/aurumcortex.md — cópia de controle
• .opencode/aurumcortex.md — ponte adicional

O arquivo aurumcortex.md é autossuficiente: contém o menu completo, regras de roteamento e instruções para responder qualquer comando @aurumcortex.

Uso dentro do OpenCode

Abra o projeto no OpenCode. O arquivo aurumcortex.md na raiz é carregado automaticamente. Digite:

@acx *menu
@acx *status
@acx *arch-plan "descrição detalhada"
@acx *commit
@acx *create-epic "pedido"
@acx *yolo @docs/epics/
@acx *yoloop @docs/epics/
@acx *scan
@acx *architecture
@acx *stories EPIC-01
@acx *review
@acx *docs-sync

Os aliases @aurumcortex e @aurum-cortex continuam funcionando (ex.: @aurumcortex *status).

Compatibilidade

Comandos sem * também funcionam:

• @aurumcortex scan é interpretado como @aurumcortex *scan

Menu no terminal

Para ver o menu no terminal (comparando modos OpenCode e Terminal):

aurumcortex menu
acx menu          # alias curto

Execução ponta a ponta com *yolo

*yolo executa um epic ou story de ponta a ponta, do código aos testes.

Entradas aceitas:

• arquivo de epic (preferencial)
• arquivo de story
• ID de epic
• ID de story
• lista de stories

Exemplos:

@aurumcortex *yolo @docs/epics/EPIC-01-estrutura-base.md
@aurumcortex *yolo @docs/stories/STORY-001-criar-html-base.md
@aurumcortex *yolo EPIC-01
@aurumcortex *yolo STORY-001 STORY-002

Execução autônoma com *yoloop

*yoloop executa automaticamente todas as stories de um epic em sequência com mecanismos de segurança integrados.

Mecanismos de segurança:

• Caps: limite máximo de stories (padrão: 1)
• Cool-down: pausa entre stories
• Kill-switch: interrompe em caso de erro, falha de teste, alteração fora de escopo
• Checkpoints: revisão entre cada story

Exemplos:

@aurumcortex *yoloop @docs/epics/EPIC-01-estrutura-base.md
@aurumcortex *yoloop @docs/epics/
@aurumcortex *yoloop EPIC-01 --limit 2
@aurumcortex *yoloop --from STORY-003 --limit 1

Roteamento inteligente

O usuário pode escrever apenas @aurumcortex "instrução" e o roteador infere o comando:

@aurumcortex "crie os épicos e histórias a partir de @docs/"
@aurumcortex "execute a STORY-001"
@aurumcortex "continue a implementação das próximas histórias"

Fluxo recomendado no OpenCode

1. aurumcortex init --type web
2. Abrir o OpenCode na pasta do projeto
3. @aurumcortex *menu
4. @aurumcortex *scan
5. @aurumcortex *architecture
6. @aurumcortex *epics
7. @aurumcortex *stories EPIC-01
8. @aurumcortex *prompt STORY-001
9. @aurumcortex *run STORY-001
10. @aurumcortex *review
11. @aurumcortex *docs-sync

Organização de épicos e histórias

O Aurum Cortex adota o padrão de arquivos individuais para épicos e histórias, com pastas separadas.

Estrutura de diretórios

docs/
├── epics/
│   ├── EPIC-01-nome-do-epico.md
│   ├── EPIC-02-nome-do-epico.md
│   └── EPIC-03-nome-do-epico.md
├── stories/
│   ├── STORY-001-nome-da-historia.md
│   ├── STORY-002-nome-da-historia.md
│   └── STORY-003-nome-da-historia.md
├── 06-EPICS.md       (apenas índice)
└── 07-STORIES.md     (apenas índice)

Regras

• docs/epics/ contém um arquivo por épico com conteúdo completo.
• docs/stories/ contém um arquivo por história com conteúdo completo.
• docs/06-EPICS.md é apenas o índice dos épicos (tabela resumida).
• docs/07-STORIES.md é apenas o índice das histórias (tabela resumida).
• .aurum-cortex/memory/epics.json armazena metadados.
• .aurum-cortex/memory/stories.json armazena metadados.

Reorganizar backlog existente

Para migrar um backlog antigo (arquivos únicos) para o novo padrão:

aurumcortex organize-backlog

Ou no OpenCode:

@aurumcortex *organize-backlog

Criar backlog já no novo padrão

Ao usar @aurumcortex *create-epic "pedido" @docs/, o backlog já será gerado no novo padrão com arquivos individuais.

Criar épicos e histórias a partir de @docs/

Use comandos de backlog completo dentro do OpenCode:

@aurumcortex *epics "COMO desenvolvedor, QUERO criar todos os épicos e histórias da arquitetura completa descrita em @docs/, PARA construir o projeto inteiro a partir do plano de arquitetura" @docs/

Ou equivalente:

@aurumcortex *create-epic "COMO desenvolvedor, QUERO criar todos os épicos e histórias da arquitetura completa descrita em @docs/, PARA construir o projeto inteiro a partir do plano de arquitetura" @docs/

No terminal:

aurumcortex create-epic "pedido" --context docs

Atualização

Para atualizar a instalação global do Aurum Cortex:

aurumcortex update

Para ver o comando que seria executado sem executar:

aurumcortex update --dry-run

O comando executa npm install -g git+https://github.com/aurumsoltec/AurumCortex.git.