kaizen-agentic/workplans/kaizen-agentic-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: 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)

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 <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

• 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 <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