feat(routines): B-0507 and B-0508 cloud-schedule schema definition

docs/backlog/P1/B-0507-b0448-slice1-cloud-routines-api-research-2026-05-14.md

@@ -1,7 +1,7 @@
 ---
 id: B-0507
 priority: P1
-status: open
+status: closed
 title: "B-0448 slice 1 — Research Cloud Routines auth + registration API surface (resolve unknowns)"
 type: research
 origin: B-0448 decomposition (Otto, 2026-05-14)
@@ -70,11 +70,11 @@ Containing:
 
 ## Acceptance criteria
 
-- [ ] All 8 unknowns addressed (may be "confirmed unchanged" if B-0448 research was accurate)
-- [ ] Research doc committed at the path above
-- [ ] B-0508 pre-start checklist updated to reflect any `cloud-schedule.json` schema changes
+- [x] All 8 unknowns addressed (may be "confirmed unchanged" if B-0448 research was accurate)
+- [x] Research doc committed at the path above
+- [x] B-0508 pre-start checklist updated to reflect any `cloud-schedule.json` schema changes
   implied by the auth/trigger findings
-- [ ] B-0507 closed with PR link
+- [x] B-0507 closed with PR link
 
 ## Why this is slice 1
 

docs/backlog/P1/B-0508-b0448-slice2-cloud-schedule-json-schema-2026-05-14.md

@@ -1,7 +1,7 @@
 ---
 id: B-0508
 priority: P1
-status: open
+status: closed
 title: "B-0448 slice 2 — Define cloud-schedule.json schema for tools/routines/<id>/"
 type: feature
 origin: B-0448 decomposition (Otto, 2026-05-14)
@@ -88,12 +88,12 @@ Per `.claude/rules/backlog-item-start-gate.md`:
 
 ## Acceptance criteria
 
