Document reader-first executable workflow writing

[taras]

Motivation

Executable documents are read twice: as source by someone deciding whether to
trust them, and as output by the person running them. The existing style guide
states important sentence-level rules, but it does not give an author a
reproducible method for structuring and refining a complete workflow.

The xmd prompt work exposed a useful method: write the workflow first as a
plain-language explanation of what happens, place each executable component
beside the sentence that explains its purpose, and refine one stage at a time
through a reader interview. That method should be recorded independently of
xmd prompt so other executable workflows can use it.

Proposed documentation

Add .agents/executable-workflows.md and link it from the Executable.md Style
Guide in AGENTS.md.

Call the method reader-first executable workflow writing:

First write the workflow as a plain-language explanation of what happens.
Then place each executable component beside the sentence that makes its
purpose clear.

The guide should establish these rules.

Structure the reader can scan

• Start with a title that names the transformation the workflow performs.
• Use the introduction to explain what enters, what comes out, what the
  workflow does, what remains inert, and when effects may begin.
• Give every meaningful stage a visible heading. A reader should understand the
  lifecycle by scanning the headings alone.
• Present the common path before exceptions and failure handling.

A comparison with a familiar concept is not a general requirement. A workflow
may use one when its own subject needs it, but the reusable method must not ask
every workflow to supply one.

Put explanation beside execution

• Explain the practical consequence before the component that performs it.
• Treat prose as the document's human-readable structure, not as comments around
  a script.
• Keep bindings, schemas, captures, counters, classifiers and formatting
  machinery silent unless their value is intentionally presented.
• Keep the workflow's bounds, branches, choices and failure paths visible in
  authored Markdown rather than hiding policy in host code.

Write for the active reader

Distinguish the voices in an executable document:

• ordinary Markdown explains the workflow to someone auditing its source;
• <Prompt> instructs an Agent;
• <Elicit> addresses the person making a decision;
• <Fail> explains why the workflow stopped; and
• <Return> passes a value without presenting it.

Use the exact labels a person sees when explaining choices. Do not make one
passage serve several audiences when they need different information.

Make outcomes complete

• A generated executable document should be independently readable: a
  descriptive title, reader-facing steps, meaningful order, and executable
  components beside the steps they perform.
• State clearly when generated text remains inert and which admission boundary
  allows effects to begin.
• Write failures as authored outcomes that say what happened, what did not
  happen, and what the person can do next.
• Do not let a defensive fallback claim a specific cause it cannot know.

Refinement interview

Define a section-by-section interview modeled on the component-description
refinement process. Review one workflow stage at a time and present exactly:

1. Current — quote the existing wording verbatim.
2. Intent — state the behavior it is trying to communicate.
3. Proposed — offer clearer replacement wording.
4. Feedback — ask one unresolved question or request approval.

Do not advance until the reader answers. Keep a visible count of approved
sections.

When feedback establishes a general rule, name it and apply it to every later
section. Explicitly reopen an earlier section when the rule changes it; never
revise approved wording silently.

When the interview reveals a product or architecture change, stop treating it
as an editorial improvement. Record the decision separately and amend the
authoritative architecture, specification, implementation and evidence. Do not
smuggle new behavior into friendlier prose.

Reusable skeleton

Include a compact example showing this shape without prescribing components
every workflow must use:

# <command> turns <input> into <result>

Explain the transformation and effect boundary.

<silent state>

## Create the first result

<Prompt>...</Prompt>

## Check and repair it

<Check ... />
<Loop max={...}>...</Loop>

## Review it

<Elicit>...</Elicit>

## Continue from the decision

<If>...</If>

## Return the approved result

<Return ... />

The skeleton illustrates narrative order; it does not introduce a required
public <Check> component or require every workflow to use an Agent, review, or
approval loop.

Verification guidance

The guide should finish with a definition of done:

• headings tell the complete story;
• every component is understandable from adjacent prose;
• source readers can audit bounds and branches;
• Agent prompts state the complete expected response;
• human choices use recognizable labels;
• failures explain their consequences;
• hidden machinery renders nothing;
• generated artifacts are independently readable;
• architecture and wording describe the same behavior; and
• focused evidence proves meaningful words, choices, bounds and effects.

Require authors to render the workflow's output and read it as the person
running it before calling the document complete.

Acceptance

1. .agents/executable-workflows.md documents the reader-first method and is
   linked from AGENTS.md.
2. The guide covers structure, adjacent prose and execution, audience-specific
   voices, visible policy, complete outcomes and effect boundaries.
3. It contains the four-part refinement interview, one-section-at-a-time rule,
   visible progress count and rule propagation behavior.
4. It separates wording improvements from product and architecture changes.
5. It includes a reusable skeleton while making clear that its particular
   components are illustrative rather than required.
6. It includes render-and-read verification and a definition of done.
7. It does not make comparison with a familiar concept a general workflow rule.

Scope

This issue documents an authoring and refinement method. It does not change XMD
runtime semantics, add components, or revise the product behavior of any
existing workflow.