agentleFS
gustavo-meilusgustavo-meilus/superpipelines/AGENTS.md

superpipelines

AGENTS.md4 starsChanged 6 months agoMITView on GitHub

superpipelines is a multi-agent pipeline orchestration framework distributed as a cross-platform AI tooling plugin. It helps users design, scaffold, audit, mutate, optimize, and run named workflows made of specs, plans, tasks, parallel branches, iterative loops, and human gates. The core product promise is repeatable AI process: define a workflow once, let tier-aware agents or inline protocols execute it, preserve reviewer isolation where the host supports it, and keep generated pipelines portable across supported tools. Primary user commands are /superpipelines:new-pipeline, /superpipelines:run-pipeline,…

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository5 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

18 rules. About 0 are common, 11 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read CLAUDE.md before editing architecture, skills, agents, manifests, pipeline dispatch, model resolution, or generated artifact rules.

    line 98
  2. Very specific:

    Keep SUB_AGENT_SPAWNING: FALSE: subagents never spawn children.

    line 100
  3. Very specific:

    Use model_tier: instead of model: in agent frontmatter unless deliberately handling a documented override path.

    line 106
  4. Very specific:

    Do not put behavior in platform manifests.

    line 108
  5. Very specific:

    Do not add bodies to Claude Code plugin agents.

    line 110
  6. Very specific:

    Use disable-model-invocation: true only for protocol skills loaded through agent skills: lists.

    line 112
  7. Distinctive:

    Do not rename, flatten, or "simplify" lifecycle phase ordering without updating the explicit phase contract, state ledger, and guards.

    line 114
  8. Very specific:

    Do not treat permissionMode: plan as an enforcement boundary for dispatched subagents.

    line 116
  9. Distinctive:

    Before claiming repository-wide completion, run:

    line 140
  10. Very specific:

    Before topology edits or pipeline workflow changes, run /superpipelines:audit-steps or the equivalent audit workflow.

    line 146
  11. Distinctive:

    Before release or installer changes, run:

    line 148
  12. Distinctive:

    Before modifying onboarding, run the aiboarding size check when installed:

    line 156
  13. Distinctive:

    Ask before deleting or rewriting generated pipeline examples, parity fixtures, release artifacts, or archived onboarding context.

    line 164
  14. Distinctive:

    Ask before changing public command names, lifecycle phase names/order, artifact locations, model-tier semantics, or tier support claims.

    line 166
  15. Distinctive:

    Ask when a fix would weaken reviewer isolation, dependency inversion, phase gating, or write permission boundaries.

    line 168
  16. Distinctive:

    Ask when CI and CLAUDE.md disagree about the intended architecture.

    line 170
  17. Distinctive:

    Ask before replacing manual parity requirements with an automated claim that has not been verified on live hosts.

    line 172
  18. Distinctive:

    Ask when onboarding sources conflict and the authoritative file is unclear.

    line 174

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Superpipelines Agent Onboarding

Project Purpose

superpipelines is a multi-agent pipeline orchestration framework distributed as a cross-platform AI tooling plugin. It helps users design, scaffold, audit, mutate, optimize, and run named workflows made of specs, plans, tasks, parallel branches, iterative loops, and human gates.

The core product promise is repeatable AI process: define a workflow once, let tier-aware agents or inline protocols execute it, preserve reviewer isolation where the host supports it, and keep generated pipelines portable across supported tools.

Primary user commands are /superpipelines:new-pipeline, /superpipelines:run-pipeline, /superpipelines:audit-steps, /superpipelines:new-step, /superpipelines:update-step, /superpipelines:delete-step, /superpipelines:change-models, /superpipelines:init-deep, and direct /superpipelines:{P} launchers.

Stack and Runtime

This repo is mostly declarative plugin source: Markdown skills, agent frontmatter, JSON manifests, shell hooks, and Node.js guard scripts. There is no compile step and no app server.

Runtime requirements: Node >=18 for bin/install.js and repository checks. The package is ESM via "type": "module" in package.json.

