tinycorn-studio/agent-skills

Convenções do Studio (Padrão TinyCorn Studio)

Aplicável a todos os repositórios/ferramentas do estúdio, desde a inicialização até a manutenção.

Idioma

• Comunicação com o usuário: vietnamita.
• Código, identificadores, mensagens de commit, nomes de branch: inglês.
• README, CHANGELOG, notas de lançamento: vietnamita.

Estrutura mínima do repositório

<repo>/
├── README.md          # obrigatório
├── CHANGELOG.md       # obrigatório (Keep a Changelog)
├── LICENSE            # normalmente MIT
└── .gitignore         # obrigatório

README.md deve conter as seções

1. Introdução (1–2 frases, o que a ferramenta faz, para quem)
2. Requisitos do sistema
3. Build / execução
4. Principais funcionalidades (agrupadas)
5. Atalhos de teclado (se houver interface)
6. Arquitetura / estrutura de diretórios
7. Configuração (UserDefaults, env, arquivo de configuração…)
8. Limitações conhecidas
9. Histórico de versões (resumo, detalhes no CHANGELOG)
10. Download (link para a última versão no GitHub Releases — não armazenar arquivos de instalação no repositório)

Git

• .gitignore mínimo: .build/, dist/, node_modules/, .DS_Store, diretórios de recursos gerados automaticamente durante o build.
• Não commitar: arquivos de instalação (DMG/ZIP), saída de build, segredos/tokens.
• Mensagem de commit: 1 linha, modo imperativo, em inglês, descrevendo completamente a funcionalidade/correção. Exemplo: Add folder view to Changes tab.
• Commitar por funcionalidade completa; commitar apenas quando o usuário solicitar ou após a funcionalidade ser confirmada.
• Branch: main sempre em estado publicável; funcionalidades desenvolvidas em branches separados, merge com --ff-only quando concluído.
• Versão: SemVer, declarada em um único local (ex.: VERSION em make-app.sh), não espalhada em vários arquivos.

Documentação

• README + CHANGELOG atualizados ao mesmo tempo que a funcionalidade (não deixar para depois).
• Toda versão deve ter: tag anotada vX.Y.Z + GitHub Release com notas de lançamento em vietnamita (veja skill release-flow).
• Anotações de decisões de design complexas diretamente no código ou na seção "Arquitetura" do README.

Qualidade

• Antes de informar conclusão: construir/testar novamente, verificar com dados reais ou sandbox.
• Interface: pré-visualizar antes de aplicar (veja skill ui-preview-first).
• Não testar gravação/commit em dados reais do usuário — usar cópia em sandbox.
• Após testes, limpar sandbox/temp, não deixar resíduos no repositório.

Checklist para novo repositório

• git init + .gitignore padrão
• README conforme estrutura acima
• CHANGELOG com seção [0.1.0]
• LICENSE (MIT)
• Script de build (make-app.sh ou equivalente) + DMG/instalador
• Remote no GitHub + push main
• Primeira versão com arquivo de instalação
• Skill release-flow já conhecido para uso nas próximas vezes