fix: standardize subagent types and add agent frontmatter#805
Closed
Tibsfox wants to merge 5 commits intogsd-build:mainfrom
Closed
fix: standardize subagent types and add agent frontmatter#805Tibsfox wants to merge 5 commits intogsd-build:mainfrom
Tibsfox wants to merge 5 commits intogsd-build:mainfrom
Conversation
Add 'never use heredoc' instruction to 6 agents that were missing it: gsd-codebase-mapper, gsd-debugger, gsd-phase-researcher, gsd-project-researcher, gsd-research-synthesizer, gsd-roadmapper. All 9 file-writing agents now consistently prevent settings.local.json corruption from heredoc permission entries (GSD gsd-build#526). Read-only agents (plan-checker, integration-checker) excluded as they cannot write files. Co-Authored-By: Claude Opus 4.6 <[email protected]>
Add skills: field to all 11 agent frontmatter files with forward-compatible GSD workflow skill references (silently ignored until skill files are created). Add commented hooks: examples to 9 file-writing agents showing PostToolUse hook syntax for project-specific linting/formatting. Read-only agents (plan-checker, integration-checker) skip hooks as they cannot modify files. Per Claude Code docs: subagents don't inherit skills or hooks from the parent conversation — they must be explicitly listed in frontmatter. Co-Authored-By: Claude Opus 4.6 <[email protected]>
Replace general-purpose workaround pattern with named subagent types: - plan-phase: researcher and planner now spawn as gsd-phase-researcher/gsd-planner - new-project: 4 researcher spawns now use gsd-project-researcher - research-phase: researcher spawns now use gsd-phase-researcher - quick: planner revision now uses gsd-planner - diagnose-issues: debug agents now use gsd-debugger (matches template spec) Removes 'First, read agent .md file' prompt prefix — named agent types auto-load their .md file as system prompt, making the workaround redundant. Preserves intentional general-purpose orchestrator spawns in discuss-phase and plan-phase (auto-advance) where the agent runs an entire workflow. Co-Authored-By: Claude Opus 4.6 <[email protected]>
Document analysis of Claude Code mcpServers frontmatter behavior based on official documentation. Key finding: frontmatter mcpServers creates independent connections but cannot solve GSD's problem because agent definitions are generic templates, not project-specific. Strategy decision: proceed with MCP migration helper (PR-6) as the practical solution. General-purpose fallback (PR-5) deprioritized. Co-Authored-By: Claude Opus 4.6 <[email protected]>
New test suite covering: - HDOC: anti-heredoc instruction present in all 9 file-writing agents - SKILL: skills: frontmatter present in all 11 agents - HOOK: commented hooks pattern in file-writing agents - SPAWN: no stale workaround patterns, valid agent type references - AGENT: required frontmatter fields (name, description, tools, color) 509 total tests (462 existing + 47 new), 0 failures. Co-Authored-By: Claude Opus 4.6 <[email protected]>
Contributor
Author
|
PR #812 evolved to cover this scope more thoroughly (anti-heredoc for all agents + skills/hooks frontmatter). Consolidating to make review easier. Thanks for bearing with the iteration! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
subagent_type="general-purpose"+ "First, read agent .md" prompt prefix with proper named subagent types (gsd-phase-researcher,gsd-planner,gsd-project-researcher,gsd-debugger) across all workflows — named types auto-load their .md as system prompt, making the workaround redundantskills:field and commentedhooks:examples (PostToolUse for project-specific linting)settings.local.jsoncorruption from heredoc permission entries (Verifier/executor agents pollute settings.local.json with heredoc permissions #526) in 6 agents that were missing itmcpServers:frontmatter behavior — works for project-specific agents but not GSD's globally-installed templates. Strategy: users should migrate MCP to global scopeContext
The original fix (#161,
314916b) switched MCP-dependent subagents togeneral-purposeas a workaround for Claude Code bug #13898 (custom subagents can't access project-scoped MCP tools). This PR supersedes that workaround — named agent types provide better role isolation, model control, and frontmatter features. Users needing MCP in subagents should migrate to global MCP scope.Test plan
node --test tests/agent-frontmatter.test.cjs— 47 tests, 0 failures"First, read ~/.claude/agents/gsd-"patterns remain in workflows/commandssubagent_type=references use valid agent names orgeneral-purposediagnose-issues.mdspawnsgsd-debugger(notgeneral-purpose)skills:in frontmatter🤖 Generated with Claude Code