squidy 1.0.2

Setup inteligente para projetos com Agentes de IA

🦑 Squidy - Setup Inteligente para Projetos com Agentes de IA

Pare de perder contexto com seu Agente de IA. Configure projetos profissionais em 2 minutos.

Instalação • Como funciona • Documentação • Contribuir

😤 O Problema que Resolvemos

Você usa Claude, ChatGPT ou Cursor para programar, mas:

• 🤯 A IA esquece tudo na próxima conversa (perda de contexto)
• 📝 Você reescreve os mesmos requisitos toda semana
• 🎨 O agente fica "criativo" e muda sua arquitetura sem avisar
• 📂 Seu projeto vira bagunça porque ninguém documenta nada
• ⏱️ Gasta 30 min configurando prompt antes de começar a codar

O Squidy resolve isso em 2 minutos.

🎯 O que é o Squidy?

O Squidy é um instalador CLI que cria automaticamente a estrutura de governança para seus projetos com Agentes de IA (Claude, GPT-4, Cursor, etc).

Em vez de você digitar 20 mensagens explicando seu projeto toda vez que abre o chat, o Squidy:

1. 🎤 Entrevista você com 5 perguntas inteligentes
2. 🧠 Usa IA para entender seu stack e regras
3. 📋 Gera 10 arquivos de documentação que seu agente DEVE ler antes de começar
4. 🔒 Cria um "contrato" entre você e a IA: regras, proibições, definição de pronto

Resultado: Sua IA nunca mais perde o contexto ou sai do escopo.

🚀 Instalação

Recomendado — via pipx (funciona no macOS, Linux e WSL sem conflitos):

pipx install squidy
squidy

Não tem pipx? Instale com: pip install pipx ou brew install pipx (macOS)

Alternativa — pip em venv (Windows / ambientes sem pipx):

python3 -m venv .venv && source .venv/bin/activate  # Linux/macOS
# ou: python -m venv .venv && .venv\Scripts\activate  (Windows)
pip install squidy
squidy

Para desenvolvedores (clone do repositório):

git clone https://github.com/seomarc/squidy.git
cd squidy
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python3 -m squidy

🎮 Como usar (2 minutos)

$ python3 -m squidy

  1  🦑 Nova instalação com IA
  2  📝 Instalação manual (offline)

  › 1

  🔑 Informe a API key (não aparece na tela)...
  ✓ Conectado ao OpenAI

  🤖 Agente: Me conte sobre o projeto.
     Você: API REST para delivery com Node e PostgreSQL

  🤖 Agente: Qual método de autenticação?
     Você: JWT

  Caminho do projeto: /home/user/meu-projeto

  🦑 10 arquivos gerados em /home/user/meu-projeto

Diga ao seu agente: "Acesse o arquivo readme-agent.md e obrigatoriamente siga todo o ritual"

Ele entenderá o contexto completo e nunca mais sairá do escopo.

✨ Por que devs usam o Squidy?

Sem Squidy	Com Squidy
IA esquece o projeto na próxima sessão	✅ Contexto preservado entre conversas
Agente propõe soluções fora do escopo	✅ Regras claras (o que pode/não pode fazer)
Você repete os mesmos requisitos	✅ Documentação gerada automaticamente
Código sem padrão	✅ Stack definida, convenções estabelecidas
Perde 30 min no setup	✅ Pronto em 2 minutos

🏗️ O que ele cria?

O Squidy gera uma estrutura de governança completa que obriga seu agente de IA a:

• 📖 Ler o contexto antes de qualquer ação (nunca mais esquece)
• 🚫 Respeitar proibições (ex: "Nunca use mock em produção")
• ✅ Seguir Definition of Done (critérios objetivos de pronto)
• 📝 Documentar no diário cada ação (rastreabilidade total)

Os 10 arquivos gerados:

seu-projeto/
├── readme-agent.md          # 🤖 Imersão completa — diga ao agente para ler isso
├── diario/                  # 📅 Log automático de decisões
└── doc/
    ├── AGENT.md             # 🎯 Referência rápida (tipo, missão, stack, DoD)
    ├── constituicao.md      # ⚖️  Regras imutáveis (o que NUNCA fazer)
    ├── oraculo.md           # 🧙 Decisões de arquitetura (ADRs)
    ├── politicas.md         # 📋 Stack tecnológica e convenções
    ├── kanban.md            # 📊 Gestão de tarefas (To Do → Done)
    ├── emergencia.md        # 🚨 Registro de bloqueios críticos
    ├── indice-diario.md     # 📑 Índice do histórico
    └── contexto-sessao.md   # 💾 Cache do estado atual

🔒 Segurança em primeiro lugar

• ✅ API keys são inputadas com getpass (não aparecem na tela)
• ✅ Nunca salvas em disco (apenas memória RAM)
• ✅ Memória limpa automaticamente após uso
• ✅ Modo offline disponível (funciona sem API key)

💻 Para quem é?

• 👨‍💻 Devs que usam Claude/Cursor/GitHub Copilot diariamente
• 🏗️ Arquitetos que precisam manter padrão em projetos complexos
• 🚀 Vibe coders que querem começar a codar em 2 minutos, não em 30
• 📚 Equipes que precisam de rastreabilidade de decisões de IA

🛠️ Desenvolvimento

git clone https://github.com/seomarc/squidy.git
cd squidy
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# Rodar
python3 -m squidy

# Rodar testes de smoke
python3 run_tests.py

🤝 Contribuir

Issues e PRs são bem-vindos! Leia CONTRIBUTING.md.

📄 Licença

MIT License - livre para usar, modificar e distribuir.

---

Feito com 🦑 para devs que cansaram de perder contexto com IA

squidy