---
name: loopify
description: "Use when a human describes a manual workflow and needs Q&A intake plus a draft Loopmaster loop bundle: loop.yaml, README, AGENT-INSTALL.md, verify.sh, and registry-entry instructions."
category: authoring
requirements:
  - repository checkout containing spec/loop.schema.json
  - free-text workflow description or notes from the human operator
  - optional artifacts such as scripts, checklists, sample inputs, or previous cron entries
  - uv with pyyaml and jsonschema, or check-jsonschema with pyyaml, for manifest validation
  - shell access for deterministic verify.sh dry-runs
deploys-template:
backends:
  - cron
  - github_actions
  - agent_kanban
---

# Loopify

Describe a job you do by hand. Get back a loop your agent can run.

Loopify turns a manual workflow into a draft Loopmaster bundle. It is conservative by default: minimum permissions, explicit state, deterministic verification where possible, and human approval for anything public, destructive, credential-changing, or spending money.

Loopify is an authoring skill, not a deployment skill. It does not deploy an existing `templates/<id>/` directory and it never marks the generated loop verified. Its output stays `draft` until a human approves it and a clean logged run proves it.

## Inputs to collect

Start with an interactive Q&A intake. Ask for or extract these inputs before drafting files:

- Free-text workflow description: what the human does, when, with which tools, and why.
- Optional artifacts: scripts, checklists, sample inputs/outputs, existing cron entries, SOPs, issue templates, runbooks, or screenshots.
- Constraints: schedule, allowed tools, forbidden actions, credential scopes, public/private boundary, spend limits, approver, and rollback preference.
- Done criteria: what evidence convinces the human the job was completed correctly.

If a required beat is missing and cannot be inferred from artifacts, stop and return a draft gap list instead of inventing behavior.

## Q&A intake first

Before writing files, interview the human or summarize the answers already present in their prompt. Do not ask again for information the human already supplied. Instead, start with:

1. **Known answers**: a short list of facts already supplied.
2. **Assumptions**: any safe defaults you intend to use.
3. **Missing or ambiguous answers**: only the questions still needed to draft the loop.

Collect these fields by Q&A before creating or editing a loop bundle:

| Field | Ask when missing or ambiguous |
| --- | --- |
| Workflow/job description | What recurring job should the loop perform, and what outcome should it produce? |
| Trigger/schedule/event | What starts it: cron schedule, webhook, CI event, kanban task, manual request, or another event? Include timezone for schedules. |
| Inputs/sources/artifacts | What repos, files, URLs, feeds, tickets, docs, APIs, sample inputs, prior scripts, or output examples should it read? |
| Allowed tools/actions | Which tools may it use, and what changes may it make without additional approval? |
| Forbidden actions | What must it never do, even if doing so would help the goal? |
| Credentials needed by scope only | Which credential scopes are required, by name and purpose only? Never ask for or record credential values. |
| Runtime target | Where should it run: cron, GitHub Actions, Hermes kanban, another agent scheduler, or another backend? |
| Done criteria and verifier | What command, script, checklist, output shape, or evidence proves the loop completed correctly? |
| Approval gates | Which actions need approval: scheduling, publishing, external posting, spending, credential creation or changes, deletes, overwrites, or other destructive changes? |
| Output repo/path and owner | Where should files be written, and who owns or approves the draft? |

If the answers are incomplete, output a draft plan and an **Unanswered questions** section. The draft plan may name likely files, schema fields, risks, and verification ideas, but it must not fabricate sources, schedules, permissions, owners, or credentials. Do not write files until the missing answers needed for safe drafting are resolved.

## Output bundle

Create a new draft loop directory, usually `loops/<loop-id>/` or `templates/<loop-id>/` depending on whether the result is project-local or reusable. Include:

- `loop.yaml` — conforming to `spec/loop.schema.json`.
- `README.md` — human overview, what it does, risks, and first-run checklist.
- `AGENT-INSTALL.md` — exact backend install guide for cron, GitHub Actions, and/or agent-kanban.
- `verify.sh` — deterministic checks derived from the done criteria.
- `registry-entry.json` or clear instructions for adding the loop to the registry/index generation path.
- Notes on gaps: especially missing verification evidence, missing sample inputs, or actions that must remain human-gated.

Every generated file must say the bundle is a draft. Never write `verified`, `production-ready`, or equivalent unless a separate clean run has produced dated evidence and a human has approved it.

## Workflow

### 1. Run Q&A intake and gap check

Use the intake fields above. If the user's initial request already includes an answer, keep it and do not ask again. If the missing fields block safe drafting, return the draft plan plus unanswered questions and stop.

### 2. Parse the workflow into five beats

Map the input into this table before writing files:

| Beat | Questions to answer | Manifest fields |
| --- | --- | --- |
| Trigger | When does the job start? Cron, webhook, CI, issue, feed change, or manual request? | `trigger`, `backends.*.schedule` |
| Context | What sources, files, APIs, repos, calendars, tickets, or state does it read? | `inputs`, `state.paths`, `capabilities` |
| Act | What does the agent or script do? What tools may it call? | `permissions.allowed_actions`, `outputs` |
| Verify | What deterministic evidence proves success? | `verification.required`, `verification.commands` |
| Escalate | When must it stop and ask a human? Who approves? | `human_gates`, `failure_policy` |

Missing verification is the most important gap. If no deterministic verifier can be derived, emit a draft bundle that lists needed evidence only; do not pretend the loop can run unattended.

