squidy 1.0.2
Setup inteligente para projetos com Agentes de IA
Requires Python: >=3.8

# 🦑 Squidy - Setup Inteligente para Projetos com Agentes de IA

<div align="center">

[![Version](https://img.shields.io/badge/version-1.0.2-blue.svg)](https://github.com/seomarc/squidy)
[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

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

[Instalação](#instalação) • [Como funciona](#como-funciona) • [Documentação](https://squidy.run) • [Contribuir](#contribuir)

</div>

## 😤 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):

```bash
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):

```bash
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):

```bash
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

```bash
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](CONTRIBUTING.md).

## 📄 Licença

MIT License - livre para usar, modificar e distribuir.

---

**Feito com 🦑 para devs que cansaram de perder contexto com IA**
# squidy