Skip to content
/ frankflow Public

FrankFlow - Production workflow framework for AI agent squads

0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

felipeggv/frankflow

BranchesTags

Repository files navigation

Frankflow AI Squad

Beads Dashboard Deploy Dashboard

Framework para criar squads de agentes IA especializados em qualquer dominio. Inclui integracao completa entre beads (operacional), ClickUp (visual/stakeholders), GitHub, CodeRabbit e Claude Code com 29 plugins habilitados.

Arquitetura

                         ┌──────────────────────┐
                         │   Squad Creator       │
                         │ /squad:create         │
                         └──────────┬───────────┘
                                    │ gera
                    ┌───────────────┼───────────────┐
                    ▼               ▼               ▼
              software-dev    accounting       (seu dominio)
                    │               │               │
                    └───────────────┴───────────────┘
                                    │
    Devs/Agentes  ──►  beads (bd CLI)  ◄──sync──►  ClickUp  ◄──  PMs/Stakeholders
                            │                          │
                        git-backed               visual dashboard
                       (operacional)            (sprints, estimativas)

Quick Start

# 1. Crie um repo a partir deste template (ou clone)
gh repo create meu-projeto --template moiraphill/frankflow-ai-squad

# 2. Abra no Codespace/devcontainer (recomendado)
#    Tudo e instalado automaticamente: beads, bv, plugins, MCPs

# 3. (Opcional) Configure variaveis no .env
cp .env.example .env
# Preencha CLICKUP_API_KEY e OPENAI_API_KEY conforme necessidade

# 4. Pronto! Use os comandos /project: no Claude Code
bd ready   # ver tasks disponiveis

Funcionalidades Principais

Squad Creator

Crie squads de agentes IA para qualquer dominio com um wizard de 6 passos:

/squad:create "Nome do Squad"   # Wizard interativo
/squad:list                     # Templates e squads gerados
/squad:generate manifest.yaml   # Gerar a partir de manifesto

Templates incluidos:

Template Dominio Roles Commands
software-dev Desenvolvimento de Software 5 14
accounting Contabilidade 4 10

Comandos do Dia a Dia

Comando O que faz
/project:iniciar BEAD_ID Busca bead, cria branch, marca in_progress
/project:enviar Push + cria PR + label in-review
/project:corrigir Le feedback do PR (CodeRabbit/CI/reviewer) e aplica correcoes
/project:testar Roda lint, testes e build
/project:status Dashboard: beads triage + grafo + git + PR
/project:triage Recomendacoes inteligentes via grafo de dependencias
/project:graph Visualizar grafo de dependencias (HTML, Mermaid)

Fluxo em 6 passos

1. Pegar task       → /project:iniciar BEAD_ID
2. Desenvolver      → Escrever codigo (com navegacao guiada)
3. Testar           → /project:testar
4. Enviar PR        → /project:enviar
5. Corrigir review  → /project:corrigir (se necessario)
6. Merge            → Aprovado? Squash and Merge no GitHub

Setup e Sync ClickUp (opcional)

Comando O que faz
/project:beads-sync Sync bidirecional beads <-> ClickUp
/project:clickup-criar "Nome" Cria projeto (List) no ClickUp
/project:clickup-popular Le docs e cria epics + tasks no ClickUp
/project:clickup-sprint planejar Organiza tasks em sprints
/project:clickup-sync Sincroniza estado ClickUp <-> local

Navegacao Guiada

Claude mostra menus contextuais em cada etapa do desenvolvimento com recomendacoes, tempos estimados e 3 niveis de automacao:

  • Piloto Automatico - Claude decide e executa tudo
  • Guiado (padrao) - Menu contextual em cada etapa
  • Manual - Usuario chama cada skill manualmente

Estrutura do Projeto

.
├── .claude/
│   ├── CLAUDE.md                      # Regras do projeto para Claude Code
│   ├── settings.json                  # 29 plugins habilitados
│   ├── commands/
│   │   ├── project/                   # 14 comandos /project:*
│   │   └── squad/                     # 3 comandos /squad:*
│   ├── rules/                         # Regras de enforcement (git, PR, commit, branch, ClickUp)
│   ├── skills/                        # Skills do projeto (10 skills)
│   └── workflows/                     # Workflows multi-step (5 workflows)
├── .devcontainer/
│   ├── Dockerfile                     # Python 3.12 + gh + build tools
│   ├── devcontainer.json              # Node 22, Docker-in-Docker, portas
│   ├── setup-beads-plugins.sh         # Instala beads, bv, plugins Claude
│   ├── setup-mcp.sh                   # Configura MCP servers
│   ├── setup-claude-memory.sh         # Configura memoria persistente
│   ├── setup-terminal.sh              # Terminal customizado
│   ├── setup-xdg-open.sh             # xdg-open para Codespaces
│   └── verify-setup.sh               # Verificacao pos-setup
├── .github/
│   ├── workflows/deploy-dashboard.yml # Deploy beads dashboard to Pages
│   └── PULL_REQUEST_TEMPLATE.md       # Template de PR
├── squads/
│   ├── core/                          # Componentes universais (incluidos em todo squad)
│   │   ├── commands/                  # iniciar, status, triage, graph
│   │   ├── rules/                     # exploration-strategy, mcp-usage
│   │   ├── skills/                    # iniciar, status
│   │   ├── workflows/                 # start-task, finish-task
│   │   ├── claude-base.md             # CLAUDE.md base
│   │   └── settings-base.json         # Settings base
│   ├── templates/                     # Templates de dominio
│   │   ├── software-dev/              # Desenvolvimento de software (14 commands, 5 rules)
│   │   └── accounting/                # Contabilidade (6 commands, 3 rules)
│   ├── catalog/                       # Catalogo de recursos
│   │   ├── plugins.yaml               # Plugins organizados por categoria
│   │   ├── mcp-servers.yaml           # MCPs disponiveis
│   │   └── roles-library.yaml         # Roles predefinidos (7 dominios)
│   └── output/                        # Squads gerados (gitignored)
├── docs/
│   └── guides/
│       ├── squad-creation.md          # Guia de criacao de squads
│       ├── template-authoring.md      # Guia de autoria de templates
│       └── tools-reference.md         # Referencia de ferramentas
├── fluxo-trabalho-scrum/              # Documentacao do workflow scrum
│   ├── 01-guia-rapido.md
│   ├── 02-workflow-completo.md
│   ├── 03-ids-configuracao.md
│   └── 04-comandos-claude.md
├── .coderabbit.yaml                   # Review automatico (PT-BR, profile: chill)
├── .env.example                       # Template de variaveis
├── AGENTS.md                          # Instrucoes para agentes IA
├── INICIO-RAPIDO.md                   # Guia de inicio rapido
└── README.md                          # Este arquivo

Ferramentas Instaladas

Devcontainer

O devcontainer inclui tudo pre-configurado:

  • Python 3.12 (base)
  • Node.js 22 (para CLIs e MCP servers)
  • GitHub CLI (gh)
  • uv (gerenciador de pacotes Python)
  • Claude Code + OpenCode + Codex + Gemini CLI (coding assistants)
  • Docker-in-Docker (para containers aninhados)

CLIs

Ferramenta Comando O que faz
beads bd Issue tracker git-backed (create, update, close, sync)
beads viewer bv / bv --robot-* Dashboard visual + triage/planning via IA

MCP Servers

Server Transporte O que faz
repomix stdio Exploracao eficiente de codebases (pack, grep, search)
docs-mcp-server HTTP (porta 6280) Indexador de documentacao com Web UI e busca semantica
beads stdio Issue tracker via MCP

docs-mcp-server roda como servico HTTP em background:

  • Web UI: http://localhost:6280 (gerenciar bibliotecas indexadas)
  • MCP: Claude Code conecta automaticamente via HTTP transport
  • Embeddings: Requer OPENAI_API_KEY no .env (opcional, melhora busca)

Plugins Claude Code (29 habilitados)

Categoria Plugins Destaques
Oficiais code-review, feature-dev Review e feature dev guiado
Compound compound-engineering Brainstorm, plan, work, review multi-agente
Beads beads Issue tracking integrado
Backend backend-development, backend-api-security, api-scaffolding, api-testing-observability Feature dev, TDD, security, API testing
Testing unit-testing, tdd-workflows Test generation, TDD red-green-refactor
Frontend javascript-typescript, full-stack-orchestration TS/JS, full-stack features
Python python-development Python best practices, packaging
DevOps cicd-automation, observability-monitoring CI/CD, monitoring
Quality code-refactoring, debugging-toolkit, security-compliance, developer-essentials Refactoring, debug, compliance
Database database-design, database-migrations Schema design, migrations
Docs code-documentation, llm-application-dev Doc generation, LLM/RAG
Git git-pr-workflows, code-review-ai Code review, PR workflows
UI/UX ui-design Design systems, accessibility, responsive
Review+ comprehensive-review, performance-testing-review Architect review, perf testing
Security security-scanning Threat modeling, STRIDE, SAST

Issue Tracking

beads (bd CLI) e a camada operacional. Issues ficam em git.

bd ready          # tasks disponiveis
bd show <id>      # detalhes da task
bd create ...     # criar nova task
bd close <id>     # marcar como feita
bd stats          # estatisticas
bv                # dashboard visual (TUI)

ClickUp e a camada visual para PMs/stakeholders. Sync via /project:beads-sync.

Dashboard visual em: https://moiraphill.github.io/frankflow-ai-squad/

Git

Branches

main (producao)
  ↑ merge (via release PR)
develop (integracao)
  ↑ squash merge (via feature PR)
feature/TASKID-descricao (trabalho)

Tipos: feature/, bugfix/, hotfix/, release/

Commits

Formato: Conventional Commits

feat: adiciona endpoint de login #abc123
fix: corrige validacao de email #abc456
chore: atualiza dependencias #xyz789
docs: documenta API de usuarios #abc123
refactor: simplifica middleware de auth #abc123

Pull Requests

  • Base: develop (nunca direto para main)
  • Titulo: tipo: descricao #TASKID
  • Merge: Squash and Merge
  • Requisitos: CI verde + CodeRabbit + 1 approval

Variaveis de Ambiente

# .env (nao committar!)
# Copie de .env.example: cp .env.example .env

# Docs MCP Server - busca semantica (opcional)
OPENAI_API_KEY=sk-proj-...

# ClickUp API - sync bidirecional (opcional)
CLICKUP_API_KEY=pk_...
CLICKUP_API_TOKEN=pk_...          # Alias para MCP adapter
CLICKUP_TEAM_ID=8403150
CLICKUP_SPACE_ID=55147424
CLICKUP_FOLDER_IA_ID=901312686022
CLICKUP_DEFAULT_LIST_ID=

Sem ClickUp configurado, os comandos funcionam normalmente com beads-only. Sem OpenAI key, docs-mcp-server funciona com busca por texto (FTS).

Documentacao

Documento Conteudo
INICIO-RAPIDO.md Guia de inicio rapido para novos devs
AGENTS.md Instrucoes para agentes IA
docs/guides/squad-creation.md Guia de criacao de squads
docs/guides/template-authoring.md Guia de autoria de templates
docs/guides/tools-reference.md Referencia de ferramentas
fluxo-trabalho-scrum/ Workflow scrum detalhado

Regras

  1. Nunca commit direto em main ou develop
  2. Sempre branch feature/TASKID-descricao (ou bugfix/, hotfix/)
  3. Sempre #TASKID nos commits
  4. Beads e a fonte operacional; ClickUp e sync opcional
  5. PRs precisam: CI verde + CodeRabbit + 1 approval humano
  6. PRs devem ter base em develop (exceto hotfixes)

Licenca

Projeto interno Vitascience.

Ultima atualizacao: 2026-02-11 | Versao: 4.1

About

FrankFlow - Production workflow framework for AI agent squads

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •  

Languages