gustavo-meilus/superpipelines / plugins/superpipelines/skills/pipeline-architect-protocol
pipeline-architect-protocol
VerifiedLoaded by the pipeline-architect agent to design or mutate Superpipelines pipeline topology and data-only CAD artifacts.
Pipeline Architect — Operational Protocol
Operating Modes
<operating_modes>
| Mode | Trigger | Primary Outputs |
|---|---|---|
| PIPELINE | new-pipeline command | spec.md, plan.md, tasks.md, topology.json, agents, skills. |
| STEP-ADD | new-step command | New agent/skill; updated topology.json, tasks.md, and entry skill (staged). |
| STEP-UPDATE | update-step command | Edited agent/skill; updated topology.json with propagated edges (staged). |
| STEP-DELETE | delete-step command | Deleted files; rewired topology.json; updated tasks.md and entry skill (staged). |
| UPDATE | Prompt: "Update X to..." | In-place edits to existing pipeline artifacts with a summary. |
| DIAGNOSE | Prompt: "Why is it failing?" | Topology diagnosis and remediation plan without destructive writes. |
| </operating_modes> |
Protocol
2. DESIGN
-
PIPELINE: Design all step agents per the canonical CAD schema in
pipeline-auditor-references/references/canonical-agent-def.mdand the CAD authoring template inreferences/sdd-artifacts.md; drafttopology.jsonedges. Anoutput-formatterstep MUST be appended as the final node, configured to write to<workspace-root>/output/. Minimal-pipeline exemption: an explicitly minimal/tracer pipeline (≤2 steps, declaredminimal: truein its registry entry) MAY omit theoutput-formatternode — its terminal step's declared output is the pipeline output. Do not auto-inject a formatter into aminimalpipeline. -
STEP-ADD: Determine component type (skill-only, skill+agent, or agent-reuse) and wire into edges. Ensure the topology still terminates with the
output-formatterstep if applicable. -
STEP-DELETE: If a blocking gap is detected, design rewire logic before removing any files.
-
Constraint: Generated agents are single CAD files (data): tool-neutral frontmatter plus inline operational protocol body. No separate companion
-protocolskill is generated for new data-only pipelines. Bundlesk-*method skills may be referenced viaprotocol_skills. -
CAD/body boundary: CAD frontmatter is portable agent data, not skill metadata. Do not add
disable-model-invocationoruser-invocableto CAD frontmatter. -
Reference extraction rule: Keep one-off operational instructions inline. Create
DATA_ROOT/pipelines/{P}/references/{name}.mdonly when two or more CADs share substantial material, when inlining would harm scanability, or when the material is a stable contract such as a schema, rubric, checklist, or severity table. -
Scaffold summary: When references are created or inline-body exceptions are made, record them in
DATA_ROOT/pipelines/{P}/scaffold-summary.md. -
Data-Only Entry Constraint (v2.x+): The entry orchestration body is written as DATA at
DATA_ROOT/pipelines/{P}/entry.md(NOT a tool-registered skill). A data-only pipeline has no registered entry skill — it is discovered and run by the bundle'srunning-a-pipelineorchestrator, which readsentry.md+topology.jsonfrom the data root. The entry body MUST dispatch every step viask-platform-dispatchDISPATCH, never directTask(subagent_type=...). This is the only way generated pipelines stay portable across Tier 1 / Tier 1b / Tier 1c / Tier 1d / Tier 2. -
Generated Entry Body Template (
entry.mddata): For each step intopology.json, emit a dispatch block of the form:Skill("sk-platform-dispatch") result = DISPATCH(step={id: "<step.id>", agent: "<step.agent>", agent_def: "pipelines/{P}/agents/<step.agent>.md", output_paths: [...]}, inputs=<resolved>) if result.status != "DONE": handle per status protocolDISPATCH receives the CAD reference via
agent_def(relative to DATA_ROOT) and materializes the native agent at run time (Option A). The legacyprotocol_skillfield is removed — the protocol is inline in the CAD. Entry skill frontmatter MUST include (C4 compliance):user-invocable: true disable-model-invocation: true plugin_version: "<current_version>"user-invocable: trueexposes the pipeline for user invocation.disable-model-invocation: trueprevents the model from spontaneously re-entering the pipeline mid-dispatch.Entry body MUST include a Phase 5.x cleanup contract (C20 compliance):
- Write
status: "completed"toDATA_ROOT/temp/{P}/{runId}/pipeline-state.json(UTF-8, no BOM) on success. - Delete
DATA_ROOT/temp/{P}/{runId}/on DONE. - Trigger
CLEANUP_MATERIALIZED(P, scope)(sk-platform-dispatch) on DONE to remove the ephemeral materialized agent cache. - Preserve temp dir and log path on BLOCKED/FAILED/ESCALATED.
Entry body paths MUST resolve via
sk-pipeline-paths(C22 compliance): every data path resolves againstDATA_ROOT(RESOLVE_DATA_ROOT(scope)), never a literal.claude/,.opencode/,.agents/directory name. Data-only paths are tier-independent, so no portability rewrite is needed.Raw
Task(subagent_type=...)invocations are forbidden in entry skills for top-level step dispatch. Scope of this constraint:- In-scope (MUST use DISPATCH): the entry skill's main per-step orchestration loop — i.e., the call that hands a step's agent + protocol-skill + inputs to the executor.
- Out-of-scope (raw Task() permitted): (a) the architect's own internal Task() calls during PIPELINE mode; (b) nested Task() calls inside a step's protocol skill (e.g., a reviewer protocol that spawns a helper) — those run under the executor selected by DISPATCH and are not themselves top-level dispatch.
- Write
3. DEVELOP
For each new agent (REQUIRED, non-optional):
- Write the CAD file at
DATA_ROOT/pipelines/{P}/agents/{agent-name}.md— tool-neutral frontmatter (schema below) followed by the inline protocol body. - Do NOT create a separate
{agent-name}-protocolskill and do NOT write a frontmatter-only tool-dir agent. The protocol is inline; the materializer translates the CAD to native frontmatter at dispatch.
Schema + capability→primitive translation: pipeline-auditor-references/references/canonical-agent-def.md. See references/sdd-artifacts.md § "Canonical agent-def template" for the exact template.
CAD frontmatter rules (capability intent, NOT platform primitives):
schema_version: "1.0",name,description(third-person, triggering-only),role,review_stage,status_protocol: standard, andplugin_version: "<current>".- Write
model_tier:(one oftriage | fast | medium | deep | inherit) and optionaleffort_tier:(low | medium | high); setturn_budget. A concretemodel:MUST NOT be written — resolved at runtime bysk-model-resolver. Defaults: planning/architecture/review →deep; coding/execution →medium; utility/formatting →fast; routers/classifiers →triage. capabilities: { write_files, run_shell, network, edit_tracked_source }— the portable security contract. The materializer translates these to each tier's enforcement primitive. Setwrite_files:trueonly for file-producing agents;edit_tracked_source:trueonly for legitimate tracked-code writers;run_shell/networkonly when the protocol needs them.isolation_required: trueONLY whenedit_tracked_source: true(writer needing a worktree).- Optional
tool_hints.allow— capability-consistent refinement only; MUST NOT grant a denied capability. io_contract— inputs ({key, from_step, kind}) and outputs ({key, path, kind}); all paths RELATIVE to the run dir (no absolute, no scope-root prefix, no..).protocol_skills— bundle skills to load (tier-discovered, unchanged); MAY be empty.memory: projectis forbidden.- Reviewer isolation =
capabilities.write_files: false. This is the single canonical source for reviewer write-deny; the materializer emits the tier's structural primitive (CC:permissionMode: plan+disallowedTools: Write, Edit, Bash; OC:permission: { edit: deny }; Codex:sandbox_mode: read-only). Per-tier recipe text MUST NOT be duplicated in this skill body — the profile JSON + the canonical-def translation table are the single sources of truth.
All files are built via Write (new) or Edit (update), resolving all paths via sk-pipeline-paths (RESOLVE_DATA_ROOT(scope)).
4. DELIVER
- PIPELINE: Write directly to final paths; emit Mermaid topology and Architect's Brief.
- STEP- Modes*: Stage artifacts ONLY to
temp/{P}/edit-{ts}/; promotion occurs after audit. - STEP-DELETE completion manifest: Before returning from STEP-DELETE mode, emit a completion manifest covering every file the architect was tasked with touching. Each entry MUST include the production path, staged path when present, and one status:
edited— staged content was intentionally changed from the production source.copied-unchanged— staged content is byte-identical to the production source.deleted— the file is intentionally removed and has no staged replacement. The manifest is mandatory even when the topology edit succeeds. The delete-step orchestrator reads it before delta audit and treatscopied-unchangedon expected markdown updates as a blocking partial-exit signal.
- UPDATE/DIAGNOSE: Edit in-place and provide a delta summary.
Reference Files
${CLAUDE_PLUGIN_ROOT}/skills/pipeline-architect-references/references/topology-selection.md${CLAUDE_PLUGIN_ROOT}/skills/pipeline-architect-references/references/agent-frontmatter-schema.md— legacy old-root reference only; do not use for new data-only pipeline scaffolding.${CLAUDE_PLUGIN_ROOT}/skills/pipeline-architect-references/references/sdd-artifacts.md${CLAUDE_PLUGIN_ROOT}/skills/pipeline-architect-references/references/anti-patterns.md
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |