Compare commits
15 Commits
e0e02e261d
...
v1.3.0
| Author | SHA1 | Date | |
|---|---|---|---|
| eeb4eee5ef | |||
| 3b2edd4a9e | |||
| 2400ff4890 | |||
| df899abd98 | |||
| b1fceeebc8 | |||
| fe795ca750 | |||
| 1d0999eabb | |||
| 297afed823 | |||
| 11a35d18d8 | |||
| 1522f12130 | |||
| 1c0c9accd9 | |||
| cb068cc2b5 | |||
| 47b743a074 | |||
| 9d2bab9a38 | |||
| 5ce3d0766e |
18
.custodian-brief.md
Normal file
18
.custodian-brief.md
Normal file
@@ -0,0 +1,18 @@
|
|||||||
|
<!-- custodian-brief: generated by fix-consistency — do not edit manually -->
|
||||||
|
# Custodian Brief — kaizen-agentic
|
||||||
|
|
||||||
|
**Domain:** custodian
|
||||||
|
**Last synced:** 2026-06-16 23:04 UTC
|
||||||
|
**State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)*
|
||||||
|
|
||||||
|
## Active Workstreams
|
||||||
|
|
||||||
|
*(none — repo may need first-session setup)*
|
||||||
|
|
||||||
|
---
|
||||||
|
## MCP Orientation (when available)
|
||||||
|
|
||||||
|
If the state-hub MCP server is reachable, call:
|
||||||
|
`get_domain_summary("custodian")`
|
||||||
|
This provides richer cross-domain context.
|
||||||
|
If the MCP call fails, use this file as your orientation source.
|
||||||
@@ -12,10 +12,11 @@ jobs:
|
|||||||
steps:
|
steps:
|
||||||
- name: Check out source
|
- name: Check out source
|
||||||
env:
|
env:
|
||||||
|
PACKAGE_USER: ${{ secrets.PACKAGE_USER }}
|
||||||
PACKAGE_TOKEN: ${{ secrets.PACKAGE_TOKEN }}
|
PACKAGE_TOKEN: ${{ secrets.PACKAGE_TOKEN }}
|
||||||
run: |
|
run: |
|
||||||
git clone --depth 1 \
|
git clone --depth 1 \
|
||||||
"https://tegwick:${PACKAGE_TOKEN}@gitea.coulomb.social/coulomb/kaizen-agentic.git" \
|
"https://${PACKAGE_USER}:${PACKAGE_TOKEN}@gitea.coulomb.social/coulomb/kaizen-agentic.git" \
|
||||||
repo
|
repo
|
||||||
cd repo
|
cd repo
|
||||||
git checkout "${{ gitea.sha }}"
|
git checkout "${{ gitea.sha }}"
|
||||||
@@ -24,13 +25,17 @@ jobs:
|
|||||||
env:
|
env:
|
||||||
TWINE_USERNAME: ${{ secrets.PACKAGE_USER }}
|
TWINE_USERNAME: ${{ secrets.PACKAGE_USER }}
|
||||||
TWINE_PASSWORD: ${{ secrets.PACKAGE_TOKEN }}
|
TWINE_PASSWORD: ${{ secrets.PACKAGE_TOKEN }}
|
||||||
|
PYTHON_KEYRING_BACKEND: keyring.backends.null.Keyring
|
||||||
run: |
|
run: |
|
||||||
cd repo
|
cd repo
|
||||||
python3 -m ensurepip --upgrade 2>/dev/null || \
|
python3 -m venv .build-venv
|
||||||
curl -sS https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py && python3 /tmp/get-pip.py
|
. .build-venv/bin/activate
|
||||||
python3 -m pip install --upgrade pip build twine
|
python -m pip install --upgrade pip build twine
|
||||||
python3 -m build
|
python -m build
|
||||||
python3 -m twine check dist/*
|
python -m twine check dist/*
|
||||||
python3 -m twine upload \
|
python -m twine upload \
|
||||||
|
--username "${TWINE_USERNAME}" \
|
||||||
|
--password "${TWINE_PASSWORD}" \
|
||||||
|
--non-interactive \
|
||||||
--repository-url https://gitea.coulomb.social/api/packages/coulomb/pypi \
|
--repository-url https://gitea.coulomb.social/api/packages/coulomb/pypi \
|
||||||
dist/*
|
dist/*
|
||||||
|
|||||||
24
CHANGELOG.md
24
CHANGELOG.md
@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||||||
|
|
||||||
## [Unreleased]
|
## [Unreleased]
|
||||||
|
|
||||||
|
## [1.3.0] - 2026-06-17
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- **Scheduled agent execution (WP-0006, ADR-005)** — run agents on a cadence
|
||||||
|
against a preselected repo roster, orchestrated by activity-core and prepared
|
||||||
|
by kaizen-agentic (no Temporal workers or LLM runtime in this repo)
|
||||||
|
- **`kaizen-agentic schedule`** CLI group — `init`, `validate`, `list`,
|
||||||
|
`prepare <agent>` (markdown/json) over `.kaizen/schedule.yml`
|
||||||
|
- **`.kaizen/schedule.yml`** manifest + schema docs and example
|
||||||
|
(`docs/integrations/schedule-schema.md`, `docs/examples/.kaizen/schedule.yml`)
|
||||||
|
- **ActivityDefinition drafts** (`enabled: false`) — `weekly-coach-orientation`,
|
||||||
|
`weekly-optimization-review`
|
||||||
|
- **Design specs** — `discover_kaizen_scheduled_repos` resolver, State Hub
|
||||||
|
roster fields, `kaizen.schedule.prepared` event payload, activity-core handoff
|
||||||
|
checklist
|
||||||
|
|
||||||
|
## [1.2.0] - 2026-06-16
|
||||||
|
|
||||||
### Added
|
### Added
|
||||||
- **`make agents-sync-package`** — sync `agents/` into packaged `data/agents/`
|
- **`make agents-sync-package`** — sync `agents/` into packaged `data/agents/`
|
||||||
- **Packaged agent parity test** — `release-check` fails when wheel data drifts from source
|
- **Packaged agent parity test** — `release-check` fails when wheel data drifts from source
|
||||||
@@ -14,7 +32,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||||||
|
|
||||||
### Changed
|
### Changed
|
||||||
- **Install documentation** — HELLO_WORLD, CLI_CHEAT_SHEET, AGENT_DISTRIBUTION use Gitea PyPI extra index
|
- **Install documentation** — HELLO_WORLD, CLI_CHEAT_SHEET, AGENT_DISTRIBUTION use Gitea PyPI extra index
|
||||||
- **`docs/PACKAGE_RELEASE.md`** — secrets setup and pre-tag release checklist
|
- **`docs/PACKAGE_RELEASE.md`** — OpenBao token custody, publish smoke-test notes, pre-tag checklist
|
||||||
|
|
||||||
|
### Fixed
|
||||||
|
- **Gitea publish workflow** — `.build-venv` for PEP 668 on haskelseed; explicit twine credentials; `tegwick` + `inter-hub-pkg-rep` token from OpenBao
|
||||||
|
- **Helix correlation docs** — bidirectional link with agentic-resources (WP-0005 T16)
|
||||||
|
|
||||||
## [1.1.0] - 2026-06-18
|
## [1.1.0] - 2026-06-18
|
||||||
|
|
||||||
|
|||||||
2
SCOPE.md
2
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
|
- 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
|
- 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
|
- 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)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
20
TODO.md
20
TODO.md
@@ -10,18 +10,20 @@ The structure organizes **future tasks** by their impact, just as a changelog or
|
|||||||
|
|
||||||
## [Unreleased] - *Active Vibe-Coding State* 💡
|
## [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
|
### Implemented (pending v1.3.0 tag)
|
||||||
* **Gitea publish pipeline verification** — secrets + workflow smoke test
|
* **ADR-005 + `.kaizen/schedule.yml`** — scheduled agent execution contract
|
||||||
* **`make agents-sync-package`** — keep `data/agents/` aligned with `agents/`
|
* **`kaizen-agentic schedule`** — validate, init, prepare, list
|
||||||
* **Install doc sweep** — HELLO_WORLD, CLI_CHEAT_SHEET, AGENT_DISTRIBUTION
|
* **activity-core definitions** — weekly coach + optimization on preselected repos
|
||||||
|
* **Resolver + roster + event design** — `discover_kaizen_scheduled_repos`,
|
||||||
|
State Hub roster fields, `kaizen.schedule.prepared` payload, handoff checklist
|
||||||
|
|
||||||
### To Refactor
|
### To Add (release)
|
||||||
* **CI lint gate** — flake8 on `src/` in Gitea Actions
|
* **Tag v1.3.0** — once activity-core handoff issue is opened and pilot smoke-tested
|
||||||
* **Makefile install hints** — point at Gitea registry or dev install
|
* **activity-core implementation** — resolver + sync (separate repo; see handoff doc)
|
||||||
|
|
||||||
### Deferred to WP-0006 (v1.3.0)
|
### Deferred to WP-0007 (v1.3.0+)
|
||||||
* Interactive agent selection wizard
|
* Interactive agent selection wizard
|
||||||
* Agent template schema validation in `validate`
|
* Agent template schema validation in `validate`
|
||||||
* Documentation generation from agent metadata
|
* Documentation generation from agent metadata
|
||||||
|
|||||||
@@ -88,6 +88,22 @@ kaizen-agentic memory init tdd-workflow --no-metrics # memory only
|
|||||||
|
|
||||||
Session-close template: `docs/templates/session-close-protocol.md`
|
Session-close template: `docs/templates/session-close-protocol.md`
|
||||||
|
|
||||||
|
### Scheduled Agent Execution (ADR-005)
|
||||||
|
```bash
|
||||||
|
# Opt this repo into fleet scheduling
|
||||||
|
kaizen-agentic schedule init # coach + optimization weekly
|
||||||
|
kaizen-agentic schedule init --timezone UTC # override timezone
|
||||||
|
kaizen-agentic schedule validate # schema + agent-name checks
|
||||||
|
kaizen-agentic schedule list # enabled entries (--all incl. disabled)
|
||||||
|
|
||||||
|
# Prepare orientation for a scheduled run (offline; no State Hub needed)
|
||||||
|
kaizen-agentic schedule prepare coach # markdown bundle
|
||||||
|
kaizen-agentic schedule prepare optimization --format json
|
||||||
|
```
|
||||||
|
|
||||||
|
activity-core fires the schedule and creates a task per (repo, agent); the task
|
||||||
|
runs `schedule prepare`. kaizen-agentic does not run cron or invoke Claude.
|
||||||
|
|
||||||
### Information
|
### Information
|
||||||
```bash
|
```bash
|
||||||
# List templates
|
# List templates
|
||||||
|
|||||||
@@ -73,6 +73,45 @@ test -f .kaizen/metrics/optimizer/analysis.json && echo OK
|
|||||||
|
|
||||||
**Boundary:** kaizen-agentic does not run Temporal schedules.
|
**Boundary:** kaizen-agentic does not run Temporal schedules.
|
||||||
|
|
||||||
|
### Scheduled agent execution (WP-0006, ADR-005)
|
||||||
|
|
||||||
|
Beyond the metrics-only definitions above, agents themselves run on a cadence
|
||||||
|
against a **preselected repo roster**. The roster combines three sources:
|
||||||
|
|
||||||
|
| Source | Purpose |
|
||||||
|
|--------|---------|
|
||||||
|
| State Hub `GET /repos/` | Canonical slug list + `host_paths` |
|
||||||
|
| Repo opt-in: `.kaizen/schedule.yml` exists with `version` set | Per-repo enablement |
|
||||||
|
| Optional hub flag `kaizen_schedule_enabled: true` (future) | Operator override |
|
||||||
|
|
||||||
|
A repo is **schedule-eligible** when it is registered with reachable
|
||||||
|
`host_paths` **and** carries a valid `.kaizen/schedule.yml`. The activity-core
|
||||||
|
resolver `discover_kaizen_scheduled_repos` intersects these and emits
|
||||||
|
`context.scheduled_runs` (one entry per `(repo, agent)`); definitions `for_each`
|
||||||
|
over that output.
|
||||||
|
|
||||||
|
| Definition | Trigger | Agent | Prepare command |
|
||||||
|
|------------|---------|-------|-----------------|
|
||||||
|
| [weekly-coach-orientation](integrations/activity-definitions/weekly-coach-orientation.md) | Cron Mon 09:00 | `coach` | `schedule prepare coach` |
|
||||||
|
| [weekly-optimization-review](integrations/activity-definitions/weekly-optimization-review.md) | Cron Mon 10:00 | `optimization` | `schedule prepare optimization` |
|
||||||
|
|
||||||
|
**Listing schedule-eligible repos** (operator, no activity-core code):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# In each candidate repo on a host listed in state-hub host_paths:
|
||||||
|
kaizen-agentic schedule validate && kaizen-agentic schedule list
|
||||||
|
```
|
||||||
|
|
||||||
|
**Design docs (no state-hub / activity-core code in this repo):**
|
||||||
|
|
||||||
|
- [schedule-schema.md](integrations/schedule-schema.md) — `.kaizen/schedule.yml`
|
||||||
|
- [state-hub-roster-fields.md](integrations/state-hub-roster-fields.md) — hub fields/filters
|
||||||
|
- [discover-kaizen-scheduled-repos.md](integrations/discover-kaizen-scheduled-repos.md) — resolver spec
|
||||||
|
- [kaizen-schedule-prepared-event.md](integrations/kaizen-schedule-prepared-event.md) — event payload
|
||||||
|
|
||||||
|
**Boundary:** kaizen-agentic declares and prepares; activity-core schedules;
|
||||||
|
state-hub owns the roster.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Pattern 3 — artifact-store evidence retention
|
## Pattern 3 — artifact-store evidence retention
|
||||||
|
|||||||
@@ -60,8 +60,18 @@ Configure in Gitea: **Repository → Settings → Actions → Secrets**.
|
|||||||
|
|
||||||
| Secret | Value |
|
| Secret | Value |
|
||||||
|--------|-------|
|
|--------|-------|
|
||||||
| `PACKAGE_USER` | Gitea username with package upload permission (e.g. `tegwick`) |
|
| `PACKAGE_USER` | `tegwick` — Gitea username that owns the package token |
|
||||||
| `PACKAGE_TOKEN` | Gitea API token with `write:package` scope |
|
| `PACKAGE_TOKEN` | Gitea API token named `inter-hub-pkg-rep` (`write:package`) |
|
||||||
|
|
||||||
|
Token custody (OpenBao):
|
||||||
|
|
||||||
|
```text
|
||||||
|
platform/data/operators/inter-hub/package-management
|
||||||
|
→ field: inter-hub-pkg-rep
|
||||||
|
```
|
||||||
|
|
||||||
|
Paste the **plaintext** token into the Gitea secret UI. `inter-hub-pkg-rep` is the
|
||||||
|
token name in Gitea, not a username.
|
||||||
|
|
||||||
Gitea rejects secret names prefixed with `GITEA_` — use `PACKAGE_USER` / `PACKAGE_TOKEN`
|
Gitea rejects secret names prefixed with `GITEA_` — use `PACKAGE_USER` / `PACKAGE_TOKEN`
|
||||||
(not `GITEA_PACKAGE_USER`). Workflows use `runs-on: haskelseed` and native `git clone`
|
(not `GITEA_PACKAGE_USER`). Workflows use `runs-on: haskelseed` and native `git clone`
|
||||||
@@ -70,12 +80,22 @@ Gitea rejects secret names prefixed with `GITEA_` — use `PACKAGE_USER` / `PACK
|
|||||||
The publish workflow fails at the upload step when either secret is missing or
|
The publish workflow fails at the upload step when either secret is missing or
|
||||||
invalid. Do not commit tokens to the repository.
|
invalid. Do not commit tokens to the repository.
|
||||||
|
|
||||||
|
**Smoke-test (2026-06-16):** `workflow_dispatch` run #3042 authenticated successfully
|
||||||
|
(`409 Conflict` on re-upload of `1.1.0` — expected). Root causes of earlier `401`s:
|
||||||
|
wrong token (`GITEA_API_TOKEN` ≠ package token), wrong username (`inter-hub-pkg-rep`
|
||||||
|
is a token name), and a stale org-level secret. Build uses `.build-venv` (PEP 668).
|
||||||
|
|
||||||
Verify secrets without cutting a release:
|
Verify secrets without cutting a release:
|
||||||
|
|
||||||
1. Open **Actions → Publish Python package → Run workflow** (`workflow_dispatch`)
|
1. Open **Actions → Publish Python package → Run workflow** (`workflow_dispatch`),
|
||||||
|
or dispatch via API:
|
||||||
|
`POST /api/v1/repos/coulomb/kaizen-agentic/actions/workflows/publish-python-package.yml/dispatches`
|
||||||
|
with body `{"ref":"main"}`
|
||||||
2. Confirm the run completes and `twine upload` succeeds
|
2. Confirm the run completes and `twine upload` succeeds
|
||||||
3. Optional: `pip install kaizen-agentic==<version> --extra-index-url ...`
|
3. Optional: `pip install kaizen-agentic==<version> --extra-index-url ...`
|
||||||
|
|
||||||
|
The publish job uses an isolated `.build-venv` on the runner (PEP 668 safe).
|
||||||
|
|
||||||
## Pre-tag release checklist
|
## Pre-tag release checklist
|
||||||
|
|
||||||
Before `git tag vX.Y.Z && git push origin vX.Y.Z`:
|
Before `git tag vX.Y.Z && git push origin vX.Y.Z`:
|
||||||
@@ -108,3 +128,27 @@ token with `TWINE_USERNAME=__token__`):
|
|||||||
make release-publish
|
make release-publish
|
||||||
python -m twine upload dist/*
|
python -m twine upload dist/*
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Scheduled-run runner prerequisites (WP-0006)
|
||||||
|
|
||||||
|
A runner that executes a scheduled kaizen agent task (fired by activity-core)
|
||||||
|
needs:
|
||||||
|
|
||||||
|
- **`kaizen-agentic` on PATH** — `pip install kaizen-agentic` (or `pipx install
|
||||||
|
kaizen-agentic`) using the Gitea PyPI extra index when installing from the
|
||||||
|
internal registry:
|
||||||
|
```bash
|
||||||
|
pip install kaizen-agentic \
|
||||||
|
--extra-index-url https://gitea.coulomb.social/api/packages/coulomb/pypi/simple/
|
||||||
|
```
|
||||||
|
- **Repo checkout reachable** at the `host_paths[<host>]` registered in State
|
||||||
|
Hub, with a valid `.kaizen/schedule.yml` (`kaizen-agentic schedule validate`).
|
||||||
|
- **No State Hub required for `prepare`** — `schedule prepare` reads local
|
||||||
|
`.kaizen/` state only. The hub is needed by the *resolver* (activity-core),
|
||||||
|
not by the prepared session.
|
||||||
|
|
||||||
|
**Enabling a definition** (activity-core operator): keep the kaizen definitions
|
||||||
|
at `enabled: false` until a manual smoke test passes (see
|
||||||
|
[INTEGRATION_PATTERNS.md Pattern 2](INTEGRATION_PATTERNS.md) and the
|
||||||
|
[activity-core handoff checklist](integrations/activity-core-handoff-wp0006.md)),
|
||||||
|
then flip one definition to `enabled: true` in staging before fleet-wide enable.
|
||||||
|
|||||||
149
docs/adr/ADR-005-scheduled-agent-execution.md
Normal file
149
docs/adr/ADR-005-scheduled-agent-execution.md
Normal file
@@ -0,0 +1,149 @@
|
|||||||
|
---
|
||||||
|
id: ADR-005
|
||||||
|
title: Scheduled Agent Execution Convention
|
||||||
|
status: accepted
|
||||||
|
date: "2026-06-17"
|
||||||
|
---
|
||||||
|
|
||||||
|
# ADR-005 — Scheduled Agent Execution Convention
|
||||||
|
|
||||||
|
## Status
|
||||||
|
|
||||||
|
Accepted
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
Kaizen agents are markdown instruction sets invoked in coding-agent sessions.
|
||||||
|
ADR-004 added project-scoped metrics; WP-0004 committed three metrics-focused
|
||||||
|
`ActivityDefinition` drafts (`enabled: false`). What is still missing is a way to
|
||||||
|
run **agents themselves** — not just the metrics optimizer — on a **regular
|
||||||
|
cadence** against a **preselected set of repos**, without kaizen-agentic owning
|
||||||
|
Temporal workers, cron, or an LLM runtime.
|
||||||
|
|
||||||
|
The ecosystem already separates concerns:
|
||||||
|
|
||||||
|
- **activity-core** owns scheduling (cron/event → task creation).
|
||||||
|
- **state-hub** owns the canonical repo roster and `host_paths`.
|
||||||
|
- **kaizen-agentic** owns the agents, project memory, and metrics.
|
||||||
|
|
||||||
|
A scheduled agent run therefore needs a contract that crosses these repos
|
||||||
|
without merging them.
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
Introduce a **repo-local schedule manifest** and a **prepare** step. The
|
||||||
|
end-to-end flow:
|
||||||
|
|
||||||
|
```
|
||||||
|
activity-core cron
|
||||||
|
→ context resolver (roster ∩ repos with schedule.yml)
|
||||||
|
→ task per (repo, agent)
|
||||||
|
→ coding-agent session runs `kaizen-agentic schedule prepare <agent>`
|
||||||
|
→ session executes the agent instructions in that repo
|
||||||
|
```
|
||||||
|
|
||||||
|
kaizen-agentic's responsibilities are exactly two: **declare** the schedule
|
||||||
|
(`.kaizen/schedule.yml`) and **prepare** an orientation bundle for a run. It
|
||||||
|
does **not** fire cron, create tasks, or invoke Claude.
|
||||||
|
|
||||||
|
### 1. Schedule manifest — `.kaizen/schedule.yml`
|
||||||
|
|
||||||
|
A repo opts into fleet scheduling by committing this file:
|
||||||
|
|
||||||
|
```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
|
||||||
|
```
|
||||||
|
|
||||||
|
**Schema:**
|
||||||
|
|
||||||
|
| Key | Required | Type | Notes |
|
||||||
|
|-----|----------|------|-------|
|
||||||
|
| `version` | yes | string | Must be `"1"` |
|
||||||
|
| `timezone` | no | string | IANA tz; default supplied by ActivityDefinition |
|
||||||
|
| `agents` | yes | mapping | `agent-name → settings` |
|
||||||
|
| `agents.<name>.cadence` | yes | enum | `daily` \| `weekly` \| `monthly` |
|
||||||
|
| `agents.<name>.cron` | no | string | 5-field cron; overrides cadence default |
|
||||||
|
| `agents.<name>.enabled` | no | bool | Default `true` |
|
||||||
|
|
||||||
|
**Validation rules** (`kaizen-agentic schedule validate`):
|
||||||
|
|
||||||
|
- `version` must equal `"1"`.
|
||||||
|
- Every agent key must be an installed or packaged agent name.
|
||||||
|
- `cadence` must be one of the allowed values.
|
||||||
|
- Duplicate agent entries are rejected.
|
||||||
|
|
||||||
|
### 2. Roster (preselected repos)
|
||||||
|
|
||||||
|
A repo is **schedule-eligible** when **all** of:
|
||||||
|
|
||||||
|
1. It is a registered repo in state-hub (`GET /repos/`) with reachable
|
||||||
|
`host_paths`.
|
||||||
|
2. It contains a valid `.kaizen/schedule.yml`.
|
||||||
|
3. (Optional, future) it carries a `kaizen_schedule_enabled: true` hub flag.
|
||||||
|
|
||||||
|
The resolver `discover_kaizen_scheduled_repos` (specified in
|
||||||
|
`docs/integrations/discover-kaizen-scheduled-repos.md`, implemented in
|
||||||
|
activity-core) intersects these sources and emits `context.scheduled_runs`.
|
||||||
|
|
||||||
|
### 3. Prepare bundle — `schedule prepare <agent>`
|
||||||
|
|
||||||
|
Assembles, from **local `.kaizen/` state only** (offline-safe):
|
||||||
|
|
||||||
|
- The agent prompt (`agents/agent-<name>.md`, installed or packaged).
|
||||||
|
- Project memory (`.kaizen/agents/<name>/memory.md`) when present.
|
||||||
|
- Metrics summary (`.kaizen/metrics/<name>/summary.json`) when present.
|
||||||
|
- Repo pointers (`SCOPE.md`, `TODO.md`) when present.
|
||||||
|
- Suggested session-close commands (`metrics record`, memory update).
|
||||||
|
|
||||||
|
Output is `markdown` (default) or `json` (`--format json`) so activity-core can
|
||||||
|
embed it in a task `description` or a runner can parse it.
|
||||||
|
|
||||||
|
### CLI interface
|
||||||
|
|
||||||
|
```
|
||||||
|
kaizen-agentic schedule init [--target PATH] [--timezone TZ] [--force]
|
||||||
|
kaizen-agentic schedule validate [--target PATH]
|
||||||
|
kaizen-agentic schedule list [--target PATH] [--all]
|
||||||
|
kaizen-agentic schedule prepare <agent> [--target PATH] [--format markdown|json]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Boundaries
|
||||||
|
|
||||||
|
- **No scheduling code** in kaizen-agentic. Cron and task creation belong to
|
||||||
|
activity-core; the roster query belongs to state-hub.
|
||||||
|
- **No LLM invocation.** `prepare` produces a runner-agnostic bundle; a human or
|
||||||
|
automated coding-agent session executes it.
|
||||||
|
- **State-hub schema changes** (roster opt-in flag) are designed here but
|
||||||
|
implemented in `the-custodian` (repo boundary).
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
- Operators declare per-repo schedules and a fleet roster without tribal
|
||||||
|
knowledge.
|
||||||
|
- activity-core can fire recurring tasks referencing `schedule prepare`.
|
||||||
|
- A scheduled session opens with full orientation (prompt + memory + metrics).
|
||||||
|
- The existing `weekly-metrics-optimize` definition (ADR-004 / WP-0004) remains
|
||||||
|
complementary; an `optimization` agent run may chain `schedule prepare
|
||||||
|
optimization` then `metrics optimize`.
|
||||||
|
|
||||||
|
## Related Documents
|
||||||
|
|
||||||
|
- [ADR-002: Project Memory Convention](ADR-002-project-memory-convention.md)
|
||||||
|
- [ADR-004: Project Metrics Convention](ADR-004-project-metrics-convention.md)
|
||||||
|
- [docs/integrations/schedule-schema.md](../integrations/schedule-schema.md)
|
||||||
|
- [docs/integrations/discover-kaizen-scheduled-repos.md](../integrations/discover-kaizen-scheduled-repos.md)
|
||||||
|
- [docs/agency-framework.md](../agency-framework.md)
|
||||||
|
- [KAIZEN-WP-0006](../../workplans/kaizen-agentic-WP-0006-scheduled-agent-execution.md)
|
||||||
@@ -299,12 +299,35 @@ Manifest: [integrations/optimizer-artifact-manifest.md](integrations/optimizer-a
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Scheduled Agent Execution
|
||||||
|
|
||||||
|
Agents can run on a **regular cadence** against **preselected repos**, fired by
|
||||||
|
**activity-core** and prepared by kaizen-agentic (ADR-005). A repo opts in by
|
||||||
|
committing `.kaizen/schedule.yml`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kaizen-agentic schedule init # scaffold (coach + optimization weekly)
|
||||||
|
kaizen-agentic schedule validate # check schema + agent names
|
||||||
|
kaizen-agentic schedule list # show enabled entries
|
||||||
|
kaizen-agentic schedule prepare coach # orientation bundle for a scheduled run
|
||||||
|
```
|
||||||
|
|
||||||
|
`schedule prepare <agent>` bundles the agent prompt, project memory, metrics
|
||||||
|
summary, and repo pointers — offline, no State Hub required. kaizen-agentic does
|
||||||
|
**not** run cron or invoke Claude; activity-core fires the schedule and a
|
||||||
|
coding-agent session executes the prepared bundle.
|
||||||
|
|
||||||
|
Schema: [integrations/schedule-schema.md](integrations/schedule-schema.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Related Documents
|
## Related Documents
|
||||||
|
|
||||||
- [ADR-001: Workplan Convention](adr/ADR-001-workplan-convention.md)
|
- [ADR-001: Workplan Convention](adr/ADR-001-workplan-convention.md)
|
||||||
- [ADR-002: Project Memory Convention](adr/ADR-002-project-memory-convention.md)
|
- [ADR-002: Project Memory Convention](adr/ADR-002-project-memory-convention.md)
|
||||||
- [ADR-003: Protocols Artifact Convention](adr/ADR-003-protocols-artifact-convention.md)
|
- [ADR-003: Protocols Artifact Convention](adr/ADR-003-protocols-artifact-convention.md)
|
||||||
- [ADR-004: Project Metrics Convention](adr/ADR-004-project-metrics-convention.md)
|
- [ADR-004: Project Metrics Convention](adr/ADR-004-project-metrics-convention.md)
|
||||||
|
- [ADR-005: Scheduled Agent Execution](adr/ADR-005-scheduled-agent-execution.md)
|
||||||
- [wiki/EcosystemIntegration.md](../wiki/EcosystemIntegration.md) — two-layer measurement model
|
- [wiki/EcosystemIntegration.md](../wiki/EcosystemIntegration.md) — two-layer measurement model
|
||||||
- [WP-0002: Agency Framework](../workplans/kaizen-agentic-WP-0002-agency-framework.md)
|
- [WP-0002: Agency Framework](../workplans/kaizen-agentic-WP-0002-agency-framework.md)
|
||||||
- [WP-0003: Measurement Loop](../workplans/kaizen-agentic-WP-0003-measurement-loop.md)
|
- [WP-0003: Measurement Loop](../workplans/kaizen-agentic-WP-0003-measurement-loop.md)
|
||||||
|
|||||||
17
docs/examples/.kaizen/schedule.yml
Normal file
17
docs/examples/.kaizen/schedule.yml
Normal file
@@ -0,0 +1,17 @@
|
|||||||
|
# Kaizen scheduled agent execution manifest (ADR-005)
|
||||||
|
# Declares which agents run on what cadence in this repo.
|
||||||
|
# Validate with: kaizen-agentic schedule validate
|
||||||
|
version: "1"
|
||||||
|
timezone: Europe/Berlin
|
||||||
|
agents:
|
||||||
|
coach:
|
||||||
|
cadence: weekly
|
||||||
|
cron: "0 9 * * 1" # Monday 09:00 — cross-agent orientation brief
|
||||||
|
enabled: true
|
||||||
|
optimization:
|
||||||
|
cadence: weekly
|
||||||
|
cron: "0 10 * * 1" # Monday 10:00 — agent performance review
|
||||||
|
enabled: true
|
||||||
|
tdd-workflow:
|
||||||
|
cadence: monthly
|
||||||
|
enabled: false # declared but paused; operator opts in deliberately
|
||||||
69
docs/integrations/activity-core-handoff-wp0006.md
Normal file
69
docs/integrations/activity-core-handoff-wp0006.md
Normal file
@@ -0,0 +1,69 @@
|
|||||||
|
# activity-core Handoff — Scheduled Agent Execution (WP-0006)
|
||||||
|
|
||||||
|
Coordination checklist for the **activity-core** team to enable kaizen scheduled
|
||||||
|
agent runs. kaizen-agentic owns the schedule contract, the prepare CLI, and the
|
||||||
|
ActivityDefinition **drafts**; activity-core owns the resolver, the schedule
|
||||||
|
firing, and task creation (repo boundary, ADR-005).
|
||||||
|
|
||||||
|
Open this as an activity-core issue/PR titled *"Enable kaizen scheduled agent
|
||||||
|
execution (WP-0006)"* and track the boxes there.
|
||||||
|
|
||||||
|
## What kaizen-agentic ships (done in this repo)
|
||||||
|
|
||||||
|
- [x] `.kaizen/schedule.yml` schema + `schedule validate|init|list|prepare` CLI
|
||||||
|
- [x] ADR-005 contract
|
||||||
|
- [x] Resolver spec: [discover-kaizen-scheduled-repos.md](discover-kaizen-scheduled-repos.md)
|
||||||
|
- [x] State Hub roster fields design: [state-hub-roster-fields.md](state-hub-roster-fields.md)
|
||||||
|
- [x] Draft definitions (`enabled: false`):
|
||||||
|
[weekly-coach-orientation](activity-definitions/weekly-coach-orientation.md),
|
||||||
|
[weekly-optimization-review](activity-definitions/weekly-optimization-review.md)
|
||||||
|
- [x] Event payload spec: [kaizen-schedule-prepared-event.md](kaizen-schedule-prepared-event.md)
|
||||||
|
|
||||||
|
## What activity-core must do
|
||||||
|
|
||||||
|
- [ ] **Implement resolver** `discover_kaizen_scheduled_repos` per the spec
|
||||||
|
(hub roster ∩ repos with valid `.kaizen/schedule.yml`).
|
||||||
|
- [ ] **Add resolver unit tests** using the four fixtures in the spec.
|
||||||
|
- [ ] **Copy definitions** from `docs/integrations/activity-definitions/`
|
||||||
|
(`weekly-coach-orientation.md`, `weekly-optimization-review.md`) into the
|
||||||
|
activity-core catalog path (per ACT-ADR-002).
|
||||||
|
- [ ] **Register** each definition slug in the activity-core index.
|
||||||
|
- [ ] **Run** `make sync-activity-definitions` in activity-core.
|
||||||
|
- [ ] **Wire cron** triggers (Mon 09:00 / 10:00 Europe/Berlin) to the resolver.
|
||||||
|
- [ ] **Smoke test** against a pilot repo (see below) with the definition still
|
||||||
|
`enabled: false` (dry-run task creation).
|
||||||
|
- [ ] **Enable gradually** — flip one definition to `enabled: true` in staging
|
||||||
|
after the smoke test passes.
|
||||||
|
- [ ] **Verify runner prerequisites** — `kaizen-agentic` on PATH and the Gitea
|
||||||
|
PyPI extra index if the runner installs from registry (see
|
||||||
|
[PACKAGE_RELEASE.md](../PACKAGE_RELEASE.md)).
|
||||||
|
|
||||||
|
## State Hub team (the-custodian)
|
||||||
|
|
||||||
|
- [ ] Optional: add `kaizen_schedule_enabled` repo flag + `GET /repos/` filter
|
||||||
|
(v2 pre-filter; the repo file remains the source of truth).
|
||||||
|
|
||||||
|
## Smoke test (manual, runner-agnostic)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /path/to/pilot-repo
|
||||||
|
kaizen-agentic schedule init # if not already present
|
||||||
|
kaizen-agentic schedule validate # exit 0
|
||||||
|
kaizen-agentic schedule list # shows coach + optimization enabled
|
||||||
|
kaizen-agentic schedule prepare coach # non-empty orientation bundle
|
||||||
|
```
|
||||||
|
|
||||||
|
Then in activity-core: run the resolver (dry-run) and confirm one
|
||||||
|
`scheduled_run` per enabled `(repo, agent)` with a correct `prepare_command`.
|
||||||
|
|
||||||
|
## Pilot roster
|
||||||
|
|
||||||
|
- `kaizen-agentic` (dogfood)
|
||||||
|
- `the-custodian` (hub operator)
|
||||||
|
- one additional custodian-domain repo with `.kaizen/` state (TBD at pilot time)
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [ADR-005](../adr/ADR-005-scheduled-agent-execution.md)
|
||||||
|
- [INTEGRATION_PATTERNS.md Pattern 2](../INTEGRATION_PATTERNS.md)
|
||||||
|
- [KAIZEN-WP-0006](../../workplans/kaizen-agentic-WP-0006-scheduled-agent-execution.md)
|
||||||
@@ -0,0 +1,55 @@
|
|||||||
|
---
|
||||||
|
id: kaizen-weekly-coach-orientation
|
||||||
|
name: Weekly Kaizen Coach Orientation
|
||||||
|
enabled: false
|
||||||
|
owner: kaizen-agentic
|
||||||
|
governance: custodian
|
||||||
|
status: proposed
|
||||||
|
trigger:
|
||||||
|
type: cron
|
||||||
|
cron_expression: "0 9 * * 1"
|
||||||
|
timezone: Europe/Berlin
|
||||||
|
misfire_policy: skip
|
||||||
|
context_sources:
|
||||||
|
- type: resolver
|
||||||
|
query: discover_kaizen_scheduled_repos
|
||||||
|
params:
|
||||||
|
domain: custodian
|
||||||
|
cadence: weekly
|
||||||
|
bind_to: context.scheduled_runs
|
||||||
|
---
|
||||||
|
|
||||||
|
# Weekly Kaizen Coach Orientation
|
||||||
|
|
||||||
|
Every Monday 09:00 Berlin time, opens a coach orientation task for each
|
||||||
|
schedule-eligible repo whose `.kaizen/schedule.yml` enables the `coach` agent.
|
||||||
|
|
||||||
|
The resolver `discover_kaizen_scheduled_repos` (see
|
||||||
|
[discover-kaizen-scheduled-repos.md](../discover-kaizen-scheduled-repos.md))
|
||||||
|
returns one `scheduled_run` per `(repo, agent)`; this definition selects the
|
||||||
|
`coach` runs.
|
||||||
|
|
||||||
|
```rule
|
||||||
|
id: run-weekly-coach
|
||||||
|
for_each: context.scheduled_runs
|
||||||
|
bind_as: r
|
||||||
|
condition: 'r.agent == "coach" and r.enabled == true'
|
||||||
|
action:
|
||||||
|
task_template: "Weekly coach orientation: {{r.repo}}"
|
||||||
|
description: |
|
||||||
|
{{r.prepare_command}}
|
||||||
|
Then load agents/agent-coach.md in a coding-agent session, paste the
|
||||||
|
prepared bundle, and follow the coach synthesis. At session close:
|
||||||
|
kaizen-agentic metrics record coach --success --time <s> --quality <0-1>
|
||||||
|
target_repo: "{{r.repo}}"
|
||||||
|
priority: medium
|
||||||
|
labels: ["kaizen", "agent-run", "coach", "scheduled", "automated"]
|
||||||
|
```
|
||||||
|
|
||||||
|
**CLI mapping:** `kaizen-agentic schedule prepare coach` (offline-safe; reads
|
||||||
|
local `.kaizen/` state).
|
||||||
|
|
||||||
|
**Activation:** sync into activity-core via `make sync-activity-definitions`
|
||||||
|
after the `discover_kaizen_scheduled_repos` resolver is enabled. Keep
|
||||||
|
`enabled: false` until a manual smoke test passes on a pilot repo. See
|
||||||
|
[INTEGRATION_PATTERNS.md Pattern 2](../../INTEGRATION_PATTERNS.md).
|
||||||
@@ -0,0 +1,55 @@
|
|||||||
|
---
|
||||||
|
id: kaizen-weekly-optimization-review
|
||||||
|
name: Weekly Kaizen Optimization Review
|
||||||
|
enabled: false
|
||||||
|
owner: kaizen-agentic
|
||||||
|
governance: custodian
|
||||||
|
status: proposed
|
||||||
|
trigger:
|
||||||
|
type: cron
|
||||||
|
cron_expression: "0 10 * * 1"
|
||||||
|
timezone: Europe/Berlin
|
||||||
|
misfire_policy: skip
|
||||||
|
context_sources:
|
||||||
|
- type: resolver
|
||||||
|
query: discover_kaizen_scheduled_repos
|
||||||
|
params:
|
||||||
|
domain: custodian
|
||||||
|
cadence: weekly
|
||||||
|
bind_to: context.scheduled_runs
|
||||||
|
---
|
||||||
|
|
||||||
|
# Weekly Kaizen Optimization Review
|
||||||
|
|
||||||
|
Every Monday 10:00 Berlin time, opens an optimization-agent review task for each
|
||||||
|
schedule-eligible repo whose `.kaizen/schedule.yml` enables the `optimization`
|
||||||
|
agent. Chains the agent orientation with the existing metrics optimizer so the
|
||||||
|
review is evidence-backed.
|
||||||
|
|
||||||
|
```rule
|
||||||
|
id: run-weekly-optimization
|
||||||
|
for_each: context.scheduled_runs
|
||||||
|
bind_as: r
|
||||||
|
condition: 'r.agent == "optimization" and r.enabled == true'
|
||||||
|
action:
|
||||||
|
task_template: "Weekly optimization review: {{r.repo}}"
|
||||||
|
description: |
|
||||||
|
{{r.prepare_command}}
|
||||||
|
kaizen-agentic metrics optimize # refresh evidence
|
||||||
|
Then load agents/agent-optimization.md, paste the prepared bundle plus the
|
||||||
|
optimizer report, and act on recommendations. At session close:
|
||||||
|
kaizen-agentic metrics record optimization --success --time <s> --quality <0-1>
|
||||||
|
target_repo: "{{r.repo}}"
|
||||||
|
priority: medium
|
||||||
|
labels: ["kaizen", "agent-run", "optimization", "scheduled", "automated"]
|
||||||
|
```
|
||||||
|
|
||||||
|
**CLI mapping:** `kaizen-agentic schedule prepare optimization` then
|
||||||
|
`kaizen-agentic metrics optimize`.
|
||||||
|
|
||||||
|
**Complementarity:** this generalizes the metrics-only
|
||||||
|
[weekly-metrics-optimize](weekly-metrics-optimize.md) definition into a full
|
||||||
|
agent run. Repos may run either; running both duplicates the optimizer step.
|
||||||
|
|
||||||
|
**Activation:** sync into activity-core via `make sync-activity-definitions`
|
||||||
|
after the resolver is enabled; hold at `enabled: false` until smoke-tested.
|
||||||
109
docs/integrations/discover-kaizen-scheduled-repos.md
Normal file
109
docs/integrations/discover-kaizen-scheduled-repos.md
Normal file
@@ -0,0 +1,109 @@
|
|||||||
|
# Resolver Spec: `discover_kaizen_scheduled_repos`
|
||||||
|
|
||||||
|
**Status:** specification — **implemented in activity-core**, not here. This doc
|
||||||
|
is the contract an activity-core implementer needs to add the context resolver
|
||||||
|
that feeds the scheduled-agent ActivityDefinitions (ADR-005).
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
Given the fleet roster and per-repo schedule manifests, emit one entry per
|
||||||
|
`(repo, agent)` that is due to run, so ActivityDefinitions can `for_each` over
|
||||||
|
the result.
|
||||||
|
|
||||||
|
## Signature
|
||||||
|
|
||||||
|
```
|
||||||
|
discover_kaizen_scheduled_repos(
|
||||||
|
domain: str | None = None, # optional scope filter, e.g. "custodian"
|
||||||
|
cadence: str | None = None, # optional: "daily" | "weekly" | "monthly"
|
||||||
|
now: datetime | None = None, # injection point for testing
|
||||||
|
) -> { "scheduled_runs": list[ScheduledRun] }
|
||||||
|
```
|
||||||
|
|
||||||
|
Bound in a definition as:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
context_sources:
|
||||||
|
- type: resolver
|
||||||
|
query: discover_kaizen_scheduled_repos
|
||||||
|
params:
|
||||||
|
domain: custodian
|
||||||
|
cadence: weekly
|
||||||
|
bind_to: context.scheduled_runs
|
||||||
|
```
|
||||||
|
|
||||||
|
## Inputs (sources, in order)
|
||||||
|
|
||||||
|
1. **State Hub** `GET /repos/` (optionally filtered by `domain` and, when the v2
|
||||||
|
flag lands, `kaizen_schedule_enabled=true`). Yields `slug`, `host_paths`,
|
||||||
|
`domain`.
|
||||||
|
2. **Repo checkout** at `host_paths[<runner-host>]`: read
|
||||||
|
`.kaizen/schedule.yml`. Skip repos without the file.
|
||||||
|
3. **Validation**: run the equivalent of `kaizen-agentic schedule validate`.
|
||||||
|
Skip (and log) repos whose schedule is invalid — never emit a bad entry.
|
||||||
|
|
||||||
|
## Output shape
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"scheduled_runs": [
|
||||||
|
{
|
||||||
|
"repo": "kaizen-agentic",
|
||||||
|
"root": "/home/worsch/kaizen-agentic",
|
||||||
|
"agent": "coach",
|
||||||
|
"cadence": "weekly",
|
||||||
|
"cron": "0 9 * * 1",
|
||||||
|
"timezone": "Europe/Berlin",
|
||||||
|
"enabled": true,
|
||||||
|
"prepare_command": "kaizen-agentic schedule prepare coach --target /home/worsch/kaizen-agentic"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `ScheduledRun` fields
|
||||||
|
|
||||||
|
| Field | Source | Notes |
|
||||||
|
|-------|--------|-------|
|
||||||
|
| `repo` | hub `slug` | becomes `target_repo` on the created task |
|
||||||
|
| `root` | `host_paths[<host>]` | absolute checkout path on the runner |
|
||||||
|
| `agent` | schedule.yml key | |
|
||||||
|
| `cadence` | schedule.yml | |
|
||||||
|
| `cron` | schedule.yml or definition default | per-repo override when present |
|
||||||
|
| `timezone` | schedule.yml or definition default | |
|
||||||
|
| `enabled` | schedule.yml (`true` only emitted) | disabled entries are filtered out |
|
||||||
|
| `prepare_command` | derived | exact CLI the task should run |
|
||||||
|
|
||||||
|
## Filtering rules
|
||||||
|
|
||||||
|
- Emit only entries with `enabled: true`.
|
||||||
|
- When `cadence` param is set, emit only matching entries (lets each cron-bound
|
||||||
|
definition select its own cadence slice).
|
||||||
|
- When `cron` is present on the entry, it is the authoritative per-repo time;
|
||||||
|
otherwise the definition's cron applies.
|
||||||
|
|
||||||
|
## Errors
|
||||||
|
|
||||||
|
| Condition | Behavior |
|
||||||
|
|-----------|----------|
|
||||||
|
| Repo unreachable / path missing on host | Skip + log `repo_unreachable` |
|
||||||
|
| `.kaizen/schedule.yml` absent | Skip silently (not opted in) |
|
||||||
|
| schedule.yml invalid | Skip + log `schedule_invalid` with validation errors |
|
||||||
|
| Hub unreachable | Fail the resolver run (no roster = no safe output) |
|
||||||
|
|
||||||
|
The resolver must be **idempotent** and **side-effect free**: it reads, it does
|
||||||
|
not write. Task creation happens in the ActivityDefinition rule, not here.
|
||||||
|
|
||||||
|
## Test fixtures
|
||||||
|
|
||||||
|
- A repo with valid `.kaizen/schedule.yml` (coach enabled) → one entry.
|
||||||
|
- A repo with the file but coach `enabled: false` → no entry.
|
||||||
|
- A repo without the file → no entry.
|
||||||
|
- A repo with an invalid schedule → no entry + logged error.
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [state-hub-roster-fields.md](state-hub-roster-fields.md)
|
||||||
|
- [schedule-schema.md](schedule-schema.md)
|
||||||
|
- [activity-definitions/weekly-coach-orientation.md](activity-definitions/weekly-coach-orientation.md)
|
||||||
|
- [ADR-005](../adr/ADR-005-scheduled-agent-execution.md)
|
||||||
@@ -93,13 +93,8 @@ documenting expected fields — no ingestion code runs in kaizen-agentic.
|
|||||||
| [DESIGN-session-memory.md](https://github.com/coulomb/agentic-resources/blob/main/docs/DESIGN-session-memory.md) | agentic-resources |
|
| [DESIGN-session-memory.md](https://github.com/coulomb/agentic-resources/blob/main/docs/DESIGN-session-memory.md) | agentic-resources |
|
||||||
| `session_memory/core/store.py` — `get_digest()` | agentic-resources |
|
| `session_memory/core/store.py` — `get_digest()` | agentic-resources |
|
||||||
|
|
||||||
**Reciprocal link status:** agentic-resources should link back to this document from
|
**Reciprocal link status:** verified (WP-0005 T16). `agentic-resources/docs/DESIGN-session-memory.md`
|
||||||
its session-memory design notes. As of WP-0005, verify
|
§11 cites this document and ADR-004.
|
||||||
`agentic-resources/docs/DESIGN-session-memory.md` (or successor) cites this URL:
|
|
||||||
|
|
||||||
`https://gitea.coulomb.social/coulomb/kaizen-agentic/src/branch/main/docs/integrations/helix-forge-correlation.md`
|
|
||||||
|
|
||||||
Open a cross-repo issue if the link is missing.
|
|
||||||
|
|
||||||
## Non-goals
|
## Non-goals
|
||||||
|
|
||||||
|
|||||||
90
docs/integrations/kaizen-schedule-prepared-event.md
Normal file
90
docs/integrations/kaizen-schedule-prepared-event.md
Normal file
@@ -0,0 +1,90 @@
|
|||||||
|
# Event Payload: `kaizen.schedule.prepared`
|
||||||
|
|
||||||
|
**Status:** design — for **future event-driven runs**. v1 of WP-0006 is
|
||||||
|
cron-driven (activity-core fires the schedule). This event lets a runner or
|
||||||
|
activity-core react when a `schedule prepare` bundle has been assembled, without
|
||||||
|
polling.
|
||||||
|
|
||||||
|
kaizen-agentic does **not** publish this event today; the `prepare` command
|
||||||
|
writes to stdout. This spec fixes the contract so an emitter (a runner wrapper
|
||||||
|
or a thin `--emit` flag in a later iteration) and consumers agree on the shape.
|
||||||
|
|
||||||
|
## Subject
|
||||||
|
|
||||||
|
```
|
||||||
|
kaizen.schedule.prepared
|
||||||
|
```
|
||||||
|
|
||||||
|
NATS/event-bus subject, sibling to the existing `kaizen.metrics.recorded` and
|
||||||
|
`kaizen.agent.installed` subjects (Pattern 2).
|
||||||
|
|
||||||
|
## Payload
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"event": "kaizen.schedule.prepared",
|
||||||
|
"version": "1",
|
||||||
|
"occurred_at": "2026-06-17T09:00:12Z",
|
||||||
|
"repo": "kaizen-agentic",
|
||||||
|
"root": "/home/worsch/kaizen-agentic",
|
||||||
|
"agent": "coach",
|
||||||
|
"cadence": "weekly",
|
||||||
|
"prepare_command": "kaizen-agentic schedule prepare coach --target /home/worsch/kaizen-agentic",
|
||||||
|
"bundle": {
|
||||||
|
"format": "markdown",
|
||||||
|
"agent_prompt_found": true,
|
||||||
|
"has_memory": true,
|
||||||
|
"has_metrics": true,
|
||||||
|
"pointers": ["scope", "todo"],
|
||||||
|
"bytes": 8421
|
||||||
|
},
|
||||||
|
"session_close": [
|
||||||
|
"kaizen-agentic metrics record coach --success --time <s> --quality <0-1>"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Fields
|
||||||
|
|
||||||
|
| Field | Type | Notes |
|
||||||
|
|-------|------|-------|
|
||||||
|
| `event` | string | Always `kaizen.schedule.prepared` |
|
||||||
|
| `version` | string | Payload schema version |
|
||||||
|
| `occurred_at` | RFC3339 | When the bundle was assembled |
|
||||||
|
| `repo` | string | State Hub slug |
|
||||||
|
| `root` | string | Absolute checkout path |
|
||||||
|
| `agent` | string | Agent the bundle orients |
|
||||||
|
| `cadence` | string | `daily` \| `weekly` \| `monthly` |
|
||||||
|
| `prepare_command` | string | Exact CLI that produced the bundle |
|
||||||
|
| `bundle.format` | string | `markdown` \| `json` |
|
||||||
|
| `bundle.agent_prompt_found` | bool | Mirrors `schedule prepare --format json` |
|
||||||
|
| `bundle.has_memory` | bool | Memory file present |
|
||||||
|
| `bundle.has_metrics` | bool | Metrics summary present |
|
||||||
|
| `bundle.pointers` | string[] | Repo pointer labels found (`scope`, `todo`) |
|
||||||
|
| `bundle.bytes` | int | Rendered bundle size |
|
||||||
|
| `session_close` | string[] | Suggested close commands |
|
||||||
|
|
||||||
|
The `bundle.*` flags map 1:1 to the JSON output of
|
||||||
|
`kaizen-agentic schedule prepare <agent> --format json`, so an emitter can build
|
||||||
|
this payload from the existing command without new computation.
|
||||||
|
|
||||||
|
## Consumers (illustrative)
|
||||||
|
|
||||||
|
- **activity-core** — close the loop: mark the scheduled task `in_progress` when
|
||||||
|
a bundle is prepared.
|
||||||
|
- **artifact-store** — archive large bundles by reference.
|
||||||
|
- **dashboards** — fleet view of which scheduled runs have been prepared vs.
|
||||||
|
executed.
|
||||||
|
|
||||||
|
## Boundary
|
||||||
|
|
||||||
|
- The payload carries **metadata and a command**, never secrets or full repo
|
||||||
|
contents.
|
||||||
|
- kaizen-agentic owns the schema; emission wiring (NATS publish) is a future
|
||||||
|
iteration and belongs to the runner / activity-core integration.
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [discover-kaizen-scheduled-repos.md](discover-kaizen-scheduled-repos.md)
|
||||||
|
- [INTEGRATION_PATTERNS.md Pattern 2](../INTEGRATION_PATTERNS.md)
|
||||||
|
- [ADR-005](../adr/ADR-005-scheduled-agent-execution.md)
|
||||||
93
docs/integrations/schedule-schema.md
Normal file
93
docs/integrations/schedule-schema.md
Normal file
@@ -0,0 +1,93 @@
|
|||||||
|
# `.kaizen/schedule.yml` Schema
|
||||||
|
|
||||||
|
The schedule manifest declares which kaizen agents run on what cadence in an
|
||||||
|
opted-in repo. It is the repo-local half of the scheduled-agent-execution
|
||||||
|
contract (ADR-005). activity-core reads it (via the roster resolver) to fire
|
||||||
|
recurring tasks; `kaizen-agentic schedule prepare` reads it indirectly by
|
||||||
|
preparing per-agent orientation.
|
||||||
|
|
||||||
|
Canonical example: [`docs/examples/.kaizen/schedule.yml`](../examples/.kaizen/schedule.yml).
|
||||||
|
|
||||||
|
## Location
|
||||||
|
|
||||||
|
```
|
||||||
|
<project-root>/.kaizen/schedule.yml
|
||||||
|
```
|
||||||
|
|
||||||
|
Lives alongside `.kaizen/agents/` (memory) and `.kaizen/metrics/`. Like those,
|
||||||
|
its presence is the **opt-in signal** for fleet scheduling.
|
||||||
|
|
||||||
|
## Fields
|
||||||
|
|
||||||
|
| Key | Required | Type | Default | Notes |
|
||||||
|
|-----|----------|------|---------|-------|
|
||||||
|
| `version` | yes | string | — | Must be `"1"` |
|
||||||
|
| `timezone` | no | string | from ActivityDefinition | IANA tz, e.g. `Europe/Berlin` |
|
||||||
|
| `agents` | yes | mapping | — | `agent-name → settings` |
|
||||||
|
| `agents.<name>.cadence` | yes | enum | — | `daily` \| `weekly` \| `monthly` |
|
||||||
|
| `agents.<name>.cron` | no | string | cadence default | 5-field cron expression |
|
||||||
|
| `agents.<name>.enabled` | no | bool | `true` | Set `false` to declare but pause |
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
version: "1"
|
||||||
|
timezone: Europe/Berlin
|
||||||
|
agents:
|
||||||
|
coach:
|
||||||
|
cadence: weekly
|
||||||
|
cron: "0 9 * * 1"
|
||||||
|
enabled: true
|
||||||
|
optimization:
|
||||||
|
cadence: weekly
|
||||||
|
cron: "0 10 * * 1"
|
||||||
|
enabled: true
|
||||||
|
tdd-workflow:
|
||||||
|
cadence: monthly
|
||||||
|
enabled: false
|
||||||
|
```
|
||||||
|
|
||||||
|
## Validation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kaizen-agentic schedule validate
|
||||||
|
```
|
||||||
|
|
||||||
|
Errors are emitted with actionable messages and a non-zero exit code:
|
||||||
|
|
||||||
|
- Missing or non-`"1"` `version`.
|
||||||
|
- `agents` not a mapping, or no agents declared.
|
||||||
|
- An agent name that is **not** installed or packaged (typo guard).
|
||||||
|
- A `cadence` outside `daily` / `weekly` / `monthly`.
|
||||||
|
- Duplicate agent entries.
|
||||||
|
|
||||||
|
Only agents available to the project (installed under `agents/` or packaged in
|
||||||
|
the distribution) may appear in a schedule.
|
||||||
|
|
||||||
|
## Scaffolding
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kaizen-agentic schedule init # defaults: coach + optimization weekly
|
||||||
|
kaizen-agentic schedule init --timezone UTC # override timezone
|
||||||
|
kaizen-agentic schedule init --force # overwrite existing
|
||||||
|
```
|
||||||
|
|
||||||
|
The default scaffold enables `coach` and `optimization` weekly and declares
|
||||||
|
`tdd-workflow` monthly but **disabled** (operator opts in deliberately).
|
||||||
|
|
||||||
|
## Listing
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kaizen-agentic schedule list # enabled entries only
|
||||||
|
kaizen-agentic schedule list --all # include disabled
|
||||||
|
```
|
||||||
|
|
||||||
|
## Relationship to activity-core
|
||||||
|
|
||||||
|
The `cron` field is an **optional per-repo override**. When omitted, the cadence
|
||||||
|
maps to the default cron declared in the matching ActivityDefinition (e.g.
|
||||||
|
`weekly-coach-orientation` fires Mon 09:00). This keeps fleet-wide timing in one
|
||||||
|
place while letting individual repos shift their slot.
|
||||||
|
|
||||||
|
See [ADR-005](../adr/ADR-005-scheduled-agent-execution.md) and
|
||||||
|
[INTEGRATION_PATTERNS.md Pattern 2](../INTEGRATION_PATTERNS.md).
|
||||||
64
docs/integrations/state-hub-roster-fields.md
Normal file
64
docs/integrations/state-hub-roster-fields.md
Normal file
@@ -0,0 +1,64 @@
|
|||||||
|
# State Hub Roster Fields for Kaizen Scheduling (Design)
|
||||||
|
|
||||||
|
**Status:** design only — implemented in `the-custodian/state-hub`, not here
|
||||||
|
(repo boundary). This document specifies what kaizen-agentic and activity-core
|
||||||
|
need from the hub so the State Hub team can add the fields and filter.
|
||||||
|
|
||||||
|
## Problem
|
||||||
|
|
||||||
|
activity-core's resolver needs to answer: *which registered repos participate in
|
||||||
|
kaizen fleet scheduling, and where do they live on disk?* Today state-hub knows
|
||||||
|
the canonical repo list and `host_paths` but has no notion of schedule opt-in.
|
||||||
|
|
||||||
|
## Existing hub data (sufficient for v1)
|
||||||
|
|
||||||
|
`GET /repos/` already returns, per repo:
|
||||||
|
|
||||||
|
| Field | Use |
|
||||||
|
|-------|-----|
|
||||||
|
| `slug` | Canonical repo identifier (`target_repo` in tasks) |
|
||||||
|
| `host_paths[hostname] → local_path` | Where the repo is checked out on a runner |
|
||||||
|
| `domain` | Scope filter (e.g. `custodian`) |
|
||||||
|
|
||||||
|
For **v1**, opt-in is detected **in the repo** (`.kaizen/schedule.yml` exists and
|
||||||
|
validates). The resolver clones/reads each candidate path and checks for the
|
||||||
|
file. No hub schema change is strictly required to ship the pilot.
|
||||||
|
|
||||||
|
## Proposed hub fields (v2, optional)
|
||||||
|
|
||||||
|
To let operators query eligibility **without touching every checkout**, add an
|
||||||
|
optional repo-metadata flag:
|
||||||
|
|
||||||
|
| Field | Type | Default | Meaning |
|
||||||
|
|-------|------|---------|---------|
|
||||||
|
| `kaizen_schedule_enabled` | bool | `false` | Operator-confirmed fleet participation |
|
||||||
|
| `kaizen_schedule_updated_at` | timestamp | null | Last time schedule.yml was synced/seen |
|
||||||
|
|
||||||
|
### Suggested filter
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /repos/?kaizen_schedule_enabled=true&domain=custodian
|
||||||
|
```
|
||||||
|
|
||||||
|
Returns only schedule-eligible repos with their `host_paths`, so the resolver
|
||||||
|
skips repos that have not opted in — cheaper than scanning every checkout.
|
||||||
|
|
||||||
|
### Write path
|
||||||
|
|
||||||
|
The flag is set by an operator (or a future `kaizen-agentic schedule register`
|
||||||
|
that calls the hub). It is **advisory**: the authoritative opt-in remains the
|
||||||
|
presence of a valid `.kaizen/schedule.yml` in the repo, re-checked by the
|
||||||
|
resolver at run time. The flag is an index, not a source of truth.
|
||||||
|
|
||||||
|
## Boundary
|
||||||
|
|
||||||
|
- kaizen-agentic does **not** write these fields in WP-0006.
|
||||||
|
- state-hub schema migration is tracked in `the-custodian`.
|
||||||
|
- The resolver (activity-core) treats the hub flag as a pre-filter and the repo
|
||||||
|
file as the decision.
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [discover-kaizen-scheduled-repos.md](discover-kaizen-scheduled-repos.md)
|
||||||
|
- [schedule-schema.md](schedule-schema.md)
|
||||||
|
- [ADR-005](../adr/ADR-005-scheduled-agent-execution.md)
|
||||||
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|||||||
|
|
||||||
[project]
|
[project]
|
||||||
name = "kaizen-agentic"
|
name = "kaizen-agentic"
|
||||||
version = "1.1.0"
|
version = "1.3.0"
|
||||||
description = "AI agent development framework embracing continuous improvement (kaizen)"
|
description = "AI agent development framework embracing continuous improvement (kaizen)"
|
||||||
readme = "README.md"
|
readme = "README.md"
|
||||||
license = {file = "LICENSE"}
|
license = {file = "LICENSE"}
|
||||||
|
|||||||
@@ -9,7 +9,7 @@ It also includes a comprehensive agent distribution system for sharing
|
|||||||
specialized agents across projects via CLI tools and package management.
|
specialized agents across projects via CLI tools and package management.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
__version__ = "1.1.0"
|
__version__ = "1.3.0"
|
||||||
__author__ = "Kaizen Agentic Team"
|
__author__ = "Kaizen Agentic Team"
|
||||||
|
|
||||||
from .core import Agent, AgentConfig
|
from .core import Agent, AgentConfig
|
||||||
|
|||||||
@@ -18,6 +18,13 @@ from .integrations.artifact_store import (
|
|||||||
from .integrations.helix import HelixCorrelationAdapter, enrich_helix_correlation
|
from .integrations.helix import HelixCorrelationAdapter, enrich_helix_correlation
|
||||||
from .metrics import MetricsStore, OptimizerStore, performance_summary_markdown
|
from .metrics import MetricsStore, OptimizerStore, performance_summary_markdown
|
||||||
from .optimization import OptimizationLoop, MIN_SAMPLES_FOR_RECOMMENDATIONS
|
from .optimization import OptimizationLoop, MIN_SAMPLES_FOR_RECOMMENDATIONS
|
||||||
|
from .schedule import (
|
||||||
|
ScheduleError,
|
||||||
|
default_schedule_yaml,
|
||||||
|
load_schedule,
|
||||||
|
schedule_path,
|
||||||
|
validate_schedule,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
def safe_cli_wrapper():
|
def safe_cli_wrapper():
|
||||||
@@ -1360,6 +1367,204 @@ def protocols_show(agent_name: str, slug: str):
|
|||||||
click.echo(protocol_path.read_text())
|
click.echo(protocol_path.read_text())
|
||||||
|
|
||||||
|
|
||||||
|
@cli.group()
|
||||||
|
def schedule():
|
||||||
|
"""Prepare and validate scheduled agent runs (.kaizen/schedule.yml, ADR-005).
|
||||||
|
|
||||||
|
kaizen-agentic does not run cron schedules or invoke Claude. activity-core
|
||||||
|
fires the cron and creates a task per (repo, agent); a coding-agent session
|
||||||
|
runs `schedule prepare <agent>` to assemble orientation, then executes the
|
||||||
|
agent instructions.
|
||||||
|
"""
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
@schedule.command("validate")
|
||||||
|
@click.option("--target", "-t", default=".", help="Project root (default: current)")
|
||||||
|
def schedule_validate(target: str):
|
||||||
|
"""Validate .kaizen/schedule.yml against the ADR-005 schema."""
|
||||||
|
path = schedule_path(_project_root(target))
|
||||||
|
|
||||||
|
try:
|
||||||
|
parsed = load_schedule(path)
|
||||||
|
except ScheduleError as exc:
|
||||||
|
click.echo(f"❌ {exc}", err=True)
|
||||||
|
click.echo(" Run: kaizen-agentic schedule init", err=True)
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
known_agents = _get_registry().agent_names()
|
||||||
|
errors = validate_schedule(parsed, known_agents=known_agents)
|
||||||
|
|
||||||
|
if errors:
|
||||||
|
click.echo(f"❌ Schedule validation failed ({path}):")
|
||||||
|
for error in errors:
|
||||||
|
click.echo(f" • {error}")
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
enabled = parsed.enabled_entries()
|
||||||
|
click.echo(f"✅ Schedule valid: {path}")
|
||||||
|
click.echo(f" {len(parsed.entries)} agent(s), {len(enabled)} enabled")
|
||||||
|
|
||||||
|
|
||||||
|
@schedule.command("init")
|
||||||
|
@click.option("--target", "-t", default=".", help="Project root (default: current)")
|
||||||
|
@click.option(
|
||||||
|
"--timezone", default="Europe/Berlin", show_default=True, help="Schedule timezone"
|
||||||
|
)
|
||||||
|
@click.option("--force", is_flag=True, help="Overwrite an existing schedule.yml")
|
||||||
|
def schedule_init(target: str, timezone: str, force: bool):
|
||||||
|
"""Scaffold a default .kaizen/schedule.yml (coach + optimization weekly)."""
|
||||||
|
path = schedule_path(_project_root(target))
|
||||||
|
|
||||||
|
if path.exists() and not force:
|
||||||
|
click.echo(f"Schedule already exists: {path}")
|
||||||
|
click.echo(" Use --force to overwrite.")
|
||||||
|
return
|
||||||
|
|
||||||
|
path.parent.mkdir(parents=True, exist_ok=True)
|
||||||
|
path.write_text(default_schedule_yaml(timezone=timezone), encoding="utf-8")
|
||||||
|
click.echo(f"Initialized schedule: {path}")
|
||||||
|
click.echo(" Validate with: kaizen-agentic schedule validate")
|
||||||
|
|
||||||
|
|
||||||
|
@schedule.command("list")
|
||||||
|
@click.option("--target", "-t", default=".", help="Project root (default: current)")
|
||||||
|
@click.option("--all", "show_all", is_flag=True, help="Include disabled entries")
|
||||||
|
def schedule_list(target: str, show_all: bool):
|
||||||
|
"""Show enabled schedule entries from .kaizen/schedule.yml."""
|
||||||
|
path = schedule_path(_project_root(target))
|
||||||
|
|
||||||
|
try:
|
||||||
|
parsed = load_schedule(path)
|
||||||
|
except ScheduleError as exc:
|
||||||
|
click.echo(f"No schedule found: {exc}")
|
||||||
|
click.echo(" Run: kaizen-agentic schedule init")
|
||||||
|
return
|
||||||
|
|
||||||
|
entries = parsed.entries if show_all else parsed.enabled_entries()
|
||||||
|
if not entries:
|
||||||
|
click.echo("No enabled schedule entries (use --all to see disabled).")
|
||||||
|
return
|
||||||
|
|
||||||
|
click.echo(f"Scheduled agents ({path}):")
|
||||||
|
if parsed.timezone:
|
||||||
|
click.echo(f" Timezone: {parsed.timezone}")
|
||||||
|
for entry in entries:
|
||||||
|
flag = "✅" if entry.enabled else "⏸ "
|
||||||
|
cron = f" cron={entry.cron}" if entry.cron else ""
|
||||||
|
click.echo(f" {flag} {entry.agent}: {entry.cadence}{cron}")
|
||||||
|
|
||||||
|
|
||||||
|
@schedule.command("prepare")
|
||||||
|
@click.argument("agent_name")
|
||||||
|
@click.option("--target", "-t", default=".", help="Project root (default: current)")
|
||||||
|
@click.option(
|
||||||
|
"--format",
|
||||||
|
"output_format",
|
||||||
|
type=click.Choice(["markdown", "json"]),
|
||||||
|
default="markdown",
|
||||||
|
show_default=True,
|
||||||
|
help="Output format for the orientation bundle",
|
||||||
|
)
|
||||||
|
def schedule_prepare(agent_name: str, target: str, output_format: str):
|
||||||
|
"""Assemble an orientation bundle for a scheduled agent run.
|
||||||
|
|
||||||
|
Bundles the agent prompt, project memory, metrics summary, and repo
|
||||||
|
pointers into a single payload. Works offline from local `.kaizen/` state;
|
||||||
|
no State Hub required. Pass the output to a coding-agent session.
|
||||||
|
"""
|
||||||
|
bundle = _build_prepare_bundle(agent_name, _project_root(target))
|
||||||
|
|
||||||
|
if output_format == "json":
|
||||||
|
click.echo(json.dumps(bundle, indent=2))
|
||||||
|
return
|
||||||
|
|
||||||
|
click.echo(_render_prepare_markdown(bundle))
|
||||||
|
|
||||||
|
|
||||||
|
def _build_prepare_bundle(agent_name: str, project_root: Path) -> dict:
|
||||||
|
"""Collect the orientation bundle pieces for `schedule prepare`."""
|
||||||
|
registry = _get_registry()
|
||||||
|
agent_path = registry.get_agent_path(agent_name)
|
||||||
|
agent_prompt = agent_path.read_text(encoding="utf-8") if agent_path else None
|
||||||
|
|
||||||
|
memory_path = project_root / ".kaizen" / "agents" / agent_name / "memory.md"
|
||||||
|
memory = memory_path.read_text(encoding="utf-8") if memory_path.exists() else None
|
||||||
|
|
||||||
|
metrics_store = MetricsStore(project_root, agent_name)
|
||||||
|
metrics_summary = metrics_store.read_summary()
|
||||||
|
if metrics_summary is None and metrics_store.executions_path.exists():
|
||||||
|
metrics_summary = metrics_store.write_summary()
|
||||||
|
|
||||||
|
pointers = {}
|
||||||
|
for label, filename in (("scope", "SCOPE.md"), ("todo", "TODO.md")):
|
||||||
|
candidate = project_root / filename
|
||||||
|
if candidate.exists():
|
||||||
|
pointers[label] = str(candidate)
|
||||||
|
|
||||||
|
return {
|
||||||
|
"agent": agent_name,
|
||||||
|
"project": project_root.name,
|
||||||
|
"generated": _today(),
|
||||||
|
"agent_prompt": agent_prompt,
|
||||||
|
"agent_prompt_found": agent_prompt is not None,
|
||||||
|
"memory": memory,
|
||||||
|
"metrics_summary": metrics_summary,
|
||||||
|
"pointers": pointers,
|
||||||
|
"session_close": [
|
||||||
|
f"kaizen-agentic metrics record {agent_name} --success "
|
||||||
|
f"--time <seconds> --quality <0-1>",
|
||||||
|
f"Update memory: kaizen-agentic memory show {agent_name}",
|
||||||
|
],
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def _render_prepare_markdown(bundle: dict) -> str:
|
||||||
|
agent = bundle["agent"]
|
||||||
|
lines = [
|
||||||
|
f"# Scheduled Run Orientation: {agent}",
|
||||||
|
f"Project: {bundle['project']}",
|
||||||
|
f"Generated: {bundle['generated']}",
|
||||||
|
"",
|
||||||
|
]
|
||||||
|
|
||||||
|
summary = bundle.get("metrics_summary")
|
||||||
|
block = performance_summary_markdown(summary or {})
|
||||||
|
if block:
|
||||||
|
lines.append(block)
|
||||||
|
|
||||||
|
lines.append("## Agent Prompt")
|
||||||
|
if bundle["agent_prompt_found"]:
|
||||||
|
lines.append(bundle["agent_prompt"])
|
||||||
|
else:
|
||||||
|
lines.append(
|
||||||
|
f"(agent '{agent}' not found in registry — " f"run: kaizen-agentic list)"
|
||||||
|
)
|
||||||
|
lines.append("")
|
||||||
|
|
||||||
|
lines.append("## Project Memory")
|
||||||
|
if bundle.get("memory"):
|
||||||
|
lines.append(bundle["memory"])
|
||||||
|
else:
|
||||||
|
lines.append(f"(none — run: kaizen-agentic memory init {agent})")
|
||||||
|
lines.append("")
|
||||||
|
|
||||||
|
pointers = bundle.get("pointers") or {}
|
||||||
|
lines.append("## Repo Pointers")
|
||||||
|
if pointers:
|
||||||
|
for label, path in pointers.items():
|
||||||
|
lines.append(f"- {label}: {path}")
|
||||||
|
else:
|
||||||
|
lines.append("- (no SCOPE.md / TODO.md found)")
|
||||||
|
lines.append("")
|
||||||
|
|
||||||
|
lines.append("## Session Close")
|
||||||
|
for cmd in bundle["session_close"]:
|
||||||
|
lines.append(f"- `{cmd}`")
|
||||||
|
|
||||||
|
return "\n".join(lines)
|
||||||
|
|
||||||
|
|
||||||
def _project_root(target: str) -> Path:
|
def _project_root(target: str) -> Path:
|
||||||
return Path(target).resolve()
|
return Path(target).resolve()
|
||||||
|
|
||||||
|
|||||||
185
src/kaizen_agentic/schedule.py
Normal file
185
src/kaizen_agentic/schedule.py
Normal file
@@ -0,0 +1,185 @@
|
|||||||
|
"""Repo-local scheduled agent execution manifest (.kaizen/schedule.yml).
|
||||||
|
|
||||||
|
ADR-005 defines the schedule contract: which agents run on what cadence in an
|
||||||
|
opted-in repo. kaizen-agentic owns parsing, validation, and preparing an
|
||||||
|
orientation bundle for a scheduled run. It does **not** run cron schedules or
|
||||||
|
invoke Claude — activity-core fires the cron and a coding-agent session executes
|
||||||
|
the prepared bundle.
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from dataclasses import dataclass, field
|
||||||
|
from pathlib import Path
|
||||||
|
from typing import Any, Dict, List, Optional
|
||||||
|
|
||||||
|
import yaml
|
||||||
|
|
||||||
|
SCHEDULE_RELATIVE_PATH = Path(".kaizen") / "schedule.yml"
|
||||||
|
SCHEDULE_VERSION = "1"
|
||||||
|
VALID_CADENCES = ("daily", "weekly", "monthly")
|
||||||
|
|
||||||
|
# Sensible defaults for `schedule init` — coach + optimization weekly, the
|
||||||
|
# heavier tdd-workflow review monthly and disabled until an operator opts in.
|
||||||
|
DEFAULT_AGENTS: Dict[str, Dict[str, Any]] = {
|
||||||
|
"coach": {"cadence": "weekly", "cron": "0 9 * * 1", "enabled": True},
|
||||||
|
"optimization": {"cadence": "weekly", "cron": "0 10 * * 1", "enabled": True},
|
||||||
|
"tdd-workflow": {"cadence": "monthly", "enabled": False},
|
||||||
|
}
|
||||||
|
DEFAULT_TIMEZONE = "Europe/Berlin"
|
||||||
|
|
||||||
|
|
||||||
|
class ScheduleError(Exception):
|
||||||
|
"""Raised when a schedule manifest cannot be parsed."""
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class ScheduleEntry:
|
||||||
|
"""One scheduled agent run declaration."""
|
||||||
|
|
||||||
|
agent: str
|
||||||
|
cadence: str
|
||||||
|
enabled: bool = True
|
||||||
|
cron: Optional[str] = None
|
||||||
|
|
||||||
|
def to_dict(self) -> Dict[str, Any]:
|
||||||
|
data: Dict[str, Any] = {"cadence": self.cadence, "enabled": self.enabled}
|
||||||
|
if self.cron:
|
||||||
|
data["cron"] = self.cron
|
||||||
|
return data
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class Schedule:
|
||||||
|
"""Parsed `.kaizen/schedule.yml` manifest."""
|
||||||
|
|
||||||
|
version: str
|
||||||
|
timezone: Optional[str] = None
|
||||||
|
entries: List[ScheduleEntry] = field(default_factory=list)
|
||||||
|
source_path: Optional[Path] = None
|
||||||
|
|
||||||
|
def entry_for(self, agent: str) -> Optional[ScheduleEntry]:
|
||||||
|
for entry in self.entries:
|
||||||
|
if entry.agent == agent:
|
||||||
|
return entry
|
||||||
|
return None
|
||||||
|
|
||||||
|
def enabled_entries(self) -> List[ScheduleEntry]:
|
||||||
|
return [e for e in self.entries if e.enabled]
|
||||||
|
|
||||||
|
|
||||||
|
def schedule_path(project_root: Path) -> Path:
|
||||||
|
"""Return the canonical schedule.yml path for a project root."""
|
||||||
|
return Path(project_root) / SCHEDULE_RELATIVE_PATH
|
||||||
|
|
||||||
|
|
||||||
|
def parse_schedule(data: Any, source_path: Optional[Path] = None) -> Schedule:
|
||||||
|
"""Parse a raw mapping into a Schedule (structural errors raise).
|
||||||
|
|
||||||
|
Semantic validation (known agents, cadence values) is handled by
|
||||||
|
:func:`validate_schedule` so callers can collect actionable error lists.
|
||||||
|
"""
|
||||||
|
if not isinstance(data, dict):
|
||||||
|
raise ScheduleError("schedule.yml must be a YAML mapping at the top level")
|
||||||
|
|
||||||
|
version = data.get("version")
|
||||||
|
if version is None:
|
||||||
|
raise ScheduleError("schedule.yml is missing required key: version")
|
||||||
|
version = str(version)
|
||||||
|
|
||||||
|
timezone = data.get("timezone")
|
||||||
|
if timezone is not None and not isinstance(timezone, str):
|
||||||
|
raise ScheduleError("timezone must be a string")
|
||||||
|
|
||||||
|
agents = data.get("agents", {})
|
||||||
|
if not isinstance(agents, dict):
|
||||||
|
raise ScheduleError("agents must be a mapping of agent-name -> settings")
|
||||||
|
|
||||||
|
entries: List[ScheduleEntry] = []
|
||||||
|
for name, settings in agents.items():
|
||||||
|
if settings is None:
|
||||||
|
settings = {}
|
||||||
|
if not isinstance(settings, dict):
|
||||||
|
raise ScheduleError(f"agent '{name}' settings must be a mapping")
|
||||||
|
cron = settings.get("cron")
|
||||||
|
if cron is not None and not isinstance(cron, str):
|
||||||
|
raise ScheduleError(f"agent '{name}' cron must be a string")
|
||||||
|
entries.append(
|
||||||
|
ScheduleEntry(
|
||||||
|
agent=str(name),
|
||||||
|
cadence=str(settings.get("cadence", "")),
|
||||||
|
enabled=bool(settings.get("enabled", True)),
|
||||||
|
cron=cron,
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
return Schedule(
|
||||||
|
version=version,
|
||||||
|
timezone=timezone,
|
||||||
|
entries=entries,
|
||||||
|
source_path=source_path,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def load_schedule(path: Path) -> Schedule:
|
||||||
|
"""Load and parse a schedule.yml file (raises ScheduleError)."""
|
||||||
|
path = Path(path)
|
||||||
|
if not path.exists():
|
||||||
|
raise ScheduleError(f"schedule file not found: {path}")
|
||||||
|
try:
|
||||||
|
raw = yaml.safe_load(path.read_text(encoding="utf-8"))
|
||||||
|
except yaml.YAMLError as exc: # pragma: no cover - passthrough message
|
||||||
|
raise ScheduleError(f"invalid YAML in {path}: {exc}") from exc
|
||||||
|
return parse_schedule(raw, source_path=path)
|
||||||
|
|
||||||
|
|
||||||
|
def validate_schedule(
|
||||||
|
schedule: Schedule, known_agents: Optional[List[str]] = None
|
||||||
|
) -> List[str]:
|
||||||
|
"""Return a list of human-readable validation errors (empty == valid)."""
|
||||||
|
errors: List[str] = []
|
||||||
|
|
||||||
|
if schedule.version != SCHEDULE_VERSION:
|
||||||
|
errors.append(
|
||||||
|
f"unsupported version '{schedule.version}' "
|
||||||
|
f"(expected '{SCHEDULE_VERSION}')"
|
||||||
|
)
|
||||||
|
|
||||||
|
if not schedule.entries:
|
||||||
|
errors.append("no agents declared under 'agents:'")
|
||||||
|
|
||||||
|
seen: set = set()
|
||||||
|
known = set(known_agents) if known_agents is not None else None
|
||||||
|
for entry in schedule.entries:
|
||||||
|
if entry.agent in seen:
|
||||||
|
errors.append(f"duplicate agent entry: {entry.agent}")
|
||||||
|
seen.add(entry.agent)
|
||||||
|
|
||||||
|
if entry.cadence not in VALID_CADENCES:
|
||||||
|
errors.append(
|
||||||
|
f"agent '{entry.agent}': invalid cadence '{entry.cadence}' "
|
||||||
|
f"(expected one of {', '.join(VALID_CADENCES)})"
|
||||||
|
)
|
||||||
|
|
||||||
|
if known is not None and entry.agent not in known:
|
||||||
|
errors.append(
|
||||||
|
f"agent '{entry.agent}' is not an installed or packaged agent"
|
||||||
|
)
|
||||||
|
|
||||||
|
return errors
|
||||||
|
|
||||||
|
|
||||||
|
def default_schedule_yaml(timezone: str = DEFAULT_TIMEZONE) -> str:
|
||||||
|
"""Render the default schedule.yml scaffold for `schedule init`."""
|
||||||
|
document = {
|
||||||
|
"version": SCHEDULE_VERSION,
|
||||||
|
"timezone": timezone,
|
||||||
|
"agents": dict(DEFAULT_AGENTS),
|
||||||
|
}
|
||||||
|
header = (
|
||||||
|
"# Kaizen scheduled agent execution manifest (ADR-005)\n"
|
||||||
|
"# Declares which agents run on what cadence in this repo.\n"
|
||||||
|
"# Validate with: kaizen-agentic schedule validate\n"
|
||||||
|
)
|
||||||
|
body = yaml.safe_dump(document, sort_keys=False, default_flow_style=False)
|
||||||
|
return header + body
|
||||||
@@ -13,7 +13,8 @@ DEFINITIONS_DIR = (
|
|||||||
|
|
||||||
def test_activity_definitions_have_required_frontmatter():
|
def test_activity_definitions_have_required_frontmatter():
|
||||||
files = list(DEFINITIONS_DIR.glob("*.md"))
|
files = list(DEFINITIONS_DIR.glob("*.md"))
|
||||||
assert len(files) == 3
|
# 3 from WP-0004 (metrics) + 2 from WP-0006 (scheduled agent runs)
|
||||||
|
assert len(files) == 5
|
||||||
|
|
||||||
for path in files:
|
for path in files:
|
||||||
text = path.read_text(encoding="utf-8")
|
text = path.read_text(encoding="utf-8")
|
||||||
|
|||||||
166
tests/test_schedule_cli.py
Normal file
166
tests/test_schedule_cli.py
Normal file
@@ -0,0 +1,166 @@
|
|||||||
|
"""CLI + module tests for scheduled agent execution (ADR-005, WP-0006)."""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import json
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
import pytest
|
||||||
|
from click.testing import CliRunner
|
||||||
|
|
||||||
|
from kaizen_agentic.cli import cli
|
||||||
|
from kaizen_agentic.schedule import (
|
||||||
|
ScheduleError,
|
||||||
|
parse_schedule,
|
||||||
|
schedule_path,
|
||||||
|
validate_schedule,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def runner() -> CliRunner:
|
||||||
|
return CliRunner()
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def project_dir(tmp_path: Path) -> Path:
|
||||||
|
root = tmp_path / "demo-project"
|
||||||
|
root.mkdir()
|
||||||
|
return root
|
||||||
|
|
||||||
|
|
||||||
|
class TestScheduleModule:
|
||||||
|
def test_parse_requires_version(self):
|
||||||
|
with pytest.raises(ScheduleError):
|
||||||
|
parse_schedule({"agents": {}})
|
||||||
|
|
||||||
|
def test_parse_rejects_non_mapping(self):
|
||||||
|
with pytest.raises(ScheduleError):
|
||||||
|
parse_schedule(["not", "a", "mapping"])
|
||||||
|
|
||||||
|
def test_validate_flags_unknown_agent_and_bad_cadence(self):
|
||||||
|
schedule = parse_schedule(
|
||||||
|
{
|
||||||
|
"version": "1",
|
||||||
|
"agents": {
|
||||||
|
"coach": {"cadence": "weekly", "enabled": True},
|
||||||
|
"made-up": {"cadence": "hourly"},
|
||||||
|
},
|
||||||
|
}
|
||||||
|
)
|
||||||
|
errors = validate_schedule(schedule, known_agents=["coach", "optimization"])
|
||||||
|
assert any("hourly" in e for e in errors)
|
||||||
|
assert any("made-up" in e for e in errors)
|
||||||
|
|
||||||
|
def test_validate_clean_schedule(self):
|
||||||
|
schedule = parse_schedule(
|
||||||
|
{"version": "1", "agents": {"coach": {"cadence": "weekly"}}}
|
||||||
|
)
|
||||||
|
assert validate_schedule(schedule, known_agents=["coach"]) == []
|
||||||
|
|
||||||
|
|
||||||
|
class TestScheduleCli:
|
||||||
|
def test_init_creates_default_schedule(self, runner: CliRunner, project_dir: Path):
|
||||||
|
result = runner.invoke(cli, ["schedule", "init", "--target", str(project_dir)])
|
||||||
|
assert result.exit_code == 0
|
||||||
|
path = schedule_path(project_dir)
|
||||||
|
assert path.exists()
|
||||||
|
assert "coach" in path.read_text()
|
||||||
|
|
||||||
|
def test_init_no_overwrite_without_force(
|
||||||
|
self, runner: CliRunner, project_dir: Path
|
||||||
|
):
|
||||||
|
runner.invoke(cli, ["schedule", "init", "--target", str(project_dir)])
|
||||||
|
result = runner.invoke(cli, ["schedule", "init", "--target", str(project_dir)])
|
||||||
|
assert result.exit_code == 0
|
||||||
|
assert "already exists" in result.output
|
||||||
|
|
||||||
|
def test_validate_passes_on_default(self, runner: CliRunner, project_dir: Path):
|
||||||
|
runner.invoke(cli, ["schedule", "init", "--target", str(project_dir)])
|
||||||
|
result = runner.invoke(
|
||||||
|
cli, ["schedule", "validate", "--target", str(project_dir)]
|
||||||
|
)
|
||||||
|
assert result.exit_code == 0
|
||||||
|
assert "valid" in result.output
|
||||||
|
|
||||||
|
def test_validate_missing_file_errors(self, runner: CliRunner, project_dir: Path):
|
||||||
|
result = runner.invoke(
|
||||||
|
cli, ["schedule", "validate", "--target", str(project_dir)]
|
||||||
|
)
|
||||||
|
assert result.exit_code == 1
|
||||||
|
|
||||||
|
def test_validate_rejects_bad_schema(self, runner: CliRunner, project_dir: Path):
|
||||||
|
path = schedule_path(project_dir)
|
||||||
|
path.parent.mkdir(parents=True, exist_ok=True)
|
||||||
|
path.write_text("version: '1'\nagents:\n not-an-agent:\n cadence: weekly\n")
|
||||||
|
result = runner.invoke(
|
||||||
|
cli, ["schedule", "validate", "--target", str(project_dir)]
|
||||||
|
)
|
||||||
|
assert result.exit_code == 1
|
||||||
|
assert "not-an-agent" in result.output
|
||||||
|
|
||||||
|
def test_list_shows_enabled(self, runner: CliRunner, project_dir: Path):
|
||||||
|
runner.invoke(cli, ["schedule", "init", "--target", str(project_dir)])
|
||||||
|
result = runner.invoke(cli, ["schedule", "list", "--target", str(project_dir)])
|
||||||
|
assert result.exit_code == 0
|
||||||
|
assert "coach" in result.output
|
||||||
|
# tdd-workflow is disabled by default; hidden without --all
|
||||||
|
assert "tdd-workflow" not in result.output
|
||||||
|
|
||||||
|
def test_list_all_shows_disabled(self, runner: CliRunner, project_dir: Path):
|
||||||
|
runner.invoke(cli, ["schedule", "init", "--target", str(project_dir)])
|
||||||
|
result = runner.invoke(
|
||||||
|
cli, ["schedule", "list", "--all", "--target", str(project_dir)]
|
||||||
|
)
|
||||||
|
assert "tdd-workflow" in result.output
|
||||||
|
|
||||||
|
def test_prepare_markdown_includes_agent_prompt(
|
||||||
|
self, runner: CliRunner, project_dir: Path
|
||||||
|
):
|
||||||
|
result = runner.invoke(
|
||||||
|
cli, ["schedule", "prepare", "coach", "--target", str(project_dir)]
|
||||||
|
)
|
||||||
|
assert result.exit_code == 0
|
||||||
|
assert "Scheduled Run Orientation: coach" in result.output
|
||||||
|
assert "## Agent Prompt" in result.output
|
||||||
|
assert "Coach Agent" in result.output
|
||||||
|
assert "## Session Close" in result.output
|
||||||
|
|
||||||
|
def test_prepare_json_format(self, runner: CliRunner, project_dir: Path):
|
||||||
|
result = runner.invoke(
|
||||||
|
cli,
|
||||||
|
[
|
||||||
|
"schedule",
|
||||||
|
"prepare",
|
||||||
|
"coach",
|
||||||
|
"--target",
|
||||||
|
str(project_dir),
|
||||||
|
"--format",
|
||||||
|
"json",
|
||||||
|
],
|
||||||
|
)
|
||||||
|
assert result.exit_code == 0
|
||||||
|
payload = json.loads(result.output)
|
||||||
|
assert payload["agent"] == "coach"
|
||||||
|
assert payload["agent_prompt_found"] is True
|
||||||
|
assert payload["session_close"]
|
||||||
|
|
||||||
|
def test_prepare_unknown_agent_notes_missing(
|
||||||
|
self, runner: CliRunner, project_dir: Path
|
||||||
|
):
|
||||||
|
result = runner.invoke(
|
||||||
|
cli,
|
||||||
|
["schedule", "prepare", "no-such-agent", "--target", str(project_dir)],
|
||||||
|
)
|
||||||
|
assert result.exit_code == 0
|
||||||
|
assert "not found in registry" in result.output
|
||||||
|
|
||||||
|
def test_prepare_includes_memory_when_present(
|
||||||
|
self, runner: CliRunner, project_dir: Path
|
||||||
|
):
|
||||||
|
runner.invoke(cli, ["memory", "init", "coach", "--target", str(project_dir)])
|
||||||
|
result = runner.invoke(
|
||||||
|
cli, ["schedule", "prepare", "coach", "--target", str(project_dir)]
|
||||||
|
)
|
||||||
|
assert "## Project Memory" in result.output
|
||||||
|
assert "Project Context" in result.output
|
||||||
@@ -96,7 +96,20 @@ ActivityDefinition reference copies (sync into activity-core to activate):
|
|||||||
- [post-install-metrics-scaffold](../docs/integrations/activity-definitions/post-install-metrics-scaffold.md)
|
- [post-install-metrics-scaffold](../docs/integrations/activity-definitions/post-install-metrics-scaffold.md)
|
||||||
- [low-success-rate-review](../docs/integrations/activity-definitions/low-success-rate-review.md)
|
- [low-success-rate-review](../docs/integrations/activity-definitions/low-success-rate-review.md)
|
||||||
|
|
||||||
**Workplan:** KAIZEN-WP-0004 Part 2. Patterns: [docs/INTEGRATION_PATTERNS.md](../docs/INTEGRATION_PATTERNS.md).
|
**Scheduled agent execution (WP-0006, ADR-005)** — run agents (not just the
|
||||||
|
metrics optimizer) on a cadence against a preselected repo roster:
|
||||||
|
|
||||||
|
- [weekly-coach-orientation](../docs/integrations/activity-definitions/weekly-coach-orientation.md)
|
||||||
|
- [weekly-optimization-review](../docs/integrations/activity-definitions/weekly-optimization-review.md)
|
||||||
|
- Resolver spec: [discover-kaizen-scheduled-repos](../docs/integrations/discover-kaizen-scheduled-repos.md)
|
||||||
|
- Roster fields: [state-hub-roster-fields](../docs/integrations/state-hub-roster-fields.md)
|
||||||
|
- Handoff checklist: [activity-core-handoff-wp0006](../docs/integrations/activity-core-handoff-wp0006.md)
|
||||||
|
|
||||||
|
A repo opts in by committing `.kaizen/schedule.yml` (`kaizen-agentic schedule
|
||||||
|
init`); activity-core fires the cron and creates a task per `(repo, agent)` that
|
||||||
|
runs `kaizen-agentic schedule prepare <agent>`.
|
||||||
|
|
||||||
|
**Workplan:** KAIZEN-WP-0004 Part 2 + KAIZEN-WP-0006. Patterns: [docs/INTEGRATION_PATTERNS.md](../docs/INTEGRATION_PATTERNS.md).
|
||||||
|
|
||||||
### artifact-store (P1)
|
### artifact-store (P1)
|
||||||
|
|
||||||
@@ -194,4 +207,4 @@ WP-0001 T04. Assess before depending on it.
|
|||||||
Persisted in `history/`:
|
Persisted in `history/`:
|
||||||
|
|
||||||
- `2026-06-16-intent-gap-analysis.md`
|
- `2026-06-16-intent-gap-analysis.md`
|
||||||
- `2026-06-16-ecosystem-assessment.md`
|
- `2026-06-16-ecosystem-assessment.md`
|
||||||
|
|||||||
@@ -9,7 +9,104 @@ owner: kaizen-agentic
|
|||||||
topic_slug: custodian
|
topic_slug: custodian
|
||||||
state_hub_workstream_id: 36252a45-f360-4496-bf77-17b5dfb02767
|
state_hub_workstream_id: 36252a45-f360-4496-bf77-17b5dfb02767
|
||||||
created: "2026-06-16"
|
created: "2026-06-16"
|
||||||
updated: "2026-06-18"
|
updated: "2026-06-17"
|
||||||
|
tasks:
|
||||||
|
- id: T01
|
||||||
|
title: Write ADR-004 project metrics convention
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 4e7b0fd2-38c0-46aa-84a7-bb18366b8c7c
|
||||||
|
- id: T02
|
||||||
|
title: Implement MetricsStore in metrics.py
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: eeaa99c7-d7a7-403b-a013-364cba45a663
|
||||||
|
- id: T03
|
||||||
|
title: Add memory init hook to scaffold metrics directory
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 247c097f-de89-4383-930c-35ee66de9b36
|
||||||
|
- id: T04
|
||||||
|
title: Unit tests for MetricsStore
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 3aa14026-6ee3-4384-b409-11300c1302f0
|
||||||
|
- id: T05
|
||||||
|
title: Implement metrics CLI command group
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 6b505d29-7d2e-44a2-a4b7-1fe82884390c
|
||||||
|
- id: T06
|
||||||
|
title: Integrate metrics record into session-close template
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 84f2a357-f2dd-4fc7-96b6-a4e80d5467a7
|
||||||
|
- id: T07
|
||||||
|
title: CLI tests for metrics commands
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 8e9ee64b-b7c4-4dff-ac6e-988fd47ef95d
|
||||||
|
- id: T08
|
||||||
|
title: Update CLI cheat sheet and agency-framework with metrics
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 4c41e0db-d5d8-4a1b-b346-06ad004edf4a
|
||||||
|
- id: T09
|
||||||
|
title: Add OptimizationLoop.from_metrics_store factory
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 0b374439-6eca-4754-8e15-2a7eece0cd27
|
||||||
|
- id: T10
|
||||||
|
title: Implement kaizen-agentic metrics optimize command
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: db87a09b-0252-495c-a771-a43b4b98f820
|
||||||
|
- id: T11
|
||||||
|
title: Consolidate optimization meta-agent definitions
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 73cb7d73-6fc6-42a9-97aa-d33cdf9ee363
|
||||||
|
- id: T12
|
||||||
|
title: Update optimization agent session protocol
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: c127eca7-7394-42db-ba5e-721aef0ccb76
|
||||||
|
- id: T13
|
||||||
|
title: Unit and integration tests for optimizer recommendations
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: f208dc9f-cdf7-47e3-9c03-09097e46eee9
|
||||||
|
- id: T14
|
||||||
|
title: Extend memory brief with metrics summary
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: d01f969c-bbb1-4eca-a4f1-d79d5c867b35
|
||||||
|
- id: T15
|
||||||
|
title: Extend agent-coach.md for metrics context
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 67f791a4-fced-4986-a331-7eb4ea47fe6e
|
||||||
|
- id: T16
|
||||||
|
title: E2e test memory brief with metrics sections
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 1fb89b54-8bd2-40bf-9a71-04693cb9f695
|
||||||
|
- id: T17
|
||||||
|
title: Add metrics section to agent-tdd-workflow.md
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 1d471a7a-9a98-4805-903e-b4a2b8153717
|
||||||
|
- id: T18
|
||||||
|
title: Add session-close metrics record step to tdd-workflow
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: abb387f1-86ce-4b9b-a516-2d4efb6aca4c
|
||||||
|
- id: T19
|
||||||
|
title: Document tdd-workflow pilot in wiki/AboutKaizenAgents.md
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 67fbc26e-a57d-4133-96e6-3d2cdbd10dc0
|
||||||
|
- id: T20
|
||||||
|
title: E2e test full tdd-workflow measure-analyse-orient loop
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: fbdd7c8b-e122-48d9-8c8f-de9f82d025e3
|
||||||
|
- id: T21
|
||||||
|
title: Sync 4 missing agents into packaged data/
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 9662bcec-34fe-451b-b61f-5d11b9574576
|
||||||
|
- id: T22
|
||||||
|
title: Update README orientation links to INTENT and wiki
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 422aae43-5697-4a00-86e9-1569baf09422
|
||||||
|
- id: T23
|
||||||
|
title: Update architecture.md agent table
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: ba6b3411-d330-4a58-8cd0-62b4fbef8c5f
|
||||||
|
- id: T24
|
||||||
|
title: CHANGELOG entry for metrics convention and CLI
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 748be9f3-f6ac-4f26-a844-6330268935b6
|
||||||
---
|
---
|
||||||
|
|
||||||
# KAIZEN-WP-0003 — Measurement Loop: Metrics Convention, Collection, and Optimizer Integration
|
# KAIZEN-WP-0003 — Measurement Loop: Metrics Convention, Collection, and Optimizer Integration
|
||||||
@@ -249,6 +346,23 @@ A reader of `INTENT.md` can point to this repo and say:
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Completion
|
||||||
|
|
||||||
|
**Shipped:** v1.1.0 (2026-06-18); measurement loop operational through v1.2.0.
|
||||||
|
|
||||||
|
| Milestone | Detail |
|
||||||
|
|-----------|--------|
|
||||||
|
| ADR-004 | Project metrics convention (`.kaizen/metrics/`) |
|
||||||
|
| CLI | `metrics record`, `show`, `list`, `export`, `optimize` |
|
||||||
|
| Coach bridge | `memory brief` includes `## Performance Summary` |
|
||||||
|
| Pilot | `tdd-workflow` reference in `wiki/AboutKaizenAgents.md` |
|
||||||
|
| Tests | `test_metrics*.py`, `test_optimization_metrics.py`, e2e agency tests pass |
|
||||||
|
|
||||||
|
All 24 tasks complete. Fleet-wide template conformance and scheduled optimizer runs
|
||||||
|
remain out of scope (future workplans).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## State Hub Task IDs
|
## State Hub Task IDs
|
||||||
|
|
||||||
| Code | UUID |
|
| Code | UUID |
|
||||||
@@ -286,4 +400,4 @@ A reader of `INTENT.md` can point to this repo and say:
|
|||||||
|
|
||||||
- Retention default: 180 days (per `wiki/AgentKaizenOptimizer.md`); override via project config in a later iteration
|
- Retention default: 180 days (per `wiki/AgentKaizenOptimizer.md`); override via project config in a later iteration
|
||||||
- WP-0001 T04 (telemetry) should consume ADR-004 schema rather than inventing a parallel format
|
- WP-0001 T04 (telemetry) should consume ADR-004 schema rather than inventing a parallel format
|
||||||
- `OptimizationLoop` threshold constants (30s execution, 0.8 success rate) are starting points; expose in config later
|
- `OptimizationLoop` threshold constants (30s execution, 0.8 success rate) are starting points; expose in config later
|
||||||
|
|||||||
@@ -9,7 +9,84 @@ owner: kaizen-agentic
|
|||||||
topic_slug: custodian
|
topic_slug: custodian
|
||||||
state_hub_workstream_id: 76be7294-e201-4074-91c0-6421992470fe
|
state_hub_workstream_id: 76be7294-e201-4074-91c0-6421992470fe
|
||||||
created: "2026-06-16"
|
created: "2026-06-16"
|
||||||
updated: "2026-06-18"
|
updated: "2026-06-17"
|
||||||
|
tasks:
|
||||||
|
- id: T01
|
||||||
|
title: Document Helix Forge correlation contract cross-repo
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: f365d19e-9619-4453-bebf-f1fd596b1bd1
|
||||||
|
- id: T02
|
||||||
|
title: Add HELIX_SESSION_UID to metrics record
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: e7f47683-5957-49db-bcbd-3aa47f44a073
|
||||||
|
- id: T03
|
||||||
|
title: Add kaizen-agentic metrics correlate command stub
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 6ef8ba99-7d0c-44f4-835d-7a66e9d55984
|
||||||
|
- id: T04
|
||||||
|
title: Integration test for helix_session_uid correlation
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 9875422c-a54b-40f1-a444-6b485a9e57d6
|
||||||
|
- id: T05
|
||||||
|
title: Update EcosystemIntegration.md with worked example
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 0dc33d13-0e0b-4336-a7ad-371fc533b823
|
||||||
|
- id: T06
|
||||||
|
title: Draft weekly metrics optimize ActivityDefinition
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: dbaa5f46-f66a-4a74-b4a0-97978e47d1c3
|
||||||
|
- id: T07
|
||||||
|
title: Draft post-install metrics scaffold ActivityDefinition
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 161a264a-8f70-4e37-a854-bd5a76a0e54b
|
||||||
|
- id: T08
|
||||||
|
title: Draft low success_rate review ActivityDefinition
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 3b58ad38-839c-436a-8d97-ef5a8f9beefe
|
||||||
|
- id: T09
|
||||||
|
title: Document activity-core triggers in INTEGRATION_PATTERNS.md
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: a004b60f-4e8f-4881-b088-229ac9ab242f
|
||||||
|
- id: T10
|
||||||
|
title: Smoke test activity-core activation
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 84866bf1-5830-470d-87a5-9786222332c2
|
||||||
|
- id: T11
|
||||||
|
title: Define optimizer artifact package manifest
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 033a19db-fbd2-411f-9d2e-779d210400d4
|
||||||
|
- id: T12
|
||||||
|
title: Add kaizen-agentic metrics publish command
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 54517f2b-23e3-433b-a483-c59227625dbc
|
||||||
|
- id: T13
|
||||||
|
title: Map raw-evidence retention class in publish manifest
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 3b378789-a761-4472-b072-a346541be239
|
||||||
|
- id: T14
|
||||||
|
title: Integration test artifact-store publish
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: a3566713-db58-4519-b9c4-5003421c1f1e
|
||||||
|
- id: T15
|
||||||
|
title: Document publish workflow in agency-framework.md
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 5d8255aa-fd7a-4fe6-bce2-3a176f954c7f
|
||||||
|
- id: T16
|
||||||
|
title: Map KaizenAgentTemplate to info-tech-canon profile outline
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 852c9cbf-0b0c-4f23-8594-905ca280c268
|
||||||
|
- id: T17
|
||||||
|
title: Draft info-tech-canon agent brief for tdd-workflow
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 62e05097-9033-401d-bbe0-d5d773da50fe
|
||||||
|
- id: T18
|
||||||
|
title: Spike kontextual-engine wiki ingestion manifest
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: cd6962c7-aaed-4d7d-81de-37c0e3ed715e
|
||||||
|
- id: T19
|
||||||
|
title: Update ecosystem assessment with Part 4 outcomes
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 2c1f66f5-e6ab-4e19-88ca-818acb15a706
|
||||||
---
|
---
|
||||||
|
|
||||||
# KAIZEN-WP-0004 — Ecosystem Integration: Helix Forge, activity-core, and artifact-store
|
# KAIZEN-WP-0004 — Ecosystem Integration: Helix Forge, activity-core, and artifact-store
|
||||||
@@ -154,6 +231,21 @@ Estimated effort: 3–5 sessions after WP-0003 Part 3.
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Completion
|
||||||
|
|
||||||
|
**Shipped:** v1.1.0–v1.2.0 ecosystem integration layer.
|
||||||
|
|
||||||
|
| Part | Outcome |
|
||||||
|
|------|---------|
|
||||||
|
| 1 Helix | `HELIX_SESSION_UID` on `metrics record`, `metrics correlate`, bidirectional docs |
|
||||||
|
| 2 activity-core | Three ActivityDefinitions under `docs/integrations/activity-definitions/` |
|
||||||
|
| 3 artifact-store | `metrics publish` with `raw-evidence` retention manifest |
|
||||||
|
| 4 Canon/knowledge | Design docs for info-tech-canon and kontextual-engine (no runtime deps) |
|
||||||
|
|
||||||
|
All 19 tasks complete. Reciprocal Helix link verified in WP-0005 T16.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## State Hub Task IDs
|
## State Hub Task IDs
|
||||||
|
|
||||||
| Code | UUID |
|
| Code | UUID |
|
||||||
@@ -187,4 +279,4 @@ Estimated effort: 3–5 sessions after WP-0003 Part 3.
|
|||||||
- ADR-004 Helix Forge correlation section is the authoritative field mapping
|
- ADR-004 Helix Forge correlation section is the authoritative field mapping
|
||||||
- WP-0001 T04 (telemetry) should evaluate tele-mcp as adapter candidate
|
- WP-0001 T04 (telemetry) should evaluate tele-mcp as adapter candidate
|
||||||
- activity-core ActivityDefinitions live in activity-core repo per ACT-ADR-002/003;
|
- activity-core ActivityDefinitions live in activity-core repo per ACT-ADR-002/003;
|
||||||
kaizen-agentic commits reference copies or links under `docs/integrations/`
|
kaizen-agentic commits reference copies or links under `docs/integrations/`
|
||||||
|
|||||||
@@ -4,17 +4,82 @@ type: workplan
|
|||||||
title: "Adoption Polish and Fleet Parity (v1.2.0)"
|
title: "Adoption Polish and Fleet Parity (v1.2.0)"
|
||||||
domain: custodian
|
domain: custodian
|
||||||
repo: kaizen-agentic
|
repo: kaizen-agentic
|
||||||
status: active
|
status: completed
|
||||||
owner: kaizen-agentic
|
owner: kaizen-agentic
|
||||||
topic_slug: custodian
|
topic_slug: custodian
|
||||||
state_hub_workstream_id: 88c7b3e6-be98-480c-b47b-936e74a1a31b
|
state_hub_workstream_id: 88c7b3e6-be98-480c-b47b-936e74a1a31b
|
||||||
created: "2026-06-16"
|
created: "2026-06-16"
|
||||||
updated: "2026-06-16"
|
updated: "2026-06-17"
|
||||||
|
tasks:
|
||||||
|
- id: T01
|
||||||
|
title: Configure PACKAGE_USER and PACKAGE_TOKEN in Gitea
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 1fb6b04e-0854-4cc9-83c7-5abf85fe5bff
|
||||||
|
- id: T02
|
||||||
|
title: Smoke-test publish-python-package workflow
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: bdb9e463-bdfb-405c-afc4-e93a7d58a18b
|
||||||
|
- id: T03
|
||||||
|
title: Add pre-tag release checklist to PACKAGE_RELEASE.md
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 6a2132e7-8b3f-4960-a5e8-85bad81e8b13
|
||||||
|
- id: T04
|
||||||
|
title: Update HELLO_WORLD_TUTORIAL.md Gitea install paths
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 553cba3a-dafa-483a-9200-70ac3f5eb2d7
|
||||||
|
- id: T05
|
||||||
|
title: Update CLI_CHEAT_SHEET.md Gitea install paths
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 7e6663a5-fedf-4b1c-acd9-6df6b43d8a12
|
||||||
|
- id: T06
|
||||||
|
title: Update AGENT_DISTRIBUTION.md Gitea install paths
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: fe553788-357f-45c4-8400-f764f68c1cde
|
||||||
|
- id: T07
|
||||||
|
title: Update Makefile agents-* install fallback messages
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: b131ff67-fe21-4d95-904b-6a0b916c5502
|
||||||
|
- id: T08
|
||||||
|
title: Cross-link CONTRIBUTING.md with PACKAGE_RELEASE.md
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 07dd4d25-250c-455c-8363-49269d2ee59f
|
||||||
|
- id: T09
|
||||||
|
title: Add make agents-sync-package target
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 7437cedd-5f7e-4c4d-9142-4f67470c9e52
|
||||||
|
- id: T10
|
||||||
|
title: Add release-check parity test agents vs data/agents
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: ddbe2114-7a47-48fd-a145-b22dca2b581a
|
||||||
|
- id: T11
|
||||||
|
title: Refresh SCOPE.md agent-count notes
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 5417524f-03c0-40ed-a48b-a7906e6daf8f
|
||||||
|
- id: T12
|
||||||
|
title: Refresh TODO.md for v1.2.0
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 5cfad56c-2664-4b2d-b5f9-4792c958c9a2
|
||||||
|
- id: T13
|
||||||
|
title: Open CHANGELOG Unreleased for v1.2.0
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: fbca9be4-3d2b-4989-baaf-97e6926bdc66
|
||||||
|
- id: T14
|
||||||
|
title: Add flake8 to Gitea CI workflow
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: a6966cfa-ca59-4087-8989-2870dc69b13f
|
||||||
|
- id: T15
|
||||||
|
title: Document activity-core ActivityDefinition registration handoff
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: fbf3f1a8-4818-473e-ae0d-cd80118e5319
|
||||||
|
- id: T16
|
||||||
|
title: Verify bidirectional Helix correlation doc link
|
||||||
|
status: done
|
||||||
|
state_hub_task_id: 37679ce7-dcb6-42a4-820d-cf8b32c2a248
|
||||||
---
|
---
|
||||||
|
|
||||||
# KAIZEN-WP-0005 — Adoption Polish and Fleet Parity
|
# KAIZEN-WP-0005 — Adoption Polish and Fleet Parity
|
||||||
|
|
||||||
**Status:** active
|
**Status:** completed
|
||||||
**Owner:** kaizen-agentic
|
**Owner:** kaizen-agentic
|
||||||
**Repo:** kaizen-agentic
|
**Repo:** kaizen-agentic
|
||||||
**Target version:** 1.2.0
|
**Target version:** 1.2.0
|
||||||
@@ -37,8 +102,8 @@ Confirm tag-triggered publication works end-to-end before the v1.2.0 cut.
|
|||||||
|
|
||||||
### Tasks
|
### Tasks
|
||||||
|
|
||||||
- [x] T01 — Configure `PACKAGE_USER` and `PACKAGE_TOKEN` secrets in Gitea (Gitea rejects `GITEA_*` secret names)
|
- [x] T01 — Configure `PACKAGE_USER` (`tegwick`) and `PACKAGE_TOKEN` (OpenBao `inter-hub-pkg-rep` token) in Gitea
|
||||||
- [ ] T02 — Smoke-test `.gitea/workflows/publish-python-package.yml` via `workflow_dispatch`
|
- [x] T02 — Smoke-test `.gitea/workflows/publish-python-package.yml` via `workflow_dispatch` (auth OK; 409 on re-upload of 1.1.0)
|
||||||
- [x] T03 — Add pre-tag release checklist to `docs/PACKAGE_RELEASE.md` (secrets, `make package-check`, tag format)
|
- [x] T03 — Add pre-tag release checklist to `docs/PACKAGE_RELEASE.md` (secrets, `make package-check`, tag format)
|
||||||
|
|
||||||
### Definition of done
|
### Definition of done
|
||||||
@@ -108,7 +173,7 @@ Cross-repo follow-through from WP-0004; no foreign code in this repo.
|
|||||||
### Tasks
|
### Tasks
|
||||||
|
|
||||||
- [x] T15 — Document activity-core ActivityDefinition registration steps in `docs/INTEGRATION_PATTERNS.md` (handoff checklist for activity-core owners)
|
- [x] T15 — Document activity-core ActivityDefinition registration steps in `docs/INTEGRATION_PATTERNS.md` (handoff checklist for activity-core owners)
|
||||||
- [ ] T16 — Verify bidirectional Helix correlation doc link with agentic-resources (kaizen side documented; reciprocal link in agentic-resources still pending)
|
- [x] T16 — Verify bidirectional Helix correlation doc link with agentic-resources (reciprocal link added in `DESIGN-session-memory.md` §11)
|
||||||
|
|
||||||
### Definition of done
|
### Definition of done
|
||||||
|
|
||||||
@@ -154,6 +219,23 @@ Estimated effort: 2–4 sessions.
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Completion
|
||||||
|
|
||||||
|
**Shipped:** v1.2.0 on 2026-06-16
|
||||||
|
|
||||||
|
| Milestone | Detail |
|
||||||
|
|-----------|--------|
|
||||||
|
| Release commit | `297afed` — adoption polish and publish pipeline |
|
||||||
|
| Tag | `v1.2.0` pushed to Gitea |
|
||||||
|
| Publish | Gitea Actions run **3044** — `kaizen_agentic-1.2.0` wheel + sdist uploaded |
|
||||||
|
| Publish auth | `PACKAGE_USER=tegwick`, token from OpenBao `inter-hub-pkg-rep` |
|
||||||
|
| Helix handoff | Reciprocal link in `agentic-resources/docs/DESIGN-session-memory.md` §11 |
|
||||||
|
|
||||||
|
All 16 tasks complete. Deferred items (agent wizard, template validation, doc generation)
|
||||||
|
tracked for **WP-0006** (v1.3.0).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## State Hub Task IDs
|
## State Hub Task IDs
|
||||||
|
|
||||||
| Code | UUID |
|
| Code | UUID |
|
||||||
|
|||||||
368
workplans/kaizen-agentic-WP-0006-scheduled-agent-execution.md
Normal file
368
workplans/kaizen-agentic-WP-0006-scheduled-agent-execution.md
Normal file
@@ -0,0 +1,368 @@
|
|||||||
|
---
|
||||||
|
id: KAIZEN-WP-0006
|
||||||
|
type: workplan
|
||||||
|
title: "Scheduled Agent Execution via activity-core (v1.3.0)"
|
||||||
|
domain: custodian
|
||||||
|
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)
|
||||||
|
|
||||||
|
```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
|
||||||
|
|
||||||
|
- [x] T01 — Write ADR-005: scheduled agent execution (roster, schedule file, dispatch, boundaries)
|
||||||
|
- [x] T02 — Add `docs/integrations/schedule-schema.md` + example under `docs/examples/.kaizen/schedule.yml`
|
||||||
|
- [x] 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
|
||||||
|
|
||||||
|
- [x] T04 — Extend `docs/INTEGRATION_PATTERNS.md` Pattern 2 with roster + schedule model
|
||||||
|
- [x] T05 — Design doc: state-hub fields/filters for kaizen-scheduled repos (no state-hub code in this repo)
|
||||||
|
- [x] 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
|
||||||
|
|
||||||
|
- [x] T07 — Add `docs/integrations/activity-definitions/weekly-coach-orientation.md`
|
||||||
|
- [x] T08 — Open activity-core coordination issue/PR checklist (resolver + sync + `enabled: false` pilot)
|
||||||
|
- [x] 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
|
||||||
|
|
||||||
|
- [x] T09 — Implement `schedule` CLI command group skeleton
|
||||||
|
- [x] T10 — Wire `prepare` to memory + metrics + agent loader (reuse existing CLI internals)
|
||||||
|
- [x] T11 — Implement `schedule init` with sensible defaults (coach + optimization weekly, disabled tdd-workflow)
|
||||||
|
- [x] 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
|
||||||
|
|
||||||
|
- [x] T13 — Commit pilot `weekly-coach-orientation` definition; map to custodian pilot repos
|
||||||
|
- [x] T14 — Commit pilot `weekly-optimization-review` definition
|
||||||
|
- [x] T15 — Smoke test: dry-run activity-core → manual `schedule prepare` on two repos → verify task payload
|
||||||
|
- [x] T16 — Operator docs: credentials, PATH, Gitea index, enabling `enabled: true` in activity-core
|
||||||
|
- [x] 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**
|
||||||
Reference in New Issue
Block a user