github / github/spec-kit

[Feature]: /speckit-implement-waves => run each phase in a subagent to prevent context rot

オープン
#3,507 コメント 3 件 リアクション 4 件 担当者 0 名 GitHub で見る
enhancement stale
主要言語
Python
スター
137k
フォーク
12.3k
平均マージ
2日 12時間
マージ済み PR(30日)
159

説明

### Problem Statement

/speckit-implement executes the entire tasks.md inside a single agent conversation. Every phase, every task, sequentially, in one context window. For anything beyond a small feature this causes context rot. By the time the agent reaches Phase 5, the context window is already saturated with things that are irrelevant to the current phase.

The symptoms compound as the feature grows:

- Degraded quality late in the run
- No true parallelism: `tasks.md` already encodes which phases/user stories are independent (via "Dependencies & Execution Order" and [P] markers), but a single-context run can't exploit it; independent user stories are done one after another.
- All-or-nothing blast radius: one long conversation implementing 20+ tasks is hard to supervise, and a mistake in phase 2 silently pollutes the context for every later phase.

The task structure is already a dependency graph. implement just doesn't execute it like one.

### Proposed Solution

Add a wave-based way to run implement. It could be a new command like `/speckit-implement-waves`, or an opt-in flag on the existing implement. Either way it acts as a thin orchestrator on top of the implement command we already have.

The idea:

Read `tasks.md `and the "Dependencies & Execution Order" section, and group the phases into waves. Phases that don't depend on each other and touch different files go in the same wave. Phases that depend on others go in a later wave.
For each phase, run a phase-scoped implement (limited to that phase's task IDs) in its own fresh agent context. Each phase loads only the design docs it needs, runs its own tests, keeps its own TDD ordering and [P] parallelism, and marks only its own tasks off.
Run wave by wave. Phases in the same wave go in parallel, then the orchestrator waits, reconciles `tasks.md`, and starts the next wave.
The orchestrator never writes code itself. Its context only holds the wave plan plus short per-phase reports, so it doesn't rot no matter how big the feature is.
Since each phase is just implement running in isolation, all the existing implement behavior stays intact (design-doc loading, checklist gate, hooks, marking tasks off). The only thing that changes is where the work happens: lots of small clean contexts instead of one giant one.

This stays integration-neutral. "One isolated context per phase" maps onto Claude Code sub-agents, Cursor's multitask sub-agents, or just sequential fresh sessions for integrations that don't have a sub-agent primitive.

### Alternatives Considered

- Running speckit.implement once per phase by hand with a scope argument. This works, but it's fully manual. You have to track the dependency graph yourself, decide what's parallel, kick off each phase, and fix up tasks.md afterwards. The whole value here is that the orchestration is automatic.
- Just making implement commit more often. That lowers the risk of losing work, but it does nothing about context rot. It's still one saturated context.
- Splitting the feature into several smaller specify runs. This fights the methodology. The point of tasks.md is one coherent feature with one dependency graph.
- Leaning on bigger context windows or summarization. Larger windows and compaction push rot further out, but they don't fix it, and summarization tends to drop the exact decisions later phases rely on.

### Component

Spec templates (BDD, Testing Strategy, etc.)

### AI Agent (if applicable)

None

### Use Cases

- Large multi-story features (3+ user stories, 20+ tasks), which are exactly the ones where the last phases get sloppy today.
- Genuinely independent user stories. For example US1 (backend) and US2 (a separate settings screen) both only need the Foundational phase, so they can run in the same wave instead of back to back.
- Backend/frontend split features where one foundational phase unblocks two separate tracks.
- Runs you actually want to supervise. Reading five short per-phase reports is much easier than scrolling through one 200-message transcript.
- MVP-scoped runs. Orchestrate only Setup, Foundational, and US1 (the MVP slice SpecKit already recommends), each in a clean context, then stop.

### Acceptance Criteria

- [ ] Given a `tasks.md`, the command builds a correct wave plan from "Dependencies & Execution Order" (independent phases share a wave, dependent phases are sequenced).
- [ ] Each phase runs in its own isolated context. No phase's context contains another phase's transcript.
- [ ] Independent phases in the same wave run at the same time. Dependent phases never start before their prerequisites finish.
- [ ] Every in-scope task ends up marked off in `tasks.md`, with nothing lost or overwritten when phases run at the same time (the orchestrator reconciles after each wave).
- [ ] Per-phase implement behavior stays intact: TDD ordering, [P] handling, checklist gate, hooks.
- [ ] Phases that are already fully done get skipped, so re-runs are safe.
- [ ] An optional scope argument can limit the run to a phase range or a single user story (like "US1 only"). Default is all unfinished phases.
- [ ] If one phase reports a blocker mid-run, the later waves stop instead of quietly carrying on.
- [ ] Output is a short summary per phase (what changed, tests run, blockers) plus a final rollup.

### Additional Context

The data this needs is already in every tasks.md: "Dependencies & Execution Order", "Parallel Opportunities", the [P] markers, and the [US#] labels. This feature isn't about generating anything new. It's about executing that graph instead of flattening it.

I've already built this as an integration-side skill: a small orchestrator that dispatches phase-scoped implement runs into background sub-agents, with a quick blocker check before it starts and a `tasks.md` reconcile after each wave. Happy to share it as a reference.

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

既存の /speckit-implement コマンドと、issue で指定されている tasks.md のセクション「Dependencies  Execution Order」「Parallel Opportunities」、[P] マーカー、[US#] ラベルから始めます。これらを、言及されている統合側のオーケストレーターと比較します。完了の条件は、分離されたフェーズ実行、正しい wave の順序付けとリコンシリエーション、完了済みフェーズの安全なスキップ、ブロッカーの処理、スコープを限定した実行、フェーズごとのサマリーおよび最終サマリーです。

索引モデルが issue の本文から書いたものです。

評価

領域
tooling
issue の種類
機能追加
難易度
5/5
見積もり時間
1週間以上
活発さ
活発
明瞭さ
おおむね明確
初心者へのやさしさ
42/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。