Deleting A Pipeline Step

Deleting a Pipeline Step — Removal Workflow

Removes a named step from an existing pipeline. Performs gap analysis to identify predecessor/successor disconnections, stages all file removals and topology mutations for audit, and enforces a mandatory human approval gate before any irreversible deletion occurs.

The process of identifying predecessor/successor disconnections caused by a step removal. A condition where a deleted step sat between two active steps, requiring direct reconnection. A condition where a deleted step was the sole source of required inputs for a successor.

Workflow Phases

PHASE 0: PIPELINE & STEP SELECTION

• Resolve scope registries and identify the target pipeline and step.
• Display the current topology.json as a graph showing all dependency chains.

PHASE 1: GAP ANALYSIS

• Analyze the impact of removal on predecessors and successors.
• If a Blocking-gap is found (no alternative input source), STOP. The user must provide an alternative source or cancel the deletion.

PHASE 2: MUTATION DESIGN (REWIRE)

• For through-gaps or entry-gaps, present a rewire plan to the user (e.g., "Wire A directly to C").
• Dispatch pipeline-architect in STEP-DELETE mode to stage all changes.
• All mutations (file removals and topology updates) MUST be staged in edit-{ts}/. NEVER delete directly from production paths during design.
• Architect completion manifest gate: After the architect returns, read the STEP-DELETE completion manifest. It MUST cover every file the architect was tasked with touching and use only edited, copied-unchanged, or deleted.
• If any expected markdown artifact (*.md) is listed as copied-unchanged, STOP before Phase 3. Emit a blocking error naming the file and explain that unchanged markdown in STEP-DELETE staging indicates an architect partial exit.
• If any expected file is missing from the manifest, STOP before Phase 3. The staging set is incomplete and cannot be audited as a coherent delta.
• Staged markdown modification guard: Independently diff every staged *.md file against its production original before Phase 3. If the staged file has a production source and is byte-identical to that source, STOP before Phase 3 with a blocking error naming both paths. This guard is independent of the manifest and catches partial exits even when the manifest is wrong or missing detail.
• Pre-audit residual-reference scan: Prefer the Phase 3 delta auditor as the authoritative gate. If a manual grep is run as an additional pre-audit smoke check, it MUST explicitly include markdown files (for example, --include="*.md") so .md artifacts cannot be silently skipped.

PHASE 3: DELTA AUDIT

• Dispatch pipeline-auditor in DELTA mode on the staged topology, entry skill, and neighbor steps.
• SEV-0 or SEV-1 findings block deletion. A fragmented pipeline is a critical failure. Re-audit until the delta is clear.

PHASE 4: HUMAN APPROVAL

• Present a "Deletion Manifest" showing exactly which files will be removed and which edges will be rewired.
• Wait for explicit APPROVE. On CANCEL, discard all staged changes and do NOT delete artifacts.

PHASE 5: ATOMIC PROMOTION

• Execute file removals (agents/skills) and write updated topology.json and tasks.md.
• Update the registry.json to reflect the removal.
• Version Stamp: Update plugin_version in topology.json and the registry entry to the current superpipelines version.

• NEVER assume a step is "unused" without verifying all depends_on entries in the topology graph.
• ALWAYS perform atomic promotion from a staging area to ensure rollback capability.
• NEVER delete a step that creates an unresolvable blocking-gap in the orchestration.
• ALWAYS update plugin_version in topology.json and the registry entry to the current superpipelines version when promoting changes.

Red Flags — STOP

• "The pipeline will work without rewiring — it's obvious." → STOP. Obvious assumptions are the leading source of silent runtime failures.
• "I'll skip the human gate; deletion is a simple task." → STOP. Deletion is irreversible; the human gate is the final recovery point.
• "I'll delete the files first, then update the topology." → STOP. This results in a broken pipeline if the topology update fails.

Rationalization Table

| Excuse | Reality | | :--- | :--- | | "The step is terminal, why audit?" | Removing a terminal step can still break final status reporting or cleanup logic. | | "Rewiring is over-engineering." | A broken dependency chain blocks every subsequent pipeline run. Rewiring is essential maintenance. | | "I can recover from git if I'm wrong." | Relying on git recovery for basic workflow errors indicates a failure of the safety protocol. |

Reference Files

• sk-pipeline-paths/SKILL.md — Path resolution.
• sk-pipeline-state/SKILL.md — Run state tracking.
• adding-a-pipeline-step/SKILL.md — Insertion workflow.
• updating-a-pipeline-step/SKILL.md — Modification workflow.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gustavo-meilus
• Source: gustavo-meilus/superpipelines
• License: MIT

Install and usage instructions live in the source repository linked above.