Supported host tiers are Tier 1 Claude Code, Tier 1b OpenCode, Tier 1c Antigravity CLI 2.0 best-effort, Tier 1d Codex App/CLI, and Tier 2 Cursor/Windsurf/Cline. Gemini CLI is retired as of 2026-06-18.

Windows development is common. Use PowerShell-compatible commands when practical. Do not write JSON with Set-Content -Encoding UTF8 in ways that introduce a UTF-8 BOM; Claude Code JSON parsing can fail on BOM-prefixed files.

Build, Test, Run

Install locally or globally through the universal installer:

npx -y superpipelines-install
.\install.ps1

POSIX install path:

./install.sh

Repository checks:

npm run check:versions
npm run check:profiles
npm run check:authoring
npm run check:parity
npm run report:preload
npm run check:install-docs
npm run check:codex-plugin
npm run check:all

Useful packaging/docs commands:

npm run package:codex
npm run check:codex-plugin
npm run docs:install-table
npm run check:install-docs
node bin/install.js --list
node bin/install.js --dry-run --non-interactive --only claude-code --only codex --only cursor --only windsurf --only cline --only antigravity

CI in .github/workflows/ci.yml validates JSON manifests, required files, version agreement, platform profiles, materialization parity, authoring rules, preload budget, packaged plugin guards, installer detection, installer dry-runs, and README install-table sync.

Architecture Map

Root source directories:

  • agents/: Claude Code zero-body agent definitions; behavior lives in protocol skills.
  • skills/: operational intelligence. Each user-facing workflow and reusable method is a SKILL.md.
  • commands/: slash-command wrappers that route into skills.
  • hooks/: shipped Claude Code hook scripts, including optional subagent telemetry.
  • bin/: installer entrypoints.
  • scripts/: repository guard, packaging, parity, authoring, version, and docs checks.
  • plugins/superpipelines/: packaged Codex plugin bundle regenerated by npm run package:codex; never hand-edit.
  • docs/: ADRs, agent docs, and archived context.
  • .claude-plugin/, .codex-plugin/, .cursor-plugin/, gemini-extension.json: discovery manifests, not behavior sources.
  • .superpipelines/: portable generated pipeline data and temp state.
  • .claude/, .opencode/, .codex/, .agents/: platform-specific examples, generated artifacts, or native materialization targets depending on tier.

Architectural source of truth is CLAUDE.md plus docs/adr/ and focused docs under docs/agents/. AGENTS.md is the cross-agent onboarding summary and must stay compressed.

Dependency direction is profile-driven. Skill bodies depend on abstract platform_profile.<field> values from skills/sk-platform-dispatch/profiles/{tier_id}.json; concrete per-platform model IDs, dispatch mechanisms, scope roots, and isolation recipes must not be duplicated into workflow bodies.

Domain Model

The core entity is a pipeline: a named multi-step AI workflow with spec, plan, task graph, topology, generated agents/protocols, and live run state.

Canonical lifecycle phases are DECONSTRUCT, DIAGNOSE, DEVELOP, HARD GATE, IMPLEMENT, STAGE1, STAGE2, COMMIT, and DONE.

Canonical execution patterns are Sequential, Parallel Fan-Out, Iterative Loop with max 3 iterations, Human-Gated, Spec-Driven Dev, and 4D Wrapper.

Generated pipeline state lives at <workspace-or-user>/.superpipelines/temp/{P}/{runId}/pipeline-state.json and carries plugin_version, metadata.source_tier, metadata.runtime_tier, phase ledger data, resolved models, and crash-resume checkpoints.

Portable generated artifacts live under .superpipelines/ as tool-neutral data. Runtime dispatch materializes host-native agent files for Claude Code, OpenCode, Codex, Antigravity, or inline Tier 2 execution.

Model selection is tier-based and runtime-resolved. Agent frontmatter writes model_tier: and optional effort_tier:. Runtime resolution uses sk-model-resolver precedence: explicit override, workspace prefs, user prefs, profile default, then native host inherit.

Agent Guardrails

