docs: add WP-0006 scheduled agent execution workplan

Define activity-core scheduling for kaizen agents on preselected repos: schedule manifest, prepare CLI, roster resolver handoff, and custodian pilot. Point TODO/SCOPE at v1.3.0 active work.
2026-06-17 01:13:10 +02:00
parent b1fceeebc8
commit df899abd98
3 changed files with 356 additions and 10 deletions
--- a/SCOPE.md
+++ b/SCOPE.md
@@ -74,7 +74,7 @@ This repo is the canonical home for the **KaizenAgentic** operating model (`INTE
 - Implementation: 20 agents, full CLI (`metrics`, `memory`, `feedback`), agency memory + ADR-004 metrics + optimizer wiring
 - Stability: CLI stable (Click workaround in place); Gitea CI on main; publish workflow on `v*` tags
 - Usage: internal dev projects and Custodian MCP hub-wide; pip install via Gitea extra index
- Active work: **WP-0005** (adoption polish, fleet parity, publish verification → v1.2.0)
+- Active work: **WP-0006** (scheduled agent execution via activity-core → v1.3.0)

 ---

--- a/TODO.md
+++ b/TODO.md
@@ -10,18 +10,14 @@ The structure organizes **future tasks** by their impact, just as a changelog or

 ## [Unreleased] - *Active Vibe-Coding State* 💡

-Tasks in workplan: `workplans/kaizen-agentic-WP-0005-adoption-parity.md` (v1.2.0)
+Tasks in workplan: `workplans/kaizen-agentic-WP-0006-scheduled-agent-execution.md` (v1.3.0)

 ### To Add
-* **Gitea publish pipeline verification** — secrets + workflow smoke test
-* **`make agents-sync-package`** — keep `data/agents/` aligned with `agents/`
-* **Install doc sweep** — HELLO_WORLD, CLI_CHEAT_SHEET, AGENT_DISTRIBUTION
+* **ADR-005 + `.kaizen/schedule.yml`** — scheduled agent execution contract
+* **`kaizen-agentic schedule`** — validate, init, prepare, list
+* **activity-core definitions** — weekly coach + optimization on preselected repos

-### To Refactor
-* **CI lint gate** — flake8 on `src/` in Gitea Actions
-* **Makefile install hints** — point at Gitea registry or dev install
-
-### Deferred to WP-0006 (v1.3.0)
+### Deferred to WP-0007 (v1.3.0+)
 * Interactive agent selection wizard
 * Agent template schema validation in `validate`
 * Documentation generation from agent metadata
--- a/workplans/kaizen-agentic-WP-0006-scheduled-agent-execution.md
+++ b/workplans/kaizen-agentic-WP-0006-scheduled-agent-execution.md
@@ -0,0 +1,350 @@
+---
+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 <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**