fix: align description fallback pattern across commands, subagents and rules

src/features/commands/agentsmd-command.test.ts

@@ -21,8 +21,7 @@ This is the body of the agentsmd command.
 It can be multiline.`;
 
   const invalidMarkdownContent = `---
-# Missing required description field
-invalid: true
+description: 123
 ---
 
 Body content`;
@@ -105,20 +104,18 @@ Body content`;
       expect(command).toBeInstanceOf(AgentsmdCommand);
     });
 
-    it("should throw error for invalid frontmatter when validation is enabled", () => {
-      expect(
-        () =>
-          new AgentsmdCommand({
-            baseDir: testDir,
-            relativeDirPath: ".agents/commands",
-            relativeFilePath: "invalid-command.md",
-            frontmatter: {
-              // Missing required description field
-            } as SimulatedCommandFrontmatter,
-            body: "Body content",
-            validate: true,
-          }),
-      ).toThrow();
+    it("should accept frontmatter without description (description is optional)", () => {
+      const command = new AgentsmdCommand({
+        baseDir: testDir,
+        relativeDirPath: ".agents/commands",
+        relativeFilePath: "no-desc-command.md",
+        frontmatter: {} as SimulatedCommandFrontmatter,
+        body: "Body content",
+        validate: true,
+      });
+
+      expect(command).toBeInstanceOf(AgentsmdCommand);
+      expect(command.getFrontmatter().description).toBeUndefined();
     });
   });
 
@@ -320,19 +317,20 @@ Body content`;
       ).rejects.toThrow();
     });
 
-    it("should handle file without frontmatter", async () => {
+    it("should handle file without frontmatter (description is optional)", async () => {
       const commandsDir = join(testDir, ".agents", "commands");
       const filePath = join(commandsDir, "no-frontmatter.md");
 
       await writeFileContent(filePath, markdownWithoutFrontmatter);
 
-      await expect(
-        AgentsmdCommand.fromFile({
-          baseDir: testDir,
-          relativeFilePath: "no-frontmatter.md",
-          validate: true,
-        }),
-      ).rejects.toThrow();
+      const command = await AgentsmdCommand.fromFile({
+        baseDir: testDir,
+        relativeFilePath: "no-frontmatter.md",
+        validate: true,
+      });
+
+      expect(command).toBeInstanceOf(AgentsmdCommand);
+      expect(command.getFrontmatter().description).toBeUndefined();
     });
   });
 

src/features/commands/antigravity-command.ts

@@ -23,7 +23,7 @@ const AntigravityWorkflowFrontmatterSchema = z.looseObject({
 
 // looseObject preserves unknown keys during parsing (like passthrough in Zod 3)
 export const AntigravityCommandFrontmatterSchema = z.looseObject({
-  description: z.string(),
+  description: z.optional(z.string()),
   // Support for workflow-specific configuration
   ...AntigravityWorkflowFrontmatterSchema.shape,
 });

src/features/commands/claudecode-command.test.ts

@@ -580,11 +580,14 @@ Roundtrip body`;
       }
     });
 
