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

```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.