awslabs / awslabs/aidlc-workflows
Front-load phases (ideation/inception) force frequent manual compaction — adopt a ralph-loop so subagents do the work and the main agent only tracks state
- Dominant language
- TypeScript
- Stars
- 4.6k
- Forks
- 827
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 165
Description
## Problem
The early phases of v2 — **initialization, ideation, inception** — accumulate a large amount of context in the **main agent** session. Token *spend* itself is fine; the pain is that all this work runs **inline in the main agent context** (per `stage-graph.json`, 30/32 stages are `mode: "inline"`; only `reverse-engineering` and `code-generation` use `mode: "subagent"`).
Because everything lives in the main session, the context window fills up fast and I have to **compact many, many times** during a single run. Worse, the forwarding loop (`SKILL.md` → `aidlc-orchestrate next/report` → repeat, enforced by the `aidlc-stop.ts` Stop hook) **keeps the workflow moving and won't naturally yield for a compaction** — I have to explicitly interrupt/pause the orchestrator mid-stage to compact, then resume.
## Proposed direction — ralph-loop execution model
Invert the execution model so the **main agent stays thin**:
- The main agent runs only the **forwarding loop + state tracking** — read `aidlc-state.md`, dispatch, observe outcome, report.
- Each stage's actual work runs in a **dedicated subagent** (the persona/lead agent for that stage), which does the heavy lifting and eventually touches the state file.
- The main agent's context then grows roughly with the *number of stages*, not with the *full transcript of every stage's reasoning* — so compaction becomes rare and the loop no longer has to be manually paused.
This generalizes the pattern already used for `reverse-engineering` and `code-generation` (both `mode: "subagent"`) to the front-loaded inline phases that hurt most.
## Relevant current mechanics
- Forwarding loop + conductor: `harness/claude/skills/aidlc/SKILL.md`
- Orchestration engine + directive kinds (`dispatch-subagent` is defined but **never emitted** today): `core/tools/aidlc-orchestrate.ts`, `core/tools/aidlc-directive.ts`
- Stage modes: `core/.../data/stage-graph.json` (`mode: inline|subagent`)
- State + audit (already atomic via `withAuditLock()`, audit-first): `core/tools/aidlc-state.ts`
- Flow control: `aidlc-stop.ts` Stop hook; existing `SESSION_COMPACTED` / `acknowledge-compaction` recovery path
## Open questions / scope
1. Should *all* inline stages move to subagent dispatch, or just the heavy ideation/inception ones?
2. Do subagents call `report` / state-mutating tools themselves, or return an outcome the main agent reports (keeping state writes single-owner)?
3. How do interactive `ask` / `present-gate` directives work when the stage body runs in a subagent (questions need to surface to the human)?
4. Should the Stop hook yield for compaction at clean stage boundaries instead of requiring a manual pause?
Contributor guide
Research direction
Start by reading harness/claude/skills/aidlc/SKILL.md, then trace dispatch and directive handling in core/tools/aidlc-orchestrate.ts and core/tools/aidlc-directive.ts. Compare the inline and subagent entries in core/.../data/stage-graph.json, and review state and Stop-hook recovery in core/tools/aidlc-state.ts and aidlc-stop.ts. Done should include a decided execution model covering state ownership, interactive directives, and compaction boundaries.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- developer-experience, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 28/100