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

id, type, title, domain, repo, status, owner, topic_slug, state_hub_workstream_id, depends_on, created, updated, tasks

id	type	title	domain	repo	status	owner	topic_slug	state_hub_workstream_id	depends_on	created	updated	tasks
KAIZEN-WP-0006	workplan	Scheduled Agent Execution via activity-core (v1.3.0)	custodian	kaizen-agentic	active	kaizen-agentic	custodian	d4edb92b-526f-4ee4-8efe-a9fa84ab6dff	KAIZEN-WP-0003 KAIZEN-WP-0004	2026-06-17	2026-06-17	id title status T01 Write ADR-005 scheduled agent execution contract todo id title status T02 Define .kaizen/schedule.yml schema and example todo id title status T03 Add kaizen-agentic schedule validate command todo id title status T04 Document fleet roster and repo opt-in in INTEGRATION_PATTERNS todo id title status T05 Draft state-hub roster query design for activity-core resolver todo id title status T06 Draft discover_kaizen_scheduled_repos context resolver spec todo id title status T07 Draft weekly-agent-run ActivityDefinition template todo id title status T08 Open activity-core handoff issue for resolver and definitions todo id title status T09 Implement kaizen-agentic schedule prepare command todo id title status T10 Bundle memory brief metrics and agent prompt in prepare output todo id title status T11 Add schedule init scaffold for new repos todo id title status T12 Unit tests for schedule validate and prepare todo id title status T13 Pilot ActivityDefinition for weekly coach on custodian repos todo id title status T14 Pilot ActivityDefinition for weekly optimization review todo id title status T15 Smoke test end-to-end on two preselected repos todo id title status T16 Document operator enablement in PACKAGE_RELEASE and agency-framework todo id title status T17 Emit kaizen.schedule.prepared event payload spec for activity-core todo id title status T18 Update wiki/EcosystemIntegration.md and CHANGELOG for v1.3.0 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

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