chief-clancy 0.1.7 → 0.2.0-beta.2

package/README.md

@@ -2,7 +2,7 @@
 
 **Autonomous, board-driven development for Claude Code.**
 
-[![npm](https://img.shields.io/npm/v/chief-clancy?color=cb3837)](https://www.npmjs.com/package/chief-clancy) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) [![Tests](https://img.shields.io/badge/tests-51%20passing-brightgreen)](./test/) [![GitHub Stars](https://img.shields.io/github/stars/Pushedskydiver/clancy?style=flat)](https://github.com/Pushedskydiver/clancy/stargazers)
+[![npm](https://img.shields.io/npm/v/chief-clancy?color=cb3837)](https://www.npmjs.com/package/chief-clancy) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) [![Tests](https://img.shields.io/badge/tests-55%20passing-brightgreen)](./test/) [![GitHub Stars](https://img.shields.io/github/stars/Pushedskydiver/clancy?style=flat)](https://github.com/Pushedskydiver/clancy/stargazers)
 
 ```bash
 npx chief-clancy
@@ -130,10 +130,13 @@ npx chief-clancy
 # 3. Scan your codebase (or say yes during init)
 /clancy:map-codebase
 
-# 4. Watch your first ticket
+# 4. Preview the first ticket (no changes made)
+/clancy:dry-run
+
+# 5. Watch your first ticket
 /clancy:once
 
-# 5. Go AFK
+# 6. Go AFK
 /clancy:run
 ```
 
@@ -147,6 +150,7 @@ npx chief-clancy
 | `/clancy:run`          | Loop mode — processes tickets until queue is empty or MAX_ITERATIONS hit |
 | `/clancy:run 20`       | Same, override MAX_ITERATIONS to 20 for this session                     |
 | `/clancy:once`         | Pick up one ticket and stop                                              |
+| `/clancy:dry-run`      | Preview next ticket without making changes — no git ops, no Claude call  |
 | `/clancy:status`       | Show next tickets without running — read-only                            |
 | `/clancy:review`       | Score next ticket (0–100%) with actionable recommendations               |
 | `/clancy:logs`         | Format and display `.clancy/progress.txt`                                |
@@ -188,7 +192,7 @@ Clancy also merges a section into your `CLAUDE.md` (or creates one) that tells C
 
 ## Optional enhancements
 
-Set during `/clancy:init` advanced setup, or by editing `.clancy/.env` directly. Use `/clancy:settings` → "Save as defaults" to save non-credential settings to `~/.clancy/defaults.json` — new projects created with `/clancy:init` will inherit them automatically.
+Set during `/clancy:init` advanced setup, or by editing `.clancy/.env` directly.
 
 ### Figma MCP
 
@@ -215,6 +219,15 @@ PLAYWRIGHT_STARTUP_WAIT=15
 
 After implementing a UI ticket, Clancy starts the dev server or Storybook, screenshots, assesses visually, checks the console, and fixes anything wrong before committing.
 
+### Status transitions
+
+```
+CLANCY_STATUS_IN_PROGRESS="In Progress"
+CLANCY_STATUS_DONE="Done"
+```
+
+Clancy automatically moves tickets through your board when it picks up and completes them. Set these to the exact column name shown in your Jira or Linear board. Best-effort — a failed transition never stops the run. Configurable via `/clancy:settings`.
+
 ### Notifications
 
 ```
@@ -405,8 +418,6 @@ lsof -ti:5173 | xargs kill -9   # replace 5173 with your PLAYWRIGHT_DEV_PORT
 
 Or directly: `npx chief-clancy@latest`
 
-The update workflow shows what's changed (changelog diff) and asks for confirmation before overwriting. If you've customised any command or workflow files, they're automatically backed up to `.claude/clancy/local-patches/` before the update — check there to reapply your changes afterwards.
-
 ---
 
 **Uninstalling?**
@@ -415,7 +426,7 @@ The update workflow shows what's changed (changelog diff) and asks for confirmat
 /clancy:uninstall
 ```
 
-Removes slash commands from your chosen location. Cleans up the `<!-- clancy:start -->` / `<!-- clancy:end -->` block from `CLAUDE.md` (or deletes it entirely if Clancy created it) and removes the `.clancy/.env` entry from `.gitignore`. Optionally removes `.clancy/` (credentials and docs).
+Removes slash commands from your chosen location. Optionally removes `.clancy/` (credentials and docs). Never touches `CLAUDE.md`.
 
 ---
 

package/bin/install.js

@@ -8,6 +8,7 @@ const readline = require('readline');
 const PKG = require('../package.json');
 const COMMANDS_SRC = path.join(__dirname, '..', 'src', 'commands');
 const WORKFLOWS_SRC = path.join(__dirname, '..', 'src', 'workflows');
+const HOOKS_SRC = path.join(__dirname, '..', 'hooks');
 
 const homeDir = process.env.HOME || process.env.USERPROFILE;
 if (!homeDir) {
@@ -48,13 +49,6 @@ async function choose(question, options, defaultChoice = 1) {
   return raw.trim() || String(defaultChoice);
 }
 
-const crypto = require('crypto');
-
-function fileHash(filePath) {
-  const content = fs.readFileSync(filePath);
-  return crypto.createHash('sha256').digest('hex', content);
-}
-
 function copyDir(src, dest) {
   // Use lstatSync (not statSync) to detect symlinks — statSync follows them and misreports
   if (fs.existsSync(dest)) {
@@ -71,73 +65,6 @@ function copyDir(src, dest) {
   }
 }
 
-/**
- * Build a manifest of installed files with SHA-256 hashes.
- * Format: { "relative/path.md": "<sha256>", ... }
- */
-function buildManifest(baseDir) {
-  const manifest = {};
-  function walk(dir, prefix) {
-    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-      const full = path.join(dir, entry.name);
-      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
-      if (entry.isDirectory()) {
-        walk(full, rel);
-      } else {
-        const content = fs.readFileSync(full);
-        manifest[rel] = crypto.createHash('sha256').update(content).digest('hex');
-      }
-    }
-  }
-  walk(baseDir, '');
-  return manifest;
-}
-
-/**
- * Detect files modified by the user since last install by comparing
- * current file hashes against the stored manifest. Returns array of
- * { rel, absPath } for modified files.
- */
-function detectModifiedFiles(baseDir, manifestPath) {
-  if (!fs.existsSync(manifestPath)) return [];
-  let manifest;
-  try {
-    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-  } catch { return []; }
-
-  const modified = [];
-  for (const [rel, hash] of Object.entries(manifest)) {
-    const absPath = path.join(baseDir, rel);
-    if (!fs.existsSync(absPath)) continue;
-    const content = fs.readFileSync(absPath);
-    const currentHash = crypto.createHash('sha256').update(content).digest('hex');
-    if (currentHash !== hash) {
-      modified.push({ rel, absPath });
-    }
-  }
-  return modified;
-}
-
-/**
- * Back up modified files to a patches directory alongside the install.
- * Returns the backup directory path if any files were backed up.
- */
-function backupModifiedFiles(modified, patchesDir) {
-  if (modified.length === 0) return null;
-  fs.mkdirSync(patchesDir, { recursive: true });
-  for (const { rel, absPath } of modified) {
-    const backupPath = path.join(patchesDir, rel);
-    fs.mkdirSync(path.dirname(backupPath), { recursive: true });
-    fs.copyFileSync(absPath, backupPath);
-  }
-  // Write metadata so /clancy:update workflow knows what was backed up
-  fs.writeFileSync(
-    path.join(patchesDir, 'backup-meta.json'),
-    JSON.stringify({ backed_up: modified.map(m => m.rel), date: new Date().toISOString() }, null, 2)
-  );
-  return patchesDir;
-}
-
 async function main() {
   console.log('');
   console.log(blue('  ██████╗██╗      █████╗ ███╗   ██╗ ██████╗██╗   ██╗'));
@@ -189,42 +116,14 @@ async function main() {
   console.log(dim(`  Installing to: ${dest}`));
 
   try {
-    // Determine manifest and patches paths (sibling to commands dir)
-    const claudeDir = path.dirname(path.dirname(dest)); // .claude/ (parent of commands/)
-    const manifestPath = path.join(claudeDir, 'clancy', 'manifest.json');
-    const patchesDir = path.join(claudeDir, 'clancy', 'local-patches');
-
     if (fs.existsSync(dest) || fs.existsSync(workflowsDest)) {
       console.log('');
-
-      // Detect user-modified files before overwriting
-      const modified = detectModifiedFiles(dest, manifestPath);
-      const modifiedWorkflows = detectModifiedFiles(workflowsDest, manifestPath.replace('manifest.json', 'workflows-manifest.json'));
-      const allModified = [...modified, ...modifiedWorkflows];
-
-      if (allModified.length > 0) {
-        console.log(blue('  Modified files detected:'));
-        for (const { rel } of allModified) {
-          console.log(`    ${dim('•')} ${rel}`);
-        }
-        console.log('');
-        console.log(dim('  These will be backed up to .claude/clancy/local-patches/'));
-        console.log(dim('  before overwriting. You can reapply them after the update.'));
-        console.log('');
-      }
-
       const overwrite = await ask(blue(`  Commands already exist at ${dest}. Overwrite? [y/N] `));
       if (!overwrite.trim().toLowerCase().startsWith('y')) {
         console.log('\n  Aborted. No files changed.');
         rl.close();
         process.exit(0);
       }
-
-      // Back up modified files before overwriting
-      if (allModified.length > 0) {
-        backupModifiedFiles(allModified, patchesDir);
-        console.log(green(`\n  ✓ ${allModified.length} modified file(s) backed up to local-patches/`));
-      }
     }
 
     copyDir(COMMANDS_SRC, dest);
@@ -251,13 +150,65 @@ async function main() {
     // Write VERSION file so /clancy:doctor and /clancy:update can read the installed version
     fs.writeFileSync(path.join(dest, 'VERSION'), PKG.version);
 
-    // Write manifests so future updates can detect user-modified files
-    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
-    fs.writeFileSync(manifestPath, JSON.stringify(buildManifest(dest), null, 2));
-    fs.writeFileSync(
-      manifestPath.replace('manifest.json', 'workflows-manifest.json'),
-      JSON.stringify(buildManifest(workflowsDest), null, 2)
-    );
+    // Install hooks and register them in Claude settings.json
+    const claudeConfigDir = dest === GLOBAL_DEST
+      ? path.join(homeDir, '.claude')
+      : path.join(process.cwd(), '.claude');
+    const hooksInstallDir = path.join(claudeConfigDir, 'hooks');
+    const settingsFile = path.join(claudeConfigDir, 'settings.json');
+
+    const hookFiles = [
+      'clancy-check-update.js',
+      'clancy-statusline.js',
+      'clancy-context-monitor.js',
+    ];
+
+    try {
+      fs.mkdirSync(hooksInstallDir, { recursive: true });
+      for (const f of hookFiles) {
+        fs.copyFileSync(path.join(HOOKS_SRC, f), path.join(hooksInstallDir, f));
+      }
+      // Force CommonJS resolution for hook files — projects with "type":"module"
+      // in their package.json would otherwise treat .js files as ESM, breaking require().
+      fs.writeFileSync(
+        path.join(hooksInstallDir, 'package.json'),
+        JSON.stringify({ type: 'commonjs' }, null, 2) + '\n'
+      );
+
+      // Merge hooks into settings.json without clobbering existing config
+      let settings = {};
+      if (fs.existsSync(settingsFile)) {
+        try { settings = JSON.parse(fs.readFileSync(settingsFile, 'utf8')); } catch {}
+      }
+      if (!settings.hooks) settings.hooks = {};
+
+      // Helper: add a hook command to an event array if not already present
+      function registerHook(event, command) {
+        if (!settings.hooks[event]) settings.hooks[event] = [];
+        const already = settings.hooks[event].some(
+          h => h.hooks && h.hooks.some(hh => hh.command === command)
+        );
+        if (!already) {
+          settings.hooks[event].push({ hooks: [{ type: 'command', command }] });
+        }
+      }
+
+      const updateScript    = path.join(hooksInstallDir, 'clancy-check-update.js');
+      const statuslineScript = path.join(hooksInstallDir, 'clancy-statusline.js');
+      const monitorScript   = path.join(hooksInstallDir, 'clancy-context-monitor.js');
+
+      registerHook('SessionStart', `node ${updateScript}`);
+      registerHook('PostToolUse',  `node ${monitorScript}`);
+
+      // Statusline: registered as top-level key, not inside hooks
+      if (!settings.statusLine) {
+        settings.statusLine = { type: 'command', command: `node ${statuslineScript}` };
+      }
+
+      fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+    } catch {
+      // Hook registration is best-effort — don't fail the install over it
+    }
 
     console.log('');
     console.log(green('  ✓ Clancy installed successfully.'));
@@ -273,6 +224,7 @@ async function main() {
       ['/clancy:map-codebase', 'Scan codebase with 5 parallel agents'],
       ['/clancy:run',          'Run Clancy in loop mode'],
       ['/clancy:once',         'Pick up one ticket and stop'],
+      ['/clancy:dry-run',      'Preview next ticket without making changes'],
       ['/clancy:status',       'Show next tickets without running'],
       ['/clancy:review',       'Score next ticket and get recommendations'],
       ['/clancy:logs',         'Display progress log'],

package/hooks/clancy-check-update.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// SessionStart hook: check for Clancy updates in the background.
+// Spawns a detached child process to hit npm, writes result to cache.
+// Claude reads the cache via CLAUDE.md instruction — no output from this script.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+
+const homeDir = os.homedir();
+const cwd = process.cwd();
+
+// Resolve the Clancy install dir (local takes priority over global).
+function findInstallDir() {
+  const localVersion = path.join(cwd, '.claude', 'commands', 'clancy', 'VERSION');
+  const globalVersion = path.join(homeDir, '.claude', 'commands', 'clancy', 'VERSION');
+  if (fs.existsSync(localVersion)) return path.dirname(localVersion);
+  if (fs.existsSync(globalVersion)) return path.dirname(globalVersion);
+  return null;
+}
+
+const installDir = findInstallDir();
+if (!installDir) process.exit(0); // Clancy not installed — nothing to check
+
+const cacheDir = path.join(homeDir, '.claude', 'cache');
+const cacheFile = path.join(cacheDir, 'clancy-update-check.json');
+const versionFile = path.join(installDir, 'VERSION');
+
+if (!fs.existsSync(cacheDir)) {
+  try { fs.mkdirSync(cacheDir, { recursive: true }); } catch { process.exit(0); }
+}
+
+// Spawn a detached background process to do the actual npm check.
+// This script returns immediately so it never delays session start.
+const child = spawn(process.execPath, ['-e', `
+  const fs = require('fs');
+  const { execSync } = require('child_process');
+
+  const cacheFile = ${JSON.stringify(cacheFile)};
+  const versionFile = ${JSON.stringify(versionFile)};
+
+  let installed = '0.0.0';
+  try { installed = fs.readFileSync(versionFile, 'utf8').trim(); } catch {}
+
+  let latest = null;
+  try {
+    latest = execSync('npm view chief-clancy version', {
+      encoding: 'utf8',
+      timeout: 10000,
+      windowsHide: true,
+    }).trim();
+  } catch {}
+
+  const result = {
+    update_available: Boolean(latest && installed !== latest),
+    installed,
+    latest: latest || 'unknown',
+    checked: Math.floor(Date.now() / 1000),
+  };
+
+  try { fs.writeFileSync(cacheFile, JSON.stringify(result)); } catch {}
+`], {
+  stdio: 'ignore',
+  windowsHide: true,
+  detached: true,
+});
+
+child.unref();

package/hooks/clancy-context-monitor.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// Clancy Context Monitor — PostToolUse hook.
+// Reads context metrics from the bridge file written by clancy-statusline.js
+// and injects warnings into Claude's conversation when context runs low.
+//
+// Thresholds:
+//   WARNING  (remaining <= 35%): wrap up analysis, move to implementation
+//   CRITICAL (remaining <= 25%): commit current work, log to .clancy/progress.txt, stop
+//
+// Debounce: 5 tool uses between warnings; severity escalation bypasses debounce.
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const WARNING_THRESHOLD  = 35;
+const CRITICAL_THRESHOLD = 25;
+const STALE_SECONDS      = 60;
+const DEBOUNCE_CALLS     = 5;
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const session = data.session_id;
+    if (!session) process.exit(0);
+
+    const bridgePath = path.join(os.tmpdir(), `clancy-ctx-${session}.json`);
+    if (!fs.existsSync(bridgePath)) process.exit(0); // no statusline data yet
+
+    const metrics = JSON.parse(fs.readFileSync(bridgePath, 'utf8'));
+    const now = Math.floor(Date.now() / 1000);
+
+    // Ignore stale metrics (statusline may not have run this session)
+    if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) process.exit(0);
+
+    const remaining = metrics.remaining_percentage;
+    const usedPct   = metrics.used_pct;
+
+    if (remaining > WARNING_THRESHOLD) process.exit(0);
+
+    // Debounce
+    const warnPath = path.join(os.tmpdir(), `clancy-ctx-${session}-warned.json`);
+    let warnData = { callsSinceWarn: 0, lastLevel: null };
+    let firstWarn = true;
+
+    if (fs.existsSync(warnPath)) {
+      try { warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8')); firstWarn = false; } catch {}
+    }
+
+    warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
+
+    const isCritical      = remaining <= CRITICAL_THRESHOLD;
+    const currentLevel    = isCritical ? 'critical' : 'warning';
+    const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
+
+    if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
+      fs.writeFileSync(warnPath, JSON.stringify(warnData));
+      process.exit(0);
+    }
+
+    warnData.callsSinceWarn = 0;
+    warnData.lastLevel = currentLevel;
+    fs.writeFileSync(warnPath, JSON.stringify(warnData));
+
+    let message;
+    if (isCritical) {
+      message =
+        `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+        'Context is nearly exhausted. Stop reading files and wrap up immediately:\n' +
+        '1. Commit whatever work is staged on the current feature branch\n' +
+        '2. Append a WIP entry to .clancy/progress.txt: ' +
+        'YYYY-MM-DD HH:MM | TICKET-KEY | Summary | WIP — context exhausted\n' +
+        '3. Inform the user what was completed and what remains.\n' +
+        'Do NOT start any new work.';
+    } else {
+      message =
+        `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+        'Context is getting limited. Stop exploring and move to implementation. ' +
+        'Avoid reading additional files unless strictly necessary. ' +
+        'Commit completed work as soon as it is ready.';
+    }
+
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: message,
+      },
+    };
+
+    process.stdout.write(JSON.stringify(output));
+  } catch {
+    process.exit(0);
+  }
+});

package/hooks/clancy-statusline.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// Clancy Statusline hook — registered as the Claude Code statusline.
+// Two jobs:
+//   1. Write context metrics to a bridge file so the PostToolUse context
+//      monitor can read them (the statusline is the only hook that receives
+//      context_window data directly).
+//   2. Output a statusline string showing context usage and update status.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const homeDir = os.homedir();
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const session = data.session_id || '';
+    const remaining = data.context_window?.remaining_percentage;
+
+    // Write bridge file for the context monitor PostToolUse hook
+    if (session && remaining != null) {
+      try {
+        const bridgePath = path.join(os.tmpdir(), `clancy-ctx-${session}.json`);
+        // Claude Code reserves ~16.5% for autocompact buffer.
+        // Normalise to show 100% at the usable limit (same as GSD).
+        const AUTO_COMPACT_BUFFER_PCT = 16.5;
+        const usableRemaining = Math.max(0, ((remaining - AUTO_COMPACT_BUFFER_PCT) / (100 - AUTO_COMPACT_BUFFER_PCT)) * 100);
+        const used = Math.max(0, Math.min(100, Math.round(100 - usableRemaining)));
+        fs.writeFileSync(bridgePath, JSON.stringify({
+          session_id: session,
+          remaining_percentage: remaining,
+          used_pct: used,
+          timestamp: Math.floor(Date.now() / 1000),
+        }));
+      } catch { /* bridge is best-effort */ }
+    }
+
+    // Build statusline output
+    const parts = [];
+
+    // Update available?
+    const claudeDir = process.env.CLAUDE_CONFIG_DIR || path.join(homeDir, '.claude');
+    const cacheFile = path.join(claudeDir, 'cache', 'clancy-update-check.json');
+    try {
+      const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+      if (cache.update_available) {
+        parts.push('\x1b[33m⬆ /clancy:update\x1b[0m');
+      }
+    } catch { /* cache missing is normal */ }
+
+    // Context bar
+    if (remaining != null) {
+      const AUTO_COMPACT_BUFFER_PCT = 16.5;
+      const usableRemaining = Math.max(0, ((remaining - AUTO_COMPACT_BUFFER_PCT) / (100 - AUTO_COMPACT_BUFFER_PCT)) * 100);
+      const used = Math.max(0, Math.min(100, Math.round(100 - usableRemaining)));
+      const filled = Math.floor(used / 10);
+      const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
+
+      let coloredBar;
+      if (used < 50)      coloredBar = `\x1b[32m${bar} ${used}%\x1b[0m`;
+      else if (used < 65) coloredBar = `\x1b[33m${bar} ${used}%\x1b[0m`;
+      else if (used < 80) coloredBar = `\x1b[38;5;208m${bar} ${used}%\x1b[0m`;
+      else                coloredBar = `\x1b[5;31m💀 ${bar} ${used}%\x1b[0m`;
+
+      parts.push(`\x1b[2mClancy\x1b[0m ${coloredBar}`);
+    } else {
+      parts.push('\x1b[2mClancy\x1b[0m');
+    }
+
+    process.stdout.write(parts.join(' │ '));
+  } catch {
+    process.exit(0);
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chief-clancy",
-  "version": "0.1.7",
+  "version": "0.2.0-beta.2",
   "description": "Autonomous, board-driven development for Claude Code — scaffolds docs, integrates Kanban boards, runs tickets in a loop.",
   "keywords": [
     "claude",
@@ -29,6 +29,7 @@
   "main": "bin/install.js",
   "files": [
     "bin/",
+    "hooks/",
     "src/",
     "registry/"
   ],

package/src/commands/dry-run.md

@@ -0,0 +1,14 @@
+# /clancy:dry-run
+
+Preview which ticket Clancy would pick up next — no changes made.
+
+Shows:
+- The ticket that would be picked up (key, summary, epic)
+- The target branch and feature branch that would be created
+- Full preflight checks — catches config issues early
+
+Nothing is written, no git operations run, Claude is not invoked.
+
+@.claude/clancy/workflows/once.md
+
+Run the once workflow with `--dry-run` as documented above. Treat this invocation as if the user passed `--dry-run`.

package/src/commands/help.md

@@ -20,6 +20,7 @@ integration, structured codebase docs, and a git workflow built for team develop
 | `/clancy:run` | Run in loop mode until queue is empty or MAX_ITERATIONS hit |
 | `/clancy:run 20` | Same, but override MAX_ITERATIONS to 20 for this session |
 | `/clancy:once` | Pick up one ticket and stop — good for first runs and debugging |
+| `/clancy:dry-run` | Preview next ticket without making any changes |
 | `/clancy:status` | Show next tickets without running — read-only board check |
 | `/clancy:review` | Score next ticket (0–100%) with actionable recommendations |
 | `/clancy:logs` | Format and display .clancy/progress.txt |
@@ -35,7 +36,7 @@ integration, structured codebase docs, and a git workflow built for team develop
 
 1. Run `/clancy:init` to connect your Kanban board and scaffold .clancy/
 2. Run `/clancy:map-codebase` to generate codebase docs (or say yes during init)
-3. Run `/clancy:once` to watch your first ticket — then go AFK with `/clancy:run`
+3. Run `/clancy:dry-run` to preview the first ticket, then `/clancy:once` to run it — then go AFK with `/clancy:run`
 
 Clancy picks one ticket per loop, fresh context every iteration. No context rot.
 

package/src/commands/once.md

@@ -8,6 +8,10 @@ Good for:
 - Debugging a specific ticket
 - When you only have time for one ticket
 
+Pass `--dry-run` to preview what Clancy would do without making any changes:
+- Shows the ticket, epic, target branch, and feature branch
+- Exits before any git operations or Claude invocation
+
 @.claude/clancy/workflows/once.md
 
 Run one ticket as documented in the workflow above.

package/src/templates/.env.example.jira

@@ -48,6 +48,12 @@ MAX_ITERATIONS=5
 # PLAYWRIGHT_STORYBOOK_PORT=6006
 # PLAYWRIGHT_STARTUP_WAIT=15
 
+# ─── Optional: Status transitions ────────────────────────────────────────────
+# Move tickets automatically when Clancy picks up or completes them.
+# Set to the exact status name shown in your Jira board column header.
+# CLANCY_STATUS_IN_PROGRESS="In Progress"
+# CLANCY_STATUS_DONE="Done"
+
 # ─── Optional: Notifications ──────────────────────────────────────────────────
 # Webhook URL for Slack or Teams notifications on ticket completion
 # CLANCY_NOTIFY_WEBHOOK=https://hooks.slack.com/services/your/webhook/url

package/src/templates/.env.example.linear

@@ -38,6 +38,12 @@ MAX_ITERATIONS=20
 # PLAYWRIGHT_STORYBOOK_PORT=6006
 # PLAYWRIGHT_STARTUP_WAIT=15
 
+# ─── Optional: Status transitions ────────────────────────────────────────────
+# Move issues automatically when Clancy picks up or completes them.
+# Set to the exact workflow state name shown in your Linear board column header.
+# CLANCY_STATUS_IN_PROGRESS="In Progress"
+# CLANCY_STATUS_DONE="Done"
+
 # ─── Optional: Notifications ──────────────────────────────────────────────────
 # Webhook URL for Slack or Teams notifications on ticket completion
 # CLANCY_NOTIFY_WEBHOOK=https://hooks.slack.com/services/your/webhook/url

package/src/templates/CLAUDE.md

@@ -3,19 +3,26 @@
 
 This project uses Clancy for autonomous ticket-driven development.
 
+### Version check
+At the start of each session, read `~/.claude/cache/clancy-update-check.json` (use the Bash tool). If it exists and `update_available` is true, display exactly:
+`⚠ Clancy update available: v{installed} → v{latest}. Run /clancy:update to upgrade.`
+Then continue normally. If the file is missing or unreadable, continue silently.
+
 ### Docs
-Before every run, read all docs in `.clancy/docs/`:
+Before every run, read these core docs from `.clancy/docs/`:
 - STACK.md — tech stack and dependencies
-- INTEGRATIONS.md — external services and APIs
 - ARCHITECTURE.md — system design and data flow
 - CONVENTIONS.md — code style and patterns
-- TESTING.md — test approach and coverage expectations
 - GIT.md — branching, commit format, merge strategy
-- DESIGN-SYSTEM.md — tokens, components, visual conventions
-- ACCESSIBILITY.md — WCAG requirements and ARIA patterns
 - DEFINITION-OF-DONE.md — checklist before marking a ticket complete
 - CONCERNS.md — known risks, tech debt, things to avoid
 
+Also read these if relevant to the ticket:
+- INTEGRATIONS.md — if the ticket touches external APIs, services, or authentication
+- TESTING.md — if the ticket involves tests, specs, or coverage requirements
+- DESIGN-SYSTEM.md — if the ticket touches UI, components, styles, or visual design
+- ACCESSIBILITY.md — if the ticket touches accessibility, ARIA, or WCAG requirements
+
 ### Executability check
 
 Before any git operation, branch creation, or code change — assess whether this ticket can be implemented entirely as a code change committed to this repo.