Add `xmd prompt`: turn a request into an approved executable Plan

[taras]

Motivation

xmd prompt turns steps into a program

This document is a workflow that generates an executable Plan from a sequence of steps. It combines the original Prompt, which describes those steps, with the XMD components available to carry them out. A coding agent turns both into one document that explains and executes the sequence.

The result is the XMD version of a coding agent’s plan. A conventional Markdown plan must be interpreted again before its steps can happen. An XMD Plan already contains those executable steps, so running it simply executes them.

A draft remains text while this workflow reviews it. Nothing in it runs before you approve it. After approval, xmd prompt validates the exact source again. By default it prints the approved XMD source. --output writes that source to a file instead, and --run executes the Plan. With both options, the command writes the source before running it.

xmd prompt "ask me for my age and write it to a file"

xmd run -e executes a program someone already wrote. xmd prompt performs the preceding conversion and review. It adds no second execution model.

Terminology

These terms are used precisely:

• A Prompt is the person’s original natural-language request.
• A Plan is the executable XMD program produced from that Prompt.
• A Plan combines reader-facing prose expressing the Prompt’s intent with the XMD components that carry it out.
• xmd prompt converts a Prompt into an approved Plan.
• The prompt command document is the packaged Markdown workflow that performs generation, checking, review, revision, approval, stopping, explanation, and exhaustion. It is not itself a Plan.
• The prompt profile is the constrained trusted-host context under which that document runs.
• A draft is candidate Plan source that has not been approved. It remains inert text.

“Plan” is not a generic synonym for a workflow, policy document, command implementation, arbitrary XMD document, or the packaged prompt command document.

The reusable or custom <Plan> surface remains separate in #660.

Architecture

The trusted host owns two root executions with complete teardown between them:

fixed command preflight
 -> build the run-profile syntax catalog
 -> execute the exact packaged prompt command document
 -> one enclosing Session
 -> draft, check, repair, review, revise, approve, stop, explain, or exhaust
 -> Return the exact approved Plan source
 -> await prompt-profile execution and complete provider teardown
 -> admit the returned source again
 -> perform exactly the selected output mode:
 -> print the exact source; or
 -> exclusively create an output file; or
 -> execute through the ordinary supplied-source path; or
 -> create the output file and then execute

The packaged Markdown owns:

• drafting;
• repair;
• diagnostic presentation;
• review;
• revision;
• approval;
• stopping;
• final-invalid explanation;
• authored failure; and
• finite exhaustion.

Trusted TypeScript owns:

• fixed command parsing and preflight;
• prompt-profile assembly;
• syntax-catalog construction;
• property-source parsing and frozen option signatures;
• non-executing draft checking;
• complete prompt-profile teardown;
• final admission;
• byte-exact stdout;
• exclusive output-file creation; and
• ordinary supplied-source execution.

No drafting, retry, review, revision, explanation, or exhaustion policy belongs in TypeScript, <Prompt>, or the Agent API.

Command surface

xmd prompt <Prompt> [--output <path>] [--run] [--session <name>] \
 [shared options] [--props-<name> <value>]…

The Prompt is exactly one positional string containing at least one non-whitespace character. Missing, repeated, empty, and whitespace-only Prompts fail during fixed preflight.

-- ends option parsing, allowing a dash-leading Prompt.

The command adds:

• --output <path> — exclusively create a file containing the exact approved source;
• --run — execute the approved Plan after final admission and any requested output-file creation;
• --session <name> — replace the invocation-unique authorship session name with a non-empty explicit name.

The unreleased --save spelling is removed. It has no compatibility alias.

-e and --eval remain exclusive to xmd run.

Property arguments

The non-empty Prompt must appear before every individual --props-* option. An individual property option before the Prompt is refused during fixed preflight.

Known fixed-arity options, including aggregate --props, may appear before the Prompt.

For every initial or revised draft, the host:

1. inspects the root declaration without execution;
2. derives property bindings from the original CLI and invocation-environment sources;
3. checks the frozen signatures of supplied individual options;
4. resolves those sources against the draft’s schema; and
5. checks the draft with the resolved props.

Candidate-versus-caller failure classification and frozen property signatures remain unchanged.

Shared option roles

These options remain meaningful without --run because they participate in authorship, catalog construction, property admission, output selection, or the whole-command deadline:

• --output;
• --session;
• --include;
• --props and declared individual --props-* options;
• --agent-provider;
• --default-agent; and
• --timeout.

The following options configure only final Plan execution and are refused during fixed preflight unless --run is present:

