Forge — AI-native project scaffolder

Forge generates a full project skeleton (governance docs, layout, CI hooks) for human–AI teams. It is not an agent runtime.

For bounded PLAN→ACT→REFLECT jobs and a thin harness embed, use neo-harness (neo init-workspace).

forge new   →  project tree (docs, src, AGENTS, workspace/, …)
     └─(optional)→  neo init-workspace  →  jobs/, scripts/neo, packs

Cross-reference (both directions):
docs/related-projects.md ·
neo-harness related projects

---

Install (recommended for development)

Profiles live in this repo and are not fully packaged in the wheel. Prefer an editable install:

git clone https://github.com/westailabs/nebulus-forge.git
cd nebulus-forge
pipx install --force --editable .
# ensure ~/.local/bin is on PATH
forge profiles list

Or:

python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Optional: export FORGE_PROFILES_DIR=/path/to/nebulus-forge/profiles

---

Quick start

# Interactive (wizard fills variables)
forge new ~/projects/my-app --profile fullstack

# Non-interactive (defaults applied for missing vars)
forge new ~/projects/my-app -p fullstack --no-interactive \
  --var project_name=my-app

# Skip neo-harness embed
forge new ~/projects/my-app -p fullstack --neo off

# Require neo embed (fails if neo not installed)
forge new ~/projects/my-app -p fullstack --neo on

After scaffold, if neo ran: copy env.neo.example → .env, set Neo4j password, then ./scripts/neo start --task-file jobs/smoke-mock.md -p mock.

---

Commands

Command	Purpose
forge new <path>	Create project from profile
forge update [path]	Refresh managed files from lock
forge info	Project / lock info
forge profiles list	List profiles
forge workspace …	Ecosystem workspace helpers

forge new options

Option	Default	Meaning
-p / --profile	fullstack	Profile name
--no-interactive	off	Use defaults + --var only
--var key=value	—	Template variables
--neo	auto	auto / on / off — post-hook neo init-workspace
--neo-pack	workspace	Pack id for neo
--force	off	Overwrite files
--dry-run	off	Render only

---

Documentation

Doc	Topic
docs/README.md	Docs index
docs/related-projects.md	neo-harness (runtime) vs Forge
docs/creating-a-profile.md	Tutorial: write your own profile
docs/profiles.md	Shipped base / fullstack / monorepo
docs/reevaluation-2026-08.md	Layout decisions, Forge vs neo

Profiles (public OSS)

Profile	Role
base	Foundation: src/tests/docs, AGENTS.md, Claude hooks/skills, CI, workspace/scratchpad
fullstack	base + notebooks, data/, models, Ansible, Docker, mkdocs
monorepo	Control plane: products/services/hosts/lab + LAYOUT (no single-package src/)

forge new ~/projects/eco -p monorepo --no-interactive --neo auto --neo-pack workspace

Add your own under profiles/<name>/ — see the profile tutorial.

Ecosystem multi-repo helpers: forge workspace (templates under templates/workspace/), not a forge new profile.

---

What a forged tree looks like

base / fullstack (single package)

my-app/
├── AGENTS.md, CLAUDE.md, GEMINI.md, AI_DIRECTIVES.md, WORKFLOW.md, CONTEXT.md
├── src/<slug>/
├── tests/
├── docs/ …
├── workspace/scratchpad/
├── agents/
├── scripts/
└── .github/workflows/

fullstack also adds notebooks/, data/, models/, ansible/, Docker files (when enabled).

monorepo (control plane)

eco/
├── LAYOUT.md, AGENTS.md, CLAUDE.md, WORKFLOW.md, BUSINESS.md, …
├── config/workspace-layout.yaml
├── products/example-app/
├── services/  hosts/  lab/
├── docs/  workspace/scratchpad/  agents/  scripts/  tests/  jobs/

No root src/<package>/ on monorepo.

After --neo auto (any profile)

├── jobs/smoke-mock.md
├── scripts/neo
├── env.neo.example
└── agents/workspace/       # neo pack (default --neo-pack workspace)

---

neo-harness integration

Env	Purpose
FORGE_NEO_CMD	Override neo binary (e.g. /path/to/.venv/bin/neo)
FORGE_PROFILES_DIR	Override profiles root

Lab paths are also probed: ~/projects/neo-harness/.venv/bin/neo, ~/projects/west_ai_labs/.venv-neo/bin/neo.

---

License

MIT — see LICENSE.