prompt-forge-cc 1.0.0

package/prompts/templates/superpowers-output-format.md

@@ -0,0 +1,89 @@
+# Superpowers Output Format
+
+How to structure Prompt Forge output when the target execution tool is Superpowers.
+
+Superpowers' brainstorming phase is where quality is won or lost. A rich, pre-analyzed prompt with design considerations already surfaced lets brainstorming go deeper — exploring architectural alternatives, edge cases, and failure modes instead of asking "what does this feature do?"
+
+---
+
+## For Brainstorming Input
+
+Structure as a rich feature brief with design considerations pre-loaded. The brainstorming skill will refine this, not extract it.
+
+```
+## Feature: [Name]
+
+### Intent
+[What I want to build and why — business context, user problem being solved]
+
+### Technical landscape
+- Stack: [framework, versions]
+- Affected code: @[list of files that will be touched]
+- Related implementations: @[similar feature already in codebase]
+- Test setup: [framework, patterns in @test-file]
+
+### Design considerations (for brainstorming to refine)
+
+**Architecture:** [How this fits into the existing codebase structure.
+Reference existing patterns. Flag any architectural decisions needed.]
+
+**Security:** [Auth implications, input validation needs, data exposure risks.
+Specific to this feature, not generic security advice.]
+
+**Performance:** [Expected load, caching considerations, query concerns.
+Reference specific DB queries or endpoints.]
+
+**UX:** [What the user sees/experiences, error states, loading states.]
+
+**Edge cases:** [Specific scenarios that could break, boundary conditions,
+error handling requirements.]
+
+### Testing strategy (for TDD planning)
+- Must test: [critical paths — feeds TDD red phase]
+- Edge cases to cover: [specific scenarios]
+- What NOT to test: [things already covered]
+
+### Research findings
+[Best practices for this specific pattern + stack.
+Known issues with current library versions.
+Alternative approaches considered and why the chosen one is preferred.]
+
+### Constraints
+- Don't modify: @[protected files]
+- Stay compatible with: [APIs, interfaces, contracts]
+- Version notes: [deprecation warnings from research]
+```
+
+---
+
+## For Direct Task Execution
+
+When the task doesn't need brainstorming (small, well-defined), structure it so planning and TDD phases have everything:
+
+```
+## Task: [Name]
+
+[Clear description — what to do]
+
+Files to modify: @[list]
+Follow pattern: @[reference]
+Test file: @[where tests should go, following @reference-test pattern]
+
+Test first:
+- RED: [what the failing test should assert]
+- GREEN: [minimal implementation to pass]
+- REFACTOR: [any cleanup needed]
+
+Constraints: [what not to touch]
+Verify: [command to run]
+```
+
+---
+
+## Detection Signals
+
+**Superpowers indicators:**
+- Skills directory with superpowers skills (brainstorming/, test-driven-development/)
+- `.claude-plugin/` with superpowers plugin.json
+- User mentions "superpowers", "brainstorm", "/superpowers:", "TDD workflow"
+- Agents directory with code-reviewer or similar

package/prompts/templates/task-type-blueprints.md

