Prompt Forge

April 3, 2026 · View on GitHub

A prompt compiler skill for Claude Code, Gemini CLI, and other coding agents.

Solves prompt fatigue — the quality collapse that happens when you've been coding for hours and your prompts go from detailed instructions to "fix the auth thing."

Why This Exists

You're three hours into a session. You know exactly what needs to happen — but you're too fried to write it properly. So you type "fix the login thing" and Claude hallucinates a solution to a problem you didn't describe.

The issue isn't Claude. It's your prompt. You stopped including context, constraints, file paths, test commands, and the six perspectives you'd normally think about. Not because you're lazy — because your working memory is full.

Prompt Forge sits between your tired brain and your coding agent. You type the vague thing. It reads your codebase, asks one or two easy questions, surfaces what you forgot, and hands you back a grounded, structured prompt you can paste and run.

It works with Superpowers and GSD — or standalone with raw Claude Code and Gemini CLI.

How It Works

You:          "fix the auth thing"

Prompt Forge: [reads your code, greps for patterns, checks docs]
              "loginUser() in auth-service.ts handles invalid passwords
               and missing users differently. Is the bug about which one?"

You:          "yeah the missing user case"

Prompt Forge: [delivers a grounded prompt with investigation steps,
               fix approach, test commands, and a security note about
               input validation you didn't think to mention]

The whole pipeline:

Read your input — detect fatigue signals, find the hidden intent
First grounding — read CLAUDE.md, scan the codebase, research docs
Ask 1-3 questions — grounded, easy to answer (yes/no, pick-one)
Second grounding — targeted deep-dive based on your answers
Apply lenses — 9 perspectives that fatigue makes you skip
Compile the prompt — structured, grounded, ready to paste

That's it. You get back a prompt. You paste it. Prompt Forge never writes code, never runs builds, never executes anything. It's the architect, not the builder.

The 9 Lenses

Things a fresh engineer thinks about but a tired one forgets:

#	Lens	What It Catches
1	Business/Product	Building the technically elegant wrong thing
2	QA/Testing	"Works on my machine" prompts with no test commands
3	Architecture	Spaghetti that ignores existing patterns
4	User Experience	Missing loading states, error messages, accessibility
5	Security	Unvalidated input, auth gaps, data exposure
6	Performance	N+1 queries, unindexed lookups, no caching strategy
7	Developer Experience	Code that future-you will curse past-you for
8	Edge Cases	Empty arrays, null users, network timeouts
9	Migration/Compat	Breaking changes to downstream consumers

These aren't presented as a checklist. They're woven naturally into the prompt: "The endpoint doesn't validate email format before the DB query — I'll include that. Also, there's no test for this route."

Modes

Prompt Forge adapts its output based on what you're doing:

Mode	Emphasis	Auto-detected from
`build`	Patterns, step-by-step, done criteria	"add", "create", "implement"
`audit`	Constraints, checklists, verification gates	"review", "check", "secure"
`debug`	Investigation-first, root cause before fix	"fix", "bug", "broken"
`research`	Alternatives, trade-offs, comparison tables	"how", "why", "explore"
`optimize`	Measure first, prove the improvement	"slow", "performance", "cache"

LLM Adapters

Same prompt intelligence, different formatting for each model:

Adapter	Formatting Style
Claude	XML tags, `@file` references, chain-of-thought
Gemini	MUST/MUST NOT rules, markdown structure, search grounding
OpenAI	System/user split, few-shot examples, bold constraints

Works With

Superpowers — Feeds brainstorming with design considerations already surfaced, so the Socratic questioning goes deeper instead of extracting basics
GSD — Produces rich project briefs that give GSD's interview and research phases a head start instead of starting from nothing
Raw Claude Code / Gemini CLI — Outputs task-type-specific blueprints (bug fix, feature, refactor, migration, performance, security, investigation, testing)

What's Inside

prompt-forge/
├── SKILL.md                          # Skill entrypoint
├── src/
│   ├── core/
│   │   ├── intent_parser.md          # Fatigue detection, grounding, questions
│   │   ├── prompt_builder.md         # Lenses, task classification, output
│   │   ├── modes.md                  # 5 compilation modes
│   │   └── constraints.md            # The cardinal rule: never implement
│   ├── adapters/
│   │   ├── claude.md                 # Claude-specific formatting
│   │   ├── gemini.md                 # Gemini-specific formatting
│   │   └── openai.md                 # OpenAI-specific formatting
│   ├── commands/
│   │   └── prompt-forge.md           # /prompt-forge slash command
│   └── utils/
│       └── helpers.md                # Tone, collaboration, complexity adaptation
├── prompts/
│   ├── templates/                    # 8 task-type blueprints + output formats
│   └── examples/                     # Full session walkthrough
├── evals/
│   ├── test_cases.md                 # 14 functional tests
│   ├── adversarial_cases.md          # 15 boundary tests
│   ├── benchmark.md                  # Cross-model benchmarks
│   └── scoring.md                    # Scoring rubric
└── docs/
    ├── architecture.md               # System design
    └── usage.md                      # Integration guide

Installation

npx prompt-forge-cc@latest

The installer prompts you to choose:

Runtime — Claude Code, Gemini CLI, or both
Scope — Global (all projects) or local (current project only)

Non-interactive Install

# Claude Code (global — recommended)
npx prompt-forge-cc --claude --global

# Gemini CLI (global)
npx prompt-forge-cc --gemini --global

# Both runtimes
npx prompt-forge-cc --all --global

# Current project only
npx prompt-forge-cc --claude --local

Verify

Start a new session and run:

/prompt-forge fix the auth thing

Updating

npx prompt-forge-cc@latest

Uninstall

npx prompt-forge-cc --uninstall

Philosophy

Investigate, never implement — Prompt Forge reads your code aggressively but never touches it
Fatigue is the enemy, not laziness — "fix the thing" is a valid input
Grounding over guessing — Every file path, function name, and type in the output comes from actually reading the code
Collaborate, don't obey — It challenges bad assumptions and proposes alternatives
Match complexity to the task — A typo fix gets a one-liner, not five sections of context

Contributing

Fork the repository
Create a branch for your changes
Submit a PR

See docs/architecture.md for system design and evals/ for validation criteria.

Contributors

Nirvaan (Nirvaan05) — Core Architecture, prompt system design, evaluation framework
Hill Patel (STiFLeR7) — Lead Contributor, prompt system design, original extraction from Superpowers

License

MIT — see LICENSE