fix: resolve 'too many arguments' CLI error

.ai-team/agents/fenster/history.md

@@ -121,3 +121,5 @@ _Summarized from initial architecture review (2026-02-07). Full entries in `hist
 - **MCP integration shipped (#11).** Added MCP Integration section to squad.agent.md (after Client Compatibility, before Eager Execution): detection via tool prefix scanning, routing rules (coordinator direct vs spawn with context), graceful degradation (CLI fallback → inform user → continue without), config file locations, Trello sample config. References the existing MCP skill at `.ai-team/skills/mcp-tool-discovery/SKILL.md` instead of duplicating it. Updated spawn template with optional MCP TOOLS AVAILABLE block. Added MCP config generation to `squad init` (creates `.copilot/mcp-config.json` sample with `EXAMPLE-trello` prefix pattern). Added 0.4.0 upgrade migration so existing installs get the sample config on `squad upgrade`. Both init and migration are idempotent (skip if file exists).
 
 - **Docs template extraction — inline→external files.** Refactored `docs/build.js` to read HTML template, CSS, and JS from external files instead of generating them inline via `getCSS()`, `getJS()`, and `getTemplate()` string-building functions. Created `docs/assets/template.html` (HTML shell with `{{title}}`, `{{nav}}`, `{{content}}`, `{{searchIndex}}`, `{{basePath}}` placeholders), `docs/assets/style.css`, and `docs/assets/script.js`. Build reads template once at startup, does placeholder replacement per page. CSS/JS are linked externally (`<link>` / `<script src>`), search index remains inlined as page-specific `<script>` block. The existing `copyDir` of `docs/assets/` → `_site/assets/` handles deploying CSS/JS automatically. Key paths: `docs/assets/template.html`, `docs/assets/style.css`, `docs/assets/script.js`.
+
+- **Copilot CLI agent manifest YAML frontmatter validation (issue #59).** The `version` field in squad.agent.md's YAML frontmatter was not a supported property per the [GitHub Copilot CLI agent manifest specification](https://docs.github.com/en/copilot/reference/custom-agents-configuration). Supported properties are: `name`, `description`, `tools`, and `mcp-servers` (org/enterprise only). Unsupported properties like `version`, `model`, `argument-hint`, and `handoffs` cause the Copilot CLI parser to throw "error: too many arguments" because it interprets them as command-line arguments. Fixed by moving version tracking from YAML frontmatter to an HTML comment (`<!-- version: X.Y.Z -->`) immediately after the frontmatter closing `---`. Updated `stampVersion()` and `readInstalledVersion()` in index.js to work with the new HTML comment format (with backward compatibility fallback for upgrade scenarios). The agent name was also simplified from `Squad (v0.0.0-source)` to just `Squad` in the frontmatter. This pattern applies to all custom agent manifests — only use officially supported YAML properties to avoid parser errors.

.ai-team/decisions/inbox/fenster-yaml-frontmatter-validation.md

@@ -0,0 +1,11 @@
+### 2026-02-14: Copilot CLI agent manifest YAML frontmatter must use only supported properties
+
+**By:** Fenster
+
+**What:** The `version` field was removed from squad.agent.md's YAML frontmatter because it is not a supported property per the GitHub Copilot CLI agent manifest specification. Version tracking was moved to an HTML comment format.
+
+**Why:** Unsupported YAML frontmatter properties (like `version`, `model`, `argument-hint`, `handoffs`) cause the Copilot CLI parser to display "error: too many arguments" above the textbox in the CLI. The parser interprets unsupported properties as command-line arguments, resulting in a persistent error message that degrades UX. The only supported properties for GitHub Copilot CLI agents are: `name`, `description`, `tools`, and `mcp-servers` (org/enterprise level only). Moving version to an HTML comment preserves version tracking without conflicting with the parser.
+
+**Reference:** https://docs.github.com/en/copilot/reference/custom-agents-configuration
+
+**Impact:** All custom agent manifests should validate their YAML frontmatter against the official specification. Version or other metadata that isn't supported should be tracked in HTML comments or the Markdown body, not in YAML.

.github/agents/squad.agent.md

@@ -1,15 +1,16 @@
 ---
-name: Squad (v0.0.0-source)
+name: Squad
 description: "Your AI team. Describe what you're building, get a team of specialists that live in your repo."
-version: "0.0.0-source"
 ---
 
+<!-- version: 0.0.0-source -->
+
 You are **Squad (Coordinator)** — the orchestrator for this project's AI team.
 
 ### Coordinator Identity
 
 - **Name:** Squad (Coordinator)
-- **Version:** Read the `version` field from the YAML frontmatter at the top of this file. Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting).
+- **Version:** 0.0.0-source (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting).
 - **Role:** Agent orchestration, handoff enforcement, reviewer gating
 - **Inputs:** User request, repository state, `.ai-team/decisions.md`
 - **Outputs owned:** Final assembled artifacts, orchestration log (via Scribe)

index.js

@@ -590,21 +590,24 @@ const isUpgrade = cmd === 'upgrade';
 // Stamp version into squad.agent.md after copying
 function stampVersion(filePath) {
   let content = fs.readFileSync(filePath, 'utf8');
-  // Replace version field
-  content = content.replace(/^version:\s*"[^"]*"/m, `version: "${pkg.version}"`);
-  // Replace version in name field to show in agent picker UI
-  // Handles both "Squad" and "Squad (vX.Y.Z)" formats
-  content = content.replace(/^name:\s*Squad(?:\s*\([^)]*\))?$/m, `name: Squad (v${pkg.version})`);
+  // Replace version in HTML comment (must come immediately after frontmatter closing ---)
+  content = content.replace(/<!-- version: [^>]+ -->/m, `<!-- version: ${pkg.version} -->`);
+  // Replace version in the Identity section's Version line
+  content = content.replace(/- \*\*Version:\*\* [0-9.]+(?:-[a-z]+)?/m, `- **Version:** ${pkg.version}`);
   fs.writeFileSync(filePath, content);
 }
 
-// Read version from squad.agent.md frontmatter
+// Read version from squad.agent.md HTML comment
 function readInstalledVersion(filePath) {
   try {
     if (!fs.existsSync(filePath)) return null;
     const content = fs.readFileSync(filePath, 'utf8');
-    const match = content.match(/^version:\s*"([^"]+)"/m);
-    return match ? match[1] : '0.0.0';
+    // Try to read from HTML comment first (new format)
+    const commentMatch = content.match(/<!-- version: ([0-9.]+(?:-[a-z]+)?) -->/);
+    if (commentMatch) return commentMatch[1];
+    // Fallback: try old frontmatter format for backward compatibility during upgrade
+    const frontmatterMatch = content.match(/^version:\s*"([^"]+)"/m);
+    return frontmatterMatch ? frontmatterMatch[1] : '0.0.0';
   } catch {
     return '0.0.0';
   }