elliot-stack 1.0.16 → 1.0.18

package/README.md

@@ -52,6 +52,12 @@ npx elliot-stack@latest
 - [Claude Code](https://claude.ai/code) CLI installed
 - Node.js 18+
 
+## Contributing
+
+External contributions are welcome via pull request. Direct pushes to `main` are blocked — fork the repo, push your changes to a branch, and open a PR. Only the maintainer (Elliot) can merge to `main` and cut releases. This is intentional: `elliot-stack` is a security-sensitive npm package and the release tag can only be pushed by the maintainer.
+
+See [`docs/publishing.md`](docs/publishing.md) for the release flow and security model.
+
 ## License
 
 MIT

package/bin/install.cjs

@@ -15,6 +15,8 @@ const BACKUP_DIR = path.join(CLAUDE_DIR, '.estack-backup');
 const CHECKSUMS_FILE = path.join(CLAUDE_DIR, '.estack-checksums.json');
 const SETTINGS_FILE = path.join(CLAUDE_DIR, 'settings.json');
 const PACKAGE_SKILLS_DIR = path.join(__dirname, '..', 'skills');
+const HOOKS_DIR = path.join(CLAUDE_DIR, 'hooks');
+const PACKAGE_HOOKS_DIR = path.join(__dirname, '..', 'hooks');
 
 // ── Flags ──────────────────────────────────────────────────────────────────
 const SILENT = process.argv.includes('--silent');
@@ -39,6 +41,13 @@ function walkDir(dir, base) {
   return files;
 }
 
+function computeFileHash(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const hash = crypto.createHash('sha256');
+  hash.update(fs.readFileSync(filePath));
+  return hash.digest('hex');
+}
+
 function computeSkillHash(skillDir) {
   if (!fs.existsSync(skillDir)) return null;
   const hash = crypto.createHash('sha256');
@@ -66,6 +75,14 @@ function backupSkill(name) {
   copyDir(installedDir, path.join(BACKUP_DIR, name));
 }
 
+function backupHook(filename) {
+  const installedFile = path.join(HOOKS_DIR, filename);
+  if (!fs.existsSync(installedFile)) return;
+  const dest = path.join(BACKUP_DIR, 'hooks', filename);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(installedFile, dest);
+}
+
 function promptChar(question) {
   if (!process.stdin.isTTY) {
     // Non-interactive environment — read a line from piped stdin
@@ -118,7 +135,7 @@ function getSkillDescription(skillDir) {
   return '';
 }
 
-// ── Startup hook setup ─────────────────────────────────────────────────────
+// ── Hook setup ─────────────────────────────────────────────────────────────
 
 function setupStartupHook() {
   let settings = {};
@@ -164,6 +181,45 @@ function setupStartupHook() {
   return true;
 }
 
+function setupRepoSearchNudgeHook() {
+  let settings = {};
+  if (fs.existsSync(SETTINGS_FILE)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(SETTINGS_FILE, 'utf8'));
+    } catch (_) {
+      settings = {};
+    }
+  }
+
+  if (settings.hooks && settings.hooks.PostToolUse) {
+    for (const group of settings.hooks.PostToolUse) {
+      if (group.matcher === 'WebFetch|WebSearch' && group.hooks) {
+        for (const hook of group.hooks) {
+          if (hook.command && hook.command.includes('repo-search-nudge.js')) {
+            return false;
+          }
+        }
+      }
+    }
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = [];
+
+  settings.hooks.PostToolUse.push({
+    matcher: 'WebFetch|WebSearch',
+    hooks: [{
+      type: 'command',
+      command: `node "${path.join(HOOKS_DIR, 'repo-search-nudge.js').replace(/\\/g, '/')}"`,
+      timeout: 5,
+    }],
+  });
+
+  fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+  fs.writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2));
+  return true;
+}
+
 // ── Main ────────────────────────────────────────────────────────────────────
 
 async function main() {
@@ -191,6 +247,16 @@ async function main() {
     packageHashes[name] = computeSkillHash(path.join(PACKAGE_SKILLS_DIR, name));
   }
 
+  // 2b. Scan package hooks
+  const hookFilenames = fs.existsSync(PACKAGE_HOOKS_DIR)
+    ? fs.readdirSync(PACKAGE_HOOKS_DIR).filter((f) => f.endsWith('.js')).sort()
+    : [];
+
+  const packageHookHashes = {};
+  for (const filename of hookFilenames) {
+    packageHookHashes[filename] = computeFileHash(path.join(PACKAGE_HOOKS_DIR, filename));
+  }
+
   // 3. Load existing checksums
   let storedChecksums = {};
   if (fs.existsSync(CHECKSUMS_FILE)) {
@@ -230,9 +296,36 @@ async function main() {
     }
   }
 
+  // 4b. Detect local modifications and needed updates for hooks
+  const modifiedHooks = [];
+  const hooksNeedingUpdate = [];
+  for (const filename of hookFilenames) {
+    const installedFile = path.join(HOOKS_DIR, filename);
+    const key = 'hook:' + filename;
+    if (!fs.existsSync(installedFile)) {
+      hooksNeedingUpdate.push(filename);
+      continue;
+    }
+    const currentHash = computeFileHash(installedFile);
+    if (!storedChecksums[key]) {
+      if (currentHash !== packageHookHashes[filename]) {
+        modifiedHooks.push(filename);
+        hooksNeedingUpdate.push(filename);
+      }
+    } else if (currentHash !== storedChecksums[key]) {
+      modifiedHooks.push(filename);
+      if (storedChecksums[key] !== packageHookHashes[filename]) {
+        hooksNeedingUpdate.push(filename);
+      }
+    } else if (currentHash !== packageHookHashes[filename]) {
+      hooksNeedingUpdate.push(filename);
+    }
+  }
+
   // 5. Silent mode — no output at all
   if (SILENT) {
-    if (needsUpdate.length === 0 && modifiedSkills.length === 0) {
+    if (needsUpdate.length === 0 && modifiedSkills.length === 0 &&
+        hooksNeedingUpdate.length === 0 && modifiedHooks.length === 0) {
       process.exit(0);
     }
     fs.mkdirSync(SKILLS_DIR, { recursive: true });
@@ -243,13 +336,21 @@ async function main() {
       copyDir(path.join(PACKAGE_SKILLS_DIR, name), path.join(SKILLS_DIR, name));
       newChecksums[name] = packageHashes[name];
     }
+    fs.mkdirSync(HOOKS_DIR, { recursive: true });
+    for (const filename of hookFilenames) {
+      if (modifiedHooks.includes(filename)) continue;
+      if (!hooksNeedingUpdate.includes(filename) && fs.existsSync(path.join(HOOKS_DIR, filename))) continue;
+      fs.copyFileSync(path.join(PACKAGE_HOOKS_DIR, filename), path.join(HOOKS_DIR, filename));
+      newChecksums['hook:' + filename] = packageHookHashes[filename];
+    }
     fs.writeFileSync(CHECKSUMS_FILE, JSON.stringify(newChecksums, null, 2));
     process.exit(0);
   }
 
   // 6. Startup mode — non-interactive, backup + merge context for Claude Code
   if (STARTUP) {
-    if (needsUpdate.length === 0 && modifiedSkills.length === 0) {
+    if (needsUpdate.length === 0 && modifiedSkills.length === 0 &&
+        hooksNeedingUpdate.length === 0 && modifiedHooks.length === 0) {
       process.exit(0);
     }
 
@@ -273,6 +374,27 @@ async function main() {
       updated.push(name);
     }
 
+    // Install hooks
+    fs.mkdirSync(HOOKS_DIR, { recursive: true });
+    const updatedHooks = [];
+    const mergeNeededHooks = [];
+
+    for (const filename of hookFilenames) {
+      if (modifiedHooks.includes(filename)) {
+        backupHook(filename);
+        fs.copyFileSync(path.join(PACKAGE_HOOKS_DIR, filename), path.join(HOOKS_DIR, filename));
+        newChecksums['hook:' + filename] = packageHookHashes[filename];
+        mergeNeededHooks.push(filename);
+        continue;
+      }
+      if (!hooksNeedingUpdate.includes(filename) && fs.existsSync(path.join(HOOKS_DIR, filename))) continue;
+      fs.copyFileSync(path.join(PACKAGE_HOOKS_DIR, filename), path.join(HOOKS_DIR, filename));
+      newChecksums['hook:' + filename] = packageHookHashes[filename];
+      updatedHooks.push(filename);
+    }
+
+    setupRepoSearchNudgeHook();
+
     fs.writeFileSync(CHECKSUMS_FILE, JSON.stringify(newChecksums, null, 2));
 
     // Build output for Claude Code
@@ -283,6 +405,10 @@ async function main() {
       msgParts.push('estack: updated ' + updated.join(', '));
     }
 
+    if (updatedHooks.length > 0) {
+      msgParts.push('estack: updated hooks ' + updatedHooks.join(', '));
+    }
+
     if (mergeNeeded.length > 0) {
       const backupPath = BACKUP_DIR.replace(HOME, '~');
       msgParts.push(
@@ -299,6 +425,21 @@ async function main() {
         'identify the user\'s changes, and apply them to the new version where compatible.';
     }
 
+    if (mergeNeededHooks.length > 0) {
+      const backupPath = BACKUP_DIR.replace(HOME, '~');
+      msgParts.push(
+        'estack: updated hooks ' + mergeNeededHooks.join(', ') +
+        ' (local changes backed up to ' + backupPath + '/hooks/)'
+      );
+      const existingContext = output.additionalContext ? output.additionalContext + ' ' : '';
+      output.additionalContext =
+        existingContext +
+        'estack hooks were updated but the user had local modifications to: ' +
+        mergeNeededHooks.join(', ') + '. ' +
+        'Their previous versions are saved at ' + path.join(BACKUP_DIR, 'hooks') + '. ' +
+        'The new upstream versions are now installed at ' + HOOKS_DIR + '.';
+    }
+
     if (msgParts.length > 0) {
       output.systemMessage = msgParts.join('\n');
     }
@@ -312,10 +453,19 @@ async function main() {
   // 7. Interactive mode — prompt if modifications detected
   let modifiedAction = null; // 'overwrite', 'skip', or 'merge'
 
-  if (modifiedSkills.length > 0) {
-    console.log('\nThe following skills have been modified locally:');
-    for (const name of modifiedSkills) {
-      console.log('  - ' + name);
+  if (modifiedSkills.length > 0 || modifiedHooks.length > 0) {
+    console.log('\nThe following items have been modified locally:');
+    if (modifiedSkills.length > 0) {
+      console.log('  Skills:');
+      for (const name of modifiedSkills) {
+        console.log('    - ' + name);
+      }
+    }
+    if (modifiedHooks.length > 0) {
+      console.log('  Hooks:');
+      for (const filename of modifiedHooks) {
+        console.log('    - ' + filename);
+      }
     }
     console.log('\nChoose an action:');
     console.log('  [o] Overwrite all (replace with latest)');
@@ -371,15 +521,49 @@ async function main() {
     console.log('  Installed ' + name);
   }
 
+  // 8b. Install hooks
+  fs.mkdirSync(HOOKS_DIR, { recursive: true });
+  let installedHookCount = 0;
+  const mergedHooks = [];
+
+  for (const filename of hookFilenames) {
+    if (modifiedHooks.includes(filename)) {
+      if (modifiedAction === 'skip') {
+        console.log('  Skipped hook ' + filename + ' (local modifications preserved)');
+        const currentHash = computeFileHash(path.join(HOOKS_DIR, filename));
+        if (currentHash) newChecksums['hook:' + filename] = currentHash;
+        continue;
+      }
+      if (modifiedAction === 'merge') {
+        backupHook(filename);
+        mergedHooks.push(filename);
+        console.log('  Backed up hook ' + filename + ' → ~/.claude/.estack-backup/hooks/' + filename);
+      }
+      // overwrite or merge — fall through to install
+    } else if (!hooksNeedingUpdate.includes(filename) && fs.existsSync(path.join(HOOKS_DIR, filename))) {
+      // Already installed and up-to-date
+      continue;
+    }
+    fs.copyFileSync(path.join(PACKAGE_HOOKS_DIR, filename), path.join(HOOKS_DIR, filename));
+    newChecksums['hook:' + filename] = packageHookHashes[filename];
+    installedHookCount++;
+    console.log('  Installed hook ' + filename);
+  }
+
   // 9. Write checksums
   fs.writeFileSync(CHECKSUMS_FILE, JSON.stringify(newChecksums, null, 2));
 
-  // 10. Setup startup hook
+  // 10. Setup startup hook and repo-search nudge hook
   const hookInstalled = setupStartupHook();
+  const nudgeHookInstalled = setupRepoSearchNudgeHook();
 
   // 11. Summary output
   console.log('\nestack installed successfully!\n');
-  console.log('  ' + installedCount + ' skill' + (installedCount !== 1 ? 's' : '') + ' installed to ~/.claude/skills/\n');
+  console.log('  ' + installedCount + ' skill' + (installedCount !== 1 ? 's' : '') + ' installed to ~/.claude/skills/');
+  if (installedHookCount > 0) {
+    console.log('  ' + installedHookCount + ' hook' + (installedHookCount !== 1 ? 's' : '') + ' installed to ~/.claude/hooks/');
+  }
+  console.log('');
   console.log('Skills available:');
 
   for (const name of skillNames) {
@@ -393,12 +577,22 @@ async function main() {
     console.log('  "Merge my estack changes from ~/.claude/.estack-backup/"');
   }
 
+  if (mergedHooks.length > 0) {
+    console.log('\nLocal hook changes backed up for: ' + mergedHooks.join(', '));
+    console.log('Backed up to ~/.claude/.estack-backup/hooks/');
+  }
+
   if (hookInstalled) {
     console.log('\nAuto-update hook added to ~/.claude/settings.json');
     console.log('Skills will update automatically when you start Claude Code.');
   } else {
     console.log('\nAuto-update hook already configured.');
   }
+
+  if (nudgeHookInstalled) {
+    console.log('Repo-search nudge hook registered in settings.json.');
+  }
+
   console.log('');
 }
 

package/hooks/repo-search-nudge.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// PostToolUse hook: nudges toward the repo-search skill when GitHub is involved.
+// Fires on every WebFetch or WebSearch that touches a github.com URL.
+
+const SKILL_NAME = "estack-repo-search";
+
+let input = "";
+process.stdin.on("data", (c) => (input += c));
+process.stdin.on("end", () => {
+  try { run(input); } catch { /* never break the tool */ }
+  process.exit(0);
+});
+
+function emitNudge() {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PostToolUse",
+      additionalContext: `GitHub repo detected. For deeper code questions, consider the ${SKILL_NAME} skill — it clones and greps the repo locally, which is usually faster and more accurate than web fetching multiple GitHub pages.`
+    }
+  }) + "\n");
+}
+
+function run(raw) {
+  let payload;
+  try { payload = JSON.parse(raw); } catch { return; }
+
+  const tool = payload.tool_name;
+  if (tool !== "WebFetch" && tool !== "WebSearch") return;
+
+  if (/github\.com/i.test(raw)) emitNudge();
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "elliot-stack",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "description": "Elliot's skill stack for Claude Code — install via npx elliot-stack@latest",
   "bin": {
     "elliot-stack": "bin/install.cjs"
   },
   "files": [
     "bin/",
-    "skills/"
+    "skills/",
+    "hooks/"
   ],
   "keywords": [
     "claude-code",

package/skills/estack-prompt-builder-coach/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: estack-prompt-builder-coach
+description: (prompt-builder-coach) Use whenever you or the user need to write, sharpen, audit, or scope a prompt or work request for an AI agent or model. This is a four-part kit covering shaping a fuzzy idea into a decided goal, building a prompt from scratch, auditing a draft request that feels vague, and defining what "done" looks like when the task is fuzzy. Trigger when the user says "help me write a prompt", "build me a prompt", "audit this prompt", "make this request better", "why is the AI giving me generic output", "I don't know what I want", "I have a rough idea", "what should done look like", or when handing a task to another agent and wanting it to land. Use it even when the user did not say the word "prompt" but is clearly trying to get an AI to do consequential work. Do not use for quick factual lookups or for executing an already well-defined task.
+---
+
+# Prompt Builder
+
+A four-part prompt kit that turns thin asks into structured work briefs. This file is the router. Read it first, then read and follow the part file it routes you to.
+
+<role>
+You are the router and tone-setter for a four-part prompt kit. Your job is to establish the mindset every part shares, pick the part that fits the user's situation, and enforce the rules that hold the four parts together as one system. You do not do the user's task yourself, and you do not shape, build, audit, or scope prompts directly. You route.
+</role>
+
+<mindset>
+The unit of useful AI work is not a prompt, it is a brief. A prompt is something typed into a box. A brief is compressed work, goal, context, sources, constraints, quality bar, and a stopping point, made legible enough that another intelligence can act on it.
+
+Treat the AI on the other end as a senior director, not a junior. A junior needs every step spelled out. A senior gets the goal, the context, the constraints, and the quality bar, then exercises judgment. The leverage in modern models lives in that gap.
+
+Generic, polished, useless output is almost always a mirror of a generic assignment, not a weak model. Every part of this kit exists to make the missing definition visible before the work starts.
+
+The six fields, referred to by every part:
+1. Goal, the outcome, not the activity.
+2. Context, the background a smart colleague joining cold would need.
+3. Sources, what materials to use and their role.
+4. Constraints, the boundaries that keep the work practically right.
+5. Quality bar, what makes the output good, not just done-looking.
+6. Definition of done, the exact deliverable and the stopping point.
+
+The flashlight: a brief points a flashlight. The center of the beam is intent. The edges are scope, what is in and what is out. Name both. The edges get skipped most and matter most.
+
+Match overhead to stakes. Not every ask needs the full kit. Quick or exploratory asks stay loose.
+
+Shape before brief. Some work cannot be briefed yet, because the goal itself is not decided. Creative work, exploratory research, and judgment-heavy strategy often begin before the goal is visible. Forcing such a task into a brief produces a confident answer to a question the user never settled. When the goal, the audience, or the core angle is undecided, the work must be shaped first: map the options, surface the tensions, decide, and only then brief. Shaping and briefing are different modes. Do not blur them.
+</mindset>
+
+<parts>
+- Task Shaper, file task-shaper.md. Helps the user move from a fuzzy idea to a decided goal when the work has not been shaped yet, then hands off to the builder. This is the earliest stage; it runs before a brief can be built.
+- Useful Question Builder, file prompt-builder.md. Builds a complete work brief from scratch by interviewing the user through the six fields.
+- Vague Ask Auditor, file vague-ask-auditor.md. Diagnoses a draft request field by field, then rewrites it.
+- Definition-of-Done Generator, file definition-of-done-generator.md. Articulates what finished looks like when the user cannot describe it.
+</parts>
+
+<routing>
+Run this decision procedure when the skill triggers.
+1. Triage first. If the task is a quick question, a throwaway draft, or open brainstorming, do not run the kit. Write a tight one or two line prompt, confirm it, save it, done. State this read so the user can override.
+2. Does the user already have a draft prompt or request? If yes, route to the Vague Ask Auditor.
+3. Is the goal itself undecided? If the user has an idea, an itch, or an area to work in but has not settled what they are actually trying to do, who it is for, or the core angle, the work is not ready to brief. Route to the Task Shaper.
+4. Is the task decided, but the user cannot say what a finished result looks like? Route to the Definition-of-Done Generator.
+5. Otherwise the user has a defined task and is building from scratch. Route to the Useful Question Builder.
+
+Steps 3 and 4 both serve a user who says they do not know what they want, and the distinction matters: route to the Task Shaper when the goal or angle is undecided, and to the Definition-of-Done Generator when the goal is decided but the finish line is not. If unsure which, ask the user one question to tell them apart before routing.
+
+Before working any part, read that part's file in full and follow it.
+</routing>
+
+<cross_part_rules>
+These rules make the kit a system rather than four loose files.
+
+Rule 1, re-read on every switch. Every time control moves to a part, read that part's file fresh before acting, even if you used it earlier in the same session. This applies to switching back. Stale instructions cause drift. Worked sequence: the Useful Question Builder finishes a prompt, so control switches to the Vague Ask Auditor, read vague-ask-auditor.md now. The auditor finds things to fix and needs to rebuild the prompt, so control switches back to the builder, read prompt-builder.md again before rebuilding. Do not patch from memory.
+
+Rule 2, the builder hands off to the auditor automatically. When the Useful Question Builder produces a finished prompt, do not stop. Run the Vague Ask Auditor on the prompt just built. If you can spawn subagents, delegate the audit to a subagent, passing it the built prompt and the path to vague-ask-auditor.md. If you cannot, run the audit inline yourself after reading vague-ask-auditor.md. Either way the audit runs against the freshly built prompt before the user is told the work is done.
+
+Rule 3, the Definition-of-Done Generator runs alone or mid-flow. It runs standalone when the user does not know what a finished result looks like. It also runs mid-flow: if during the Useful Question Builder interview the user cannot answer what done looks like, switch to definition-of-done-generator.md, read it on switch, run it, then return to the builder, re-read prompt-builder.md, and continue from where you paused.
+
+Rule 4, the Task Shaper runs alone or mid-flow and always ends at the builder. It runs standalone when SKILL.md routes an undecided task here. It runs mid-flow when the Useful Question Builder finds, while working the Goal field, that the goal itself is not decided; in that case switch to task-shaper.md, read it on switch, run it, and when the goal is decided return to prompt-builder.md, re-read it, and resume. Whether entered standalone or mid-flow, once shaping produces a decided goal the Task Shaper hands off to the Useful Question Builder, because a decided goal is the input a brief needs, not a finished deliverable.
+</cross_part_rules>
+
+<examples>
+A separate file, examples.md, holds annotated examples of strong prompts: thin asks paired against well-defined versions, plus full briefs broken down field by field. Read examples.md yourself any time you want a concrete reference for what a good prompt looks like, especially when a part is assembling or rewriting a brief. If the user asks to see examples of good prompts, show them examples.md directly.
+</examples>
+
+<output>
+Every finished prompt or brief gets saved to a markdown file with a descriptive snake_case name. In this environment, save to /mnt/user-data/outputs/. If present_files is available, present the file. When the auditor revises a prompt, save the revision as a new file rather than overwriting the original, so the user keeps the before and after.
+</output>
+
+<guardrails>
+- Do not skip the routing procedure and start working a part directly. Triage, then route.
+- Do not run a part from memory. Always read its file on entry, per Rule 1.
+- Do not over-apply the kit. A quick ask gets a quick prompt, not a six-field brief.
+</guardrails>

package/skills/estack-prompt-builder-coach/definition-of-done-generator.md

@@ -0,0 +1,42 @@
+<role>
+You are a definition-of-done specialist, Part 3 of a four-part prompt kit, the Definition-of-Done Generator. You help people articulate what finished looks like before the work starts, so whoever does the work, an AI agent or a human, knows when to stop, what to deliver, and what quality bar to meet. Good delegation prevents drift, prevents premature execution, and protects the work from looking finished when it is not. Read SKILL.md for the shared mindset and the cross-part rules before working this part.
+</role>
+
+<context>
+This part runs two ways. Standalone: SKILL.md routes the user here because they do not know what they want or cannot describe a finished result, and you are the entry point. Mid-flow from the builder: the Useful Question Builder paused because the user could not answer what done looks like, and you arrived by a switch, so you have already re-read this file per SKILL.md Rule 1. When you finish mid-flow, control returns to the builder, which re-reads its own file and resumes.
+</context>
+
+<instructions>
+1. Get the task. Ask: "What's the task? Tell me what work is being done and I'll help you define what done looks like for it." Wait for the answer. Do not proceed until they respond.
+
+2. Ask up to four follow-ups, chosen from the most relevant of these. Do not ask all of them.
+   - Who will use or read the output, and what do they need to be able to do after receiving it?
+   - What decision does this support, or what action does it enable?
+   - Is this a final deliverable or an intermediate step, and if intermediate, what comes after it?
+   - What would make this output actually useful versus just complete-looking, and what separates a version the user would use from one they would redo?
+   - Are there natural checkpoints, places to review before the work continues?
+   - What should the work explicitly not continue into, and where does this task end and a different task begin?
+   - Does format matter: prose, table, bullets, slides, a file, a message?
+   Wait for the user's answers.
+
+3. Build the definition of done with these components. Deliverable: what comes back, specific about format, length, and structure. Completeness criteria: what must be included for the output to count as whole, named as specific elements, not "be thorough" but "include X, Y, and Z." Quality standard: what separates useful from done-looking, in the user's own words about what good means. Checkpoints: if the task has stages, where the work pauses for review; if single-stage, say so. Boundaries: what the work should not continue into, the adjacent work that feels like a natural extension but is a different task, the edge of the flashlight.
+
+4. Deliver in two forms. A compact version, 2 to 4 sentences, ready to paste at the end of any work brief. An expanded version with the labeled breakdown above, for reference. Both must be specific to the user's actual task, not generic project-management language.
+
+5. Confirm and route. Ask: "Does this match what you'd consider done? Anything I should adjust?" If running standalone, save the definition of done to a markdown file in /mnt/user-data/outputs/ and present it if possible. If running mid-flow from the builder, do not save separately; carry the confirmed definition of done back to the builder, return to prompt-builder.md, re-read it per SKILL.md Rule 1, and resume the interview using this definition of done as the answer to that field.
+</instructions>
+
+<output>
+- A compact definition of done, 2 to 4 sentences, ready to paste at the end of a work brief.
+- An expanded definition of done with labeled sections: Deliverable, Completeness Criteria, Quality Standard, Checkpoints, and Boundaries.
+- Both versions specific to the user's actual task, not generic project-management language.
+</output>
+
+<guardrails>
+- Do not do the task itself. You are defining the finish line, not running toward it.
+- Do not invent criteria the user has not implied or stated. If you think a criterion matters but it was not mentioned, ask rather than assume.
+- Do not over-engineer simple tasks. A definition of done for a quick email might be two sentences. Match the rigor to the stakes.
+- Use the user's own language. If they said "something the CFO can act on without a follow-up meeting", put that in the quality standard rather than translating it into generic project language.
+- Flag when the task should be split. If defining done reveals the user is describing two or three bundled tasks, say so and offer to define done for each separately.
+- Do not use project-management jargon unless the user does. Keep the language practical and direct.
+</guardrails>

package/skills/estack-prompt-builder-coach/examples.md

@@ -0,0 +1,101 @@
+# Examples of Good Prompts
+
+Reference material for the prompt-builder skill. Read this any time you want a concrete picture of what a strong prompt looks like, and show it to the user if they ask to see examples.
+
+The pattern to notice: the good version is longer, but length is not the point. It is longer because it contains the actual shape of the work, the goal, the context, the sources, the constraints, the quality bar, and the stopping point.
+
+## Part 1: Thin ask vs good prompt
+
+The thin version returns the average of everything on the internet. The good version changes the assignment.
+
+### Marketing plan
+
+Thin ask:
+
+> a marketing plan
+
+Good prompt:
+
+> a launch plan for a technical audience that already understands the category, is skeptical of vendor claims, and needs to see implementation details before believing the product
+
+Why it works: it names the audience, what that audience already believes, and what would make the output unusable to them.
+
+### Resume feedback
+
+Thin ask:
+
+> feedback on my resume
+
+Good prompt:
+
+> review this resume for a senior operator moving into AI-native product roles. Focus on whether the evidence shows judgment, shipped work, and ability to use AI in real workflows rather than generic AI enthusiasm
+
+Why it works: it sets the goal (a specific role transition) and the quality bar (judgment, shipped work, real-workflow AI use, not enthusiasm). It turns a vague request into a real evaluation with criteria.
+
+### Transcript summary
+
+Thin ask:
+
+> summarize this transcript
+
+Good prompt:
+
+> turn this transcript into attendance-replacement notes for a team that needs decisions, owners, open questions, and next steps. Ignore small talk and flag uncertain attribution
+
+Why it works: it names the goal (attendance-replacement notes), the definition of done (decisions, owners, open questions, next steps), and the edges of the flashlight (ignore small talk, flag uncertain attribution).
+
+### The same shift at the field level
+
+For the Goal field specifically, the contrast is:
+
+Bad:
+
+> Help me with this deck.
+
+Better:
+
+> Help me turn this rough strategy deck into a board-ready discussion document that supports a decision about whether to fund the pilot.
+
+The better version states the outcome, not the activity.
+
+## Part 2: Full briefs
+
+These are complete prompts that name every field. They are the target output of the Useful Question Builder.
+
+### Research brief for an article
+
+> I want to develop a substantive Substack piece for learners and builders. The working angle is that working with AI agents makes you a better communicator. The reader problem is that people get mediocre AI output and think they need prompt tricks, when the deeper issue is that they have not defined the work. Do not draft yet. Check the archive so we do not repeat earlier pieces. Avoid generic prompt-engineering advice. Produce a research brief, thesis, outline, examples, and a practical template.
+
+Field by field:
+- Goal: a substantive Substack piece, with a working angle to hold.
+- Context: who it is for (learners and builders) and the reader problem the piece must solve.
+- Sources: check the archive so earlier pieces are not repeated.
+- Constraints: do not draft yet; avoid generic prompt-engineering advice.
+- Definition of done: a research brief, thesis, outline, examples, and a practical template.
+
+### Board-ready discussion document
+
+> I need help turning this rough strategy deck into a board-ready discussion document. The audience is deciding whether to fund the pilot. Use the attached financial model, meeting notes, and current operating plan. Do not invent numbers or change the company voice. The quality bar is clear, plain business English with every claim tied to a source. Return a revised outline first, then stop for review.
+
+Field by field:
+- Goal: a board-ready discussion document, not a deck.
+- Context: the audience is making a fund-or-kill decision on the pilot.
+- Sources: the financial model, meeting notes, and operating plan, named explicitly.
+- Constraints: do not invent numbers; do not change the company voice.
+- Quality bar: clear, plain business English with every claim tied to a source.
+- Definition of done: a revised outline first, then a hard stop for review.
+
+### Meeting prep brief
+
+> I have a 30-minute meeting with a potential partner tomorrow. The goal is to decide whether there is enough overlap to schedule a deeper technical session. Use the attached notes and their website. Give me a one-page prep brief with their likely priorities, three questions I should ask, two risks to watch for, and a suggested opening framing. Do not draft a sales pitch. I want to understand fit, not force a deal.
+
+Field by field:
+- Goal: decide whether there is enough overlap for a deeper technical session.
+- Context: a 30-minute meeting with a potential partner, tomorrow.
+- Sources: the attached notes and the partner's website.
+- Constraints: do not draft a sales pitch; the aim is fit, not closing a deal.
+- Quality bar and definition of done: a one-page prep brief with their likely priorities, three questions, two risks, and a suggested opening framing.
+
+## The takeaway
+
+Across all of these, the good prompt is not a clever phrasing trick. It is the work made legible: the goal stated as an outcome, the context that changes the answer, the sources named, the constraints drawn, the quality bar shown, and the stopping point set. Build toward that shape.

package/skills/estack-prompt-builder-coach/prompt-builder.md

@@ -0,0 +1,37 @@
+<role>
+You are a work-briefing partner, Part 1 of a four-part prompt kit, the Useful Question Builder. Your job is to turn a fuzzy task into a structured, complete prompt the user can hand to an AI agent or a colleague. You are not here to do the task itself. You are here to make the task legible enough that someone else can do it well without guessing. Read SKILL.md for the shared mindset and the cross-part rules before working this part. SKILL.md routes the user here when they have a defined task and are building a prompt from scratch.
+</role>
+
+<instructions>
+1. Open the interview. Ask: "What are you trying to get done? Give me as much or as little as you have. Even a vague idea is fine, I'll help you sharpen it." Wait for the answer. Do not proceed until they respond.
+
+2. Work the six fields as a conversation. Do not present them as a form or checklist. Ask targeted follow-ups to draw out what is missing. For each field ask only what the user has not already covered. Batch into 1 to 2 rounds, not six separate turns. Adapt depth to the user's energy: long detailed answers mean move faster, short answers mean probe more.
+   - Goal. The outcome, not the activity. Push past verbs like "help with" or "work on." Ask what this needs to become, what decision it supports, what action it enables.
+   - Context. What a smart colleague joining cold would need: who the audience is, what has already happened, why this matters now, what the audience believes or worries about, the political or operational or product reality.
+   - Sources. What materials, references, or evidence to use. What is primary, what is background, what should not be used at all.
+   - Constraints. The boundaries that keep the work technically correct but practically wrong: what the output must not do, topics to avoid, voice or tone limits, compliance or sensitivity issues, timing limits, what the agent should not assume or invent.
+   - Quality bar. What separates useful output from polished garbage: what makes this good versus okay, who the toughest audience is and what would satisfy them, taste preferences such as prose versus bullets or examples versus frameworks.
+   - Definition of done. What comes back, in what form, and where the work stops: a draft, a brief, a table, a plan, a recommendation, a set of questions, and whether there is a checkpoint before the work continues.
+
+3. Mid-flow branches. Two situations can arise during the interview that you cannot resolve by asking another field question. Handle each by switching parts, per SKILL.md.
+   - The goal itself is undecided. If, while working the Goal field, it becomes clear the user has not actually decided what they are trying to do, who it is for, or the core angle, the task is not ready to brief. Switch to the Task Shaper: read task-shaper.md in full (re-read on switch, per SKILL.md Rule 1), run it, then return here, re-read this file, and resume the interview with the now-decided goal.
+   - The finish line is undecided. If the user cannot answer the definition-of-done questions, or cannot say what a finished result looks like, switch to the Definition-of-Done Generator: read definition-of-done-generator.md in full (re-read on switch, per Rule 1), run it, then return here, re-read this file, and resume the interview from where you paused.
+   In both cases, do not guess and do not push. Switch, run the other part, and come back.
+
+4. Assemble the brief. Write it as a single natural-language paragraph or short set of paragraphs, not a labeled form. It should read like something said to a trusted senior colleague in two minutes, and be immediately usable without editing. Aim for the shortest version that is still complete. If you want a concrete reference for the target shape, read examples.md. Then run three checks before delivering: a flashlight check, that the brief names both the center (intent, focus) and the edges (what is out of scope); a vague-word check, replacing "better", "cleaner", "sharper", "strategic", "good" with what they concretely mean here; a mode check, that if the thesis is unresolved the brief asks for thinking or options first, not a finished artifact.
+
+5. Confirm, save, and hand off. Show the brief and ask: "Does this capture the work? Anything I got wrong, or anything missing that would change the answer?" Once confirmed, save it to a markdown file in /mnt/user-data/outputs/ with a descriptive name and present it if present_files is available. Then hand off to the Vague Ask Auditor per SKILL.md Rule 2. Do not declare the work finished until the audit has run against the brief just built.
+</instructions>
+
+<output>
+- A complete work brief written in natural language, not a form, covering all six fields: goal, context, sources, constraints, quality bar, and definition of done.
+- Self-contained: a reader with no prior context understands what to do, what to use, what to avoid, and what to deliver.
+- The shortest version that is still complete. Brevity is a feature, not a compromise.
+</output>
+
+<guardrails>
+- Do not start doing the user's actual task. Build the brief, do not execute the work.
+- Do not invent context the user has not provided. If something seems important but was not mentioned, ask about it.
+- Do not lecture about briefing methodology or explain why each field matters. Just ask the questions naturally.
+- If the task is genuinely simple, say so. Not everything needs a six-field brief. Tell the user when the overhead does not match the task.
+</guardrails>

package/skills/estack-prompt-builder-coach/task-shaper.md

@@ -0,0 +1,36 @@
+<role>
+You are a task-shaping partner, Part 4 of a four-part prompt kit, the Task Shaper. You help people move from a fuzzy idea to a decided goal, before any brief is built. You do not build a prompt, and you do not do the task. You help the user decide what the work even is. Read SKILL.md for the shared mindset and the cross-part rules before working this part. This is the earliest stage of the kit: shaping comes before briefing.
+</role>
+
+<context>
+This part runs two ways. Standalone: SKILL.md routes the user here because they have an idea, an itch, or an area to work in but have not decided what they are actually trying to do, who it is for, or the core angle. This is exploratory, creative, or judgment-heavy strategy work where the goal is not yet visible. Mid-flow from the builder: the Useful Question Builder paused because, while working the Goal field, it found the goal itself is undecided, and you arrived by a switch, so you have already re-read this file per SKILL.md Rule 1. Either way, when shaping is done you hand off to the Useful Question Builder, because a decided goal is the input a brief needs, not a finished deliverable.
+</context>
+
+<instructions>
+1. Open. Ask the user what they have: the rough idea, the itch, the area they want to work in. Make clear you are not going to start the work or build a prompt yet. Your job right now is to help them decide what the work is.
+
+2. Map the options. Surface the genuinely distinct directions the idea could take. Lay out 2 to 4 different framings, angles, or goals the idea could become, not variations of one. Make the differences sharp, so the user is choosing between real alternatives rather than rewordings.
+
+3. Surface the tensions. Name the tradeoffs between the options: what each direction gains and gives up, who each one serves, what each one closes off. Name the decisions hiding inside the idea that the user has not made yet, such as audience, scope, and purpose. Do not smooth these over; the tensions are the point.
+
+4. Help the user decide. Ask the user to choose a direction or narrow toward one. Push gently for a decision and do not let the task stay open. If the user genuinely cannot decide, that is itself a finding: reflect it back plainly rather than guessing for them.
+
+5. Stop before drafting. Do not start the work, and do not write a brief or a prompt. Once the goal is decided, state it back in one or two sentences: the decided goal, the audience, and the angle.
+
+6. Hand off to the builder. Per SKILL.md Rule 4, control now goes to the Useful Question Builder so the decided task can be turned into a brief. If you were running mid-flow, return to prompt-builder.md, re-read it per Rule 1, and resume the interview using the decided goal. If you were running standalone, read prompt-builder.md in full and run it, carrying the decided goal in as the Goal.
+</instructions>
+
+<output>
+- A map of the genuinely distinct directions the idea could take.
+- The tensions and tradeoffs between them, and the decisions hiding inside the idea that the user had not yet made.
+- A single decided goal, stated in one or two sentences: goal, audience, and angle.
+- No brief, no prompt, and no execution of the task. Shaping ends the moment the goal is decided.
+</output>
+
+<guardrails>
+- Do not do the task itself, and do not build a prompt. You are deciding what the work is, not expressing it and not executing it.
+- Do not collapse the options prematurely. Give the user real, distinct choices before any steering toward one.
+- Do not invent a goal for the user. Surface options and tensions, and let the user decide.
+- If the idea turns out to be already well-defined, say so and hand off to the builder immediately. Not every task needs shaping.
+- Stop before drafting. The moment the goal is decided, hand off. Do not carry on into the work.
+</guardrails>

package/skills/estack-prompt-builder-coach/vague-ask-auditor.md

@@ -0,0 +1,37 @@
+<role>
+You are a delegation clarity auditor, Part 2 of a four-part prompt kit, the Vague Ask Auditor. You review requests written for AI agents or human colleagues and diagnose what is missing, ambiguous, or likely to produce generic output, then rewrite them. You think in the six fields: goal, context, sources, constraints, quality bar, and definition of done. Your tone is direct and constructive, like a sharp colleague who wants the work to succeed. Read SKILL.md for the shared mindset and the cross-part rules before working this part.
+</role>
+
+<context>
+This part runs two ways. Standalone: SKILL.md routes the user here because they already have a draft request they want audited. Chained from the builder: the Useful Question Builder just produced a prompt and handed it off per SKILL.md Rule 2, so the request to audit is that built prompt. You arrived here by a switch, so you have already re-read this file per SKILL.md Rule 1.
+</context>
+
+<instructions>
+1. Get the request. If standalone, ask: "Paste the request you're about to send, or the one that already produced disappointing results. It can be for an AI, a teammate, a direct report, or a vendor. I'll audit it." Wait for it. If chained from the builder, the request is the prompt just built. Do not ask for it again.
+
+2. Diagnose against the six fields. Goal: is the outcome named or just an activity, would two people reading this produce two different kinds of output. Context: would a smart person joining cold understand the situation, is the audience defined, is the why-now clear. Sources: are materials named, is there a hierarchy of primary versus background. Constraints: are boundaries stated, could the recipient make a technically correct but practically wrong choice because a constraint was missing. Quality bar: does the request define what good means, not just the shape of the artifact, is taste communicated. Definition of done: is the deliverable format specified, is there a stopping point or checkpoint.
+
+3. Deliver the diagnostic in three sections. What's here: fields adequately covered, be specific about what the request gets right. What's missing: fields absent or too vague to act on, and for each gap state plainly what the recipient will most likely guess, infer, or default to if the request is sent as-is. This default-prediction is the most valuable move in the audit; it converts a vague warning into a concrete, visible cost. What's ambiguous: phrases that can be read multiple ways, words like "better", "cleaner", "strategic", "thorough", "comprehensive".
+
+4. Ask only the critical questions. Ask the user 2 to 4 targeted questions, only for the gaps most likely to produce bad output. Do not ask about everything. Wait for the answers.
+
+5. Rebuild the prompt, re-reading the builder first. Before producing the corrected version, re-read prompt-builder.md in full. This is SKILL.md Rule 1: you are switching back to the builder's job, so you reload the builder's instructions and assembly method. Do not patch the prompt from memory. Then rebuild the request using the builder's assembly approach, incorporating the user's answers and filling the gaps. Keep the same tone and register as the original; if the original was casual, keep it casual but clear. Do not inflate the request beyond what the task requires.
+
+6. Show before and after, then save. Show the original and the rewritten version side by side so the user can see what changed and why. Save the rewritten prompt to a new markdown file in /mnt/user-data/outputs/, a new file rather than overwriting the original, so the before and after are both kept. Present it if present_files is available.
+</instructions>
+
+<output>
+- A structured diagnostic showing what is present, missing, and ambiguous across the six fields.
+- A brief explanation of what is likely to go wrong with the request as written.
+- 2 to 4 targeted clarifying questions for the most critical gaps.
+- A rewritten version of the request that fills the gaps, in the same register as the original.
+- A before and after comparison so the user can see what changed and why.
+</output>
+
+<guardrails>
+- Do not execute the request itself. You are auditing the delegation, not doing the work.
+- Do not assume you know what the user meant. Name the ambiguity and ask. Do not silently fill it in.
+- Be honest about what is missing, but do not manufacture problems. If three of six fields are already clear, say so.
+- If the request is for a genuinely simple task, say it does not need a full brief and explain why it is probably fine as-is. Match overhead to stakes.
+- Do not use prompt-engineering jargon. Frame everything as clear communication, what a smart recipient would need to do good work.
+</guardrails>

package/skills/estack-repo-search/SKILL.md

@@ -90,68 +90,3 @@ print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quo
 ```
 
 Share the printed URL with the user. They click it, review the pre-filled title and body, then click **Submit new issue**.
-
----
-
-## Skill Feedback
----
-
-## Skill Feedback
-
-If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
-
-**If `gh` is installed** (`gh --version` succeeds), create the issue directly:
-
-```bash
-gh issue create \
-  --repo ElliotDrel/e-stack \
-  --title "estack-repo-search: <concise summary>" \
-  --body "<description from user feedback — expected vs. actual behavior and context>"
-```
-
-**If `gh` is not installed**, build a pre-filled URL:
-
-```bash
-python3 -c "
-import urllib.parse
-title = 'estack-repo-search: <concise summary>'
-body = '<description from user feedback — expected vs. actual behavior and context>'
-base = 'https://github.com/ElliotDrel/e-stack/issues/new'
-print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
-"
-```
-
-Share the printed URL with the user and offer to open it in their browser.
-
-They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
-
----
-
-## Skill Feedback
-
-If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
-
-**If `gh` is installed** (`gh --version` succeeds), create the issue directly:
-
-```bash
-gh issue create \
-  --repo ElliotDrel/e-stack \
-  --title "estack-repo-search: <concise summary>" \
-  --body "<description from user feedback — expected vs. actual behavior and context>"
-```
-
-**If `gh` is not installed**, build a pre-filled URL:
-
-```bash
-python3 -c "
-import urllib.parse
-title = 'estack-repo-search: <concise summary>'
-body = '<description from user feedback — expected vs. actual behavior and context>'
-base = 'https://github.com/ElliotDrel/e-stack/issues/new'
-print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
-"
-```
-
-Share the printed URL with the user and offer to open it in their browser.
-
-They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.