User Guide

Getting Started Your First Build The Build Pipeline Models & When to Use Them Formations (Agent Teams) Autonomy System (A0–A5) Interview vs Quick Build Preview & Deploy Commands Reference Configuration Benchmarking Troubleshooting

Getting Started

Install

git clone https://github.com/herakles-dev/nova-forge.git
cd nova-forge
./setup.sh                    # Creates venv + installs deps
source .venv/bin/activate

Set Credentials

Nova Forge needs API keys for at least one provider. Amazon Bedrock is recommended:

export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"
export AWS_DEFAULT_REGION="us-east-1"

Or use OpenRouter (OPENROUTER_API_KEY) for Gemini models, or Anthropic (ANTHROPIC_API_KEY) for Claude models.

You can also run /login inside Nova Forge for an interactive setup wizard.

Launch

python3 forge_cli.py

On first run, Nova Forge asks your experience level (Beginner / Intermediate / Expert) and sets an appropriate autonomy level automatically.

Your First Build

Just describe what you want:

> Build me an expense tracker with categories and charts

Nova Forge detects your intent and runs the full pipeline automatically:

Smart Planning — Analyzes your goal, detects components (frontend, API, database, auth)
Quick Scope — Asks 2–6 targeted questions about features, design, and data model
Plan — Generates spec.md + tasks.json with dependency ordering
Build — Executes tasks in parallel waves using AI agents
Preview — Offers to launch a live shareable URL

No commands needed

Phrases like “Build me…”, “Create a…”, “Make a…”, “I want…”, or “I need…” automatically trigger the full pipeline.

The Build Pipeline

1. Plan

The planner generates spec.md (project specification) and tasks.json (dependency-ordered task list). Tasks are sorted into parallel waves using topological sort.

If the decomposer fails, a 3-stage fallback guarantees tasks are always produced: retry → JSON recovery → single fallback task.

2. Build

Each task is assigned to a ForgeAgent — an autonomous tool-use loop calling Amazon Nova via AWS Bedrock.

Tool	Purpose
read_file	Read any project file
write_file	Create or overwrite a file
edit_file	Search-and-replace within a file
bash	Run shell commands
glob_files	Find files by pattern
grep	Search file contents
append_file	Add to end of file
list_directory	List directory contents
search_replace_all	Bulk find-and-replace
think	Internal reasoning (no side effects)
claim_file	Claim ownership (multi-agent)
remember	Store a note in persistent memory
check_context	Check remaining context budget

Safety: Circuit breaker (3 failures → tool disabled), convergence tracker (5 idle turns → writes disabled), verify phase (agent reads back files to check correctness), adaptive turn budgets.

3. Gate Review

An adversarial read-only reviewer inspects output: PASS, CONDITIONAL, or FAIL.

4. Preview

Auto-detects your stack (14 supported), starts a dev server, creates a Cloudflare Tunnel for a shareable URL.

5. Deploy

Docker + nginx + SSL deployment: auto-generates Dockerfile, builds container, writes reverse-proxy config, health-checks.

Models

Amazon Nova (primary)

Model	Alias	Context	Cost/1K	Best For
Nova Lite	`nova-lite`	32K	$0.00006	Fast prototypes, simple apps
Nova Pro	`nova-pro`	300K	$0.0008	Complex features, multi-file
Nova Premier	`nova-premier`	1M	$0.002	Deep reasoning, architecture

Additional Models

Model	Alias	Context	Provider
Gemini Flash	`gemini-flash`	1M	OpenRouter
Gemini Pro	`gemini-pro`	1M	OpenRouter
Claude Sonnet	`claude-sonnet`	200K	Anthropic
Claude Haiku	`claude-haiku`	200K	Anthropic

When to Use Which

Project Type	Model	Why
Quick prototype (1–3 files)	`nova-lite` REC	Fast, cheap, S-tier on benchmarks
Multi-file feature (4–8 files)	`nova-pro`	Larger context, better coordination
Complex architecture (10+ files)	`nova-premier`	1M context, deep reasoning
Tight budget	`nova-lite`	33x cheaper than Pro
Speed priority	`gemini-flash`	Fastest inference

3-Tier Prompt System

Nova Forge auto-adapts prompts to each model’s context window:

Slim (32K) — ~600 chars, 8 essential tools, output coaching
Focused (300K+) — ~1,500 chars, full 13 tools
Full (1M+) — ~5,000 chars with pre-seeded upstream context

/model nova-pro          # Switch directly
/model                   # Interactive selector
/models                  # Compare all models

Formations

Pre-configured multi-agent team layouts. Nova Forge auto-selects the right one, or you can override with /formation.

single-file

Solo implementer. Config changes, small edits.

1 agent · 1 wave

lightweight-feature

Implementer → Tester. Simple single-layer features.

2 agents · 2 waves

feature-impl

Backend + Frontend → Integrator → Tester. Most common.

4 agents · 3 waves

new-project

Architect → 2 parallel implementers. Greenfield builds.

3 agents · 2 waves

bug-investigation

3 parallel investigators with different strategies.

3 agents · 1 wave

security-review

Threat modeler + Scanner → Fixer. Security audits.

3 agents · 2 waves

perf-optimization

Optimizer → Tester. Performance bottlenecks.

2 agents · 2 waves

code-review

3 parallel reviewers (security, perf, coverage). Read-only.

3 agents · 1 wave

recovery

Investigator → Fixer → Validator. Broken deployments.

3 agents · 3 waves

all-hands-planning

4 reviewers → Synthesizer. Complex architecture decisions.

5 agents · 2 waves

integration-check

Auditor → Fixer → Verifier. Cross-file validation.

3 agents · 3 waves

Auto-Selection (DAAO Routing)

	Small (1–3 tasks)	Medium (4–8)	Large (9+)
Routine	single-file	lightweight-feature	lightweight-feature
Medium	lightweight-feature	lightweight-feature	feature-impl
Complex	lightweight-feature	feature-impl	all-hands-planning

Autonomy System

Six trust levels control how much agents can do without asking.

A0ManualEverything blocked. Agent must explain every action.

A1GuidedReads auto-approved. Writes and bash blocked.

A2Supervised DEFAULTReads and writes auto-approved. Only high-risk commands blocked.

A3TrustedNearly everything auto-approved. Only destructive ops blocked.

A4AutonomousFull autopilot. No interruptions. CAUTION

A5UnattendedLike A4 with enhanced audit logging. For CI/CD pipelines.

Auto-Escalation

Trust grows with successful builds: A0→A1 (5 builds), A1→A2 (10), A2→A3 (25). A3→A4 is never automatic — must use /autonomy 4.

/autonomy           # Show current level
/autonomy ?         # Explain all levels
/autonomy 3         # Set to Trusted

Interview vs Quick Build

	Quick Build (default)	/interview	/guide
Trigger	“Build me a todo app”	`/interview`	`/guide`
Questions	2–6 targeted	15–25 deep dive	Step-by-step wizard
Categories	Features, data, auth, design	8 categories (features, data, auth, visual, API, realtime, deploy, testing)	Conversational
Best for	Prototypes, known scope	Complex projects, precise control	First-time users
Time	~1 minute	~5 minutes	~3 minutes

Pro tip

Use /interview for important projects. The deep planning produces dramatically better specs — especially for projects with auth, real-time features, or complex data models.

Preview & Deploy

Preview

/preview              # Auto-detect stack, start server + tunnel
/preview stop         # Stop the preview
/preview status       # Check preview status

14 supported stacks: Flask, FastAPI, Django, Streamlit, Next.js, Vite, Node.js, Go, Rust, Rails, PHP, generic Python, Docker, static HTML.

Creates a Cloudflare Tunnel for a shareable URL — no account needed. Falls back to localhost if Cloudflare is unavailable.

Deploy

/deploy                           # Interactive (asks for domain)
/deploy myapp.herakles.dev        # Direct deployment

Generates Dockerfile → builds image → runs container → nginx config → SSL → health check. All automated.

Non-Interactive CLI

forge plan "expense tracker" --model nova-lite
forge build
forge preview
forge deploy --domain myapp.herakles.dev

Commands Reference

Build

Command	Description
`/plan <goal>`	Plan a project from description
`/build`	Execute all tasks with AI agents
`/preview`	Live preview via Cloudflare Tunnel
`/deploy [domain]`	Ship to production (Docker + nginx)
`/status`	Progress bar and overview
`/tasks`	All tasks with dependencies

Setup

Command	Description
`/guide`	Smart setup wizard
`/interview`	5-step deep planning
`/autonomy [0-5]`	View or set autonomy level
`/model [alias]`	Switch model
`/models`	Compare all models
`/config [key] [val]`	View or edit settings
`/login`	Credential setup wizard
`/formation [name]`	View or set formation

Project

Command	Description
`/new <name>`	Start fresh project
`/resume [n]`	Resume recent project
`/cd <path>`	Switch project directory
`/audit`	View build audit log
`/builds [n]`	Build history
`/health`	System health dashboard
`/competition`	Hackathon readiness check

Configuration

Setting	Default	Description
`default_model`	nova-lite	Model for new builds
`model_preset`	nova	`nova` / `mixed` / `premium`
`project_dir`	~/projects	Where new projects are created
`max_turns`	50	Maximum turns per agent task
`temperature`	0.3	LLM sampling temperature
`auto_build`	true	Auto-confirm in guided flow
`show_tips`	true	Display contextual hints

/config                      # View all settings
/config default_model nova-pro   # Change a setting

Benchmarking

python3 benchmark_nova_models.py --model nova-lite -v    # Single model
python3 benchmark_nova_models.py --all                    # All 3 Nova models
python3 benchmark_nova_models.py --scenario kanban-board   # Hard scenario

Scenarios

Scenario	Difficulty	Stack
expense-tracker	Easy	Flask + SQLite + Chart.js
todo-app	Easy	FastAPI + SQLite
kanban-board	Hard	Flask + SQLite + Auth
realtime-kanban	Nightmare	Flask + SSE + Uploads

Current Scores (Sprint 19)

Model	Expense Tracker	Time	Turns
Nova Lite (32K)	S 100%	144s	40
Nova Pro (300K)	S 100%	167s	39
Nova Premier (1M)	S 100%	1110s	33

Grades: S 95–100% · A 85–94% · B 75–84% · C 60–74% · D 40–59% · F <40%

Troubleshooting

“Need Amazon Bedrock credentials first”

Set AWS env vars or run /login. Or switch to a non-AWS model: /model gemini-flash

Build produces 0 tasks

Shouldn’t happen (3-stage fallback). Try a more specific description or use /interview.

Preview won’t start

Check for port conflicts: lsof -i :5000. Try /preview stop then /preview.

Agent stuck retrying

Circuit breaker auto-disables after 3 failures. Re-run /build for a fresh attempt.

Context exhaustion

Auto-compaction handles this. For large builds, switch to /model nova-pro or /model nova-premier.

Build partially completes

Run /build again to retry only failed tasks. Or describe the issue and Nova will help fix it.

Power user tips

Start with Lite, upgrade if needed (33x cheaper)
Use /interview for important projects
Watch the gate review — CONDITIONAL results point to real issues
Check /audit to see every tool call and decision
Run benchmarks after model changes: python3 benchmark_nova_models.py --all

Contents

Getting Started

Install

Set Credentials

Launch

Your First Build

The Build Pipeline

1. Plan

2. Build

3. Gate Review

4. Preview

5. Deploy

Models

Amazon Nova (primary)

Additional Models

When to Use Which

3-Tier Prompt System

Formations

single-file

lightweight-feature

feature-impl

new-project

bug-investigation

security-review

perf-optimization

code-review

recovery

all-hands-planning

integration-check

Auto-Selection (DAAO Routing)

Autonomy System

Auto-Escalation

Interview vs Quick Build

Preview & Deploy

Preview

Deploy

Non-Interactive CLI

Commands Reference

Build

Setup

Project

Configuration

Benchmarking

Scenarios

Current Scores (Sprint 19)

Troubleshooting

“Need Amazon Bedrock credentials first”

Build produces 0 tasks

Preview won’t start

Agent stuck retrying

Context exhaustion

Build partially completes