You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
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:
when to use a workflow run instead of xmd run;
how to start with an allocated or specified run ID and properties;
how to resume by run ID;
how the workflow definition is identified;
how filesystem changes use the workflow Workspace;
what the commands report and which exit statuses they return; and
where local runs are stored and how XMD_WORKFLOW_RUNS selects a different
absolute directory.
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:
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 startandxmd workflow resumeand documentedtheir 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 runandxmd workflow. CLI help andspecs/workflow-workspace-spec.mdcontain thecomplete contract, but they are not a guide for someone trying to complete a
workflow task.
Guide
Add
/docs/workflowsand link it from both the Getting Started workflow cardand the documentation navigation.
After the common path, explain in this order:
xmd run;XMD_WORKFLOW_RUNSselects a differentabsolute directory.
Include these runnable forms:
Describe only shipped behavior. Link to specifications for detailed invariants
instead of creating a second normative contract.
Acceptance
/docs/workflowsgives a coherent start-to-resume learning path.exit status, and preserved result for each documented operation.
regression.
📝 Make the README the development guide, and run it #436.
Authoritative sources
packages/cli/src/cli.ts— command grammar and help.specs/workflow-workspace-spec.md— workflow lifecycle and persistence.architecture.md— authority, identity, Workspace, and replay.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.