d0ugal / d0ugal/graith

feat: scenarios v2 — event-driven step composition & lifecycle automation

Open
#111 3 comments 0 reactions 0 assignees View on GitHub
scenario size: L
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.