Forge.Cli 1.0.1

Forge

Pattern-driven AI build orchestrator. Forge is a dotnet CLI tool that orchestrates AI coding agents through sprint-based development workflows. Define your project's build commands, test runners, and coding conventions in a Stack Profile (YAML), write a Sprint Spec describing what to build, and Forge drives the AI through a complete 10-phase pipeline — iterating automatically until acceptance criteria pass.

Highlights

• Multi-AI support — Claude, Codex, and Gemini drivers with per-phase engine selection and automatic fallback
• Structured output parsing — MSBuild, TSC, Cargo, Python, TRX, JUnit, and Vitest parsers turn raw build/test output into structured errors and results
• Sprint memory — Forge learns from patterns, failures, and hotspots across iterations
• MCP server — Expose Forge as tools for AI agents via the Model Context Protocol
• Profile marketplace — Import community profiles with forge profile import user/repo
• Changeset testing — AI-generated edge cases, selective tests, and live API/UI testing

Quick Start

# Install (requires .NET 10 SDK)
dotnet tool install -g Forge.Cli

# Initialize a profile in your project
cd your-project
forge init

# Run a sprint
forge run --sprint-spec sprint.md

# Check progress
forge status

# View results
forge report

How It Works

Forge executes a 10-phase pipeline for each sprint:

Sprint Spec (markdown)  +  Stack Profile (YAML)
                    |
          +---------+---------+
          |  1. Analyze       |  Parse requirements, detect project type
          |  2. Plan          |  AI creates implementation strategy
          |  3. Implement     |  AI writes code per plan
          |  4. Build         |  Compile, parse errors
          |  5. Test          |  Run tests, parse results
          |  6. TestChangeset |  Selective + edge case + live tests
          |  7. Verify        |  Lint, format, pre-commit checks
          |  8. Review        |  AI reviews changes for quality
          |  9. Evaluate      |  Check acceptance criteria
          | 10. Commit        |  Git commit with AI-generated message
          +---------+---------+
                    |
          Done (or iterate if fixes needed)

If build or tests fail, Forge loops back to fix issues automatically. You set the max iterations.

Stack Profiles

A Stack Profile tells Forge how your project works. It defines discovery patterns, build/test commands, result parsers, AI permissions, and git behavior.

Forge ships with built-in profiles for common stacks:

Using a Built-in Profile

# Auto-detect your project and copy the matching profile
forge init

# Or specify a built-in profile by name
forge init --profile dotnet-clean-arch

Example Profile

name: dotnet-clean-arch
description: ".NET Clean Architecture — modular monolith with xUnit testing"

# Discovery: how Forge finds and understands your project
discovery:
  solutionFile: "*.sln"           # Glob pattern for the solution/project file
  sourceDirs:
    - src                          # Directories containing source code
  testDirs:
    - tests                        # Directories containing tests
  conventionsFile: CLAUDE.md       # Coding conventions passed to the AI

# Build: compilation command and error parser
build:
  command: dotnet build --verbosity minimal
  successPattern: "Build succeeded"   # Optional string to confirm success
  errorParser: msbuild                # Parser for structured error extraction

# Test: test runner command and result parser
test:
  command: dotnet test --logger trx --results-directory ./test-results
  resultFormat: trx                   # Parser for structured test results
  resultPath: "./test-results/**/*.trx"  # Where to find result files

# Verify: optional pre-commit checks (linting, formatting)
verify:
  - name: format-check
    command: dotnet format --verify-no-changes
    onFailure: fix                    # "fail" to stop, "fix" to auto-repair
    fixCommand: dotnet format

# AI: permissions and context for the AI driver
ai:
  systemContext: >
    This is a .NET solution following Clean Architecture conventions.
  permissions:
    plan: [Read, Glob, Grep]
    review: [Read, Glob, Grep]
    implement: [Read, Edit, Write, Glob, Grep, Bash]
  denied: [git push, curl, wget, dotnet publish]

# Git: version control behavior
git:
  commitFormat: conventional          # "conventional" or "semantic"
  autoCommit: true                    # Commit after successful iterations
  branchPrefix: "forge/"             # Branch naming prefix

Profile Sections

Profile Marketplace

Browse and import community profiles:

# List built-in profiles
forge profile list

# Import from a GitHub repo
forge profile import octocat/forge-profiles

# Import from a URL with a specific path
forge profile import https://github.com/user/repo/tree/main/profiles/custom

# Validate a profile
forge profile validate .forge/profile.yaml

See the awesome-forge-profiles template for creating a community profile gallery.

Sprint Specs

A Sprint Spec is a markdown file that describes what you want the AI to build. Forge parses it to extract acceptance criteria that drive the pipeline.

Example Sprint Spec

# Sprint: Add User Authentication

## Context
The API currently has no authentication. We need JWT-based auth
using the existing User entity in the Domain layer.

## Deliverables

### Authentication Endpoints
- [ ] AC-001: POST /api/auth/login returns a JWT token for valid credentials
- [ ] AC-002: POST /api/auth/register creates a new user and returns a token
- [ ] AC-003: Invalid credentials return 401 with an error message

### Authorization Middleware
- [ ] AC-004: Protected endpoints return 401 without a valid token
- [ ] AC-005: Token expiration is configurable via appsettings.json

## Notes
Use BCrypt for password hashing. Do not add any third-party auth providers.

Sprint Spec Format

• ## Context / ## Background — Background information passed to the AI as-is
• ## Deliverables / ## Features — Contains acceptance criteria grouped by ### headings
• - [ ] text — An acceptance criterion (unchecked = not yet met)
• - [x] text — A criterion already met (pre-checked)
• AC-NNN: prefix — Optional ID for tracking (e.g., AC-001)
• ## Notes — Implementation hints, constraints, or warnings

CLI Reference

Dry Run Mode

Use --dry-run to preview what Forge would do without making changes:

forge run --sprint-spec sprint.md --dry-run

This runs only the Analyze and Plan phases, showing the planned tasks and acceptance criteria mapping. No files are modified and no git commits are made.

Pause and Resume

Forge saves pipeline state to .forge/state.json after each phase. If interrupted (Ctrl+C) or if max iterations are reached, you can resume:

forge run --continue

Creating Custom Profiles

1. Start from a built-in profile:

   forge init --profile dotnet-clean-arch
   

   This copies the profile to .forge/profile.yaml where you can customize it.

2. Or create from scratch. A minimal profile needs only build and test:

   name: my-project
   description: "My custom project profile"
   
   discovery:
     solutionFile: "*.sln"
     sourceDirs: [src]
     testDirs: [tests]
   
   build:
     command: dotnet build
     errorParser: msbuild
   
   test:
     command: dotnet test --logger trx --results-directory ./test-results
     resultFormat: trx
     resultPath: "./test-results/**/*.trx"
   
   git:
     commitFormat: conventional
     autoCommit: true
     branchPrefix: "forge/"
   

3. Choose the right parsers for your stack:

   Build Error Parser	For
   msbuild	.NET (C#, VB.NET, F#)
   tsc	TypeScript
   cargo	Rust
   python	Python
   generic	Any other tool (regex-based fallback)

   Test Result Parser	For
   trx	.NET test output (xUnit, NUnit, MSTest via --logger trx)
   junit	JUnit XML (Maven, Gradle, pytest via --junitxml)
   vitest-json	Vitest JSON reporter
   generic	Any other tool (counts pass/fail from text output)

4. Configure AI permissions to control what tools the AI can use in each phase:

   ai:
     permissions:
       plan: [Read, Glob, Grep]           # Read-only for planning
       review: [Read, Glob, Grep]         # Read-only for review
       implement: [Read, Edit, Write, Glob, Grep, Bash]  # Full access for implementation
     denied: [git push, curl, wget]       # Never allow these
   

5. Add verification steps for linting or formatting:

   verify:
     - name: lint
       command: npm run lint
       onFailure: fix          # "fail" stops the pipeline, "fix" runs fixCommand
       fixCommand: npm run lint:fix
   

MCP Server

Forge includes an MCP (Model Context Protocol) server that allows AI agents to interact with Forge programmatically. Start it with:

forge mcp start

This exposes tools like forge_run, forge_status, forge_criteria, forge_report, and memory management tools via JSON-RPC over stdio. Use --read-only to restrict to inspection tools only.

Architecture

Forge follows Clean Architecture with strict dependency isolation:

Forge.Cli (composition root)
  -> Forge.Claude (AI driver implementations: Claude, Codex, Gemini)
  -> Forge.Builders (parsers, command runners, project analyzers)
  -> Forge.Mcp (MCP server for AI agent integration via JSON-RPC)
  -> Forge.Core (abstractions, pipeline engine, models)

Dependencies flow inward only. Forge.Core has zero references to Forge.Claude, Forge.Builders, or Forge.Mcp — it defines interfaces (IAiDriver, IResultParser, IBuildErrorParser) that outer layers implement. This makes the pipeline engine AI-agnostic and build-system-agnostic.

Requirements

• .NET 10 SDK or later
• Git
• Claude Code (for the AI driver)

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT