atlas-routines

---
name: atlas-routines
description: "Cloud-scheduled recurring tasks via Anthropic Routines API. Headless execution, no local session required. Trigger: /atlas routines, 'set up cloud routine', 'schedule headless task'. Subcommands: create, delete, list, run."
mode: [personal, all]
effort: medium
thinking_mode: adaptive
superpowers_pattern: [none]
see_also: [atlas-loop, reminder-scheduler]
tier: core
version: 6.0.0-alpha.1
---

# atlas-routines — Cloud Scheduled Tasks

> **Goal**: Schedule recurring Claude tasks that run on Anthropic's cloud, no local session needed.
> **Decision**: ADR-0002 (complementary to atlas-loop / CronCreate in-session).

## When to Invoke

- "Set up cloud routine"
- "Schedule headless task"
- "Run X every morning even if I'm not logged in"
- "Daily/weekly automation"
- "Cross-session workflow"

## Decision Tree (vs atlas-loop)

```
Need scheduling?
├─ Active CC session + want results in session?
│   └─ atlas-loop (CronCreate)  — local
└─ Headless / cloud / cross-session?
    └─ atlas-routines (this skill) — Anthropic cloud
```

## Subcommands

### `create` — Schedule a new routine

```bash
/atlas routines create --schedule="0 8 * * 1-5" --task="morning brief: summarize overnight emails + GitHub activity"
/atlas routines create --interval=daily --task="weekly report aggregation"
```

Behavior:
- `--schedule="<cron>"` → Pass cron expression directly (avoid :00 / :30 marks per CC best practices)
- `--interval=daily|weekly|monthly` → Convenience shortcuts
- `--task="<description>"` → The prompt to execute
- `--max-output-tokens=N` → Cap response size (optional)

Returns: routine ID for delete/run

### `delete <id>` — Remove a routine

```bash
/atlas routines delete <routine_id>
```

### `list` — Show all routines

```bash
/atlas routines list
```

Format: table (id, schedule, task summary, last run, next run, enabled).

### `run <id>` — Trigger immediately (one-off)

```bash
/atlas routines run <routine_id>
```

Useful for testing or manual triggers without waiting for next scheduled fire.

## Implementation Pattern

The skill instructs Claude to use the **RemoteTrigger** tool (CC native) with the Routines API endpoints:

```
list:    GET  /v1/code/triggers
get:     GET  /v1/code/triggers/{trigger_id}
create:  POST /v1/code/triggers (body required)
update:  POST /v1/code/triggers/{trigger_id} (body, partial)
run:     POST /v1/code/triggers/{trigger_id}/run (optional body)
```

## Best Practices

- **Schedule expressions**: avoid `0 9 * * *` (everyone's 9am) — pick `7 9 * * *` instead
- **Cost predictability**: routines bill at standard API rates per execution; estimate frequency × tokens
- **Failure handling**: Routines retry per Anthropic policy; check status via `list`
- **Authentication**: RemoteTrigger uses session OAuth token, no manual key needed

## Examples

```bash
# Daily morning brief at off-peak minute
/atlas routines create --schedule="11 8 * * *" --task="brief moi sur emails non-lus + PRs ouverts"

# Weekly review every Friday 5pm
/atlas routines create --schedule="13 17 * * 5" --task="weekly retrospective: wins, blockers, next week priorities"

# Monthly cost analysis
/atlas routines create --schedule="7 9 1 * *" --task="cost report previous month: API spend + budget burn"

# Weekly CLAUDE.md drift check — Mon 08:00 Atlantic (sp4 CLAUDE.md SOTA Universal)
# Runs claudemd-drift-checker.sh across AXOIQ ecosystem, opens Forgejo issue if drift detected
/atlas routines create \
  --schedule="17 12 * * 1" \
  --task="Run scripts/claudemd-drift-checker.sh --repo-root ~/workspace_atlas --open-issue --json in atlas-plugin repo. Report any CLAUDE.md files with: line count >100, missing W3H sections (What/Why/How), or credential patterns. If drift found, summarize which repos need attention and what type of fix is needed."
```

## When NOT to use

- Active session polling → use `atlas-loop` (in-session, immediate)
- One-off task → just execute it now, don't schedule
- Long-running monitor → use `Monitor` tool (streaming events)

## Migration from atlas-loop

If you set up `atlas-loop` recurring tasks that should survive session close, migrate to atlas-routines:

```bash
# Old (in-session, dies with REPL)
/atlas loop start --interval=1h --task="check CI"

# New (cloud, persistent)
/atlas routines create --schedule="3 * * * *" --task="check CI status of feat/v6 branch"
```

## Related Skills

- `atlas-loop` (in-session CronCreate, complementary)
- `reminder-scheduler` (one-shot reminders)
- `atlas-team` (parallel agents, not loops)

## See ADR

`.blueprint/adrs/0002-routines-vs-croncreate.md` for design rationale.

---

# Migration Adapter (W2.4 — Wave 2 cron migration)

> **Goal**: Migrate Forgejo Actions weekly tasks + cron locaux → Anthropic Routines (cloud-native, no local cron infrastructure).
> **Plan**: `.blueprint/plans/ultrathink-regarde-ce-qui-abundant-petal.md` Section H W2.4
> **Tag**: ATLAS v7.0
> **Status**: 3 routines déjà actives chez Seb (canary hourly, drift weekly, backup daily). Adapter ajoute 4 cibles supplémentaires.

## Migration Target List

Cron jobs / Forgejo Actions identifiées comme candidats pour migration vers Anthropic Routines:

| # | Source | Current Mechanism | Schedule (suggéré) | Justification migration |
|---|--------|-------------------|---------------------|-------------------------|
| 1 | **Weekly disk audit** | Forgejo Actions on Woodpecker (hebdo) | `23 6 * * 0` (Sun 06:23 UTC) | Pure observability — pas besoin de runner local. Sortie = report dans memory/ + alert si seuil dépassé. |
| 2 | **OAuth health monitor** | Cron local VM 550 (every 6h) | `19 */6 * * *` (every 6h, +19min off-peak) | Détection précoce OAuth refresh-token race (cf. `lesson_oauth_refresh_token_race.md`). Cloud routine = no SPOF VM 550. |
| 3 | **Git maintenance** | Cron local hebdo (atlas user) | `41 3 * * 6` (Sat 03:41 UTC) | `git gc` + prune cross-repos. Cloud routine peut SSH ou utiliser Forgejo API. |
| 4 | **PBS backup integrity check** | Daily PBS native | **KEEP NATIVE** | PBS healthcheck = mieux servi par PBS lui-même (intégré, garanties cohérence). NE PAS migrer. |
| 5 | **Authentik scope sweep** | Manual (W6.2 in main 2026-04-30) | `27 9 * * 1` (Mon 09:27 UTC) | Audit hebdomadaire des 18 providers Authentik (cf. `lesson_authentik_provider_zero_mappings_silent_oidc_fail.md`). Calls authentik-audit skill. |

**Total candidates**: 4 actionnables (PBS exclu volontairement).

**Schedule discipline**: tous les schedules utilisent des minutes off-peak (pas :00, :15, :30, :45) pour respecter Anthropic Routines best practice.

## Migration CLI Subcommands

### `migrate <name>` — Migrate a single target

```bash
/atlas routines migrate weekly-disk-audit
/atlas routines migrate oauth-health-monitor
/atlas routines migrate git-maintenance
/atlas routines migrate authentik-scope-sweep
```

Behavior (idempotent + HITL gate):
1. Lookup target in migration table above
2. Show diff: existing cron entry vs proposed Routine spec
3. **HITL gate** — AskUserQuestion (irreversible: creates routine + disables source)
4. On approval:
   - Create Anthropic Routine via RemoteTrigger
   - Disable source cron (`crontab -l | grep -v <pattern> | crontab -`) OR Forgejo Actions workflow (rename to `*.disabled`)
   - Append entry to `~/.atlas/routines-migrated.jsonl` (audit trail)
5. Output: routine_id + verification command

### `migrate-all` — Migrate all 4 actionable targets

```bash
/atlas routines migrate-all
```

Behavior:
- Iterates the 4 actionable targets (skips PBS)
- HITL gate **per migration** (no batch approval — irreversibility per item)
- Stops on first user `no` (fail-safe)
- Final report: N migrated / N skipped / N failed

### `status` — Show all active routines with telemetry

```bash
/atlas routines status
```

Output (table):
| Routine ID | Name | Schedule | Last Run | Next Run | Success Rate (7d) | Status |
|-----------|------|----------|----------|----------|-------------------|--------|

Reads from RemoteTrigger `list` + Anthropic Routines run history endpoint.

### `suggest` — Analyze remaining cron / Forgejo Actions

```bash
/atlas routines suggest
```

Behavior:
- Invokes `scripts/routine-migrator.sh` (read-only)
- Parses `crontab -l` + `.forgejo/workflows/*.yml`
- For each entry NOT already in migration table, suggests Routine equivalent
- Output: markdown table with proposed schedule + prompt template
- **No mutation** — recommendation only

### `list --include-migrated` — Show all routines + migration status

```bash
/atlas routines list --include-migrated
```

Adds column `[MIGRATED]` for routines created via `migrate`/`migrate-all`. Reads `~/.atlas/routines-migrated.jsonl` for tagging.

## Migration Workflow (HITL gate per target)

```
1. atlas routines migrate <name>
   ↓
2. Read source mechanism (crontab / Forgejo workflow)
   ↓
3. Show proposed Routine spec (schedule + prompt)
   ↓
4. AskUserQuestion: "Migrate <name> to Routine? (creates routine + disables source)"
   ├─ no  → abort, source unchanged
   └─ yes → continue
   ↓
5. Create Routine via RemoteTrigger POST /v1/code/triggers
   ↓
6. Verify routine created (GET /v1/code/triggers/{id})
   ↓
7. Disable source:
   - Cron: backup crontab → remove line → reinstall
   - Forgejo Actions: rename workflow.yml → workflow.yml.disabled + commit
   ↓
8. Log to ~/.atlas/routines-migrated.jsonl
   ↓
9. Output: routine_id + first scheduled run timestamp
```

## Verification

After migration:

```bash
# Verify routine created
/atlas routines list --include-migrated | grep <name>

# Verify source disabled
crontab -l | grep <pattern>  # should be empty
ls .forgejo/workflows/*.disabled  # for Forgejo migrations

# Verify audit trail
tail -1 ~/.atlas/routines-migrated.jsonl
```

## Rollback

If a migrated routine fails or needs reversal:

```bash
# Delete the cloud routine
/atlas routines delete <routine_id>

# Restore source
# Cron: re-add line to crontab from ~/.atlas/routines-migrated.jsonl backup field
# Forgejo: rename workflow.yml.disabled → workflow.yml + commit
```

## Constraints (NON-NEGOTIABLE)

- ❌ NEVER migrate without HITL gate (irreversible — creates external resource + disables source)
- ❌ NEVER batch-approve (`--yes`) — each migration is its own decision
- ❌ NEVER migrate PBS backup integrity check (native > cloud for backup verify)
- ✅ ALWAYS log to `~/.atlas/routines-migrated.jsonl` with timestamp + source backup
- ✅ ALWAYS verify routine creation before disabling source (avoid double-disable)

## Companion Script

`scripts/routine-migrator.sh` — Bash helper that performs read-only analysis of cron + Forgejo Actions and outputs migration suggestions. Used by `suggest` subcommand.