• --verbose / -V;
• --journal / -j;
• --raw;
• --timeout-exec;
• --timeout-fetch;
• --approve-all;
• --approve-reads;
• --deny-all;
• --secret-detection; and
• --no-secret-detection.

Final-run permission flags cannot widen the prompt profile.

Help

xmd prompt --help is generic and effect-free. It documents:

• the Prompt positional;
• default byte-exact source output;
• --output;
• --run;
• --session;
• aggregate props;
• the individual-property ordering rule;
• shared authorship and admission options; and
• which final-run options require --run.

Help does not generate individual property options and does not:

• load the packaged prompt command document;
• build a syntax catalog;
• inspect a generated document;
• start an Agent;
• construct a prompt profile;
• elicit an answer;
• create a file or journal; or
• execute a Plan.

A complete Plan

A produced Plan begins, after optional frontmatter, with one descriptive level-one Markdown heading as its first body content.

The Plan then preserves:

• the Prompt’s sequence of readable steps;
• every requested outcome;
• meaningful ordering between those outcomes;
• reader-facing prose; and
• the XMD components beside the steps they perform.

For example:

# Ask for an age and save it

Ask me for my age.

<Elicit ... as="result" />

Write it to a file.

<File path="age.txt">{result.age}</File>

The Prompt need not be quoted literally. It may be divided, clarified, and rewritten as natural prose. The resulting Plan must remain understandable in the same order in which its actions execute.

The descriptive H1 and narrative-plus-components form are enforced through the initial, repair, and revision instructions and through human review. They are not hidden checks in TypeScript or validateDocument().

The packaged prompt command document

The host executes one exact checked-in Markdown value root, packaged as prompt-command.md, under the stable internal source identity <prompt-command>.

Its declared return schema is exactly:

{ "type": "string" }

The host supplies these internal inputs:

• the original Prompt;
• the rendered run-profile syntax catalog;
• the resolved logical session name.

They are not Plan root props and consume none of the Plan’s property sources.

The document begins with the approved introduction in this issue and uses these visible stage headings:

## Create the first draft
## Check and repair the draft
## Review the draft
## Continue from your decision
## Return the approved Plan

Stable explanations remain outside repeated loops where possible. The command document does not expose internal <Return> failure precedence to the user.

<Return> is internal control flow. It transfers the exact approved source from the command document to the trusted host and does not print that source.

Authorship Agent and Session

One enclosing <Session> expansion carries every Agent turn:

• the initial draft;
• automatic repairs;
• human-requested revisions; and
• the optional final explanation.

Sibling Sessions are not used. The same authored name on sibling Sessions would still represent distinct placements.

Without --session, the host generates an invocation-unique logical name. With --session <name>, the exact non-empty name replaces it. The default and named session-directory identities, preparation rules, cleanup rules, and continuation behavior remain unchanged.

The prompt profile gives the authorship Agent:

• its session-specific host-owned directory;
• no additional directories;
• no MCP servers;
• an empty native-tool allowlist;
• strict denial of every native permission request; and
• no document Files, command, service, or XMD-mediated network authority.

The provider’s own model transport does not grant the Agent a native network tool.

The host instruction layer establishes authority and common context. It does not require every Agent answer to be XMD source.

Each authored <Prompt> owns its own response contract:

• initial, repair, and revision turns request one complete replacement Plan as source only;
• the final explanation turn requests explanatory prose only.

A failed, cancelled, unavailable, or protocol-invalid Agent turn is terminal. Partial text never becomes a draft or explanation.

Drafts remain inert

Every Agent reply remains an inert string throughout prompt-profile execution.

The command document may:

• bind the string;
• pass it to <CheckDraft>;
• present it through <CodeBlock>;
• pass diagnostics into another Agent turn;
• retain it as the approved value; or
• return it to the host.

It never evaluates, imports, or executes a draft.

Only the exact approved source may proceed, and only after complete prompt-profile teardown and final host admission.

Internal draft checking

The prompt profile declares one protected internal value component:

<CheckDraft source={draft} as="assessment" />

Repository component lookup cannot replace it.

<CheckDraft> checks an unapproved draft without executing it. Its behavior is the behavior previously assigned to the internal <ValidateCandidate> name.

For each draft it:

1. checks the supplied root declaration without execution;
2. derives bindings once a usable root property schema exists;
3. verifies every frozen supplied individual-option signature before consuming tokens;
4. resolves the original CLI and invocation-environment property sources; and
5. calls core’s validateDocument() with those props, the caller’s includes, and the run-profile declarations.

