@agent-forge-copilot/cli

AI-Native Context Kit for GitHub Copilot-Driven Development
Generate agents, prompts, instructions, skills, hooks, MCP configs, and agentic workflows — powered by a multi-agent AI pipeline.

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

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

npx @agent-forge-copilot/cli init

The CLI walks you through everything interactively — choose to create from a description, analyze an existing project, or install pre-built templates.

Global install: npm install -g @agent-forge-copilot/cli, then use forge directly.

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.)

Features

7 Artifact Types

Project Modes

Speed Modes

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

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

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

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

forge list

forge check

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/

Contributing

git clone https://github.com/jiratouchmhp/agent-forge.git
cd agent-forge
npm install
npm run build
node dist/index.js init --help

src/
├── index.ts                 # CLI entry point (Commander)
├── types.ts                 # Shared TypeScript types
├── commands/                # CLI command handlers
│   ├── init.ts              # forge init — interactive wizard
│   ├── generate.ts          # forge generate — direct AI generation
│   ├── list.ts              # forge list — show installed & gallery
│   ├── validate.ts          # forge validate — quality checks
│   └── check.ts             # forge check — prerequisites
├── lib/                     # Core libraries
│   ├── copilot-cli.ts       # Copilot CLI orchestration & fleet mode
│   ├── detector.ts          # Workspace tech stack detection
│   ├── domain-registry.ts   # Domain pattern matching & decomposition
│   ├── gallery.ts           # Built-in template registry
│   ├── merger.ts            # Smart merge for existing .github/ files
│   ├── prerequisites.ts     # Prerequisite checking
│   ├── prompt-builder.ts    # Prompt construction with reference examples
│   ├── scaffold.ts          # Workspace setup & file installation
│   └── validator.ts         # YAML validation, tool name checks & auto-fix
├── cli/                     # Multi-agent pipeline definitions
│   ├── planners/            # Plan-phase agents
│   ├── orchestrators/       # Execution-phase agents
│   ├── writers/             # 7 specialized writer agents
│   └── reference/           # Format specifications
└── template/                # Gallery template files

assets/                      # Branding (SVG logos)
scripts/
└── copy-assets.mjs          # Build helper

License

MIT