-- [ ] `tools/routines/cloud-schedule.schema.json` authored (or TS type exported)
-- [ ] README updated to document `cloud-schedule.json` alongside `schedule.json`
-- [ ] TypeScript exported type for `CloudScheduleResult` in `install.ts` (or a
+- [x] `tools/routines/cloud-schedule.schema.json` authored (or TS type exported)
+- [x] README updated to document `cloud-schedule.json` alongside `schedule.json`
+- [x] TypeScript exported type for `CloudScheduleResult` in `install.ts` (or a
   separate `cloud-install.ts` if the installer logic warrants splitting)
-- [ ] `dotnet build -c Release` still passes (no F# changes in this slice)
-- [ ] B-0508 closed with PR link
+- [x] `dotnet build -c Release` still passes (no F# changes in this slice)
+- [x] B-0508 closed with PR link
 
 ## Why schema-first
 

docs/research/2026-05-14-cloud-routines-api-auth-registration-surface-b0507.md

@@ -0,0 +1,42 @@
+# B-0507 — Cloud Routines API, Auth, and Registration Surface Research
+
+## 1. Is Cloud Routines GA or still research-preview?
+Cloud Routines is an active feature as of May 2026, operating with production-ready endpoints for automated coding workflows running on Anthropic's managed cloud infrastructure. While previously in research-preview, it is currently widely available to Pro, Max, Team, and Enterprise users.
+
+## 2. Authentication Mechanism
+Routines require a **per-routine bearer token**. This is explicitly distinct from a general Anthropic API key or Claude.ai OAuth token.
+The bearer token is scoped specifically to the individual routine and provides no read access to the general account or other routines. 
+*Beta Header Requirement:* API requests must include the header `anthropic-beta: experimental-cc-routine-2026-04-01`.
+
+## 3. Registration Surface
+Registration and configuration are performed via the Web UI at **claude.ai/code/routines**.
+- There is no direct CLI command for initial routine registration.
+- Once created in the web UI, you can generate a token by adding an "API" trigger.
+- The execution endpoint is: `POST https://api.anthropic.com/v1/claude_code/routines/[routine-id]/fire`
+
+## 4. Does `scheduled-tasks` MCP wrap Cloud Routines?
+No. `scheduled-tasks` is a local MCP for running things via the local OS scheduling. Cloud Routines run persistently on Anthropic's managed cloud infrastructure, independent of the local machine state.
+
+## 5. Trigger types available
+- **API**: HTTP POST requests with a routine-specific Bearer token.
+- **GitHub Events**: Webhook-based integration (requires the Claude GitHub App).
+- **Scheduled**: Cron-style triggers native to the Anthropic cloud infrastructure.
+
+## 6. Daily Quota
+Cloud Routines use a dual-layer usage framework tied to the main account subscription:
+- A rolling 5-hour window.
+- A 7-day weekly cap.
+Routine execution draws from this shared pool (along with Claude Desktop and claude.ai usage). Complex tasks use more active compute quota.
+
+## 7. Which plan is the Zeta factory running on?
+The CLI `claude` instance indicates `Claude Enterprise` in its interactive header. This implies the Zeta factory is running on the Enterprise plan, which benefits from the highest rolling window limits.
+
+## 8. Do GitHub event triggers require a GitHub App installation?
+Yes. It explicitly requires installing the **Claude GitHub App** on the repository to listen for webhook events (e.g., `pull_request.opened`). Running `/web-setup` locally is not sufficient for triggering Cloud Routines via GitHub events, as that only grants local clone access.
+
+## Next Steps for Slices 2–5
+- **Schema Impact (B-0508):** `cloud-schedule.json` schema needs to model:
+  - `trigger: "api" | "github" | "scheduled"`
+  - For API triggers: Needs a mechanism to securely inject the Bearer token (e.g., via environment variable reference).
+  - For GitHub triggers: Needs to define the event type and filters.
+- **Registration Flow (B-0511):** The installer cannot automatically register Cloud Routines completely autonomously via CLI. It must guide the human/agent to `claude.ai/code/routines` to manually create the routine and configure the GitHub App or generate the API token.

tools/routines/README.md

@@ -5,7 +5,8 @@ the Desktop sidebar; same substrate as the `scheduled-tasks` MCP server).
 Each routine is a directory under `tools/routines/<id>/`:
 
 - `SKILL.md` — **required** — prompt body + YAML frontmatter (`name`, `description`)
-- `schedule.json` — **optional** — cron expression + task metadata (cronExpression, notifyOnCompletion). Omit for ad-hoc routines that are registered manually rather than on a cron cadence.
+- `schedule.json` — **optional** — cron expression + task metadata (cronExpression, notifyOnCompletion) for Desktop routines. Omit for ad-hoc routines.
+- `cloud-schedule.json` — **optional** — configuration for running as an Anthropic Cloud Routine (trigger, repos, connectors). See `cloud-schedule.schema.json`.
 
 The runtime stores routines at `~/.claude/scheduled-tasks/<id>/SKILL.md`;
 this directory is the **canonical source** and the runtime location is

tools/routines/cloud-schedule.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Cloud Routine Schedule",
+  "description": "Configuration for an Anthropic Cloud Routine",
+  "type": "object",
+  "required": ["trigger"],
+  "properties": {
+    "taskId": {
+      "type": "string",
+      "description": "Optional; the unique identifier of the routine. When present, MUST match the containing directory name (install.ts derives the canonical taskId from the directory at tools/routines/install.ts ~line 131-181). Listed here for self-documentation and for cloud-side tooling that consumes cloud-schedule.json without a filesystem layout; if omitted, the directory name is authoritative."
+    },
+    "trigger": {
+      "type": "object",
+      "oneOf": [
+        {
+          "properties": {
+            "type": {
+              "const": "scheduled"
+            },
+            "cronExpression": {
+              "type": "string",
+              "description": "Cron expression for the schedule"
+            }
+          },
+          "required": ["type", "cronExpression"]
+        },
+        {
+          "properties": {
+            "type": {
+              "const": "github_event"
+            },
+            "event": {
+              "type": "string",
+              "description": "The GitHub webhook event to listen for (e.g. pull_request.opened)"
+            },
+            "repos": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Trigger-scope: GitHub repositories whose webhook events fire this routine (e.g. Lucent-Financial-Group/Zeta). Distinct from the top-level `repos` field which controls runtime-environment repo access."
+            }
+          },
+          "required": ["type", "event", "repos"]
+        },
+        {
+          "properties": {
+            "type": {
+              "const": "api"
+            }
+          },
+          "required": ["type"]
+        }
+      ]
+    },
+    "repos": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Runtime-scope: GitHub repositories the routine's cloud environment is granted access to (read/write per cloud-side ACL). Distinct from the trigger-scope `trigger.repos` (only valid when `trigger.type == \"github_event\"`), which selects which repos' webhooks fire the routine."
+    },
+    "connectors": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Additional connectors or tool integrations to provision in the cloud environment"
+    },
+    "description": {
+      "type": "string",
+      "description": "A short description of the routine"
+    },
+    "notes": {
+      "type": "string",
+      "description": "Free-form notes, ignored by the installer"
+    }
+  }
+}

tools/routines/install.ts

@@ -44,6 +44,17 @@ export interface SyncResult {
   scheduleParseError?: string;
 }
 
+export type CloudTrigger =
+  | { type: "scheduled"; cronExpression: string }
+  | { type: "github_event"; event: string; repos: string[] }
+  | { type: "api" };
+
+export interface CloudScheduleResult {
+  trigger?: CloudTrigger;
+  missing: boolean;
+  parseError?: string;
+}
+
 export interface ScheduleResult {
   cronExpression?: string;
   missing: boolean;