kaizen-agentic/docs/adr/ADR-005-scheduled-agent-execution.md

---
id: ADR-005
title: Scheduled Agent Execution Convention
status: accepted
date: "2026-06-17"
---

# ADR-005 — Scheduled Agent Execution Convention

## Status

Accepted

## Context

Kaizen agents are markdown instruction sets invoked in coding-agent sessions.
ADR-004 added project-scoped metrics; WP-0004 committed three metrics-focused
`ActivityDefinition` drafts (`enabled: false`). What is still missing is a way to
run **agents themselves** — not just the metrics optimizer — on a **regular
cadence** against a **preselected set of repos**, without kaizen-agentic owning
Temporal workers, cron, or an LLM runtime.

The ecosystem already separates concerns:

- **activity-core** owns scheduling (cron/event → task creation).
- **state-hub** owns the canonical repo roster and `host_paths`.
- **kaizen-agentic** owns the agents, project memory, and metrics.

A scheduled agent run therefore needs a contract that crosses these repos
without merging them.

## Decision

Introduce a **repo-local schedule manifest** and a **prepare** step. The
end-to-end flow:

```
activity-core cron
  → context resolver (roster ∩ repos with schedule.yml)
  → task per (repo, agent)
  → coding-agent session runs `kaizen-agentic schedule prepare <agent>`
  → session executes the agent instructions in that repo
```

kaizen-agentic's responsibilities are exactly two: **declare** the schedule
(`.kaizen/schedule.yml`) and **prepare** an orientation bundle for a run. It
does **not** fire cron, create tasks, or invoke Claude.

### 1. Schedule manifest — `.kaizen/schedule.yml`

A repo opts into fleet scheduling by committing this file:

```yaml
version: "1"
timezone: Europe/Berlin
agents:
  coach:
    cadence: weekly
    cron: "0 9 * * 1"      # optional override; default from ActivityDefinition
    enabled: true
  optimization:
    cadence: weekly
    cron: "0 10 * * 1"
    enabled: true
  tdd-workflow:
    cadence: monthly
    enabled: false
```

**Schema:**

| Key | Required | Type | Notes |
|-----|----------|------|-------|
| `version` | yes | string | Must be `"1"` |
| `timezone` | no | string | IANA tz; default supplied by ActivityDefinition |
| `agents` | yes | mapping | `agent-name → settings` |
| `agents.<name>.cadence` | yes | enum | `daily` \| `weekly` \| `monthly` |
| `agents.<name>.cron` | no | string | 5-field cron; overrides cadence default |
| `agents.<name>.enabled` | no | bool | Default `true` |

**Validation rules** (`kaizen-agentic schedule validate`):

- `version` must equal `"1"`.
- Every agent key must be an installed or packaged agent name.
- `cadence` must be one of the allowed values.
- Duplicate agent entries are rejected.

### 2. Roster (preselected repos)

A repo is **schedule-eligible** when **all** of:

1. It is a registered repo in state-hub (`GET /repos/`) with reachable
   `host_paths`.
2. It contains a valid `.kaizen/schedule.yml`.
3. (Optional, future) it carries a `kaizen_schedule_enabled: true` hub flag.

The resolver `discover_kaizen_scheduled_repos` (specified in
`docs/integrations/discover-kaizen-scheduled-repos.md`, implemented in
activity-core) intersects these sources and emits `context.scheduled_runs`.

### 3. Prepare bundle — `schedule prepare <agent>`

Assembles, from **local `.kaizen/` state only** (offline-safe):

- The agent prompt (`agents/agent-<name>.md`, installed or packaged).
- Project memory (`.kaizen/agents/<name>/memory.md`) when present.
- Metrics summary (`.kaizen/metrics/<name>/summary.json`) when present.
- Repo pointers (`SCOPE.md`, `TODO.md`) when present.
- Suggested session-close commands (`metrics record`, memory update).

Output is `markdown` (default) or `json` (`--format json`) so activity-core can
embed it in a task `description` or a runner can parse it.

### CLI interface

```
kaizen-agentic schedule init [--target PATH] [--timezone TZ] [--force]
kaizen-agentic schedule init --engagement <slug> [--agents A,B] [--bootstrap-cadence hourly|daily|weekly]
kaizen-agentic schedule validate [--target PATH]
kaizen-agentic schedule list [--target PATH] [--all]
kaizen-agentic schedule prepare <agent> [--target PATH] [--format markdown|json]
```

## Boundaries

- **No scheduling code** in kaizen-agentic. Cron and task creation belong to
  activity-core; the roster query belongs to state-hub.
- **No LLM invocation.** `prepare` produces a runner-agnostic bundle; a human or
  automated coding-agent session executes it.
- **State-hub schema changes** (roster opt-in flag) are designed here but
  implemented in `the-custodian` (repo boundary).

## Consequences

- Operators declare per-repo schedules and a fleet roster without tribal
  knowledge.
- activity-core can fire recurring tasks referencing `schedule prepare`.
- A scheduled session opens with full orientation (prompt + memory + metrics).
- The existing `weekly-metrics-optimize` definition (ADR-004 / WP-0004) remains
  complementary; an `optimization` agent run may chain `schedule prepare
  optimization` then `metrics optimize`.

## Related Documents

- [ADR-002: Project Memory Convention](ADR-002-project-memory-convention.md)
- [ADR-004: Project Metrics Convention](ADR-004-project-metrics-convention.md)
- [docs/integrations/schedule-schema.md](../integrations/schedule-schema.md)
- [docs/integrations/discover-kaizen-scheduled-repos.md](../integrations/discover-kaizen-scheduled-repos.md)
- [docs/agency-framework.md](../agency-framework.md)
- [KAIZEN-WP-0006](../../workplans/kaizen-agentic-WP-0006-scheduled-agent-execution.md)