ai-prompt-framework-helper 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcos Castro
+
+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,130 @@
+# AI Prompt Framework Helper — CLI
+
+> Interactive terminal assistant to build structured AI prompts using **APE**, **CO-STAR**, **RISEN** and **RTCCF** frameworks. Works with any AI CLI — Claude, Gemini, llm, aichat, and more.
+
+[![npm version](https://img.shields.io/npm/v/ai-prompt-framework-helper)](https://www.npmjs.com/package/ai-prompt-framework-helper)
+[![license](https://img.shields.io/npm/l/ai-prompt-framework-helper)](./LICENSE)
+
+---
+
+## Install
+
+```bash
+npm install -g ai-prompt-framework-helper
+```
+
+```bash
+# or with other package managers
+pnpm add -g ai-prompt-framework-helper
+yarn global add ai-prompt-framework-helper
+bun add -g ai-prompt-framework-helper
+```
+
+No external dependencies. Requires Node.js ≥ 16.
+
+---
+
+## Usage
+
+```bash
+ai-prompt
+```
+
+The tool will:
+1. Auto-detect any AI CLIs installed on your system
+2. Ask you to choose a framework
+3. Guide you field by field
+4. Show a live preview of the generated prompt
+5. Let you run it directly, copy it, pipe it, or save it
+
+```bash
+# Pipe the output directly to any AI CLI
+ai-prompt | claude
+ai-prompt | gemini
+ai-prompt | llm
+```
+
+---
+
+## Frameworks
+
+| Framework | Stands for | Best for |
+|-----------|------------|----------|
+| **APE** | Action · Purpose · Expectation | Fast, focused tasks |
+| **CO-STAR** | Context · Objective · Style · Tone · Audience · Response | Copy, emails, content |
+| **RISEN** | Role · Instructions · Steps · End Goal · Narrowing | Workflows, plans, execution |
+| **RTCCF** | Role · Task · Context · Constraints · Format | Full project kickstart |
+
+---
+
+## Demo
+
+```
+⬡  AI Prompt Framework Helper  ·  CLI
+by Marcos Castro · marcoscv.github.io
+
+✓ Detected AI CLIs: claude  gemini
+
+Select a framework:
+
+  [1]  APE       Action · Purpose · Expectation
+       ↳ Fastest. Ideal for focused, well-defined tasks.
+
+  [2]  CO-STAR   Context · Objective · Style · Tone · Audience · Response
+       ↳ Best for copy, emails, content, presentations.
+  ...
+
+→ 2
+
+── CO-STAR ──────────────────────────────────────────────────────────────
+  Context · Objective · Style · Tone · Audience · Response
+  ↳ Best for copy, emails, content, presentations.
+─────────────────────────────────────────────────────────────────────────
+
+  [C] CONTEXT  (required)
+  What's the background or situation?
+  → We are launching a B2B SaaS for project management
+
+  [O] OBJECTIVE  (required)
+  What outcome do you want to achieve?
+  → Write a landing page that converts visitors into trial sign-ups
+  ...
+
+── Generated Prompt ──────────────────────────────────────────────────────
+
+C – Context: We are launching a B2B SaaS for project management
+O – Objective: Write a landing page that converts visitors into sign-ups
+S – Style: Conversational, startup-like
+T – Tone: Confident, not salesy
+A – Audience: CTOs and technical leads
+R – Response Format: Hero + 3 benefit sections + CTA, under 300 words
+
+─────────────────────────────────────────────────────────────────────────
+
+What do you want to do?
+
+  [1]  Run with claude (Anthropic Claude)
+  [2]  Run with gemini (Google Gemini)
+  [3]  Copy to clipboard
+  [4]  Print to stdout (pipe-friendly)
+  [5]  Save to file
+  [6]  Exit without action
+
+→ 1
+```
+
+---
+
+## Also available as a Chrome Extension
+
+Use the same frameworks directly from any text field in your browser — ChatGPT, Gemini, Notion, Gmail, and more.
+
+[AI Prompt Framework Helper on Chrome Web Store](https://github.com/marcoscv-work/AI-Prompt-Framework-Helper)
+
+---
+
+## Author
+
+**Marcos Castro** · [marcoscv.github.io](https://marcoscv.github.io) · [marcoscv@gmail.com](mailto:marcoscv@gmail.com)
+
+MIT License

package/ai-prompt.js

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+'use strict';
+
+// ─── AI Prompt Framework Helper — CLI ────────────────────────────────────────
+// Author : Marcos Castro · https://marcoscv.github.io
+// No external dependencies — requires only Node.js ≥ 16
+// Usage  : node ai-prompt.js
+//          ai-prompt              (if installed globally)
+//          ai-prompt | claude     (pipe output to any CLI)
+
+const readline = require('readline');
+const { execSync, spawnSync } = require('child_process');
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+
+// ─── ANSI ─────────────────────────────────────────────────────────────────────
+
+const A = {
+  reset:   '\x1b[0m',
+  bold:    '\x1b[1m',
+  dim:     '\x1b[2m',
+  green:   '\x1b[32m',
+  blue:    '\x1b[34m',
+  yellow:  '\x1b[33m',
+  magenta: '\x1b[35m',
+  cyan:    '\x1b[36m',
+  red:     '\x1b[31m',
+  gray:    '\x1b[90m',
+  white:   '\x1b[97m',
+};
+
+const b  = (s) => `${A.bold}${s}${A.reset}`;
+const d  = (s) => `${A.dim}${s}${A.reset}`;
+const co = (color, s) => `${A[color]}${s}${A.reset}`;
+
+// ─── Frameworks ───────────────────────────────────────────────────────────────
+
+const FRAMEWORKS = [
+  {
+    key: 'APE',
+    color: 'green',
+    fullName: 'Action · Purpose · Expectation',
+    tip: 'Fastest. Ideal for focused, well-defined tasks.',
+    fields: [
+      { id: 'action',      letter: 'A', label: 'Action',      hint: 'What should the AI do?',                       required: true },
+      { id: 'purpose',     letter: 'P', label: 'Purpose',     hint: 'Why? What problem does it solve?',             required: true },
+      { id: 'expectation', letter: 'E', label: 'Expectation', hint: 'What does a great output look like?',          required: true },
+    ],
+    build: (f) => [
+      `A – Action: ${f.action}`,
+      `P – Purpose: ${f.purpose}`,
+      `E – Expectation: ${f.expectation}`,
+    ].join('\n\n'),
+  },
+  {
+    key: 'CO-STAR',
+    color: 'blue',
+    fullName: 'Context · Objective · Style · Tone · Audience · Response',
+    tip: 'Best for copy, emails, content, presentations.',
+    fields: [
+      { id: 'context',   letter: 'C', label: 'Context',         hint: "What's the background or situation?",        required: true },
+      { id: 'objective', letter: 'O', label: 'Objective',       hint: 'What outcome do you want to achieve?',       required: true },
+      { id: 'style',     letter: 'S', label: 'Style',           hint: 'Writing style (e.g. conversational, formal)',required: false },
+      { id: 'tone',      letter: 'T', label: 'Tone',            hint: 'Emotional tone (e.g. confident, friendly)',  required: false },
+      { id: 'audience',  letter: 'A', label: 'Audience',        hint: 'Who will read or receive this?',             required: false },
+      { id: 'response',  letter: 'R', label: 'Response Format', hint: 'How should the output be structured?',       required: true },
+    ],
+    build: (f) => [
+      ['C – Context', f.context],
+      ['O – Objective', f.objective],
+      ['S – Style', f.style],
+      ['T – Tone', f.tone],
+      ['A – Audience', f.audience],
+      ['R – Response Format', f.response],
+    ].filter(([, v]) => v).map(([k, v]) => `${k}: ${v}`).join('\n\n'),
+  },
+  {
+    key: 'RISEN',
+    color: 'yellow',
+    fullName: 'Role · Instructions · Steps · End Goal · Narrowing',
+    tip: 'Best for workflows, plans, technical execution.',
+    fields: [
+      { id: 'role',         letter: 'R', label: 'Role',         hint: 'What role should the AI embody?',            required: true },
+      { id: 'instructions', letter: 'I', label: 'Instructions', hint: 'Specific instructions for the task',         required: true },
+      { id: 'steps',        letter: 'S', label: 'Steps',        hint: 'Sequential steps to follow (optional)',      required: false },
+      { id: 'endgoal',      letter: 'E', label: 'End Goal',     hint: 'What does a successful output look like?',   required: true },
+      { id: 'narrowing',    letter: 'N', label: 'Narrowing',    hint: 'What to exclude, avoid, or keep in scope',   required: false },
+    ],
+    build: (f) => [
+      ['R – Role', f.role],
+      ['I – Instructions', f.instructions],
+      ['S – Steps', f.steps],
+      ['E – End Goal', f.endgoal],
+      ['N – Narrowing', f.narrowing],
+    ].filter(([, v]) => v).map(([k, v]) => `${k}: ${v}`).join('\n\n'),
+  },
+  {
+    key: 'RTCCF',
+    color: 'magenta',
+    fullName: 'Role · Task · Context · Constraints · Format',
+    tip: 'Full project kickstart with maximum structure.',
+    fields: [
+      { id: 'role',        letter: 'R', label: 'Role',        hint: 'What role should the AI assume?',              required: true },
+      { id: 'task',        letter: 'T', label: 'Task',        hint: 'What specific task should it perform?',        required: true },
+      { id: 'context',     letter: 'C', label: 'Context',     hint: 'What does it need to know to do it well?',     required: true },
+      { id: 'constraints', letter: 'C', label: 'Constraints', hint: "What can't it do? What limits exist?",         required: false },
+      { id: 'format',      letter: 'F', label: 'Format',      hint: 'How do you want the response delivered?',      required: false },
+    ],
+    build: (f) => [
+      ['R – Role', f.role],
+      ['T – Task', f.task],
+      ['C – Context', f.context],
+      ['C – Constraints', f.constraints],
+      ['F – Format', f.format],
+    ].filter(([, v]) => v).map(([k, v]) => `${k}: ${v}`).join('\n\n'),
+  },
+];
+
+// ─── Detect installed AI CLIs ─────────────────────────────────────────────────
+
+const CLI_CATALOG = [
+  { name: 'claude',  label: 'Anthropic Claude',       args: (p) => [p] },
+  { name: 'gemini',  label: 'Google Gemini',          args: (p) => [p] },
+  { name: 'llm',     label: 'llm (Simon Willison)',   args: (p) => [p] },
+  { name: 'aichat',  label: 'aichat (multi-model)',   args: (p) => [p] },
+  { name: 'gpt',     label: 'gpt-cli',                args: (p) => [p] },
+  { name: 'sgpt',    label: 'ShellGPT',               args: (p) => [p] },
+];
+
+function detectCLIs() {
+  return CLI_CATALOG.filter(({ name }) => {
+    try { execSync(`which ${name} 2>/dev/null`, { stdio: 'pipe' }); return true; }
+    catch { return false; }
+  });
+}
+
+// ─── Terminal helpers ─────────────────────────────────────────────────────────
+
+const W = Math.min(process.stdout.columns || 72, 80);
+
+function line(ch = '─') { return co('gray', ch.repeat(W)); }
+
+function box(lines, color = 'cyan') {
+  const inner = W - 4;
+  const top    = co(color, '┌' + '─'.repeat(W - 2) + '┐');
+  const bot    = co(color, '└' + '─'.repeat(W - 2) + '┘');
+  const rows   = lines.map(l => co(color, '│') + ' ' + l.padEnd(inner) + ' ' + co(color, '│'));
+  return [top, ...rows, bot].join('\n');
+}
+
+function header() {
+  const title  = '⬡  AI Prompt Framework Helper  ·  CLI';
+  const sub    = 'by Marcos Castro · marcoscv.github.io';
+  const inner  = W - 4;
+  console.log('\n' + box([
+    b(title).padEnd(inner + 9),   // +9 for bold codes
+    d(sub),
+  ], 'cyan'));
+}
+
+function sectionHeader(fw) {
+  console.log('\n' + line());
+  console.log(` ${b(co(fw.color, fw.key))}  ${d(fw.fullName)}`);
+  console.log(` ${d('↳ ' + fw.tip)}`);
+  console.log(line() + '\n');
+}
+
+function showPreview(prompt) {
+  console.log('\n' + line());
+  console.log(b(' Generated Prompt'));
+  console.log(line() + '\n');
+  // indent each line
+  prompt.split('\n').forEach(l => {
+    if (l.startsWith('  ')) {
+      console.log(co('gray', '  ' + l.trimStart()));
+    } else if (l.match(/^[A-Z] [–—]/)) {
+      const [key, ...rest] = l.split(': ');
+      console.log(b(co('cyan', key)) + ': ' + rest.join(': '));
+    } else {
+      console.log(l);
+    }
+  });
+  console.log('\n' + line());
+}
+
+// ─── readline ─────────────────────────────────────────────────────────────────
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+  terminal: true,
+});
+
+function ask(question, defaultVal = '') {
+  const def = defaultVal ? d(` [${defaultVal}]`) : '';
+  return new Promise(resolve => {
+    rl.question(`  ${question}${def}\n  ${co('cyan', '→')} `, (ans) => {
+      resolve(ans.trim() || defaultVal);
+    });
+  });
+}
+
+function askNum(prompt, min, max) {
+  return new Promise(resolve => {
+    const ask = () => {
+      rl.question(`\n  ${prompt}\n  ${co('cyan', '→')} `, (ans) => {
+        const n = parseInt(ans.trim(), 10);
+        if (!isNaN(n) && n >= min && n <= max) resolve(n);
+        else {
+          console.log(co('red', `  Please enter a number between ${min} and ${max}.`));
+          ask();
+        }
+      });
+    };
+    ask();
+  });
+}
+
+// ─── Steps ────────────────────────────────────────────────────────────────────
+
+async function selectFramework() {
+  console.log('\n' + b('  Select a framework:\n'));
+  FRAMEWORKS.forEach((fw, i) => {
+    console.log(
+      `  ${b(co(fw.color, `[${i + 1}]`))}  ${b(fw.key.padEnd(8))}  ${d(fw.fullName)}`
+    );
+    console.log(`        ${d('↳ ' + fw.tip)}\n`);
+  });
+
+  const n = await askNum(`Choose [1–${FRAMEWORKS.length}]:`, 1, FRAMEWORKS.length);
+  return FRAMEWORKS[n - 1];
+}
+
+async function fillFields(fw) {
+  sectionHeader(fw);
+  const values = {};
+
+  for (const field of fw.fields) {
+    const badge    = co(fw.color, `[${field.letter}]`);
+    const label    = b(field.label.toUpperCase());
+    const required = field.required ? co('red', '(required)') : d('(optional — press Enter to skip)');
+
+    console.log(`  ${badge} ${label}  ${required}`);
+    console.log(`  ${d(field.hint)}\n`);
+
+    let value = '';
+    while (true) {
+      value = await ask('');
+      if (value || !field.required) break;
+      console.log(co('red', `  This field is required.\n`));
+    }
+    values[field.id] = value;
+    console.log();
+  }
+
+  return values;
+}
+
+async function selectAction(prompt, detectedCLIs) {
+  const options = [];
+
+  // AI CLIs first
+  detectedCLIs.forEach(cli => {
+    options.push({
+      label: `Run with ${b(co('green', cli.name))} ${d('(' + cli.label + ')')}`,
+      action: () => runWithCLI(cli, prompt),
+    });
+  });
+
+  // Always-present options
+  options.push({ label: `${b('Copy')} to clipboard`,          action: () => copyToClipboard(prompt) });
+  options.push({ label: `${b('Print')} to stdout ${d('(pipe-friendly)')}`, action: () => printStdout(prompt) });
+  options.push({ label: `${b('Save')} to file`,               action: () => saveToFile(prompt) });
+  options.push({ label: `${d('Exit without action')}`,        action: () => {} });
+
+  console.log('\n' + b('  What do you want to do?\n'));
+  options.forEach((opt, i) => {
+    console.log(`  ${co('cyan', `[${i + 1}]`)}  ${opt.label}`);
+  });
+
+  const n = await askNum(`Choose [1–${options.length}]:`, 1, options.length);
+  console.log();
+  await options[n - 1].action();
+}
+
+// ─── Actions ──────────────────────────────────────────────────────────────────
+
+function runWithCLI(cli, prompt) {
+  console.log(co('green', `  Running: ${cli.name} …\n`));
+  rl.close();
+
+  const result = spawnSync(cli.name, cli.args(prompt), {
+    stdio: 'inherit',
+    shell: false,
+  });
+
+  if (result.error) {
+    console.error(co('red', `  Error running ${cli.name}: ${result.error.message}`));
+    process.exit(1);
+  }
+  process.exit(result.status ?? 0);
+}
+
+function copyToClipboard(prompt) {
+  const platform = os.platform();
+  try {
+    if (platform === 'darwin') {
+      execSync('pbcopy', { input: prompt });
+      console.log(co('green', '  ✓ Copied to clipboard.'));
+    } else if (platform === 'linux') {
+      // Try xclip, then xsel
+      try {
+        execSync('xclip -selection clipboard', { input: prompt });
+      } catch {
+        execSync('xsel --clipboard --input', { input: prompt });
+      }
+      console.log(co('green', '  ✓ Copied to clipboard.'));
+    } else if (platform === 'win32') {
+      execSync('clip', { input: prompt, shell: true });
+      console.log(co('green', '  ✓ Copied to clipboard.'));
+    }
+  } catch {
+    console.log(co('yellow', '  Could not copy automatically. Here is the prompt:\n'));
+    printStdout(prompt);
+  }
+}
+
+function printStdout(prompt) {
+  // If stdout is a TTY we show it styled; if piped we print clean
+  if (process.stdout.isTTY) {
+    showPreview(prompt);
+  } else {
+    process.stdout.write(prompt + '\n');
+  }
+}
+
+async function saveToFile(prompt) {
+  const defaultPath = path.join(os.homedir(), 'ai-prompt.txt');
+  const dest = await ask(`Save to path:`, defaultPath);
+  try {
+    fs.writeFileSync(dest, prompt, 'utf8');
+    console.log(co('green', `  ✓ Saved to ${dest}`));
+  } catch (e) {
+    console.log(co('red', `  Error saving: ${e.message}`));
+  }
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  // Detect before entering interactive mode
+  const detectedCLIs = detectCLIs();
+
+  console.clear();
+  header();
+
+  if (detectedCLIs.length > 0) {
+    const names = detectedCLIs.map(c => co(c.color || 'green', c.name)).join(', ');
+    console.log(`\n  ${co('green', '✓')} Detected AI CLIs: ${detectedCLIs.map(c => b(c.name)).join('  ')}`);
+  } else {
+    console.log(`\n  ${d('No AI CLIs detected. Output options: clipboard, stdout, file.')}`);
+  }
+
+  const fw     = await selectFramework();
+  const values = await fillFields(fw);
+  const prompt = fw.build(values);
+
+  showPreview(prompt);
+
+  await selectAction(prompt, detectedCLIs);
+
+  rl.close();
+}
+
+main().catch((err) => {
+  console.error(co('red', '\n  Error: ' + err.message));
+  rl.close();
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "ai-prompt-framework-helper",
+  "version": "1.0.0",
+  "description": "Interactive CLI to build structured AI prompts using APE, CO-STAR, RISEN and RTCCF frameworks. Works with Claude, Gemini, and any AI CLI.",
+  "author": "Marcos Castro <marcoscv@gmail.com> (https://marcoscv.github.io)",
+  "license": "MIT",
+  "homepage": "https://github.com/marcoscv-work/AI-Prompt-Framework-Helper#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marcoscv-work/AI-Prompt-Framework-Helper.git"
+  },
+  "bugs": {
+    "url": "https://github.com/marcoscv-work/AI-Prompt-Framework-Helper/issues",
+    "email": "marcoscv@gmail.com"
+  },
+  "bin": {
+    "ai-prompt": "./ai-prompt.js"
+  },
+  "files": [
+    "ai-prompt.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": [
+    "ai", "prompt", "prompt-engineering", "cli", "terminal",
+    "ape", "costar", "co-star", "risen", "rtccf",
+    "claude", "gemini", "chatgpt", "llm", "openai",
+    "framework", "interactive", "assistant"
+  ]
+}