Forge
An opinionated toolchain for building applications with coding agents.
forge new <app> # scaffolds a deployable app
forge feature "<desc>" # AI generates from spec (future)
forge test # verifies correctness
forge deploy # ships to production
Project Identity
Forge is a personal experiment to test whether opinionated conventions improve AI code generation quality.
This is not (yet) an industry standard or framework for others to adopt. It's a hypothesis being tested through building a real application (rally-hq).
If the hypothesis proves out: Tooling may be extracted and shared. If not: Lessons learned will be documented.
Adoption by others is not a goal for Phase 1-2.
Status
| Phase | Status | Description |
|---|---|---|
| Research | Done | Framework comparison, AI-friendliness analysis |
| Foundation | Current | Building rally-hq by hand to prove conventions |
| Extraction | Planned | Extract forge new/test/deploy from patterns |
| Generation | Planned | Add AI-assisted feature generation |
The Thesis
React-era patterns (hooks, client state, hydration) exceed AI's reasoning capacity. 45% of AI-generated code has security vulnerabilities. Senior engineers are burning out on "vibe coded" spaghetti.
The fix isn't a new framework. It's an opinionated workflow:
| Convention | What It Means |
|---|---|
| Finite component registries | AI selects from known components, doesn't invent |
| Server-first state | No client state management to confuse AI |
| Typed primitives | All functions have Zod schemas |
| Explicit workflows | State machines, not implicit control flow |
| Property-based tests | Derived from types automatically |
| File-based discovery | Structure in filesystem, not config |
Documentation
Core Documents
| Document | Purpose | When to Read |
|---|---|---|
| ARCHITECTURE.md | Full technical architecture | Before building |
| RALLY-HQ.md | Proof-of-concept app specification | Before building |
| DECISIONS.md | Stack choices and rationale | Understanding the stack |
| PROGRESS.md | Status, hypotheses, success criteria | Tracking progress |
| LEARNINGS.md | What worked, what didn't | Retrospectives |
| SCOPE.md | What we're building, what we're not | Scope questions |
Decision Records
| Document | Purpose |
|---|---|
| DECISION-LOG.md | Chronological record of decisions (append-only) |
| AUDIT.md | Engineering audit findings and recommendations |
Agent Stack
| Document | Purpose |
|---|---|
| 12-FACTOR-AGENTS.md | Start here — 12 principles for production-ready AI agents |
| BUILD-TIME-AGENTS.md | Patterns for AI-assisted development (11 patterns) |
| RUNTIME-AGENTS.md | Patterns for AI features in running apps (tooling decisions) |
| AI-INTEGRATION-LEVELS.md | Decision framework for AI integration depth (4 dimensions) |
Research Archive
| Document | Purpose |
|---|---|
| research/README.md | Research index |
| research/AI-NATIVE-WEB-THESIS.md | Core thesis on AI + web development |
| research/RED-TEAM-ANALYSIS.md | Critical analysis of proposed stack |
| research/STACK-COMPARISON.md | Framework decision matrices |
| research/OPPORTUNITIES.md | Identified opportunities |
| research/AGENTIC-WEB-STANDARD.md | Specification-first approach (deferred) |
Quick Links
- What stack are we using? → DECISIONS.md
- What is rally-hq? → RALLY-HQ.md
- What hypotheses are we testing? → PROGRESS.md
- What's the success criteria? → PROGRESS.md
- What did the audit find? → AUDIT.md
- 12 principles for AI agents? → 12-FACTOR-AGENTS.md
- LangChain vs direct SDK? → RUNTIME-AGENTS.md
The Stack
"Forge apps use Go + HTMX for the core, Svelte islands for escape hatches. Server renders HTML. State lives on the server. Primitives over frameworks."
| Layer | Choice | Why |
|---|---|---|
| Core (80%) | ||
| Language | Go 1.23+ | Fast, typed, single binary |
| Router | net/http (stdlib) | Zero dependencies |
| Templates | Templ | Type-safe HTML |
| Interactivity | HTMX 2.x (~14kb) | HTML-over-the-wire |
| Database | PostgreSQL 16 + sqlc | SQL-first, type-safe |
| Real-time | SSE (stdlib) | Browser-native |
| Islands (20%) | ||
| Framework | Svelte 5 | Smallest runtime |
| Build | Vite | Standard tooling |
| Infrastructure | ||
| Hosting | Fly.io | Go-native, edge deploys |
| Styling | Tailwind 4.0 | Fast builds, utility CSS |
See DECISIONS.md for full rationale and ARCHITECTURE.md for technical details.
Key Hypotheses
| ID | Hypothesis | Target |
|---|---|---|
| H1 | Go + HTMX produces more reliable AI code | >85% compile success |
| H2 | HTML responses are simpler than JSON → JS → DOM | Fewer bugs than SvelteKit |
| H3 | Islands needed for <20% of features | Audit after MVP |
| H4 | SSE handles real-time without WebSockets | <100ms latency |
| H5 | sqlc is more AI-friendly than ORMs | >90% correct queries |
| H6 | Bundle stays under 50kb for most pages | Measure at deploy |
See PROGRESS.md for measurement details.
Regenerating HTML Documentation
After editing markdown files:
npx tsx scripts/generate-docs.ts
This generates:
INDEX.html- Navigation hubdocs/*.html- Project docsdocs/research/*.html- Research archive
Origin
This project emerged from research into AI-native development approaches (December 2025).
Key conclusion: Don't write specs first, build something real and extract patterns.
rally-hq is an existing Next.js application being rebuilt in SvelteKit as the Forge proof-of-concept. This provides:
- Known functional requirements from a working app
- Controlled comparison between Next.js and SvelteKit with AI assistance
- Real patterns to extract for Forge tooling