gcontext/docs/share-workflow.md

share-workflow

Instructions for an AI agent that turns a private, lived workflow into a marketplace template. You are the agent; the human in the conversation is the author. The input is their workflow module, personal state included. The output is a template folder that follows the workflow template standard (docs/workflows.md) and contains zero personal data.

Work through the phases in order. Propose, let the author confirm, then act. Do not skip a phase.

Phase 0: load

1. Ask the author which workflow module to share, if not already stated. Read it completely: index.md, steps/, functions/ and commands/ if present, and the run folders in runs/.
2. Read the template spec (docs/workflows.md, or fetch it from the gcontext repo if it is not in reach). Do not work from memory of the spec; the spec is the contract the output must pass.

Phase 1: eligibility

Check the workflow against the five tests for shareable workflows and report the result per test:

1. Procedure generic, state personal. The steps contain a loop that is not tied to the author's life; the personal content sits in state files that can start empty for someone else.
2. The AI is needed every run. Each run requires interpretation and judgment. If a cron job or a static script could do it, it is not a workflow.
3. The state feeds judgment. Later runs read the accumulated state to act better. Knowledge qualifies; telemetry nobody consults does not.
4. Lived first. At least one real, completed run exists in runs/. The shapes must have been discovered by use, not designed on paper.
5. Low trust barrier. Few parameter slots, few secrets. Every credential a stranger must grant raises the install cost.

If any test fails, tell the author which and why, and continue only after their explicit confirmation. The marketplace is open; you warn, the author decides.

Phase 2: extract the slots

Walk index.md, every file in steps/, and functions/ if present. Collect every author-specific element: personal and company names, domains, URLs, account identifiers, email addresses, concrete product names, file paths outside the module, and data values from the author's own work.

Classify each element as exactly one of:

• (a) Parameter slot: a value a new user supplies at setup or per run. Becomes a parameters entry in the manifest.
• (b) Connection requirement: a service capability the workflow needs. Becomes a structured connections entry (kind + description), described generically ("the hosting panel API", not "Coolify").
• (c) Personal state: files or content that must not ship (playbooks learned from the author's systems, configs, credentials references, logs). Excluded from the template; the setup command will regenerate the empty shapes.
• (d) Generic rewrite: a concrete-service mention inside a step that stays in the text but must be reworded to the capability kind.

Present the full classification as one list and get the author's confirmation before rewriting anything. This is the author's main control point; the leak scan in phase 5 is the second net.

Phase 3: generate the template

Create the template folder next to the source module (for example <workflow-id>-template/). Build:

• index.md: the frontmatter manifest per the spec: id (url-safe slug), name, description, parameters (name, description, required), connections (kind, description), tags. Then the body, rewritten clean: the objective in the first paragraph, what each parameter means in practice, the workflow's run naming scheme, and the general cross-step context.
• 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.

Phase 4: fabricate the example run

Build runs/example/ inside the template, in the exact runs/ shape: index.md (map and status), 0-parameters.*, one folder per step with results, done/info.md.

• Default: start from the author's most representative real run and replace every real value with a coherent fake: invented names, plausible numbers, same schemas, same story arc.
• Fallback: if the author's runs are too sensitive to anonymize confidently, fabricate the example fully from the step definitions. Say so to the author.
• Keep the fake data internally consistent: the same invented name must flow through all steps, so a site visitor can follow one item from parameters to done. This example is what the marketplace renders on the workflow's page; it is the template's sales pitch.

Phase 5: verify

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.
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.

Phase 6: hand off

The finished template is a local folder. Submission: the marketplace accepts templates through its API with a review step (submitted entries stay pending until approved). If the submission endpoint is not yet available, tell the author the template is ready and where it lives, and stop there.

Never submit without the author's explicit go-ahead, and never include the source module or any personal state in what is submitted.