feat(aidd-orchestrator): drop OS cron, route local scheduling via Claude Code

The 04-generate-local-script action now writes a Claude Code-native
scheduling guide instead of a cron+launchd snippets file. The two
documented paths are the Desktop scheduled task and the `/schedule`
skill (cloud routine). OS-level cron is intentionally avoided so that
the schedule stays inside Claude Code, where the rest of the workflow
already lives.

- New asset: assets/local-mode-scheduling-template.md
- 04-generate-local-script.md updated to render aidd_docs/local-mode-scheduling.md
- README updated to describe the two paths and drop the cron snippet

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: blafourcade

plugins/aidd-orchestrator/CATALOG.md

@@ -27,6 +27,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 | Group | File | Description |
 |-------|------|---|
 | `assets` | [config-template.json](skills/01-setup-async-dev/assets/config-template.json) | - |
+| `assets` | [local-mode-scheduling-template.md](skills/01-setup-async-dev/assets/local-mode-scheduling-template.md) | - |
 | `assets` | [local-poll-template.sh](skills/01-setup-async-dev/assets/local-poll-template.sh) | - |
 | `evals` | [scenarios.json](skills/01-setup-async-dev/evals/scenarios.json) | - |
 | `references` | [auth-modes.md](skills/01-setup-async-dev/references/auth-modes.md) | - |

plugins/aidd-orchestrator/README.md

@@ -157,25 +157,15 @@ The next time you apply `to-implement` on an issue, the workflow runs.
 
 ### 4b. Local-mode finalisation
 
-The setup skill drops a poll script and a scheduler snippet:
+The setup skill drops two files:
 
 ```
-scripts/aidd-async-poll.sh                # the runner
-scripts/aidd-async-poll.scheduler.txt     # cron + launchd snippets to copy/paste
+scripts/aidd-async-poll.sh             # the poll runner (wraps claude -p)
+aidd_docs/local-mode-scheduling.md     # short guide: two Claude Code-native scheduling paths
 ```
 
-Pick one of the snippets and install it. Examples:
+Manual sanity check first:
 
