Loop template

not tested yetcatalog data (JSON)

Landscape Watch Loop

Loopmaster's own instance of the research-watch template. Polls the AI loop / agent-tooling landscape (frameworks, protocols, labs) weekly and turns new, high-signal changes into cited findings reports in docs/research/. Findings publish autonomously; public positioning or recommendation changes require human approval.

Human guide

Raw README.md

Loopmaster maintenance loops

This directory contains Loopmaster's own self-maintenance loop manifests. Each *.loop.yaml file declares a recurring maintenance loop using the draft v0.1 manifest format in spec/loop-spec-v0.1.md.

Current loops:

  • link-audit.loop.yaml — checks documentation and resource URLs, writes reports to loops/log/, and escalates non-trivial source replacement.
  • landscape-watch.loop.yaml — Loopmaster's own instance of the research-watch template. Polls the AI loop / agent-tooling landscape weekly and writes cited findings reports to docs/research/. Findings publish autonomously; public positioning or recommendation changes require maintainer approval.
  • resource-discovery.loop.yaml — sweeps committed sources plus rotating queries weekly, dedupes against the resource library, writes candidate reports to loops/log/, and records review-only proposal YAML under loops/proposals/. Publishing entries to resources/resources.yaml is gated.
  • loopmaster-content-freshness.loop.yaml — Loopmaster's own instance of the content-freshness template. Audits public docs, learning content, template guides, maintenance logs, and resource metadata monthly, writes dated reports to loops/log/, and keeps rewrites/deletions/product-positioning changes human-gated.

Scheduled runs use GitHub Actions where possible so audit evidence, safe automated changes, and failures remain visible in the repository history.

The job description (loop.yaml)

View raw loop.yaml

loops/landscape-watch.loop.yaml

spec_version: "0.1"
id: landscape-watch
name: Landscape Watch Loop
purpose: >
  Loopmaster's own instance of the research-watch template. Polls the AI loop /
  agent-tooling landscape (frameworks, protocols, labs) weekly and turns new,
  high-signal changes into cited findings reports in docs/research/. Findings
  publish autonomously; public positioning or recommendation changes require
  human approval.
# Instance of templates/research-watch/loop.yaml. Spec v0.1 has no `template`
# field (additionalProperties is false), so the instance-of relationship is
# expressed via inputs.files and verification.commands pointing at the shared
# runner. Tracked as friction against lm-tpl-01.
audience: [human, agent, operator]
trigger:
  type: schedule
  default: weekly
  schedule: "30 9 * * 1"
inputs:
  sources:
    - type: rss
      name: Lab and practitioner engineering feeds
      url: loops/sources/landscape-watch.json
    - type: url
      name: Stable framework and protocol documentation pages
      url: loops/sources/landscape-watch.json
    - type: github_repo
      name: Agent framework repositories
      url: loops/sources/landscape-watch.json
  files:
    - loops/sources/landscape-watch.json
    - templates/research-watch/scripts/research_watch.py
capabilities:
  - polling
  - source_summarization
  - dedupe
  - cited_reporting
  - task_creation
permissions:
  allowed_actions:
    - read_web
    - read_repo
    - write_report
    - write_state
    - create_proposal_branch
    - create_task
  forbidden_actions:
    - publish_publicly_without_approval
    - spend_money
    - delete_user_data
    - mutate_source_systems
    - change_public_positioning_without_approval
  credential_scopes:
    - repo:contents:write
    - pull_request:write
    - kanban:create
state:
  paths:
    - .loopmaster/state/landscape-watch.json
  retention: 90 days
outputs:
  artifacts:
    - docs/research/YYYY-MM-DD-landscape-watch.md
  notifications:
    - run_summary
  tasks:
    - kanban_card_for_high_signal_finding
verification:
  required:
    - every reported item includes a source URL or repo-relative source path
    - report records whether it acted autonomously or needs approval
    - state file prevents duplicate reporting on repeated runs
    - public publishing and product direction changes remain human-gated
  commands:
    - name: validate loop manifest
      run: uv run --with check-jsonschema --with pyyaml check-jsonschema --schemafile spec/loop.schema.json loops/landscape-watch.loop.yaml
      expected: exits 0 and prints ok -- validation done
    - name: dry-run runner against landscape sources
      run: python3 templates/research-watch/scripts/research_watch.py --report-basename landscape-watch --sources loops/sources/landscape-watch.json --state .loopmaster/state/landscape-watch.json --output-dir docs/research
      expected: exits 0 and prints RESEARCH_WATCH_REPORT and RESEARCH_WATCH_STATE paths
human_gates:
  required_for:
    - public publishing
    - product direction changes
    - public positioning or recommendation changes
    - credential changes
    - merging proposed resource entries
  approver: maintainer
failure_policy:
  retry: 2
  escalate_after: repeated_fetch_or_validation_failure
  rollback: leave the previous state file unchanged when report generation fails; delete only the failed run artifact after recording the error
maintenance:
  freshness_cadence: weekly
  owner: Loopmaster maintainers
  audit_log: loops/log/
backends:
  github_actions:
    schedule: "30 9 * * 1"
    workflow: .github/workflows/landscape-watch.yml
    install_notes:
      - Chosen scheduler is GitHub Actions cron so maintenance evidence lives with the repository.
      - Weekly runs write a dated report to docs/research/, update .loopmaster/state/landscape-watch.json, and open a PR with those changes.
      - Per the research-watch template AGENT-INSTALL.md, no web-search credential is required; the loop only polls public RSS/URL/repo sources.
      - Reuses templates/research-watch/scripts/research_watch.py with --report-basename landscape-watch so reports do not collide with other research-watch instances.
  agent_kanban:
    task_template: Create a weekly landscape-watch task that runs the helper, reviews the report, and creates follow-up cards only for high-signal findings.
    install_notes:
      - Kanban installation assigns a recurring agent task; the agent still runs the same helper and verification commands.

Install guide (for your agent)

Raw for agents

Installing Loopmaster maintenance loops

The link audit loop is installed through .github/workflows/link-audit.yml.

What the schedule does:

  1. Runs uv run --with pyyaml python tools/link_audit.py --write from the repository root every Monday at 10:23 UTC.
  2. Writes a five-part report to loops/log/YYYY-MM-DD-link-audit.md.
  3. Commits the report plus safe autonomous updates, limited to same-host/trivial redirect rewrites and resources/resources.yaml status or last_verified stamps.
  4. Fails the workflow when a dead link is detected so maintainers see the escalation.

Manual run:

uv run --with pyyaml python tools/link_audit.py --write

Dead-link probe:

uv run --with pyyaml python tools/link_audit.py --no-report --extra-url https://example.com/__loopmaster_dead_link_probe__

Human gate: do not replace a source with a different source autonomously. Record the dead or non-trivial replacement in the report and let a maintainer approve the change.

Landscape watch

The landscape watch loop is an instance of the research-watch template (templates/research-watch/loop.yaml). It is installed through .github/workflows/landscape-watch.yml and reuses templates/research-watch/scripts/research_watch.py.

What the schedule does:

  1. Runs python3 templates/research-watch/scripts/research_watch.py --report-basename landscape-watch --sources loops/sources/landscape-watch.json --state .loopmaster/state/landscape-watch.json --output-dir docs/research from the repository root every Monday at 09:30 UTC.
  2. Polls public RSS, URL, and GitHub-repo sources listed in loops/sources/landscape-watch.json (OpenAI, Hugging Face, Karpathy, Anthropic, LangChain, CrewAI, OpenAI Agents SDK, AutoGen, LangGraph, A2A, MCP, and the matching repos).
  3. Dedupes against .loopmaster/state/landscape-watch.json so repeated runs do not re-report seen items.
  4. Writes a dated, cited, five-part report to docs/research/YYYY-MM-DD-landscape-watch.md.
  5. Opens a pull request with the report and state changes. No web-search credential is required.

Manual run:

python3 templates/research-watch/scripts/research_watch.py \
  --report-basename landscape-watch \
  --sources loops/sources/landscape-watch.json \
  --state .loopmaster/state/landscape-watch.json \
  --output-dir docs/research

Dedupe check (second run reports NEW_ITEMS=0):

python3 templates/research-watch/scripts/research_watch.py \
  --report-basename landscape-watch \
  --sources loops/sources/landscape-watch.json \
  --state .loopmaster/state/landscape-watch.json \
  --output-dir docs/research

Human gate: findings publish autonomously; changes to public recommendations, positioning, or product direction require maintainer approval. Do not merge the report PR if it changes Loopmaster's public positioning.

