Your first loop in 15 minutes

This is the do-it guide: you (a human, or an agent acting for one) go from zero to a running, verified research-watch loop. It does not duplicate the template's install docs or the skill pack's commands — it links to them and walks the shape. Expect roughly fifteen minutes if your prerequisites are already met; if they aren't, the time is in the prerequisites, not the loop.

For agents: - The fastest path is the skill pack — fetch the raw SKILL.md from /skills, run its prerequisite checks, follow the backend branch matching your runtime, then execute the manifest's verification.commands and report evidence. - The manifest is the contract: read templates/research-watch/loop.yaml first; field definitions are at /spec. - If any step's expected output doesn't match, stop and report the divergence rather than improvising. - Do not mark your own install verified — that flip belongs to a separate checker or a human (module 4).

What you'll build

A research-watch loop on sources you choose: a scheduled sweep that turns source changes into deduped, cited findings, and proposes follow-up tasks — nothing published without you. This is the research-watch template, whose manifest declares the trigger, inputs, permissions, state, verification, and gates.

Set expectations honestly. "~15 minutes" assumes you have a repo, a scheduler, and the credentials the manifest declares. If you are starting from a clean machine, the prerequisites are the long part, and that's normal.

Before you start

Prerequisites, checked before you touch the template:

• A repository to install into — the loop writes reports and state into repo paths.
• A scheduler: cron on a machine with a persistent checkout, GitHub Actions on a repo

that can run scheduled workflows, or an agent task board (Hermes kanban). The manifest's backends section lists all three; pick one.

• Credentials the manifest declares — read inputs.environment_variables in

templates/research-watch/loop.yaml before installing. If you cannot supply a declared credential, the AGENT-INSTALL has a documented branch for running on public sources only.

• The spec and schema — spec/loop.schema.json is what the manifest validates against;

the verification commands use it.

When a loop must stop and ask you covers why credential scope is a gate, not a chore: read the required scopes before you install, not after a surprise.

Install

The template and its install docs live at templates/research-watch/. This guide gives the anchor steps; the exact commands are in the template's AGENT-INSTALL.md and the skill pack at /skills. One representative command per step — follow the linked docs for the full path.

1. Get the template. Copy templates/research-watch/ into your repo. The skill pack

(/skills) has a prerequisite checker that confirms the files are in place; run it before proceeding. Representative check:

``sh test -f templates/research-watch/loop.yaml && \ test -f templates/research-watch/AGENT-INSTALL.md ``

1. Prepare inputs and state. Create the source list, the selection rules, and the state file the

manifest declares. AGENT-INSTALL.md has the exact setup commands; the key paths are resources/SOURCES.md, resources/RUBRIC.md, and .loopmaster/state/research-watch.json.

1. Configure credentials without exposing values. Set the declared environment variable

in your scheduler's secret store — never in a repo file. AGENT-INSTALL.md covers the per-backend branch (cron, Actions, kanban).

1. Validate the manifest. Before binding a scheduler, confirm the manifest validates

against the schema. This is the one command worth reproducing here, because it is the gate every install must pass:

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

Expected output: ok -- validation done. If this fails, fix the manifest before installing a scheduler — a loop whose manifest does not validate is not ready.

1. Bind your backend. Follow the AGENT-INSTALL.md branch for your runtime: cron,

GitHub Actions, or agent kanban. The skill pack at /skills has the per-backend checklist and the first-week guidance.

Verify it worked

Run the manifest's verification.commands after the first run. For the research-watch template that is schema validation plus the template-docs and checklist checks declared in loop.yaml. A good first report has the five-part shape: what changed, evidence (every finding cited with a source URL), recommended action, confidence and risk, and autonomous-or-gated. Run 2 should show dedupe — no finding repeated from run 1's state. How you know it worked explains why a separate check matters.

If the checks pass but the report is empty, that can be correct: an empty run that updates state and says "no high-signal changes found" is a healthy run, not a failure. Silence is valid output; The harness: what actually does the work explains why quiet success matters.

Your first week of ownership

• Check run 1's output by hand. Read the findings, follow a couple of source links, confirm

the dedupe key is doing its job.

• Tune sources. The source list is yours; prune noisy feeds and add ones the first run

missed.

• Confirm dedupe on run 2. If run 2 re-surfaces run 1's findings, the state file isn't being

read — that's a harness bug, not a model bug; see The harness: what actually does the work.

• Decide what stays gated. The manifest declares publishing as a gate; respect it. If you

find yourself wanting to auto-publish, that's a signal to widen autonomy deliberately — see When a loop must stop and ask you — not to quietly bypass the gate.

• Know when to turn it off. If the loop keeps hitting its gate, redesign rather than

re-grant — a loop that keeps asking for approval is telling you its scope is wrong (see Loops rot: maintenance is part of the design).

Where to go next

• Browse /loops for the next template — content-freshness, CI repair, and

agent-usability loops each exercise a different pattern.

• /learn/glossary is the ongoing reference: terms plus the pattern cheat sheet

you used to choose this loop.

• Loops rot: maintenance is part of the design covers the maintenance this loop will need; schedule its

maintenance.freshness_cadence now, not later.

Sources

• docs/research/loop-landscape.md

— the landscape report behind the research-watch manifest and first-loop questions.

• templates/research-watch/AGENT-INSTALL.md

— the install path this guide points to.

• /skills

— the skill pack that performs the install checks.