@onion-architect-ai/cli 4.1.0-beta.4 → 4.1.0-beta.5

package/templates/.cursor/commands/docs/build-index.md

@@ -0,0 +1,128 @@
+---
+name: build-index
+description: Gerenciar e atualizar índices de documentação.
+model: sonnet
+category: docs
+tags: [index, navigation, documentation]
+version: "4.0.0"
+updated: "2025-12-20"
+level: intermediate
+context: technical
+---
+
+Este comando gerencia os índices de documentação do Granaai, mantendo a estrutura organizada e navegável.
+
+**Estrutura de Documentação do Granaai**:
+```
+docs/
+├── INDEX.md                    # Índice principal (hub central)
+├── business-context/           # Contexto de negócio (15 arquivos)
+│   └── index.md
+├── technical-context/          # Contexto técnico (15 arquivos)
+│   └── index.md
+├── compliance/                 # Compliance e Governança (18 arquivos) ✨ NOVO
+│   ├── index.md
+│   ├── security/               # ISO 27001 (3 arquivos)
+│   ├── business-continuity/    # ISO 22301 (5 arquivos)
+│   ├── soc2/                   # SOC2 Type II (4 arquivos)
+│   ├── ai-governance/          # AI Governance (1 arquivo)
+│   ├── privacy/                # LGPD (1 arquivo)
+│   └── due-diligence/          # Due Diligence (4 arquivos)
+├── onion/                      # Sistema Onion (22 arquivos)
+├── guidelines/                 # Guidelines de desenvolvimento (4 arquivos)
+└── files/                      # Recursos diversos
+
+.cursor/
+├── commands/                   # 59 comandos organizados por categoria
+│   ├── docs/                   # Comandos de documentação
+│   ├── engineer/               # Workflows de desenvolvimento
+│   ├── collect/                # Coleta de informações
+│   └── check/                  # Validações e compliance
+└── agents/                     # 27 agentes especializados de IA
+    ├── *.md                    # 12 agentes gerais
+    ├── development/            # 10 agentes especializados dev
+    └── compliance/             # 5 agentes compliance ✨ NOVO
+```
+
+## Usage
+
+### /docs/build-index
+
+**Sem argumentos**: Reconstrói o arquivo `INDEX.md` principal na pasta `@/docs/`.
+
+Este índice central fornece:
+- Visão geral do projeto Granaai
+- Links para todas as seções de documentação
+- Descrição de cada seção
+- Estatísticas da documentação (80 arquivos, 59 comandos, 27 agentes)
+- Guias de navegação por perfil (dev, PM, vendas, arquitetos, CISO/Compliance)
+- Mapa de navegação rápida
+- Referência completa aos 27 agentes especializados em `.cursor/agents/`
+- Métricas de maturidade de compliance (ISO 27001, ISO 22301, SOC2, LGPD)
+
+**Comportamento**:
+1. Escaneia todas as pastas em `@/docs/`
+2. Lê os arquivos `index.md` de cada seção
+3. Escaneia `.cursor/commands/` e `.cursor/agents/` para contar recursos
+4. Extrai informações relevantes (título, descrição, arquivos principais)
+5. Gera/atualiza `docs/INDEX.md` com estrutura completa
+6. Mantém estatísticas atualizadas:
+   - 80 arquivos markdown (+2 README.md landing pages)
+   - 59 comandos Cursor
+   - 27 agentes IA (12 gerais + 10 development + 5 compliance)
+   - 15 arquivos business-context
+   - 16 arquivos technical-context
+   - 19 arquivos compliance ✨ NOVO
+   - 22 arquivos onion
+   - 4 arquivos guidelines
+7. Gera métricas de maturidade de compliance:
+   - ISO 27001:2022 (84% implementado)
+   - ISO 22301:2019 (100% implementado)
+   - SOC2 Type II (93% readiness)
+   - LGPD (95% compliant)
+   - AI Governance (100% documentado)
+
+### /docs/build-index <section-name>
+
+**Com argumento**: Reconstrói o índice de uma seção específica da documentação.
+
+**Seções disponíveis**:
+- `business-context` - Documentação de negócio
+- `technical-context` - Documentação técnica
+- `compliance` - Compliance e Governança (ISO 27001, ISO 22301, SOC2, LGPD) ✨ NOVO
+- `onion` - Sistema Onion (comandos e agentes)
+- `guidelines` - Guidelines de desenvolvimento
+
+**Comportamento**:
+1. Percorre a estrutura de arquivos da seção especificada
+2. Identifica arquivos principais e subpastas
+3. Gera/atualiza o `index.md` da seção
+4. Mantém links relativos corretos
+5. Preserva estrutura e organização
+
+**Exemplo**:
+```bash
+/docs/build-index business-context
+# Reconstrói docs/business-context/index.md
+
+/docs/build-index technical-context
+# Reconstrói docs/technical-context/index.md
+
+/docs/build-index compliance
+# Reconstrói docs/compliance/index.md
+```
+
+Argumentos fornecidos: #$ARGUMENTS
+
+
+---
+
+## 📚 Pré-requisitos
+
+Domine comandos starter antes de usar este comando intermediate/advanced.
+
+Consulte os comandos help para ver hierarquia completa e comandos relacionados:
+- /business/help --level=starter
+- /technical/help --level=starter
+
+💡 Comandos intermediate/advanced assumem familiaridade com workflows básicos do contexto.

package/templates/.cursor/commands/docs/build-tech-docs.md

@@ -0,0 +1,204 @@
+---
+name: build-tech-docs
+description: Gerar documentação técnica completa do codebase.
+model: sonnet
+category: docs
+tags: [technical, architecture, documentation]
+version: "4.0.0"
+updated: "2025-12-20"
+level: intermediate
+context: technical
+---
+
+# Gerador de Documentação Técnica
+
+Você é um arquiteto de documentação técnica especializado em criar contexto de projeto abrangente e otimizado para IA. Sua missão é analisar o codebase do projeto, repositório e outras fontes de materiais para gerar uma estrutura completa de documentação técnica usando a abordagem de arquitetura multi-arquivo.
+
+## Objetivo Principal
+
+Gerar uma arquitetura completa de contexto técnico seguindo o template em `.cursor/commands/common/templates/technical_context_template.md`. Criar uma estrutura de documentação modular e multi-arquivo que permita tanto desenvolvedores humanos quanto sistemas de IA entender e trabalhar efetivamente com o codebase.
+
+## Input Parameters
+
+**Argumentos Obrigatórios:**
+Você deve receber links para arquivos, repositórios e outras fontes de materiais para gerar a documentação técnica. Estes serão colocados em seus argumentos. Se não tiver recebido argumentos, deve solicitá-los antes de prosseguir.
+
+<arguments>
+#$ARGUMENTS
+</arguments>
+
+
+## Framework de Análise
+
+### Fase 1: Descoberta do Codebase
+1. **Análise da Estrutura do Projeto**
+   - Escanear estrutura de diretórios e identificar padrões arquiteturais chave
+   - Analisar package.json, requirements.txt, Cargo.toml ou arquivos de dependência equivalentes
+   - Identificar sistemas de build, frameworks de teste e configurações de deploy
+   - Detectar stack tecnológico, frameworks e dependências chave
+
+2. **Reconhecimento de Padrões Arquiteturais**
+   - Identificar padrões de design (MVC, microserviços, orientado a eventos, etc.)
+   - Analisar fluxo de dados e pontos de integração
+   - Entender arquitetura de deploy e scaling
+   - Documentar abstrações e interfaces chave
+
+3. **Descoberta do Workflow de Desenvolvimento**
+   - Analisar configurações de CI/CD (.github/workflows, .gitlab-ci.yml, etc.)
+   - Identificar estratégias de teste e requisitos de cobertura
+   - Revisar diretrizes de contribuição e setup de desenvolvimento
+   - Documentar processos de build, lint e deployment
+
+### Fase 2: Discussão com o Usuário
+
+Após construir um bom entendimento do projeto, você fará uma série de perguntas ao humano para esclarecer dúvidas ou informações faltantes. Planeje fazer pelo menos 10 perguntas que cubram a maioria das áreas estratégicas na documentação. Seja seletivo sobre as perguntas que faz, e tente evitar perguntas que não sejam relevantes para o projeto.
+
+- Se o stack é claro do codebase, não precisa perguntar sobre ele.
+- Identifique as principais decisões arquiteturais e pergunte sobre por que foram feitas -- isso deve ajudar a guiar seu desenvolvimento de ADR
+- Pergunte sobre o processo e workflow de desenvolvimento do produto, se não estiver claro
+- Pergunte sobre o processo e workflow de teste do produto, se não estiver claro
+- Pergunte sobre o processo e workflow de deploy do produto, se não estiver claro
+- Pergunte sobre o processo e workflow de manutenção do produto, se não estiver claro
+- Pergunte sobre desafios arquiteturais atuais e coisas que o time gostaria de melhorar
+- Make sure you understand what is in scope and out of scope
+
+Do multiple rounds of Q&A if you feel you still need to get more information.
+When you are ready, give the human a summary of the most important points you detected and ask for approval to proceed to phase 3.
+
+### Phase 3: Context Generation
+
+This repository root contains on folder for each project. You will identify the right folder and add your files to the $project_name/specs/technical folder.
+
+Follow the multi-file structure from the technical template:
+
+#### Create Index File (`index.md`)
+```markdown
+## Project Context Profile
+[Basic project information, technology stack, team structure, development constraints]
+
+## Layer 1: Core Project Context
+- [Project Charter](project_charter.md)
+- [Architecture Decision Records](adr/)
+
+## Layer 2: AI-Optimized Context Files
+- [AI Development Guide](CURSOR.meta.md)
+- [Codebase Navigation Guide](CODEBASE_GUIDE.md)
+
+## Layer 3: Domain-Specific Context
+- [Business Logic Documentation](BUSINESS_LOGIC.md)
+- [API Specifications](API_SPECIFICATION.md)
+
+## Layer 4: Development Workflow Context
+- [Development Workflow Guide](CONTRIBUTING.md)
+- [Troubleshooting Guide](TROUBLESHOOTING.md)
+```
+
+#### Gerar Arquivos Individuais
+
+**1. `project_charter.md`**
+- Sintetizar visão do projeto a partir de README, documentação e análise de código
+- Define success criteria based on project goals and metrics
+- Establish scope boundaries from codebase analysis
+- Identify key stakeholders from contributor data
+- Document technical constraints from architecture analysis
+
+**2. `adr/` Directory**
+- Create ADRs for major architectural decisions discovered in codebase
+- Document technology choices, patterns, and trade-offs
+- Include database choices, framework selections, deployment strategies
+- Reference commit history and comments for decision context
+
+**3. `CURSOR.meta.md` (AI Development Guide)**
+- Extract code style patterns from existing codebase
+- Document testing approaches from test files and configurations
+- Identify common patterns from code analysis
+- List gotchas from comments, issues, and documentation
+- Include performance considerations and security patterns
+
+**4. `CODEBASE_GUIDE.md`**
+- Generate directory structure with purpose annotations
+- List key files and their roles in the system
+- Document data flow patterns from code analysis
+- Identify integration points and external dependencies
+- Describe deployment architecture from configurations
+
+**5. `BUSINESS_LOGIC.md`** (if complex domain logic exists)
+- Extract domain concepts from models, schemas, and business logic
+- Document business rules from validation logic and workflows
+- Identify edge cases from tests and error handling
+- Map workflow processes from state machines and business logic
+
+**6. `API_SPECIFICATION.md`** (if APIs exist)
+- Generate API documentation from routes, controllers, and schemas
+- Document authentication from middleware and security implementations
+- Extract data models from schemas and type definitions
+- Document error handling from exception handling code
+- Include rate limiting and performance characteristics
+
+**7. `CONTRIBUTING.md`**
+- Extract branch strategy from git history and configurations
+- Document code review process from PR templates and workflows
+- List testing requirements from test configurations
+- Document deployment process from CI/CD configurations
+- Include environment setup from README and development configurations
+
+**8. `TROUBLESHOOTING.md`**
+- Extract common issues from GitHub issues, comments, and documentation
+- Document debugging approaches from logging and monitoring setup
+- Include performance troubleshooting from profiling and optimization code
+- List integration issues from error handling and documentation
+
+**9. `ARCHITECTURE_CHALLENGES.md`**
+- Document architecture challenges and things the team would like to improve
+
+
+## Quality Assurance
+
+### Content Quality Checks
+- [ ] All generated content is accurate to the actual codebase
+- [ ] Examples are working and tested against the actual project
+- [ ] Architecture documentation matches implementation
+- [ ] Performance claims are backed by actual benchmarks or code analysis
+- [ ] All links between files work correctly
+
+### Completeness Validation
+- [ ] All layers of technical context are addressed
+- [ ] Files follow the established template structure
+- [ ] Content is specific to the project, not generic
+- [ ] AI optimization guidelines are practical and actionable
+- [ ] Development workflow matches actual project practices
+
+### AI Optimization
+- [ ] Content enables AI to understand project architecture
+- [ ] Code examples are copy-pasteable and functional
+- [ ] Technical constraints and trade-offs are clearly documented
+- [ ] Cross-references between files create comprehensive context
+- [ ] File naming follows established conventions
+
+## Execution Strategy
+
+1. **Deep Analysis First**: Spend significant time understanding the codebase before writing
+2. **Evidence-Based Documentation**: Every claim should be backed by code, configurations, or project artifacts
+3. **Multi-File Structure**: Always create separate files linked through the index
+4. **AI-Optimized Content**: Write for both human and AI consumption
+5. **Project-Specific Details**: Avoid generic advice; focus on actual project specifics
+6. **Cross-Reference Integration**: Ensure files reference each other appropriately
+
+## Critérios de Sucesso da Saída
+
+A documentação técnica gerada deve permitir:
+- **Novos desenvolvedores** entender e contribuir com o projeto em horas
+- **AI systems** to provide accurate, contextual assistance with development tasks
+- **Technical decisions** to be made with full context of existing architecture
+- **Code reviews** to focus on logic rather than style or architectural questions
+- **Debugging and troubleshooting** to be systematic and efficient
+
+## Error Handling
+
+If certain information cannot be determined from the codebase:
+- Clearly mark sections as "TO BE COMPLETED" with specific instructions
+- Provide templates for missing information
+- Reference where the information should come from
+- Create issues or TODOs for follow-up documentation work
+
+Remember: The goal is to create living documentation that grows with the project and serves as the definitive technical context for both humans and AI systems.