feat: add --command flag hijacking for generic markdown files

- Add --command / -c flag to override command resolution
- Priority: --command > MA_COMMAND env > filename pattern
- Flag is consumed (not passed to underlying command)
- Allows generic .md files without command in filename
- Document flag hijacking in README (--command and $varname)
- Add tests for flag hijacking behavior

Author: johnlindquist

README.md

@@ -114,13 +114,55 @@ ma task.claude.md --verbose --debug
 
 Commands are resolved in this priority order:
 
-1. **Environment variable**: `MA_COMMAND=claude`
-2. **Filename pattern**: `task.claude.md` → `claude`
+1. **CLI flag**: `--command claude` or `-c claude`
+2. **Environment variable**: `MA_COMMAND=claude`
+3. **Filename pattern**: `task.claude.md` → `claude`
 
 If no command can be resolved, you'll get an error with instructions.
 
 ---
 
+## Flag Hijacking
+
+Some CLI flags are "hijacked" by markdown-agent—they're consumed and never passed to the underlying command. This allows generic markdown files without command names to be executed.
+
+### `--command` / `-c`
+
+Override the command for any markdown file:
+
+```bash
+# Run a generic .md file with any command
+ma task.md --command claude
+ma task.md -c gemini
+
+# Override the filename-inferred command
+ma task.claude.md --command gemini  # Runs gemini, not claude
+```
+
+### `$varname` Fields
+
+Frontmatter fields starting with `$` (except `$1`, `$2`...) hijack their corresponding CLI flags:
+
+```yaml
+---
+$feature_name: Authentication   # Default value
+$target_dir: src/features       # Default value
+---
+Build {{ feature_name }} in {{ target_dir }}.
+```
+
+```bash
+# Use defaults
+ma create.claude.md
+
+# Override with CLI flags (hijacked, not passed to command)
+ma create.claude.md --feature_name "Payments" --target_dir "src/billing"
+```
+
+The `--feature_name` and `--target_dir` flags are consumed by markdown-agent for template substitution—they won't be passed to the command.
+
+---
+
 ## Frontmatter Reference
 
 ### System Keys (handled by markdown-agent)
@@ -377,13 +419,15 @@ Environment variables are available:
 
 ```
 Usage: ma <file.md> [any flags for the command]
+       ma <file.md> --command <cmd>
        ma --setup
        ma --logs
        ma --help
 
 Command resolution:
-  1. MA_COMMAND env var (e.g., MA_COMMAND=claude ma task.md)
-  2. Filename pattern (e.g., task.claude.md → claude)
+  1. --command flag (e.g., ma task.md --command claude)
+  2. MA_COMMAND env var (e.g., MA_COMMAND=claude ma task.md)
+  3. Filename pattern (e.g., task.claude.md → claude)
 
 All frontmatter keys are passed as CLI flags to the command.
 Global defaults can be set in ~/.markdown-agent/config.yaml
@@ -392,6 +436,8 @@ 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_COMMAND=claude ma task.md
 
 Without a file:

src/args.test.ts

@@ -1,6 +1,7 @@
 import { expect, test, describe } from "bun:test";
 import { parseFrontmatter } from "./parse";
 import { substituteTemplateVars, extractTemplateVars } from "./template";
+import { resolveCommand } from "./command";
 
 /**
  * Tests for the args system:
@@ -168,3 +169,48 @@ Build {{ feature_name }}`;
     expect(result).toBe("Build Payments");
   });
 });
+
+describe("flag hijacking", () => {
+  test("--command flag is consumed and used as command", () => {
+    // Simulate CLI: ma generic.md --command claude --model opus
+    const cliArgs = ["--command", "claude", "--model", "opus"];
+
+    // Extract --command flag (same logic as index.ts)
+    let commandFromCli: string | undefined;
+    const remainingArgs = [...cliArgs];
+
+    const commandFlagIndex = remainingArgs.findIndex(arg => arg === "--command" || arg === "-c");
+    if (commandFlagIndex !== -1 && commandFlagIndex + 1 < remainingArgs.length) {
+      commandFromCli = remainingArgs[commandFlagIndex + 1];
+      remainingArgs.splice(commandFlagIndex, 2);
+    }
+
+    expect(commandFromCli).toBe("claude");
+    expect(remainingArgs).toEqual(["--model", "opus"]); // --command consumed
+  });
+
+  test("-c short flag also works for command", () => {
+    const cliArgs = ["-c", "gemini", "--verbose"];
+    const remainingArgs = [...cliArgs];
+
+    let commandFromCli: string | undefined;
+    const commandFlagIndex = remainingArgs.findIndex(arg => arg === "--command" || arg === "-c");
+    if (commandFlagIndex !== -1 && commandFlagIndex + 1 < remainingArgs.length) {
+      commandFromCli = remainingArgs[commandFlagIndex + 1];
+      remainingArgs.splice(commandFlagIndex, 2);
+    }
+
+    expect(commandFromCli).toBe("gemini");
+    expect(remainingArgs).toEqual(["--verbose"]);
+  });
+
+  test("--command takes priority over filename", () => {
+    // If --command is provided, it takes priority
+    // (filename would give "codex" but --command says "claude")
+    const commandFromCli = "claude";
+    const commandFromFilename = "codex"; // from task.codex.md
+
+    const command = commandFromCli || commandFromFilename;
+    expect(command).toBe("claude");
+  });
+});

src/index.ts

@@ -76,11 +76,27 @@ async function main() {
   const { frontmatter: baseFrontmatter, body: rawBody } = parseFrontmatter(content);
   getParseLogger().debug({ frontmatter: baseFrontmatter, bodyLength: rawBody.length }, "Frontmatter parsed");
 
-  // Resolve command (from env var or filename)
+  // Check for --command flag in CLI args (consumed, not passed to command)
+  // This allows: ma generic.md --command claude
+  let remainingArgs = [...passthroughArgs];
+  let commandFromCli: string | undefined;
+
+  const commandFlagIndex = remainingArgs.findIndex(arg => arg === "--command" || arg === "-c");
+  if (commandFlagIndex !== -1 && commandFlagIndex + 1 < remainingArgs.length) {
+    commandFromCli = remainingArgs[commandFlagIndex + 1];
+    remainingArgs.splice(commandFlagIndex, 2); // Consume --command and its value
+  }
+
+  // Resolve command: CLI --command > MA_COMMAND env > filename
   let command: string;
   try {
-    command = resolveCommand(localFilePath);
-    getCommandLogger().debug({ command }, "Command resolved");
+    if (commandFromCli) {
+      command = commandFromCli;
+      getCommandLogger().debug({ command, source: "cli" }, "Command from --command flag");
+    } else {
+      command = resolveCommand(localFilePath);
+      getCommandLogger().debug({ command }, "Command resolved");
+    }
   } catch (err) {
     getCommandLogger().error({ error: (err as Error).message }, "Command resolution failed");
     console.error((err as Error).message);
@@ -103,7 +119,6 @@ async function main() {
 
   // Consume named positional arguments from CLI
   let templateVars: Record<string, string> = {};
-  let remainingArgs = [...passthroughArgs];
 
   if (frontmatter.args && Array.isArray(frontmatter.args)) {
     const requiredArgs = frontmatter.args;