Resource discovery

The resource-discovery loop (loops/resource-discovery.loop.yaml) is an instance of the research-watch pattern tuned for resource-library proposals. Its concrete runner is tools/resource_discovery.py, and the scheduled backend is .github/workflows/resource-discovery.yml.

What the schedule does:

  1. Runs uv run --with pyyaml python tools/resource_discovery.py --sources loops/resource-discovery.sources.json --state .loopmaster/state/resource-discovery.json --output-dir loops/log --resources resources/resources.yaml --max-items 5 every Monday at 09:30 UTC.
  2. Dedupes against both resources/resources.yaml and .loopmaster/state/resource-discovery.json.
  3. Writes a five-part report to loops/log/YYYY-MM-DD-resource-discovery.md and updates the state ledger.
  4. Opens a review-only pull request with report/state changes; scored proposal YAML can be added by an agent or maintainer after applying resources/RUBRIC.md.

Manual run:

uv run --with pyyaml python tools/resource_discovery.py \
  --sources loops/resource-discovery.sources.json \
  --state .loopmaster/state/resource-discovery.json \
  --output-dir loops/log \
  --resources resources/resources.yaml \
  --max-items 5 \
  --exploratory "rotating queries this run: ..."

Expected output shape:

RESOURCE_DISCOVERY_REPORT=loops/log/YYYY-MM-DD-resource-discovery.md
RESOURCE_DISCOVERY_STATE=.loopmaster/state/resource-discovery.json
NEW_CANDIDATES=<n>
FETCH_ERRORS=<n>

Dedupe verification: run the same command a second time against the same state and expect NEW_CANDIDATES=0.

Scoring and proposing: after a run with NEW_CANDIDATES > 0, score each candidate against resources/RUBRIC.md (five dimensions, 0–2 each). Write ready-to-merge YAML for candidates scoring ≥7 with no dimension at 0 into loops/proposals/YYYY-MM-DD-resource-discovery.proposal.yaml, and record at least one rejected candidate with scores to prove the rubric has teeth.

Human gate: do not merge proposed entries into resources/resources.yaml without maintainer approval. Proposing is autonomous; publishing is gated.

Content freshness

The content-freshness loop (loops/loopmaster-content-freshness.loop.yaml) is Loopmaster's own instance of the content-freshness template. Its concrete runner is templates/content-freshness/scripts/content_freshness.py, configured by loops/content-freshness.targets.json, and the scheduled backend is .github/workflows/content-freshness.yml.

What the schedule does:

  1. Runs python3 templates/content-freshness/scripts/content_freshness.py --targets loops/content-freshness.targets.json --state .loopmaster/state/content-freshness.json --output-dir loops/log --max-link-checks 40 monthly at 10:00 UTC on the first day of the month.
  2. Scans public docs, authored site content, template guides, maintenance-loop docs, and resource metadata for stale files, stale markers, and checked-link failures.
  3. Writes a dated report to loops/log/YYYY-MM-DD-content-freshness.md and updates .loopmaster/state/content-freshness.json.
  4. Opens a review-only pull request with the report and state changes.

Manual run:

python3 templates/content-freshness/scripts/content_freshness.py \
  --targets loops/content-freshness.targets.json \
  --state .loopmaster/state/content-freshness.json \
  --output-dir loops/log \
  --max-link-checks 40

Expected output shape:

CONTENT_FRESHNESS_REPORT=loops/log/YYYY-MM-DD-content-freshness.md
CONTENT_FRESHNESS_STATE=.loopmaster/state/content-freshness.json
FINDINGS=<n>
AUDIT_ERRORS=<n>
LINKS_CHECKED=<n>

Human gate: the loop may report stale evidence, broken links, and source-backed recommendations. Do not rewrite public copy, delete content, or change product positioning without maintainer approval.

How we know it works

Status
not tested yet
Date
not tested yet
Stale after
—

no dated passing checks found under verification/

    What it's allowed to do

    6 allowed action(s), 5 forbidden action(s), 3 credential scope(s)

    Allowed actions
    read_web, read_repo, write_report, write_state, create_proposal_branch, create_task
    Credential scopes
    repo:contents:write, pull_request:write, kanban:create
    Forbidden actions
    publish_publicly_without_approval, spend_money, delete_user_data, mutate_source_systems, change_public_positioning_without_approval