273 lines
14 KiB
Markdown
273 lines
14 KiB
Markdown
# 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.
|