kaizen-agentic/SCOPE.md

SCOPE

This file is the operational map of the repository. For stable purpose and strategic boundaries, see INTENT.md.

---

One-liner

KaizenAgentic is the blueprint and improvement-contract layer for versioned AI digital talents: agent definitions, project memory, protocols, measurement and optimization loops, Role/engagement reference packages, and preparation tools for human-led or governed automated execution.

---

Core Idea

This repository turns repeatable digital work into inspectable, versioned artifacts. An agent blueprint defines how a task is approached; project memory and protocols supply local continuity; metrics and feedback provide evidence; and optimization proposes the next safe refinement.

KaizenAgentic declares and prepares agent work. It does not own the clock, credentials, policy enforcement, or LLM session runtime. In the current ecosystem, activity-core decides when/what/where and emits claimable work; rein-aharness binds a repo-owned instance to a Kaizen blueprint and executes a bounded session. This separation is the implementation of the strategic boundary in INTENT.md, not an unfinished runtime hidden in this repository.

---

In Scope

• Operating model and product framing: mission, agent template, meta-optimizer, guidance model, business model, pricing, and brand language
• Reference blueprint catalog: 20 packaged agent definitions across project management, development process, code quality, testing, infrastructure, documentation, and meta-improvement
• Blueprint authoring and distribution: registry, validation, generated documentation, packaged-data parity, installation, migration, templates, and Forgejo PyPI publication
• Project continuity: .kaizen/agents/<name>/memory.md, Coach orientation, session-start/session-close conventions, and protocol runbooks
• Measurement and optimization: per-agent execution records, summaries, feedback, correlation, artifact publication, event emission, and optimizer recommendations
• Scheduling contract and preparation: .kaizen/schedule.yml, validation, listing, scaffolding, cadence promotion, activity-definition sync, and schedule prepare orientation bundles
• Agency and engagement conventions: loop engagements, supplier-owned Role packages, staffed-role lifecycle, bound agent definitions, ramp-up/down, client-custodied memory, engagement metrics, and reference pilot artifacts
• Interoperability contracts and reference patterns for activity-core, rein-aharness, role-engine, llm-connect, State Hub, artifact-store, Helix Forge, and Custodian discovery
• ADRs, workplans, tutorials, and integration handoffs that make these conventions human-readable and machine-consumable

---

Out of Scope

• Running LLM sessions or operating a multi-tenant agent runtime
• Owning cron/event schedules, durable work queues, task lifecycle, or workflow execution
• Holding credentials or granting authentication, authorization, decision rights, or tool permissions
• Live assignment of a person or agent to an organizational role
• Owning the complete organizational role catalog; role-engine is the current definition source, while this repository may consume roles and package execution-oriented reference Roles
• Customer-specific operational state as a default; client configurations, vaults, targets, and private memory belong with the client/consumer
• Every concrete agent implementation or vendor integration; this repository carries a reference fleet and portable integration patterns
• Generic AI automation unrelated to measurable continuous improvement
• A complete KaizenGuidance codemod platform; the guidance model remains a maturity target
• Public pypi.org distribution; the Forgejo package registry is primary

---

Relevant When

• Defining, reviewing, packaging, or installing an agent blueprint
• Adding project memory, Coach orientation, or reusable protocol runbooks
• Measuring an agent run and turning evidence into a versioned improvement
• Declaring a repo-local agent instance and preparing it for scheduled execution
• Designing a staffed digital Role engagement or mapping an organizational role to an executable agent blueprint
• Integrating Kaizen work with activity-core, rein-aharness, State Hub, Helix Forge, or artifact-store
• Understanding the KaizenAgentic product and agency operating model

---

Not Relevant When

• A task needs only ad-hoc automation with no reusable agent or improvement loop
• The need is purely schedule/runtime operation; use activity-core and the selected rein/harness
• The need is organizational role definition only; use role-engine
• The need is identity, credentials, or authorization; use the owning identity, OpenBao/credential-routing, and policy systems
• The need is repository capability profiling or SCOPE generation at scale; use repo-scoping

---

Current State

• Release: 1.4.0, distributed through the Forgejo PyPI registry
• Blueprints: 20 source and packaged definitions with parity validation
• CLI: installation, registry, validation, memory, protocols, metrics, feedback, agent authoring/docs, schedule, and engagement workflows
• Improvement loop: metrics storage, summary, optimization, correlation, publishing, and kaizen.metrics.recorded event emission are implemented
• Automation contract: schedule manifests and offline prepare bundles are implemented; activity-core has a durable ops_run queue and rein-aharness has a live claim loop plus a generic agent-session approach
• Agency model: one supplier Role package and one staffed host-operator pilot prove the file conventions; broader role-catalog integration is not yet standardized
• Repository health: Forgejo CI, release checks, agent validation, and metadata/workplan conventions are normalized through KAIZEN-WP-0011
• Open maturity gap: a canonical role-definition → assignment → agent-instance contract and an end-to-end role-based pilot remain to be implemented

