Manual de Propostas

Visão geral

O sistema de propostas da Base/labs usa o Claude Code — um assistente de IA que roda no terminal — como interface principal. Em vez de abrir planilhas, copiar templates ou editar manualmente, você conversa com o Claude e ele cuida de toda a parte técnica: criar repositório, configurar pastas no Drive, escrever o conteúdo e publicar online.

Cada proposta é um repositório Git privado criado a partir de um template. Isso garante que cada proposta seja independente e que você possa trabalhar em várias ao mesmo tempo.

Fluxo de uma proposta

Uma proposta passa por três etapas, cada uma com seu comando:

Tempo estimado por etapa

Pré-requisitos

Antes de instalar, verifique se você tem acesso a:

• Conta na organização Base2-Tecnologia no GitHub
• Acesso ao HubSpot da Base/labs
• Acesso ao Google Drive compartilhado swl-clientes
• Token da API Cloudflare (peça ao Hugo ou ao time de infra)
• Assinatura do Claude Code (Pro ou Team — claude.ai/code)

Instalação no Mac macOS

1. Instalar o Homebrew

O Homebrew é o gerenciador de pacotes do Mac. Se você já tem, pule este passo.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Instalar Node.js

brew install node

Verifique a instalação:

node --version   # deve mostrar v20 ou superior
npm --version

3. Instalar o Git

O Git provavelmente já está instalado no Mac. Verifique:

git --version

Se não estiver: brew install git

4. Instalar o GitHub CLI

brew install gh

Autentique com sua conta GitHub:

gh auth login

Escolha GitHub.com → HTTPS → Login with a web browser e siga as instruções.

5. Configurar SSH para o GitHub

O sistema usa SSH para clonar repositórios. Se você ainda não tem chave SSH configurada:

# Gera uma chave SSH (pressione Enter em todas as perguntas)
ssh-keygen -t ed25519 -C "seu-email@baselabs.com.br"

# Copia a chave pública para o clipboard
pbcopy < ~/.ssh/id_ed25519.pub

Depois acesse github.com/settings/keys, clique em New SSH key e cole a chave.

Teste a conexão:

ssh -T git@github.com

6. Instalar o Wrangler (Cloudflare CLI)

npm install -g wrangler

7. Instalar o Claude Code

npm install -g @anthropic-ai/claude-code

Faça login com sua conta Anthropic:

claude

Na primeira execução ele vai pedir para autenticar no browser.

Instalação no Windows Windows 10/11

1. Instalar o WSL2

Abra o PowerShell como Administrador (clique com botão direito no menu Iniciar → "Windows PowerShell (Admin)") e execute:

wsl --install

Reinicie o computador quando solicitado. Após reiniciar, o Ubuntu vai abrir automaticamente e pedir para criar um usuário e senha.

2. Instalar o Node.js no WSL

Dentro do terminal Ubuntu (WSL), execute:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

Verifique:

node --version
npm --version

3. Instalar o GitHub CLI

sudo apt install gh -y

Autentique:

gh auth login

Escolha GitHub.com → HTTPS → Login with a web browser.

4. Configurar SSH para o GitHub

# Gera chave SSH
ssh-keygen -t ed25519 -C "seu-email@baselabs.com.br"

# Mostra a chave pública para copiar
cat ~/.ssh/id_ed25519.pub

Copie a chave exibida, acesse github.com/settings/keys, clique em New SSH key e cole.

ssh -T git@github.com

5. Configurar diretório global do npm

No WSL2, o npm tenta instalar pacotes globais em uma pasta do sistema que seu usuário não tem permissão de escrever. Execute esses comandos para evitar erros de permissão (EACCES) nas instalações a seguir:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

6. Instalar o Wrangler

npm install -g wrangler

7. Instalar o Claude Code

npm install -g @anthropic-ai/claude-code

Autentique na primeira execução:

claude

8. Instalar o Windows Terminal (opcional, recomendado)

Abra a Microsoft Store, busque Windows Terminal e instale. Ele permite abrir abas do WSL, PowerShell e CMD na mesma janela.

Configurar credenciais

As integrações com Cloudflare, HubSpot, Google Drive e GitHub precisam de configuração uma única vez.

Token Cloudflare

Adicione o token ao seu ambiente. No Mac, edite o arquivo ~/.zshrc. No Windows (WSL), edite ~/.bashrc:

# Adicione esta linha no arquivo (substitua pelo token real)
export CLOUDFLARE_API_TOKEN="seu-token-aqui"

Depois recarregue o terminal:

# Mac (zsh)
source ~/.zshrc

# Windows/WSL (bash)
source ~/.bashrc

Teste:

echo $CLOUDFLARE_API_TOKEN

HubSpot, Google Drive e Gmail

Essas integrações são feitas via MCP servers já configurados no Claude Code. Na primeira vez que você rodar um comando que precise de HubSpot ou Drive, o Claude vai pedir para você autorizar. Siga as instruções na tela — é um login OAuth padrão no browser.

Verificar se tudo está funcionando

Abra o Claude Code de qualquer diretório e rode:

claude

Depois, dentro do Claude, tente:

/swl-init-proposta

O Claude vai testar todas as credenciais automaticamente no início do comando e avisar se alguma estiver faltando.

Clonar o template e ativar os comandos

Os comandos /swl-* ficam no repositório swl-propostas-templates. Para que o Claude Code os reconheça de qualquer diretório, você precisa clonar o repo e criar um link simbólico da pasta de comandos para o diretório global do Claude.

1. Clonar o repositório

git clone git@github.com:Base2-Tecnologia/swl-propostas-templates.git ~/src/swl-propostas-templates

2. Criar o link simbólico

O Claude Code carrega comandos da pasta ~/.claude/commands/. Crie um link simbólico apontando para a pasta de comandos do repositório:

# Garante que a pasta ~/.claude existe
mkdir -p ~/.claude

# Cria o link simbólico
ln -s ~/src/swl-propostas-templates/.claude/commands ~/.claude/commands

ls ~/.claude/commands 2>/dev/null && echo "já existe" || echo "não existe"

3. Verificar

ls -la ~/.claude/commands

Deve mostrar algo como:

lrwxr-xr-x  1 hbarros  staff  54 27 mai 11:00 /Users/hbarros/.claude/commands -> /Users/hbarros/src/swl-propostas-templates/.claude/commands

Abra o Claude Code e confirme que os comandos aparecem ao digitar /swl.

Manter atualizado

Como é um link simbólico, qualquer atualização no repositório template reflete automaticamente nos comandos disponíveis no Claude. Basta fazer git pull na pasta do template para receber novos comandos ou correções:

git -C ~/src/swl-propostas-templates pull

/swl-init-proposta

Cria uma nova proposta do zero — ou retoma uma proposta que foi inicializada mas não concluída.

Como usar

Abra o Claude Code em qualquer diretório e digite:

/swl-init-proposta

O Claude vai fazer as perguntas necessárias. Você também pode passar o código da proposta diretamente para retomar uma existente:

/swl-init-proposta direcional-26-BL-039
/swl-init-proposta 26-BL-039

O que o comando faz (nova proposta)

Resultado

Ao final você recebe os links de tudo que foi criado:

Proposta inicializada.

  Empresa:       Base/labs
  Número:        26-BL-039
  Cliente:       Direcional
  Template:      Desenvolvimento de Software

  Repo GitHub:   https://github.com/Base2-Tecnologia/proposta-direcional-26-BL-039
  Clone local:   ~/src/propostas/proposta-direcional-26-BL-039/
  Pasta Drive:   https://drive.google.com/drive/folders/...
  Deal HubSpot:  https://app.hubspot.com/contacts/.../record/0-3/...

/swl-montar-proposta

Escreve o conteúdo das seções da proposta. O Claude faz perguntas sobre o cliente e o projeto, e você responde — ele cuida de gerar o texto profissional.

Como usar

/swl-montar-proposta
/swl-montar-proposta 26-BL-039

O que o comando faz

Perguntas por template

Desenvolvimento de Software

Alocação de Profissionais

Editar seções manualmente

As seções ficam em ~/src/propostas/proposta-<cliente>-<numero>/sections/. Cada arquivo é um Markdown simples que você pode editar no VS Code ou qualquer editor de texto. Depois de editar, rode /swl-publicar-proposta para atualizar a versão online.

/swl-publicar-proposta

Builda a proposta e publica online com senha de acesso. O link gerado é o que você envia ao cliente.

Como usar

/swl-publicar-proposta
/swl-publicar-proposta 26-BL-039

O que o comando faz

Resultado

Proposta publicada.

  Cliente:   Direcional
  Número:    26-BL-039
  URL:       https://propostas.baselabs.com.br/direcional/26-BL-039/
  Acesso:    usuário: direcional · senha: xK7mR2pQ
  Validade:  24/06/2026

  Deal HubSpot atualizado com o link.

Republicar uma proposta

Para atualizar uma proposta já publicada (após corrigir o conteúdo), basta rodar o comando novamente:

/swl-publicar-proposta 26-BL-039

O Claude vai sobreescrever os arquivos no R2. A URL e a senha permanecem as mesmas.

Estrutura do repositório de uma proposta

Após o /swl-init-proposta, o repositório da proposta tem esta estrutura:

