# Adding A Pipeline Step

> Add a new step, capability, or agent to an existing named Superpipelines workflow.

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

---


# Adding a Pipeline Step — Mutation Workflow

<glossary>
  <term name="Insertion Point">The specific location in the topology (Before, After, Parallel, or Append) where the new step is added.</term>
  <term name="Topology Mutation">The process of updating `topology.json` and the entry skill to reflect new dependency edges.</term>
  <term name="Atomic Promotion">Moving all verified artifacts from a temporary staging directory to final production paths in a single operation.</term>
</glossary>

## Workflow Phases

<protocol>
### PHASE 0: PIPELINE SELECTION & INSPECTION
- Resolve scope registries and select the target pipeline via `AskUserQuestion`.
- Read and display the current `topology.json` as a numbered list of steps and dependency edges.

### PHASE 1: INSERTION DESIGN
- Identify the insertion point (Before/After/Parallel/Append) and affected neighbors.
- Apply the 4D Method to define the new step's intent, inputs, and outputs.
- Determine the component type: Skill-only, Skill + Agent, or Reuse Existing.

### PHASE 2: ARCHITECTED STAGING
- Dispatch `pipeline-architect` in `STEP-ADD` mode to generate new artifacts.
- <invariant>All new artifacts MUST be written to `{ROOT}/superpipelines/temp/{P}/edit-{ts}/` for staging. NEVER write directly to production paths during design.</invariant>

### PHASE 3: TOPOLOGY VALIDATION
- Verify the staged `topology.json` for:
  - Unique Step ID.
  - Valid `depends_on` references.
  - Schema compatibility between predecessor outputs and new step inputs.
- **Failures**: Return to the Architect with specific error logs.

### PHASE 4: DELTA AUDIT
- Dispatch `pipeline-auditor` in `DELTA` mode on all staged files (components, topology, and entry skill).
- <HARD-GATE>If the audit returns SEV-0 or SEV-1 findings, remediate and re-audit. Do NOT proceed to promotion until the delta is clear.</HARD-GATE>

### PHASE 5: PROMOTION & REGISTRATION
- Present the updated topology and audit results for human approval (`AskUserQuestion`).
- Upon `APPROVE`, move staged files to their final absolute paths in agents, skills, and pipeline directories.
- Update the `registry.json` lists to include new components.
- **Version Stamp**: Update `plugin_version` in `topology.json`, the registry entry, and the new agent's frontmatter to the current superpipelines version.
</protocol>

<invariants>
- NEVER skip the delta audit; topology mutations are the primary source of runtime orchestration failures.
- ALWAYS use a staging directory (`edit-{ts}/`) for artifact generation to prevent partial, unverified updates.
- Promote changes ONLY after explicit human approval of the updated `tasks.md` and topology snippet.
- ALWAYS update `plugin_version` in `topology.json`, the registry entry, and new agent frontmatter to the current superpipelines version when promoting changes.
</invariants>

## Red Flags — STOP
- "The audit found minor issues, let's promote anyway." → **STOP**. SEV-0/1 findings are hard blockers for promotion.
- "I'll write directly to production paths to save time." → **STOP**. Direct writes bypass the mutation safety protocol.
- "The insertion point looks obvious, skip validation." → **STOP**. Topology validation catches silent edge mismatches.

## Rationalization Table

<rationalization_table>
| Excuse | Reality |
| :--- | :--- |
| "Staging is extra overhead." | Staging allows for a rollback if the audit or human review fails. Direct writes are permanent and destructive. |
| "Topology validation is redundant." | Manual inspection often misses transitive dependency breaks caused by insertion. |
| "Minor audit findings won't break it." | Even SEV-1 findings can cause context leakage or state corruption during execution. |
</rationalization_table>

## Reference Files
- `sk-pipeline-paths/SKILL.md` — Path resolution.
- `sk-4d-method/SKILL.md` — Brief refinement.
- `creating-a-pipeline/SKILL.md` — Core scaffolding rules.
- `deleting-a-pipeline-step/SKILL.md` — Removal workflow.