Referência de Comandos

O ai-core-kit oferece dois tipos de comando de barra, divididos ao longo da fronteira META vs CHILD:

• Comandos META vivem no próprio .claude/commands/ do kit e operam sobre o próprio kit ou sobre um fork durante a configuração. São exatamente dois: /ack-build (construir o kit) e /ack-init (inicializar um fork).
• Comandos CHILD vivem em templates/commands/ e são renderizados em um fork pelo /ack-init. Estes são os comandos de entrega do dia a dia que os desenvolvedores de um projeto filho invocam: o trio RPI mais o par de planejamento de produto.

As skills invocáveis pelo usuário (skill-creator, skill-validator, mcp-builder, cost-telemetry) são invocadas pelo modelo ou por humanos, em vez de serem comandos de barra; elas estão listadas no final por completude e detalhadas no Catálogo de Skills.

Mas os comandos de barra não são a única superfície — a CLI create-ack é a espinha dorsal. Tudo que você faz no Claude Code ou no site, você também faz a partir de um único binário, em qualquer terminal ou runner de CI.

A CLI create-ack — a espinha dorsal

O princípio que guia o kit é que tudo é alcançável pela CLI, não apenas pelos comandos de barra do Claude Code ou por este site. create-ack é um único binário (o pacote npm @arthurghz/create-ack) que você roda com npx @arthurghz/create-ack@latest …, ou instala uma vez com npm i -g @arthurghz/create-ack@latest.

Ela agrupa seu trabalho em subcomandos. O scaffold é o comando original; os subcomandos de telemetria são invólucros finos sobre as ferramentas Python (stdlib) em telemetry/ — o mesmo código documentado em Observabilidade, exposto sob uma única CLI para que você nunca precise lembrar de uma invocação python3 telemetry/<script>.py.

Status, honestamente. O scaffold (new/scaffold) já é entregue hoje (@arthurghz/create-ack@0.1.0). Os motores de telemetria sob telemetry/ são reais e rodam hoje via python3 telemetry/<script>.py … — a tabela mostra a superfície unificada create-ack <verbo> que os envolve para que a CLI seja a espinha dorsal única. Até que um subcomando esteja conectado na sua versão instalada, chame a ferramenta subjacente diretamente; as flags e o comportamento são idênticos. Acompanhe a paridade no roadmap.

Por que a CLI, e não só comandos de barra