Core’s validateDocument() keeps its existing name. This issue introduces no generic public <Validate> component.

Draft-authored failures return structured problems eligible for repair, including:

• source and frontmatter failures;
• invalid root props or return declarations;
• binding collisions;
• missing required props; and
• other definite whole-document diagnostics.

Caller-authored failures raise terminally, including:

• malformed aggregate CLI or environment JSON;
• a supplied individual option not declared by the usable draft schema;
• a malformed individual value;
• an extra positional exposed by the draft’s arity; and
• a later schema removing a frozen option or changing its arity or accumulation behavior.

Caller-authored failures cause no repair, presentation, approval, output, journal, or execution.

<CheckDraft> reports structural facts only. It does not decide whether the H1 or prose adequately communicates the Prompt.

Create, check, and repair a draft

The first draft instruction requires:

• one complete replacement root as source only;
• optional frontmatter followed immediately by one descriptive H1;
• the Prompt’s complete sequence as readable prose;
• every requested outcome;
• meaningful ordering; and
• each XMD component beside the prose describing its action.

Each initial draft and each human-requested revision receives its own automatic repair budget:

• the base draft is attempt one;
• at most three repair turns may replace it;
• every repair prompt contains the complete structured draft diagnostics;
• every repair response is one complete replacement root; and
• repair instructions repeat the complete Plan requirements, including the descriptive H1.

The fourth invalid draft is repair-exhausted and proceeds to human review with its diagnostics.

No fence is stripped, Markdown substring extracted, or patch applied.

Human review

The command document permits at most ten draft presentations.

The exact Elicitation values are:

• Approve
• Request changes
• Stop
• Explain what went wrong

The offered decision set depends on validity and round:

Review state	Offered values
Valid, rounds 1–9	Approve, Request changes, Stop
Invalid, rounds 1–9	Request changes, Stop
Valid, round 10	Approve, Stop
Invalid, round 10	Explain what went wrong, Stop

Request changes requires non-empty feedback. It sends one complete-replacement revision request through the same enclosing Session and resets the automatic repair budget.

Revision instructions repeat the descriptive-H1 and narrative-plus-components requirements.

The review presents the exact draft through <CodeBlock>. Invalid reviews also present the complete structured diagnostics. Draft text cannot close the presentation fence and is never interpreted.

Approve binds the exact draft for return. It does not execute or print the draft.

Explanation after the final invalid draft

When the tenth presented draft is invalid, the person may select Explain what went wrong.

That choice:

1. makes one final <Prompt> turn in the same enclosing Session;
2. is not another draft, repair, revision, or review round;
3. relies on the Session’s existing conversation history;
4. supplies the final diagnostics, which the Agent has not previously seen;
5. asks why the attempts failed and what the person should clarify next time;
6. requests explanatory prose rather than document source;
7. treats the answer as inert text;
8. cannot return to drafting or approval; and
9. ends without source output, file output, journal, or Plan execution.

The explanation prompt supplies no draft, Prompt, catalog, or prior diagnostics again. Those remain available only through the existing Session history. Its new contextual data is the final diagnostics.

A failed explanation turn is terminal.

A successful explanation is reported through the command’s ordinary terminal failure reporting as the authored failure message. It is not written to source stdout and is not interpreted as XMD. The command exits nonzero because no Plan was approved.

No TypeScript or Agent API behavior implements this branch.

Command-document history and presentation

The prompt command document uses an invocation-owned in-memory durable stream because ordinary document and <Prompt> semantics require one.

That stream is:

• never written to --journal;
• never persisted as a workflow;
• never reused or replayed; and
• discarded after complete prompt-profile teardown.

The configured Agent provider may retain the named Session under its ordinary provider contract.

Command-document rendering is not successful CLI source output. Successful source output is written by the trusted host only after teardown and final admission.

Final admission

After the command document returns and its entire prompt-profile scope tears down successfully, the host treats the approved source as untrusted again.

The host repeats checking and property resolution using:

• the exact returned bytes;
• the original raw CLI and invocation-environment property sources;
• the frozen individual-option signatures;
• the caller’s ordered includes; and
• the ordinary run-profile declarations.

A final caller-source failure or document failure exits nonzero. It does not re-enter drafting or review.

The resolved props belong to the exact approved bytes. No props object from an earlier draft is reused.

No stdout source, output file, journal, or Plan execution begins before this admission succeeds.

The approved source is the CLI result

The exact approved source is the primary result of xmd prompt.