@@ -0,0 +1,317 @@
+# Task-Type Prompt Blueprints
+
+Each task type has a different prompt structure because each type requires different thinking from Claude Code. The prompt shape signals the right mode.
+
+Every blueprint includes a docs-check preamble — Claude Code should read the relevant project CLAUDE.md before starting work.
+
+---
+
+## 1. Bug Fix / Debugging
+
+**Thinking mode:** Investigate first, understand the root cause, then fix. Never guess-and-patch.
+
+```
+Before starting, read @CLAUDE.md for project conventions.
+
+## Bug report
+[What's happening — symptoms, error messages, reproduction steps]
+
+## Expected behavior
+[What should happen instead]
+
+## Affected code
+[Specific files/functions where the bug likely lives — grounded from code analysis]
+
+## Investigation steps
+1. First, reproduce the issue by [specific steps/commands]
+2. Read and understand the relevant code path: [grounded file list]
+3. Identify the root cause — explain what's wrong and why before writing any fix
+4. Check if this same bug pattern exists elsewhere in the codebase
+5. Implement the fix
+6. Verify the fix resolves the issue without introducing regressions
+
+## Constraints
+- Do NOT apply a surface-level patch — find and fix the root cause
+- Do NOT modify [files/modules that should stay untouched]
+- Preserve existing behavior for [related functionality]
+
+## Verification
+- Run `[actual test command from project]` — all tests must pass
+- Specifically test: [the exact scenario that was broken]
+- Run `[lint/typecheck command]` — no new warnings
+```
+
+---
+
+## 2. New Feature / Implementation
+
+**Thinking mode:** Follow existing patterns, build incrementally, verify as you go.
+
+```
+Before starting, read @CLAUDE.md for project conventions.
+
+## Context
+[What part of the app, current state, why this feature is needed — business context]
+
+## Feature requirements
+[Clear description of what to build]
+
+## Pattern reference
+Follow the existing implementation pattern in @[reference file] for:
+- [Routing / API structure]
+- [Validation approach]
+- [Error handling]
+- [Response format]
+- [Test structure]
+
+## Implementation plan
+1. [Step-by-step breakdown — each step is a verifiable unit]
+2. After each step, run `[test command]` to verify nothing broke
+3. [Continue steps...]
+
+## Scope boundaries
+- IN scope: [explicit list]
+- OUT of scope: [explicit list]
+- Do NOT refactor existing code unless directly necessary
+
+## Technical notes
+- [Version-specific guidance from web research]
+- [Dependency notes]
+- [Architecture notes from code analysis]
+
+## Done criteria
+- [ ] Feature works as described
+- [ ] Tests written and passing: `[test command]`
+- [ ] Types/interfaces updated
+- [ ] No lint errors: `[lint command]`
+- [ ] Follows existing patterns — code should look like it belongs
+```
+
+---
+
+## 3. Refactor / Code Improvement
+
+**Thinking mode:** Understand deeply, change structure without changing behavior, verify continuously.
+
+```
+Before starting, read @CLAUDE.md for project conventions.
+
+## Current state
+[What the code looks like now — specific files, the problem with the current structure]
+
+## Desired state
+[What the code should look like after — structural improvement, not new behavior]
+
+## The rule: behavior must not change
+This is a refactor, not a feature. External behavior must remain identical. Every existing test must continue to pass at every step.
+
+## Files in scope
+[Explicit grounded list]
+
+## Files NOT in scope — do not modify
+[Explicit list]
+
+## Approach
+1. First, run `[test command]` to establish a green baseline
+2. [First refactor step — small, verifiable]
+3. Run tests again — must still pass
+4. [Next step]
+5. Run tests again
+6. [Continue — never more than one structural change between test runs]
+
+## Verification
+- All existing tests pass: `[test command]`
+- No new lint warnings: `[lint command]`
+- No type errors: `[typecheck command]`
+- Git diff should show structural changes only — no behavior changes
+```
+
+---
+
+## 4. Migration / Upgrade
+
+**Thinking mode:** Incremental, backwards-compatible, rollback-aware. Never big-bang.
+
+```
+Before starting, read @CLAUDE.md for project conventions.
+
+## Migration overview
+[What's being migrated — from X to Y, why, what's at stake]
+
+## Current stack
+- [Framework/library]: [current version]
+- [Relevant config files]
+- [Current patterns in use]
+
+## Target stack
+- [Framework/library]: [target version]
+- [New patterns to adopt]
+- [Deprecations to address]
+
+## Migration strategy: incremental, not big-bang
+
+### Phase 1: Preparation
+1. [Setup step — install new dependency alongside old]
+2. Verify existing tests still pass: `[test command]`
+
+### Phase 2: Gradual migration
+1. [Migrate one module as a pilot]
+2. Test thoroughly: `[test command]`
+3. [Continue one at a time]
+
+### Phase 3: Cleanup
+1. [Remove old dependencies/code]
+2. [Update configs]
+3. Final full test run
+
+## Known gotchas
+[Version-specific issues from web research — breaking changes, renamed APIs]
+
+## Verification
+- Full test suite passes at each phase: `[test command]`
+- No deprecation warnings from [target framework]
+```
+
+---
+
+## 5. Performance Optimization
+
+**Thinking mode:** Measure first, optimize the bottleneck, verify improvement with numbers.
+
+```
+Before starting, read @CLAUDE.md for project conventions.
+
+## Performance problem
+[What's slow — specific endpoint, operation, or page. Include metrics if available]
+
+## Affected code
+[Grounded file paths and functions]
+
+## Investigation first — do NOT optimize before profiling
+1. Read and trace the full execution path
+2. Identify the actual bottleneck — DB queries? Network calls? Computation? Memory?
+3. If there are N+1 queries, count them
+4. Explain the bottleneck and proposed optimization before implementing
+
+## Optimization constraints
+- Do NOT change external API/behavior
+- Do NOT add new dependencies without mentioning it first
+- Readability over cleverness
+
+## Verification
+- Run existing tests: `[test command]` — must pass
+- [Benchmark command to prove improvement]
+- Check that related endpoints aren't negatively affected
+```
+
+---
+
+## 6. Security Hardening
+
+**Thinking mode:** Assume adversarial input. Audit systematically, fix comprehensively.
+
+```
+Before starting, read @CLAUDE.md for project conventions.
+
+## Security concern
+[What needs hardening — specific area, known vulnerability, or audit scope]
+
+## Systematic audit checklist
+For each file in scope, check:
+1. **Input validation** — Are all user inputs validated and sanitized?
+2. **Authentication** — Are protected routes properly guarded?
+3. **Authorization** — Can users access only their own resources?
+4. **Data exposure** — Are sensitive fields stripped from responses?
+5. **Secrets handling** — Are secrets in env vars, not hardcoded?
+6. **SQL/NoSQL injection** — Are queries parameterized?
+7. **XSS/CSRF** — Are outputs escaped? CSRF tokens in place?
+8. **Dependencies** — Run `npm audit` or equivalent
+
+## Fix approach
+- Explain the risk before fixing each vulnerability
+- Use the framework's built-in security features where available
+
+## Verification
+- All existing tests pass: `[test command]`
+- `npm audit` shows no high/critical vulnerabilities
+```
+
+---
+
+## 7. Investigation / Understanding Code
+
+**Thinking mode:** Read, trace, explain. No modifications unless explicitly asked.
+
+```
+Before starting, read @CLAUDE.md for project context.
+
+## What I want to understand
+[The question — how does X work? Why does Y happen?]
+
+## Starting points
+[Grounded file paths and functions]
+
+## Investigation approach
+1. Read the relevant code paths starting from [entry point]
+2. Trace the execution flow — what calls what, in what order
+3. Map dependencies
+4. Identify non-obvious behavior
+
+## Output format
+- High-level summary (2-3 sentences)
+- Step-by-step flow walkthrough
+- Call out anything surprising or risky
+
+## Rules
+- READ ONLY — do not modify any files
+- Don't guess — if something is ambiguous, say so
+```
+
+---
+
+## 8. Testing / Test Coverage
+
+**Thinking mode:** Understand the code's contract, then write tests that verify it — including edge cases.
+
+```
+Before starting, read @CLAUDE.md for testing conventions.
+
+## What to test
+[Specific module/function/endpoint — grounded paths]
+
+## Existing test setup
+- Test framework: [from package.json]
+- Test location: [where tests live]
+- Existing examples: follow patterns in @[reference test file]
+
+## Coverage requirements
+1. **Happy path** — [normal expected behavior]
+2. **Edge cases** — [specific edge cases from code analysis]
+3. **Error cases** — [what should fail and how]
+4. **Boundary conditions** — [empty arrays, null values, max lengths]
+
+## Constraints
+- Do NOT modify the source code — only add/modify test files
+- Use existing test utilities in @[test helpers file]
+
+## Verification
+- All new tests pass: `[test command]`
+- All existing tests still pass
+```
+
+---
+
+## Task Classification Guide
+
+| Signal | Task Type |
+|--------|-----------|
+| "bug", "broken", "not working", "error", "fix" | Bug Fix |
+| "add", "build", "create", "implement", "new" | New Feature |
+| "refactor", "clean up", "reorganize", "simplify" | Refactor |
+| "migrate", "upgrade", "update to", "switch from X to Y" | Migration |
+| "slow", "optimize", "performance", "speed up", "cache" | Performance |
+| "secure", "vulnerability", "auth", "injection", "audit" | Security |
+| "how does", "explain", "understand", "trace", "what does" | Investigation |
+| "test", "coverage", "spec", "write tests for" | Testing |
+
+If a task spans multiple types, use the **primary** type as the base and incorporate relevant sections from the secondary type. For compound tasks, suggest separate prompts.