---

How It Fits

Concern	Owning system	KaizenAgentic relationship
Organizational role definitions	role-engine	Consume stable role references and translate duties/evidence into blueprint inputs
Agent blueprints and improvement	kaizen-agentic	Own
Repo-local agent instance	Consuming repository	Define through .kaizen/ contracts owned jointly with runtime extensions
Scheduling and claimable work	activity-core	Supply manifests, definitions, prepare commands, and event contracts
Governed unattended execution	rein-aharness (selected rein)	Supply blueprint/orientation bundle; receive metrics and improvement evidence
Model/provider abstraction	llm-connect	Runtime dependency outside this repository
Credentials and authorization	OpenBao/credential routing, identity and policy systems	Reference named routes/profiles only; never hold grants or secrets
Durable coordination evidence	Custodian State Hub	Publish/index progress and workplan state; do not own hub code

The workspace currently has role-engine, not a component named role-manager. Role-engine explicitly excludes live assignment and execution. An assignment/binding contract therefore needs an explicit owner before roles can be automated at scale.

---

Terminology

• Blueprint / agent definition: versioned instructions for how an agent performs a kind of work; not a running process
• Role definition: organizational contract for outcomes, responsibilities, authority, interfaces, escalation, and evidence; not an identity or grant
• Role package: KaizenAgentic's execution-oriented reference product containing blueprint/protocol/ramp assets; currently not the canonical organization-wide role catalog
• Assignment / binding: a record that selects who or what fills a role in a specific context; ownership is not yet standardized
• Instance: consumer-owned declaration binding a blueprint to target, cadence, policy lane, tool profile, budget, memory, and metrics
• Engagement: a client-scoped lifecycle and custody boundary for staffed work
• Harness / rein: governed runtime that executes an instance; not owned here
• Agency: the memory, coaching, measurement, and engagement operating model; not unconstrained autonomous orchestration

---

Getting Oriented

Read in this order:

1. INTENT.md — stable purpose and strategic boundaries
2. docs/assessments/2026-08-20-intent-role-automation-readiness.md — current intent fit and role-automation path
3. README.md — install and daily CLI entry points
4. docs/agency-framework.md — memory, Coach, protocols, metrics, and schedules
5. docs/adr/ADR-005-scheduled-agent-execution.md — scheduling boundary
6. docs/adr/ADR-007-forward-deployed-engagement-convention.md — staffed Roles
7. docs/INTEGRATION_PATTERNS.md — ecosystem handoffs
8. workplans/ — implementation history and active work

Key directories: agents/, agents/protocols/, roles/, engagements/, src/kaizen_agentic/, docs/adr/, and wiki/.

---

Provided Capabilities

type: process
title: Versioned agent blueprints and protocols
description: Twenty packaged digital-talent definitions plus reusable runbooks for guided software and operational work.
keywords: [agents, blueprints, personas, protocols, digital-talent]

type: infrastructure
title: Agent deployment and project scaffolding CLI
description: Install, update, validate, author, document, and bundle agents in new or existing repositories.
keywords: [cli, install, templates, scaffolding, registry]

type: process
title: Project memory, coaching, and engagement lifecycle
description: Conventions and tooling for project-scoped memory, Coach orientation, staffed Role engagements, ramp-up/down, and client-custodied evidence.
keywords: [memory, coach, agency, engagement, roles]

type: data
title: Agent measurement and optimization evidence
description: Record, summarize, correlate, publish, and emit agent performance evidence for versioned improvement decisions.
keywords: [metrics, feedback, optimization, evidence, events]

type: integration
title: Scheduled-agent declaration and preparation
description: Validate repo-local schedules and assemble offline orientation bundles for activity-core-triggered, harness-executed runs.
keywords: [schedule, activity-core, rein-aharness, preparation, automation]

type: process
title: KaizenAgentic operating model and specification standards
description: Strategic framing, design principles, agent template, optimizer model, and product/agency conventions for continuously improving digital talents.
keywords: [kaizen, intent, template, optimization, operating-model]

---

Notes

• agents/ is the development source for the 20 reference definitions; src/kaizen_agentic/data/agents/ must remain synchronized with make agents-sync-package.
• Agent definitions still use less structure than the full wiki/KaizenAgentTemplate.md; schema conformance is a maturity gap.
• .kaizen/schedule.yml base fields are owned here. rein-aharness adds runtime policy extensions and validates them separately.