@joshski/dust 0.1.10 → 0.1.12

package/README.md

@@ -1,129 +1,51 @@
 # Dust
 
-A lightweight workflow tool for humans working with AI agents.
+A workflow tool for keeping AI coding agents on track.
 
 [![CI](https://github.com/joshski/dust/actions/workflows/ci.yml/badge.svg)](https://github.com/joshski/dust/actions/workflows/ci.yml)
 
-## Why Would I Use This?
+## Why Use This?
 
-Use this to plan a series of tasks that coding agents can perform autonomously.
+AI coding agents work best with clear tasks and fast feedback. Dust gives them both:
 
-## Getting Started
+- **Tasks** — a queue of work, each with clear requirements and definition of done
+- **Checks** — quality gates (tests, lint, build) that run before and after changes
 
-Install dust using your package manager of choice (`npm` and `bun` officially supported for now):
+Agents pick tasks, implement them, verify checks pass, and move on. You add tasks, review commits, and steer direction.
 
-```bash
-npm install @joshski/dust
-```
-
-Initialize dust in your repository:
+## Quick Start
 
 ```bash
+npm install @joshski/dust
 npx dust init
 ```
 
-## How It Works
-
-The [.dust](./.dust) directory in your repository contains 4 sets of markdown files:
-
-```
-.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
-```
-
-These files are used to facilitate exploration and management of AI agent workflow.
-
-## Workflow
-
-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.
+This creates a [.dust](./.dust/facts/dust-directory-structure.md) directory and adds an [instruction](./.dust/facts/agents-md-instruction.md) to your `AGENTS.md` file.
 
-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.
-
-Humans primarily interact with `dust` using their AI coding agent of choice, e.g.
-
-```
-> claude "implement the next task"
-> claude "get to work!"
-> codex "add task: coverage reporting"
-> codex "goal: cross-platform compatibility"
-```
+## Running Agents
 
-Agents discover everything they need to know to interpret human prompts using the `dust` CLI.
-
-## Agent CLI
-
-The `dust` CLI is intended to be used primarily by agents, not by humans (except for the `init` command, as mentioned above).
-
-Don't let that stop you:
+Start an agent on a single task:
 
 ```bash
-npx dust help
-```
-
-## AGENTS.md
-
-Add a line like this to your `AGENTS.md` or `CLAUDE.md` file:
-
-```markdown
-Always immediately run `npx dust agent` when you start working in this repository.
+claude "implement the next task"
 ```
 
-In fact, you might find it effective to use that as the _only_ line in those files. Essential documentation should be discoverable by agents exploring your `./.dust` directory.
-
-## Configuration
+Or let dust run agents continuously [in a sandbox](./.dust/facts/autonomous-agents-need-sandboxes.md) with the [loop](./.dust/facts/loop-command.md) command:
 
-Configure dust in `./.dust/config/settings.json` e.g.
-
-```json
-{
-  "dustCommand": "bunx dust",
-  "checks": [
-    { "name": "lint", "command": "bunx biome check ." },
-    { "name": "build", "command": "bun run build" },
-    { "name": "tests", "command": "bun run test:coverage" },
-    { "name": "typecheck", "command": "bunx tsc --noEmit lib/**/*.ts" }
-  ]
-}
-```
-
-The `dust check` command will run all of the configured checks in parallel and produce a very terse (context window-friendly) output unless one or more of the checks fail.
-
-### Check Failure Hints
-
-Add optional `hints` to help agents recover from check failures:
-
-```json
-{
-  "checks": [
-    {
-      "name": "build",
-      "command": "npm run build",
-      "hints": [
-        "Run `npm install` if this is a fresh checkout",
-        "Check for TypeScript errors in the files you modified"
-      ]
-    }
-  ]
-}
+```bash
+npx dust loop claude
 ```
 
-When a check fails, hints are displayed after the error output:
+This runs Claude Code in a [ralph loop](https://ghuntley.com/loop/), picking up tasks until the iteration limit is reached (default: 10). You can specify a custom limit:
 
+```bash
+npx dust loop claude 5
 ```
-✓ validate
-✗ build
-
-> npm run build
-error TS2307: Cannot find module 'lodash'...
 
-Hints for fixing 'build':
-  - Run `npm install` if this is a fresh checkout
-  - Check for TypeScript errors in the files you modified
+## Learn More
 
-1/2 checks passed
-```
+Details live in the [.dust/facts](./.dust/facts) directory:
 
-Agents are instructed to run `dust check` before and after any changes, as a way of keeping them on track. It's more important that these commands are comprehensive, than they are fast.
+- [Directory Structure](./.dust/facts/dust-directory-structure.md) — how `.dust/` is organized
+- [Configuration](./.dust/facts/configuration-system.md) — settings and quality checks
+- [CLI Commands](./.dust/facts/unified-cli.md) — full command reference

package/dist/dust.js

@@ -254,7 +254,7 @@ async function agentUnderstandGoals(dependencies) {
 // lib/cli/commands/check.ts
 import { spawn } from "node:child_process";
 
-// lib/cli/commands/validate.ts
+// lib/cli/commands/lint-markdown.ts
 import { dirname as dirname2, resolve } from "node:path";
 
 // lib/cli/markdown-utilities.ts
@@ -263,8 +263,53 @@ function extractTitle(content) {
   return match ? match[1].trim() : null;
 }
 var MARKDOWN_LINK_PATTERN = /\[([^\]]+)\]\(([^)]+)\)/;
+function extractOpeningSentence(content) {
+  const lines = content.split(`
+`);
+  let h1Index = -1;
+  for (let i = 0;i < lines.length; i++) {
+    if (lines[i].match(/^#\s+.+$/)) {
+      h1Index = i;
+      break;
+    }
+  }
+  if (h1Index === -1) {
+    return null;
+  }
+  let paragraphStart = -1;
+  for (let i = h1Index + 1;i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line !== "") {
+      paragraphStart = i;
+      break;
+    }
+  }
+  if (paragraphStart === -1) {
+    return null;
+  }
+  const firstLine = lines[paragraphStart];
+  const trimmedFirstLine = firstLine.trim();
+  if (trimmedFirstLine.startsWith("#") || trimmedFirstLine.startsWith("-") || trimmedFirstLine.startsWith("*") || trimmedFirstLine.startsWith("+") || trimmedFirstLine.match(/^\d+\./) || trimmedFirstLine.startsWith("```") || trimmedFirstLine.startsWith(">")) {
+    return null;
+  }
+  let paragraph = "";
+  for (let i = paragraphStart;i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line === "")
+      break;
+    if (line.startsWith("#") || line.startsWith("```") || line.startsWith(">")) {
+      break;
+    }
+    paragraph += (paragraph ? " " : "") + line;
+  }
+  const sentenceMatch = paragraph.match(/^(.+?[.?!])(?:\s|$)/);
+  if (!sentenceMatch) {
+    return null;
+  }
+  return sentenceMatch[1];
+}
 