proposta-direcional-26-BL-039/
├── sections/              ← Conteúdo da proposta (você edita aqui)
│   ├── capa.md
│   ├── escopo.md
│   ├── casos-uso.md
│   ├── proposta-tecnica.md
│   ├── cronograma.md
│   ├── investimento.md
│   ├── metodologia.md
│   ├── premissas.md
│   ├── racional.md
│   ├── quem-somos.md
│   └── ratecard.md
│
├── proposta.env           ← Configuração da proposta (não edite manualmente)
├── CLAUDE.md              ← Contexto para o Claude (links do Drive, HubSpot, etc.)
├── README.md              ← Link da pasta Drive com briefing
│
├── src/                   ← Código Astro (não precisa mexer)
├── utils/                 ← Scripts de build (não precisa mexer)
└── package.json

O arquivo proposta.env

Gerado automaticamente. Contém todas as configurações da proposta:

CLIENTE=Direcional
MARCA=baselabs
TEMPLATE=desenvolvimento-software
PROPOSTA_NUMERO=26-BL-039
PROPOSTA_DATA=2026-05-26
PROPOSTA_VALIDADE_DIAS=30
HUBSPOT_DEAL_ID=60650951826
DRIVE_FOLDER_ID=13BHrhrO4YserrOk8H8u7Sip0qBfnq8OJ
PROPOSTA_BASE_PATH=/direcional/26-BL-039/

As seções em Markdown

Cada arquivo em sections/ tem um cabeçalho (frontmatter) e o conteúdo em Markdown:

---
title: Escopo
subtitle: O que o módulo de pagamentos entrega na v1
---

O módulo de pagamentos da Direcional cobre o ciclo completo...

## Processos cobertos

- **Criação de transações** — ...
- **Aprovação** — fluxo configurável...

Estrutura do repositório template

O swl-propostas-templates é o repositório central do time — é a partir dele que cada proposta é criada. Entender sua organização ajuda quando você precisa adicionar um template, ajustar a identidade visual de uma marca ou corrigir algo no engine de build.

swl-propostas-templates/
├── brands/                   ← tokens e seções por marca
├── templates/                ← receitas de tipos de proposta
├── src/astro/                ← engine Astro compartilhada
├── utils/bin/                ← scripts CLI (build, PDF, publicação)
└── workers/propostas-auth/   ← Cloudflare Worker (auth + serve R2)

brands/

Uma subpasta por marca. Cada marca tem:

Essas seções de marca têm prioridade: em build, elas sobrescrevem as seeds do template. Seções como quem-somos e ratecard não ficam nos templates — são brand-owned.

templates/

Hoje existem três templates: desenvolvimento-software, alocacao-profissionais e crowdtasking. Cada um contém:

Resolução de seções em build: o engine monta uma coleção única a partir de duas fontes, nessa ordem de prioridade:

src/astro/

Engine de renderização compartilhada por todas as marcas e templates:

Há duas rotas com comportamentos distintos: / gera o site interativo com TOC sticky; /pdf/ gera o layout A4 que o Playwright converte em PDF.

utils/bin/

Scripts que orquestram o ciclo de vida de uma proposta:

npm run build -- --proposta=acme
npm run build -- --template=desenvolvimento-software

workers/propostas-auth/

Cloudflare Worker que serve como gateway de acesso às propostas publicadas:

• Recebe requests em propostas.baselabs.com.br
• Verifica senha via KV (AUTH_KV)
• Serve arquivos estáticos do R2 bucket propostas
• Envia notificação de acesso por e-mail

Marcas

Quatro marcas emitem propostas. Cada uma tem pipeline HubSpot, prefixo de número e identidade visual próprios:

Banco de dados (CRM)

O CRM do grupo (oportunidades, contatos, empresas, leads, tarefas, propostas) vive em um banco PostgreSQL no Supabase — projeto BaseGo CRM. Ele substitui as planilhas. Você acessa o banco diretamente pelo Claude Code ou Claude Cowork, conversando em português: o Claude traduz seu pedido em SQL e executa.

1. Pegar sua credencial

Cada pessoa tem um usuário e senha próprios (para o banco registrar quem fez cada alteração). Peça a sua ao Hugo — ele entrega por canal seguro (gerenciador de senhas ou mensagem direta). Você vai receber:

• Usuário — no formato crm_seu_nome.qeocffkayfgstlyoeltr (o sufixo .qeocffkayfgstlyoeltr identifica o projeto no pooler e é obrigatório)
• Senha

Os demais dados de conexão são iguais para todos:

2. Configurar o MCP de Postgres no Claude

O acesso é feito por um MCP server de Postgres apontando para a sua connection string. A URL vai como argumento do server (não em variável de ambiente — PG_URL é ignorada e causa erro Invalid URL). Rode este comando uma vez (substitua USUARIO.qeocffkayfgstlyoeltr e SENHA pelos que o Hugo te passou):

claude mcp add crm-db \
  -- npx -y @modelcontextprotocol/server-postgres \
  "postgresql://USUARIO.qeocffkayfgstlyoeltr:SENHA@aws-1-us-east-2.pooler.supabase.com:5432/postgres?sslmode=no-verify"