Default: print the source

xmd prompt "<Prompt>"

After teardown and final admission, the host writes the exact approved source to stdout.

It adds no fence, label, delimiter, or newline. It does not execute the Plan or create a generated-source file.

Write the source

xmd prompt "<Prompt>" --output <path>

After teardown and final admission, the host exclusively creates <path> with the exact approved bytes.

An existing target remains unchanged and fails the command. The command writes nothing to stdout and does not execute the Plan.

Run the Plan

xmd prompt "<Prompt>" --run

After teardown and final admission, the host executes:

retainedSource("<prompt>", source)

through the ordinary supplied-source path.

The host does not print the source. Stdout belongs exclusively to the Plan’s ordinary output.

Write, then run

xmd prompt "<Prompt>" --output <path> --run

After teardown and final admission, the host exclusively creates the file first.

Execution begins only if file creation succeeds. An existing target or other write failure leaves the target unchanged where applicable and prevents execution.

The host does not print the source. Stdout belongs exclusively to the Plan.

A runtime failure does not return to authorship. A successfully created output file remains.

Journal behavior

Authorship never writes the final journal.

A diagnostic journal may be created only when:

• --run is present;
• --journal <path> is present; and
• final Plan execution is beginning.

Default source output and output-only mode create no journal.

The final journal contains no prompt command document, authorship Session, Agent turn, draft check, repair, human review, explanation, or approval event.

Authored failures

Path	Authored failure
Ordinary Stop	xmd prompt stopped at your request. Nothing was output or run.
Stop on the final invalid draft	xmd prompt reviewed ten drafts without an approved Plan. Nothing was output or run.
Unexpected post-Session fallback without approval	xmd prompt ended without an approved Plan. Nothing was output or run.
Successful final explanation	The coding agent’s explanation is the authored terminal failure message; no generic advice replaces it

An ordinary Stop includes stopping a valid tenth draft.

The final-invalid Stop is distinct from the explanation choice. It reports exhaustion without spending another Agent turn.

All authored failures are selected by the Markdown command document. They exit nonzero and produce no approved-source stdout, output file, final journal, or execution.

Cancellation and failure ordering

The whole-command deadline encloses:

• fixed preparation after argument admission;
• catalog construction;
• prompt-profile execution;
• Elicitation;
• explanation when selected;
• profile teardown;
• final admission;
• source output or exclusive file creation; and
• final execution when requested.

Cancellation stops active authorship and awaits structured teardown.

No final admission or output mode begins until prompt-profile execution and teardown both succeed. A teardown failure wins over an approved source.

Once ordinary Plan execution begins, its existing outcome and teardown precedence apply unchanged.

Acceptance matrix

The amended evidence replaces the superseded TypeScript-policy matrix.

ID	Boundary	Required evidence
P1	Fixed grammar	Exactly one non-empty Prompt; individual --props-* options require the Prompt first; aggregate props retain ordinary placement
P2	Effect-free help	Generic help documents default output, --output, --run, --session, property ordering, and run-only flags without loading the packaged document or performing effects
P3	Packaged command document	The package-relative prompt-command.md is the exact root executed under <prompt-command> and cannot be replaced through component lookup
P4	Approved document language	The shipped document contains the approved introduction and the five visible stage headings
P5	Complete Plan instructions	Initial, repair, and revision prompts require optional frontmatter followed by a descriptive H1, readable ordered steps, and components beside their prose
P6	One Session	Initial drafting, repairs, revisions, and final explanation use one enclosing Session; default names differ and --session supplies the exact override
P7	Prompt-profile authority	The authorship Agent receives only the settled session directory and constrained authority; final-run flags cannot widen it
P8	Draft inertness	No draft is imported, evaluated, journaled as the final Plan, saved, printed as success, or executed before approval
P9	Protected checker	<CheckDraft> is the protected host-declared capability, repository lookup cannot replace it, and <ValidateCandidate> is absent
P10	Failure classification	Draft-authored problems return structured facts; caller-authored failures escape terminally; frozen property signatures are checked before token consumption
P11	Repair budget	Each base draft receives at most three repair turns; a human revision resets that budget
P12	Friendly review values	The exact values and per-round decision sets are Approve, Request changes, Stop, and final-invalid-only Explain what went wrong
P13	Revision feedback	Request changes requires non-empty feedback and requests a complete replacement Plan preserving the H1 and narrative requirements
P14	Final explanation	Final-invalid explanation makes exactly one additional <Prompt> turn in the same Session and supplies only the previously unseen final diagnostics as new context
P15	Explanation is terminal	Explanation cannot trigger checking, repair, presentation, revision, approval, or another Agent turn; its inert answer is reported and the command ends without a Plan
P16	Authored stopping	Ordinary Stop, final-invalid Stop, unexpected fallback, and explanation use authored Markdown failure paths with the required messages or explanation
P17	Final gate	Complete prompt-profile teardown and final admission precede every successful output mode
P18	Default stdout	Default success writes the exact approved bytes to stdout with no fence, label, delimiter, or added newline and performs no execution
P19	--output	Output-only success exclusively creates a byte-identical file, writes no stdout, and performs no execution
P20	Explicit --run	Plan execution occurs only with --run, through the ordinary supplied-source path
P21	Write before run	With --output --run, byte-identical exclusive creation completes before execution; write refusal prevents execution
P22	Stdout ownership	Source bytes and runtime output never share stdout: default owns source stdout; run modes leave stdout entirely to the Plan
P23	Run-only preflight	Every explicitly supplied run-only flag is refused before catalog or Agent work unless --run is present
P24	Journal separation	No journal file is created without final execution; a requested journal begins only when --run starts and contains no authorship activity
P25	Session-directory lifetime	Invocation-unique cleanup and named-directory preservation remain exactly as specified, with no recursive deletion
P26	Exact bytes and props	Approval, final admission, stdout, --output, and execution use the exact returned bytes; final props are resolved for those bytes
P27	Ordinary run behavior	--run preserves ordinary cwd, includes, props, Agent configuration, permissions, timeouts, output, value, failures, and exit behavior
P28	Teardown and cancellation	Cancellation and every teardown failure settle before final admission, source output, file output, journal creation, or execution

