\n\n---\n\n## What is AGENT-FORGE?\n\nAGENT-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.\n\n- **Multi-agent generation** — a planner decomposes your project into domains, then 7 specialized writer agents create tailored artifacts\n- **Greenfield & brownfield** — works from a description (new projects) or scans your existing codebase to codify real patterns\n- **Tech stack detection** — identifies frameworks, libraries, and conventions from your project files\n- **Post-generation validation** — checks YAML frontmatter, tool names, glob patterns, and content quality with auto-fix\n\n---\n\n## How It Works\n\nAGENT-FORGE uses a **plan-then-execute** architecture powered by GitHub Copilot CLI:\n\n1. **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`.\n2. **Execute** — An orchestrator reads the plan and delegates to 7 specialized writer agents that create each artifact type.\n3. **Validate** — All generated files are checked for YAML correctness, valid tool names, and content quality. Issues are auto-fixed when possible.\n4. **Install** — Artifacts are placed into `.github/` and `.vscode/` with smart merge logic.\n\n```\nforge init / generate\n │\n ▼\n ┌─────────┐ Analyzes description or scans codebase\n │ Planner │──▶ Extracts tech stack, decomposes domains\n └────┬────┘ Outputs forge-plan.json\n │\n ▼\n ┌──────────────┐\n │ Orchestrator │──▶ Reads plan, delegates to writers\n └──────┬───────┘\n │\n ├──▶ Agent Writer → *.agent.md\n ├──▶ Instruction Writer → *.instructions.md\n ├──▶ Skill Writer → SKILL.md\n ├──▶ Prompt Writer → *.prompt.md\n ├──▶ Hook Writer → hooks/*.json\n ├──▶ MCP Writer → .vscode/mcp.json\n └──▶ Workflow Writer → workflows/*.md\n │\n ▼\n Validate & Auto-fix\n │\n ▼\n Install to .github/\n```\n\n---\n\n## Prerequisites\n\n**Required:**\n\n- **Node.js 18+**\n- **VS Code** (or VS Code Insiders) with the GitHub Copilot extension\n- **[GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli)** — powers the generation pipeline\n\n**Optional:**\n\n- **Git** — version control\n- **GitHub CLI** (`gh`) — needed for agentic workflows\n- **Docker** — needed by some MCP servers\n\nRun `forge check` to verify everything in one step.\n\n---\n\n## Quick Start\n\n```bash\nnpm install -g @agent-forge-copilot/cli\n```\n\n> Or run without installing: `npx @agent-forge-copilot/cli init`\n\n### 🟢 Create — Start from a Description\n\nDescribe what you're building. The AI plans and generates everything from scratch.\n\n```bash\nforge init --mode create\n```\n\nYou'll be prompted for a description interactively — or pass it directly:\n\n```bash\nforge init --mode create --description \"Next.js e-commerce app with Stripe payments\"\n```\n\n### 🔵 Analyze — Scan Your Existing Project\n\nAlready have code? The tool scans your repo and generates Copilot configs that match your real stack.\n\n```bash\nforge init --mode analyze\n```\n\n### 📦 Templates — Install Pre-Built Configs\n\nSkip AI entirely. Pick from ready-made templates:\n\n```bash\nforge init --mode templates\n```\n\n### What gets created\n\n```\n.github/\n├── agents/ # AI personas — define what Copilot can do\n├── prompts/ # Slash commands — shortcuts you type in chat\n├── instructions/ # Rules — auto-applied to matching file patterns\n├── skills/ # Knowledge packs — domain info agents reference\n├── hooks/ # Automation — scripts triggered by agent events\n├── workflows/ # GitHub Actions with AI automation\n└── copilot-instructions.md\n.vscode/\n└── mcp.json # External tool servers (GitHub, Playwright, etc.)\n```\n\n---\n\n## Example Prompts\n\nThe description you provide drives the entire generation. Here are examples from simple to detailed.\n\n### 🟢 Create Mode — Describe Your App\n\n```bash\nforge init --mode create\n```\n\nYou'll be prompted: *\"Describe your project\"*. The quality of your description affects the output:\n\n**Simple** — works, but generates generic config:\n```\nTodo app\n```\n\n**Better** — detects 2 tech layers, creates 2 specialized agents:\n```\nTodo app with React and Express\n```\n\n**Best** — full stack detection, tailored agents + instructions + skills for each layer:\n```\nTodo app with React frontend using TailwindCSS, Express REST API\nwith Prisma ORM and PostgreSQL, JWT auth, and Docker deployment\n```\n\n**More examples you can try:**\n\n```\nE-commerce marketplace with Next.js, Stripe checkout, and Supabase\n```\n\n```\nRAG chatbot using LangChain, FastAPI, and Pinecone vector store\n```\n\n```\nREST API for fitness tracking with NestJS, Prisma, and Redis caching\n```\n\n```\nEvent-driven microservices with Go, gRPC, Kafka, and Kubernetes\n```\n\n```\nNode.js CLI that converts Markdown to PDF with custom templates\n```\n\n#### Writing Better Descriptions\n\n| Tip | Example |\n|-----|---------|\n| Name your frameworks | `Next.js` not `React framework` |\n| Mention your database | `PostgreSQL`, `MongoDB`, `Redis` |\n| Include infrastructure | `Docker`, `Kubernetes`, `AWS` |\n| Add business context | `e-commerce`, `healthcare`, `fintech` |\n| Specify patterns | `TDD`, `microservices`, `event-driven` |\n\n> The more specific your description, the more tailored the output. Business context like `\"e-commerce\"` or `\"healthcare\"` triggers domain-specific agent patterns.\n\n### 🔵 Analyze Mode — Scan Your Codebase\n\n```bash\nforge init --mode analyze\n```\n\nNo description needed — the tool scans your codebase automatically. Just choose a strategy:\n\n| Strategy | Command | What it does |\n|----------|---------|-------------|\n| **Auto** | `forge init --mode analyze --strategy auto` | Scans your repo and generates configs automatically — no questions asked |\n| **Guided** | `forge init --mode analyze --strategy guided` | Scans your repo, then asks what you'd like to add on top |\n\nThe analyzer detects:\n- `package.json`, `requirements.txt`, `go.mod` → your tech stack\n- `src/` structure → your project layout\n- Existing `.github/` files → avoids duplicating what you already have\n\n---\n\n## Features\n\n### 7 Artifact Types\n\n| Type | File Pattern | Purpose |\n|------|-------------|---------|\n| Agent | `*.agent.md` | AI persona with tools, responsibilities, and process |\n| Prompt | `*.prompt.md` | Slash command that routes to an agent |\n| Instruction | `*.instructions.md` | Quality rules auto-applied to matching files |\n| Skill | `SKILL.md` | Domain knowledge loaded on-demand |\n| Hook | `hooks/*.json` | Lifecycle automation triggered on agent events |\n| MCP Config | `.vscode/mcp.json` | External tool servers for AI-powered development |\n| Workflow | `workflows/*.md` | GitHub Actions with AI automation |\n\n### Project Modes\n\n| Mode | Description |\n|------|-------------|\n| **Greenfield** | Provide a description. The planner extracts the tech stack, decomposes domains, and generates everything from scratch. |\n| **Brownfield** | The planner scans your codebase — `package.json`, source files, directory structure, existing `.github/` config — and creates a plan aligned to your real patterns. |\n\n### Speed Modes\n\n| Mode | How it works | Cost |\n|------|-------------|------|\n| **Standard** | Single Copilot CLI session, orchestrator creates all files sequentially | ~2 PRU |\n| **Turbo** | Single session with `/fleet` — parallel subagents, each with their own context | ~N+1 PRU |\n\n### Smart Merging\n\nWhen generating into a project with existing `.github/` files, AGENT-FORGE detects files it previously generated (via `` markers) and only overwrites those. User-created files are preserved. Use `--force` to override.\n\n---\n\n## CLI Reference\n\n| Command | Description |\n|---------|-------------|\n| `forge init` | Interactive setup wizard |\n| `forge generate ` | Generate Copilot files from a description |\n| `forge list` | Show installed and available use cases |\n| `forge validate [scope]` | Check config files for errors |\n| `forge check` | Verify prerequisites |\n\n\nforge init\n\n| Flag | Description |\n|------|-------------|\n| `--mode ` | Wizard mode: `create`, `analyze`, or `templates` |\n| `--description ` | Use case description (skip prompt) |\n| `--model ` | AI model to use (skip prompt) |\n| `--strategy ` | Analyze strategy: `auto` (scan-only) or `guided` (scan + custom requirements) |\n| `--speed ` | `standard` or `turbo` |\n| `--use-cases ` | Comma-separated template IDs (e.g., `code-review,testing`) |\n| `--skip-check` | Skip the prerequisite check |\n| `--force` | Overwrite existing files |\n\n```bash\nforge init\nforge init --mode templates --use-cases code-review,testing\nforge init --mode analyze --strategy auto\nforge init --mode create --description \"Next.js app\" --model claude-sonnet-4.6 --speed turbo\n```\n\n\n\n\nforge generate\n\n| Flag | Description |\n|------|-------------|\n| `--model ` | AI model to use |\n| `--mode ` | `discovery`, `full`, `on-demand`, `mcp-server`, `hooks`, `agentic-workflow` |\n| `--types ` | Comma-separated artifact types for on-demand mode |\n| `--speed ` | `standard` or `turbo` |\n\n```bash\nforge generate \"API rate limiter with per-tenant limits\"\nforge generate \"Security scanner\" --model claude-opus-4.6\nforge generate \"CI/CD automation\" --mode hooks\nforge generate \"Dev tooling\" --mode mcp-server\nforge generate \"Testing tools\" --mode on-demand --types agent,hook\nforge generate \"Full-stack app\" --speed turbo\n```\n\n\n\n\nforge validate\n\n| Flag | Description |\n|------|-------------|\n| `--fix` | Auto-fix issues using AI |\n| `--no-fix` | Skip the interactive fix prompt |\n| `--model ` | Model for AI-powered fixes |\n\n```bash\nforge validate\nforge validate ./path/to/dir\nforge validate --fix\nforge validate --fix --model claude-opus-4.6\n```\n\n\n\n\nforge list\n\nShows which Copilot customization files exist in your project and which gallery templates are available. No flags.\n\n```bash\nforge list\n```\n\n\n\n\nforge check\n\nVerifies that Node.js, VS Code, Git, GitHub CLI, Copilot CLI, and Docker are installed. No flags.\n\n```bash\nforge check\n```\n\n\n\n\nModel selection\n\nPass `--model ` or choose interactively during generation:\n\n| Value | Name | Description | Premium |\n|-------|------|-------------|---------|\n| `claude-sonnet-4.6` | Claude Sonnet 4.6 | Fastest — best speed/quality tradeoff **(default)** | 1× |\n| `claude-sonnet-4.5` | Claude Sonnet 4.5 | Fast — higher quality reasoning | 1× |\n| `gpt-4.1` | GPT-4.1 | Fast — efficient code generation | 1× |\n| `gpt-5.2-codex` | GPT 5.2 Codex | Balanced — strong code generation | 1× |\n| `gemini-3-pro-preview` | Gemini 3 Pro | Strong reasoning — large context window | 2× |\n| `claude-opus-4.6` | Claude Opus 4.6 | Highest quality — deep reasoning | 5× |\n\n\n","readmeFilename":"README.md"}
![\"npm](\"https://img.shields.io/npm/v/@agent-forge-copilot/cli?color=orange\")
![\"license\"/](\"https://img.shields.io/github/license/microsoft/agent-forge\")