@godrix/flow

> Context-Driven Development: Estrutura Inteligente para Desenvolvimento com IA

O @godrix/flow implementa uma metodologia de desenvolvimento baseada em contexto que estrutura cada tarefa em três fases distintas: Requisitos (Business Context), Design (Approach), e Implementação (Completion Report). Este processo garante alinhamento, rastreabilidade e foco constante na entrega de valor.

Este workflow cria um ecossistema onde humanos e IA podem colaborar com precisão e propósito.

🎯 Princípios Fundamentais

$3

Uma vez que os requisitos estão claros, um plano técnico sólido é criado. O APPROACH.md serve como o blueprint de engenharia. Ele detalha a arquitetura, design e um plano de implementação definido. Este documento é nossa referência; não muda durante a execução, garantindo que o plano permaneça como fonte única da verdade.

$3

Toda tarefa começa com uma compreensão profunda de seu propósito. O arquivo BUSINESS_CONTEXT.md é nossa fonte de verdade para requisitos, usando uma estrutura simplificada e IA-friendly com tags delimitadas para criar especificações comportamentais que são claras, testáveis e compreendidas por todos.

$3

O progresso deve ser documentado. O COMPLETION_REPORT.md é o registro formal e cronológico do trabalho realizado. Ele conecta as ações tomadas de volta às tarefas planejadas, documenta desvios e serve como prova final de que os objetivos no BUSINESS_CONTEXT.md foram atendidos.

📊 Fluxo do Processo Flow

``mermaid
flowchart TD
A[🚀 Início do Projeto] --> B[📋 Criar Task]
B --> C[📝 BUSINESS_CONTEXT.md]
C --> D[🎯 Definir Requisitos]
D --> E[📐 APPROACH.md]
E --> F[🏗️ Planejamento Técnico]
F --> G[⚡ Implementação]
G --> H[📊 COMPLETION_REPORT.md]
H --> I{✅ Objetivos
Alcançados?}
I -->|Sim| J[🎉 Task Concluída]
I -->|Não| K[🔄 Revisar APPROACH]
K --> F

subgraph "📁 Estrutura de Arquivos"
L[PROJECT_CONTEXT.md
Contexto Global]
M[AGENTS.md
Instruções para IA]
N[.flow/
Diretório do Projeto]
end

subgraph "🤖 Ferramentas MCP"
O[create_task
Criar Tasks]
P[generate_business_context
Gerar Contexto]
Q[generate_approach
Gerar Plano]
R[generate_completion_report
Gerar Relatório]
S[add_tech_instruction
Adicionar Instruções]
end

B -.-> O
C -.-> P
E -.-> Q
H -.-> R
M -.-> S

style A fill:#e1f5fe
style J fill:#c8e6c9
style I fill:#fff3e0
style K fill:#ffecb3
`

🚀 Instalação

`bash
npm install -g @godrix/flow
`

💻 Uso

$3


`bash

Criar uma task (com geração automática de conteúdo)

npx @godrix/flow

Criar uma task com tipo específico

npx @godrix/flow FEATURE_AUTH --type feature
npx @godrix/flow BUG_LOGIN_ISSUE --type bug
npx @godrix/flow IMPROVE_PERFORMANCE --type improvement
npx @godrix/flow RESEARCH_AI_INTEGRATION --type research

Criar task com templates tradicionais (sem geração automática)

npx @godrix/flow FEATURE_AUTH --type feature --no-auto-generate

Listar todas as tasks

npx @godrix/flow list

Validar estrutura de uma task

npx @godrix/flow validate FEATURE_AUTH

Inicializar projeto Flow

npx @godrix/flow init --name "Meu Projeto" --mission "Resolver problema X"

Iniciar servidor MCP para integração com IA

npx @godrix/flow mcp
`

$3

`bash

Criar uma tarefa com nome task-1234

npx @godrix/flow task-1234

Criar uma tarefa de feature

npx @godrix/flow FEATURE_AUTH --type feature

Criar uma tarefa de correção de bug

npx @godrix/flow BUG_LOGIN_ISSUE --type bug

Criar uma tarefa de melhoria

npx @godrix/flow IMPROVE_PERFORMANCE --type improvement
`

📁 Estrutura Criada

O comando cria uma estrutura organizada no diretório atual:

$3

- AGENTS.md - Instruções para IA (criado na raiz do projeto por padrão)
- .flow/PROJECT_CONTEXT.md - Contexto do projeto (criado na primeira execução)

$3

- APPROACH.md - O blueprint técnico imutável
- BUSINESS_CONTEXT.md - Os requisitos de negócio e critérios de aceitação
- COMPLETION_REPORT.md - O relatório formal do trabalho realizado

🏗️ Estrutura de Pastas

`
seu-projeto/
├── AGENTS.md # Arquivo global - instruções para IA (raiz)
└── .flow/
├── PROJECT_CONTEXT.md # Arquivo global - contexto do projeto
├── 00_task-1234/ # Tarefa específica
│ ├── APPROACH.md
│ ├── BUSINESS_CONTEXT.md
│ └── COMPLETION_REPORT.md
├── 01_FEATURE_AUTH/ # Outra tarefa
│ ├── APPROACH.md
│ ├── BUSINESS_CONTEXT.md
│ └── COMPLETION_REPORT.md
└── 02_BUG_LOGIN_ISSUE/ # Mais uma tarefa
├── APPROACH.md
├── BUSINESS_CONTEXT.md
└── COMPLETION_REPORT.md
`

🔄 Fluxo de Desenvolvimento

$3


Cada XX_nome-da-tarefa representa uma tarefa específica e isolada. A IA trabalha APENAS com os arquivos da tarefa atual, ignorando outras tarefas existentes, a menos que explicitamente referenciadas.

$3

- Contexto Global: PROJECT_CONTEXT.md fornece contexto geral do projeto
- Contexto Específico: Cada tarefa tem seu próprio contexto isolado
- Rastreabilidade: Todas as ações são documentadas e rastreáveis

$3

- Approach: Plano técnico imutável
- Business Context: Requisitos funcionais claros
- Completion Report: Evidência do trabalho realizado

🤖 Integração com IA

$3

O Flow agora gera automaticamente conteúdo inteligente para todos os arquivos de task:

- Conteúdo Contextualizado: Baseado no nome da task, descrição e tipo
- Templates IA-Friendly: Estrutura com tags delimitadas para fácil compreensão
- Preenchimento Inteligente: Parâmetros específicos preenchem tags correspondentes
- Flexibilidade: Use geração automática ou templates tradicionais

$3

O Flow implementa um servidor MCP que permite integração direta com assistentes de IA:

#### Ferramentas Disponíveis via MCP:

Fase 1 - Core Features:
- init_flow_project: Inicializar novo projeto Flow
- create_task: Criar tasks com templates estruturados
- list_tasks: Listar todas as tasks do projeto
- validate_task: Validar estrutura de tasks específicas
- get_task_info: Obter informações detalhadas de tasks
- get_project_status: Estatísticas gerais do projeto
- customize_agents: Personalizar AGENTS.md automaticamente baseado na análise do projeto
- add_tech_instruction: Adicionar instruções técnicas personalizadas nas seções de desenvolvimento e PR

Fase 2 - AI Integration:
- generate_business_context: Gerar BUSINESS_CONTEXT.md com preenchimento automático de tags
- generate_approach: Gerar APPROACH.md baseado no contexto
- generate_completion_report: Gerar COMPLETION_REPORT.md automaticamente
- analyze_codebase: Analisar estrutura e dependências do projeto
- update_project_context: Atualizar PROJECT_CONTEXT.md com novas informações

#### Parâmetros Específicos para generate_business_context:
`typescript
{
taskName: string, // Nome da task
description: string, // Descrição geral

// Tags específicas (opcionais):
context: string, // →
businessValue: string, // →
validationRules: string, // →
businessLogic: string, // →
dataConstraints: string, // →
positiveScenario: string, // →
negativeScenario: string, // →
edgeCaseScenario: string, // →
functionalCriteria: string, // →
nonFunctionalCriteria: string, // →
apiEndpoints: string, // →
externalServices: string, // →
loggingRequirements: string, // →
analyticsRequirements: string, // →

// Metadados:
priority: string, // → {{PRIORITY}}
estimate: string, // → {{ESTIMATE}}
stakeholder: string, // → {{STAKEHOLDER}}
deadline: string, // → {{DEADLINE}}
responsible: string, // → {{RESPONSIBLE}}
}
`

#### Configuração Rápida:
`json
{
"mcpServers": {
"flow": {
"command": "npx",
"args": ["@godrix/flow", "mcp"]
}
}
}
`

#### Exemplo de Workflow Completo com IA:

Para Novos Projetos:
`
1. IA: "Inicialize um novo projeto Flow para e-commerce"
→ init_flow_project() - Cria estrutura completa

2. IA: "Crie uma task para implementar autenticação"
→ create_task("FEATURE_AUTH", "feature") - Cria estrutura

3. IA: "Gere o BUSINESS_CONTEXT baseado na descrição"
→ generate_business_context() - Cria requisitos estruturados

4. IA: "Gere o APPROACH baseado no contexto"
→ generate_approach() - Cria plano técnico

5. IA: "Após implementar, gere o COMPLETION_REPORT"
→ generate_completion_report() - Documenta conclusão

6. IA: "Valide a qualidade da task"
→ validate_task() - Verifica estrutura
`

Para Projetos Existentes:
`
1. IA: "Analise o codebase do projeto"
→ analyze_codebase() - Entende estrutura e tecnologias

2. IA: "Atualize o contexto do projeto com as tecnologias encontradas"
→ update_project_context() - Mantém contexto global atualizado

3. IA: "Crie uma task para implementar autenticação"
→ create_task("FEATURE_AUTH", "feature") - Cria estrutura

4. IA: "Gere o BUSINESS_CONTEXT baseado na descrição"
→ generate_business_context() - Cria requisitos estruturados

5. IA: "Gere o APPROACH baseado no contexto"
→ generate_approach() - Cria plano técnico

6. IA: "Após implementar, gere o COMPLETION_REPORT"
→ generate_completion_report() - Documenta conclusão

7. IA: "Valide a qualidade da task"
→ validate_task() - Verifica estrutura
`

#### Benefícios da Integração MCP:
- Automação completa do ciclo de desenvolvimento
- Documentação automática de alta qualidade
- Análise inteligente do codebase
- Templates personalizados baseados em contexto
- Validação automática de qualidade

$3

- Prompts estruturados seguindo melhores práticas
- Contexto claro para cada tipo de arquivo
- Instruções específicas para diferentes cenários
- Rastreabilidade completa de todas as ações

$3

- Role-based prompts com contexto específico
- Constraints claras sobre permissões de arquivos
- Examples práticos para diferentes situações
- Quality gates para validação de entregas

🚀 Comandos CLI

$3

`bash

Criar uma nova task

flow [--type feature|bug|improvement|research]

Listar todas as tasks

flow list

Validar estrutura de uma task

flow validate

Inicializar projeto Flow

flow init [--name ] [--mission ] [--agents-scoped]

Iniciar servidor MCP para IA

flow mcp
`

$3

Modo Padrão (Recomendado):
`bash


Cria AGENTS.md na raiz do projeto


flow init --name "Meu Projeto" --mission "Resolver problema X"
`

Modo Agents-Scoped (Legacy):
`bash


Cria AGENTS.md dentro de .flow/ (comportamento anterior)


flow init --agents-scoped
`

$3

- --name : Nome do projeto
- --mission : Declaração de missão
- --agents-scoped: Cria AGENTS.md dentro de .flow/ (modo legacy)

$3

- ✅ Visibilidade imediata: IAs encontram instruções na raiz
- ✅ Padronização: Todos os projetos Flow seguem a mesma estrutura
- ✅ Facilidade: Não precisa navegar até .flow/
- ✅ Convenção: Segue padrões como README.md, CONTRIBUTING.md

🛠️ Desenvolvimento

`bash


Instalar dependências

npm install

Compilar projeto

npm run build

Testar localmente

npm run dev task-1234
`

📋 Templates Incluídos

$3

Instruções completas para IA com:
- Workflow obrigatório
- Permissões de arquivos
- Regras de isolamento por tarefa
- Boas práticas de desenvolvimento

#### 🔧 Configuração Personalizada do AGENTS.md

O arquivo AGENTS.md inclui seções que devem ser personalizadas pelos desenvolvedores com informações específicas do projeto:

Seções a Personalizar:

1. 🛠️ Instruções de Desenvolvimento
- Substitua [COMANDO_DEV], [COMANDO_BUILD], [COMANDO_TEST], [COMANDO_LINT] pelos comandos reais do projeto
- Adicione regras específicas de organização de arquivos
- Inclua padrões de código específicos (ESLint, Prettier, etc.)
- Defina critérios de qualidade específicos do projeto

2. 📋 Instruções de PR
- Personalize o formato de título de PR
- Adicione verificações específicas ao checklist de commit
- Inclua critérios específicos de review do projeto

Exemplo de Personalização:

`markdown


🛠️ Instruções de Desenvolvimento

$3


- Use npm run dev para iniciar o servidor de desenvolvimento
- Use npm run build para compilar o projeto
- Use npm run test para executar testes
- Use npm run lint para verificar qualidade do código

$3

- Mantenha a estrutura .flow/ para organização de tasks
- Use nomes descritivos para tasks (ex: 01_FEATURE_AUTH, 02_BUG_LOGIN_ISSUE)
- Siga o padrão de templates IA-friendly com tags delimitadas
- Regras específicas: Use TypeScript para todos os arquivos .ts
- Organização: Mantenha componentes em /src/components/

$3

- Sempre documente mudanças no COMPLETION_REPORT.md
- Mantenha rastreabilidade entre código e documentação
- Valide critérios de aceitação antes de considerar completo
- Padrões específicos: Use ESLint com regras Airbnb, Prettier para formatação

$3

- Execute testes antes de cada commit
- Mantenha cobertura de testes mínima de 80%
- Use linting para manter consistência de código
- Valide funcionalidades contra BUSINESS_CONTEXT.md
- Critérios específicos: Todos os componentes devem ter testes unitários
`

Como Personalizar:

$3

Use a ferramenta MCP customize_agents para personalização automática:

`bash


Via MCP (recomendado)


customize_agents({
workingDirectory: "/path/to/your/project",
forceUpdate: false,
preserveCustomizations: true
})
`

O que a ferramenta faz automaticamente:
- 🔍 Analisa o projeto (package.json, lock files, configs)
- 📦 Detecta package manager (npm, yarn, pnpm)
- 🛠️ Identifica frameworks (React, Vue, Angular, etc.)
- 🔧 Detecta ferramentas (TypeScript, ESLint, Jest, etc.)
- ⚙️ Personaliza comandos baseado no package manager
- 📝 Mantém regras do Flow intactas (só altera seções técnicas)

$3

Use a ferramenta MCP add_tech_instruction para adicionar instruções técnicas específicas:

`bash


Via MCP


add_tech_instruction({
instruction: "Use 'pnpm dlx turbo run dev' para iniciar o servidor de desenvolvimento",
section: "development", // ou "pr" ou "both"
workingDirectory: "/path/to/your/project"
})
`

O que esta ferramenta faz:
- 📝 Adiciona instruções personalizadas com timestamp
- 🎯 Permite especificar seção (desenvolvimento, PR, ou ambas)
- 📊 Mantém rastreabilidade das instruções adicionadas
- 🔒 Não modifica as regras do fluxo Flow

$3

1. Edite o arquivo AGENTS.md` na raiz do seu projeto
2. Substitua os placeholders pelos comandos e regras específicos
3. Adicione seções personalizadas conforme necessário
4. Mantenha a estrutura base para compatibilidade com IA
5. Teste a configuração criando uma task de exemplo

$3

Contexto global do projeto com:
- Missão e objetivos
- Stack tecnológico
- Padrões de desenvolvimento
- Métricas de sucesso

$3

Requisitos funcionais com:
- User stories
- Cenários de teste simplificados
- Critérios de aceitação
- Regras de negócio
- Integrações e APIs
- Logs e Analytics

$3

Plano técnico com:
- Arquitetura da solução
- Modelos de dados
- Contratos de API
- Estratégia de testes

$3

Relatório de conclusão com:
- Resumo executivo
- Log cronológico
- Validação de critérios
- Métricas de qualidade

🎯 Benefícios

$3

- Estrutura clara para organizar tarefas
- Contexto preservado entre sessões
- Rastreabilidade completa do progresso
- Padrões consistentes em todo o projeto

$3

- Instruções claras e específicas
- Contexto isolado por tarefa
- Prompts otimizados para melhor compreensão
- Workflow estruturado para execução eficiente

$3

- Colaboração eficiente entre humanos e IA
- Documentação automática do progresso
- Padrões uniformes de desenvolvimento
- Qualidade consistente nas entregas

🔗 Links Úteis

- Documentação Completa
- Exemplos de Uso
- Contribuindo
- Changelog

📄 Licença

MIT License - veja LICENSE para detalhes.

---

Desenvolvido com ❤️ para melhorar a colaboração entre humanos e IA no desenvolvimento de software.

👨‍💻🤝🤖 "A humanidade é uma coisa boa; a IA é apenas uma extensão dela."