prompt-forge-cc 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nirvaan (Nirvaan05), Hill Patel (STiFLeR7)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,215 @@
+# Prompt Forge
+
+**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."**
+
+[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/STiFLeR7/prompt-forge?style=for-the-badge&logo=github&color=181717)](https://github.com/STiFLeR7/prompt-forge)
+
+---
+
+## 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](https://github.com/obra/superpowers) and [GSD](https://github.com/gsd-build/get-shit-done) — 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:
+
+1. **Read your input** — detect fatigue signals, find the hidden intent
+2. **First grounding** — read CLAUDE.md, scan the codebase, research docs
+3. **Ask 1-3 questions** — grounded, easy to answer (yes/no, pick-one)
+4. **Second grounding** — targeted deep-dive based on your answers
+5. **Apply lenses** — 9 perspectives that fatigue makes you skip
+6. **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](https://github.com/obra/superpowers)** — Feeds brainstorming with design considerations already surfaced, so the Socratic questioning goes deeper instead of extracting basics
+- **[GSD](https://github.com/gsd-build/get-shit-done)** — 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
+
+```bash
+npx prompt-forge-cc@latest
+```
+
+The installer prompts you to choose:
+1. **Runtime** — Claude Code, Gemini CLI, or both
+2. **Scope** — Global (all projects) or local (current project only)
+
+### Non-interactive Install
+
+```bash
+# 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
+
+```bash
+npx prompt-forge-cc@latest
+```
+
+### Uninstall
+
+```bash
+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
+
+1. Fork the repository
+2. Create a branch for your changes
+3. Submit a PR
+
+See `docs/architecture.md` for system design and `evals/` for validation criteria.
+
+---
+
+## Contributors
+
+- **Nirvaan** ([Nirvaan05](https://github.com/Nirvaan05)) — Core Architecture, prompt system design, evaluation framework
+- **Hill Patel** ([STiFLeR7](https://github.com/STiFLeR7)) — Lead Contributor, prompt system design, original extraction from Superpowers
+
+## License
+
+MIT — see [LICENSE](LICENSE)

package/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: prompt-forge
+description: "Use when a developer explicitly asks for help crafting or refining an execution prompt. Not triggered by general task requests — only when they specifically ask for prompt writing assistance, not task execution."
+---
+
+# Prompt Forge
+
+A prompt refinement skill that extracts what a developer actually means — especially when they're too deep in a session to say it clearly. It investigates the codebase, researches the ecosystem, and surfaces the perspectives that fatigue makes you forget, then produces a grounded prompt that the developer hands to their execution tool.
+
+Built on Anthropic's official prompting best practices. Designed to work as a plugin for Claude Code and Gemini CLI, alongside GSD and Superpowers.
+
+## The Cardinal Rule
+
+**Investigate freely — but never implement.** Prompt Forge is a prompt writer, not a task executor. Its only job is to produce a refined, grounded prompt. See `src/core/constraints.md` for full boundary definition.
+
+## Core Workflow
+
+The workflow has two grounding passes — one before asking questions, one after.
+
+| Step | Module | What Happens |
+|------|--------|-------------|
+| 1. Receive input | `src/core/intent_parser.md` | Read raw input, detect fatigue signals |
+| 2. First grounding | `src/core/intent_parser.md` | CLAUDE.md → code analysis → web research |
+| 3. Ask questions | `src/core/intent_parser.md` | 1-3 grounded, fatigue-friendly questions |
+| 4. Second grounding | `src/core/intent_parser.md` | Targeted deep-dive from answers |
+| 5. Apply lenses | `src/core/prompt_builder.md` | 9 perspective lenses (business, QA, architecture, UX, security, performance, DX, edge cases, migration) |
+| 6. Produce output | `src/core/prompt_builder.md` | Intent breakdown + copy-paste prompt |
+| 7. Scope check | `src/core/constraints.md` | Verify no implementation drift |
+| 8. Deliver | `src/utils/helpers.md` | Present prompt, stay open for refinement |
+
+## Module Index
+
+### Core Logic
+- **`src/core/intent_parser.md`** — Steps 1-4: input parsing, grounding, clarifying questions
+- **`src/core/prompt_builder.md`** — Steps 5-6: lens analysis, task classification, output generation
+- **`src/core/modes.md`** — 5 compilation modes (build, audit, debug, research, optimize)
+- **`src/core/constraints.md`** — The Cardinal Rule, scope boundaries, drift detection
+
+### LLM Adapters
+- **`src/adapters/claude.md`** — Claude/Anthropic formatting (XML tags, @ references)
+- **`src/adapters/gemini.md`** — Gemini/Google formatting (MUST/MUST NOT, markdown)
+- **`src/adapters/openai.md`** — OpenAI/GPT formatting (system/user split, few-shot)
+
+### Command
+- **`src/commands/prompt-forge.md`** — Slash command entrypoint and invocation guide
+
+### Helpers
+- **`src/utils/helpers.md`** — Tone, collaboration style, complexity adaptation, delivery protocol
+
+### Templates
+- **`prompts/templates/task-type-blueprints.md`** — 8 task-type prompt structures
+- **`prompts/templates/gsd-output-format.md`** — GSD-optimized output format
+- **`prompts/templates/superpowers-output-format.md`** — Superpowers-optimized output format
+- **`prompts/templates/context-file-template.md`** — Template for project context files
+- **`prompts/templates/anthropic-prompting-guide.md`** — Anthropic prompting best practices
+
+### Examples
+- **`prompts/examples/example-session.md`** — Full walkthrough: vague input → 3 output formats
+
+### Evaluation
+- **`evals/test_cases.md`** — 14 functional test cases
+- **`evals/adversarial_cases.md`** — 15 boundary and failure mode tests
+- **`evals/benchmark.md`** — Cross-model benchmark framework (8 cases)
+- **`evals/scoring.md`** — Scoring rubric (clarity, constraints, structure, grounding, leakage)
+
+### Documentation
+- **`docs/architecture.md`** — System design and directory map
+- **`docs/usage.md`** — Integration and usage guide
+
+## Reference Files
+
+When building prompts, read the relevant references:
+
+- **Task-type blueprints** — Primary reference on every invocation
+- **Anthropic prompting guide** — Prompting principles: XML structuring, few-shot, chain-of-thought, grounding
+- **Context file template** — For generating project context files
+- **GSD/Superpowers output formats** — When plugins are detected

package/bin/install.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+
+// Colors
+const cyan = '\x1b[36m';
+const green = '\x1b[32m';
+const yellow = '\x1b[33m';
+const red = '\x1b[31m';
+const bold = '\x1b[1m';
+const dim = '\x1b[2m';
+const reset = '\x1b[0m';
+
+const pkg = require('../package.json');
+
+// Parse args
+const args = process.argv.slice(2);
+const hasClaude = args.includes('--claude');
+const hasGemini = args.includes('--gemini');
+const hasAll = args.includes('--all');
+const hasGlobal = args.includes('--global') || args.includes('-g');
+const hasLocal = args.includes('--local') || args.includes('-l');
+const hasUninstall = args.includes('--uninstall') || args.includes('-u');
+const hasHelp = args.includes('--help') || args.includes('-h');
+
+if (hasHelp) {
+  console.log(`
+${bold}Prompt Forge Installer v${pkg.version}${reset}
+
+${bold}Usage:${reset}
+  npx prompt-forge-cc@latest              ${dim}# Interactive install${reset}
+  npx prompt-forge-cc --claude --global   ${dim}# Claude Code, all projects${reset}
+  npx prompt-forge-cc --gemini --global   ${dim}# Gemini CLI, all projects${reset}
+  npx prompt-forge-cc --all --global      ${dim}# All runtimes${reset}
+  npx prompt-forge-cc --uninstall         ${dim}# Remove Prompt Forge${reset}
+
+${bold}Options:${reset}
+  --claude          Install for Claude Code
+  --gemini          Install for Gemini CLI
+  --all             Install for all runtimes
+  --global, -g      Install globally (all projects)
+  --local, -l       Install locally (current project only)
+  --uninstall, -u   Remove Prompt Forge
+  --help, -h        Show this help
+`);
+  process.exit(0);
+}
+
+// Skill files to copy (relative to package root)
+const SKILL_FILES = [
+  'SKILL.md',
+  'src/core/intent_parser.md',
+  'src/core/prompt_builder.md',
+  'src/core/constraints.md',
+  'src/core/modes.md',
+  'src/adapters/claude.md',
+  'src/adapters/gemini.md',
+  'src/adapters/openai.md',
+  'src/commands/prompt-forge.md',
+  'src/utils/helpers.md',
+  'prompts/templates/task-type-blueprints.md',
+  'prompts/templates/gsd-output-format.md',
+  'prompts/templates/superpowers-output-format.md',
+  'prompts/templates/context-file-template.md',
+  'prompts/templates/anthropic-prompting-guide.md',
+  'prompts/examples/example-session.md',
+  'evals/test_cases.md',
+  'evals/adversarial_cases.md',
+  'evals/benchmark.md',
+  'evals/scoring.md',
+  'docs/architecture.md',
+  'docs/usage.md',
+];
+
+const packageRoot = path.resolve(__dirname, '..');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function copyFileSync(src, dest) {
+  const destDir = path.dirname(dest);
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+  fs.copyFileSync(src, dest);
+}
+
+function removeDir(dir) {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+    return true;
+  }
+  return false;
+}
+
+function getTargetDir(runtime, isGlobal) {
+  const home = os.homedir();
+  if (runtime === 'claude') {
+    const base = isGlobal ? path.join(home, '.claude') : path.join(process.cwd(), '.claude');
+    return path.join(base, 'skills', 'prompt-forge');
+  }
+  if (runtime === 'gemini') {
+    const base = isGlobal ? path.join(home, '.gemini') : path.join(process.cwd(), '.gemini');
+    return path.join(base, 'skills', 'prompt-forge');
+  }
+  return null;
+}
+
+function installRuntime(runtime, isGlobal) {
+  const targetDir = getTargetDir(runtime, isGlobal);
+  if (!targetDir) return false;
+
+  const scope = isGlobal ? 'global' : 'local';
+  console.log(`\n${cyan}Installing Prompt Forge for ${bold}${runtime}${reset}${cyan} (${scope})...${reset}`);
+  console.log(`${dim}  Target: ${targetDir}${reset}`);
+
+  let copied = 0;
+  for (const file of SKILL_FILES) {
+    const src = path.join(packageRoot, file);
+    const dest = path.join(targetDir, file);
+    if (fs.existsSync(src)) {
+      copyFileSync(src, dest);
+      copied++;
+    }
+  }
+
+  console.log(`${green}  Copied ${copied} files.${reset}`);
+  return true;
+}
+
+function uninstallRuntime(runtime, isGlobal) {
+  const targetDir = getTargetDir(runtime, isGlobal);
+  if (!targetDir) return false;
+  if (removeDir(targetDir)) {
+    const scope = isGlobal ? 'global' : 'local';
+    console.log(`${green}  Removed Prompt Forge from ${runtime} (${scope}).${reset}`);
+    return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Interactive prompts
+// ---------------------------------------------------------------------------
+
+function createRL() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+function ask(rl, question) {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+async function promptRuntime(rl) {
+  console.log(`\n${bold}Which runtime?${reset}`);
+  console.log(`  ${cyan}1${reset} Claude Code`);
+  console.log(`  ${cyan}2${reset} Gemini CLI`);
+  console.log(`  ${cyan}3${reset} Both`);
+  const answer = await ask(rl, `\n${bold}Choose (1-3):${reset} `);
+  const choice = answer.trim();
+  if (choice === '1') return ['claude'];
+  if (choice === '2') return ['gemini'];
+  if (choice === '3') return ['claude', 'gemini'];
+  console.log(`${yellow}Invalid choice, defaulting to Claude Code.${reset}`);
+  return ['claude'];
+}
+
+async function promptScope(rl) {
+  console.log(`\n${bold}Install scope?${reset}`);
+  console.log(`  ${cyan}1${reset} Global ${dim}(all projects — recommended)${reset}`);
+  console.log(`  ${cyan}2${reset} Local  ${dim}(current project only)${reset}`);
+  const answer = await ask(rl, `\n${bold}Choose (1-2):${reset} `);
+  return answer.trim() === '2' ? false : true;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  console.log(`\n${bold}${cyan}Prompt Forge${reset} ${dim}v${pkg.version}${reset}`);
+  console.log(`${dim}A prompt compiler skill for coding agents${reset}`);
+
+  // Resolve runtimes
+  let runtimes = [];
+  if (hasAll) {
+    runtimes = ['claude', 'gemini'];
+  } else {
+    if (hasClaude) runtimes.push('claude');
+    if (hasGemini) runtimes.push('gemini');
+  }
+
+  let isGlobal = hasGlobal ? true : hasLocal ? false : null;
+
+  // Uninstall flow
+  if (hasUninstall) {
+    console.log(`\n${yellow}Uninstalling Prompt Forge...${reset}`);
+    let removed = false;
+    for (const runtime of ['claude', 'gemini']) {
+      removed = uninstallRuntime(runtime, true) || removed;
+      removed = uninstallRuntime(runtime, false) || removed;
+    }
+    if (!removed) {
+      console.log(`${dim}  Nothing to remove.${reset}`);
+    }
+    console.log(`\n${green}Done.${reset}\n`);
+    return;
+  }
+
+  // Interactive mode if no flags
+  if (runtimes.length === 0 || isGlobal === null) {
+    const rl = createRL();
+    try {
+      if (runtimes.length === 0) {
+        runtimes = await promptRuntime(rl);
+      }
+      if (isGlobal === null) {
+        isGlobal = await promptScope(rl);
+      }
+    } finally {
+      rl.close();
+    }
+  }
+
+  // Install
+  for (const runtime of runtimes) {
+    installRuntime(runtime, isGlobal);
+  }
+
+  // Done
+  console.log(`\n${green}${bold}Prompt Forge installed.${reset}`);
+  console.log(`\n${dim}Invoke with:${reset}`);
+  if (runtimes.includes('claude')) {
+    console.log(`  ${cyan}Claude Code:${reset}  /prompt-forge [your intent]`);
+  }
+  if (runtimes.includes('gemini')) {
+    console.log(`  ${cyan}Gemini CLI:${reset}   /prompt-forge [your intent]`);
+  }
+  console.log('');
+}
+
+main().catch((err) => {
+  console.error(`${red}Error: ${err.message}${reset}`);
+  process.exit(1);
+});