Make run command required in workflow spec, update share-workflow

Every workflow must ship commands/run.md that drives step-by-step
execution and enforces the per-step folder structure in runs/. The
run command contract is added to the spec. share-workflow updated
to generate run.md during authoring and verify it at phase 5.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/share-workflow.md

@@ -42,6 +42,7 @@ Create the template folder next to the source module (for example `<workflow-id>
 - **`steps/`**: the same files as the source, with the classified specifics replaced by parameter references and generic capability wording. Keep the structure untouched: the shapes were proven by use; you strip, you do not redesign. Every step file must state Purpose, Input, Output (with schema when tabular), How to execute, and Done when; if a source step lacks one of these, derive it from what the lived runs show and confirm with the author.
 - **`functions/`**: same treatment, only if the source has it.
 - **`commands/setup.md`**: generate it from the slots, following the setup contract in the spec: read index.md and steps/index.md first; bind every setup-time parameter; map each connection requirement to a real service in the user's environment; generate the personal state (list in the command exactly what it creates); smoke-test the critical path; never edit steps/. Give it command frontmatter (`description`, optional `parameters`) and a self-contained prose body that assumes only file access, so it works in gcontext as an MCP prompt and standalone in any agent.
+- **`commands/run.md`**: generate the run driver, following the run command contract in the spec. It must: read the workflow's index.md and steps/index.md, collect per-run parameters, create the run folder with index.md and 0-parameters.*, execute each step in order writing output into per-step folders (e.g. `1-collect/results.md`), update the run's index.md after each step, and close the run with `done/info.md`. Give it command frontmatter (`description`, optional `parameters`) and a self-contained prose body.
 
 ## Phase 4: fabricate the example run
 
@@ -55,7 +56,7 @@ Build `runs/example/` inside the template, in the exact runs/ shape: `index.md`
 
 Run three checks and show the results:
 
-1. **Spec compliance**: every required file exists (index.md with parseable frontmatter carrying all fields, steps/ with index and numbered files, commands/setup.md, runs/example/ complete with done/); every step states Purpose, Input, Output, How, Done when.
+1. **Spec compliance**: every required file exists (index.md with parseable frontmatter carrying all fields, steps/ with index and numbered files, commands/setup.md, commands/run.md, runs/example/ complete with per-step folders and done/); every step states Purpose, Input, Output, How, Done when.
 2. **Leak scan**: search the entire template, example run included, for every author-specific string collected in phase 2, plus generic patterns: email addresses, things shaped like API keys or tokens, the author's domains. Present every hit. The template passes only with zero unexplained hits.
 3. **Cold read**: in a fresh context (a subagent or a new session) that sees only the template folder, have the agent explain back what the workflow does, what it needs, and what a run produces. If the explanation is wrong or incomplete, the template is not self-contained; fix and repeat.
 

docs/workflows.md

@@ -16,7 +16,7 @@ This document is the template spec: the contract a workflow folder must follow t
     ...
   commands/           # required: entry points
     setup.md          #   required: the install interview (see setup contract)
-    start-workflow.md #   optional: the run driver, added when it earns its place
+    run.md            #   required: the run driver (see run command contract)
   functions/          # optional: per-step helper library
     2-transform/
       index.md        #   which helper applies to which case (the switch)
@@ -27,7 +27,7 @@ This document is the template spec: the contract a workflow folder must follow t
     2026-08-07/       #   the user's own runs, generated locally, never shared
 ```
 
-The only code-enforced requirement is `index.md` with valid frontmatter. Everything else is convention: step files state what they need from previous steps in prose; nothing checks it mechanically. The process is AI-driven, so requirements live in the text the agent reads, not in validation code.
+The only code-enforced requirement is `index.md` with valid frontmatter. Everything else is convention enforced by the run command: step files state what they need from previous steps in prose, and the run command drives execution through them in order, writing results into per-step folders inside the run. The process is AI-driven, so requirements live in the text the agent reads, not in validation code.
 
 ## Manifest: frontmatter in index.md
 
@@ -90,21 +90,22 @@ Inside a run folder:
 ```
 runs/<run-key>/
   index.md           # map and status: scope of the run, per-step status table
-  0-parameters.csv   # the parameters this run started with (.csv, .json, or .md)
+  0-parameters.md    # the parameters this run started with (.csv, .json, or .md)
-  1-init/
+  1-init/            # one folder per executed step, named like the step file
-    results.csv      # the step's output, schema per the step file
+    results.md       #   the step's output, schema per the step file
-    script.py        # optional: a generated script saved to avoid regenerating it
+    script.py        #   optional: a generated script saved to avoid regenerating it
   2-transform/
     results.json
   done/
     info.md          # written when the run closes: what was achieved, what was learned
 ```
 
+**This structure is mandatory, not a suggestion.** The run command creates it; agents must not flatten results into a single file. Every executed step gets its own folder inside the run, named like the step file without the extension (e.g. step `1-collect.md` writes to `1-collect/`). The folder's main artifact is `results.*`. When the agent generates code worth keeping, it saves the script next to the results.
+
 Conventions:
 
 - `0-parameters.*` records what the run started with, always, even when trivial. It is what makes a run reproducible and auditable.
-- One folder per executed step, named like the step file without the extension. Its main artifact is `results.*`. When the agent generated code worth keeping, it saves the script next to the results.
+- The run's `index.md` is the resume point: a session picking up a half-finished run reads it and continues from the first step that is not done. The run command updates it after each step.
-- The run's `index.md` is the resume point: a session picking up a half-finished run reads it and continues from the first step that is not done.
 - `done/` closes the run: `info.md` summarizes what was achieved and anything learned that should change the steps, plus any final deliverable files. A run without `done/` is open.
 - Learnings that outlive the run (a new blocker type, a better procedure) get folded back into the step files or `functions/`. That is how the workflow improves with use.
 
@@ -120,7 +121,7 @@ Ships in the template:
 
 - `index.md` with the frontmatter manifest
 - `steps/`
-- `commands/setup.md` (and any other generic commands)
+- `commands/setup.md` and `commands/run.md`
 - `functions/` when the workflow has them
 - `runs/example/`: the example run
 
@@ -158,6 +159,20 @@ The same file must work on both install paths:
 - **In gcontext**: `commands/setup.md` carries the standard command frontmatter (`description`, optional `parameters`), so the server exposes it as an MCP prompt and the user runs it as a slash command.
 - **Standalone**: the user downloads the plain folder, opens any agent in it, and says "run the setup in commands/setup.md". The agent reads the file and executes the same interview. Therefore the body must be self-contained prose that assumes only file access, not gcontext tools.
 
+## The run command contract
+
+`commands/run.md` is the entry point for every execution. It drives the agent through the steps in order and enforces the per-step folder structure in the run. The contract:
+
+1. **Read first**: read the workflow's `index.md`, `steps/index.md`, and `runs/example/` to understand the procedure and what correct output looks like.
+2. **Collect parameters**: ask for any per-run parameters declared in the manifest. Write them to `0-parameters.*` in the run folder.
+3. **Create the run folder**: name it per the workflow's run naming scheme (stated in `index.md`). Create `index.md` with the run scope and a per-step status table, all steps marked pending.
+4. **Execute each step in order**: read the step file, execute it, write the output into a folder named like the step file without the extension (e.g. `1-collect/results.md`). Update the run's `index.md` status table after each step.
+5. **Close the run**: when all steps are done, create `done/info.md` with a summary of what was achieved and anything learned. Update the run's `index.md` to mark the run as done.
+
+The run command never skips the folder structure. A step that produces no file still gets its folder with a brief `results.md` noting "no output" and why. The run folder is the audit trail; a flat file or a single summary defeats its purpose.
+
+The same file must work on both paths (gcontext MCP prompt and standalone agent), just like the setup command.
+
 ## Sharing a workflow
 
 Authors turn a lived workflow into a template with the share-workflow instructions: docs/share-workflow.md. It strips the personal specifics into parameter slots and connection requirements, generates the setup command, fabricates the example run, and verifies the result against this spec.