fix: reconcile merge-help-csv HEADER with canonical 13-column schema

merge-help-csv.py defined a 15-column HEADER (agent-name, skill-name,
capability, trailing empty) that diverged from the 13-column schema used
by validate-module.py, all module-help.csv files, and create-module.md.
This would silently corrupt or misalign CSV data during module setup.

Author: bmadcode

docs/explanation/module-configuration.md

@@ -88,8 +88,8 @@ If these cover your discoverability needs, you can skip the setup skill entirely
 The CSV asset registers the module's capabilities with the help system. Each row describes one capability that users can discover and invoke.
 
 ```csv
-module,agent-name,skill-name,display-name,menu-code,capability,args,description,...
-mymod,,my-skill,My Skill,MS,build-process,,"Does something useful.",...
+module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
+mymod,my-skill,My Skill,MS,"Does something useful.",build-process,,anytime,,,false,,
 ```
 
 When the setup skill runs, it merges these rows into the project-wide `_bmad/module-help.csv`, replacing any existing rows for this module. This is how users find your module's commands through the help system.

skills/bmad-builder-setup/scripts/merge-help-csv.py

@@ -26,20 +26,18 @@
 # CSV header for module-help.csv
 HEADER = [
     "module",
-    "agent-name",
-    "skill-name",
+    "skill",
     "display-name",
     "menu-code",
-    "capability",
-    "args",
     "description",
+    "action",
+    "args",
     "phase",
     "after",
     "before",
     "required",
     "output-location",
     "outputs",
-    "",  # trailing empty column from trailing comma
 ]
 
 

skills/bmad-builder-setup/scripts/tests/test-merge-help-csv.py

@@ -32,8 +32,8 @@
 
 
 SAMPLE_ROWS = [
-    ["bmb", "", "bmad-bmb-module-init", "Install Module", "IM", "install", "", "Install BMad Builder.", "anytime", "", "", "false", "", "config", ""],
-    ["bmb", "", "bmad-agent-builder", "Build Agent", "BA", "build-process", "", "Create an agent.", "anytime", "", "", "false", "output_folder", "agent skill", ""],
+    ["bmb", "bmad-bmb-module-init", "Install Module", "IM", "Install BMad Builder.", "install", "", "anytime", "", "", "false", "", "config"],
+    ["bmb", "bmad-agent-builder", "Build Agent", "BA", "Create an agent.", "build-process", "", "anytime", "", "", "false", "output_folder", "agent skill"],
 ]
 
 
@@ -44,7 +44,7 @@ def test_extracts_codes(self):
 
     def test_multiple_codes(self):
         rows = SAMPLE_ROWS + [
-            ["cis", "", "cis-skill", "CIS Skill", "CS", "run", "", "A skill.", "anytime", "", "", "false", "", "", ""],
+            ["cis", "cis-skill", "CIS Skill", "CS", "A skill.", "run", "", "anytime", "", "", "false", "", ""],
         ]
         codes = extract_module_codes(rows)
         self.assertEqual(codes, {"bmb", "cis"})
@@ -61,7 +61,7 @@ def test_removes_matching_rows(self):
 
     def test_preserves_non_matching_rows(self):
         mixed_rows = SAMPLE_ROWS + [
-            ["cis", "", "cis-skill", "CIS Skill", "CS", "run", "", "A skill.", "anytime", "", "", "false", "", "", ""],
+            ["cis", "cis-skill", "CIS Skill", "CS", "A skill.", "run", "", "anytime", "", "", "false", "", ""],
         ]
         result = filter_rows(mixed_rows, "bmb")
         self.assertEqual(len(result), 1)
@@ -86,7 +86,7 @@ def test_round_trip(self):
             header, rows = read_csv_rows(path)
             self.assertEqual(len(rows), 2)
             self.assertEqual(rows[0][0], "bmb")
-            self.assertEqual(rows[0][2], "bmad-bmb-module-init")
+            self.assertEqual(rows[0][1], "bmad-bmb-module-init")
 
     def test_creates_parent_dirs(self):
         with tempfile.TemporaryDirectory() as tmpdir:
@@ -125,7 +125,7 @@ def test_fresh_install_no_existing_target(self):
     def test_merge_into_existing_with_other_module(self):
         with tempfile.TemporaryDirectory() as tmpdir:
             other_rows = [
-                ["cis", "", "cis-skill", "CIS Skill", "CS", "run", "", "A skill.", "anytime", "", "", "false", "", "", ""],
+                ["cis", "cis-skill", "CIS Skill", "CS", "A skill.", "run", "", "anytime", "", "", "false", "", ""],
             ]
             target_path = self._write_target(tmpdir, other_rows)
             source_path = self._write_source(tmpdir, SAMPLE_ROWS)
@@ -150,11 +150,11 @@ def test_anti_zombie_replaces_stale_entries(self):
         with tempfile.TemporaryDirectory() as tmpdir:
             # Existing target has old bmb entries + cis entry
             old_bmb_rows = [
-                ["bmb", "", "old-skill", "Old Skill", "OS", "run", "", "Old.", "anytime", "", "", "false", "", "", ""],
-                ["bmb", "", "another-old", "Another", "AO", "run", "", "Old too.", "anytime", "", "", "false", "", "", ""],
+                ["bmb", "old-skill", "Old Skill", "OS", "Old.", "run", "", "anytime", "", "", "false", "", ""],
+                ["bmb", "another-old", "Another", "AO", "Old too.", "run", "", "anytime", "", "", "false", "", ""],
             ]
             cis_rows = [
-                ["cis", "", "cis-skill", "CIS Skill", "CS", "run", "", "A skill.", "anytime", "", "", "false", "", "", ""],
+                ["cis", "cis-skill", "CIS Skill", "CS", "A skill.", "run", "", "anytime", "", "", "false", "", ""],
             ]
             target_path = self._write_target(tmpdir, old_bmb_rows + cis_rows)
             source_path = self._write_source(tmpdir, SAMPLE_ROWS)
@@ -179,7 +179,7 @@ def test_anti_zombie_replaces_stale_entries(self):
             self.assertEqual(module_codes.count("bmb"), 2)
             self.assertEqual(module_codes.count("cis"), 1)
             # Old skills should be gone
-            skill_names = [r[2] for r in result_rows]
+            skill_names = [r[1] for r in result_rows]
             self.assertNotIn("old-skill", skill_names)
             self.assertNotIn("another-old", skill_names)
 

skills/bmad-module-builder/assets/setup-skill-template/scripts/merge-help-csv.py

@@ -26,20 +26,18 @@
 # CSV header for module-help.csv
 HEADER = [
     "module",
-    "agent-name",
-    "skill-name",
+    "skill",
     "display-name",
     "menu-code",
-    "capability",
-    "args",
     "description",
+    "action",
+    "args",
     "phase",
     "after",
     "before",
     "required",
     "output-location",
     "outputs",
-    "",  # trailing empty column from trailing comma
 ]