-**cron** (Linux, macOS):
-```cron
-*/5 * * * * cd /abs/path/to/repo && ./scripts/aidd-async-poll.sh >> /tmp/aidd-async.log 2>&1
-```
-
-**launchd** (macOS): copy the `<plist>` from the `.scheduler.txt` file into `~/Library/LaunchAgents/com.aidd.async-poll.plist`, then `launchctl load …`.
-
-**Claude Code Desktop scheduled task**: create a task that runs `./scripts/aidd-async-poll.sh` from the repo root every N minutes.
-
-Manual sanity check:
 ```bash
 ./scripts/aidd-async-poll.sh --dry-run    # lists what it would do
 ./scripts/aidd-async-poll.sh              # runs once for real
@@ -186,6 +176,15 @@ The script invokes `claude -p` under the hood, so the local machine must have:
 - `gh auth status` OK
 - The `aidd-orchestrator` and SDLC plugins installed at user scope (`claude plugin install …`)
 
+Then schedule via one of the two Claude Code-native paths documented in `aidd_docs/local-mode-scheduling.md`:
+
+| Path | Where the schedule lives | Runs when |
+| ---- | ------------------------ | --------- |
+| **Desktop scheduled task** | Inside Claude Code Desktop on your machine | Only when the machine is awake |
+| **`/schedule` skill** | On Anthropic's cloud (a routine in your account) | Always, machine-independent |
+
+Both paths call the same poll script (or invoke the same skill prompt), so behaviour is identical. Pick the one that fits your availability needs. OS-level cron and launchd are intentionally not used here: the scheduling stays inside Claude Code so it is visible and pausable from the same UI as the rest of the workflow.
+
 ## Daily workflow
 
 | You do | Claude does |
@@ -215,7 +214,7 @@ Repeat. The same flow scales to N issues in parallel; each one has its own concu
 | ------------------------------------- | ------------------------------------------------------------- |
 | `.github/workflows/aidd-async.yml`    | GitHub Actions workflow: dispatch + run + review jobs (remote mode). |
 | `scripts/aidd-async-poll.sh`          | Local poll script wrapping `claude -p` (local mode).          |
-| `scripts/aidd-async-poll.scheduler.txt` | Ready-to-paste cron and launchd snippets (local mode).      |
+| `aidd_docs/local-mode-scheduling.md`  | Guide: schedule the poll script via Claude Code Desktop or `/schedule`. |
 | `.claude/aidd-orchestrator.json`      | Runtime config (committed; no secrets).                       |
 | `aidd_docs/async-runs/<YYYY_MM>/<run-id>.json` | Per-run audit log: trigger, dependency check, lock timestamps, SDLC outcome, iteration log. |
 

plugins/aidd-orchestrator/skills/01-setup-async-dev/actions/skills/04-generate-local-script.md

@@ -1,6 +1,6 @@
 # 04 -- Generate Local Script
 
-Renders the local poll script that wraps `claude -p` invocations of the run and review skills, plus a scheduler snippet (launchd plist or cron line) for the user to install.
+Renders the local poll script and a short Claude Code-native scheduling guide that wraps it.
 
 ## Inputs
 
@@ -10,8 +10,8 @@ Renders the local poll script that wraps `claude -p` invocations of the run and
 ## Outputs
 
 Two files at:
-- `scripts/aidd-async-poll.sh` -- executable poll script
-- `scripts/aidd-async-poll.scheduler.txt` -- ready-to-paste cron line (one-line) and a launchd plist body (multiline), with TODO markers for the absolute paths
+- `scripts/aidd-async-poll.sh` -- executable poll script that wraps `claude -p` invocations of the run and review skills
+- `aidd_docs/local-mode-scheduling.md` -- a short guide explaining the two Claude Code-native ways to run the script on a schedule (Desktop scheduled task, `/schedule` skill)
 
 ## Depends on
 
@@ -27,14 +27,13 @@ Two files at:
    - `__WORKING_LABEL__` -> `answers.labels.working`
    - `__BLOCKED_LABEL__` -> `answers.labels.blocked`
    - `__REPO_FULL_NAME__` -> `${detection.remote_owner}/${detection.remote_repo}`
-4. If `scripts/aidd-async-poll.sh` already exists, prompt the user to overwrite or skip. Write with mode `0755` (`chmod +x`).
-5. Render a sibling file `scripts/aidd-async-poll.scheduler.txt` with two snippets:
-   - **cron** (Linux, macOS): `*/5 * * * * cd /abs/path/to/repo && ./scripts/aidd-async-poll.sh >> /tmp/aidd-async.log 2>&1`
-   - **launchd plist** (macOS): a complete `<plist>` that runs the script every 5 minutes, with TODO comments for the absolute paths.
-   The user installs whichever fits their OS; the plugin does not install schedulers itself.
-6. Print a follow-up note explaining how to test the script once: `./scripts/aidd-async-poll.sh` from the repo root, after labelling at least one issue with `to-implement`.
+4. If `scripts/aidd-async-poll.sh` already exists, prompt the user to overwrite or skip. Write with mode `0755`.
+5. Render `aidd_docs/local-mode-scheduling.md` from `assets/local-mode-scheduling-template.md`. The guide does NOT install OS-level cron or launchd; it documents two Claude Code-native paths:
+   - **Path A -- Claude Code Desktop scheduled task**: the user creates a task in the app UI that runs `./scripts/aidd-async-poll.sh` from the repo root every N minutes. The template includes a checklist of the fields to fill in the UI.
+   - **Path B -- `/schedule` skill** (cloud routine): the user opens a Claude Code session and runs `/schedule` with a cron expression and the prompt `Use skill aidd-orchestrator:02:run-async-dev on the next ready issue in <owner>/<repo>`. The template gives the exact prompt with placeholders pre-filled from `answers` and `detection`.
+6. Print a follow-up note explaining how to test the script once before scheduling: `./scripts/aidd-async-poll.sh --dry-run` from the repo root, after labelling at least one issue with `to-implement`.
 7. `git add` both files but do not commit.
 
 ## Test
 
-After running, `./scripts/aidd-async-poll.sh --dry-run` (when invoked from the repo root) prints the list of issues it would process, exits 0, and makes no `claude -p` calls. The scheduler snippet file contains both a `cron` block and a `launchd` `<plist>` block.
+After running, `./scripts/aidd-async-poll.sh --dry-run` (when invoked from the repo root) prints the list of issues it would process, exits 0, and makes no `claude -p` calls. The scheduling guide file exists and contains both `Desktop scheduled task` and `/schedule` headings.

plugins/aidd-orchestrator/skills/01-setup-async-dev/assets/local-mode-scheduling-template.md

@@ -0,0 +1,54 @@
+# Local-mode scheduling
+
+Two Claude Code-native ways to run `scripts/aidd-async-poll.sh` on a schedule. Pick one. Both stay inside Claude Code; neither needs OS-level cron or launchd.
+
+## Path A -- Claude Code Desktop scheduled task
+
+Best for: users who want the schedule to live on their machine and run only when the laptop is awake.
+
+1. Open Claude Code Desktop.
+2. Open the scheduled tasks panel (settings -> Scheduled tasks -> New task).
+3. Fill the form:
+   - **Working directory**: the absolute path of this repo
+   - **Schedule**: every 5 minutes (or whatever cadence you want)
+   - **Prompt**: `Run ./scripts/aidd-async-poll.sh and report what was processed.`
+4. Save. The Desktop will run the script in a fresh session at each tick.
+
+To pause: disable the task in the same panel. To remove: delete the task.
+
+## Path B -- `/schedule` skill (cloud routine)
+
+Best for: users who want the schedule to keep running even when their machine is off, and accept that the cycle runs on Anthropic's cloud.
+
+1. Open any Claude Code session in this repo.
+2. Run the `/schedule` skill with this exact input (placeholders are already filled in):
+
+   ```
+   /schedule
+   cron: */5 * * * *
+   prompt: Use skill aidd-orchestrator:02:run-async-dev on the next ready issue in __REPO_FULL_NAME__
+   ```
+
+3. Confirm. The routine appears in your Claude Code account and runs server-side.
+
+To pause: `/schedule list`, then disable the routine. To remove: delete it from the same UI.
+
+## Sanity check first
+
+Before scheduling either path, run the script once manually to make sure it picks up the right issues:
+
+```
+./scripts/aidd-async-poll.sh --dry-run    # lists what it would do
+./scripts/aidd-async-poll.sh              # runs once for real
+```
+
+If the script reports `no open issues with label to-implement`, label one issue with `to-implement` and try again.
+
+## Why no OS-level cron?
+
+OS-level cron and launchd work, but they:
+- bypass Claude Code's session boundary (each tick spawns a brand-new `claude -p`),
+- are harder to see and pause from inside Claude Code,
+- silently fail when `claude` is not on the PATH of the cron user.
+
+The two paths above keep the schedule visible inside Claude Code, where the rest of the workflow already lives.