@joshski/dust 0.1.41 → 0.1.43

package/dist/dust.js

@@ -1,10 +1,149 @@
 #!/usr/bin/env node
 // lib/cli/run.ts
-import { existsSync } from "node:fs";
+import { existsSync, statSync as statSync2 } from "node:fs";
 import { chmod as chmod2, mkdir as mkdir2, readdir as readdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
 
 // lib/config/settings.ts
 import { join } from "node:path";
+var KNOWN_SETTINGS_KEYS = new Set([
+  "dustCommand",
+  "checks",
+  "extraDirectories",
+  "installCommand",
+  "eventsUrl"
+]);
+var KNOWN_CHECK_KEYS = new Set([
+  "name",
+  "command",
+  "hints",
+  "timeoutMilliseconds"
+]);
+function validateSettingsJson(content) {
+  const violations = [];
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch (error) {
+    violations.push({
+      message: `Invalid JSON: ${error.message}`
+    });
+    return violations;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    violations.push({
+      message: "settings.json must be a JSON object"
+    });
+    return violations;
+  }
+  const settings = parsed;
+  for (const key of Object.keys(settings)) {
+    if (!KNOWN_SETTINGS_KEYS.has(key)) {
+      violations.push({
+        message: `Unknown key "${key}" in settings.json. Known keys: ${[...KNOWN_SETTINGS_KEYS].sort().join(", ")}`
+      });
+    }
+  }
+  if ("checks" in settings) {
+    if (!Array.isArray(settings.checks)) {
+      violations.push({
+        message: '"checks" must be an array'
+      });
+    } else {
+      for (let i = 0;i < settings.checks.length; i++) {
+        const check = settings.checks[i];
+        const checkPath = `checks[${i}]`;
+        if (typeof check === "string") {
+          continue;
+        }
+        if (typeof check !== "object" || check === null || Array.isArray(check)) {
+          violations.push({
+            message: `${checkPath} must be a string or object`
+          });
+          continue;
+        }
+        const checkObj = check;
+        for (const key of Object.keys(checkObj)) {
+          if (!KNOWN_CHECK_KEYS.has(key)) {
+            violations.push({
+              message: `Unknown key "${key}" in ${checkPath}. Known keys: ${[...KNOWN_CHECK_KEYS].sort().join(", ")}`
+            });
+          }
+        }
+        if (!("name" in checkObj)) {
+          violations.push({
+            message: `${checkPath} is missing required field "name"`
+          });
+        } else if (typeof checkObj.name !== "string") {
+          violations.push({
+            message: `${checkPath}.name must be a string`
+          });
+        }
+        if (!("command" in checkObj)) {
+          violations.push({
+            message: `${checkPath} is missing required field "command"`
+          });
+        } else if (typeof checkObj.command !== "string") {
+          violations.push({
+            message: `${checkPath}.command must be a string`
+          });
+        }
+        if ("hints" in checkObj) {
+          if (!Array.isArray(checkObj.hints)) {
+            violations.push({
+              message: `${checkPath}.hints must be an array of strings`
+            });
+          } else {
+            for (let j = 0;j < checkObj.hints.length; j++) {
+              if (typeof checkObj.hints[j] !== "string") {
+                violations.push({
+                  message: `${checkPath}.hints[${j}] must be a string`
+                });
+              }
+            }
+          }
+        }
+        if ("timeoutMilliseconds" in checkObj) {
+          if (typeof checkObj.timeoutMilliseconds !== "number" || checkObj.timeoutMilliseconds <= 0) {
+            violations.push({
+              message: `${checkPath}.timeoutMilliseconds must be a positive number`
+            });
+          }
+        }
+      }
+    }
+  }
+  if ("extraDirectories" in settings) {
+    if (!Array.isArray(settings.extraDirectories)) {
+      violations.push({
+        message: '"extraDirectories" must be an array of strings'
+      });
+    } else {
+      for (let i = 0;i < settings.extraDirectories.length; i++) {
+        if (typeof settings.extraDirectories[i] !== "string") {
+          violations.push({
+            message: `extraDirectories[${i}] must be a string`
+          });
+        }
+      }
+    }
+  }
+  if ("dustCommand" in settings && typeof settings.dustCommand !== "string") {
+    violations.push({
+      message: '"dustCommand" must be a string'
+    });
+  }
+  if ("installCommand" in settings && typeof settings.installCommand !== "string") {
+    violations.push({
+      message: '"installCommand" must be a string'
+    });
+  }
+  if ("eventsUrl" in settings && typeof settings.eventsUrl !== "string") {
+    violations.push({
+      message: '"eventsUrl" must be a string'
+    });
+  }
+  return violations;
+}
 var DEFAULT_SETTINGS = {
   dustCommand: "npx dust",
   installCommand: "npm install"
@@ -110,36 +249,18 @@ async function loadSettings(cwd, fileSystem) {
   }
 }
 
-// lib/cli/templates.ts
-import { readFileSync } from "node:fs";
-import { dirname, join as join2 } from "node:path";
-import { fileURLToPath } from "node:url";
-var __dirname2 = dirname(fileURLToPath(import.meta.url));
-var templatesDir = join2(__dirname2, "../templates");
-function isTruthy(value) {
-  return value !== undefined && value !== "" && value !== "false";
-}
-function processConditionals(content, variables) {
-  let result = content.replace(/\{\{#if (\w+)\}\}([\s\S]*?)\{\{\/if\}\}/g, (_, varName, block) => {
-    return isTruthy(variables[varName]) ? block : "";
-  });
-  result = result.replace(/\{\{#unless (\w+)\}\}([\s\S]*?)\{\{\/unless\}\}/g, (_, varName, block) => {
-    return !isTruthy(variables[varName]) ? block : "";
-  });
-  return result;
-}
-function loadTemplate(name, variables = {}) {
-  const templatePath = join2(templatesDir, `${name}.txt`);
-  let content = readFileSync(templatePath, "utf-8");
-  content = processConditionals(content, variables);
-  for (const [key, value] of Object.entries(variables)) {
-    content = content.replaceAll(`{{${key}}}`, value);
-  }
-  return content;
+// lib/cli/dedent.ts
+function dedent(strings, ...values) {
+  const result = strings.reduce((acc, part, index) => acc + part + (values[index] ?? ""), "");
+  const lines = result.split(`
+`);
+  const indent = lines.filter((line) => line.trim()).reduce((min, line) => Math.min(min, line.match(/^\s*/)[0].length), Number.POSITIVE_INFINITY);
+  return lines.map((line) => line.slice(indent)).join(`
+`).trim();
 }
 
 // lib/cli/commands/agent-shared.ts
-import { join as join4 } from "node:path";
+import { join as join3 } from "node:path";
 
 // lib/agents/detection.ts
 function detectAgent(env = process.env) {
@@ -156,7 +277,7 @@ function detectAgent(env = process.env) {
 }
 
 // lib/git/hooks.ts
-import { join as join3 } from "node:path";
+import { join as join2 } from "node:path";
 var DUST_HOOK_START = "# BEGIN DUST HOOK";
 var DUST_HOOK_END = "# END DUST HOOK";
 function generateHookContent(dustCommand) {
@@ -189,9 +310,9 @@ function removeDustSection(content) {
 `).trim();
 }
 function createHooksManager(cwd, fileSystem, settings) {
-  const gitDir = join3(cwd, ".git");
-  const hooksDir = join3(gitDir, "hooks");
-  const prePushPath = join3(hooksDir, "pre-push");
+  const gitDir = join2(cwd, ".git");
+  const hooksDir = join2(gitDir, "hooks");
+  const prePushPath = join2(hooksDir, "pre-push");
   return {
     isGitRepo: () => fileSystem.exists(gitDir),
     isHookInstalled: async () => {
@@ -286,7 +407,7 @@ ${newHookContent}
 
 // lib/cli/commands/agent-shared.ts
 async function loadAgentInstructions(cwd, fileSystem, agentType) {
-  const instructionsPath = join4(cwd, ".dust", "config", "agents", `${agentType}.md`);
+  const instructionsPath = join3(cwd, ".dust", "config", "agents", `${agentType}.md`);
   if (!fileSystem.exists(instructionsPath)) {
     return "";
   }
@@ -297,23 +418,27 @@ async function loadAgentInstructions(cwd, fileSystem, agentType) {
     return "";
   }
 }
-function templateVariables(settings, hooksInstalled, env = process.env) {
+function templateVariables(settings, hooksInstalled, env = process.env, options) {
   const agent = detectAgent(env);
+  const hasIdeaFile = options?.hasIdeaFile ?? true;
   return {
     bin: settings.dustCommand,
     agentName: agent.name,
-    hooksInstalled: hooksInstalled ? "true" : "false",
-    isClaudeCodeWeb: agent.type === "claude-code-web" ? "true" : ""
+    hooksInstalled,
+    isClaudeCodeWeb: agent.type === "claude-code-web",
+    hasIdeaFile
   };
 }
-async function templateVariablesWithInstructions(cwd, fileSystem, settings, hooksInstalled, env = process.env) {
+async function templateVariablesWithInstructions(cwd, fileSystem, settings, hooksInstalled, env = process.env, options) {
   const agent = detectAgent(env);
   const agentInstructions = await loadAgentInstructions(cwd, fileSystem, agent.type);
+  const hasIdeaFile = options?.hasIdeaFile ?? true;
   return {
     bin: settings.dustCommand,
     agentName: agent.name,
-    hooksInstalled: hooksInstalled ? "true" : "false",
-    isClaudeCodeWeb: agent.type === "claude-code-web" ? "true" : "",
+    hooksInstalled,
+    isClaudeCodeWeb: agent.type === "claude-code-web",
+    hasIdeaFile,
     agentInstructions
   };
 }
@@ -336,6 +461,39 @@ async function manageGitHooks(dependencies) {
 }
 
 // lib/cli/commands/agent.ts
+function agentGreeting(vars) {
+  const instructions = vars.agentInstructions ? `
+---
+
+${vars.agentInstructions}` : "";
+  return dedent`
+    🤖 Hello ${vars.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** → \`${vars.bin} pick task\`
+       User wants to start working. Examples: "work", "go", "pick a task", "what's next?"
+
+    2. **Implement a specific task** → \`${vars.bin} focus "<task name>"\`
+       User mentions a particular task by name. Examples: "implement the auth task", "work on caching"
+
+    3. **Capture a new task** → \`${vars.bin} new task\`
+       User has concrete work to add. Keywords: "task: ..." or "add a task ..."
+
+    4. **Capture a new goal** → \`${vars.bin} new goal\`
+       User has a higher-level objective to add. Keywords: "goal: ..." or "add a goal ..."
+
+    5. **Capture a vague idea** → \`${vars.bin} new idea\`
+       User has a rough idea that might become work later. Keywords: "idea: ..." or "add an idea ..."
+
+    6. **Unclear** → \`${vars.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.${instructions}
+  `;
+}
 async function agent(dependencies, env = process.env) {
   const { context, fileSystem, settings } = dependencies;
   if (env.DUST_SKIP_AGENT === "1") {
@@ -343,15 +501,13 @@ async function agent(dependencies, env = process.env) {
     return { exitCode: 0 };
   }
   const hooksInstalled = await manageGitHooks(dependencies);
-  const vars = await templateVariablesWithInstructions(context.cwd, fileSystem, settings, hooksInstalled);
-  context.stdout(loadTemplate("agent-greeting", vars));
+  const vars = await templateVariablesWithInstructions(context.cwd, fileSystem, settings, hooksInstalled, env);
+  context.stdout(agentGreeting(vars));
   return { exitCode: 0 };
 }
 
 // lib/cli/commands/audit.ts
-import { readdirSync, readFileSync as readFileSync2 } from "node:fs";
-import { basename, dirname as dirname2, join as join5 } from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { basename } from "node:path";
 
 // lib/markdown/markdown-utilities.ts
 function extractTitle(content) {
@@ -405,6 +561,286 @@ function extractOpeningSentence(content) {
   return sentenceMatch[1];
 }
 
+// lib/audits/stock-audits.ts
+function agentDeveloperExperience() {
+  return dedent`
+    # Agent Developer Experience
+
+    Review the codebase to ensure agents have everything they need to operate effectively. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues you identify, avoiding duplication.
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **Context window efficiency** - Are files small and well-organized?
+    2. **Test coverage** - Can agents verify correctness through tests?
+    3. **Feedback loop speed** - How fast are checks and tests?
+    4. **Debugging tools** - Can agents diagnose issues without trial and error?
+    5. **Structured logging** - Is system behavior observable through logs?
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Reviewed file sizes and organization for context window fit
+    - [ ] Verified test coverage is sufficient for agent verification
+    - [ ] Measured feedback loop speed (time from change to check result)
+    - [ ] Confirmed debugging tools and structured logging are in place
+    - [ ] Proposed ideas for any improvements identified
+  `;
+}
+function deadCode() {
+  return dedent`
+    # Dead Code
+
+    Find and remove unused code to improve maintainability and reduce bundle size. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues you identify, avoiding duplication.
+
+    ## 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
+
+    ## 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
+    - [ ] Proposed ideas for any dead code worth removing
+  `;
+}
+function factsVerification() {
+  return dedent`
+    # Facts Verification
+
+    Review \`.dust/facts/\` to ensure documented facts match current reality. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues you identify, avoiding duplication.
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **Accuracy** - Do documented facts reflect the current codebase?
+    2. **Completeness** - Are important implementation details documented?
+    3. **Staleness** - Have facts become outdated due to recent changes?
+    4. **Relevance** - Are all facts still useful for understanding the project?
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Read each fact file in \`.dust/facts/\`
+    - [ ] Verified each fact against current codebase
+    - [ ] Identified outdated or inaccurate facts
+    - [ ] Listed missing facts that would help agents
+    - [ ] Updated or removed stale facts
+    - [ ] Proposed ideas for any facts improvements needed
+  `;
+}
+function ideasFromCommits() {
+  return dedent`
+    # Ideas from Commits
+
+    Review recent commit history to identify follow-up improvement ideas. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues or opportunities you identify, avoiding duplication.
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **Technical debt** - Did recent work introduce shortcuts?
+    2. **Incomplete work** - Are there TODO comments or partial implementations?
+    3. **Pattern opportunities** - Can recent changes be generalized?
+    4. **Test gaps** - Do recent changes have adequate test coverage?
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Reviewed commits from the last 20 commits
+    - [ ] Identified patterns or shortcuts worth addressing
+    - [ ] Listed TODO comments added in recent commits
+    - [ ] Noted areas where changes could be generalized
+    - [ ] Proposed follow-up ideas for any issues identified
+  `;
+}
+function ideasFromGoals() {
+  return dedent`
+    # Ideas from Goals
+
+    Review \`.dust/goals/\` to generate new improvement ideas. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues or opportunities you identify, avoiding duplication.
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **Unmet goals** - Which goals lack supporting work?
+    2. **Gap analysis** - Where does the codebase fall short of goals?
+    3. **New opportunities** - What work would better achieve each goal?
+    4. **Goal alignment** - Are current tasks aligned with stated goals?
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Read each goal file in \`.dust/goals/\`
+    - [ ] Analyzed codebase for alignment with each goal
+    - [ ] Listed gaps between current state and goal intent
+    - [ ] Proposed new ideas for unmet or underserved goals
+  `;
+}
+function performanceReview() {
+  return dedent`
+    # Performance Review
+
+    Review the application for performance issues and optimization opportunities. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues you identify, avoiding duplication.
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **Startup time** - How fast does the application start?
+    2. **Command latency** - How responsive are CLI commands?
+    3. **Memory usage** - Is memory being used efficiently?
+    4. **Build performance** - How fast is the build process?
+    5. **Test speed** - Are tests running efficiently?
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Measured startup time for common commands
+    - [ ] Profiled memory usage during typical operations
+    - [ ] Identified slow commands or operations
+    - [ ] Listed optimization opportunities by impact
+    - [ ] Proposed ideas for any performance improvements identified
+  `;
+}
+function securityReview() {
+  return dedent`
+    # Security Review
+
+    Review the codebase for common security vulnerabilities and misconfigurations. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues you identify, avoiding duplication.
+
+    ## 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
+
+    ## 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
+    - [ ] Proposed ideas for any security issues found
+  `;
+}
+function staleIdeas() {
+  return dedent`
+    # Stale Ideas
+
+    Review \`.dust/ideas/\` to identify ideas that have become stale or irrelevant. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues you identify, avoiding duplication.
+
+    ## Scope
+
+    Focus on these areas:
+
+    1. **Age** - Ideas unchanged for many commits may need attention
+    2. **Relevance** - Has the project evolved past the idea?
+    3. **Actionability** - Can the idea be converted to a task?
+    4. **Duplication** - Are there overlapping or redundant ideas?
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] Listed all ideas with their last modification date
+    - [ ] Identified ideas unchanged for 50+ commits
+    - [ ] Reviewed each stale idea for current relevance
+    - [ ] Promoted actionable ideas to tasks
+    - [ ] Deleted ideas that are no longer relevant
+  `;
+}
+function testCoverage() {
+  return dedent`
+    # Test Coverage
+
+    Identify untested code paths and areas that need additional test coverage. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues you identify, avoiding duplication.
+
+    ## 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
+
+    ## 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
+    - [ ] Proposed ideas for any test coverage gaps identified
+  `;
+}
+var stockAuditFunctions = {
+  "agent-developer-experience": agentDeveloperExperience,
+  "dead-code": deadCode,
+  "facts-verification": factsVerification,
+  "ideas-from-commits": ideasFromCommits,
+  "ideas-from-goals": ideasFromGoals,
+  "performance-review": performanceReview,
+  "security-review": securityReview,
+  "stale-ideas": staleIdeas,
+  "test-coverage": testCoverage
+};
+function loadStockAudits() {
+  return Object.entries(stockAuditFunctions).sort(([a], [b]) => a.localeCompare(b)).map(([name, render]) => {
+    const template = render();
+    const description = extractOpeningSentence(template);
+    return { name, description, template };
+  });
+}
+
 // lib/cli/colors.ts
 var ANSI_COLORS = {
   reset: "\x1B[0m",
@@ -439,17 +875,6 @@ function getColors() {
 }
 
 // lib/cli/commands/audit.ts
-var __dirname3 = dirname2(fileURLToPath2(import.meta.url));
-var stockAuditsDir = join5(__dirname3, "../../templates/audits");
-function loadStockAudits() {
-  const files = readdirSync(stockAuditsDir).filter((f) => f.endsWith(".md")).sort();
-  return files.map((file) => {
-    const template = readFileSync2(join5(stockAuditsDir, file), "utf-8");
-    const name = basename(file, ".md");
-    const description = extractOpeningSentence(template);
-    return { name, description, template };
-  });
-}
 function transformAuditContent(content) {
   const titleMatch = content.match(/^#\s+(.+)$/m);
   if (!titleMatch) {
@@ -544,13 +969,13 @@ async function audit(dependencies) {
 
 // lib/cli/commands/bucket.ts
 import { spawn as nodeSpawn3 } from "node:child_process";
-import { accessSync } from "node:fs";
+import { accessSync, statSync } from "node:fs";
 import { chmod, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { createServer as httpCreateServer } from "node:http";
 import { homedir, tmpdir } from "node:os";
 
 // lib/bucket/auth.ts
-import { join as join6 } from "node:path";
+import { join as join4 } from "node:path";
 var CREDENTIALS_DIR = ".dust";
 var CREDENTIALS_FILE = "credentials.json";
 var AUTH_TIMEOUT_MS = 120000;
@@ -559,7 +984,7 @@ function getDustbucketHost() {
   return process.env.DUST_BUCKET_HOST || DEFAULT_DUSTBUCKET_HOST;
 }
 function credentialsPath(homeDir) {
-  return join6(homeDir, CREDENTIALS_DIR, CREDENTIALS_FILE);
+  return join4(homeDir, CREDENTIALS_DIR, CREDENTIALS_FILE);
 }
 async function loadStoredToken(fileSystem, homeDir) {
   const path = credentialsPath(homeDir);
@@ -572,7 +997,7 @@ async function loadStoredToken(fileSystem, homeDir) {
   }
 }
 async function storeToken(fileSystem, homeDir, token) {
-  const dirPath = join6(homeDir, CREDENTIALS_DIR);
+  const dirPath = join4(homeDir, CREDENTIALS_DIR);
   await fileSystem.mkdir(dirPath, { recursive: true });
   await fileSystem.writeFile(credentialsPath(homeDir), JSON.stringify({ token }));
 }
@@ -694,7 +1119,7 @@ function getLogLines(buffer) {
 }
 
 // lib/bucket/repository.ts
-import { join as join7 } from "node:path";
+import { join as join6 } from "node:path";
 
 // lib/agent-events.ts
 function rawEventToAgentEvent(rawEvent) {
@@ -1116,12 +1541,28 @@ async function run(prompt, options = {}, dependencies = defaultRunnerDependencie
 
 // lib/cli/commands/loop.ts
 import { spawn as nodeSpawn2 } from "node:child_process";
+import { readFileSync } from "node:fs";
+import os from "node:os";
+import { dirname, join as join5 } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// lib/workflow-tasks.ts
+var IDEA_TRANSITION_PREFIXES = [
+  "Refine Idea: ",
+  "Decompose Idea: ",
+  "Shelve Idea: "
+];
+var BUILD_IDEA_PREFIX = "Build Idea: ";
+function titleToFilename(title) {
+  return `${title.toLowerCase().replace(/\./g, "-").replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "")}.md`;
+}
 
 // lib/cli/commands/focus.ts
-function buildImplementationInstructions(bin, hooksInstalled) {
+function buildImplementationInstructions(bin, hooksInstalled, taskTitle) {
   const steps = [];
   let step = 1;
-  steps.push(`Note: Skip the \`${bin} agent\` step - your task has already been specified below.`, "");
+  const hasIdeaFile = !taskTitle?.startsWith(BUILD_IDEA_PREFIX);
+  steps.push(`Note: Do NOT run \`${bin} agent\`.`, "");
   steps.push(`${step}. Run \`${bin} check\` to verify the project is in a good state`);
   step++;
   steps.push(`${step}. Implement the task`);
@@ -1130,7 +1571,16 @@ function buildImplementationInstructions(bin, 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", "   ```", "");
+  const commitMessageLine = taskTitle ? `   Use this exact commit message: "${taskTitle}". Do not add any prefix.` : '   Use the task title as the commit message. Do not add prefixes like "Complete task:" - use the title directly.';
+  const commitItems = [
+    "   - All implementation changes",
+    "   - Deletion of the completed task file",
+    "   - Updates to any facts that changed"
+  ];
+  if (hasIdeaFile) {
+    commitItems.push("   - Deletion of the idea file that spawned this task (if remaining scope exists, create new ideas for it)");
+  }
+  steps.push(`${step}. Create a single atomic commit that includes:`, ...commitItems, "", commitMessageLine, "");
   step++;
   steps.push(`${step}. Push your commit to the remote repository`);
   steps.push("");
@@ -1234,6 +1684,29 @@ async function next(dependencies) {
 }
 
 // lib/cli/commands/loop.ts
+var __dirname2 = dirname(fileURLToPath(import.meta.url));
+function getDustVersion() {
+  const candidates = [
+    join5(__dirname2, "../../../package.json"),
+    join5(__dirname2, "../package.json")
+  ];
+  for (const candidate of candidates) {
+    try {
+      const packageJson = JSON.parse(readFileSync(candidate, "utf-8"));
+      return packageJson.version ?? "unknown";
+    } catch {}
+  }
+  return "unknown";
+}
+function getEnvironmentContext(cwd) {
+  return {
+    machineName: os.hostname(),
+    cwd,
+    platform: `${os.platform()} ${os.release()}`,
+    dustVersion: getDustVersion(),
+    runtimeVersion: process.version
+  };
+}
 function formatLoopEvent(event) {
   switch (event.type) {
     case "loop.warning":
@@ -1333,7 +1806,7 @@ async function runOneIteration(dependencies, loopDependencies, onLoopEvent, onAg
       type: "loop.sync_skipped",
       reason: pullResult.message
     });
-    const prompt2 = `Note: Skip the \`dust agent\` step - your task has already been specified below.
+    const prompt2 = `Note: Do NOT run \`dust agent\`.
 
 git pull failed with the following error:
 
@@ -1350,7 +1823,8 @@ Make sure the repository is in a clean state and synced with remote before finis
       title: "Resolving git conflict",
       prompt: prompt2,
       agentType: "claude",
-      purpose: "git-conflict"
+      purpose: "git-conflict",
+      ...getEnvironmentContext(context.cwd)
     });
     try {
       await run2(prompt2, {
@@ -1383,14 +1857,14 @@ Make sure the repository is in a clean state and synced with remote before finis
   onLoopEvent({ type: "loop.tasks_found" });
   const taskContent = await dependencies.fileSystem.readFile(`${dependencies.context.cwd}/${task.path}`);
   const { dustCommand, installCommand = "npm install" } = dependencies.settings;
-  const instructions = buildImplementationInstructions(dustCommand, true);
+  const instructions = buildImplementationInstructions(dustCommand, true, task.title ?? undefined);
   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}\`.
 
@@ -1402,7 +1876,8 @@ ${instructions}`;
     title: task.title ?? task.path,
     prompt,
     agentType: "claude",
-    purpose: "task"
+    purpose: "task",
+    ...getEnvironmentContext(context.cwd)
   });
   try {
     await run2(prompt, {
@@ -1512,7 +1987,7 @@ function parseRepository(data) {
 }
 function getRepoTempPath(repoName, tempDir) {
   const safeName = repoName.replace(/[^a-zA-Z0-9-_]/g, "-");
-  return join7(tempDir, `dust-bucket-${safeName}`);
+  return join6(tempDir, `dust-bucket-${safeName}`);
 }
 async function cloneRepository(repository, targetPath, spawn, context) {
   return new Promise((resolve) => {
@@ -1966,7 +2441,7 @@ function renderTabs(state) {
     const width = name.length + 4;
     if (i === state.selectedIndex) {
       tabs.push({
-        text: `${ANSI.INVERSE} ${dot}${ANSI.INVERSE}${color} ${name} ${ANSI.RESET}`,
+        text: ` ${dot}${color} ${ANSI.INVERSE}${name}${ANSI.RESET} `,
         width
       });
     } else {
@@ -2230,6 +2705,13 @@ function createDefaultBucketDependencies() {
         return false;
       }
     },
+    isDirectory: (path) => {
+      try {
+        return statSync(path).isDirectory();
+      } catch {
+        return false;
+      }
+    },
     readFile: (path) => readFile(path, "utf8"),
     writeFile: (path, content) => writeFile(path, content, "utf8"),
     mkdir: (path, options) => mkdir(path, options).then(() => {}),
@@ -2478,9 +2960,10 @@ function createKeypressHandler(useTUI, state, onQuit, options) {
       onQuit();
   };
 }
-async function resolveToken(commandArgs, authDeps, context) {
-  if (commandArgs[0]) {
-    return commandArgs[0];
+async function resolveToken(authDeps, context) {
+  const envToken = process.env.DUST_BUCKET_TOKEN;
+  if (envToken) {
+    return envToken;
   }
   const stored = await loadStoredToken(authDeps.fileSystem, authDeps.getHomeDir());
   if (stored) {
@@ -2498,8 +2981,8 @@ async function resolveToken(commandArgs, authDeps, context) {
   }
 }
 async function bucket(dependencies, bucketDeps = createDefaultBucketDependencies()) {
-  const { arguments: commandArgs, context, fileSystem } = dependencies;
-  const token = await resolveToken(commandArgs, bucketDeps.auth, context);
+  const { context, fileSystem } = dependencies;
+  const token = await resolveToken(bucketDeps.auth, context);
   if (!token) {
     return { exitCode: 1 };
   }
@@ -2614,22 +3097,11 @@ function runBufferedProcess(spawnFn, command, commandArguments, cwd, shell, time
 }
 
 // lib/cli/commands/lint-markdown.ts
-import { dirname as dirname3, resolve } from "node:path";
-
-// lib/workflow-tasks.ts
-var IDEA_TRANSITION_PREFIXES = [
-  "Refine Idea: ",
-  "Decompose Idea: ",
-  "Shelve Idea: "
-];
-function titleToFilename(title) {
-  return `${title.toLowerCase().replace(/\./g, "-").replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "")}.md`;
-}
-
-// lib/cli/commands/lint-markdown.ts
+import { dirname as dirname2, join as join7, resolve } from "node:path";
 var REQUIRED_HEADINGS = ["## Goals", "## Blocked By", "## Definition of Done"];
 var REQUIRED_GOAL_HEADINGS = ["## Parent Goal", "## Sub-Goals"];
 var SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*\.md$/;
+var EXPECTED_DIRECTORIES = ["goals", "ideas", "tasks", "facts", "config"];
 var MAX_OPENING_SENTENCE_LENGTH = 150;
 function validateFilename(filePath) {
   const parts = filePath.split("/");
@@ -2727,7 +3199,7 @@ function validateLinks(filePath, content, fileSystem) {
   const violations = [];
   const lines = content.split(`
 `);
-  const fileDir = dirname3(filePath);
+  const fileDir = dirname2(filePath);
   for (let i = 0;i < lines.length; i++) {
     const line = lines[i];
     const linkPattern = new RegExp(MARKDOWN_LINK_PATTERN.source, "g");
@@ -2844,7 +3316,7 @@ function validateSemanticLinks(filePath, content) {
   const violations = [];
   const lines = content.split(`
 `);
-  const fileDir = dirname3(filePath);
+  const fileDir = dirname2(filePath);
   let currentSection = null;
   for (let i = 0;i < lines.length; i++) {
     const line = lines[i];
@@ -2927,7 +3399,7 @@ function validateGoalHierarchyLinks(filePath, content) {
   const violations = [];
   const lines = content.split(`
 `);
-  const fileDir = dirname3(filePath);
+  const fileDir = dirname2(filePath);
   let currentSection = null;
   for (let i = 0;i < lines.length; i++) {
     const line = lines[i];
@@ -2977,7 +3449,7 @@ function validateGoalHierarchyLinks(filePath, content) {
 function extractGoalRelationships(filePath, content) {
   const lines = content.split(`
 `);
-  const fileDir = dirname3(filePath);
+  const fileDir = dirname2(filePath);
   const parentGoals = [];
   const subGoals = [];
   let currentSection = null;
@@ -3083,6 +3555,72 @@ async function safeScanDir(glob, dirPath) {
     throw error;
   }
 }
+async function validateContentDirectoryFiles(dirPath, fileSystem) {
+  const violations = [];
+  let entries;
+  try {
+    entries = await fileSystem.readdir(dirPath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  for (const entry of entries) {
+    const entryPath = `${dirPath}/${entry}`;
+    if (entry.startsWith(".")) {
+      violations.push({
+        file: entryPath,
+        message: `Hidden file "${entry}" found in content directory`
+      });
+      continue;
+    }
+    if (fileSystem.isDirectory(entryPath)) {
+      violations.push({
+        file: entryPath,
+        message: `Subdirectory "${entry}" found in content directory (content directories should be flat)`
+      });
+      continue;
+    }
+    if (!entry.endsWith(".md")) {
+      violations.push({
+        file: entryPath,
+        message: `Non-markdown file "${entry}" found in content directory`
+      });
+    }
+  }
+  return violations;
+}
+async function validateDirectoryStructure(dustPath, fileSystem, extraDirectories = []) {
+  const violations = [];
+  let entries;
+  try {
+    entries = await fileSystem.readdir(dustPath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  const allowedDirectories = new Set([
+    ...EXPECTED_DIRECTORIES,
+    ...extraDirectories
+  ]);
+  for (const entry of entries) {
+    const entryPath = `${dustPath}/${entry}`;
+    if (!fileSystem.isDirectory(entryPath)) {
+      continue;
+    }
+    if (!allowedDirectories.has(entry)) {
+      const allowedList = [...allowedDirectories].sort().join(", ");
+      violations.push({
+        file: entryPath,
+        message: `Unexpected directory "${entry}" in .dust/. Allowed directories: ${allowedList}. To allow this directory, add it to "extraDirectories" in .dust/config/settings.json`
+      });
+    }
+  }
+  return violations;
+}
 async function lintMarkdown(dependencies) {
   const { context, fileSystem, globScanner: glob } = dependencies;
   const dustPath = `${context.cwd}/.dust`;
@@ -3094,6 +3632,26 @@ async function lintMarkdown(dependencies) {
   }
   const dustFiles = dustScan.files;
   const violations = [];
+  context.stdout("Validating directory structure...");
+  violations.push(...await validateDirectoryStructure(dustPath, fileSystem, dependencies.settings.extraDirectories));
+  const settingsPath = join7(dustPath, "config", "settings.json");
+  if (fileSystem.exists(settingsPath)) {
+    context.stdout("Validating settings.json...");
+    try {
+      const settingsContent = await fileSystem.readFile(settingsPath);
+      const settingsViolations = validateSettingsJson(settingsContent);
+      for (const sv of settingsViolations) {
+        violations.push({
+          file: settingsPath,
+          message: sv.message
+        });
+      }
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
   context.stdout("Validating links in .dust/...");
   for (const file of dustFiles) {
     if (!file.endsWith(".md"))
@@ -3110,6 +3668,10 @@ async function lintMarkdown(dependencies) {
   }
   const contentDirs = ["goals", "facts", "ideas", "tasks"];
   context.stdout("Validating content files...");
+  for (const dir of contentDirs) {
+    const dirPath = `${dustPath}/${dir}`;
+    violations.push(...await validateContentDirectoryFiles(dirPath, fileSystem));
+  }
   for (const dir of contentDirs) {
     const dirPath = `${dustPath}/${dir}`;
     const { files } = await safeScanDir(glob, dirPath);
@@ -3276,8 +3838,8 @@ async function runValidationCheck(dependencies) {
   });
   const durationMs = Date.now() - startTime;
   return {
-    name: "lint markdown",
-    command: "dust lint markdown",
+    name: "lint",
+    command: "dust lint",
     exitCode: result.exitCode,
     output: outputLines.join(`
 `),
@@ -3374,7 +3936,45 @@ async function check(dependencies, shellRunner = defaultShellRunner) {
 
 // lib/cli/commands/help.ts
 function generateHelpText(settings) {
-  return loadTemplate("help", { bin: settings.dustCommand });
+  const bin = settings.dustCommand;
+  return dedent`
+    💨 dust - Flow state for AI coding agents.
+
+    Usage: ${bin} <command> [options]
+
+    Commands:
+      init              Initialize a new Dust repository
+      lint              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!
+  `;
 }
 async function help(dependencies) {
   dependencies.context.stdout(generateHelpText(dependencies.settings));
@@ -3405,6 +4005,24 @@ var USE_DUST_FACT = `# Use dust for planning
 
 This project uses [dust](https://github.com/joshski/dust) for planning and documentation.
 `;
+function claudeMdContent(dustCommand) {
+  return dedent`
+    # 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.
+  `;
+}
+function agentsMdContent(dustCommand) {
+  return dedent`
+    # 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.
+  `;
+}
 async function init(dependencies) {
   const { context, fileSystem } = dependencies;
   const colors = getColors();
@@ -3443,8 +4061,9 @@ async function init(dependencies) {
   }
   const claudeMdPath = `${context.cwd}/CLAUDE.md`;
   try {
-    const claudeContent = loadTemplate("claude-md", { dustCommand });
-    await fileSystem.writeFile(claudeMdPath, claudeContent, { flag: "wx" });
+    await fileSystem.writeFile(claudeMdPath, claudeMdContent(dustCommand), {
+      flag: "wx"
+    });
     context.stdout(`${colors.green}\uD83D\uDCC4 Created${colors.reset} ${colors.cyan}CLAUDE.md${colors.reset} with agent instructions`);
   } catch (error) {
     if (error.code === "EEXIST") {
@@ -3455,8 +4074,9 @@ async function init(dependencies) {
   }
   const agentsMdPath = `${context.cwd}/AGENTS.md`;
   try {
-    const agentsContent = loadTemplate("agents-md", { dustCommand });
-    await fileSystem.writeFile(agentsMdPath, agentsContent, { flag: "wx" });
+    await fileSystem.writeFile(agentsMdPath, agentsMdContent(dustCommand), {
+      flag: "wx"
+    });
     context.stdout(`${colors.green}\uD83D\uDCC4 Created${colors.reset} ${colors.cyan}AGENTS.md${colors.reset} with agent instructions`);
   } catch (error) {
     if (error.code === "EEXIST") {
@@ -3603,23 +4223,147 @@ async function list(dependencies) {
   return { exitCode: 0 };
 }
 
-// lib/cli/template-command.ts
-var createTemplateCommand = (templateName) => async (dependencies) => {
+// lib/cli/commands/new-goal.ts
+function newGoalInstructions(vars) {
+  const intro = vars.isClaudeCodeWeb ? "Follow these steps. Use a todo list to track your progress." : "Follow these steps:";
+  return dedent`
+    ## Adding a New Goal
+
+    Goals are guiding principles that persist across tasks. They define the "why" behind the work.
+
+    ${intro}
+    1. Run \`${vars.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 \`${vars.bin} lint\` 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
+  `;
+}
+async function newGoal(dependencies) {
   const { context, settings } = dependencies;
   const hooksInstalled = await manageGitHooks(dependencies);
   const vars = templateVariables(settings, hooksInstalled);
-  context.stdout(loadTemplate(templateName, vars));
+  context.stdout(newGoalInstructions(vars));
   return { exitCode: 0 };
-};
-
-// lib/cli/commands/new-goal.ts
-var newGoal = createTemplateCommand("agent-new-goal");
+}
 
 // lib/cli/commands/new-idea.ts
-var newIdea = createTemplateCommand("agent-new-idea");
+function newIdeaInstructions(vars) {
+  return dedent`
+    ## Adding a New Idea
+
+    Follow these steps:
+
+    1. Run \`${vars.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 \`${vars.bin} lint\` 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.)
+  `;
+}
+async function newIdea(dependencies) {
+  const { context, settings } = dependencies;
+  const hooksInstalled = await manageGitHooks(dependencies);
+  const vars = templateVariables(settings, hooksInstalled);
+  context.stdout(newIdeaInstructions(vars));
+  return { exitCode: 0 };
+}
 
 // lib/cli/commands/new-task.ts
-var newTask = createTemplateCommand("agent-new-task");
+function newTaskInstructions(vars) {
+  const steps = [];
+  steps.push("## Adding a New Task");
+  steps.push("");
+  if (vars.isClaudeCodeWeb) {
+    steps.push("Follow these steps to create the task definition, then spawn a sub-agent for implementation.");
+    steps.push("");
+    steps.push("Use a todo list to track your progress through these steps.");
+  } else {
+    steps.push("Follow these steps:");
+  }
+  steps.push("");
+  steps.push(`1. Run \`${vars.bin} ideas\` to see all existing ideas`);
+  steps.push("2. Determine which ideas (if any) should be:");
+  steps.push("   - **Deleted** - if the new task fully covers the idea");
+  steps.push("   - **Updated** - if the idea's scope changes as a result of the task");
+  steps.push("3. Research thoroughly to ensure the task will be clearly defined:");
+  steps.push("   - Explore the codebase to understand existing patterns and relevant files");
+  steps.push("   - Identify exactly which files need to change and how");
+  steps.push("   - Resolve any ambiguities in the requirements before writing the task");
+  steps.push("   - Gather specific technical details (function names, file paths, data structures)");
+  steps.push("   - The goal is a task description with minimal ambiguity at implementation time");
+  steps.push("4. Create a new markdown file in `.dust/tasks/` with a descriptive kebab-case name (e.g., `add-user-authentication.md`)");
+  steps.push("5. Add a title as the first line using an H1 heading (e.g., `# Add user authentication`)");
+  steps.push('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.');
+  steps.push("7. Add a `## Goals` section with links to relevant goals this task supports (e.g., `- [Goal Name](../goals/goal-name.md)`)");
+  steps.push("8. Add a `## Blocked By` section listing any tasks that must complete first, or `(none)` if there are no blockers");
+  steps.push("9. Add a `## Definition of Done` section with a checklist of completion criteria using `- [ ]` for each item");
+  steps.push(`10. Run \`${vars.bin} lint\` to catch any issues with the task format`);
+  steps.push('11. Create a single atomic commit with a message in the format "Add task: <title>" that includes:');
+  steps.push("    - The new task file");
+  steps.push("    - Deletion of the idea file that spawned this task (if remaining scope exists, create new ideas for it)");
+  if (vars.isClaudeCodeWeb) {
+    steps.push(`12. **Start a sub-agent** to implement the task: "Run \`${vars.bin} implement task\` and implement the task in \`.dust/tasks/[task-file].md\`"`);
+  } else {
+    steps.push("12. Push your commit to the remote repository");
+  }
+  return steps.join(`
+`);
+}
+async function newTask(dependencies) {
+  const { context, settings } = dependencies;
+  const hooksInstalled = await manageGitHooks(dependencies);
+  const vars = templateVariables(settings, hooksInstalled);
+  context.stdout(newTaskInstructions(vars));
+  return { exitCode: 0 };
+}
 
 // lib/cli/commands/pick-task.ts
 async function pickTask(dependencies) {
@@ -3791,7 +4535,7 @@ async function facts(dependencies) {
 // lib/cli/main.ts
 var commandRegistry = {
   init,
-  "lint markdown": lintMarkdown,
+  lint: lintMarkdown,
   list,
   tasks,
   goals,
@@ -3860,6 +4604,13 @@ async function main(options) {
 function createFileSystem(primitives) {
   return {
     exists: primitives.existsSync,
+    isDirectory: (path) => {
+      try {
+        return primitives.statSync(path).isDirectory();
+      } catch {
+        return false;
+      }
+    },
     readFile: (path) => primitives.readFile(path, "utf-8"),
     writeFile: (path, content, options) => primitives.writeFile(path, content, {
       encoding: "utf-8",
@@ -3899,4 +4650,4 @@ async function wireEntry(fsPrimitives, processPrimitives, consolePrimitives) {
 }
 
 // lib/cli/run.ts
-await wireEntry({ existsSync, readFile: readFile2, writeFile: writeFile2, mkdir: mkdir2, readdir: readdir2, chmod: chmod2 }, { argv: process.argv, cwd: () => process.cwd(), exit: process.exit }, { log: console.log, error: console.error });
+await wireEntry({ existsSync, statSync: statSync2, readFile: readFile2, writeFile: writeFile2, mkdir: mkdir2, readdir: readdir2, chmod: chmod2 }, { argv: process.argv, cwd: () => process.cwd(), exit: process.exit }, { log: console.log, error: console.error });