---
name: deploy-your-first-loop
description: Use when an agent or human wants to deploy the research-watch Loopmaster template through cron, GitHub Actions, or agent-kanban and verify a running loop in one session.
category: authoring
requirements:
  - Python 3
  - repository checkout containing templates/research-watch
  - uv for manifest validation
  - cron for the local scheduler backend, or GitHub Actions / Hermes kanban for alternate backends
  - no web-search API key for the default research-watch run
deploys-template: research-watch
backends:
  - cron
  - github_actions
  - agent_kanban
---

# 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:

```bash
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.

```bash
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:

```bash
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:

```bash
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:

```bash
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.