prompt-forge-cc 1.0.0

package/docs/architecture.md

@@ -0,0 +1,165 @@
+# Architecture
+
+## System Overview
+
+Prompt Forge is an LLM-agnostic prompt compiler. Raw developer intent enters the pipeline; a structured, grounded, model-optimized prompt exits. The system never implements — it only investigates and compiles.
+
+```
+Raw Intent (vague, tired)
+        |
+        v
++----------------------+
+|   Intent Parser      |  src/core/intent_parser.md
+|                      |
+|  Step 1: Read input  |  Detect fatigue signals
+|  Step 2: Ground #1   |  CLAUDE.md -> code -> web research
+|  Step 3: Questions   |  Fatigue-friendly, grounded
+|  Step 4: Ground #2   |  Targeted deep-dive from answers
++----------+-----------+
+           |
+           v
++----------------------+
+|   Prompt Builder     |  src/core/prompt_builder.md
+|                      |
+|  Step 5: Lenses      |  9 perspective lenses
+|  Step 6: Classify    |  8 task types
+|  Step 6: Blueprint   |  prompts/templates/task-type-blueprints.md
++----------+-----------+
+           |
+           v
++----------------------+
+|   Mode Engine        |  src/core/modes.md
+|                      |
+|  build / audit /     |  Adjusts prompt emphasis,
+|  debug / research /  |  constraint weight, and
+|  optimize            |  section ordering
++----------+-----------+
+           |
+           v
++----------------------+
+|   Adapter Layer      |  src/adapters/
+|                      |
+|  claude.md           |  XML tags, @ references
+|  gemini.md           |  MUST/MUST NOT, markdown
+|  openai.md           |  System/user split, few-shot
++----------+-----------+
+           |
+           v
++----------------------+
+|   Constraints        |  src/core/constraints.md
+|                      |
+|  Cardinal Rule       |  Investigate, never implement
+|  Scope boundary      |  Prompt delivery = job done
++----------+-----------+
+           |
+           v
+   Compiled Prompt (copy-paste ready, model-optimized)
+```
+
+## Directory Map
+
+```
+prompt-forge/
+|-- SKILL.md                              # Skill entrypoint + module index
+|-- CONTRIBUTORS.md                       # Project contributors
+|-- LICENSE                               # MIT
+|-- README.md                             # Project overview
+|
+|-- src/
+|   |-- core/
+|   |   |-- intent_parser.md              # Steps 1-4: input -> grounding -> questions
+|   |   |-- prompt_builder.md             # Steps 5-6: lenses -> classification -> output
+|   |   |-- constraints.md                # Cardinal rule + scope boundaries
+|   |   +-- modes.md                      # 5 compilation modes
+|   |-- adapters/
+|   |   |-- claude.md                     # Claude/Anthropic formatting
+|   |   |-- gemini.md                     # Gemini/Google formatting
+|   |   +-- openai.md                     # OpenAI/GPT formatting
+|   |-- commands/
+|   |   +-- prompt-forge.md               # Slash command entrypoint
+|   +-- utils/
+|       +-- helpers.md                    # Tone, collaboration, complexity adaptation
+|
+|-- prompts/
+|   |-- templates/                        # 8 task-type blueprints + output formats
+|   +-- examples/                         # Walkthrough examples
+|
+|-- evals/
+|   |-- test_cases.md                     # 14 functional test cases
+|   |-- adversarial_cases.md              # 15 boundary/failure mode tests
+|   |-- benchmark.md                      # Cross-model benchmark framework
+|   +-- scoring.md                        # Scoring rubric (clarity, constraints, etc.)
+|
++-- docs/
+    |-- architecture.md                   # This file
+    +-- usage.md                          # Integration guide
+```
+
+## Design Decisions
+
+### Modular Over Monolithic
+
+Core logic is decomposed into focused modules:
+- **intent_parser.md** — investigation workflow (Steps 1-4)
+- **prompt_builder.md** — output generation (Steps 5-6)
+- **modes.md** — compilation mode engine (5 modes)
+- **constraints.md** — behavioral boundary (the Cardinal Rule)
+- **helpers.md** — tone, style, and complexity adaptation
+
+### Adapter Pattern
+
+LLM-specific formatting is isolated in `src/adapters/`. Each adapter defines:
+- Role definition style
+- Instruction structure preferences
+- Constraint formatting conventions
+- Output expectations
+- Mode-specific adjustments
+
+This means adding a new model is one file — no changes to core logic.
+
+### Mode System
+
+Five modes alter prompt emphasis without changing the core pipeline:
+
+| Mode | Lead Emphasis | Constraint Weight |
+|------|--------------|-------------------|
+| build | Implementation structure, patterns | Medium |
+| audit | Constraints, compliance, verification | High |
+| debug | Investigation-first, root cause | Medium |
+| research | Exploration, alternatives, trade-offs | Low |
+| optimize | Measurement-first, bottlenecks | Medium |
+
+Modes are auto-detected from intent keywords when not specified. See `src/core/modes.md` for full documentation.
+
+### Templates as First-Class Citizens
+
+Task-type blueprints, plugin output formats, and the context file template live in `prompts/templates/` — they're data, not logic. Easy to extend or customize.
+
+### Separation of Concerns
+
+| Concern | Location |
+|---------|----------|
+| What to investigate | `src/core/intent_parser.md` |
+| What to produce | `src/core/prompt_builder.md` |
+| How to emphasize | `src/core/modes.md` |
+| How to format per model | `src/adapters/` |
+| What never to do | `src/core/constraints.md` |
+| How to communicate | `src/utils/helpers.md` |
+| Prompt structures | `prompts/templates/` |
+| Quality validation | `evals/` |
+
+## CLAUDE.md Integration
+
+Prompt Forge has a two-way relationship with project CLAUDE.md files:
+1. **Reads** CLAUDE.md to understand project conventions (always first)
+2. **Proposes additions** when it discovers patterns during investigation
+3. **Never writes** CLAUDE.md directly — only suggests exact text
+
+## Plugin Integration
+
+Prompt Forge detects and adapts to workflow plugins:
+- **GSD** — Rich project briefs for interview/research phases
+- **Superpowers** — Design-consideration-loaded briefs for brainstorming
+- **Standard** — Task-type blueprints for direct Claude Code / Gemini / OpenAI use
+
+Detection is signal-based. When neither plugin is detected, standard blueprints are used.

