feat: scheduled agent execution via activity-core (WP-0006, v1.3.0)
Enable kaizen agents to run on a regular cadence against a preselected repo roster, orchestrated by activity-core and prepared by kaizen-agentic — without this repo owning cron, Temporal workers, or an LLM runtime. CLI + module: - src/kaizen_agentic/schedule.py — .kaizen/schedule.yml parse/validate/scaffold - `kaizen-agentic schedule` group: init, validate, list, prepare <agent> (prepare bundles agent prompt + memory + metrics + repo pointers, offline) - tests/test_schedule_cli.py — 15 tests Contract & design: - ADR-005 scheduled agent execution; schema doc + example manifest - discover_kaizen_scheduled_repos resolver spec, state-hub roster fields, kaizen.schedule.prepared event payload, activity-core handoff checklist - INTEGRATION_PATTERNS Pattern 2 extended with roster model ActivityDefinition drafts (enabled: false): - weekly-coach-orientation, weekly-optimization-review Docs: agency-framework, CLI cheat sheet, PACKAGE_RELEASE runner prereqs, EcosystemIntegration, CHANGELOG, TODO. Workplan closed (status: done). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -18,6 +18,13 @@ from .integrations.artifact_store import (
|
||||
from .integrations.helix import HelixCorrelationAdapter, enrich_helix_correlation
|
||||
from .metrics import MetricsStore, OptimizerStore, performance_summary_markdown
|
||||
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():
|
||||
@@ -1360,6 +1367,204 @@ def protocols_show(agent_name: str, slug: str):
|
||||
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:
|
||||
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
|
||||
Reference in New Issue
Block a user