ai-forge-cli 2.1.3

Forge V3 context CLI

Forge

Forge is a Python CLI and framework for vertical-first system design and delivery. It helps you define a system clearly, split it into buildable verticals, and then deepen and implement one slice at a time with the minimum context needed for the task at hand.

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_V3.md: the framework process and recommended authoring order used to seed forge/FRAMEWORK_V3.md
• SCHEMA_REFERENCE_V3.md: the schema contract and field rules used to seed forge/SCHEMA_REFERENCE_V3.md
• examples/: example Forge repositories and audit artifacts

CLI Commands

• forge init: scaffold a new Forge workspace and explain how to use it
• forge context: render scoped context for a system, vertical, flow, container, or component
• 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 broad system design to one thin vertical at a time
• a scoped context generator for build, review, and security tasks
• an audit artifact generator for human review

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
• an excuse to widen a vertical beyond what can be built and validated cleanly

Recommended Workflow

1. Run forge init in an empty repository.
2. Read:
   • forge/USING_FORGE.md
   • forge/FRAMEWORK_V3.md
   • forge/SCHEMA_REFERENCE_V3.md
3. Use forge-schema to define:
   • forge/system.yaml
   • forge/high_level_flows/
   • forge/early_state.yaml
   • forge/runtime.yaml
4. Derive forge/verticals/ once the runtime picture is clear.
5. Pick one vertical and deepen it through:
   • forge/runtime_flows/
   • forge/data_shapes/
   • forge/persistent_shapes/
   • forge/containers/
   • forge/deployment.yaml
6. Use forge-review to check the slice for drift, bloat, and broken references before build starts.
7. Use forge-security to make the slice security posture explicit before build starts.
8. Use forge-build to plan or implement that approved vertical.

The intended operating mode is:

1. choose the active skill first
2. ask that skill what scope it needs
3. use forge context only for that narrow scope
4. use forge audit when you need a whole-system 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_v2_ordering_example: the compact canonical example for docs, smoke tests, and first-time users
• examples/forge_v2_fulfillment_control_example: the richer example used to pressure-test flows, data, deployment, 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_v2_fulfillment_control_example"
.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 vertical-first: model broadly, then deepen one thin slice.
• The framework should reduce context, not increase it.
• Components and exact schemas should only appear when runtime boundaries and vertical intent are already clear.
• Important decisions should be captured in decision_notes.md.

Maintainer Notes

• Release instructions live in docs/RELEASING.md.

Repository Notes

Previous iteration artifacts have been retained in old-forge-v2/.