tegwick
93bf49479b
Some checks failed
ci / test (push) Has been cancelled
Add --engagement, --agents, and --bootstrap-cadence flags to scaffold hourly/daily/weekly engagement schedules. Hourly bootstrap keeps cadence: daily with hourly cron overrides per coulomb-loop ADR-003. Document activity-core requirements in activity-core-handoff-engagement.md. Closes KAIZEN-WP-0008 T02 and T04.
101 lines
3.2 KiB
Markdown
101 lines
3.2 KiB
Markdown
# `.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).
|