YARD: Orquestração por Inteligência Artificial

Devolvendo às pessoas o poder de criar

🌍 English | Português

Início Rápido · Agentes · ADE · Squads

🌐 README por idioma: EN | PT

Framework open source de orquestração de IA que devolve o controle a quem tem coragem de construir. Agentes especializados, workflows e experiência CLI First para qualquer domínio.

⚡ Comece Aqui (10 Min)

Se é sua primeira vez no Yard, siga este caminho linear:

1. Instale em um projeto novo ou existente:

# novo projeto
npx yard-core init meu-projeto

# projeto existente
cd seu-projeto
npx yard-core install

2. Escolha sua IDE/CLI e o caminho de ativação:
   • Claude Code: /agent-name
   • Gemini CLI: /yard-menu → /yard-<agent>
   • Codex CLI: /skills → yard-<agent-id>
   • Cursor/Copilot/AntiGravity: siga os limites e workarounds em docs/ide-integration.md
3. Ative 1 agente e confirme o greeting.
4. Rode 1 comando inicial (*help ou equivalente) para validar first-value.

Definição de first-value (binária): ativação de agente + greeting válido + comando inicial com output útil em <= 10 minutos.

🖥️ Compatibilidade de Hooks por IDE (Realidade Yard 4.2)

Muitos recursos avançados do Yard dependem de eventos de ciclo de vida (hooks). A tabela abaixo mostra a paridade real entre IDEs/plataformas:

| IDE/CLI | Paridade de Hooks vs Claude | Impacto Prático | |---|---|---| | Claude Code | Completa (referência) | Automação máxima de contexto, guardrails e auditoria | | Gemini CLI | Alta (eventos nativos) | Cobertura forte de automações pre/post tool e sessão | | Codex CLI | Parcial/limitada | Parte das automações depende de AGENTS.md, /skills, MCP e fluxo operacional | | Cursor | Sem lifecycle hooks equivalentes | Menor automação de pre/post tool; foco em regras, MCP e fluxo do agente | | GitHub Copilot | Sem lifecycle hooks equivalentes | Menor automação de sessão/tooling; foco em instruções de repositório + MCP no VS Code | | AntiGravity | Workflow-based (não hook-based) | Integração por workflows, não por eventos de hook equivalentes ao Claude |

Impactos e mitigação detalhados: docs/ide-integration.md.

🏗️ Visão Geral

Premissa Arquitetural: CLI First

O Yard segue uma hierarquia clara de prioridades:

CLI First → Observability Second → UI Third

| Camada | Prioridade | Foco | Exemplos | |---|---|---|---| | CLI | Máxima | Onde a inteligência vive. Toda execução, decisões e automação acontecem aqui. | Agentes (@dev, @qa), workflows, comandos | | Observability | Secundária | Observar e monitorar o que acontece no CLI em tempo real. | Dashboard SSE, logs, métricas, timeline | | UI | Terciária | Gestão pontual e visualizações quando necessário. | Kanban, settings, story management |

Princípios derivados:

• A CLI é a fonte da verdade — dashboards apenas observam
• Funcionalidades novas devem funcionar 100% via CLI antes de ter UI
• A UI nunca deve ser requisito para operação do sistema
• Observabilidade serve para entender o que o CLI está fazendo, não para controlá-lo

As Duas Inovações Chave do Yard

1. Planejamento Agêntico: Agentes dedicados (analyst, pm, architect) colaboram com você para criar documentos de PRD e Arquitetura detalhados e consistentes. Através de engenharia avançada de prompts e refinamento com human-in-the-loop, estes agentes de planejamento produzem especificações abrangentes que vão muito além da geração genérica de tarefas de IA.

2. Desenvolvimento Contextualizado por Engenharia: O agente sm (Scrum Master) então transforma estes planos detalhados em histórias de desenvolvimento hiperdetalhadas que contêm tudo que o agente dev precisa — contexto completo, detalhes de implementação e orientação arquitetural incorporada diretamente nos arquivos de histórias.

Esta abordagem de duas fases elimina tanto a inconsistência de planejamento quanto a perda de contexto — os maiores problemas no desenvolvimento assistido por IA. Seu agente dev abre um arquivo de história com compreensão completa do que construir, como construir e por quê.

📖 Veja o fluxo de trabalho completo no Guia do Usuário — Fase de planejamento, ciclo de desenvolvimento e todos os papéis dos agentes

📋 Pré-requisitos

• Node.js >=18.0.0 (v20+ recomendado)
• npm >=9.0.0
• GitHub CLI (opcional, necessário para colaboração em equipe)

[!TIP] Problemas de instalação? Consulte o Guia de Troubleshooting

Guias específicos por plataforma:

• Guia de Instalação para macOS
• Guia de Instalação para Windows
• Guia de Instalação para Linux

Documentação disponível em: English | Português

🗺️ Navegação Rápida

Entendendo o Fluxo de Trabalho YARD

Antes de mergulhar, revise estes diagramas críticos de fluxo de trabalho que explicam como o YARD funciona:

1. Fluxo de Planejamento (Interface Web) — Como criar documentos de PRD e Arquitetura
2. Ciclo Principal de Desenvolvimento (IDE) — Como os agentes sm, dev e qa colaboram através de arquivos de histórias

[!IMPORTANT] Estes diagramas explicam 90% da confusão sobre o fluxo YARD Agentic Agile. Entender a criação de PRD+Arquitetura e o fluxo de trabalho sm/dev/qa e como os agentes passam notas através de arquivos de histórias é essencial — e também explica por que isto NÃO é taskmaster ou apenas um simples executor de tarefas!

O que você gostaria de fazer?

• Instalar e Construir software com Equipe Ágil Full Stack de IA → Instruções de Início Rápido
• Aprender como usar o YARD → Guia completo do usuário e passo a passo
• Ver agentes IA disponíveis → Papéis especializados para sua equipe
• Explorar usos não técnicos → Escrita criativa, negócios, bem-estar, educação
• Criar meus próprios agentes IA → Construir agentes para seu domínio
• Navegar Squads prontos → Veja como criar e usar equipes de agentes IA
• Entender a arquitetura → Mergulho técnico profundo
• Reportar problemas → Bug reports e feature requests

🔄 Mantenha Sua Instalação YARD Atualizada

Mantenha-se atualizado sem esforço. Para atualizar sua instalação YARD existente:

npx yard-core@latest install

Isto vai:

• Detectar automaticamente sua instalação existente
• Atualizar apenas os arquivos que mudaram
• Criar arquivos de backup .bak para quaisquer modificações customizadas
• Preservar suas configurações específicas do projeto

Isto facilita beneficiar-se das últimas melhorias, correções de bugs e novos agentes sem perder suas customizações!

🚀 Início Rápido

Instalação via NPX (Recomendado)

Instale o YARD com um único comando:

# Criar um novo projeto com assistente interativo moderno
npx yard-core init meu-projeto

# Ou instalar em projeto existente
cd seu-projeto
npx yard-core install

# Ou usar uma versão específica
npx yard-core@latest init meu-projeto

✨ Assistente de Instalação Moderno

O YARD agora inclui uma experiência de instalação interativa de última geração, inspirada em ferramentas modernas como Vite e Next.js:

Recursos do Instalador Interativo:

| Recurso | Descrição | |---|---| | Interface Moderna | Prompts coloridos e visuais com @clack/prompts | | Validação em Tempo Real | Feedback instantâneo sobre entradas inválidas | | Indicadores de Progresso | Spinners para operações longas | | Seleção Multi-Componente | Escolha quais componentes instalar | | Escolha de Package Manager | Selecione entre npm, yarn ou pnpm | | Suporte a Cancelamento | Ctrl+C ou ESC para sair graciosamente | | Resumo de Instalação | Visualize todas as configurações antes de prosseguir | | Rastreamento de Duração | Veja quanto tempo levou a instalação |

O instalador oferece:

• Download da versão mais recente do NPM
• Assistente de instalação interativo moderno
• Configuração automática do IDE (Codex CLI, Cursor ou Claude Code)
• Configuração de todos os agentes e fluxos de trabalho YARD
• Criação dos arquivos de configuração necessários
• Inicialização do sistema de meta-agentes
• Verificações de saúde do sistema
• Suporte Cross-Platform: testado em Windows, macOS e Linux

[!NOTE] Sem clonar, sem configuração manual — apenas um comando e você está pronto para começar com uma experiência de instalação moderna e profissional.

Pré-requisitos: Node.js v18+ necessário (v20+ recomendado) | Troubleshooting

Atualizando uma Instalação Existente

Se você já tem o YARD instalado:

npx yard-core@latest install
# O instalador detectará sua instalação existente e a atualizará

⚙️ Configure Seu IDE para Desenvolvimento YARD

O YARD inclui regras pré-configuradas para IDE para melhorar sua experiência de desenvolvimento:

1. Abra as configurações do Cursor
2. Navegue até User Rules
3. Copie o conteúdo de .cursor/global-rules.md
4. Cole na seção de regras e salve

• Já configurado! O arquivo .claude/CLAUDE.md é carregado automaticamente
• Sync dedicado de agentes: npm run sync:ide:claude
• Validacao dedicada: npm run validate:claude-sync && npm run validate:claude-integration

• Integração de primeira classe no YARD 4.2 (pipeline de ativação e greeting compartilhado)
• Já configurado! O arquivo AGENTS.md na raiz é carregado automaticamente
• Opcional: sincronize agentes auxiliares com npm run sync:ide:codex
• Recomendado neste repositório: gerar e versionar skills locais com npm run sync:skills:codex
• Use npm run sync:skills:codex:global apenas fora deste projeto (para evitar duplicidade no /skills)
• Validacao dedicada: npm run validate:codex-sync && npm run validate:codex-integration
• Guardrails de skills/paths: npm run validate:codex-skills && npm run validate:paths

