fix(agents): 1.6 — agent frontmatter alignment (name, model, color, description) (#56)

* fix(plugin-dev): validate-agent.sh — arithmetic, SIGPIPE, and shellcheck fixes

Bug 1 — arithmetic (((n++)) with set -e):
  Replace all 18 ((n++)) with n=$((n+1)) to prevent premature script exit.
  ((n++)) returns exit code 1 when n=0 (post-increment evaluates to 0 = false);
  set -e treats this as failure and aborts the script before counting is complete.
  Pattern already applied in validate-hook-schema.sh; now consistent.

Bug 2 — SIGPIPE in tail | grep -q:
  Replace `tail -n +2 | grep -q '^---$'` with `grep -c` check.
  grep -q exits immediately on first match while tail is still writing; with
  set -o pipefail, tail's SIGPIPE exit (141) propagates as pipeline failure.
  The `if !` inversion converts this to a false positive "Frontmatter not
  closed" for any agent where the closing --- appears before tail finishes.
  grep -c reads all input before exiting, eliminating the race condition.
  Affects locally: all plugin-dev agents (177-185 lines) and most other
  agents (≥108 lines on WSL). CI (Ubuntu) was unaffected due to different
  pipe buffer behaviour.

Shellcheck SC2086 — unquoted integer variables:
  Quote $name_length, $desc_length, $prompt_length in numeric comparisons.
  Pre-existing issues, fixed while script is open.

ux-reviewer.md — CRLF line endings:
  Discovered during investigation: ux-reviewer.md had Windows (CRLF) line
  endings causing Check 2 to fail ("File must start with YAML frontmatter")
  since head -1 returned '---\r' instead of '---'. Fixed with sed -i 's/\r//'.

plugin-validation.yml — update stale CI comment:
  Remove reference to the now-fixed arithmetic bug; keep || true as defensive
  programming (tolerates future script regressions).

Note: 4 non-plugin-dev agents (pm-assistant, productivity-assistant,
automation-validator, strategic-analyst) use a different frontmatter format
(no name/model/color fields) and exit silently on validation — pre-existing
behaviour unchanged. Tracked separately for a future frontmatter alignment fix.

Generated by Nuno Salvação

Co-Authored-By: Nexo <nexo.modeling@gmail.com>

* fix(agents): 1.6 — add missing frontmatter and fix descriptions in 4 agents

Four agents were missing `name:`, `model:`, `color:` fields required by
validate-agent.sh, causing the script to silently exit under `set -e` when
grep returned exit 1 on the missing `name:` field. Descriptions also used
multiline YAML `>` blocks which the validator's single-line grep could only
capture as `>` (1 character), triggering false description-too-short warnings
and masking the missing <example> blocks.

Changes per agent:
- pm-assistant (product-management): add name/model:sonnet/color:blue,
  convert description to inline with trigger phrases + 2 <example> blocks
- productivity-assistant (productivity): add name/model:sonnet/color:green,
  convert description to inline with trigger phrases + 2 <example> blocks
- automation-validator (repo-structure): add name/model:sonnet/color:yellow,
  convert description to inline with trigger phrases + 2 <example> blocks
- strategic-analyst (strategy-toolkit): add name/model:sonnet/color:cyan,
  convert description to inline with trigger phrases + 2 <example> blocks

Also fixes validate-agent.sh TOOLS grep: `grep '^tools:'` with `set -e`
caused silent exit for agents without a `tools:` field (optional field).
Added `|| true` guard — same safe pattern used for required-field greps.

All 4 agents now complete full validation with ✅ All checks passed or
⚠️ warnings-only (no ❌ errors). CI `grep -q '❌'` check unaffected.

Generated by Nuno Salvação

Co-Authored-By: Nexo <nexo.modeling@gmail.com>

---------

Co-authored-by: Nexo <nexo.modeling@gmail.com>

Author: nsalvacao

plugins/plugin-dev/skills/agent-development/scripts/validate-agent.sh

@@ -163,7 +163,7 @@ else
 fi
 
 # Check tools field (optional)
-TOOLS=$(echo "$FRONTMATTER" | grep '^tools:' | sed 's/tools: *//')
+TOOLS=$(echo "$FRONTMATTER" | grep '^tools:' | sed 's/tools: *//' || true)
 
 if [ -n "$TOOLS" ]; then
   echo "✅ tools: $TOOLS"

plugins/product-management/agents/pm-assistant.md

@@ -1,19 +1,15 @@
 ---
-description: >
-  Product management assistant for PM decision support and workflow routing.
-  Use when the user asks for "PM help", "what should I work on", "help me prioritize",
-  "draft a spec", "analyze competitors", "write a stakeholder update", "review the
-  roadmap", "synthesize this feedback", or any product management task that spans
-  multiple PM disciplines. Reads existing project context before responding — never
-  makes assumptions about the product, roadmap, or stakeholders without first
-  checking available documentation.
+name: pm-assistant
+description: Use this agent when the user asks for "PM help", "what should I work on", "help me prioritize", "draft a spec", "analyze competitors", "write a stakeholder update", "review the roadmap", "synthesize this feedback", or any product management task spanning multiple PM disciplines. Reads existing project context before responding. <example>user: "Help me prioritize these features for the next sprint" assistant: "I'll use the pm-assistant agent to apply PM prioritization frameworks."</example> <example>user: "Write a stakeholder update for this week's progress" assistant: "I'll use the pm-assistant agent to draft a structured update."</example>
 capabilities:
   - Routes between PM workflows: spec writing, roadmap, research synthesis, metrics, competitive analysis, stakeholder comms
   - Reads existing docs (README, roadmap files, specs) before producing PM outputs
   - Applies structured PM frameworks (RICE, MoSCoW, Jobs-to-be-Done, OKRs)
   - Helps prioritize feature requests against strategic goals
   - Surfaces metrics gaps and measurement blind spots
   - Produces stakeholder-appropriate communications (exec summary vs eng detail)
+model: sonnet
+color: blue
 ---
 
 # PM Assistant

plugins/productivity/agents/productivity-assistant.md

@@ -1,19 +1,15 @@
 ---
-description: >
-  Productivity assistant that routes between task management and memory management
-  based on conversational context. Use when the user asks about "my tasks", "what's
-  on my plate", "remind me to", "who is X", "what does Y mean", "help me stay on
-  track", "end of day review", "what did I work on today", or needs help maintaining
-  focus and clarity across a work session.
-  Reads TASKS.md and memory files before responding — never makes assumptions
-  about the user's current workload or terminology without checking.
+name: productivity-assistant
+description: Use this agent when the user asks about "my tasks", "what's on my plate", "remind me to", "who is X", "what does Y mean", "help me stay on track", "end of day review", or "what did I work on today". Routes between task management and memory management. Reads TASKS.md and memory files before responding. <example>user: "What tasks do I still have for today?" assistant: "I'll use the productivity-assistant agent to check your task list."</example> <example>user: "Who is the lead dev on the API project?" assistant: "I'll use the productivity-assistant agent to look up that context from memory."</example>
 capabilities:
   - Reads TASKS.md and surfaces active commitments and blockers
   - Understands workplace acronyms, nicknames, and terminology from memory
   - Extracts action items from meeting notes or conversation summaries
   - Tracks what was worked on during a session and updates accordingly
   - Flags overdue or stalled tasks proactively
   - Bridges task-management and memory-management skills seamlessly
+model: sonnet
+color: green
 ---
 
 # Productivity Assistant

plugins/repo-structure/agents/automation-validator.md

@@ -1,16 +1,14 @@
 ---
-description: >
-  Validates health of all automation files in a repository — GitHub Actions workflows,
-  pre-commit hooks, Claude Code hooks, Makefile/package.json scripts, and GitHub Actions
-  matrix coherence. Use when: "validate automation", "check my hooks", "automation health
-  check", /repo-validate --automation. Produces structured report with OK/WARN/FAIL per
-  category plus actionable fix list.
+name: automation-validator
+description: Use this agent when the user asks to "validate automation", "check my hooks", "automation health check", or runs /repo-validate --automation. Validates GitHub Actions workflows, pre-commit hooks, Claude Code hooks, Makefile/package.json scripts, and GitHub Actions matrix coherence. Produces structured report with OK/WARN/FAIL per category plus actionable fix list. <example>user: "Validate my GitHub Actions and hook setup" assistant: "I'll use the automation-validator agent for a comprehensive health check."</example> <example>user: "Check if my Claude Code hooks are correctly configured" assistant: "I'll use the automation-validator agent to audit the automation files."</example>
 capabilities:
   - Validate GitHub Actions workflow files (YAML syntax, events, runners, permissions)
   - Validate .pre-commit-config.yaml (hook existence, stale versions, executable)
   - Validate Claude Code hooks (scripts exist, executable, syntax OK)
   - Validate task runners (Makefile, package.json scripts, pyproject.toml taskipy)
   - Check GitHub Actions matrix coherence across workflow files
+model: sonnet
+color: yellow
 ---
 
 # Automation Validator Agent

plugins/strategy-toolkit/agents/strategic-analyst.md

@@ -1,18 +1,15 @@
 ---
-description: >
-  Strategic analyst agent for deep project analysis and strategic recommendations.
-  Use when the user asks to "analyze this project strategically", "help me think about
-  expansion", "do a strategic deep-dive", "evaluate my product positioning",
-  "prepare me for a launch decision", or needs a systematic strategic perspective
-  that goes beyond quick brainstorming. This agent reads the full project context
-  before producing analysis — never makes claims without reading available files.
+name: strategic-analyst
+description: Use this agent when the user asks to "analyze this project strategically", "help me think about expansion", "do a strategic deep-dive", "evaluate my product positioning", or "prepare me for a launch decision". Reads full project context before producing analysis — never makes claims without reading available files. <example>user: "Do a strategic deep-dive on my CLI tool project" assistant: "I'll use the strategic-analyst agent for a comprehensive strategic analysis."</example> <example>user: "Help me think about whether to pivot this project" assistant: "I'll use the strategic-analyst agent to evaluate the strategic options."</example>
 capabilities:
   - Reads and synthesizes full project context (README, docs, CLAUDE.md, code structure)
   - Applies 12 strategic frameworks from the toolkit reference
   - Produces asset-first analysis (identifies the real asset, not just the code)
   - Generates second-order thinking (what happens after success?)
   - Delivers honest assessments including failure modes and uncomfortable truths
   - Connects every insight to a concrete, actionable next step
+model: sonnet
+color: cyan
 ---
 
 # Strategic Analyst