# 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//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 ```capability 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] ``` ```capability 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] ``` ```capability 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] ``` ```capability 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] ``` ```capability 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] ``` ```capability 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.