package/src/adapters/claude.md

@@ -0,0 +1,86 @@
+# Claude Adapter
+
+Formats Prompt Forge output for Anthropic Claude models (Claude Code, Claude API, Claude chat).
+
+## Role Definition
+
+Claude responds best to direct, structured instructions with explicit constraints. It follows XML tags reliably and benefits from chain-of-thought prompting.
+
+```
+You are a senior software engineer working on this codebase. Follow instructions precisely.
+Read all referenced files before making changes. Verify your work after each step.
+```
+
+## Instruction Structure
+
+Claude excels with this layout:
+
+1. **Preamble** — Read project context first (`@CLAUDE.md`, referenced files)
+2. **Context block** — Background, stack, current state (use XML `<context>` tags for complex prompts)
+3. **Task block** — Clear, imperative instructions (use XML `<task>` tags)
+4. **Constraints block** — What NOT to do (use XML `<constraints>` tags)
+5. **Verification block** — Feedback loop commands (test, lint, typecheck)
+
+### XML Tag Usage
+
+Claude reliably parses XML structure. Use it for multi-section prompts:
+
+```xml
+<context>
+Express 4.18 + Prisma 5.x + PostgreSQL. Auth via JWT in @src/middleware/auth.ts.
+</context>
+
+<task>
+Add rate limiting to /api/login. Limit to 5 attempts per IP per 15-minute window.
+</task>
+
+<constraints>
+- Use existing Redis connection in @src/lib/redis.ts
+- Do not add new dependencies
+- Preserve existing error response format
+</constraints>
+
+<verification>
+Run `npm test` after changes. Fix any failures before completing.
+Run `npm run lint` — no new warnings.
+</verification>
+```
+
+For simple prompts, skip XML — plain markdown with clear sections works fine.
+
+## Constraint Formatting
+
+Claude respects constraints best when they are:
+- **Explicit and negative** — "Do NOT modify auth.ts" over "be careful with auth.ts"
+- **Positioned after the task** — constraints after instructions reduce accidental ignoring
+- **Grouped together** — one constraints section, not scattered throughout
+- **Explained briefly** — "Do NOT use class components — project migrated to hooks in Q3" is stronger than "Do NOT use class components"
+
+## Output Expectations
+
+Tell Claude what format to deliver results in:
+
+```
+After implementing:
+1. Run `npm test` — report pass/fail
+2. Run `npm run typecheck` — report any errors
+3. Summarize what you changed and why
+```
+
+Claude benefits from explicit feedback loops — "run X, then fix any issues" produces 2-3x better results than "make sure it works."
+
+## @ Reference Convention
+
+Claude Code uses `@filename` to reference files. Always use this syntax:
+- `@src/routes/orders.ts` not "the orders route file"
+- `@CLAUDE.md` not "the project conventions"
+
+## Mode Adjustments for Claude
+
+| Mode | Claude-Specific Emphasis |
+|------|-------------------------|
+| build | Reference existing patterns with @ syntax, step-by-step with test gates |
+| audit | XML `<constraints>` block, explicit negative instructions, checklist format |
+| debug | "Explain what's wrong before fixing" — Claude naturally supports chain-of-thought |
+| research | "Read these files, then explain" — leverage Claude's strong comprehension |
+| optimize | "Profile first, propose second, implement third" — explicit ordering |

