@joshski/dust 0.1.5 → 0.1.7

package/README.md

@@ -4,104 +4,38 @@ A lightweight planning system and work tracker optimised for humans working with
 
 [![CI](https://github.com/joshski/dust/actions/workflows/ci.yml/badge.svg)](https://github.com/joshski/dust/actions/workflows/ci.yml)
 
-## Usage
+## Getting Started
 
-Document your system and any future plans in a [.dust](./.dust) directory in your repository:
+Install dust:
 
+```bash
+npm install -g @joshski/dust
 ```
-.dust/
-├── goals/    # Mission statements explaining why the project exists
-├── ideas/    # Brief notes about future tasks (intentionally vague)
-├── tasks/    # Detailed work plans with dependencies and definition of done
-├── facts/    # Current state: design, architecture, rules, invariants
-└── hooks/    # Executable scripts for CLI integration (e.g., quality gates)
-```
-
-The `goals`, `ideas`, `tasks`, and `facts` directories should be flat (no subdirectories) and contain only markdown files with slug-style names (alphanumeric and hyphens only).
-
-The `hooks` directory contains executable scripts that integrate with the `dust` CLI. For example, the `check` hook is run by `dust check` to execute project-defined quality gates.
-
-## CLI Commands
 
-The `dust` CLI provides commands for managing your planning repository:
-
-| Command | Description |
-|---------|-------------|
-| `dust init` | Initialize a new Dust repository with the standard directory structure |
-| `dust prompt <name>` | Output a prompt by name from the `prompts/` directory |
-| `dust validate` | Run validation checks on `.dust/` files (links, task structure, naming) |
-| `dust list [type]` | List items by type (tasks, ideas, goals, facts) or all if no type specified |
-| `dust next` | Show tasks ready to work on (not blocked by other incomplete tasks) |
-| `dust check` | Run `validate` then execute the project's quality gate hook at `.dust/hooks/check` |
-| `dust help` | Show help message with all available commands |
-
-### Examples
+Initialize dust in your repository:
 
 ```bash
-# Initialize a new project
-dust init
-
-# List all tasks
-dust list tasks
-
-# List everything (tasks, ideas, goals, facts)
-dust list
-
-# Show tasks that are ready to start
-dust next
-
-# Validate all markdown files under ./.dust
-dust validate
-
-# Run quality checks (validation + custom hook)
-dust check
-
-# Output a prompt by name
-dust prompt work
+npx dust init
+# or
+bunx dust init
 ```
 
-## Workflow
-
-Dust is designed for successive cycles of human planning (AI-assisted, of course) followed by agent autonomy, followed by human planning, and so on.
-
-In order for work to begin, there must be a task. A worker (an AI agent or human) chooses any task to work on. In a team environment, the worker must “claim” the task i.e. let the team know they are working on it. The team can use a version control system (like git) claim the task by making a branch with the same name as the task. If any attempt to claim fails (e.g. a branch with that name already exists) then the agent must choose an alternative task.
-
-When the worker completes their task, they make a single commit that includes the work, but also deletes the task, and removes any references to the task. The commit should often update one or more facts as well.
-
-Tasks should be small units of work that can be completed quickly and result in a single commit that leaves the system in a reasonable state (e.g. no broken or half-implemented features exposed to end users). When in doubt, workers are encouraged to split the task into smaller sub-tasks, and abandon the attempt to finish any ambitious work in one go.
-
-Over time, new ideas emerge, and ideas become more detailed plans in the form of "tasks". This should be deferred until the last responsible moment. Since humans like control over plans, ideas become plans in the "human-in-the-loop" phase at the start of a sprint.
+## How It Works
 
-## Tasks
-
-Tasks are the only markdown files that have a strict structure. Tasks must have each of the following subheadings:
+The [.dust](./.dust) directory in your repository contains 4 sets of markdown files:
 
 ```
-## Goals
-## Blocked by
-## Definition of done
+.dust/
+├── goals/    # Mission statements explaining why the project exists
+├── ideas/    # Brief notes about future tasks (intentionally vague)
+├── tasks/    # Detailed work plans with dependencies and definition of done
+└── facts/    # Current state: design, architecture, rules, invariants
 ```
 
-* Goals - a list of relative links to other markdown files, always under ./.dust/goals
-* Blocked by - a list relative links to other markdown files, each of which nominates a task that must be implemented before this task can be started.
-* Definition of done - A short description of how the implementor of the task can decide when the task has been completed successfully
-
-These special headings and sections are required, but the remainder of the document is free form.
-
-## The single commit
-
-Each task should be a small unit of work. If it was underestimated, the agent implementing the task should commit any progress that does not have a negative impact on end users, and create another "follow up" task to complete the remainder of the work.
-
-## Links between documents
+These files are used to facilitate exploration and management of AI agent workflow.
 
-Documents should include links to all relevant related documents, regardless of the type. These should be relative links in markdown format. The link text should typically match the title of the target document.
-
-## Change history
-
-Commits delete tasks, but commit history can be traversed to retrieve the thinking behind any changes. Tools can be implemented to make this easier or build indexes. The current working copy is kept intentionally free of this detail, to keep commits clean and reduce noise in the current repository state.
-
-## Hygiene
+## Workflow
 
-A linter can be used for static analysis of task files, and to ensure there are no broken relative links as the result of any changes.
+Progress is tracked via changes to markdown files in the `.dust/` directory. The four directories together (`goals/`, `ideas/`, `tasks/`, `facts/`) act as a kanban system for managing work.
 
-Regular semantic and logic checks are expected to be carried out to ensure ideas have not drifted from reality. This would typically happen after one or more commits, e.g. at the end of a sprint.
+The `tasks/` directory acts as a work queue. When a task is completed, the commit typically includes both the code changes and the deletion of the task file—removing work from the queue for subsequent agents.

package/dist/dust.js

@@ -27,22 +27,22 @@ var AGENT_SUBCOMMANDS = [
   "help"
 ];
 function generateAgentGreeting(settings) {
-  return loadTemplate("agent-greeting", { bin: settings.binaryPath });
+  return loadTemplate("agent-greeting", { bin: settings.dustCommand });
 }
 function generateWorkInstructions(settings) {
-  return loadTemplate("agent-work", { bin: settings.binaryPath });
+  return loadTemplate("agent-work", { bin: settings.dustCommand });
 }
 function generateTasksInstructions(settings) {
-  return loadTemplate("agent-tasks", { bin: settings.binaryPath });
+  return loadTemplate("agent-tasks", { bin: settings.dustCommand });
 }
 function generateGoalsInstructions(settings) {
-  return loadTemplate("agent-goals", { bin: settings.binaryPath });
+  return loadTemplate("agent-goals", { bin: settings.dustCommand });
 }
 function generateIdeasInstructions(settings) {
-  return loadTemplate("agent-ideas", { bin: settings.binaryPath });
+  return loadTemplate("agent-ideas", { bin: settings.dustCommand });
 }
 function generateAgentHelp(settings) {
-  return loadTemplate("agent-help", { bin: settings.binaryPath });
+  return loadTemplate("agent-help", { bin: settings.dustCommand });
 }
 async function agent(ctx, args, settings) {
   const subcommand = args[0];
@@ -76,6 +76,54 @@ async function agent(ctx, args, settings) {
 // lib/cli/check.ts
 import { spawn } from "node:child_process";
 
+// lib/cli/settings.ts
+import { join as join2 } from "node:path";
+var DEFAULT_SETTINGS = {
+  dustCommand: "npx dust"
+};
+function detectDustCommand(cwd, fs) {
+  if (fs.exists(join2(cwd, "bun.lockb"))) {
+    return "bunx dust";
+  }
+  if (fs.exists(join2(cwd, "pnpm-lock.yaml"))) {
+    return "pnpx dust";
+  }
+  if (fs.exists(join2(cwd, "package-lock.json"))) {
+    return "npx dust";
+  }
+  if (process.env.BUN_INSTALL) {
+    return "bunx dust";
+  }
+  return "npx dust";
+}
+async function loadSettings(cwd, fs) {
+  const settingsPath = join2(cwd, ".dust", "config", "settings.json");
+  if (!fs.exists(settingsPath)) {
+    return {
+      dustCommand: detectDustCommand(cwd, fs)
+    };
+  }
+  try {
+    const content = await fs.readFile(settingsPath);
+    const parsed = JSON.parse(content);
+    if (!parsed.dustCommand) {
+      return {
+        ...DEFAULT_SETTINGS,
+        ...parsed,
+        dustCommand: detectDustCommand(cwd, fs)
+      };
+    }
+    return {
+      ...DEFAULT_SETTINGS,
+      ...parsed
+    };
+  } catch {
+    return {
+      dustCommand: detectDustCommand(cwd, fs)
+    };
+  }
+}
+
 // lib/cli/validate.ts
 import { dirname as dirname2, resolve } from "node:path";
 var REQUIRED_HEADINGS = ["## Goals", "## Blocked by", "## Definition of done"];
@@ -240,66 +288,121 @@ async function validate(ctx, fs, _args, glob) {
 }
 
 // lib/cli/check.ts
-function createProcessRunner(spawnFn) {
+function createBufferedRunner(spawnFn) {
   return {
-    spawn: (command, args, options) => {
+    run: (command, cwd) => {
       return new Promise((resolve2) => {
-        const proc = spawnFn(command, args, options);
-        proc.on("close", (code) => resolve2(code ?? 1));
-        proc.on("error", () => resolve2(1));
+        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", (err) => {
+          resolve2({ exitCode: 1, output: err.message });
+        });
       });
     }
   };
 }
-var defaultProcessRunner = createProcessRunner(spawn);
-async function check(ctx, fs, _args, runner = defaultProcessRunner, glob) {
-  if (glob) {
-    const validationResult = await validate(ctx, fs, [], glob);
-    if (validationResult.exitCode !== 0) {
-      return validationResult;
+var defaultBufferedRunner = createBufferedRunner(spawn);
+async function runConfiguredChecks(checks, cwd, runner) {
+  const promises = checks.map(async (check) => {
+    const { exitCode, output } = await runner.run(check.command, cwd);
+    return {
+      name: check.name,
+      command: check.command,
+      exitCode,
+      output
+    };
+  });
+  return Promise.all(promises);
+}
+async function runValidationCheck(ctx, fs, glob) {
+  const outputLines = [];
+  const bufferedCtx = {
+    cwd: ctx.cwd,
+    stdout: (msg) => outputLines.push(msg),
+    stderr: (msg) => outputLines.push(msg)
+  };
+  const result = await validate(bufferedCtx, fs, [], glob);
+  return {
+    name: "validate",
+    command: "dust validate",
+    exitCode: result.exitCode,
+    output: outputLines.join(`
+`),
+    isBuiltIn: true
+  };
+}
+function displayResults(results, ctx) {
+  const passed = results.filter((r) => r.exitCode === 0);
+  const failed = results.filter((r) => r.exitCode !== 0);
+  for (const result of results) {
+    if (result.exitCode === 0) {
+      ctx.stdout(`✓ ${result.name}`);
+    } else {
+      ctx.stdout(`✗ ${result.name}`);
     }
+  }
+  for (const result of failed) {
     ctx.stdout("");
+    ctx.stdout(`> ${result.command}`);
+    if (result.output.trim()) {
+      ctx.stdout(result.output.trimEnd());
+    }
   }
-  const hookPath = `${ctx.cwd}/.dust/hooks/check`;
-  if (!fs.exists(hookPath)) {
-    ctx.stderr("Error: No check hook found at .dust/hooks/check");
+  ctx.stdout("");
+  ctx.stdout(`${passed.length}/${results.length} checks passed`);
+  return failed.length > 0 ? 1 : 0;
+}
+async function check(ctx, fs, _args, glob, bufferedRunner = defaultBufferedRunner) {
+  const settings = await loadSettings(ctx.cwd, fs);
+  if (!settings.checks || settings.checks.length === 0) {
+    ctx.stderr("Error: No checks configured in .dust/config/settings.json");
     ctx.stderr("");
-    ctx.stderr("To create a check hook:");
-    ctx.stderr("  1. Create the hooks directory: mkdir -p .dust/hooks");
-    ctx.stderr("  2. Create the check script: touch .dust/hooks/check");
-    ctx.stderr("  3. Make it executable: chmod +x .dust/hooks/check");
-    ctx.stderr("  4. Add your quality checks (tests, linting, etc.)");
+    ctx.stderr("Add checks to your settings.json:");
+    ctx.stderr("  {");
+    ctx.stderr('    "checks": [');
+    ctx.stderr('      { "name": "lint", "command": "npm run lint" },');
+    ctx.stderr('      { "name": "test", "command": "npm test" }');
+    ctx.stderr("    ]");
+    ctx.stderr("  }");
     return { exitCode: 1 };
   }
-  const exitCode = await runner.spawn(hookPath, [], {
-    cwd: ctx.cwd,
-    stdio: "inherit"
-  });
+  const checkPromises = [];
+  if (glob) {
+    checkPromises.push(runValidationCheck(ctx, fs, glob));
+  }
+  checkPromises.push(runConfiguredChecks(settings.checks, ctx.cwd, bufferedRunner));
+  const promiseResults = await Promise.all(checkPromises);
+  const results = [];
+  for (const result of promiseResults) {
+    if (Array.isArray(result)) {
+      results.push(...result);
+    } else {
+      results.push(result);
+    }
+  }
+  const exitCode = displayResults(results, ctx);
   return { exitCode };
 }
 
 // lib/cli/init.ts
 var DUST_DIRECTORIES = ["goals", "ideas", "tasks", "facts"];
-var DEFAULT_GOAL = `# Project Goal
+var USE_DUST_FACT = `# Use dust for planning
 
-Describe the high-level mission of this project.
+This project uses [dust](https://github.com/joshski/dust) for planning and documentation.
 `;
-function detectPackageRunner(cwd, fs) {
-  if (process.versions.bun) {
-    return "bunx";
-  }
-  if (fs.exists(`${cwd}/bun.lockb`)) {
-    return "bunx";
-  }
-  if (fs.exists(`${cwd}/pnpm-lock.yaml`)) {
-    return "pnpx";
-  }
-  return "npx";
-}
 async function init(ctx, fs, _args) {
   const dustPath = `${ctx.cwd}/.dust`;
-  const runner = detectPackageRunner(ctx.cwd, fs);
-  const agentInstruction = `Always immediately run \`${runner} dust agent\` when you start working in this repository.`;
+  const dustCommand = detectDustCommand(ctx.cwd, fs);
+  const agentInstruction = `Always immediately run \`${dustCommand} agent\` when you start working in this repository.`;
   if (fs.exists(dustPath)) {
     ctx.stdout("Note: .dust directory already exists, skipping creation");
   } else {
@@ -307,16 +410,16 @@ async function init(ctx, fs, _args) {
     for (const dir of DUST_DIRECTORIES) {
       await fs.mkdir(`${dustPath}/${dir}`, { recursive: true });
     }
-    await fs.writeFile(`${dustPath}/goals/project-goal.md`, DEFAULT_GOAL);
+    await fs.writeFile(`${dustPath}/facts/use-dust-for-planning.md`, USE_DUST_FACT);
     ctx.stdout("Initialized Dust repository in .dust/");
     ctx.stdout(`Created directories: ${DUST_DIRECTORIES.join(", ")}`);
-    ctx.stdout("Created initial goal: .dust/goals/project-goal.md");
+    ctx.stdout("Created initial fact: .dust/facts/use-dust-for-planning.md");
   }
   const claudeMdPath = `${ctx.cwd}/CLAUDE.md`;
   if (fs.exists(claudeMdPath)) {
     ctx.stdout(`Warning: CLAUDE.md already exists. Consider adding: "${agentInstruction}"`);
   } else {
-    const claudeContent = loadTemplate("claude-md", { runner });
+    const claudeContent = loadTemplate("claude-md", { dustCommand });
     await fs.writeFile(claudeMdPath, claudeContent);
     ctx.stdout("Created CLAUDE.md with agent instructions");
   }
@@ -324,7 +427,7 @@ async function init(ctx, fs, _args) {
   if (fs.exists(agentsMdPath)) {
     ctx.stdout(`Warning: AGENTS.md already exists. Consider adding: "${agentInstruction}"`);
   } else {
-    const agentsContent = loadTemplate("agents-md", { runner });
+    const agentsContent = loadTemplate("agents-md", { dustCommand });
     await fs.writeFile(agentsMdPath, agentsContent);
     ctx.stdout("Created AGENTS.md with agent instructions");
   }
@@ -443,61 +546,9 @@ async function next(ctx, fs, _args) {
   return { exitCode: 0 };
 }
 
-// lib/cli/prompt.ts
-async function prompt(ctx, fs, args) {
-  const promptsDir = `${ctx.cwd}/prompts`;
-  if (args.length === 0) {
-    ctx.stderr("Usage: dust prompt <name>");
-    ctx.stderr("Example: dust prompt work");
-    return { exitCode: 1 };
-  }
-  const promptName = args[0];
-  const promptFile = `${promptsDir}/${promptName}.md`;
-  if (!fs.exists(promptFile)) {
-    ctx.stderr(`Error: Prompt '${promptName}' not found`);
-    ctx.stderr("Available prompts:");
-    try {
-      const files = await fs.readdir(promptsDir);
-      const prompts = files.filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, ""));
-      for (const p of prompts) {
-        ctx.stderr(`  ${p}`);
-      }
-    } catch {
-      ctx.stderr("  (no prompts directory found)");
-    }
-    return { exitCode: 1 };
-  }
-  const content = await fs.readFile(promptFile);
-  ctx.stdout(content);
-  return { exitCode: 0 };
-}
-
-// lib/cli/settings.ts
-import { join as join2 } from "node:path";
-var DEFAULT_SETTINGS = {
-  binaryPath: "dust"
-};
-async function loadSettings(cwd, fs) {
-  const settingsPath = join2(cwd, ".dust", "config", "settings.json");
-  if (!fs.exists(settingsPath)) {
-    return DEFAULT_SETTINGS;
-  }
-  try {
-    const content = await fs.readFile(settingsPath);
-    const parsed = JSON.parse(content);
-    return {
-      ...DEFAULT_SETTINGS,
-      ...parsed
-    };
-  } catch {
-    return DEFAULT_SETTINGS;
-  }
-}
-
 // lib/cli/main.ts
 var COMMANDS = [
   "init",
-  "prompt",
   "validate",
   "list",
   "next",
@@ -506,9 +557,9 @@ var COMMANDS = [
   "help"
 ];
 function generateHelpText(settings) {
-  return loadTemplate("help", { bin: settings.binaryPath });
+  return loadTemplate("help", { bin: settings.dustCommand });
 }
-var HELP_TEXT = generateHelpText({ binaryPath: "dust" });
+var HELP_TEXT = generateHelpText({ dustCommand: "dust" });
 function isHelpRequest(command) {
   return !command || command === "help" || command === "--help" || command === "-h";
 }
@@ -519,8 +570,6 @@ async function runCommand(command, commandArgs, ctx, fs, glob, settings) {
   switch (command) {
     case "init":
       return init(ctx, fs, commandArgs);
-    case "prompt":
-      return prompt(ctx, fs, commandArgs);
     case "validate":
       return validate(ctx, fs, commandArgs, glob);
     case "list":
@@ -528,7 +577,7 @@ async function runCommand(command, commandArgs, ctx, fs, glob, settings) {
     case "next":
       return next(ctx, fs, commandArgs);
     case "check":
-      return check(ctx, fs, commandArgs, defaultProcessRunner, glob);
+      return check(ctx, fs, commandArgs, glob);
     case "agent":
       return agent(ctx, commandArgs, settings);
     case "help":
@@ -548,7 +597,7 @@ async function main(options) {
   }
   if (!isValidCommand(command)) {
     ctx.stderr(`Unknown command: ${command}`);
-    ctx.stderr(`Run '${settings.binaryPath} help' for available commands`);
+    ctx.stderr(`Run '${settings.dustCommand} help' for available commands`);
     return { exitCode: 1 };
   }
   return runCommand(command, commandArgs, ctx, fs, glob, settings);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joshski/dust",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "A lightweight planning system for human-AI collaboration",
   "type": "module",
   "bin": {

package/templates/agent-greeting.txt

@@ -2,10 +2,43 @@ Hello Claude, welcome to dust!
 
 Your goal today is to make ONE SMALL CHANGE and then commit and push your changes.
 
-Based on what the user asked you to do, run the appropriate command:
+The user might be prompting you to do one of many things. Depending on their intention, run
+one of the following commands:
 
-- If the user mentioned "work" → run `{{bin}} agent work`
-- If the user mentioned "task" or "tasks" → run `{{bin}} agent tasks`
-- If the user mentioned "goal" or "goals" → run `{{bin}} agent goals`
-- If the user mentioned "idea" or "ideas" → run `{{bin}} agent ideas`
-- For anything else → run `{{bin}} agent help`
+If your prompt is something like one of these:
+
+    * "work"
+    * "get to work"
+    * "go"
+    * "pick a task"
+
+...then run:
+
+`{{bin}} agent work`
+
+If your prompt is something like one of these:
+
+    * "add a task ..."
+    * "task: ..."
+
+...then you should create a new task. To find out how, you should immediately run:
+
+`{{bin}} agent tasks`
+
+If your prompt is something like one of these:
+
+    * "add a goal ..."
+    * "goal: ..."
+
+...then you should create a new goal. To find out how, you should immediately run:
+
+`{{bin}} agent goals`
+
+If it sounds like the prompt is a vague idea about some potential change to the system,
+then you should create an idea. To find out how, you should immediately run:
+
+`{{bin}} agent ideas`
+
+If it's still not clear, run:
+
+`{{bin}} agent help`

package/templates/agent-help.txt

@@ -21,3 +21,14 @@ For focused guidance, run:
 - `{{bin}} agent tasks` - Task management
 - `{{bin}} agent goals` - Understanding goals
 - `{{bin}} agent ideas` - Working with ideas
+
+### Configuring Agent Files
+
+Projects using dust should add a minimal pointer to their agent configuration files (CLAUDE.md, AGENTS.md, etc.):
+
+```markdown
+This project uses [dust](https://github.com/joshski/dust) for planning and documentation.
+Always run `dust agent` when you start working in this repository.
+```
+
+This keeps agent instructions minimal and ensures agents get current documentation.

package/templates/agent-ideas.txt

@@ -7,7 +7,6 @@ Ideas live in `.dust/ideas/` as markdown files. They are intentionally vague pro
 **Converting an idea to tasks:**
 1. Read the idea file to understand the proposal
 2. Break it down into concrete, actionable tasks
-3. Create task files in `.dust/tasks/` with clear definitions of done
-4. Delete the idea file once it's fully captured in tasks
+3. Run `{{bin}} agent tasks` to see the workflow to apply to each individual task.
 
 Ideas are cheap to create and easy to discard. Not every idea becomes a task.

package/templates/agent-tasks.txt

@@ -1,15 +1,48 @@
-## Task Management
+# Task Management
 
-**List tasks:** `{{bin}} list tasks`
+**List all tasks:** `{{bin}} list tasks`
 **Find ready tasks:** `{{bin}} next`
 
-Tasks live in `.dust/tasks/` as markdown files. Each task has:
-- `## Goals` - Links to goals this task supports
-- `## Blocked by` - Tasks that must complete first
-- `## Definition of done` - Checklist of completion criteria
+## Implementing a Task
 
-A task is ready when "Blocked by" is empty or says "(none)".
+When implementing a task, follow these steps:
 
-**Creating tasks:** Write a new markdown file in `.dust/tasks/` following the format above.
+1. Install dependencies first (e.g., `npm install`, `bundle install`)
+2. Run `{{bin}} check` before implementing anything to verify the project is in a good state
+3. Read the task file and understand all requirements in "Definition of done"
+4. Implement the changes, checking off items as you complete them
+5. Run `{{bin}} check` after implementing all changes to verify nothing is broken
+6. Create a single atomic commit that includes:
+   - All implementation changes
+   - Deletion of the completed task file
+   - Updates to any facts that changed
+   - Deletion of any ideas that were fully realized
 
-**Completing tasks:** Delete the task file in your commit after implementation.
+## Adding a Task from scratch
+
+To add a new task, follow these steps:
+
+1. Create a new markdown file in `.dust/tasks/` with a descriptive kebab-case name (e.g., `add-user-authentication.md`)
+2. Add a title as the first line using an H1 heading (e.g., `# Add user authentication`)
+3. Write a comprehensive description of what needs to be done with technical details and references to relevant files
+4. Add a `## Goals` section with links to relevant goals this task supports (e.g., `- [Goal Name](../goals/goal-name.md)`)
+5. Add a `## Blocked by` section listing any tasks that must complete first, or `(none)` if there are no blockers
+6. Add a `## Definition of done` section with a checklist of completion criteria using `- [ ]` for each item
+7. Run `{{bin}} validate` to catch any issues with the task format
+8. Create a single atomic commit with a message in the format "Add task: <title>"
+
+## Converting an Idea into a Task (fleshing out an idea)
+
+To add a new task, follow these steps:
+
+1. Create a new markdown file in `.dust/tasks/` with a descriptive kebab-case name (e.g., `add-user-authentication.md`)
+2. Add a title as the first line using an H1 heading (e.g., `# Add user authentication`)
+3. Write a comprehensive description of what needs to be done with technical details and references to relevant files
+4. Add a `## Goals` section with links to relevant goals this task supports (e.g., `- [Goal Name](../goals/goal-name.md)`)
+5. Add a `## Blocked by` section listing any tasks that must complete first, or `(none)` if there are no blockers
+6. Add a `## Definition of done` section with a checklist of completion criteria using `- [ ]` for each item
+7. Run `{{bin}} validate` to catch any issues with the task format or regressions
+8. Create a single atomic commit with the message "Add task: <title>" that includes:
+   - All implementation changes
+   - Deletion of the idea file
+   - Updates to any facts that changed

package/templates/agents-md.txt

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

package/templates/claude-md.txt

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

package/templates/help.txt

@@ -4,7 +4,6 @@ Usage: {{bin}} <command> [options]
 
 Commands:
   init              Initialize a new Dust repository
-  prompt <name>     Output a prompt by name (e.g., {{bin}} prompt work)
   validate          Run validation checks on .dust/ files
   list [type]       List items (tasks, ideas, goals, facts)
   next              Show tasks ready to work on (not blocked)
@@ -14,7 +13,6 @@ Commands:
 
 Examples:
   {{bin}} init
-  {{bin}} prompt work
   {{bin}} validate
   {{bin}} list tasks
   {{bin}} list
@@ -22,61 +20,4 @@ Examples:
   {{bin}} check
   {{bin}} agent work
 
----
-
-## Agent Guide
-
-This section provides comprehensive guidance for AI agents working with dust.
-
-### Directory Structure
-
-The `.dust/` directory contains all planning artifacts:
-
-- **`.dust/goals/`** - Mission statements and guiding principles
-- **`.dust/ideas/`** - Future feature notes and proposals (intentionally vague)
-- **`.dust/tasks/`** - Detailed work plans with dependencies and definitions of done
-- **`.dust/facts/`** - Documentation of current system state and architecture
-- **`.dust/hooks/`** - Executable scripts for quality gates (e.g., `check` hook)
-
-All files are markdown with slug-style names (lowercase, hyphens, no spaces).
-
-### Working on Tasks
-
-**Run `{{bin}} check` before starting work** to verify the project is in a good state before making changes.
-
-Run `{{bin}} next` to find tasks ready to work on. Each task file contains:
-
-- `## Goals` - Links to goals this task supports
-- `## Blocked by` - Tasks that must complete first (empty or "(none)" means ready)
-- `## Definition of done` - Criteria for completion
-
-A task is **unblocked** when its "Blocked by" section is empty, says "(none)", or all referenced task files have been deleted.
-
-### Completing a Task
-
-**Run `{{bin}} check` before committing** to ensure all quality gates pass.
-
-When finishing a task, create a single atomic commit that includes:
-
-1. All implementation changes
-2. Deletion of the completed task file
-3. Updates to any facts that changed
-4. Deletion of any ideas that were fully realized
-5. Updates to any tasks that referenced this one in their "Blocked by" sections
-
-### Common Workflows
-
-- **"Work on the next task"** - Run `{{bin}} next`, pick a task, implement it
-- **"Work on task X"** - Implement `.dust/tasks/X.md` directly
-- **"Convert idea Y to tasks"** - Break down `.dust/ideas/Y.md` into tasks
-- **"Validate facts"** - Check `.dust/facts/` for accuracy against the codebase
-
-### Configuring Agent Files
-
-Projects using dust should add a minimal pointer to their agent configuration files (CLAUDE.md, AGENTS.md, etc.):
-
-```markdown
-This project uses [dust](https://github.com/joshski/dust) for planning and documentation.\nAlways run `dust help` when you start working in this repository.
-```
-
-This approach keeps agent instructions minimal, ensures agents get current documentation, and reduces maintenance burden.
+For AI agent guidance, run `{{bin}} agent`.