A skill termfy-init prepara um repositório criado a partir do starter kit
e mantém as skills do framework instaladas. No modo de setup, ela aplica a
identidade do seu binário, instala as dependências, confere as skills e os
três modos e roda a validação completa. No modo de manutenção, ela instala,
atualiza ou repara as skills sem mexer no produto. No fim, você tem um
projeto com o nome certo em package.json, as skills conferidas e o
caminho aberto para a termfy-clispec.
Quando usar
Use a termfy-init nestas situações:
- Você acabou de criar o repositório com Use this template e o
bun run dev -- --versionainda respondetermfy. - As skills de
.agents/skills/estão desatualizadas, faltando ou com arquivos quebrados. - O
bun run skills:checkfalha dentro dobun run validate.
Prefira outra skill nestes casos:
- O setup já foi feito e você quer trocar título, cores, créditos ou o próprio nome do executável: use termfy-brand.
- Você quer descrever o que o binário faz: use termfy-clispec.
- Você só tem a ideia e quer que o agente conduza tudo: use
termfy, que chama a
termfy-initquando precisa.
Como pedir
Para o setup de um projeto novo, com todos os campos de uma vez:
Use a skill termfy-init para preparar este projeto com o nome mycli, o título My CLI, a descrição “Query shop orders from the terminal.”, o autor Loja Exemplo e o repositório
https://github.com/loja-exemplo/mycli.
Para atualizar as skills de um projeto que já existe:
Use a skill termfy-init para atualizar as skills do Termfy no mycli.
Para reparar uma instalação quebrada:
Use a skill termfy-init para reparar as skills: o skills:check diz que falta a pasta references da termfy-spec.
O que a skill faz
Primeiro, a skill informa o modo escolhido (setup ou manutenção) e os arquivos que vai conferir. Ela só pergunta quando o pedido não deixa claro qual dos dois você quer.
No modo de setup:
- Pergunta os campos que faltarem: nome do executável (minúsculas, números e hífen), título, descrição em uma frase, autor, URL do repositório e site.
- Roda
git status --shorte preserva as mudanças locais. - Roda
bun install. - Roda o bootstrap com os campos conhecidos:
bun run init -- --name mycli --title "My CLI" .... - Executa a manutenção das skills (descrita abaixo) e confere a compatibilidade.
- Roda
bun run openclipara regenerardocs/opencli.jsoncom a nova identidade. - Confere os três modos com
bun run dev -- --version,bun run dev -- about --jsonebun run dev -- mcp --list. Sem terminal interativo, usa o testetests/tui.test.tspara a TUI. - Roda
bun run validate. - Reescreve a abertura do
README.mdcom o propósito do produto e apaga o trecho sobre o template. - Passa para a termfy-clispec.
No modo de manutenção:
- Confere o Git, a versão em
package.json,.agents/skills/eskills-lock.json. Avisa antes de sobrescrever alterações locais. - Lê os scripts
skills:install,skills:updateeskills:checke confirma a origemhttps://github.com/promovaweb/termfy. - Roda
bun run skills:updatepara atualizar oubun run skills:installpara instalar e reparar. Quando os scripts alcançam outras bibliotecas, restringe a operação ao Termfy. - Roda
bun run skills:check, lê os avisos e confere os links dos agentes, as origens no lock e o diff. - Reabre os arquivos atualizados e encerra. A identidade fica como estava.
Exemplo
O bootstrap que a skill roda para o mycli e a saída que ele imprime:
bun run init -- --name mycli --title "My CLI" \ --description "Query shop orders from the terminal." \ --author "Loja Exemplo" \ --repository https://github.com/loja-exemplo/mycli \ --site https://loja-exemplo.com✓ package.json: termfy → mycli✓ .env.example✓ README.md✓ AGENTS.md✓ CHANGELOG.md: history started at 0.1.0
Done. Check with: bun run dev -- --version && bun run dev -- --helpThen run: bun run validateDepois do bootstrap, o bloco termfy do package.json fica assim:
{ "name": "mycli", "version": "0.1.0", "bin": { "mycli": "src/main.ts" }, "termfy": { "bin": "mycli", "title": "My CLI", "author": "Loja Exemplo", "site": "https://loja-exemplo.com", "repository": "https://github.com/loja-exemplo/mycli", "framework": "https://github.com/promovaweb/termfy" }}A conferência dos modos confirma o nome novo:
$ bun run dev -- --versionmycli 0.1.0$ bun run dev -- config path Directory /home/voce/.mycli settings.json /home/voce/.mycli/settings.json credentials.json /home/voce/.mycli/credentials.json master.key /home/voce/.mycli/master.keyRegras que a skill segue
- O agente roda os comandos. A skill executa o setup e a manutenção e não entrega a você uma lista de comandos para copiar. Isso evita passos esquecidos e mantém o relato fiel ao que rodou.
- O nome do executável segue
^[a-z][a-z0-9-]{1,39}$. O bootstrap recusa outro formato com exit code 2, porque o nome vira a pasta~/.mycli/, o prefixoMYCLI_HOMEeMYCLI_MASTER_KEYe o esquemamycli://das URIs MCP. - O bootstrap não cria
CLISPEC.mdnemspecs/. O starter kit não traz nenhum dos dois. A visão macro sai da entrevista datermfy-clispec. A primeira spec recebe o número 0001. - O bootstrap não altera
src/nemdocs/. Os dois leem a identidade do manifest em tempo de execução, então não precisam de reescrita. - O projeto novo começa em 0.1.0. O bootstrap troca a versão e cria um
CHANGELOG.mdpróprio. O histórico do template não pertence ao seu binário. - Manutenção preserva o produto. Ela não roda o bootstrap, não
renomeia o binário e não recria o
CLISPEC.mdnem as specs. Assim, você recebe as instruções atualizadas sem alterar o produto. - Compatibilidade conferida, não presumida. A skill só declara a
instalação compatível depois de ler os avisos do
skills:check. - Setup não publica. Commit, push, tag e GitHub Release ficam com a
termfy-release. Elas só acontecem quando você pedir. - Validação vermelha não vira produto pronto. Com
bun run validatefalhando, a skill relata que só a preparação terminou.
O bun run validate encadeia typecheck, testes, skills:check,
opencli:check, docs:check e build. Ele não lê o CLISPEC.md nem as
specs: a conferência desses arquivos com o código é manual.
O que ela entrega
No setup, a skill relata:
- o nome do binário e os caminhos de configuração (
~/.mycli/), - a origem das skills instaladas (o
skills-lock.jsonregistra origem e hash, sem versão SemVer), - os comandos conferidos e os testes executados,
- o que ficou pendente.
Arquivos que mudam no setup: package.json, .env.example, README.md,
AGENTS.md, CHANGELOG.md, .github/workflows/*.yml,
docs/opencli.json, .agents/skills/ e skills-lock.json.
Na manutenção, a skill relata as skills alteradas. Mudam só
.agents/skills/, os links dos agentes e o skills-lock.json.
Próxima skill
Depois do setup, siga para a termfy-clispec, que
entrevista você e escreve o primeiro CLISPEC.md. Se quiser ajustar
cores ou créditos antes, passe pela termfy-brand.