package/src/adapters/gemini.md

@@ -0,0 +1,89 @@
+# Gemini Adapter
+
+Formats Prompt Forge output for Google Gemini models (Gemini CLI, Gemini API, AI Studio).
+
+## Role Definition
+
+Gemini responds well to clear role framing and benefits from structured markdown. It handles long context well and supports grounding with Google Search.
+
+```
+Role: Senior software engineer performing a focused task on this codebase.
+Approach: Read all relevant files first, then plan your approach, then implement.
+Standard: Production-quality code that follows existing project patterns.
+```
+
+## Instruction Structure
+
+Gemini works best with this layout:
+
+1. **Role and approach** — Set the persona and methodology upfront
+2. **Context** — Background information, stack details, file references
+3. **Task** — Clear, numbered steps with explicit ordering
+4. **Rules** — Constraints as a bulleted list with "MUST" / "MUST NOT" language
+5. **Output format** — What to deliver and how to verify
+
+### Markdown Structure
+
+Gemini parses markdown headers and lists reliably. Use them for structure:
+
+```markdown
+## Context
+Express 4.18 app with Prisma 5.x and PostgreSQL.
+Auth handled by JWT middleware in `src/middleware/auth.ts`.
+
+## Task
+1. Add rate limiting to `/api/login`
+2. Limit to 5 attempts per IP per 15-minute window
+3. Use the existing Redis connection in `src/lib/redis.ts`
+
+## Rules
+- MUST NOT add new dependencies
+- MUST NOT change the existing error response format
+- MUST follow the middleware pattern in `src/middleware/auth.ts`
+
+## Verification
+- Run `npm test` — all tests pass
+- Run `npm run lint` — no new warnings
+```
+
+## Constraint Formatting
+
+Gemini responds best to constraints when they use:
+- **MUST / MUST NOT** language — stronger signal than "don't" or "avoid"
+- **Rules section** — separated clearly from the task itself
+- **Positive + negative pairs** — "MUST use Prisma client, MUST NOT write raw SQL"
+- **Numbered priority** — if constraints conflict, number them by importance
+
+## Output Expectations
+
+Gemini benefits from explicit output structure requests:
+
+```
+## Expected Output
+1. Modified files with changes explained
+2. Test results from `npm test`
+3. Summary of approach taken and any trade-offs
+```
+
+## File Reference Convention
+
+Gemini CLI uses backtick paths. Always use:
+- `src/routes/orders.ts` not "the orders route file"
+- Include relative paths from project root
+
+## Grounding Note
+
+Gemini has native Google Search grounding. For research-heavy prompts, you can include:
+```
+Use Google Search to verify current best practices for [topic] before implementing.
+```
+
+## Mode Adjustments for Gemini
+
+| Mode | Gemini-Specific Emphasis |
+|------|------------------------|
+| build | Numbered step-by-step, explicit pattern references with file paths |
+| audit | MUST/MUST NOT rules list, checklist output format |
+| debug | "Analyze → Hypothesize → Verify → Fix" — explicit methodology steps |
+| research | Leverage search grounding, ask for alternatives with trade-off tables |
+| optimize | Request measurement data in structured table format before/after |

