Skip to content

Commit 7f2a10f

Browse files
committed
✨ Make the approved Plan the result, and the workflow readable end to end (#260)
The command document is now a workflow somebody can read straight through. It opens by saying what `xmd prompt` is for — a Prompt describes steps, the components carry them out, and the coding agent turns both into one document that explains and executes the sequence — and every stage after that is a heading: creating the first draft, checking and repairing it, reviewing it, continuing from the decision, returning the approved Plan. Every Plan now begins with one descriptive level-one title, and the generation, repair and revision turns each ask for it alongside the steps-beside-components structure, so a replacement cannot quietly drop either. The worked example is a titled Plan itself. This is an authorship and human-review requirement, not a rule hidden in the checker: `<CheckDraft>` reports structural facts and would accept a titleless Plan that a person would send back. `<ValidateCandidate>` is `<CheckDraft>` throughout. It checks a draft rather than validating a candidate, and nothing about what it does changed. The review choices are the words a person reads — Approve, Request changes, Stop — with no internal spelling behind them. A tenth draft that still has problems now offers something better than only stopping: Explain what went wrong makes one more ordinary turn in the same Session, carrying only the final diagnostics, because the conversation already holds the Prompt, the catalog and every draft. It asks for an explanation and explicitly not another Plan; its answer is inert text, reopens no draft limit, is reported as the coding agent's own words, and ends the command. So the host's instruction layer no longer demands that every answer be document source — it says only that an answer belongs to the message that asked for it, and each authored turn owns its own shape. The approved Plan is the command's result. By default it goes to stdout, byte for byte, with nothing this command added, so it can be piped, diffed or read before anybody commits to it. `--output` puts those bytes in a file instead, exclusively created. `--run` runs it. With both, the file is written first and only a successful write is followed by the run. `--save` is gone rather than aliased; nothing has been released to keep compatible with. That makes most execution flags conditional, so they are refused rather than ignored: a caller who asks for a journal, a permission mode or an exec deadline from a command that runs nothing has not been answered. `--include`, `--agent-provider`, `--default-agent`, `--session` and `--timeout` keep working always — they build the catalog, settle the agent, name the conversation, admit properties and bound the command. A journal exists only when `--run` begins. Claude-Session: https://claude.ai/code/session_015HcqB9kJM9KFnMNToAuZF6
1 parent 1e44987 commit 7f2a10f

15 files changed

Lines changed: 792 additions & 290 deletions

‎architecture.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3545,7 +3545,7 @@ Status is measured against main.
35453545
| --- | --- | --- |
35463546
| `xmd syntax` | describes every structural construct and every selected component the production `run` profile would let a document write in the contextual working directory, as deterministic Markdown or as version-1 JSON, from one catalog. Inspection only: it registers the run profile's declarations in a bounded scope and reads the filesystem for which files exist and, for a selected Markdown component, that file's frontmatter. It runs no body, imports no repository TypeScript module, installs no provider, mints no authority and writes no journal. An include it cannot enumerate — a selection-relevant symbolic link to a directory beneath it included — fails the whole request rather than printing a healthy subset | built on the #632 stack |
35473547
| document validation | validates one supplied root projection and the recursive Markdown source closure normal component selection discovers, returning deterministic version-1 document diagnostics and `valid`, `invalid` or `not-statically-checkable` invocation outcomes without evaluating document code or installing operational host behavior | built on the #654 stack |
3548-
| `xmd prompt` | turns one Prompt into a Plan and runs it, by executing two root documents with a complete scope boundary between them. First the packaged prompt command document, under the internal `<prompt-command>` identity, inside the prompt profile: one enclosing Session, a host ceiling of one host-owned directory dedicated to that logical session — keyed by the digest of the name, never the name, created empty and required to be empty before the provider exists or a session is materialized, refused rather than cleaned when it is not, durable when the caller named the session and handed back non-recursively after teardown when it did not — with no additional directories, no MCP servers, no native tools and a private strict denial no permission flag widens, no Files, command, service or network capability for that document, no repository component search, and one host-declared `<ValidateCandidate>` whose closed assessment answers `valid: false` for a defect the draft authored and raises for a defect the command line authored. Its instructions require the Plan to keep every requested outcome as reader-facing prose with each component beside the sentences describing it, through repairs and revisions alike, and prose quality stays that document's policy rather than a TypeScript rule. Authorship sits outside durability: it runs on an invocation-owned in-memory stream that is never journaled, persisted, reused or replayed. Then, only after that execution and every provider, Prompt task and Elicitation resource inside it has torn down, the host validates the returned Plan again, resolves props for exactly those bytes, optionally creates the save exclusively, and executes them through the ordinary supplied-source path under the `<prompt>` identity — one ordinary document with its own Agent provider, its own journal and ordinary run output, result and failure behavior | built on the #659 stack |
3548+
| `xmd prompt` | turns one Prompt into a Plan and runs it, by executing two root documents with a complete scope boundary between them. First the packaged prompt command document, under the internal `<prompt-command>` identity, inside the prompt profile: one enclosing Session, a host ceiling of one host-owned directory dedicated to that logical session — keyed by the digest of the name, never the name, created empty and required to be empty before the provider exists or a session is materialized, refused rather than cleaned when it is not, durable when the caller named the session and handed back non-recursively after teardown when it did not — with no additional directories, no MCP servers, no native tools and a private strict denial no permission flag widens, no Files, command, service or network capability for that document, no repository component search, and one host-declared `<CheckDraft>` whose closed assessment answers `valid: false` for a defect the draft authored and raises for a defect the command line authored. Its instructions require every Plan to begin with one descriptive level-one title and to keep the Prompt's outcomes as readable steps with each component beside the step it performs, through repairs and revisions alike; that is an authorship and human-review requirement, and `<CheckDraft>` never enforces it. A tenth draft that still has problems may be stopped or explained: the explanation is one more ordinary turn in the same Session carrying only the final diagnostics, is inert text, reopens no draft limit, and ends the command. The host's instruction layer states only that an answer belongs to the message that asked for it, so which shape a turn wants stays in the document. Authorship sits outside durability: it runs on an invocation-owned in-memory stream that is never journaled, persisted, reused or replayed. Then, only after that execution and every provider, Prompt task and Elicitation resource inside it has torn down, the host validates the returned Plan again, resolves props for exactly those bytes, and then delivers the approved Plan where the caller asked: to stdout byte for byte by default, to an exclusively created `--output` path, and — only under `--run` — through the ordinary supplied-source path under the `<prompt>` identity, one ordinary document with its own Agent provider, its own journal and ordinary run output, result and failure behavior. A journal exists only when `--run` begins, and the flags that configure only a run are refused in preflight without it | built on the #659 stack |
35493549
| `<PrintErrors>` / `printErrors(fn)` | prints failures | built on main |
35503550
| `<Fail message>` | stops authored work with the sentence its author wrote, raised where it is written. An ordinary overridable core default — never structural, never reserved, so a repository `Fail.md` is chosen ahead of it — with a closed schema of one required non-empty `message` and **self-closing only**: a paired spelling never enters its body, and `as` is refused by the body itself because there is nothing to bind. Every refusal reports the invocation and happens before the authored message, so a document that never reached its decision is never reported as having made one. A valid invocation is the ordinary failure of a function component: an `Error` carrying the exact authored message, positioned at the opening tag, rendering nothing and binding nothing. It carries no `printErrors()` declaration, which is what leaves recovery to an authored `<PrintErrors>` region under ordinary text-root modes; a value body's `throw` is not replaced there, so the authored failure settles the body ahead of missing-`<Return>` settlement. No authority, context, provider, resource, module state or durable operation of its own: replay of a completed root restores the recorded outcome without re-expanding the body | built on the #659 stack |
35513551
| `<Let as="name">` | binds one name in the current environment from exactly one source: the content it renders, or the exact value `value` names, bound by reference and never through the JSON boundary component props cross — the scanner resolves no JSON for that one prop, and expansion projects none. Which source it has is read from what the author wrote, before either one runs, so a construct naming both expands no child and evaluates no expression. It opens no scope, owns no resource, adds no middleware boundary and writes no journal record — replay reconstructs both sources through ordinary expansion | built on the #527 stack |

‎packages/cli/src/cli.ts‎

Lines changed: 46 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,13 @@ import {
109109
resolvePropsFromSources,
110110
} from "./props.ts";
111111
import type { Binding, Extraction } from "./props.ts";
112-
import { namesPrompt, scanPromptArgs, SAVE_OPTION, SESSION_OPTION } from "./prompt-args.ts";
112+
import {
113+
namesPrompt,
114+
OUTPUT_OPTION,
115+
RUN_OPTION,
116+
scanPromptArgs,
117+
SESSION_OPTION,
118+
} from "./prompt-args.ts";
113119
import type { PromptScan } from "./prompt-args.ts";
114120
import { runPrompt } from "./prompt.ts";
115121
import type { PromptExecution } from "./prompt.ts";
@@ -239,8 +245,7 @@ const runConfig = object({
239245
});
240246

241247
/**
242-
* `xmd prompt` — the request, where to keep the source, and the execution the
243-
* approved document runs under.
248+
* `xmd prompt` — the Prompt, where the approved Plan goes, and whether it runs.
244249
*
245250
* The individual `--props-*` options a candidate declares are deliberately
246251
* absent: they exist only once a document does, and the props phase binds them
@@ -249,13 +254,17 @@ const runConfig = object({
249254
*/
250255
const promptConfig = object({
251256
request: {
252-
description: "what the agent should write a document to do",
257+
description: "the steps the coding agent should turn into a Plan",
253258
...field(z.string().optional(), cli.argument()),
254259
},
255-
save: {
256-
description: "write the approved document here before running it (path must not exist)",
260+
output: {
261+
description: "write the approved Plan here instead of to stdout (path must not exist)",
257262
...field(z.string().optional()),
258263
},
264+
run: {
265+
description: "run the approved Plan instead of writing it",
266+
...field(z.boolean(), field.default(false)),
267+
},
259268
session: {
260269
description: "logical name for the assistant session (default: unique to this invocation)",
261270
...field(z.string().optional()),
@@ -1659,34 +1668,47 @@ const RUN_SOURCE_HELP = [
16591668
* are. Answering otherwise would mean generating a document to describe one.
16601669
*/
16611670
const PROMPT_REQUEST_HELP = [
1662-
"Exactly one request is required, and it is text for the agent rather than a",
1663-
"path. Quote it so the shell passes it as a single argument:",
1671+
"Exactly one Prompt is required, and it is the steps you want carried out",
1672+
"rather than a path. Quote it so the shell passes it as a single argument:",
16641673
' xmd prompt "ask me for my age and write the result to a file"',
16651674
"",
1666-
"A first-party command document turns your request into a Plan: an executable",
1667-
"Markdown document that states what you asked for in ordinary language and",
1668-
"places the components that do the work alongside those words. xmd checks each",
1669-
"draft and repairs definite defects; you approve, revise or abort before",
1670-
"anything runs.",
1675+
"A first-party command document turns your Prompt into a Plan: an executable",
1676+
"Markdown document that states each step in ordinary language and places the",
1677+
"component that carries it out beside those words. xmd checks each draft and",
1678+
"repairs definite defects; you approve, request changes or stop before anything",
1679+
"leaves the command.",
16711680
"",
1672-
"Document properties follow the request. The individual options a document",
1673-
"declares are the generated document's, so they are not listed here:",
1674-
' xmd prompt "<request>" --props-name Ada',
1681+
"The approved Plan is the result. By default it is written to stdout and nothing",
1682+
"runs, so it can be piped, diffed or read before you commit to it.",
1683+
"",
1684+
"Document properties follow the Prompt. The individual options a Plan declares",
1685+
"are the generated document's, so they are not listed here:",
1686+
' xmd prompt "<prompt>" --props-name Ada',
16751687
"",
16761688
` ${AGGREGATE_OPTION} <json>`,
16771689
" Set document properties as a JSON object",
16781690
` Environment: ${AGGREGATE_ENV}`,
16791691
"",
1680-
` ${SAVE_OPTION} <path>`,
1681-
" Write the approved document there before running it. The path must not",
1682-
" exist; an existing one is left alone and the run stops.",
1692+
` ${OUTPUT_OPTION} <path>`,
1693+
" Write the approved Plan there instead of to stdout. The path must not",
1694+
" exist; an existing one is left alone and the command stops.",
1695+
"",
1696+
` ${RUN_OPTION}`,
1697+
" Run the approved Plan instead of writing it. With --output the file is",
1698+
" written first, and only a successful write is followed by the run.",
16831699
"",
16841700
` ${SESSION_OPTION} <name>`,
16851701
" Use this logical assistant session instead of one unique to this run.",
16861702
"",
1687-
"Permission flags configure the approved document. Writing the Plan is a",
1688-
"conversation about text and gives the assistant nothing: an empty directory of",
1689-
"its own, no tools, no MCP servers, and every native permission request denied.",
1703+
`Options that only configure running a Plan — --journal, --raw, --verbose, the`,
1704+
"exec and fetch timeouts, the permission flags and secret detection — are",
1705+
`refused without ${RUN_OPTION}, because without it nothing runs for them to`,
1706+
"configure.",
1707+
"",
1708+
"Permission flags configure the approved Plan. Writing the Plan is a",
1709+
"conversation about text and gives the coding agent nothing: an empty directory",
1710+
"of its own, no tools, no MCP servers, and every native permission request",
1711+
"denied.",
16901712
].join("\n");
16911713

16921714
/**
@@ -1935,7 +1957,8 @@ function* dispatch(
19351957
argv: helpRequest.args,
19361958
scan,
19371959
include: config.include,
1938-
...(config.save === undefined ? {} : { save: config.save }),
1960+
...(config.output === undefined ? {} : { output: config.output }),
1961+
run: config.run,
19391962
...(config.session === undefined ? {} : { session: config.session }),
19401963
stack: promptStack,
19411964
},

0 commit comments

Comments
 (0)