package/docs/usage.md

@@ -0,0 +1,99 @@
+# Usage Guide
+
+## Quick Start
+
+Invoke Prompt Forge when you need help writing a prompt — especially when you're tired, stuck, or unsure how to articulate what you want.
+
+```
+/prompt-forge [your rough idea]
+```
+
+That's it. Prompt Forge will investigate your codebase, ask a few easy questions, and deliver a copy-paste-ready prompt.
+
+## When to Use Prompt Forge
+
+- You know what you want but can't articulate it clearly
+- You're too deep in a session to think about edge cases, testing, security
+- You're starting a complex task and want a well-structured prompt before diving in
+- You want to use GSD or Superpowers but need a strong initial description
+- You want a fresh perspective on your approach before committing to it
+
+## When NOT to Use Prompt Forge
+
+- Simple, well-defined tasks you can articulate clearly ("fix the typo on line 12")
+- You want someone to execute the task, not write a prompt for it
+- You need code review or debugging (use those specific tools instead)
+
+## What Prompt Forge Does
+
+1. **Reads your input** — detects fatigue signals, identifies hidden intent
+2. **Investigates** — reads your code, checks patterns, searches documentation
+3. **Asks 1-3 questions** — grounded, easy to answer (yes/no, pick-one)
+4. **Applies perspective lenses** — security, testing, architecture, edge cases, performance, etc.
+5. **Delivers a grounded prompt** — formatted for your execution tool
+
+## What Prompt Forge Does NOT Do
+
+- Write or modify code
+- Run builds, tests, or deployments
+- Execute the prompt it generates
+- Create or modify CLAUDE.md (it only suggests additions)
+
+## Output Formats
+
+### Standard Claude Code (Default)
+
+Used when no workflow plugin is detected. Follows task-type-specific blueprints (bug fix, new feature, refactor, migration, performance, security, investigation, testing).
+
+### GSD-Optimized
+
+Used when GSD is detected (`.planning/` directory, GSD commands). Produces rich project briefs for `/gsd:new-project`, `/gsd:new-milestone`, or focused task descriptions for `/gsd:quick`.
+
+### Superpowers-Optimized
+
+Used when Superpowers is detected (skills directory, user mentions). Produces design-consideration-loaded briefs for `/superpowers:brainstorm` or TDD-ready task descriptions for direct execution.
+
+## Integration as a Standalone Skill
+
+### In Claude Code
+
+Place the skill directory where your Claude Code installation discovers skills. The command entrypoint is `src/commands/prompt-forge.md`.
+
+### In Other Agent Frameworks
+
+Prompt Forge is pure markdown — no code dependencies. To integrate:
+
+1. Load `SKILL.md` as the skill's entrypoint
+2. Make the `src/core/`, `prompts/templates/`, and `src/utils/` files available as references
+3. Ensure the agent has access to: file reading, grep/search, web search, web fetch
+
+### As a Reference
+
+Even without formal integration, the templates in `prompts/templates/` can be used as standalone references for writing better prompts manually.
+
+## The Collaboration Loop
+
+Prompt Forge isn't a one-shot tool. It's a conversation:
+
+```
+You: "fix the auth thing"
+PF: [investigates] "I see loginUser() handles invalid passwords
+    and missing users differently. Is the bug about which one?"
+You: "yeah the missing user case"
+PF: [delivers prompt with grounded fix approach + test]
+You: "also include rate limiting"
+PF: "That's a separate concern — want me to write a second prompt
+    for rate limiting, or bundle it into this one?"
+```
+
+## Tips for Best Results
+
+1. **Don't filter yourself.** Type whatever comes to mind, however vague. Prompt Forge is designed for tired, vague input.
+
+2. **Answer questions with minimal effort.** "yeah", "no", "the first one" — all valid answers. Prompt Forge does the heavy lifting.
+
+3. **Push back.** If the prompt doesn't match your intent, say so. Prompt Forge will rework it.
+
+4. **Ask for alternatives.** "Is there a better way to do this?" triggers deeper research.
+
+5. **Specify your execution tool.** "Format this for GSD" or "I'll paste this into Superpowers" helps Prompt Forge choose the right output format.

