Get Started

Install & Initialize

# One-shot (no install needed)
npx agent-forge-cli init

# Or install globally
npm install -g agent-forge-cli
forge init

What Happens

forge init launches an interactive wizard with 3 modes:

**New project** — prompts for a project name and a description of what to automate, then generates custom Copilot artifacts using AI.

**Existing project** — scans your workspace (detects tech stack, project type, existing `.github/` files), then generates tailored customizations.

**Clone gallery** — lets you pick from 6 pre-built use case templates:

? Pick use cases to install: (space to select) ◉ Code Review Agent — reviews PRs for quality & security ◯ Testing Workflow — TDD agent pipeline ◉ Documentation Generator — auto-generates docs from code ◯ Deployment Guardian — pre-deploy validation ◯ Onboarding Assistant — helps new devs understand codebase ◯ Refactoring Coach — suggests and validates refactors

✓ Code Review Agent (4 files) ✓ Documentation Generator (4 files)

✓ AGENT-FORGE initialized!

> **AI vs. Static generation:** If the [GitHub Copilot CLI](https://docs.github.com/en/copilot/using-github-copilot/using-github-copilot-in-the-command-line) (`copilot`) is installed, `init` and `generate` use it to produce AI-generated artifacts tailored to your description. Without it, AGENT-FORGE falls back to pre-built static templates.

### Open Copilot & Go

@Copilot Architect I need a code review workflow for my Python Django project

The Copilot Architect will analyze your workspace, interview you about your needs, and design the right artifact mix — then hand off creation to specialized worker agents.

## CLI Reference

| Command | Description |
|---------|-------------|
| `forge init` | Interactive setup — 3 modes: new project, existing project, or gallery clone |
| `forge generate <description>` | Generate a use case directly into `.github/` |
| `forge list` | Show installed and available use cases |
| `forge validate [scope]` | Validate customization files for schema and quality |
| `forge check` | Verify prerequisites (Node.js, VS Code, Git, GitHub CLI, Copilot CLI) |

### Init Options

| Flag | Description |
|------|-------------|
| `--mode <mode>` | Skip mode prompt — `new`, `existing`, or `gallery` |
| `--description <text>` | Use case description (skip prompt) |
| `--model <model>` | AI model to use (skip prompt) |
| `--use-cases <ids>` | Comma-separated gallery IDs (skip prompt) |
| `--force` | Overwrite existing files |

```bash
forge init                                        # Fully interactive
forge init --mode gallery --use-cases code-review,testing  # Non-interactive gallery clone
forge init --mode existing --description "CI/CD pipeline guardian"  # Add to current project
forge init --mode new --description "API rate limiter" --model claude-sonnet-4.6

Generate Options

| Flag | Description | |------|-------------| | --model <model> | AI model to use (skip prompt) | | --static | Force static template generation (skip Copilot CLI) |

forge generate "API rate limiter with per-tenant limits"
forge generate "Security vulnerability scanner for Python" --model claude-opus-4.6
forge generate "Database migration validator" --static

Model Selection

When using AI generation, you can choose a model interactively or pass --model:

| Value | Description | |-------|-------------| | claude-sonnet-4.6 | Fastest — best speed/quality tradeoff (default) | | claude-sonnet-4.5 | Fast — higher quality reasoning | | gpt-5.2-codex | Balanced — strong code generation | | claude-opus-4.6 | Slowest — highest quality output |

What Gets Installed

Core (always installed)

.github/
├── copilot-instructions.md              # Always-on project rules
├── agents/
│   ├── copilot-architect.agent.md       # Orchestrator (user-facing)
│   ├── artifact-builder.agent.md        # Worker: generates artifacts
│   ├── workflow-designer.agent.md       # Worker: multi-agent workflows
│   └── customization-reviewer.agent.md  # Worker: validates everything
├── prompts/
│   ├── design-workflow.prompt.md        # /design-workflow
│   ├── scaffold-all.prompt.md           # /scaffold-all
│   ├── generate-usecase.prompt.md       # /generate-usecase
│   ├── install-usecase.prompt.md        # /install-usecase
│   ├── list-customizations.prompt.md    # /list-customizations
│   └── validate-customizations.prompt.md # /validate-customizations
├── instructions/                        # Auto-applied quality gates
│   ├── agent-authoring.instructions.md
│   ├── prompt-authoring.instructions.md
│   ├── instruction-authoring.instructions.md
│   └── skill-authoring.instructions.md
└── skills/                              # On-demand knowledge packs
    ├── vscode-customization/SKILL.md    # Schema reference
    ├── subagent-patterns/SKILL.md       # Orchestration patterns
    ├── agent-template/SKILL.md          # Agent field reference
    ├── instruction-template/SKILL.md    # Instruction field reference
    ├── prompt-template/SKILL.md         # Prompt field reference
    └── skill-template/SKILL.md          # Skill field reference

Gallery Use Cases (pick during init)

| Use Case | Description | |----------|-------------| | Code Review | Reviews PRs for code quality, security, performance, and best practices | | Testing | TDD pipeline — writes tests, identifies coverage gaps, ensures quality | | Documentation | Auto-generates docs from code structure, comments, and conventions | | Deployment | Pre-deploy validation — config, env vars, dependencies, readiness | | Onboarding | Helps new devs understand the codebase — architecture, patterns, conventions | | Refactoring | Identifies code smells and guides safe, incremental improvements |

Each use case installs 4 files: an agent, a prompt (slash command), an instruction (quality rules), and a skill (domain knowledge).

Copilot Integration

Once installed, you get these slash commands in Copilot Chat:

| Command | Description | |---------|-------------| | /design-workflow | Guided design session — describe your goal and get a tailored artifact plan | | /generate-usecase | Create a custom use case with full agent + prompt + instruction + skill | | /scaffold-all | Generate all 4 artifact types for any topic | | /install-usecase | Copy a generated use case from use-cases/ into .github/ | | /list-customizations | Scan workspace and inventory all customization files | | /validate-customizations | Check artifacts for schema errors and best-practice violations |

Plus any slash commands from your installed gallery use cases (/code-review, /testing, /documentation, etc.).

How It Works

Architecture

AGENT-FORGE uses a coordinator-worker architecture with a strict 3-phase pipeline:

Phase 1: PLAN                    Phase 2: BUILD (parallel)         Phase 3: VALIDATE
┌──────────────────┐     ┌─────────────────┐ ┌─────────────────┐  ┌─────────────────┐
│ Copilot Architect│     │Artifact Builder  │ │Workflow Designer│  │  Customization  │
│   (coordinator)  │────▶│  (standalone     │ │  (multi-agent   │─▶│   Reviewer      │
│                  │     │   files)         │ │   systems)      │  │                 │
│ • Interview user │     │ • agents         │ │ • coordinator   │  │ • Schema check  │
│ • Scan workspace │     │ • prompts        │ │ • workers       │  │ • Cross-refs    │
│ • Recommend plan │     │ • instructions   │ │ • handoffs      │  │ • Best practices│
│ • Get approval   │     │ • skills         │ │ • patterns      │  │                 │
└──────────────────┘     └─────────────────┘ └─────────────────┘  └─────────────────┘
                                                                          │
                                                                   ✅ PASS → Done
                                                                   ❌ FAIL → Retry

Key Principles

| Principle | Description | |-----------|-------------| | Context isolation | Subagents run in isolated windows — no shared state | | Coordinator never creates files | Only plans and delegates | | Mandatory validation | Every build must pass the quality gate | | Retry loop | Errors trigger re-build, not manual fixes | | Parallel by default | Both Phase 2 subagents run simultaneously |

Artifact Types

| Type | File Pattern | Purpose | |------|-------------|---------| | Agent | *.agent.md | AI persona with tools, responsibilities, and process | | Prompt | *.prompt.md | User-facing 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 by agents |

Generating Custom Use Cases

From the CLI

forge generate "API rate limiter with per-tenant limits"

With the Copilot CLI installed, this launches the Copilot Architect agent to generate AI-tailored artifacts directly into .github/ — an agent, prompt, instruction, and skill file.

Without the Copilot CLI (or with --static), it generates pre-built template files instead.

From Copilot Chat

/generate-usecase security vulnerability scanner for Python

The Copilot Architect designs and creates a tailored set of artifacts using the Plan → Build → Validate pipeline.

Installing a Generated Use Case

# Copy into .github/ manually
cp -r use-cases/api-rate-limiter/* .github/

# Or use the Copilot command
/install-usecase api-rate-limiter

Prerequisites

| Tool | Required | Notes | |------|----------|-------| | Node.js 18+ | Yes | Runtime | | VS Code (or Insiders) | Yes | With GitHub Copilot extension | | GitHub Copilot | Yes | Subscription with Copilot Chat enabled | | Agent mode | Yes | chat.agent.enabled: true in VS Code settings | | Git | Recommended | For version control | | GitHub Copilot CLI | Recommended | Enables AI-powered generation (npm install -g @github/copilot) | | GitHub CLI (gh) | Optional | For GitHub integration |

Run forge check to verify your setup.

Contributing

Development

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

Project Structure

src/
├── index.ts              # CLI entry point (commander)
├── commands/             # CLI command handlers
│   ├── init.ts           # forge init
│   ├── generate.ts       # forge generate
│   ├── list.ts           # forge list
│   ├── validate.ts       # forge validate
│   └── check.ts          # forge check
├── lib/                  # Core libraries
│   ├── scaffold.ts       # Template rendering & file generation
│   ├── gallery.ts        # Built-in use case registry
│   ├── merger.ts         # Smart merge for existing .github/
│   ├── detector.ts       # Workspace tech stack detection
│   └── validator.ts      # YAML schema validation
├── templates/
│   ├── core/             # Always-installed Copilot files
│   └── gallery/          # Pre-built use case templates
└── types.ts              # Shared TypeScript types

License

MIT