chief-clancy 0.1.4 → 0.2.0-beta.1

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-34%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`                                |
@@ -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
 
 ```

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) {
@@ -149,6 +150,66 @@ 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);
 
+    // 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.'));
     console.log('');
@@ -163,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.4",
+  "version": "0.2.0-beta.1",
   "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.

package/src/templates/scripts/clancy-once-github.sh

@@ -3,6 +3,15 @@
 # This means any command that fails will stop the script immediately rather than silently continuing.
 set -euo pipefail
 
+# Parse flags — must happen before preflight so --dry-run works without side effects.
+DRY_RUN=false
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=true ;;
+  esac
+done
+readonly DRY_RUN
+
 # ─── WHAT THIS SCRIPT DOES ─────────────────────────────────────────────────────
 #
 # Board: GitHub Issues
@@ -136,17 +145,31 @@ TICKET_BRANCH="feature/issue-${ISSUE_NUMBER}"
 if [ "$MILESTONE" != "none" ]; then
   MILESTONE_SLUG=$(echo "$MILESTONE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-')
   TARGET_BRANCH="milestone/${MILESTONE_SLUG}"
-  git show-ref --verify --quiet "refs/heads/$TARGET_BRANCH" \
-    || git checkout -b "$TARGET_BRANCH" "$BASE_BRANCH"
 else
   TARGET_BRANCH="$BASE_BRANCH"
 fi
 
+# ─── DRY RUN ───────────────────────────────────────────────────────────────────
+
+if [ "$DRY_RUN" = "true" ]; then
+  echo ""
+  echo "── Dry run ──────────────────────────────────────"
+  echo "  Issue:          [#${ISSUE_NUMBER}] $TITLE"
+  echo "  Milestone:      $MILESTONE"
+  echo "  Target branch:  $TARGET_BRANCH"
+  echo "  Feature branch: $TICKET_BRANCH"
+  echo "─────────────────────────────────────────────────"
+  echo "  No changes made. Remove --dry-run to run for real."
+  exit 0
+fi
+
 # ─── IMPLEMENT ─────────────────────────────────────────────────────────────────
 
 echo "Picking up: [#${ISSUE_NUMBER}] $TITLE"
 echo "Milestone: $MILESTONE | Target branch: $TARGET_BRANCH"
 
+git show-ref --verify --quiet "refs/heads/$TARGET_BRANCH" \
+  || git checkout -b "$TARGET_BRANCH" "$BASE_BRANCH"
 git checkout "$TARGET_BRANCH"
 # -B creates the branch if it doesn't exist, or resets it to HEAD if it does.
 # This handles retries cleanly without failing on an already-existing branch.
@@ -172,7 +195,8 @@ If you must SKIP this issue:
 4. Stop — no branches, no file changes, no git operations.
 
 If the issue IS implementable, continue:
-1. Read ALL docs in .clancy/docs/ — especially GIT.md for branching and commit conventions
+1. Read core docs in .clancy/docs/: STACK.md, ARCHITECTURE.md, CONVENTIONS.md, GIT.md, DEFINITION-OF-DONE.md, CONCERNS.md
+   Also read if relevant to this ticket: INTEGRATIONS.md (external APIs/services/auth), TESTING.md (tests/specs/coverage), DESIGN-SYSTEM.md (UI/components/styles), ACCESSIBILITY.md (accessibility/ARIA/WCAG)
 2. Follow the conventions in GIT.md exactly
 3. Implement the issue fully
 4. Commit your work following the conventions in GIT.md

package/src/templates/scripts/clancy-once-linear.sh

@@ -3,6 +3,15 @@
 # This means any command that fails will stop the script immediately rather than silently continuing.
 set -euo pipefail
 
+# Parse flags — must happen before preflight so --dry-run works without side effects.
+DRY_RUN=false
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=true ;;
+  esac
+done
+readonly DRY_RUN
+
 # ─── WHAT THIS SCRIPT DOES ─────────────────────────────────────────────────────
 #
 # Board: Linear
@@ -153,6 +162,7 @@ if [ "$NODE_COUNT" -eq 0 ]; then
   exit 0
 fi
 
+ISSUE_ID=$(echo "$RESPONSE" | jq -r '.data.viewer.assignedIssues.nodes[0].id')
 IDENTIFIER=$(echo "$RESPONSE" | jq -r '.data.viewer.assignedIssues.nodes[0].identifier')
 TITLE=$(echo "$RESPONSE" | jq -r '.data.viewer.assignedIssues.nodes[0].title')
 DESCRIPTION=$(echo "$RESPONSE" | jq -r '.data.viewer.assignedIssues.nodes[0].description // "No description"')
@@ -172,22 +182,58 @@ TICKET_BRANCH="feature/$(echo "$IDENTIFIER" | tr '[:upper:]' '[:lower:]')"
 # BASE_BRANCH if it doesn't exist yet). Otherwise branch from BASE_BRANCH directly.
 if [ "$PARENT_ID" != "none" ]; then
   TARGET_BRANCH="epic/$(echo "$PARENT_ID" | tr '[:upper:]' '[:lower:]')"
-  git show-ref --verify --quiet "refs/heads/$TARGET_BRANCH" \
-    || git checkout -b "$TARGET_BRANCH" "$BASE_BRANCH"
 else
   TARGET_BRANCH="$BASE_BRANCH"
 fi
 
+# ─── DRY RUN ───────────────────────────────────────────────────────────────────
+
+if [ "$DRY_RUN" = "true" ]; then
+  echo ""
+  echo "── Dry run ──────────────────────────────────────"
+  echo "  Issue:          [$IDENTIFIER] $TITLE"
+  echo "  Epic:           $EPIC_INFO"
+  echo "  Target branch:  $TARGET_BRANCH"
+  echo "  Feature branch: $TICKET_BRANCH"
+  echo "─────────────────────────────────────────────────"
+  echo "  No changes made. Remove --dry-run to run for real."
+  exit 0
+fi
+
 # ─── IMPLEMENT ─────────────────────────────────────────────────────────────────
 
 echo "Picking up: [$IDENTIFIER] $TITLE"
 echo "Epic: $EPIC_INFO | Target branch: $TARGET_BRANCH"
 
+git show-ref --verify --quiet "refs/heads/$TARGET_BRANCH" \
+  || git checkout -b "$TARGET_BRANCH" "$BASE_BRANCH"
 git checkout "$TARGET_BRANCH"
 # -B creates the branch if it doesn't exist, or resets it to HEAD if it does.
 # This handles retries cleanly without failing on an already-existing branch.
 git checkout -B "$TICKET_BRANCH"
 
+# Transition issue to In Progress (best-effort — never fails the run).
+# Queries team workflow states by type "started", picks the first match.
+if [ -n "${CLANCY_STATUS_IN_PROGRESS:-}" ]; then
+  STATE_RESP=$(curl -s -X POST https://api.linear.app/graphql \
+    -H "Content-Type: application/json" \
+    -H "Authorization: $LINEAR_API_KEY" \
+    -d "$(jq -n --arg teamId "$LINEAR_TEAM_ID" --arg name "$CLANCY_STATUS_IN_PROGRESS" \
+      '{"query": "query($teamId: String!, $name: String!) { workflowStates(filter: { team: { id: { eq: $teamId } } name: { eq: $name } }) { nodes { id } } }", "variables": {"teamId": $teamId, "name": $name}}')")
+  IN_PROGRESS_STATE_ID=$(echo "$STATE_RESP" | jq -r '.data.workflowStates.nodes[0].id // empty')
+  if [ -n "$IN_PROGRESS_STATE_ID" ]; then
+    curl -s -X POST https://api.linear.app/graphql \
+      -H "Content-Type: application/json" \
+      -H "Authorization: $LINEAR_API_KEY" \
+      -d "$(jq -n --arg issueId "$ISSUE_ID" --arg stateId "$IN_PROGRESS_STATE_ID" \
+        '{"query": "mutation($issueId: String!, $stateId: String!) { issueUpdate(id: $issueId, input: { stateId: $stateId }) { success } }", "variables": {"issueId": $issueId, "stateId": $stateId}}')" \
+      >/dev/null 2>&1 || true
+    echo "  → Transitioned to $CLANCY_STATUS_IN_PROGRESS"
+  else
+    echo "  ⚠ Workflow state '$CLANCY_STATUS_IN_PROGRESS' not found — check CLANCY_STATUS_IN_PROGRESS in .clancy/.env."
+  fi
+fi
+
 PROMPT="You are implementing Linear issue $IDENTIFIER.
 
 Title: $TITLE
@@ -208,7 +254,8 @@ If you must SKIP this issue:
 4. Stop — no branches, no file changes, no git operations.
 
 If the issue IS implementable, continue:
-1. Read ALL docs in .clancy/docs/ — especially GIT.md for branching and commit conventions
+1. Read core docs in .clancy/docs/: STACK.md, ARCHITECTURE.md, CONVENTIONS.md, GIT.md, DEFINITION-OF-DONE.md, CONCERNS.md
+   Also read if relevant to this ticket: INTEGRATIONS.md (external APIs/services/auth), TESTING.md (tests/specs/coverage), DESIGN-SYSTEM.md (UI/components/styles), ACCESSIBILITY.md (accessibility/ARIA/WCAG)
 2. Follow the conventions in GIT.md exactly
 3. Implement the issue fully
 4. Commit your work following the conventions in GIT.md
@@ -232,6 +279,27 @@ fi
 # Delete ticket branch locally
 git branch -d "$TICKET_BRANCH"
 
+# Transition issue to Done (best-effort — never fails the run).
+if [ -n "${CLANCY_STATUS_DONE:-}" ]; then
+  STATE_RESP=$(curl -s -X POST https://api.linear.app/graphql \
+    -H "Content-Type: application/json" \
+    -H "Authorization: $LINEAR_API_KEY" \
+    -d "$(jq -n --arg teamId "$LINEAR_TEAM_ID" --arg name "$CLANCY_STATUS_DONE" \
+      '{"query": "query($teamId: String!, $name: String!) { workflowStates(filter: { team: { id: { eq: $teamId } } name: { eq: $name } }) { nodes { id } } }", "variables": {"teamId": $teamId, "name": $name}}')")
+  DONE_STATE_ID=$(echo "$STATE_RESP" | jq -r '.data.workflowStates.nodes[0].id // empty')
+  if [ -n "$DONE_STATE_ID" ]; then
+    curl -s -X POST https://api.linear.app/graphql \
+      -H "Content-Type: application/json" \
+      -H "Authorization: $LINEAR_API_KEY" \
+      -d "$(jq -n --arg issueId "$ISSUE_ID" --arg stateId "$DONE_STATE_ID" \
+        '{"query": "mutation($issueId: String!, $stateId: String!) { issueUpdate(id: $issueId, input: { stateId: $stateId }) { success } }", "variables": {"issueId": $issueId, "stateId": $stateId}}')" \
+      >/dev/null 2>&1 || true
+    echo "  → Transitioned to $CLANCY_STATUS_DONE"
+  else
+    echo "  ⚠ Workflow state '$CLANCY_STATUS_DONE' not found — check CLANCY_STATUS_DONE in .clancy/.env."
+  fi
+fi
+
 # Log progress
 echo "$(date '+%Y-%m-%d %H:%M') | $IDENTIFIER | $TITLE | DONE" >> .clancy/progress.txt
 

package/src/templates/scripts/clancy-once.sh

@@ -3,6 +3,15 @@
 # This means any command that fails will stop the script immediately rather than silently continuing.
 set -euo pipefail
 
+# Parse flags — must happen before preflight so --dry-run works without side effects.
+DRY_RUN=false
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=true ;;
+  esac
+done
+readonly DRY_RUN
+
 # ─── WHAT THIS SCRIPT DOES ─────────────────────────────────────────────────────
 #
 # Board: Jira
@@ -178,22 +187,56 @@ TICKET_BRANCH="feature/$(echo "$TICKET_KEY" | tr '[:upper:]' '[:lower:]')"
 # BASE_BRANCH if it doesn't exist yet). Otherwise branch from BASE_BRANCH directly.
 if [ "$EPIC_INFO" != "none" ]; then
   TARGET_BRANCH="epic/$(echo "$EPIC_INFO" | tr '[:upper:]' '[:lower:]')"
-  git show-ref --verify --quiet "refs/heads/$TARGET_BRANCH" \
-    || git checkout -b "$TARGET_BRANCH" "$BASE_BRANCH"
 else
   TARGET_BRANCH="$BASE_BRANCH"
 fi
 
+# ─── DRY RUN ───────────────────────────────────────────────────────────────────
+
+if [ "$DRY_RUN" = "true" ]; then
+  echo ""
+  echo "── Dry run ──────────────────────────────────────"
+  echo "  Ticket:         [$TICKET_KEY] $SUMMARY"
+  echo "  Epic:           $EPIC_INFO"
+  echo "  Blockers:       $BLOCKERS"
+  echo "  Target branch:  $TARGET_BRANCH"
+  echo "  Feature branch: $TICKET_BRANCH"
+  echo "─────────────────────────────────────────────────"
+  echo "  No changes made. Remove --dry-run to run for real."
+  exit 0
+fi
+
 # ─── IMPLEMENT ─────────────────────────────────────────────────────────────────
 
 echo "Picking up: [$TICKET_KEY] $SUMMARY"
 echo "Epic: $EPIC_INFO | Target branch: $TARGET_BRANCH | Blockers: $BLOCKERS"
 
+git show-ref --verify --quiet "refs/heads/$TARGET_BRANCH" \
+  || git checkout -b "$TARGET_BRANCH" "$BASE_BRANCH"
 git checkout "$TARGET_BRANCH"
 # -B creates the branch if it doesn't exist, or resets it to HEAD if it does.
 # This handles retries cleanly without failing on an already-existing branch.
 git checkout -B "$TICKET_BRANCH"
 
+# Transition ticket to In Progress (best-effort — never fails the run)
+if [ -n "${CLANCY_STATUS_IN_PROGRESS:-}" ]; then
+  TRANSITIONS=$(curl -s \
+    -u "$JIRA_USER:$JIRA_API_TOKEN" \
+    -H "Accept: application/json" \
+    "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY/transitions")
+  IN_PROGRESS_ID=$(echo "$TRANSITIONS" | jq -r \
+    --arg name "$CLANCY_STATUS_IN_PROGRESS" \
+    '.transitions[] | select(.name == $name) | .id' | head -1)
+  if [ -n "$IN_PROGRESS_ID" ]; then
+    curl -s -X POST \
+      -u "$JIRA_USER:$JIRA_API_TOKEN" \
+      -H "Content-Type: application/json" \
+      "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY/transitions" \
+      -d "$(jq -n --arg id "$IN_PROGRESS_ID" '{"transition":{"id":$id}}')" >/dev/null 2>&1 || true
+    echo "  → Transitioned to $CLANCY_STATUS_IN_PROGRESS"
+  fi
+fi
+
 PROMPT="You are implementing Jira ticket $TICKET_KEY.
 
 Summary: $SUMMARY
@@ -215,7 +258,8 @@ If you must SKIP this ticket:
 4. Stop — no branches, no file changes, no git operations.
 
 If the ticket IS implementable, continue:
-1. Read ALL docs in .clancy/docs/ — especially GIT.md for branching and commit conventions
+1. Read core docs in .clancy/docs/: STACK.md, ARCHITECTURE.md, CONVENTIONS.md, GIT.md, DEFINITION-OF-DONE.md, CONCERNS.md
+   Also read if relevant to this ticket: INTEGRATIONS.md (external APIs/services/auth), TESTING.md (tests/specs/coverage), DESIGN-SYSTEM.md (UI/components/styles), ACCESSIBILITY.md (accessibility/ARIA/WCAG)
 2. Follow the conventions in GIT.md exactly
 3. Implement the ticket fully
 4. Commit your work following the conventions in GIT.md
@@ -239,6 +283,25 @@ fi
 # Delete ticket branch locally (never push deletes)
 git branch -d "$TICKET_BRANCH"
 
+# Transition ticket to Done (best-effort — never fails the run)
+if [ -n "${CLANCY_STATUS_DONE:-}" ]; then
+  TRANSITIONS=$(curl -s \
+    -u "$JIRA_USER:$JIRA_API_TOKEN" \
+    -H "Accept: application/json" \
+    "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY/transitions")
+  DONE_ID=$(echo "$TRANSITIONS" | jq -r \
+    --arg name "$CLANCY_STATUS_DONE" \
+    '.transitions[] | select(.name == $name) | .id' | head -1)
+  if [ -n "$DONE_ID" ]; then
+    curl -s -X POST \
+      -u "$JIRA_USER:$JIRA_API_TOKEN" \
+      -H "Content-Type: application/json" \
+      "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY/transitions" \
+      -d "$(jq -n --arg id "$DONE_ID" '{"transition":{"id":$id}}')" >/dev/null 2>&1 || true
+    echo "  → Transitioned to $CLANCY_STATUS_DONE"
+  fi
+fi
+
 # Log progress
 echo "$(date '+%Y-%m-%d %H:%M') | $TICKET_KEY | $SUMMARY | DONE" >> .clancy/progress.txt
 

package/src/workflows/init.md

@@ -420,4 +420,4 @@ Clancy is ready.
 - Config: `.clancy/.env`
 - CLAUDE.md: updated
 
-Run `/clancy:once` to pick up your first ticket, or `/clancy:run` to process the full queue.
+Run `/clancy:dry-run` to preview the first ticket without making changes, `/clancy:once` to pick it up, or `/clancy:run` to process the full queue.

package/src/workflows/once.md

@@ -45,6 +45,10 @@ Pick up exactly one ticket from the Kanban board, implement it, commit, squash-m
 
 ## Step 2 — Run
 
+Check if the user passed `--dry-run` as an argument to the slash command.
+
+**Without `--dry-run`:**
+
 Display:
 ```
 Running Clancy for one ticket.
@@ -55,6 +59,18 @@ Execute:
 bash .clancy/clancy-once.sh
 ```
 
+**With `--dry-run`:**
+
+Display:
+```
+Running Clancy in dry-run mode — no changes will be made.
+```
+
+Execute:
+```bash
+bash .clancy/clancy-once.sh --dry-run
+```
+
 Stream output directly — do not buffer or summarise.
 
 ---

package/src/workflows/scaffold.md

@@ -304,6 +304,15 @@ Write this file when the chosen board is **Jira**:
 # This means any command that fails will stop the script immediately rather than silently continuing.
 set -euo pipefail
 
+# Parse flags — must happen before preflight so --dry-run works without side effects.
+DRY_RUN=false
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=true ;;
+  esac
+done
+readonly DRY_RUN
+
 # ─── WHAT THIS SCRIPT DOES ─────────────────────────────────────────────────────
 #
 # Board: Jira
@@ -479,22 +488,56 @@ TICKET_BRANCH="feature/$(echo "$TICKET_KEY" | tr '[:upper:]' '[:lower:]')"
 # BASE_BRANCH if it doesn't exist yet). Otherwise branch from BASE_BRANCH directly.
 if [ "$EPIC_INFO" != "none" ]; then
   TARGET_BRANCH="epic/$(echo "$EPIC_INFO" | tr '[:upper:]' '[:lower:]')"
-  git show-ref --verify --quiet "refs/heads/$TARGET_BRANCH" \
-    || git checkout -b "$TARGET_BRANCH" "$BASE_BRANCH"
 else
   TARGET_BRANCH="$BASE_BRANCH"
 fi
 
+# ─── DRY RUN ───────────────────────────────────────────────────────────────────
+
+if [ "$DRY_RUN" = "true" ]; then
+  echo ""
+  echo "── Dry run ──────────────────────────────────────"
+  echo "  Ticket:         [$TICKET_KEY] $SUMMARY"
+  echo "  Epic:           $EPIC_INFO"
+  echo "  Blockers:       $BLOCKERS"
+  echo "  Target branch:  $TARGET_BRANCH"
+  echo "  Feature branch: $TICKET_BRANCH"
+  echo "─────────────────────────────────────────────────"
+  echo "  No changes made. Remove --dry-run to run for real."
+  exit 0
+fi
+
 # ─── IMPLEMENT ─────────────────────────────────────────────────────────────────
 
 echo "Picking up: [$TICKET_KEY] $SUMMARY"
 echo "Epic: $EPIC_INFO | Target branch: $TARGET_BRANCH | Blockers: $BLOCKERS"
 
+git show-ref --verify --quiet "refs/heads/$TARGET_BRANCH" \
+  || git checkout -b "$TARGET_BRANCH" "$BASE_BRANCH"
 git checkout "$TARGET_BRANCH"
 # -B creates the branch if it doesn't exist, or resets it to HEAD if it does.
 # This handles retries cleanly without failing on an already-existing branch.
 git checkout -B "$TICKET_BRANCH"
 
+# Transition ticket to In Progress (best-effort — never fails the run)
+if [ -n "${CLANCY_STATUS_IN_PROGRESS:-}" ]; then
+  TRANSITIONS=$(curl -s \
+    -u "$JIRA_USER:$JIRA_API_TOKEN" \
+    -H "Accept: application/json" \
+    "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY/transitions")
+  IN_PROGRESS_ID=$(echo "$TRANSITIONS" | jq -r \
+    --arg name "$CLANCY_STATUS_IN_PROGRESS" \
+    '.transitions[] | select(.name == $name) | .id' | head -1)
+  if [ -n "$IN_PROGRESS_ID" ]; then
+    curl -s -X POST \
+      -u "$JIRA_USER:$JIRA_API_TOKEN" \
+      -H "Content-Type: application/json" \
+      "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY/transitions" \
+      -d "$(jq -n --arg id "$IN_PROGRESS_ID" '{"transition":{"id":$id}}')" >/dev/null 2>&1 || true
+    echo "  → Transitioned to $CLANCY_STATUS_IN_PROGRESS"
+  fi
+fi
+
 PROMPT="You are implementing Jira ticket $TICKET_KEY.
 
 Summary: $SUMMARY
@@ -516,7 +559,8 @@ If you must SKIP this ticket:
 4. Stop — no branches, no file changes, no git operations.
 
 If the ticket IS implementable, continue:
-1. Read ALL docs in .clancy/docs/ — especially GIT.md for branching and commit conventions
+1. Read core docs in .clancy/docs/: STACK.md, ARCHITECTURE.md, CONVENTIONS.md, GIT.md, DEFINITION-OF-DONE.md, CONCERNS.md
+   Also read if relevant to this ticket: INTEGRATIONS.md (external APIs/services/auth), TESTING.md (tests/specs/coverage), DESIGN-SYSTEM.md (UI/components/styles), ACCESSIBILITY.md (accessibility/ARIA/WCAG)
 2. Follow the conventions in GIT.md exactly
 3. Implement the ticket fully
 4. Commit your work following the conventions in GIT.md
@@ -540,6 +584,25 @@ fi
 # Delete ticket branch locally (never push deletes)
 git branch -d "$TICKET_BRANCH"
 
+# Transition ticket to Done (best-effort — never fails the run)
+if [ -n "${CLANCY_STATUS_DONE:-}" ]; then
+  TRANSITIONS=$(curl -s \
+    -u "$JIRA_USER:$JIRA_API_TOKEN" \
+    -H "Accept: application/json" \
+    "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY/transitions")
+  DONE_ID=$(echo "$TRANSITIONS" | jq -r \
+    --arg name "$CLANCY_STATUS_DONE" \
+    '.transitions[] | select(.name == $name) | .id' | head -1)
+  if [ -n "$DONE_ID" ]; then
+    curl -s -X POST \
+      -u "$JIRA_USER:$JIRA_API_TOKEN" \
+      -H "Content-Type: application/json" \
+      "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY/transitions" \
+      -d "$(jq -n --arg id "$DONE_ID" '{"transition":{"id":$id}}')" >/dev/null 2>&1 || true
+    echo "  → Transitioned to $CLANCY_STATUS_DONE"
+  fi
+fi
+
 # Log progress
 echo "$(date '+%Y-%m-%d %H:%M') | $TICKET_KEY | $SUMMARY | DONE" >> .clancy/progress.txt
 
@@ -572,6 +635,15 @@ Write this file when the chosen board is **GitHub Issues**:
 # This means any command that fails will stop the script immediately rather than silently continuing.
 set -euo pipefail
 
+# Parse flags — must happen before preflight so --dry-run works without side effects.
+DRY_RUN=false
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=true ;;
+  esac
+done
+readonly DRY_RUN
+
 # ─── WHAT THIS SCRIPT DOES ─────────────────────────────────────────────────────
 #
 # Board: GitHub Issues
@@ -705,17 +777,31 @@ TICKET_BRANCH="feature/issue-${ISSUE_NUMBER}"
 if [ "$MILESTONE" != "none" ]; then
   MILESTONE_SLUG=$(echo "$MILESTONE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-')
   TARGET_BRANCH="milestone/${MILESTONE_SLUG}"
-  git show-ref --verify --quiet "refs/heads/$TARGET_BRANCH" \
-    || git checkout -b "$TARGET_BRANCH" "$BASE_BRANCH"
 else
   TARGET_BRANCH="$BASE_BRANCH"
 fi
 
+# ─── DRY RUN ───────────────────────────────────────────────────────────────────
+
+if [ "$DRY_RUN" = "true" ]; then
+  echo ""
+  echo "── Dry run ──────────────────────────────────────"
+  echo "  Issue:          [#${ISSUE_NUMBER}] $TITLE"
+  echo "  Milestone:      $MILESTONE"
+  echo "  Target branch:  $TARGET_BRANCH"
+  echo "  Feature branch: $TICKET_BRANCH"
+  echo "─────────────────────────────────────────────────"
+  echo "  No changes made. Remove --dry-run to run for real."
+  exit 0
+fi
+
 # ─── IMPLEMENT ─────────────────────────────────────────────────────────────────
 
 echo "Picking up: [#${ISSUE_NUMBER}] $TITLE"
 echo "Milestone: $MILESTONE | Target branch: $TARGET_BRANCH"
 
+git show-ref --verify --quiet "refs/heads/$TARGET_BRANCH" \
+  || git checkout -b "$TARGET_BRANCH" "$BASE_BRANCH"
 git checkout "$TARGET_BRANCH"
 # -B creates the branch if it doesn't exist, or resets it to HEAD if it does.
 # This handles retries cleanly without failing on an already-existing branch.
@@ -741,7 +827,8 @@ If you must SKIP this issue:
 4. Stop — no branches, no file changes, no git operations.
 
 If the issue IS implementable, continue:
-1. Read ALL docs in .clancy/docs/ — especially GIT.md for branching and commit conventions
+1. Read core docs in .clancy/docs/: STACK.md, ARCHITECTURE.md, CONVENTIONS.md, GIT.md, DEFINITION-OF-DONE.md, CONCERNS.md
+   Also read if relevant to this ticket: INTEGRATIONS.md (external APIs/services/auth), TESTING.md (tests/specs/coverage), DESIGN-SYSTEM.md (UI/components/styles), ACCESSIBILITY.md (accessibility/ARIA/WCAG)
 2. Follow the conventions in GIT.md exactly
 3. Implement the issue fully
 4. Commit your work following the conventions in GIT.md
@@ -806,6 +893,15 @@ Write this file when the chosen board is **Linear**:
 # This means any command that fails will stop the script immediately rather than silently continuing.
 set -euo pipefail
 
+# Parse flags — must happen before preflight so --dry-run works without side effects.
+DRY_RUN=false
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=true ;;
+  esac
+done
+readonly DRY_RUN
+
 # ─── WHAT THIS SCRIPT DOES ─────────────────────────────────────────────────────
 #
 # Board: Linear
@@ -956,6 +1052,7 @@ if [ "$NODE_COUNT" -eq 0 ]; then
   exit 0
 fi
 
+ISSUE_ID=$(echo "$RESPONSE" | jq -r '.data.viewer.assignedIssues.nodes[0].id')
 IDENTIFIER=$(echo "$RESPONSE" | jq -r '.data.viewer.assignedIssues.nodes[0].identifier')
 TITLE=$(echo "$RESPONSE" | jq -r '.data.viewer.assignedIssues.nodes[0].title')
 DESCRIPTION=$(echo "$RESPONSE" | jq -r '.data.viewer.assignedIssues.nodes[0].description // "No description"')
@@ -975,22 +1072,58 @@ TICKET_BRANCH="feature/$(echo "$IDENTIFIER" | tr '[:upper:]' '[:lower:]')"
 # BASE_BRANCH if it doesn't exist yet). Otherwise branch from BASE_BRANCH directly.
 if [ "$PARENT_ID" != "none" ]; then
   TARGET_BRANCH="epic/$(echo "$PARENT_ID" | tr '[:upper:]' '[:lower:]')"
-  git show-ref --verify --quiet "refs/heads/$TARGET_BRANCH" \
-    || git checkout -b "$TARGET_BRANCH" "$BASE_BRANCH"
 else
   TARGET_BRANCH="$BASE_BRANCH"
 fi
 
+# ─── DRY RUN ───────────────────────────────────────────────────────────────────
+
+if [ "$DRY_RUN" = "true" ]; then
+  echo ""
+  echo "── Dry run ──────────────────────────────────────"
+  echo "  Issue:          [$IDENTIFIER] $TITLE"
+  echo "  Epic:           $EPIC_INFO"
+  echo "  Target branch:  $TARGET_BRANCH"
+  echo "  Feature branch: $TICKET_BRANCH"
+  echo "─────────────────────────────────────────────────"
+  echo "  No changes made. Remove --dry-run to run for real."
+  exit 0
+fi
+
 # ─── IMPLEMENT ─────────────────────────────────────────────────────────────────
 
 echo "Picking up: [$IDENTIFIER] $TITLE"
 echo "Epic: $EPIC_INFO | Target branch: $TARGET_BRANCH"
 
+git show-ref --verify --quiet "refs/heads/$TARGET_BRANCH" \
+  || git checkout -b "$TARGET_BRANCH" "$BASE_BRANCH"
 git checkout "$TARGET_BRANCH"
 # -B creates the branch if it doesn't exist, or resets it to HEAD if it does.
 # This handles retries cleanly without failing on an already-existing branch.
 git checkout -B "$TICKET_BRANCH"
 
+# Transition issue to In Progress (best-effort — never fails the run).
+# Queries team workflow states by type "started", picks the first match.
+if [ -n "${CLANCY_STATUS_IN_PROGRESS:-}" ]; then
+  STATE_RESP=$(curl -s -X POST https://api.linear.app/graphql \
+    -H "Content-Type: application/json" \
+    -H "Authorization: $LINEAR_API_KEY" \
+    -d "$(jq -n --arg teamId "$LINEAR_TEAM_ID" --arg name "$CLANCY_STATUS_IN_PROGRESS" \
+      '{"query": "query($teamId: String!, $name: String!) { workflowStates(filter: { team: { id: { eq: $teamId } } name: { eq: $name } }) { nodes { id } } }", "variables": {"teamId": $teamId, "name": $name}}')")
+  IN_PROGRESS_STATE_ID=$(echo "$STATE_RESP" | jq -r '.data.workflowStates.nodes[0].id // empty')
+  if [ -n "$IN_PROGRESS_STATE_ID" ]; then
+    curl -s -X POST https://api.linear.app/graphql \
+      -H "Content-Type: application/json" \
+      -H "Authorization: $LINEAR_API_KEY" \
+      -d "$(jq -n --arg issueId "$ISSUE_ID" --arg stateId "$IN_PROGRESS_STATE_ID" \
+        '{"query": "mutation($issueId: String!, $stateId: String!) { issueUpdate(id: $issueId, input: { stateId: $stateId }) { success } }", "variables": {"issueId": $issueId, "stateId": $stateId}}')" \
+      >/dev/null 2>&1 || true
+    echo "  → Transitioned to $CLANCY_STATUS_IN_PROGRESS"
+  else
+    echo "  ⚠ Workflow state '$CLANCY_STATUS_IN_PROGRESS' not found — check CLANCY_STATUS_IN_PROGRESS in .clancy/.env."
+  fi
+fi
+
 PROMPT="You are implementing Linear issue $IDENTIFIER.
 
 Title: $TITLE
@@ -1011,7 +1144,8 @@ If you must SKIP this issue:
 4. Stop — no branches, no file changes, no git operations.
 
 If the issue IS implementable, continue:
-1. Read ALL docs in .clancy/docs/ — especially GIT.md for branching and commit conventions
+1. Read core docs in .clancy/docs/: STACK.md, ARCHITECTURE.md, CONVENTIONS.md, GIT.md, DEFINITION-OF-DONE.md, CONCERNS.md
+   Also read if relevant to this ticket: INTEGRATIONS.md (external APIs/services/auth), TESTING.md (tests/specs/coverage), DESIGN-SYSTEM.md (UI/components/styles), ACCESSIBILITY.md (accessibility/ARIA/WCAG)
 2. Follow the conventions in GIT.md exactly
 3. Implement the issue fully
 4. Commit your work following the conventions in GIT.md
@@ -1035,6 +1169,27 @@ fi
 # Delete ticket branch locally
 git branch -d "$TICKET_BRANCH"
 
+# Transition issue to Done (best-effort — never fails the run).
+if [ -n "${CLANCY_STATUS_DONE:-}" ]; then
+  STATE_RESP=$(curl -s -X POST https://api.linear.app/graphql \
+    -H "Content-Type: application/json" \
+    -H "Authorization: $LINEAR_API_KEY" \
+    -d "$(jq -n --arg teamId "$LINEAR_TEAM_ID" --arg name "$CLANCY_STATUS_DONE" \
+      '{"query": "query($teamId: String!, $name: String!) { workflowStates(filter: { team: { id: { eq: $teamId } } name: { eq: $name } }) { nodes { id } } }", "variables": {"teamId": $teamId, "name": $name}}')")
+  DONE_STATE_ID=$(echo "$STATE_RESP" | jq -r '.data.workflowStates.nodes[0].id // empty')
+  if [ -n "$DONE_STATE_ID" ]; then
+    curl -s -X POST https://api.linear.app/graphql \
+      -H "Content-Type: application/json" \
+      -H "Authorization: $LINEAR_API_KEY" \
+      -d "$(jq -n --arg issueId "$ISSUE_ID" --arg stateId "$DONE_STATE_ID" \
+        '{"query": "mutation($issueId: String!, $stateId: String!) { issueUpdate(id: $issueId, input: { stateId: $stateId }) { success } }", "variables": {"issueId": $issueId, "stateId": $stateId}}')" \
+      >/dev/null 2>&1 || true
+    echo "  → Transitioned to $CLANCY_STATUS_DONE"
+  else
+    echo "  ⚠ Workflow state '$CLANCY_STATUS_DONE' not found — check CLANCY_STATUS_DONE in .clancy/.env."
+  fi
+fi
+
 # Log progress
 echo "$(date '+%Y-%m-%d %H:%M') | $IDENTIFIER | $TITLE | DONE" >> .clancy/progress.txt
 
@@ -1234,6 +1389,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
@@ -1330,6 +1491,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/workflows/settings.md

@@ -46,10 +46,14 @@ Jira
 [4] Queue status      {CLANCY_JQL_STATUS:-To Do}
 [5] Sprint filter     {on if CLANCY_JQL_SPRINT set, else off}
 [6] Label filter      {CLANCY_LABEL if set, else off — only pick up tickets with this label}
+[7] Pickup status     {CLANCY_STATUS_IN_PROGRESS if set, else off — move ticket on pickup}
+[8] Done status       {CLANCY_STATUS_DONE if set, else off — move ticket on completion}
 
 {If Linear:}
 Linear
 [4] Label filter      {CLANCY_LABEL if set, else off — only pick up issues with this label}
+[5] Pickup status     {CLANCY_STATUS_IN_PROGRESS if set, else off — move issue on pickup}
+[6] Done status       {CLANCY_STATUS_DONE if set, else off — move issue on completion}
 
 Optional enhancements
 [{N}] Figma MCP       {enabled if FIGMA_API_KEY set, else not set}
@@ -62,7 +66,7 @@ Optional enhancements
 Which setting would you like to change?
 ```
 
-Number each option sequentially. Show only the board-specific section that matches the configured board. If Jira: show [4] queue status, [5] sprint, [6] label. If Linear: show [4] label. If GitHub: no board-specific options.
+Number each option sequentially. Show only the board-specific section that matches the configured board. If Jira: show [4] queue status, [5] sprint, [6] label, [7] pickup status, [8] done status. If Linear: show [4] label, [5] pickup status, [6] done status. If GitHub: no board-specific options.
 
 ---
 
@@ -164,6 +168,40 @@ If [2]: remove `CLANCY_LABEL` from `.clancy/.env`.
 
 ---
 
+### [7] Jira In Progress status (Jira only)
+
+```
+Jira In Progress status — current: {value or "off"}
+When set, Clancy moves a ticket to this status when it starts working on it.
+Must match the exact column name shown in your Jira board.
+
+[1] Set status name
+[2] Off (do not transition on pickup)
+[3] Cancel
+```
+
+If [1]: prompt `What status name should Clancy use for In Progress? (e.g. In Progress, In Dev, Doing)` then write `CLANCY_STATUS_IN_PROGRESS=<value>` to `.clancy/.env`.
+If [2]: remove `CLANCY_STATUS_IN_PROGRESS` from `.clancy/.env`.
+
+---
+
+### [8] Jira Done status (Jira only)
+
+```
+Jira Done status — current: {value or "off"}
+When set, Clancy moves a ticket to this status after completing it.
+Must match the exact column name shown in your Jira board.
+
+[1] Set status name
+[2] Off (do not transition on completion)
+[3] Cancel
+```
+
+If [1]: prompt `What status name should Clancy use for Done? (e.g. Done, Complete, Closed)` then write `CLANCY_STATUS_DONE=<value>` to `.clancy/.env`.
+If [2]: remove `CLANCY_STATUS_DONE` from `.clancy/.env`.
+
+---
+
 ### [4] Linear label filter (Linear only)
 
 ```
@@ -181,6 +219,40 @@ If [2]: remove `CLANCY_LABEL` from `.clancy/.env`.
 
 ---
 
+### [5] Linear In Progress status (Linear only)
+
+```
+Linear In Progress status — current: {value or "off"}
+When set, Clancy moves an issue to this workflow state when it starts working on it.
+Must match the exact state name shown in your Linear board column header.
+
+[1] Set state name
+[2] Off (do not transition on pickup)
+[3] Cancel
+```
+
+If [1]: prompt `What workflow state name should Clancy use for In Progress? (e.g. In Progress, In Dev, Doing)` then write `CLANCY_STATUS_IN_PROGRESS=<value>` to `.clancy/.env`.
+If [2]: remove `CLANCY_STATUS_IN_PROGRESS` from `.clancy/.env`.
+
+---
+
+### [6] Linear Done status (Linear only)
+
+```
+Linear Done status — current: {value or "off"}
+When set, Clancy moves an issue to this workflow state after completing it.
+Must match the exact state name shown in your Linear board column header.
+
+[1] Set state name
+[2] Off (do not transition on completion)
+[3] Cancel
+```
+
+If [1]: prompt `What workflow state name should Clancy use for Done? (e.g. Done, Complete, Closed)` then write `CLANCY_STATUS_DONE=<value>` to `.clancy/.env`.
+If [2]: remove `CLANCY_STATUS_DONE` from `.clancy/.env`.
+
+---
+
 ### Figma MCP
 
 ```

package/src/workflows/uninstall.md

@@ -35,9 +35,33 @@ Continue? (yes / no)
 ```
 
 - `no` → print "Nothing removed." and stop
-- `yes` → delete both the commands directory and the workflows directory for the chosen location(s), print "✓ Clancy removed from [location]."
+- `yes` → proceed to remove commands, workflows, hooks, and settings entries (Steps 2a–2c)
 
-If "Both" was chosen in Step 1: confirm once for both, remove all four directories, print two confirmation lines.
+If "Both" was chosen in Step 1: confirm once for both, remove everything for both locations.
+
+### Step 2a — Remove command and workflow directories
+
+Delete both the commands directory and the workflows directory for the chosen location(s):
+- Project-local: `.claude/commands/clancy/` and `.claude/clancy/`
+- Global: `~/.claude/commands/clancy/` and `~/.claude/clancy/`
+
+Print: `✓ Clancy commands removed from [location].`
+
+### Step 2b — Remove hooks
+
+For each location being removed, delete these hook files if they exist:
+- Project-local: `.claude/hooks/clancy-check-update.js`, `.claude/hooks/clancy-statusline.js`, `.claude/hooks/clancy-context-monitor.js`
+- Global: `~/.claude/hooks/clancy-check-update.js`, `~/.claude/hooks/clancy-statusline.js`, `~/.claude/hooks/clancy-context-monitor.js`
+
+Then remove the Clancy hook registrations from the corresponding `settings.json` (`.claude/settings.json` for local, `~/.claude/settings.json` for global):
+- Remove any entry in `hooks.SessionStart` whose `command` contains `clancy-check-update`
+- Remove any entry in `hooks.PostToolUse` whose `command` contains `clancy-context-monitor`
+- Remove the `statusLine` key if its `command` value contains `clancy-statusline`
+- If removing an entry leaves a `hooks.SessionStart` or `hooks.PostToolUse` array empty, remove the key entirely
+
+Also remove the update check cache if it exists: `~/.claude/cache/clancy-update-check.json`
+
+If `settings.json` does not exist or cannot be parsed, skip silently — do not create or overwrite it.
 
 ---