⚒️ Forge Lite

Turn a written spec into a working React app — using Claude Code as the orchestrator, and nothing else.

No APIs. No queues. No deployment infrastructure. A library of markdown, shell scripts, and a small web wizard.

---

The problem

Spec-to-app pipelines work, but they're expensive to maintain: queues, secrets, deploys, custom UIs. Most of what they do — read context, plan, edit files, run commands, verify — already lives inside Claude Code.

Forge Lite collapses the pipeline into a library. You hand the system a spec (structured JSON, unstructured notes, or a Whimsical mindmap export), one shell script scaffolds the project with the right context loaded, and Claude Code does the build.

The trade: you keep a human in the loop. What you get: zero infrastructure, full transparency, and the same workflow whether it's a weekend prototype or a real product.

Who this is for

You are…	Forge Lite gives you…
A solo dev shipping client apps	A repeatable scaffold so you stop re-prompting the same auth/payments patterns every project
A small team standardising on Claude Code	25 shared system docs — one set of conventions instead of five developers' habits
Someone evaluating spec-driven development	A working reference implementation you can read in fifteen minutes, with no service to sign up for

It is not an autonomous agent, a hosted platform, or a no-code builder. You review the spec and you review the code.

What's in the repo

forge-lite/
├── scripts/
│   ├── forge.sh                  Unified CLI — new / list / status / open
│   ├── new-project.sh            Scaffold a fresh project folder
│   ├── json-to-spec.sh           JSON spec → product-spec.md + design-brief.md
│   ├── text-to-json.sh           Unstructured notes → JSON spec (Claude Chat prompt)
│   ├── whimsical-to-spec.sh      Whimsical mindmap export → JSON spec
│   └── forge-convert.sh          Legacy single-script converter (kept for compat)
├── context/
│   ├── system/                   Cross-project conventions (25 files)
│   └── capabilities/             Per-feature playbooks — auth, payments, …  (31 files)
├── templates/                    Blank product-spec.md, starter CLAUDE.md
├── fixtures/                     Sample inputs for the converters
└── web/                          Optional browser wizard (Vite + Express)

context/ is the bulk of the repo's value. Every scaffolded project gets pointers to these files, so when Claude Code builds (say) your auth flow, it reads context/capabilities/authentication.md first — instead of you re-explaining the same pattern in every project.

Capability playbooks cover: authentication · payments (Stripe and M-Pesa STK Push) · multi-tenancy with Supabase RLS · rate limiting · file uploads · PDF generation · event-driven architecture — and 24 more.

The M-Pesa playbook is the one most people won't have. If you're building for East African users, that path is written, tested, and reusable.

Quick start

Prerequisites

• Node.js 20+ and Git
• Claude Code — npm install -g @anthropic-ai/claude-code
• Optional: poppler-utils for PDF input (sudo apt install poppler-utils / brew install poppler); Python 3 for the JSON and Whimsical converters

git clone https://github.com/Csasaka19/forge-lite.git ~/projects/forge-lite
chmod +x ~/projects/forge-lite/scripts/*.sh

Then set up your global Claude Code preferences — at minimum a ~/.claude/CLAUDE.md with your stack defaults and a ~/.claude/skills/react-vite-builder/SKILL.md with the build skill. First time using Claude Code? The end-to-end walkthrough is in Forge_Lite_Team_Onboarding.md.

Creating a project

forge.sh auto-detects the input format:

# Structured JSON spec
./scripts/forge.sh new fixtures/sample-water-vending.json

# Unstructured notes — prints a Claude Chat prompt; paste the JSON output back in
./scripts/forge.sh new fixtures/efficiency-tracker-notes.txt

# Whimsical mindmap export (UI / Logic / Q&A nodes)
./scripts/forge.sh new fixtures/payment-flow.json

# Blank scaffold — write the spec by hand later
./scripts/forge.sh new --name blank-experiment

Each path creates ~/projects/<name>/ containing:

• CLAUDE.md — project-specific Claude Code config, placeholder name auto-filled
• docs/product-spec.md and docs/design-brief.md — populated from the input
• docs/react-stack.md, docs/design-system.md — copies of context/system/*.md, so the project stays self-contained even if Forge Lite moves on
• .claude/rules/ and .claude/commands/ — auto-loaded by Claude Code: lazy rules per file extension, slash commands like /build-feature and /review
• An initialised git repo with .gitignore

cd ~/projects/my-app
$EDITOR docs/product-spec.md    # review and adjust the generated spec
$EDITOR docs/design-brief.md    # describe the visual direction
claude                          # open Claude Code

Other subcommands:

./scripts/forge.sh list                  # all projects in ~/projects/
./scripts/forge.sh status my-app         # spec vs built — what's done, what's not
./scripts/forge.sh open my-app           # cd in and open in $EDITOR

Inside Claude Code

Slash commands load automatically. The typical sequence:

> /build-feature Scaffold the project from scratch — Vite, React, TS, Tailwind,
  shadcn. Build the layout (Header, Footer, theme toggle), the route table in
  App.tsx, and shared components. Don't build any pages yet.

> /build-feature Build the [page name]. Cover [feature list]. Handle the edge
  cases listed in the spec for this page.

> /review

/review reads the spec, compares it to what's built, marks each feature done / partial / not started, runs npm run build, and reports issues.

Web wizard (alternative)

For a drag-and-drop UX, web/ holds a four-step browser wizard wrapping the same scripts:

cd web
npm install
npm run dev      # Vite frontend (5173) + Express backend (5174)

Drop a spec file onto the input, pick capabilities, and the wizard shells out to new-project.sh, streaming stdout back as a live activity log. Same engine as the CLI — every web run produces a project structurally identical to forge.sh new.

Design decisions

Decision	Why	What it costs
Markdown library, not a service	Nothing to host, nothing to pay for, readable in a text editor	No multi-user state, no run history
Human in the loop at spec review	Bad specs produce bad apps faster than bad code does	Not fully unattended
Context copied into each project	Projects keep working when Forge Lite changes	Playbook updates don't propagate backwards
Shell + Claude Code only	Stack is ~200 lines of bash you can read and audit	No Windows support without WSL

Roadmap

• Eval hooks — measure whether a generated build matches the spec, rather than eyeballing /review output
• Capability playbook for background jobs and scheduled workflows
• Non-React target (Next.js app router)

Issues and PRs welcome — especially new capability playbooks. One markdown file, one feature, the pattern you actually shipped.

License

MIT — see LICENSE.

---

Built by Clive Sasaka — applied AI engineer, Nairobi (UTC+3). LinkedIn · Medium

If this saved you an afternoon, a ⭐ helps other people find it.