fix: add command metadata frontmatter

commands/build-fix.md

@@ -1,3 +1,7 @@
+---
+description: Detect the project build system and incrementally fix build/type errors with minimal safe changes.
+---
+
 # Build and Fix
 
 Incrementally fix build and type errors with minimal, safe changes.

commands/checkpoint.md

@@ -1,3 +1,7 @@
+---
+description: Create, verify, or list workflow checkpoints after running verification checks.
+---
+
 # Checkpoint Command
 
 Create or verify a checkpoint in your workflow.

commands/gan-build.md

@@ -1,3 +1,7 @@
+---
+description: Run a generator/evaluator build loop for implementation tasks with bounded iterations and scoring.
+---
+
 Parse the following from $ARGUMENTS:
 1. `brief` — the user's one-line description of what to build
 2. `--max-iterations N` — (optional, default 15) maximum generator-evaluator cycles

commands/gan-design.md

@@ -1,3 +1,7 @@
+---
+description: Run a generator/evaluator design loop for frontend or visual work with bounded iterations and scoring.
+---
+
 Parse the following from $ARGUMENTS:
 1. `brief` — the user's description of the design to create
 2. `--max-iterations N` — (optional, default 10) maximum design-evaluate cycles

commands/harness-audit.md

@@ -1,3 +1,7 @@
+---
+description: Run a deterministic repository harness audit and return a prioritized scorecard.
+---
+
 # Harness Audit Command
 
 Run a deterministic repository harness audit and return a prioritized scorecard.

commands/learn.md

@@ -1,3 +1,7 @@
+---
+description: Extract reusable patterns from the current session and save them as candidate skills or guidance.
+---
+
 # /learn - Extract Reusable Patterns
 
 Analyze the current session and extract any patterns worth saving as skills.

commands/loop-start.md

@@ -1,3 +1,7 @@
+---
+description: Start a managed autonomous loop pattern with safety defaults and explicit stop conditions.
+---
+
 # Loop Start Command
 
 Start a managed autonomous loop pattern with safety defaults.

commands/loop-status.md

@@ -1,3 +1,7 @@
+---
+description: Inspect active loop state, progress, failure signals, and recommended intervention.
+---
+
 # Loop Status Command
 
 Inspect active loop state, progress, and failure signals.

commands/model-route.md

@@ -1,3 +1,7 @@
+---
+description: Recommend the best model tier for the current task based on complexity, risk, and budget.
+---
+
 # Model Route Command
 
 Recommend the best model tier for the current task by complexity and budget.

commands/multi-backend.md

@@ -1,3 +1,7 @@
+---
+description: Run a backend-focused multi-model workflow for APIs, algorithms, data, and business logic.
+---
+
 # Backend - Backend-Focused Development
 
 Backend-focused workflow (Research → Ideation → Plan → Execute → Optimize → Review), Codex-led.

commands/multi-execute.md

@@ -1,3 +1,7 @@
+---
+description: Execute a multi-model implementation plan while preserving Claude as the only filesystem writer.
+---
+
 # Execute - Multi-Model Collaborative Execution
 
 Multi-model collaborative execution - Get prototype from plan → Claude refactors and implements → Multi-model audit and delivery.

commands/multi-frontend.md

@@ -1,3 +1,7 @@
+---
+description: Run a frontend-focused multi-model workflow for components, layouts, animation, and UI polish.
+---
+
 # Frontend - Frontend-Focused Development
 
 Frontend-focused workflow (Research → Ideation → Plan → Execute → Optimize → Review), Gemini-led.

commands/multi-plan.md

@@ -1,3 +1,7 @@
+---
+description: Create a multi-model implementation plan without modifying production code.
+---
+
 # Plan - Multi-Model Collaborative Planning
 
 Multi-model collaborative planning - Context retrieval + Dual-model analysis → Generate step-by-step implementation plan.

commands/multi-workflow.md

@@ -1,3 +1,7 @@
+---
+description: Run a full multi-model development workflow with research, planning, execution, optimization, and review.
+---
+
 # Workflow - Multi-Model Collaborative Development
 
 Multi-model collaborative development workflow (Research → Ideation → Plan → Execute → Optimize → Review), with intelligent routing: Frontend → Gemini, Backend → Codex.

commands/pm2.md

@@ -1,3 +1,7 @@
+---
+description: Analyze a project and generate PM2 service commands for detected frontend, backend, or database services.
+---
+
 # PM2 Init
 
 Auto-analyze project and generate PM2 service commands.

commands/quality-gate.md

@@ -1,3 +1,7 @@
+---
+description: Run the ECC quality pipeline for a file or project scope and report remediation steps.
+---
+
 # Quality Gate Command
 
 Run the ECC quality pipeline on demand for a file or project scope.

commands/refactor-clean.md

@@ -1,3 +1,7 @@
+---
+description: Safely identify and remove dead code with verification after each change.
+---
+
 # Refactor Clean
 
 Safely identify and remove dead code with test verification at every step.

commands/test-coverage.md

@@ -1,3 +1,7 @@
+---
+description: Analyze coverage, identify gaps, and generate missing tests toward the target threshold.
+---
+
 # Test Coverage
 
 Analyze test coverage, identify gaps, and generate missing tests to reach 80%+ coverage.

commands/update-codemaps.md

@@ -1,3 +1,7 @@
+---
+description: Scan project structure and generate token-lean architecture codemaps.
+---
+
 # Update Codemaps
 
 Analyze the codebase structure and generate token-lean architecture documentation.

commands/update-docs.md

@@ -1,3 +1,7 @@
+---
+description: Sync documentation from source-of-truth files such as scripts, schemas, routes, and exports.
+---
+
 # Update Documentation
 
 Sync documentation with the codebase, generating from source-of-truth files.

tests/commands/command-frontmatter.test.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const repoRoot = path.resolve(__dirname, '..', '..');
+const commandsDir = path.join(repoRoot, 'commands');
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  PASS ${name}`);
+    passed++;
+  } catch (error) {
+    console.log(`  FAIL ${name}`);
+    console.log(`    Error: ${error.message}`);
+    failed++;
+  }
+}
+
+function getCommandFiles() {
+  return fs.readdirSync(commandsDir)
+    .filter(fileName => fileName.endsWith('.md'))
+    .sort();
+}
+
+function parseFrontmatter(content) {
+  if (!content.startsWith('---\n')) {
+    return null;
+  }
+
+  const endIndex = content.indexOf('\n---', 4);
+  if (endIndex === -1) {
+    return null;
+  }
+
+  return content.slice(4, endIndex);
+}
+
+console.log('\n=== Testing command frontmatter metadata ===\n');
+
+for (const fileName of getCommandFiles()) {
+  test(`${fileName} declares command metadata frontmatter`, () => {
+    const content = fs.readFileSync(path.join(commandsDir, fileName), 'utf8');
+    const frontmatter = parseFrontmatter(content);
+
+    assert.ok(frontmatter, 'Expected command file to start with YAML frontmatter');
+    assert.ok(
+      /^description:\s*\S/m.test(frontmatter),
+      'Expected command frontmatter to include a non-empty description'
+    );
+  });
+}
+
+if (failed > 0) {
+  console.log(`\nFailed: ${failed}`);
+  process.exit(1);
+}
+
+console.log(`\nPassed: ${passed}`);