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

Open
#421 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.