forge-dev 0.2.1

AI-Native Development Workflow Engine

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, which manages its own Python and isolates CLI tools automatically:

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

Alternatives: pipx, pip, or from source

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

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

# 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:

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