forge-dev 0.1.3

AI-Native Development Workflow Engine

Forge — AI-Native Development Workflow Engine

Forge is a development workflow system that transforms requirements into production-ready, audited, observable code. It is designed exclusively for AI-assisted development, optimizing every step for how AI coding agents work.

Philosophy

Forge encodes a complete development paradigm — from receiving a vague requirement to deploying a fully observable SaaS application. It handles all the non-functional requirements (security, observability, auth, API design, compliance) so you can focus on business logic.

Core principles:

• Requirements in, production code out
• Strong defaults, flexible overrides
• Every project starts with everything (observability, auth, CI/CD, IaC)
• AI-coding-agent-first task ordering
• Continuous auditing — not just at the end
• API-first, MCP-ready, repackageable microservices
• The workflow evolves and versions itself

⚠️ Alpha (v0.1.0) — APIs and commands may change between releases.

Installation

Forge is published on PyPI as forge-dev. The recommended way to install it is with uv, which manages its own Python and isolates CLI tools automatically:

# 1. Install uv (one-time, if you don't have it)
curl -LsSf https://astral.sh/uv/install.sh | sh          # macOS / Linux
# Windows PowerShell:
#   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. Install forge-dev as a global tool
uv tool install forge-dev

# 3. Verify
forge --version

Alternative: pipx

pipx install forge-dev
forge --version

Alternative: plain pip

pip install forge-dev

From source (for contributors)

git clone https://github.com/luiskcr/forge.git
cd forge
pip install -e ".[dev]"

Requires Python ≥ 3.11. If you use uv, it will download a compatible Python automatically.

Updating

Use the same tool you installed with:

uv tool upgrade forge-dev        # if installed via uv (recommended)
pipx upgrade forge-dev           # if installed via pipx
pip install --upgrade forge-dev  # if installed via pip
forge --version                  # verify the new version

To pin a specific version:

uv tool install forge-dev==0.1.2 --force

Homebrew is not supported. Forge is distributed exclusively via PyPI.

Note for macOS users on Tahoe (macOS 26): the Homebrew bottles for python@3.13 and python@3.14 currently ship a broken pyexpat module (a libexpat symbol mismatch) that breaks pip, pipx and venv. If you hit ImportError: Symbol not found: _XML_SetAllocTrackerActivationThreshold, use uv instead — it bundles its own Python and avoids the issue entirely.

How Forge Works

Forge is a governance layer that sits between you and your AI coding agent. It does not call LLMs itself — instead, it:

1. Captures decisions about your project (stack, cloud, auth, regulatory constraints) in .forge/context.yaml
2. Normalizes requirements into a structured brief (.forge/brief.yaml)
3. Generates prompts and artifacts that your editor (Claude Code, Cursor, Copilot, etc.) consumes
4. Translates all that knowledge into a CLAUDE.md / .cursorrules / equivalent via forge sync, so the editor automatically reads and follows your standards

The result: one source of truth for "how we build" that every AI assistant on the project reads.

Typical Workflow

# 1. Initialize (inside the project folder)
cd my-new-project
forge init
#   → asks about mission, stack, regulatory requirements
#   → writes .forge/context.yaml and .forge/journal.md

# 2. Process a requirement document (optional)
forge intake requirements.md
#   → classifies the requirement (PRD / user story / epic)
#   → produces .forge/intake_prompt.md for LLM analysis
#   → the LLM response becomes .forge/brief.yaml

# 3. Generate editor instructions from Forge governance
forge sync --format claude           # writes CLAUDE.md
forge sync --format cursor           # writes .cursorrules
forge sync --format all              # all supported editors

# 4. Let the AI editor build the feature
#    (Claude Code / Cursor will read CLAUDE.md automatically)

# 5. Audit what was built against standards
forge audit src/api/users.py         # single file
forge audit --full                   # entire project
#    → writes .forge/audit/*.md audit prompts for the LLM to execute

# 6. Record project-specific learnings
forge journal "Azure Postgres requires pg_bouncer tunnel for local dev"

# 7. Check state anytime
forge status

Existing projects

cd my-existing-project
forge init      # detects stack from package files
forge assess    # maturity report against current standards

Managing standards

Standards live in ~/.forge/user/standards/ (yours) and ~/.forge/core/standards/ (shipped). Add your own:

forge standards \
  --name "API Versioning" \
  --area "api-design" \
  --description "All public APIs must use URL-prefix versioning (e.g., /v1/users)"

New standards go through a coherence check before being accepted — conflicts with existing standards are surfaced as errors.

AI-Optimized Implementation Order

When Forge generates a plan, it orders work to minimize AI agent hallucinations — each phase has the full output of previous phases as context:

1. Types & Contracts (Pydantic, TypeScript interfaces, OpenAPI schemas)
2. Infrastructure (IaC, environment configs, secret references)
3. Auth & Security (auth flows, RBAC, middleware)
4. Data Layer (ORM models, migrations, repositories)
5. Core Services (business logic, no HTTP concerns)
6. API Layer (endpoints, OpenAPI-documented, MCP-ready)
7. Frontend (components, pages, state management)
8. Observability (APM, metrics, logs, dashboards, AI tracking)
9. Testing (unit, integration, E2E)
10. CI/CD & Deploy (pipelines, IaC execution, smoke tests)

Default Stack

Defaults live in ~/.forge/user/config.yaml and can be overridden per-project:

Layer	Default
Cloud	Azure
Backend	Ask each time (FastAPI / Django / Express / Fastify / NestJS)
Frontend	React
Database	PostgreSQL
Auth	Azure AD B2C
Observability	App Insights + Prometheus + Loki + Grafana
API	REST, OpenAPI 3.1, MCP-ready, URL-prefix versioning
CI/CD	GitHub Actions + Pulumi

Commands

Command	Description
forge init	Initialize Forge in a project (detects context automatically)
forge intake <file>	Process a requirement document into a Forge Brief
forge sync --format <editor>	Generate editor instruction file (claude, cursor, copilot, generic, all)
forge audit [files] [--full]	Build audit prompts for files or the entire project
forge assess	Evaluate existing project against current standards
forge journal <entry>	Add learnings/nuances to project journal
forge standards --name ... --area ... --description ...	Add a new standard (coherence-checked)
forge status	Show current project state
forge mcps	View the MCP registry
forge upgrade	Update Forge core from upstream (planned)

Architecture

~/.forge/                          ← Global Forge installation
├── core/                          ← Upstream (updated via forge upgrade)
│   ├── VERSION
│   ├── phases/                    ← Workflow phase definitions
│   ├── agents/                    ← Audit agent configurations
│   ├── templates/                 ← Project scaffold templates
│   └── standards/                 ← Base standards
├── user/                          ← Your customizations (never touched by upgrade)
│   ├── config.yaml                ← Your defaults (cloud, stack, preferences)
│   ├── standards/                 ← Standards you've added
│   ├── patterns/                  ← Approved patterns with code examples
│   ├── anti-patterns/             ← Things to never do
│   ├── mcps.yaml                  ← Your MCP registry
│   └── history/                   ← Project history and learnings

project/.forge/                    ← Per-project Forge state
├── context.yaml                   ← Stack, infra, decisions
├── brief.md                       ← Normalized requirement
├── plan.yaml                      ← AI-optimized implementation plan
├── journal.md                     ← Project-specific learnings
├── overrides/                     ← Local standard overrides
├── audit/                         ← Audit logs
└── maturity.yaml                  ← Assessment results

MCP Server

Forge also runs as an MCP server, making the same operations available as tools to any MCP-compatible editor (Claude Code, Cursor, Copilot, Windsurf):

python -m mcp_server.server

Exposed tools mirror the CLI: forge_init, forge_intake, forge_status, forge_audit, forge_assess, forge_journal, forge_standards, forge_coherence_check, forge_mcps.

License

MIT