hub-launch 1.3.0 → 1.4.0

package/dist/templates/skills/hula-execute/SKILL.md

@@ -1,37 +1,194 @@
 ---
 name: hula-execute
-description: Trigger or schedule an execute-action on the hula-project server. Use when the user wants to run a built-in action (e.g. harden) or a custom action file, optionally on a recurring schedule.
+description: Run, schedule, create, or manage execute-actions on the hula-project server. Use to run a built-in action (e.g. harden) or custom action file, author a new action from a plain description, or list/show/run-now/cancel/update runs and schedules.
 disable-model-invocation: true
-argument-hint: <action> [on <entry-point>] [outcome pr|plan|feedback] [schedule <when>]
-allowed-tools: Bash Read
+argument-hint: <action | description | list | show <id> | run now <id> | cancel <id> | update ...> [on <entry-point>] [outcome pr|plan|feedback] [schedule <when>]
+allowed-tools: Bash Read Write Edit
 ---
 
-You are an expert HubLaunch workflow assistant. Your job is to turn the user's
-free-form request into a single `hula execute` invocation (run via a wrapper
-script), translating any natural-language schedule into a cron expression and
-confirming it before running.
+You are an expert HubLaunch workflow assistant. You turn the user's free-form
+request into the right `hula execute` operation — running or scheduling an
+action, authoring a new action file from a description, or managing existing
+runs and schedules — running everything through wrapper scripts and confirming
+any cron expression before sending it.
 
-## Step 1: Extract arguments
+## Step 0: Intent routing
 
-From `$ARGUMENTS` (and recent chat context), determine:
+Classify `$ARGUMENTS` (and recent chat context) into exactly one mode:
 
-- **Action selector (required, exactly one):**
-  - `--built-in <name>` — a bare word naming a built-in action (e.g. `harden`).
-  - `--action-path <path>` — a custom action file. Treat the input as an action
-    path when it contains a `/`, ends in `.md`, or is an `https://` URL.
+- **`run-existing`** — the input names an existing action:
+  - contains a `/`, ends in `.md`, or is an `https://` URL → `--action-path`.
+  - is a bare word naming a built-in (e.g. `harden`) → `--built-in`.
+- **management verb** — the input begins with or clearly expresses one of:
+  - `list` / "list runs" / "list schedules" → **`list`**
+  - `show <id>` → **`show`**
+  - `run now <id>` / "run <id> now" → **`run-now`**
+  - `cancel <id>` / `delete <id>` / `pause <id>` → **`cancel/delete`**
+    (there is no pause/resume — "pause" means cancel).
+  - `update …` → **`update-skill-file`** or **`update-cron`** (see below).
+- **`create-from-description`** — anything else: a plain-language description of
+  what the action should do.
+
+**Ambiguity rule (mandatory):** If the input could be either an existing action
+or a description (e.g. a single word like `harden` that might be a built-in name
+OR a thing to do), **ask the user which they intend** before proceeding. Never
+guess between "run an existing action" and "create a new one". Likewise, if an
+`update` request does not clearly indicate the skill file vs the cron, ask which.
+
+---
+
+## Mode: run-existing (unchanged behavior)
+
+### Step 1: Extract arguments
+
+- **Action selector (exactly one):** `--built-in <name>` or `--action-path <path>`.
 - **Entry point (optional):** `--entry-point <path>` — the file, directory, or
-  URL the action targets (e.g. `src/`). Phrases like "on src/", "against the
-  src directory", or "target lib/" indicate the entry point.
+  URL the action targets (e.g. `src/`). Phrases like "on src/", "against the src
+  directory", or "target lib/" indicate the entry point.
 - **Outcome type (optional, default `pr`):** `--outcome-type <pr|plan|feedback>`.
   Map "open a PR" / "pull request" → `pr`; "make a plan" / "planning" → `plan`;
   "just feedback" / "review" / "report" → `feedback`. If the user names
   something else, ask which of `pr|plan|feedback` they mean.
-- **Schedule (optional):** a human phrase or a raw cron string (see Step 2).
+- **Schedule (optional):** a human phrase or a raw cron string (see Cron table).
+
+### Step 2: Resolve the schedule (see Cron table below) and confirm it.
+
+### Step 3: Stop conditions
+
+- If neither a built-in name nor an action path can be determined, stop with:
+  ```
+  ❌ Action required. Usage: /hula-execute <built-in name | action path | description | list | show <id> | run now <id> | cancel <id> | update ...>
+  ```
+- If BOTH a built-in name and an action path are detected, stop and ask which
+  one they intend (the CLI rejects both).
+
+### Step 4: Run the wrapper script
+
+Run exactly one Bash command. Use `--built-in` OR `--action-path`, never both:
+
+```bash
+bash .github/scripts/hula-execute-run.sh --built-in <name> [--entry-point <path>] [--outcome-type <type>] [--schedule "<cron>"]
+```
+
+or, for a custom action file:
+
+```bash
+bash .github/scripts/hula-execute-run.sh --action-path <path> [--entry-point <path>] [--outcome-type <type>] [--schedule "<cron>"]
+```
 
-## Step 2: Resolve the schedule
+Pass only the flags you resolved. Quote the cron expression. Then report the
+result (see **Reporting run/schedule results**).
 
-If the user mentions a recurring schedule, translate it to a 5-field cron
-expression using this preset table (case-insensitive, tolerant of minor wording):
+---
+
+## Mode: create-from-description
+
+The user described what they want done but did not supply an existing action.
+
+**Read `.hublaunch/skill-creation-instructions.md` and follow it exactly.** In
+summary it has you: ask clarifying questions first (then STOP), confirm the
+action name, resolve+confirm any cron, write a free-form instruction markdown
+file to `.hublaunch/skills/<YYYY-MM-DD-HH:MM-slug>.md`, **publish it to
+origin/main BEFORE running** via
+`bash .github/scripts/hula-execute-manage.sh --publish-skill <path>` (abort if
+that returns `status:"error"`), then run/schedule it with
+`bash .github/scripts/hula-execute-run.sh --action-path <path> …`, and report the
+created file path plus the run/schedule result.
+
+---
+
+## Mode: list
+
+Run via the management wrapper:
+
+- `list` (no qualifier) → show **both** recent runs and active schedules:
+  ```bash
+  bash .github/scripts/hula-execute-manage.sh --list
+  bash .github/scripts/hula-execute-manage.sh --list-schedules
+  ```
+- "list runs" → only `--list`. "list schedules" → only `--list-schedules`.
+
+Display the `cliOutput` from each result.
+
+## Mode: show
+
+```bash
+bash .github/scripts/hula-execute-manage.sh --show <runId>
+```
+
+Display the `cliOutput`.
+
+## Mode: run-now
+
+```bash
+bash .github/scripts/hula-execute-manage.sh --run-now <scheduleId>
+```
+
+Report the new run id (`runId`) from the JSON, falling back to `cliOutput`.
+
+## Mode: cancel/delete (with guarded file removal)
+
+1. Cancel the schedule:
+   ```bash
+   bash .github/scripts/hula-execute-manage.sh --cancel-schedule <scheduleId>
+   ```
+2. If the cancelled schedule referenced an `actionPath` under
+   `.hublaunch/skills/`, **ask the user whether to also delete that file.**
+3. If they opt in, FIRST verify no other active schedule still uses it:
+   ```bash
+   bash .github/scripts/hula-execute-manage.sh --list-schedules
+   ```
+   - If another active schedule references the same `actionPath`, **refuse** and
+     report which schedule id(s) still use it. Leave the file on the branch.
+   - Otherwise delete it:
+     ```bash
+     bash .github/scripts/hula-execute-manage.sh --delete-skill <actionPath>
+     ```
+
+## Mode: update-skill-file
+
+The user wants to change *what the action does* (its instructions), not the
+schedule.
+
+1. Locate the action file: from the schedule's `actionPath`
+   (via `--list-schedules`), or a path the user names. It must be under
+   `.hublaunch/skills/`.
+2. Apply the requested change to the working-tree copy with `Edit` (or rewrite
+   it with `Write` for a large change), keeping the free-form template format.
+3. Re-publish it:
+   ```bash
+   bash .github/scripts/hula-execute-manage.sh --publish-skill <actionPath>
+   ```
+4. No schedule change is needed. Inform the user that the **next scheduled run
+   will use the updated content** (the server re-reads the file on every fire).
+
+## Mode: update-cron
+
+The user wants to change *when* a schedule fires. The server has no
+update-schedule endpoint, so cancel + recreate on the same action:
+
+1. Read the existing schedule's `actionPath` (or `builtIn`), `entryPoint`, and
+   `outcomeType` via:
+   ```bash
+   bash .github/scripts/hula-execute-manage.sh --list-schedules
+   ```
+2. Resolve the new cron and **confirm the readback** (see Cron table).
+3. Cancel the old schedule, then recreate with the new cron on the **same**
+   action:
+   ```bash
+   bash .github/scripts/hula-execute-manage.sh --cancel-schedule <old-id>
+   bash .github/scripts/hula-execute-run.sh --action-path <same-path> [--entry-point <path>] [--outcome-type <type>] --schedule "<new-cron>"
+   ```
+   (Use `--built-in <name>` instead of `--action-path` if the schedule used a
+   built-in.)
+4. Report the new schedule id.
+
+---
+
+## Cron table (used by run/schedule and update-cron)
+
+Translate a recurring phrase to a 5-field cron expression (case-insensitive,
+tolerant of minor wording):
 
 | Phrase | Cron |
 | --- | --- |
@@ -50,77 +207,50 @@ Rules:
 - If the user specifies an explicit time (e.g. "every day at 9pm"), adjust the
   hour/minute fields accordingly (`0 21 * * *`).
 - If the user supplies a raw 5-field cron string, accept it as-is.
-- **Always** print the resolved cron expression with a plain-English readback
-  and confirm before running, e.g.:
+- **Always** print the resolved cron with a plain-English readback and confirm
+  before sending, e.g.:
   ```
   Schedule → 0 3 * * * (every day at 3:00 AM)
   ```
-  There is no client-side cron validation — the server accepts whatever is sent,
-  so the readback + confirmation is mandatory.
+  There is no client-side cron validation — confirmation is mandatory.
 - If a phrase cannot be confidently mapped, ask the user to rephrase or supply a
   raw cron expression. Do NOT send an unverified guess.
 - If no schedule is mentioned, the action runs once (omit `--schedule`).
 
-## Step 3: Stop conditions
-
-- If neither a built-in name nor an action path can be determined, stop with:
-  ```
-  ❌ Action required. Usage: /hula-execute <built-in name | action path> [on <entry-point>] [outcome pr|plan|feedback] [schedule <when>]
-  ```
-- If BOTH a built-in name and an action path are detected, stop and ask the user
-  which one they intend (the CLI rejects both).
-
-## Step 4: Run the wrapper script
-
-With the arguments resolved (and the schedule confirmed, if any), run exactly
-one Bash command. Use `--built-in` OR `--action-path`, never both:
-
-```bash
-bash .github/scripts/hula-execute-run.sh --built-in <name> [--entry-point <path>] [--outcome-type <type>] [--schedule "<cron>"]
-```
-
-or, for a custom action file:
-
-```bash
-bash .github/scripts/hula-execute-run.sh --action-path <path> [--entry-point <path>] [--outcome-type <type>] [--schedule "<cron>"]
-```
-
-Pass only the flags you resolved. Quote the cron expression.
+---
 
-## Step 5: Report the result
+## Reporting run/schedule results
 
-Parse the single JSON object the script prints to stdout:
+Every wrapper prints a single JSON object to stdout. On any `status:"error"`,
+display `❌ <message>` and stop.
 
-- If `status` is `"error"`, display `❌ Execute failed: <message>` and stop.
-- If `status` is `"success"` and `kind` is `"run"`, display:
+- run (`kind:"run"`):
   ```
   ✅ Execute action queued
 
   🔖 **Run ID**: <runId>
   🔗 **PR**: <prUrl>   (omit this line if prUrl is empty)
 
-  Check status with: hula execute --show <runId>
+  Check status with: /hula-execute show <runId>
   ```
-- If `status` is `"success"` and `kind` is `"schedule"`, display:
+- schedule (`kind:"schedule"`):
   ```
   ✅ Schedule created
 
   🔖 **Schedule ID**: <scheduleId>
   ⏰ **Cron**: <cronExpr>
 
-  Manage with: hula execute --list-schedules
+  Manage with: /hula-execute list · /hula-execute run now <scheduleId> · /hula-execute cancel <scheduleId>
   ```
 
 If an identifier is empty, fall back to showing the `cliOutput` field.
 
 ## Important Notes
 
-- Do NOT call the `Read` tool to check whether an action file exists. The server
-  validates the action; the wrapper handles errors clearly.
 - Do NOT pre-check credentials. The CLI resolves the Anthropic OAuth token,
   Daytona key, and GitHub token from flags/config/env and reports a clear error
-  if any are missing; the wrapper surfaces it.
+  if any are missing; the wrappers surface it.
 - Do NOT echo secrets.
-- This skill only triggers runs and creates schedules. The management modes
-  (`--show`, `--list`, `--list-schedules`, `--cancel-schedule`, `--run-now`) are
-  available directly via `hula execute …`.
+- Generated action files live under `.hublaunch/skills/` and are committed to
+  `origin/main` via a temporary worktree — never on the user's current branch.
+- Never run `hula execute` before a `--publish-skill` succeeds.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hub-launch",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "GitHub Issue and PR automation CLI tool with plugin/hook system for project-specific customizations",
   "type": "module",
   "main": "./dist/index.js",