Skip to content

Add a guide for starting and resuming workflows with xmd #459

Description

@taras

Story

As an Executable.md user, I want a task-oriented workflow guide, so I can start
and resume a workflow run without reconstructing the CLI contract from
specifications or pull-request history.

Common path

The guide begins with a workflow from start through resume:

xmd workflow start --id=release-1.4 --props-channel=stable flows/prepare-release.md
xmd workflow resume release-1.4

It explains what the first command creates, where the run ID appears, what is
preserved between commands, and what the resumed command continues. A reader
should understand this path before learning identity, storage, or exit-status
details.

Current gap

PR #428 shipped xmd workflow start and xmd workflow resume and documented
their use in the product README. PR #436 then made the repository README a
local-development guide and intentionally removed its product sections.

The documentation site now gives only a short comparison between xmd run and
xmd workflow. CLI help and specs/workflow-workspace-spec.md contain the
complete contract, but they are not a guide for someone trying to complete a
workflow task.

Guide

Add /docs/workflows and link it from both the Getting Started workflow card
and the documentation navigation.

After the common path, explain in this order:

  1. when to use a workflow run instead of xmd run;
  2. how to start with an allocated or specified run ID and properties;
  3. how to resume by run ID;
  4. how the workflow definition is identified;
  5. how filesystem changes use the workflow Workspace;
  6. what the commands report and which exit statuses they return; and
  7. where local runs are stored and how XMD_WORKFLOW_RUNS selects a different
    absolute directory.

Include these runnable forms:

xmd workflow start flows/prepare-release.md
xmd workflow start --id=release-1.4 --props-channel=stable flows/prepare-release.md
xmd workflow resume release-1.4

Describe only shipped behavior. Link to specifications for detailed invariants
instead of creating a second normative contract.

Acceptance

  • /docs/workflows gives a coherent start-to-resume learning path.
  • A user can determine the command, required identifier, observable output,
    exit status, and preserved result for each documented operation.
  • Examples match current CLI help and are covered by a site or documentation
    regression.
  • Getting Started and the documentation navigation link directly to the guide.
  • The repository README remains the local-development guide established by
    📝 Make the README the development guide, and run it #436.
  • The page contains no roadmap or inventory of unavailable commands.

Authoritative sources

Relationship to #450

#450 adds a contributor entrypoint for finding repository contracts, code, and
tests. This issue adds a product guide for people running workflows.

Activity

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

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions