Loopmaster loop.yaml Specification v0.1

Status: draft

This document defines the draft v0.1 Loopmaster loop manifest format. It is descriptive and backend-agnostic: a manifest declares what a loop needs, may do, must verify, and when it must escalate; backend-specific install instructions live in adjacent docs and in the backends hint section.

v0.1 remains draft until LM-RETRO-01. Template authors MAY propose changes while the first Phase 0 templates are being written. Consumers MUST NOT treat v0.1 as frozen until the retro explicitly freezes it.

1. Conformance language

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, MAY, and OPTIONAL are to be interpreted as normative requirements for v0.1 manifests.

A conforming manifest:

• MUST be named loop.yaml for templates, or <id>.loop.yaml for Loopmaster's own maintenance loops.
• MUST validate against spec/loop.schema.json.
• MUST set spec_version to the string "0.1".
• MUST NOT include unknown top-level keys.
• MUST include at least one permission in permissions.allowed_actions.
• SHOULD keep field values short enough for an agent to read the whole manifest in one context window.
• SHOULD keep prose documentation and manifest fields consistent: every operational claim in prose should map to a manifest field, and every manifest field should be explained by the human or agent install docs.

2. Manifest shape

Top-level fields are deliberately small and stable. Optional fields are omitted when they do not add useful installation or safety information.

Field	Type	Required	Example	Definition
spec_version	string	yes	"0.1"	Manifest spec version. v0.1 manifests MUST use the exact string "0.1".
id	string	yes	research-watch	Stable kebab-case identifier. It SHOULD match the template directory name.
name	string	yes	Research Watch Loop	Human-readable display name.
purpose	string	yes	Monitor sources and turn high-signal changes into cited findings or tasks.	One-sentence description of the loop's job and outcome.
audience	array of enum strings	yes	[human, agent]	Primary consumers. Allowed values: human, agent, operator, team.
trigger	object	yes	{type: schedule, default: daily}	What starts the loop. See §3.
inputs	object	no	{sources: [{type: rss}]}	External sources, files, or environment variables the loop reads. See §4.
capabilities	array of strings	no	[polling, source_summarization, task_creation]	Runtime or agent-harness capabilities needed to execute the loop.
permissions	object	yes	{allowed_actions: [read_web, write_report]}	Actions the loop may and may not take. See §5.
state	object	yes	{paths: [.loopmaster/state/research-watch.json]}	Durable state paths used for dedupe, memory, progress, or audit correlation.
outputs	object	yes	{artifacts: [docs/research/YYYY-MM-DD-findings.md]}	Files, notifications, or tasks the loop emits.
verification	object	yes	{required: [every finding has a source URL], commands: [{run: python3 tools/check.py}]}	Declarative success criteria plus executable checks.
human_gates	object	yes	{required_for: [public publishing]}	Conditions that require a human or reviewer before acting.
failure_policy	object	yes	{retry: 2, escalate_after: repeated_provider_failure}	Retry, escalation, and rollback behavior.
maintenance	object	yes	{freshness_cadence: weekly}	How often the template or loop should be reviewed for rot.
backends	object	yes	{cron: {schedule: daily}}	Runtime-specific install hints for supported backends.

3. trigger

trigger declares what starts the loop. It is a contract, not the scheduler implementation.

Field	Type	Required	Example	Definition
trigger.type	enum string	yes	schedule	One of schedule, webhook, manual, user_goal, ci_event, issue_event, feed_change.
trigger.default	string	no	daily	Human-readable default cadence or starter condition.
trigger.schedule	string	no	0 9 * * 1	Concrete schedule hint when the trigger is schedule-like.
trigger.event	string	no	pull_request.failed_check	Event name when the trigger is event-like.

4. inputs

inputs is OPTIONAL because some loops operate only on local state or a user goal. When present, it MUST contain at least one of the fields below.

Field	Type	Required	Example	Definition
inputs.sources	array of source objects	no	[{type: web_search, query: agent loop engineering}]	External or internal systems the loop reads.
inputs.environment_variables	array of strings	no	[GITHUB_TOKEN]	Environment variable names required by the loop. Values MUST NOT appear in the manifest.
inputs.files	array of strings	no	[resources/SOURCES.md]	Repo-relative or documented runtime paths the loop reads.

Source object fields:

Field	Type	Required	Example	Definition
type	enum string	yes	rss	One of rss, web_search, github_repo, url, file, api, database, kanban, calendar.
name	string	no	Anthropic engineering blog	Human-readable source label.
url	string	no	https://www.anthropic.com/engineering	Source URL.
query	string	no	agent loop engineering	Search query or API query.
path	string	no	docs/research/loop-landscape.md	File or state path.

5. permissions

permissions is REQUIRED because safety is part of the product. Empty permissions are invalid.

Field	Type	Required	Example	Definition
permissions.allowed_actions	array of strings	yes	[read_web, write_report, create_task]	Actions the loop may perform autonomously. MUST contain at least one item.
permissions.forbidden_actions	array of strings	no	[publish_publicly_without_approval, spend_money]	Actions the loop MUST NOT perform autonomously.
permissions.credential_scopes	array of strings	no	[read:repo, issues:write]	Credential scopes needed. Names only; never include secret values.

6. state

state is REQUIRED so loops can dedupe, resume, and produce an audit trail.

Field	Type	Required	Example	Definition
state.paths	array of strings	yes	[.loopmaster/state/research-watch.json]	Files or stores where durable loop state is written.
state.retention	string	no	90 days	How long state should be kept before pruning or archiving.

7. outputs

outputs is REQUIRED and MUST contain at least one output category.

