# @code-ops-ai/app-aops-cli

CLI do **CodeOps AI (AgentOps)** para dar continuidade e governança ao trabalho
de agentes de IA, como Claude Code e Codex. Ela mantém o contexto entre
sessões, executa validações reais de build e testes e sincroniza handoffs,
tarefas e histórico em um fluxo compartilhado pelo time.

O binário instalado se chama `aops`.

## Instalação

```bash
npm install -g @code-ops-ai/app-aops-cli
aops --version
```

Requer Node.js 20 ou superior.

## Fluxo remoto recomendado

O servidor é a fonte de verdade para projeto, participantes e arquitetura
canônica. Publique o projeto antes de o time começar: assim, todos trabalham
com a mesma configuração e a mesma arquitetura.

### Tech lead: preparar e publicar

1. No dashboard, crie a equipe, adicione os desenvolvedores e atribua a si o
   papel de `tech_lead`.
2. Em **Projects**, crie o projeto associado à equipe e copie seu ID.
3. No clone do repositório, instale a CLI e autentique-se:

```bash
npm install -g @code-ops-ai/app-aops-cli
aops login
```

4. Vincule explicitamente o clone ao projeto remoto e grave a configuração local:

```bash
aops configure --write --project-id <project-id>
```

5. Inicialize o projeto:

```bash
aops init --write
aops setup --write
```

Para um aplicativo mobile, use `aops init mobile --write` explicitamente
quando o repositório também tiver backend ou frontend web. Sem perfil,
`aops init --write` reconhece React Native/Expo, Flutter, Android nativo e
iOS nativo apenas quando os sinais da stack são inequívocos. Repositórios
híbridos exigem uma escolha explícita para não receber instruções erradas.

As validações continuam sendo definidas pelo projeto em `.aops/policy.json`.
Use somente comandos que já existam na stack, como testes
Flutter, Gradle ou Xcode quando aplicáveis; não adicione toolchains mobile à
policy padrão.

Com um projeto remoto configurado, `aops init --write` envia a análise do
repositório, recebe a versão canônica da arquitetura, grava `ARCHITECTURE.md`
somente com esse conteúdo e solicita a publicação. Caso o servidor esteja
indisponível ou um requisito esteja pendente, ele não deve ser tratado como
publicado: corrija a pendência e execute novamente o comando.

### Desenvolvedor: entrar em um projeto já publicado

O desenvolvedor deve estar na equipe do projeto e receber o `<project-id>` do
tech lead. Não crie outro projeto remoto para contornar falta de acesso.

```bash
npm install -g @code-ops-ai/app-aops-cli
aops login
aops configure --write --project-id <project-id>
aops setup --write
aops context
```

Se `aops configure` informar que o projeto não foi encontrado ou não está
acessível, confirme a associação à equipe e peça ao tech lead para concluir a
publicação. Projetos em `rascunho` ou `configurando` não são disponibilizados
a desenvolvedores.

Para um projeto que já foi inicializado antes, use `update` para reaplicar o
bloco gerenciado com a versão atual da CLI:

```bash
aops update --write
aops setup --write
```

Se o time também usa Claude Code, o tech lead ou cada desenvolvedor pode rodar
o setup global do Claude além do setup do Codex:

```bash
aops setup --agent claude --write
```

Não execute `aops update --write` logo após `aops init --write`: o `init` já
escreve os arquivos do projeto. `aops setup` configura o ambiente global da
máquina; `init` e `update` configuram apenas o projeto atual.

## Como funciona

O `aops` mantém estado local e uma outbox em `.aops/agentops.db`, mas a
colaboração é **remote-first**: acesso, integrantes, arquitetura e histórico
compartilhado vêm do backend. Use `aops sync --write` durante e ao final do
trabalho para enviar evidências. A arquitetura canônica é remota;
`ARCHITECTURE.md` só é atualizado após confirmação da API e não deve ser uma
fonte alternativa editada manualmente.

### Limite entre uso local e serviço hospedado

A CLI continua útil sem login para trabalho individual no clone: inicialização
e leitura de arquivos, diagnósticos, validação de links, cache de contexto,
sessão e outbox locais funcionam no disco do projeto. Esses dados não criam
uma colaboração remota por si só.

Login, organização e projeto configurados são necessários para sincronizar
eventos, consultar ou persistir histórico compartilhado, colaborar em equipe,
publicar a arquitetura canônica e criar, aprovar ou aplicar planos de harness.
A API revalida a identidade, o acesso ao projeto e o entitlement em cada
operação remota; a CLI apenas apresenta o estado e as orientações de upgrade.

Um fork pode, portanto, manter o fluxo local para uso individual, mas não
recebe acesso automático ao serviço hospedado nem às suas capacidades
associadas a plano. A licença e a política para forks comerciais continuam
decisões separadas, sujeitas à revisão jurídica.

Fluxo recomendado para uma sessão de agente:

```bash
aops context                              # carrega o resumo de continuidade
aops workflow check                       # verifica bloqueios operacionais
aops session begin --agent claude         # abre uma sessão local
# ... trabalho normal do agente ...
aops session heartbeat --status "implementando validações"
aops validation add --command "pnpm test" --execute   # roda o comando de verdade
aops agent complete --summary "..." --files "a.ts,b.ts" --sync
aops session complete --status completed
aops sync --write
```

Para transportar o uso real informado pelo provedor durante o fluxo local:

```bash
aops session heartbeat --token-usage '{"inputTokens":1200,"outputTokens":300,"totalTokens":1500,"provider":"openai","model":"gpt-5"}'
aops session complete --status completed --token-usage '{"inputTokens":1200,"outputTokens":300,"totalTokens":1500,"provider":"openai","model":"gpt-5"}'
aops sync --write
```

### Uso de tokens por sessão e tarefa

Quando o provedor de IA retornar metadados de uso, o adaptador do agente deve
enviar um snapshot cumulativo no heartbeat e no encerramento da sessão. O SDK
aceita `inputTokens`, `outputTokens`, `totalTokens`, `provider` e `model`:

```ts
await client.operations.heartbeatSession(sessionId, {
  tokenUsage: {
    inputTokens: 1200,
    outputTokens: 300,
    totalTokens: 1500,
    provider: "openai",
    model: "gpt-5"
  }
});

await client.operations.completeSession(sessionId, {
  status: "completed",
  tokenUsage: { inputTokens: 1200, outputTokens: 300, totalTokens: 1500 }
});
```

O snapshot deve ser cumulativo para evitar dupla contagem entre heartbeats. A
API soma as sessões vinculadas e exibe o total na página da tarefa. Não estime
valores nem envie prompts, respostas, credenciais ou logs brutos.

## Comandos

### Setup do projeto

| Comando | Descrição |
|---|---|
| `aops init [path] [profile] --agent <claude\|codex\|gemini>` | Detecta a stack e gera `CLAUDE.md`/`AGENTS.md`, `.aops/policy.json` e o skill `tlc-spec-driven`. Quando o clone já está vinculado a um projeto remoto e o tech lead usa `--write`, sincroniza a arquitetura canônica e publica o projeto após a validação do servidor. |
| `aops update --write` | Reaplica o mesmo conteúdo gerenciado do `init` sobre um projeto já inicializado, preservando conteúdo customizado fora do bloco gerenciado. Use quando a CLI evoluir e o projeto precisar receber as instruções novas. |
| `aops configure --write --project-id <id>` | Associa o diretório atual a um projeto remoto existente e grava `.aops/config.json` local. Para desenvolvedores, o projeto precisa estar publicado e a pessoa precisa pertencer à equipe. |
| `aops login` | Login via navegador (device flow) contra o backend, grava `accessToken` na config global (`~/.aops/config.json`). |
| `aops doctor` | Verificações de config/drift: `package.json`, lockfile, `.gitignore`, `AGENTS.md`/`CLAUDE.md` desatualizados em relação ao gerador, specs não sincronizadas. |
| `aops whoami` | Mostra o usuário autenticado no backend. |
| `aops status` | Resumo do projeto local (stack detectada, apps do monorepo, etc.). |
| `aops next` | Indica a próxima ação operacional segura a partir da configuração, outbox e estado local. |

