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

{forge_dev-0.1.2 → forge_dev-0.1.4}/.github/workflows/release-please.yml

@@ -15,5 +15,6 @@ jobs:
     steps:
       - uses: googleapis/release-please-action@v4
         with:
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
           config-file: .release-please-config.json
           manifest-file: .release-please-manifest.json

{forge_dev-0.1.2 → forge_dev-0.1.4}/.gitignore

@@ -12,3 +12,4 @@ build/
 venv/
 .env
 *.log
+CLAUDE.md

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

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

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

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.1.4](https://github.com/luiskcr/forge/compare/v0.1.3...v0.1.4) (2026-04-12)
+
+
+### Features
+
+* refresh flow for already-initialized projects + config commands ([fae7242](https://github.com/luiskcr/forge/commit/fae7242072b5dfa6ae23c40bd601b906cc122ab2))
+
+## [0.1.3](https://github.com/luiskcr/forge/compare/v0.1.2...v0.1.3) (2026-04-12)
+
+
+### Documentation
+
+* recommend uv as install method and document macOS Tahoe pyexpat issue ([292518a](https://github.com/luiskcr/forge/commit/292518a01ca7d546fa892a4618cced8033290524))
+
 ## [0.1.2](https://github.com/luiskcr/forge/compare/v0.1.1...v0.1.2) (2026-04-12)
 
 

{forge_dev-0.1.2 → forge_dev-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: forge-dev
-Version: 0.1.2
+Version: 0.1.4
 Summary: AI-Native Development Workflow Engine
 Author: NaiaTech
 License-Expression: MIT
@@ -48,35 +48,73 @@ Forge encodes a complete development paradigm — from receiving a vague require
 
 ## 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
 ```
 
-Or install from source:
+</details>
+
+<details>
+<summary>From source (for contributors)</summary>
 
 ```bash
 git clone https://github.com/luiskcr/forge.git
 cd forge
-pip install -e .
+pip install -e ".[dev]"
 ```
 
-Requires Python ≥ 3.11.
+</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
-pip install --upgrade forge-dev          # latest stable
-pip install --upgrade forge-dev==0.1.2   # pin a specific version
-forge --version                          # verify
+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
 ```
 
-If you installed with `pipx`:
+To pin a specific version:
 
 ```bash
-pipx upgrade forge-dev
+uv tool install forge-dev==0.1.2 --force
 ```
 
-> Homebrew is not supported yet — Forge is distributed exclusively via PyPI.
+> **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_dev-0.1.2 → forge_dev-0.1.4}/README.md

@@ -19,35 +19,73 @@ Forge encodes a complete development paradigm — from receiving a vague require
 
 ## 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
 ```
 
-Or install from source:
+</details>
+
+<details>
+<summary>From source (for contributors)</summary>
 
 ```bash
 git clone https://github.com/luiskcr/forge.git
 cd forge
-pip install -e .
+pip install -e ".[dev]"
 ```
 
-Requires Python ≥ 3.11.
+</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
-pip install --upgrade forge-dev          # latest stable
-pip install --upgrade forge-dev==0.1.2   # pin a specific version
-forge --version                          # verify
+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
 ```
 
-If you installed with `pipx`:
+To pin a specific version:
 
 ```bash
-pipx upgrade forge-dev
+uv tool install forge-dev==0.1.2 --force
 ```
 
-> Homebrew is not supported yet — Forge is distributed exclusively via PyPI.
+> **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_dev-0.1.2 → forge_dev-0.1.4}/forge_core/cli.py

@@ -28,22 +28,127 @@ def main() -> None:
     pass
 
 
+def _refresh_initialized_project(project_path: Path, detection) -> None:
+    """Refresh an already-initialized project.
+
+    Called when `forge init` runs on a directory that already has `.forge/`.
+    Keeps the existing context as the source of truth, but:
+    - Tops up any UNSPECIFIED fields that the current detector can now resolve
+      (e.g., the user added a main.bicep since last init)
+    - Regenerates the Claude Code skill and discovery prompt (Forge-owned)
+    - Generates CLAUDE.md if it was deleted, but never overwrites a custom one
+    - Ensures .forge/overrides/ exists
+    """
+    from forge_core.editor_bridge import collect_unspecified_fields, write_editor_file
+    from forge_core.phases.context import load_context, save_context
+
+    ctx = load_context(project_path)
+    if ctx is None:
+        console.print(
+            "[red].forge/context.yaml is missing or unreadable. "
+            "Run `forge init --force` to recreate.[/red]"
+        )
+        return
+
+    # Top up unspecified fields from current detection
+    detected = detection.detected_stack or {}
+    topped_up: list[str] = []
+    mapping = {
+        "cloud": ("cloud", ctx.cloud.value),
+        "backend": ("backend", ctx.backend.value),
+        "frontend": ("frontend", ctx.frontend.value),
+        "database": ("database", ctx.database.value),
+        "auth": ("auth", ctx.auth.value),
+    }
+    ctx_data = ctx.model_dump(mode="json")
+    for det_key, (ctx_key, current) in mapping.items():
+        if current == "unspecified" and det_key in detected:
+            ctx_data[ctx_key] = detected[det_key]
+            topped_up.append(f"{ctx_key}={detected[det_key]}")
+    # CICD nested
+    if ctx_data.get("cicd", {}).get("iac") == "unspecified" and "iac" in detected:
+        ctx_data["cicd"]["iac"] = detected["iac"]
+        topped_up.append(f"cicd.iac={detected['iac']}")
+    if ctx_data.get("cicd", {}).get("provider") == "unspecified" and "cicd" in detected:
+        ctx_data["cicd"]["provider"] = detected["cicd"]
+        topped_up.append(f"cicd.provider={detected['cicd']}")
+
+    if topped_up:
+        from forge_core.models import ProjectContext
+        try:
+            ctx = ProjectContext(**ctx_data)
+            save_context(ctx, project_path)
+        except Exception as exc:
+            console.print(f"[red]Could not persist detected fields: {exc}[/red]")
+
+    # Ensure overrides/
+    overrides_dir = project_path / ".forge" / "overrides"
+    overrides_dir.mkdir(parents=True, exist_ok=True)
+
+    # Regenerate editor files
+    claude_path = project_path / "CLAUDE.md"
+    if not claude_path.exists():
+        write_editor_file(project_path, ctx, "claude")
+        claude_status = "[green]generated[/green]"
+    else:
+        # Don't overwrite a customized CLAUDE.md, but refresh OTHER editor files
+        # that already exist (cursor, copilot, etc.)
+        from forge_core.editor_bridge import sync_editor_file
+        sync_editor_file(project_path, ctx)
+        claude_status = "[dim]kept (customized or existing)[/dim]"
+
+    write_editor_file(project_path, ctx, "skill")
+
+    remaining = collect_unspecified_fields(ctx)
+    discovery_file = project_path / ".forge" / "discovery_prompt.md"
+    if remaining:
+        write_editor_file(project_path, ctx, "discovery")
+    elif discovery_file.exists():
+        discovery_file.unlink()
+
+    # Summary
+    lines = [
+        "[green]✓ Forge refreshed[/green]",
+        "",
+        f"Project: [bold]{ctx.name}[/bold]",
+        f"CLAUDE.md: {claude_status}",
+    ]
+    if topped_up:
+        lines.append(f"[green]Detected new:[/green] {', '.join(topped_up)}")
+    if remaining:
+        fields = ", ".join(f"`{r['key']}`" for r in remaining)
+        lines.append(f"[yellow]Still unspecified:[/yellow] {fields}")
+        lines.append("Read `.forge/discovery_prompt.md` in your AI editor.")
+    else:
+        lines.append("[green]All context fields resolved.[/green]")
+    lines.append("")
+    lines.append("Tip: use `forge init --force` to wipe context and re-run from scratch.")
+
+    console.print(Panel("\n".join(lines), title="🔄 Refreshed", border_style="green"))
+
+
 @main.command()
 @click.option("--name", "-n", help="Project name (default: directory name)")
 @click.option("--backend", "-b", help="Backend framework override")
 @click.option("--no-interactive", is_flag=True, help="Skip interactive questions")
-def init(name: str | None, backend: str | None, no_interactive: bool) -> None:
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Wipe existing .forge/context.yaml and re-run init from scratch",
+)
+def init(name: str | None, backend: str | None, no_interactive: bool, force: bool) -> None:
     """Initialize Forge in the current directory.
-    
+
     Detects the project state and adapts:
     - Empty folder → guided setup conversation
     - Has docs → analyzes documents, generates brief
     - Has code → detects stack, offers assessment
-    - Has .forge/ → offers to continue or re-evaluate
+    - Has .forge/ → refresh editor files + re-run detection (use --force to reset)
     """
     from forge_core.detector import detect_project
     from forge_core.phases.context import (
         get_questions_for_empty_project,
+        load_context,
         resolve_context,
         save_context,
     )
@@ -65,14 +170,29 @@ def init(name: str | None, backend: str | None, no_interactive: bool) -> None:
     ))
     console.print()
 
-    if detection.has_forge:
-        console.print("[yellow]This project already has Forge initialized.[/yellow]")
-        console.print("Options:")
-        console.print("  forge status    — see current state")
-        console.print("  forge assess    — re-evaluate against latest standards")
-        console.print("  forge audit     — run audit agents")
+    if detection.has_forge and not force:
+        # Refresh mode: keep existing context, top up any newly detectable fields,
+        # regenerate editor files (skill, discovery prompt, CLAUDE.md if missing).
+        _refresh_initialized_project(project_path, detection)
         return
 
+    if detection.has_forge and force:
+        # Wipe context.yaml so the rest of the function proceeds as a fresh init.
+        (project_path / ".forge" / "context.yaml").unlink(missing_ok=True)
+        console.print("[yellow]--force: existing .forge/context.yaml removed.[/yellow]")
+        detection.has_forge = False
+        detection.forge_context_path = None
+        # Re-evaluate state so the branching below picks the right path
+        if detection.code_files or detection.config_files:
+            from forge_core.models import ProjectState
+            detection.state = ProjectState.HAS_CODE
+        elif detection.doc_files:
+            from forge_core.models import ProjectState
+            detection.state = ProjectState.HAS_DOCS
+        else:
+            from forge_core.models import ProjectState
+            detection.state = ProjectState.EMPTY
+
     if detection.is_empty:
         console.print("[cyan]Empty directory detected. Let's set up your project.[/cyan]")
         console.print()
@@ -633,6 +753,104 @@ def audit(files: tuple[str, ...], full: bool) -> None:
         )
 
 
