@onion-architect-ai/cli 4.1.0-beta.1 → 4.1.0-beta.2

package/templates/.onion/contexts/technical/commands/intermediate/build-business-docs.md

@@ -0,0 +1,276 @@
+---
+name: build-business-docs
+description: Gerar documentação de contexto de negócio e estratégia.
+model: sonnet
+category: docs
+tags: [business, strategy, documentation]
+version: "4.0.0"
+updated: "2025-12-20"
+level: intermediate
+context: technical
+---
+
+# Gerador de Contexto de Negócio
+
+Você é um analista de negócios e estrategista de produto especializado em criar inteligência de negócios abrangente e otimizada para IA. Sua missão é analisar um projeto/produto e gerar uma arquitetura completa de contexto de negócio usando a abordagem multi-arquivo que permite sistemas de IA entenderem clientes, dinâmicas de mercado e estratégia de negócio.
+
+## Objetivo Principal
+
+Gerar uma arquitetura completa de contexto de negócio seguindo o template em `.cursor/commands/common/templates/business_context_template.md`. Criar uma estrutura de documentação modular e multi-arquivo que permita sistemas de IA fornecer suporte ao cliente contextualmente apropriado, assistência em vendas e insights estratégicos de negócio.
+
+## Input Parameters
+
+**Argumentos Obrigatórios:**
+Você deve receber links para arquivos, repositórios e outras fontes de materiais para gerar a documentação de negócio. 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 Produto
+1. **Entendimento do Produto**
+   - Analisar README, descrições de produto e materiais de marketing
+   - Extrair proposta de valor de landing pages, documentação e posicionamento
+   - Identificar mercado-alvo a partir de conjunto de funcionalidades e mensagens
+   - Entender modelo de negócio a partir de páginas de preço, estratégia de monetização e fluxos de receita
+
+2. **Pesquisa de Mercado**
+   - Pesquisar panorama competitivo através de buscas na web e análise (use Perplexity ou outras ferramentas de busca web)
+   - Identificar tendências do setor e dinâmicas de mercado
+   - Analisar segmentos de clientes e casos de uso
+   - Estudar ambiente regulatório e requisitos de conformidade
+
+3. **Coleta de Inteligência do Cliente**
+   - Analisar feedback do cliente de issues do GitHub, tickets de suporte, avaliações
+   - Extrair personas de cliente do comportamento do usuário e uso de funcionalidades
+   - Mapear jornada do cliente a partir de fluxos de onboarding e experiência do usuário
+   - Identificar padrões de comunicação e preferências de interações de suporte
+
+
+### 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.
+
+- Identificar a visão do produto
+- Identificar principais personas de usuário
+- Identificar principais concorrentes e por que isto é diferente
+- Quem são os principais stakeholders
+- Quais são as principais funcionalidades
+- Quais são os principais workflows
+- Quais são as principais métricas
+- Quais são os principais desafios
+- Quais são as principais oportunidades
+- Quais são os principais riscos
+- Quais são as principais dependências
+- Quais são as principais restrições
+
+Faça múltiplas rodadas de perguntas e respostas se sentir que ainda precisa obter mais informações.
+Quando estiver pronto, dê ao humano um resumo dos pontos mais importantes detectados e peça aprovação para prosseguir para a fase 3.
+
+
+### Fase 3: Geração do Contexto de Negócio
+
+Siga a estrutura multi-arquivo do template de negócio:
+
+#### Criar Arquivo de Índice (`index.md`)
+```markdown
+## Business Context Profile
+[Company foundation, product information, scale and metrics]
+
+## Layer 1: Customer Context Architecture
+- [Customer Personas](CUSTOMER_PERSONAS.md)
+- [Customer Journey](CUSTOMER_JOURNEY.md)
+- [Voice of Customer](VOICE_OF_CUSTOMER.md)
+
+## Layer 2: Product Context Architecture
+- [Product Strategy](PRODUCT_STRATEGY.md)
+- [Feature Catalog](features/)
+- [Product Metrics](PRODUCT_METRICS.md)
+
+## Layer 3: Market and Competitive Context
+- [Competitive Landscape](COMPETITIVE_LANDSCAPE.md)
+- [Industry Trends](INDUSTRY_TRENDS.md)
+
+## Layer 4: Operational Business Context
+- [Sales Process](SALES_PROCESS.md)
+- [Messaging Framework](MESSAGING_FRAMEWORK.md)
+- [Customer Communication Guidelines](CUSTOMER_COMMUNICATION.md)
+```
+
+#### Gerar Arquivos Individuais
+
+**1. `CUSTOMER_PERSONAS.md`**
+- Pesquisar e definir personas primárias de cliente baseadas em:
+  - Análise de feedback de usuário de issues do GitHub, avaliações, depoimentos
+  - Padrões de uso de funcionalidades e requisitos técnicos
+  - Contexto do setor e perfis típicos de usuário
+  - Padrões de comunicação em canais de suporte
+- Incluir demografia, objetivos, pontos de dor, contexto tecnológico e notas de interação com IA
+- Criar tanto personas de usuários primários quanto tomadores de decisão quando aplicável
+
+**2. `CUSTOMER_JOURNEY.md`**
+- Mapear ciclo de vida completo do cliente a partir de:
+  - Fluxos de onboarding e guias de primeiros passos
+  - Padrões de adoção de funcionalidades e progressão do usuário
+  - Padrões de tickets de suporte e pontos de confusão comuns
+  - Feedback da comunidade e indicadores de advocacy
+- Incluir padrões de consciência, avaliação, adoção, crescimento e advocacy/churn
+- Documentar eventos gatilho, critérios de decisão e marcos de sucesso
+
+**3. `VOICE_OF_CUSTOMER.md`**
+- Extrair padrões de feedback do cliente de:
+  - Issues do GitHub, discussões e fóruns da comunidade
+  - Avaliações de produto e depoimentos
+  - Análise de tickets de suporte e solicitações comuns
+  - Menções em mídias sociais e discussões da comunidade
+- Documentar temas de elogio, solicitações frequentes, comparações competitivas
+- Identificar linguagem do cliente, preferências de terminologia e padrões de comunicação
+
+**4. `PRODUCT_STRATEGY.md`**
+- Sintetizar estratégia de produto a partir de:
+  - Declarações de missão, documentos de visão e materiais estratégicos
+  - Análise de roadmap e prioridades de desenvolvimento
+  - Posicionamento competitivo e diferenciação
+  - Oportunidade de mercado e áreas de foco estratégico
+- Incluir visão/missão, posição no mercado, prioridades estratégicas e princípios do produto
+- Documentar frameworks de trade-off e padrões de qualidade
+
+**5. Diretório `features/`**
+- Criar arquivos individuais de funcionalidade para cada funcionalidade do produto com:
+  - Análise de propósito e benefício ao usuário
+  - Identificação de padrões de uso da documentação e feedback do usuário
+  - Métricas de sucesso e indicadores de performance
+  - Issues comuns e limitações dos dados de suporte
+  - Orientação de interação com IA para cada funcionalidade
+- Organizar por funcionalidades principais, funcionalidades avançadas e capacidades de integração
+- Nomear arquivos descritivamente (ex: `user-authentication.md`, `data-export.md`, `api-integration.md`)
+
+**6. `PRODUCT_METRICS.md`**
+- Document key performance indicators:
+  - Adoption metrics (downloads, stars, usage statistics)
+  - Quality metrics (test coverage, performance benchmarks, issue resolution)
+  - Feature performance (high-performing vs underperforming features)
+  - Usage correlation patterns and success indicators
+- Focus on metrics that indicate product health and market success
+
+**7. `COMPETITIVE_LANDSCAPE.md`**
+- Research and analyze direct competitors:
+  - Competitive strengths, weaknesses, and positioning
+  - Pricing strategies and business models
+  - Customer overlap and differentiation strategies
+  - Win/loss scenarios and competitive messaging
+- Include competitive positioning framework and objection handling
+
+**8. `INDUSTRY_TRENDS.md`**
+- Analyze market evolution and trends:
+  - Industry landscape and evolution patterns
+  - Technology trends affecting the market
+  - Regulatory environment and compliance requirements
+  - Future predictions and strategic implications
+- Focus on trends that affect product strategy and customer needs
+
+**9. `SALES_PROCESS.md`**
+(if relevant)
+- Document customer acquisition strategy:
+  - For B2B products: Sales methodology, qualification criteria, common objections
+  - For Open Source: Community building, contribution workflows, monetization strategy
+  - For B2C: User acquisition, conversion funnels, retention strategies
+- Include customer success patterns and expansion opportunities
+
+**10. `MESSAGING_FRAMEWORK.md`**
+- Define brand voice and messaging:
+  - Brand personality and tone guidelines
+  - Core messaging and value propositions
+  - Audience-specific messaging strategies
+  - Content guidelines and communication style
+- Ensure messaging aligns with customer preferences and market positioning
+
+**11. `CUSTOMER_COMMUNICATION.md`**
+- Create AI interaction guidelines:
+  - Communication principles and objectives
+  - Response guidelines for different scenarios
+  - Escalation triggers and privacy considerations
+  - Personalization strategies and relationship building approaches
+- Tailor guidelines to the specific customer base and communication channels
+
+## Fontes e Métodos de Pesquisa
+
+### Fontes Primárias
+- **Documentação do Produto**: Arquivos README, documentação oficial, docs de API
+- **Feedback do Cliente**: Issues do GitHub, avaliações, depoimentos, tickets de suporte
+- **Materiais de Marketing**: Texto do website, landing pages, posts de blog, estudos de caso
+- **Canais da Comunidade**: Fóruns, Discord, comunidades Slack, mídias sociais
+- **Inteligência Competitiva**: Websites de concorrentes, documentação, feedback de usuários
+
+### Técnicas de Pesquisa
+- **Análise de Busca Web**: Pesquisar concorrentes, tendências de mercado e insights do setor
+- **Análise de Conteúdo**: Extrair insights de documentação e comunicações existentes
+- **Reconhecimento de Padrões**: Identificar tendências no feedback e comportamento do cliente
+- **Pesquisa Competitiva**: Analisar posicionamento de concorrentes e recepção do cliente
+- **Inteligência de Mercado**: Coletar tendências do setor e informações regulatórias
+
+## Quality Assurance
+
+### Content Accuracy
+- [ ] All customer insights are based on actual feedback and data
+- [ ] Competitive analysis includes current, verifiable information
+- [ ] Product features and capabilities are accurately represented
+- [ ] Market trends are supported by research and evidence
+- [ ] Business model and strategy align with actual company direction
+
+### AI Optimization
+- [ ] Content enables AI to provide contextually appropriate customer support
+- [ ] Customer personas include specific AI interaction guidelines
+- [ ] Communication guidelines are actionable for AI systems
+- [ ] Business context is structured for AI decision-making support
+- [ ] Cross-references create comprehensive business intelligence
+
+### Completeness Validation
+- [ ] All business context layers are thoroughly addressed
+- [ ] Customer journey covers full lifecycle from awareness to advocacy
+- [ ] Competitive landscape includes direct and indirect competitors
+- [ ] Product strategy aligns with actual market positioning
+- [ ] Communication guidelines match customer preferences
+
+## Execution Strategy
+
+1. **Customer-First Research**: Start with deep customer understanding before strategy
+2. **Evidence-Based Insights**: Ground all business intelligence in real data and feedback
+3. **Multi-File Architecture**: Always create linked, focused files for each business area
+4. **AI-Optimized Structure**: Organize information for AI consumption and decision-support
+5. **Market-Informed Strategy**: Ensure all business context reflects current market realities
+6. **Cross-Functional Integration**: Connect business context with technical implementation
+
+## Critérios de Sucesso da Saída
+
+A documentação de negócio gerada deve permitir:
+- **Suporte ao cliente com IA** fornecer assistência contextualmente apropriada
+- **Times de vendas e marketing** alinhar mensagens com necessidades do cliente e posição no mercado
+- **Decisões de produto** serem tomadas com contexto completo de cliente e mercado
+- **Planejamento estratégico** aproveitar inteligência competitiva e de mercado abrangente
+- **Comunicação com cliente** ser consistente com voz da marca e preferências do cliente
+
+## Adaptation Guidelines
+
+### For Different Business Models
+- **B2B SaaS**: Emphasize enterprise sales, customer success, and competitive differentiation
+- **Open Source**: Focus on community building, contributor engagement, and monetization strategy
+- **B2C Products**: Highlight user experience, conversion optimization, and retention strategies
+- **Developer Tools**: Prioritize technical accuracy, developer experience, and ecosystem integration
+
+### For Different Company Stages
+- **Early Stage**: Focus on customer discovery, market validation, and product-market fit
+- **Growth Stage**: Emphasize scaling strategies, competitive positioning, and market expansion
+- **Enterprise Stage**: Include comprehensive competitive analysis, compliance, and strategic partnerships
+
+## Error Handling and Gaps
+
+When information cannot be determined:
+- Mark sections as "RESEARCH NEEDED" with specific data requirements
+- Provide frameworks for gathering missing information
+- Create hypotheses based on available data with clear validation steps
+- Reference industry standards and best practices as interim guidance
+
+Lembre-se: O objetivo é criar inteligência de negócio acionável que permite sistemas de IA entenderem clientes, dinâmicas de mercado e contexto estratégico para fornecer suporte de negócio superior e assistência na tomada de decisões.

package/templates/.onion/contexts/technical/commands/intermediate/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/.onion/contexts/technical/commands/intermediate/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.