### Arquitetura canônica

| Comando | Descrição |
|---|---|
| `aops architecture analyze` | Gera uma prévia da análise arquitetural a partir das fontes do projeto, sem gravar arquivos. |
| `aops architecture analyze --write` | Publica a arquitetura analisada no backend e atualiza o `ARCHITECTURE.md` local após confirmação remota. |
| `aops architecture publish --file ARCHITECTURE.md` | Publica um documento de arquitetura aprovado e grava a versão canônica retornada pelo backend. |

### Sessão e continuidade

| Comando | Descrição |
|---|---|
| `aops context` | Carrega o resumo de continuidade: última tarefa, última sessão, riscos pendentes, sessões conflitantes de outros devs, última validação. **Rodar no início de toda sessão de agente.** |
| `aops session begin --agent <nome>` | Abre uma sessão local ativa depois de executar `workflow check`. Se já existir uma sessão remota ativa do mesmo usuário/projeto, a CLI a recupera e grava o `remoteSessionId` local em vez de falhar. `aops start` e `aops session check-in` continuam como aliases de compatibilidade. |
| `aops session heartbeat --status "..."` | Registra progresso intermediário durante o trabalho. No sync remoto, atualiza `lastHeartbeatAt` da sessão e também mantém um handoff resumido no histórico. |
| `aops session complete --status completed` | Encerra a sessão local. `aops finish` e `aops session check-out` continuam como aliases de compatibilidade. |
| `aops session list` | Lista sessões remotas do projeto configurado. Útil para diagnosticar sessões ativas antes de sincronizar. |
| `aops session close <session-id> --status completed\|failed\|canceled` | Encerra uma sessão remota específica usando o endpoint oficial da API. |
| `aops session close-stale --timeout 60m` | Mostra, sem alterar nada, as sessões remotas ativas sem heartbeat recente. Usa `lastHeartbeatAt` como fonte principal de atividade e `updatedAt` apenas como fallback para registros legados. Use `--write` para encerrá-las. |
| `aops handoff --summary "..."` | Registra um handoff (repasse de contexto) local. |
| `aops handoff suggest` | Sugere arquivos alterados e validações aprovadas para apoiar a criação do handoff, sem gravar estado. |
| `aops handoff check --summary "..." --next-steps "..." --tests "..." --risks "..." --files "..."` | Verifica a completude do handoff e emite avisos para campos ausentes, sem bloquear o comando. |
| `aops event send <nome> --payload '{...}'` | Registra um evento arbitrário local. |
| `aops task create --title "..."` | Registra a criação de uma tarefa operacional local. |
| `aops tasks import --from .specs/features/<feature>/tasks.md --write` | Importa diretamente tasks geradas pelo `tlc-spec-driven` a partir de um `tasks.md`, criando tarefas operacionais locais com `source=spec`. |
| `aops risks sync --write` | Promove risks acionáveis encontrados em handoffs/eventos para tarefas operacionais locais com `source=risk`, mantendo idempotência local. |
| `aops risk block --risk-id <id> --reason "..."` | Registra o bloqueio auditável de um risco, com suporte offline e sincronização posterior. |
| `aops workflow check` | Verifica riscos, tarefas prioritárias e demais bloqueios operacionais antes de iniciar trabalho. |

