adding-a-pipeline-step

name	adding-a-pipeline-step
description	Add a new step, capability, or agent to an existing named Superpipelines workflow.
user-invocable	false

Adding a Pipeline Step — Mutation Workflow

The specific location in the topology (Before, After, Parallel, or Append) where the new step is added. The process of updating `topology.json` and the entry skill to reflect new dependency edges. Moving all verified artifacts from a temporary staging directory to final production paths in a single operation.

Workflow Phases

### 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.
• All new artifacts MUST be written to {ROOT}/superpipelines/temp/{P}/edit-{ts}/ for staging. NEVER write directly to production paths during design.

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).
• If the audit returns SEV-0 or SEV-1 findings, remediate and re-audit. Do NOT proceed to promotion until the delta is clear.

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.

- 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.

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.