kaizen-agentic/workplans/KAIZEN-WP-0006-scheduled-agent-execution.md

---
id: KAIZEN-WP-0006
type: workplan
title: "Scheduled Agent Execution via activity-core (v1.3.0)"
domain: agents
repo: kaizen-agentic
status: finished
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
  state_hub_workstream_id: "d4edb92b-526f-4ee4-8efe-a9fa84ab6dff"
---

# KAIZEN-WP-0006 — Scheduled Agent Execution via activity-core

**Status:** finished
**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**