docs: reframe the subagent-dispatch rule as a justified default#100
Draft
taminomara wants to merge 3 commits into
Draft
docs: reframe the subagent-dispatch rule as a justified default#100taminomara wants to merge 3 commits into
taminomara wants to merge 3 commits into
Conversation
The agent-building guidance asserted, as a flat platform rule, that a subagent cannot dispatch another subagent. Git history shows this was an accurately-sourced platform constraint layered onto a pre-existing Han convention, then flattened by a repo-agnostic generalization edit that stripped the "not just a Han convention" qualifier. The platform's nesting behavior has since varied by version, so the flat rule is stale. Reframe the rule across six live files from a flat prohibition into a preferred default with a justification clause: dispatch flows from skills to agents, so an agent defaults to no `Agent` tool, and that default is broken only with a documented, concrete need. The platform's current nesting behavior is left unstated rather than asserted in either direction. The Han convention (agents withhold the `Agent` tool; skills dispatch) is kept; only its rationale changes, and the agent-builder conformance check shifts from unconditional removal to a justify-gate. Refs testdouble#99 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
taminomara
force-pushed
the
fix/stale-subagent-dispatch-rule
branch
from
54b596d to
55fb66c
Compare
The reframed tool-set question in the agent-builder design tree carried a mid-sentence em-dash forward from the original line. Swap it for a comma to follow docs/writing-voice.md, leaving the list-structural em-dashes that match the sibling design-tree items untouched. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Per review feedback, an agent does not record a separate rationale for carrying the `Agent` tool. The tool earns its place the way every tool does: the agent's body protocol actually dispatches sub-agents, and those dispatch steps are the justification, so there is nothing extra to write into the agent. Reword the guidance, the agent-builder design-tree question and Step 6 conformance check, and the two operator-facing docs so the exception is gated on the body using the tool (present only if used), not on documenting a rationale. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
What changed
Reframes the agent-building guidance's "subagents cannot spawn subagents" rule from a flat platform prohibition into a preferred default with a justification clause, across six files:
Agenttool. The default keeps dispatch boundaries clean, keeps every dispatch namespaced through a skill, and keeps the orchestrating context economical.Agenttool then earns its place the way every tool does, by being used in the body, so the dispatch steps are the justification and nothing extra is recorded. The worked example is a review coordinator that dispatches a dedicated review agent so the reviewers get fresh context and the panel's deliberation stays out of the coordinator's window.The Han convention itself is kept (all 23
han-core/agents/*.mdwithhold theAgenttool; skills carry it and do the dispatching). What changes is the rationale, and the agent-builder conformance check shifts from "remove theAgenttool" to "default to none; keep it only when the agent's body dispatches sub-agents."Closes #99
Key file changes
han-plugin-builder/skills/guidance/references/agent-building-guidelines/agent-external-files.md— rewrote the "Subagents cannot spawn subagents" section (now "Default to noAgenttool: prefer dispatch from skills to agents") into the preferred-default-with-justification, and dropped the flat platform-rule statement.han-plugin-builder/skills/guidance/references/skill-building-guidance/agent-dispatch-namespacing.md— de-conditionalized the "If your agents do not have theAgenttool" framing back to a prescriptive convention, dropped the platform-rule citation, and added a reciprocal cross-link to the exception discussion.han-plugin-builder/skills/guidance/references/plugin-entity-taxonomy.md— reconciled the composition rule so "agents can dispatch other agents" reads as a deliberate exception, not the default.han-plugin-builder/skills/agent-builder/SKILL.md— reworded the design-tree question and the Step 6 conformance criterion so theAgenttool is kept only when the agent's own protocol dispatches sub-agents (present only if the body uses it).docs/how-to/create-a-new-agent.mdanddocs/skills/han-plugin-builder/agent-builder.md— reworded the operator-facing echoes to match.Notes for review
docs/research/guidance-currency-review.mdanddocs/research/guidance-update-plan.mdcarry the same stale framing but are protected from edits bydocs/research/CLAUDE.md. Whoever later executes the guidance-update plan should re-check the current platform behavior before adding a platform-rule citation.CHANGELOG.mdedits, per the PR template (handled by/han-release).Docs-only change; no test plan.
🤖 Generated with Claude Code