package/src/adapters/openai.md

@@ -0,0 +1,100 @@
+# OpenAI Adapter
+
+Formats Prompt Forge output for OpenAI models (GPT-4o, o1/o3, Codex, ChatGPT).
+
+## Role Definition
+
+OpenAI models respond strongly to system-level role definition. Set the persona clearly:
+
+```
+You are a senior software engineer. You write clean, tested, production-ready code.
+You follow existing project patterns exactly. You verify your work before reporting completion.
+```
+
+## Instruction Structure
+
+OpenAI models work best with this layout:
+
+1. **System context** — Role + project background (maps to system message in API)
+2. **User task** — Direct, imperative instructions
+3. **Constraints** — Boundaries and prohibitions as a clear list
+4. **Examples** — Few-shot examples when pattern-following is critical
+5. **Output specification** — What format to deliver in
+
+### System/User Split
+
+For API usage, structure maps naturally to message roles:
+
+```
+[System]
+You are a senior engineer working on an Express 4.18 + Prisma 5.x + PostgreSQL app.
+Project conventions: services are class-based, routes use Zod validation,
+errors follow AppError pattern in src/lib/errors.ts.
+
+[User]
+Add rate limiting to /api/login. Limit to 5 attempts per IP per 15-minute window.
+
+Requirements:
+- Use existing Redis connection in src/lib/redis.ts
+- Do not add new dependencies
+- Preserve existing error response format
+- Follow middleware pattern in src/middleware/auth.ts
+
+After implementing, run `npm test` and fix any failures.
+```
+
+For chat/agent usage, combine into a single structured prompt with clear sections.
+
+## Constraint Formatting
+
+OpenAI models respect constraints best when:
+- **Listed explicitly** — bullet points, not embedded in prose
+- **Negative constraints are bolded** — "**Do NOT** modify auth.ts"
+- **Placed after the task** — instructions first, then boundaries
+- **Few-shot reinforced** — if a constraint is critical, show an example of correct behavior
+
+## Output Expectations
+
+OpenAI models benefit from explicit format requests:
+
+```
+Output format:
+1. List of files changed
+2. For each file: what changed and why
+3. Test results
+4. Any concerns or follow-up items
+```
+
+For code generation, specify: "Write complete, runnable code — not pseudocode or snippets."
+
+## File Reference Convention
+
+Use standard path notation:
+- `src/routes/orders.ts` not "the orders file"
+- Include full relative paths from project root
+- For multi-file tasks, list all files upfront
+
+## Few-Shot Patterns
+
+OpenAI models benefit significantly from examples. When the task requires following a specific pattern:
+
+```
+Example of the pattern to follow (from src/routes/orders.ts):
+- Router definition at top
+- Zod schema for validation
+- Auth middleware in chain
+- Service call, not direct DB access
+- JSON response with consistent format
+
+Now apply this same pattern to create src/routes/payments.ts.
+```
+
+## Mode Adjustments for OpenAI
+
+| Mode | OpenAI-Specific Emphasis |
+|------|------------------------|
+| build | Few-shot examples from codebase, explicit pattern references |
+| audit | Bold **DO NOT** constraints, checklist output with pass/fail |
+| debug | Chain-of-thought: "Think step by step about what could cause this" |
+| research | Request structured comparison tables, pros/cons format |
+| optimize | Ask for profiling analysis before implementation, metrics-focused |