@joshski/dust 0.1.36 → 0.1.38

package/dist/dust.js

@@ -693,22 +693,20 @@ function getLogLines(buffer) {
 import { join as join7 } from "node:path";
 
 // lib/agent-events.ts
-function mapToAgentEvent(event) {
+function rawEventToAgentEvent(rawEvent) {
+  if (typeof rawEvent.type === "string" && rawEvent.type === "stream_event") {
+    return { type: "agent-session-activity" };
+  }
+  return { type: "claude-event", rawEvent };
+}
+function formatAgentEvent(event) {
   switch (event.type) {
-    case "claude.started":
-      return { type: "agent-session-started" };
-    case "claude.ended":
-      return {
-        type: "agent-session-ended",
-        success: event.success,
-        error: event.error
-      };
-    case "claude.raw_event":
-      if (typeof event.rawEvent.type === "string" && event.rawEvent.type === "stream_event") {
-        return { type: "agent-session-activity" };
-      }
-      return { type: "claude-event", rawEvent: event.rawEvent };
-    default:
+    case "agent-session-started":
+      return `\uD83E\uDD16 Starting Claude: ${event.title}`;
+    case "agent-session-ended":
+      return event.success ? "\uD83E\uDD16 Claude session ended (success)" : `\uD83E\uDD16 Claude session ended (error: ${event.error})`;
+    case "agent-session-activity":
+    case "claude-event":
       return null;
   }
 }
@@ -1115,6 +1113,42 @@ async function run(prompt, options = {}, dependencies = defaultRunnerDependencie
 // lib/cli/commands/loop.ts
 import { spawn as nodeSpawn2 } from "node:child_process";
 
+// lib/cli/commands/focus.ts
+function buildImplementationInstructions(bin, hooksInstalled) {
+  const steps = [];
+  let step = 1;
+  steps.push(`${step}. Run \`${bin} check\` to verify the project is in a good state`);
+  step++;
+  steps.push(`${step}. Implement the task`);
+  step++;
+  if (!hooksInstalled) {
+    steps.push(`${step}. Run \`${bin} check\` before committing`);
+    step++;
+  }
+  steps.push(`${step}. Create a single atomic commit that includes:`, "   - All implementation changes", "   - Deletion of the completed task file", "   - Updates to any facts that changed", "   - Deletion of the idea file that spawned this task (if remaining scope exists, create new ideas for it)", "", '   Use the task title as the commit message. Task titles are written in imperative form, which is the recommended style for git commit messages. Do not add prefixes like "Complete task:" - use the title directly.', "", '   Example: If the task title is "Add validation for user input", the commit message should be:', "   ```", "   Add validation for user input", "   ```", "");
+  step++;
+  steps.push(`${step}. Push your commit to the remote repository`);
+  steps.push("");
+  steps.push("Keep your change small and focused. One task, one commit.");
+  return steps.join(`
+`);
+}
+async function focus(dependencies) {
+  const { context, settings } = dependencies;
+  const objective = dependencies.arguments.join(" ").trim();
+  if (!objective) {
+    context.stderr("Error: No objective provided");
+    context.stderr('Usage: dust focus "your objective here"');
+    return { exitCode: 1 };
+  }
+  const hooksInstalled = await manageGitHooks(dependencies);
+  const vars = templateVariables(settings, hooksInstalled);
+  context.stdout(`\uD83C\uDFAF Focus: ${objective}`);
+  context.stdout("");
+  context.stdout(buildImplementationInstructions(vars.bin, hooksInstalled));
+  return { exitCode: 0 };
+}
+
 // lib/cli/commands/next.ts
 function extractBlockedBy(content) {
   const blockedByMatch = content.match(/^## Blocked By\s*\n([\s\S]*?)(?=\n## |\n*$)/m);
@@ -1195,7 +1229,7 @@ async function next(dependencies) {
 }
 
 // lib/cli/commands/loop.ts
-function formatEvent(event) {
+function formatLoopEvent(event) {
   switch (event.type) {
     case "loop.warning":
       return "⚠️  WARNING: This command skips all permission checks. Only use in a sandbox environment!";
@@ -1213,16 +1247,12 @@ function formatEvent(event) {
     case "loop.tasks_found":
       return `✨ Found a task. Going to work!
 `;
-    case "claude.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":
-      return null;
     case "loop.iteration_complete":
       return `\uD83D\uDCCB Completed iteration ${event.iteration}/${event.maxIterations}`;
     case "loop.ended":
       return `\uD83C\uDFC1 Reached max iterations (${event.maxIterations}). Exiting.`;
+    case "loop.start_agent":
+      return null;
   }
 }
 async function defaultPostEvent(url, payload) {
@@ -1240,21 +1270,18 @@ function createDefaultDependencies() {
     postEvent: defaultPostEvent
   };
 }
-function createEventPoster(eventsUrl, sessionId, postEvent, onError, getAgentSessionId, repository = "") {
+function createWireEventSender(eventsUrl, sessionId, postEvent, onError, getAgentSessionId, repository = "") {
   let sequence = 0;
   return (event) => {
     if (!eventsUrl)
       return;
-    const agentEvent = mapToAgentEvent(event);
-    if (!agentEvent)
-      return;
     sequence++;
     const payload = {
       sequence,
       timestamp: new Date().toISOString(),
       sessionId,
       repository,
-      event: agentEvent
+      event
     };
     const agentSessionId = getAgentSessionId?.();
     if (agentSessionId) {
@@ -1287,29 +1314,26 @@ async function gitPull(cwd, spawn) {
     });
   });
 }
-async function hasAvailableTasks(dependencies) {
-  let hasOutput = false;
-  const captureContext = {
-    ...dependencies.context,
-    stdout: () => {
-      hasOutput = true;
-    }
-  };
-  await next({ ...dependencies, context: captureContext });
-  return hasOutput;
+async function findAvailableTasks(dependencies) {
+  const { context, fileSystem } = dependencies;
+  const result = await findUnblockedTasks(context.cwd, fileSystem);
+  return result.tasks;
 }
-async function runOneIteration(dependencies, loopDependencies, emit, options = {}) {
+async function runOneIteration(dependencies, loopDependencies, onLoopEvent, onAgentEvent, options = {}) {
   const { context } = dependencies;
   const { spawn, run: run2 } = loopDependencies;
   const { onRawEvent } = options;
-  emit({ type: "loop.syncing" });
+  onLoopEvent({ type: "loop.syncing" });
   const pullResult = await gitPull(context.cwd, spawn);
   if (!pullResult.success) {
-    emit({
+    onLoopEvent({
       type: "loop.sync_skipped",
-      reason: pullResult.message ?? "unknown error"
+      reason: pullResult.message
+    });
+    onAgentEvent?.({
+      type: "agent-session-started",
+      title: "Resolving git conflict"
     });
-    emit({ type: "claude.started" });
     const prompt2 = `git pull failed with the following error:
 
 ${pullResult.message}
@@ -1320,6 +1344,7 @@ Please resolve this issue. Common approaches:
 3. After resolving, commit any changes and push to remote
 
 Make sure the repository is in a clean state and synced with remote before finishing.`;
+    onLoopEvent({ type: "loop.start_agent", prompt: prompt2 });
     try {
       await run2(prompt2, {
         spawnOptions: {
@@ -1329,24 +1354,47 @@ Make sure the repository is in a clean state and synced with remote before finis
         },
         onRawEvent
       });
-      emit({ type: "claude.ended", success: true });
+      onAgentEvent?.({ type: "agent-session-ended", success: true });
       return "resolved_pull_conflict";
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       context.stderr(`Claude failed to resolve git pull conflict: ${errorMessage}`);
-      emit({ type: "claude.ended", success: false, error: errorMessage });
+      onAgentEvent?.({
+        type: "agent-session-ended",
+        success: false,
+        error: errorMessage
+      });
     }
   }
-  emit({ type: "loop.checking_tasks" });
-  const hasTasks = await hasAvailableTasks(dependencies);
-  if (!hasTasks) {
-    emit({ type: "loop.no_tasks" });
+  onLoopEvent({ type: "loop.checking_tasks" });
+  const tasks = await findAvailableTasks(dependencies);
+  if (tasks.length === 0) {
+    onLoopEvent({ type: "loop.no_tasks" });
     return "no_tasks";
   }
-  emit({ type: "loop.tasks_found" });
-  emit({ type: "claude.started" });
+  const task = tasks[0];
+  onLoopEvent({ type: "loop.tasks_found" });
+  onAgentEvent?.({
+    type: "agent-session-started",
+    title: task.title ?? task.path
+  });
+  const taskContent = await dependencies.fileSystem.readFile(`${dependencies.context.cwd}/${task.path}`);
   const { dustCommand, installCommand = "npm install" } = dependencies.settings;
-  const prompt = `Run \`${installCommand} && ${dustCommand} agent && ${dustCommand} pick task\` and follow the instructions.`;
+  const instructions = buildImplementationInstructions(dustCommand, true);
+  const prompt = `Run \`${installCommand}\` to install dependencies, then implement the following task.
+
+## Task: ${task.title}
+
+The following is the contents of the task file \`${task.path}\`:
+
+${taskContent}
+
+When the task is complete, delete the task file \`${task.path}\`.
+
+## Instructions
+
+${instructions}`;
+  onLoopEvent({ type: "loop.start_agent", prompt });
   try {
     await run2(prompt, {
       spawnOptions: {
@@ -1356,12 +1404,16 @@ Make sure the repository is in a clean state and synced with remote before finis
       },
       onRawEvent
     });
-    emit({ type: "claude.ended", success: true });
+    onAgentEvent?.({ type: "agent-session-ended", success: true });
     return "ran_claude";
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : String(error);
     context.stderr(`Claude exited with error: ${errorMessage}`);
-    emit({ type: "claude.ended", success: false, error: errorMessage });
+    onAgentEvent?.({
+      type: "agent-session-ended",
+      success: false,
+      error: errorMessage
+    });
     return "claude_error";
   }
 }
@@ -1382,46 +1434,49 @@ async function loopClaude(dependencies, loopDependencies = createDefaultDependen
   const eventsUrl = settings.eventsUrl;
   const sessionId = crypto.randomUUID();
   let agentSessionId;
-  const postEventFn = createEventPoster(eventsUrl, sessionId, postEvent, (error) => {
+  const sendWireEvent = createWireEventSender(eventsUrl, sessionId, postEvent, (error) => {
     const message = error instanceof Error ? error.message : String(error);
     context.stderr(`Event POST failed: ${message}`);
   }, () => agentSessionId);
-  const emit = (event) => {
-    const formatted = formatEvent(event);
+  const onLoopEvent = (event) => {
+    const formatted = formatLoopEvent(event);
     if (formatted !== null) {
       context.stdout(formatted);
     }
-    postEventFn(event);
   };
-  emit({ type: "loop.warning" });
-  emit({ type: "loop.started", maxIterations });
+  const onAgentEvent = (event) => {
+    const formatted = formatAgentEvent(event);
+    if (formatted !== null) {
+      context.stdout(formatted);
+    }
+    sendWireEvent(event);
+  };
+  onLoopEvent({ type: "loop.warning" });
+  onLoopEvent({ type: "loop.started", maxIterations });
   context.stdout("   Press Ctrl+C to stop");
   context.stdout("");
   let completedIterations = 0;
   const iterationOptions = {};
   if (eventsUrl) {
     iterationOptions.onRawEvent = (rawEvent) => {
-      if (typeof rawEvent.session_id === "string" && rawEvent.session_id) {
-        agentSessionId = rawEvent.session_id;
-      }
-      emit({ type: "claude.raw_event", rawEvent });
+      onAgentEvent(rawEventToAgentEvent(rawEvent));
     };
   }
   while (completedIterations < maxIterations) {
-    agentSessionId = undefined;
-    const result = await runOneIteration(dependencies, loopDependencies, emit, iterationOptions);
+    agentSessionId = crypto.randomUUID();
+    const result = await runOneIteration(dependencies, loopDependencies, onLoopEvent, onAgentEvent, iterationOptions);
     if (result === "no_tasks") {
       await loopDependencies.sleep(SLEEP_INTERVAL_MS);
     } else {
       completedIterations++;
-      emit({
+      onLoopEvent({
         type: "loop.iteration_complete",
         iteration: completedIterations,
         maxIterations
       });
     }
   }
-  emit({ type: "loop.ended", maxIterations });
+  onLoopEvent({ type: "loop.ended", maxIterations });
   return { exitCode: 0 };
 }
 
@@ -1534,20 +1589,30 @@ async function runRepositoryLoop(repoState, repoDeps, sendEvent, sessionId) {
   };
   let agentSessionId;
   let sequence = 0;
-  const loopEmit = (event) => {
-    const formatted = formatEvent(event);
+  const onLoopEvent = (event) => {
+    const formatted = formatLoopEvent(event);
     if (formatted !== null) {
       appendLogLine(repoState.logBuffer, createLogLine(formatted, "stdout"));
     }
-    const agentEvent = mapToAgentEvent(event);
-    if (agentEvent && sendEvent && sessionId) {
+  };
+  const onAgentEvent = (event) => {
+    if (event.type === "agent-session-started") {
+      repoState.agentStatus = "busy";
+    } else if (event.type === "agent-session-ended") {
+      repoState.agentStatus = "idle";
+    }
+    const formatted = formatAgentEvent(event);
+    if (formatted !== null) {
+      appendLogLine(repoState.logBuffer, createLogLine(formatted, "stdout"));
+    }
+    if (sendEvent && sessionId) {
       sequence++;
       const msg = {
         sequence,
         timestamp: new Date().toISOString(),
         sessionId,
         repository: repoName,
-        event: agentEvent
+        event
       };
       if (agentSessionId) {
         msg.agentSessionId = agentSessionId;
@@ -1556,13 +1621,10 @@ async function runRepositoryLoop(repoState, repoDeps, sendEvent, sessionId) {
     }
   };
   while (!repoState.stopRequested) {
-    agentSessionId = undefined;
-    const result = await runOneIteration(commandDeps, loopDeps, loopEmit, {
+    agentSessionId = crypto.randomUUID();
+    const result = await runOneIteration(commandDeps, loopDeps, onLoopEvent, onAgentEvent, {
       onRawEvent: (rawEvent) => {
-        if (typeof rawEvent.session_id === "string" && rawEvent.session_id) {
-          agentSessionId = rawEvent.session_id;
-        }
-        loopEmit({ type: "claude.raw_event", rawEvent });
+        onAgentEvent(rawEventToAgentEvent(rawEvent));
       }
     });
     if (result === "no_tasks") {
@@ -1596,7 +1658,8 @@ async function addRepository(repository, manager, repoDeps, context) {
     path: repoPath,
     loopPromise: null,
     stopRequested: false,
-    logBuffer: manager.logBuffers.get(repository.name) ?? createLogBuffer()
+    logBuffer: manager.logBuffers.get(repository.name) ?? createLogBuffer(),
+    agentStatus: "idle"
   };
   manager.repositories.set(repository.name, repoState);
   const addedEvent = {
@@ -1726,6 +1789,7 @@ function createTerminalUIState() {
     repositories: [],
     selectedIndex: -1,
     logBuffers: new Map,
+    agentStatuses: new Map,
     scrollOffset: 0,
     autoScroll: true,
     width: 80,
@@ -1747,6 +1811,7 @@ function addRepository2(state, name, logBuffer) {
         return -1;
       return a.localeCompare(b);
     });
+    state.agentStatuses.set(name, "idle");
   }
   state.logBuffers.set(name, logBuffer);
 }
@@ -1755,6 +1820,7 @@ function removeRepository2(state, name) {
   if (index >= 0) {
     state.repositories.splice(index, 1);
     state.logBuffers.delete(name);
+    state.agentStatuses.delete(name);
     if (state.selectedIndex >= state.repositories.length) {
       state.selectedIndex = state.repositories.length - 1;
     }
@@ -1805,7 +1871,7 @@ function getTabRowCount(state) {
     return 1;
   const tabWidths = [5];
   for (const name of state.repositories) {
-    tabWidths.push(name.length + 2);
+    tabWidths.push(name.length + 4);
   }
   let rows = 1;
   let currentRowWidth = 0;
@@ -1873,14 +1939,17 @@ function renderTabs(state) {
   for (let i = 0;i < state.repositories.length; i++) {
     const name = state.repositories[i];
     const color = getRepoColor(name, i);
-    const width = name.length + 2;
+    const agentStatus = state.agentStatuses.get(name) ?? "idle";
+    const dotColor = agentStatus === "busy" ? ANSI.FG_GREEN : ANSI.DIM;
+    const dot = `${dotColor}●${ANSI.RESET}`;
+    const width = name.length + 4;
     if (i === state.selectedIndex) {
       tabs.push({
-        text: `${ANSI.INVERSE}${color} ${name} ${ANSI.RESET}`,
+        text: `${ANSI.INVERSE} ${dot}${ANSI.INVERSE}${color} ${name} ${ANSI.RESET}`,
         width
       });
     } else {
-      tabs.push({ text: `${color} ${name} ${ANSI.RESET}`, width });
+      tabs.push({ text: ` ${dot}${color} ${name} ${ANSI.RESET}`, width });
     }
   }
   const rows = [[]];
@@ -2207,12 +2276,18 @@ function syncUIWithRepoList(state, repos) {
     }
   }
 }
+function syncAgentStatuses(state) {
+  for (const [name, repoState] of state.repositories) {
+    state.ui.agentStatuses.set(name, repoState.agentStatus);
+  }
+}
 function syncTUI(state) {
   const currentUIRepos = new Set(state.ui.repositories);
   const currentRepos = new Set(state.repositories.keys());
   for (const [name, repoState] of state.repositories) {
     state.logBuffers.set(name, repoState.logBuffer);
     addRepository2(state.ui, name, repoState.logBuffer);
+    state.ui.agentStatuses.set(name, repoState.agentStatus);
   }
   for (const name of currentUIRepos) {
     if (name !== "system" && !currentRepos.has(name)) {
@@ -2342,6 +2417,7 @@ function setupTUI(state, bucketDeps) {
   });
   const renderInterval = setInterval(() => {
     if (!state.shuttingDown) {
+      syncAgentStatuses(state);
       bucketDeps.writeStdout(renderFrame(state.ui));
     }
   }, 100);
@@ -3260,39 +3336,6 @@ async function check(dependencies, shellRunner = defaultShellRunner) {
   return { exitCode };
 }
 
-// lib/cli/commands/focus.ts
-async function focus(dependencies) {
-  const { context, settings } = dependencies;
-  const objective = dependencies.arguments.join(" ").trim();
-  if (!objective) {
-    context.stderr("Error: No objective provided");
-    context.stderr('Usage: dust focus "your objective here"');
-    return { exitCode: 1 };
-  }
-  const hooksInstalled = await manageGitHooks(dependencies);
-  const vars = templateVariables(settings, hooksInstalled);
-  context.stdout(`\uD83C\uDFAF Focus: ${objective}`);
-  context.stdout("");
-  const steps = [];
-  let step = 1;
-  steps.push(`${step}. Run \`${vars.bin} check\` to verify the project is in a good state`);
-  step++;
-  steps.push(`${step}. Implement the task`);
-  step++;
-  if (!hooksInstalled) {
-    steps.push(`${step}. Run \`${vars.bin} check\` before committing`);
-    step++;
-  }
-  steps.push(`${step}. Create a single atomic commit that includes:`, "   - All implementation changes", "   - Deletion of the completed task file", "   - Updates to any facts that changed", "   - Deletion of the idea file that spawned this task (if remaining scope exists, create new ideas for it)", "", '   Use the task title as the commit message. Task titles are written in imperative form, which is the recommended style for git commit messages. Do not add prefixes like "Complete task:" - use the title directly.', "", '   Example: If the task title is "Add validation for user input", the commit message should be:', "   ```", "   Add validation for user input", "   ```", "");
-  step++;
-  steps.push(`${step}. Push your commit to the remote repository`);
-  steps.push("");
-  steps.push("Keep your change small and focused. One task, one commit.");
-  context.stdout(steps.join(`
-`));
-  return { exitCode: 0 };
-}
-
 // lib/cli/commands/help.ts
 function generateHelpText(settings) {
   return loadTemplate("help", { bin: settings.dustCommand });

package/dist/workflow-tasks.d.ts

@@ -1,6 +1,7 @@
 import type { FileSystem } from './cli/types';
 export declare const IDEA_TRANSITION_PREFIXES: string[];
 export declare const CAPTURE_IDEA_PREFIX = "Add Idea: ";
+export declare const BUILD_IDEA_PREFIX = "Build Idea: ";
 export interface IdeaInProgress {
     taskSlug: string;
     ideaTitle: string;
@@ -8,6 +9,7 @@ export interface IdeaInProgress {
 export interface ParsedCaptureIdeaTask {
     ideaTitle: string;
     ideaDescription: string;
+    buildItNow: boolean;
 }
 export declare function findAllCaptureIdeaTasks(fileSystem: FileSystem, dustPath: string): Promise<IdeaInProgress[]>;
 /**
@@ -42,5 +44,9 @@ export interface DecomposeIdeaOptions {
 export declare function createRefineIdeaTask(fileSystem: FileSystem, dustPath: string, ideaSlug: string, description?: string): Promise<CreateIdeaTransitionTaskResult>;
 export declare function decomposeIdea(fileSystem: FileSystem, dustPath: string, options: DecomposeIdeaOptions): Promise<CreateIdeaTransitionTaskResult>;
 export declare function createShelveIdeaTask(fileSystem: FileSystem, dustPath: string, ideaSlug: string, description?: string): Promise<CreateIdeaTransitionTaskResult>;
-export declare function createCaptureIdeaTask(fileSystem: FileSystem, dustPath: string, title: string, description: string): Promise<CreateIdeaTransitionTaskResult>;
+export declare function createCaptureIdeaTask(fileSystem: FileSystem, dustPath: string, options: {
+    title: string;
+    description: string;
+    buildItNow?: boolean;
+}): Promise<CreateIdeaTransitionTaskResult>;
 export declare function parseCaptureIdeaTask(fileSystem: FileSystem, dustPath: string, taskSlug: string): Promise<ParsedCaptureIdeaTask | null>;

package/dist/workflow-tasks.js

@@ -5,6 +5,7 @@ var IDEA_TRANSITION_PREFIXES = [
   "Shelve Idea: "
 ];
 var CAPTURE_IDEA_PREFIX = "Add Idea: ";
+var BUILD_IDEA_PREFIX = "Build Idea: ";
 async function findAllCaptureIdeaTasks(fileSystem, dustPath) {
   const tasksPath = `${dustPath}/tasks`;
   if (!fileSystem.exists(tasksPath))
@@ -22,6 +23,11 @@ async function findAllCaptureIdeaTasks(fileSystem, dustPath) {
         taskSlug: file.replace(/\.md$/, ""),
         ideaTitle: title.slice(CAPTURE_IDEA_PREFIX.length)
       });
+    } else if (title.startsWith(BUILD_IDEA_PREFIX)) {
+      results.push({
+        taskSlug: file.replace(/\.md$/, ""),
+        ideaTitle: title.slice(BUILD_IDEA_PREFIX.length)
+      });
     }
   }
   return results;
@@ -112,7 +118,7 @@ async function createRefineIdeaTask(fileSystem, dustPath, ideaSlug, description)
   ], { description });
 }
 async function decomposeIdea(fileSystem, dustPath, options) {
-  return createIdeaTask(fileSystem, dustPath, "Decompose Idea: ", options.ideaSlug, (ideaTitle) => `Create one or more well-defined tasks from this idea. Prefer smaller, narrowly scoped tasks -- split the idea into multiple tasks if it covers more than one logical change. Review \`.dust/goals/\` to link relevant goals and \`.dust/facts/\` for design decisions that should inform the task. See [${ideaTitle}](../ideas/${options.ideaSlug}.md).`, [
+  return createIdeaTask(fileSystem, dustPath, "Decompose Idea: ", options.ideaSlug, (ideaTitle) => `Create one or more well-defined tasks from this idea. Prefer smaller, narrowly scoped tasks that each deliver a thin but complete vertical slice of working software -- a path through the system that can be tested end-to-end -- rather than component-oriented tasks (like "add schema" or "build endpoint") that only work once all tasks are done. Split the idea into multiple tasks if it covers more than one logical change. Review \`.dust/goals/\` to link relevant goals and \`.dust/facts/\` for design decisions that should inform the task. See [${ideaTitle}](../ideas/${options.ideaSlug}.md).`, [
     "One or more new tasks are created in .dust/tasks/",
     "Task's Goals section links to relevant goals from .dust/goals/",
     "The original idea is deleted or updated to reflect remaining scope"
@@ -124,14 +130,44 @@ async function decomposeIdea(fileSystem, dustPath, options) {
 async function createShelveIdeaTask(fileSystem, dustPath, ideaSlug, description) {
   return createIdeaTask(fileSystem, dustPath, "Shelve Idea: ", ideaSlug, (ideaTitle) => `Archive this idea and remove it from the active backlog. See [${ideaTitle}](../ideas/${ideaSlug}.md).`, ["Idea file is deleted", "Rationale is recorded in the commit message"], { description });
 }
-async function createCaptureIdeaTask(fileSystem, dustPath, title, description) {
+async function createCaptureIdeaTask(fileSystem, dustPath, options) {
+  const { title, description, buildItNow } = options;
   if (!title || !title.trim()) {
     throw new Error("title is required and must not be whitespace-only");
   }
   if (!description || !description.trim()) {
     throw new Error("description is required and must not be whitespace-only");
   }
-  const taskTitle = `Add Idea: ${title}`;
+  if (buildItNow) {
+    const taskTitle2 = `${BUILD_IDEA_PREFIX}${title}`;
+    const filename2 = titleToFilename(taskTitle2);
+    const filePath2 = `${dustPath}/tasks/${filename2}`;
+    const content2 = `# ${taskTitle2}
+
+Research this idea thoroughly, review \`.dust/goals/\` and \`.dust/facts/\` for relevant context, then create one or more narrowly-scoped task files in \`.dust/tasks/\`. Each task should deliver a thin but complete vertical slice of working software.
+
+## Idea Description
+
+${description}
+
+## Goals
+
+(none)
+
+## Blocked By
+
+(none)
+
+## Definition of Done
+
+- [ ] One or more new tasks are created in \`.dust/tasks/\`
+- [ ] Tasks link to relevant goals from \`.dust/goals/\`
+- [ ] Tasks are narrowly scoped vertical slices
+`;
+    await fileSystem.writeFile(filePath2, content2);
+    return { filePath: filePath2 };
+  }
+  const taskTitle = `${CAPTURE_IDEA_PREFIX}${title}`;
   const filename = titleToFilename(taskTitle);
   const filePath = `${dustPath}/tasks/${filename}`;
   const ideaFilename = titleToFilename(title);
@@ -173,16 +209,23 @@ async function parseCaptureIdeaTask(fileSystem, dustPath, taskSlug) {
     return null;
   }
   const title = titleMatch[1].trim();
-  if (!title.startsWith(CAPTURE_IDEA_PREFIX)) {
+  let ideaTitle;
+  let buildItNow;
+  if (title.startsWith(BUILD_IDEA_PREFIX)) {
+    ideaTitle = title.slice(BUILD_IDEA_PREFIX.length);
+    buildItNow = true;
+  } else if (title.startsWith(CAPTURE_IDEA_PREFIX)) {
+    ideaTitle = title.slice(CAPTURE_IDEA_PREFIX.length);
+    buildItNow = false;
+  } else {
     return null;
   }
-  const ideaTitle = title.slice(CAPTURE_IDEA_PREFIX.length);
   const descriptionMatch = content.match(/^## Idea Description\n\n([\s\S]*?)\n\n## /m);
   if (!descriptionMatch) {
     return null;
   }
   const ideaDescription = descriptionMatch[1];
-  return { ideaTitle, ideaDescription };
+  return { ideaTitle, ideaDescription, buildItNow };
 }
 export {
   titleToFilename,
@@ -194,5 +237,6 @@ export {
   createRefineIdeaTask,
   createCaptureIdeaTask,
   IDEA_TRANSITION_PREFIXES,
-  CAPTURE_IDEA_PREFIX
+  CAPTURE_IDEA_PREFIX,
+  BUILD_IDEA_PREFIX
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joshski/dust",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "Flow state for AI coding agents",
   "type": "module",
   "bin": {

package/templates/agent-new-task.txt

@@ -18,6 +18,7 @@ Use a todo list to track your progress through these steps.
 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 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.
+   - Scope the task as a **vertical slice**: a thin but complete path through the system that can be tested and built upon, rather than an isolated component or layer.
 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/agent-greeting.txt

@@ -1,31 +0,0 @@
-🤖 Hello {{agentName}}, welcome to dust!
-
-CRITICAL: You MUST run exactly ONE of the commands below before doing anything else.
-
-Determine the user's intent and run the matching command NOW:
-
-1. **Pick up work from the backlog** → `{{bin}} pick task`
-   User wants to start working. Examples: "work", "go", "pick a task", "what's next?"
-
-2. **Implement a specific task** → `{{bin}} focus "<task name>"`
-   User mentions a particular task by name. Examples: "implement the auth task", "work on caching"
-
-3. **Capture a new task** → `{{bin}} new task`
-   User has concrete work to add. Keywords: "task: ..." or "add a task ..."
-
-4. **Capture a new goal** → `{{bin}} new goal`
-   User has a higher-level objective to add. Keywords: "goal: ..." or "add a goal ..."
-
-5. **Capture a vague idea** → `{{bin}} new idea`
-   User has a rough idea that might become work later. Keywords: "idea: ..." or "add an idea ..."
-
-6. **Unclear** → `{{bin}} help`
-   If none of the above clearly apply, run this to see all available commands.
-
-Do NOT proceed without running one of these commands.
-{{#if agentInstructions}}
-
----
-
-{{agentInstructions}}
-{{/if}}

package/templates/agent-implement-task.txt

@@ -1,26 +0,0 @@
-## Implement a Task
-
-{{#if isClaudeCodeWeb}}Follow these steps. Use a todo list to track your progress.
-{{/if}}{{#unless isClaudeCodeWeb}}Follow these steps:
-{{/unless}}
-1. Run `{{bin}} next` to identify the (unblocked) task the user is referring to
-2. Run `{{bin}} focus "<task name>"` (so everyone knows you're working on it)
-3. Run `{{bin}} check` to verify the project is in a good state
-4. Implement the task
-{{#unless hooksInstalled}}5. Run `{{bin}} check` before committing
-6.{{/unless}}{{#if hooksInstalled}}5.{{/if}} Create a single atomic commit that includes:
-   - All implementation changes
-   - Deletion of the completed task file
-   - Updates to any facts that changed
-   - Deletion of the idea file that spawned this task (if remaining scope exists, create new ideas for it)
-
-   Use the task title as the commit message. Task titles are written in imperative form, which is the recommended style for git commit messages. Do not add prefixes like "Complete task:" - use the title directly.
-
-   Example: If the task title is "Add validation for user input", the commit message should be:
-   ```
-   Add validation for user input
-   ```
-
-{{#unless hooksInstalled}}7.{{/unless}}{{#if hooksInstalled}}6.{{/if}} Push your commit to the remote repository
-
-Keep your change small and focused. One task, one commit.

package/templates/agent-new-goal.txt

@@ -1,22 +0,0 @@
-## Adding a New Goal
-
-Goals are guiding principles that persist across tasks. They define the "why" behind the work.
-
-{{#if isClaudeCodeWeb}}Follow these steps. Use a todo list to track your progress.
-{{/if}}{{#unless isClaudeCodeWeb}}Follow these steps:
-{{/unless}}
-1. Run `{{bin}} goals` to see existing goals and avoid duplication
-2. Create a new markdown file in `.dust/goals/` with a descriptive kebab-case name (e.g., `cross-platform-support.md`)
-3. Add a title as the first line using an H1 heading (e.g., `# Cross-platform support`)
-4. Write a clear description explaining:
-   - What this goal means in practice
-   - Why it matters for the project
-   - How to evaluate whether work supports this goal
-5. Run `{{bin}} lint markdown` to catch any formatting issues
-6. Create a single atomic commit with a message in the format "Add goal: <title>"
-7. Push your commit to the remote repository
-
-Goals should be:
-- **Stable** - They rarely change once established
-- **Actionable** - Tasks can be linked to them
-- **Clear** - Anyone reading should understand what it means

package/templates/agent-new-idea.txt

@@ -1,46 +0,0 @@
-## Adding a New Idea
-
-Follow these steps:
-
-1. Run `{{bin}} ideas` to see all existing ideas and avoid duplicates
-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. 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-pick-task.txt

@@ -1,7 +0,0 @@
-## Pick a Task
-
-Follow these steps:
-
-1. Run `{{bin}} next` to see available tasks
-2. Pick ONE task and read its file to understand the requirements
-3. Run `{{bin}} implement task` for instructions about how to implement

package/templates/agents-md.txt

@@ -1,5 +0,0 @@
-# Agent Instructions
-
-This project uses [dust](https://github.com/joshski/dust) for planning and documentation.
-
-Always immediately run `{{dustCommand}} agent` when you start working in this repository.

package/templates/audits/dead-code.md

@@ -1,30 +0,0 @@
-# Dead Code
-
-Find and remove unused code to improve maintainability and reduce bundle size.
-
-## Scope
-
-Focus on these areas:
-
-1. **Unused exports** - Functions, classes, constants that are never imported
-2. **Unreachable code** - Code after return statements, impossible conditions
-3. **Orphaned files** - Files that are not imported anywhere
-4. **Unused dependencies** - Packages in package.json not used in code
-5. **Commented-out code** - Old code left in comments
-
-## Goals
-
-(none)
-
-## Blocked By
-
-(none)
-
-## Definition of Done
-
-- [ ] Ran static analysis tools to find unused exports
-- [ ] Identified files with no incoming imports
-- [ ] Listed unused dependencies
-- [ ] Reviewed commented-out code blocks
-- [ ] Created list of code safe to remove
-- [ ] Verified removal won't break dynamic imports or reflection

package/templates/audits/security-review.md

@@ -1,30 +0,0 @@
-# Security Review
-
-Review the codebase for common security vulnerabilities and misconfigurations.
-
-## Scope
-
-Focus on these areas:
-
-1. **Hardcoded secrets** - API keys, passwords, tokens in source code
-2. **Injection vulnerabilities** - SQL injection, command injection, XSS
-3. **Authentication issues** - Weak password handling, missing auth checks
-4. **Sensitive data exposure** - Logging sensitive data, insecure storage
-5. **Dependency vulnerabilities** - Known CVEs in dependencies
-
-## Goals
-
-(none)
-
-## Blocked By
-
-(none)
-
-## Definition of Done
-
-- [ ] Searched for hardcoded secrets (API keys, passwords, tokens)
-- [ ] Reviewed input validation and sanitization
-- [ ] Checked authentication and authorization logic
-- [ ] Verified sensitive data is not logged or exposed
-- [ ] Ran dependency audit for known vulnerabilities
-- [ ] Documented any findings with severity ratings

package/templates/audits/test-coverage.md

@@ -1,29 +0,0 @@
-# Test Coverage
-
-Identify untested code paths and areas that need additional test coverage.
-
-## Scope
-
-Focus on these areas:
-
-1. **Core business logic** - Functions that handle critical operations
-2. **Edge cases** - Boundary conditions, error handling paths
-3. **Integration points** - API endpoints, database operations
-4. **User-facing features** - UI components, form validation
-5. **Recent changes** - Code modified in the last few commits
-
-## Goals
-
-(none)
-
-## Blocked By
-
-(none)
-
-## Definition of Done
-
-- [ ] Identified modules with low or no test coverage
-- [ ] Listed critical paths that lack tests
-- [ ] Prioritized areas by risk and importance
-- [ ] Created list of specific test cases to add
-- [ ] Estimated effort for improving coverage

package/templates/claude-md.txt

@@ -1,5 +0,0 @@
-# Claude Code Instructions
-
-This project uses [dust](https://github.com/joshski/dust) for planning and documentation.
-
-Always immediately run `{{dustCommand}} agent` when you start working in this repository.

package/templates/help.txt

@@ -1,36 +0,0 @@
-💨 dust - Flow state for AI coding agents.
-
-Usage: {{bin}} <command> [options]
-
-Commands:
-  init              Initialize a new Dust repository
-  lint markdown     Run lint checks on .dust/ files
-  list              List all items (tasks, ideas, goals, facts)
-  tasks             List tasks (actionable work with definitions of done)
-  ideas             List ideas (vague proposals, convert to tasks when ready)
-  goals             List goals (guiding principles, stable, rarely change)
-  facts             List facts (documentation of current system state)
-  next              Show tasks ready to work on (not blocked)
-  check             Run project-defined quality gate hook
-  agent             Agent greeting and routing instructions
-  focus             Declare current objective (for remote session tracking)
-  pick task         Pick the next task to work on
-  implement task    Implement a task
-  new task          Create a new task
-  new goal          Create a new goal
-  new idea          Create a new idea
-  loop claude       Run continuous Claude iteration on tasks
-  pre push          Git pre-push hook validation
-  help              Show this help message
-
-🤖 Agent Guide
-
-Dust is a lightweight planning system. The .dust/ directory contains:
-- goals/  - Guiding principles (stable, rarely change)
-- ideas/  - Proposals (convert to tasks when ready)
-- tasks/  - Actionable work with definitions of done
-- facts/  - Documentation of current system state
-
-Workflow: Pick a task → implement it → delete the task file → commit atomically.
-
-Run `{{bin}} agent` to get started!