Loop template

not tested yetcatalog data (JSON)

Loopmaster Content Freshness Loop

Check Loopmaster's public docs, learning content, resource metadata, and loop guides for stale claims, broken links, and unresolved freshness markers; report proposals without rewriting public positioning autonomously.

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/loopmaster-content-freshness.loop.yaml

spec_version: "0.1"
id: loopmaster-content-freshness
name: Loopmaster Content Freshness Loop
purpose: Audit Loopmaster's public docs, learning content, resource metadata, and loop guides for stale claims, broken links, and unresolved freshness markers; report proposals without rewriting public positioning autonomously.
audience:
  - human
  - agent
  - operator
trigger:
  type: schedule
  default: monthly
  schedule: "0 10 1 * *"
inputs:
  sources:
    - type: file
      name: Loopmaster freshness target configuration
      path: loops/content-freshness.targets.json
    - type: file
      name: Shared content-freshness runner
      path: templates/content-freshness/scripts/content_freshness.py
  files:
    - loops/content-freshness.targets.json
    - templates/content-freshness/scripts/content_freshness.py
    - docs/
    - content/
    - templates/
    - resources/resources.yaml
    - loops/log/
capabilities:
  - content_audit
  - link_checking
  - stale_claim_detection
  - source_backed_reporting
  - proposal_creation
permissions:
  allowed_actions:
    - read_repo
    - read_web
    - write_report
    - write_state
    - create_proposal_branch
    - create_task
  forbidden_actions:
    - publish_publicly_without_approval
    - rewrite_content_without_review
    - change_public_positioning_without_approval
    - spend_money
    - delete_user_data
    - mutate_source_systems
  credential_scopes:
    - repo:contents:write
    - pull_request:write
    - kanban:create
state:
  paths:
    - .loopmaster/state/content-freshness.json
  retention: 180 days
outputs:
  artifacts:
    - loops/log/YYYY-MM-DD-content-freshness.md
  notifications:
    - run_summary
  tasks:
    - kanban_card_for_review_required_update
verification:
  required:
    - every finding cites a repo-relative file path, URL, or explicit source check
    - broken or skipped link checks are separated from stale-content findings
    - report records whether it only proposed changes or needs human approval
    - public publishing, positioning changes, and content rewrites remain human-gated
    - state file records last run counts and does not hide repeated unresolved findings
  commands:
    - name: validate loop manifest
      run: uv run --with check-jsonschema --with pyyaml check-jsonschema --schemafile spec/loop.schema.json loops/loopmaster-content-freshness.loop.yaml
      expected: exits 0 and prints ok -- validation done
    - name: run Loopmaster content freshness audit
      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: exits 0, writes loops/log/YYYY-MM-DD-content-freshness.md, and prints CONTENT_FRESHNESS_REPORT plus CONTENT_FRESHNESS_STATE paths
human_gates:
  required_for:
    - public publishing
    - content rewrites
    - product positioning changes
    - deleting stale content
    - credential changes
  approver: maintainer
failure_policy:
  retry: 2
  escalate_after: repeated_fetch_or_validation_failure
  rollback: leave previous content untouched; remove only failed run artifacts after recording the error; close or revert any bad proposal PR
maintenance:
  freshness_cadence: monthly
  owner: Loopmaster maintainers
  audit_log: loops/log/
backends:
  github_actions:
    schedule: "0 10 1 * *"
    workflow: .github/workflows/content-freshness.yml
    install_notes:
      - Chosen scheduler is GitHub Actions cron so maintenance evidence lives with the repository.
      - Monthly runs write a dated audit report to loops/log/, update .loopmaster/state/content-freshness.json, and open a review-only pull request.
      - The workflow may report findings and propose follow-up tasks; it must not rewrite public positioning or publish corrections without maintainer approval.
  agent_kanban:
    task_template: Create a monthly content-freshness task that runs the helper, reviews findings, and creates follow-up cards only for source-backed updates requiring human review.
    install_notes:
      - Kanban installation assigns a recurring agent task; the agent still runs the same helper and verification commands.
      - The agent may report and propose; content rewrites, deletions, and product positioning changes remain human-gated.

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), 6 forbidden action(s), 3 credential scope(s)

    Allowed actions
    read_repo, read_web, 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, rewrite_content_without_review, change_public_positioning_without_approval, spend_money, delete_user_data, mutate_source_systems