💡 The problem

You have an idea. You open Claude Code / Cursor / Codex and start prompting. Three hours later you're deep in a refactor because the idea was never actually defined — wrong scope, wrong stack, maybe the wrong kind of solution entirely (you built an app when a 200-line automation would've done it).

AI coding agents are only as good as the context you give them. Half-baked ideas produce half-baked code, wasted tokens, and expensive rewrites.

🔨 The solution

Hephaestus' Forge is a self-hosted web app that interviews you about your idea through a focused 5-phase wizard, then forges a complete, build-ready documentation pack you drop straight into your AI IDE as context:

• 🧭 Project Blueprint — recommends the right kind of solution (automation / agent / web / app / CLI), the scale, the time, the stages, and the scope.
• 📋 PRD — personas, prioritized user stories with acceptance criteria, non-goals, KPIs.
• 🏗️ Technical Spec — a justified stack, data model, API surface, deployment strategy.
• ⏱️ Estimation — honest min/max ranges with named risk factors, not one optimistic number.

And the part nobody else does: it runs on the AI you already have.

✨ Why you'll want it

👤 Who it's for

• Vibe coders & indie hackers turning a spark into something real this weekend.
• Developers who want their AI agent to build the right thing the first time.
• Founders & PMs who need a credible spec, scope, and estimate to align on.
• No-code builders who want to know whether to build an app, an automation, or an agent.
• Privacy-conscious teams who can't send their ideas to a third-party SaaS.

⚡ Bring Your Own Engine

Every other planning tool locks you into one API key. Hephaestus runs on whatever you've got — including the coding agents already installed on your machine:

The app auto-detects the CLI agents in your PATH and lets you configure API/Ollama providers in a dedicated Engines panel — test the connection, pick a default, done. Keys are stored only in a local SQLite file and are honest about state: detected in PATH ≠ authenticated — you click Test to verify before using.

🛠️ How it works

Describe your idea → 5-phase guided wizard → Generate docs → Export ZIP
       💡        Discovery·Audience·Solution-Fit·Scope·Constraints   📦 drop into your AI IDE

1. Describe your idea in a sentence or a paragraph.
2. Answer a short, AI-generated interview — one sharp question at a time, streamed live — across five phases: Discovery → Audience → Solution-Fit → Scope → Constraints. This is what lets Hephaestus recommend the right kind of solution instead of assuming you need an app.
3. Generate a pack led by a Project Blueprint, plus PRD · Technical Spec · Estimation.
4. Export as a ZIP of clean Markdown, ready as context for your coding agent.

📸 See it in action

🌐 Prefer to look first? Visit the website →

Project Blueprint (solution type · scale · stages)	Multilingual UI (中文)
Bring Your Own Engine	Generated document viewer

📂 Examples (real output)

Three complete packs generated by Hephaestus itself with the Claude Code engine — from one sentence to a full doc set:

• 🤖 Standup Forge — git activity → daily standup. Its Blueprint recommends a scheduled automation, not a web app.
• 🇬🇧 Streakly — an AI habit tracker → PRD.
• 🇨🇳 聚单宝 — a restaurant order/inventory mini-program (fully in Chinese).

See examples/ for the breakdown.

🆚 How it compares

🚀 Quickstart

Option A — Docker (API + Ollama engines)

git clone https://github.com/r10d1nsec/hephaestus-forge
cd hephaestus-forge
cp .env.example .env        # optional — you can also configure engines in the UI
docker compose up -d
# open http://localhost:3000

Option B — Native mode (unlocks CLI agents 🔓)

Runs on the host so it can reach claude / codex / gemini in your PATH:

git clone https://github.com/r10d1nsec/hephaestus-forge
cd hephaestus-forge
./run.sh
# open http://localhost:3000

📐 Architecture

React + Vite + Tailwind frontend · FastAPI + SQLite backend · a single Engine abstraction that every provider plugs into. Read docs/ARCHITECTURE.md and docs/ENGINES.md.

🗺️ Roadmap

• v0.1 — MVP: Docker + native, Engines panel, wizard, PRD/Tech Spec/Estimation, ZIP export
• v0.2: 5-phase wizard, Project Blueprint with solution-type recommendation, multilingual app, premium redesign
• v0.3: User Flows (Mermaid), AI Prompts Pack, inline editor, version history, PDF export
• v1.0: "Copy as Claude context", GitHub Gist export, custom templates, CLI companion, VS Code extension

Have an idea for the roadmap? Open an issue or start a discussion.

🤝 Join the forge

Hephaestus is built in the open, and contributors are what make it better. Whether you write Rust or you've never opened a terminal, there's a way in:

• ⭐ Star the repo — the single biggest, easiest way to help it reach more builders.
• 🖥️ Add an engine — the highest-value contribution. Each new engine brings its whole community. There's a hands-on "add your first engine in ~20 minutes" walkthrough in CONTRIBUTING.md.
• 🌍 Translate — add a README.<lang>.md or a UI locale and reach a new audience.
• 📝 Improve the prompts — the wizard and generators are just Markdown in backend/prompts/. No code required.
• 🐛 Report a bug or 💡 suggest a feature — open an issue.
• 🧪 Share what you forged — post a generated pack in Discussions.

New here? Look for good first issue — we keep a seed list of scoped, friendly starters. Be kind; see the Code of Conduct.

Every star, issue, and PR genuinely moves this forward. Thank you for forging with us. 🔥

📜 License

MIT © 2026 Angel Roldan — Córdoba, Spain.