From fda32b6e66cd7c1db9ed5adbbc55055db0725faa Mon Sep 17 00:00:00 2001
From: tt-a1i <53142663+tt-a1i@users.noreply.github.com>
Date: Fri, 19 Jun 2026 03:36:59 +0800
Subject: [PATCH] fix(core): serialize migrated command descriptions as YAML
 (#5321)

---
 .../services/command-migration-tool.test.ts   | 31 +++++++++++++++++++
 .../utils/toml-to-markdown-converter.test.ts  | 22 ++++++++++++-
 .../src/utils/toml-to-markdown-converter.ts   |  8 ++++-
 3 files changed, 59 insertions(+), 2 deletions(-)

diff --git a/packages/cli/src/services/command-migration-tool.test.ts b/packages/cli/src/services/command-migration-tool.test.ts
index 618a38f946..8b327682ca 100644
--- a/packages/cli/src/services/command-migration-tool.test.ts
+++ b/packages/cli/src/services/command-migration-tool.test.ts
@@ -13,6 +13,10 @@ import {
   migrateTomlCommands,
   generateMigrationPrompt,
 } from './command-migration-tool.js';
+import {
+  parseMarkdownCommand,
+  MarkdownCommandDefSchema,
+} from './markdown-command-parser.js';
 
 describe('command-migration-tool', () => {
   let tempDir: string;
@@ -153,6 +157,33 @@ description = "Test description"`;
       expect(backupExists).toBe(false);
     });
 
+    it('should preserve YAML-like descriptions as strings', async () => {
+      const tomlContent = `prompt = "Test prompt"
+description = "false"`;
+
+      await fs.writeFile(path.join(tempDir, 'test.toml'), tomlContent, 'utf-8');
+
+      const result = await migrateTomlCommands({
+        commandDir: tempDir,
+        createBackup: false,
+      });
+
+      expect(result.success).toBe(true);
+
+      const mdContent = await fs.readFile(
+        path.join(tempDir, 'test.md'),
+        'utf-8',
+      );
+      const parsed = parseMarkdownCommand(mdContent);
+      const validationResult = MarkdownCommandDefSchema.safeParse(parsed);
+
+      expect(validationResult.success).toBe(true);
+      if (!validationResult.success) {
+        throw new Error('expected migrated command to be valid markdown');
+      }
+      expect(validationResult.data.frontmatter?.description).toBe('false');
+    });
+
     it('should fail if Markdown file already exists', async () => {
       await fs.writeFile(
         path.join(tempDir, 'existing.toml'),
diff --git a/packages/core/src/utils/toml-to-markdown-converter.test.ts b/packages/core/src/utils/toml-to-markdown-converter.test.ts
index 8adc811f92..2b84d0d79e 100644
--- a/packages/core/src/utils/toml-to-markdown-converter.test.ts
+++ b/packages/core/src/utils/toml-to-markdown-converter.test.ts
@@ -9,6 +9,13 @@ import {
   convertTomlToMarkdown,
   isTomlFormat,
 } from './toml-to-markdown-converter.js';
+import { parse as parseYaml } from './yaml-parser.js';
+
+function readDescriptionFromFrontmatter(markdown: string): unknown {
+  const match = markdown.match(/^---\n([\s\S]*?)\n---\n/);
+  expect(match).not.toBeNull();
+  return parseYaml(match![1])['description'];
+}
 
 describe('convertTomlToMarkdown', () => {
   it('should convert TOML with description to Markdown', () => {
@@ -69,7 +76,20 @@ description = "Command with: special, characters!"`;
 
     const result = convertTomlToMarkdown(tomlContent);
 
-    expect(result).toContain('description: Command with: special, characters!');
+    expect(readDescriptionFromFrontmatter(result)).toBe(
+      'Command with: special, characters!',
+    );
+  });
+
+  it('should preserve YAML-like description strings as strings', () => {
+    for (const description of ['false', '123', 'null', 'line one\nline two']) {
+      const tomlContent = `prompt = "Test prompt"
+description = ${JSON.stringify(description)}`;
+
+      const result = convertTomlToMarkdown(tomlContent);
+
+      expect(readDescriptionFromFrontmatter(result)).toBe(description);
+    }
   });
 });
 
diff --git a/packages/core/src/utils/toml-to-markdown-converter.ts b/packages/core/src/utils/toml-to-markdown-converter.ts
index 92f7778c06..8dc8222b8c 100644
--- a/packages/core/src/utils/toml-to-markdown-converter.ts
+++ b/packages/core/src/utils/toml-to-markdown-converter.ts
@@ -9,6 +9,7 @@
  */
 
 import toml from '@iarna/toml';
+import { stringify as stringifyYaml } from './yaml-parser.js';
 
 export interface TomlCommandFormat {
   prompt: string;
@@ -47,8 +48,13 @@ export function convertTomlToMarkdown(tomlContent: string): string {
 
   // Generate Markdown
   if (description) {
+    const frontmatter = stringifyYaml(
+      { description },
+      { lineWidth: 0 },
+    ).trimEnd();
+
     return `---
-description: ${description}
+${frontmatter}
 ---
 
 ${prompt}