GitHub - stumpyfr/loop-spec

Agent Loops OCI Artifacts Specification

Version: 0.1.0 Status: Draft Date: 2026-07-16 License: Apache-2.0

Abstract

This document defines Agent Loops: portable YAML contracts for orchestrating agentic work through declared inputs, phases, actions, completion criteria, outputs, transitions, and escalation rules.

It also specifies a standard method for packaging, distributing, signing, discovering, pinning, caching, and executing Agent Loop definitions using OCI Artifacts. It defines the loop document format, execution model, media types, manifest structure, config metadata, annotation conventions, collection indexes, project manifest files, lock files, local cache layout, and supply-chain security expectations required for interoperable loop sharing across any OCI-compliant registry.

This specification is inspired by, and intentionally aligned with, the Agent Skills OCI Artifacts Specification. The agentkit CLI is one implementation of this specification; the specification is the source of truth.

Table of Contents

1. Introduction
   • 1.1 Motivation
   • 1.2 Design Goals
   • 1.3 Relationship to Agent Skills OCI Artifacts
   • 1.4 Notational Conventions
2. Glossary
3. Agent Loop Document Format
   • 3.1 Top-Level Structure
   • 3.2 Metadata
   • 3.3 Inputs
   • 3.4 Dependencies
   • 3.5 Phases
   • 3.6 Transitions
   • 3.7 Escalation
   • 3.8 Execution Model
4. Media Types
5. Individual Loop Artifact
   • 5.1 OCI Manifest Structure
   • 5.2 Config Object Schema
   • 5.3 Layers
   • 5.4 Annotations
   • 5.5 Tagging Conventions
6. Loop Collection Artifact
   • 6.1 OCI Image Index Structure
   • 6.2 Collection Annotations
7. Loops Manifest File
   • 7.1 Purpose
   • 7.2 File Location
   • 7.3 Schema
8. Lock File
   • 8.1 Purpose
   • 8.2 File Location
   • 8.3 Schema
   • 8.4 Update Check Workflow
9. Local Cache and Execution Layout
10. Supply-Chain Security
11. Registry Compatibility
12. Reference Implementation
13. Future Considerations
14. Acknowledgments

1. Introduction

1.1 Motivation

Agent Loops are reusable orchestration contracts for agentic work. A loop definition describes the objective, required inputs, phases, phase actions, completion criteria, outputs, transitions, and escalation policy an agent should follow. The loop format is intentionally file-based and human-readable, centered on a YAML document with apiVersion: agent-loops.dev/v1alpha1 and kind: AgentLoop.

Without a standard distribution mechanism, loops are copied between repositories, pasted into prompts, or fetched from Git paths. That works for experimentation, but it becomes fragile once teams need versioned workflows, digest pinning, private registries, provenance, mirroring, and repeatable execution across projects.

OCI Artifacts provide a registry-agnostic packaging layer for arbitrary content. They let loop authors publish small, non-container artifacts to registries that organizations already know how to operate, mirror, authenticate, scan, sign, and audit. A loop artifact does not require a container runtime. Clients can use ORAS-compatible libraries to push, pull, inspect, and verify loop packages.

1.2 Design Goals

1. Registry agnostic. Loop artifacts MUST be storable in and retrievable from any OCI-compliant registry without registry-specific extensions.
2. Content addressable. Every published loop artifact MUST be identifiable by an immutable digest. Tags are convenience pointers; digests are the source of reproducibility.
3. Transparent packaging. Pulling a loop artifact MUST yield a conforming Agent Loop YAML document. OCI packaging MUST NOT change the loop execution contract defined by this specification.
4. Inspectable before execution. Clients SHOULD be able to inspect loop metadata from the OCI manifest and config before downloading or executing the YAML layer.
5. Signable and attestable. It MUST be possible to sign loop artifacts and attach provenance, validation, evaluation, or security attestations using standard OCI referrers.
6. Deterministic execution. A lock file records the exact digest for each loop and skill dependency so a project can reproduce the same dependency set later.
7. Minimal client burden. A conforming client needs only OCI Distribution support plus YAML validation against the Agent Loop schema.

1.3 Relationship to Agent Skills OCI Artifacts

This specification follows the same architectural pattern as Thomas Vitale's Agent Skills OCI Artifacts Specification:

• define a portable agent-facing format first;
• use OCI manifests and artifacts only as the distribution layer;
• expose useful metadata through config blobs and annotations;
• model collections as OCI image indexes;
• use project-local manifest and lock files for repeatability;
• rely on OCI referrers for signatures and attestations.

Agent Loops and Agent Skills are complementary but different primitives. A skill teaches an agent how to perform a class of work. A loop orchestrates a bounded run through phases, inputs, outputs, transitions, and escalation rules. Because the payload semantics differ, loop artifacts SHOULD use their own media types, config schema, annotations, manifest file, and lock file. Clients MAY support both specifications side by side.

1.4 Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

2. Glossary

Loop : A YAML document conforming to the Agent Loop schema defined by this specification.

Loop Artifact : An OCI Artifact that packages one loop document and metadata.

Loop Collection : An OCI Image Index that references a curated set of Loop Artifacts by digest.

Loops Manifest : A project-local loops.json file declaring loop dependencies by OCI references.

Lock File : A project-local loops.lock.json file recording resolved digests for deterministic pulls and update checks.

Orchestrator : The agent or tool responsible for resolving inputs, running phases, recording outputs, following transitions, and escalating decisions.

Referrers API : The OCI Distribution API mechanism used to discover signatures, attestations, and other artifacts attached to a loop artifact.

3. Agent Loop Document Format

An Agent Loop document is a YAML object that conforms to the structure in this section. JSON representations MAY be used by tooling, but YAML is the canonical authoring and interchange format for loop content layers.

3.1 Top-Level Structure

An Agent Loop document MUST contain:

3.2 Metadata

metadata MUST contain:

3.3 Inputs

spec MUST contain:

Each input definition MUST include:

3.4 Dependencies

spec.dependencies declares external Agent Loops and Agent Skills the orchestrator must make available before executing the loop. Dependencies are part of the loop contract: they describe the capabilities or sub-loops the author expects the orchestrator to have, but they do not inline or vendor those dependencies into the loop document.

spec.dependencies MAY contain:

At least one of loops or skills MUST be present when dependencies is defined.

Each loop dependency MUST contain:

Loop dependencies MUST resolve to artifacts with artifact type application/vnd.agentloops.loop.v1.

Each skill dependency MUST contain:

Skill dependencies MUST resolve to artifacts conforming to Thomas Vitale's Agent Skills OCI Artifacts Specification, including the application/vnd.agentskills.skill.v1 artifact type.

Example:

spec:
  objective: Deliver a feature safely.
  inputs:
    ticket:
      type: string
      required: true
      description: Ticket key or URL.
  dependencies:
    loops:
      - name: review_loop_engineering
        ref: ghcr.io/acme/loops/review_loop_engineering:0.2.0
        description: Reusable engineering review loop invoked before publication.
    skills:
      - name: github-pr-review
        ref: ghcr.io/acme/agent-skills/github-pr-review:1.4.0@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
        description: Skill used to inspect and address pull request review feedback.

Clients SHOULD resolve dependencies recursively, detect dependency cycles, and fail before execution when a required dependency cannot be resolved, verified, or installed. Resolved dependency digests MUST be recorded in loops.lock.json or an equivalent lock file.

3.5 Phases

Each phase MUST contain:

Phase names SHOULD be unique within a loop. Clients SHOULD reject loops with duplicate phase names because transitions would be ambiguous.

3.6 Transitions

A transition MUST contain:

When a phase has no transition selected, the orchestrator SHOULD proceed to the next phase in declaration order. A transition MAY point to the same phase or an earlier phase to model iteration.

3.7 Escalation

escalation defines when and how the orchestrator asks for human input. It MUST contain:

