convez.ai
AgenteDevOps & InfraestruturaAvançado
cristiancorreau

Forge — Framework de Desenvolvimento Agentic Multi-Runtime

cristiancorreau/forge

Uma equipe de agentes, 19 runtimes — defina uma vez, execute em tudo

Ver no GitHub
BomPluginScore · de 0 a 100

Framework agentic que configura projetos para trabalhar com agentes IA em um único comando. Sincroniza uma equipe de agentes especializados em 19 runtimes diferentes (Claude Code, OpenCode, Codex CLI e outros) a partir de um único arquivo `project.yaml` como fonte da verdade.

Instalação

$npx convez-ai cristiancorreau/forge

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
0
Acompanhando
1
Saúde
71%
Último commit
há 4 meses
Versão
v3.12.0
Issues abertas
8
Contribuidores
1

Casos de uso

  • Coordenar múltiplos agentes IA em diferentes IDEs e CLIs
  • Implementar guardrails de segurança e compliance (GDPR/LGPD/CCPA)
  • Desenvolver com fluxo spec-first (especificação aprovada antes de execução)
  • Reutilizar configurações de agentes entre projetos sem duplicação

Veredito

Forge é um projeto sofisticado para equipes que precisam orquestrar múltiplos agentes IA com rigor, compliance e portabilidade entre runtimes. A curva de aprendizado é acentuada, mas resolve genuinamente o problema de fragmentação de configurações em ecossistemas agentic heterogêneos.

README

A tradução para o português deste README ainda está na fila.

English · Español

Set up any project to work with AI agents in a single command

One agent team, every runtime — 19 runtimes (4 native + 15 rules-based editors) from a single project.yaml.

npm version CI tests license node

Landing   •   Documentation   •   npm   •   Issues

npx @cristiancorreau/forge init

The forge interactive panel (forge panel) requires Bun (OpenTUI) — explore agents, skills, hooks and profiles without leaving the terminal.


What is forge?

forge is a multi-runtime agentic development framework. A single command analyzes your project, installs a team of specialized agents, wires up security guardrails, and leaves a project.yaml as the single source of truth from which each AI runtime's native configuration is regenerated.

Instead of copy-pasting agent rules across projects and across tools, you define the team once and forge materializes it for all 19 supported runtimes.

  • 🤖 Multi-runtime agent teams — 7 universal agents + 19 stack profiles
  • 📐 Spec-first SDD flow — no code task without an APPROVED spec
  • 🪝 Guardrail hooks in pure JS — branch-guard, debug, secrets and prod-safety, zero Python
  • 🔁 One project.yaml, every CLI — 19 runtimes: 4 native + 15 rules-based
  • ⚖️ Compliance with binding veto — GDPR/LGPD/CCPA reviewer that blocks the merge
  • 🔄 Reversible operations — SHA-256 manifest + --dry-run to audit every change
  • 📚 Project knowledge base — wiki that ingests, lints and answers with citations

Why forge?

vs. hand-made agent rules

  • One project.yaml, four runtimes — you write the team once, not four times.
  • Spec-first by default — the orchestrator refuses to spawn agents without an approved spec.
  • Guardrails already wired — security hooks ready to go, no Python to install.
  • Regenerable — forge generate rebuilds the entire team from the source of truth.

vs. copy-pasting agents across projects

  • Composable TIERs — universal → stack → domain, with predictable collision resolution.
  • 19 stack profiles ready to go — Next.js, FastAPI, Django, Rails, Laravel, Go, Rust, Flutter…
  • Reversible operations — SHA-256 manifest detects drift; forge teardown uninstalls cleanly.
  • Drift under control — forge update re-syncs with the catalog while preserving your edits.

Installation

forge runs on Node.js 20+. With Bun you unlock the full-screen panel (OpenTUI, @opentui/core); on Node it falls back to @clack prompts; on legacy consoles, to ASCII.

Try without installing:

npx @cristiancorreau/forge init

Install the global forge command — pick your package manager:

npm  install -g @cristiancorreau/forge   # npm
pnpm add     -g @cristiancorreau/forge   # pnpm  (run `pnpm setup` once)
bun  add     -g @cristiancorreau/forge   # bun   (needs ~/.bun/bin on PATH)

The full-screen forge init wizard (OpenTUI) runs under Bun; with npm/node it works the same via prompts. If you have forge installed with both bun and npm, whichever is first on your PATH wins — update that same manager (e.g. bun add -g @cristiancorreau/forge@latest).

Is the forge command not recognized after the global install? The global binaries directory is not on your PATH. npx @cristiancorreau/forge <cmd> always works without installing; for the bare command:

  • npm: export PATH="$(npm prefix -g)/bin:$PATH"
  • pnpm: run pnpm setup and reopen the terminal
  • bun: add export PATH="$HOME/.bun/bin:$PATH" to your shell rc

Quickstart (30 s)

# 1. Inicializa forge en tu proyecto
#    (wizard: detecta stack, instala agentes + hooks, escribe el manifest)
npx @cristiancorreau/forge init

# 2. Verifica el entorno y la conformidad
forge doctor
forge validate

# 3. Regenera la configuración nativa de cada runtime desde project.yaml
forge generate

Already have a codebase up and running? Integrate it without starting from scratch:

forge adopt        # analiza el repo existente + auto-wiki

The 5 layers

forge is organized into five layers that go from the source of truth to per-runtime materialization.

LayerResponsibility
🧠 Memoryproject.yaml as the single source of truth — stack, team, skills, rules.
📚 KnowledgeAgents + stack profiles that bring the knowledge of each role and framework.
🛡️ GuardrailCompliance and security enforcement: hooks, branch-guard, secret detection.
🎯 DelegationSkill orchestration and dispatch: which agent handles which task.
📡 DistributionRuntime adapters that translate the source of truth to 19 AI runtimes (4 native + 15 rules-based).

TIER system

Three composable levels, from the general to the specific. Each tier inherits and specializes the previous one; on a collision, the most concrete one wins.

TierWhat it isExamples
Tier 1 — universal7 agents defined by their output, not by the stack. Useful in any project.orchestrator, backend-engineer, frontend-engineer, test-engineer, docs-writer, compliance-reviewer, security-auditor
Tier 2 — stackThe same roles with framework-specific instructions. 19 profiles available.Next.js, FastAPI, Django, Rails, Laravel, Go-Gin, Rust, NestJS…
Tier 3 — domainAgents that know the project's business. They live in the repo, registered under agents.specialized.dsar-specialist, gcm-engineer, policy-engineer…

Full detail in docs/en/tiers.md.


Commands

The 16 CLI commands.

CommandWhat it does
forge initFull wizard: detects the stack, installs agents and hooks, writes the manifest.
forge adoptOnboards forge into an existing codebase (analysis + auto-wiki).
forge generateRegenerates each runtime's native configuration from project.yaml.
forge updateRe-syncs managed files with the catalog while preserving local edits (SHA-256 drift).
forge validateValidates that project.yaml and the generated files conform to the schema.
forge doctorEnvironment health-check: Node.js, git, active AI runtime, permissions.
forge migrateMigrates project.yaml from schema v1 to v2 (--dry-run, --backup).
forge auditVerifies the project against the manifest; detects modified or missing files.
forge scaffoldGenerates a new agent: Tier 2 profile or Tier 3 domain agent.
forge teardownCleanly uninstalls forge from the project via the manifest (--dry-run, --keep-config).
forge skillsLists the available skills grouped by category.
forge aitmpl-searchSearches the curated offline catalog (frameworks, MCP servers, profiles).
forge wikiManages the project knowledge base (status | ingest | query | lint).
forge panelInteractive OpenTUI panel (config / monitor / skills / hooks / templates).
forge session-startOpens a work session: detects the repo state and routes.
forge session-closeCloses a session: commit → daily note → sync → PR.

Interactive panel. With Bun, forge panel (and the post-init dashboard) opens a navigable OpenTUI panel to explore agents, skills, hooks and profiles without leaving the terminal. With Node it falls back to the standard prompt flow.


Stacks / Profiles (19)

Tier 2 profiles ready to activate. Each one brings architecture rules, code conventions and framework patterns.

TypeScript / JSPythonPHPOthers
astrodjangolaravelgo-gin (Go)
expressfastapiwordpressrust
hono-drizzleflaskspringboot (Java)
nestjsrails (Ruby)
nextjs-adminflutter (Dart)
sveltekit
vuenuxt
expo
playwright-crawler

Runtimes

A single forge project adapts to four runtimes, each with its native output.

RuntimeSupportOutput
Claude Code✅ CompleteCLAUDE.md, .claude/agents/, .claude/commands/, .claude/settings.json, hooks
OpenCode✅ SupportedAGENTS.md generated from the root
Codex CLI✅ SupportedAGENTS.md enriched for project context
Kiro🔭 Monitoringsteering files (.kiro/steering/*.md)

Per-runtime detail in docs/en/runtimes/.


VS Code extension

The forge Agent Framework extension (cristiancorreau.forge-agent-framework) surfaces the CLI inside VS Code: run init, audit, doctor, generate and other commands from the Command Palette and the sidebar panel, without leaving the editor.

Status: v0.6.0 is packaged but pending publication to the Marketplace (the current live version is 0.5.0). Publishing requires a valid VSCE_PAT secret loaded in the repository.

Trigger the publish: push tag vscode-v0.6.0 or dispatch the publish-vscode workflow manually — both require the VSCE_PAT secret (Azure DevOps PAT, scope Marketplace › Manage).

Full development and publishing instructions: vscode-extension/README.md.


Skills

12 general skills that encapsulate complete flows, mapped per runtime and triggerable as slash commands (/spec, /new-feature, /db-migrate…), plus per-stack skills.

SkillWhat it's for
specDrafts SDD specs in docs/specs/.
new-featureSpec-first feature kickoff, from plan to deploy.
security-auditSecurity audit checklist.
db-migrateSafe migrations (Prisma, Drizzle, ActiveRecord, Alembic, Goose).
local2prodDeploy with a multi-provider production gate.
browser-testUI and critical-flow verification via browser.
phase-kickoffRoadmap phase startup.
obsidian-syncSync with Obsidian.
aitmpl-searchSearches the curated offline catalog.
wiki-ingestIngests sources into the knowledge base.
wiki-lintLints the wiki's consistency.
wiki-queryAnswers queries citing wiki pages.

In addition, session-start and session-close are available as CLI commands.

Per-stack skills. The Laravel profile adds 5 Laravel 13-oriented skills: /laravel-eloquent, /laravel-pest, /laravel-security, /laravel-verify and /laravel-mcp (Boost, laravel/mcp, AI SDK, embeddings/pgvector).

Full catalog in docs/en/skills.md.


SDD: spec-first, not optional

forge enforces Spec-Driven Development with a real gate, not a suggestion:

  • No code task starts without a spec in the APPROVED state inside docs/specs/.
  • The orchestrator vetoes spawning implementation agents if there is no approved spec.
  • The /spec skill drafts the spec; /new-feature takes it from plan to deploy.

The result: the agent team doesn't improvise code on top of ambiguous requirements — first the what is agreed upon, then the how is generated.


Compliance with binding veto

The compliance-reviewer agent (Tier 1, model opus) reviews every PR against the active compliance frameworks — GDPR / LGPD / CCPA — with binding veto power before merging.

On top of the guardrail hooks in pure JavaScript (zero Python):

  • 🚫 branch-guard — prevents direct commits on protected branches.
  • 🐛 debug detection — blocks console.log / print debug statements.
  • 🔐 secret detection — stops hardcoded secrets before the commit.
  • 🚀 prod-safety — protects sensitive operations against production.

Comparison

Capabilityforgeautoskillscc-sdd
FocusEnd-to-end agentic frameworkSkills collectionSDD for Claude Code
Spec-first SDD with gate✅ orchestrator veto❌✅ core
Agents by tier (1/2/3)✅❌❌
Stack profiles✅ 19🚧 partial❌
Invokable skills✅ 12✅ central focus🚧
Multi-runtime✅ 19 runtimes🚧 mostly Claude Code🚧
Compliance with veto (GDPR/LGPD/CCPA)✅ binding❌❌
Guardrail hooks (branch/secrets/prod)✅ no Python❌❌
Knowledge base / wiki with citations✅ ingest/lint/query❌❌
Reversible operations (SHA-256, dry-run)✅❌❌
Deploy with production gate✅ multi-provider❌❌

Documentation


Forge your agent team in a single command

npx @cristiancorreau/forge init

Get started on the landing →

Made with fire, anvil and a lot of dogfooding.


License

Apache-2.0 — Copyright © 2026 Cristian Correa.

Ver o original no GitHub

Bom para

Relacionados