🐙 Octechpus

CLI instalável que scaffolda um sistema completo de orquestração de agentes em qualquer projeto Claude Code.

octechpus init detecta sua stack automaticamente e instala 14 agentes especializados (incluindo um Verifier que executa build/testes/lint/audit, Privacy/LGPD e um Designer stack-agnóstico), templates de CI/GitHub e documentação estruturada — tudo configurado para o seu projeto, pronto para usar com /pipeline no Claude Code.

Instalação

# Sem instalar (recomendado para uso pontual)
npx octechpus init

# Global
npm install -g octechpus
octechpus init

Requisitos: Node.js >= 20

Quick start

npx octechpus init

Sem flags, o init pergunta como você quer instalar, com dois caminhos:

• A) Projeto em andamento — o CLI lê a base de código existente e auto-detecta a stack coerente, instalando de forma harmoniosa com o que já está lá.
• B) Projeto novo — você aponta um documento PID (.md) descrevendo o projeto; o CLI lê o documento e escolhe a stack ideal para começar.

Você pode pular o menu com flags:

# Stack explícita (bypass total)
npx octechpus init --stack=python-fastapi

# Projeto novo: aponta o PID direto (entra no caminho B, não-interativo)
npx octechpus init --describe=docs/pid.md

💡 Não precisa do caminho completo. Basta o nome do arquivo (com ou sem .md) — o CLI procura o documento em projectDir e no diretório atual, ignorando node_modules, .git, dist, etc. Ex.: --describe=pid. Se houver mais de um arquivo com o mesmo nome, o CLI lista os caminhos e pede para você especificar.

Na detecção (caminhos A e B), o CLI inspeciona manifests (package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml/build.gradle, *.csproj/*.sln, Gemfile, composer.json) e também documentos .md (o PID no caminho B; README.md, PROJECT.md, ARCHITECTURE.md, etc. no caminho A):

• Alta confiança → aplica o profile imediatamente
• Confiança média → pede confirmação antes de aplicar
• Baixa confiança → lista candidatos (com "quando usar") e abre o modo guiado
• Sem confiança / stack mista → use o profile generic

Profiles disponíveis

Designer e Privacy/LGPD são always-on em todos os profiles (não aparecem como "extras"). Só Cost Engineer é opt-in por profile.

| Profile | Linguagem / Framework | Agente opt-in | |---|---|---| | node-typescript | Node.js + TypeScript, Vitest, Zod | — | | node-javascript | Node.js puro (JS, sem TypeScript) | — | | nextjs-react | Next.js + React + Tailwind + shadcn/ui | — | | vue-nuxt | Vue 3 + Nuxt + Tailwind | — | | react-native | React Native / Expo (mobile) | — | | python-fastapi | Python ≥ 3.12, FastAPI, Pydantic v2, pytest, uv, ruff | — | | python-ai-pipeline | FastAPI + LLM (Anthropic/OpenAI/LangChain) | Cost Engineer | | python-cli | Click / Typer, pytest | — | | go-api | Go, chi ou stdlib, testify | — | | rust-cli | Rust, clap, tokio, cargo test | — | | java-spring | Java 17+, Spring Boot, JUnit 5 | — | | dotnet-api | C#, ASP.NET Core, xUnit | — | | ruby-rails | Ruby on Rails, RSpec | — | | php-laravel | PHP 8.2+, Laravel, Pest/PHPStan | — | | generic | Fallback agnóstico (stack mista / desconhecida) | — |

Todos herdam de _base, que define pipeline, segurança, privacidade, ADRs e convenções universais. A herança é resolvida por deep-merge: o filho sobrescreve escalares e concatena arrays (use !override como 1º item para substituir).

_base
├── node-typescript
│   ├── nextjs-react
│   ├── vue-nuxt
│   └── react-native
├── node-javascript
├── python-fastapi
│   ├── python-ai-pipeline
│   └── python-cli
├── go-api · rust-cli · java-spring · dotnet-api · ruby-rails · php-laravel
└── generic

O que é instalado

seu-projeto/
├── .claude/
│   ├── commands/              ← agentes como slash commands (orquestração)
│   │   ├── pipeline.md            /pipeline
│   │   ├── maestro.md             /maestro
│   │   ├── audit.md               /audit
│   │   ├── architect.md           /architect
│   │   ├── coder.md               /coder
│   │   ├── verify.md              /verify    ← gate de execução
│   │   ├── review.md              /review
│   │   ├── qa.md                  /qa
│   │   ├── security.md            /security
│   │   ├── privacy.md             /privacy   ← LGPD/GDPR
│   │   ├── reporter.md            /reporter
│   │   ├── docs.md                /docs
│   │   ├── github-issue.md        /github-issue
│   │   ├── profiler.md            /profiler
│   │   ├── design.md              /design
│   │   ├── cost-engineer.md       /cost
│   │   └── progress.md            /progress  ← página de andamento
│   ├── agents/                ← subagents escopados (tools por agente, model: inherit)
│   │   ├── security.md            read-only
│   │   ├── coder.md               read-write
│   │   ├── docs.md                read-write
│   │   └── … (um por agente ativo)
│   ├── overrides/             ← (opcional, seu) ajustes locais anexados aos agentes
│   └── settings.json          ← permissões: allow / ask / deny (segurança)
├── .github/
│   ├── ISSUE_TEMPLATE/            Templates bug / feature / refactor
│   └── PULL_REQUEST_TEMPLATE.md
├── docs/
│   ├── OCTECHPUS_AGENTS.md    ← Referência completa dos agentes
│   ├── project-context.md     ← Documentação do SEU projeto (não gerenciado, nunca sobrescrito)
│   └── adr/                   ← Architecture Decision Records (ADR-NNN-titulo.md)
├── .octechpus/
│   └── manifest.json          ← Hashes SHA-256 para rastrear customizações
└── CLAUDE.md                  ← Config do projeto lida pelo Claude Code

Design system: o init scaffolda design-system/ (starter Stratum) por padrão. O agente Designer é stack-agnóstico e para quando não encontra um design system — com o starter local ele sempre tem uma fonte da verdade para tokens, componentes e estados. O conteúdo enviado segue o profile (design_system.tokens: tailwind manda o preset, css-only só as variáveis CSS, none apenas a documentação + referência visual).

Para pular: npx octechpus init --no-design-system. Se você já tem um design system próprio, edite os arquivos à vontade — update só preenche o que estiver faltando e nunca sobrescreve o que existe.

Permissões e subagents (v2.5)

Desde a v2.5 o init configura segurança por padrão — sem você precisar aprovar cada ação dos agentes. Ver ADR 002.

.claude/settings.json — modelo de menor privilégio

Gerado a partir do profile, com três níveis:

| Nível | Comportamento | Exemplos | |---|---|---| | allow | roda sem perguntar | npm test, git commit, pytest, cargo build, gh … | | ask | pausa e pede aprovação | git push, npm publish | | deny | bloqueado (nem pergunta) | rm -rf, force-push, sudo, curl/wget/scp, env/printenv, gh auth token, ler .env/chaves |

As pastas em guardrails.read_only_paths viram regras Write(...)/Edit(...) no deny — o guardrail deixa de ser texto no CLAUDE.md e passa a ser trava imposta.

O resultado é mais autonomia (o trabalho seguro flui sem prompts) e mais segurança (o destrutivo é barrado, não perguntado). Para overrides pessoais, use .claude/settings.local.json — ele precede o settings.json.

v2.16.1 — o settings.local.json também é limpo. O CLI nunca cria esse arquivo nem injeta baseline nele, mas, se ele já existir, init/update/profile switch convertem regra de caminho inerte (Write(x) → Edit(x), Glob(x) → Read(x), mesmo tier) — senão o aviso de startup sobrevive ao update. Só reescreve quando há forma morta de fato, guarda backup antes, e deixa JSON inválido intacto.

Revise o seu allow depois do update: regra inerte ali passa a valer, e duas conversões cobrem escopo maior que o original — Glob(x) → Read(x) (listar vira ler) e NotebookEdit(x) → Edit(x) (notebook vira qualquer arquivo). Em deny/ask a conversão só aperta; em allow, amplia o que roda sem perguntar.

⚠️ deny é defesa-em-profundidade, não sandbox. As regras casam por prefixo de comando (Bash(rm -rf:*)), então reduzem o risco mas não eliminam toda evasão possível (ex.: find -delete, aliases). É uma camada de proteção — não substitui review humano. Cada subagent também carrega uma instrução anti prompt-injection (conteúdo lido do repo é dado, nunca comando).

.claude/agents/ — subagents escopados

Cada agente vira um subagent do Claude Code com contexto isolado e ferramentas por princípio do menor privilégio:

| Agente | Tools | |---|---| | Architect · Reviewer · Security · Privacy · Reporter · Profiler · Designer | Read, Grep, Glob (read-only) | | Coder · QA · Docs · GitHub · Maestro | Read, Write, Edit, Bash, Grep, Glob |

Os agentes de análise não conseguem editar código (não têm a ferramenta) — a segurança vem de não ter a capacidade, não de te perguntar. Configurável via agents_runtime no profile.

v2.12 — sem pin de modelo: todos os agentes usam model: inherit — quem decide o esforço em contexto é a sessão/orquestrador, não uma constante fixada antes da tarefa existir. (Em campo, docs e profiler pinados em haiku deixaram defeitos de template passarem despercebidos por meses.) Precisa de piso? Sobrescreva agents_runtime no profile, com um comentário explicando o porquê.

v2.6 — orquestração real: o /pipeline delega cada fase ao subagent via ferramenta Task (em vez de trocar de papel numa conversa só). O fan-out pós-Coder — Reviewer ∥ QA ∥ Security ∥ Privacy — roda em paralelo, e o handoff entre agentes passa por artefatos em .octechpus/run/ (cada subagent recebe os outputs relevantes dos anteriores). O /audit também delega aos subagents read-only em paralelo (v2.7).

v2.7 — adoção sem atrito: se você já tem um .claude/settings.json, o Octechpus faz merge das permissões nele (preserva suas regras e chaves hooks/env/etc.) em vez de pular o arquivo. Um settings.json inválido nunca é sobrescrito. O init/update também adicionam .octechpus/run/ ao .gitignore.

Os 13 agentes

Maestro → GitHub → Architect → [Designer] → Coder → Reviewer → QA → Security → Privacy → Docs → Reporter
                                     ↑ em demandas de UI            🔬 Profiler   💰 Cost Engineer (opt-in)

| # | Agente | Responsabilidade | |---|---|---| | 1 | 🎯 Maestro | Orquestra; rubrica de severidade, critérios testáveis, teto de 2 iterações → escala p/ humano | | 2 | 🐙 GitHub | Issues, branches (conventional), commits semânticos, PRs; CODEOWNERS/branch protection/secret-scan | | 3 | 📐 Architect | Impacto técnico, ADRs, NFRs e classificação de dados (público/pessoal/sensível) | | 4 | 🎨 Designer | Stack-agnóstico — melhores práticas de UX/UI; pede o design system do Claude Design em runtime | | 5 | 💻 Coder | Implementação pelo profile; Karpathy (Simplicity/Surgical); regras de segredos/PII e feature flags | | 6 | 🔍 Reviewer | Code review com severidade (🔴/🟡/🔵); K1-K4; concorrência, i18n; checklist de UX em PRs de UI | | 7 | 🧪 QA | Unit/integração/E2E + negativos de segurança; fixtures sem PII; smoke de performance | | 8 | 🛡️ Security | OWASP 2021 + API Security Top 10 (BOLA/BFLA) + SSRF + supply chain | | 8b | ⚖️ Privacy | Conformidade LGPD/GDPR: base legal, minimização, retenção, direitos do titular, RIPD/DPIA | | 9 | 📚 Docs | Docstrings/JSDoc, README, CHANGELOG, ADRs, documentação de dados pessoais | | 10 | 📊 Reporter | Relatório consolidado; scorecard com piso (Segurança/Privacidade < 4 capa o geral) | | 11 | 🔬 Profiler | Auto-detecção de stack (incl. monorepo/drift); rode /profiler para re-verificar | | 12 | 💰 Cost Engineer | Guarda contra gasto de API/infra (budget + kill-switch); opt-in em AI/ML |

Princípios de Karpathy (embutidos em todos os agentes desde v2.3)

Todo agente gerado por octechpus init segue os 4 princípios:

1. Think Before Coding — Architect declara premissas e define critérios testáveis antes de qualquer plano
2. Simplicity First — Coder proíbe abstrações prematuras e código defensivo desnecessário
3. Surgical Changes — Coder altera o mínimo necessário; Reviewer rejeita escopo extra
4. Goal-Driven Execution — Maestro converte demandas vagas em resultados mensuráveis antes de rotear

Slash commands (pós-init)

Abra o Claude Code no projeto e use:

| Comando | Para quê | |---|---| | /pipeline [demanda] | Pipeline completo — todos os agentes em sequência | | /maestro [demanda] | Classificação, severidade e roteamento | | /audit [escopo] | Raio-x do projeto com scorecard | | /architect [escopo] | Análise de impacto arquitetural | | /coder [demanda] | Implementação guiada pelo profile | | /review [escopo] | Code review com severidade | | /qa [escopo] | Gerar testes (unit, integration, E2E) | | /security [escopo] | Audit OWASP 2021 + API Top 10 | | /privacy [escopo] | Conformidade LGPD/GDPR | | /docs [escopo] | Documentação | | /github-issue [demanda] | Criar issue no GitHub | | /profiler | Re-detectar e reportar stack atual | | /reporter [escopo] | Relatório consolidado do pipeline | | /design [demanda] | Briefing de UX/UI (Designer) | | /cost [escopo] | Audit de gasto de API e dependências | | /readiness [escopo] | Scorecard de prontidão técnica publicado numa Issue (integração Maestro) | | /progress | Página de andamento do projeto em linguagem simples (docs/status/) |

Comandos CLI

octechpus init                        # Setup com auto-detecção de stack
octechpus init --stack=<profile>      # Setup com stack explícita
octechpus status                      # Verifica setup e profile ativo
octechpus doctor                      # Diagnostica problemas e drift de profile
octechpus docs-check                  # Verificações mecânicas da documentação (feito p/ CI)
octechpus docs-check --strict         # Idem, tratando avisos como erro
octechpus secrets-check               # Varredura de credenciais (CI / pre-commit)
octechpus integrity-check             # Lista arquivos gerenciados editados fora da origem
octechpus integrity-check --strict    # Idem, falhando o CI também em divergências
octechpus update                      # Atualiza commands (preserva customizações)
octechpus profile list                # Lista profiles disponíveis
octechpus profile show <nome>         # Mostra profile resolvido (após herança)
octechpus profile current             # Mostra profile ativo do projeto atual
octechpus profile switch <nome>       # Troca o projeto para outro profile
octechpus design-system add           # Adiciona design system ao projeto
octechpus design-system update        # Sincroniza design-system/ com os templates mais recentes
octechpus vault init                  # Memória de projeto em grafo (docs/, formato Obsidian)
octechpus vault check                 # Cruza o vault com o filesystem (CI: exit 1 em erro)
octechpus vault map                   # Desenha o grafo do vault em docs/status/vault.html
octechpus dashboard                   # Painel único (andamento + grafo) em docs/status/dashboard.html
octechpus help                        # Ajuda

Vault de contexto (octechpus vault)

Cria em docs/ um vault em grafo: notas .md ligadas por wikilinks [[assim]], com entrada única em docs/00-INDEX.md.

docs/
  00-INDEX.md          — mapa de conteúdo: o único ponto de entrada
  dominio/             — glossario.md (o que as palavras significam aqui) e
                         invariantes.md (o que o negócio não permite)
  modulos/             — um nó por módulo: o que faz, invariantes, fronteiras
  sessoes/             — um nó por execução do pipeline, datado
  adr/                 — decisões de impacto medium/high

O ganho não é o formato — é a forma de leitura. O agente entra pelo índice e segue só os wikilinks que a demanda exige, em vez de carregar o projeto inteiro no contexto. O vault entra no init e no update por padrão (--no-vault recusa, e a recusa é registrada): a instrução de navegação vai para o CLAUDE.md, o agente Docs mantém as notas de módulo dos módulos tocados, e cada execução do pipeline vira um nó em docs/sessoes/ — o grafo se enche pelo trabalho que já foi feito.

• vault check cruza o vault com o filesystem (puro fs): caminho: órfão e wikilink que não resolve são erro (exit 1); nota fora do índice e Invariantes vazia são aviso. Serve de gate de CI, como o docs-check.
• vault map desenha o grafo em docs/status/vault.html (página única, sem rede) e imprime as lacunas — módulos ainda sem nota.

Nada depende do Obsidian: um vault é uma pasta de markdown, e qualquer editor lê o mesmo conteúdo. Abrir docs/ no Obsidian mostra o grafo.

O vault é do projeto: vault init nunca sobrescreve nota existente — rodar de novo é seguro, e só completa o que faltar. Use --force para trazer os modelos da release atual por cima. Ver ADR-013 (substitui o ADR-010).

Painel compartilhável (octechpus dashboard)

Funde a página de andamento (docs/status/index.html, escrita pelo agente /progress) e o grafo do vault (docs/status/vault.html, do vault map) num arquivo único: docs/status/dashboard.html — as duas visões em abas, cada uma embutida num <iframe srcdoc> (isolamento total de estilo, zero requisição externa).

octechpus dashboard        # gera/atualiza docs/status/dashboard.html

É o artefato de compartilhamento: envie o arquivo por anexo ou hospede como página estática — abre por duplo clique, sem servidor e sem internet. O comando é determinístico (mesma entrada ⇒ arquivo idêntico, sem carimbo de relógio) e puro fs, sem dependência nova. Sem vault, erra alto; sem andamento, a aba existe com um aviso em vez de sumir.

Duas metades, duas naturezas — e é isso que decide onde cada uma se atualiza:

| Metade | Origem | Atualiza sozinha? | |---|---|---| | Grafo | código determinístico (vault map) | ✅ em qualquer CI/hook | | Andamento | agente /progress (linguagem simples) | ❌ precisa de um LLM |

Por isso a atualização automática vive em dois pontos:

• No pipeline (passo 11b): depois de /progress, o orquestrador roda octechpus dashboard — o único ponto onde agente e código coexistem, e cai no mesmo commit da mudança.
• Na CI (push do main): o workflow octechpus-dashboard.yml regenera o grafo e comita se algo mudou, com três amarras contra loop (filtro de caminho invertido, guarda de ator, no-op em diff vazio). Instala por padrão; --no-dashboard recusa e registra a recusa no manifest.

Ver ADR-014.

Flags

| Flag | Efeito | |---|---| | --stack=<nome> | Força um profile, ignorando auto-detecção | | --describe=<file.md> | Infere a stack a partir de um doc .md do projeto | | --force | Sobrescreve arquivos existentes sem perguntar | | --minimal | Só o núcleo .claude/: commands + settings.json + agents (sem docs/GitHub) | | --dry-run | Preview do que seria criado, sem escrever nada | | --no-design-system | Pula o starter design-system/ (que é instalado por padrão) | | --no-vault | Pula o vault de contexto (instalado por padrão; a recusa é registrada) | | --no-dashboard | Pula o workflow de CI do painel compartilhável (instalado por padrão; a recusa é registrada) | | --keep-customizations | update pula arquivos editados pelo usuário (padrão: true) | | --allow-downgrade | Deixa o update rodar a partir de um CLI anterior ao manifest | | --strict | docs-check / secrets-check / integrity-check tratam avisos como erro |

O Verifier — o único agente que executa

Todo agente do pipeline lê o código. O Verifier o executa. Sem ele, o pipeline inteiro era auto-declarado: o QA reportava "cobertura estimada", o Security exigia npm audit sem poder rodá-lo (é read-only), e o pipeline podia terminar em ready_to_merge com o build quebrado.

Ele roda depois do Coder e antes do fan-out de análise:

Coder → ✅ Verifier → [Reviewer ∥ QA ∥ Security ∥ Privacy ∥ Cost] → Docs → Reporter → GitHub

| Etapa | 🔴 quando | |---|---| | build / compilação | erro de build | | type check | erro de tipo | | lint | erro de lint (warning → 🟡) | | testes | qualquer teste falhando | | cobertura | abaixo da meta do profile → 🟠 | | audit de dependências | vulnerabilidade high/critical |

Três regras que definem o agente:

1. Nunca reporta resultado que não obteve executando. Sem número estimado. Comando inexistente → n/a, nunca inventado. Falha de ambiente → error, não fail.
2. Não conserta nada. É o gate, não o Coder. Achou falha, devolve com a saída real.
3. Descobre os comandos do projeto (scripts do manifesto, Makefile, CI) em vez de presumir — funciona igual em Node, Python, Go, Rust ou Java.

Se o Verifier falha, o fan-out não roda. Não se gasta Reviewer, QA, Security, Privacy e Cost analisando código que não compila — é o único gate cujo veredito é exit code, não opinião de agente.

Escala de severidade — uma só

Antes havia duas (o Reviewer usava BLOCKER/WARNING/SUGGESTION, o Security usava CRITICAL/HIGH/MEDIUM/LOW) e o gate não sabia dizer se um 🟠 HIGH de segurança bloqueava. Agora todos os agentes usam a mesma:

| Nível | Gate | |---|:---:| | 🔴 BLOCKER — explorável / quebra o build / viola contrato | bloqueia | | 🟠 HIGH — risco significativo (vuln alta, PII em log, custo multiplicado) | bloqueia | | 🟡 WARNING — deveria ser corrigido | não bloqueia | | 🔵 INFO — melhoria opcional | não bloqueia |

🟡 e 🔵 viram débito técnico — e débito não morre no corpo do PR: o Reporter os emite em formato fixo e o agente GitHub abre uma issue por item (label octechpus:debt, idempotente por título) na Fase 2.

Segredos — o que é garantia e o que é mitigação

Três camadas, com escopos diferentes. Vale saber o que cada uma entrega:

| Camada | Onde | Garantia real | |---|---|---| | 1. Permissões (.claude/settings.json) | harness | Determinística para a ferramenta Read e para prefixos de comando. Não é infalível: shell tem infinitas formas de expressar a mesma leitura. | | 2. octechpus secrets-check | CI + pre-commit | Determinística para o que interessa: segredo que entra no repositório. Exit 1 quebra o build. | | 3. Guard nos prompts | agente | Best-effort. Cobre o que permissão não alcança — o que o agente escreve a partir do que já está no contexto. |

⚠️ Nenhuma combinação dá "zero possibilidade de vazamento" — quem prometer isso está vendendo. O que dá para garantir é: credencial não entra no repositório sem o CI falhar (camada 2), e o alcance de leitura do agente é estreito por padrão (camada 1). O resto é reduzir superfície.

A regra que mais reduz risco não é ferramenta, é arquitetura: o que o agente não consegue ler, não consegue vazar. Nesta ordem de preferência:

1. Secret manager (1Password/Vault/Doppler/AWS SM) injetando no processo — nada em disco.
2. .env fora da árvore do projeto (~/.config/app/.env), referenciado por caminho absoluto.
3. .env no projeto, gitignored — aceitável, e o padrão da maioria. É o que a camada 1 bloqueia para o agente.
4. ❌ Segredo em arquivo versionado — o que a camada 2 impede.

Uso

npx octechpus secrets-check          # exit 1 se achar credencial ou arquivo de segredo
npx octechpus secrets-check --strict # avisos (.gitignore, .env.example) também falham

Achados saem mascarados (AKIA****DFGH) — um scanner que imprime o segredo que encontrou é ele próprio um vazamento, e log de CI costuma ser público.

Falsos positivos em fixture ou documentação: marque a linha (ou a anterior) com octechpus:allow-secret.

No CI, junto do docs-check:

- run: npx octechpus secrets-check

No pre-commit (opcional, mas é onde o custo de um vazamento é zero):

printf '#!/bin/sh\nnpx octechpus secrets-check || exit 1\n' > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

🔑 Se o scanner achar algo real, remover o commit NÃO resolve — a credencial já esteve no histórico (e possivelmente em fork, cache do GitHub, log de CI). O único desfecho seguro é rotacionar a chave. Só depois limpe o histórico.

docs-check — CI para a documentação (v2.12)

O código passa por lint, testes e type check; a documentação passava por um checkbox. octechpus docs-check fecha esse buraco com quatro verificações mecânicas — exatamente as que, em campo, teriam evitado meses de acúmulo silencioso:

| Verificação | Severidade | |---|---| | Mais de uma seção ## [Unreleased] no CHANGELOG | erro (exit 1) | | Link relativo quebrado em qualquer .md | erro (exit 1) | | ADR com nome fora de ADR-NNN-titulo.md ou Status fora do enum | aviso | | Variável no .env.example sem uso no código (órfã) | aviso |

Use no CI: npx octechpus docs-check (ou --strict para rigor total). O agente Docs roda o check automaticamente antes de encerrar.

Arquivos gerenciados — o Octechpus se declara ao agente (v2.14)

O Octechpus gera arquivos para o Claude ler, mas até a v2.13 não se declarava a ele. O agente via um .md versionado no repo com conteúdo estranho e reagia como reagiria a qualquer código: consertava. Perguntado "por que esse arquivo está assim?", construía uma justificativa arquitetural plausível e errada para o que era interpolação de {{var}}.

Nenhuma camada isolada resolve isso — o dono do repositório sempre pode editar o próprio repositório. São cinco:

| Camada | Onde | Papel | |---|---|---| | Declara | Seção ⚠️ Arquivos gerenciados no CLAUDE.md gerado | Diz quais caminhos são gerados e o que acontece com cada um numa edição à mão | | Impede | Deny de Edit/Write em .claude/settings.json | Fecha o buraco do agente — onde a edição acontecia sem ninguém notar | | Preserva | Hash no manifest + skip no update | Edição que escapou não é perdida | | Denuncia | octechpus integrity-check · passo 8 do /audit | Divergência vira informação acionável, com nome de arquivo | | Protege | Guard de downgrade no update | CLI mais velho não regride a instalação |

O que acontece se você editar à mão

| Caminho | Efeito | |---|---| | .claude/commands/*.md | Congela — o update pula e o arquivo para de receber melhorias upstream | | .claude/agents/*.md | Congela — idem | | docs/OCTECHPUS_AGENTS.md | Congela — idem | | .claude/settings.json | Union-merge — suas regras são preservadas | | CLAUDE.md acima de 📋 PROJECT DOCUMENTATION | Sobrescrito no update |

Fora do deny de propósito: o CLAUDE.md (tem a seção do usuário no fim) e o settings.json (union-merge já preserva). O deny vale para as ferramentas do agente — npx octechpus update continua gerando os arquivos normalmente.

Quer ajustar o comportamento de um agente? Não edite o arquivo gerado — use overrides. É customização sem congelamento.

integrity-check

npx octechpus integrity-check          # exit 1 se faltar arquivo gerenciado
npx octechpus integrity-check --strict # divergências também falham (CI)

✓ 31/33 arquivo(s) gerenciado(s) idêntico(s) ao template

⚠ 1 arquivo(s) alterado(s) fora da origem:
    • .claude/agents/coder.md
  → Melhoria de verdade: leve para Phaiolli/octechpus-cli
  → Ajuste local do projeto: use .claude/overrides/coder.md
  → Descartar a edição: npx octechpus update --force

Semântica deliberada: arquivo faltando é exit 1 sempre (o pipeline perdeu um agente sem avisar ninguém); arquivo alterado é exit 0 com aviso, exit 1 só com --strict. Editar um arquivo gerenciado não é proibido — é uma decisão com custo, e o papel da ferramenta é tornar o custo visível, não bloquear.

Guard de downgrade

Um update rodado por um CLI anterior ao que gerou os arquivos regenerava tudo a partir dos templates velhos: features de versão nova sumiam sem erro nenhum, e a única pista ficava no campo version do manifest. Acontece com cache velho de npx, e é permanente em repositório de dogfooding. Agora bloqueia antes de escrever qualquer coisa, indicando octechpus@latest, o código local, ou --allow-downgrade para rollback proposital.

Detalhes da decisão: ADR-006.

Rastreamento de customizações

octechpus update armazena um hash SHA-256 de cada arquivo gerado em .octechpus/manifest.json. Em updates subsequentes, compara o hash armazenado com o conteúdo atual:

• Hash bate → arquivo não foi editado → atualiza
• Hash diverge → arquivo foi customizado → pula (preserva suas edições)
• --force → sobrescreve tudo independente de customizações

Overrides do projeto — personalize sem sair do canal de update (v2.12)

O dilema clássico: corrigir um template localmente significava ou perder a correção no próximo upgrade, ou ficar marcado como customizado e parar de receber melhorias. A camada de overrides resolve os dois:

# .claude/overrides/docs.md  (arquivo SEU — o CLI nunca o toca)
Sempre atualizar também o glossário em docs/glossario.md.

O conteúdo é anexado ao final do agente (.claude/agents/docs.md) e do slash command (.claude/commands/docs.md) em todo init/update/profile switch, numa seção "Ajustes do projeto". Pares com nomes divergentes (designer↔design, github↔github-issue) compartilham o override por qualquer um dos nomes.

Outros pontos que continuam seus, fora do manifest: docs/project-context.md (documentação específica do projeto, referenciada pelo CLAUDE.md gerenciado) e .claude/settings.local.json (permissões pessoais — o CLI só o toca para migrar regra de caminho inerte, e nunca o cria).

Baseline com prune e opt-out (excludeRules)

O merge do settings.json preserva toda regra sua, mas deixou de ser aditivo puro para o que o próprio Octechpus escreveu: o baseline emitido fica registrado em .octechpus/manifest.json → baselineRules, e regra que o baseline anterior emitiu e o atual não emite mais é removida no próximo init/update/profile switch. Trocar de profile deixa de acumular guardrails do profile antigo para sempre.

Para dispensar uma regra do baseline neste projeto (ex.: o ask de Bash(git push:*), que gera prompt até em bypassPermissions), declare no manifest — match exato da regra:

{
  "excludeRules": ["Bash(git push:*)"]
}

No próximo update a regra sai do settings.json e nunca é reinjetada. octechpus doctor lista as exclusões ativas — dispensar regra de segurança é decisão visível, não buraco esquecido. Detalhes e limites: docs/adr/ADR-008.

Skills por stack — conhecimento sob demanda

Desde a v2.19, o CLAUDE.md emite quatro skills (convencoes-da-stack, padrao-de-testes, checklist-de-revisao, fluxo-de-commit-e-release) em .claude/skills/<nome>/SKILL.md, renderizadas a partir de campos do profile.

O ganho é a forma de leitura. Blocos que já estavam nos prompts dos agentes específicos (coder, qa, review, github-issue) são consultados pelo caminho ad-hoc — agente editando um arquivo sem passar pelo /pipeline. As skills são arquivos gerenciados: hash no manifest, overrides valem, skipped se customizado (--keep-customizations). Perdem o guard anti prompt-injection porque são consultadas por um agente que já o carrega — seguro por construção.

O template do CLAUDE.md encolhe ~30% e ganha a capacidade de encolher sem travar a base instalada, via RETIRED_MANAGED_HEADINGS — lista de headings do passado para não os classificar como seção do usuário. Ver ADR-011.

Leia a skill deliberadamente com /skills nome ou deixe-a ser carregada quando a demanda casar com a description. octechpus doctor lista as skills ativas.

Hooks por profile — verificação determinística

Desde a v2.19, dois hooks podem ser ligados por projeto no settings.json:

| Hook | Evento | Matcher | O que faz | |---|---|---|---| | stop_check | Stop | — | Roda a suíte do projeto ao encerrar o turno. Determinístico (sem prompt), bloqueante. | | post_edit_format | PostToolUse | Edit\|MultiEdit\|Write | Formata o projeto após edição de arquivo. Apenas em stacks que o declaram. |

Ambos residem em baselineHooks no manifest, permitindo prune análogo ao ADR-008: trocar de profile limpa o hook antigo, desligar o opt-in remove de verdade. Comandos vêm exclusivamente do YAML do pacote, proibindo interpolação e metacaracteres de shell — segurança + portabilidade Windows.

Habilitação:

# Ver status
octechpus doctor
# → "Hooks disponíveis: stop_check (desligado), post_edit_format (desligado)"

# Ligar
npx octechpus init --stack=seu-stack  # gera manifest.json
# ou editar: .octechpus/manifest.json → "hooks": { "stop_check": true }

Contraindicação crítica (Security): não ligue stop_check num repositório que você não confia o bastante para rodar a suíte inteira. O hook:

• Roda fora do deny — permissões do baseline não se aplicam
• Roda sem prompt — a cada fim de turno
• Erra quando a suíte já estava vermelha por motivo alheio — o agente passa a "consertar" o que ninguém pediu (violação de mudanças cirúrgicas)

Se a suíte está verde e é rápida (< 2 min), está seguro ligar. Se está falhando ou é lenta, deixe desligado e rode o /verify quando precisar. O Verifier é do pipeline, onde há contexto para decidir se refaz. Ver ADR-012.

Criando um profile customizado

1. Crie src/profiles/meu-stack.yaml herdando da base mais próxima:

extends: _base        # ou python-fastapi, node-typescript, etc.
name: meu-stack
description: "Minha stack customizada"

language: kotlin
runtime: "jvm>=21"
package_manager: gradle

testing:
  framework: junit5
  coverage_target: 80

design_system:
  tokens: none

2. Valide o profile:

node src/cli.mjs profile show meu-stack

3. Use:

octechpus init --stack=meu-stack

Consulte docs/profiles.md para a especificação completa do schema.

Projetos existentes

O CLI detecta CLAUDE.md existentes e faz merge automaticamente — seu conteúdo é preservado abaixo da seção gerada pelo Octechpus.

cd projeto-existente
octechpus init
octechpus status

Migração do 1.x

npm install -g octechpus
cd seu-projeto
octechpus init        # detecta stack, faz merge do CLAUDE.md, atualiza commands
octechpus status
octechpus doctor

Breaking changes na 2.0:

• CLAUDE.md ganhou seção Stack Profile no topo — o init faz merge automaticamente
• docs/AGENTS.md renomeado para docs/OCTECHPUS_AGENTS.md
• Commands passaram a usar placeholders {{stack.xxx}} em vez de nomes de linguagem hardcoded

Testes

npm test              # 773 testes, ~12s
npm run test:watch    # modo watch
npm run test:coverage # com cobertura

Cobertura: profile-loader, stack-detector, template-renderer, profile-advisor, cli-init, cli-permissions, cli-profile-commands, template-rendering-integration, agents-commands-sync, docs-check, secrets-scan, file-ops, settings-builder, vault, vault-check, agent-write-scope, dashboard.

Publicar no npm

A versão vive em dois lugares que precisam ficar em sync: package.json e src/lib/version.mjs. (Até a v2.17 essa constante morava em src/cli.mjs; saiu de lá na modularização — ADR-009.)

# bumpe version em package.json e src/lib/version.mjs (em sync) + CHANGELOG
npm test
git add package.json src/lib/version.mjs CHANGELOG.md
git commit -m "chore(release): bump version to X.Y.Z"
git push origin main

Manual — é o caminho que funciona hoje. Requer token npm válido em ~/.npmrc:

npm whoami && npm publish --access public && npm view octechpus version

Automático (pendente de configuração): o workflow .github/workflows/publish.yml publica via OIDC / Trusted Publishers quando a versão muda no main (e pula se já estiver no npm). Ele ainda falha com npm error code ENEEDAUTH porque falta o vínculo — passo único no npmjs.com: pacote octechpus → Settings → Trusted Publisher → GitHub Actions (Phaiolli/octechpus-cli, workflow publish.yml, Environment em branco). Feito isso, gh workflow run publish.yml --ref main publica sem precisar de novo commit.

Detalhes e troubleshooting de auth: ver CLAUDE.md → "Como publicar no npm".

Links

• npm: npmjs.com/package/octechpus
• GitHub: github.com/Phaiolli/octechpus-cli
• Issues: github.com/Phaiolli/octechpus-cli/issues

Versão atual

2.21.0 — Um painel único e compartilhável. octechpus dashboard funde a página de andamento e o grafo do vault num arquivo único, offline (docs/status/dashboard.html) — as duas visões em abas, cada uma num <iframe srcdoc>, zero requisição externa: envia-se como anexo. Determinístico e puro fs, sem dependência nova. O pipeline atualiza o painel no passo 11b (o único ponto onde agente e código coexistem), no mesmo commit da mudança; e um workflow de CI mantém o grafo em dia entre pipelines, com três amarras contra loop. Instala por padrão, --no-dashboard recusa (ADR-014).

2.20.0 — O vault vira o modelo de contexto do sistema. O grafo deixa de ser opt-in: entra no init e no update por padrão (--no-vault recusa, com a recusa registrada), a raiz é configurável e validada, e o pipeline passa a escrever nele — uma nota de sessão por execução (persistida pelo orquestrador, não pelo Reporter read-only) e a nota de módulo atualizada por toda demanda que toca o módulo, então o grafo se enche pelo trabalho já feito. Nova camada docs/dominio/ (glossario.md + invariantes.md) ataca a maior fonte de erro de agente fora do código: vocabulário errado. vault check cruza o grafo com o filesystem como gate de CI (puro fs, sem dependência nova) e vault map desenha o grafo em docs/status/vault.html. O campo leitor: agente | humano governa a tolerância à obsolescência — o check verifica os nós de agente e ignora os de humano. Fecha a #27 com uma invariante estrutural travada por teste: instrução de escrita nunca é injetada em agente sem ferramenta de escrita (ADR-013, substitui o ADR-010).

2.19.0 — Conhecimento sob demanda e verificação determinística. Três mudanças no custo de contexto: (1) quatro skills renderizadas por profile (convencoes-da-stack, padrao-de-testes, checklist-de-revisao, fluxo-de-commit-e-release) substituem blocos do CLAUDE.md que já eram duplicados nos prompts dos agentes específicos — template cai ~30%, só o caminho ad-hoc perde detalhe e ganha um ponteiro nominalizado. Skills são arquivos gerenciados com hash e overrides (ADR-011); (2) dois hooks podem ser ligados por projeto (opt-in): stop_check roda a suíte como barrier ao fim de turno, post_edit_format formata o projeto pós-edição — ambos determinísticos, residem no settings.json, com prune análogo ao ADR-008 — e portabilidade Windows via proibição de metacaracteres (ADR-012); (3) campo model: no frontmatter dos agentes permite override por subagente (padrão inherit, que deixa a sessão decidir — pinar modelos revertiria o ADR-005 item 4 com evidência de campo). Segurança: não ligue stop_check num repositório que você não confia executar inteiro — roda fora do deny, sem prompt, a cada fim de turno.

2.18.0 — Memória de projeto que sobrevive ao merge. O novo octechpus vault init cria em docs/ um vault em grafo (formato Obsidian): 00-INDEX.md como único ponto de entrada, modulos/ com invariantes e armadilhas de cada módulo, sessoes/ com uma nota por execução do pipeline, tudo ligado por wikilinks. O ganho não é o formato — é a forma de leitura: o agente entra pelo índice e segue só os links que a demanda exige, em vez de carregar o projeto inteiro no contexto. Com o vault presente, o CLAUDE.md ganha a instrução de navegação, o Docs mantém as notas dos módulos tocados e o Reporter grava a sessão — sem vault, nada muda. Adesão explícita, nunca sobrescreve nota existente, zero dependência nova (ADR-010). Junto: o cli.mjs foi de 2.375 para 153 linhas — um módulo por comando em src/commands/, helpers em src/lib/, refactor puro verificado saída-a-saída contra o HEAD anterior (ADR-009) —, e a migração de regra inerte passou a logar os pares antes→depois (Glob(src/**) → Read(src/**)), com marca de atenção só no allow, o único tier onde a conversão concede.

2.17.0 — A regra que o profile antigo deixou para trás finalmente sai. A v2.16.0 ligou regras que estavam mortas, e o campo mostrou o efeito colateral: guardrail de profile antigo, órfão pelo merge só-aditivo, bloqueando pastas que o fluxo real precisa editar — sem opt-out durável, porque deny vence allow em qualquer arquivo, inclusive em bypassPermissions. Agora o baseline emitido é registrado no manifest e podado no merge seguinte; regra que nunca esteve em baseline (a sua) é sempre preservada. Para o resto, manifest.json → excludeRules remove por match exato e nunca reinjeta, com o doctor listando as exclusões ativas (ADR-008). Quatro correções que valem citar: {{#each}} corrompia item contendo $ (e profiles carregam regex nos arrays); octechpus status meuprojeto rodava em silêncio no cwd em vez de errar alto; docs-check reprovava todo link relativo válido no Windows por um separador POSIX cravado; e octechpus --version imprimia o help inteiro, porque os case de flag no roteador eram inalcançáveis.

2.16.0 — O que era escrito à mão no CLAUDE.md para de sumir. Duas correções de perda de dados, uma delas observada em campo (327 linhas apagadas em silêncio). O profile switch reescrevia o arquivo inteiro quando faltava o marcador 📋 PROJECT DOCUMENTATION — e a mensagem do update mandava o usuário justamente para lá. O update, por sua vez, descartava tudo acima do marcador, onde os projetos guardam regra de negócio e tabela de gate lida pelo CI. Agora seção que não veio do template faz o comando recusar e listar o que se perderia; --force assume a perda. Toda sobrescrita passa a gravar backup em .octechpus/backups/. Junto: as regras Write(path) do settings.json, que o Claude Code aceita mas nunca consulta — 13 avisos por sessão —, viram Edit(path), e o update converte as que já estão nos projetos, porque um merge só-aditivo nunca as removeria.

2.15.0 — /progress: a página que o cliente abre. Um comando novo gera docs/status/index.html — andamento do projeto em português simples, sem sigla, sem score, sem escala de severidade — com histórico por período e prova citada (SHA, issue fechada, PR mesclado) para toda afirmação de "pronto". Descobre o vocabulário de fase do projeto em vez de assumir (milestone → doc de plano → CHANGELOG+tags → semana), trata "parado" como categoria própria com limiar visível, é idempotente (carimba a data do último commit, não a do relógio), abre por duplo clique sem rede, e escapa título de issue nas duas camadas — HTML no corpo e unicode no JSON embutido, porque um </script> num título fecha o bloco. Entra no pipeline como passo 11b, depois do Reporter. Automação de atualização é proposta, nunca instalada.

2.14.1 — O Octechpus passa a se declarar ao agente. Os arquivos gerados são output de template, não código-fonte do projeto — e nada dizia isso, então o agente os "consertava" e inventava justificativa arquitetural para o que era interpolação de {{var}}. Cinco camadas: o CLAUDE.md declara, o settings.json impede (deny de Edit/Write), o update preserva, o novo octechpus integrity-check e o passo 8 do /audit denunciam com nome de arquivo, e um guard de downgrade protege contra CLI velho regredindo a instalação. Corrige docs/OCTECHPUS_AGENTS.md, que era sobrescrito cego a cada update. Zera o npm audit (js-yaml → 4.3.1, vitest → 4.x).
Veja o CHANGELOG e a ADR-006.

Veja o CHANGELOG para o histórico completo.

Licença

MIT