Each escalation input MUST contain name, type, and description.

3.8 Execution Model

An orchestrator executing an Agent Loop MUST:

1. Validate the loop document against this specification.
2. Resolve, verify, and make available all required spec.dependencies, including loop dependencies and Agent Skill dependencies.
3. Resolve all required spec.inputs before entering the first phase, unless the loop explicitly permits deferred resolution.
4. Execute phases in declaration order, subject to selected transitions.
5. Treat phase actions as the work instructions for that phase.
6. Evaluate completion criteria before leaving a phase.
7. Record each phase's declared outputs.
8. Use escalation.principle to decide when a decision cannot be safely inferred.
9. Keep run evidence separate from the loop definition.

The execution model is intentionally orchestration-oriented. The loop describes what an agent must accomplish and record; individual clients decide how to delegate actions to tools, sub-agents, or humans.

4. Media Types

All media types defined by this specification use the application/vnd.agentloops vendor tree.

Implementations MAY read earlier proof-of-concept media types for backwards compatibility, but conforming publishers MUST use the application/vnd.agentloops.* media types.

5. Individual Loop Artifact

5.1 OCI Manifest Structure

A Loop Artifact MUST be represented as an OCI Image Manifest with:

• mediaType: application/vnd.oci.image.manifest.v1+json
• artifactType: application/vnd.agentloops.loop.v1
• config.mediaType: application/vnd.agentloops.loop.config.v1+json
• exactly one required YAML content layer with media type application/vnd.agentloops.loop.content.v1+yaml

Example:

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "artifactType": "application/vnd.agentloops.loop.v1",
  "config": {
    "mediaType": "application/vnd.agentloops.loop.config.v1+json",
    "digest": "sha256:...",
    "size": 524
  },
  "layers": [
    {
      "mediaType": "application/vnd.agentloops.loop.content.v1+yaml",
      "digest": "sha256:...",
      "size": 8123,
      "annotations": {
        "org.opencontainers.image.title": "implement_feature.yml"
      }
    }
  ],
  "annotations": {
    "io.agentloops.loop.name": "implement_feature",
    "org.opencontainers.image.title": "implement_feature",
    "org.opencontainers.image.description": "Implement Feature from Jira Ticket",
    "org.opencontainers.image.version": "0.1.0",
    "org.opencontainers.image.source": "https://github.com/example/loops"
  }
}

5.2 Config Object Schema

The config object contains normalized metadata extracted from the loop YAML. A client SHOULD validate that config values match the YAML layer before execution.

Example:

{
  "schemaVersion": 1,
  "apiVersion": "agent-loops.dev/v1alpha1",
  "kind": "AgentLoop",
  "name": "implement_feature",
  "version": "0.1.0",
  "title": "Implement Feature from Jira Ticket",
  "description": "Analyse a Jira ticket, implement the requested feature, and iterate until checks pass.",
  "inputs": [
    {
      "name": "ticket",
      "type": "string",
      "required": true
    }
  ],
  "dependencies": {
    "loops": [
      {
        "name": "review_loop_engineering",
        "ref": "ghcr.io/acme/loops/review_loop_engineering:0.2.0"
      }
    ],
    "skills": [
      {
        "name": "github-pr-review",
        "ref": "ghcr.io/acme/agent-skills/github-pr-review:1.4.0@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      }
    ]
  },
  "phases": [
    "analyze-ticket",
    "prepare",
    "implement",
    "cyber review",
    "publish"
  ],
  "hasEscalation": true
}

5.3 Layers

A Loop Artifact MUST contain one YAML content layer. The layer MUST be a valid Agent Loop document. The layer SHOULD be stored as the original .yml or .yaml file without archive wrapping so clients can fetch and cache it directly.

Clients MUST reject artifacts with no YAML layer. Clients SHOULD reject artifacts with multiple loop YAML layers unless an implementation-specific selection policy is explicitly configured.

5.4 Annotations

Loop annotations use the io.agentloops.* namespace. OCI image annotations SHOULD be used for generic metadata.

5.5 Tagging Conventions

Published loop releases SHOULD be tagged with the loop version:

ghcr.io/acme/loops/implement_feature:0.1.0

The canonical reproducible reference is digest-pinned:

ghcr.io/acme/loops/implement_feature@sha256:<digest>

Tags such as latest, stable, or experimental MAY be used for human convenience, but clients MUST record resolved digests in lock files.

6. Loop Collection Artifact

6.1 OCI Image Index Structure

A Loop Collection is an OCI Image Index whose manifests reference individual Loop Artifacts by digest. It enables discovery without downloading every loop YAML layer.

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "artifactType": "application/vnd.agentloops.loop.collection.v1",
  "annotations": {
    "io.agentloops.collection.name": "engineering-loops",
    "org.opencontainers.image.title": "engineering-loops",
    "org.opencontainers.image.description": "Reusable engineering loops"
  },
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "artifactType": "application/vnd.agentloops.loop.v1",
      "digest": "sha256:...",
      "size": 0,
      "annotations": {
        "io.agentloops.loop.name": "implement_feature",
        "io.agentloops.loop.ref": "ghcr.io/acme/loops/implement_feature:0.1.0",
        "org.opencontainers.image.title": "implement_feature",
        "org.opencontainers.image.version": "0.1.0",
        "org.opencontainers.image.description": "Implement a feature from a ticket."
      }
    }
  ]
}

