Shark AI: AI-Native Collaborative Development Tool powered by StackSpot AI and BMAD Method
npm install shark-ai``
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⣾⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣀⣀⣀⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣰⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⢠⣾⣿⣏⠉⠉⠉⠉⠉⠉⢡⣶⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⠻⢿⣿⣿⣿⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣤⡄⠀
⠈⣿⣿⣿⣿⣦⣽⣦⡀⠀⠀⠛⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⢧⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⣿⣿⠀⠀
⠀⠘⢿⣿⣿⣿⣿⣿⣿⣦⣄⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣾⣿⣿⠇⠀⠀
⠀⠀⠈⠻⣿⣿⣿⣿⡟⢿⠻⠛⠙⠉⠋⠛⠳⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⣿⣿⣿⡟⠀⠀⠀
⠀⠀⠀⠀⠈⠙⢿⡇⣠⣤⣶⣶⣾⡉⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⣰⣰⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠠⠾⢇⠀⠀⠀⠀⠀⣴⣿⣿⣿⣿⠃⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠱⣿⣿⣿⣿⣿⣿⣦⡀⠀⠀⠀⠀⠀⠀⠀⠀⣰⣿⣿⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠐⠤⢤⣀⣀⣀⣀⣀⣀⣠⣤⣤⣤⣬⣭⣿⣿⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠈⠛⢿⣿⣿⣿⣿⣿⣶⣤⣄⣀⣀⣠⣴⣾⣿⣿⣿⣷⣤⣀⡀⠀⠀⠀⠀⠀⠀⣀⣀⣤⣾⣿⣿⣿⣿⡿⠿⠛⠛⠻⣿⣿⣿⣿⣇⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠙⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣶⣶⣤⣤⣘⡛⠿⢿⡿⠟⠛⠉⠁⠀⠀⠀⠀⠀⠈⠻⣿⣿⣿⣦⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣴⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠿⢿⣿⣿⣿⣿⣿⣶⣦⣤⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠻⣿⣿⡄⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢠⣾⣿⣿⣿⠿⠛⠉⠁⠀⠈⠉⠙⠛⠛⠻⠿⠿⠿⠿⠟⠛⠃⠀⠀⠀⠉⠉⠉⠛⠛⠛⠿⠿⠿⣶⣦⣄⡀⠀⠀⠀⠀⠀⠈⠙⠛⠂
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠠⠿⠛⠋⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀
____ _ _ _ ____ _ __ _ ___
/ ___|| | | | / \ | _ \| |/ / / \ |_ _|
\___ \| |_| |/ _ \ | |_) | ' / / _ \ | |
___) | _ / ___ \| _ <| . \ / ___ \ | |
|____/|_| |_/_/ \_\_| \_\_|\_\ /_/ \_\___|
AI-Native Collaborative Development Tool
`
Ferramenta de Desenvolvimento Colaborativo com IA
Transforme o desenvolvimento com IA em um processo estruturado e transparente



English | Português
---
Shark AI é uma ferramenta de linha de comando open-source que eleva o desenvolvimento assistido por IA a um novo patamar através de um workflow colaborativo, estruturado e persistente.
O Shark AI amplifica suas capacidades orquestrando um pipeline de agentes especializados (Business Analyst, Specification, Architect, Developer) integrados nativamente com a StackSpot AI, mantendo você sempre no controle das decisões críticas.
O coração do Shark AI é inspirado no BMAD (Business Model Agile Development) - uma metodologia estruturada para desenvolvimento ágil com IA. O Shark AI adapta os princípios do BMAD para criar um CLI que mantém o desenvolvedor no controle enquanto a IA executa o trabalho pesado.
---
) que rastreia o progresso passo a passo. Pause e retome o trabalho entre sessões sem perder contexto.$3
Acesso direto a Knowledge Sources e padrões da empresa, garantindo que o código gerado siga automaticamente as diretrizes corporativas.$3
Loops de feedback autônomos que executam builds, detectam erros e corrigem automaticamente (até 5 tentativas) antes de solicitar sua intervenção.$3
TUI (Text User Interface) com menus interativos, cores, spinners e feedback visual para uma experiência premium no terminal.$3
Pipeline completo de desenvolvimento:
`
Business Analyst → Specification → Architecture → Development
`---
🚀 Instalação
`bash
npm install -g shark-ai
`Requisitos:
- Node.js >= 20.0.0
- Conta StackSpot AI (para autenticação)
---
⚡ Quick Start
$3
`bash
shark login
`O navegador abrirá automaticamente para autenticação OAuth. Seus tokens serão armazenados de forma segura no sistema operacional.
$3
`bash
shark init
`O Shark AI perguntará:
- Qual stack você está usando? (React, Next.js, Angular)
- Novo workflow ou continuar existente?
- O que você quer construir?
$3
O Shark orquestrará automaticamente:
1. Business Analyst Agent → Entende seus requisitos e cria um briefing
2. Specification Agent → Transforma o briefing em especificação técnica
3. Architect Agent → Projeta a arquitetura da solução
4. Developer Agent → Gera o código e executa testes
Você aprova cada etapa crítica. A IA executa, você decide.
$3
Se houver erros de build ou lint, o Shark:
1. Executa o build/test automaticamente
2. Captura o erro (stderr)
3. Envia para o Developer Agent corrigir
4. Tenta novamente (até 5x)
5. Se falhar, pede sua ajuda
---
📚 Comandos Disponíveis
$3
Autentica com StackSpot AI via OAuth 2.0.`bash
shark login
`$3
Inicializa um novo workflow ou retoma um existente.`bash
shark init
`O Shark detecta automaticamente se há um workflow em andamento e oferece opções para:
- Continuar de onde parou
- Iniciar um novo workflow
- Visualizar o progresso atual
$3
Gerencia configurações globais do Shark AI.`bash
shark config
`Abre um menu interativo para configurar:
- Tokens de API
- Preferências de interface
- Configurações padrão de projeto
$3
Inicia uma sessão interativa com o Business Analyst Agent.`bash
shark ba
`Use quando quiser:
- Refinar requisitos de negócio
- Criar briefings detalhados
- Validar critérios de aceitação
$3
Inicia o Specification Agent para criar especificações técnicas.`bash
shark spec [--briefing ]
`Opções:
-
--briefing: Caminho para arquivo de briefing existente
- --id: ID customizado do agente$3
Ativa o Developer Agent para geração de código.`bash
shark dev
`$3
Executa o QA Agent para testes e validação.`bash
shark qa
`$3
Escaneia o projeto atual e analisa a estrutura.`bash
shark scan
`---
🎯 Casos de Uso
$3
Situação: Precisa criar um módulo de extrato financeiro complexo mas foi interrompido para uma reunião.Com Shark AI:
1. Inicia
shark init, descreve o módulo
2. Aprova a arquitetura proposta pelo Architect Agent
3. Sai para a reunião (fecha o terminal)
4. Volta 2 horas depois, roda shark init novamente
5. Shark retoma exatamente de onde parou - zero contexto perdido
6. Developer Agent completa a implementaçãoResultado: Módulo pronto em < 1 hora de trabalho real vs 4-6 horas manual.
$3
Situação: Primeira vez otimizando performance de um dashboard.Com Shark AI:
1.
shark ba - O Business Analyst explica métricas de performance (LCP, FID)
2. shark spec - Specification Agent define alvos mensuráveis
3. Durante desenvolvimento, Auto-Healing corrige um loop infinito no useEffect
4. Julia aprende lendo os diffs e explicações da IAResultado: Feature otimizada + aprendizado real sobre Web Vitals.
$3
Situação: Garantir que toda a equipe siga novos padrões de backend.Com Shark AI:
1. Atualiza documento "Backend Standards" no StackSpot Knowledge Source
2. Não precisa avisar ninguém
3. Quando Carlos e Julia rodam Shark, os agentes consultam o Knowledge Source atualizado
4. Código gerado já nasce seguindo os novos padrões
Resultado: Compliance 100% + PRs aprovados rapidamente.
---
🏗️ Arquitetura
$3
`mermaid
graph LR
A[shark init] --> B[Business Analyst]
B --> C[Specification Agent]
C --> D[Architect Agent]
D --> E[Developer Agent]
E --> F{Build OK?}
F -->|Sim| G[✅ Concluído]
F -->|Não| H[Auto-Healing]
H --> E
`$3
O arquivo
shark-workflow.json armazena:
- Histórico de todas as decisões
- Estado atual do pipeline
- Artefatos gerados por cada agente
- Contexto da sessãoVocê pode pausar e retomar a qualquer momento.
$3
`
┌─────────────┐
│ Shark CLI │
└──────┬──────┘
│
├──► StackSpot AI API
│ (Agentes)
│
└──► Knowledge Sources
(Padrões da Empresa)
`---
🔒 Segurança
- ✅ Tokens armazenados de forma segura usando keychain do SO
- ✅ Zero vazamento de código - comunicação restrita à API StackSpot (SOC2 compliant)
- ✅ Arquivos sensíveis protegidos -
.gitignore` configurado para prevenir commit de secrets---
Contribuições são bem-vindas! Veja CONTRIBUTING.md para detalhes sobre:
- Como reportar bugs
- Como sugerir features
- Processo de Pull Request
- Coding standards
---
Veja CHANGELOG.md para histórico de versões e mudanças.
---
Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.
---
- Issues: GitHub Issues
- Discussões: GitHub Discussions
---
- BMAD Method - Inspiração metodológica
- StackSpot AI - Plataforma de agentes de IA
- Comunidade Open Source - Por tornar tudo isso possível
---
Feito com ❤️ por Miguel Arcangelo
Se o Shark AI te ajudou, considere dar uma ⭐ no projeto!