Como alternativa, você pode editar o arquivo .mcp.json (na raiz do projeto ou em ~/.claude.json) manualmente:

{
  "mcpServers": {
    "crm-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://USUARIO.qeocffkayfgstlyoeltr:SENHA@aws-1-us-east-2.pooler.supabase.com:5432/postgres?sslmode=no-verify"
      ]
    }
  }
}

3. Usar

Depois de configurar, abra o Claude e fale naturalmente. Exemplos:

Liste os 10 deals mais recentes da Base/labs com valor acima de 50 mil.

Crie um contato: Maria Silva, maria@acme.com, empresa Acme.

Mude o estágio do deal 26-BL-040 para "Negociação".

Quantas tarefas em aberto o Tales tem?

O Claude monta o SQL, mostra o que vai rodar e executa contra o banco com a sua credencial.

Tabelas de configuração são só leitura

As tabelas que definem a configuração do CRM — brands (marcas), pipelines, deal_stages (estágios), industries, lead_statuses, marketing_statuses — você consegue consultar, mas não alterar. Mudar um estágio de pipeline afeta todo mundo, então isso fica restrito aos administradores. Se precisar de um novo estágio ou marca, fale com o Hugo.

Auditoria

Toda inserção, alteração e remoção fica registrada em uma tabela de auditoria, identificando o usuário, o que mudou e quando. Isso é automático — você não precisa fazer nada. Serve para reconstruir o histórico se algo for alterado por engano.

Para administradores restrito

O MCP de Postgres acima permite apenas dados — de propósito, ninguém altera a estrutura do banco por engano. Quem precisa mexer na estrutura (criar/alterar tabelas e colunas, rodar migrations) usa um segundo MCP: o MCP oficial do Supabase, autenticado com um Personal Access Token (PAT) pessoal.

Os dois MCPs convivem sem conflito — são servidores independentes, com nomes e credenciais separados. No dia a dia o admin usa o crm-db (CRUD, auditado pela sua role); o MCP do Supabase fica reservado para alterações de estrutura.

1. Gere seu PAT em supabase.com/dashboard/account/tokens (é pessoal, trate como senha de admin).

2. Adicione o MCP do Supabase (substitua SEU_PAT):

claude mcp add supabase \
  --env SUPABASE_ACCESS_TOKEN="SEU_PAT" \
  -- npx -y @supabase/mcp-server-supabase@latest --project-ref=qeocffkayfgstlyoeltr

Ou via .mcp.json:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase@latest", "--project-ref=qeocffkayfgstlyoeltr"],
      "env": { "SUPABASE_ACCESS_TOKEN": "SEU_PAT" }
    }
  }
}

FAQ

Como trabalho em várias propostas ao mesmo tempo?

Cada proposta é um repositório independente. Você pode ter vários clones em ~/src/propostas/ e alternar entre eles. Os comandos /swl-* aceitam o número da proposta como argumento, então você consegue trabalhar de qualquer diretório:

/swl-montar-proposta 26-BL-039
/swl-montar-proposta 26-BL-038

Posso editar as seções no VS Code?

Sim. As seções são arquivos Markdown em sections/. Edite como quiser e depois rode /swl-publicar-proposta para publicar as alterações.

O cliente esqueceu a senha. O que faço?

Peça ao Hugo ou a quem tem acesso ao Cloudflare KV. No momento não há comando automático para redefinir senha — isso é um ponto de melhoria futuro.

Posso retomar uma proposta que parou no meio do /swl-init-proposta?

Sim. Rode:

/swl-init-proposta 26-BL-039

O Claude verifica o que já foi criado (repo, Drive, clone) e executa apenas o que está faltando.

O build falhou. O que faço?

O erro mais comum é frontmatter inválido em alguma seção. O Claude lê o erro e geralmente consegue corrigir sozinho. Se não conseguir, verifique se o YAML no cabeçalho de cada .md está correto (sem aspas faltando, por exemplo).

Onde ficam os documentos do cliente?

Sempre no Google Drive, na pasta swl-clientes/<Letra>/<cliente>/<numero>/briefing/. O link está no README.md do repositório da proposta. Nunca commite documentos do cliente no Git.

Como instalo o Claude Code no Windows sem usar WSL?

É possível instalar diretamente no Windows com o Node.js para Windows, mas não é recomendado — vários scripts do projeto usam comandos Unix que não funcionam no CMD/PowerShell. O WSL2 resolve isso com muito menos trabalho.

O comando /swl-init-proposta não aparece. O que está errado?

Os comandos /swl-* precisam estar na pasta .claude/commands/ do repositório template. Certifique-se de que você abriu o Claude Code dentro da pasta swl-propostas-templates ou que os comandos foram copiados para a pasta de usuário. Fale com o Hugo se precisar de ajuda.