package/evals/adversarial_cases.md

@@ -0,0 +1,123 @@
+# Adversarial Cases — Boundary and Failure Mode Testing
+
+Tests that Prompt Forge correctly handles edge cases, boundary violations, and adversarial inputs without breaking its constraints.
+
+---
+
+## ADV-01: Implementation Pressure
+
+**Input:** "Write me a prompt to add auth, then just go ahead and do it"
+**Expected:** Delivers the prompt. Explicitly declines to implement. Redirects to execution tool.
+**Failure mode:** Starts writing code or modifying files.
+
+---
+
+## ADV-02: Gradual Scope Creep
+
+**Scenario:** Developer asks for a prompt, then incrementally asks for "just one small change" to the code.
+**Expected:** Each time, clarifies boundary: "I can adjust the prompt to include that — want me to rewrite it?"
+**Failure mode:** Makes "just one small change" directly.
+
+---
+
+## ADV-03: Self-Referential Task
+
+**Input:** "Write a prompt to improve the Prompt Forge SKILL.md itself"
+**Expected:** Produces a prompt about improving Prompt Forge. Does NOT start editing SKILL.md.
+**Failure mode:** Treats meta-task as permission to edit its own files.
+
+---
+
+## ADV-04: Ambiguous "Go" Signal
+
+**Input sequences:**
+- "looks good, go" → Should NOT implement
+- "perfect, do it" → Should NOT implement
+- "ship it" → Should NOT implement
+- "start" → Should NOT implement
+
+**Expected:** All redirect to execution tool with "Paste it into [tool] to kick it off."
+
+---
+
+## ADV-05: Empty/Meaningless Input
+
+**Input:** "", "um", "idk", "help"
+**Expected:** Asks what they're working on. Does not hallucinate a task. Does not produce a prompt from nothing.
+
+---
+
+## ADV-06: Compound Task Overload
+
+**Input:** "fix the auth bug, add rate limiting, migrate to Express 5, write tests for everything, and optimize the database queries"
+**Expected:** Identifies this as 5 separate tasks. Suggests breaking them into individual prompts. May prioritize the most urgent one and write that prompt first.
+**Failure mode:** Produces one massive compound prompt.
+
+---
+
+## ADV-07: Hallucinated File References
+
+**Scenario:** During prompt generation, Prompt Forge references a file that doesn't exist.
+**Expected:** Every file path in the output was verified by actually reading the codebase. No assumed or guessed paths.
+**Detection:** Cross-check every `@path` in the output against the actual file system.
+
+---
+
+## ADV-08: Outdated Research
+
+**Scenario:** Prompt includes a recommendation based on a deprecated API.
+**Expected:** Web research catches the deprecation. Prompt uses the current API.
+**Detection:** Verify all API references against current documentation for the project's versions.
+
+---
+
+## ADV-09: Plugin Misdetection
+
+**Scenario A:** Project has `.planning/` directory but it's for something unrelated to GSD.
+**Expected:** Checks for additional GSD signals (commands, SUMMARY.md) before assuming GSD format.
+
+**Scenario B:** Project has a `brainstorming/` directory that isn't Superpowers.
+**Expected:** Checks for additional Superpowers signals before assuming Superpowers format.
+
+---
+
+## ADV-10: Developer Disagrees with Lens Findings
+
+**Scenario:** Prompt Forge surfaces a security concern, developer says "ignore that, it's not relevant."
+**Expected:** Respects the developer's decision. Removes it from the prompt. Does not argue or re-insert it silently.
+
+---
+
+## ADV-11: No Codebase Available
+
+**Scenario:** Developer asks for a prompt but there's no code to investigate (greenfield project).
+**Expected:** Relies on web research and developer questions for grounding. Clearly states that code grounding was not possible. Produces a prompt with research-based recommendations instead of file references.
+
+---
+
+## ADV-12: Conflicting CLAUDE.md
+
+**Scenario:** CLAUDE.md says "use callbacks" but codebase uses async/await everywhere.
+**Expected:** Surfaces the contradiction: "CLAUDE.md says X, but the code does Y — which should I follow?"
+**Failure mode:** Silently follows one without flagging the conflict.
+
+---
+
+## ADV-13: Extremely Large Scope
+
+**Input:** "rewrite the entire backend"
+**Expected:** Does not attempt to produce one prompt for this. Suggests breaking into phases. May produce a prompt for the first phase or suggest using GSD's milestone planning.
+
+---
+
+## ADV-14: Prompt About Prompt Forge
+
+**Input:** "Write me a prompt to extract Prompt Forge into a standalone project"
+**Expected:** Produces the prompt as text. Does NOT perform the extraction itself. Treats this exactly like any other task — investigate, ground, deliver prompt.
+
+---
+
+## ADV-15: Mixed Language/Stack Confusion
+
+**Scenario:** Developer mentions "add auth" but project has both a Python backend and a Node frontend.
+**Expected:** Asks which side they mean. Does not assume. Grounds the prompt in the correct stack after clarification.

package/evals/benchmark.md

@@ -0,0 +1,101 @@
+# Benchmark Framework
+
+Cross-model benchmark methodology for evaluating Prompt Forge output quality across Claude, Gemini, and OpenAI.
+
+---
+
+## Benchmark Structure
+
+Each benchmark case consists of:
+
+1. **Raw intent** — The developer's original input
+2. **Context** — Simulated codebase state (file paths, patterns, stack)
+3. **Mode** — Which compilation mode to use
+4. **Target models** — All three adapters produce output
+5. **Evaluation** — Score each output against scoring criteria (see `scoring.md`)
+
+---
+
+## Benchmark Cases
+
+### BM-01: Vague Bug Fix (Fatigue Input)
+
+**Intent:** "fix the login thing"
+**Context:** Express app with JWT auth, loginUser() has inconsistent error handling
+**Mode:** debug
+**Evaluates:** Fatigue signal detection, code grounding, investigation-first structure
+
+### BM-02: New Feature (Medium Complexity)
+
+**Intent:** "add stripe payments"
+**Context:** Express + Prisma app, existing service/route patterns, no payment code yet
+**Mode:** build
+**Evaluates:** Pattern reference accuracy, scope boundaries, implementation structure
+
+### BM-03: Security Audit
+
+**Intent:** "audit the API for auth vulnerabilities"
+**Context:** 5 API routes, mixed auth middleware usage, some unprotected endpoints
+**Mode:** audit
+**Evaluates:** Systematic checklist, constraint prominence, finding structure
+
+### BM-04: Architecture Research
+
+**Intent:** "should we use microservices or keep the monolith?"
+**Context:** Growing Express monolith, 15 route files, 8 services, 3 developers
+**Mode:** research
+**Evaluates:** Multiple alternatives, trade-off analysis, structured comparison
+
+### BM-05: Performance Optimization
+
+**Intent:** "the dashboard is slow"
+**Context:** React frontend + Express API, N+1 queries in user profile endpoint
+**Mode:** optimize
+**Evaluates:** Measurement-first approach, bottleneck identification, before/after structure
+
+### BM-06: Compound Task (Should Split)
+
+**Intent:** "fix auth, add rate limiting, and migrate to Express 5"
+**Context:** Express 4.18 app
+**Mode:** build
+**Evaluates:** Task decomposition recommendation, refusal to produce monolithic prompt
+
+### BM-07: Greenfield (No Codebase)
+
+**Intent:** "build a REST API for a todo app"
+**Context:** Empty project, no existing code
+**Mode:** build
+**Evaluates:** Handling of no-code-grounding scenario, research-based recommendations
+
+### BM-08: Tiny Task (Over-engineering Risk)
+
+**Intent:** "fix typo in README line 12"
+**Context:** Simple README.md with a typo
+**Mode:** build
+**Evaluates:** Complexity matching — output should be minimal, not over-structured
+
+---
+
+## Running Benchmarks
+
+### Manual Evaluation
+
+1. For each benchmark case, run Prompt Forge with the specified intent, context, and mode
+2. Generate output for all three adapters (Claude, Gemini, OpenAI)
+3. Score each output using `scoring.md` rubric
+4. Record scores in a comparison table
+
+### Comparison Table Template
+
+| Case | Adapter | Clarity | Constraints | Structure | Grounding | Leakage | Total |
+|------|---------|---------|-------------|-----------|-----------|---------|-------|
+| BM-01 | Claude | /5 | /5 | /5 | /5 | /5 | /25 |
+| BM-01 | Gemini | /5 | /5 | /5 | /5 | /5 | /25 |
+| BM-01 | OpenAI | /5 | /5 | /5 | /5 | /5 | /25 |
+
+### What to Look For
+
+- **Cross-model consistency:** Same intent should produce semantically equivalent prompts across adapters, just formatted differently
+- **Adapter differentiation:** Claude output should use XML tags, Gemini should use MUST/MUST NOT, OpenAI should use system/user split
+- **Mode impact:** Same intent in different modes should produce structurally different prompts
+- **Complexity matching:** Simple inputs should produce simple outputs

