feat: add .ma/ agent discovery for user and project levels

- Add ~/.ma/ for user-level agents (available everywhere)
- Add ./.ma/ for project-level agents
- Discovery priority: cwd > ./.ma/ > ~/.ma/ > $PATH
- Export getProjectAgentsDir() and getUserAgentsDir() helpers
- Update help text with new discovery documentation
- Add 6 tests for new discovery functionality

Author: johnlindquist

src/cli.test.ts

@@ -1,5 +1,8 @@
-import { expect, test, describe } from "bun:test";
-import { parseCliArgs } from "./cli";
+import { expect, test, describe, beforeEach, afterEach } from "bun:test";
+import { parseCliArgs, findAgentFiles, getProjectAgentsDir, getUserAgentsDir } from "./cli";
+import { mkdirSync, writeFileSync, rmSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
 
 describe("parseCliArgs", () => {
   test("extracts file path", () => {
@@ -45,3 +48,82 @@ describe("parseCliArgs", () => {
     expect(result.passthroughArgs).toEqual(["--help", "--setup"]);
   });
 });
+
+describe("agent directory paths", () => {
+  test("getProjectAgentsDir returns .ma in cwd", () => {
+    const dir = getProjectAgentsDir();
+    expect(dir).toBe(join(process.cwd(), ".ma"));
+  });
+
+  test("getUserAgentsDir returns ~/.ma", () => {
+    const dir = getUserAgentsDir();
+    expect(dir).toBe(join(homedir(), ".ma"));
+  });
+});
+
+describe("findAgentFiles", () => {
+  const testProjectMaDir = join(process.cwd(), ".ma-test");
+  const testUserMaDir = join(homedir(), ".ma-test-user");
+
+  beforeEach(() => {
+    // Create test directories
+    if (!existsSync(testProjectMaDir)) {
+      mkdirSync(testProjectMaDir, { recursive: true });
+    }
+  });
+
+  afterEach(() => {
+    // Cleanup test directories
+    if (existsSync(testProjectMaDir)) {
+      rmSync(testProjectMaDir, { recursive: true, force: true });
+    }
+  });
+
+  test("finds files from current directory", async () => {
+    const files = await findAgentFiles();
+    // Should find .md files in cwd (like CLAUDE.md, README.md, etc.)
+    const cwdFiles = files.filter(f => f.source === "cwd");
+    expect(cwdFiles.length).toBeGreaterThan(0);
+  });
+
+  test("finds files from .ma/ directory when present", async () => {
+    // Create a test .ma directory with a file
+    const maDir = join(process.cwd(), ".ma");
+    const testFile = join(maDir, "test-agent.claude.md");
+
+    try {
+      mkdirSync(maDir, { recursive: true });
+      writeFileSync(testFile, "---\nmodel: opus\n---\nTest agent");
+
+      const files = await findAgentFiles();
+      const maFiles = files.filter(f => f.source === ".ma");
+
+      expect(maFiles.length).toBeGreaterThan(0);
+      expect(maFiles.some(f => f.name === "test-agent.claude.md")).toBe(true);
+    } finally {
+      // Cleanup
+      if (existsSync(testFile)) rmSync(testFile);
+      if (existsSync(maDir)) rmSync(maDir, { recursive: true, force: true });
+    }
+  });
+
+  test("deduplicates files by normalized path", async () => {
+    const files = await findAgentFiles();
+    const paths = files.map(f => f.path);
+    const uniquePaths = new Set(paths);
+    expect(paths.length).toBe(uniquePaths.size);
+  });
+
+  test("returns files with correct structure", async () => {
+    const files = await findAgentFiles();
+    if (files.length > 0) {
+      const file = files[0];
+      expect(file).toHaveProperty("name");
+      expect(file).toHaveProperty("path");
+      expect(file).toHaveProperty("source");
+      expect(typeof file.name).toBe("string");
+      expect(typeof file.path).toBe("string");
+      expect(typeof file.source).toBe("string");
+    }
+  });
+});

src/cli.ts

@@ -1,7 +1,8 @@
 import { select } from "@inquirer/prompts";
 import { Glob } from "bun";
-import { basename } from "path";
+import { basename, join } from "path";
 import { realpathSync } from "fs";
+import { homedir } from "os";
 
 export interface CliArgs {
   filePath: string;
@@ -87,6 +88,13 @@ Command resolution:
   1. --command flag (e.g., ma task.md --command claude)
   2. Filename pattern (e.g., task.claude.md → claude)
 
+Agent file discovery (in priority order):
+  1. Explicit path:      ma ./path/to/agent.md
+  2. Current directory:  ./
+  3. Project agents:     ./.ma/
+  4. User agents:        ~/.ma/
+  5. $PATH directories
+
 All frontmatter keys are passed as CLI flags to the command.
 Global defaults can be set in ~/.markdown-agent/config.yaml
 
@@ -116,9 +124,10 @@ ma-specific flags (consumed, not passed to command):
   --trust         Skip trust prompt for remote URLs (TOFU bypass)
 
 Without a file:
-  ma --setup    Configure shell to run .md files directly
-  ma --logs     Show log directory
-  ma --help     Show this help
+  ma             Interactive agent picker (from ./.ma/, ~/.ma/, etc.)
+  ma --setup     Configure shell to run .md files directly
+  ma --logs      Show log directory
+  ma --help      Show this help
 `);
 }
 
@@ -135,9 +144,20 @@ function normalizePath(filePath: string): string {
   }
 }
 
+/** Project-level agent directory */
+const PROJECT_AGENTS_DIR = ".ma";
+
+/** User-level agent directory */
+const USER_AGENTS_DIR = join(homedir(), ".ma");
+
 /**
- * Find agent markdown files from current directory and $PATH
- * Returns files sorted by source (cwd first, then PATH directories)
+ * Find agent markdown files with priority order:
+ * 1. Current directory (cwd)
+ * 2. Project-level: ./.ma/
+ * 3. User-level: ~/.ma/
+ * 4. $PATH directories
+ *
+ * Returns files sorted by source priority (earlier sources take precedence)
  */
 export async function findAgentFiles(): Promise<AgentFile[]> {
   const files: AgentFile[] = [];
@@ -158,7 +178,34 @@ export async function findAgentFiles(): Promise<AgentFile[]> {
     // Skip if cwd is not accessible
   }
 
-  // 2. $PATH directories
+  // 2. Project-level: ./.ma/
+  const projectAgentsPath = join(process.cwd(), PROJECT_AGENTS_DIR);
+  try {
+    for await (const file of glob.scan({ cwd: projectAgentsPath, absolute: true })) {
+      const normalizedPath = normalizePath(file);
+      if (!seenPaths.has(normalizedPath)) {
+        seenPaths.add(normalizedPath);
+        files.push({ name: basename(file), path: normalizedPath, source: ".ma" });
+      }
+    }
+  } catch {
+    // Skip if .ma/ doesn't exist
+  }
+
+  // 3. User-level: ~/.ma/
+  try {
+    for await (const file of glob.scan({ cwd: USER_AGENTS_DIR, absolute: true })) {
+      const normalizedPath = normalizePath(file);
+      if (!seenPaths.has(normalizedPath)) {
+        seenPaths.add(normalizedPath);
+        files.push({ name: basename(file), path: normalizedPath, source: "~/.ma" });
+      }
+    }
+  } catch {
+    // Skip if ~/.ma/ doesn't exist
+  }
+
+  // 4. $PATH directories
   const pathDirs = (process.env.PATH || "").split(":");
   for (const dir of pathDirs) {
     if (!dir) continue;
@@ -178,6 +225,20 @@ export async function findAgentFiles(): Promise<AgentFile[]> {
   return files;
 }
 
+/**
+ * Get the project agents directory path
+ */
+export function getProjectAgentsDir(): string {
+  return join(process.cwd(), PROJECT_AGENTS_DIR);
+}
+
+/**
+ * Get the user agents directory path
+ */
+export function getUserAgentsDir(): string {
+  return USER_AGENTS_DIR;
+}
+
 /**
  * Show interactive file picker and return selected file path
  */