feat: add _i alias and CLI flags for interactive mode

- Add --_interactive and -_i CLI flags (consumed by ma, not passed to command)
- Add _i as shorthand alias for _interactive in frontmatter
- Fix handling of empty YAML values (_interactive: and _i: now enable interactive mode)
- Add comprehensive tests for applyInteractiveMode function
- Update README with new CLI flags and frontmatter options

Author: johnlindquist

README.md

@@ -173,7 +173,7 @@ The `--feature_name` and `--target_dir` flags are consumed by markdown-agent for
 | `env` | object | Set process environment variables |
 | `env` | string[] | Pass as `--env` flags to command |
 | `$1`, `$2`... | string | Map positional args to flags (e.g., `$1: prompt`) |
-| `_interactive` | boolean | Enable interactive mode (overrides print-mode defaults) |
+| `_interactive` / `_i` | boolean | Enable interactive mode (overrides print-mode defaults) |
 | `_subcommand` | string/string[] | Prepend subcommand(s) to CLI args |
 
 ### All Other Keys → CLI Flags
@@ -199,7 +199,7 @@ p: true                               # → -p (single char = short flag)
 
 ## Print vs Interactive Mode
 
-All commands run in **print mode by default** (non-interactive, exit after completion). Use the `.i.` filename marker or `_interactive: true` to enable interactive mode.
+All commands run in **print mode by default** (non-interactive, exit after completion). Use the `.i.` filename marker, `_interactive` frontmatter, or CLI flags to enable interactive mode.
 
 ### Print Mode (Default)
 
@@ -221,16 +221,23 @@ task.i.codex.md     # Runs: codex "..." (interactive session)
 task.i.gemini.md    # Runs: gemini --prompt-interactive "..."
 ```
 
-Or use `_interactive: true` in frontmatter:
+Or use `_interactive` (or `_i`) in frontmatter:
 
 ```yaml
 ---
