umbrella-coding

Kit instalavel e reutilizavel para iniciar, organizar ou continuar qualquer projeto com um fluxo de agente mais proximo de "Claude Code / Codex-like", mas com baixo atrito.

O que e

umbrella-coding funciona como um framework operacional leve para projetos assistidos por agente.

Ele existe para ser aplicado sobre:

• uma pasta nova
• um repositorio ja existente
• um projeto baguncado que precisa ganhar padrao
• um projeto em andamento que precisa de continuidade e contexto

A proposta e ser algo mais proximo de um GSD-like installable kit do que de um produto final tradicional.

Diretriz principal

O kit existe para ajudar o agente a trabalhar de forma proxima de Claude Code / Codex-like, mas com gestao enterprise-like desde o inicio.

Na pratica, isso significa:

• contexto nunca pode ficar so na conversa
• fix temporario nao e caminho padrao
• toda atividade relevante deve deixar rastro canônico
• toda entrega deve buscar fechamento completo e verificavel
• toda mudanca relevante deve buscar protecao contra regressao
• estrutura, documentacao e continuidade importam tanto quanto a execucao

O que ele instala em um projeto

• um contrato canonico via AGENTS.md
• compatibilidade com Claude Code via CLAUDE.md
• memoria viva via uma root canonica de planning (.planning/ por default)
• log leve de decisoes na root canonica de planning
• limite ativo de fase na root canonica de planning
• documentacao minima via docs/README.md e DOC_REGISTRY.md
• uma memory layer local em docs/memory/ para principios, decisoes e indice tematico
• perfis leves por tipo de projeto e uma matriz de verificacao reutilizavel
• diretrizes de contexto e awareness de runtime
• prompts/agentes locais para OpenCode
• um ponto de partida seguro para planejar, implementar, verificar e continuar

Stack mental

umbrella-coding combina:

• OpenCode como runtime principal
• GSD como memoria viva e continuidade
• padrao estrutural orientado a continuidade, contexto e entrega disciplinada
• compatibilidade de contexto com Claude Code / OMC quando necessario

Core e adapters

O kit agora deixa mais explicito o que e estrutural e o que e especifico de runtime.

• core = contexto canonico, root de planning, perfis, verificacao, coordenacao leve, evals
• adapters = OpenCode, compatibilidade Claude/OMC e qualquer superficie especifica de runtime

Isso nao muda o comportamento do kit. So evita acoplamento silencioso e ajuda a evoluir suporte multi-runtime sem bagunca.

Perfis de projeto e verificacao

O kit nasce com perfis leves para que o agente nao precise reaprender do zero como fechar cada tipo de repo.

Perfis incluidos:

• general
• backend-api
• frontend-web
• data-pipeline
• automation

O fluxo esperado e simples:

1. o agente le AGENTS.md e o STATE.md da root de planning canonica
2. se o perfil ja estiver explicito, ele o usa
3. se nao estiver, ele infere na primeira passagem de mapeamento
4. ele registra isso no PROJECT.md da root de planning canonica
5. ele fecha a tarefa usando docs/verification-matrix.md

Isso mantem a experiencia de "abrir a pasta e comecar", mas com verificacao menos generica.

Contexto seletivo e awareness de harness

O kit agora endurece duas coisas que influenciam muito a qualidade real:

• carregar so o contexto util em vez de despejar metade do repo no modelo
• reconhecer que o mesmo modelo pode performar diferente dependendo do runtime/harness

Isso ficou refletido em:

• prompts e subagentes mais seletivos
• docs/context-discipline.md
• docs/runtime-harness-awareness.md
• evals novos para medir contexto e runtime

Coordenacao leve entre subagentes

O kit tambem endurece a orquestracao sem ficar pesado.

A regra e:

• um agente principal continua sendo a porta de entrada
• subagentes ocultos entram so quando realmente ajudam
• o handoff precisa ser curto, claro e path-based
• o retorno do subagente precisa vir em formato minimo e acionavel

Isso reduz perda de contexto sem transformar o kit em uma agencia complexa. A referencia canonica disso agora esta em docs/agent-coordination.md.

Decisoes, escopo e baseline

Para projetos longos, o kit agora reforca tres artefatos simples:

• DECISIONS.md para decisoes estruturais
• SCOPE.md para o limite da fase atual
• STATE.md como arquivo de controle para verdade atual, proximo passo seguro, baseline e riscos vivos

