@joshski/dust 0.1.3 → 0.1.5

package/dist/dust.js

@@ -284,20 +284,50 @@ var DEFAULT_GOAL = `# Project Goal
 
 Describe the high-level mission of this project.
 `;
+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.`;
   if (fs.exists(dustPath)) {
-    ctx.stderr("Error: .dust directory already exists");
-    return { exitCode: 1 };
-  }
-  await fs.mkdir(dustPath, { recursive: true });
-  for (const dir of DUST_DIRECTORIES) {
-    await fs.mkdir(`${dustPath}/${dir}`, { recursive: true });
+    ctx.stdout("Note: .dust directory already exists, skipping creation");
+  } else {
+    await fs.mkdir(dustPath, { recursive: true });
+    for (const dir of DUST_DIRECTORIES) {
+      await fs.mkdir(`${dustPath}/${dir}`, { recursive: true });
+    }
+    await fs.writeFile(`${dustPath}/goals/project-goal.md`, DEFAULT_GOAL);
+    ctx.stdout("Initialized Dust repository in .dust/");
+    ctx.stdout(`Created directories: ${DUST_DIRECTORIES.join(", ")}`);
+    ctx.stdout("Created initial goal: .dust/goals/project-goal.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 });
+    await fs.writeFile(claudeMdPath, claudeContent);
+    ctx.stdout("Created CLAUDE.md with agent instructions");
+  }
+  const agentsMdPath = `${ctx.cwd}/AGENTS.md`;
+  if (fs.exists(agentsMdPath)) {
+    ctx.stdout(`Warning: AGENTS.md already exists. Consider adding: "${agentInstruction}"`);
+  } else {
+    const agentsContent = loadTemplate("agents-md", { runner });
+    await fs.writeFile(agentsMdPath, agentsContent);
+    ctx.stdout("Created AGENTS.md with agent instructions");
   }
-  await fs.writeFile(`${dustPath}/goals/project-goal.md`, DEFAULT_GOAL);
-  ctx.stdout("Initialized Dust repository in .dust/");
-  ctx.stdout(`Created directories: ${DUST_DIRECTORIES.join(", ")}`);
-  ctx.stdout("Created initial goal: .dust/goals/project-goal.md");
   return { exitCode: 0 };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joshski/dust",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "A lightweight planning system for human-AI collaboration",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "templates"
   ],
   "repository": {
     "type": "git",
@@ -23,7 +24,7 @@
   "author": "joshski",
   "license": "MIT",
   "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",
+    "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"
   },

package/templates/agent-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/agent-greeting.txt

@@ -0,0 +1,11 @@
+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:
+
+- 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`

package/templates/agent-help.txt

@@ -0,0 +1,23 @@
+## 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
+- **hooks/** - Quality gate scripts
+
+**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}} validate` - Check .dust/ files for errors
+
+**Workflow:** Pick a task, implement it, delete the task file, commit atomically.
+
+For focused guidance, run:
+- `{{bin}} agent work` - Work on the next task
+- `{{bin}} agent tasks` - Task management
+- `{{bin}} agent goals` - Understanding goals
+- `{{bin}} agent ideas` - Working with ideas

package/templates/agent-ideas.txt

@@ -0,0 +1,13 @@
+## Working with Ideas
+
+**List ideas:** `{{bin}} list ideas`
+
+Ideas live in `.dust/ideas/` as markdown files. They are intentionally vague proposals for future work.
+
+**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
+
+Ideas are cheap to create and easy to discard. Not every idea becomes a task.

package/templates/agent-tasks.txt

@@ -0,0 +1,15 @@
+## Task Management
+
+**List 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
+
+A task is ready when "Blocked by" is empty or says "(none)".
+
+**Creating tasks:** Write a new markdown file in `.dust/tasks/` following the format above.
+
+**Completing tasks:** Delete the task file in your commit after implementation.

package/templates/agent-work.txt

@@ -0,0 +1,16 @@
+## Work on the Next Task
+
+Follow these steps:
+
+1. Run `{{bin}} check` to verify the project is in a good state
+2. Run `{{bin}} next` to see available tasks
+3. Pick ONE task and read its file to understand the requirements
+4. Implement the task, checking off items in "Definition of done"
+5. Run `{{bin}} check` before committing
+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
+
+Keep your change small and focused. One task, one commit.

package/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 `{{runner}} dust agent` when you start working in this repository.

package/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 `{{runner}} dust agent` when you start working in this repository.

package/templates/help.txt

@@ -0,0 +1,82 @@
+dust - A lightweight planning system for human-AI collaboration
+
+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)
+  check             Run project-defined quality gate hook
+  agent [cmd]       Agent-specific guidance (work, tasks, goals, ideas, help)
+  help              Show this help message
+
+Examples:
+  {{bin}} init
+  {{bin}} prompt work
+  {{bin}} validate
+  {{bin}} list tasks
+  {{bin}} list
+  {{bin}} next
+  {{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.