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>
This commit is contained in:
149
docs/adr/ADR-005-scheduled-agent-execution.md
Normal file
149
docs/adr/ADR-005-scheduled-agent-execution.md
Normal file
@@ -0,0 +1,149 @@
|
||||
---
|
||||
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 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)
|
||||
Reference in New Issue
Block a user