194 lines
8 KiB
Markdown
194 lines
8 KiB
Markdown
# Kaizen Agentic
|
|
|
|
AI **agency** framework: 20 specialized agents that arrive in your project informed, learn from experience, and improve over time.
|
|
|
|
kaizen-agentic provides two things: a library of agent instruction sets you deploy into projects, and an **agency framework** that gives those agents persistent memory and coordination. Agents accumulate project-scoped knowledge across sessions. A Coach meta-agent synthesises patterns across the entire fleet and briefs incoming agents on what to know first.
|
|
|
|
This project embraces the Japanese concept of "kaizen" (continuous improvement) applied to AI agent development. Every agent becomes part of an optimization loop where performance is measured, patterns are analyzed, and knowledge is carried forward.
|
|
|
|
## Quick Start
|
|
|
|
### Install the Package
|
|
|
|
**From Source (Development):**
|
|
```bash
|
|
git clone https://forgejo.coulomb.social/coulomb/kaizen-agentic.git
|
|
cd kaizen-agentic
|
|
make setup-complete
|
|
make agents-install-cli
|
|
source .venv/bin/activate # Required for each session
|
|
```
|
|
|
|
**Global Installation (Available from any directory):**
|
|
```bash
|
|
git clone https://forgejo.coulomb.social/coulomb/kaizen-agentic.git
|
|
cd kaizen-agentic
|
|
make setup-complete
|
|
python3 -m build && make install-global
|
|
# No virtual environment activation needed
|
|
```
|
|
|
|
**Local Package Testing:**
|
|
```bash
|
|
git clone https://forgejo.coulomb.social/coulomb/kaizen-agentic.git
|
|
cd kaizen-agentic
|
|
make setup-complete
|
|
python3 -m build && make install-local
|
|
source .venv/bin/activate # Required for each session
|
|
```
|
|
|
|
**From Forgejo PyPI (current release: v1.4.0):**
|
|
```bash
|
|
pip install kaizen-agentic \
|
|
--extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/
|
|
|
|
# or global CLI via pipx
|
|
pipx install kaizen-agentic \
|
|
--pip-args="--extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/"
|
|
```
|
|
|
|
See [docs/PACKAGE_RELEASE.md](docs/PACKAGE_RELEASE.md) for release and CI details.
|
|
|
|
### Your First Project (New Users)
|
|
**👋 New to Kaizen Agentic?** Follow our [Hello World Tutorial](docs/HELLO_WORLD_TUTORIAL.md) for a complete step-by-step guide.
|
|
|
|
### Create a Project (Experienced Users)
|
|
```bash
|
|
# Create a new project with AI agents
|
|
kaizen-agentic init my-project --template python-web
|
|
cd my-project
|
|
|
|
# Set up development environment
|
|
make setup-complete
|
|
|
|
# Start coding with agent assistance!
|
|
make help # See all available commands
|
|
```
|
|
|
|
### Add Agents to Existing Project
|
|
```bash
|
|
# Navigate to your project
|
|
cd your-existing-project
|
|
|
|
# Install relevant agents
|
|
kaizen-agentic install keepaTodofile keepaChangelog tdd-workflow
|
|
|
|
# Check what was installed
|
|
kaizen-agentic status
|
|
```
|
|
|
|
## Agency Framework
|
|
|
|
Agents deployed into a project can accumulate **project-scoped memory** — a structured file written at session close and read at session start. A **Coach** meta-agent reads across all agent memories and produces targeted orientation briefs for incoming agents.
|
|
|
|
```bash
|
|
# Scaffold memory for an agent
|
|
kaizen-agentic memory init sys-medic
|
|
|
|
# Brief an incoming agent using all existing project memories
|
|
kaizen-agentic memory brief tdd-workflow
|
|
|
|
# Review an agent's accumulated knowledge
|
|
kaizen-agentic memory show project-assistant
|
|
```
|
|
|
|
See [docs/agency-framework.md](docs/agency-framework.md) for the full model.
|
|
|
|
## Orientation
|
|
|
|
Read in this order for strategic context:
|
|
|
|
1. [INTENT.md](INTENT.md) — purpose, boundaries, design principles
|
|
2. [wiki/KaizenAgenticMission.md](wiki/KaizenAgenticMission.md) — product narrative
|
|
3. [wiki/AboutKaizenAgents.md](wiki/AboutKaizenAgents.md) — agent concepts and metrics pilot
|
|
4. [wiki/EcosystemIntegration.md](wiki/EcosystemIntegration.md) — ecosystem composition
|
|
5. [SCOPE.md](SCOPE.md) — repository boundaries and current state
|
|
6. [history/](history/) — persisted assessments and gap analyses
|
|
|
|
Released **v1.4.0** — see [CHANGELOG.md](CHANGELOG.md). Repository state and
|
|
completed delivery are summarized in [SCOPE.md](SCOPE.md) and
|
|
[WORK-RECORDS.md](WORK-RECORDS.md).
|
|
|
|
Feedback: `kaizen-agentic feedback` · [docs/FEEDBACK.md](docs/FEEDBACK.md)
|
|
|
|
## Features
|
|
|
|
- **20 Specialized Agents**: Planning, testing, code quality, infrastructure, release, and meta-agent craft
|
|
- **Agency Framework**: Project-scoped agent memory + Coach meta-agent for cross-agent synthesis
|
|
- **Metrics and Improvement Loop**: Session evidence, optimizer recommendations, and optional artifact publication
|
|
- **Roles and Engagements**: Versioned role packages, client-bound engagement records, lifecycle checklists, and custody controls
|
|
- **Scheduled Preparation**: Repo-local schedules and offline orientation bundles for activity-core/Glas execution
|
|
- **CLI Tool**: Agent, memory, metrics, protocol, engagement, and schedule commands (`kaizen-agentic`)
|
|
- **Project Templates**: Pre-configured setups for different project types
|
|
- **Runtime-neutral Contracts**: Instruction and preparation surfaces usable by governed coding-agent harnesses
|
|
- **Comprehensive Testing**: Full test coverage with multiple testing strategies
|
|
|
|
## Available Agents
|
|
|
|
### Project Management
|
|
- **keepaTodofile**: Manages TODO.md files following Keep a Todofile format
|
|
- **keepaChangelog**: Maintains CHANGELOG.md files following Keep a Changelog format
|
|
- **keepaContributingfile**: Creates and updates CONTRIBUTING.md files
|
|
- **project-assistant**: General project planning and coordination
|
|
- **priority-evaluation**: Evaluates and orders competing work
|
|
- **requirements-engineering**: Requirements analysis and documentation
|
|
- **scope-analyst**: Maintains explicit product and repository boundaries
|
|
- **releaseManager**: Coordinates release readiness and delivery
|
|
|
|
### Development Process
|
|
- **tdd-workflow**: Test-driven development workflow guidance
|
|
- **test-maintenance**: Test suite maintenance and optimization
|
|
- **testing-efficiency**: Improves test feedback speed and signal quality
|
|
|
|
### Code Quality
|
|
- **code-refactoring**: Code improvement and refactoring guidance
|
|
- **optimization**: Agent definition optimization and improvement
|
|
- **datamodel-optimization**: Data model design and optimization
|
|
- **tooling-optimization**: Improves effective use of repository tooling
|
|
|
|
### Infrastructure
|
|
- **setupRepository**: Repository initialization and standards compliance
|
|
- **claude-documentation**: Claude Code configuration and documentation
|
|
- **sys-medic**: Infrastructure health monitoring and diagnostics
|
|
|
|
### Meta
|
|
- **coach**: Coaching meta-agent — reads all project agent memories, synthesises cross-agent briefs, and orients incoming agents
|
|
- **wisdom-encouragement**: Encourages reflective, evidence-backed improvement
|
|
|
|
## Automated execution boundary
|
|
|
|
Kaizen Agentic defines agent craft, validates repo-local schedules, and prepares
|
|
offline execution bundles. In the current unattended path, **activity-core**
|
|
creates durable, claimable `ops_run` work. A Kaizen blueprint or agent instance
|
|
hands a versioned `harness_profile_ref` to **glas-harness**, which resolves the
|
|
concrete rein, model route, sandbox, tool policy, and limits and returns one
|
|
evidence envelope. State Hub supplies roster and coordination evidence.
|
|
|
|
Manual execution remains supported. Kaizen Agentic itself does not own cron,
|
|
the durable work queue, inference, credentials, or runtime authorization. See
|
|
[Integration Patterns](docs/INTEGRATION_PATTERNS.md) and
|
|
[ADR-005](docs/adr/ADR-005-scheduled-agent-execution.md).
|
|
|
|
[View complete agent list](docs/AGENT_DISTRIBUTION.md#agent-categories)
|
|
|
|
## Project Templates
|
|
|
|
```bash
|
|
# Available templates
|
|
kaizen-agentic templates
|
|
|
|
# python-basic: Basic Python project setup
|
|
# python-web: Web application development
|
|
# python-cli: Command-line tool development
|
|
# python-data: Data science and analysis
|
|
# comprehensive: All available agents
|
|
```
|
|
|
|
## Known Issues
|
|
|
|
### Click Library Workaround
|
|
|
|
The CLI currently implements a workaround for spurious error messages in the Click library. This affects the `install` command but is transparent to users. See [CLICK_WORKAROUND.md](CLICK_WORKAROUND.md) for technical details and removal timeline.
|
|
|
|
**User Impact**: None - the workaround provides clean CLI output
|
|
**Status**: Monitoring Click library updates for resolution
|