### 3. Classify the loop pattern

Use `docs/research/loop-landscape.md` as the pattern source. Pick the closest canonical pattern and state why in the README:

- ReAct / tool loop
- Plan → execute → verify
- Evaluator–optimizer
- Reflection / Reflexion
- Orchestrator–workers
- Watchdog / monitor loop
- CI repair loop
- Content freshness loop
- Agent usability loop
- Self-improvement loop

If two patterns fit, choose the safer outer loop as the primary classification. For example, a weekly feed review that later creates follow-up tasks is primarily a watchdog / monitor loop, not an open-ended autonomous agent.

### 4. Draft `loop.yaml` with default-deny permissions

Start from the smallest useful `allowed_actions`. Put risky actions in `forbidden_actions` or `human_gates.required_for` by default.

Mandatory safety defaults:

- Public publishing, external posting, production changes, deletes, credential changes, and spending money require a human gate.
- Credentials are scope declarations only. Never include values in `loop.yaml`, README, install docs, examples, logs, or verify output.
- State paths must be explicit and owned by the loop.
- Outputs must be explicit enough for an agent to report evidence, not just say “done.”
- `failure_policy.retry` must be finite.

### 5. Derive verification from done criteria

Prefer checks that can run without the LLM judging itself:

- JSON/YAML schema validation.
- Required files exist and are non-empty.
- Report contains required sections or `KEY=value` lines.
- Every finding has a URL or repo-relative source path.
- Duplicate suppression can be tested by running the same sample twice.
- Dry-run mode uses sample inputs and writes only under `/tmp` or a scratch directory.
- `forbidden_actions` and `human_gates.required_for` include required safety gates.

`verify.sh` should fail closed: if evidence is missing, exit non-zero and print the missing evidence. It should not call paid APIs, mutate production systems, or require secrets for the default dry run.

### 6. Write install guides for supported backends

Include only backends that fit the user's constraints:

- Cron: exact crontab line or systemd timer pattern, env file path, state/output paths, log path, and stop command.
- GitHub Actions: workflow filename, permissions, schedule, secrets by scope name only, branch/PR behavior, and manual dispatch.
- Agent-kanban: recurring task prompt, assignee expectations, evidence keys to report, and block/escalate conditions.

Do not hide backend caveats. If a backend cannot run safely without a missing credential or human approval path, mark that backend “draft only — needs evidence.”

### 7. Validate and dry-simulate

From repo root, run the schema validation against the generated manifest:

```bash
uv run --with check-jsonschema --with pyyaml check-jsonschema --schemafile spec/loop.schema.json <draft-dir>/loop.yaml
```

Then run the deterministic verifier against sample inputs:

```bash
bash <draft-dir>/verify.sh
```

Record the exact commands, exit codes, and output shape in the README or a draft transcript. If validation fails, fix the manifest. If dry simulation cannot run because evidence is missing, keep the bundle draft and list the missing evidence.

### 8. Stop at draft

Loopify output is always draft. The final response must say one of:

- “Draft bundle created and schema-valid; verification dry run passed on sample inputs. Human approval and a clean logged run are still required before verified status.”
- “Draft bundle created, but verification could not be derived or could not run. Needed evidence: …”

Do not create public claims, publish the loop, schedule it, spend money, create credentials, or mark anything verified.

## Worked example: Monday feeds

A checked-in worked example lives under `skills/authoring/loopify/examples/monday-feeds/`.

It is based on the F3/R2 example: “Every Monday I check three feeds and post a summary.” Loopify classifies it as a watchdog / monitor loop, drafts a `loop.yaml`, writes backend install guidance, and produces a deterministic `verify.sh` that validates the manifest and checks a sample summary file shape.

Run the example check from repo root:

```bash
python3 skills/authoring/loopify/scripts/check_loopify_example.py
```

Expected result: it validates `skills/authoring/loopify/examples/monday-feeds/loop.yaml` against `spec/loop.schema.json`, runs `verify.sh` in a scratch directory, and prints `LOOPIFY_EXAMPLE_STATUS=draft_validated`. The status remains draft, not verified.

## Draft registry entry

For a generated loop, write a small `registry-entry.json` next to the draft bundle when the repo does not auto-index that directory yet. It should include at least:

```json
{
  "id": "example-loop-id",
  "name": "Example Loop",
  "status": "draft",
  "manifest_path": "loops/example-loop-id/loop.yaml",
  "doc_path": "loops/example-loop-id/README.md",
  "install_path": "loops/example-loop-id/AGENT-INSTALL.md",
  "verification": {
    "status": "draft",
    "details": "schema-valid draft; needs clean logged run and human approval before verification"
  }
}
```

If the repo's `tools/build_index.py` already discovers the target directory, say that the generated registry entry is informational and the real index must be regenerated and validated.

## Safety checklist

Before returning a Loopify draft, confirm:

- `loop.yaml` validates against `spec/loop.schema.json`, or the failure is documented as a draft gap.
- `permissions.allowed_actions` is minimal and non-empty.
- Risky actions appear in `human_gates.required_for` and/or `permissions.forbidden_actions`.
- Credential scopes are names only; no values or tokens appear anywhere.
- `verify.sh` is deterministic, local/scratch-safe by default, and fails closed.
- Install docs include stop/rollback instructions.
- The response says draft only and does not mark the loop verified.