+@main.group()
+def config() -> None:
+    """Manage the global Forge user config (~/.forge/user/config.yaml)."""
+    pass
+
+
+@config.command("show")
+def config_show() -> None:
+    """Print the current global user config."""
+    import yaml as _yaml
+
+    from forge_core.registry import USER_DIR
+
+    config_path = USER_DIR / "config.yaml"
+    if not config_path.exists():
+        console.print(f"[yellow]No config at {config_path}[/yellow]")
+        return
+    console.print(_yaml.dump(_yaml.safe_load(config_path.read_text()), sort_keys=False))
+
+
+@config.command("reset")
+@click.option("--yes", is_flag=True, help="Skip confirmation")
+def config_reset(yes: bool) -> None:
+    """Regenerate ~/.forge/user/config.yaml with current defaults.
+
+    Use this after upgrading Forge if you're seeing stale options (e.g. the
+    config was written by an older version with hardcoded defaults like
+    `iac: pulumi`). The new defaults leave all stack fields as `unspecified`,
+    so you decide per-project or via `forge config set`.
+    """
+    from forge_core.registry import USER_DIR, _write_default_user_config  # type: ignore
+
+    config_path = USER_DIR / "config.yaml"
+    if config_path.exists() and not yes:
+        if not click.confirm(
+            f"Overwrite {config_path} with the current Forge defaults?",
+            default=False,
+        ):
+            console.print("[yellow]Cancelled.[/yellow]")
+            return
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    _write_default_user_config(config_path)
+    console.print(f"[green]✓ {config_path} regenerated.[/green]")
+    console.print(
+        "[dim]All stack fields are now `unspecified` — project init will "
+        "ask you or detect them from the code.[/dim]"
+    )
+
+
+@config.command("set")
+@click.argument("assignments", nargs=-1, required=True)
+def config_set(assignments: tuple[str, ...]) -> None:
+    """Set global defaults: `forge config set cloud=azure cicd.iac=bicep`."""
+    import yaml as _yaml
+
+    from forge_core.registry import USER_DIR
+
+    config_path = USER_DIR / "config.yaml"
+    data = _yaml.safe_load(config_path.read_text()) if config_path.exists() else {}
+
+    updated: list[str] = []
+    for assignment in assignments:
+        if "=" not in assignment:
+            console.print(f"[red]✗ '{assignment}' — expected key=value[/red]")
+            continue
+        key, raw = assignment.split("=", 1)
+        key = key.strip()
+        value: object = raw.strip()
+        if value in ("true", "True"):
+            value = True
+        elif value in ("false", "False"):
+            value = False
+        parts = key.split(".")
+        target = data
+        for p in parts[:-1]:
+            target = target.setdefault(p, {})
+        target[parts[-1]] = value
+        updated.append(f"{key}={raw}")
+
+    if not updated:
+        sys.exit(1)
+
+    # Validate by loading through UserConfig
+    from forge_core.models import UserConfig
+    try:
+        UserConfig(**data)
+    except Exception as exc:
+        console.print(f"[red]✗ Validation failed:[/red] {exc}")
+        sys.exit(1)
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(config_path, "w") as f:
+        _yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+    for u in updated:
+        console.print(f"[green]✓ {u}[/green]")
+
+
 @main.group()
 def context() -> None:
     """Inspect or update the project context (.forge/context.yaml).

{forge_dev-0.1.2 → forge_dev-0.1.4}/forge_core/registry.py

@@ -186,16 +186,28 @@ def version_workflow(change_description: str) -> str:
 # ── Private helpers ────────────────────────────────────────────────────────
 
 def _write_default_user_config(path: Path) -> None:
-    """Write the default user config with Luis's preferences."""
+    """Write the default user config with no opinionated choices.
+
+    All stack fields default to UNSPECIFIED so Forge never silently assumes
+    a cloud / IaC / auth / database choice. The user sets their preferences
+    explicitly with `forge config set key=value` (or by editing this file).
+
+    The non-stack fields (observability, api, ai) keep reasonable technical
+    defaults that don't lock the user into a vendor.
+    """
     config = UserConfig(
-        cloud="azure",
+        cloud="unspecified",
         backend=None,  # Ask each time
-        frontend="react",
-        database="postgresql",
-        auth="azure-ad-b2c",
-        ai={"enabled": True, "providers": ["anthropic", "openai"], "observability": True},
+        frontend="unspecified",
+        database="unspecified",
+        auth="unspecified",
+        ai={
+            "enabled": False,
+            "providers": [],
+            "observability": True,
+        },
         observability={
-            "apm": "azure-app-insights",
+            "apm": "unspecified",
             "metrics": "prometheus",
             "logs": "loki",
             "dashboards": "grafana",
@@ -207,8 +219,8 @@ def _write_default_user_config(path: Path) -> None:
             "versioning": "url-prefix",
         },
         cicd={
-            "provider": "github-actions",
-            "iac": "pulumi",
+            "provider": "unspecified",
+            "iac": "unspecified",
             "environments": ["dev", "staging", "production"],
         },
         standards={

{forge_dev-0.1.2 → forge_dev-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forge-dev"
-version = "0.1.2"
+version = "0.1.4"
 description = "AI-Native Development Workflow Engine"
 readme = "README.md"
 license = "MIT"

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

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

forge_dev-0.1.2/CLAUDE.md

@@ -1,81 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project
-
-Forge is an **AI-Native Development Workflow Engine** — a Python CLI + MCP server that transforms requirements into production-ready code. It generates prompts and structured artifacts (briefs, plans, audit reports) that are consumed by LLM-backed editors (Claude Code, Cursor, Copilot). Forge itself does not call LLMs; it prepares and orchestrates the context.
-
-Published to PyPI as `forge-dev`. Installed binary is `forge`.
-
-## Commands
-
-```bash
-# Install for local dev (editable)
-pip install -e ".[dev]"
-
-# Run the CLI
-forge --help
-forge init                    # initialize .forge/ in cwd
-forge status                  # show project state
-forge sync --format claude    # generate CLAUDE.md from Forge governance
-forge audit --full            # build audit prompt for entire project
-forge intake <file>           # process requirement doc into a brief
-
-# Run the MCP server
-python -m mcp_server.server
-
-# Quality gates
-ruff check .
-ruff format .
-mypy forge_core mcp_server
-pytest                        # testpaths = ["tests"] (no tests yet)
-pytest tests/path/to/test.py::test_name   # single test
-
-# Release (trusted publishing via GitHub Actions)
-# 1. bump version in forge_core/__init__.py AND pyproject.toml
-# 2. gh release create vX.Y.Z --title "..." --notes "..."
-# → .github/workflows/publish.yml builds and publishes to PyPI automatically
-```
-
-Python ≥3.11, ruff line-length 100, mypy strict mode.
-
-## Architecture
-
-Forge has **three persistence layers** — understand these before touching code that reads/writes state:
-
-1. **`~/.forge/`** — global registry (managed by `forge_core/registry.py`)
-   - `core/`: upstream definitions (phases, agents, templates, standards) — updated via `forge upgrade`
-   - `user/`: user customizations that must survive upgrades (standards, patterns, anti-patterns, mcps.yaml, config.yaml, history)
-   - `versions/`: workflow version snapshots
-   - **Invariant**: `forge upgrade` must never touch `user/`; project `.forge/` dirs are never touched by any global operation.
-
-2. **`<project>/.forge/`** — per-project state
-   - `context.yaml` (stack/cloud/auth decisions), `brief.yaml`, `plan.yaml`, `journal.md`, `audit/*.md`, `maturity.yaml`
-   - Created by `forge init`, read by every other command.
-
-3. **Editor bridge output** — `CLAUDE.md`, `.cursorrules`, etc. generated from (1)+(2) by `forge sync`. This is the *delivery mechanism* — Forge's entire value is translating governance into something the editor reads automatically.
-
-### Module layout
-
-- `forge_core/cli.py` — Click command group; every subcommand lazy-imports its dependencies to keep `forge --help` fast. Each command is thin glue that calls into phases/auditor/editor_bridge.
-- `forge_core/registry.py` — sole owner of `~/.forge/`. Everything that reads or writes the global registry goes through here (`ensure_registry`, `load_user_config`, `load_standards`, `load_mcps`, `record_project`, `version_workflow`).
-- `forge_core/detector.py` — inspects a directory and classifies it (`is_empty` / `has_docs` / `has_existing_code` / `has_forge`). Drives the branching in `forge init`.
-- `forge_core/models.py` — Pydantic models for context, briefs, standards, MCPs, enums (Backend, Cloud, Auth, Regulatory, etc.). Serialization contract between all layers; breaking these changes all persisted state.
-- `forge_core/phases/` — one module per workflow phase. Each phase produces an artifact in `.forge/`:
-  - `context.py` → `context.yaml` (+ `get_questions_for_empty_project`, `resolve_context`)
-  - `intake.py` → `brief.yaml` (+ classification, prompt builder)
-  - `coherence.py` → validates new standards against existing ones before they're added
-- `forge_core/auditor.py` — builds audit prompts (file-scoped and full-project) from context + standards. Does not execute audits; writes prompts to `.forge/audit/` for the LLM editor to consume.
-- `forge_core/editor_bridge.py` — central translator: (context + standards + patterns + journal) → editor-specific instruction file. Add new editor formats here; `cli.py sync` just dispatches by format name.
-- `forge_core/standards/*.yaml` — shipped baseline standards (security, observability, type-safety, api-first, microservice-packaging). These seed `~/.forge/core/standards/` on first run.
-- `mcp_server/server.py` — `FastMCP` wrapper exposing the same operations as MCP tools (`forge_init`, `forge_intake`, `forge_audit`, etc.). Input models use `extra="forbid"`; mirror CLI semantics exactly.
-- `claude_skill/SKILL.md` — Claude Code skill definition that teaches the agent when to invoke Forge.
-
-### Key design rules
-
-- **Forge builds prompts; LLMs run them.** Commands like `intake`, `audit`, `assess` write a `*_prompt.md` file rather than calling an LLM. Don't add LLM client code to `forge_core`.
-- **Phases write artifacts, commands are glue.** If you're tempted to put logic in `cli.py`, it probably belongs in a phase module or `editor_bridge.py`.
-- **Registry paths live in `registry.py` only.** Don't hardcode `~/.forge/...` elsewhere; import `FORGE_HOME`, `CORE_DIR`, `USER_DIR`.
-- **CLI imports are lazy inside command bodies** (see `cli.py`) — preserve this to keep startup fast. Don't hoist imports to module top.
-- **Standards are YAML, loaded by name.** Adding a new built-in standard = drop a YAML in `forge_core/standards/` matching the existing shape; no code change.