--- id: KAIZEN-WP-0006 type: workplan title: "Scheduled Agent Execution via activity-core (v1.3.0)" domain: custodian repo: kaizen-agentic status: active 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 title: Write ADR-005 scheduled agent execution contract status: todo - id: T02 title: Define .kaizen/schedule.yml schema and example status: todo - id: T03 title: Add kaizen-agentic schedule validate command status: todo - id: T04 title: Document fleet roster and repo opt-in in INTEGRATION_PATTERNS status: todo - id: T05 title: Draft state-hub roster query design for activity-core resolver status: todo - id: T06 title: Draft discover_kaizen_scheduled_repos context resolver spec status: todo - id: T07 title: Draft weekly-agent-run ActivityDefinition template status: todo - id: T08 title: Open activity-core handoff issue for resolver and definitions status: todo - id: T09 title: Implement kaizen-agentic schedule prepare command status: todo - id: T10 title: Bundle memory brief metrics and agent prompt in prepare output status: todo - id: T11 title: Add schedule init scaffold for new repos status: todo - id: T12 title: Unit tests for schedule validate and prepare status: todo - id: T13 title: Pilot ActivityDefinition for weekly coach on custodian repos status: todo - id: T14 title: Pilot ActivityDefinition for weekly optimization review status: todo - id: T15 title: Smoke test end-to-end on two preselected repos status: todo - id: T16 title: Document operator enablement in PACKAGE_RELEASE and agency-framework status: todo - id: T17 title: Emit kaizen.schedule.prepared event payload spec for activity-core status: todo - id: T18 title: Update wiki/EcosystemIntegration.md and CHANGELOG for v1.3.0 status: todo --- # KAIZEN-WP-0006 — Scheduled Agent Execution via activity-core **Status:** active **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 - [ ] T01 — Write ADR-005: scheduled agent execution (roster, schedule file, dispatch, boundaries) - [ ] T02 — Add `docs/integrations/schedule-schema.md` + example under `docs/examples/.kaizen/schedule.yml` - [ ] 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 - [ ] T04 — Extend `docs/INTEGRATION_PATTERNS.md` Pattern 2 with roster + schedule model - [ ] T05 — Design doc: state-hub fields/filters for kaizen-scheduled repos (no state-hub code in this repo) - [ ] 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 - [ ] T07 — Add `docs/integrations/activity-definitions/weekly-coach-orientation.md` - [ ] T08 — Open activity-core coordination issue/PR checklist (resolver + sync + `enabled: false` pilot) - [ ] 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 [--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-.md`) - `memory brief ` output (if memory enabled) - `metrics show ` summary (if metrics exist) - Repo SCOPE/TODO pointers when present - Suggested session-close commands (`metrics record`, memory update) ### Tasks - [ ] T09 — Implement `schedule` CLI command group skeleton - [ ] T10 — Wire `prepare` to memory + metrics + agent loader (reuse existing CLI internals) - [ ] T11 — Implement `schedule init` with sensible defaults (coach + optimization weekly, disabled tdd-workflow) - [ ] 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 - [ ] T13 — Commit pilot `weekly-coach-orientation` definition; map to custodian pilot repos - [ ] T14 — Commit pilot `weekly-optimization-review` definition - [ ] T15 — Smoke test: dry-run activity-core → manual `schedule prepare` on two repos → verify task payload - [ ] T16 — Operator docs: credentials, PATH, Gitea index, enabling `enabled: true` in activity-core - [ ] 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 `. 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 | *(pending hub registration)* | | T02 | *(pending)* | | T03 | *(pending)* | | T04 | *(pending)* | | T05 | *(pending)* | | T06 | *(pending)* | | T07 | *(pending)* | | T08 | *(pending)* | | T09 | *(pending)* | | T10 | *(pending)* | | T11 | *(pending)* | | T12 | *(pending)* | | T13 | *(pending)* | | T14 | *(pending)* | | T15 | *(pending)* | | T16 | *(pending)* | | T17 | *(pending)* | | T18 | *(pending)* | **Hub workstream:** *(pending)* `kaizen-wp-0006-scheduled-agent-execution` --- ## 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**