Deploy your first loop

This is the flagship getting-started pack for Loopmaster. It deploys the research-watch starter template and gets you to evidence that a loop can run, write a report, update state, and avoid duplicate reporting.

Important distinction: the checked-in template is not an unattended installed loop. After copying it, customize the targets, schedule, report/state paths, and credential storage for the target repository. Do not enable a scheduler, publish findings, change product direction, or use new credentials until the install has explicit maintainer approval.

Canonical template references:

• templates/research-watch/loop.yaml — manifest, permissions, gates, state paths, backend hints, and verification command names.
• templates/research-watch/AGENT-INSTALL.md — complete backend install guide. Use it as the source of truth for backend-specific setup.
• templates/research-watch/scripts/research_watch.py — concrete runner used by every backend.
• templates/research-watch/examples/dry-run-sources.json — local-only source list for scratch verification.
• templates/research-watch/examples/sources.json — editable source list for a real installation.

Do not copy the template docs into this pack. If a command or field appears to conflict with templates/research-watch/AGENT-INSTALL.md, follow the template guide and fix this skill pack.

1. Preflight from repo root

Run these checks before choosing a backend:

test -f templates/research-watch/loop.yaml
test -f templates/research-watch/AGENT-INSTALL.md
test -f templates/research-watch/scripts/research_watch.py
python3 templates/research-watch/scripts/research_watch.py --help >/tmp/loopmaster-research-watch-help.txt
uv run --with check-jsonschema --with pyyaml check-jsonschema --schemafile spec/loop.schema.json templates/research-watch/loop.yaml

Expected result: every command exits 0, and the final command prints ok -- validation done.

If preflight fails, stop and fix the repo checkout or manifest before installing any scheduler.

2. Pick a backend

Use cron first when you want the shortest local path to a running loop. Use GitHub Actions when the loop should open report PRs from the repository scheduler. Use agent-kanban when a recurring agent should inspect the report and create follow-up cards.

The full backend details live in templates/research-watch/AGENT-INSTALL.md:

• cron: section "Backend A — cron".
• GitHub Actions: section "Backend B — GitHub Actions".
• agent-kanban: section "Backend C — agent-kanban".

3. Fast cron-backed scratch run

This path proves the copied starter template and cron-shaped environment without requiring secrets. It writes only under /tmp; it is a verification run, not a live unattended install.

SCRATCH=$(mktemp -d /tmp/loopmaster-first-loop.XXXXXX)
mkdir -p "$SCRATCH/state" "$SCRATCH/reports" "$SCRATCH/env"
cat > "$SCRATCH/env/research-watch.env" <<EOF
RESEARCH_WATCH_SOURCES=templates/research-watch/examples/dry-run-sources.json
RESEARCH_WATCH_STATE=$SCRATCH/state/research-watch.json
RESEARCH_WATCH_OUTPUT_DIR=$SCRATCH/reports
EOF
chmod 600 "$SCRATCH/env/research-watch.env"
set -a && . "$SCRATCH/env/research-watch.env" && set +a
python3 templates/research-watch/scripts/research_watch.py --sources "$RESEARCH_WATCH_SOURCES" --state "$RESEARCH_WATCH_STATE" --output-dir "$RESEARCH_WATCH_OUTPUT_DIR" --max-items 5
python3 templates/research-watch/scripts/research_watch.py --sources "$RESEARCH_WATCH_SOURCES" --state "$RESEARCH_WATCH_STATE" --output-dir "$RESEARCH_WATCH_OUTPUT_DIR" --max-items 5

Expected result: the first run prints RESEARCH_WATCH_REPORT=..., RESEARCH_WATCH_STATE=..., NEW_ITEMS=1, and FETCH_ERRORS=0; the second run prints the same artifact keys with NEW_ITEMS=0 and FETCH_ERRORS=0.

That is enough evidence for a scratch run. To install a real cron entry, continue with templates/research-watch/AGENT-INSTALL.md section "Backend A — cron" and use a project-local .loopmaster/env/research-watch.env instead of /tmp.

4. GitHub Actions path

Use this when the loop should run from GitHub and open pull requests for changed reports/state. Follow templates/research-watch/AGENT-INSTALL.md section "Backend B — GitHub Actions" exactly.

Minimal readiness check from repo root:

test -f templates/research-watch/examples/github-actions/research-watch.yml
grep -q "pull-requests: write" templates/research-watch/examples/github-actions/research-watch.yml
grep -q "contents: write" templates/research-watch/examples/github-actions/research-watch.yml

Expected result: every command exits 0. After copying the workflow and merging it, verify the first Actions run from the GitHub run log and the resulting report PR, as described in the template guide.

5. Agent-kanban path

Use this when an agent should run the helper, read the report, and create follow-up cards only for evidence-backed findings. The prompt must remain self-contained and must name the concrete commands from templates/research-watch/AGENT-INSTALL.md section "Backend C — agent-kanban".

Readiness check from repo root:

test -f templates/research-watch/scripts/research_watch.py
test -f templates/research-watch/examples/sources.json

Expected result: both commands exit 0. The recurring task is not verified unless its completion evidence includes RESEARCH_WATCH_REPORT, RESEARCH_WATCH_STATE, NEW_ITEMS, and FETCH_ERRORS from the helper.

6. Verify the installed loop

Before declaring the first loop deployed, capture:

uv run --with check-jsonschema --with pyyaml check-jsonschema --schemafile spec/loop.schema.json templates/research-watch/loop.yaml
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

Expected result: manifest validation exits 0; the runner prints the report path, state path, new-item count, and fetch-error count. If FETCH_ERRORS is non-zero, inspect the generated report and fix sources before scheduling.

7. Stop or roll back

• Cron: remove the crontab line that contains templates/research-watch/scripts/research_watch.py.
• GitHub Actions: delete or disable .github/workflows/research-watch.yml in a normal PR.
• Agent-kanban: pause or remove the recurring task.
• Bad report: close/revert the report PR, or delete the local report artifact after recording what failed. Do not delete the last known-good state file unless you intentionally want to re-report old items.

8. First-week ownership checklist

After the first scheduled run:

• Confirm the report contains source evidence for every item.
• Confirm duplicate suppression works on a repeated run.
• Review noisy sources and update templates/research-watch/examples/sources.json or your project-local copy.
• Confirm the backend did not publish public claims or change product direction without approval.
• Record any friction as a task against the template or this skill pack.