Forge: One-Pager

Everything you need to know in 60 seconds.

What It Is

Opinionated toolchain for reliable AI code generation

forge new <app>        # scaffolds a deployable app
forge feature "<desc>" # AI generates from spec
forge test             # verifies correctness
forge deploy           # ships to production

The Problem

React Era AI Failure Pattern:
┌─────────────────────────────────────────┐
│ User clicks button                      │
│   ↓ useState hook                       │
│   ↓ useEffect triggers                  │
│   ↓ fetch API                           │
│   ↓ JSON response                       │
│   ↓ setState updates                    │
│   ↓ Component re-renders                │
│   ↓ Hydration mismatch                  │
│   ↓ AI gets confused                    │
│   ✗ 45% has security vulnerabilities    │
└─────────────────────────────────────────┘

Result: Senior devs debugging AI spaghetti

The Solution

Primitive-First Pattern:
┌─────────────────────────────────────────┐
│ User clicks button                      │
│   ↓ HTTP POST to server                 │
│   ↓ Go handler executes                 │
│   ↓ HTML response                       │
│   ↓ Browser renders                     │
│   ✓ AI understands this                 │
└─────────────────────────────────────────┘

Result: >85% compile success (target)

The Stack

Bundle size: <50kb (target) Dependencies: Minimal (stdlib-first)

The Approach

Phase 1: Foundation → Build rally-hq by hand
         (Current)    Track AI generations
                      Prove conventions work

Phase 2: Extraction → Extract forge new/test/deploy
                      Templates with conventions

Phase 3: Generation → Add forge feature "<desc>"
                      AI generates code
                      Tests verify correctness

Phase 4: Polish     → Public release
                      Documentation
                      Example apps

Six Conventions

┌────────────────────────────────────────────────────┐
│ 1. Finite Component Registry                      │
│    AI selects from list, doesn't invent           │
│                                                    │
│ 2. Server-First State                             │
│    No client state management                     │
│                                                    │
│ 3. Typed Primitives                               │
│    All functions have schemas                     │
│                                                    │
│ 4. Workflow State Machines                        │
│    Explicit states, not implicit logic            │
│                                                    │
│ 5. Property-Based Tests                           │
│    Generated from types automatically             │
│                                                    │
│ 6. File-Based Discovery                           │
│    Structure in filesystem, not config            │
└────────────────────────────────────────────────────┘

Hypotheses Being Tested

Tracking: .forge/ai-generations/YYYY-MM-DD/

Current Status

✅ Research complete
✅ Stack decided (Go + HTMX + Svelte islands)
✅ Context engineering adopted
🔲 rally-hq initialization ← YOU ARE HERE
🔲 First feature deployed
🔲 Hypotheses validated
🔲 forge new extracted
🔲 forge feature working

Success = Proof

rally-hq deployed + hypotheses validated = patterns work

Then extract into forge new tooling.

The Bottom Line

We're betting that primitive-first conventions can make AI code generation reliable enough for production.

Building rally-hq to prove it.

Read More

• This → You just read it
• EXECUTIVE-SUMMARY.md → 5-minute deep dive
• README.md → Full project overview
• INDEX.html → Complete documentation

Status: Foundation Phase Updated: Dec 23, 2025