# Pipelex Edit

> Edit an existing MTHDS method bundle (.mthds files). Use when the user says "change this pipe", "update the prompt", "rename this concept", "rename this pipe", "change the model", "tweak the instructions", "modify the method", "add a step", "remove this pipe", "refactor this pipeline", or wants any modification to an existing .mthds bundle. Applies contract-preserving edits directly and routes structural or contract changes to /pipelex-design.

- Skill: `pipelex/pipelex-edit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pipelex/pipelex-edit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pipelex/pipelex-edit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: pipelex (https://skillmd.com/u/pipelex)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pipelex/pipelex-edit

---


# Edit a MTHDS bundle

Modify an existing MTHDS method bundle. There are two classes of change; this skill applies the first and routes the second:

- **Contract-preserving edits** (this skill): prompt and instruction text, `description` and `system_prompt` wording, model references, operator settings, and mechanical renames of pipes, concepts, or input variables. The method's structure — which pipes exist, how they wire, what each one takes and produces — stays the same.
- **Structural or contract changes** (route to `/pipelex-design`): adding, removing, or rewiring steps; changing any pipe's `inputs`/`output` beyond a pure rename; reshaping a concept's structure; refactoring the flow. These propagate — the parent wiring, concept shapes, and contracts all move together — so they are design work: tell the user which pipe(s) the change touches and that `/pipelex-design` re-enters existing methods adaptively (a direct coherent edit for a fully understood shallow region, or signature-driven reopening for nested, uncertain, cross-module, or staged work), and stop. Never attempt a partial structural edit here.

## Requirements — the Pipelex MCP tools

This skill proves every edit with the **`mthds_validate`** tool, served by the plugin's `pipelex` MCP server. It is required — never declare an edit done on the hook's silence alone: the hook's semantic-validation stage is fail-open (it is skipped without an API key), so the MCP verdict is the authoritative check.

- **If the tool is absent from this session** (the MCP server isn't connected), STOP and tell the user in one line: *"The Pipelex MCP server isn't connected — the plugin manifest spawns the local workshop (`npx -y @pipelex/mcp@latest`), so its absence usually means `node`/`npx` is unavailable or the spawn failed. Check the plugin's MCP connection (`/mcp`)."*
- **If a call returns `status: "error"` with an error of class `config`** (missing or rejected `PIPELEX_API_KEY`, unreachable API), STOP the same way and surface the error's `hint` verbatim.
- **`mthds_inputs_template`** is needed only for the inputs-refresh check (Step 6) — when the edit cannot have touched the input template, it goes unused.
- The server authenticates to the API with **`PIPELEX_API_KEY`** from the session environment — the same variable the plugin's validation hook documents.

**Formatting is automatic.** Every write of a `.mthds` file triggers the plugin's validation hook: it lints, rewrites the file in canonical formatting, and blocks on syntax errors. Just write the files — don't hand-format, and re-read a file before editing it again after the hook reformatted it.

## Mode Selection

**Default**: automatic for clear, specific changes; interactive for ambiguous or multi-part modifications.

| Signal | Mode |
|--------|------|
| "Rename X to Y" | automatic |
| "Update the prompt in pipe Z" with new text provided | automatic |
| "Add a step to do X" (open-ended) | structural → route to `/pipelex-design` |
| "Refactor this pipeline" (subjective) | structural → route to `/pipelex-design` |
| Multiple changes requested at once | interactive (confirm the plan first) |

In interactive mode, present the planned edits and ask "Does this plan look right?" before applying. In automatic mode, state the planned edits in one line and proceed.

## Process

### Step 1: Read the bundle

Locate the bundle directory and read **every** `.mthds` file in it (the root — usually `main.mthds` — carries the `domain` header, `description`, and `main_pipe`; module files carry the pipes and concepts). Understand where the change lands before touching anything.

### Step 2: Baseline verdict

Validate the whole bundle **before editing**: call `mthds_validate` with `files` for every file, and branch on the structured verdict, never on transport. Prefer the path form `{path: <absolute path to the file>}` — it keeps the real path as provenance in diagnostics and spares copying whole bundles into the request; the workshop resolves a path against **its own** working directory, so pass an absolute one. Inline `{content: <file content>, uri: <path relative to the bundle dir>}` is the fallback, and the only form the hosted console accepts.

- `is_valid: true` → record whether it is runnable or a scaffold (non-empty `pending_signatures`). That same state must hold after your edits.
- `is_valid: false` → the bundle is broken **before** your change. Surface the `validation_errors[]` and the Markdown summary, and offer to repair first — never edit on a broken baseline, or your regressions and the pre-existing errors become indistinguishable.
- `status: "error"` → no verdict: class `config` → stop per the Requirements above; class `input_domain` → fix the call; class `runtime` → report and retry once.

### Step 3: Classify the change

Check the requested change against the scope split at the top. Structural or contract-changing → route to `/pipelex-design` now, before any files change. Everything else proceeds.

### Step 4: Apply the edits

Use the Edit tool on the affected files. For renames, the edit is only done when **no stale reference remains** — grep the whole bundle for the old code:

- **Rename a pipe**: the `[pipe.<code>]` table header, every step/branch reference in controllers, and `main_pipe` in the root if it names this pipe.
- **Rename a concept**: the concept declaration, every `inputs`/`output` mention, `refines` references, `concept` fields inside structures, and field-reads in prompts (`$var.field` stays keyed to the *variable*, but construct `from` paths and concept-typed fields name the concept).
- **Rename an input variable**: the pipe's `inputs` key and every `$var` / `@var` reference in its prompts. If the variable belongs to the **main pipe**, the client-facing template keys change — Step 6 is mandatory.
- **Update a prompt**: the `$var` / `@var` references are contract, the prose around them is free — every variable referenced must still exist in the pipe's `inputs`.
- **Change a model reference**: the `model` field is optional — omit it to use defaults. See the language reference for accepted forms.

### Step 5: Re-validate

Same whole-bundle `mthds_validate` call as Step 2. The bar is the **baseline verdict restored**: `is_valid: true`, and the runnable/scaffold state unchanged (a renamed pending signature legitimately renames its backlog entry — anything else in the pending set should be untouched). On `is_valid: false`, the failure is in your edit: use the summary's locators, fix, re-validate. If the same construct fails twice, pause and show the user instead of thrashing. On `status: "error"` (no verdict — e.g. the MCP connection dropped after the write), the edit is applied but **unproven** — never report it as done: tell the user it is on disk but could not be validated, and offer to restore the pre-edit content you still hold from Step 1 or to retry validation once the server is reachable again.

### Step 6: Inputs refresh check

When the edit could have changed the input template — a renamed main-pipe input variable, a renamed boundary concept — re-project it: call `mthds_inputs_template` with the whole-bundle `files` submission plus `explicit: false`, so the fresh template arrives in the same light shape `/pipelex-inputs` writes into `inputs.json` (the tool's own default is the ceremonial `{concept, content}` envelope). If an `inputs.json` exists next to the bundle, compare its keys with the fresh template: pure key renames may be applied in place; anything beyond that goes to `/pipelex-inputs`. No `inputs.json`, or an edit that cannot touch the template → skip this step.

### Step 7: Report

State what changed (files and constructs), give the verdict line from the summary, and where the host renders MCP views, point to the method graph that accompanied the valid verdict. If inputs were refreshed or invalidated, say so. Suggest `/pipelex-inputs` when the user wants to prepare inputs or run the method.

## Reference

- [MTHDS Language Reference](../shared/mthds-reference.md) — read for concept definitions and syntax before editing constructs you haven't touched recently
- [Native Content Types](../shared/native-content-types.md) — read when editing prompts or construct paths that field-read native concepts (`Image.url`, `Page.text_and_images`, ...)