Skip to content

gustavo-meilus/superpipelines / plugins/superpipelines/skills/pipeline-optimizer-protocol

pipeline-optimizer-protocol

Verified

Loaded by the pipeline-optimizer agent to inspect an existing workflow and recommend optimization opportunities.

Pipeline Optimizer — Operational Protocol

Inputs (handed in by the orchestrator)

Resolve any unprovided paths via sk-pipeline-paths. Read only; do not glob outside the named bundle and its run dirs.

Telemetry Degradation (bound the survey to available evidence)

<telemetry_tiers>

TierAvailableAxes the survey can ground
no-run-dirstopology.json + agent frontmatter onlyTopology + model-tier cost (static). Emit advisory: "analysis is static — no run history."
state-onlystate files, no telemetryAdd past-run signals from escalations / failures / loop-cap hits.
full-telemetrystate files + run-telemetry.jsonlAdd cost/latency/ctx hotspots from telemetry rows.
</telemetry_tiers>

When telemetry is absent, do not fabricate token/latency numbers. State the tier reached in the report header so the orchestrator can advise enabling the opt-in hook (CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 + register subagent-telemetry). NEVER instruct settings edits — that is advisory text for the orchestrator to relay.

Workflow

2. SURVEY (four axes)

Apply sk-4d-method to frame "better" for this bundle, then survey each axis. Detection heuristics + false-positive guards live in references/opportunity-taxonomy.md — consult, do not duplicate.

Axis 1 — Topology structure.

  • Merge sequential redundancy (adjacent steps with the same agent / overlapping I/O and no branch between).
  • Split overloaded steps (a single step whose protocol spans multiple unrelated responsibilities).
  • Parallelize independent steps (steps with no depends_on edge between them and disjoint inputs → Pattern 1 sequential → Pattern 2 fan-out candidates).
  • Reorder to shorten the critical path.
  • Flag dead/unreachable steps (no inbound edge and not the entry step; or outputs no downstream step consumes).

Axis 2 — Model-tier cost.

  • Over-provisioned: a deep/high step doing mechanical/deterministic work.
  • Under-provisioned: a fast/triage step doing planning/architecture/review work.
  • Effort mismatch: effort_tier inconsistent with the step's reasoning load.
  • All cost opportunities carry suggested_engine: change-models (Mode C).

Axis 3 — Past-run signals (state-only / full-telemetry tiers).

  • Repeated escalation at the same step_id across runs.
  • Loop-cap hits (iterative pattern reaching the 3-iteration cap without progress).
  • Failure hotspots (a step disproportionately producing BLOCKED / non-terminal state).
  • Token/latency/ctx hotspots from run-telemetry.jsonl (full-telemetry only).

Axis 4 — Protocol/prompt quality (ADVISORY ONLY — never auto-action).

  • Vague step descriptions, missing I/O contracts, untyped outputs.
  • Every Axis-4 opportunity carries suggested_engine: advisory-only.

3. RENDER (read-only, inline)

  • Render the structured opportunity report as TERMINAL OUTPUT. NEVER write a file.
  • The orchestrator persists the report to temp/{P}/optimize-{ts}/findings.md.

4. DELEGATION BOUNDARY

  • The Optimizer MUST NOT re-check isolation correctness or frontmatter compliance (criteria #23/#24). pipeline-auditor owns that; the orchestrator runs the auditor in the apply/proof phases. Reference it; never duplicate its checks (DEPENDENCY_INVERSION).

Output Contract

<output_contract> Render an executive summary (telemetry tier reached, opportunity count by axis) followed by one entry per opportunity:

- id:              OPP-{n}
  axis:            topology | cost | past-run | quality
  impact:          high | medium | low
  affected_steps:  [step_id, ...]
  proposed_change: <one-line description>
  rationale:       <evidence, citing file:line or run/state when grounded>
  suggested_engine: update-step | add-step | delete-step | change-models | advisory-only

Cite file:line or run-id/state evidence for every grounded opportunity. Static-only opportunities (no run history) must be labelled as such in rationale. </output_contract>

Terminal Status

Emit exactly one: DONE (survey complete, opportunities rendered or none found), DONE_WITH_CONCERNS (survey complete but blind to one or more axes due to telemetry tier), NEEDS_CONTEXT (a required input path was not provided/resolvable), or BLOCKED (cannot read the bundle).

Red Flags — STOP

  • "I'll write findings.md myself." → STOP. Read-only render-inline; the orchestrator persists (#33).
  • "I'll also flag the isolation defect." → STOP. That is pipeline-auditor's job (DEPENDENCY_INVERSION); do not duplicate.
  • "Telemetry is missing, I'll estimate token counts." → STOP. Never fabricate metrics; degrade and label the tier.
  • "This tier is deep, name the model to change it to." → STOP. Recommend a model_tier direction only; concrete IDs live in profile JSON.
  • "I'll apply the merge to save a round-trip." → STOP. The Optimizer never mutates.

Rationalization Table

<rationalization_table>

ExcuseReality
"Writing the report file is faster."Render-inline avoids the report-ownership / permissionMode split-brain fixed in #33. Orchestrator persists.
"Re-checking isolation is thorough."Duplicating auditor checks is source-of-truth drift (DEPENDENCY_INVERSION). Delegate.
"No telemetry, but I can guess the hotspot."Guessed metrics mislead the plan. Degrade to the available tier and say so.
"Quality issues should auto-fix."Axis-4 is advisory-only by contract; the human decides.
</rationalization_table>

Reference Files

  • ${CLAUDE_PLUGIN_ROOT}/skills/pipeline-optimizer-references/references/opportunity-taxonomy.md
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 321kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall