loop-spec.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://loop-lang.dev/spec/loop-spec.schema.json",
  "title": "LoopFlow Spec",
  "description": "The open intermediate representation a .loop file parses to. The contract between @loop-lang/parser, @loop-lang/runtime, and the loop-vscode extension. Anyone may implement against this.",
  "type": "object",
  "required": ["loopVersion", "definitions"],
  "additionalProperties": false,
  "properties": {
    "loopVersion": {
      "type": "string",
      "description": "Spec version this document targets.",
      "const": "0.1"
    },
    "config": {
      "description": "The config tier: which method/preset, when it runs, where. Null when the file has no config block.",
      "type": ["object", "null"],
      "additionalProperties": false,
      "properties": {
        "use": {
          "type": "string",
          "description": "A preset reference: a stdlib name (\"BMAD\"), a local path (\"./my-method.loop\"), or a registry ref (\"owner/method\")."
        },
        "useOverrides": {
          "description": "Overrides applied to the used preset (the `use X, but: ...` form). Each entry patches a named stage or a top-level config key.",
          "type": "array",
          "items": { "$ref": "#/$defs/overrideEntry" }
        },
        "live": {
          "type": "boolean",
          "description": "Claude Code /loopflow dashboard opt-in from loop.config. true opens the live dashboard; false runs normally."
        },
        "runner": {
          "type": "string",
          "description": "Execution backend. v1 supports only \"claude-code\".",
          "default": "claude-code"
        },
        "schedule": {
          "type": "string",
          "description": "When to run: \"manual\", \"nightly\", \"on push\", or a cron expression. v1 parses but only runs \"manual\" (via Play)."
        },
        "target": {
          "type": "string",
          "description": "Working directory / scope the runner operates in."
        },
        "notify": {
          "type": "string",
          "description": "Notification destination (e.g. \"slack\"). Deferred past v1."
        },
        "git": { "$ref": "#/$defs/gitPolicy" },
        "models": { "$ref": "#/$defs/modelPolicy" },
        "cycle": {
          "type": "array",
          "description": "File-level default cycle (`each cycle: …` at the config tier). Applies to every loop without its own `each cycle:`; a per-loop cycle overrides it. Lowest wins, like git.",
          "items": {
            "type": "string",
            "enum": ["plan", "act", "observe"]
          },
          "minItems": 1
        },
        "rigor": {
          "type": "string",
          "enum": ["vibe coding", "structured ai-assisted", "agentic engineering"],
          "description": "The spectrum dial — bundles best-practice defaults (a back-edge + thrash guard) over every loop in the file. structured/agentic inject them when a loop omits its own; vibe coding injects nothing."
        },
        "mode": {
          "type": "string",
          "enum": ["conductor", "orchestrator"],
          "description": "Supervision posture: conductor = in-session/synchronous (gates answered inline); orchestrator = async/reviews-outcomes (opens a PR)."
        },
        "observe": {
          "type": "object",
          "additionalProperties": false,
          "description": "Observability: a per-cycle trace, cost metering, and an optional spend cap.",
          "properties": {
            "trace": { "type": "boolean", "description": "Emit a per-cycle trace and a stop-time OpEx report." },
            "meter": { "type": "boolean", "description": "Meter tokens and cost per cycle (needs a provider that reports usage)." },
            "costCap": { "type": "string", "description": "Stop and warn if spend exceeds this (e.g. \"$5\")." }
          }
        },
        "sandbox": {
          "type": "object",
          "additionalProperties": false,
          "description": "Run isolation: where code runs and what it cannot reach.",
          "properties": {
            "network": { "type": "string", "enum": ["none", "allowlist"] },
            "egress": { "type": "array", "items": { "type": "string" } },
            "cpu": { "type": "string" },
            "memory": { "type": "string" },
            "time": { "type": "string" }
          }
        },
        "runsAs": {
          "type": "string",
          "description": "Identity the run executes as (`runs as: …`) — an auditable principal for unattended runs."
        }
      }
    },
    "definitions": {
      "type": "array",
      "description": "Top-level definitions in file order: pipelines and standalone loops.",
      "items": {
        "oneOf": [
          { "$ref": "#/$defs/pipeline" },
          { "$ref": "#/$defs/loop" },
          { "$ref": "#/$defs/flow" }
        ]
      }
    }
  },
  "$defs": {
    "overrideEntry": {
      "type": "object",
      "additionalProperties": false,
      "required": ["target"],
      "properties": {
        "target": {
          "type": "string",
          "description": "What is being overridden: a stage name, or a config key like \"schedule\"."
        },
        "kind": {
          "type": "string",
          "enum": ["stage", "config"],
          "default": "stage"
        },
        "patch": {
          "description": "For kind=stage, a partial loop to merge into the stage's loop. For kind=config, a {key,value}.",
          "type": "object"
        }
      }
    },
    "pipeline": {
      "type": "object",
      "additionalProperties": false,
      "required": ["kind", "name", "stages"],
      "properties": {
        "kind": { "const": "pipeline" },
        "name": { "type": "string" },
        "stages": {
          "type": "array",
          "description": "Stages run sequentially in v1; a failing stage halts the rest.",
          "items": { "$ref": "#/$defs/stage" }
        }
      }
    },
    "stage": {
      "type": "object",
      "additionalProperties": false,
      "required": ["name", "loop"],
      "properties": {
        "name": { "type": "string" },
        "gate": {
          "description": "A blocking human gate that must be approved before the stage's loop runs (e.g. \"a human approves before provisioning\").",
          "type": ["object", "null"],
          "additionalProperties": false,
          "properties": {
            "message": { "type": "string" }
          }
        },
        "loop": { "$ref": "#/$defs/loop" },
        "parallelGroup": {
          "type": "integer",
          "description": "Stages sharing a parallel-group id run concurrently (`stages in parallel:`)."
        }
      }
    },
    "loop": {
      "type": "object",
      "additionalProperties": false,
      "required": ["kind", "goal", "cycle"],
      "properties": {
        "kind": { "const": "loop" },
        "name": {
          "type": ["string", "null"],
          "description": "Optional name; null for an anonymous loop inside a stage."
        },
        "goal": {
          "type": "string",
          "description": "The objective in plain language."
        },
        "doneWhen": {
          "description": "Verification conditions — ALL must pass (a conjunction of predicates). A test/command predicate is a deterministic check (TESTS); a skill predicate is an eval (EVALS). Empty/absent means the loop relies on a human review to stop.",
          "type": "array",
          "items": { "$ref": "#/$defs/predicate" }
        },
        "context": {
          "description": "What the agent may look at before acting (the `look at:` block).",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "files": { "type": "array", "items": { "type": "string" } },
            "docs": { "type": "array", "items": { "type": "string" } },
            "includeLastFailure": {
              "type": "boolean",
              "description": "Whether \"and the last failure\" was present.",
              "default": false
            },
            "knowledge": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Read-only reference material (`knowledge:`) the agent reads but must not edit."
            },
            "examples": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Reference patterns to imitate (`examples:`)."
            }
          }
        },
        "policy": {
          "description": "Action policy: which action classes run automatically vs require confirmation.",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "auto": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Action classes allowed without asking (e.g. [\"edit\"])."
            },
            "confirm": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Action classes that pause for human confirmation (e.g. [\"migrate\",\"push\"])."
            }
          }
        },
        "cycle": {
          "type": "array",
          "description": "The repeated steps, in order. Each step is an agent node executed by the runner.",
          "items": {
            "type": "string",
            "enum": ["plan", "act", "observe"]
          },
          "minItems": 1
        },
        "hooks": {
          "type": "array",
          "description": "Deterministic checks bound to lifecycle points (`hooks:`). A failing hook blocks.",
          "items": { "$ref": "#/$defs/hook" }
        },
        "also": {
          "type": "array",
          "description": "Extra finishing passes run in order after the goal is met (e.g. \"polish\", \"run a security check\", \"update the docs\"). Lightweight agent passes; promote to a stage when one needs its own verification.",
          "items": { "type": "string" }
        },
        "skills": {
          "type": "array",
          "description": "Named execution skills the loop may invoke during plan/act (e.g. [\"check-weather\", \"analyze-workout\"]). The runner surfaces them as available capabilities to coordinate, instead of one mega-prompt.",
          "items": { "type": "string" }
        },
        "tools": {
          "type": "array",
          "description": "MCP servers whose tools the loop may use (`use tools from the \"github\" server`).",
          "items": { "type": "string" }
        },
        "memory": {
          "description": "Cross-run memory: a markdown file the loop reads on start (its lessons feed the first plan) and appends an outcome entry to on stop.",
          "type": "object",
          "additionalProperties": false,
          "required": ["file"],
          "properties": {
            "file": { "type": "string", "description": "Markdown file, resolved relative to the loop file." }
          }
        },
        "planSource": {
          "description": "Where the `plan` step gets its plan. Default (omitted) = the agent generates it. \"file\" reads the plan from a file (`plan from \"<path>\"`), so the loop executes a plan you control. The `type` enum is open to future sources (a URL, a command).",
          "type": "object",
          "additionalProperties": false,
          "required": ["type", "path"],
          "properties": {
            "type": { "type": "string", "enum": ["file"] },
            "path": {
              "type": "string",
              "description": "For type=file: the file to read the plan from, relative to the .loop file (or the loop's target dir)."
            }
          }
        },
        "humanPlan": {
          "type": "boolean",
          "description": "\"a human approves the plan first\" — the plan step is authored/approved by a person before acting.",
          "default": false
        },
        "humanReviewBeforeStop": {
          "type": "boolean",
          "description": "\"a human reviews before stopping\" — a person judges the output and feeds the verdict back before the loop may stop.",
          "default": false
        },
        "transitions": {
          "type": "array",
          "description": "The `when ...:` rules evaluated after each observe.",
          "items": { "$ref": "#/$defs/transition" }
        },
        "git": { "$ref": "#/$defs/gitPolicy" },
        "models": { "$ref": "#/$defs/modelPolicy" }
      }
    },
    "hook": {
      "type": "object",
      "additionalProperties": false,
      "required": ["at", "predicate"],
      "properties": {
        "at": {
          "type": "string",
          "enum": ["before-cycle", "after-plan", "after-act", "after-observe", "on-commit", "on-push", "on-stop"],
          "description": "The lifecycle point this check runs at."
        },
        "predicate": { "$ref": "#/$defs/predicate" }
      }
    },
    "predicate": {
      "type": "object",
      "additionalProperties": false,
      "required": ["type"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["test", "command", "human", "skill"]
        },
        "target": {
          "type": "string",
          "description": "For type=test: the test id, e.g. \"billing.spec.ts::apostrophe\"."
        },
        "skill": {
          "type": "string",
          "description": "For type=skill: the review skill name. It is invoked to judge the goal and return an approved/score verdict (\"bridge the abstract to the verifiable\")."
        },
        "minScore": {
          "type": "integer",
          "description": "For type=skill: when present (\"scores N or more\"), the verdict passes only when the skill's numeric score is at least this. Absent means a plain approve/reject."
        },
        "subject": {
          "type": "string",
          "enum": ["output", "trajectory"],
          "description": "For type=skill (an eval): what the judge inspects — the produced \"output\" (default) or the \"trajectory\" (the path and tool calls the agent took). Set by `on the output` / `on the trajectory`."
        },
        "bar": {
          "type": "string",
          "description": "For type=skill (an eval): an inline rubric (`the bar:`) naming the conditions the judge scores against."
        },
        "command": {
          "type": "string",
          "description": "For type=command: the shell command. Default success = exit 0."
        },
        "expect": {
          "type": "string",
          "enum": ["exit-zero", "empty", "approve"],
          "description": "For type=command: \"empty\" encodes \"finds nothing\" (no stdout); defaults to exit-zero. For type=skill: \"approve\" (the verdict must be approving).",
          "default": "exit-zero"
        },
        "description": {
          "type": "string",
          "description": "For type=human: what the person should confirm."
        }
      }
    },
    "transition": {
      "type": "object",
      "additionalProperties": false,
      "required": ["on", "do"],
      "properties": {
        "on": {
          "type": "string",
          "enum": ["pass", "fail", "blocked", "attempts"],
          "description": "The observed outcome that triggers this rule."
        },
        "requireGoalMet": {
          "type": "boolean",
          "description": "For on=pass: only fire when doneWhen is also satisfied (\"when it passes and the goal is met\").",
          "default": false
        },
        "threshold": {
          "type": "integer",
          "description": "For on=attempts: fire once the attempt count exceeds this (\"after 6 tries\")."
        },
        "do": {
          "type": "array",
          "description": "Actions to run, in order.",
          "items": { "$ref": "#/$defs/action" },
          "minItems": 1
        }
      }
    },
    "action": {
      "type": "object",
      "additionalProperties": false,
      "required": ["action"],
      "properties": {
        "action": {
          "type": "string",
          "enum": ["stop", "reflect", "plan", "act", "observe", "ask-human"]
        },
        "focus": {
          "type": "string",
          "description": "For reflect: what to reflect on (\"which layer broke\")."
        },
        "warn": {
          "type": "string",
          "description": "For stop: an optional warning message (\"thrashing\")."
        }
      }
    },
    "flow": {
      "type": "object",
      "additionalProperties": false,
      "required": ["kind", "name", "steps"],
      "properties": {
        "kind": { "const": "flow" },
        "name": { "type": "string" },
        "steps": {
          "type": "array",
          "description": "Files run in order, fail-fast; each step's text summary carries to the next.",
          "items": { "$ref": "#/$defs/flowStep" }
        }
      }
    },
    "flowStep": {
      "type": "object",
      "additionalProperties": false,
      "required": ["ref", "name"],
      "properties": {
        "ref": { "type": "string", "description": "File path as written, resolved relative to the flow file." },
        "name": { "type": "string", "description": "Step name = ref basename without extension." },
        "gate": {
          "type": ["object", "null"],
          "additionalProperties": false,
          "properties": { "message": { "type": "string" } }
        },
        "fromStep": { "type": "string", "description": "'with the result of <name>' — upstream source override." },
        "forEach": {
          "type": "object",
          "additionalProperties": false,
          "required": ["var", "source"],
          "properties": {
            "var": { "type": "string", "description": "LoopFlow variable name (e.g. \"story\")." },
            "source": { "type": "string", "description": "Data file to enumerate (.yaml/.yml/.md), relative to the flow file." }
          },
          "description": "Present when this step iterates: run `ref` once per item enumerated from `source`."
        }
      }
    },
    "modelPolicy": {
      "type": "object",
      "additionalProperties": false,
      "description": "Per-phase model tiering. Two tiers (fast/strong) auto-assigned by phase; cascades file→loop→stage.",
      "properties": {
        "tiers": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "fast": { "type": "string", "description": "model alias/id for the fast tier" },
            "strong": { "type": "string", "description": "model alias/id for the strong tier" }
          }
        },
        "phases": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "plan": { "type": "string", "enum": ["fast", "strong"] },
            "act": { "type": "string", "enum": ["fast", "strong"] },
            "reflect": { "type": "string", "enum": ["fast", "strong"] },
            "also": { "type": "string", "enum": ["fast", "strong"] }
          }
        }
      }
    },
    "gitPolicy": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "isolation": {
          "type": "string",
          "enum": ["in-place", "branch", "worktree"],
          "description": "How the agent isolates its work. \"branch\" = a new git branch; \"worktree\" = a git worktree; \"in-place\" = no isolation."
        },
        "branch": {
          "type": "string",
          "description": "Branch or worktree name when isolation is \"branch\" or \"worktree\"."
        },
        "commit": {
          "type": "string",
          "enum": ["done", "cycle", "story", "never"],
          "description": "When to commit. \"done\" = after goal is met; \"cycle\" = after each cycle; \"story\" = after each story; \"never\" = never."
        },
        "push": {
          "type": "boolean",
          "description": "Whether to push to remote when done."
        },
        "openPr": {
          "type": "boolean",
          "description": "Whether to open a pull request when done."
        }
      }
    }
  }
}