Metadata-Version: 2.4
Name: forge-dev
Version: 0.1.4
Summary: AI-Native Development Workflow Engine
Author: NaiaTech
License-Expression: MIT
Keywords: ai,development,mcp,scaffold,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.11
Requires-Dist: click>=8.1.0
Requires-Dist: gitpython>=3.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: jinja2>=3.1
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# 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`](https://github.com/astral-sh/uv), which manages its own Python and isolates CLI tools automatically:

```bash
# 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
```

<details>
<summary>Alternative: <code>pipx</code></summary>

```bash
pipx install forge-dev
forge --version
```

</details>

<details>
<summary>Alternative: plain <code>pip</code></summary>

```bash
pip install forge-dev
```

</details>

<details>
<summary>From source (for contributors)</summary>

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

</details>

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

### Updating

Use the same tool you installed with:

```bash
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:

```bash
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

```bash
# 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

```bash
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:

```bash
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):

```bash
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
