@joshski/dust 0.1.21 → 0.1.23

package/dist/artifacts.js

@@ -0,0 +1,59 @@
+// lib/artifacts/idea-transition-task.ts
+var IDEA_TRANSITION_PREFIXES = [
+  "Refine Idea: ",
+  "Create Task From Idea: ",
+  "Shelve Idea: "
+];
+var TRANSITION_PREFIX_MAP = {
+  "refine-idea": "Refine Idea: ",
+  "create-task-from-idea": "Create Task From Idea: ",
+  "shelve-idea": "Shelve Idea: "
+};
+function titleToFilename(title) {
+  return `${title.toLowerCase().replace(/\./g, "-").replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "")}.md`;
+}
+async function createIdeaTransitionTask(fileSystem, dustPath, input) {
+  const ideaPath = `${dustPath}/ideas/${input.ideaSlug}.md`;
+  if (!fileSystem.exists(ideaPath)) {
+    throw new Error(`Idea not found: "${input.ideaSlug}" (expected file at ${ideaPath})`);
+  }
+  const ideaContent = await fileSystem.readFile(ideaPath);
+  const ideaTitleMatch = ideaContent.match(/^#\s+(.+)$/m);
+  if (!ideaTitleMatch) {
+    throw new Error(`Idea file has no title: ${ideaPath}`);
+  }
+  const ideaTitle = ideaTitleMatch[1].trim();
+  const prefix = TRANSITION_PREFIX_MAP[input.transition];
+  const taskTitle = `${prefix}${ideaTitle}`;
+  const filename = titleToFilename(taskTitle);
+  const filePath = `${dustPath}/tasks/${filename}`;
+  const goalsSection = input.goals.length > 0 ? input.goals.map((slug) => `- [${slug}](../goals/${slug}.md)`).join(`
+`) : "(none)";
+  const blockedBySection = input.blockedBy.length > 0 ? input.blockedBy.map((slug) => `- [${slug}](../tasks/${slug}.md)`).join(`
+`) : "(none)";
+  const definitionOfDoneSection = input.definitionOfDone.map((item) => `- [ ] ${item}`).join(`
+`);
+  const content = `# ${taskTitle}
+
+${input.openingSentence}
+
+## Goals
+
+${goalsSection}
+
+## Blocked By
+
+${blockedBySection}
+
+## Definition of Done
+
+${definitionOfDoneSection}
+`;
+  await fileSystem.writeFile(filePath, content);
+  return { filePath };
+}
+export {
+  titleToFilename,
+  createIdeaTransitionTask,
+  IDEA_TRANSITION_PREFIXES
+};

package/dist/dust.js

@@ -108,6 +108,9 @@ function loadTemplate(name, variables = {}) {
   return content;
 }
 
+// lib/cli/commands/agent-shared.ts
+import { join as join4 } from "node:path";
+
 // lib/agents/detection.ts
 function detectAgent(env = process.env) {
   if (env.CLAUDECODE) {
@@ -252,6 +255,18 @@ ${newHookContent}
 }
 
 // lib/cli/commands/agent-shared.ts
+async function loadAgentInstructions(cwd, fileSystem, agentType) {
+  const instructionsPath = join4(cwd, ".dust", "config", "agents", `${agentType}.md`);
+  if (!fileSystem.exists(instructionsPath)) {
+    return "";
+  }
+  try {
+    const content = await fileSystem.readFile(instructionsPath);
+    return content.trim();
+  } catch {
+    return "";
+  }
+}
 function templateVariables(settings, hooksInstalled, env = process.env) {
   const agent = detectAgent(env);
   return {
@@ -261,6 +276,17 @@ function templateVariables(settings, hooksInstalled, env = process.env) {
     isClaudeCodeWeb: agent.type === "claude-code-web" ? "true" : ""
   };
 }
+async function templateVariablesWithInstructions(cwd, fileSystem, settings, hooksInstalled, env = process.env) {
+  const agent = detectAgent(env);
+  const agentInstructions = await loadAgentInstructions(cwd, fileSystem, agent.type);
+  return {
+    bin: settings.dustCommand,
+    agentName: agent.name,
+    hooksInstalled: hooksInstalled ? "true" : "false",
+    isClaudeCodeWeb: agent.type === "claude-code-web" ? "true" : "",
+    agentInstructions
+  };
+}
 async function manageGitHooks(dependencies) {
   const { context, fileSystem, settings } = dependencies;
   const hooks = createHooksManager(context.cwd, fileSystem, settings);
@@ -281,19 +307,59 @@ async function manageGitHooks(dependencies) {
 
 // lib/cli/commands/agent.ts
 async function agent(dependencies) {
-  const { context, settings } = dependencies;
+  const { context, fileSystem, settings } = dependencies;
   const hooksInstalled = await manageGitHooks(dependencies);
-  const vars = templateVariables(settings, hooksInstalled);
+  const vars = await templateVariablesWithInstructions(context.cwd, fileSystem, settings, hooksInstalled);
   context.stdout(loadTemplate("agent-greeting", vars));
   return { exitCode: 0 };
 }
 
-// lib/cli/commands/check.ts
+// lib/cli/process-runner.ts
 import { spawn } from "node:child_process";
+function createShellRunner(spawnFn) {
+  return {
+    run: (command, cwd) => runBufferedProcess(spawnFn, command, [], cwd, true)
+  };
+}
+var defaultShellRunner = createShellRunner(spawn);
+function createGitRunner(spawnFn) {
+  return {
+    run: (gitArguments, cwd) => runBufferedProcess(spawnFn, "git", gitArguments, cwd, false)
+  };
+}
+var defaultGitRunner = createGitRunner(spawn);
+function runBufferedProcess(spawnFn, command, commandArguments, cwd, shell) {
+  return new Promise((resolve) => {
+    const proc = spawnFn(command, commandArguments, { cwd, shell });
+    const chunks = [];
+    proc.stdout?.on("data", (data) => {
+      chunks.push(data.toString());
+    });
+    proc.stderr?.on("data", (data) => {
+      chunks.push(data.toString());
+    });
+    proc.on("close", (code) => {
+      resolve({ exitCode: code ?? 1, output: chunks.join("") });
+    });
+    proc.on("error", (error) => {
+      resolve({ exitCode: 1, output: error.message });
+    });
+  });
+}
 
 // lib/cli/commands/lint-markdown.ts
 import { dirname as dirname2, resolve } from "node:path";
 
+// lib/artifacts/idea-transition-task.ts
+var IDEA_TRANSITION_PREFIXES = [
+  "Refine Idea: ",
+  "Create Task From Idea: ",
+  "Shelve Idea: "
+];
+function titleToFilename(title) {
+  return `${title.toLowerCase().replace(/\./g, "-").replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "")}.md`;
+}
+
 // lib/markdown/markdown-utilities.ts
 function extractTitle(content) {
   const match = content.match(/^#\s+(.+)$/m);
@@ -362,9 +428,6 @@ function validateFilename(filePath) {
   }
   return null;
 }
-function titleToFilename(title) {
-  return `${title.toLowerCase().replace(/\./g, "-").replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "")}.md`;
-}
 function validateTitleFilenameMatch(filePath, content) {
   const title = extractTitle(content);
   if (!title) {
@@ -404,6 +467,36 @@ function validateOpeningSentenceLength(filePath, content) {
   }
   return null;
 }
+var NON_IMPERATIVE_STARTERS = new Set([
+  "the",
+  "a",
+  "an",
+  "this",
+  "that",
+  "these",
+  "those",
+  "we",
+  "it",
+  "they",
+  "you",
+  "i"
+]);
+function validateImperativeOpeningSentence(filePath, content) {
+  const openingSentence = extractOpeningSentence(content);
+  if (!openingSentence) {
+    return null;
+  }
+  const firstWord = openingSentence.split(/\s/)[0].replace(/[^a-zA-Z]/g, "");
+  const lower = firstWord.toLowerCase();
+  if (NON_IMPERATIVE_STARTERS.has(lower) || lower.endsWith("ing")) {
+    const preview = openingSentence.length > 40 ? `${openingSentence.slice(0, 40)}...` : openingSentence;
+    return {
+      file: filePath,
+      message: `Opening sentence should use imperative form (e.g., "Add X" not "This adds X"). Found: "${preview}"`
+    };
+  }
+  return null;
+}
 function validateTaskHeadings(filePath, content) {
   const violations = [];
   for (const heading of REQUIRED_HEADINGS) {
@@ -443,6 +536,61 @@ function validateLinks(filePath, content, fileSystem) {
   }
   return violations;
 }
+function validateIdeaOpenQuestions(filePath, content) {
+  const violations = [];
+  const lines = content.split(`
+`);
+  let inOpenQuestions = false;
+  let currentQuestionLine = null;
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith("## ")) {
+      if (inOpenQuestions && currentQuestionLine !== null) {
+        violations.push({
+          file: filePath,
+          message: "Question has no options listed beneath it",
+          line: currentQuestionLine
+        });
+      }
+      inOpenQuestions = line === "## Open Questions";
+      currentQuestionLine = null;
+      continue;
+    }
+    if (!inOpenQuestions)
+      continue;
+    if (line.startsWith("### ")) {
+      if (currentQuestionLine !== null) {
+        violations.push({
+          file: filePath,
+          message: "Question has no options listed beneath it",
+          line: currentQuestionLine
+        });
+      }
+      if (!line.trimEnd().endsWith("?")) {
+        violations.push({
+          file: filePath,
+          message: 'Questions must end with "?" (e.g., "### Should we take our own payments?")',
+          line: i + 1
+        });
+        currentQuestionLine = null;
+      } else {
+        currentQuestionLine = i + 1;
+      }
+      continue;
+    }
+    if (line.startsWith("#### ")) {
+      currentQuestionLine = null;
+    }
+  }
+  if (inOpenQuestions && currentQuestionLine !== null) {
+    violations.push({
+      file: filePath,
+      message: "Question has no options listed beneath it",
+      line: currentQuestionLine
+    });
+  }
+  return violations;
+}
 var SEMANTIC_RULES = [
   {
     section: "## Goals",
@@ -506,6 +654,26 @@ function validateSemanticLinks(filePath, content) {
   }
   return violations;
 }
+function validateIdeaTransitionTitle(filePath, content, ideasPath, fileSystem) {
+  const title = extractTitle(content);
+  if (!title) {
+    return null;
+  }
+  for (const prefix of IDEA_TRANSITION_PREFIXES) {
+    if (title.startsWith(prefix)) {
+      const ideaTitle = title.slice(prefix.length);
+      const ideaFilename = titleToFilename(ideaTitle);
+      if (!fileSystem.exists(`${ideasPath}/${ideaFilename}`)) {
+        return {
+          file: filePath,
+          message: `Idea transition task references non-existent idea: "${ideaTitle}" (expected file "${ideaFilename}" in ideas/)`
+        };
+      }
+      return null;
+    }
+  }
+  return null;
+}
 function validateGoalHierarchySections(filePath, content) {
   const violations = [];
   for (const heading of REQUIRED_GOAL_HEADINGS) {
@@ -735,6 +903,26 @@ async function lintMarkdown(dependencies) {
       }
     }
   }
+  const ideasPath = `${dustPath}/ideas`;
+  const { files: ideaFiles } = await safeScanDir(glob, ideasPath);
+  if (ideaFiles.length > 0) {
+    context.stdout("Validating idea files in .dust/ideas/...");
+    for (const file of ideaFiles) {
+      if (!file.endsWith(".md"))
+        continue;
+      const filePath = `${ideasPath}/${file}`;
+      let content;
+      try {
+        content = await fileSystem.readFile(filePath);
+      } catch (error) {
+        if (error.code === "ENOENT") {
+          continue;
+        }
+        throw error;
+      }
+      violations.push(...validateIdeaOpenQuestions(filePath, content));
+    }
+  }
   const tasksPath = `${dustPath}/tasks`;
   const { files: taskFiles } = await safeScanDir(glob, tasksPath);
   if (taskFiles.length > 0) {
@@ -758,6 +946,14 @@ async function lintMarkdown(dependencies) {
       }
       violations.push(...validateTaskHeadings(filePath, content));
       violations.push(...validateSemanticLinks(filePath, content));
+      const imperativeViolation = validateImperativeOpeningSentence(filePath, content);
+      if (imperativeViolation) {
+        violations.push(imperativeViolation);
+      }
+      const ideaTransitionViolation = validateIdeaTransitionTitle(filePath, content, ideasPath, fileSystem);
+      if (ideaTransitionViolation) {
+        violations.push(ideaTransitionViolation);
+      }
     }
   }
   const goalsPath = `${dustPath}/goals`;
@@ -800,29 +996,6 @@ async function lintMarkdown(dependencies) {
 }
 
 // lib/cli/commands/check.ts
-function createBufferedRunner(spawnFn) {
-  return {
-    run: (command, cwd) => {
-      return new Promise((resolve2) => {
-        const proc = spawnFn(command, [], { cwd, shell: true });
-        const chunks = [];
-        proc.stdout?.on("data", (data) => {
-          chunks.push(data.toString());
-        });
-        proc.stderr?.on("data", (data) => {
-          chunks.push(data.toString());
-        });
-        proc.on("close", (code) => {
-          resolve2({ exitCode: code ?? 1, output: chunks.join("") });
-        });
-        proc.on("error", (error) => {
-          resolve2({ exitCode: 1, output: error.message });
-        });
-      });
-    }
-  };
-}
-var defaultBufferedRunner = createBufferedRunner(spawn);
 async function runConfiguredChecks(checks, cwd, runner) {
   const promises = checks.map(async (check) => {
     const startTime = Date.now();
@@ -893,7 +1066,7 @@ function displayResults(results, context) {
   context.stdout(`${indicator} ${passed.length}/${results.length} checks passed`);
   return failed.length > 0 ? 1 : 0;
 }
-async function check(dependencies, bufferedRunner = defaultBufferedRunner) {
+async function check(dependencies, shellRunner = defaultShellRunner) {
   const { context, fileSystem, settings } = dependencies;
   if (!settings.checks || settings.checks.length === 0) {
     context.stderr("Error: No checks configured in .dust/config/settings.json");
@@ -912,7 +1085,7 @@ async function check(dependencies, bufferedRunner = defaultBufferedRunner) {
   if (fileSystem.exists(dustPath)) {
     checkPromises.push(runValidationCheck(dependencies));
   }
-  checkPromises.push(runConfiguredChecks(settings.checks, context.cwd, bufferedRunner));
+  checkPromises.push(runConfiguredChecks(settings.checks, context.cwd, shellRunner));
   const promiseResults = await Promise.all(checkPromises);
   const results = [];
   for (const result of promiseResults) {
@@ -960,9 +1133,8 @@ var createTemplateCommand = (templateName) => async (dependencies) => {
 // lib/cli/commands/implement-task.ts
 var implementTask = createTemplateCommand("agent-implement-task");
 
-// lib/cli/commands/init.ts
-var DUST_DIRECTORIES = ["goals", "ideas", "tasks", "facts", "config"];
-var colors = {
+// lib/cli/colors.ts
+var ANSI_COLORS = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",
   dim: "\x1B[2m",
@@ -970,6 +1142,32 @@ var colors = {
   green: "\x1B[32m",
   yellow: "\x1B[33m"
 };
+var NO_COLORS = {
+  reset: "",
+  bold: "",
+  dim: "",
+  cyan: "",
+  green: "",
+  yellow: ""
+};
+function shouldDisableColors() {
+  if (process.env.NO_COLOR !== undefined) {
+    return true;
+  }
+  if (process.env.TERM === "dumb") {
+    return true;
+  }
+  if (!process.stdout.isTTY) {
+    return true;
+  }
+  return false;
+}
+function getColors() {
+  return shouldDisableColors() ? NO_COLORS : ANSI_COLORS;
+}
+
+// lib/cli/commands/init.ts
+var DUST_DIRECTORIES = ["goals", "ideas", "tasks", "facts", "config"];
 function generateSettings(cwd, fileSystem) {
   const dustCommand = detectDustCommand(cwd, fileSystem);
   const testCommand = detectTestCommand(cwd, fileSystem);
@@ -985,6 +1183,7 @@ This project uses [dust](https://github.com/joshski/dust) for planning and docum
 `;
 async function init(dependencies) {
   const { context, fileSystem } = dependencies;
+  const colors = getColors();
   const dustPath = `${context.cwd}/.dust`;
   const dustCommand = detectDustCommand(context.cwd, fileSystem);
   const agentInstruction = `Always immediately run \`${dustCommand} agent\` when you start working in this repository.`;
@@ -1057,37 +1256,6 @@ async function init(dependencies) {
 
 // lib/cli/commands/list.ts
 import { basename } from "node:path";
-
-// lib/cli/colors.ts
-var ANSI_COLORS = {
-  reset: "\x1B[0m",
-  bold: "\x1B[1m",
-  dim: "\x1B[2m",
-  cyan: "\x1B[36m"
-};
-var NO_COLORS = {
-  reset: "",
-  bold: "",
-  dim: "",
-  cyan: ""
-};
-function shouldDisableColors() {
-  if (process.env.NO_COLOR !== undefined) {
-    return true;
-  }
-  if (process.env.TERM === "dumb") {
-    return true;
-  }
-  if (!process.stdout.isTTY) {
-    return true;
-  }
-  return false;
-}
-function getColors() {
-  return shouldDisableColors() ? NO_COLORS : ANSI_COLORS;
-}
-
-// lib/cli/commands/list.ts
 var VALID_TYPES = ["tasks", "ideas", "goals", "facts"];
 var SECTION_HEADERS = {
   tasks: "\uD83D\uDCCB Tasks",
@@ -1149,7 +1317,7 @@ function renderHierarchy(nodes, output, prefix = "") {
 async function list(dependencies) {
   const { arguments: commandArguments, context, fileSystem } = dependencies;
   const dustPath = `${context.cwd}/.dust`;
-  const colors2 = getColors();
+  const colors = getColors();
   if (!fileSystem.exists(dustPath)) {
     context.stderr("Error: .dust directory not found");
     context.stderr("Run 'dust init' to initialize a Dust repository");
@@ -1185,7 +1353,7 @@ async function list(dependencies) {
     if (type === "goals") {
       const hierarchy = await buildGoalHierarchy(dirPath, fileSystem);
       if (hierarchy.length > 0) {
-        context.stdout(`${colors2.dim}Hierarchy:${colors2.reset}`);
+        context.stdout(`${colors.dim}Hierarchy:${colors.reset}`);
         renderHierarchy(hierarchy, (line) => context.stdout(line));
         context.stdout("");
       }
@@ -1197,14 +1365,14 @@ async function list(dependencies) {
       const openingSentence = extractOpeningSentence(content);
       const relativePath = `.dust/${type}/${file}`;
       if (title) {
-        context.stdout(`${colors2.bold}# ${title}${colors2.reset}`);
+        context.stdout(`${colors.bold}# ${title}${colors.reset}`);
       } else {
-        context.stdout(`${colors2.bold}# ${file.replace(".md", "")}${colors2.reset}`);
+        context.stdout(`${colors.bold}# ${file.replace(".md", "")}${colors.reset}`);
       }
       if (openingSentence) {
-        context.stdout(`${colors2.dim}${openingSentence}${colors2.reset}`);
+        context.stdout(`${colors.dim}${openingSentence}${colors.reset}`);
       }
-      context.stdout(`${colors2.cyan}→ ${relativePath}${colors2.reset}`);
+      context.stdout(`${colors.cyan}→ ${relativePath}${colors.reset}`);
       context.stdout("");
     }
   }
@@ -1629,7 +1797,7 @@ function extractBlockedBy(content) {
 async function next(dependencies) {
   const { context, fileSystem } = dependencies;
   const dustPath = `${context.cwd}/.dust`;
-  const colors2 = getColors();
+  const colors = getColors();
   if (!fileSystem.exists(dustPath)) {
     context.stderr("Error: .dust directory not found");
     context.stderr("Run 'dust init' to initialize a Dust repository");
@@ -1666,11 +1834,11 @@ async function next(dependencies) {
   for (const task of unblockedTasks) {
     const parts = task.path.split("/");
     const displayTitle = task.title || parts[parts.length - 1].replace(".md", "");
-    context.stdout(`${colors2.bold}# ${displayTitle}${colors2.reset}`);
+    context.stdout(`${colors.bold}# ${displayTitle}${colors.reset}`);
     if (task.openingSentence) {
-      context.stdout(`${colors2.dim}${task.openingSentence}${colors2.reset}`);
+      context.stdout(`${colors.dim}${task.openingSentence}${colors.reset}`);
     }
-    context.stdout(`${colors2.cyan}→ ${task.path}${colors2.reset}`);
+    context.stdout(`${colors.cyan}→ ${task.path}${colors.reset}`);
     context.stdout("");
   }
   return { exitCode: 0 };
@@ -1693,9 +1861,10 @@ function formatEvent(event) {
       return `\uD83D\uDE34 No tasks available. Sleeping...
 `;
     case "loop.tasks_found":
-      return "✨ Found task(s). \uD83E\uDD16 Starting Claude...";
+      return `✨ Found a task. Going to work!
+`;
     case "claude.started":
-      return "\uD83E\uDD16 Claude session started";
+      return "\uD83E\uDD16 Starting Claude...";
     case "claude.ended":
       return event.success ? "\uD83E\uDD16 Claude session ended (success)" : `\uD83E\uDD16 Claude session ended (error: ${event.error})`;
     case "claude.raw_event":
@@ -1879,7 +2048,7 @@ async function loopClaude(dependencies, loopDependencies = createDefaultDependen
   const iterationOptions = {};
   if (eventsUrl) {
     iterationOptions.onRawEvent = (rawEvent) => {
-      if (rawEvent.type === "result" && typeof rawEvent.session_id === "string" && rawEvent.session_id) {
+      if (typeof rawEvent.session_id === "string" && rawEvent.session_id) {
         agentSessionId = rawEvent.session_id;
       }
       emit({ type: "claude.raw_event", rawEvent });
@@ -1916,30 +2085,6 @@ var newTask = createTemplateCommand("agent-new-task");
 var pickTask = createTemplateCommand("agent-pick-task");
 
 // lib/cli/commands/pre-push.ts
-import { spawn as spawn2 } from "node:child_process";
-function createGitRunner(spawnFn) {
-  return {
-    run: (gitArguments, cwd) => {
-      return new Promise((resolve2) => {
-        const proc = spawnFn("git", gitArguments, { cwd });
-        const chunks = [];
-        proc.stdout?.on("data", (data) => {
-          chunks.push(data.toString());
-        });
-        proc.stderr?.on("data", (data) => {
-          chunks.push(data.toString());
-        });
-        proc.on("close", (code) => {
-          resolve2({ exitCode: code ?? 1, output: chunks.join("") });
-        });
-        proc.on("error", (error) => {
-          resolve2({ exitCode: 1, output: error.message });
-        });
-      });
-    }
-  };
-}
-var defaultGitRunner = createGitRunner(spawn2);
 function parseGitDiffNameStatus(output) {
   const changes = [];
   const lines = output.trim().split(`

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@joshski/dust",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Flow state for AI coding agents",
   "type": "module",
   "bin": {
     "dust": "./dist/dust.js"
   },
+  "exports": {
+    "./artifacts": "./dist/artifacts.js"
+  },
   "files": [
     "dist",
     "bin",
@@ -24,7 +27,7 @@
   "author": "joshski",
   "license": "MIT",
   "scripts": {
-    "build": "bun build lib/cli/run.ts --target node --outfile dist/dust.js && printf '%s\\n%s' '#!/usr/bin/env node' \"$(cat dist/dust.js)\" > dist/dust.js && cp -r lib/templates templates",
+    "build": "bun build lib/cli/run.ts --target node --outfile dist/dust.js && printf '%s\\n%s' '#!/usr/bin/env node' \"$(cat dist/dust.js)\" > dist/dust.js && bun build lib/artifacts/idea-transition-task.ts --target browser --outfile dist/artifacts.js && cp -r lib/templates templates",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "eval": "bun run ./evals/run.ts"

package/templates/agent-greeting.txt

@@ -1,4 +1,10 @@
 🤖 Hello {{agentName}}, welcome to dust!
+{{#if agentInstructions}}
+
+## Project Instructions
+
+{{agentInstructions}}
+{{/if}}
 
 CRITICAL: You MUST run exactly ONE of the commands below before doing anything else.
 

package/templates/agent-new-idea.txt

@@ -6,6 +6,41 @@ Follow these steps:
 2. Create a new markdown file in `.dust/ideas/` with a descriptive kebab-case name (e.g., `improve-error-messages.md`)
 3. Add a title as the first line using an H1 heading (e.g., `# Improve error messages`)
 4. Write a brief description of the potential change or improvement
-5. Run `{{bin}} lint markdown` to catch any issues with the idea file format
-6. Create a single atomic commit with a message in the format "Add idea: <title>"
-7. Push your commit to the remote repository
+5. If the idea has open questions, add an `## Open Questions` section (see below)
+6. Run `{{bin}} lint markdown` to catch any issues with the idea file format
+7. Create a single atomic commit with a message in the format "Add idea: <title>"
+8. Push your commit to the remote repository
+
+### Open Questions section
+
+Ideas exist to eventually spawn tasks, so they start intentionally vague. An optional `## Open Questions` section captures the decisions that need to be made before the idea becomes actionable. Each question is an h3 heading ending with `?`, and each option is an h4 heading with markdown content explaining the trade-offs:
+
+```markdown
+## Open Questions
+
+### Should we take our own payments?
+
+#### Yes, take our own payments
+
+Lower costs and we become the seller of record, but requires a merchant account.
+
+#### No, use a payment provider
+
+Higher costs but simpler setup. No merchant account needed.
+
+### Which storage backend should we use?
+
+#### SQLite
+
+Simple and embedded. Good for single-node deployments.
+
+#### PostgreSQL
+
+Scalable but requires a separate server.
+```
+
+Rules:
+- Questions are `###` headings and must end with `?`
+- Options are `####` headings beneath a question
+- Each question must have at least one option
+- Options can contain any markdown content (paragraphs, lists, code blocks, etc.)

package/templates/agent-new-task.txt

@@ -17,7 +17,7 @@ Use a todo list to track your progress through these steps.
    - The goal is a task description with minimal ambiguity at implementation time
 4. Create a new markdown file in `.dust/tasks/` with a descriptive kebab-case name (e.g., `add-user-authentication.md`)
 5. Add a title as the first line using an H1 heading (e.g., `# Add user authentication`)
-6. Write a comprehensive description of what needs to be done with technical details and references to relevant files
+6. Write a comprehensive description starting with an imperative opening sentence (e.g., "Add caching to the API layer." not "This task adds caching."). Include technical details and references to relevant files.
 7. Add a `## Goals` section with links to relevant goals this task supports (e.g., `- [Goal Name](../goals/goal-name.md)`)
 8. Add a `## Blocked By` section listing any tasks that must complete first, or `(none)` if there are no blockers
 9. Add a `## Definition of Done` section with a checklist of completion criteria using `- [ ]` for each item

package/templates/help.txt

@@ -1,4 +1,4 @@
-💨 dust - A tool for keeping AI coding agents on track.
+💨 dust - Flow state for AI coding agents.
 
 Usage: {{bin}} <command> [options]
 

package/templates/templates/agent-greeting.txt

@@ -1,4 +1,10 @@
 🤖 Hello {{agentName}}, welcome to dust!
+{{#if agentInstructions}}
+
+## Project Instructions
+
+{{agentInstructions}}
+{{/if}}
 
 CRITICAL: You MUST run exactly ONE of the commands below before doing anything else.
 

package/templates/templates/agent-new-idea.txt

@@ -6,6 +6,41 @@ Follow these steps:
 2. Create a new markdown file in `.dust/ideas/` with a descriptive kebab-case name (e.g., `improve-error-messages.md`)
 3. Add a title as the first line using an H1 heading (e.g., `# Improve error messages`)
 4. Write a brief description of the potential change or improvement
-5. Run `{{bin}} lint markdown` to catch any issues with the idea file format
-6. Create a single atomic commit with a message in the format "Add idea: <title>"
-7. Push your commit to the remote repository
+5. If the idea has open questions, add an `## Open Questions` section (see below)
+6. Run `{{bin}} lint markdown` to catch any issues with the idea file format
+7. Create a single atomic commit with a message in the format "Add idea: <title>"
+8. Push your commit to the remote repository
+
+### Open Questions section
+
+Ideas exist to eventually spawn tasks, so they start intentionally vague. An optional `## Open Questions` section captures the decisions that need to be made before the idea becomes actionable. Each question is an h3 heading ending with `?`, and each option is an h4 heading with markdown content explaining the trade-offs:
+
+```markdown
+## Open Questions
+
+### Should we take our own payments?
+
+#### Yes, take our own payments
+
+Lower costs and we become the seller of record, but requires a merchant account.
+
+#### No, use a payment provider
+
+Higher costs but simpler setup. No merchant account needed.
+
+### Which storage backend should we use?
+
+#### SQLite
+
+Simple and embedded. Good for single-node deployments.
+
+#### PostgreSQL
+
+Scalable but requires a separate server.
+```
+
+Rules:
+- Questions are `###` headings and must end with `?`
+- Options are `####` headings beneath a question
+- Each question must have at least one option
+- Options can contain any markdown content (paragraphs, lists, code blocks, etc.)

package/templates/templates/agent-new-task.txt

@@ -17,7 +17,7 @@ Use a todo list to track your progress through these steps.
    - The goal is a task description with minimal ambiguity at implementation time
 4. Create a new markdown file in `.dust/tasks/` with a descriptive kebab-case name (e.g., `add-user-authentication.md`)
 5. Add a title as the first line using an H1 heading (e.g., `# Add user authentication`)
-6. Write a comprehensive description of what needs to be done with technical details and references to relevant files
+6. Write a comprehensive description starting with an imperative opening sentence (e.g., "Add caching to the API layer." not "This task adds caching."). Include technical details and references to relevant files.
 7. Add a `## Goals` section with links to relevant goals this task supports (e.g., `- [Goal Name](../goals/goal-name.md)`)
 8. Add a `## Blocked By` section listing any tasks that must complete first, or `(none)` if there are no blockers
 9. Add a `## Definition of Done` section with a checklist of completion criteria using `- [ ]` for each item

package/templates/templates/help.txt

@@ -1,4 +1,4 @@
-💨 dust - A tool for keeping AI coding agents on track.
+💨 dust - Flow state for AI coding agents.
 
 Usage: {{bin}} <command> [options]