feat: scenarios v2 — event-driven step composition & lifecycle automation
- Dominant language
- Go
- Stars
- 2
- Forks
- 0
- Avg merge
- 5h 49m
- Merged PRs (30d)
- 189
Description
## Problem
Today's backlog blitz involved: spawning 13 agents with custom prompts, monitoring them, reviewing PRs with Codex consensus, merging, rebasing on conflicts, nudging stuck agents, and cleaning up. Every step was manual orchestration by a supervisor.
Skills help (`spawn-agent`, `review-loop`, `fan-out-review`) but they're isolated — each describes one step, not the full workflow. And [scenarios](../blob/main/CLAUDE.md) today only cover the **static setup** half: a scenario TOML enumerates N sessions and launches them all at once (`gr scenario start`), with lifecycle (`stop`/`resume`/`delete`/`status`), dynamic membership (`add`), and completion tracking (`task-done`). There's no way to say "run this 5-step pipeline across N issues."
## Proposal
Grow the **existing scenarios feature** into a full lifecycle orchestrator — call it **scenarios v2**. This is deliberately *not* a new top-level concept ("recipes"): we extend the scenario TOML and the `gr scenario` command family rather than introducing a parallel format. Static scenarios (today's behaviour) remain the zero-step base case; v2 layers event-driven step composition on top.
The v2 scenario TOML keeps the existing `[scenario]` + `[[sessions]]` blocks and adds an optional ordered `[[steps]]` pipeline:
```toml
version = 2
[scenario]
name = "backlog-blitz"
goal = "Process issues into PRs via parallel agents"
# Sessions can be generated dynamically instead of enumerated by hand.
[[sessions]]
source = "github_issues" # or enumerate sessions explicitly, as in v1
filter = { label = "next" }
agent = "claude"
prompt_template = "prompts/issue-worker.md"
[[steps]]
name = "monitor"
action = "watch"
until = "all_sessions_done"
on_review_ready = "review"
on_stuck = "nudge"
stuck_timeout = "10m"
[[steps]]
name = "review"
action = "fan_out_review"
lenses = ["correctness", "security"]
use_codex = true
[[steps]]
name = "merge"
action = "merge_ready"
method = "rebase"
cleanup = true # delete session after merge
```
Run with the existing command, no new verb:
```bash
gr scenario start backlog-blitz --repo ~/projects/example
```
### What v2 adds over today's scenarios
- **Ordered step pipeline** — `[[steps]]` with an `action` per step (`watch`, `fan_out_review`, `merge_ready`, `nudge`, …). A scenario with no steps behaves exactly as it does today.
- **Event-driven routing** — steps react to agent state changes (`on_review_ready`, `on_stuck`, `until = all_sessions_done`, `stuck_timeout`). Builds on #109 (event stream) and #110 (supervisor mode).
- **Dynamic session sources** — `source = "github_issues"` + `filter` fans out one session per matched issue, instead of enumerating each session by hand. `file_list` / `manual` also supported.
- **Built-in action primitives** — each action maps to an existing skill/primitive (`fan_out_review` ≈ the fan-out-review skill + Codex consensus; `merge_ready` ≈ rebase + merge + cleanup).
- **Prompt templates** — `prompt_template = "prompts/issue-worker.md"` in addition to the inline `task` string scenarios take today.
- **Workflow-position resume** — scenario state persists step position, so `gr scenario resume` can pick up a partially-completed pipeline (not just bulk-restart the sessions, as it does today).
### Relationship to existing features
- **Supersedes the "recipes" framing** — recipes and scenarios are the same concept at two maturity levels, so we merge them rather than shipping two formats. v1 (static) is the base case; v2 (stepped) is the superset.
- #25 (session templates) ⊂ scenarios: templates define *what to create*, scenarios v2 defines the *full lifecycle*.
- Builds on #109 (event stream), #110 (supervisor mode), and #36 (structured message types for step→step comms).
### Open design questions
- **Versioning**: gate steps behind `version = 2` in the TOML, or feature-detect from the presence of a `[[steps]]` block?
- **`coordinator_kind`** (from the competitive-analysis note below): a per-scenario field letting the orchestrator apply an agreement protocol (e.g. Raft) before committing shared state — useful for approval / red-blue step actions.
- **Workspace safety invariants** (cwd-prefix containment, path checks, name sanitization) should be formalized in the scenario spec, especially ahead of multi-host (#606).
### Prior art
- [Hive Recipes](https://colonyops.github.io/hive/recipes/) — multi-agent workflow templates
- Claude Code workflows — JS-based agent orchestration
- GitHub Actions — step-based workflow definitions
## Before and after TOML
### Before: static topology only
All declared sessions start together, so sequencing and reactions live in an external supervisor:
```toml
version = 1
[scenario]
name = "change-pipeline"
[[sessions]]
name = "implementer"
repo = "~/projects/example"
task = "Implement the requested change."
[[sessions]]
name = "reviewer"
repo = "~/projects/example"
task = "Review the implementation after it is ready."
[[sessions]]
name = "integrator"
repo = "~/projects/example"
task = "Integrate the change after review."
```
### After: illustrative v2 pipeline
The same file declares when each lifecycle action becomes eligible. The precise v2 vocabulary remains a design decision:
```toml
version = 2
[scenario]
name = "change-pipeline"
[[sessions]]
name = "implementer"
repo = "~/projects/example"
task = "Implement the requested change."
[[steps]]
name = "wait-for-implementation"
action = "watch"
until = "all_sessions_done"
on_review_ready = "review"
[[steps]]
name = "review"
action = "fan_out_review"
lenses = ["correctness", "security"]
[[steps]]
name = "integrate"
action = "merge_ready"
method = "rebase"
cleanup = true
```
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with CLAUDE.md and the existing `gr scenario start`, `resume`, and lifecycle commands to understand the v1 contract. Then read the dependencies called out in #109, #110, and #36 before settling the v2 TOML, versioning, and event-routing design. Done means static scenarios remain compatible and stepped scenarios can persist and resume workflow position.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- cli, devtools
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100