schedule

# Schedule

Manage scheduled workflow jobs for the Claude Octopus scheduler.

## Usage


**Preflight — Ensure plugin root is resolvable (run via Bash tool FIRST):**

```bash
OCTO_ROOT="${HOME}/.claude-octopus/plugin"
if [[ ! -x "$OCTO_ROOT/scripts/orchestrate.sh" ]]; then
  helper="$OCTO_ROOT/scripts/helpers/ensure-plugin-root.sh"
  if [[ ! -x "$helper" ]]; then
    helper="$(find "${HOME}/.claude/plugins/cache" "${HOME}/Library/Application Support/Claude" "${LOCALAPPDATA:-/dev/null}/Claude" "${XDG_DATA_HOME:-${HOME}/.local/share}/Claude" -maxdepth 8 -path "*/nyldn-plugins/octo/*/scripts/helpers/ensure-plugin-root.sh" -print -quit 2>/dev/null)"
  fi
  [[ -x "$helper" ]] && bash "$helper" >/dev/null 2>&1 || true
fi
test -x "$OCTO_ROOT/scripts/orchestrate.sh" && echo "plugin-root:ok" || echo "plugin-root:missing"
```

If the output is `plugin-root:missing`, stop and ask the user to run `/octo:setup`.


```bash
${HOME}/.claude-octopus/plugin/scripts/scheduler/octopus-scheduler.sh [subcommand]
```

## Instructions for Claude

This command supports **natural language** and provides two primary experiences:
- **No args / "show jobs" / "what's scheduled"** → Dashboard table
- **"add a job" / "schedule X" / `add` with no file** → Guided wizard

### MANDATORY COMPLIANCE — DO NOT SKIP

**When the user explicitly invokes `/octo:schedule`, you MUST use the scheduler command paths below.** You are PROHIBITED from inventing job state, editing scheduler files by hand, or bypassing the dashboard/wizard flow.

---

### Step 0: Parse Intent First

| User says | Action |
|-----------|--------|
| No args, "show jobs", "status", "what's scheduled", "list" | **Dashboard** (Step 1A) |
| Describes a new job, "add", "create", "schedule a...", any time/frequency reference | **Wizard** (Step 1B) |
| "remove", "delete" + job name/id | Run `remove <id>` directly |
| "enable", "turn on" + job reference | Run `enable <id>` |
| "disable", "pause", "turn off" + job reference | Run `disable <id>` |
| "logs", "what happened", "last run" | Run `logs [id]` + summarize |
| Wants to change schedule/budget/prompt on existing job | **Modify** (Step 1C) |

If intent is ambiguous, show the dashboard first, then ask what they'd like to do.

---

### Step 1A: Dashboard (No-args / List)

Display the banner, then run:

```bash
${HOME}/.claude-octopus/plugin/scripts/scheduler/octopus-scheduler.sh dashboard
```

Present the output as-is. After showing it, offer quick actions:
```
What would you like to do?
• Add a new job
• Enable/disable a job
• View logs for a job
• Remove a job
```

---

### Step 1B: Wizard — Guided Job Creation (MANDATORY for new jobs without a file arg)

Display banner:
```
🐙 CLAUDE OCTOPUS ACTIVATED — Job Wizard
⏰ Schedule: Creating a new scheduled job

Providers:
🔵 Claude — Job configuration
```

**You MUST ask these questions via AskUserQuestion:**

```yaml
Question 1:
  question: "What should this job do?"
  header: "Task"
  multiSelect: false
  options:
    - label: "Security scan"
      description: "Nightly vulnerability and code quality audit (squeeze workflow)"
    - label: "Research digest"
      description: "Research a topic and summarize findings (probe workflow)"
    - label: "Full review"
      description: "Complete 4-phase Double Diamond analysis (embrace workflow)"
    - label: "Custom task"
      description: "Describe what you want in your own words"

Question 2:
  question: "How often should it run?"
  header: "Schedule"
  multiSelect: false
  options:
    - label: "Every night at 2am"
      description: "cron: 0 2 * * *"
    - label: "Every weekday morning"
      description: "cron: 0 9 * * 1-5"
    - label: "Weekly (Sunday night)"
      description: "cron: 0 22 * * 0"
    - label: "Custom schedule"
      description: "Describe the timing in natural language"

Question 3:
  question: "Which project/directory should it run in?"
  header: "Workspace"
  multiSelect: false
  options:
    - label: "Current directory"
      description: "Use the current working directory"
    - label: "Specify a path"
      description: "I'll enter the full path"
```

**WAIT for the user's answers before proceeding.**

**After answers, generate the JSON job definition:**

Map user answers:
| User says | workflow | cron |
|-----------|----------|------|
| Security scan | `squeeze` | `0 2 * * *` |
| Research digest | `probe` | user's choice |
| Full review | `embrace` | user's choice |
| Custom | infer from description | parse time expression |

**Cron translation (natural language → cron):**
| Phrase | Cron |
|--------|------|
| every night / nightly | `0 2 * * *` |
| every morning / daily | `0 9 * * *` |
| weekday mornings | `0 9 * * 1-5` |
| weekly / every week | `0 22 * * 0` |
| hourly | `@hourly` |
| every N minutes | `*/N * * * *` |
| every Monday at Xam | `0 X * * 1` |

**Generate job slug:** "Nightly Security Scan" → `nightly-security`

**Show the generated definition for user confirmation:**
```json
{
  "id": "<slug>",
  "name": "<Full Name>",
  "enabled": true,
  "backend": "<detected — see Step 2>",
  "schedule": { "cron": "<expression>" },
  "task": {
    "workflow": "<workflow>",
    "prompt": "<expanded description>"
  },
  "execution": {
    "workspace": "<path>",
    "timeout_seconds": 3600
  },
  "budget": {
    "max_cost_usd_per_run": 5.0,
    "max_cost_usd_per_day": 15.0
  },
  "security": {
    "sandbox": "workspace-write"
  }
}
```

Ask: "Does this look right? (yes to save / no to adjust)"

---

### Step 2: Backend Detection (MANDATORY — run before saving any job)

This step determines which execution backend to use and sets `"backend"` in the job JSON.

**Check 1 — User override wins:**
```bash
backend_pref="${OCTOPUS_SCHEDULER_BACKEND:-auto}"
```
- If `daemon` → set `backend: daemon`, skip further checks
- If `coworkd` → attempt detection; error loudly if unavailable (do NOT fall back)

**Check 2 — Detect CronCreate availability (inside CC session):**

Use ToolSearch to check if CronCreate i