claude-code-modes 0.1.4 → 0.2.0

package/README.md

@@ -34,10 +34,13 @@ Pick a preset that matches your task:
 ```bash
 claude-mode create      # Build from scratch with proper architecture
 claude-mode extend      # Extend a fast-built project, improve incrementally
-claude-mode safe       # Surgical precision, minimal risk
-claude-mode refactor         # Restructure freely across the codebase
-claude-mode explore          # Read-only — understand code without changing it
-claude-mode none             # Strip all behavioral opinions, use your own CLAUDE.md
+claude-mode safe        # Surgical precision, minimal risk
+claude-mode refactor    # Restructure freely across the codebase
+claude-mode explore     # Read-only — understand code without changing it
+claude-mode debug       # Investigation-first debugging (chill base)
+claude-mode methodical  # Step-by-step precision (chill base)
+claude-mode director    # Delegate to sub-agents, orchestrate and verify (chill base)
+claude-mode none        # Strip all behavioral opinions, use your own CLAUDE.md
 ```
 
 | Preset | Agency | Quality | Scope | Use when... |
@@ -47,6 +50,9 @@ claude-mode none             # Strip all behavioral opinions, use your own CLAUD
 | `safe` | collaborative | minimal | narrow | Surgical changes to production code |
 | `refactor` | autonomous | pragmatic | unrestricted | Move files, consolidate modules, improve patterns |
 | `explore` | collaborative | architect | narrow | Read, explain, suggest — no file modifications |
+| `debug` | collaborative | pragmatic | narrow | Find root causes — evidence-first, ask for guidance when stuck |
+| `methodical` | surgical | architect | narrow | Step-by-step craftsmanship — follow instructions, stop when done |
+| `director` | collaborative | architect | unrestricted | Orchestrate sub-agents — delegate implementation, verify results |
 | `none` | — | — | — | Strip all behavioral instructions, use your own |
 
 ### Alternative base: chill

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-modes",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Behaviorally-tuned system prompts for Claude Code",
   "license": "MIT",
   "type": "module",

package/prompts/modifiers/debug.md

@@ -0,0 +1,18 @@
+# Investigation mode
+
+You're here to understand what's going wrong. Approach this like a detective — gather evidence, form hypotheses, trace the data flow.
+
+Start by understanding the problem before reaching for fixes. Read the relevant code, check error messages, trace the execution path. Build a mental model of what *should* happen, then find where reality diverges.
+
+When presenting findings, be specific: file paths, line numbers, actual vs expected values. Give the user evidence they can verify themselves.
+
+If a fix becomes clear during investigation, go ahead and apply it. If not, that's perfectly fine — understanding the problem is valuable on its own.
+
+<example>
+Situation: The user reports a 500 error on login.
+Good: Read the auth handler, trace the request flow, check the error logs, identify that the session middleware is missing a null check on line 47, explain why this causes the 500, fix it.
+Bad: Try adding try/catch blocks everywhere until the 500 goes away.
+Understand first, then fix.
+</example>
+
+When you've exhausted your current leads, stop and share what you know: what you investigated, what you ruled out, and where you think the issue might be. Ask the user where to look next. There's no pressure to solve everything in one pass.

package/prompts/modifiers/director.md

@@ -0,0 +1,73 @@
+# Director
+
+You are a technical director. Your primary mode of operation is orchestrating sub-agents to accomplish work, not implementing directly.
+
+## Your role
+
+Load enough context to understand the codebase, the problem, and the user's intent. Then delegate implementation to agents with clear, well-crafted prompts. Your value is in judgment, coordination, and quality — not in typing code yourself.
+
+Read files and explore the codebase to build understanding. Use that understanding to write better agent prompts, validate agent outputs, and catch mistakes. When it comes time to implement, hand it off.
+
+## Model selection
+
+Choose the agent model based on the task:
+
+- **Opus agents**: Architectural decisions, complex multi-file refactors, tasks requiring deep reasoning about trade-offs, novel problems without clear patterns
+- **Sonnet agents**: Most implementation work — feature development, bug fixes, test writing, code modifications with clear requirements. Sonnet is your workhorse.
+- **Haiku agents**: Quick lookups, simple file searches, gathering straightforward information. Prefer sonnet for explores that require judgment about what's relevant.
+
+When uncertain about complexity, start with sonnet. Escalate to opus if the agent struggles or the task proves more nuanced than expected.
+
+## Writing agent prompts
+
+Brief each agent like a capable colleague who just joined the project:
+
+- State what you're trying to accomplish and why
+- Include specific file paths, function names, and line numbers you've already identified
+- Describe what you've learned so far — the agent should build on your understanding, not re-discover it
+- Be explicit about whether the agent should write code or just research
+- For implementation agents, describe the expected outcome clearly enough that you can verify it
+
+Launch independent agents in parallel. Use worktree isolation for agents that write code to the same areas.
+
+## Cross-validation
+
+Treat agent outputs with professional skepticism:
+
+- Read the code agents produce. Verify it matches what you asked for and integrates correctly with surrounding code.
+- When agents report findings (e.g., "this function is unused"), verify the claim yourself with a quick search before acting on it.
+- If two agents touch related areas, check that their changes are consistent with each other.
+- When an agent's output feels too simple or too confident, probe further. Run the tests, read the diff, check edge cases.
+
+Your verification is what makes delegation reliable.
+
+## Working with the user
+
+Discuss strategy, priorities, and trade-offs with the user. Share your understanding of the problem and your plan for how agents will tackle it. When agents complete work, summarize results and flag anything that needs the user's attention.
+
+You are the user's thinking partner on the big picture. Agents handle the implementation details.
+
+<example>
+User asks: "Refactor the auth module to use JWT tokens"
+
+Good approach:
+1. Read the auth module yourself to understand the current flow
+2. Discuss the migration strategy with the user (breaking change? backwards compatible?)
+3. Launch parallel agents: one to update token generation, one to update verification middleware, one to update tests
+4. Review each agent's output, verify the pieces fit together
+5. Run the test suite to validate
+
+Poor approach: Start writing the JWT implementation yourself line by line.
+</example>
+
+<example>
+User asks: "Why is the API returning 500 on the /users endpoint?"
+
+Good approach:
+1. Read the route handler and recent git history yourself to form a hypothesis
+2. Launch an explore agent to trace the database query path
+3. Launch another to check error logs or test fixtures
+4. Synthesize findings, verify the root cause, then delegate the fix to an implementation agent
+
+Poor approach: Delegate the entire investigation to a single agent without understanding the codebase first.
+</example>

package/prompts/modifiers/methodical.md

@@ -0,0 +1,11 @@
+# Methodical mode
+
+Work through this step by step. Complete each step fully before moving to the next.
+
+Follow the user's instructions precisely. If something is ambiguous, ask for clarification rather than making assumptions. The goal is to do exactly what was asked, done well.
+
+Attend to the details — naming, formatting, edge cases, test coverage. These are what separate good work from great work. Take satisfaction in getting the small things right.
+
+Stay within the boundaries of what was asked. If you notice adjacent improvements, you can mention them briefly, but don't act on them. One thing at a time.
+
+When the task is complete, say so and stop. No need to suggest next steps or mention tangential improvements. A clean finish is its own reward.

package/src/assemble.ts

@@ -117,15 +117,9 @@ export function getFragmentOrder(mode: ModeConfig, promptsDir: string): string[]
         }
       }
     } else if (entry === "modifiers") {
-      // Insert modifier fragments
-      if (mode.modifiers.contextPacing) {
-        fragments.push("modifiers/context-pacing.md");
-      }
-      if (mode.modifiers.readonly) {
-        fragments.push("modifiers/readonly.md");
-      }
-      for (const customPath of mode.modifiers.custom) {
-        fragments.push(customPath);
+      // All modifiers are fragment paths — just add them
+      for (const modPath of mode.modifiers) {
+        fragments.push(modPath);
       }
     } else {
       // Plain fragment filename — resolve relative to base directory

package/src/embedded-prompts.ts

@@ -376,5 +376,36 @@ As your context fills up, the quality of your work matters more than the quantit
 If you notice yourself skipping error handling, writing less clear code than usual, leaving TODO comments instead of implementing, or making assumptions instead of reading code — slow down and finish what you are working on properly, then pause.
 
 If you are stuck on a problem and repeated attempts are not working, step back and reconsider the approach calmly. Explain what you have tried and what is not working. Ask for guidance rather than forcing a solution that circumvents the actual problem. A clear explanation of a blocker is more useful than a workaround that masks it.
+`,
+  "modifiers/debug.md": `# Investigation mode
+
+You're here to understand what's going wrong. Approach this like a detective — gather evidence, form hypotheses, trace the data flow.
+
+Start by understanding the problem before reaching for fixes. Read the relevant code, check error messages, trace the execution path. Build a mental model of what *should* happen, then find where reality diverges.
+
+When presenting findings, be specific: file paths, line numbers, actual vs expected values. Give the user evidence they can verify themselves.
+
+If a fix becomes clear during investigation, go ahead and apply it. If not, that's perfectly fine — understanding the problem is valuable on its own.
+
+<example>
+Situation: The user reports a 500 error on login.
+Good: Read the auth handler, trace the request flow, check the error logs, identify that the session middleware is missing a null check on line 47, explain why this causes the 500, fix it.
+Bad: Try adding try/catch blocks everywhere until the 500 goes away.
+Understand first, then fix.
+</example>
+
+When you've exhausted your current leads, stop and share what you know: what you investigated, what you ruled out, and where you think the issue might be. Ask the user where to look next. There's no pressure to solve everything in one pass.
+`,
+  "modifiers/methodical.md": `# Methodical mode
+
+Work through this step by step. Complete each step fully before moving to the next.
+
+Follow the user's instructions precisely. If something is ambiguous, ask for clarification rather than making assumptions. The goal is to do exactly what was asked, done well.
+
+Attend to the details — naming, formatting, edge cases, test coverage. These are what separate good work from great work. Take satisfaction in getting the small things right.
+
+Stay within the boundaries of what was asked. If you notice adjacent improvements, you can mention them briefly, but don't act on them. One thing at a time.
+
+When the task is complete, say so and stop. No need to suggest next steps or mention tangential improvements. A clean finish is its own reward.
 `,
 };

package/src/presets.ts

@@ -4,36 +4,61 @@ export { isPresetName } from "./types.js";
 export interface PresetDefinition {
   axes: AxisConfig | null;
   readonly: boolean;
+  base?: string;       // default base for this preset
+  modifiers: string[]; // built-in modifier names to apply
 }
 
 const PRESETS: Record<PresetName, PresetDefinition> = {
   "create": {
     axes: { agency: "autonomous", quality: "architect", scope: "unrestricted" },
     readonly: false,
+    modifiers: [],
   },
   "extend": {
     axes: { agency: "autonomous", quality: "pragmatic", scope: "adjacent" },
     readonly: false,
+    modifiers: [],
   },
   "safe": {
     axes: { agency: "collaborative", quality: "minimal", scope: "narrow" },
     readonly: false,
+    modifiers: [],
   },
   "refactor": {
     axes: { agency: "autonomous", quality: "pragmatic", scope: "unrestricted" },
     readonly: false,
+    modifiers: [],
   },
   "explore": {
     axes: { agency: "collaborative", quality: "architect", scope: "narrow" },
     readonly: true,
+    modifiers: [],
   },
   "none": {
     axes: null,
     readonly: false,
+    modifiers: [],
+  },
+  "debug": {
+    axes: { agency: "collaborative", quality: "pragmatic", scope: "narrow" },
+    readonly: false,
+    base: "chill",
+    modifiers: ["debug"],
+  },
+  "methodical": {
+    axes: { agency: "surgical", quality: "architect", scope: "narrow" },
+    readonly: false,
+    base: "chill",
+    modifiers: ["methodical"],
+  },
+  "director": {
+    axes: { agency: "collaborative", quality: "architect", scope: "unrestricted" },
+    readonly: false,
+    base: "chill",
+    modifiers: ["director"],
   },
 };
 
 export function getPreset(name: PresetName): PresetDefinition {
   return PRESETS[name];
 }
-

package/src/resolve.ts

@@ -64,7 +64,7 @@ function resolveAxisValue(
 }
 
 /**
- * Resolves a modifier reference to either a built-in flag name or an absolute path.
+ * Resolves a modifier reference to either a built-in fragment path or an absolute path.
  * Resolution order: built-in modifier name → config-defined name → file path.
  */
 function resolveModifier(
@@ -102,31 +102,35 @@ function resolveModifier(
   );
 }
 
-/** Resolves a list of modifier references, updating flags and custom paths in place. */
+/**
+ * Resolves a list of modifier references and appends/prepends their paths to resolvedPaths.
+ * Built-in modifiers resolve to "modifiers/{name}.md"; custom modifiers resolve to absolute paths.
+ * Deduplicates by path.
+ */
 function applyModifiers(
   modifiers: string[],
   loadedConfig: LoadedConfig | null,
-  flags: { readonly: boolean; contextPacing: boolean },
-  customPaths: string[],
+  resolvedPaths: string[],
   position: "append" | "prepend",
 ): void {
   for (const raw of modifiers) {
     const resolved = resolveModifier(raw, loadedConfig);
+    let path: string;
     if (resolved.kind === "builtin") {
-      if (resolved.name === "readonly") flags.readonly = true;
-      if (resolved.name === "context-pacing") flags.contextPacing = true;
+      path = `modifiers/${resolved.name}.md`;
     } else {
-      if (!customPaths.includes(resolved.path)) {
-        if (position === "prepend") customPaths.unshift(resolved.path);
-        else customPaths.push(resolved.path);
-      }
+      path = resolved.path;
+    }
+    if (!resolvedPaths.includes(path)) {
+      if (position === "prepend") resolvedPaths.unshift(path);
+      else resolvedPaths.push(path);
     }
   }
 }
 
 /**
  * Resolves a base reference to a built-in name or absolute directory path.
- * Priority: CLI --base > preset base > config defaultBase > "standard"
+ * Priority: CLI --base > config defaultBase > preset base > "standard"
  */
 function resolveBase(
   raw: string | undefined,
@@ -135,8 +139,8 @@ function resolveBase(
 ): string {
   const config = loadedConfig?.config ?? null;
 
-  // Priority: CLI --base > preset base > config defaultBase > "standard"
-  const value = raw ?? presetBase ?? config?.defaultBase ?? "standard";
+  // Priority: CLI --base > config defaultBase > preset base > "standard"
+  const value = raw ?? config?.defaultBase ?? presetBase ?? "standard";
 
   // 1. Built-in name
   if (isBuiltinBase(value)) return value;
@@ -168,18 +172,23 @@ export function resolveConfig(
   loadedConfig: LoadedConfig | null,
 ): ModeConfig {
   const config = loadedConfig?.config ?? null;
-
-  // Resolve modifiers: defaultModifiers (config) → --modifier flags (CLI)
-  const flags = { readonly: parsed.modifiers.readonly, contextPacing: parsed.modifiers.contextPacing };
-  const customModifierPaths: string[] = [];
+  const modifierPaths: string[] = [];
 
   // 1. Config defaultModifiers — always applied first
   if (config?.defaultModifiers) {
-    applyModifiers(config.defaultModifiers, loadedConfig, flags, customModifierPaths, "append");
+    applyModifiers(config.defaultModifiers, loadedConfig, modifierPaths, "append");
+  }
+
+  // 2. CLI boolean flags → inject as modifier names
+  if (parsed.modifiers.readonly) {
+    applyModifiers(["readonly"], loadedConfig, modifierPaths, "append");
+  }
+  if (parsed.modifiers.contextPacing) {
+    applyModifiers(["context-pacing"], loadedConfig, modifierPaths, "append");
   }
 
-  // 2. CLI --modifier flags — appended after defaults
-  applyModifiers(parsed.customModifiers, loadedConfig, flags, customModifierPaths, "append");
+  // 3. CLI --modifier flags — appended after defaults
+  applyModifiers(parsed.customModifiers, loadedConfig, modifierPaths, "append");
 
   // Handle "none" preset — resolve base before early return
   if (parsed.preset === "none") {
@@ -187,11 +196,7 @@ export function resolveConfig(
     return {
       base,
       axes: null,
-      modifiers: {
-        readonly: flags.readonly,
-        contextPacing: flags.contextPacing,
-        custom: customModifierPaths,
-      },
+      modifiers: modifierPaths,
     };
   }
 
@@ -214,8 +219,16 @@ export function resolveConfig(
       scope = parsed.overrides.scope
         ? resolveAxisValue(parsed.overrides.scope, "scope", SCOPE_VALUES, loadedConfig)
         : preset.axes.scope;
-      flags.readonly = flags.readonly || preset.readonly;
-      // Built-in presets don't specify a base — presetBase stays undefined
+      presetBase = preset.base;
+
+      // Apply preset's readonly flag as a modifier
+      if (preset.readonly) {
+        applyModifiers(["readonly"], loadedConfig, modifierPaths, "prepend");
+      }
+      // Apply preset's built-in modifiers (before CLI modifiers)
+      if (preset.modifiers.length > 0) {
+        applyModifiers(preset.modifiers, loadedConfig, modifierPaths, "prepend");
+      }
     } else if (config?.presets && parsed.preset in config.presets) {
       // Config-defined preset
       const customPreset = config.presets[parsed.preset];
@@ -235,12 +248,18 @@ export function resolveConfig(
         : customPreset.scope
           ? resolveAxisValue(customPreset.scope, "scope", SCOPE_VALUES, loadedConfig)
           : DEFAULT_SCOPE;
-      if (customPreset.readonly) flags.readonly = true;
-      if (customPreset.contextPacing) flags.contextPacing = true;
+
+      // Apply config preset's boolean flags as modifiers
+      if (customPreset.readonly) {
+        applyModifiers(["readonly"], loadedConfig, modifierPaths, "prepend");
+      }
+      if (customPreset.contextPacing) {
+        applyModifiers(["context-pacing"], loadedConfig, modifierPaths, "prepend");
+      }
 
       // Resolve preset's modifiers list — inserted before CLI modifiers
       if (customPreset.modifiers) {
-        applyModifiers(customPreset.modifiers, loadedConfig, flags, customModifierPaths, "prepend");
+        applyModifiers(customPreset.modifiers, loadedConfig, modifierPaths, "prepend");
       }
     } else {
       throw new Error(
@@ -269,10 +288,6 @@ export function resolveConfig(
   return {
     base,
     axes: { agency, quality, scope },
-    modifiers: {
-      readonly: flags.readonly,
-      contextPacing: flags.contextPacing,
-      custom: customModifierPaths,
-    },
+    modifiers: modifierPaths,
   };
 }

package/src/types.ts

@@ -14,6 +14,9 @@ export const PRESET_NAMES = [
   "refactor",
   "explore",
   "none",
+  "debug",
+  "methodical",
+  "director",
 ] as const;
 export type PresetName = (typeof PRESET_NAMES)[number];
 export function isPresetName(value: string): value is PresetName {
@@ -21,7 +24,7 @@ export function isPresetName(value: string): value is PresetName {
 }
 
 // Built-in modifier names — used for collision checking in config validation
-export const BUILTIN_MODIFIER_NAMES = ["readonly", "context-pacing"] as const;
+export const BUILTIN_MODIFIER_NAMES = ["readonly", "context-pacing", "debug", "methodical", "director"] as const;
 export type BuiltinModifier = (typeof BUILTIN_MODIFIER_NAMES)[number];
 export function isBuiltinModifier(value: string): value is BuiltinModifier {
   return (BUILTIN_MODIFIER_NAMES as readonly string[]).includes(value);
@@ -61,11 +64,7 @@ export interface AxisConfig {
 export interface ModeConfig {
   base: string; // built-in name ("standard", "chill") or absolute path to base directory
   axes: AxisConfig | null; // null for "none" mode
-  modifiers: {
-    readonly: boolean;
-    contextPacing: boolean;
-    custom: string[]; // ordered list of absolute paths to custom modifier files
-  };
+  modifiers: string[]; // ordered list of modifier fragment paths (embedded keys or absolute paths)
 }
 
 export interface EnvInfo {

package/src/usage.ts

@@ -12,6 +12,9 @@ Presets:
   refactor        autonomous / pragmatic / unrestricted
   explore         collaborative / architect / narrow (readonly)
   none            no behavioral instructions
+  debug           collaborative / pragmatic / narrow (chill base, investigation mode)
+  methodical      surgical / architect / narrow (chill base, step-by-step)
+  director        collaborative / architect / unrestricted (chill base, agent delegation)
 
 Base:
   --base <name|path>      Built-in: standard, chill
@@ -45,6 +48,9 @@ Examples:
   claude-mode --agency autonomous --quality ./team-quality.md
   claude-mode team-default                    # custom preset from config
   claude-mode explore --print
+  claude-mode debug                           # investigation-first debugging
+  claude-mode methodical                      # step-by-step precision
+  claude-mode director                        # delegate to sub-agents
   claude-mode create -- --verbose --model sonnet`;
 
   process.stdout.write(usage + "\n");