# Pipelex Design > Design a MTHDS method bundle top-down with a construction workflow matched to its complexity — build a fully understood shallow graph directly as a coherent runnable bundle, or use validated signature-driven stepwise refinement for deep, uncertain, staged, or resumable work. Re-enters existing methods with the same adaptive choice for structural and contract changes. - Skill: `pipelex/pipelex-design-2` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add pipelex/pipelex-design-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/pipelex/pipelex-design-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: pipelex (https://skillmd.com/u/pipelex) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/pipelex/pipelex-design-2 --- # Design a MTHDS bundle top-down at the right depth Design a `.mthds` method **contract-first**, then use the lightest construction workflow that preserves confidence. A fully understood shallow graph is written directly as a coherent runnable bundle. A deep, uncertain, intentionally staged, or resumable graph is developed through `PipeSignature` checkpoints and stepwise refinement. Both modes fix the client contract before implementation, preserve the same concept-shape and wiring rules, validate through the Pipelex MCP tools, and finish at the same runnable verdict. ## Scope (what this skill can emit) - Bundle headers: `domain`, `description`, `main_pipe`, `system_prompt`. - Concepts: simple, refining, structured (field types `text`, `integer`, `boolean`, `number`, `date`, `concept`, `list`). - Pipes: `PipeSignature` (contract-only header), `PipeLLM`, `PipeCompose`, `PipeSequence`, `PipeBatch`, `PipeParallel`, `PipeCondition`, `PipeExtract`, `PipeSearch`, `PipeImgGen`, `PipeFunc`. **Outside this skill's scope:** `dict` field types, `PipeStructure`, inline `templating_style` blocks, and other advanced features. When the user asks for those, write the closest in-scope equivalent and call out the deviation; do not silently emit unsupported constructs. --- ## How it works — read this first - **The artifact is a library, not necessarily one file.** A directory of same-domain `.mthds` files is validated as one submission. The runtime merges them into one domain; pipes and concepts reference each other across files by bare code. A direct design normally has one coherent `main.mthds`; a larger result may have natural module files. - **Top-down reasoning does not require signatures.** In both modes, determine the root inputs, output, semantics, full boundary concept shapes, graph, wiring, and concept ownership before materializing the construction artifacts that are justified. - **Direct mode writes the complete graph.** It contains concrete pipes only, declares each concept once, and is validated after the coherent write. It never creates temporary signatures or construction-only definition files. - **Stepwise mode materializes uncertainty.** Every not-yet-designed pipe is a reachable `PipeSignature`. Each refinement adds one concrete definition file, may introduce child signatures, and is validated immediately. The pending-signature verdict is the resumable backlog. - **Completed means runnable in either mode.** Delivery requires `is_valid: true`, `is_runnable: true`, and no `pending_signatures`. See [writing-mthds.md](references/writing-mthds.md) for the supported syntax, operator/controller rules, `PipeSignature`, `signature_for`, and all pipe-type fields. It is the syntax source of truth. --- ## Requirements — the Pipelex MCP tools This skill validates through the **`mthds_validate`** tool and projects input schemas through the **`mthds_inputs_template`** tool, both served by the plugin's `pipelex` MCP server. They are required — this skill never guesses at validity. - **If the tools are 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 — on Mistral Vibe the local workshop (`npx -y @pipelex/mcp@latest`) is not auto-spawned: register it in Vibe's MCP configuration with `PIPELEX_API_KEY` in its environment, then retry."* Do not write `.mthds` files without validation available. - **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. Never silently skip validation. - The server authenticates to the validation API with **`PIPELEX_API_KEY`** from the session environment — the same variable the plugin's validation hook documents. > **No backend setup needed**: designing and validating never run the method, so no inference backends are required. **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. ### How to validate 1. Gather **all** `.mthds` files in the bundle directory (the whole library — a broken sibling fails the verdict too, and the report names it). 2. Call `mthds_validate` with `files` for every file. Prefer the path form `{path: }` — 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: , uri: }` is the fallback, and the only form the hosted console accepts. 3. Branch on the **structured verdict**, never on transport: - `status: "ok"`, `is_valid: true`, `pending_signatures` non-empty → valid stepwise design scaffold, not yet runnable. The Markdown summary's `## Pending signatures` section is the backlog. - `status: "ok"`, `is_valid: true`, `is_runnable: true`, `pending_signatures` empty → the method is complete and runnable. - `status: "ok"`, `is_valid: false` → a produced failure verdict: read `validation_errors[]` and the Markdown summary (it carries locators and names the offending file), fix, re-validate. - `status: "error"` → no verdict was produced: class `input_domain` means the submission is malformed (fix the call); class `config` → stop per the rule above; class `runtime` → report it and retry once before stopping. The Markdown summary in the tool's text output is written for you — read the verdict line and any backlog from it directly. Where the host renders MCP views (e.g. claude.ai), an interactive method graph accompanies valid verdicts (`available_view_specs: ["dry_run_graph"]`); in terminal hosts there is no visible graph — the summary is the review surface. --- ## Before writing — capture the contract and choose the workflow Read [writing-mthds.md](references/writing-mthds.md) **before writing**. Determine the three things that are the client requirement: - **Input concept(s)** — what the client provides. - **Output concept** — what the client gets back. - **Description** — the semantics, in prose precise enough to implement against. Specify every boundary concept fully now. Decide whether each boundary and intermediate concept is simple or structured from all known consumers: if any consumer field-reads it (`$x.field`, or a construct `from = "x.field"`), it must be structured; if every consumer uses it whole (`@x` or wholesale mapping), it can stay simple. Declare each concept exactly once, owned by the root boundary or by the controller that introduces the intermediate value. **Announce the captured contract in one line** (inputs → output, one-sentence semantics) before writing, so the user can interject without blocking progress. Infer the construction mode automatically; do not ask the user to choose a strategy. ### Choose direct construction only when all boundaries are resolved Use direct construction when the complete graph can be authored without placeholders or speculative contracts. Observable signals: - the graph is one concrete operator; or one top-level controller whose children are concrete leaf operators; - no child is itself a controller, unless the entire nested graph and every contract is already fixed and a direct coherent layout is still clearly safer; - every branch, iteration, input mapping, output mapping, and intermediate owner is decided before writing; - every boundary and intermediate concept shape can be fixed from its consumers; - every pipe can be concrete in the first coherent artifact. One controller is a strong fast-path signal, not a rule. Pipe count is secondary: a controller with cross-branch concept dependencies, uncertain ownership, or unresolved child contracts belongs in stepwise mode even if it is the only controller. ### Choose signature-driven stepwise refinement when it buys confidence Use stepwise refinement when any useful boundary remains unresolved or a resumable scaffold is part of the request. Observable signals: - nested controllers or multiple structural layers whose child contracts are not all fixed; - uncertain sub-pipe contracts, intermediate concept ownership, branching, iteration, or wiring; - shared concepts whose shapes depend on consumers in different branches; - a large graph that benefits from independently valid review checkpoints; - an explicit request for a scaffold, partial design, staged work, or a resumable intermediate result. If classification is borderline, use the simplest path that can be written **completely** and validated confidently. The moment direct design would need a placeholder or guessed contract, switch to the stepwise workflow. --- ## Direct construction — complete shallow graph ### Step D1 — Design the coherent artifact before writing Design in memory: - bundle `domain`, `description`, `main_pipe`, and optional `system_prompt`; - fully specified boundary and intermediate concepts; - the concrete main operator/controller and every concrete leaf; - all controller steps, branches, mappings, and ownership. The normal target is `pipelex-wip//main.mthds`, containing the metadata, boundary concepts, intermediate concepts, concrete main pipe, and concrete leaves in top-down reading order. Use more than one file only when the graph already has a natural coherent module boundary; never create one file per pipe merely to mimic refinement history. Include **no temporary `PipeSignature` declarations**. ### Step D2 — Write once as a coherent runnable candidate Create the bundle directory and write the complete candidate file set. Because the graph was designed together, concept codes are checked library-wide before the write, each concept shape is final, and every concrete pipe carries explicit `inputs` and `output`. Validate the whole bundle. Fix ordinary syntax, contract, or semantic errors in the coherent files and re-validate. The direct path is complete only when the common runnable gate passes. ### Step D3 — Graduate cleanly if hidden complexity appears If writing or validation exposes an unresolved structural boundary, stop extending the direct draft and transition to stepwise refinement: 1. Keep the announced root contract and boundary concept shapes stable unless the evidence shows the client requirement itself was wrong. 2. Compose the replacement scaffold in memory. Its root keeps bundle metadata and boundary concepts, replaces the main concrete graph with one root `PipeSignature`, and removes abandoned direct-only intermediate concepts and concrete child definitions that the refinement files will own. 3. Replace the candidate file set as one consistent layout. Do **not** append signatures beside the abandoned concrete definitions. Re-gather the directory and confirm every pipe/concept code is declared only where the stepwise model permits it: one root header, then one later concrete per pending code; each concept exactly once. 4. Validate the root scaffold before adding definitions. It must be valid with the root pipe in `pending_signatures`; then continue at Step S2. This replacement is the construction-mode transition, not an additive refinement. Keeping both drafts would create duplicate concepts, conflicting concrete pipes, or falsely satisfied signatures. --- ## Signature-driven construction — validated stepwise refinement This mode preserves the additive, breadth-first construction loop and valid intermediate checkpoints. ### Step S1 — Write and validate the root scaffold Write `pipelex-wip//main.mthds` (unless the user asks for another root name) with: - `domain`, `description`, `main_pipe`, optional `system_prompt`; - the fully specified boundary concepts; - the top pipe as one `PipeSignature` whose code is `main_pipe`, with its precise `description`, explicit `inputs`, `output`, and `signature_for`. The root is written once for this construction mode. Validate it: the one-signature library must pass with the top pipe listed as pending. An explicit partial-scaffold request may stop after any later valid checkpoint, but never before this first passing verdict. ### Step S2 — Refine layer by layer Drain the signature backlog breadth-first, **serially** (one signature at a time — no parallel workers in this version): 1. Validate and read `pending_signatures[]` (the summary's `## Pending signatures` list). This verdict is the bundle's own todo list. 2. Expand each current pending signature one at a time. Every expansion adds exactly one new `.mthds` definition file and never edits an existing construction file. 3. Re-validate after each expansion, recompute the backlog, and repeat until it is empty. #### Expand one signature Given pending signature `S` with frozen `inputs`, `output`, `description`, and `signature_for`: 1. Decide operator or controller. A single cognitive/IO step is an operator; multiple steps, iteration, branching, or parallelism require a controller. 2. Add `.mthds`, using `S`'s **bare** pipe code. The verdict names signatures as `domain.code`, but a namespaced `[pipe.domain.code]` would define a different pipe and never satisfy the header. A non-root file carries only `domain = ""` for membership. If the code is literally `main`, use a non-colliding filename such as `main_pipe.mthds`; filenames do not define pipe identity. 3. For a leaf, write the concrete operator (`PipeLLM`, `PipeExtract`, `PipeSearch`, `PipeImgGen`, `PipeCompose`, `PipeFunc`) with all type-specific fields. For a controller (`PipeSequence`, `PipeBatch`, `PipeParallel`, `PipeCondition`), wire one structural level, declare only intermediate concepts not already owned by the assembled library, and forward-declare every not-yet-designed child as a new `PipeSignature` in the same file. During re-entry, a reshaped concept may already be retained in the scaffold/common owner so signatures can validate; reference it from the new definition instead of redeclaring it. 4. Repeat `S`'s explicit `inputs` and `output` on the concrete definition. Contracts reconcile by concept identity (bare/qualified spellings and native equivalents), not textual coincidence. 5. Before introducing an intermediate concept, check its code across the assembled library. Derive a unique parent-based code if needed. Declare it once, in the controller that logically introduces it or in the re-entry scaffold that must freeze its changed contract, with a shape fixed from every wired consumer. If consumers in different branches field-read it, the common parent owns and structures it. Never duplicate a concept already retained by a direct→stepwise transition or signature-driven re-entry. #### If validation fails after an expansion The new file bounds the ordinary fix: - **Contract mismatch:** conform the definition to the frozen header. If the header itself is wrong, that is a propagating contract change; pause and revise the parent region deliberately rather than silently changing the header. - **Other semantic errors:** use `validation_errors[]`, the Markdown locators, and the relevant `writing-mthds.md` section; fix the added file and re-validate. ### Step S3 — Early-stop scaffold Early stopping exists only in stepwise mode. When the user requested a partial scaffold or interrupts before convergence, confirm `is_valid: true`, report the exact pending-signature backlog, and explain that resuming means expanding those signatures. Do not claim it is runnable and do not auto-organize it; offer `/pipelex-organize` only if the user wants the valid scaffold regrouped. --- ## Common runnable gate and delivery For a completed method, re-gather the whole bundle and confirm **`is_valid: true`, `is_runnable: true`, and an empty `pending_signatures`**. There is no separate strict-validation call; this structured verdict is the runnable gate. Fix whole-bundle semantic errors and re-validate until it passes. After the gate: 1. **Organize only when the layout needs it.** A direct result that is already coherent skips `/pipelex-organize`. A converged stepwise result normally invokes it automatically because one-definition-per-file construction history and satisfied headers need regrouping. A naturally coherent result in either mode does not take an organization round trip solely for process compliance. 2. **Project the input schema.** Call `mthds_inputs_template` with the final whole-bundle `files` submission plus `explicit: false`. Show the returned compact template, but **do not save it as `inputs.json`** — input preparation belongs exclusively to `/pipelex-inputs`. 3. **Present the flow.** Point to the interactive method graph where the host rendered the valid verdict's view; in terminal hosts, present a concise text flow of the final structure. 4. **Hand off inputs.** Suggest preparing real inputs with `/pipelex-inputs`. > **NEVER write `inputs.json` manually.** If the user provides files, paths, or wants to run with real data, invoke `/pipelex-inputs` — it handles the template, path resolution, placeholder formatting, and file copying. --- ## Editing an existing method (adaptive re-entry) Structural changes to an existing method — adding, removing, or rewiring steps; changing a pipe contract; reshaping a concept — are design work (contract-preserving tweaks belong to `/pipelex-edit`, which routes structural requests here). 1. **Baseline before every edit.** Read every `.mthds` file and validate the whole bundle. Record whether it is runnable or a scaffold and its exact pending set. If it is invalid, repair the baseline first; never redesign on a broken baseline. Retain the original contents until the final verdict is restored. 2. **Map the full affected region.** - A pipe contract change includes every parent controller whose wiring must adapt. - A main-pipe contract change includes root boundary concepts and invalidates any saved `inputs.json`. - A concept reshape includes its introducing declaration and every consumer that field-reads it. 3. **Choose the re-entry mode from the affected graph, not the whole method's size.** - **Direct coherent edit:** when the affected region is shallow and its complete graph, propagated contracts, mappings, ownership, and concept shapes can be understood together, edit the smallest coherent region directly. Validate the whole bundle after the coherent edit and restore the baseline runnable/scaffold state. - **Signature-driven re-entry:** when the affected region is nested, uncertain, cross-module, cross-branch, or intentionally staged, reopen the smallest sufficient region to signatures. Internals-only changes may replace one concrete with a same-contract signature; contract changes reopen the child and sufficient parent wiring; concept reshapes reopen the declaration and every field-reading consumer. 4. **Build a reachable re-entry scaffold atomically.** - Keep or coherently edit the smallest unaffected concrete ancestor whose wiring reaches the affected region; it is the scaffold anchor. - Replace only the directly affected concrete children reachable from that anchor with signatures, and remove their old concrete definitions before validating. A signature left beside its old concrete is already satisfied and is not a backlog item. - Reshape or declare each changed concept exactly once in the scaffold at its common logical owner, so the new signatures' contracts resolve. Later refinements reference that declaration; they do not redeclare it. - Do not predeclare deeper descendants while their parent is only a signature. Introduce those child signatures when that parent receives its concrete controller definition, keeping every pending signature reachable. - Validate the atomic scaffold, then drain its structured backlog with Step S2. 5. **Recover rather than leave an unproven edit.** If a post-edit call returns no verdict, or the edited region cannot be made valid after two focused fixes, restore the retained baseline contents and report the failure. 6. **Converge and deliver.** Restore at least the baseline verdict. Run `/pipelex-organize` only if signature-driven re-entry produced a construction-shaped layout that needs regrouping. Re-project the input template; if `inputs.json` exists and the client surface changed, flag the drift and hand the refresh to `/pipelex-inputs`. --- ## Invariants & rules ### Both modes - **Contract stability.** A definition preserves the contract its parent relies on, matched by concept identity. An intentional contract change propagates through every affected parent mapping before delivery. - **Client contract first.** The root inputs, output, semantics, and boundary concept shapes are fixed before implementation artifacts are written. - **One concept declaration, complete shape.** A concept is declared exactly once. Its structure is fixed from every field-reading consumer; it is never "completed" by a duplicate later declaration. - **Whole-bundle proof.** Every claimed checkpoint or completion state comes from `mthds_validate` over all bundle files. Completed always means valid, runnable, and no pending signatures. ### Stepwise mode only - **Additive refinement.** After the root scaffold (or a deliberate re-entry reopening), every refinement adds one concrete definition file; existing construction files and satisfied headers persist until organization. - **One concrete definition per refinement file.** This keeps failures bounded and checkpoints resumable. - **Backlog = `{signatures} − {concretes}`.** Recompute it from the structured verdict after every expansion; never hand-track it. - **The root file is written once during new stepwise construction.** Direct construction and coherent direct re-entry are not subject to this construction-history rule. --- ## Autonomy This skill is **automatic by default**. - Infer and announce the client contract; discuss only genuine input/output/semantic ambiguity or a user request to collaborate on it. - Choose direct or stepwise construction automatically from the observable tests above. Never ask the user to choose the workflow. - Direct mode writes and validates the coherent candidate. Stepwise mode refines automatically without per-layer approval; valid checkpoints are the review surface. - Pause only when the client contract itself appears wrong, validation fails twice on the same construct, or the required MCP tools cannot produce a verdict. --- ## Reference - [Writing `.mthds` Directly](references/writing-mthds.md) — **read before writing**. The supported MTHDS subset, concrete operators/controllers, `PipeSignature`, and runnable gate. - [Native Content Types](../shared/native-content-types.md) — attributes of native concepts (`Image.url`, `Page.text_and_images`, ...) for `$var.field` references and construct `from` paths.