6.2 Collection Annotations

7. Loops Manifest File

7.1 Purpose

The loops.json file declares the loop dependencies a project expects agents or tools to use. It is analogous to a dependency manifest. It records desired OCI references, which MAY be mutable tags, immutable digests, or tag plus digest references.

7.2 File Location

The manifest file SHOULD live at the project root:

7.3 Schema

Each loop entry has:

Example:

{
  "loops": [
    {
      "name": "implement_feature",
      "ref": "ghcr.io/acme/loops/implement_feature:0.1.0"
    },
    {
      "name": "fix_pr_ci",
      "ref": "ghcr.io/acme/loops/fix_pr_ci:1.2.0@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "aliases": ["fix-ci"]
    }
  ]
}

8. Lock File

8.1 Purpose

The lock file records exact digests for resolved loop and skill dependencies. Given the same lock file, a client MUST be able to pull the same loop artifacts and Agent Skill artifacts.

8.2 File Location

The lock file SHOULD live beside loops.json:

my-project/
  loops.json
  loops.lock.json

8.3 Schema

{
  "lockfileVersion": 1,
  "generatedAt": "2026-07-16T00:00:00Z",
  "loops": [
    {
      "name": "implement_feature",
      "path": ".agents/loops/implement_feature/0.1.0/loop.yml",
      "compatibilityPath": ".agents/loops/implement_feature/loop.yml",
      "source": {
        "registry": "ghcr.io",
        "repository": "acme/loops/implement_feature",
        "tag": "0.1.0",
        "digest": "sha256:...",
        "ref": "ghcr.io/acme/loops/implement_feature:0.1.0@sha256:..."
      },
      "resolvedAt": "2026-07-16T00:00:00Z"
    }
  ],
  "skills": [
    {
      "name": "github-pr-review",
      "path": ".agents/skills/github-pr-review/1.4.0",
      "compatibilityPath": ".agents/skills/github-pr-review",
      "source": {
        "registry": "ghcr.io",
        "repository": "acme/agent-skills/github-pr-review",
        "tag": "1.4.0",
        "digest": "sha256:...",
        "ref": "ghcr.io/acme/agent-skills/github-pr-review:1.4.0@sha256:..."
      },
      "resolvedAt": "2026-07-16T00:00:00Z"
    }
  ]
}

8.4 Local Install Layout

Clients SHOULD install loops and skills under the selected agent root, commonly .agents/.

When an artifact reference contains a tag, clients SHOULD use that tag as the local version directory:

.agents/
  loops/<loop-name>/<version>/loop.yml
  loops/<loop-name>/loop.yml
  skills/<skill-name>/<version>/SKILL.md
  skills/<skill-name>/SKILL.md

The versioned paths are the authoritative paths for execution. The unversioned paths are compatibility mirrors of the latest pulled version for tools that expect the older layout.

When a reference is digest-only, clients SHOULD use a filesystem-safe digest label such as sha256-<digest> instead of <version>.

Lock files MUST record the exact installed path and resolved digest for each loop and skill dependency so orchestrators can select the version required by the loop being executed.

8.5 Update Check Workflow

1. Read loops.lock.json.
2. Resolve the current digest for each loop or skill ref when the ref contains a tag.
3. Compare the resolved digest with the locked digest.
4. Report an available update when the digests differ.
5. Update the lock file only after pulling, validating, and accepting the new loop or skill artifact.

9. Local Cache and Execution Layout

Clients SHOULD cache pulled loop YAML by registry, repository, tag, and digest to avoid accidental reuse of mutable tags.

Recommended project-local layout:

my-project/
  .loop/
    cache/
      ghcr.io/
        acme/
          loops/
            implement_feature/
              0.1.0/
                sha256-<digest>/
                  loop.yml
    runs/
      yyyy/
        mm/
          dd/
            hh/
              mm/
                run.json

An orchestrator MUST validate the cached YAML against the Agent Loop schema before execution. It SHOULD record run outputs separately from the loop artifact so replay evidence does not mutate the installed loop definition.

10. Supply-Chain Security

Loop artifacts can influence agent behavior across repositories and systems. Consumers SHOULD verify provenance before execution, especially for loops that grant agents access to issue trackers, source control, cloud infrastructure, or deployment systems.

Publishers SHOULD:

• sign loop artifacts with Sigstore Cosign or an equivalent OCI-compatible signing mechanism;
• attach provenance attestations describing source repository, revision, build workflow, and schema validation result;
• attach optional evaluation attestations describing tested agent behavior;
• publish immutable version tags and avoid retagging released versions.

Consumers SHOULD:

• prefer digest-pinned references for automation;
• verify signatures before execution;
• validate the YAML layer against the loop schema;
• inspect required inputs and escalation policy before starting a run;
• treat unsigned public loops as untrusted unless local policy permits them.

11. Registry Compatibility

Loop artifacts MUST be compatible with registries implementing OCI Distribution Spec v1.1 or compatible behavior for non-image artifacts. Implementations SHOULD work with GHCR, ECR, GAR, ACR, Docker Hub, Harbor, Zot, and local OCI registries when those registries permit arbitrary artifact media types.

When a registry does not preserve unknown media types, a client MAY fall back to descriptor annotations and YAML file-name detection, but it SHOULD warn that the artifact is not fully conformant.

12. Reference Implementation

The agentkit CLI is a reference implementation of this specification. It can:

• validate Agent Loop YAML;
• push a loop YAML file as an OCI artifact with agentkit loop push;
• pull and install a loop artifact with agentkit loop pull;
• render local or remote loop sources as a terminal flowchart;
• print agent-facing prime instructions for loop execution.

The CLI follows this specification as the source of truth for accepted document and artifact formats.

13. Future Considerations

Version constraints : A later revision may define semver ranges and compatibility rules for automatic loop updates.

Collections and search : Collection artifacts may grow richer category, owner, compatibility, and quality metadata for registry browsing.

Execution attestations : Completed runs may be published as separate referrer artifacts that point back to the loop digest used for the run.

Policy gates : Organizations may define policy checks that block unsigned loops, loops with forbidden tools, or loops whose escalation model is too broad.

Schema evolution : Future loop API versions should preserve validation and discovery behavior while allowing richer transition logic and typed outputs.

14. Acknowledgments

This specification builds on the design pattern introduced by Thomas Vitale's Agent Skills OCI Artifacts Specification, the OCI Image and Distribution Specifications, the ORAS project, and Sigstore/Cosign.