-    it("should reject frontmatter without description", () => {
-      const invalidFrontmatter = {};
-      const result = ClaudecodeCommandFrontmatterSchema.safeParse(invalidFrontmatter);
+    it("should accept frontmatter without description (description is optional)", () => {
+      const frontmatter = {};
+      const result = ClaudecodeCommandFrontmatterSchema.safeParse(frontmatter);
 
-      expect(result.success).toBe(false);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.description).toBeUndefined();
+      }
     });
 
     it("should reject frontmatter with non-string description", () => {

src/features/commands/claudecode-command.ts

@@ -17,7 +17,7 @@ import {
 
 // looseObject preserves unknown keys during parsing (like passthrough in Zod 3)
 export const ClaudecodeCommandFrontmatterSchema = z.looseObject({
-  description: z.string(),
+  description: z.optional(z.string()),
   "allowed-tools": z.optional(z.union([z.string(), z.array(z.string())])),
   "argument-hint": z.optional(z.string()),
   model: z.optional(z.string()),

src/features/commands/cline-command.ts

@@ -30,7 +30,6 @@ export class ClineCommand extends ToolCommand {
   toRulesyncCommand(): RulesyncCommand {
     const rulesyncFrontmatter: RulesyncCommandFrontmatter = {
       targets: ["*"],
-      description: "",
     };
 
     return new RulesyncCommand({

src/features/commands/codexcli-command.ts

@@ -27,7 +27,6 @@ export class CodexcliCommand extends ToolCommand {
   toRulesyncCommand(): RulesyncCommand {
     const rulesyncFrontmatter: RulesyncCommandFrontmatter = {
       targets: ["*"],
-      description: "",
     };
 
     return new RulesyncCommand({

src/features/commands/copilot-command.test.ts

@@ -25,8 +25,8 @@ This is the body of the copilot command.
 It can be multiline.`;
 
   const invalidMarkdownContent = `---
-# Missing required description field
-mode: agent
+mode: 123
+description: 456
 ---
 
 Body content`;
@@ -114,20 +114,18 @@ Body content`;
       expect(command).toBeInstanceOf(CopilotCommand);
     });
 
-    it("should throw error for invalid frontmatter when validation is enabled", () => {
-      expect(
-        () =>
-          new CopilotCommand({
-            baseDir: testDir,
-            relativeDirPath: join(".github", "prompts"),
-            relativeFilePath: "invalid-command.prompt.md",
-            frontmatter: {
-              // Missing required mode and description field
-            } as CopilotCommandFrontmatter,
-            body: "Body content",
-            validate: true,
-          }),
-      ).toThrow();
+    it("should accept frontmatter without description (description is optional)", () => {
+      const command = new CopilotCommand({
+        baseDir: testDir,
+        relativeDirPath: join(".github", "prompts"),
+        relativeFilePath: "no-desc-command.prompt.md",
+        frontmatter: {} as CopilotCommandFrontmatter,
+        body: "Body content",
+        validate: true,
+      });
+
+      expect(command).toBeInstanceOf(CopilotCommand);
+      expect(command.getFrontmatter().description).toBeUndefined();
     });
   });
 
@@ -351,18 +349,19 @@ Body content`;
       ).rejects.toThrow();
     });
 
-    it("should handle file without frontmatter", async () => {
+    it("should handle file without frontmatter (description is optional)", async () => {
       const commandsDir = join(testDir, ".github", "prompts");
       const filePath = join(commandsDir, "no-frontmatter.prompt.md");
 
       await writeFileContent(filePath, markdownWithoutFrontmatter);
 
-      await expect(
-        CopilotCommand.fromFile({
-          relativeFilePath: "no-frontmatter.prompt.md",
-          validate: true,
-        }),
-      ).rejects.toThrow();
+      const command = await CopilotCommand.fromFile({
+        relativeFilePath: "no-frontmatter.prompt.md",
+        validate: true,
+      });
+
+      expect(command).toBeInstanceOf(CopilotCommand);
+      expect(command.getFrontmatter().description).toBeUndefined();
     });
   });
 
@@ -426,12 +425,14 @@ Body content`;
       expect(result).toEqual(validFrontmatter);
     });
 
-    it("should throw error for frontmatter without description", () => {
-      const invalidFrontmatter = {
+    it("should accept frontmatter without description (description is optional)", () => {
+      const frontmatter = {
         mode: "agent",
       };
 
-      expect(() => CopilotCommandFrontmatterSchema.parse(invalidFrontmatter)).toThrow();
+      const result = CopilotCommandFrontmatterSchema.parse(frontmatter);
+      expect(result.mode).toBe("agent");
+      expect(result.description).toBeUndefined();
     });
 
     it("should validate frontmatter with any string mode (mode is optional string)", () => {

src/features/commands/copilot-command.ts

@@ -18,7 +18,7 @@ import {
 // looseObject preserves unknown keys during parsing (like passthrough in Zod 3)
 export const CopilotCommandFrontmatterSchema = z.looseObject({
   mode: z.optional(z.string()),
-  description: z.string(),
+  description: z.optional(z.string()),
 });
 
 export type CopilotCommandFrontmatter = z.infer<typeof CopilotCommandFrontmatterSchema>;

src/features/commands/cursor-command.test.ts

@@ -152,7 +152,7 @@ describe("CursorCommand", () => {
       expect(rulesyncCommand.getFileContent()).toContain("Test body content");
     });
 
-    it("should default description to empty string when not set", () => {
+    it("should propagate undefined description when not set", () => {
       const command = new CursorCommand({
         baseDir: testDir,
         relativeDirPath: ".cursor/commands",
@@ -163,7 +163,7 @@ describe("CursorCommand", () => {
       });
 
       const rulesyncCommand = command.toRulesyncCommand();
-      expect(rulesyncCommand.getFrontmatter().description).toBe("");
+      expect(rulesyncCommand.getFrontmatter().description).toBeUndefined();
     });
 
     it("should preserve handoffs in cursor section", () => {

src/features/commands/cursor-command.ts

@@ -76,7 +76,7 @@ export class CursorCommand extends ToolCommand {
   }
 
   toRulesyncCommand(): RulesyncCommand {
-    const { description = "", ...restFields } = this.frontmatter;
+    const { description, ...restFields } = this.frontmatter;
 
     const rulesyncFrontmatter: RulesyncCommandFrontmatter = {
       targets: ["*"],

src/features/commands/factorydroid-command.test.ts

@@ -20,8 +20,7 @@ This is the body of the factorydroid command.
 It can be multiline.`;
 
   const invalidMarkdownContent = `---
-# Missing required fields
-invalid: true
+description: 123
 ---
 
 Body content`;

src/features/commands/geminicli-command.test.ts

@@ -75,7 +75,7 @@ prompt = "Unclosed string`;
 
       expect(command.getBody()).toBe("This is a test prompt without description.\n");
       expect(command.getFrontmatter()).toEqual({
-        description: "",
+        description: undefined,
         prompt: "This is a test prompt without description.\n",
       });
     });
@@ -134,7 +134,7 @@ prompt = "Unclosed string`;
       });
 
       const frontmatter = command.getFrontmatter() as GeminiCliCommandFrontmatter;
-      expect(frontmatter.description).toBe("");
+      expect(frontmatter.description).toBeUndefined();
       expect(frontmatter.prompt).toBe("This is a test prompt without description.\n");
     });
 
@@ -223,7 +223,7 @@ prompt = "Unclosed string`;
 
       expect(rulesyncCommand.getFrontmatter()).toEqual({
         targets: ["geminicli"],
-        description: "",
+        description: undefined,
       });
     });
   });

src/features/commands/geminicli-command.ts

@@ -58,7 +58,7 @@ export class GeminiCliCommand extends ToolCommand {
       // Preserve all fields including unknown ones (looseObject passthrough)
       return {
         ...result.data,
-        description: result.data.description || "",
+        description: result.data.description,
       };
     } catch (error) {
       throw new Error(
@@ -84,7 +84,7 @@ export class GeminiCliCommand extends ToolCommand {
 
     const rulesyncFrontmatter: RulesyncCommandFrontmatter = {
       targets: ["geminicli"],
-      description: description ?? "",
+      description: description,
       // Preserve extra fields in geminicli section (excluding prompt which is the body)
       ...(Object.keys(restFields).length > 0 && { geminicli: restFields }),
     };
@@ -123,8 +123,11 @@ export class GeminiCliCommand extends ToolCommand {
     // Generate proper file content with TOML format
     // Note: TOML format only supports description and prompt fields
     // Extra fields from geminicli section are stored in the object but not serialized to TOML
-    const tomlContent = `description = "${geminiFrontmatter.description}"
-prompt = """
+    const descriptionLine =
+      geminiFrontmatter.description !== undefined
+        ? `description = "${geminiFrontmatter.description}"\n`
+        : "";
+    const tomlContent = `${descriptionLine}prompt = """
 ${geminiFrontmatter.prompt}
 """`;
 

src/features/commands/kilo-command.test.ts

@@ -58,7 +58,7 @@ Step 1`;
       const rulesyncCommand = kiloCommand.toRulesyncCommand();
 
       expect(rulesyncCommand).toBeInstanceOf(RulesyncCommand);
-      expect(rulesyncCommand.getFrontmatter()).toEqual({ targets: ["*"], description: "" });
+      expect(rulesyncCommand.getFrontmatter()).toEqual({ targets: ["*"] });
       expect(rulesyncCommand.getBody()).toBe(validContent);
       expect(rulesyncCommand.getRelativeDirPath()).toBe(RULESYNC_COMMANDS_RELATIVE_DIR_PATH);
     });

src/features/commands/kilo-command.ts

@@ -24,7 +24,6 @@ export class KiloCommand extends ToolCommand {
   toRulesyncCommand(): RulesyncCommand {
     const rulesyncFrontmatter: RulesyncCommandFrontmatter = {
       targets: ["*"],
-      description: "",
     };
 
     return new RulesyncCommand({

src/features/commands/kiro-command.test.ts

@@ -58,7 +58,7 @@ Step 1`;
       const rulesyncCommand = kiroCommand.toRulesyncCommand();
 
       expect(rulesyncCommand).toBeInstanceOf(RulesyncCommand);
-      expect(rulesyncCommand.getFrontmatter()).toEqual({ targets: ["*"], description: "" });
+      expect(rulesyncCommand.getFrontmatter()).toEqual({ targets: ["*"] });
       expect(rulesyncCommand.getBody()).toBe(validContent);
       expect(rulesyncCommand.getRelativeDirPath()).toBe(RULESYNC_COMMANDS_RELATIVE_DIR_PATH);
     });

src/features/commands/kiro-command.ts

@@ -22,7 +22,6 @@ export class KiroCommand extends ToolCommand {
   toRulesyncCommand(): RulesyncCommand {
     const rulesyncFrontmatter: RulesyncCommandFrontmatter = {
       targets: ["*"],
-      description: "",
     };
 
     return new RulesyncCommand({

src/features/commands/opencode-command.ts

@@ -16,7 +16,7 @@ import {
 } from "./tool-command.js";
 
 export const OpenCodeCommandFrontmatterSchema = z.looseObject({
-  description: z.string(),
+  description: z.optional(z.string()),
   agent: optional(z.string()),
   subtask: optional(z.boolean()),
   model: optional(z.string()),

src/features/commands/roo-command.test.ts

@@ -422,13 +422,17 @@ This file has invalid frontmatter`;
       }
     });
 
-    it("should reject frontmatter without description", () => {
-      const invalidFrontmatter = {
-        "argument-hint": "Missing description",
+    it("should accept frontmatter without description (description is optional)", () => {
+      const frontmatter = {
+        "argument-hint": "Has hint but no description",
       };
 
-      const result = RooCommandFrontmatterSchema.safeParse(invalidFrontmatter);
-      expect(result.success).toBe(false);
+      const result = RooCommandFrontmatterSchema.safeParse(frontmatter);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.description).toBeUndefined();
+        expect(result.data["argument-hint"]).toBe("Has hint but no description");
+      }
     });
 
     it("should reject frontmatter with invalid description type", () => {

src/features/commands/roo-command.ts

@@ -16,7 +16,7 @@ import {
 
 // looseObject preserves unknown keys during parsing (like passthrough in Zod 3)
 export const RooCommandFrontmatterSchema = z.looseObject({
-  description: z.string(),
+  description: z.optional(z.string()),
   "argument-hint": optional(z.string()),
 });