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; a repo-owned instance binds a Kaizen blueprint to a versioned harness_profile_ref; glas-harness resolves the concrete execution constellation; and the selected rein 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, glas-harness, the selected reins, role-engine, agentic-resources, human-resources, fin-hub, resource-control, 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
• Setting organizational goals, granting leadership authority, allocating the agent workforce, or owning financial/resource budgets
• 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
• Translating leadership-owned goals and budget-constrained assignments into measurable blueprint, protocol, schedule, and evidence contracts
• Integrating Kaizen work with activity-core, glas-harness, a selected rein, 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, glas-harness, and the selected rein
• The need is organizational role definition only; use role-engine
• The need is agent inventory, assignment, capacity planning, portfolio review, or retirement; agentic-resources is the intended owner once its boundary is ratified and implemented
• The need is authoritative budget, burn, runway, resource capacity, or procurement evidence; use fin-hub and resource-control
• 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; glas-harness contract 1.0 resolves versioned execution profiles and is proven across two rein/model constellations; rein-local intake remains where already implemented
• 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: canonical goal/leadership/resource-envelope → role → assignment → agent-instance contracts and an end-to-end role-based pilot remain to be implemented

---

How It Fits

Concern	Owning system	KaizenAgentic relationship
Organizational goals and leadership mandates	Accountable organization/engagement control source (binky-control for Binky)	Consume goal, outcome, decision-right, and escalation references; never invent strategic authority
Organizational role definitions	role-engine	Consume stable role references and translate duties/evidence into blueprint inputs
Agent workforce inventory, assignment, capacity, and portfolio review	agentic-resources (recommended boundary; not yet implemented)	Provide blueprint/metric contracts and receive assignment/performance references
Human workforce planning and mixed-team boundaries	human-resources	Align compatible vocabulary without sharing human-sensitive records or treating people as compute
Agent blueprints and improvement	kaizen-agentic	Own
Repo-local agent instance	Consuming repository	Define through .kaizen/ contracts owned jointly with runtime extensions
Monetary budgets, commitments, burn, runway, and AI-plan booked cost	fin-hub	Consume provenance-bearing constraints; publish goal/assignment/duty attribution evidence
Resource demand, capacity, allocation, utilization, and technical economics	resource-control	Consume capacity/cost evidence; do not duplicate resource or procurement authority
Scheduling and claimable work	activity-core	Supply manifests, definitions, prepare commands, and event contracts
Governed execution abstraction	glas-harness	Supply versioned harness_profile_ref plus blueprint/orientation and organizational references; consume normalized evidence
Inner execution loop and backend policy	Glas-selected rein (rein-aharness, rein-openweights, …)	Remain rein-neutral; 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. Agentic-resources is the best-fit existing assignment/workforce owner, but its current implemented scope is session improvement and its root SCOPE is stale; that responsibility needs an explicit boundary decision 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 goal/context under a leadership mandate and resource envelope; agentic-resources is the recommended owner
• Leadership mandate: explicit delegation of goal decomposition, decision rights, review, and escalation; not implied by an agent or role name
• Resource envelope: provenance-bearing financial, token, time, capacity, and attention constraints delegated to an assignment
• 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, glas-harness, 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. Consumer-owned agent instances carry a versioned harness_profile_ref; Glas and the selected rein validate runtime policy separately.