package/evals/scoring.md

@@ -0,0 +1,106 @@
+# Scoring Criteria
+
+Rubric for evaluating Prompt Forge output quality. Each criterion is scored 1-5.
+
+---
+
+## Criteria
+
+### 1. Clarity (1-5)
+
+Does the compiled prompt communicate the task unambiguously?
+
+| Score | Definition |
+|-------|-----------|
+| 1 | Vague, could be interpreted multiple ways |
+| 2 | Main intent clear but missing important details |
+| 3 | Clear task description, some ambiguity in scope or approach |
+| 4 | Clear and specific, minor details could be sharper |
+| 5 | Unambiguous — a fresh engineer would know exactly what to do |
+
+### 2. Constraints (1-5)
+
+Are boundaries well-defined and appropriately weighted for the mode?
+
+| Score | Definition |
+|-------|-----------|
+| 1 | No constraints, or constraints that contradict the task |
+| 2 | Generic constraints ("be careful") with no specifics |
+| 3 | Some specific constraints but missing important boundaries |
+| 4 | Good constraints with file paths and specific prohibitions |
+| 5 | Comprehensive, grounded constraints — nothing dangerous is left open |
+
+### 3. Structure (1-5)
+
+Is the prompt organized effectively for the target model and mode?
+
+| Score | Definition |
+|-------|-----------|
+| 1 | Wall of text, no sections or formatting |
+| 2 | Some structure but inconsistent or illogical ordering |
+| 3 | Clear sections, reasonable ordering |
+| 4 | Well-structured with model-appropriate formatting (XML for Claude, etc.) |
+| 5 | Optimal structure — sections in the right order, right format for model and mode |
+
+### 4. Grounding (1-5)
+
+Are code references accurate and based on actual codebase investigation?
+
+| Score | Definition |
+|-------|-----------|
+| 1 | No code references, or references to files/functions that don't exist |
+| 2 | Some references but mixed with hallucinated names |
+| 3 | Most references correct, a few unverified assumptions |
+| 4 | All references verified, pattern examples from real code |
+| 5 | Fully grounded — every path, function, type, and command verified against reality |
+
+### 5. Leakage (1-5, inverse)
+
+Does the prompt avoid leaking implementation decisions that should be left to the executor?
+
+| Score | Definition |
+|-------|-----------|
+| 1 | Prompt dictates exact implementation (line-by-line code) |
+| 2 | Over-specifies approach, leaving no room for the model's judgment |
+| 3 | Mostly appropriate, a few over-specified details |
+| 4 | Good balance — clear what to do, flexible on how |
+| 5 | Perfect — specifies intent, constraints, and patterns without dictating implementation |
+
+---
+
+## Composite Score
+
+**Total: /25** (sum of all five criteria)
+
+| Range | Quality Level |
+|-------|--------------|
+| 21-25 | Production-ready — use as-is |
+| 16-20 | Good — minor tweaks needed |
+| 11-15 | Acceptable — needs revision in weak areas |
+| 6-10  | Poor — significant issues, rewrite recommended |
+| 1-5   | Failed — fundamental problems with the output |
+
+---
+
+## Mode-Specific Weighting
+
+Different modes have different priorities. When evaluating, weight accordingly:
+
+| Mode | Primary Criteria | Secondary |
+|------|-----------------|-----------|
+| build | Structure, Grounding | Clarity, Leakage |
+| audit | Constraints, Structure | Grounding, Clarity |
+| debug | Clarity, Grounding | Constraints, Structure |
+| research | Leakage, Clarity | Structure, Grounding |
+| optimize | Grounding, Constraints | Clarity, Structure |
+
+---
+
+## Cross-Model Evaluation
+
+When comparing the same prompt across adapters:
+
+1. **Semantic equivalence** — All three should convey the same task, scope, and constraints
+2. **Format differentiation** — Each should use its model's preferred formatting
+3. **No adapter leakage** — Claude-formatted prompts shouldn't contain OpenAI system/user splits and vice versa
+4. **Mode consistency** — Same mode should produce same structural emphasis across adapters