Astrofy

O Astrofy reúne skills para trabalhar em sites Astro por conversa com Codex ou Claude. Instale o pacote, disponibilize as skills no projeto e peça o trabalho em linguagem natural. O agente escolhe as especialistas, faz as perguntas necessárias e apresenta o plano antes de implementar.

Comece por uma conversa

Instale o pacote e as skills para o agente que usa no projeto:

npm install --global @promovaweb/[email protected]
cd /caminho/do/site
astrofy skills install --agent codex

Para Claude, troque codex por claude. Se quiser conferir os arquivos antes da instalação, acrescente --dry-run ao último comando.

Depois, peça o trabalho ao agente. Por exemplo:

Quero criar uma página para meu produto. Use o Astrofy para entender este projeto, conversar comigo sobre o conteúdo e apresentar um plano antes de implementar.

Para uma adoção ampla ou uma revisão do projeto, peça astrofy-setup. Para uma página, descreva o resultado esperado. O agente confere o que precisa preparar e conduz a entrevista com astrofy-page-planner. Você não precisa preencher a entrevista por meio de comandos do CLI.

O CLI continua disponível para instalar skills, acompanhar estado, executar checks ou retomar uma página manualmente. Consulte a referência do CLI quando precisar desses comandos.

As skills operam sobre projetos Astro existentes. O pacote não inclui um template de site.

Astrofy Design

A área Astrofy Design acrescenta composição visual, estudo de referências, auditoria e redesign. A skill inclui as referências e as paletas localmente, com integração aos tokens e componentes do projeto Astro. O guia prático e a referência de uso também integram o PDF, o EPUB e a documentação do site.

No checkout desta edição, instale a skill no projeto desejado:

node dist/cli/index.js skills install --agent codex --skill astrofy-design --root /caminho/do/site --dry-run
node dist/cli/index.js skills install --agent codex --skill astrofy-design --root /caminho/do/site

Depois peça ao agente astrofy-design build, astrofy-design study, astrofy-design audit ou astrofy-design redesign. Esses nomes são modos da skill e não comandos adicionais do CLI. Os avisos de licença ficam junto dos materiais incorporados.

Desenvolvimento do pacote

Use Node.js 22.12 ou posterior e instale as dependências registradas no lockfile. No diretório deste repositório, execute:

npm ci
npm run build
node dist/cli/index.js --help

O pacote está disponível publicamente no npm. A versão 0.8.0 inclui planejamento conversacional e técnico para páginas de vendas, produto, serviço, Home, Sobre, Contato e Preços, além de tarefas pontuais em .sitespec/. O painel opcional abre com astrofy tui --root /caminho/do/site depois que o projeto foi inicializado com astrofy init.

O pacote conserva UNLICENSED, sem concessão de licença aberta. Para uma instalação a partir do checkout autorizado, npm pack gera o arquivo .tgz. O tarball mantém somente a edição atual do ebook. Edições anteriores continuam disponíveis nas respectivas GitHub Releases.

Adotar em um site existente

A entrada setup escreve apenas contratos ausentes e cria o estado retomável da coordenação. O dry-run permite conferir os caminhos sem criar a pasta .astrofy.

node dist/cli/index.js inspect --root /caminho/site
node dist/cli/index.js setup --root /caminho/site --dry-run
node dist/cli/index.js setup --root /caminho/site
node dist/cli/index.js check --root /caminho/site --json

O check grava relatórios e a checklist. Ele não instala dependências nem executa scripts do site com a configuração padrão. Uma revisão visual ou editorial continua pendente até receber uma avaliação identificada.

Planejar uma página

Peça a página em linguagem natural, como "quero criar uma página para meu produto". astrofy-page-planner inspeciona o site, escolhe a entrevistadora adequada e coleta finalidade, público, áreas, textos, mídia e ações. A especificação aprovada fica em .astrofy/pages/<slug>/. O agente conduz essa etapa na conversa. Os comandos abaixo servem para registrar cada resposta pelo terminal.

