Files

tegwick 3b2edd4a9e feat: scheduled agent execution via activity-core (WP-0006, v1.3.0)

Enable kaizen agents to run on a regular cadence against a preselected repo
roster, orchestrated by activity-core and prepared by kaizen-agentic — without
this repo owning cron, Temporal workers, or an LLM runtime.

CLI + module:
- src/kaizen_agentic/schedule.py — .kaizen/schedule.yml parse/validate/scaffold
- `kaizen-agentic schedule` group: init, validate, list, prepare <agent>
  (prepare bundles agent prompt + memory + metrics + repo pointers, offline)
- tests/test_schedule_cli.py — 15 tests

Contract & design:
- ADR-005 scheduled agent execution; schema doc + example manifest
- discover_kaizen_scheduled_repos resolver spec, state-hub roster fields,
  kaizen.schedule.prepared event payload, activity-core handoff checklist
- INTEGRATION_PATTERNS Pattern 2 extended with roster model

ActivityDefinition drafts (enabled: false):
- weekly-coach-orientation, weekly-optimization-review

Docs: agency-framework, CLI cheat sheet, PACKAGE_RELEASE runner prereqs,
EcosystemIntegration, CHANGELOG, TODO. Workplan closed (status: done).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-17 08:19:51 +02:00

5.3 KiB

Raw Blame History

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:

It is a registered repo in state-hub (GET /repos/) with reachable host_paths.
It contains a valid .kaizen/schedule.yml.
(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 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.

5.3 KiB Raw Blame History