Metadata-Version: 2.4
Name: forge-dev
Version: 0.2.1
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 — Compliance Agent for AI-Assisted Development

Forge is a **compliance agent** for teams building software with AI code editors (Claude Code, Cursor, Copilot, Windsurf). It does not write code, plan features, or generate scaffolding — your AI editor already does that better. What Forge does is keep the editor *in check*: it captures your stack decisions, standards, patterns, and regulatory constraints in one place, and delivers them to the editor through the files it already reads (`CLAUDE.md`, `.claude/skills/`, `.cursorrules`, etc.).

The editor decides *what* to build and *how*. Forge enforces the *rules that must hold*.

> ⚠️ **Alpha (0.x)** — commands and file layouts may still change between releases.

## What Forge actually does

- **Captures** project-level decisions in `.forge/context.yaml` (cloud, stack, database, auth, IaC, regulatory).
- **Detects** the stack of an existing repo from `package.json`, `pyproject.toml`, `main.bicep`, `docker-compose.yml`, `.github/workflows/`, etc. Anything it can't detect is marked `unspecified` so the AI editor can fill it in.
- **Ships** opinionated standards (security, observability, type-safety, api-first, microservice-packaging) that get injected into `CLAUDE.md`.
- **Generates** `CLAUDE.md`, a Claude Code skill, and a discovery prompt from all of the above. Every session of your AI editor reads this automatically.
- **Maintains** a `.forge/journal.md` where the AI editor appends project-specific learnings across sessions.
- **Validates** everything is internally consistent with a single `forge check` command.
- **Normalizes** a requirement document (PRD, user story, conversation) into a structured brief via `forge intake`.

## What Forge does NOT do

- Plan features or produce implementation plans. That is Claude's job.
- Write or scaffold code, infrastructure, migrations, auth flows, or tests.
- Run code audits by itself. Your editor reads the standards from `CLAUDE.md` and checks files as it edits them.
- Call LLMs. Forge is pure Python and file I/O; the intelligence is in your editor.
- Replace `~/.claude/CLAUDE.md` global preferences. Forge only owns per-project files.

## Installation

Forge is published on PyPI as `forge-dev`. The recommended way is [`uv`](https://github.com/astral-sh/uv), which manages its own Python and isolates CLI tools automatically:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh    # one-time: install uv
uv tool install forge-dev
forge --version
```

<details>
<summary>Alternatives: <code>pipx</code>, <code>pip</code>, or from source</summary>

```bash
pipx install forge-dev
# or
pip install forge-dev
# or
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

```bash
uv tool upgrade forge-dev         # or: pipx upgrade forge-dev / pip install --upgrade forge-dev
```

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

## The 3 commands

| Command | What it does |
|---|---|
| `forge init` | Create or refresh the project. Detects stack, generates `CLAUDE.md`, `.claude/skills/forge/SKILL.md`, and — if anything is unclear — a `.forge/discovery_prompt.md` the editor uses to fill in the gaps. |
| `forge check` | Validate current state. Reports context completeness, brief ↔ context consistency, and registry health. Exits non-zero on critical issues. |
| `forge intake <file>` | Turn a requirement document into `.forge/intake_prompt.md`. The prompt tells the AI editor to produce `.forge/brief.yaml` in the required schema, cross-checking it against `.forge/context.yaml`. |

That's the whole surface. Everything else is file-based: edit `.forge/context.yaml`, `.forge/brief.yaml`, `.forge/journal.md`, or `~/.forge/user/standards/*.yaml` with your editor's Write/Edit tool, then run `forge init` to refresh `CLAUDE.md`.

## Typical flow

```bash
# 1. In a brand-new project
mkdir my-app && cd my-app
forge init
# → asks a few questions (mission, type, cloud, IaC, ...) if this is a greenfield repo
# → creates .forge/, CLAUDE.md, .claude/skills/forge/SKILL.md

# 2. In an existing project
cd existing-repo
forge init
# → detects backend/frontend/cloud/database/auth/IaC/CI-CD from config files
# → writes .forge/discovery_prompt.md listing fields it could not detect
# → open Claude Code / Cursor and ask it to "resolve the Forge discovery prompt"
#   the editor reads .forge/discovery_prompt.md, explores the repo, edits
#   .forge/context.yaml directly, and runs forge init to refresh CLAUDE.md

# 3. You have a requirement doc
forge intake requirements.md
# → writes .forge/intake_prompt.md for the AI editor
# → the editor produces .forge/brief.yaml (YAML matching the ForgeBrief schema)
# → run forge check to validate it against context

# 4. Before every commit / at the end of a session
forge check
# ✓ context — all fields resolved
# ✓ brief   — consistent with context
# ✓ standards — 5 core, 2 user
# All good.
```

## How the editor knows about Forge

When you run `forge init`, two files are written that your AI editor reads automatically:

- **`CLAUDE.md`** at the repo root — contains the full set of standards, stack rules, patterns, journal entries, and self-audit instructions. Claude Code reads this at the start of every session.
- **`.claude/skills/forge/SKILL.md`** — a Claude Code skill that fires whenever the editor is about to write or modify code. It tells the editor: read `CLAUDE.md`, respect every rule, append learnings to `.forge/journal.md`, and run `forge check` before declaring work complete.

Your editor does not need any new tool or MCP server to use Forge — it just reads the files Forge writes.

## Repository layout Forge creates

```
project/
├── CLAUDE.md                         ← editor instructions (do not edit manually)
├── .claude/skills/forge/SKILL.md     ← Claude Code skill
└── .forge/
    ├── context.yaml                  ← stack, cloud, auth, regulatory decisions
    ├── brief.yaml                    ← (optional) normalized requirement
    ├── journal.md                    ← project-specific learnings the editor appends
    ├── discovery_prompt.md           ← (appears when fields are unresolved)
    ├── intake_prompt.md              ← (appears after forge intake)
    └── overrides/
        └── README.md                 ← drop project-specific standard overrides here
```

And globally:

```
~/.forge/
├── core/standards/                   ← standards shipped with the installed forge_dev wheel
└── user/
    ├── config.yaml                   ← your personal defaults (all `unspecified` until you set them)
    ├── standards/*.yaml              ← standards you've added manually
    ├── patterns/*.yaml               ← approved patterns
    ├── anti-patterns/*.yaml          ← prohibited patterns
    └── mcps.yaml                     ← your MCP registry
```

## MCP server (experimental)

Forge also exposes an MCP server mirroring the CLI, so editors that speak MCP can invoke Forge operations as tools:

```bash
python -m mcp_server.server
```

The MCP surface is currently larger than the CLI (it exposes the old commands too). A minimal 3-tool version matching the CLI surface is on the roadmap.

## License

MIT
