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:

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:

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:

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

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:

{
  "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.