-// lib/cli/commands/validate.ts
+// lib/cli/commands/lint-markdown.ts
 var REQUIRED_HEADINGS = ["## Goals", "## Blocked by", "## Definition of done"];
 var SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*\.md$/;
 function validateFilename(filePath) {
@@ -278,6 +323,16 @@ function validateFilename(filePath) {
   }
   return null;
 }
+function validateOpeningSentence(filePath, content) {
+  const openingSentence = extractOpeningSentence(content);
+  if (!openingSentence) {
+    return {
+      file: filePath,
+      message: "Missing or malformed opening sentence after H1 heading"
+    };
+  }
+  return null;
+}
 function validateTaskHeadings(filePath, content) {
   const violations = [];
   for (const heading of REQUIRED_HEADINGS) {
@@ -380,7 +435,7 @@ function validateSemanticLinks(filePath, content) {
   }
   return violations;
 }
-async function validate(dependencies) {
+async function lintMarkdown(dependencies) {
   const { context, fileSystem, globScanner: glob } = dependencies;
   const dustPath = `${context.cwd}/.dust`;
   if (!fileSystem.exists(dustPath)) {
@@ -397,6 +452,23 @@ async function validate(dependencies) {
     const content = await fileSystem.readFile(filePath);
     violations.push(...validateLinks(filePath, content, fileSystem));
   }
+  const contentDirs = ["goals", "facts", "ideas", "tasks"];
+  context.stdout("Validating opening sentences...");
+  for (const dir of contentDirs) {
+    const dirPath = `${dustPath}/${dir}`;
+    if (!fileSystem.exists(dirPath))
+      continue;
+    for await (const file of glob.scan(dirPath)) {
+      if (!file.endsWith(".md"))
+        continue;
+      const filePath = `${dirPath}/${file}`;
+      const content = await fileSystem.readFile(filePath);
+      const openingSentenceViolation = validateOpeningSentence(filePath, content);
+      if (openingSentenceViolation) {
+        violations.push(openingSentenceViolation);
+      }
+    }
+  }
   const tasksPath = `${dustPath}/tasks`;
   if (fileSystem.exists(tasksPath)) {
     context.stdout("Validating task files in .dust/tasks/...");
@@ -471,14 +543,14 @@ async function runValidationCheck(dependencies) {
     stdout: (msg) => outputLines.push(msg),
     stderr: (msg) => outputLines.push(msg)
   };
-  const result = await validate({
+  const result = await lintMarkdown({
     ...dependencies,
     context: bufferedContext,
     arguments: []
   });
   return {
-    name: "validate",
-    command: "dust validate",
+    name: "lint markdown",
+    command: "dust lint markdown",
     exitCode: result.exitCode,
     output: outputLines.join(`
 `),
@@ -695,6 +767,24 @@ async function init(dependencies) {
 
 // lib/cli/commands/list.ts
 var VALID_TYPES = ["tasks", "ideas", "goals", "facts"];
+var SECTION_HEADERS = {
+  tasks: "\uD83D\uDCCB Tasks",
+  ideas: "\uD83D\uDCA1 Ideas",
+  goals: "\uD83C\uDFAF Goals",
+  facts: "\uD83D\uDCC4 Facts"
+};
+var TYPE_EXPLANATIONS = {
+  tasks: "Tasks are detailed work plans with dependencies and completion criteria. Each task describes a specific piece of work to be done.",
+  ideas: "Ideas are future feature notes and proposals. Ideas capture possibilities that haven't yet been refined into actionable tasks.",
+  goals: "Goals are mission statements and guiding principles. Goals describe desired outcomes and values that inform decision-making.",
+  facts: "Facts are current state documentation. Facts capture how things work today, providing context for agents and contributors."
+};
+var colors = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  cyan: "\x1B[36m"
+};
 async function list(dependencies) {
   const { arguments: commandArguments, context, fileSystem } = dependencies;
   const dustPath = `${context.cwd}/.dust`;
@@ -709,29 +799,44 @@ async function list(dependencies) {
     context.stderr(`Valid types: ${VALID_TYPES.join(", ")}`);
     return { exitCode: 1 };
   }
+  const specificTypeRequested = commandArguments.length > 0;
   for (const type of typesToList) {
     const dirPath = `${dustPath}/${type}`;
-    if (!fileSystem.exists(dirPath)) {
-      continue;
-    }
-    const files = await fileSystem.readdir(dirPath);
+    const dirExists = fileSystem.exists(dirPath);
+    const files = dirExists ? await fileSystem.readdir(dirPath) : [];
     const mdFiles = files.filter((f) => f.endsWith(".md")).sort();
     if (mdFiles.length === 0) {
+      if (specificTypeRequested) {
+        context.stdout(SECTION_HEADERS[type]);
+        context.stdout("");
+        context.stdout(TYPE_EXPLANATIONS[type]);
+        context.stdout("");
+        context.stdout(`No ${type} found.`);
+        context.stdout("");
+      }
       continue;
     }
-    context.stdout(`${type}:`);
+    context.stdout(SECTION_HEADERS[type]);
+    context.stdout("");
+    context.stdout(TYPE_EXPLANATIONS[type]);
+    context.stdout("");
     for (const file of mdFiles) {
       const filePath = `${dirPath}/${file}`;
       const content = await fileSystem.readFile(filePath);
       const title = extractTitle(content);
-      const name = file.replace(/\.md$/, "");
+      const openingSentence = extractOpeningSentence(content);
+      const relativePath = `.dust/${type}/${file}`;
       if (title) {
-        context.stdout(`  ${name} - ${title}`);
+        context.stdout(`${colors.bold}# ${title}${colors.reset}`);
       } else {
-        context.stdout(`  ${name}`);
+        context.stdout(`${colors.bold}# ${file.replace(".md", "")}${colors.reset}`);
+      }
+      if (openingSentence) {
+        context.stdout(`${colors.dim}${openingSentence}${colors.reset}`);
       }
+      context.stdout(`${colors.cyan}→ ${relativePath}${colors.reset}`);
+      context.stdout("");
     }
-    context.stdout("");
   }
   return { exitCode: 0 };
 }
@@ -915,6 +1020,12 @@ async function run(prompt, options = {}, dependencies = defaultRunnerDependencie
 }
 
 // lib/cli/commands/next.ts
+var colors2 = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  cyan: "\x1B[36m"
+};
 function extractBlockedBy(content) {
   const blockedByMatch = content.match(/^## Blocked by\s*\n([\s\S]*?)(?=\n## |\n*$)/m);
   if (!blockedByMatch) {
@@ -959,20 +1070,24 @@ async function next(dependencies) {
     const hasIncompleteBlocker = blockers.some((blocker) => existingTasks.has(blocker));
     if (!hasIncompleteBlocker) {
       const title = extractTitle(content);
+      const openingSentence = extractOpeningSentence(content);
       const relativePath = `.dust/tasks/${file}`;
-      unblockedTasks.push({ path: relativePath, title });
+      unblockedTasks.push({ path: relativePath, title, openingSentence });
     }
   }
   if (unblockedTasks.length === 0) {
     return { exitCode: 0 };
   }
-  context.stdout("Next tasks:");
+  context.stdout("\uD83D\uDCCB Next tasks");
+  context.stdout("");
   for (const task of unblockedTasks) {
-    if (task.title) {
-      context.stdout(`  ${task.path} - ${task.title}`);
-    } else {
-      context.stdout(`  ${task.path}`);
+    const displayTitle = task.title || task.path.split("/").pop().replace(".md", "");
+    context.stdout(`${colors2.bold}# ${displayTitle}${colors2.reset}`);
+    if (task.openingSentence) {
+      context.stdout(`${colors2.dim}${task.openingSentence}${colors2.reset}`);
     }
+    context.stdout(`${colors2.cyan}→ ${task.path}${colors2.reset}`);
+    context.stdout("");
   }
   return { exitCode: 0 };
 }
@@ -986,6 +1101,7 @@ function createDefaultDependencies() {
   };
 }
 var SLEEP_INTERVAL_MS = 30000;
+var DEFAULT_MAX_ITERATIONS = 10;
 async function gitPull(cwd, spawn2) {
   return new Promise((resolve2) => {
     const proc = spawn2("git", ["pull"], {
@@ -1022,48 +1138,66 @@ async function hasAvailableTasks(dependencies) {
 async function runOneIteration(dependencies, loopDependencies) {
   const { context } = dependencies;
   const { spawn: spawn2, run: run2 } = loopDependencies;
-  context.stdout("Syncing with remote...");
+  context.stdout("\uD83D\uDD04 Syncing with remote...");
   const pullResult = await gitPull(context.cwd, spawn2);
   if (!pullResult.success) {
     context.stdout(`Note: git pull skipped (${pullResult.message})`);
   }
-  context.stdout("Checking for available tasks...");
+  context.stdout("\uD83D\uDD0D Checking for available tasks...");
   const hasTasks = await hasAvailableTasks(dependencies);
   if (!hasTasks) {
-    context.stdout("No tasks available. Sleeping...");
+    context.stdout("\uD83D\uDCA4 No tasks available. Sleeping...");
     context.stdout("");
     return "no_tasks";
   }
-  context.stdout("Found task(s). Starting Claude...");
+  context.stdout("✨ Found task(s). \uD83E\uDD16 Starting Claude...");
   context.stdout("");
   try {
     await run2("go", { cwd: context.cwd, dangerouslySkipPermissions: true });
     context.stdout("");
-    context.stdout("Claude session complete. Continuing loop...");
+    context.stdout("✅ Claude session complete. Continuing loop...");
     context.stdout("");
     return "ran_claude";
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     context.stderr(`Claude exited with error: ${message}`);
     context.stdout("");
-    context.stdout("Claude session complete. Continuing loop...");
+    context.stdout("✅ Claude session complete. Continuing loop...");
     context.stdout("");
     return "claude_error";
   }
 }
-async function loop(dependencies, loopDependencies = createDefaultDependencies()) {
+function parseMaxIterations(commandArguments) {
+  if (commandArguments.length === 0) {
+    return DEFAULT_MAX_ITERATIONS;
+  }
+  const parsed = Number.parseInt(commandArguments[0], 10);
+  if (Number.isNaN(parsed) || parsed <= 0) {
+    return DEFAULT_MAX_ITERATIONS;
+  }
+  return parsed;
+}
+async function loopClaude(dependencies, loopDependencies = createDefaultDependencies()) {
   const { context } = dependencies;
-  context.stdout("WARNING: This command skips all permission checks. Only use in a sandbox environment!");
+  const maxIterations = parseMaxIterations(dependencies.arguments);
+  context.stdout("⚠️  WARNING: This command skips all permission checks. Only use in a sandbox environment!");
   context.stdout("");
-  context.stdout("Starting dust loop...");
-  context.stdout("Press Ctrl+C to stop");
+  context.stdout(`\uD83D\uDD04 Starting dust loop claude (max ${maxIterations} iterations)...`);
+  context.stdout("   Press Ctrl+C to stop");
   context.stdout("");
-  while (true) {
+  let completedIterations = 0;
+  while (completedIterations < maxIterations) {
     const result = await runOneIteration(dependencies, loopDependencies);
     if (result === "no_tasks") {
       await loopDependencies.sleep(SLEEP_INTERVAL_MS);
+    } else {
+      completedIterations++;
+      context.stdout(`\uD83D\uDCCB Completed iteration ${completedIterations}/${maxIterations}`);
+      context.stdout("");
     }
   }
+  context.stdout(`\uD83C\uDFC1 Reached max iterations (${maxIterations}). Exiting.`);
+  return { exitCode: 0 };
 }
 
 // lib/cli/commands/pre-push.ts
@@ -1074,7 +1208,7 @@ async function prePush(dependencies) {
 // lib/cli/main.ts
 var commandRegistry = {
   init,
-  validate,
+  "lint-markdown": lintMarkdown,
   list,
   next,
   check,
@@ -1086,7 +1220,7 @@ var commandRegistry = {
   "agent-implement-task": agentImplementTask,
   "agent-pick-task": agentPickTask,
   "agent-understand-goals": agentUnderstandGoals,
-  loop,
+  "loop-claude": loopClaude,
   "pre-push": prePush,
   help
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joshski/dust",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "A lightweight planning system for human-AI collaboration",
   "type": "module",
   "bin": {
@@ -26,7 +26,8 @@
   "scripts": {
     "build": "bun build lib/cli/entry.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",
     "test": "vitest run",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "eval": "bun run ./evals/run.ts"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.13",

package/templates/agent-help.txt

@@ -11,7 +11,7 @@ Dust is a lightweight planning system. The `.dust/` directory contains:
 - `{{bin}} check` - Run quality gates (do this before and after work)
 - `{{bin}} next` - Show tasks ready to work on
 - `{{bin}} list [type]` - List artifacts (tasks, ideas, goals, facts)
-- `{{bin}} validate` - Check .dust/ files for errors
+- `{{bin}} lint markdown` - Check .dust/ files for errors
 
 **Workflow:** Pick a task, implement it, delete the task file, commit atomically.
 

package/templates/agent-new-goal.txt

@@ -11,7 +11,7 @@ Follow these steps:
    - What this goal means in practice
    - Why it matters for the project
    - How to evaluate whether work supports this goal
-5. Run `{{bin}} validate` to catch any formatting issues
+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
 

package/templates/agent-new-idea.txt

@@ -6,6 +6,6 @@ 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}} validate` to catch any issues with the idea file format
+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

package/templates/agent-new-task.txt

@@ -12,7 +12,7 @@ Follow these steps:
 6. Add a `## Goals` section with links to relevant goals this task supports (e.g., `- [Goal Name](../goals/goal-name.md)`)
 7. Add a `## Blocked by` section listing any tasks that must complete first, or `(none)` if there are no blockers
 8. Add a `## Definition of done` section with a checklist of completion criteria using `- [ ]` for each item
-9. Run `{{bin}} validate` to catch any issues with the task format
+9. Run `{{bin}} lint markdown` to catch any issues with the task format
 10. Create a single atomic commit with a message in the format "Add task: <title>" that includes:
     - The new task file
     - Deletion of any ideas that were fully realized

package/templates/help.txt

@@ -1,24 +1,27 @@
-dust - A lightweight planning system for human-AI collaboration
+💨 dust - A workflow tool for keeping AI coding agents on track.
 
 Usage: {{bin}} <command> [options]
 
 Commands:
-  init              Initialize a new Dust repository
-  validate          Run validation checks on .dust/ files
-  list [type]       List items (tasks, ideas, goals, facts)
-  next              Show tasks ready to work on (not blocked)
-  check             Run project-defined quality gate hook
-  agent [cmd]       Agent-specific guidance (work, tasks, goals, ideas, help)
-  loop              Run continuous Claude iteration on tasks
-  help              Show this help message
+  init                      Initialize a new Dust repository
+  lint markdown             Run lint checks on .dust/ files
+  list                      List all items (tasks, ideas, goals, facts)
+  list tasks                List tasks (actionable work with definitions of done)
+  list ideas                List ideas (vague proposals, convert to tasks when ready)
+  list goals                List goals (guiding principles, stable, rarely change)
+  list 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
+  agent help                Show agent guidance
+  agent pick task           Pick the next task to work on
+  agent implement task      Implement a task
+  agent new task            Create a new task
+  agent new goal            Create a new goal
+  agent new idea            Working with ideas
+  agent understand goals    Understanding goals
+  loop                      Run continuous Claude iteration on tasks
+  pre-push                  Git pre-push hook validation
+  help                      Show this help message
 
-Examples:
-  {{bin}} init
-  {{bin}} validate
-  {{bin}} list tasks
-  {{bin}} list
-  {{bin}} next
-  {{bin}} check
-  {{bin}} agent work
-
-If you are an AI agent, run `{{bin}} agent` now!
+🤖 If you are an AI agent, run `{{bin}} agent` to get started!

package/templates/templates/agent-greeting.txt

@@ -0,0 +1,14 @@
+Hello Agent, welcome to dust!
+
+CRITICAL: You MUST run exactly ONE of the commands below before doing anything else.
+
+Based on what the user asked, run the matching command NOW:
+
+1. "work", "go", "pick a task", "implement a task" → `{{bin}} agent pick task`
+2. "implement [task name]" → `{{bin}} agent implement task`
+3. "task: ..." or "add a task ..." → `{{bin}} agent new task`
+4. "goal: ..." or "add a goal ..." → `{{bin}} agent new goal`
+5. A vague idea about a potential change → `{{bin}} agent new idea`
+6. Anything else → `{{bin}} agent help`
+
+Do NOT proceed without running one of these commands.

package/templates/templates/agent-help.txt

@@ -0,0 +1,35 @@
+## Dust Agent Guide
+
+Dust is a lightweight planning system. The `.dust/` directory contains:
+
+- **goals/** - Guiding principles (stable, rarely change)
+- **ideas/** - Vague proposals (convert to tasks when ready)
+- **tasks/** - Actionable work with definitions of done
+- **facts/** - Documentation of current system state
+
+**Key commands:**
+- `{{bin}} check` - Run quality gates (do this before and after work)
+- `{{bin}} next` - Show tasks ready to work on
+- `{{bin}} list [type]` - List artifacts (tasks, ideas, goals, facts)
+- `{{bin}} lint markdown` - Check .dust/ files for errors
+
+**Workflow:** Pick a task, implement it, delete the task file, commit atomically.
+
+For focused guidance, run:
+- `{{bin}} agent pick task` - Pick the next task to work on
+- `{{bin}} agent implement task` - Implement a task
+- `{{bin}} agent new task` - Create a new task
+- `{{bin}} agent new goal` - Create a new goal
+- `{{bin}} agent new idea` - Working with ideas
+- `{{bin}} agent understand goals` - Understanding goals
+
+### 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/templates/agent-implement-task.txt

@@ -0,0 +1,24 @@
+## Implement a Task
+
+Follow these steps:
+
+1. {{installDependenciesHint}} (unless already installed)
+2. Run `{{bin}} check` to verify the project is in a good state
+3. Implement the task
+{{#unless hooksInstalled}}4. Run `{{bin}} check` before committing
+5.{{/unless}}{{#if hooksInstalled}}4.{{/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 any ideas that were fully realized
+
+   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}}6.{{/unless}}{{#if hooksInstalled}}5.{{/if}} Push your commit to the remote repository
+
+Keep your change small and focused. One task, one commit.

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

@@ -0,0 +1,21 @@
+## Adding a New Goal
+
+Goals are guiding principles that persist across tasks. They define the "why" behind the work.
+
+Follow these steps:
+
+1. Run `{{bin}} list 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/templates/agent-new-idea.txt

@@ -0,0 +1,11 @@
+## Adding a New Idea
+
+Follow these steps:
+
+1. Run `{{bin}} list 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. 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

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

@@ -0,0 +1,20 @@
+## Adding a New Task
+
+Follow these steps:
+
+1. Run `{{bin}} list ideas` to see all existing ideas
+2. Determine which ideas (if any) should be:
+   - **Deleted** - if the new task fully covers the idea
+   - **Updated** - if the idea's scope changes as a result of the task
+3. Create a new markdown file in `.dust/tasks/` with a descriptive kebab-case name (e.g., `add-user-authentication.md`)
+4. Add a title as the first line using an H1 heading (e.g., `# Add user authentication`)
+5. Write a comprehensive description of what needs to be done with technical details and references to relevant files
+6. Add a `## Goals` section with links to relevant goals this task supports (e.g., `- [Goal Name](../goals/goal-name.md)`)
+7. Add a `## Blocked by` section listing any tasks that must complete first, or `(none)` if there are no blockers
+8. Add a `## Definition of done` section with a checklist of completion criteria using `- [ ]` for each item
+9. Run `{{bin}} lint markdown` to catch any issues with the task format
+10. Create a single atomic commit with a message in the format "Add task: <title>" that includes:
+    - The new task file
+    - Deletion of any ideas that were fully realized
+    - Updates to any ideas whose scope changed
+11. Push your commit to the remote repository

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

@@ -0,0 +1,7 @@
+## 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}} agent implement task` for instructions about how to implement

package/templates/templates/agent-understand-goals.txt

@@ -0,0 +1,9 @@
+## Understanding Goals
+
+**List goals:** `{{bin}} list goals`
+
+Goals live in `.dust/goals/` as markdown files. They define the project's guiding principles and priorities.
+
+Goals are linked from tasks to show which principles each task supports. When working on a task, you can read its linked goals for context on why the work matters.
+
+Goals are stable—they rarely change. Tasks come and go, but goals persist.

package/templates/templates/agents-md.txt

@@ -0,0 +1,5 @@
+# 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/templates/claude-md.txt

@@ -0,0 +1,5 @@
+# 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/templates/help.txt

@@ -0,0 +1,27 @@
+💨 dust - A workflow tool for keeping AI coding agents on track.
+
+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)
+  list tasks                List tasks (actionable work with definitions of done)
+  list ideas                List ideas (vague proposals, convert to tasks when ready)
+  list goals                List goals (guiding principles, stable, rarely change)
+  list 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
+  agent help                Show agent guidance
+  agent pick task           Pick the next task to work on
+  agent implement task      Implement a task
+  agent new task            Create a new task
+  agent new goal            Create a new goal
+  agent new idea            Working with ideas
+  agent understand goals    Understanding goals
+  loop                      Run continuous Claude iteration on tasks
+  pre-push                  Git pre-push hook validation
+  help                      Show this help message
+
+🤖 If you are an AI agent, run `{{bin}} agent` to get started!