Skip to content

feat: delegate inline-stage artifact drafting to throwaway subagents#422

Open
fanhongy wants to merge 1 commit into
awslabs:v2from
fanhongy:feat/ralph-loop-draft-delegation
Open

feat: delegate inline-stage artifact drafting to throwaway subagents#422
fanhongy wants to merge 1 commit into
awslabs:v2from
fanhongy:feat/ralph-loop-draft-delegation

Conversation

@fanhongy

Copy link
Copy Markdown

Summary

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 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 §11
summary. The heavy drafting reasoning never lands in the main transcript.

Stages stay mode: inlineno engine, schema, or directive-type change.
This is deliberately distinct from whole-stage mode: subagent, which an
interactive stage cannot use (a subagent cannot drive the question UI or the
approval gate).

Approach

Chosen over wiring the unused dispatch-subagent directive because the split we
need is intra-stage: it fits inside the one existing run-stage directive, so
it 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) — it
specifies how the artifact step runs, not a new step.

Hook-safety

  • The conductor never spawns the draft Task while any [Answer]: tag is still
    blank (the §3 Step 4 completeness check gates it).
  • The subagent treats any *-questions.md in the stage dir as read-only
    (the Stop hook matches the -questions.md suffix, not just the canonical
    name), so it can never introduce/clear a blank tag that aidlc-stop.ts's
    Tier-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 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-drafting-delegation-contract.test.ts — locks the contract across protocol + SKILL
  • dist/ — regenerated for all four harnesses (drift-clean)

Scope notes

  • This lands the shared mechanism; it applies by shape to every gated
    artifact-generating inline stage. Verify on the heaviest stages
    (requirements-analysis, application-design) before relying on it broadly.
  • Versioning intentionally left to maintainers — this PR does not touch
    aidlc-version.ts, CHANGELOG.md, or the README badge. Happy to add the
    bump/changelog entry if you'd prefer it in-PR.

Testing

  • bun scripts/package.ts --check — drift-clean across all four harnesses
  • t154 (new), t32, t37, t38, t68, t119 — all pass
  • Full default tier: 181/183 files pass; the 2 failures (t140, t19) are a
    pre-existing missing @anthropic-ai/claude-agent-sdk dependency in the local
    environment, unrelated to this change.

Refs #421

🤖 Generated with Claude Code

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant