📜 Nirvana README Architect (NRA)

Squad AIOS que gera o README.md perfeito para qualquer projeto — combina análise profunda de codebase, seleção inteligente de template, todas as features do GitHub Flavored Markdown, validação com checklist de 25+ pontos e polimento final.

📑 Índice

• Visão Geral
• Agentes
• Pipeline
• Primeiros Passos
• Comandos
• Arquitetura
• Features GitHub Suportadas
• Checklist de Qualidade
• Troubleshooting
• Contribuindo
• Licença

✨ Visão Geral

O Nirvana README Architect é um squad de 5 agentes especializados que trabalham em pipeline para transformar qualquer codebase em um README de nível profissional.

Diferente de geradores simples que produzem templates genéricos, o NRA:

• Analisa o codebase real (tech stack, scripts, env vars, estrutura de diretórios)
• Seleciona o template ideal por tipo de projeto (Library, CLI, Web App, API, Monorepo, Mobile, Squad)
• Gera conteúdo usando todas as features do GitHub Flavored Markdown
• Valida com checklist de 25+ pontos e scoring automático
• Polisa com badges, TOC, collapsed sections e espaçamento perfeito

🤖 Agentes

🔄 Pipeline

⚡ Primeiros Passos

1. Clone o repositório

git clone https://github.com/gutomec/nirvana-readme-architect.git

2. Instale como squad AIOS

Copie o diretório para

squads/

squads install gutomec/nirvana-readme-architect

3. Use o squad

# Ative o orchestrador
@nra-orchestrator

# Gere o README completo
*readme {caminho-do-projeto}

# Ou modo rápido (6 seções essenciais)
*readme-quick

Checklist de Setup

• Clone ou instalação do squad concluída
• Projeto AIOS configurado com squad.yaml
• Claude Code com acesso ao codebase alvo

⌨️ Comandos

🏗️ Arquitetura

nirvana-readme-architect/
├── agents/
│   ├── nra-orchestrator.md          # Quill — FlowMaster
│   ├── nra-codebase-analyzer.md     # Prism — Seeker
│   ├── nra-content-architect.md     # Serif — Architect
│   ├── nra-quality-validator.md     # Lens — Guardian
│   └── nra-polisher.md              # Gloss — Alchemist
├── tasks/
│   ├── nra-orchestrator-parse-request.md
│   ├── nra-codebase-analyzer-scan-project.md
│   ├── nra-content-architect-select-template.md
│   ├── nra-content-architect-generate-sections.md
│   ├── nra-quality-validator-validate-readme.md
│   ├── nra-polisher-enhance-readme.md
│   └── nra-orchestrator-deliver.md
├── workflows/
│   └── readme-generation-pipeline.yaml
├── checklists/
│   └── readme-quality.md            # 25+ pontos de validação
├── templates/
│   └── nirvana-readme.md            # Template master com GFM features
├── config/
│   ├── coding-standards.md
│   ├── tech-stack.md
│   └── source-tree.md
├── squad.yaml                       # Manifesto do squad
└── README.md                        # Este arquivo

🌟 Features GitHub Suportadas

O NRA gera READMEs que utilizam todas as features do GitHub Flavored Markdown:

+ added

📋 Checklist de Qualidade

O nra-quality-validator (Lens) aplica um checklist de 25+ pontos dividido em 4 categorias:

Score = (blocking × 60%) + (advisory × 40%) + bonus

🆘 Troubleshooting

🤝 Contribuindo

Contribuições são bem-vindas! Siga os passos:

1. Fork o projeto
2. Crie sua branch (

   git checkout -b feature/minha-feature

   )
3. Commit suas mudanças (git commit -m 'feat: descrição')
4. Push para a branch (

   git push origin feature/minha-feature

   )
5. Abra um Pull Request

📃 Licença

Este projeto está licenciado sob a licença MIT — veja o arquivo LICENSE para detalhes.