Assess scope intent and role automation readiness
This commit is contained in:
parent
9d996d7936
commit
d1dece7409
6 changed files with 584 additions and 87 deletions
244
SCOPE.md
244
SCOPE.md
|
|
@ -1,124 +1,190 @@
|
|||
# SCOPE
|
||||
|
||||
> This file helps you quickly understand what this repository is about,
|
||||
> when it is relevant, and when it is not.
|
||||
> It is intentionally lightweight and may be incomplete.
|
||||
> For strategic purpose and boundaries, see `INTENT.md`.
|
||||
> This file is the operational map of the repository. For stable purpose and
|
||||
> strategic boundaries, see `INTENT.md`.
|
||||
|
||||
---
|
||||
|
||||
## One-liner
|
||||
|
||||
KaizenAgentic: a digital talent agency framework — agent personas, project memory, measurable improvement loops, and CLI tooling for deploying continuously refining AI coding agents into Claude Code sessions.
|
||||
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 repo is the canonical home for the **KaizenAgentic** operating model (`INTENT.md`, `wiki/`). It packages recurring development workflows as named agent personas invoked in Claude Code. The **agency layer** adds project-scoped memory (`.kaizen/agents/<name>/memory.md`) and a **Coach** meta-agent for cross-agent orientation. The **kaizen loop** — measure, analyse, refine — is defined in `wiki/` and partially implemented: `OptimizationLoop` exists in Python, but per-execution metrics collection and optimizer integration are in progress (WP-0003). Runtime execution remains Claude Code's responsibility.
|
||||
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
|
||||
|
||||
- **Strategic framing**: `INTENT.md` (purpose, boundaries, design principles) and `wiki/` (mission, agent template, guidance model, brand/pricing)
|
||||
- **20 agent definitions** (`agents/agent-*.md`) — markdown persona instruction sets with YAML frontmatter (reference fleet; see `INTENT.md` boundaries)
|
||||
- **Agent categories**: project-management, development-process, code-quality, infrastructure, testing, documentation, meta
|
||||
- **Agency framework**: project memory convention (ADR-002), session-start/close protocols, Coach meta-agent (`agent-coach.md`)
|
||||
- **Protocol runbooks** (`agents/protocols/<agent>/<slug>.md`) — procedural checklists distinct from agent prompts
|
||||
- **CLI tooling** (`kaizen-agentic`): `init`, `install`, `update`, `remove`, `list`, `status`, `validate`, `templates`, `detect`, `migrate`, `extensions`, `memory` (show/init/brief/clear), `protocols` (list/show); `metrics` commands planned in WP-0003
|
||||
- **Project templates** (python-basic, python-web, python-cli, python-data, comprehensive) — agent bundles in registry code
|
||||
- **Python framework** (`src/kaizen_agentic/`): `Agent`/`AgentConfig`, `AgentRegistry`, `AgentInstaller`, `OptimizationLoop`/`PerformanceMetrics`, detection/migration/extensions
|
||||
- **Packaged agent data** (`src/kaizen_agentic/data/agents/`) — agents bundled for pip installs (sync with `agents/` via `make agents-sync-package`)
|
||||
- **Forgejo PyPI publication** — `make publish-forgejo`, tag-triggered `.forgejo/workflows/publish-python-package.yml` (v1.1.0+)
|
||||
- **Custodian MCP integration** (owned by `the-custodian`): `list_kaizen_agents()` and `get_kaizen_agent()`
|
||||
- **ADRs and workplans** for memory, protocols, workplan, and metrics conventions
|
||||
- **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
|
||||
|
||||
- Agent runtime / execution engine (agents are persona definitions; Claude Code executes them)
|
||||
- LLM orchestration, scheduling, or multi-agent debate systems
|
||||
- Project-specific implementation (agents guide work; they do not build the target software)
|
||||
- Custodian State Hub, MCP server code, or cross-domain governance (consumed, not owned)
|
||||
- Full KaizenGuidance codemod pipeline (vision in `wiki/KaizenGuidance.md`; not yet implemented)
|
||||
- Public pypi.org distribution (optional; the Forgejo registry is primary)
|
||||
- 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
|
||||
|
||||
- Understanding **why** KaizenAgentic exists and what it must not become (`INTENT.md`)
|
||||
- Exploring the conceptual model: agent template, optimizer, guidance, composable capabilities (`wiki/`)
|
||||
- Starting a guided development workflow (TDD, refactoring, testing, requirements, scope analysis)
|
||||
- Deploying agents with persistent cross-session memory or Coach-mediated orientation
|
||||
- Scaffolding projects with agent bundles; looking up personas via CLI or Custodian MCP
|
||||
- Contributing agent personas, protocol runbooks, or improvement-loop conventions
|
||||
- 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
|
||||
|
||||
- Ad-hoc scripting with no need for structured agent guidance
|
||||
- Non-Claude-Code development environments (primary target; patterns may transfer)
|
||||
- Need for runtime orchestration, task scheduling, or autonomous agent execution
|
||||
- Repository capability profiling or SCOPE.md generation at scale (see `repo-scoping`)
|
||||
- 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
|
||||
|
||||
- Status: stabilizing (v1.4.0 published on Forgejo PyPI; WP-0001–0009 completed)
|
||||
- Strategic layer: `INTENT.md` and `wiki/` established; ecosystem integration docs in `wiki/EcosystemIntegration.md`
|
||||
- Implementation: 20 agents, full CLI (`metrics`, `memory`, `feedback`), agency memory + ADR-004 metrics + optimizer wiring
|
||||
- Stability: CLI stable (Click workaround in place); Forgejo CI on main; publish workflow on `v*` tags
|
||||
- Usage: internal dev projects and Custodian MCP hub-wide; pip install via Forgejo extra index
|
||||
- Active work: none; **KAIZEN-WP-0010** completed the CoulombCore distribution cleanup
|
||||
- **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
|
||||
|
||||
- Upstream dependencies: Claude Code (agent invocation), kaizen continuous-improvement philosophy
|
||||
- Downstream consumers: Custodian State Hub (MCP agent discovery); domain repos that install agents and maintain `.kaizen/` state
|
||||
- Often used with: `the-custodian` (MCP integration), `markitect_project` (project-management patterns), `activity-core` (scaffolding references), `repo-scoping` (SCOPE.md generation)
|
||||
| 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
|
||||
|
||||
- Preferred terms: KaizenAgentic (product), agent, agent persona, agency, project memory, protocol runbook, Coach, kaizen loop
|
||||
- Also known as: "kaizen agents", "kaizen-agentic" (repo/package slug), "the agent library"
|
||||
- Potentially confusing terms: "Agent" is a persona/instruction set, not a running process; "agency" means memory + coaching, not autonomous orchestration; repo slug `kaizen-agentic` vs product name `KaizenAgentic`
|
||||
|
||||
---
|
||||
|
||||
## Related / Overlapping Repositories
|
||||
|
||||
- `the-custodian` — hosts MCP tools that load agents; integration code lives there, not here
|
||||
- `repo-scoping` — generates/refreshes SCOPE.md from approved characteristics
|
||||
- `markitect_project` — references kaizen-agentic as a capability submodule
|
||||
- `sys-medic` (source repo) — origin of sys-medic agent; canonical copy in `agents/agent-sys-medic.md`
|
||||
- **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 for full context:
|
||||
Read in this order:
|
||||
|
||||
1. `INTENT.md` — stable purpose, boundaries, design principles
|
||||
2. `wiki/KaizenAgenticMission.md` — product narrative and key components
|
||||
3. `wiki/EcosystemIntegration.md` — how KaizenAgentic composes with adjacent repos
|
||||
4. `wiki/KaizenAgentTemplate.md` — intended agent specification format
|
||||
5. `README.md` — quick start and agency overview
|
||||
6. `docs/agency-framework.md` — memory, coach, protocols, metrics (ADR-004)
|
||||
7. `history/` — persisted assessments and gap analyses
|
||||
8. `workplans/` — active implementation roadmap
|
||||
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: `wiki/` (conceptual model), `agents/` (personas), `agents/protocols/` (runbooks), `src/kaizen_agentic/` (Python framework), `docs/adr/` (conventions)
|
||||
|
||||
Entry points: `kaizen-agentic --help`; MCP: `get_kaizen_agent("scope-analyst")`; docs: `docs/GETTING_STARTED.md`, `docs/AGENT_DISTRIBUTION.md`
|
||||
Key directories: `agents/`, `agents/protocols/`, `roles/`, `engagements/`,
|
||||
`src/kaizen_agentic/`, `docs/adr/`, and `wiki/`.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -126,42 +192,54 @@ Entry points: `kaizen-agentic --help`; MCP: `get_kaizen_agent("scope-analyst")`;
|
|||
|
||||
```capability
|
||||
type: process
|
||||
title: Guided development agent personas
|
||||
description: Named markdown instruction sets for TDD, refactoring, documentation standards, requirements engineering, and project management workflows in Claude Code sessions.
|
||||
keywords: [agents, personas, tdd, refactoring, claude-code, workflows]
|
||||
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, and bundle agents into new or existing projects via the kaizen-agentic CLI and registry-backed templates.
|
||||
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-scoped agent memory and coaching
|
||||
description: Convention and CLI for .kaizen/agents memory files, session protocols, and Coach-mediated orientation briefs across a deployed agent fleet.
|
||||
keywords: [memory, coach, agency, kaizen, cross-session]
|
||||
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: infrastructure
|
||||
title: Kaizen agent discovery via Custodian MCP
|
||||
description: Single source of truth for agent definitions consumed by the Custodian State Hub list_kaizen_agents and get_kaizen_agent tools.
|
||||
keywords: [mcp, custodian, discovery, agent-library]
|
||||
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, rein-aharness, preparation, automation]
|
||||
```
|
||||
|
||||
```capability
|
||||
type: process
|
||||
title: KaizenAgentic conceptual model and agent specification standards
|
||||
description: Strategic framing, design principles, agent template, optimizer spec, and improvement philosophy via INTENT.md and wiki/.
|
||||
keywords: [kaizen, intent, template, optimization, digital-talent-agency]
|
||||
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/` (20 files) is the development source of truth; `src/kaizen_agentic/data/agents/` must stay in sync (enforced in WP-0005 T09–T10)
|
||||
- Agent definitions use minimal frontmatter today; full `wiki/KaizenAgentTemplate.md` conformance is a maturity target, not current reality
|
||||
- `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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue