What is AGENT-FORGE?

AGENT-FORGE is a Context Engineering Toolkit that generates GitHub Copilot customization files for your VS Code project. Instead of manually authoring .github/ configuration, you describe what you need and a multi-agent AI pipeline plans, generates, validates, and installs everything.

• Multi-agent generation — a planner decomposes your project into domains, then 7 specialized writer agents create tailored artifacts
• Greenfield & brownfield — works from a description (new projects) or scans your existing codebase to codify real patterns
• Tech stack detection — identifies frameworks, libraries, and conventions from your project files
• Post-generation validation — checks YAML frontmatter, tool names, glob patterns, and content quality with auto-fix

How It Works

AGENT-FORGE uses a plan-then-execute architecture powered by GitHub Copilot CLI:

1. Plan — A planner agent analyzes your description (greenfield) or scans your codebase (brownfield), extracts the tech stack, decomposes it into domains, and outputs a forge-plan.json.
2. Execute — An orchestrator reads the plan and delegates to 7 specialized writer agents that create each artifact type.
3. Validate — All generated files are checked for YAML correctness, valid tool names, and content quality. Issues are auto-fixed when possible.
4. Install — Artifacts are placed into .github/ and .vscode/ with smart merge logic.

forge init / generate
        │
        ▼
   ┌─────────┐     Analyzes description or scans codebase
   │ Planner  │──▶  Extracts tech stack, decomposes domains
   └────┬────┘     Outputs forge-plan.json
        │
        ▼
   ┌──────────────┐
   │ Orchestrator  │──▶  Reads plan, delegates to writers
   └──────┬───────┘
          │
          ├──▶ Agent Writer       → *.agent.md
          ├──▶ Instruction Writer → *.instructions.md
          ├──▶ Skill Writer       → SKILL.md
          ├──▶ Prompt Writer      → *.prompt.md
          ├──▶ Hook Writer        → hooks/*.json
          ├──▶ MCP Writer         → .vscode/mcp.json
          └──▶ Workflow Writer    → workflows/*.md
                                        │
                                        ▼
                                  Validate & Auto-fix
                                        │
                                        ▼
                                  Install to .github/

Prerequisites

Required:

• Node.js 18+
• VS Code (or VS Code Insiders) with the GitHub Copilot extension
• GitHub Copilot CLI — powers the generation pipeline

Optional:

• Git — version control
• GitHub CLI (gh) — needed for agentic workflows
• Docker — needed by some MCP servers

Run forge check to verify everything in one step.

Quick Start

npm install -g @agent-forge-copilot/cli

Or run without installing: npx @agent-forge-copilot/cli init

🟢 Create — Start from a Description

Describe what you're building. The AI plans and generates everything from scratch.

forge init --mode create

You'll be prompted for a description interactively — or pass it directly:

forge init --mode create --description "Next.js e-commerce app with Stripe payments"

🔵 Analyze — Scan Your Existing Project

Already have code? The tool scans your repo and generates Copilot configs that match your real stack.

forge init --mode analyze

📦 Templates — Install Pre-Built Configs

Skip AI entirely. Pick from ready-made templates:

forge init --mode templates

What gets created

.github/
├── agents/                # AI personas — define what Copilot can do
├── prompts/               # Slash commands — shortcuts you type in chat
├── instructions/          # Rules — auto-applied to matching file patterns
├── skills/                # Knowledge packs — domain info agents reference
├── hooks/                 # Automation — scripts triggered by agent events
├── workflows/             # GitHub Actions with AI automation
└── copilot-instructions.md
.vscode/
└── mcp.json               # External tool servers (GitHub, Playwright, etc.)

Example Prompts

The description you provide drives the entire generation. Here are examples from simple to detailed.

🟢 Create Mode — Describe Your App

forge init --mode create

You'll be prompted: "Describe your project". The quality of your description affects the output:

Simple — works, but generates generic config:

Todo app

Better — detects 2 tech layers, creates 2 specialized agents:

Todo app with React and Express

Best — full stack detection, tailored agents + instructions + skills for each layer:

Todo app with React frontend using TailwindCSS, Express REST API
with Prisma ORM and PostgreSQL, JWT auth, and Docker deployment

More examples you can try:

E-commerce marketplace with Next.js, Stripe checkout, and Supabase

RAG chatbot using LangChain, FastAPI, and Pinecone vector store

REST API for fitness tracking with NestJS, Prisma, and Redis caching

Event-driven microservices with Go, gRPC, Kafka, and Kubernetes

Node.js CLI that converts Markdown to PDF with custom templates

Writing Better Descriptions

| Tip | Example | |-----|---------| | Name your frameworks | Next.js not React framework | | Mention your database | PostgreSQL, MongoDB, Redis | | Include infrastructure | Docker, Kubernetes, AWS | | Add business context | e-commerce, healthcare, fintech | | Specify patterns | TDD, microservices, event-driven |

The more specific your description, the more tailored the output. Business context like "e-commerce" or "healthcare" triggers domain-specific agent patterns.

🔵 Analyze Mode — Scan Your Codebase

forge init --mode analyze

No description needed — the tool scans your codebase automatically. Just choose a strategy:

| Strategy | Command | What it does | |----------|---------|-------------| | Auto | forge init --mode analyze --strategy auto | Scans your repo and generates configs automatically — no questions asked | | Guided | forge init --mode analyze --strategy guided | Scans your repo, then asks what you'd like to add on top |

The analyzer detects:

• package.json, requirements.txt, go.mod → your tech stack
• src/ structure → your project layout
• Existing .github/ files → avoids duplicating what you already have

Features

7 Artifact Types

| Type | File Pattern | Purpose | |------|-------------|---------| | Agent | *.agent.md | AI persona with tools, responsibilities, and process | | Prompt | *.prompt.md | Slash command that routes to an agent | | Instruction | *.instructions.md | Quality rules auto-applied to matching files | | Skill | SKILL.md | Domain knowledge loaded on-demand | | Hook | hooks/*.json | Lifecycle automation triggered on agent events | | MCP Config | .vscode/mcp.json | External tool servers for AI-powered development | | Workflow | workflows/*.md | GitHub Actions with AI automation |

Project Modes

| Mode | Description | |------|-------------| | Greenfield | Provide a description. The planner extracts the tech stack, decomposes domains, and generates everything from scratch. | | Brownfield | The planner scans your codebase — package.json, source files, directory structure, existing .github/ config — and creates a plan aligned to your real patterns. |

Speed Modes

| Mode | How it works | Cost | |------|-------------|------| | Standard | Single Copilot CLI session, orchestrator creates all files sequentially | ~2 PRU | | Turbo | Single session with /fleet — parallel subagents, each with their own context | ~N+1 PRU |

Smart Merging

When generating into a project with existing .github/ files, AGENT-FORGE detects files it previously generated (via <!-- Generated by AGENT-FORGE --> markers) and only overwrites those. User-created files are preserved. Use --force to override.

CLI Reference

| Command | Description | |---------|-------------| | forge init | Interactive setup wizard | | forge generate <description> | Generate Copilot files from a description | | forge list | Show installed and available use cases | | forge validate [scope] | Check config files for errors | | forge check | Verify prerequisites |

| Flag | Description | |------|-------------| | --mode <mode> | Wizard mode: create, analyze, or templates | | --description <text> | Use case description (skip prompt) | | --model <model> | AI model to use (skip prompt) | | --strategy <strategy> | Analyze strategy: auto (scan-only) or guided (scan + custom requirements) | | --speed <speed> | standard or turbo | | --use-cases <ids> | Comma-separated template IDs (e.g., code-review,testing) | | --skip-check | Skip the prerequisite check | | --force | Overwrite existing files |

forge init
forge init --mode templates --use-cases code-review,testing
forge init --mode analyze --strategy auto
forge init --mode create --description "Next.js app" --model claude-sonnet-4.6 --speed turbo

| Flag | Description | |------|-------------| | --model <model> | AI model to use | | --mode <mode> | discovery, full, on-demand, mcp-server, hooks, agentic-workflow | | --types <types> | Comma-separated artifact types for on-demand mode | | --speed <speed> | standard or turbo |

forge generate "API rate limiter with per-tenant limits"
forge generate "Security scanner" --model claude-opus-4.6
forge generate "CI/CD automation" --mode hooks
forge generate "Dev tooling" --mode mcp-server
forge generate "Testing tools" --mode on-demand --types agent,hook
forge generate "Full-stack app" --speed turbo

| Flag | Description | |------|-------------| | --fix | Auto-fix issues using AI | | --no-fix | Skip the interactive fix prompt | | --model <model> | Model for AI-powered fixes |

forge validate
forge validate ./path/to/dir
forge validate --fix
forge validate --fix --model claude-opus-4.6

Shows which Copilot customization files exist in your project and which gallery templates are available. No flags.

forge list

Verifies that Node.js, VS Code, Git, GitHub CLI, Copilot CLI, and Docker are installed. No flags.

forge check

Pass --model <value> or choose interactively during generation:

| Value | Name | Description | Premium | |-------|------|-------------|---------| | claude-sonnet-4.6 | Claude Sonnet 4.6 | Fastest — best speed/quality tradeoff (default) | 1× | | claude-sonnet-4.5 | Claude Sonnet 4.5 | Fast — higher quality reasoning | 1× | | gpt-4.1 | GPT-4.1 | Fast — efficient code generation | 1× | | gpt-5.2-codex | GPT 5.2 Codex | Balanced — strong code generation | 1× | | gemini-3-pro-preview | Gemini 3 Pro | Strong reasoning — large context window | 2× | | claude-opus-4.6 | Claude Opus 4.6 | Highest quality — deep reasoning | 5× |