Use one discriminating regression for each distinct boundary. Do not restore permutations that existed only to prove the superseded TypeScript policy loop.

Dependencies and delivery

Delivered foundations remain:

• Add xmd run -e "<inline document>" to run inline content without a file #76 — supplied-root-source execution;
• Add provider-neutral Elicit through the core Context API #197 — Elicitation and the CLI WebForm provider;
• Add xmd syntax for discoverable component documentation #632 — structured syntax catalog;
• Allow a value body to produce its <Return> conditionally #640 and Give a nested run-profile child a deterministic agent route #641 — Markdown control flow and nested Agent routing;
• Materialize fresh ACP sessions at the first consuming operation #648 — lazy fresh Session materialization;
• Validate supplied document structure without executing it #653 — supplied-document validation without execution;
• ✨ Render arbitrary text safely with <CodeBlock> #658 — safe source presentation through <CodeBlock>;
• ✨ Deliberately fail an XMD document with <Fail> #659 — authored failure through <Fail>;
• ✨ Let <Json> capture its text with as #667 — current PR foundation at e75859d0fcf9195581f38841675263e73e1d96cc.

PR #657 remains the focused implementation vehicle. Its issue #260 delivery includes:

• rename the packaged asset to prompt-command.md;
• rename PROMPT_PLAN and related source/test vocabulary to PROMPT_COMMAND;
• install the approved introduction and visible stage headings;
• strengthen initial, repair, and revision instructions with the complete Plan requirement;
• rename the protected internal checker to <CheckDraft>;
• install the exact friendly review values and round-specific decision sets;
• add the final same-Session explanation branch;
• remove any host instruction requiring every Agent response to be source;
• replace --save with --output, without an alias;
• make byte-exact stdout the default result;
• require --run for execution;
• enforce run-only option preflight;
• preserve final admission and complete teardown before every output mode;
• preserve output-file-before-run ordering;
• keep source stdout separate from Plan stdout;
• create a journal only when final execution begins;
• update architecture.md;
• rewrite specs/prompt-command-spec.md;
• update the affected prompt-command, Agent-provider, property-binding, CLI, and Tier PR sections of the specifications; and
• add the revised acceptance evidence.

The architecture review of feedback commit 1e449879c04e7c458ff6738ae13c2da8abb290dd is not reopened by this amendment. The next feedback commit is reviewed against this amended contract.

Out of scope

• arbitrary custom prompt command documents;
• public or reusable <Plan>;
• --plan and --plan-eval;
• File or Glob authorship context;
• a generic public <Validate>;
• a general arbitrary-code sandbox;
• the collaborative playground;
• stdin or editor Prompt input;
• automatic revision after runtime failure;
• a terminal Elicitation provider; and
• durable journaling or workflow replay of authorship.