Isso ajuda a evitar tres falhas classicas:

• re-litigar decisoes antigas
• implementar fora do escopo sem perceber
• quebrar algo que antes passava sem deixar a regressao explicita

Para reduzir ambiguidade entre runtimes, o STATE.md agora deve ficar estavel o suficiente para ser escaneado por qualquer agente. As secoes esperadas sao:

• Delivery Status
• Canonical Continuity
• Current Truth
• Next Safe Step
• Regression Baseline
• Open Risks
• Pending Updates
• Blockers

Memoria local e shared memory opcional

Todo projeto bootstrappado agora recebe uma camada local em docs/memory/ com:

• PRINCIPLES.md
• DECISIONS.md
• MEMORY_INDEX.md

Ela existe para destilar conhecimento duravel e reaproveitavel sem substituir os arquivos canonicos do projeto.

Se no futuro existir uma memoria compartilhada cross-project, por exemplo com Postgres + pgvector, ela deve permanecer opcional e secundaria. A regra continua sendo:

• a memoria compartilhada sugere precedentes
• o projeto atual decide
• o documento canonico confirma

Suporte por runtime

O kit tambem passa a registrar de forma mais honesta o estado atual de suporte por runtime.

Isso serve para diferenciar:

• o que ja esta forte no caminho OpenCode
• o que esta apenas compativel no lado Claude/OMC
• o que ainda e intencionalmente fora de escopo

Essa leitura fica em docs/runtime-parity.md.

Model routing barato por padrao

O kit fecha a disciplina de custo assim:

• um modelo barato como default global
• premium apenas como fallback por excecao
• criterio explicito de escalacao em docs/model-routing.md
• uso de evals leves para medir quando o fallback premium realmente vale a pena

O objetivo nao e adivinhar o melhor modelo do mundo. O objetivo e manter a experiencia forte sem custo alto no caminho normal.

Evals leves para manter o kit honesto

O repositorio inclui uma suite leve em evals/ para validar:

• bootstrap em repo vazio
• bootstrap em repo existente
• inferencia de perfil
• verificacao orientada por perfil
• disciplina de contexto
• comparacao de runtime/harness
• disciplina de handoff entre subagentes
• disciplina de drift guard

A ideia nao e criar uma plataforma de benchmark pesada. A ideia e evitar regressao silenciosa conforme o kit evolui.

Politica forte de testes

O kit assume como padrao que mudanca relevante precisa de protecao contra regressao sempre que isso for razoavelmente possivel.

Na pratica:

• mudanca de comportamento pede teste, check, smoke ou eval correspondente
• verificacao nao serve so para provar que algo rodou uma vez
• verificacao serve para reduzir chance de quebrar depois
• o tipo de protecao deve seguir o perfil do projeto e o risco da mudanca

Exemplos concretos

O repositorio tambem inclui exemplos gerados em examples/ para que o kit fique tangivel:

• greenfield-backend-api/
• existing-automation-repo/

Eles sao regenerados por:

./scripts/regenerate-examples.sh

O objetivo real

Permitir que voce faca algo assim em qualquer projeto:

cd /path/to/umbrella-coding
./bootstrap.sh /path/to/project

Ou, se preferir guardar o caminho em uma variavel:

export UMBRELLA_CODING_ROOT=/path/to/umbrella-coding
"$UMBRELLA_CODING_ROOT/bootstrap.sh" /path/to/project

E depois simplesmente comece a conversar com o agente, sem ter que redesenhar toda a estrutura de contexto e operacao do zero.

Principios

• baixa friccao para comecar
• enterprise-like sem burocracia excessiva
• reutilizavel em projetos de naturezas diferentes
• barato por padrao, premium so quando realmente necessario
• compativel com multiplos runtimes no nivel do contexto
• verificacao orientada por perfil, nao por checklist cego
• melhoria guiada por evals, nao por impressao solta
• contexto seletivo em vez de contexto maximalista
• orquestracao leve em vez de multiplicacao de agentes

O que o repositorio umbrella-coding entrega

• bootstrap.sh para aplicar o kit em qualquer repositorio
• templates de AGENTS.md, continuidade canonica de planning, docs/, profiles/ e opencode.jsonc
• prompts locais para um agente principal e subagentes ocultos de mapeamento, review e verificacao
• documentacao para operar o kit com consistencia
• um guard leve para drift entre arquivos espelhados da raiz e templates/
• guidance de model routing barato/premium
• evals e scorecards leves para manutencao do proprio kit
• exemplos concretos gerados pelo proprio kit
• validacao de release via ./scripts/validate-kit.sh

Estrutura

umbrella-coding/
├── AGENTS.md
├── README.md
├── .planning/
├── .opencode/
├── docs/
├── evals/
├── examples/
├── global/
├── profiles/
├── scripts/
├── templates/
├── opencode.jsonc
└── bootstrap.sh

Uso rapido

Projeto novo ou existente:

cd /path/to/umbrella-coding
./bootstrap.sh /path/to/project

Inspecao sem escrita:

./bootstrap.sh --dry-run /path/to/project

Saida estruturada:

./bootstrap.sh --dry-run --format=json /path/to/project

Comportamento em projeto existente (sobreposicao segura)

O bootstrap foi desenhado para evitar sobrescrita leviana.

Regras atuais:

• roots canônicas de continuidade compatíveis sao adotadas automaticamente quando ja existem
• docs/planning/ e planning/ podem virar a raiz de planning no lugar de .planning/
• docs/memory/ e memory/ podem virar a raiz de memory no lugar do default
• arquivos inexistentes do kit sao criados normalmente
• arquivos existentes fora do conjunto de merge seguro continuam como skip
• arquivos existentes no conjunto de merge seguro recebem um bloco de overlay idempotente, preservando o conteudo original

Conjunto de merge seguro atual:

• AGENTS.md
• docs/README.md
• docs/memory/README.md
• docs/memory/PRINCIPLES.md
• docs/memory/DECISIONS.md
• docs/memory/MEMORY_INDEX.md

Cada instalacao gera um manifesto em:

• .umbrella/install-manifest.tsv

Esse manifesto registra as roots escolhidas (planning_root, memory_root, docs_readme) e tambem create, merge e skip.

Overrides opcionais:

• UMBRELLA_PLANNING_ROOT=<relative/path>
• UMBRELLA_MEMORY_ROOT=<relative/path>
• UMBRELLA_DOCS_README=<relative/path>

O --dry-run usa a mesma logica real do bootstrap:

• detecta roots compativeis
• resolve onde cada arquivo do kit cairia
• informa o que seria create, merge e skip
• nao escreve manifesto nem altera arquivos do projeto

Tambem existe rollback assistido pelo manifesto para os arquivos criados pelo bootstrap:

./scripts/uninstall-from-manifest.sh /path/to/project

Ou para inspecao sem escrita:

./scripts/uninstall-from-manifest.sh --dry-run /path/to/project

Esse rollback remove apenas arquivos registrados como create. Blocos de overlay merge continuam preservados e exigem revisao manual, por seguranca.

O estado final pretendido e ter um unico modelo operacional do umbrella, sem criar um segundo canônico paralelo so porque o projeto ja usava outro layout equivalente.

Depois:

1. configure o OpenCode global uma vez
2. conecte providers via /connect
3. escolha um modelo barato por padrao via /models
4. abra o projeto e comece a conversar com o agente principal
5. deixe o agente inferir o perfil do projeto na primeira passagem, se voce ainda nao o souber

Mensagem inicial recomendada para projeto existente:

Understand this project, map the codebase, infer the project profile, update PROJECT and STATE, and tell me the source of truth.

Mensagem inicial recomendada para projeto novo:

Structure this project from scratch using the AGENTS + GSD pattern, choose the safest starting profile, and define the first safe phase.

Regra pratica:

• isso e um alinhamento inicial da sessao
• nao e algo para repetir em todo prompt depois

Fonte de verdade neste repositorio

Quando houver conflito dentro do proprio umbrella-coding, seguir:

1. AGENTS.md
2. .planning/STATE.md
3. docs/README.md
4. scripts e templates executaveis

Manutencao do kit

Antes de fechar mudancas que tocam arquivos espelhados entre a raiz e templates/, rode:

./scripts/check-template-drift.sh

Antes de tratar o kit como pronto para release ou reutilizacao mais ampla, rode:

./scripts/validate-kit.sh

Quando quiser comparar setups de modelo ou regressao de comportamento, use os artefatos em evals/.

Proximos passos opcionais

• adicionar exemplos para outros perfis
• polir compatibilidade multi-runtime ainda mais
• empacotar o kit para distribuicao fora do filesystem atual