Pular para conteúdo

ConectaFapes SOT

Este repositório é a Source of Truth (SOT) para governança, arquitetura e planejamento de evolução dos subdomínios de um sistema de Grant Management.

A ideia é simples: centralizar estratégia, decisões técnicas e plano de execução em um lugar versionado, para reduzir dependência de ferramentas externas e aumentar a coesão entre PO/PM, arquitetura, desenvolvimento e operações.

Visão de uso

Este SOT suporta o ciclo:

SOW -> Discovery -> Inception -> Implementação -> Operação

Com isso: - gestão e engenharia consultam a mesma base; - mudanças de direção ficam explícitas em histórico Git; - análise de evolução pode ser feita por diff de ADRs, sprints e artefatos.

Estrutura do repositório

  • docs/: documentacao para leitura humana + configuracao do MkDocs.
  • method/: processo de trabalho, SDLC, onboarding e uso do SOT.
  • product-definition/: referencia de metodo e entregaveis para discovery, inception e handoff para implementacao.
  • plan/: planejamento segmentável por domínio/subdomínio de trabalho (em dev e ops), ADRs e rastreabilidade.
  • agents/: guias de agents e skills por função/componente.
  • CONTRIBUTING.md: guia central de governança e contribuição.
  • AGENTS.md: regras operacionais para agentes.

Segmentação do plano por domínio/subdomínio

O planejamento em plan/ pode ser organizado por domínio/subdomínio do produto e também por fase de trabalho (dev e ops).

Exemplo prático: - Pre-Award pode ter seu próprio conjunto de planejamento. - Post-Award pode ter outro conjunto independente. - times diferentes podem atuar nesses contextos em paralelo ou em momentos distintos.

Isso permite que cada contexto evolua com autonomia, mantendo coesão no SOT via rastreabilidade comum (ADRs, sprints, tasks e evidências).

Princípios operacionais

  • Toda mudança no SOT altera governança de produto.
  • PR no SOT deve ter rastreabilidade clara.
  • Evolução segue commits semânticos e PRs.
  • Aprovação de PR deve seguir regra de 2 gestores (detalhes em CONTRIBUTING.md e arquivos em .github/).

Gestão ativa via documentação renderizada

A gestão ativa deste repositório depende do acompanhamento da documentação renderizada.
Em prática: decisões e mudanças devem ser revisadas no site local do MkDocs, não só no diff bruto de Markdown.

Isso ajuda a validar: - navegação e coesão dos artefatos; - links relativos entre docs, agents e plan; - entendimento de fluxo para times não técnicos.

Como rodar localmente (MkDocs)

O projeto usa Makefile, mkdocs.yml e requirements.txt na raiz do repositorio.

Pré-requisitos

  • make
  • python3
  • mkdocs disponível (global ou em .venv)

Comandos principais

make build
make run

Comportamento: - make build: gera o site em ../site/. - make run: sobe servidor local do MkDocs a partir da raiz do repositorio.

URL local: - http://127.0.0.1:9999/conectafapes-sot/

Uso no Windows

Se você usa Windows, abra o repositório via WSL (recomendado).

Passos: 1. Abra terminal WSL (Ubuntu ou equivalente). 2. Navegue até o repositório pelo terminal WSL. 3. Execute os comandos de build/run na raiz do repositorio.

Evite executar via terminal CMD/PowerShell para este fluxo, pois o ambiente e paths do projeto foram padronizados para shell Unix.

Referências rápidas

  • Governança e fluxo oficial: CONTRIBUTING.md
  • Método de trabalho e onboarding: method/
  • Regras para agentes: AGENTS.md
  • Planejamento e rastreabilidade: plan/
  • Product definition e contexto inicial: product-definition/