• Regras e agentes sincronizaveis com npm run sync:ide:gemini
• Arquivos gerados em .gemini/rules.md, .gemini/rules/YARD/agents/ e .gemini/commands/*.toml
• Hooks e settings locais no fluxo de instalacao (.gemini/hooks/ + .gemini/settings.json)
• Ativacao rapida por slash commands (/yard-menu, /yard-dev, /yard-architect, etc.)
• Validacao dedicada: npm run validate:gemini-sync && npm run validate:gemini-integration
• Paridade multi-IDE em um comando: npm run validate:parity

Estas regras fornecem reconhecimento de comandos de agentes, fluxo de trabalho dirigido por histórias, rastreamento automático de checkboxes, padrões de teste e validação, e padrões de código específicos do YARD.

Início Mais Rápido com Interface Web (2 minutos)

1. Instale o YARD: Execute npx yard-core init meu-projeto
2. Configure seu IDE: Siga as instruções de configuração para Codex CLI, Cursor ou Claude Code
3. Comece a Planejar: Ative um agente como @analyst para começar a criar seu briefing
4. Use comandos YARD: Digite *help para ver comandos disponíveis
5. Siga o fluxo: Veja o Guia do usuário para mais detalhes

🖱️ Referência de Comandos CLI

O YARD oferece uma CLI moderna e cross-platform com comandos intuitivos:

# Gerenciamento de Projeto (com assistente interativo)
npx yard-core init <nome-projeto> [opções]
  --force              Forçar criação em diretório não vazio
  --skip-install       Pular instalação de dependências npm
  --template <nome>    Usar template específico (default, minimal, enterprise)

# Instalação e Configuração (com prompts modernos)
npx yard-core install [opções]
  --force              Sobrescrever configuração existente
  --quiet              Saída mínima durante instalação
  --dry-run            Simular instalação sem modificar arquivos

# Comandos do Sistema
npx yard-core --version   Exibir versão instalada
npx yard-core --help      Exibir ajuda detalhada
npx yard-core info        Exibir informações do sistema
npx yard-core doctor      Executar diagnósticos do sistema
npx yard-core doctor --fix Corrigir problemas detectados automaticamente

# Manutenção
npx yard-core update      Atualizar para versão mais recente
npx yard-core uninstall   Remover YARD

Recursos da CLI:

| Recurso | Descrição | |---|---| | Help System Abrangente | --help em qualquer comando mostra documentação detalhada | | Validação de Entrada | Feedback imediato sobre parâmetros inválidos | | Mensagens Coloridas | Erros em vermelho, sucessos em verde, avisos em amarelo | | Cross-Platform | Funciona perfeitamente em Windows, macOS e Linux | | Suporte a Dry-Run | Teste instalações sem modificar arquivos |

💡 Exemplos de Uso

$ npx yard-core install

🚀 YARD Installation

◆ What is your project name?
│  my-awesome-project
│
◇ Which directory should we use?
│  ./my-awesome-project
│
◆ Choose components to install:
│  ● Core Framework (Required)
│  ● Agent System (Required)
│  ● Squads (optional)
│  ○ Example Projects (optional)
│
◇ Select package manager:
│  ● npm
│  ○ yarn
│  ○ pnpm
│
◆ Initialize Git repository?
│  Yes
│
◆ Install dependencies?
│  Yes
│
▸ Creating project directory...
▸ Copying framework files...
▸ Initializing Git repository...
▸ Installing dependencies (this may take a minute)...
▸ Configuring environment...
▸ Running post-installation setup...

✔ Installation completed successfully! (34.2s)

Next steps:
  cd my-awesome-project
  yard-core doctor     # Verify installation
  yard-core --help     # See available commands

# Instalação automatizada sem prompts
$ npx yard-core install --quiet --force
✔ YARD installed successfully

# Testar instalação sem modificar arquivos
$ npx yard-core install --dry-run

[DRY RUN] Would create: ./my-project/
[DRY RUN] Would copy: .yard-core/ (45 files)
[DRY RUN] Would initialize: Git repository
[DRY RUN] Would install: npm dependencies
✔ Dry run completed - no files were modified

$ npx yard-core doctor

🏥 YARD System Diagnostics

✔ Node.js version: v20.10.0 (meets requirement: >=18.0.0)
✔ npm version: 10.2.3
✔ Git installed: version 2.43.0
✔ GitHub CLI: gh 2.40.1
✔ YARD: v4.2.11

Configuration:
✔ .yard-core/ directory exists
✔ Agent files: 11 found
✔ Workflow files: 8 found
✔ Templates: 15 found

Dependencies:
✔ @clack/prompts: ^0.7.0
✔ commander: ^12.0.0
✔ execa: ^9.0.0
✔ fs-extra: ^11.0.0
✔ picocolors: ^1.0.0

✅ All checks passed! Your installation is healthy.

$ npx yard-core --help

Usage: yard-core [options] [command]

YARD: AI-Orchestrated System for Full Stack Development

Options:
  -V, --version                output the version number
  -h, --help                   display help for command

Commands:
  init <project-name>          Create new YARD project with interactive wizard
  install [options]            Install YARD in current directory
  info                         Display system information
  doctor [options]             Run system diagnostics and health checks
  help [command]               display help for command

Run 'yard-core <command> --help' for detailed information about each command.

Alternativa: Clonar e Construir

Para contribuidores ou usuários avançados que queiram modificar o código fonte:

# Clonar o repositório
git clone https://github.com/ernesto-langa/yard-core.git
cd yard-core

# Instalar dependências
npm install

# Executar o instalador
npx yard-core install

Configuração Rápida para Equipe

Para membros da equipe ingressando no projeto:

# Instalar YARD no projeto
npx yard-core@latest install

# Isto vai:
# 1. Detectar instalação existente (se houver)
# 2. Instalar/atualizar framework YARD
# 3. Configurar agentes e workflows

🌟 Além do Desenvolvimento de Software - Squads

O framework de linguagem natural do YARD funciona em QUALQUER domínio. Os Squads fornecem agentes IA especializados para escrita criativa, estratégia de negócios, saúde e bem-estar, educação e muito mais. Além disso, os Squads podem expandir o núcleo do YARD com funcionalidade específica que não é genérica para todos os casos. Veja o Guia de Squads e aprenda a criar os seus próprios!

🤖 Agentes Disponíveis

O YARD vem com 12 agentes especializados:

Agentes Meta

| Agente | Descrição | |---|---| | yard-master | Agente mestre de orquestração (inclui capacidades de desenvolvimento de framework) | | yard-orchestrator | Orquestrador de fluxo de trabalho e coordenação de equipe |

Agentes de Planejamento (Interface Web)

| Agente | Descrição | |---|---| | analyst | Especialista em análise de negócios e criação de PRD | | pm (Product Manager) | Gerente de produto e priorização | | architect | Arquiteto de sistema e design técnico | | ux-expert | Design de experiência do usuário e usabilidade |

Agentes de Desenvolvimento (IDE)

| Agente | Descrição | |---|---| | sm (Scrum Master) | Gerenciamento de sprint e criação de histórias | | dev | Desenvolvedor e implementação | | qa | Garantia de qualidade e testes | | po (Product Owner) | Gerenciamento de backlog e histórias | | data-engineer | Design de banco de dados e modelagem de dados | | devops | CI/CD, infraestrutura e operações git (autoridade exclusiva de push) |

📚 Documentação e Recursos

Guias Essenciais

• 📖 Guia do Usuário — Passo a passo completo desde a concepção até a conclusão do projeto
• 🏗️ Arquitetura Principal — Mergulho técnico profundo e design do sistema
• 🚀 Guia de Squads — Estenda o YARD para qualquer domínio além do desenvolvimento de software

Documentação Adicional

• 🤖 Guia de Squads — Crie e publique equipes de agentes IA
• 📋 Primeiros Passos — Tutorial passo a passo para iniciantes
• 🔧 Solução de Problemas — Soluções para problemas comuns
• 🎯 Princípios Orientadores — Filosofia e melhores práticas do YARD
• 🏛️ Visão Geral da Arquitetura — Visão detalhada da arquitetura do sistema
• ⚙️ Guia de Ajuste de Performance — Otimize seu fluxo de trabalho YARD
• 🔒 Melhores Práticas de Segurança — Segurança e proteção de dados
• 🔄 Guia de Migração — Migração de versões anteriores
• 📦 Versionamento e Releases — Política de versões

🤖 YARD Autonomous Development Engine (ADE)

O YARD introduz o Autonomous Development Engine (ADE) — um sistema completo para desenvolvimento autônomo que transforma requisitos em código funcional.

O Que é o ADE?

ADE é um conjunto de 7 Epics que habilitam execução autônoma de desenvolvimento:

| Epic | Nome | Descrição | |---|---|---| | 1 | Worktree Manager | Isolamento de branches via Git worktrees | | 2 | Migration V2→V3 | Migração para formato autoClaude V3 | | 3 | Spec Pipeline | Transforma requisitos em specs executáveis | | 4 | Execution Engine | Executa specs com 13 steps + self-critique | | 5 | Recovery System | Recuperação automática de falhas | | 6 | QA Evolution | Review estruturado em 10 fases | | 7 | Memory Layer | Memória persistente de padrões e insights |

Fluxo Principal

User Request → Spec Pipeline → Execution Engine → QA Review → Working Code
                                      ↓
                              Recovery System
                                      ↓
                               Memory Layer

Quick Start ADE

# 1. Criar spec a partir de requisito
@pm *gather-requirements
@architect *assess-complexity
@analyst *research-deps
@pm *write-spec
@qa *critique-spec

# 2. Executar spec aprovada
@architect *create-plan
@architect *create-context
@dev *execute-subtask 1.1

# 3. QA Review
@qa *review-build STORY-42

Documentação ADE

• Guia Completo do ADE — Tutorial passo a passo
• Alterações nos Agentes — Comandos e capabilities por agente
• Epic 1 - Worktree Manager
• Epic 2 - Migration V2→V3
• Epic 3 - Spec Pipeline
• Epic 4 - Execution Engine
• Epic 5 - Recovery System
• Epic 6 - QA Evolution
• Epic 7 - Memory Layer

Novos Comandos por Agente

@devops:

• *create-worktree, *list-worktrees, *merge-worktree, *cleanup-worktrees
• *inventory-assets, *analyze-paths, *migrate-agent, *migrate-batch

@pm:

• *gather-requirements, *write-spec

@architect:

• *assess-complexity, *create-plan, *create-context, *map-codebase

@analyst:

• *research-deps, *extract-patterns

@qa:

• *critique-spec, *review-build, *request-fix, *verify-fix

@dev:

• *execute-subtask, *track-attempt, *rollback, *capture-insights, *list-gotchas, *apply-qa-fix

🧩 Criando Seu Próprio Squad

Squads permitem estender o YARD para qualquer domínio. Estrutura básica:

squads/seu-squad/
├── config.yaml           # Configuração do squad
├── agents/              # Agentes especializados
├── tasks/               # Fluxos de trabalho de tarefas
├── templates/           # Templates de documentos
├── checklists/          # Checklists de validação
├── data/                # Base de conhecimento
├── README.md            # Documentação do squad
└── user-guide.md        # Guia do usuário

Veja o Guia de Squads para instruções detalhadas.

Squads Disponíveis

Squads são equipes modulares de agentes IA. Veja a Visão Geral de Squads para mais informações.

Squads Externos

• hybrid-ops — Operações híbridas humano-agente (repositório separado)

💎 Yard Pro

O Yard Pro (@ernesto-langa/yard-pro) é o módulo premium do Yard, oferecendo funcionalidades avançadas para equipes e projetos de maior escala.

[!NOTE] Disponibilidade restrita: O Yard Pro está disponível exclusivamente para membros do Yard Cohort Advanced. Saiba mais sobre o programa.

Instalação

npm install @ernesto-langa/yard-pro

Features Premium

| Feature | Descrição | |---|---| | Squads Avançados | Squads especializados com capacidades expandidas | | Memory Layer | Memória persistente de padrões e insights entre sessões | | Métricas & Analytics | Dashboard de produtividade e métricas de desenvolvimento | | Integrações Enterprise | Conectores para Jira, Linear, Notion e mais | | Configuração em Camadas | Sistema de configuração L1-L4 com herança | | Licenciamento | Gerenciamento de licença via npx yard-pro activate --key <KEY> |

Para mais informações, execute npx yard-pro --help após a instalação.

🆘 Suporte

• 🐛 Rastreador de Issues — Bug reports e feature requests
• 💡 Processo de Features — Como propor novas funcionalidades
• 📋 Como Contribuir
• 🗺️ Roadmap — Veja o que estamos construindo
• 🤖 Guia de Squads — Crie equipes de agentes IA

🛡️ Git Workflow e Validação

O YARD implementa um sistema de validação de múltiplas camadas para garantir qualidade do código e consistência.

Defense in Depth — 3 Camadas de Validação

Camada 1: Pre-commit (Local — Rápida)

• ESLint — Qualidade de código
• TypeScript — Verificação de tipos
• Performance: <5s
• Cache habilitado

Camada 2: Pre-push (Local — Validação de Stories)

• Validação de checkboxes de histórias
• Consistência de status
• Seções obrigatórias

Camada 3: CI/CD (Cloud — Obrigatório para merge)

• Todos os testes
• Cobertura de testes (80% mínimo)
• Validações completas
• GitHub Actions

Documentação Detalhada

• 📋 Guia Completo de Git Workflow — Guia detalhado do fluxo de trabalho
• 📋 CONTRIBUTING.md — Guia de contribuição

Comandos Disponíveis

# Validações locais
npm run lint           # ESLint
npm run typecheck      # TypeScript
npm test              # Testes
npm run test:coverage # Testes com cobertura

# Validador YARD
node .yard-core/utils/yard-validator.js pre-commit   # Validação pre-commit
node .yard-core/utils/yard-validator.js pre-push     # Validação pre-push
node .yard-core/utils/yard-validator.js stories      # Validar todas stories

Branch Protection

Configure proteção da branch master com:

node scripts/setup-branch-protection.js

Requer GitHub CLI (gh) instalado e autenticado, e acesso de admin ao repositório.

🤝 Contribuindo

Estamos empolgados com contribuições e acolhemos suas ideias, melhorias e Squads!

Para contribuir:

1. Fork o repositório
2. Crie uma branch para sua feature (git checkout -b feature/MinhaNovaFeature)
3. Commit suas mudanças (git commit -m 'feat: Adicionar nova feature')
4. Push para a branch (git push origin feature/MinhaNovaFeature)
5. Abra um Pull Request

Veja também:

• 📋 Como Contribuir com Pull Requests
• 📋 Guia de Git Workflow

📄 Legal

| Documento | English | Português | |---|---|---| | Licença | MIT License | — | | Modelo de Licença | Core vs Pro | — | | Privacidade | Privacy Policy | — | | Termos de Uso | Terms of Use | — | | Código de Conduta | Code of Conduct | PT-BR | | Contribuição | Contributing | PT-BR | | Segurança | Security | PT-BR | | Comunidade | Community | PT-BR | | Roadmap | Roadmap | PT-BR | | Changelog | Version History | — |

Voltar ao topo