Em `.aops/policy.json`, `workflow.blockOnBlockedRisks` controla riscos cuja task
de origem está explicitamente `blocked`: o padrão `false` mantém o risco visível
no handoff e libera trabalho técnico independente; `true` mantém o bloqueio total
do workflow. Tasks de risco bloqueadas continuam correlacionadas por `sourceKey` e
não são recriadas por `aops risks sync --write`.

### Validação (harness) e conclusão

| Comando | Descrição |
|---|---|
| `aops validation add --command "..." --status passed\|failed\|skipped` | Autorrelato: registra que uma validação foi executada, sem rodar nada. |
| `aops validation add --command "..." --execute [--timeout <ms>]` | **Harness real**: executa o comando de verdade e deriva `status` do exit code (`0` → `passed`, senão `failed`). Qualquer `--status` informado junto é ignorado. |
| `aops loop check` | Executa sequencialmente todas as `requiredValidations` da policy, registra um evento por comando e retorna exit code `0` apenas quando todas passam. Sem policy ou validações configuradas, retorna `0` com aviso. |
| `aops agent complete --summary "..." --files "a.ts,b.ts" --tests "..." --risks "..." [--sync]` | Registra a conclusão da tarefa (resumo do que mudou, arquivos, testes, riscos). Com `--sync`, sincroniza imediatamente com o backend. |

**Gate de qualidade opcional**: se o projeto tiver um `.aops/policy.json`
versionado com `requiredValidations`, `aops agent complete --sync` **bloqueia**
até existir, na sessão atual, uma validação `passed` para cada comando
obrigatório:

```json
{ "requiredValidations": ["pnpm test", "pnpm build"] }
```

Um driver externo pode usar `aops loop check` como critério objetivo de parada:

```bash
if aops loop check; then
  echo "critério de parada atingido"
fi
```

### Governança do harness

O harness de melhoria segue um fluxo protegido: primeiro analise somente os
metadados sanitizados, revise a prévia, crie o plano, obtenha aprovação de
owner/admin e aplique exclusivamente o plano aprovado. A aplicação valida o
escopo, hash, catálogo, expiração e as validações declaradas.

| Comando | Descrição |
|---|---|
| `aops harness status` | Exibe a disponibilidade da análise, do plano local e a próxima ação segura. |
| `aops harness analyze` | Gera `.aops/harness-analysis.json` a partir de metadados sanitizados do projeto. |
| `aops harness plan --dry-run` | Mostra as alterações propostas, sem criar plano nem modificar arquivos. |
| `aops harness plan create --write` | Cria o plano local e o registra como rascunho no projeto remoto configurado. |
| `aops harness approve --plan-id <id> --plan-file .aops/harness-plan.json` | Registra a aprovação remota de owner/admin para o plano íntegro e não expirado. |
| `aops harness apply --plan-id <id> --plan-file .aops/harness-plan.json` | Aplica um plano remoto aprovado e executa somente suas validações declaradas. |
| `aops harness watch --once --apply-approved --agent <agent-id>` | Executa um ciclo controlado de busca e aplicação de planos aprovados. Para automação contínua, habilite explicitamente `harness.applyApproved` em `.aops/config.json`. |

Mantenha CI em modo informativo e revise o diff antes da aprovação. Quando
disponíveis, a aplicação registra `commitSha`, `pipelineId` e `evidenceId`;
uma melhoria permanece aguardando novo scan até a chegada de evidência recente
do CI.

### Sincronização remota

| Comando | Descrição |
|---|---|
| `aops sync --dry-run` | Mostra o plano de sincronização (o que seria enviado) sem tocar o backend. |
| `aops sync --write` | Envia os eventos locais pendentes (validações, handoffs, tarefas, heartbeats, conclusão de sessão) para o backend configurado. Antes de criar uma sessão remota nova, tenta reutilizar uma sessão ativa recuperável do mesmo usuário/projeto. |
| `aops sync inspect` | Mostra os eventos pendentes e rejeitados, a data do último sync e a próxima ação recomendada, sem enviar dados. |
| `aops sync retry --write` | Repete uma sincronização pendente de forma explícita; o `--write` é obrigatório. |

