# Pipelex Organize > Reorganize a designed method bundle into a clear, browsable layout. Use when signature-driven construction left one .mthds file per refinement, when any existing layout needs regrouping into coherent modules (or one simple file), or when the user says "organize the bundle", "organize the method", "regroup the files", "clean up the bundle layout". Automatically follows converged /pipelex-design runs only when their construction-shaped layout needs it. Pure reorganization — never changes what the method does. - Skill: `pipelex/pipelex-organize` (Agent Skill) - Install (CLI): `npx skillmds@latest add pipelex/pipelex-organize` - Raw SKILL.md: https://api.skillmd.com/api/skills/pipelex/pipelex-organize/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: pipelex (https://skillmd.com/u/pipelex) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/pipelex/pipelex-organize --- # Organize a designed MTHDS bundle The signature-driven mode of `/pipelex-design` is deliberately additive: every refinement **adds** a new `.mthds` file, and satisfied `PipeSignature` headers linger in the files that declared them. A converged library can therefore be correct but shaped by construction history — one file per pipe, contracts duplicated as stale headers, no relationship between file layout and how the method reads. Direct designs are normally coherent already and skip this skill; they may still use it later on explicit request or when their layout genuinely needs regrouping. This skill regroups that library into a layout organized for **comprehension** — the way source code is spread across files in any language: related pipes gathered into one file per coherent unit, so a reader (human or agent) can discover the method progressively — open the root to see the contract and the top-level flow, then descend into just the module they care about. **The layout scales with the method:** a simple method fits entirely in `main.mthds`; a complex method with many pipes gets one file per subtree or functional area. Consolidation into fewer files is the usual *effect*, but the goal is grouping, not a single file. It is a **content-preserving transformation** — the method's semantics never change, and the validation verdict before and after must be identical. That equivalence is proven with the `mthds_validate` tool, never assumed. ## Requirements — the Pipelex MCP tool Equivalence is checked through the **`mthds_validate`** tool, served by the plugin's `pipelex` MCP server. It is required — this skill never reorganizes without proving the verdict is preserved. - **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`)."* Do not touch the bundle 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 reorganize unvalidated. - The server authenticates to the validation 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. Don't hand-format, and re-read a file before editing it again after the hook reformatted it. --- ## What this skill may and may not change **May change (layout only):** - Which file a concept or pipe declaration lives in, and the file names of non-root files. - The order of declarations. - Dropping a `PipeSignature` header whose code has a concrete definition anywhere in the library (the definition supersedes it — the header is construction scaffolding). - Absorbing per-file `domain = "..."` membership lines into whichever files survive. **Must NOT change (semantics):** - Pipe codes, concept codes, the `domain`, `main_pipe`, `description`, `system_prompt`. - Any pipe's `inputs`/`output` contract, `type`, prompts, steps, branches, outcomes, or any other body field. - Any concept's `description`, `refines`, or structure fields. - **Unsatisfied signatures.** A `PipeSignature` with no concrete definition (an early-stopped scaffold's backlog) is kept — deduplicated to one header per code, never dropped. The bundle stays its own todo list. If reorganizing seems to require a semantic edit (a rename, a contract fix, a missing declaration), STOP and report it — that is `/pipelex-design` territory, not organization. --- ## The target layout — group for comprehension Think of it exactly like organizing source code across files. The unit of grouping is a **coherent piece of the method**: a controller together with the sub-pipes only it wires (its private subtree), or a functional area several small pipes serve. - **Root `main.mthds` is the entry point and table of contents.** It carries the bundle header (`domain`, `description`, `main_pipe`, `system_prompt`), the boundary concepts (the client-facing contract), and the main pipe. Reading it alone tells you what the method does, what goes in and out, and what the top-level steps are. **The root file is always named `main.mthds`** unless the user says otherwise — a root inherited under another name (e.g. a legacy `bundle.mthds`) is renamed as part of organizing. - **One file per module.** Each top-level subtree (or clearly-named functional area) gets its own `.mthds` file — named after the controller that heads it or the area it implements — containing that subtree's pipes in flow order (controller first, then the pipes it wires) plus the intermediate concepts introduced for that subtree. Each non-root file starts with `domain = ""` only. - **Shared declarations go up.** A pipe or concept used by several modules lives in the root file (or, if the shared surface is large, a dedicated `shared.mthds`), never duplicated. - **Scale the file count to the method, in both directions.** A simple method — a handful of pipes — belongs entirely in `main.mthds`; don't scatter it. A complex method with tens of pipes needs several module files; don't cram it into one. And never keep a file per pipe: that is the construction sprawl this skill exists to clean up. Each file should read like a chapter, not a line. - **Progressive discovery is the test.** An agent that needs to understand or modify one step should be able to read the root plus one module file and have everything relevant — nothing important hidden in an unrelated file, no file that can't be understood without opening all the others. Within every file: satisfied signature headers are dropped; a still-pending signature (scaffold case) sits in the module of the controller that wires it. --- ## Procedure ### Step 1 — Baseline verdict 1. Gather **all** `.mthds` files in the bundle directory (e.g. `pipelex-wip//`). 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. Record the **baseline**: `is_valid`, `is_runnable`, and the exact `pending_signatures` set. Branch on the structured verdict: - `is_valid: true` → proceed (runnable or scaffold — both are organizable). - `is_valid: false` → STOP. Do not reorganize a broken library — report the verdict and point to `/pipelex-design` to fix it first. Organization must start from, and preserve, a passing verdict. - `status: "error"` → class `input_domain`: fix the call; class `config`: stop per the rule above; class `runtime`: report and retry once before stopping. ### Step 2 — Plan the layout, compose the files 1. **Map the structure**: from the main pipe down, identify the subtrees and which pipes/concepts belong to each; identify shared declarations. 2. **Decide the file set** using the target-layout rules above — possibly just `main.mthds`, possibly root + several module files. State the plan in one line (e.g. `main.mthds + extract.mthds + analyze.mthds + report.mthds`). 3. **Compose every file in memory** (do not write yet): copy each declaration verbatim into its assigned file, one declaration per concept, one entry per pipe, ordered for top-down reading within each file. ### Step 3 — Prove equivalence before touching disk Call `mthds_validate` with **the composed candidate set** (all planned files, nothing else). The verdict must match the baseline exactly: `is_valid: true`, the same `is_runnable`, and an identical `pending_signatures` set. - **Match** → proceed to Step 4. - **Mismatch or failure** → the composition dropped or duplicated something; fix the *composition* (never the semantics) and re-validate. If it still fails after two fix attempts, STOP, leave the original layout untouched, and report the discrepancy. ### Step 4 — Swap the layout Only after the candidate verdict matches: 1. **Write every file of the new layout** (Write tool — the hook lints and reformats each in place; a new file may legitimately reuse an old file's name, e.g. `main.mthds`). 2. **Delete every `.mthds` file that is not part of the new layout.** Delete only `.mthds` files; leave `inputs.json`, input files, and anything else in the directory alone. 3. **Confirm on disk**: re-gather the directory's `.mthds` files and validate once more — this catches anything the formatting hook changed. 4. **If that confirmation fails, restore the original layout — never leave the directory unconfirmed.** On `status: "error"` (no verdict — e.g. the MCP dropped mid-swap) or a verdict that does not match the baseline, roll back: you still hold every original file's content from Step 1 — rewrite the original files, delete the new-layout files that were not in the original set, and report the failure with the layout left as it was. The swap ends either proven equivalent or fully rolled back. ### Step 5 — Report One short summary: the layout (which files, what each contains, one line per file), the preserved verdict (runnable, or valid scaffold with its pending list). No approval prompts — by the time you report, the bundle is organized and proven equivalent. --- ## Autonomy This skill is **fully automatic once invoked** — no per-step approval, including the layout decision (announce it, don't ask). `/pipelex-design` auto-invokes it after converged signature-driven construction or re-entry when the layout still reflects construction history; an already coherent direct result does not invoke it solely for process compliance. It can also be invoked explicitly on any designed bundle directory. The only stops are the ones above: missing/misconfigured MCP tool, a failing baseline verdict, or a candidate that cannot be proven equivalent. If the user has expressed a layout preference (single file, specific grouping), honor it — the equivalence proof works the same for any layout.