Comandos de barra precisam de uma sessão do Claude Code; o site é somente leitura. A CLI não precisa de nenhum dos dois. Um job de CI, uma entrada de cron, um colega sem Claude Code, ou um rápido create-ack cost --by feature entre turnos — todos alcançam as mesmas capacidades. O custo permanece offline em todo lugar — é derivado das transcrições locais × um mapa de preços versionado, nunca uma API ao vivo (não há API de custo ao vivo em hooks; issue #11008). O DORA permanece exato em todo lugar — ele lê o histórico git.

Atribuição de custo por feature vs por branch

O create-ack cost (e o aggregate.py) pode atribuir o gasto a uma feature de duas maneiras, e a escolha é sua:

• branch_prefix (o padrão, zero configuração). A feature de um turno é inferida da branch git em que ele rodou: com --branch-prefix feat/, o trabalho em feat/order-intake é agrupado em order-intake. Nada para manter — mas é tão granular quanto suas branches, e turnos na main (ou em qualquer branch sem o prefixo) caem no --default-bucket (ex.: unattributed).
• sidecar_map (preciso, opt-in via create-ack feature). O create-ack feature <id-do-contrato> escreve uma entrada sidecar {from: <agora>, to: null, bucket: <id-do-contrato>}; rodá-lo de novo (ou com a feature finalizada) fecha a janela aberta. O aggregate.py --sidecar-map <arquivo> então atribui cada turno por timestamp → contrato, independentemente da branch. Isso é a única coisa que um hook de sessão pode registrar honestamente — um mapeamento timestamp→contrato, nunca um custo — então combina naturalmente com os IDs C-NNN do portão de contrato.

Escolha branch_prefix quando suas branches já acompanham features; recorra ao create-ack feature quando quiser o gasto fixado em contratos específicos, independentemente de como você cria branches. As duas são mutuamente exclusivas por execução — um --sidecar-map fornecido sobrescreve o --branch-prefix.

Comandos META

/ack-build — orquestrador de build META

Orquestra o próprio auto-build do kit a partir de bootstrap/ack.bootstrap.yaml. Lê a configuração de build orientada a dados, valida-a contra seu JSON-Schema e então conduz o build fase por fase com uma equipe multiagente por fase (verdade-fundamental -> autor -> QA adversarial), expondo o status por fase e o custo cumulativo offline, parando em cada gate para aprovação.

Roda somente dentro do repositório META do ai-core-kit. Ele recusa a menos que ambos os sentinelas META estejam presentes (bootstrap/ack.bootstrap.yaml e docs/BOOTSTRAP.md). É o inverso de /ack-init.

Argumentos (todos opcionais):

Garantias e invariantes:

• O custo é sempre offline. Não há API de token/custo ao vivo em hooks (issue #11008). O gasto cumulativo é computado por telemetry/aggregate.py sobre ~/.claude/projects/**/*.jsonl multiplicado por um pricing.json versionado. Se o agregador ainda não existir, ele reporta cost: unavailable (P6 pending) e prossegue — nunca fabrica um número.
• A verdade-fundamental é obrigatória por fase. Cada fase de autoria clona meta.reference_repos para extração exata e verifica os primitivos contra code.claude.com/docs antes de escrever.
• Disciplina de camada. /ack-build escreve somente artefatos META. Se um worker fosse escrever um project.manifest.yaml concreto, uma instância de contrato ou uma entrada de contract-gate na raiz META, isso é uma violação de camada e é recusado.
• done: é gerenciado pelo operador. Autorar uma fase não muda sua flag done — essa é uma decisão humana após revisar o QA.

Veja Construindo o Kit: /ack-build para o passo a passo completo.

/ack-init — inicializador de projeto CHILD

Inicializa um projeto CHILD forkado. Pergunta o arquétipo primeiro, roda uma entrevista determinística com escopo no arquétipo, escreve project.manifest.yaml (a única fonte de verdade), renderiza o conjunto de templates do arquétipo e conecta hooks / MCP / telemetria / descoberta opt-in. É reentrante e idempotente via merge de bloco gerenciado.

Este é o /ack-init, não o /init — a skill init embutida é dona do /init. Rode-o em um repositório CHILD forkado, nunca no repositório META do ai-core-kit. Ele recusa (fail-closed, sem flag de override) se qualquer sentinela META estiver presente: um diretório templates/archetypes/ ou um arquivo docs/BOOTSTRAP.md.

Argumentos (todos opcionais):

Sequência de passos:

1. Guarda de repositório META — fail-closed se rodando dentro do próprio ai-core-kit.
2. Detectar modo e reentrância — interativo vs QA; sonda se um manifesto já existe (re-execução -> território de merge).
3. Congelar o contrato, perguntar o arquétipo primeiro — verificação cruzada de que o writes_to de cada pergunta da entrevista resolve para uma propriedade real do schema (invariante I1); o arquétipo é o eixo de ramificação (invariante I3).
4. Rodar a entrevista, escrever o manifesto — a entrevista é a única escritora; managed: é regenerado por inteiro, user: é semeado uma vez e preservado; valida contra o schema antes de qualquer escrita irreversível (fail-closed, invariante I6); computa manifest_hash por último.
5. Renderizar via o render engine contra managed:.
6. Conectar integrações conforme os toggles opt-in usando merge de bloco gerenciado delimitado (nunca sobrescrita cega).
7. Emitir um CLAUDE.md filho mínimo apontador e atualizar o ledger rendered_files[].

Menu de arquétipos: backend-api e fullstack renderizam profundamente (subconjunto completo de perguntas + conjunto de templates); monorepo, library-sdk, infra-iac são conhecidos pelo schema e renderizam um núcleo mínimo na v1 (um aviso é impresso quando um deles é selecionado).

Um comando de barra invocado pelo usuário não pode ser invocado pelo nome sob claude -p. O modo QA / não interativo é alcançado embutindo a tarefa e canalizando um arquivo de respostas via stdin. A mesma guarda de repositório META, validação de schema e merge idempotente se aplicam inalterados.

O modelo produtor/consumidor por trás do manifesto é coberto em Manifesto e Entrevista; o passo a passo de primeiros passos está em Início Rápido.

Comandos CHILD (renderizados em um fork)

Estes são oferecidos em templates/commands/ e renderizados em um projeto filho pelo /ack-init. São os comandos de entrega cotidianos da equipe do projeto.

RPI: Research -> Plan -> Implement

O loop de entrega padrão do kit para trabalho não trivial. Cada etapa tem um gate de aprovação (Research -> Plan -> Implement).

Os comandos RPI foram reescritos para o ai-core-kit a partir de shanraisshan/claude-code-best-practice (MIT). Veja o Ledger de Licenças.

Planejamento de produto

/prd e /rice são originais do ai-core-kit.

Skills invocáveis pelo usuário

Estas são skills, não comandos de barra — o modelo as invoca quando o gatilho de sua description corresponde, e um humano pode invocá-las pelo nome. As quatro que vêm no próprio .claude/skills/ do kit (ferramental de build META) são as mais propensas a serem executadas diretamente:

As skills de payload CHILD (coding-standards, production-audit, language packs e assim por diante) são carregadas por agents durante a entrega, em vez de serem invocadas como comandos. O catálogo completo com proveniência e gatilhos de conexão está no Catálogo de Skills.

Frontmatter de comando

Todo arquivo de comando é markdown com frontmatter YAML. Apenas description é obrigatório; o linter avisa sobre chaves não reconhecidas e gera erro nas chaves proibidas para SKILL. Veja Contribuindo para as convenções completas de frontmatter e o linter.

---
description: One-line, third-person summary of what the command does.   # REQUIRED
argument-hint: "[--flag] [<arg>]"                                       # OPTIONAL
allowed-tools: Read, Write, Bash(git status:*)                          # OPTIONAL
disable-model-invocation: true                                          # OPTIONAL (human-only)
---