Skip to content

[feat] Add a minimal command-only workflow runtime #1076

Closed

Description

@hsuchifeng

Parent: #818

Goal

Deliver the smallest real workflow vertical slice: pull validates command-only workflows independently, start creates durable state, and the local driver completes a run through the same next and report operations exposed to external drivers.

Scope

  • Add the initial workflows/*.yaml v1alpha1 subset: required header, ordered steps, unique IDs, one command per step, and optional shorthand output.
  • Validate each workflow file independently during pull and push, with file, line, and field diagnostics.
  • Cache only validated workflow definitions. If a previously valid file becomes invalid, retain its last valid cached version; a newly invalid file has no runnable version.
  • Continue syncing all other workflows and resources when one workflow is invalid.
  • Add only teamai workflow start, next, and report.
  • Use the common { "data": ... } / { "error": ... } envelope.
  • Persist minimal run, revision, attempt, lease, step-state, and outcome data using atomic writes and a per-run lock.
  • Reject stale, repeated, wrong-attempt, and wrong-driver reports.
  • Implement a local command driver using the same engine operations.
  • Support success, failed, and released.

Out of scope

Agent steps, retry, cancel, control flow, worktrees, gates, records, publish/resume, and external drivers.

Dependencies

Acceptance criteria

  • A two-command workflow completes through the real CLI.
  • State survives process exit between next and report.
  • Concurrent callers cannot lease the same step.
  • One invalid workflow does not block other resources or valid workflows.
  • Its last valid version remains runnable; the invalid revision never becomes runnable.
  • Diagnostics identify the file and source location.

Verification

Focused validation, cache, locking, transition, and stale-report tests; build/typecheck/lint; one real-CLI command-workflow E2E. Regenerate commands.md and add both workflow guide languages.

Activity

  1. kittimzhe commented on Oct 14, 2026

    @kittimzhe
    Contributor

    This series is an impressively clean breakdown of the #818 design. Is it open for community implementation? If so, which issue would you point a contributor at as the right entry point — #1076 looks like the natural base (everything else builds on the command-only runtime and its next/report operations), but you may prefer to keep the foundation in-house and open the series up from a higher layer.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions