caro-scaffold

name	caro-scaffold
description	Scaffold a new CaroML task file (.caro) from a natural-language description. Use this when the user wants to create a repeatable shell task that Caro will validate, generate, and maintain over time. Triggers on requests like "make a CaroML task that...", "scaffold a runbook for...", "create a .caro file for...", or invocations of `/caro new <name>`.

CaroML Task Scaffolding

This skill helps you create a new .caro file (a CaroML task) and an accompanying lock + runbook by walking through the user's intent in a small number of focused steps.

When to invoke

The user is asking for a repeatable shell task that they'd otherwise script by hand and gradually drift away from. Examples:

• "Make a CaroML task that cleans up old log files weekly"
• "Scaffold a runbook to deploy the API to staging"
• "Create a .caro for the nightly snapshot job"

Caro's value proposition is that the intent (the what) stays stable while the generated script can evolve — across model upgrades, new CVE patterns, platform changes, or learned team preferences. The eight-keyword DSL (TASK / WHY / NEED / ON / LET / DO / NOTE / REM) is meant to feel like your first programming language: line-oriented, minimal syntax, BASIC-like.

Workflow

1. Clarify the intent. Ask 1–3 short questions:

   • What's the one-line title? (becomes TASK)
   • Why does this task exist? When does it run? (becomes WHY)
   • Does it need sudo / network / a specific tool? (becomes NEED)
   • Target platforms? macOS, Linux, both? (becomes ON)

2. Sketch the steps. Each DO line is one natural-language intent. Keep them short and imperative. Order matters — later steps may use earlier results.

3. Run caro new <name> "<description>" if the user is in a shell with caro installed. Otherwise, write the file content yourself following the format below.

4. Show the user the resulting .caro before generating. Let them refine before committing.

5. Run caro check, then caro generate <name> --backend mock for a dry-run; show the resulting commands. If anything looks off, refine the intent (not the output).

6. For real generation, point the user at caro generate with their configured backend; for now mock is the only one wired through.

File format reference

REM Optional comments anywhere; ignored at runtime
TASK <one-line title>
WHY  <reason; when does this run?>

NEED <prerequisite>      # zero or more
ON   <platform> [PREFER <a, b>] [AVOID <c, d>]    # zero or more

LET  <name> = <value>     # zero or more; use {name} in DO lines

NOTE <hint to the LLM>    # attaches to the next DO line
DO   <natural-language intent>
DO   <next intent>

Recognized platforms: macos, linux, windows, posix.

Example session

USER: Make a CaroML task that deletes log files older than 30 days,
      with confirmation per file.

ASSISTANT: A few quick questions:
  1. Title for the task? (e.g., "Clean up old log files")
  2. Where do the logs live? (`/var/log` is the conventional spot)
  3. Target platforms? Both macOS and Linux?

USER: Yes, both. /var/log is fine. Title is "Cleanup logs".

ASSISTANT: Drafting tasks/cleanup-logs.caro:

  TASK Cleanup logs
  WHY  Free disk space; runs weekly via cron

  NEED sudo
  ON   macos PREFER bsd-tools
  ON   linux PREFER gnu-tools

  LET  path = /var/log
  LET  days = 30

  DO   find log files in {path}
  DO   filter to those older than {days} days
  DO   delete each, asking confirmation per file
  DO   record what was deleted to /tmp/caro-cleanup.log

Want me to commit this as-is, or refine anything first?

Don'ts

• Don't over-constrain — leave the LLM room to choose a sensible idiom. DO find all .log files older than 30 days and delete them is fine; DO run "find /var/log -mtime +30 -delete" defeats the point.
• Don't put shell flags in the intent — that's the lock's job.
• Don't ship .sh runbooks as the primary deliverable. The committed artifact is the .caro + .caro.lock; runbooks are derived.

Triggers

This skill should activate when the user says any of:

• "make a CaroML task"
• "scaffold a runbook"
• "create a .caro for ..."
• "/caro new"
• "I want a repeatable shell task"