O sync é sempre **explícito** — nada é enviado à rede sem `--write`. Isso não
substitui a configuração e a publicação remotas: elas são pré-requisitos para
o acesso compartilhado ao projeto.

### Cache de contexto local

O cache reduz pesquisas repetidas sem substituir o código, os testes ou as
fontes canônicas. O índice é estritamente local: armazena caminhos, hashes,
tipos e palavras-chave das fontes permitidas; não armazena conteúdo bruto nem
é enviado pelo `sync`.

| Comando | Descrição |
|---|---|
| `aops cache build --write` | Cria ou atualiza incrementalmente o índice local. |
| `aops cache status` | Mostra se o índice existe e quando foi atualizado. |
| `aops cache brief --query "..."` | Retorna referências locais relevantes e limitadas para uma tarefa. |
| `aops cache list --scope <área>` | Lista entradas válidas dentro de um escopo. |
| `aops cache search --query "..." --include-content` | Pesquisa conhecimento manual; use conteúdo somente quando necessário e confirme a fonte primária. |
| `aops cache check` | Verifica a validade das entradas antes da reutilização. |

### Diagnóstico e documentação

| Comando | Descrição |
|---|---|
| `aops profile suggest` | Sugere o perfil `documentation` quando os arquivos alterados forem somente Markdown; caso haja código, sugere `behavior`. A sugestão não grava estado nem substitui uma escolha explícita. |
| `aops docs check-links` | Valida links relativos locais em arquivos Markdown. URLs externas e âncoras são ignoradas; links inexistentes retornam o arquivo, a linha e o destino. |

### Evidência de qualidade no CI

Para preparar a coleta de Harness Score sem alterar o pipeline, gere primeiro a
prévia e revise seus arquivos e secrets esperados:

```bash
aops ci init --provider gitlab
aops ci init --provider github
```

Após a revisão explícita, `--write` adiciona um bloco gerenciado ao GitLab ou
um workflow dedicado ao GitHub. A integração usa apenas os nomes
`CODEOPS_API_URL`, `CODEOPS_PROJECT_ID` e `CODEOPS_INGESTION_TOKEN`; seus
valores devem permanecer nos secrets protegidos do provedor. O job publica
`quality-evidence.json` e continua em modo `inform`.

### Métricas locais

| Comando | Descrição |
|---|---|
| `aops metrics` | Exibe duração de sessão, eventos pendentes/sincronizados e data do último sync. Campos sem dados são reportados como indisponíveis. |

### Ofertas da plataforma

Usuários autenticados de organizações no plano Free podem receber uma oferta discreta após `init`, `configure`, `sync` ou `context` concluírem com sucesso. A mensagem é emitida somente em `stderr`, no máximo uma vez a cada 7 dias, e aponta para a URL segura de billing retornada pela API. Ela nunca aparece em JSON, CI, pipes, erros ou para planos pagos.

Use `aops plan` para consultar o plano e a URL de billing, `aops promotions status` para conferir a preferência e a próxima elegibilidade e `aops config set promotions false` para desativar as ofertas (reative com `true`). A CLI não mede cliques; falhas de rede ou do cache são silenciosas e jamais alteram o exit code do comando solicitado.

## Sessões remotas e conflitos

O backend mantém no máximo uma sessão ativa por usuário/projeto. Isso evita
histórico fragmentado e mantém cada mudança rastreável pelo `userId`.

Quando a sessão ativa pertence ao mesmo usuário autenticado, `session begin` e
`sync --write` recuperam automaticamente a sessão remota. Quando a sessão
ativa pertence a outro usuário, `aops context` continua emitindo warning para
evitar mistura de trabalho entre desenvolvedores.

Para limpar sessões órfãs:

```bash
aops session list
aops session close-stale --timeout 60m
# depois de revisar a prévia:
aops session close-stale --timeout 60m --write
# ou, se precisar encerrar uma sessão específica:
aops session close <session-id> --status completed
```

### Spec-Driven Development

| Comando | Descrição |
|---|---|
| `aops spec sync [--write]` | Importa artefatos gerados pelo skill `tlc-spec-driven` (`.specs/features/<feature>/`) para o histórico local/remoto. Depois da aprovação de `tasks.md`, cria tarefas operacionais; depois de `validation.md`, reconcilia evidências do verifier. |
| `aops tasks import --from .specs/features/<feature>/tasks.md [--write]` | Importação direta de um arquivo `tasks.md` quando o techlead quer trazer tasks TLC sem depender do scan completo de specs. Sem `--write`, roda em dry-run. |

### Risks

| Comando | Descrição |
|---|---|
| `aops risks sync [--write]` | Analisa risks em handoffs/eventos locais e sincronizados, promove itens acionáveis para tarefas operacionais com `source=risk` e evita duplicação por `sourceKey`. Sem `--write`, roda em dry-run. |
| `aops risk block --risk-id <id> --reason "..."` | Bloqueia o risco persistido no handoff, registra autor/data/motivo localmente e sincroniza para a API com `aops sync --write`. Repetições são idempotentes. |

### Codex Toolkit

`aops codex <subcomando>` cobre o bootstrap e a migração de configurações do
Codex CLI (perfis, modos, sincronização de `AGENTS.md`, geração de relatórios,
etc.). O `aops setup --write` configura arquivos globais da máquina, incluindo
`~/.codex/parts/agentops.md`, aliases e `~/.codex/config.toml`. Para Claude,
`aops setup --agent claude --write` escreve `~/.claude/CLAUDE.md` e
`.claude/settings.json`. Os blocos de AgentOps/Spec usados aqui são os mesmos
gerados por `aops init`/`aops update`, evitando drift entre setup global e projeto.

Subcomandos: `setup`, `build`, `mode`, `status`, `project-info`,
`profile`, `sync`, `restore`, `run`, `flow`, `test-gen`, `ci-run`,
`pr-review`, `architecture-report`, `changelog-gen`, `auto-refactor`,
`new-mode`, `new-profile`, `lint-agents`, `doctor`. Veja `aops codex doctor`
e `aops help` para o detalhe de cada um.

### Utilitário

| Comando | Descrição |
|---|---|
| `aops --version` / `aops -v` / `aops version` | Imprime a versão instalada. |
| `aops help` | Lista todos os comandos e flags. |

Toda saída aceita `--json` para uso em scripts/outros agentes.

## Arquivos de configuração

| Arquivo | Versionado? | Conteúdo |
|---|---|---|
| `.aops/config.json` | **Não** (`.gitignore`) | `apiUrl`, `accessToken`, `organizationId`, `projectId` — por máquina/dev. |
| `.aops/agentops.db` | **Não** (`.gitignore`) | Sessão local, estado operacional e outbox de eventos. |
| `.aops/context-cache.db` | **Não** (`.gitignore`) | Índice local e derivado do cache de contexto; nunca é sincronizado. |
| `.aops/policy.json` | **Sim** | `requiredValidations` — comandos obrigatórios para `agent complete --sync`, compartilhado pelo time. |
| `ARCHITECTURE.md` | Conforme a política do repositório | Cópia local da arquitetura canônica retornada pelo servidor. O tech lead a gera pela CLI; a versão canônica fica disponível no dashboard. |

## Variáveis de ambiente

`AOPS_API_URL`, `AOPS_ACCESS_TOKEN`, `AOPS_ORGANIZATION_ID` e
`AOPS_PROJECT_ID` sobrescrevem os valores de `.aops/config.json`. Forneça
`AOPS_ACCESS_TOKEN` apenas pelo ambiente seguro do processo; nunca o versione.

## Licença

MIT
