# `.kaizen/schedule.yml` Schema

The schedule manifest declares which kaizen agents run on what cadence in an
opted-in repo. It is the repo-local half of the scheduled-agent-execution
contract (ADR-005). activity-core reads it (via the roster resolver) to fire
recurring tasks; `kaizen-agentic schedule prepare` reads it indirectly by
preparing per-agent orientation.

Canonical example: [`docs/examples/.kaizen/schedule.yml`](../examples/.kaizen/schedule.yml).

## Location

```
<project-root>/.kaizen/schedule.yml
```

Lives alongside `.kaizen/agents/` (memory) and `.kaizen/metrics/`. Like those,
its presence is the **opt-in signal** for fleet scheduling.

## Fields

| Key | Required | Type | Default | Notes |
|-----|----------|------|---------|-------|
| `version` | yes | string | — | Must be `"1"` |
| `timezone` | no | string | from ActivityDefinition | IANA tz, e.g. `Europe/Berlin` |
| `agents` | yes | mapping | — | `agent-name → settings` |
| `agents.<name>.cadence` | yes | enum | — | `daily` \| `weekly` \| `monthly` |
| `agents.<name>.cron` | no | string | cadence default | 5-field cron expression |
| `agents.<name>.enabled` | no | bool | `true` | Set `false` to declare but pause |

## Example

```yaml
version: "1"
timezone: Europe/Berlin
agents:
  coach:
    cadence: weekly
    cron: "0 9 * * 1"
    enabled: true
  optimization:
    cadence: weekly
    cron: "0 10 * * 1"
    enabled: true
  tdd-workflow:
    cadence: monthly
    enabled: false
```

## Validation

```bash
kaizen-agentic schedule validate
```

Errors are emitted with actionable messages and a non-zero exit code:

- Missing or non-`"1"` `version`.
- `agents` not a mapping, or no agents declared.
- An agent name that is **not** installed or packaged (typo guard).
- A `cadence` outside `daily` / `weekly` / `monthly`.
- Duplicate agent entries.

Only agents available to the project (installed under `agents/` or packaged in
the distribution) may appear in a schedule.

## Scaffolding

```bash
kaizen-agentic schedule init                 # defaults: coach + optimization weekly
kaizen-agentic schedule init --timezone UTC  # override timezone
kaizen-agentic schedule init --force         # overwrite existing
kaizen-agentic schedule init --engagement coulomb-loop \
  --agents coach,optimization --bootstrap-cadence hourly
```

The default scaffold enables `coach` and `optimization` weekly and declares
`tdd-workflow` monthly but **disabled** (operator opts in deliberately).

**Engagement bootstrap** (`--engagement`) writes customer-loop presets: hourly
bootstrap uses `cadence: daily` with hourly `cron` overrides (coach `:15`,
optimization `:30`). See
[customer-engagement-playbook.md](customer-engagement-playbook.md).

## Listing

```bash
kaizen-agentic schedule list        # enabled entries only
kaizen-agentic schedule list --all  # include disabled
```

## Relationship to activity-core

The `cron` field is an **optional per-repo override**. When omitted, the cadence
maps to the default cron declared in the matching ActivityDefinition (e.g.
`weekly-coach-orientation` fires Mon 09:00). This keeps fleet-wide timing in one
place while letting individual repos shift their slot.

See [ADR-005](../adr/ADR-005-scheduled-agent-execution.md) and
[INTEGRATION_PATTERNS.md Pattern 2](../INTEGRATION_PATTERNS.md).