SquadsCli

🚀 Orquestrador do SquadsCli para terminal, API, MCP e cockpit web.

Este projeto transforma o runtime de squads em um sistema operacional de entrega com:

🧠 runtime real do squad e dos agentes
⚙️ multiprovider e multimodelo
📁 artifacts como fonte da verdade (PRD, Tech Spec, Tasks, Review, memória)
🔎 retrieval seletivo para reduzir tokens e melhorar consistência
🛰️ server HTTP para integrações
🤖 MCP para clientes agent-native
🖥️ cockpit web inicial
🎬 workflow universal de vídeo para qualquer editor

O que ele faz

executa qualquer squad disponivel no workspace por CLI
gera PRD, Tech Spec, Tasks e Review por workflow
mantém memória incremental por feature
escolhe provider e model explicitamente por comando
permite escolher o squad por --squad na CLI e pela interface desktop
expõe providers, models, doctor e retrieval
publica e instala como pacote privado
planeja edição de vídeo e gera pacote para vários editores

Superfícies disponíveis

1. CLI

squadscli
listagem de squads disponíveis: squadscli squads
criação de squad mínimo: squadscli squad create meu-squad "Meu Squad"
inspeção visual de squad: squadscli squad show software-factory
modo REPL estilo terminal com estado de sessão: squadscli console
launcher desktop visual: squadscli desktop

Instalação simples

Windows em uma linha

Instala e já abre o console no diretório atual:

irm https://raw.githubusercontent.com/Juanblack1/software-factory-cli/master/scripts/install-windows.ps1 | iex

O instalador tenta nesta ordem:

usar GITHUB_PACKAGES_TOKEN se já existir
usar gh auth token se o GitHub CLI estiver logado
pedir o token interativamente se ainda faltar
se o token do gh nao tiver escopo para packages, ele pede um token manual e tenta de novo

Instala sem abrir automaticamente:

$tmp="$env:TEMP\sf-install.ps1"; iwr https://raw.githubusercontent.com/Juanblack1/software-factory-cli/master/scripts/install-windows.ps1 -OutFile $tmp; & $tmp -NoLaunch

Se preferir baixar e executar um arquivo local, use:

scripts\install-windows.cmd

Requisitos para o instalador:

Windows PowerShell
Node.js 20+
GitHub token com acesso ao pacote, apenas se gh auth token nao estiver disponivel

Windows por executavel

Baixe o instalador .exe na release mais recente:

software-factory-installer-<versao>.exe

Ao abrir o executavel, ele:

instala o pacote global do software-factory
tenta usar gh auth token se o GitHub CLI estiver logado
pede token manualmente se necessario
abre o software-factory console no fim

O executavel da release e gerado a partir do instalador PowerShell com ps2exe.

Desktop app por executavel

Baixe o launcher desktop na release mais recente:

Software Factory Desktop <versao>.exe

O launcher desktop oferece:

seletor visual de pasta
navegação lateral por views
views de Home, Providers, Workflows, Runs, Memory e Sessions
histórico local de sessões
cards clicáveis de providers, workflows e runs
composer visual estilo OpenCode para rodar o motor do software-factory
controles visíveis no composer para trocar Provider, Modelo e Effort sem sair do prompt
modal de conexão de providers com readiness, modelo ativo, binário e status
modal de modelos agrupado por provider, com busca e seleção do modelo de IA da próxima execução
view Providers com conector, status do runtime e modelos disponíveis por provider
interface moderna estilo app desktop
workspace persistido entre aberturas
execução mais segura com validação de IPC e navegação bloqueada

Tambem pode ser aberto pela CLI:

software-factory desktop --workspace .

2. Server HTTP

Suba com:

software-factory serve

Endpoints atuais:

GET /health
GET /providers
GET /models
GET /workflows
GET /workflows/:name
GET /artifacts/:name
POST /runs/dry-run
POST /stages/:stage/dry-run
POST /stages/:stage/run
POST /retrieval/dry-run
POST /video/plan/dry-run
POST /video/package
POST /video/shorts/dry-run
POST /video/shorts

3. MCP

Suba com:

software-factory mcp

Tools atuais:

software_factory.providers
software_factory.models
software_factory.run_dry
software_factory.stage_dry
software_factory.retrieval_dry
software_factory.video_plan_dry
software_factory.video_package
software_factory.video_shorts_dry
software_factory.video_shorts

4. Web

Suba o server e depois:

software-factory web

Abra:

http://127.0.0.1:4173

O cockpit inicial mostra:

health do server
providers
models
workflows

🧠 Agentes do squad e especialidades

Liderança e produto

🧭 JuanBlack: liderança de fluxo, gates, aprovações e roteamento
📌 Otavio Objetivo: descoberta, clarificação do problema e PRD
🧭 Sergio Sprint: backlog executável, ordem de entrega e handoffs
✨ Mila Melhorias: melhoria contínua e memória durável do workflow

Pesquisa e contexto

🔎 Explorer Atlas: pesquisa multimodal e contexto externo
💡 Iris Inovacao: benchmark e elevação de barra
✍️ Paula Prompt: prompts fortes, enxutos e reutilizáveis

UX, arquitetura e especificação

🧩 Yasmin UX: jornada, interface, microcopy e Pencil-first
🏗️ Sid Sistematico: system design e topologia do sistema
🧠 Tadeu Tech: tech spec, contratos e decisões técnicas

Engenharia e entrega

🔌 Mica MCP: skills, MCPs e integrações
🗄️ Davi Dados: dados, schema, migrações e acesso
⚙️ Bruno Backend: APIs, regras e domínio
🖥️ Fernanda Frontend: fluxos, telas e experiência final
☁️ Ivo Infra: ambientes, observabilidade e base operacional
🚀 Diego Deploy: rollout, monitoramento e rollback
🌿 Guto GitHub: branch, commit, PR e trilha de release
▲ Vera Vercel: publicação final e smoke de entrega

Qualidade, risco e revisão

🔐 Caio Cyber: segurança, auth e mitigação
🧪 Tito Testes: testes e smoke técnico
🧐 Aline Avalia: aderência a PRD, UX, segurança e testes
✅ Quirino Qualidade: critérios de aceite e regressão
🗣️ Livia Linguistica: português do Brasil para produto
⚡ Pericles Performance: gargalos e otimização
🧪 Clara Qualidade: consolidação final de evidências
🧐 Rita Revisa: revisão final de coerência e risco

Regras operacionais do squad

🎨 Pencil first: mudanças visuais relevantes passam pelo Pencil antes do frontend
🖼️ Gemini for images: imagens reais usam Gemini Imagen
💬 Ask when blocked: dúvida crítica pede pergunta curta, não chute
💸 Token discipline: lite reduz contexto e força tarefas menores

Instalação

Local

npm install
npm run build:all
npm install -g .

GitHub Packages

.npmrc:

@juanblack1:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=SEU_TOKEN

Instalação:

npm install -g @juanblack1/software-factory-cli

Repositório privado

npm install -g git+ssh://git@github.com/Juanblack1/software-factory-cli.git

Configuração

Exemplo de .env:

SF_PROVIDER=openai
SF_EFFORT=balanced
SF_MODEL=

OPENAI_API_KEY=
OPENAI_MODEL=gpt-5.4

OPENAI_COMPATIBLE_API_KEY=
OPENAI_COMPATIBLE_BASE_URL=
OPENAI_COMPATIBLE_MODEL=

GEMINI_API_KEY=
GEMINI_IMAGE_MODEL=imagen-4.0-generate-001

YOUTUBE_CLIENT_ID=
YOUTUBE_CLIENT_SECRET=
YOUTUBE_REFRESH_TOKEN=
YOUTUBE_OAUTH_PORT=8787

OPENCODE_COMMAND_TEMPLATE=opencode run "Execute the attached software-factory prompt file end-to-end. Ask concise questions if blocking ambiguity remains." --dir "{workspace}" --file "{promptFile}"
OPENCODE_MODEL=

CODEX_COMMAND_TEMPLATE=codex exec -
CODEX_MODEL=

CLAUDE_COMMAND_TEMPLATE=claude -p
CLAUDE_MODEL=

GEMINI_COMMAND_TEMPLATE=gemini -p "{promptFile}"
GEMINI_MODEL=

Providers e modelos

Ver providers detectados:

software-factory providers

Ver modelos ativos e sugeridos:

software-factory models
software-factory models --provider codex

Executar com provider/model explícitos:

software-factory create-prd --name onboarding --brief "Criar onboarding" --provider openai --model gpt-5.4
software-factory run --name onboarding --brief "Executar fluxo completo" --provider codex --model gpt-5.4 --effort lite
software-factory create-tasks --name onboarding --brief "Quebrar onboarding em tarefas" --provider codex --skills "task-planning,acceptance-gate"

Console TUI

Abra a interface moderna de terminal:

software-factory console

O console agora abre uma TUI simples no estilo Claude/OpenCode:

barra compacta de contexto no topo
conversa/resultado no meio
prompt fixo e claro na parte inferior
comandos curtos para trocar contexto sem sair da tela
histórico por setas
atalhos de terminal

Troca rápida dentro do console:

/compozy
/idea Validar uma ideia de produto
/prd Criar requisitos do onboarding
/techspec Desenhar arquitetura do onboarding
/tasks Quebrar em tarefas executaveis
/execute Implementar as tarefas pendentes
/review Revisar a entrega atual
/fix Corrigir issues de review
/verify Rodar verificacao final com evidencias
/squad list
/squad show
/squad create growth-lab Growth Lab
/squad next
/provider list
/provider next
/provider claude
/providers
/model list
/model sonnet
/model auto
/models

Fluxo mais simples de uso:

Escolha o squad
Rode /provider list e troque o executor, se precisar
Rode /model list e troque o modelo, se precisar
Digite o brief e pressione Enter

Fluxo Compozy-like dentro do SquadsCli:

/idea -> /prd -> /techspec -> /tasks -> /execute -> /review -> /fix -> /verify

Esses comandos usam os conceitos das skills cy-* do Compozy como orquestracao local:

cy-idea-factory: explora ideia, riscos, alternativas e debate inicial
cy-create-prd: gera requisitos de produto e criterios de aceite
cy-create-techspec: transforma requisitos em desenho tecnico
cy-create-tasks: cria tarefas pequenas, rastreaveis e verificaveis
cy-execute-task: executa tarefas com contexto e status
cy-review-round: gera rodada de review estruturada
cy-fix-reviews: corrige issues de review com verificacao
cy-final-verify: exige evidencia fresca antes de declarar pronto
cy-workflow-memory: preserva aprendizados entre runs

Gerenciar squads pela CLI:

software-factory squad list
software-factory squad show software-factory
software-factory squad create growth-lab "Growth Lab" --description "Squad para experimentos de produto" --skills "task-planning,code-review"

O squad create gera a estrutura mínima carregável:

squads/<code>/squad.yaml
squads/<code>/squad-party.csv
squads/<code>/agents/lead.agent.md
squads/<code>/pipeline/pipeline.yaml
squads/<code>/pipeline/data/compozy-orchestration.md
squads/<code>/pipeline/steps/step-*.md
squads/<code>/_memory/memories.md

Ele mantém uma sessão persistida em .software-factory/console-session.json com:

provider atual
model atual
effort atual
workflow atual
stage atual
skills focadas
modo dry-run/live

Você pode digitar um brief direto para executar com o estado atual da sessão ou usar slash commands:

/help
/status
/providers
/models
/compozy
/idea Validar uma ideia
/squads
/squad list
/squad show
/squad create growth-lab Growth Lab
/workflows
/history
/skills
/doctor
/provider codex
/model gpt-5.4
/workflow onboarding
/skills set api-design,code-review
/effort lite
/prd Criar onboarding com dashboard inicial
/run Implementar fluxo completo do onboarding
/review Revisar a implementação atual
/reset
/clear
/exit

Exemplo de sessão:

/provider claude
/model sonnet
/workflow onboarding
/skills set task-planning,acceptance-gate
Implementar fluxo completo de onboarding com foco em conversão

Atalhos da TUI:

Tab: alterna o painel direito
Up/Down: navega no histórico do input
Esc: limpa o input atual
Ctrl+L: limpa o feed visual
Ctrl+P: abre seletor de provider
Ctrl+O: abre seletor de modelo
Ctrl+J: abre seletor de squad
Ctrl+K: abre seletor de stage

As skills escolhidas por --skills ou /skills set ... entram no prompt como foco operacional da rodada, sem sobrescrever o pacote padrão do squad.

MCP em Codex e Claude

Registrar no Codex:

codex mcp add software-factory -- "%APPDATA%\npm\software-factory.cmd" mcp

Registrar no Claude Code:

claude mcp add -s user software-factory -- "%APPDATA%\npm\software-factory.cmd" mcp

Validar:

codex mcp get software-factory
claude mcp get software-factory

Depois disso, o software-factory fica disponível como servidor MCP global nas duas CLIs.

Fluxo básico

Inicializar

software-factory init --target .

Gerar PRD

software-factory create-prd --name onboarding --brief "Criar onboarding com dashboard inicial"

Gerar Tech Spec

software-factory create-techspec --name onboarding --brief "Detalhar a implementação do onboarding"

Gerar Tasks

software-factory create-tasks --name onboarding --brief "Quebrar onboarding em tarefas pequenas" --effort lite

Rodar fluxo completo

software-factory run --name onboarding --brief "Executar fluxo completo do onboarding" --provider codex --model gpt-5.4 --effort lite

Preview sem gravar artifacts:

software-factory run --name onboarding --brief "Executar fluxo completo do onboarding" --dry-run

Se quiser salvar o preview para auditoria, use --persist-dry-run. Respostas de providers agora precisam conter as seções obrigatórias do stage (PRD, Tech Spec, Task Breakdown, etc.); saída incompleta falha em vez de gravar artifacts ambíguos.

Review

software-factory run --mode review --name onboarding --brief "Revisar a implementação atual"

Autonomia

software-factory run --mode autonomy --name onboarding --brief "Consolidar próximo ciclo"

Vídeo universal

Planejar edição de vídeo para qualquer editor:

software-factory video-plan --name reels-edit --input ./video.mp4 --goal "Criar um reels com cortes rápidos, legenda e foco no gancho inicial" --editor generic --provider codex --model gpt-5.4 --effort lite

Tambem aceita URL do YouTube como fonte. O CLI usa yt-dlp para baixar o video e reaproveitar legendas quando houver:

software-factory video-plan --name youtube-reels --input "https://www.youtube.com/watch?v=VIDEO_ID" --goal "Planejar cortes para conteudo curto com foco em retencao" --editor capcut --provider codex --model gpt-5.4 --effort lite

Gerar pacote para editor:

software-factory video-package --name reels-edit --input ./video.mp4 --editor premiere
software-factory video-package --name reels-edit --input ./video.mp4 --editor davinci
software-factory video-package --name reels-edit --input ./video.mp4 --editor capcut

Gerar highlights e transformar em shorts com manifesto + script ffmpeg:

software-factory video-shorts --name youtube-shorts --input "https://www.youtube.com/watch?v=VIDEO_ID" --goal "Separar os melhores momentos em shorts independentes" --count 5 --min-seconds 20 --max-seconds 45 --editor generic --provider codex --model gpt-5.4

Para renderizar automaticamente os cortes base com ffmpeg, adicione --materialize:

software-factory video-shorts --name youtube-shorts --input "https://www.youtube.com/watch?v=VIDEO_ID" --goal "Separar os melhores momentos em shorts independentes" --count 5 --materialize --editor generic --provider codex --model gpt-5.4

Se o video for local e voce ja tiver transcript/legenda, informe --transcript-file (.txt, .srt ou .vtt) para a IA localizar os highlights com mais precisao.

Conectar e publicar no YouTube

Primeiro conecte a conta com OAuth 2.0. O CLI abre o navegador, recebe o callback local e salva as credenciais em .software-factory/youtube/.

software-factory youtube-auth --client-id SEU_CLIENT_ID --client-secret SEU_CLIENT_SECRET

Depois publique qualquer video finalizado:

software-factory youtube-upload --file ./.software-factory/workflows/youtube-shorts/video/shorts/generic/rendered/01-gancho-inicial.mp4 --title "Meu short" --description "Descricao do video" --tags shorts,youtube,clips --privacy unlisted

Com thumbnail, playlist e agendamento:

software-factory youtube-upload --file ./dist/short.mp4 --title "Meu short" --description "Descricao do video" --thumbnail ./thumb.png --playlist-id PLAYLIST_ID --privacy private --publish-at 2026-04-12T15:00:00Z

Notas:

youtube-auth tambem aceita YOUTUBE_CLIENT_ID e YOUTUBE_CLIENT_SECRET via .env
youtube-upload reutiliza o refresh token salvo localmente ou YOUTUBE_REFRESH_TOKEN
para playlist e operacoes mais amplas, o CLI pede os escopos youtube.upload e youtube
para baixar videos do YouTube continua sendo necessario ter yt-dlp no PATH
para renderizar shorts automaticamente continua sendo necessario ter ffmpeg no PATH

Editores suportados:

generic
capcut
premiere
davinci
shotcut
kdenlive
final-cut

Estrutura do workflow

.software-factory/
  workflows/
    onboarding/
      _brief.md
      _prd.md
      _techspec.md
      _tasks.md
      task_01.md
      summary.md
      memory/
        MEMORY.md
        onboarding.md
      reviews/
        reviews-123456/
          summary.md
          issue_001.md

Arquitetura 2.0

Implementado hoje:

packages/core
packages/artifact-engine
packages/memory-engine
packages/squad-runtime
packages/provider-runtime
packages/retrieval
apps/server
apps/mcp
apps/web

Documentação:

docs/software-factory-2.0.md
docs/software-factory-2.0-roadmap.md

Scripts úteis

npm run build
npm run build:server
npm run build:mcp
npm run build:all
npm test
npm run check

Publicação

Por padrão, publish faz apenas preview e não inicializa git, commita, cria repo, faz push ou publica pacote:

software-factory publish --repo software-factory-cli --workspace .

Para executar de verdade, confirme explicitamente. O push só acontece com working tree limpa:

software-factory publish --repo software-factory-cli --workspace . --yes

Para criar commit durante a publicação:

software-factory publish --repo software-factory-cli --workspace . --yes --commit --commit-message "chore: update software factory cli"

Por segurança, --commit usa git add -u. Adicione --include-untracked somente se quiser incluir arquivos novos no commit.

Com GitHub Packages:

set GITHUB_PACKAGES_TOKEN=seu_token
software-factory publish --repo software-factory-cli --workspace . --yes --github-packages

Status

✅ pronto para uso real por CLI
✅ pronto para uso por HTTP server
✅ pronto para uso por MCP
✅ pronto para planejamento universal de vídeo
✅ pronto para publicação privada e GitHub Packages

O próximo salto natural é endurecer observabilidade, streaming e cockpit visual mais completo sobre o server atual.

Name		Name	Last commit message	Last commit date
Latest commit History 80 Commits
.github		.github
apps		apps
assets		assets
docs		docs
packages		packages
scripts		scripts
skills		skills
src		src
tasks		tasks
.env.example		.env.example
.gitignore		.gitignore
.npmrc.example		.npmrc.example
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

SquadsCli

O que ele faz

Superfícies disponíveis

1. CLI

Instalação simples

Windows em uma linha

Windows por executavel

Desktop app por executavel

2. Server HTTP

3. MCP

4. Web

🧠 Agentes do squad e especialidades

Liderança e produto

Pesquisa e contexto

UX, arquitetura e especificação

Engenharia e entrega

Qualidade, risco e revisão

Regras operacionais do squad

Instalação

Local

GitHub Packages

Repositório privado

Configuração

Providers e modelos

Console TUI

MCP em Codex e Claude

Fluxo básico

Inicializar

Gerar PRD

Gerar Tech Spec

Gerar Tasks

Rodar fluxo completo

Review

Autonomia

Vídeo universal

Conectar e publicar no YouTube

Estrutura do workflow

Arquitetura 2.0

Scripts úteis

Publicação

Status

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 11

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages