tegwick
3b2edd4a9e
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>
369 lines
13 KiB
Markdown
369 lines
13 KiB
Markdown
---
|
||
id: KAIZEN-WP-0006
|
||
type: workplan
|
||
title: "Scheduled Agent Execution via activity-core (v1.3.0)"
|
||
domain: custodian
|
||
repo: kaizen-agentic
|
||
status: done
|
||
owner: kaizen-agentic
|
||
topic_slug: custodian
|
||
state_hub_workstream_id: d4edb92b-526f-4ee4-8efe-a9fa84ab6dff
|
||
depends_on:
|
||
- KAIZEN-WP-0003
|
||
- KAIZEN-WP-0004
|
||
created: "2026-06-17"
|
||
updated: "2026-06-17"
|
||
tasks:
|
||
- id: T01
|
||
state_hub_task_id: f513cf74-6e32-4dce-a3bc-2995f98a30de
|
||
status: done
|
||
title: Write ADR-005 scheduled agent execution contract
|
||
- id: T02
|
||
state_hub_task_id: dcb8d674-5472-4657-85bc-02ca9890fb92
|
||
status: done
|
||
title: Define .kaizen/schedule.yml schema and example
|
||
- id: T03
|
||
state_hub_task_id: 1f9a4959-d200-4d7b-8666-96472e23d820
|
||
status: done
|
||
title: Add kaizen-agentic schedule validate command
|
||
- id: T04
|
||
state_hub_task_id: 13ab4b76-ded2-4613-b8e2-15ab206d8c57
|
||
status: done
|
||
title: Document fleet roster and repo opt-in in INTEGRATION_PATTERNS
|
||
- id: T05
|
||
state_hub_task_id: 685b35f3-af20-483a-9136-150f5fff68dd
|
||
status: done
|
||
title: Draft state-hub roster query design for activity-core resolver
|
||
- id: T06
|
||
state_hub_task_id: 5f0a0859-3ff5-4ec8-b916-35486f045b2b
|
||
status: done
|
||
title: Draft discover_kaizen_scheduled_repos context resolver spec
|
||
- id: T07
|
||
state_hub_task_id: 2fd0f00c-5cf1-47bd-9c12-aee65bca5932
|
||
status: done
|
||
title: Draft weekly-agent-run ActivityDefinition template
|
||
- id: T08
|
||
state_hub_task_id: cc0565bc-ccd4-4739-9c7e-088adaa9834b
|
||
status: done
|
||
title: Open activity-core handoff issue for resolver and definitions
|
||
- id: T09
|
||
state_hub_task_id: 23aeff77-3429-438b-a395-5c7b5dc2824e
|
||
status: done
|
||
title: Implement kaizen-agentic schedule prepare command
|
||
- id: T10
|
||
state_hub_task_id: cba9685b-408f-4292-8169-9965e7ad5c5b
|
||
status: done
|
||
title: Bundle memory brief metrics and agent prompt in prepare output
|
||
- id: T11
|
||
state_hub_task_id: 7c1b049b-5566-4b5e-9d82-d9c29fab0c84
|
||
status: done
|
||
title: Add schedule init scaffold for new repos
|
||
- id: T12
|
||
state_hub_task_id: 80a8e98a-9146-4a58-8fd3-8c37f7893960
|
||
status: done
|
||
title: Unit tests for schedule validate and prepare
|
||
- id: T13
|
||
state_hub_task_id: 9aee6348-d5ad-4413-b01c-5588b07c8ede
|
||
status: done
|
||
title: Pilot ActivityDefinition for weekly coach on custodian repos
|
||
- id: T14
|
||
state_hub_task_id: 697e612b-7531-4329-82fb-b0423ba86904
|
||
status: done
|
||
title: Pilot ActivityDefinition for weekly optimization review
|
||
- id: T15
|
||
state_hub_task_id: 92db5130-2212-4780-ab8f-1de3adf6c6f8
|
||
status: done
|
||
title: Smoke test end-to-end on two preselected repos
|
||
- id: T16
|
||
state_hub_task_id: bbecdcbf-42b8-4b48-9f85-e4c10e4ff3ab
|
||
status: done
|
||
title: Document operator enablement in PACKAGE_RELEASE and agency-framework
|
||
- id: T17
|
||
state_hub_task_id: a9e91d4b-990a-457a-9591-d1243db5b386
|
||
status: done
|
||
title: Emit kaizen.schedule.prepared event payload spec for activity-core
|
||
- id: T18
|
||
state_hub_task_id: 73986472-bf19-4b13-af1b-6505ab944459
|
||
status: done
|
||
title: Update wiki/EcosystemIntegration.md and CHANGELOG for v1.3.0
|
||
---
|
||
|
||
# KAIZEN-WP-0006 — Scheduled Agent Execution via activity-core
|
||
|
||
**Status:** done
|
||
**Owner:** kaizen-agentic
|
||
**Repo:** kaizen-agentic
|
||
**Target version:** 1.3.0
|
||
**Depends on:** WP-0003 (metrics CLI), WP-0004 Part 2 (ActivityDefinition drafts)
|
||
|
||
## Goal
|
||
|
||
Enable kaizen agents to run **on a regular schedule** against **preselected repos**,
|
||
orchestrated by **activity-core** and prepared by **kaizen-agentic** — without
|
||
this repo owning Temporal workers or LLM runtime.
|
||
|
||
Today, agents are markdown instruction sets invoked in coding-agent sessions.
|
||
WP-0004 committed three metrics-focused ActivityDefinitions (`enabled: false`) but
|
||
no general **agent dispatch** path, no **repo roster**, and no **per-repo schedule
|
||
manifest**. This workplan closes that gap.
|
||
|
||
### What “scheduled agent execution” means here
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
AC[activity-core cron] --> CR[context resolver]
|
||
CR --> ROSTER[preselected repos]
|
||
ROSTER --> RULE[ActivityDefinition rule]
|
||
RULE --> TASK[hub task per repo+agent]
|
||
TASK --> PREP[kaizen-agentic schedule prepare]
|
||
PREP --> SESSION[coding-agent session]
|
||
```
|
||
|
||
1. **activity-core** fires on cron (or event).
|
||
2. A **context resolver** returns repos from the preselected roster that have a
|
||
matching schedule entry and reachable `host_paths`.
|
||
3. For each `(repo, agent)` pair, activity-core creates a **task** (State Hub /
|
||
issue-core) with labels and a `schedule prepare` command.
|
||
4. A coding agent (human or automated session) runs `kaizen-agentic schedule prepare`
|
||
to assemble orientation: agent prompt, `memory brief`, metrics summary, repo
|
||
context — then executes the agent instructions in that repo.
|
||
|
||
Kaizen-agentic does **not** invoke Claude directly; it **prepares** and **validates**
|
||
the scheduled run contract.
|
||
|
||
---
|
||
|
||
## Background
|
||
|
||
| Layer | WP-0004 state | WP-0006 adds |
|
||
|-------|---------------|--------------|
|
||
| activity-core | Three proposed definitions (metrics only) | Agent-run definitions + roster resolver |
|
||
| kaizen-agentic | CLI for metrics/memory | `schedule` command group + `.kaizen/schedule.yml` |
|
||
| state-hub | Registered repos + `host_paths` | Fleet roster opt-in + schedule metadata |
|
||
| Execution | Manual session | Cron → task → prepared session bundle |
|
||
|
||
**Prior WP-0006 placeholder** (agent wizard, template validation, doc generation)
|
||
moves to **KAIZEN-WP-0007**.
|
||
|
||
---
|
||
|
||
## Part 1 — Schedule Contract (repo-local)
|
||
|
||
Declare which agents run how often in each opted-in repo.
|
||
|
||
### `.kaizen/schedule.yml` (draft shape)
|
||
|
||
```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
|
||
```
|
||
|
||
### Tasks
|
||
|
||
- [x] T01 — Write ADR-005: scheduled agent execution (roster, schedule file, dispatch, boundaries)
|
||
- [x] T02 — Add `docs/integrations/schedule-schema.md` + example under `docs/examples/.kaizen/schedule.yml`
|
||
- [x] T03 — Implement `kaizen-agentic schedule validate [--target PATH]` (schema + agent name checks)
|
||
|
||
### Definition of done
|
||
|
||
- ADR-005 accepted; referenced from `docs/agency-framework.md`
|
||
- Invalid schedule files fail validation with actionable errors
|
||
- Only agents installed in the project (or fleet defaults) may appear in schedule
|
||
|
||
---
|
||
|
||
## Part 2 — Fleet Roster (preselected repos)
|
||
|
||
Define which registered repos participate in fleet scheduling.
|
||
|
||
### Roster sources (combined)
|
||
|
||
| Source | Purpose |
|
||
|--------|---------|
|
||
| State Hub `GET /repos/` | Canonical slug list + `host_paths` |
|
||
| Repo opt-in | `.kaizen/schedule.yml` exists and `version` set |
|
||
| Optional hub flag | `kaizen_schedule_enabled: true` in repo metadata (design in T05) |
|
||
|
||
### Tasks
|
||
|
||
- [x] T04 — Extend `docs/INTEGRATION_PATTERNS.md` Pattern 2 with roster + schedule model
|
||
- [x] T05 — Design doc: state-hub fields/filters for kaizen-scheduled repos (no state-hub code in this repo)
|
||
- [x] T06 — Spec `discover_kaizen_scheduled_repos` resolver for activity-core (inputs, output shape, errors)
|
||
|
||
### Definition of done
|
||
|
||
- Operators can list which repos are schedule-eligible without reading activity-core code
|
||
- Resolver spec is sufficient for activity-core implementers to add adapter (separate repo PR)
|
||
|
||
---
|
||
|
||
## Part 3 — activity-core ActivityDefinitions (handoff)
|
||
|
||
Generalize WP-0004 metrics definitions into **agent-run** definitions.
|
||
|
||
### New reference definitions (kaizen-agentic commits drafts)
|
||
|
||
| Definition | Trigger | Agent | Prepare command |
|
||
|------------|---------|-------|-----------------|
|
||
| `weekly-coach-orientation` | Cron Mon 09:00 | `coach` | `schedule prepare coach` |
|
||
| `weekly-optimization-review` | Cron Mon 10:00 | `optimization` | `schedule prepare optimization` |
|
||
| `weekly-metrics-optimize` | *(existing)* | — | `metrics optimize` |
|
||
|
||
### Tasks
|
||
|
||
- [x] T07 — Add `docs/integrations/activity-definitions/weekly-coach-orientation.md`
|
||
- [x] T08 — Open activity-core coordination issue/PR checklist (resolver + sync + `enabled: false` pilot)
|
||
- [x] T17 — Document `kaizen.schedule.prepared` event payload (for future event-driven runs)
|
||
|
||
### Definition of done
|
||
|
||
- Definition files use `for_each` over resolver output `context.scheduled_runs`
|
||
- Handoff checklist mirrors WP-0004 Pattern 2 activation steps
|
||
- No scheduling code added to kaizen-agentic
|
||
|
||
---
|
||
|
||
## Part 4 — Dispatch Prepare CLI
|
||
|
||
Bridge schedule intent to session-executable orientation.
|
||
|
||
### Commands
|
||
|
||
```
|
||
kaizen-agentic schedule validate [--target PATH]
|
||
kaizen-agentic schedule init [--target PATH] # scaffold .kaizen/schedule.yml
|
||
kaizen-agentic schedule prepare <agent> [--target PATH] [--format markdown|json]
|
||
kaizen-agentic schedule list [--target PATH] # show enabled entries from schedule.yml
|
||
```
|
||
|
||
`schedule prepare` outputs a single bundle:
|
||
|
||
- Agent markdown (from installed or packaged `agents/agent-<name>.md`)
|
||
- `memory brief <agent>` output (if memory enabled)
|
||
- `metrics show <agent>` summary (if metrics exist)
|
||
- Repo SCOPE/TODO pointers when present
|
||
- Suggested session-close commands (`metrics record`, memory update)
|
||
|
||
### Tasks
|
||
|
||
- [x] T09 — Implement `schedule` CLI command group skeleton
|
||
- [x] T10 — Wire `prepare` to memory + metrics + agent loader (reuse existing CLI internals)
|
||
- [x] T11 — Implement `schedule init` with sensible defaults (coach + optimization weekly, disabled tdd-workflow)
|
||
- [x] T12 — Tests for validate, init, prepare (temp repo fixtures)
|
||
|
||
### Definition of done
|
||
|
||
- `schedule prepare coach` prints non-empty orientation for a repo with agents installed
|
||
- Prepare works offline (no State Hub required) given local `.kaizen/` state
|
||
- CLI cheat sheet updated
|
||
|
||
---
|
||
|
||
## Part 5 — Pilot and Enablement
|
||
|
||
Prove the loop on a small custodian repo set before fleet-wide enable.
|
||
|
||
### Pilot roster (initial)
|
||
|
||
- `kaizen-agentic` (dogfood)
|
||
- `the-custodian` (hub operator)
|
||
- One additional custodian-domain repo with `.kaizen/` state (TBD at pilot time)
|
||
|
||
### Tasks
|
||
|
||
- [x] T13 — Commit pilot `weekly-coach-orientation` definition; map to custodian pilot repos
|
||
- [x] T14 — Commit pilot `weekly-optimization-review` definition
|
||
- [x] T15 — Smoke test: dry-run activity-core → manual `schedule prepare` on two repos → verify task payload
|
||
- [x] T16 — Operator docs: credentials, PATH, Gitea index, enabling `enabled: true` in activity-core
|
||
- [x] T18 — `wiki/EcosystemIntegration.md`, `CHANGELOG [Unreleased]`, `TODO.md` pointer
|
||
|
||
### Definition of done
|
||
|
||
- Two repos run through prepare successfully on a fixed schedule (manual or dry-run cron)
|
||
- activity-core owners have a clear PR path to enable one definition in staging
|
||
- Progress event recorded in State Hub at pilot completion
|
||
|
||
---
|
||
|
||
## Sequencing
|
||
|
||
```
|
||
Part 1 (T01–T03) ──→ Part 4 (T09–T12) ──→ Part 5 (T13–T16)
|
||
│ │
|
||
Part 2 (T04–T06) ──→ Part 3 (T07–T08, T17)
|
||
```
|
||
|
||
Parts 1–2 can start in parallel. Part 4 depends on ADR + schema. Part 5 depends
|
||
on Part 3 drafts and Part 4 `prepare`. activity-core resolver implementation
|
||
runs in **activity-core** (parallel track after T06 spec).
|
||
|
||
Estimated effort: 4–6 sessions (kaizen-agentic) + 1–2 sessions (activity-core handoff).
|
||
|
||
---
|
||
|
||
## Out of Scope
|
||
|
||
- Implementing Temporal workflows or context resolvers in activity-core (handoff only)
|
||
- Headless Claude Code / cloud agent runner integration (future; prepare output is runner-agnostic)
|
||
- Scheduling all 20 agents fleet-wide in v1.3.0 (pilot: coach + optimization)
|
||
- Replacing human review for high-risk agents (sys-medic, releaseManager)
|
||
- WP-0007 items: agent selection wizard, template schema enforcement, doc generation
|
||
|
||
---
|
||
|
||
## Success Criteria
|
||
|
||
1. Operators declare a **preselected repo roster** and per-repo **schedules** without tribal knowledge.
|
||
2. activity-core can fire recurring tasks that reference `kaizen-agentic schedule prepare <agent>`.
|
||
3. A coding-agent session opened from a scheduled task has full orientation (memory + metrics + prompt).
|
||
4. Pilot runs on ≥2 custodian repos demonstrate the cron → task → prepare path.
|
||
|
||
---
|
||
|
||
## State Hub Task IDs
|
||
|
||
| Code | UUID |
|
||
|------|------|
|
||
| T01 | f513cf74-6e32-4dce-a3bc-2995f98a30de |
|
||
| T02 | dcb8d674-5472-4657-85bc-02ca9890fb92 |
|
||
| T03 | 1f9a4959-d200-4d7b-8666-96472e23d820 |
|
||
| T04 | 13ab4b76-ded2-4613-b8e2-15ab206d8c57 |
|
||
| T05 | 685b35f3-af20-483a-9136-150f5fff68dd |
|
||
| T06 | 5f0a0859-3ff5-4ec8-b916-35486f045b2b |
|
||
| T07 | 2fd0f00c-5cf1-47bd-9c12-aee65bca5932 |
|
||
| T08 | cc0565bc-ccd4-4739-9c7e-088adaa9834b |
|
||
| T09 | 23aeff77-3429-438b-a395-5c7b5dc2824e |
|
||
| T10 | cba9685b-408f-4292-8169-9965e7ad5c5b |
|
||
| T11 | 7c1b049b-5566-4b5e-9d82-d9c29fab0c84 |
|
||
| T12 | 80a8e98a-9146-4a58-8fd3-8c37f7893960 |
|
||
| T13 | 9aee6348-d5ad-4413-b01c-5588b07c8ede |
|
||
| T14 | 697e612b-7531-4329-82fb-b0423ba86904 |
|
||
| T15 | 92db5130-2212-4780-ab8f-1de3adf6c6f8 |
|
||
| T16 | bbecdcbf-42b8-4b48-9f85-e4c10e4ff3ab |
|
||
| T17 | a9e91d4b-990a-457a-9591-d1243db5b386 |
|
||
| T18 | 73986472-bf19-4b13-af1b-6505ab944459 |
|
||
|
||
**Hub workstream:** `kaizen-wp-0006-scheduled-agent-execution` (`d4edb92b-526f-4ee4-8efe-a9fa84ab6dff`)
|
||
|
||
---
|
||
|
||
## Notes
|
||
|
||
- WP-0004 `weekly-metrics-optimize` remains complementary; optimization agent schedule
|
||
may chain `schedule prepare optimization` then `metrics optimize` in task description
|
||
- `schedule prepare` output should be stable enough for activity-core task `description` templates
|
||
- Repo boundary: state-hub schema changes tracked in the-custodian; kaizen-agentic owns ADR + CLI + definition drafts
|
||
- Previous WP-0005 deferrals (wizard, validate schema, doc gen) → **KAIZEN-WP-0007**
|