Field	Type	Required	Example	Definition
outputs.artifacts	array of strings	no	[docs/research/YYYY-MM-DD-findings.md]	Files or structured artifacts the loop writes.
outputs.notifications	array of strings	no	[summary]	Notifications the loop may send.
outputs.tasks	array of strings	no	[kanban_card_for_high_signal_finding]	Task or issue outputs the loop may create.

8. verification

verification is REQUIRED. It combines human-readable assertions with commands that agents and CI can execute.

Field	Type	Required	Example	Definition
verification.required	array of strings	yes	[every finding has a source URL]	Declarative acceptance criteria.
verification.commands	array of command objects	yes	[{name: validate findings, run: python3 tools/check_findings.py}]	Executable checks. MUST contain at least one command.

Command object fields:

Field	Type	Required	Example	Definition
name	string	no	validate findings	Human-readable check name.
run	string	yes	python3 tools/check_findings.py	Command to execute from the documented working directory.
expected	string	no	exits 0 and prints OK	Expected success signal.

9. human_gates

human_gates is REQUIRED. A loop that appears to need no approval SHOULD still declare the boundary that would make it unsafe.

Field	Type	Required	Example	Definition
human_gates.required_for	array of strings	yes	[public publishing, credential changes]	Conditions that MUST stop for human or reviewer approval.
human_gates.approver	string	no	maintainer	Role or person expected to approve gated actions.

10. failure_policy

failure_policy is REQUIRED so agents know when to retry and when to stop.

Field	Type	Required	Example	Definition
failure_policy.retry	integer	yes	2	Maximum retry attempts before escalation.
failure_policy.escalate_after	string	yes	repeated_provider_failure	Condition or class of failure that triggers escalation.
failure_policy.rollback	string	no	revert the proposal branch and leave the previous state file unchanged	Rollback or recovery guidance.

11. maintenance

maintenance is REQUIRED because loop rot is an expected failure mode.

Field	Type	Required	Example	Definition
maintenance.freshness_cadence	string	yes	weekly	How often to review this loop/template for source, API, model, or process drift.
maintenance.owner	string	no	Loopmaster maintainers	Owner responsible for maintenance.
maintenance.audit_log	string	no	loops/log/	Where maintenance evidence is recorded.

12. backends

backends is REQUIRED and MUST contain at least one supported backend hint. Hints are not executable adapters; they tell an installer where the manifest maps onto runtime-specific setup.

Allowed backend keys in v0.1 are cron, github_actions, and agent_kanban.

Field	Type	Required	Example	Definition
backends.cron	backend hint object	no	{schedule: daily}	Installation hints for cron-like schedulers.
backends.github_actions	backend hint object	no	{workflow: .github/workflows/research-watch.yml}	Installation hints for GitHub Actions.
backends.agent_kanban	backend hint object	no	{task_template: Create a weekly research watch task}	Installation hints for agent task boards such as Hermes kanban.

Backend hint fields:

Field	Type	Required	Example	Definition
schedule	string	no	daily	Cadence or cron expression.
workflow	string	no	.github/workflows/research-watch.yml	Workflow file or runtime entry point.
task_template	string	no	Create a weekly research-watch task assigned to researcher	Task prompt or template hint.
install_notes	array of strings	no	[Run from repo root]	Backend-specific setup notes.

13. Worked example

This example updates the R1 §7 research-watch manifest to v0.1. It is intentionally still a draft template shape, but it validates against spec/loop.schema.json.

spec_version: "0.1"
id: research-watch
name: Research Watch Loop
purpose: Monitor sources and turn high-signal changes into cited findings or tasks.
audience: [human, agent]
trigger:
  type: schedule
  default: daily
  schedule: "0 9 * * *"
inputs:
  sources:
    - type: rss
      name: practitioner blogs
    - type: web_search
      query: agent loop engineering
    - type: github_repo
      url: https://github.com/anthropics/claude-cookbooks
capabilities:
  - polling
  - source_summarization
  - dedupe
  - task_creation
permissions:
  allowed_actions:
    - read_web
    - write_report
    - create_task
  forbidden_actions:
    - publish_publicly_without_approval
    - spend_money
    - delete_user_data
  credential_scopes:
    - web:read
    - kanban:create
state:
  paths:
    - .loopmaster/state/research-watch.json
  retention: 90 days
outputs:
  artifacts:
    - docs/research/YYYY-MM-DD-findings.md
  notifications:
    - summary
  tasks:
    - kanban_card_for_high_signal_finding
verification:
  required:
    - every finding has a source URL
    - no duplicate finding from previous state
    - recommendations include confidence/risk
  commands:
    - name: validate findings report
      run: python3 tools/validate_findings.py docs/research/YYYY-MM-DD-findings.md
      expected: exits 0 and prints OK
human_gates:
  required_for:
    - public publishing
    - product direction changes
    - credential changes
  approver: maintainer
failure_policy:
  retry: 2
  escalate_after: repeated_provider_failure
  rollback: leave prior state file unchanged and report partial findings only
maintenance:
  freshness_cadence: weekly
  owner: Loopmaster maintainers
  audit_log: loops/log/
backends:
  cron:
    schedule: daily
    install_notes:
      - Run from the repository root.
  github_actions:
    workflow: .github/workflows/research-watch.yml
  agent_kanban:
    task_template: Create a weekly research-watch task assigned to researcher.

14. Versioning notes

v0.1 is expected to change while the Phase 0 templates exercise it. Backward-incompatible changes SHOULD be recorded in spec/CHANGELOG.md. Unknown spec_version values MUST be rejected by v0.1 validators.