Story
As a command-line user, I want xmd plan to produce one reviewed XMD program
artifact and never execute it, so I can choose explicitly when and where that
program runs.
Common paths
Write the exact approved source to stdout:
xmd plan "Prepare the release program."
Compose planning and execution explicitly through standard input:
xmd plan "Prepare the release program." | xmd run -
Or preserve the artifact first and run the saved file later:
xmd plan "Prepare the release program." --output release.md && xmd run release.md
--output remains an exclusive file sink: it creates the requested path only
after approval and never replaces an existing file. Without it, stdout contains
only the exact approved program bytes.
One command responsibility
xmd plan maps one instruction string to reviewed and approved XMD source. It
uses the same packaged <Plan> workflow as an ordinary document and does not
start a second root after authorship.
The packaged plan-command document remains a thin adapter: it supplies the
command surface to <Plan>, captures the resulting text, and returns those
exact bytes. The host awaits authorship and teardown, performs the existing
final caller-owned checks, and sends the artifact to exactly one destination.
No approved program effect runs on any success or failure path.
Command grammar
Remove --run completely; it has no alias. --run, --run=true,
--run=false, repeated occurrences, and any placement of that spelling receive
one actionable migration refusal before a catalog, Agent, session, review,
output file, journal, or document execution exists:
xmd plan --run was removed because xmd plan only produces approved source.
Run the program explicitly:
xmd plan "..." | xmd run -
xmd plan "..." --output release.md && xmd run release.md
Retain only arguments that configure planning or artifact disposition:
- the one instruction argument;
--include for the syntax catalog;
--agent-provider and --default-agent for authorship;
--session for the planning conversation;
--timeout for the whole planning invocation;
--output for the exclusive artifact sink; and
- ordinary
--help and --version behavior.
Remove options that configured the approved program's former execution:
- generated root-property arguments:
--props, --props-*, and --no-props-*;
--journal / -j;
--raw;
--verbose / -V;
--timeout-exec and --timeout-fetch;
--approve-all, --approve-reads, and --deny-all;
--secret-detection and --no-secret-detection.
Each removed spelling refuses as an xmd plan option before authorship. The
corresponding xmd run options remain unchanged. Planning-specific progress and
diagnostic trace work belongs to #676 rather than preserving execution flags
under a new interpretation.
Update command help to say that xmd plan creates, reviews, and writes approved
XMD source. Help never promises to run it and shows both explicit compositions.
Exact artifact behavior
- Default stdout and
--output receive the same byte-identical source and
digest supplied by #722.
- Status, review UI, and later planning-progress output do not contaminate
stdout; interactive presentation uses its existing non-stdout channels.
- Stop, exhaustion, failure, cancellation, or final refusal writes no artifact
and starts no program.
- The output file is created exclusively only after approval and teardown.
- A command continuation or planning session cannot cause the approved program
to execute implicitly.
Acceptance ownership
This story exclusively owns these Quest cases:
- CLI Plan: exact approved bytes reach stdout or the exclusive output file;
a negative-control program effect never occurs.
- Removed option: every
--run spelling reports the migration above and
never aliases or executes.
The successful stdin pipeline belongs to #723; this story owns the Plan
producer and the diagnostic that points to it.
Documentation and focused evidence
Rewrite specs/plan-command-spec.md around the single source-artifact outcome.
Update the command/component inventory and command lifecycle in
architecture.md and specs/executable-mdx-spec.md. Update CLI help, README,
and the homepage delivered by PR #719 so they show the public model explicitly:
Plan produces a program.
Evaluate evaluates a program in the current XMD execution.
Run executes a program from the host/CLI.
Composition decides whether and when a planned program runs.
The homepage includes both <Plan> followed by <Evaluate> and xmd plan | xmd run -; PR #719 remains historical and unchanged.
Focused feedback evidence:
deno task test \
packages/cli/tests/plan-cli.test.ts \
packages/cli/tests/plan-command-document.test.ts \
packages/cli/tests/plan-component.test.ts \
packages/cli/tests/syntax-cli.test.ts \
packages/cli/tests/packaged-document.test.ts
The CLI suite covers every retained and removed option class, exact stdout and
exclusive output, all no-artifact failures, and negative-control non-execution.
After a feedback commit, run deno task test --changed. Delivery proves the npm
binary with scripts/tests/cli-npm-bin.test.ts, the compiled command with
scripts/tests/plan-component-compiled.test.ts after deno task build, and the
required CI checks.
Dependencies
#722 supplies the exact text-producing <Plan> artifact.
#723 makes the prescribed pipe migration executable before --run is
removed.
Out of scope
Story
As a command-line user, I want
xmd planto produce one reviewed XMD programartifact and never execute it, so I can choose explicitly when and where that
program runs.
Common paths
Write the exact approved source to stdout:
xmd plan "Prepare the release program."Compose planning and execution explicitly through standard input:
Or preserve the artifact first and run the saved file later:
--outputremains an exclusive file sink: it creates the requested path onlyafter approval and never replaces an existing file. Without it, stdout contains
only the exact approved program bytes.
One command responsibility
xmd planmaps one instruction string to reviewed and approved XMD source. Ituses the same packaged
<Plan>workflow as an ordinary document and does notstart a second root after authorship.
The packaged plan-command document remains a thin adapter: it supplies the
command surface to
<Plan>, captures the resulting text, and returns thoseexact bytes. The host awaits authorship and teardown, performs the existing
final caller-owned checks, and sends the artifact to exactly one destination.
No approved program effect runs on any success or failure path.
Command grammar
Remove
--runcompletely; it has no alias.--run,--run=true,--run=false, repeated occurrences, and any placement of that spelling receiveone actionable migration refusal before a catalog, Agent, session, review,
output file, journal, or document execution exists:
Retain only arguments that configure planning or artifact disposition:
--includefor the syntax catalog;--agent-providerand--default-agentfor authorship;--sessionfor the planning conversation;--timeoutfor the whole planning invocation;--outputfor the exclusive artifact sink; and--helpand--versionbehavior.Remove options that configured the approved program's former execution:
--props,--props-*, and--no-props-*;--journal/-j;--raw;--verbose/-V;--timeout-execand--timeout-fetch;--approve-all,--approve-reads, and--deny-all;--secret-detectionand--no-secret-detection.Each removed spelling refuses as an
xmd planoption before authorship. Thecorresponding
xmd runoptions remain unchanged. Planning-specific progress anddiagnostic trace work belongs to #676 rather than preserving execution flags
under a new interpretation.
Update command help to say that
xmd plancreates, reviews, and writes approvedXMD source. Help never promises to run it and shows both explicit compositions.
Exact artifact behavior
--outputreceive the same byte-identical source anddigest supplied by
#722.stdout; interactive presentation uses its existing non-stdout channels.
and starts no program.
to execute implicitly.
Acceptance ownership
This story exclusively owns these Quest cases:
a negative-control program effect never occurs.
--runspelling reports the migration above andnever aliases or executes.
The successful stdin pipeline belongs to
#723; this story owns the Planproducer and the diagnostic that points to it.
Documentation and focused evidence
Rewrite
specs/plan-command-spec.mdaround the single source-artifact outcome.Update the command/component inventory and command lifecycle in
architecture.mdandspecs/executable-mdx-spec.md. Update CLI help, README,and the homepage delivered by PR #719 so they show the public model explicitly:
The homepage includes both
<Plan>followed by<Evaluate>andxmd plan | xmd run -; PR #719 remains historical and unchanged.Focused feedback evidence:
deno task test \ packages/cli/tests/plan-cli.test.ts \ packages/cli/tests/plan-command-document.test.ts \ packages/cli/tests/plan-component.test.ts \ packages/cli/tests/syntax-cli.test.ts \ packages/cli/tests/packaged-document.test.tsThe CLI suite covers every retained and removed option class, exact stdout and
exclusive output, all no-artifact failures, and negative-control non-execution.
After a feedback commit, run
deno task test --changed. Delivery proves the npmbinary with
scripts/tests/cli-npm-bin.test.ts, the compiled command withscripts/tests/plan-component-compiled.test.tsafterdeno task build, and therequired CI checks.
Dependencies
#722supplies the exact text-producing<Plan>artifact.#723makes the prescribed pipe migration executable before--runisremoved.
Out of scope
configuring a later run.
xmd planauthorship observable during and after an invocation #676.<Evaluate>, owned by Make<Evaluate>evaluate complete XMD programs #713.