feat: delegate inline-stage artifact drafting to throwaway subagents#422
Open
fanhongy wants to merge 1 commit into
Open
feat: delegate inline-stage artifact drafting to throwaway subagents#422fanhongy wants to merge 1 commit into
fanhongy wants to merge 1 commit into
Conversation
Inline ideation/inception stages run their full body in the main conductor context, so heavy artifact-drafting reasoning (large consumes, full produces drafts) accumulates in the main session and forces frequent manual compaction. Add a protocol-driven drafting hand-off: the conductor collects answers and runs the approval gate inline, but delegates ONLY the artifact-drafting sub-step to a single throwaway Task(directive.lead_agent) whose context is discarded after it returns the §11 summary. Stages stay mode: inline — no engine, schema, or directive-type change; this is distinct from whole-stage mode: subagent (which an interactive stage cannot use, since a subagent cannot drive the question UI or the gate). Hook-safety: the conductor never spawns the draft Task while any [Answer]: tag is blank, and the subagent treats any *-questions.md in the stage dir as read-only (the Stop hook matches the -questions.md suffix), keeping aidlc-stop.ts's human-wait carve-out honest. - core/aidlc-common/protocols/stage-protocol.md: new "Drafting delegation for inline stages" section (three-part execution, ordering, hook-safety, fallback) - harness/claude/skills/aidlc/SKILL.md: draft sub-step in the gate: true arm - core/aidlc-common/conductor.md: persona craft for the delegation - docs/reference/03,04,15: document the hand-off, distinct from mode: subagent - tests/integration/t154: lock in the contract across protocol + SKILL - dist/: regenerated for all four harnesses (drift-clean) Refs awslabs#421 Co-Authored-By: Claude Opus 4.8 <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
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
Inline ideation/inception stages run their full body in the main conductor
context, so heavy artifact-drafting reasoning (large
consumes, fullproducesdrafts) accumulates in the main session and forces the user to compact
repeatedly — and the forwarding loop won't yield for a compaction without a
manual interrupt.
This adds a protocol-driven drafting hand-off (ralph-loop style): the
conductor stays thin — it collects answers and runs the approval gate inline —
but delegates only the artifact-drafting sub-step to a single throwaway
Task(directive.lead_agent)whose context is discarded after it returns the §11summary. The heavy drafting reasoning never lands in the main transcript.
Stages stay
mode: inline— no engine, schema, or directive-type change.This is deliberately distinct from whole-stage
mode: subagent, which aninteractive stage cannot use (a subagent cannot drive the question UI or the
approval gate).
Approach
Chosen over wiring the unused
dispatch-subagentdirective because the split weneed is intra-stage: it fits inside the one existing
run-stagedirective, soit needs no engine/schema/directive churn and keeps the blast radius to prose +
docs + one test. The draft step slots into the existing atomic stage ritual
(
questions → artifact → reviewer → completion → learnings → gate) — itspecifies how the artifact step runs, not a new step.
Hook-safety
Taskwhile any[Answer]:tag is stillblank (the §3 Step 4 completeness check gates it).
*-questions.mdin the stage dir as read-only(the Stop hook matches the
-questions.mdsuffix, not just the canonicalname), so it can never introduce/clear a blank tag that
aidlc-stop.ts'sTier-2 human-wait carve-out would misread.
Changes
core/aidlc-common/protocols/stage-protocol.md— new "Drafting delegation for inline stages" section (three-part execution, ordering, hook-safety, fallback)harness/claude/skills/aidlc/SKILL.md— draft sub-step in thegate: truearmcore/aidlc-common/conductor.md— persona craft for the delegationdocs/reference/03,04,15— document the hand-off, distinct frommode: subagenttests/integration/t154-drafting-delegation-contract.test.ts— locks the contract across protocol + SKILLdist/— regenerated for all four harnesses (drift-clean)Scope notes
artifact-generating inline stage. Verify on the heaviest stages
(
requirements-analysis,application-design) before relying on it broadly.aidlc-version.ts,CHANGELOG.md, or the README badge. Happy to add thebump/changelog entry if you'd prefer it in-PR.
Testing
bun scripts/package.ts --check— drift-clean across all four harnessest154(new),t32,t37,t38,t68,t119— all passt140,t19) are apre-existing missing
@anthropic-ai/claude-agent-sdkdependency in the localenvironment, unrelated to this change.
Refs #421
🤖 Generated with Claude Code