Agent surface

Agent guide

This guide is for agents that are given only the Loopmaster repository URL and need to choose, install, and verify a loop template without human hand-holding.

Repository URL:

  • https://github.com/chrismaddern/loopmaster.ai

Raw fetch base for direct file reads:

  • https://raw.githubusercontent.com/chrismaddern/loopmaster.ai/main/

Six-step flow

1. Discover

Fetch the agent entry point, then the generated catalog.

Exact paths:

  • llms.txt
  • registry/index.json

Raw URLs:

  • https://raw.githubusercontent.com/chrismaddern/loopmaster.ai/main/llms.txt
  • https://raw.githubusercontent.com/chrismaddern/loopmaster.ai/main/registry/index.json

Use llms.txt for the repo usage contract and registry/index.json for structured fields: id, name, purpose, triggers, permissions, verification, manifest_path, install_path, and doc_path.

2. Select

Match the user's goal against the catalog entry fields.

Use these fields first:

  • purpose — what the loop is for.
  • triggers — when it should run.
  • backends — supported runtimes such as cron, github_actions, or agent_kanban.
  • permissions.summary, permissions.allowed_actions, permissions.forbidden_actions, and permissions.credential_scopes — whether the loop is safe and possible in the current environment.
  • verification.status, verification.date, and verification.evidence_path — whether the loop has current positive evidence.

Do not silently substitute a different template. If no template matches the goal, report the gap or create an appropriately scoped follow-up task.

3. Read

For the selected template, fetch both the machine contract and the install guide from the paths in the catalog.

Example: research-watch.

  • Manifest path: templates/research-watch/loop.yaml
  • Install path: templates/research-watch/AGENT-INSTALL.md
  • Human guide path: templates/research-watch/README.md

Raw URLs:

  • https://raw.githubusercontent.com/chrismaddern/loopmaster.ai/main/templates/research-watch/loop.yaml
  • https://raw.githubusercontent.com/chrismaddern/loopmaster.ai/main/templates/research-watch/AGENT-INSTALL.md
  • https://raw.githubusercontent.com/chrismaddern/loopmaster.ai/main/templates/research-watch/README.md

Treat loop.yaml as the authority for what the loop may do. Treat AGENT-INSTALL.md as the authority for exact setup commands, expected outputs, and backend-specific wiring.

4. Install

Create only the files, state paths, schedules, tasks, or workflow entries declared by the selected template and install guide.

Before writing or scheduling anything, check:

  • inputs for required source files, environment variables, and runtime files.
  • state.paths for persistent state locations.
  • outputs for expected reports, notifications, and task creation.
  • backends for the chosen runtime's install notes.
  • human_gates.required_for for actions that require approval.

If a credential is missing, do not invent it or broaden scope. Stop at the relevant human gate and report the exact missing scope.

5. Verify

Run the selected template's verification.commands and check every verification.required assertion before reporting success.

Example: research-watch manifest validation command from templates/research-watch/loop.yaml:

uv run --with check-jsonschema --with pyyaml check-jsonschema --schemafile spec/loop.schema.json templates/research-watch/loop.yaml

Example: research-watch local dry run from the same manifest:

python3 templates/research-watch/scripts/research_watch.py --sources templates/research-watch/examples/dry-run-sources.json --state /tmp/loopmaster-research-watch-state.json --output-dir /tmp/loopmaster-research-watch --max-items 5

A successful install report should name the commands run, exit codes, key output paths, and any assertions that could not be checked.

6. Escalate

Escalate instead of guessing when any of these happen:

  • A human_gates.required_for action is needed.
  • A required credential or permission scope is missing.
  • A verification command fails.
  • The template asks to spend money, publish publicly, delete data, mutate source systems, or change public positioning.
  • The install guide and manifest disagree.
  • The registry marks the chosen entry unverified or its evidence is stale, and the user asked for a proven loop.

When escalating, include the selected template id, the exact path or field that caused the stop, what was already fetched, and the next safe action.

Three-fetch manifest reachability test

An agent with only the repository URL can reach a chosen template manifest in three fetches:

  1. GET https://raw.githubusercontent.com/chrismaddern/loopmaster.ai/main/llms.txt
  2. GET https://raw.githubusercontent.com/chrismaddern/loopmaster.ai/main/registry/index.json
  3. Read templates[].manifest_path for the chosen id, then GET https://raw.githubusercontent.com/chrismaddern/loopmaster.ai/main/<manifest_path>.

For research-watch, fetch 3 is:

  • https://raw.githubusercontent.com/chrismaddern/loopmaster.ai/main/templates/research-watch/loop.yaml

The same pattern works for every catalog entry that includes manifest_path.