kikita-labs/kikita-create-angular-app

O que kikita-create-angular-app faz?

Inicializa um novo projeto Angular e gera sua árvore de documentação AGENTS.md / .agents/ para que qualquer agente de IA (Claude Code, Codex, etc.) que trabalhe no projeto tenha uma fonte única de verdade completa e auto-mantida.

0. Detecção de modo (sempre faça isso primeiro)

Três estados possíveis para o diretório alvo — verifique nesta ordem:

1. .agents/.kikita-scaffold.json presente → este projeto já foi escaffoldado ou adotado por esta habilidade. Siga update.md — não reexecute o questionário, não reescaffolde, não reexecute adopt.md. update.md cuida de puxar o template mais recente, fazer diff desde o commit registrado e mesclar as alterações nos arquivos (possivelmente personalizados) da pasta .agents/.
2. Diretório vazio ou quase vazio (sem package.json, sem angular.json, apenas talvez um .git//README que o usuário acabou de criar) → inicialização limpa. Continue com a seção 1 abaixo, depois plan.md.
3. Projeto existente, sem registro de escaffold (package.json/angular.json presente, sem .agents/.kikita-scaffold.json) → este é um projeto Angular de outra pessoa (ou anterior a esta habilidade). Não execute plan.md — ele assume um diretório vazio e tentará executar ng new sobre um projeto real. Siga adopt.md: ele gera a árvore .agents/ com base no que realmente está lá, inferindo as respostas do questionário a partir da configuração existente em vez de escaffoldar novas ferramentas, e pergunta antes de alterar qualquer coisa que já exista.

0.5 Pré-condições (apenas para inicialização limpa)

• Confirme que o diretório de trabalho está vazio ou o usuário explicitamente deseja inicializar aqui.
• Se o diretório não estiver vazio ao verificar, pare e redirecione para o caso 3 acima (adopt.md) em vez de forçar o caminho de inicialização — não peça ao usuário apenas "confirme que está tudo bem inicializar aqui" quando o que é realmente necessário é o fluxo de adoção.

1. Questionário (sempre pergunte antes de tocar no sistema de arquivos)

Siga plan.md passo a passo a partir daqui. Não pule o questionário. Não pule a instalação MCP. Quando terminar, execute checklist.md antes de informar ao usuário que está concluído.

Pergunte ao usuário, em uma única rodada, tudo de uma vez:

1. CSS: CSS nativo (custom properties), SCSS ou Tailwind CSS?
   • Tailwind é um branch estruturalmente diferente, não uma variação dos outros dois: sem esquema @layer {{PREFIX}}.*, sem tokens :root escritos à mão, sem mixins SCSS — veja os blocos de escaffold CSS=Tailwind em templates/.agents/code-style/css-architecture.md, component-structure.md e templates/.agents/architecture/folder-structure.md.
2. Biblioteca de UI: @kikita-labs/ui, Taiga UI, PrimeNG ou nenhuma (construir um conjunto de UI local baseado em tokens)?
   • Se uma biblioteca for escolhida: verifique se ela possui um schematic ng add e/ou um servidor MCP. Prefira o schematic. Se tiver um MCP, instale-o (veja plan.md passo 4).
3. Testes: nenhum, apenas unitários, apenas e2e ou ambos? Qual executor (Vitest/Jasmine+Karma é depreciado no novo Angular — prefira Vitest; Playwright para e2e)?
4. SSR: esta aplicação é renderizada no servidor (Angular SSR / hidratação) ou somente no cliente?
   • Define se .agents/architecture/platform-adapter.md é gerado.
5. i18n: este projeto precisa de múltiplos locales (@angular/localize ou uma biblioteca de i18n em tempo de execução)? Se sim, qual abordagem?
   • Define se .agents/i18n.md é gerado.
6. JSDoc na API pública: aplicar JSDoc obrigatório em todo símbolo exportado, ou pular?
   • Define se .agents/agent-surface.md é gerado (padrão recomendado: sim).
7. Prefixo do projeto: prefixo curto em kebab-case para seletores de componentes/diretivas.
8. Política de Git: o agente pode commitar e fazer push sem perguntar a cada vez, ou todo commit/push deve ser confirmado?
9. Gerenciador de pacotes: npm, pnpm ou yarn? Recomendação padrão: pnpm (mais rápido, eficiente em disco via armazenamento compartilhado endereçável por conteúdo, resolução de dependências mais restrita). Só substitua o padrão se o usuário pedir outra coisa.
10. Remote Git: o usuário já tem uma URL de repositório para fazer push? Se sim, registre-a — git remote add origin <url> executa logo após git init (veja plan.md passo 9). Se nenhuma URL for fornecida, pule; o usuário configura o remote mais tarde.

Registre cada resposta — elas orientam tanto o escaffolding quanto quais arquivos de documentação são gerados. Nunca assuma um padrão silenciosamente; se o usuário pular uma pergunta, pergunte novamente apenas aquela. Esta habilidade tem como alvo um único projeto Angular, não um monorepo — se o usuário quiser um monorepo/workspace Nx, diga que esta habilidade não cobre isso e pare, em vez de improvisar.

2. Gerar

Siga plan.md. Copie arquivos de templates/ para o projeto alvo, incluindo os arquivos de configuração (.gitignore, .editorconfig, .prettierrc, .prettierignore, .nvmrc, .vscode/extensions.json).

Duas coisas diferentes acontecem com as respostas do questionário, não as confunda:

• Placeholders de texto — localize e substitua cada {{TOKEN}} pelo valor real, sem deixar nenhum para trás: {{PREFIX}}, {{PROJECT_NAME}}, {{CSS}}, {{CSS_EXT}}, {{UI_LIB}}, {{UI_LIB_MCP_NAME}}, {{UI_LIB_MCP_PURPOSE}}, {{TESTS}}, {{GIT_POLICY}}, {{PACKAGE_MANAGER}}, {{NODE_VERSION}}, {{I18N_APPROACH}}, {{DATE}}.
• Portões de inclusão — respostas sobre SSR, i18n, JSDoc obrigatório, biblioteca de UI e engine CSS não preenchem um placeholder; elas decidem se um arquivo inteiro (ou um bloco marcado com <!-- SCAFFOLD -->) é copiado. Uma resposta "não" (ou, para CSS, as duas engines não escolhidas) significa que o arquivo/bloco é deletado, não preenchido com uma string vazia. Arquivos condicionais ainda devem ser linkados a partir de AGENTS.md / do README relevante quando mantidos, e seus links removidos quando ignorados.

3. Verificar

Execute checklist.md por completo antes de relatar sucesso.

Notas sobre a estrutura da documentação (leia uma vez, depois siga os templates/ literalmente)

• CLAUDE.md é sempre um stub de uma linha apontando para AGENTS.md.
• AGENTS.md é o ponto de entrada obrigatório: uma lista curta de "Leitura Obrigatória" mais regras não negociáveis, na raiz do projeto.
• .agents/README.md é um índice plano de tudo sob .agents/ — o equivalente a index.ts para a árvore de documentação. Todo documento raiz e todo README de subpasta são linkados a partir dele. Mantenha-o sincronizado sempre que um arquivo condicional (i18n, agent-surface, platform-adapter) for adicionado ou ignorado.
• Tópicos que são genuinamente um documento curto permanecem planos em .agents/*.md (workflow, git-policy, documentation, mcp, testing-and-quality, agent-surface, refactoring, progress, i18n, accessibility).
• Tópicos que se desdobram em vários documentos pequenos ganham uma subpasta com seu próprio README.md hub: .agents/code-style/, .agents/architecture/, .agents/shared/, .agents/core/, .agents/decisions/. Este é um desvio deliberado do kikita-ui/-docs (que permaneceu totalmente plano) porque a especificação desta habilidade exige documentos de reúso por componente e por preocupação que continuarão crescendo após o escaffold.
• .agents/shared/README.md registra tudo sob src/app/shared/, dividido por forma de dependência: shared/ui/ (componente/diretiva/pipe, decorado com Angular) e shared/utilities/ (funções puras, zero imports Angular — garantido por uma regra ESLint de import restrito). Mixins SCSS, se SCSS foi escolhido, ficam em styles/mixins/, não sob shared/ de forma alguma. .agents/core/README.md registra singletons da aplicação (serviços/guards/interceptors) sob src/app/core/. Nenhum deles é nomeado "components" — ambos cobrem mais do que componentes, daí a nomenclatura.
• .agents/decisions/README.md explica quando um ADR curto é necessário (direção de camadas, propriedade de estado, estratégia de roteamento, esquema de alias público) — sempre gerado, começa sem arquivos ADR. AGENTS.md o linka sob um grupo condicional "para mudanças estruturais", não na lista de leitura obrigatória — mesmo padrão dos grupos shared//core/ "para trabalho com componentes".
• Todo o conteúdo dos arquivos rastreados — incluindo JSDoc — é apenas em inglês. Sem cirílico, sem mojibake.
• Toda documentação em .agents/ deve ser lida como angular-code-style.md no kikita-ui: imperativa, curta, com exemplos, terminando em uma lista de verificação de revisão.