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

[Tibsfox]

Summary

• Add skills: frontmatter to all 11 agents for declarative skill loading (BUG-2)
• Add commented hooks: examples to 9 file-writing agents showing PostToolUse syntax (BUG-1)
• Extend anti-heredoc instruction to all 9 file-writing agents to prevent settings.local.json pollution (BUG-6 / Verifier/executor agents pollute settings.local.json with heredoc permissions gsd-build/get-shit-done#526)
• Standardize subagent_type across all workflow spawn calls, replacing stale general-purpose workarounds with proper named agent types
• Add 47 agent frontmatter and spawn consistency tests

Root Cause

Three bugs identified in the GSD Subagent Capability Inheritance analysis:

1. BUG-1 — Hooks don't fire in custom subagents. Claude Code subagents do not inherit hooks from the parent process. Hooks must be declared explicitly in each agent's YAML frontmatter.
2. BUG-2 — Skills loading is best-effort via prompt. Without a skills: field in agent frontmatter, skill activation in subagents is unreliable. Declarative frontmatter makes it explicit.
3. BUG-6 — Heredoc file writes pollute settings.local.json (Verifier/executor agents pollute settings.local.json with heredoc permissions gsd-build/get-shit-done#526). When agents use Bash(cat << 'EOF' > file) instead of the Write tool, Claude Code's settings can be corrupted. An explicit anti-heredoc instruction prevents this.

Additionally, workflow files used a "First, read ~/.claude/agents/gsd-*.md" workaround with subagent_type="general-purpose" because named agent types were not originally supported. This workaround is now stale — Claude Code supports named subagent_type values that map directly to agent definition files.

Fix

Agent frontmatter additions (11 agents)

Every agents/gsd-*.md file now includes a skills: field referencing a gsd-*-workflow skill name. File-writing agents (those with Write in their tools: list) additionally receive:

• A commented # hooks: block demonstrating PostToolUse hook syntax for Write|Edit matchers
• An explicit anti-heredoc instruction: "ALWAYS use the Write tool to create files — never use Bash(cat << 'EOF') or heredoc commands for file creation."

Agent	skills:	# hooks:	Anti-heredoc
gsd-codebase-mapper	gsd-mapper-workflow	Yes	Yes
gsd-debugger	gsd-debugger-workflow	Yes	Yes
gsd-executor	gsd-executor-workflow	Yes	Yes
gsd-phase-researcher	gsd-researcher-workflow	Yes	Yes
gsd-planner	gsd-planner-workflow	Yes	Yes
gsd-project-researcher	gsd-researcher-workflow	Yes	Yes
gsd-research-synthesizer	gsd-synthesizer-workflow	Yes	Yes
gsd-roadmapper	gsd-roadmapper-workflow	Yes	Yes
gsd-verifier	gsd-verifier-workflow	Yes	Yes
gsd-integration-checker	gsd-integration-workflow	--	--
gsd-plan-checker	gsd-plan-checker-workflow	--	--

Read-only agents (integration-checker, plan-checker) receive skills: only — they have no Write tool, so hooks and anti-heredoc are not applicable.

Workflow spawn standardization (5 files)

All Task() spawn calls updated to use named subagent_type values and remove the "First, read agent .md" prompt prefix:

File	Old subagent_type	New subagent_type
commands/gsd/research-phase.md	"general-purpose"	"gsd-phase-researcher"
get-shit-done/workflows/plan-phase.md	"general-purpose"	"gsd-phase-researcher" / "gsd-planner"
get-shit-done/workflows/new-project.md	"general-purpose"	"gsd-project-researcher"
get-shit-done/workflows/quick.md	"general-purpose"	"gsd-planner"
get-shit-done/workflows/diagnose-issues.md	"general-purpose"	"gsd-debugger"

Relationship to Other PRs

This is PR #5 of 6 from the dev-bugfix branch:

PR	Title	Status	Interaction
#2	Milestone completion bugs	Independent	No file overlap
#3	Cross-platform Windows CI fixes	Independent	No file overlap
#4	Feature enhancements (Codex, discuss, agents)	Merge first	Touches some agent files — PR #4 adds TDD/paralysis-guard content to agents, PR #5 adds frontmatter fields. Recommend merging #4 before #5 to avoid conflicts.
#5	Agent frontmatter + heredoc fix (this PR)	--	--
#6	CLI/config bug fixes	Independent	No file overlap
#1	MCP migration helper (targets dev-bugfix)	Merge after	PR #1 adds <mcp_check> blocks to agent body sections; PR #5 adds frontmatter and anti-heredoc to header sections. Both modify agent files but different regions. Recommend merging #5 before #1.

Recommended merge order: #2, #3, #4, #5, #6, #1

Testing

New tests: tests/agent-frontmatter.test.cjs (47 tests across 5 describe blocks)

#	Group	Test	Status
1	HDOC	gsd-codebase-mapper has anti-heredoc instruction	PASS
2	HDOC	gsd-debugger has anti-heredoc instruction	PASS
3	HDOC	gsd-executor has anti-heredoc instruction	PASS
4	HDOC	gsd-phase-researcher has anti-heredoc instruction	PASS
5	HDOC	gsd-planner has anti-heredoc instruction	PASS
6	HDOC	gsd-project-researcher has anti-heredoc instruction	PASS
7	HDOC	gsd-research-synthesizer has anti-heredoc instruction	PASS
8	HDOC	gsd-roadmapper has anti-heredoc instruction	PASS
9	HDOC	gsd-verifier has anti-heredoc instruction	PASS
10	HDOC	no active heredoc patterns in any agent file	PASS
11	SKILL	gsd-codebase-mapper has skills: in frontmatter	PASS
12	SKILL	gsd-debugger has skills: in frontmatter	PASS
13	SKILL	gsd-executor has skills: in frontmatter	PASS
14	SKILL	gsd-integration-checker has skills: in frontmatter	PASS
15	SKILL	gsd-phase-researcher has skills: in frontmatter	PASS
16	SKILL	gsd-plan-checker has skills: in frontmatter	PASS
17	SKILL	gsd-planner has skills: in frontmatter	PASS
18	SKILL	gsd-project-researcher has skills: in frontmatter	PASS
19	SKILL	gsd-research-synthesizer has skills: in frontmatter	PASS
20	SKILL	gsd-roadmapper has skills: in frontmatter	PASS
21	SKILL	gsd-verifier has skills: in frontmatter	PASS
22	SKILL	skill references follow naming convention	PASS
23	HOOK	gsd-codebase-mapper has commented hooks pattern	PASS
24	HOOK	gsd-debugger has commented hooks pattern	PASS
25	HOOK	gsd-executor has commented hooks pattern	PASS
26	HOOK	gsd-phase-researcher has commented hooks pattern	PASS
27	HOOK	gsd-planner has commented hooks pattern	PASS
28	HOOK	gsd-project-researcher has commented hooks pattern	PASS
29	HOOK	gsd-research-synthesizer has commented hooks pattern	PASS
30	HOOK	gsd-roadmapper has commented hooks pattern	PASS
31	HOOK	gsd-verifier has commented hooks pattern	PASS
32	HOOK	gsd-integration-checker (read-only) does not need hooks	PASS
33	HOOK	gsd-plan-checker (read-only) does not need hooks	PASS
34	SPAWN	no "First, read agent .md" workaround pattern remains	PASS
35	SPAWN	named agent spawns use correct agent names	PASS
36	SPAWN	diagnose-issues uses gsd-debugger (not general-purpose)	PASS
37	AGENT	gsd-codebase-mapper has name, description, tools, color	PASS
38	AGENT	gsd-debugger has name, description, tools, color	PASS
39	AGENT	gsd-executor has name, description, tools, color	PASS
40	AGENT	gsd-integration-checker has name, description, tools, color	PASS
41	AGENT	gsd-phase-researcher has name, description, tools, color	PASS
42	AGENT	gsd-plan-checker has name, description, tools, color	PASS
43	AGENT	gsd-planner has name, description, tools, color	PASS
44	AGENT	gsd-project-researcher has name, description, tools, color	PASS
45	AGENT	gsd-research-synthesizer has name, description, tools, color	PASS
46	AGENT	gsd-roadmapper has name, description, tools, color	PASS
47	AGENT	gsd-verifier has name, description, tools, color	PASS

Full suite results

# tests 466
# suites 84
# pass 466
# fail 0
# cancelled 0
# skipped 0
# duration_ms 5044

All 466 tests pass (84 suites), including all 47 new tests. Zero regressions.

Impact

• All changes are additive. No existing agent behavior is modified — frontmatter fields are new additions, and the anti-heredoc instruction replaces weaker phrasing (e.g., "Use the Write tool") with an explicit prohibition.
• Workflow spawn calls are functionally equivalent. Named subagent_type values cause Claude Code to load the agent definition file directly, which previously happened via prompt instruction. The agent receives the same role and instructions either way — the named type is cleaner and more reliable.
• 17 files changed: 11 agent definitions, 5 workflow/command files, 1 new test file. Net +289 / -32 lines.

Future Considerations

• Claude Code #13898 (project MCP in subagents) remains open upstream. If fixed, the general-purpose workaround removal becomes even more justified, since named agent types will also inherit MCP server access.
• skills: frontmatter is forward-compatible. Referenced skills (e.g., gsd-executor-workflow) do not need to exist at install time — they are resolved at spawn. Users can create matching skill files later.
• hooks: are commented examples only. Users must uncomment and customize the PostToolUse hook patterns for their project. The examples show the correct YAML structure and a common eslint auto-fix pattern.
• Agent file convergence. PRs fix: add MCP migration helper and subagent connectivity pre-check #1, feat: add Codex parity, discuss-phase scouting, and agent quality guards #4, and fix(agents): add skills/hooks frontmatter, anti-heredoc rules, and spawn type standardization #5 all modify agent files. The recommended merge order (feat: add Codex parity, discuss-phase scouting, and agent quality guards #4, fix(agents): add skills/hooks frontmatter, anti-heredoc rules, and spawn type standardization #5, fix: add MCP migration helper and subagent connectivity pre-check #1) minimizes conflict surface since each PR modifies different sections of the frontmatter/body.

[Tibsfox]

Code Logic Verification of PR #5

1. The Before State (Bug Paths)

BUG-1 — Hooks don't fire in subagents: Claude Code subagents do not inherit hooks from the parent process. Without hooks: in frontmatter, hook-based automation (like auto-linting on Write) can't work in agents. No agent had hooks declared.

BUG-2 — Skills loading unreliable in subagents: Without a skills: field in agent frontmatter, skill activation depends on prompt-matching heuristics. This is best-effort and unreliable for agents that need specific workflow skills.

BUG-6 — Heredoc file writes corrupt settings (gsd-build#526): When agents use Bash(cat << 'EOF' > file) instead of the Write tool, Claude Code's settings.local.json can be polluted. Only 3 of 9 file-writing agents had the anti-heredoc instruction.

Spawn workaround: 11 spawn calls across 5 files used subagent_type="general-purpose" with a "First, read ~/.claude/agents/gsd-*.md for your role and instructions.\n\n" prompt prefix. This is fragile — if the agent fails to read the file, it operates without instructions. It also means the agent gets default tools instead of the tools declared in its frontmatter.

2. The After State (Fix Paths)

Frontmatter additions (11 agents):

Every agents/gsd-*.md file now includes skills: in YAML frontmatter. All 9 file-writing agents also get commented # hooks: block and the full anti-heredoc instruction.

Agent	skills:	# hooks:	Anti-heredoc
gsd-codebase-mapper	gsd-mapper-workflow	Yes	Yes (strengthened from partial)
gsd-debugger	gsd-debugger-workflow	Yes	Yes (added)
gsd-executor	gsd-executor-workflow	Yes	Yes (existed, unchanged)
gsd-phase-researcher	gsd-researcher-workflow	Yes	Yes (strengthened)
gsd-planner	gsd-planner-workflow	Yes	Yes (existed, unchanged)
gsd-project-researcher	gsd-researcher-workflow	Yes	Yes (added)
gsd-research-synthesizer	gsd-synthesizer-workflow	Yes	Yes (added)
gsd-roadmapper	gsd-roadmapper-workflow	Yes	Yes (strengthened from partial)
gsd-verifier	gsd-verifier-workflow	Yes	Yes (existed, unchanged)
gsd-integration-checker	gsd-integration-workflow	—	— (read-only, correct)
gsd-plan-checker	gsd-plan-checker-workflow	—	— (read-only, correct)

Spawn standardization (5 files, 11 spawns fixed):

File	Spawns Fixed	New subagent_type
commands/gsd/research-phase.md	2	gsd-phase-researcher
get-shit-done/workflows/plan-phase.md	3	gsd-phase-researcher / gsd-planner
get-shit-done/workflows/quick.md	1	gsd-planner
get-shit-done/workflows/new-project.md	4	gsd-project-researcher
get-shit-done/workflows/diagnose-issues.md	1	gsd-debugger

Two general-purpose spawns intentionally remain in plan-phase.md:490 and discuss-phase.md:493 — these are orchestrator spawns that read entire workflow files as instructions, not agent definitions.

3. Key Correctness Checks

Check	Result
All 11 agents have skills: in YAML frontmatter	✅ Verified in diff — values follow gsd-*-workflow convention
All 9 file-writing agents have anti-heredoc + commented hooks	✅ 4 added, 2 strengthened, 3 existed
Anti-heredoc wording consistent across all 9	✅ Identical text (phase-researcher adds commit_docs context)
Read-only agents correctly excluded from hooks/anti-heredoc	✅ integration-checker and plan-checker get skills: only
All 11 general-purpose agent spawns converted to named types	✅ Zero "First, read" patterns remain on PR branch
Prompt prefix removed when named type used	✅ Auto-load replaces manual read — no context waste
Remaining general-purpose refs are orchestrator spawns	✅ 2 remain, both read workflow files (not agent defs)
47 tests validate all claims against real files	✅ Reads actual agent files, not mocks
No regressions — all changes additive	✅ No behavior removed, merges cleanly

4. Verdict

PASS — All four commits deliver exactly what the PR describes:

1. Anti-heredoc extended to all 9 file-writing agents with consistent wording
2. skills: frontmatter and commented hooks: examples added to all 11 agents
3. 11 general-purpose spawn calls converted to named agent types across 5 files
4. 47 tests validate all changes against real agent files

No regressions. Merges cleanly to main (no conflicts).

• Tibsfox ^.^