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 implementationskills/: the Forge skill source used by initialized repositoriesFRAMEWORK_V4.md: the V4 framework process used to seedforge/FRAMEWORK_V4.mdSCHEMA_REFERENCE_V4.md: the V4 schema contract used to seedforge/SCHEMA_REFERENCE_V4.mdexamples/: example Forge repositories and audit artifacts
CLI Commands
forge init: scaffold a new Forge workspace and explain how to use itforge crawl: extract the merged V4 model from central files and code annotationsforge context: render scoped context for a system, flow, container, entity, component, operation, or data shapeforge knowledge: list supporting Markdown knowledge docs attached to Forge refs such as containers, flows, entities, components, and operationsforge update skills: refresh onlyforge/skills/using conflict-safe manifestsforge 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
Recommended Workflow
- Run
forge initin an empty repository. - Read:
forge/USING_FORGE.mdforge/FRAMEWORK_V4.mdforge/SCHEMA_REFERENCE_V4.md
- Use
forge-businessto createbusiness-plan.mdfor new ideas. - Use
forge-schemato define:forge/system.yamlforge/containers.yamlforge/entities.yamlforge/decisions.yamlforge/crawler.yaml
- Use
forge-hydratewhen an existing codebase needs to be reverse-engineered into Forge V4. - Use business actions to speculate cross-container runtime flows before settling containers.
- Define a complete actor/system outcome, its acceptance conditions, and all material flow outcomes.
- Add C3 annotations beside implementation code as the outcome is built.
- Use
forge crawl,forge context, andforge auditto validate the merged model. - Use
forge-reviewandforge-securitybefore build work. - Use
forge-buildto implement the approved outcome andforge-testto independently prove it.
The intended operating mode is:
- choose the active skill first
- ask that skill what scope it needs
- use
forge crawlto validate extraction - use
forge contextonly for narrow scope - use
forge auditwhen 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.gzdist/*.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
- Release instructions live in docs/RELEASING.md.
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.