From 9128beebd8ce6ea6816df2137efa77a1cc91a5d9 Mon Sep 17 00:00:00 2001 From: bernatsampera Date: Mon, 10 Aug 2026 12:10:57 +0200 Subject: [PATCH] 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) --- docs/share-workflow.md | 3 ++- docs/workflows.md | 33 ++++++++++++++++++++++++--------- 2 files changed, 26 insertions(+), 10 deletions(-) diff --git a/docs/share-workflow.md b/docs/share-workflow.md index 0ecbae2..e223afb 100644 --- a/docs/share-workflow.md +++ b/docs/share-workflow.md @@ -42,6 +42,7 @@ Create the template folder next to the source module (for example ` - **`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. diff --git a/docs/workflows.md b/docs/workflows.md index c93b569..6f8c4bc 100644 --- a/docs/workflows.md +++ b/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// 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) - 1-init/ - results.csv # the step's output, schema per the step file - script.py # optional: a generated script saved to avoid regenerating it + 0-parameters.md # the parameters this run started with (.csv, .json, or .md) + 1-init/ # one folder per executed step, named like 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 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'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. - `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.