Skip to main content

Forge

Forge is a Python CLI and framework for V4 system design and delivery. It keeps C1/C2 architecture central, keeps C3 implementation architecture beside code, and gives skills narrow context from the merged model.

Forge is skills-first. The skills drive the work. The CLI exists to provide scoped context, validation, and audit artifacts to the active skill.

What This Repository Contains

  • src/cli: the Forge CLI implementation
  • skills/: the Forge skill source used by initialized repositories
  • FRAMEWORK_V4.md: the V4 framework process used to seed forge/FRAMEWORK_V4.md
  • SCHEMA_REFERENCE_V4.md: the V4 schema contract used to seed forge/SCHEMA_REFERENCE_V4.md
  • examples/: example Forge repositories and audit artifacts

CLI Commands

  • forge init: scaffold a new Forge workspace and explain how to use it
  • forge crawl: extract the merged V4 model from central files and code annotations
  • forge context: render scoped context for a system, flow, container, entity, component, operation, or data shape
  • forge knowledge: list supporting Markdown knowledge docs attached to Forge refs such as containers, flows, entities, components, and operations
  • forge update skills: refresh only forge/skills/ using conflict-safe manifests
  • forge audit: generate a self-contained architecture audit dashboard

What Forge Is

  • a framework for capturing architectural truth before implementation detail
  • a skills-first workflow for moving from business discovery to a flow-complete delivery outcome
  • a scoped context generator for build, review, and security tasks
  • an audit artifact generator for human review
  • a lightweight index for repo-native delivery knowledge such as runbooks, testing notes, security notes, operations notes, and domain glossaries

What Forge Is Not

  • a generic project scaffolder for arbitrary app stacks
  • a replacement for implementation skills such as build, review, and security
  • a reason to model every payload, component, or environment detail up front
  • a reason to widen scope beyond an approved, coherent and verifiable outcome
  1. Run forge init in an empty repository.
  2. Read:
    • forge/USING_FORGE.md
    • forge/FRAMEWORK_V4.md
    • forge/SCHEMA_REFERENCE_V4.md
  3. Use forge-business to create business-plan.md for new ideas.
  4. Use forge-schema to define:
    • forge/system.yaml
    • forge/containers.yaml
    • forge/entities.yaml
    • forge/decisions.yaml
    • forge/crawler.yaml
  5. Use forge-hydrate when an existing codebase needs to be reverse-engineered into Forge V4.
  6. Use business actions to speculate cross-container runtime flows before settling containers.
  7. Define a complete actor/system outcome, its acceptance conditions, and all material flow outcomes.
  8. Add C3 annotations beside implementation code as the outcome is built.
  9. Use forge crawl, forge context, and forge audit to validate the merged model.
  10. Use forge-review and forge-security before build work.
  11. Use forge-build to implement the approved outcome and forge-test to independently prove it.

The intended operating mode is:

  1. choose the active skill first
  2. ask that skill what scope it needs
  3. use forge crawl to validate extraction
  4. use forge context only for narrow scope
  5. use forge audit when you need a review artifact

An initialized repository keeps the Forge-owned schema workspace under ./forge/. The repo root stays available for product code, app docs, and non-Forge tooling.

Golden Path Examples

  • examples/forge_minimal_web_app: the V4 example used for docs, smoke tests, crawler extraction, context, and audit rendering

Local Development

Use the project virtual environment:

.venv/bin/python -m pip install -e .[dev]

Validation Commands

make lint
make typecheck
make test
make compile
make build
make verify-package
make smoke-init
make check

make verify-package builds the wheel, installs it into a fresh Python 3.11+ virtual environment, and confirms that the installed forge entrypoint works.

Packaging

Build artifacts are generated with:

.venv/bin/python -m build

This produces:

  • dist/*.tar.gz
  • dist/*.whl

Validate package metadata before release with:

make check-dist

Local Testing

Run the full local verification path:

make check

That covers linting, type checking, tests, compile validation, build output, distribution metadata checks, clean wheel install, and forge init smoke validation.

If you want to test the richer example schema directly:

EXAMPLE="examples/forge_minimal_web_app"
.venv/bin/forge audit --project-dir "$EXAMPLE" --output /tmp/forge-audit-example.html

That generates the audit artifact and opens it unless --no-open is supplied.

Framework Notes

  • Forge is flow-complete: model broadly, then deliver one approved, meaningful outcome at a time.
  • The framework should reduce context, not increase it.
  • Components and exact schemas should only appear when runtime boundaries and business action intent are already clear.
  • Important decisions should be captured in forge/decisions.yaml.

Maintainer Notes

Metadata

Release files for ai-forge-cli 3.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ai-forge-cli 3.1.2
File Size Uploaded Provenance Actions
ai_forge_cli-3.1.2.tar.gz 274.1 kB With provenance Details for ai_forge_cli-3.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ai-forge-cli 3.1.2
File Interpreter ABI Platform Actions
ai_forge_cli-3.1.2-py3-none-any.whl Python 3 none any Details for ai_forge_cli-3.1.2-py3-none-any.whl

Total release size: 554.3 kB

Release files / ai_forge_cli-3.1.2.tar.gz

Download URL ai_forge_cli-3.1.2.tar.gz
Size 274.1 kB
Tags Source
SHA-256 checksum
How to use checksums
82f5b23efd45bc25b0c0aa5728b7f6bddd2a0fe8151afeaacd667bbad4d25f57
BLAKE2b-256 checksum
How to use checksums
191f3db5e2786575b04ef62cbf7a4717d8e853fec1bf2d89b274d861f67ceaca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 11, 2026.

Transparency log

Release files / ai_forge_cli-3.1.2-py3-none-any.whl

Download URL ai_forge_cli-3.1.2-py3-none-any.whl
Size 280.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
97754943fea7504196bffc5543db361954ce12e5c7f10e3bfbf30cbf02d4e4ff
BLAKE2b-256 checksum
How to use checksums
7576d23f202caaf19e4bcc7b4167bec9a9450406bc399e1b17d65b118045de51
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 11, 2026.

Transparency log

Security for ai-forge-cli 3.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ai_forge_cli-3.1.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.1.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page