█████ ████ ███ █ █ █████ ███ ███ ████ █████ █ █ ███ ████ █████ █ █ ███ ████ █ █
█ █ █ █ █ ██ ██ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █
████ ████ █████ █ █ █ ████ █ █ █ █ █ ████ █ █ █ ████ ████ █ █ █ █ █ ████ ███
█ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ ██ ██ █ █ █ █ █ █
█ █ █ █ █ █ █ █████ ███ ███ ████ █████ █ ███ ████ █████ █ █ ███ █ █ █ █
Um framework de governança que organiza escopo, planos, changelogs, auditorias, troubleshooting, decisões arquiteturais, design system, habilidades de IA sob demanda e wiki técnica — tudo em Markdown versionado. Stack-agnostic, 100% rastreável, projetado para que agentes de IA trabalhem com regras claras.
2
3
4
5
6
Um framework de governança assistida por IA focado em rastreabilidade, arquitetura de memória técnica e automação de fluxos de decisão técnica. Funciona como documentação versionada em Markdown, organiza planos, changelogs, auditorias, troubleshooting, decisões, design system, habilidades e wiki técnica.
2
3
4
5
6
Não é uma ferramenta de chat genérica, nem um sistema de gestão de projetos (Jira/Trello). Não é uma biblioteca de código ou um SDK. Não substitui a validação humana final, mas atua como o sistema nervoso central da lógica arquitetural.
Problemas que o FCVW Resolve
2
3
4
5
6
7
Dívida de Contexto
Decisões técnicas perdidas entre sessões de IA, threads de Slack ou reuniões sem ata. A IA perde o fio da meada a cada nova sessão.
2
3
4
5
6
7
Inconsistência de Padrão
Cada sessão de IA gera código com arquitetura e padrões diferentes, sem um guia vivo.
2
3
4
5
6
7
Erosão de Requisitos
O código final diverge drasticamente do que foi pedido, sem rastreabilidade de mudanças.
Ciclo Operacional
V3.0 LOGIC2
3
4
5
6
7
8
9
10
11
12
Primeiro carregamento operacional da sessão para limitar escopo.
Alinhamento operacional de humanos e agentes através do AGENTS.md.
Definição de intenção do usuário ou diagnóstico de bugs.
Blueprint técnico aprovado (pending) detalhando a alteração.
Código alterado de forma controlada conforme o escopo planejado.
Validação e registro de saídas físicas e testes no terminal.
Geração do fragmento delta de changelog e auditoria pré-release.
Compactação do aprendizado da sessão (AICC) e publicação opcional.
Os 8 Pilares do Framework
Governança por Planos
Nenhuma alteração funcional, visual, estrutural ou documental é aplicada sem um plano correspondente em FCVW/Plans/.
Rastreabilidade por Versão
Toda alteração em arquivo versionado é registrada em FCVW/changelogs/. Sem exceções, nem para ajustes pequenos.
Memória Técnica Incremental
A wiki em FCVW/wiki/ segue o padrão LLM Wiki: fontes brutas, páginas sintetizadas, índice, log e estados de confiança.
Design System Declarativo
FCVW/DESIGN.md centraliza tokens, regras visuais, contratos de componentes e critérios de experiência.
Refatoração Governada
FCVW/REFACTORING.md e o refactoring-guide/ definem quando refatorar, como mapear risco, quais testes e quando parar.
Separação Framework/App
Templates genéricos ficam em FCVW/governance/. Documentos preenchidos ficam nos canônicos do projeto. Sem mistura.
Instanciação Nova e Retroativa
FCVW/INSTANTIATION.md para projetos novos. FCVW/RETROACTIVE_INSTANTIATION.md para aplicações existentes ou legadas.
Motor de Habilidades (Skills)
FCVW/skills/ armazena procedimentos JIT carregados sob demanda pelo agente, nunca pré-carregados no prompt.
Arquivos do Framework
Cada arquivo tem um propósito específico. A IA carrega apenas os documentos relevantes para o tipo de sessão.
Carregamento Seletivo de Contexto
O FCVW impõe um carregamento seletivo e JIT de contexto para evitar desperdício de tokens.
- Ler
CONTEXT_MAP.mdprimeiro para mapear a sessão. - Consultar
AGENTS.mdpara alinhamento operacional. - Identificar o tipo de sessão ativo.
- Carregar apenas os documentos imediatos necessários.
- Consultar documentos canônicos sob demanda do escopo.
- Ignorar e pular documentos não relacionados à tarefa.
Antes de Modificar Arquivos, a IA Deve:
- 1.Verificar o estado físico e git do repositório.
- 2.Consultar CONTEXT_MAP.md para mapear o escopo.
- 3.Consultar AGENTS.md para regras operacionais.
- 4.Ingerir a última síntese AICC da wiki para alinhar contexto.
- 5.Identificar formalmente o tipo de sessão técnica.
- 6.Verificar se há skill JIT aplicável em skills/ e ativá-la via ASE.
- 7.Localizar ou criar um plano (pending) em Plans/.
- 8.Confirmar que as alterações estão dentro dos arquivos em escopo.
- 9.Preservar mudanças preexistentes e evitar reversões acidentais.
- 10.Regra Anti-Ação Imediata: Se o pedido for ambíguo, extrair intenção, critérios e riscos em vez de alterar código.
Agentes
Agentes especializados que podem ser ativados sob demanda conforme o tipo de sessão.
Aegis — Agente de Código de Segurança
- •Focado em melhorias pequenas, seguras e verificáveis de segurança
- •Validação e sanitização de entradas contra injeção de comandos
- •Tratamento seguro de segredos e dados pessoais sensíveis
- •Remediações localizadas com baixo risco de regressão
- •Conformidade técnica seguindo os controles de SECURITY.md
- •Correções e hardening de segurança com plano e evidência física
Hephaestus — Agente de UX/UI
- •Focado em melhorias pequenas e seguras de UX/UI
- •Implementação de microinterações e transições de interface
- •Ajustes de acessibilidade (contraste, aria-labels, navegação por teclado)
- •Consistência visual e polimento de componentes de design
- •Não realiza redesigns complexos ou migrações amplas de comportamento
Hermes — Agente de Performance
- •Focado em otimizações pequenas, seguras e mensuráveis de performance
- •Identificação e resolução de gargalos de processamento em runtime
- •Redução de bundle size e otimização de ativos
- •Eliminação de re-renderizações e latência de layout
- •Otimização de rotinas de caching de rede e armazenamento
Orquestrador de Coordenação Multi-Agente
- •Coordena a delegação e ativação de múltiplos agentes e skills
- •Usado para refactorizações amplas, migrações e investigações complexas
- •Descompõe tarefas em alcances paralelos de execução
- •Gestiona conflitos entre agentes especializados em sessões ativas
- •Mantém a integridade do estado e o alinhamento de contexto
Motor de Habilidades (Skills JIT)
Procedimentos técnicos carregados sob demanda pelo agente. Nunca pré-carregados no prompt — economiza tokens e mantém o foco.
Sessão AICC compacta para validação de conformidade com baixo consumo de tokens
Investigação estruturada de bugs usando dados históricos da wiki
Compactação e descarte seguro de contexto antigo da memória técnica
Checklist pré-release: docs, testes, changelogs validados
Validação de estrutura, links e formatação da wiki técnica
Validação de configurações de agentes (SKILL.md, CLAUDE.md, MCP). Suporta LSP
Brainstorming socrático + loop Red-Green-Refactor de TDD
Padrão de mensagens Git (feat:, fix:, etc.) para changelog automático
Formatação Markdown compatível com Obsidian vault
Scaffold de novo projeto com estrutura FCVW completa
Adoção FCVW em codebase existente com defaults não-destrutivos
Comportamento da IA por Cenário
Cada tipo de sessão define quais documentos a IA carrega e qual comportamento é esperado.
| Cenário | Documentos Carregados | Comportamento Esperado | ||
|---|---|---|---|---|
| Bugfix / Troubleshooting | AGENTS.md + TROUBLESHOOTING.md + PLANNING.md | ~5.000 | ~1.200 | -76% |
| Feature Nova | AGENTS.md + SCOPE.md + PLANNING.md + DESIGN.md | ~7.000 | ~1.500 | -78% |
| UI / Componentes | AGENTS.md + DESIGN.md | ~4.000 | ~900 | -77% |
| Refatoração | AGENTS.md + REFACTORING.md + PLANNING.md | ~8.000 | ~1.800 | -77% |
| Instanciação Nova | AGENTS.md + INSTANTIATION.md + BRIEFING.md + MANIFEST.md | ~8.500 | ~2.000 | -76% |
| Instanciação Retroativa | AGENTS.md + RETROACTIVE_INSTANTIATION.md + CONTEXT_MAP.md | ~7.500 | ~1.900 | -75% |
| Release | CONTEXT_MAP.md + skill:release-checklist | ~2.500 | ~600 | -76% |
Escopo Mínimo dos Templates
Campos obrigatórios para cada tipo de documento de governança.
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Plano de Alteração
TEMPLATE_PLAN.md
- [ID] Identificador único
- [OBJECTIVE] Meta mensurável
- [PRIORITY] Prioridade P1-P5
- [RISK] Nível de risco R1-R5
- [CONTEXT_FILES] context_files: []
- [IMPACT] Arquivos e módulos afetados
- [TECH_STACK] Ferramentas e bibliotecas
- [CURRENT_VERSION] Versão atual
- [EXPECTED_VERSION] Versão após mudança
- [ACCEPTANCE_CRITERIA] Critérios de aceitação
- [TEST_PLAN] Plano de testes
- [VALIDATION_STEPS] Como validar
- [ROLLBACK] Plano de recuo
2
3
4
5
6
7
8
Troubleshooting
TEMPLATE_TROUBLESHOOTING.md
- [SYMPTOM] Sintoma observado
- [ENVIRONMENT] Ambiente do problema
- [REPRODUCTION_STEPS] Passos para reproduzir
- [ROOT_CAUSE] Causa raiz identificada
- [SOLUTION] Solução aplicada
- [PREVENTION] Medidas preventivas
2
3
4
5
6
7
ADR — Decisão Arquitetural
TEMPLATE_ADR.md
- [TITLE] Título descritivo da decisão
- [STATUS] Proposed / Accepted / Deprecated / Superseded
- [CONTEXT] Contexto do problema e forças em jogo
- [DECISION] Decisão tomada e justificativa
- [CONSEQUENCES] Consequências positivas e negativas
Matriz de Risco e Prioridades
A classificação de planos por prioridade e risco define os portões de governança, o fluxo de rollback e as exigências de validação para as alterações do repositório.
2
3
4
5
6
7
8
9
10
11
12
13
14
15
low_priority Escala de Prioridade (P1–P5)
Crítica (Critical)
Segurança, integridade de dados e falhas críticas que impedem o uso.
Alta (High)
Fluxos principais da aplicação, estabilidade e novas funcionalidades relevantes.
Média (Medium)
Melhorias funcionais de processos, organização geral ou usabilidade do sistema.
Baixa (Low)
Ajustes visuais, textos da interface ou pequenas refatorações localizadas.
Opcional (Optional)
Ideias futuras, melhorias experimentais de código ou otimizações não essenciais.
2
3
4
5
6
7
8
9
10
11
12
13
14
15
warning Escala de Risco (R1–R5)
Muito Baixo (Very Low)
Apenas alterações de textos, documentação ou estilos visuais sem lógica ou dados.
Baixo (Low)
Alterações em componentes isolados, lógica simples e testes puramente locais.
Moderado (Moderate)
Lógica compartilhada entre módulos, fluxos operacionais principais, possibilidade de regressões.
Alto (High)
Persistência local, estados globais de aplicação, refatoração de módulos importantes ou integrações.
Crítico (Critical)
Segurança de acessos, autenticação, migração estrutural de banco de dados ou risco severo de perda de dados.
calculate Operational Score
O Operational Score determina os portões obrigatórios de validação que o plano deve seguir.
grid_on Matriz de risco 5x5
Eixo Horizontal: Prioridade (P1 a P5) | Eixo Vertical: Risco (R1 a R5)
| Risk \ Pri | P1 (5) | P2 (4) | P3 (3) | P4 (2) | P5 (1) |
|---|---|---|---|---|---|
| R5 (5) | 25 |
20 |
15 |
10 |
5 |
| R4 (4) | 20 |
16 |
12 |
8 |
4 |
| R3 (3) | 15 |
12 |
9 |
6 |
3 |
| R2 (2) | 10 |
8 |
6 |
4 |
2 |
| R1 (1) | 5 |
4 |
3 |
2 |
1 |
Documentação da Aplicação em Desenvolvimento
O framework VibeWork determina que a documentação das regras de negócio, telas e fluxos da própria aplicação deve residir fora da pasta do framework canônico, seguindo o padrão de separação física de propriedades.
share Separação de Propriedade Física
O Framework define a regra: A pasta FCVW/ e seus subdiretórios guardam as instruções e os templates genéricos de governança que orientam a IA e os desenvolvedores.
A Aplicação possui o conteúdo: A documentação das regras e telas geradas pertence à aplicação downstream e deve residir em docs/ na raiz do projeto (como docs/modules/ e docs/flows/), mantendo o código e o negócio separados.
folder_open Estrutura Física Recomendada
Governança por Planos
Criação do Plano
O escopo da mudança é definido em um plano (pending) em Plans/. O plano é criado usando TEMPLATE_PLAN.md como base com a lista context_files.
Contexto AICC
A IA ingere a última síntese e prepara a compressão de contexto para a sessão, mitigando alucinações e context drift.
Verificação do Plano
Plano verificado antes da execução; confirmação humana explícita para mudanças destrutivas, sensíveis ou ambíguas.
Execução Rastreada
O código é gerado seguindo estritamente o plano aprovado. Cada mudança gera changelog obrigatório.
Ciclo de Vida do Plano
- pending:Plano criado, ainda não executado
- in_progress:Plano em execução
- completed:Execução concluída e validada
- discontinued:Plano encerrado sem conclusão, com justificativa
2
3
4
5
6
7
8
LLM Wiki
wiki/schema.md
- • Estrutura de Obsidian Vault com navegação gráfica entre links e decisões
- • Frontmatter obrigatório com status, nível de confiança e referências
- • Promoção de conhecimentos reutilizáveis e registro explícito de lacunas
- • Política de Contradições: Sinalizar conflitos e marcar páginas obsoletas/superseded
- • Créditos de Conceito: Inspirado na abordagem de LLM Wiki proposta por Andrej Karpathy
2
3
4
5
6
7
8
Refatoração Governada
REFACTORING.md
- • Garantia estrita de comportamento externo preservado (sem misturar com novas features)
- • Classificação de refatoração em tipos RF1 a RF10
- • Matriz de risco R1 a R5 com definição de testes mínimos obrigatórios
- • Rollback documentado obrigatório para alterações de riscos R4 e R5
- • Dívida Técnica: Registro em Ledger (#tech-debt) com risco e condições de remoção
2
3
4
5
6
7
8
Versionamento e Release
VERSIONING.md / RELEASE.md
- • Formato de numeração Vx.y.z seguindo SemVer rigoroso
- • Changelog cumulativo compilado de fragmentos da unreleased/
- • Processo de publicação com status formais e plano de recuo/rollback
- • Auditoria documental e integridade pré-publicação
- • Fonte de Verdade: A pasta FCVW/ é canônica; docs/ é apenas interface de deploy
Technical Engine
2
3
4
5
6
7
8
AICC
AI Interaction Context Compression- •Mecanismo de continuidade de contexto e síntese incremental entre sessões de IA
- •Compactação de contexto operacional para redução de desperdício de tokens
- •Preservação de decisões técnicas, pendências e riscos ativos
- •Apoio à rastreabilidade do raciocínio e fechamento da sessão com nova síntese
2
3
4
5
6
7
8
9
ASE
AI Skills Engine- •Carregamento JIT (Just-in-Time) de habilidades e checklists sob demanda
- •Execução especializada e isolada por tipo de tarefa
- •Separação entre prompt-base e procedimentos específicos
- •Economia drástica de tokens ao evitar contexto permanente no prompt
- •Gatilhos automatizados por tipo de tarefa com registro na síntese AICC
2
3
4
5
6
7
8
Controles de Segurança
Security Controls- •Regras documentadas e auditoria contínua em SECURITY.md
- •Uso da skill agent-aegis e do agente correspondente para hardening localizado
- •Confirmação humana obrigatória para comandos e ações destrutivas
- •Segredos mantidos localmente em env variables, fora de logs, chat e changelogs
Estimativa de Consumo de Tokens por Cenário
Referências de planejamento para reduzir custo de contexto em chamadas de LLMs. Recalibre após crescimento dos documentos.
| Cenário | Documentos Ingeridos | Custo Inicial | Com AICC Compact | Economia |
|---|---|---|---|---|
| Bugfix / Troubleshooting | AGENTS + TROUBLESHOOTING + PLANNING | ~4.700 | ~1.500 | ~68% |
| Feature Nova | AGENTS + SCOPE + PLANNING + DESIGN + PERF | ~7.400 | ~2.800 | ~62% |
| UI / Componentes | AGENTS + DESIGN | ~4.500 | ~1.600 | ~64% |
| Refatoração | AGENTS + REFACTORING + PLANNING | ~7.300 | ~2.500 | ~66% |
| Release | CONTEXT_MAP + release-checklist | ~3.400 | ~1.200 | ~65% |
| Segurança / Dados | AGENTS + SECURITY + DATA + ENV | ~8.200 | ~3.000 | ~63% |
| AI / RAG / Wiki | AGENTS + AI + wiki/schema | ~5.800 | ~2.100 | ~64% |
| Auditoria Documental | AGENTS + MANIFEST + AUDIT | ~6.600 | ~2.400 | ~64% |
| Novo Projeto | AGENTS + INSTANTIATION + BRIEFING + MANIFEST | ~8.100 | ~3.200 | ~60% |
| Migração Retroativa | AGENTS + RETROACTIVE + CONTEXT_MAP | ~5.800 | ~2.000 | ~66% |
Parâmetros de LLM Recomendados
| Model Range | Context Window | Uso Recomendado |
|---|---|---|
| 7B — 8B | 8k — 32k | Micro-tarefas, autocompletar código, formatação |
| 14B — 32B | 32k — 128k | Planos, code review, mapeamento de integração |
| 32B — 70B+ | 128k+ | Arquitetura complexa, auditoria cross-repo |
Segurança & Validação
2
3
4
5
6
7
8
9
Princípios & Classificações
- Privilégio mínimo por padrão de execução
- Validação estrita de entradas e prevenção de path traversal
- Confirmação humana obrigatória para comandos destrutivos
Classificação S1-S4:
- S1 — Low: Sem dados sensíveis, sem rede, sem comandos críticos.
- S2 — Moderate: Acesso a dados locais sem exposição de segredos.
- S3 — High: Contratos de persistência, tokens e ações destrutivas.
- S4 — Critical: Execução de comandos de alto privilégio ou rede externa.
2
3
4
5
Secret Handshake Protocol
A IA está proibida de solicitar segredos, API keys ou tokens no chat público da sessão.
Em vez disso, a IA deve preparar a variável local adequada no arquivo .env.local e orientar o usuário a preencher o valor localmente no seu computador, longe dos logs de conversação.
SUPABASE_TOKEN= # Copie localmente aqui
2
3
4
5
6
Security Checklist
Licença
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
MIT License
Copyright (c) 2026 Hugo Araújo de Melo
MIT License Copyright (c) 2026 Hugo Araújo de Melo Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.