forge-dev 0.1.4__tar.gz → 0.2.1__tar.gz

forge_dev-0.2.1/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.1"
+}

{forge_dev-0.1.4 → forge_dev-0.2.1}/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.2.1](https://github.com/luiskcr/forge/compare/v0.2.0...v0.2.1) (2026-04-12)
+
+
+### Features
+
+* teach CLAUDE.md and skill to handle stack conflicts explicitly ([1414623](https://github.com/luiskcr/forge/commit/141462333a918c24c928fd1dce32f25ff4ba3062))
+
+## [0.2.0](https://github.com/luiskcr/forge/compare/v0.1.4...v0.2.0) (2026-04-12)
+
+
+### ⚠ BREAKING CHANGES
+
+* removes forge status, journal, standards, upgrade, assess, mcps, sync, audit, and the context/brief/config command groups. Forge is now a 3-command compliance agent.
+
+### Features
+
+* brief command group with schema validation and context cross-check ([4e0496a](https://github.com/luiskcr/forge/commit/4e0496a301e18eb1df115d98c9d37653d13d0bfe))
+* collapse CLI to init/check/intake; file-based workflow ([623712e](https://github.com/luiskcr/forge/commit/623712eac2631505f2e8e99de007f45149496ca4))
+* ship standards and upgrade the intake prompt ([cf69a78](https://github.com/luiskcr/forge/commit/cf69a782c6f5c47be4874c1cd1dbe673c5cf5735))
+
 ## [0.1.4](https://github.com/luiskcr/forge/compare/v0.1.3...v0.1.4) (2026-04-12)
 
 

forge_dev-0.2.1/PKG-INFO

@@ -0,0 +1,181 @@
+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

forge_dev-0.2.1/README.md

@@ -0,0 +1,152 @@
+# 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