add-pipeline

name	add-pipeline
description	Scaffold a Trinity-compatible long-running pipeline inside any agent — creates projects/<slug>/{project.md, pipeline.yaml, instances/}, copies pipeline-tick/status/recover/pause/resume skills into .claude/skills/, sets up the ~/.trinity/ read surface, installs the heartbeat schedule, adds a dashboard section, and removes the harmful legacy pre-check hook if present.
allowed-tools	Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill
user-invocable	true
metadata	{"version":"1.7","created":"2026-05-23T00:00:00.000Z","updated":"2026-07-22T00:00:00.000Z","author":"Ability.ai","changelog":["1.7: Cross-agent stages — pipeline.yaml stages accept an optional agent: (the stage is that fleet agent's playbook); pipeline-tick 1.3 dispatches it as a one-line playbook call and polls the execution; when-to-use gains the multi-agent-process shape (instance = one run). Fleet convention protocols/playbook-call.md, operator direction 2026-08-16","1.6: Platform caveat rewritten for ent#89 — Trinity materializes the declared schedules: block at agent creation (disabled unless a literal YAML true, max 20, deduped by name, never re-applied on recreate), so a derived agent DOES get the heartbeat. Dropped the non-schema `id:` key from the scaffold and made `name:` the live schedule name, since Trinity keys idempotency on name — the mismatch produced two heartbeats for one job","1.5: Fix the scaffolded escalation contract — pipeline-tick now files operator-queue items by writing ~/.trinity/operator-queue.json with an agent-chosen request_id (trinity#1631; send_notification is a different subsystem and returns no queue_id), pipeline-recover resolves via respond_to_operator_queue; Step 7 notes a schedule message naming an uninstalled skill now fails loudly as SKILL_NOT_FOUND (#1410)","1.4: When-to-use caveat — a heavy CPU-bound stage (index rebuild, bulk embedding, full bootstrap) must NOT run inside the heartbeat's LLM turn: a headless run can't host a job past the ~10-min sync Bash ceiling (auto-backgrounded, then reaped at turn-end). Model it as an OS-level job (container cron / systemd / sidecar) writing a done-marker; the stage only triggers + verifies the artifact moved. Keeps the heartbeat a cheap read-and-advance loop","1.3: Platform-alignment fixes, verified against Trinity source — (1) the pre-check hook is REMOVED entirely, with migration: Trinity's scheduler has no fire/skip vocabulary (exit 0 + empty stdout ⇒ skip; exit 0 + ANY stdout ⇒ stdout replaces the calling schedule's configured message; the hook is agent-global with no schedule context), so v3's `echo fire` rewrote every schedule's prompt to the literal word 'fire' — Step 6 now strips any add-pipeline block (v1–v3) and deletes an empty leftover hook; skip logic lives in pipeline-tick alone; (2) create_agent_schedule is called with its real params (agent_name/name/cron_expression/message — schedule_name/cron/skill/pre_check never existed); (3) the dashboard.yaml block now uses Trinity's real sections[]→widgets[] schema with materialized rows that pipeline-tick refreshes (the old panel_type/source block was never rendered); (4) template.yaml schedules: caveat — Trinity never reads that block at agent creation; only /trinity:onboard and /trinity:sync materialize it","1.2: Fleet-orchestrator integration — Step 7 also records the heartbeat in template.yaml's schedules: block (source of truth for /trinity:sync; makes the pipeline discoverable to /add-orchestrator's /discover-agents); when-to-use now names /add-orchestrator + /orchestrate as the cross-agent layer for one-agent-per-tenant fan-out","1.1: Add 'When to use a pipeline' guidance (multi-instance ≠ multi-tenant); add Skill to allowed-tools and invoke /validate-pipeline canonically (Composition Rule)"]}

Add Pipeline

ℹ️ First, set expectations: before anything else, print one short line with this skill's version and its most recent change — the top entry of metadata.changelog above — e.g. add-pipeline vX.Y — recent: <summary>. Then proceed.

Add a long-running, multi-stage pipeline to any Trinity-compatible agent. Implements the canonical pipeline spec: the agent owns the DAG and stage logic; Trinity owns the read surface (~/.trinity/pipelines/*.yaml + ~/.trinity/pipeline-state/**/*.json); a single heartbeat skill (pipeline-tick) owns advancement, retry, and escalation.

When to use a pipeline (and when not): reach for this when the work is a population of items that each crawl through multiple stages over many runs — or a multi-agent process where each stage is another agent's playbook (a release propagation, an onboarding chain; one instance = one run, agent: on the stage, the tick dispatches a one-line playbook call — fleet convention protocols/playbook-call.md) — and you need durable per-item state, isolated retries, and an at-a-glance "what stage is each item in" — e.g. per-customer onboarding, document ingestion, batched research crawls, especially when the whole batch can't finish in one scheduled run. If it's a single recurring task, a scheduled playbook is simpler — don't reach for a pipeline. And mind the boundary: instances are multi-instance, not multi-tenant — their state is isolated but they all run inside the same agent (same credentials, context window, and heartbeat), so for genuinely isolated or large-scale tenants, deploy one agent per tenant (Trinity fan-out) rather than one pipeline with many instances — that cross-agent layer is /add-orchestrator's domain: its /orchestrate skill does the routing, fan-out, and ephemeral roll-out/tear-down across a fleet, and its /discover-agents surfaces this agent's pipelines to the fleet map.

Keep heavy CPU jobs out of the heartbeat turn. A stage that does real compute (a FAISS/index rebuild, bulk embedding, a full bootstrap) must not run synchronously inside pipeline-tick's LLM turn. A headless run is a single agent turn and can't host a job past the ~10-min synchronous Bash ceiling — past it the harness auto-backgrounds the job, active waiting is blocked, and the turn ending reaps the backgrounded task (it fires killed, not ; see → ). Model the heavy work as an (a container cron / systemd unit or a small non-LLM sidecar writing a ), and let the stage only (mtime advanced / count > 0 — not an exit code or ). The heartbeat stays a cheap read-and-advance loop.