feat: replace $START _ status with new/resume semantics #101

New Issue

2026-06-05T09:03:02Z

xiaoju commented

2026-06-05 09:03:02 +00:00

What

Replace the special _ status key on $START graph nodes with two explicit status values:

new — first-time thread start (thread start)
resume — resuming a completed thread (thread resume on a completed thread)

Why

Currently $START is the only graph node that uses _ as a special status key, breaking the consistency rule that all graph edges route by $status. The _ convention:

Breaks consistency — every other node uses $status-based routing, but $START uses magic _
Limits flexibility — resume from completed thread is hardcoded in CLI with a fixed prompt ("Previous run completed. Resuming with additional context.") instead of being defined in the workflow YAML
Forces special-case code — evaluate.ts, validate.ts, validate-semantic.ts all have $START/_ special handling

Changes Required

1. Moderator (`evaluate.ts`)

Remove START_STATUS = "_" constant
When lastRole === "$START", read $status from lastOutput like any other role (it will be "new" or "resume")

2. Thread commands (`thread.ts`)

resolveEvaluateArgs(): when chain.headIsStart, return { [STATUS_KEY]: "new" } instead of "_"
cmdThreadResume() (completed path, ~line 1102-1134): evaluate $START with { $status: "resume" } instead of {}, use the graph edge prompt instead of the hardcoded completedPromptPrefix

3. Validators

validate.ts (isGraph): remove the _ exception for $START — _ is no longer valid anywhere
validate-semantic.ts (checkGraphStructure): change $START validation from "must have exactly one edge with status _" to "must have edges new and resume"
validate-semantic.ts (checkStatusEdges): remove _ rejection for user roles (no longer needed since _ is globally invalid)

4. Workflow YAML files (all `$START._` → `$START.new` + `$START.resume`)

.workflows/solve-issue.yaml
.workflows/e2e-walkthrough.yaml (if it has $START)
examples/solve-issue.yaml
examples/debate.yaml
examples/analyze-topic.yaml
examples/eval-simple.yaml
workflows/solve-issue.yaml
workflows/normalize-bun-monorepo.yaml

5. Test fixtures (`.yaml`)

packages/cli/src/__tests__/fixtures/e2e-linear.workflow.yaml
packages/cli/src/__tests__/fixtures/e2e-mustache.workflow.yaml
packages/cli/src/__tests__/fixtures/e2e-count.workflow.yaml
packages/cli/src/__tests__/fixtures/e2e-loop.workflow.yaml
packages/cli/src/__tests__/fixtures/e2e-suspend.workflow.yaml
packages/cli/src/__tests__/fixtures/e2e-completed-resume.mock.yaml

6. Tests (`.ts`)

evaluate.test.ts — all $START test cases: _ → new
validate-semantic.test.ts — update $START validation tests
thread-suspended-display.test.ts — update $START._ fixtures
thread-suspend-step.test.ts — update $START._ fixtures
thread-start-cwd-cli.test.ts — update $START._ fixture

7. Changeset

Add .changeset/start-new-resume.md bumping @united-workforce/cli as minor

YAML Example

Before:

$START:
  _: { role: planner, prompt: "Analyze the issue..." }

After:

$START:
  new: { role: planner, prompt: "Analyze the issue..." }
  resume: { role: planner, prompt: "Review the previous run output and continue the work." }

Notes

The resume edge prompt replaces the hardcoded completedPromptPrefix in cmdThreadResume
supplement (user-provided text on thread resume) is still appended to the graph prompt via buildResumePrompt()
This is a breaking change for existing workflow YAML files — all $START._ must be updated to $START.new + $START.resume

## What Replace the special `_` status key on `$START` graph nodes with two explicit status values: - `new` — first-time thread start (`thread start`) - `resume` — resuming a completed thread (`thread resume` on a completed thread) ## Why Currently `$START` is the only graph node that uses `_` as a special status key, breaking the consistency rule that all graph edges route by `$status`. The `_` convention: 1. **Breaks consistency** — every other node uses `$status`-based routing, but `$START` uses magic `_` 2. **Limits flexibility** — resume from completed thread is hardcoded in CLI with a fixed prompt (`"Previous run completed. Resuming with additional context."`) instead of being defined in the workflow YAML 3. **Forces special-case code** — `evaluate.ts`, `validate.ts`, `validate-semantic.ts` all have `$START`/`_` special handling ## Changes Required ### 1. Moderator (`evaluate.ts`) - Remove `START_STATUS = "_"` constant - When `lastRole === "$START"`, read `$status` from `lastOutput` like any other role (it will be `"new"` or `"resume"`) ### 2. Thread commands (`thread.ts`) - `resolveEvaluateArgs()`: when `chain.headIsStart`, return `{ [STATUS_KEY]: "new" }` instead of `"_"` - `cmdThreadResume()` (completed path, ~line 1102-1134): evaluate `$START` with `{ $status: "resume" }` instead of `{}`, use the graph edge prompt instead of the hardcoded `completedPromptPrefix` ### 3. Validators - `validate.ts` (`isGraph`): remove the `_` exception for `$START` — `_` is no longer valid anywhere - `validate-semantic.ts` (`checkGraphStructure`): change `$START` validation from "must have exactly one edge with status `_`" to "must have edges `new` and `resume`" - `validate-semantic.ts` (`checkStatusEdges`): remove `_` rejection for user roles (no longer needed since `_` is globally invalid) ### 4. Workflow YAML files (all `$START._` → `$START.new` + `$START.resume`) - `.workflows/solve-issue.yaml` - `.workflows/e2e-walkthrough.yaml` (if it has $START) - `examples/solve-issue.yaml` - `examples/debate.yaml` - `examples/analyze-topic.yaml` - `examples/eval-simple.yaml` - `workflows/solve-issue.yaml` - `workflows/normalize-bun-monorepo.yaml` ### 5. Test fixtures (`.yaml`) - `packages/cli/src/__tests__/fixtures/e2e-linear.workflow.yaml` - `packages/cli/src/__tests__/fixtures/e2e-mustache.workflow.yaml` - `packages/cli/src/__tests__/fixtures/e2e-count.workflow.yaml` - `packages/cli/src/__tests__/fixtures/e2e-loop.workflow.yaml` - `packages/cli/src/__tests__/fixtures/e2e-suspend.workflow.yaml` - `packages/cli/src/__tests__/fixtures/e2e-completed-resume.mock.yaml` ### 6. Tests (`.ts`) - `evaluate.test.ts` — all `$START` test cases: `_` → `new` - `validate-semantic.test.ts` — update $START validation tests - `thread-suspended-display.test.ts` — update `$START._` fixtures - `thread-suspend-step.test.ts` — update `$START._` fixtures - `thread-start-cwd-cli.test.ts` — update `$START._` fixture ### 7. Changeset - Add `.changeset/start-new-resume.md` bumping `@united-workforce/cli` as `minor` ## YAML Example Before: ```yaml $START: _: { role: planner, prompt: "Analyze the issue..." } ``` After: ```yaml $START: new: { role: planner, prompt: "Analyze the issue..." } resume: { role: planner, prompt: "Review the previous run output and continue the work." } ``` ## Notes - The `resume` edge prompt replaces the hardcoded `completedPromptPrefix` in `cmdThreadResume` - `supplement` (user-provided text on `thread resume`) is still appended to the graph prompt via `buildResumePrompt()` - This is a **breaking change** for existing workflow YAML files — all `$START._` must be updated to `$START.new` + `$START.resume`

xiaoju referenced this issue from a commit

2026-06-05 09:31:24 +00:00

feat: replace $START `_` status with `new`/`resume` semantics

xiaoju referenced a pull request that will close this issue

2026-06-05 09:31:40 +00:00

feat: replace $START `_` status with `new`/`resume` semantics #102

xiaomo closed this issue

2026-06-05 09:35:36 +00:00

xiaoju referenced this issue from a commit

2026-06-05 09:37:56 +00:00

docs: update wf-stateless-design.md to reflect new/resume semantics

xiaoju referenced this issue from a commit