-_interactive: true
+_interactive: true   # or _interactive: (empty), or _i:
 model: opus
 ---
 Review this code with me interactively.
 ```
 
+Or use CLI flags:
+
+```bash
+ma task.claude.md --_interactive  # Enable interactive mode
+ma task.claude.md -_i             # Short form
+```
+
 ---
 
 ## Global Configuration
@@ -478,12 +485,18 @@ Command resolution:
 All frontmatter keys are passed as CLI flags to the command.
 Global defaults can be set in ~/.markdown-agent/config.yaml
 
+ma-specific flags (consumed, not passed to command):
+  --command, -c       Specify command to run
+  --dry-run           Preview without executing
+  --_interactive, -_i Enable interactive mode
+
 Examples:
   ma task.claude.md -p "print mode"
   ma task.claude.md --model opus --verbose
   ma commit.gemini.md
   ma task.md --command claude
   ma task.md -c gemini
+  ma task.claude.md -_i  # Run in interactive mode
 
 Without a file:
   ma --setup    Configure shell to run .md files directly

src/config.test.ts

@@ -3,6 +3,7 @@ import {
   loadGlobalConfig,
   getCommandDefaults,
   applyDefaults,
+  applyInteractiveMode,
   clearConfigCache,
   findGitRoot,
   loadProjectConfig,
@@ -310,3 +311,92 @@ describe("config cascade", () => {
     expect(config.commands?.claude?.model).toBe("opus");
   });
 });
+
+describe("applyInteractiveMode", () => {
+  test("removes print flag for claude with _interactive: true", () => {
+    const frontmatter = { print: true, model: "opus", _interactive: true };
+    const result = applyInteractiveMode(frontmatter, "claude");
+    expect(result.print).toBeUndefined();
+    expect(result._interactive).toBeUndefined();
+    expect(result.model).toBe("opus");
+  });
+
+  test("removes print flag for claude with _i: true", () => {
+    const frontmatter = { print: true, model: "opus", _i: true };
+    const result = applyInteractiveMode(frontmatter, "claude");
+    expect(result.print).toBeUndefined();
+    expect(result._i).toBeUndefined();
+    expect(result.model).toBe("opus");
+  });
+
+  test("handles _interactive with null value (YAML empty key)", () => {
+    const frontmatter = { print: true, _interactive: null };
+    const result = applyInteractiveMode(frontmatter, "claude");
+    expect(result.print).toBeUndefined();
+    expect(result._interactive).toBeUndefined();
+  });
+
+  test("handles _i with null value (YAML empty key)", () => {
+    const frontmatter = { print: true, _i: null };
+    const result = applyInteractiveMode(frontmatter, "claude");
+    expect(result.print).toBeUndefined();
+    expect(result._i).toBeUndefined();
+  });
+
+  test("handles _interactive with empty string value", () => {
+    const frontmatter = { print: true, _interactive: "" };
+    const result = applyInteractiveMode(frontmatter, "claude");
+    expect(result.print).toBeUndefined();
+  });
+
+  test("handles _i with empty string value", () => {
+    const frontmatter = { print: true, _i: "" };
+    const result = applyInteractiveMode(frontmatter, "claude");
+    expect(result.print).toBeUndefined();
+  });
+
+  test("does not trigger interactive mode with _interactive: false", () => {
+    const frontmatter = { print: true, _interactive: false };
+    const result = applyInteractiveMode(frontmatter, "claude");
+    expect(result.print).toBe(true);
+  });
+
+  test("does not trigger interactive mode when _interactive not present", () => {
+    const frontmatter = { print: true, model: "opus" };
+    const result = applyInteractiveMode(frontmatter, "claude");
+    expect(result.print).toBe(true);
+  });
+
+  test("triggers interactive mode via external flag (interactiveFromExternal)", () => {
+    const frontmatter = { print: true, model: "opus" };
+    const result = applyInteractiveMode(frontmatter, "claude", true);
+    expect(result.print).toBeUndefined();
+    expect(result.model).toBe("opus");
+  });
+
+  test("changes copilot $1 from prompt to interactive", () => {
+    const frontmatter = { $1: "prompt", silent: true, _interactive: true };
+    const result = applyInteractiveMode(frontmatter, "copilot");
+    expect(result.$1).toBe("interactive");
+    expect(result.silent).toBe(true);
+  });
+
+  test("removes _subcommand for codex", () => {
+    const frontmatter = { _subcommand: "exec", _interactive: true };
+    const result = applyInteractiveMode(frontmatter, "codex");
+    expect(result._subcommand).toBeUndefined();
+  });
+
+  test("adds prompt-interactive for gemini", () => {
+    const frontmatter = { model: "pro", _interactive: true };
+    const result = applyInteractiveMode(frontmatter, "gemini");
+    expect(result.$1).toBe("prompt-interactive");
+  });
+
+  test("unknown command just removes _interactive", () => {
+    const frontmatter = { custom: "value", _interactive: true };
+    const result = applyInteractiveMode(frontmatter, "my-custom-cli");
+    expect(result._interactive).toBeUndefined();
+    expect(result.custom).toBe("value");
+  });
+});

src/config.ts

@@ -55,17 +55,29 @@ export const BUILTIN_DEFAULTS: GlobalConfig = {
 export function applyInteractiveMode(
   frontmatter: AgentFrontmatter,
   command: string,
-  interactiveFromFilename: boolean = false
+  interactiveFromExternal: boolean = false
 ): AgentFrontmatter {
-  // Check if _interactive is enabled (truthy, empty string, or from filename)
-  const interactiveMode = frontmatter._interactive ?? interactiveFromFilename;
-  if (!interactiveMode && interactiveMode !== "") {
+  // Check if _interactive or _i is enabled
+  // Can be: true, empty string (YAML key with no value), null (YAML key with explicit null), or external trigger
+  // NOTE: We check key existence separately because ?? treats null as "nullish" and skips to next value
+  const hasInteractiveKey = "_interactive" in frontmatter;
+  const hasIKey = "_i" in frontmatter;
+  const interactiveValue = hasInteractiveKey ? frontmatter._interactive : frontmatter._i;
+  const interactiveMode = interactiveFromExternal ||
+    interactiveValue === true ||
+    interactiveValue === "" ||
+    (hasInteractiveKey && interactiveValue === null) ||
+    (hasIKey && interactiveValue === null) ||
+    (interactiveValue !== undefined && interactiveValue !== false);
+
+  if (!interactiveMode) {
     return frontmatter;
   }
 
-  // Remove _interactive from output (it's a meta-key, not a CLI flag)
+  // Remove _interactive and _i from output (they're meta-keys, not CLI flags)
   const result = { ...frontmatter };
   delete result._interactive;
+  delete result._i;
 
   switch (command) {
     case "copilot":

src/index.ts

@@ -218,6 +218,14 @@ async function main() {
       remainingArgs.splice(trustIndex, 1); // Consume it
     }
 
+    // Check for --_interactive or -_i flag (consumed by ma, enables interactive mode)
+    let interactiveFromCli = false;
+    const interactiveIndex = remainingArgs.findIndex(arg => arg === "--_interactive" || arg === "-_i");
+    if (interactiveIndex !== -1) {
+      interactiveFromCli = true;
+      remainingArgs.splice(interactiveIndex, 1); // Consume it
+    }
+
     // Resolve command: CLI --command > MA_COMMAND env > filename
     let command: string;
     try {
@@ -242,7 +250,8 @@ async function main() {
     const interactiveFromFilename = hasInteractiveMarker(localFilePath);
 
     // Apply _interactive mode transformations (converts print defaults to interactive mode per command)
-    frontmatter = applyInteractiveMode(frontmatter, command, interactiveFromFilename);
+    // Interactive can be triggered by: CLI flag (--_interactive/-_i), filename (.i.), or frontmatter (_interactive/_i)
+    frontmatter = applyInteractiveMode(frontmatter, command, interactiveFromFilename || interactiveFromCli);
 
     // Extract and apply environment variables (object form) to process.env
     // This must happen BEFORE import expansion so !`command` inlines can use them