feat(cli): add --debug/-d flag for CLI debugging

- Add -d/--debug option to ccw cli command
- Enable debug logging at runtime when flag is set
- Change DEBUG check from const to function for runtime evaluation
- Support debug mode for both exec and status subcommands
- Update help text to include --debug option

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

ccw/src/cli.ts

@@ -171,6 +171,7 @@ export function run(argv: string[]): void {
     .option('-f, --file <file>', 'Read prompt from file (best for multi-line prompts)')
     .option('--tool <tool>', 'CLI tool to use', 'gemini')
     .option('--mode <mode>', 'Execution mode: analysis, write, auto', 'analysis')
+    .option('-d, --debug', 'Enable debug logging for troubleshooting')
     .option('--model <model>', 'Model override')
     .option('--cd <path>', 'Working directory')
     .option('--includeDirs <dirs>', 'Additional directories (--include-directories for gemini/qwen, --add-dir for codex/claude)')

ccw/src/commands/cli.ts

@@ -81,6 +81,7 @@ interface CliExecOptions {
   noNative?: boolean; // Force prompt concatenation instead of native resume
   cache?: string | boolean; // Cache: true = auto from CONTEXT, string = comma-separated patterns/content
   injectMode?: 'none' | 'full' | 'progressive'; // Inject mode for cached content
+  debug?: boolean; // Enable debug logging
 }
 
 /** Cache configuration parsed from --cache */
@@ -457,7 +458,13 @@ function testParseAction(args: string[], options: CliExecOptions): void {
 /**
  * Show CLI tool status
  */
-async function statusAction(): Promise<void> {
+async function statusAction(debug?: boolean): Promise<void> {
+  // Enable debug mode if --debug flag is set
+  if (debug) {
+    process.env.DEBUG = 'true';
+    console.log(chalk.yellow('  Debug mode enabled\n'));
+  }
+
   console.log(chalk.bold.cyan('\n  CLI Tools Status\n'));
 
   const status = await getCliToolsStatus();
@@ -481,7 +488,13 @@ async function statusAction(): Promise<void> {
  * @param {Object} options - CLI options
  */
 async function execAction(positionalPrompt: string | undefined, options: CliExecOptions): Promise<void> {
-  const { prompt: optionPrompt, file, tool = 'gemini', mode = 'analysis', model, cd, includeDirs, timeout, stream, resume, id, noNative, cache, injectMode } = options;
+  const { prompt: optionPrompt, file, tool = 'gemini', mode = 'analysis', model, cd, includeDirs, timeout, stream, resume, id, noNative, cache, injectMode, debug } = options;
+
+  // Enable debug mode if --debug flag is set
+  if (debug) {
+    process.env.DEBUG = 'true';
+    console.log(chalk.yellow('  Debug mode enabled\n'));
+  }
 
   // Priority: 1. --file, 2. --prompt/-p option, 3. positional argument
   let finalPrompt: string | undefined;
@@ -957,7 +970,7 @@ export async function cliCommand(
 
   switch (subcommand) {
     case 'status':
-      await statusAction();
+      await statusAction((options as CliExecOptions).debug);
       break;
 
     case 'history':
@@ -1014,6 +1027,7 @@ export async function cliCommand(
         console.log(chalk.gray('    -f, --file <file>   Read prompt from file'));
         console.log(chalk.gray('    --tool <tool>       Tool: gemini, qwen, codex (default: gemini)'));
         console.log(chalk.gray('    --mode <mode>       Mode: analysis, write, auto (default: analysis)'));
+        console.log(chalk.gray('    -d, --debug         Enable debug logging for troubleshooting'));
         console.log(chalk.gray('    --model <model>     Model override'));
         console.log(chalk.gray('    --cd <path>         Working directory'));
         console.log(chalk.gray('    --includeDirs <dirs>  Additional directories'));

ccw/src/tools/cli-executor.ts

@@ -10,11 +10,13 @@ import { spawn, ChildProcess } from 'child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, readdirSync, statSync } from 'fs';
 import { join, relative } from 'path';
 
-// Debug logging utility
+// Debug logging utility - check env at runtime for --debug flag support
-const DEBUG = process.env.DEBUG === 'true' || process.env.DEBUG === '1' || process.env.CCW_DEBUG === 'true';
+function isDebugEnabled(): boolean {
+  return process.env.DEBUG === 'true' || process.env.DEBUG === '1' || process.env.CCW_DEBUG === 'true';
+}
 
 function debugLog(category: string, message: string, data?: Record<string, unknown>): void {
-  if (!DEBUG) return;
+  if (!isDebugEnabled()) return;
   const timestamp = new Date().toISOString();
   const prefix = `[${timestamp}] [CLI-DEBUG] [${category}]`;
   if (data) {
@@ -30,7 +32,7 @@ function errorLog(category: string, message: string, error?: Error | unknown, co
   console.error(`${prefix} ${message}`);
   if (error instanceof Error) {
     console.error(`${prefix} Error: ${error.message}`);
-    if (DEBUG && error.stack) {
+    if (isDebugEnabled() && error.stack) {
       console.error(`${prefix} Stack: ${error.stack}`);
     }
   } else if (error) {

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-code-workflow",
-  "version": "6.3.15",
+  "version": "6.3.16",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-code-workflow",
-      "version": "6.3.15",
+      "version": "6.3.16",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.0.4",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-workflow",
-  "version": "6.3.15",
+  "version": "6.3.16",
   "description": "JSON-driven multi-agent development framework with intelligent CLI orchestration (Gemini/Qwen/Codex), context-first architecture, and automated workflow execution",
   "type": "module",
   "main": "ccw/src/index.js",