fix(agents): add skills/hooks frontmatter, anti-heredoc rules, and spawn type standardization

[Tibsfox]

Summary

This PR adds preventive hardening to the GSD agent system — ensuring all agents have the right frontmatter declarations and workflow spawn calls use proper named types. While the specific bugs that motivated this (#526, #546, #548, #671) have been addressed upstream, the underlying patterns that allowed them to occur are still present across the agent definitions.

Think of this as the difference between fixing a leak and waterproofing the roof — the leaks are patched, but this PR makes sure the same class of issue doesn't recur elsewhere.

What This Adds

1. Skills frontmatter for all 11 agents (BUG-2 prevention)

Without a skills: field in agent frontmatter, skill activation in subagents is unreliable — it depends on the parent process happening to load the right context. Declaring skills explicitly makes agent behavior predictable and reproducible.

2. Anti-heredoc instructions for all 9 file-writing agents (BUG-6 / #526 prevention)

When agents use Bash(cat << 'EOF' > file) instead of the Write tool, Claude Code's settings.local.json can accumulate permission entries that grow unboundedly. The original fix in #526 addressed the verifier specifically — this extends the protection to every agent that has write access.

3. Commented hooks examples for file-writing agents (BUG-1 awareness)

Claude Code subagents don't inherit hooks from the parent process. While the commented examples don't enforce behavior today, they document the pattern for contributors and make it straightforward to enable per-agent hooks when Claude Code supports frontmatter hook declarations.

4. Workflow spawn type standardization (5 files)

Several workflow files used a "First, read ~/.claude/agents/gsd-*.md" workaround with subagent_type="general-purpose" — a pattern from before Claude Code supported named agent types. This updates all spawn calls to use the proper named types (e.g., gsd-phase-researcher, gsd-planner), which gives subagents the correct tool permissions and context automatically.

5. 47 agent frontmatter and spawn consistency tests

Automated tests that verify every agent definition has the required frontmatter fields and every workflow spawn call references a valid agent type. These catch regressions if new agents or workflows are added without proper declarations.

Why This Matters

The GSD agent system is growing — new agents, new workflows, new contributors. These changes establish a consistent baseline so that:

• Every agent knows what skills it needs (explicit, not inherited)
• File-writing agents have guardrails against known footguns
• Workflow orchestration uses the right agent types (not generic workarounds)
• Tests catch inconsistencies automatically

Relationship to Upstream Fixes

The specific bugs (#526, #546, #548, #671) were fixed upstream — great work by the maintainers! This PR extends those fixes into a systemic prevention pattern across all agents rather than addressing them one at a time.

Test Plan

• All 47 new tests pass (npm test)
• Agent frontmatter validates against expected schema
• Spawn type references resolve to real agent definitions
• No regressions in existing agent behavior

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.6 [email protected]