fix(components): add frontmatter to 58 components, dedupe nested agent path, and document frontmatter in CONTRIBUTING

VJ
4h ago
+203-35

Follow-up to #888, closes #889.

What this does

1. Frontmatter added to all 58 components that shipped without one (item 1)

  • 5 agents: vital-health-content-agent, sdd-spec-writer, commit-guardian, supply-chain-security (plus the moved vital-health-content-agent below). Each gets name, description, and where the component's behavior calls for it, tools and model: sonnet.
  • 53 commands: each gets a description written from the command's own content, plus a quoted argument-hint for the 19 commands that take arguments (`` users and the orchestration commands with documented TASK-ID usage).
  • Descriptions summarize what each component actually does based on its body, per the issue's note that these need to be written by someone who knows the component.

2. Duplicated nested path cleaned up (item 2)

  • vital-health-content-agent.md moved from agents/business-marketing/cli-tool/components/agents/business-marketing/... to agents/business-marketing/vital-health-content-agent.md, the duplicate copy and the nested cli-tool/ directories deleted.
  • The agent was absent from components.json entirely; the regenerated catalog now lists it at business-marketing/vital-health-content-agent.md.

3. CONTRIBUTING.md documents the frontmatter format (item 3)

  • The "Adding Agents" and "Adding Commands" file templates now start with a YAML frontmatter block (name + description for agents; description + quoted argument-hint for commands), matching the sub-agents and slash-commands docs.
  • Both sections mention npm run frontmatter:check as the local pre-flight.
  • The stale agent and command category lists were replaced with the actual directories under cli-tool/components/ (28 agent categories, 25 command categories).

Validation

  • All 57 changed component files parse with PyYAML; name/description/argument-hint are non-empty strings, model values are documented aliases.
  • scripts/generate_components_json.py runs clean and the regenerated dashboard data is included (matching the convention in #885).
  • Quoting follows the repo convention — argument-hint is quoted so YAML does not read [task-id] as a flow sequence.

One correction to the issue

The file flagged in item 2 as a similar stray path — skills/business-marketing/app-builder/templates/cli-tool/TEMPLATE.md — is not stray: it has valid frontmatter and follows the exact templates/<type>/TEMPLATE.md convention of its 13 sibling directories (astro-static, nextjs-fullstack, …), so it is left unchanged.

Regenerated catalog data

Includes the regenerated dashboard/public JSONs and docs/components.json so the catalog is consistent with the component changes in this same PR.

Summary by cubic

Adds validated YAML frontmatter to 58 components in cli-tool/components/ so they load correctly in Claude Code, moves the duplicated vital-health-content-agent nested path to its proper location, and documents the required format in CONTRIBUTING.md (docs/).

  • Agents now require name, description, tools, and model; commands require description and allowed-tools, with a quoted argument-hint where arguments exist. Review feedback trimmed verbose descriptions, tightened tool grants, and removed a redundant Bash(git:*) grant from supply-chain-audit.
  • CONTRIBUTING.md agent/command templates include frontmatter blocks, and stale category lists were replaced with the actual directories under cli-tool/components/.
  • No new components were added; docs/components.json was restored from base, so no catalog regeneration is needed.
  • No new environment variables or secrets are required.