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

id, title, status, date

id	title	status	date
ADR-005	Scheduled Agent Execution Convention	accepted	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:

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-004: Project Metrics Convention
• docs/integrations/schedule-schema.md
• docs/integrations/discover-kaizen-scheduled-repos.md
• docs/agency-framework.md
• KAIZEN-WP-0006