diff --git a/SCOPE.md b/SCOPE.md index 73a41d6..481c8e4 100644 --- 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) --- diff --git a/TODO.md b/TODO.md index 8166e7a..b3948f2 100644 --- 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 diff --git a/workplans/kaizen-agentic-WP-0006-scheduled-agent-execution.md b/workplans/kaizen-agentic-WP-0006-scheduled-agent-execution.md new file mode 100644 index 0000000..5d47b35 --- /dev/null +++ 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 [--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**