Depois, astrofy-implementation-planner relaciona a especificação com rotas, componentes, checklist e scripts atuais, e registra uma sitespec por tarefa (rota, conteúdo, validação) em .sitespec/<id>-<slug>-<tarefa>/SITEPEC.md, com page e task apontando de volta para a página. Reexecutar o plano reconcilia essas tarefas sem perder progresso. Nenhuma das duas orquestradoras altera ou publica o site sem uma solicitação posterior.

O CLI conserva a mesma sequência em arquivos retomáveis:

astrofy page create --slug produto --type product
astrofy page status --slug produto
astrofy page answer --slug produto --field title --value "Produto"
astrofy plan --slug produto
astrofy apply --slug produto

Cada resposta atualiza interview.json. Quando não há lacunas obrigatórias, o CLI gera o contrato com conteúdo, SEO, integrações, acessibilidade e testes. apply registra a passagem das tarefas (sitespecs ligadas à página) por in_progress, completed, failed e skipped; a skill indicada em cada uma executa a alteração no site. astrofy sitespec progress e a aba Specs da TUI mostram essas tarefas junto das tarefas pontuais, no mesmo resumo.

Registrar uma tarefa pontual do site

Nem toda mudança é uma página nova. Um ajuste de componente, uma correção, uma pendência de SEO — descreva o pedido ao agente e astrofy-sitespec-create cria a tarefa em .sitespec/<id>-<slug>/SITEPEC.md. A skill mapeia as skills relacionadas ao pedido antes de perguntar; a maioria dos pedidos não gera pergunta nenhuma, e no máximo três quando o pedido é ambíguo. Depois, astrofy-sitespec-implement executa os itens da checklist e atualiza o arquivo até done, blocked ou archived.

astrofy sitespec list --json

O comando é só leitura: mostra o progresso, o próximo id livre e as dependências (blockedBy) entre tarefas. Pelo terminal interativo, astrofy tui abre a aba Specs (Ctrl+S) para navegar e acompanhar sem gravar nada. O contrato completo do arquivo está em docs/sitespec.md.

Documentação

• Guia do usuário

• Ebook em PDF e EPUB

• Referência das skills

• Matriz operacional das skills

• CLI

• Configuração

• Contrato do SITEPEC.md

• Uso do CLI: comandos e opções.

• Contratos: configuração e estado.

• Tokens: geração e importação Brandfy.

• TUI: navegação e revisão manual.

• Arquitetura: pacotes e integridade de escrita.

• Compatibilidade: faixas e validação.

• Skills: guia das 54 skills, instalação, fluxos e exemplos.

• Verificação das skills: cenários executados e limites dos testes.

• Tarefas pontuais: contrato do SITEPEC.md.

• Gestão do projeto: backlog, timesheets e redistribuição de datas.

Desenvolvimento

npm test compila o TypeScript e executa a suíte sem navegador. npm run test:browser executa apenas os testes que abrem Chromium e npm run test:all reúne os dois grupos. npm run check faz somente a checagem de tipos. O código fica em packages/ e o JavaScript de distribuição é gerado em dist/.

O pacote não transporta o binário do Chromium. Instale-o sob demanda com astrofy browser install, confira com astrofy browser status e remova com astrofy browser remove. astrofy check executa as verificações estáticas; astrofy check --browser inclui temas, persistência, overflow, erros JavaScript e responsividade contra o preview configurado.

Os builds adicionais com Astro 5, 6 e 7 ficam nas fixtures de compatibilidade, com seus próprios lockfiles e verificação de navegador. Esse fluxo é separado de npm test, pois instala versões adicionais do site.

Depois de instalar as dependências das fixtures, os scripts test:compatibility, test:skill-procedures e test:skill-domains conferem respectivamente o site mínimo, os procedimentos comuns e os domínios de Astro 7 usados pelas skills. O job compatibility do CI instala os três lockfiles, gera os builds e executa esses runners no Linux com Node 26 e Chromium. O job browser mantém um cache próprio; a matriz de Node e sistemas operacionais não baixa navegador.