Forge is a production-grade project generator designed specifically for modern AI engineering. It doesn't just create folders; it establishes an AI Collaboration Framework that ensures human-AI teams work within strict governance, shared context, and professional engineering standards.
Traditional scaffolding tools (like Cookiecutter) focus on file organization. Forge focuses on Agentic Governance. It prepares your workspace to be understood and respected by AI tools (like Gemini Code Assist or Cursor) the moment you run the first commit.
- AI-Native Context: Every project ships with
AI_DIRECTIVES.md,CLAUDE.md, andGEMINI.mdto ground your AI agent. - Strict Governance: Prevent AI "shadow logic" and reinvention of existing utilities.
- Production-Ready: Enforces Type Hinting, Google-style docstrings, and 1000gic coverage in tests.
| Feature | Description |
|---|---|
| Agentic Rules | Dedicated AI_DIRECTIVES.md to define operational guardrails for AI agents. |
| Universal Ansible | Production-ready ansible/ scaffold with setup_workstation.yml for instant environment bootstrapping. |
| Strict Quality | Enforced pre-commit hooks for pytest, flake8, yamllint, and ansible-lint. |
| Git Flow Automation | Initializes a repo with main and develop branches out of the box. |
| Modular CI/CD | Production-ready GitHub Actions for testing and linting. |
| Feature Tracking | Structured docs/features/ system with a ready-to-use template. |
| Standardized Layout | Clean separation of src/, data/, models/, and notebooks/. |
The easiest way to use Forge globally is with pipx. This installs Forge in an isolated environment and makes the forge command available everywhere.
pipx install git+https://github.com/jlwestsr/nebulus-forge.gitIf you want to contribute to Forge or customize the templates locally:
-
Clone the repository:
git clone https://github.com/jlwestsr/nebulus-forge.git cd nebulus-forge -
Create a virtual environment and install in editable mode:
python3 -m venv .venv source .venv/bin/activate pip install -e .
Forge can be invoked as forge (via alias or pipx).
# Forge in the current directory
forge .
# Forge in a specific target directory
forge ~/projects/my-new-ai-modelEnable the "Update" feature to add missing standard files without overwriting your manual changes.
# Update existing project (safe, idempotent)
forge . --update --profile fullstackWhen you forge a project, you get a battle-tested structure:
.
├── AI_DIRECTIVES.md # Operational guardrails for AI
├── CLAUDE.md # Persona & project instructions
├── GEMINI.md # PM communication protocol
├── WORKFLOW.md # Git & development process
├── data/ # Git-ignored (raw/processed)
├── docs/
│ ├── feature_template.md # Standardized feature requirement format
│ └── features/ # Root for all feature documentation
├── src/ # Production-grade Python modules
└── tests/ # Unit & integration testing suite
Forge projects enforce the following by default:
- Type Hinting: Mandatory for all function signatures.
- Modular Logic: Business logic lives in
src/, never in notebooks. - Docstrings: Google-style documentation for all public modules.
- Automated Verification: CI/CD pipeline integrated into every scaffold.
We are building the future of AI-native engineering. If you have ideas for improving agentic governance or scaffolding templates, please:
- Fork the repo.
- Create a feature branch off
develop. - Open a Pull Request.
Iterate fast, governed safely. Forge is released under the MIT License.
Built with ❤️ by JLWestSr