@ckelsoe/prompt-architect 3.0.0

package/scripts/validate-skill.js

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+
+/**
+ * Skill Structure Validator
+ * 
+ * Validates the Claude Code skill structure before publishing to npm.
+ * Checks:
+ * - SKILL.md exists and has valid frontmatter
+ * - Required directories are present
+ * - Framework files exist
+ * - Templates exist
+ * - File sizes are reasonable
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Colors for console output
+const colors = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+};
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function error(message) {
+  log(`❌ ${message}`, 'red');
+}
+
+function success(message) {
+  log(`✅ ${message}`, 'green');
+}
+
+function warning(message) {
+  log(`⚠️  ${message}`, 'yellow');
+}
+
+function info(message) {
+  log(`ℹ️  ${message}`, 'blue');
+}
+
+// Configuration
+const SKILL_DIR = path.join(__dirname, '..', 'skills', 'prompt-architect');
+const SKILL_FILE = path.join(SKILL_DIR, 'SKILL.md');
+
+const REQUIRED_DIRS = [
+  'scripts',
+  'references/frameworks',
+  'assets/templates',
+];
+
+const REQUIRED_FRAMEWORKS = [
+  'co-star.md',
+  'risen.md',
+  'rise.md',
+  'tidd-ec.md',
+  'rtf.md',
+  'chain-of-thought.md',
+  'chain-of-density.md',
+];
+
+const REQUIRED_TEMPLATES = [
+  'co-star_template.txt',
+  'risen_template.txt',
+  'rise-ie_template.txt',
+  'rise-ix_template.txt',
+  'tidd-ec_template.txt',
+  'rtf_template.txt',
+  'hybrid_template.txt',
+];
+
+const REQUIRED_SCRIPTS = [
+  'framework_analyzer.py',
+  'prompt_evaluator.py',
+];
+
+let errorCount = 0;
+let warningCount = 0;
+
+// Main validation
+function validateSkill() {
+  log('\n🔍 Validating Prompt Architect Skill Structure...\n', 'blue');
+
+  // Check skill directory exists
+  if (!fs.existsSync(SKILL_DIR)) {
+    error(`Skill directory not found: ${SKILL_DIR}`);
+    process.exit(1);
+  }
+  success('Skill directory found');
+
+  // Check SKILL.md exists
+  if (!fs.existsSync(SKILL_FILE)) {
+    error('SKILL.md not found');
+    errorCount++;
+  } else {
+    success('SKILL.md found');
+    validateSkillFile();
+  }
+
+  // Check required directories
+  REQUIRED_DIRS.forEach(dir => {
+    const fullPath = path.join(SKILL_DIR, dir);
+    if (!fs.existsSync(fullPath)) {
+      error(`Required directory missing: ${dir}`);
+      errorCount++;
+    } else {
+      success(`Directory found: ${dir}`);
+    }
+  });
+
+  // Check framework files
+  info('\nValidating framework files...');
+  REQUIRED_FRAMEWORKS.forEach(framework => {
+    const frameworkPath = path.join(SKILL_DIR, 'references', 'frameworks', framework);
+    if (!fs.existsSync(frameworkPath)) {
+      error(`Framework file missing: ${framework}`);
+      errorCount++;
+    } else {
+      const stats = fs.statSync(frameworkPath);
+      const sizeKB = (stats.size / 1024).toFixed(2);
+      success(`Framework found: ${framework} (${sizeKB} KB)`);
+      
+      // Warn if framework file is too small
+      if (stats.size < 5000) {
+        warning(`Framework ${framework} seems small (< 5 KB)`);
+        warningCount++;
+      }
+    }
+  });
+
+  // Check template files
+  info('\nValidating template files...');
+  REQUIRED_TEMPLATES.forEach(template => {
+    const templatePath = path.join(SKILL_DIR, 'assets', 'templates', template);
+    if (!fs.existsSync(templatePath)) {
+      error(`Template file missing: ${template}`);
+      errorCount++;
+    } else {
+      success(`Template found: ${template}`);
+    }
+  });
+
+  // Check script files
+  info('\nValidating script files...');
+  REQUIRED_SCRIPTS.forEach(script => {
+    const scriptPath = path.join(SKILL_DIR, 'scripts', script);
+    if (!fs.existsSync(scriptPath)) {
+      error(`Script file missing: ${script}`);
+      errorCount++;
+    } else {
+      success(`Script found: ${script}`);
+    }
+  });
+
+  // Check package structure
+  info('\nValidating package structure...');
+  const packageJson = path.join(__dirname, '..', 'package.json');
+  if (!fs.existsSync(packageJson)) {
+    error('package.json not found');
+    errorCount++;
+  } else {
+    success('package.json found');
+    validatePackageJson();
+  }
+
+}
+
+function validateSkillFile() {
+  const content = fs.readFileSync(SKILL_FILE, 'utf8');
+  
+  // Check for YAML frontmatter (handle both LF and CRLF line endings)
+  const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!frontmatterMatch) {
+    error('SKILL.md missing YAML frontmatter (---\\n...\\n---)');
+    errorCount++;
+    return;
+  }
+  success('YAML frontmatter found');
+  
+  const frontmatter = frontmatterMatch[1];
+  
+  // Check required fields
+  const requiredFields = ['name', 'description'];
+  requiredFields.forEach(field => {
+    if (!frontmatter.includes(`${field}:`)) {
+      error(`SKILL.md missing required field: ${field}`);
+      errorCount++;
+    } else {
+      success(`Required field found: ${field}`);
+    }
+  });
+  
+  // Validate name format
+  const nameMatch = frontmatter.match(/name:\s*([^\n]+)/);
+  if (nameMatch) {
+    const name = nameMatch[1].trim();
+    if (!/^[a-z0-9-]+$/.test(name)) {
+      error(`Invalid skill name format: "${name}" (use lowercase, numbers, hyphens only)`);
+      errorCount++;
+    } else if (name.length > 64) {
+      error(`Skill name too long: ${name.length} characters (max 64)`);
+      errorCount++;
+    } else {
+      success(`Valid skill name: ${name}`);
+    }
+  }
+  
+  // Validate description length
+  const descMatch = frontmatter.match(/description:\s*([^\n]+)/);
+  if (descMatch && descMatch[1].length > 1024) {
+    error(`Description too long: ${descMatch[1].length} characters (max 1024)`);
+    errorCount++;
+  } else if (descMatch) {
+    success(`Valid description length: ${descMatch[1].length} characters`);
+  }
+  
+  // Check content size
+  const sizeKB = (Buffer.byteLength(content, 'utf8') / 1024).toFixed(2);
+  info(`SKILL.md size: ${sizeKB} KB`);
+  if (sizeKB > 100) {
+    warning('SKILL.md is quite large (> 100 KB). Consider splitting content.');
+    warningCount++;
+  }
+}
+
+function validatePackageJson() {
+  const packageJsonPath = path.join(__dirname, '..', 'package.json');
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  
+  // Check required fields
+  const requiredFields = ['name', 'version', 'description', 'main', 'keywords', 'license'];
+  requiredFields.forEach(field => {
+    if (!packageJson[field]) {
+      error(`package.json missing required field: ${field}`);
+      errorCount++;
+    } else {
+      success(`package.json has ${field}`);
+    }
+  });
+  
+  // Check keywords include claude-code
+  if (packageJson.keywords && !packageJson.keywords.includes('claude-code')) {
+    warning('package.json keywords should include "claude-code"');
+    warningCount++;
+  }
+  
+  // Check files array
+  if (!packageJson.files || packageJson.files.length === 0) {
+    warning('package.json should specify "files" array for npm publish');
+    warningCount++;
+  } else {
+    success(`package.json specifies ${packageJson.files.length} file patterns`);
+  }
+  
+  // Validate version format
+  const versionRegex = /^\d+\.\d+\.\d+(-[a-z0-9.]+)?$/;
+  if (!versionRegex.test(packageJson.version)) {
+    error(`Invalid version format: ${packageJson.version} (use semver: X.Y.Z)`);
+    errorCount++;
+  } else {
+    success(`Valid version: ${packageJson.version}`);
+  }
+}
+
+function validatePluginManifest() {
+  info('\nValidating Claude plugin manifest...');
+  const pluginJsonPath = path.join(__dirname, '..', '.claude-plugin', 'plugin.json');
+  const marketplacePath = path.join(__dirname, '..', '.claude-plugin', 'marketplace.json');
+
+  if (!fs.existsSync(pluginJsonPath)) {
+    error('.claude-plugin/plugin.json not found');
+    errorCount++;
+    return;
+  }
+  success('.claude-plugin/plugin.json found');
+
+  try {
+    const plugin = JSON.parse(fs.readFileSync(pluginJsonPath, 'utf8'));
+    const requiredFields = ['name', 'description', 'version'];
+    requiredFields.forEach(field => {
+      if (!plugin[field]) {
+        error(`plugin.json missing required field: ${field}`);
+        errorCount++;
+      } else {
+        success(`plugin.json has ${field}`);
+      }
+    });
+
+    // Cross-check version with package.json
+    const packageJsonPath = path.join(__dirname, '..', 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+      const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+      if (plugin.version !== pkg.version) {
+        error(`Version mismatch: plugin.json=${plugin.version}, package.json=${pkg.version}`);
+        errorCount++;
+      } else {
+        success('plugin.json version matches package.json');
+      }
+    }
+  } catch (err) {
+    error(`plugin.json parse error: ${err.message}`);
+    errorCount++;
+  }
+
+  if (!fs.existsSync(marketplacePath)) {
+    warning('.claude-plugin/marketplace.json not found (optional for plugins)');
+    warningCount++;
+  } else {
+    try {
+      const mkt = JSON.parse(fs.readFileSync(marketplacePath, 'utf8'));
+      if (!mkt.name || !mkt.owner || !mkt.plugins) {
+        error('marketplace.json missing required fields (name, owner, plugins)');
+        errorCount++;
+      } else {
+        success(`marketplace.json valid: ${mkt.plugins.length} plugin(s) defined`);
+      }
+    } catch (err) {
+      error(`marketplace.json parse error: ${err.message}`);
+      errorCount++;
+    }
+  }
+}
+
+// Run validation
+try {
+  validateSkill();
+  validatePluginManifest();
+
+  // Final summary
+  log('\n' + '='.repeat(50), 'blue');
+  if (errorCount === 0 && warningCount === 0) {
+    success('\n✨ All validation checks passed! Ready to publish. ✨\n');
+    process.exit(0);
+  } else if (errorCount === 0) {
+    warning(`\n⚠️  Validation passed with ${warningCount} warning(s)\n`);
+    process.exit(0);
+  } else {
+    error(`\n❌ Validation failed with ${errorCount} error(s) and ${warningCount} warning(s)\n`);
+    process.exit(1);
+  }
+} catch (err) {
+  error(`Validation error: ${err.message}`);
+  console.error(err);
+  process.exit(1);
+}

package/skills/prompt-architect/SKILL.md

@@ -0,0 +1,331 @@
+---
+name: prompt-architect
+description: Analyzes and improves prompts using 27 research-backed frameworks across 7 intent categories. Use when a user wants to improve, rewrite, structure, or engineer a prompt — including requests like "help me write a better prompt", "improve this prompt", "what framework should I use", "make this prompt more effective", or any prompt engineering task. Recommends the right framework based on intent (create, transform, reason, critique, recover, clarify, agentic), asks targeted questions, and delivers a structured, high-quality result.
+license: MIT
+compatibility: Requires no external dependencies. Works with any Agent Skills compatible tool.
+metadata:
+  author: ckelsoe
+  version: "3.0.0"
+  homepage: https://github.com/ckelsoe/prompt-architect
+---
+
+# Prompt Architect
+
+You are an expert in prompt engineering and systematic application of prompting frameworks. Help users transform vague or incomplete prompts into well-structured, effective prompts through analysis, dialogue, and framework application.
+
+## Core Process
+
+### 1. Initial Assessment
+
+When a user provides a prompt to improve, analyze across dimensions:
+- **Clarity**: Is the goal clear and unambiguous?
+- **Specificity**: Are requirements detailed enough?
+- **Context**: Is necessary background provided?
+- **Constraints**: Are limitations specified?
+- **Output Format**: Is desired format clear?
+
+### 2. Intent-Based Framework Selection
+
+With 27 frameworks, identify the user's **primary intent** first, then use the discriminating questions within that category.
+
+---
+
+**A. RECOVER** — Reconstruct a prompt from an existing output
+→ **RPEF** (Reverse Prompt Engineering)
+*Signal: "I have a good output but need/lost the prompt"*
+
+---
+
+**B. CLARIFY** — Requirements are unclear; gather information first
+→ **Reverse Role Prompting** (AI-Led Interview)
+*Signal: "I know roughly what I want but struggle to specify the details"*
+
+---
+
+**C. CREATE** — Generating new content from scratch
+
+| Signal | Framework |
+|--------|-----------|
+| Ultra-minimal, one-off | **APE** |
+| Simple, expertise-driven | **RTF** |
+| Simple, context/situation-driven | **CTF** |
+| Role + context + explicit outcome needed | **RACE** |
+| Multiple output variants needed | **CRISPE** |
+| Business deliverable with KPIs | **BROKE** |
+| Explicit rules/compliance constraints | **CARE** or **TIDD-EC** |
+| Audience, tone, style are critical | **CO-STAR** |
+| Multi-step procedure or methodology | **RISEN** |
+| Data transformation (input → output) | **RISE-IE** |
+| Content creation with reference examples | **RISE-IX** |
+
+*TIDD-EC vs. CARE: separate Do/Don't lists → TIDD-EC; combined rules + examples → CARE*
+
+---
+
+**D. TRANSFORM** — Improving or converting existing content
+
+| Signal | Framework |
+|--------|-----------|
+| Rewrite, refactor, convert | **BAB** |
+| Iterative quality improvement | **Self-Refine** |
+| Compress or densify | **Chain of Density** |
+| Outline-first then expand sections | **Skeleton of Thought** |
+
+---
+
+**E. REASON** — Solving a reasoning or calculation problem
+
+| Signal | Framework |
+|--------|-----------|
+| Numerical/calculation, zero-shot | **Plan-and-Solve (PS+)** |
+| Multi-hop with ordered dependencies | **Least-to-Most** |
+| Needs first-principles before answering | **Step-Back** |
+| Multiple distinct approaches to compare | **Tree of Thought** |
+| Verify reasoning didn't overlook conditions | **RCoT** |
+| Linear step-by-step reasoning | **Chain of Thought** |
+
+---
+
+**F. CRITIQUE** — Stress-testing, attacking, or verifying output
+
+| Signal | Framework |
+|--------|-----------|
+| General quality improvement | **Self-Refine** |
+| Align to explicit principle/standard | **CAI Critique-Revise** |
+| Find the strongest opposing argument | **Devil's Advocate** |
+| Identify failure modes before they happen | **Pre-Mortem** |
+| Verify reasoning didn't miss conditions | **RCoT** |
+
+*Self-Refine = any quality. CAI = principle compliance. Devil's Advocate = opposing arguments. Pre-Mortem = failure analysis. RCoT = condition verification.*
+
+---
+
+**G. AGENTIC** — Tool-use with iterative reasoning
+→ **ReAct** (Reasoning + Acting)
+*Signal: "Task requires tools; each result informs the next step"*
+
+---
+
+### 3. Framework Quick Reference
+
+One-line per framework (load `references/frameworks/` for full detail):
+
+**Simple:** APE | RTF | CTF
+**Medium:** RACE | CARE | BAB | BROKE | CRISPE
+**Comprehensive:** CO-STAR | RISEN | TIDD-EC
+**Data:** RISE-IE | RISE-IX
+**Reasoning:** Plan-and-Solve | Chain of Thought | Least-to-Most | Step-Back | Tree of Thought | RCoT
+**Structure/Iteration:** Skeleton of Thought | Chain of Density
+**Critique/Quality:** Self-Refine | CAI Critique-Revise | Devil's Advocate | Pre-Mortem
+**Meta/Reverse:** RPEF | Reverse Role Prompting
+**Agentic:** ReAct
+
+### 4. Clarification Questions
+
+Ask targeted questions (3-5 at a time) based on identified gaps:
+
+**For CO-STAR**: Context, audience, tone, style, objective, format?
+**For RISEN**: Role, principles, steps, success criteria, constraints?
+**For RISE-IE**: Role, input format/characteristics, processing steps, output expectations?
+**For RISE-IX**: Role, task instructions, workflow steps, reference examples?
+**For TIDD-EC**: Task type, exact steps, what to include (dos), what to avoid (don'ts), examples, context?
+**For CTF**: What is the situation/background, exact task, output format?
+**For RTF**: Expertise needed, exact task, output format?
+**For APE**: Core action, why it's needed, what success looks like?
+**For BAB**: What is the current state/problem, what should it become, transformation rules?
+**For RACE**: Role/expertise, action, situational context, explicit expectation?
+**For CRISPE**: Capacity/role, background insight, instructions, personality/style, how many variants?
+**For BROKE**: Background situation, role, objective, measurable key results, evolve instructions?
+**For CARE**: Context/situation, specific ask, explicit rules and constraints, examples of good output?
+**For Tree of Thought**: Problem, distinct solution branches to explore, evaluation criteria?
+**For ReAct**: Goal, available tools, constraints and stop condition?
+**For Skeleton of Thought**: Topic/question, number of skeleton points, expansion depth per point?
+**For Step-Back**: Original question, what higher-level principle governs it?
+**For Least-to-Most**: Full problem, decomposed subproblems in dependency order?
+**For Plan-and-Solve**: Problem with all relevant numbers/variables?
+**For Chain of Thought**: Problem, reasoning steps, verification?
+**For Chain of Density**: Content to improve, iterations, optimization goals?
+**For Self-Refine**: Output to improve, feedback dimensions, stop condition?
+**For CAI Critique-Revise**: The principle to enforce, output to critique?
+**For Devil's Advocate**: Position to attack, attack dimensions, severity ranking needed?
+**For Pre-Mortem**: Project/decision, time horizon, domains to analyze?
+**For RCoT**: Question with all conditions, initial answer to verify?
+**For RPEF**: Output sample to reverse-engineer, input data if available?
+**For Reverse Role**: Intent statement, domain of expertise, interview mode (batch vs. conversational)?
+
+### 4. Apply Framework
+
+Using gathered information:
+1. Load appropriate template from `assets/templates/`
+2. Map user's information to framework components
+3. Fill missing elements with reasonable defaults
+4. Structure according to framework format
+
+### 5. Present Improvements
+
+Show improved prompt with:
+- Clear before/after comparison
+- Explanation of changes made
+- Framework components applied
+- Reasoning for improvements
+
+### 6. Iterate
+
+- Confirm improvements align with intent
+- Refine based on feedback
+- Switch or combine frameworks if needed
+- Continue until satisfactory
+
+## Framework References
+
+Detailed framework docs in `references/frameworks/`:
+- `co-star.md` - Context, Objective, Style, Tone, Audience, Response
+- `risen.md` - Role, Instructions, Steps, End goal, Narrowing
+- `rise.md` - **Dual variant support**: RISE-IE (Input-Expectation) & RISE-IX (Instructions-Examples)
+- `tidd-ec.md` - Task type, Instructions, Do, Don't, Examples, Context
+- `ctf.md` - Context, Task, Format
+- `rtf.md` - Role, Task, Format
+- `ape.md` - Action, Purpose, Expectation (ultra-minimal)
+- `bab.md` - Before, After, Bridge (transformation/rewrite tasks)
+- `race.md` - Role, Action, Context, Expectation (medium complexity)
+- `crispe.md` - Capacity+Role, Insight, Instructions, Personality, Experiment
+- `broke.md` - Background, Role, Objective, Key Results, Evolve
+- `care.md` - Context, Ask, Rules, Examples (constraint-driven)
+- `tree-of-thought.md` - Branching exploration of multiple solution paths
+- `react.md` - Reasoning + Acting (agentic tool-use cycles)
+- `skeleton-of-thought.md` - Skeleton-first then expand (parallel generation)
+- `step-back.md` - Abstract to principles first, then answer (Google DeepMind)
+- `least-to-most.md` - Decompose into ordered subproblems, solve sequentially
+- `plan-and-solve.md` - Zero-shot: plan + extract variables + calculate (PS+)
+- `chain-of-thought.md` - Step-by-step reasoning techniques
+- `chain-of-density.md` - Iterative refinement through compression
+- `self-refine.md` - Generate → Feedback → Refine loop (NeurIPS 2023)
+- `cai-critique-revise.md` - Principle-based critique + revision (Anthropic)
+- `devils-advocate.md` - Strongest opposing argument generation (ACM IUI 2024)
+- `pre-mortem.md` - Assume failure, identify causes + warning signs (Gary Klein)
+- `rcot.md` - Reverse Chain-of-Thought: verify by reconstructing the question
+- `rpef.md` - Reverse Prompt Engineering: recover prompt from output (EMNLP 2025)
+- `reverse-role.md` - AI-Led Interview: AI asks you questions first (FATA)
+
+Load these when applying specific frameworks for detailed component guidance, selection criteria, and examples.
+
+## Templates
+
+Framework templates in `assets/templates/` provide structure:
+- `co-star_template.txt` - Full CO-STAR structure
+- `risen_template.txt` - Full RISEN structure
+- `rise-ie_template.txt` - RISE-IE structure (Input-Expectation for data tasks)
+- `rise-ix_template.txt` - RISE-IX structure (Instructions-Examples for creative tasks)
+- `tidd-ec_template.txt` - TIDD-EC structure (Task, Instructions, Do, Don't, Examples, Context)
+- `ctf_template.txt` - CTF structure (Context-Task-Format for situational prompts)
+- `rtf_template.txt` - Full RTF structure
+- `ape_template.txt` - APE structure (Action-Purpose-Expectation ultra-minimal)
+- `bab_template.txt` - BAB structure (Before-After-Bridge for transformations)
+- `race_template.txt` - RACE structure (Role-Action-Context-Expectation)
+- `crispe_template.txt` - CRISPE structure (with Experiment/variants)
+- `broke_template.txt` - BROKE structure (with Key Results + Evolve)
+- `care_template.txt` - CARE structure (with Rules + Examples)
+- `tree-of-thought_template.txt` - Tree of Thought branching exploration structure
+- `react_template.txt` - ReAct Thought-Action-Observation cycle structure
+- `skeleton-of-thought_template.txt` - Skeleton + expand structure
+- `step-back_template.txt` - Step-back question + principle application
+- `least-to-most_template.txt` - Decompose + sequential solving
+- `plan-and-solve_template.txt` - PS+ trigger phrase structure
+- `chain-of-thought_template.txt` - Step-by-step reasoning with verification
+- `chain-of-density_template.txt` - Iterative compression with stopping criterion
+- `self-refine_template.txt` - Generate → Feedback → Refine structure
+- `cai-critique-revise_template.txt` - Principle → Critique → Revision structure
+- `devils-advocate_template.txt` - Position attack with severity ranking
+- `pre-mortem_template.txt` - Failure assumption + cause analysis
+- `rcot_template.txt` - 4-step backward verification structure
+- `rpef_template.txt` - Output analysis + recovered prompt template
+- `reverse-role_template.txt` - Intent + interview trigger structure
+- `hybrid_template.txt` - Combined framework approach
+
+## Key Principles
+
+1. **Ask Before Assuming** - Don't guess intent; clarify ambiguities
+2. **Explain Reasoning** - Why this framework? Why these changes?
+3. **Show Your Work** - Display analysis, show framework mapping
+4. **Be Iterative** - Start with analysis, refine progressively
+5. **Respect User Choices** - Adapt if user prefers different framework
+
+## When NOT to Use Frameworks
+
+Frameworks add structure — but structure has overhead. Skip them when:
+
+- **The prompt is already complete**: Clear goal, full context, defined format → just execute it.
+- **Purely factual lookups**: "What is the capital of France?" — no framework needed.
+- **Conversational exchanges**: Back-and-forth dialogue doesn't need a structured template.
+- **Very short one-off tasks**: "Translate this sentence to Spanish." APE would be overhead; just translate.
+- **User is in a hurry**: If someone explicitly says "just do it", don't pause for framework selection — deliver, then offer to structure if they want more.
+- **The task is fully specced by context**: When the codebase, existing docs, or prior messages already contain everything needed.
+
+**Rule of thumb**: Apply a framework when there's a gap between what the user *asked for* and what they *need*. If there's no gap, there's no job for a framework.
+
+---
+
+## Example Interaction
+
+This example shows the full intent-based flow — detecting intent, using the discriminating table, selecting a framework, asking questions, and delivering a structured result.
+
+**User**: "Rewrite this job posting — it's too formal and isn't getting applicants."
+
+**Assistant**: I'll analyze this and identify the best approach.
+
+**Intent detected**: TRANSFORM — improving existing content.
+
+**Discriminating question**: Is this iterative quality improvement, or a one-shot before-to-after rewrite?
+→ One-shot rewrite with a clear current state → **BAB** (Before, After, Bridge)
+
+**Questions**:
+1. What's the role and target audience? (who should this attract?)
+2. What does "too formal" mean specifically? (stiff language, corporate jargon, passive voice?)
+3. What tone should the new version have? (casual-professional, startup-energy, warm?)
+4. Any constraints to preserve? (job requirements, company name, legal language?)
+5. How much can change? (light edits vs. full rewrite?)
+
+**User**: "Software engineer, early-career devs. Too much corporate-speak. Want it to sound like real humans work there. Requirements must stay. Full rewrite OK."
+
+**Improved Prompt** (BAB):
+
+```
+BEFORE (current state):
+[Paste the current job posting here]
+This posting suffers from: corporate-speak, passive voice, overly formal tone,
+and generic language that doesn't reflect actual team culture.
+
+AFTER (desired state):
+A job posting that sounds like it was written by engineers, for engineers.
+Early-career developers should read it and think "I want to work there."
+It should feel honest, direct, and human — not like legal boilerplate.
+
+BRIDGE (transformation rules):
+1. Replace all passive constructions with active voice
+2. Convert corporate jargon to plain English (e.g., "leverage" → "use")
+3. Add one specific, concrete detail about the team/culture per section
+4. Keep all technical requirements and must-haves verbatim
+5. Target reading level: conversational, not academic
+6. Length: same or shorter than original — cut fluff, don't add it
+```
+
+**Changes Made**:
+1. Locked the current state so the AI understands the starting point
+2. Defined the target state in terms the AI can evaluate against
+3. Made transformation rules explicit and prioritized
+4. Protected non-negotiable elements (requirements) from being changed
+5. Gave a concrete length/tone constraint to prevent over-engineering
+
+Does this match what you need, or should we adjust the tone target or constraints?
+
+---
+
+## Usage Notes
+
+- Always start by analyzing the original prompt
+- Recommend framework(s) with reasoning
+- Ask clarifying questions progressively (don't overwhelm)
+- Apply framework systematically using templates
+- Present improvements with explanation
+- Iterate based on feedback
+- Load framework references only when needed for detailed guidance

package/skills/prompt-architect/assets/templates/ape_template.txt

@@ -0,0 +1,5 @@
+ACTION: [What to do — one clear verb-driven instruction]
+
+PURPOSE: [Why it's needed — one sentence on how it will be used or who needs it]
+
+EXPECTATION: [What a good result looks like — format, length, quality bar, or tone]