Read CLAUDE.md before editing architecture, skills, agents, manifests, pipeline dispatch, model resolution, or generated artifact rules.

Keep SUB_AGENT_SPAWNING: FALSE: subagents never spawn children. Orchestration belongs in top-level skills or the parent session.

Preserve WRITE_REVIEW_ISOLATION: writer agents must not review their own work. Stage 1 spec compliance gates Stage 2 quality review. Tier 2 isolation is convention-only and must be surfaced as a degradation.

Preserve DEPENDENCY_INVERSION: PROFILE_DRIVEN: platform facts belong in skills/sk-platform-dispatch/profiles/{tier_id}.json, not copied into skill bodies.

Use model_tier: instead of model: in agent frontmatter unless deliberately handling a documented override path.

Do not put behavior in platform manifests. .claude-plugin/, .codex-plugin/, .cursor-plugin/, and gemini-extension.json are discovery-only.

Do not add bodies to Claude Code plugin agents. agents/*.md should stay frontmatter-only; companion {agent}-protocol/SKILL.md files hold behavior.

Use disable-model-invocation: true only for protocol skills loaded through agent skills: lists. Skills loaded through the Skill tool must remain loadable and should use user-invocable: false alone when hiding from slash menus.

Do not rename, flatten, or "simplify" lifecycle phase ordering without updating the explicit phase contract, state ledger, and guards.

Do not treat permissionMode: plan as an enforcement boundary for dispatched subagents. Structural write barriers come from tools: and disallowedTools: allowlists.

Known Failure Modes

Worktree artifact loss: data-only agents in isolated worktrees can write only gitignored temp files, then lose artifacts when the worktree is cleaned. Data/artifact-only agents should omit isolation; tracked-code writers may use isolation: worktree and must host-anchor artifacts.

Audit ownership split: read-only reviewers/auditors must render reports inline or return content; the orchestrator persists files. A read-only protocol instructing an agent to write is a defect.

Phase drift: live orchestration previously skipped pre-dispatch phases and invented fake phases. running-a-pipeline must maintain the ordered phase manifest and hard-stop if required pre-run gates are absent.

Invocation-flag trap: disable-model-invocation: true on a Skill-tool-loaded skill blocks runtime loading. Use it only when the skill is loaded through an agent skills list.

Profile drift: concrete tier values duplicated in skill bodies drift away from skills/sk-platform-dispatch/profiles/{tier_id}.json.

Claude plugin-scope caveat: Claude Code ignores some plugin-shipped subagent settings such as permissionMode; plugin agents rely on tools: and disallowedTools: for real barriers.

Subagent telemetry blind spot: orchestrators cannot see per-subagent token counts directly. Cost/latency signals require hook-authored telemetry and must degrade gracefully when unavailable.

Cross-platform parity remains partly manual. CI checks materialization translators and goldens, but live host dispatch still needs manual release verification.

Verification Before Completion

For ordinary code, docs, manifests, or skill changes, run the narrowest relevant checks plus npm run check:all when the change can affect release integrity.

Before claiming repository-wide completion, run:

npm run check:all

Before topology edits or pipeline workflow changes, run /superpipelines:audit-steps or the equivalent audit workflow.

Before release or installer changes, run:

node bin/install.js --list
node bin/install.js --dry-run --non-interactive --only claude-code --only codex --only cursor --only windsurf --only cline --only antigravity
npm run check:install-docs

Before modifying onboarding, run the aiboarding size check when installed:

.aiboarding/tools/check-size-budget AGENTS.md

Escalation - Ask the User When

Ask before deleting or rewriting generated pipeline examples, parity fixtures, release artifacts, or archived onboarding context.

Ask before changing public command names, lifecycle phase names/order, artifact locations, model-tier semantics, or tier support claims.

Ask when a fix would weaken reviewer isolation, dependency inversion, phase gating, or write permission boundaries.

Ask when CI and CLAUDE.md disagree about the intended architecture.

Ask before replacing manual parity requirements with an automated claim that has not been verified on live hosts.

Ask when onboarding sources conflict and the authoritative file is unclear.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.