CLI Creator (Criador de CLI)

O que CLI Creator (Criador de CLI) faz?

Roteador para construir e auditar ferramentas CLI Python de nível de produção e skills/modelos relacionados a CLI. Use-o para decidir a forma da CLI, manter a superfície de comandos pequena, preservar a capacidade de instalação e reforçar saídas de revisão. Este skill permanece leve: leia apenas as referências necessárias.

Quando Usar

• Nova CLI Python ou árvore de comandos.
• Refatoração de CLI, simplificação ou limpeza de empacotamento.
• Revisão/auditoria de CLI, incluindo UX, configuração, erros, cache e fluxo de lançamento.
• Skill de agente, scaffold ou modelo que se comporta como um pacote CLI.
• Verificação de instalação, wheel ou comportamento de console-script.

Seleção de Tipo de CLI

Tipo	Viés
Utilitário comando-primeiro	Roteador enxuto, códigos de saída estritos, saída JSON/plana.
Ferramenta orientada a configuração	Descoberta de config, precedência, reprodutibilidade.
Assistente interativo	Fluxo/máquina de estados, prompts, recuperação.
CLI híbrida	Pequena árvore de comandos mais orquestração reutilizável.
CLI com foco em desempenho	Imports lentos (lazy), IO limitado, cache/progresso.
CLI extensível/plugins	Contrato de extensão estável e registro.

Não force uma arquitetura de assistente em uma ferramenta comando-primeiro. Não force a forma de script único em um produto em crescimento.

Regras Principais

• Prefira o menor CLI que resolva o trabalho do usuário.
• Use o caminho mínimo/YAGNI: se a ferramenta tem um ou dois comandos, sem estado persistente, sem rede, sem plugins e sem credenciais, mantenha-a pequena; não adicione Rich, Pydantic, platformdirs, camadas de cache, doctor ou registros de plugin a menos que resolvam um problema imediato.
• Mantenha nomes, flags, códigos de saída, chaves de configuração e modos de saída estáveis.
• Torne os padrões úteis e seguros.
• Separe roteamento, lógica de domínio, IO, configuração, persistência, renderização e integrações.
• Mantenha a saída da máquina scriptável com modo JSON ou plano.
• Verifique se o comando do README é o console script instalado.

Regras de Carregamento de Referências

Leia apenas as referências necessárias para a tarefa:

• Criação ou refatoração: references/creation-playbook.md.
• Revisão ou auditoria: references/review-rubric.md e references/pitfalls-and-solutions.md.
• Detalhes de implementação, empacotamento, segurança, comportamento multiplataforma, saída Rich, cache ou provedores LLM: references/technical-best-practices.md.
• Para manutenção de skill/pacote, consulte as pastas de governança raiz do workspace skill-ir/, evals/, scripts/, reports/ e registry/ quando existirem. Estes são auxiliares de roteamento do mantenedor, não incluídos em uma cópia instalada do skill.

Não duplique essas referências aqui. Carregue-as apenas quando a tarefa atual precisar delas.

Fluxo de Criação de Nova CLI ou Skill

1. Determine a forma do produto: quem o executa, sob qual pressão está e o que deve ser armazenado em cache, lembrado ou esquecido.
2. Projete a superfície de comandos com alguns comandos estáveis e exemplos reais.
3. Escolha a menor pilha que se encaixa.
   • Typer ou Click para a maioria das CLIs.
   • argparse apenas para ferramentas minúsculas compatíveis com a stdlib.
4. Escolha a menor arquitetura que sobreviverá aos próximos dois lançamentos.
5. Implemente o loop do produto: entrada, validação, execução, renderização, persistência, código de saída, dica de recuperação.
6. Verifique antes do lançamento.

Exemplos de Superfície de Comandos

my-cli run
my-cli init
my-cli config show
my-cli doctor
my-cli cache clear
my-cli check PATH
my-cli fetch QUERY --json
my-cli export ID --output result.md

Regras:

• Use argumentos para objetos de domínio obrigatórios.
• Use opções para modificadores, modos de saída e comportamento opcional.
• Forneça --json ou --format json para automação.
• Forneça --quiet, --verbose e --debug de forma consistente.
• Evite rede surpreendente ou mutação em comandos que soam como somente leitura.

Expectativas de Verificação

Sempre verifique a superfície de comandos, o caminho de instalação e o caminho do wheel quando forem relevantes:

• --help para o comando raiz e cada comando de nível superior.
• Instalação limpa em um novo ambiente.
• Configuração ausente ou caminho de primeira execução quando a ferramenta tem configuração.
• Configuração inválida ou caminho de erro quando a ferramenta valida entrada.
• Caminho de sucesso mais modo JSON/scriptável quando suportado.
• Atualização de cache e limpeza de cache quando a ferramenta tem cache.
• Metadados de empacotamento e console script.
• Instalação via wheel de fora do repositório quando você quer confiança na instalação.

Use este pacote compacto quando aplicável:

uv venv /tmp/cli-audit
. /tmp/cli-audit/bin/activate
uv pip install -e .
cli-creator-skill --help
cli-creator-skill install
uv build
uv pip install dist/*.whl
python -m pytest

Fluxo de Revisão

Ao auditar uma CLI existente ou skill/modelo relacionado a CLI:

Antes de revisar, leia:

• references/review-rubric.md
• references/pitfalls-and-solutions.md

Leia references/technical-best-practices.md quando a auditoria tocar em detalhes de implementação, empacotamento, segurança, comportamento multiplataforma, saída Rich, caching ou provedores LLM.

Então:

1. Inspecione a forma do repositório: estrutura do pacote, pontos de entrada de comandos, arquivos de configuração, testes, docs, CI.
2. Execute help: --help raiz e help de nível de comando.
3. Trace um comando bem-sucedido do callback ao serviço de domínio ao renderizador.
4. Trace um caminho de falha e inspecione a qualidade do erro.
5. Verifique a precedência da configuração: flags, env, configuração do projeto, configuração do usuário, padrões.
6. Verifique segurança: segredos, execução de shell, manipulação de caminhos, configuração/plugins inseguros, telemetria, timeouts de subprocesso, cadeia de dependências.
7. Verifique desempenho: imports na inicialização, timeouts de rede, comportamento de cache, descoberta de arquivos.
8. Verifique automação: códigos de saída, saída JSON, separação stdin/stdout/stderr, comportamento não-TTY.
9. Verifique empacotamento: versão do Python, dependências, scripts, wheels, comandos do README.
10. Pontue cada área da rubrica com references/review-rubric.md.
11. Apresente primeiro os achados, depois as correções priorizadas.

Saída de Auditoria Obrigatória

A saída da auditoria deve incluir estas seções, nesta ordem:

**Achados**

**Pontuações**

| Área | Pontuação | Notas |
|---|---:|---|

**Ordem de Reparo**

**Lacunas de Teste**

**Comandos de Verificação**

Notas de Manutenção

• Mantenha este skill como um roteador; coloque os detalhes de implementação nas quatro referências.
• Mantenha os exemplos de comandos, os cabeçalhos de auditoria e o pacote de verificação sincronizados com o lançamento do pacote.
• Para governança do lado do mantenedor, use as pastas skill-ir/, evals/, scripts/, reports/ e registry/ na raiz do workspace quando presentes; não finja que elas fazem parte do skill instalado.

Com o Que Este Skill Ajuda

• Projetar uma nova CLI Python do zero.
• Revisar uma CLI existente quanto a UX, empacotamento, erros, configuração de modelo, caching e capacidade de manutenção.
• Estruturar aplicações Typer, Click, argparse ou híbridas.
• Construir fluxos naturais de CLI de múltiplas etapas sem fazer os usuários sentirem que estão preenchendo um formulário.
• Adicionar diagnósticos, cache, perfil de memória e fluxos de configuração de primeira execução quando eles são realmente necessários.
• Revisar skills e modelos relacionados a CLI quanto à clareza de gatilho, completude de referências, modelos de comando, contratos de saída e estratégia de manutenção.

Base de Design

Este skill destila a experiência do mantenedor e padrões de documentação oficial para empacotamento Python, Typer, Click, Rich, uv, Ruff, Pydantic e integração de provedores LLM. Ele não inclui código ou instruções de repositórios não oficiais de terceiros.