# Workflows A context-based workflow is a module with a fixed shape. Every workflow lives in `modules/` as a module, but not every module is a workflow: a module is any folder of files that holds accumulated knowledge on a topic; a workflow is a module that follows the specific structure defined here (frontmatter manifest, steps/, runs/). It is a series of steps the agent executes with judgment, where every run leaves a persistent trace on disk. The workflow remembers what happened last run, accumulates knowledge, and gets better over time. A skill or prompt runs and forgets; a workflow holds state. This document is the template spec: the contract a workflow folder must follow to be distributable. The CLI (`gcontext add`), the site directory, and the authoring tooling all build against it. It is one standard for all workflows; there are no per-domain variants. ## Folder anatomy ``` / index.md # required: frontmatter manifest + objective, parameters, context steps/ # required: the procedure index.md # map: one line per step 0-preflight.md # numbered step files, executed in order 1-init.md ... commands/ # required: entry points setup.md # required: the install interview (see setup contract) 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) from-x.md from-y.md runs/ # one folder per run example/ # ships with the template: a fabricated run (see example run) 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 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 The manifest is YAML frontmatter at the top of the workflow's `index.md`. There is no separate manifest file, and no version field: installs are snapshots, and a version mechanism comes only when updates exist. ```yaml --- id: coolify-ops # unique, url-safe slug; the argument to `gcontext add` # and the site path /workflows/ name: Coolify Ops # human display name, shown in the directory description: > # one or two sentences; the directory card text Mirror of a Coolify instance with operational playbooks that accumulate as incidents are resolved. parameters: # what a run starts with; bound at setup or per run - name: instance-url description: Base URL of the instance to operate required: true - name: scope description: Limit operations to one project required: false connections: # service capabilities the workflow needs - kind: http-api # generic kind, not a product name description: The hosting panel API (Coolify, Dokploy, or similar) tags: [ops, infrastructure] # directory filtering --- ``` Field notes: - `id` is the identity everywhere: the install argument, the folder name, the site slug. Lowercase letters, digits, hyphens. - `name` is the display name for the directory and the workflow page; the id stays the machine identity. - `parameters` are slots, not values. The setup interview or the run start binds them. Never ship bound values. - `connections` entries are structured (`kind` plus `description`) so the site can render them as requirement badges. They name capability kinds, not products. The body of `index.md` may mention concrete services as examples; the steps must not depend on one (see docs/modules.md on connection-agnostic modules). The agent maps kinds to its own `connections/` at run time. - `tags` is a flat list for the directory. Keep it short. After the frontmatter, the body of `index.md` carries: the objective in the first paragraph, what each parameter means in practice, the workflow's run naming scheme (see runs/), and the general context the agent needs across all steps. Context specific to one step belongs in that step's file. ## steps/ `steps/index.md` is the map: one line per step, in order. Each step is one numbered file (`0-preflight.md`, `1-init.md`, ...). Number from 0 when there is a gate or check before real work starts. Each step file states: - **Purpose**: what this step achieves and why it exists. - **Input**: what it needs, and from where (parameters, a previous step's results file, a connection). - **Output**: what it writes into the run folder, with the schema when the output is tabular (column list for a CSV, field list for JSON). - **How to execute**: the procedure, in enough detail that an agent without prior context can do it. Include known blockers and how to classify or route them. - **Done when**: the condition that closes the step. Steps that pause for the user (approval, manual action, batching) say so explicitly: what to present, what to wait for. ## runs/ Every execution of the workflow is one folder in `runs/`. **The run folder name is workflow-defined.** Each workflow states its own run naming scheme in its `index.md`: whatever identifies one run in that domain. A gym migration names runs by gym id, an invoicing workflow by plant and period, a research pipeline by batch name. The ISO date (`2026-08-07`; second run the same day `2026-08-07-b`) is only the default for workflows with no better key. The run name should carry meaning; the date is the fallback. Inside a run folder: ``` runs// index.md # map and status: scope of the run, per-step status table 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. - 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. ## functions/ (optional) Some steps do the same transformation from ever-varying inputs. `functions/` is a mini library the agent picks from, organized per step: `functions//index.md` describes the cases (the switch), one file per case describes the procedure or code for it. The step file points to its functions folder. Add `functions/` only when a step has proven to need it; most workflows ship without it. ## What ships vs what is generated A workflow is distributed as a template. The template is the procedure plus one fabricated demonstration; the state is born empty on the user's machine. Ships in the template: - `index.md` with the frontmatter manifest - `steps/` - `commands/setup.md` and `commands/run.md` - `functions/` when the workflow has them - `runs/example/`: the example run Never ships, generated locally at setup and use: - the user's own run folders in `runs/` - every personalized file: configs, credentials references, scripts bound to the user's systems, playbooks learned from the user's own work Installs are snapshots. The user's copy is theirs: personalized, growing, never overwritten by an update. `gcontext add` on an existing module warns and stops instead of overwriting. ## The example run Every template ships one fabricated run at `runs/example/`, in the exact `runs/` shape: `index.md`, `0-parameters.*`, one folder per step with plausible results, `done/info.md`. All names and data in it are fake, made up by the author; it must contain nothing personal. The example run has two jobs: - On the site, it is the centerpiece of the workflow's page: the visitor browses it file by file and sees exactly what each step produces before installing anything. - In the installed folder, it is the reference: the agent reads it to see what a correct run looks like before executing its first real one. The folder name `example` (instead of a run key) is what marks it fabricated. The setup command leaves it in place. ## The setup command contract `commands/setup.md` is the bridge from template to personal instance. It is an interview: the agent asks, the user answers in plain words, the agent builds and confirms. The contract: 1. **Read first**: the command starts by instructing the agent to read the workflow's `index.md` and `steps/index.md` so the interview is informed. 2. **Bind every parameter slot**: ask for each manifest parameter that is bound at setup time (per-run parameters are only explained, not bound). 3. **Map connections**: for each `connections` entry, find a matching service in the agent's environment or help the user create one. In gcontext that means `connections/`; standalone it means whatever access the user's agent has. 4. **Generate the personal state**: create the files this workflow needs locally (config, scripts against the user's systems, an empty runs/ besides the example). What gets generated is listed in the setup command itself. 5. **Smoke test**: verify the critical path (a read against the user's system, a dry run of the first step) before declaring setup done. 6. **Never rewrite the procedure**: setup personalizes state; it does not edit `steps/`. 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. ## Relation to modules A workflow is a module (see docs/modules.md): installed into `modules/`, connection-agnostic, growing with use. The workflow spec adds the fixed shape on top: manifest frontmatter, `steps/`, `runs/`, the setup contract, the example run. Everything modules.md says about growth and portability applies unchanged.