# Kaizen Agentic CLI Cheat Sheet Quick reference for the `kaizen-agentic` command-line tool. ## Installation From Coulomb Gitea PyPI (see [PACKAGE_RELEASE.md](PACKAGE_RELEASE.md)): ```bash export GITEA_PACKAGE_USER= export GITEA_PACKAGE_TOKEN= pip install kaizen-agentic \ --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/" ``` ## Core Commands ### Project Initialization ```bash # New project with default template kaizen-agentic init my-project # New project with specific template kaizen-agentic init web-app --template python-web # New project with custom agents kaizen-agentic init cli-tool --agents todo-keeper,tdd-workflow,claude-documentation # Initialize in specific directory kaizen-agentic init my-project --parent-dir ~/projects ``` ### Agent Management ```bash # List available agents kaizen-agentic list kaizen-agentic list --category project-management kaizen-agentic list --verbose # Install agents kaizen-agentic install todo-keeper changelog-keeper kaizen-agentic install tdd-workflow --target ~/my-project kaizen-agentic install code-refactoring --no-backup --no-docs # Update agents kaizen-agentic update # Update all installed kaizen-agentic update todo-keeper # Update specific agents # Remove agents kaizen-agentic remove old-agent-name # Project status kaizen-agentic status # Show current project status kaizen-agentic validate # Validate agents (incl. frontmatter schema) ``` ### Authoring & Docs (WP-0007) ```bash # Scaffold a new schema-valid agent (agents/agent-.md) kaizen-agentic create-agent my-agent -c testing -d "What it does" kaizen-agentic create-agent my-agent # prompts for category + description kaizen-agentic create-agent my-agent --force # overwrite existing # Refresh the CLAUDE.md "Installed Agents" section from agent metadata kaizen-agentic docs generate # idempotent rewrite kaizen-agentic docs generate --check # CI gate: non-zero if out of date # validate enforces required name/description/category, valid category, # and valid memory/model values kaizen-agentic validate ``` After adding or editing agents, run `make agents-sync-package` so the packaged `data/agents/` copies stay in parity (release-check gate). ### Project Metrics (ADR-004) ```bash # Record outcome at session close kaizen-agentic metrics record tdd-workflow --success --time 120 --quality 0.9 kaizen-agentic metrics record tdd-workflow --failure --time 45 # Full JSON record from stdin echo '{"success": true, "quality_score": 1.0}' | kaizen-agentic metrics record tdd-workflow --json # Inspect metrics kaizen-agentic metrics show tdd-workflow kaizen-agentic metrics list kaizen-agentic metrics export tdd-workflow kaizen-agentic metrics optimize tdd-workflow # analyze one agent (≥10 records) kaizen-agentic metrics optimize # analyze all agents with metrics # Helix Forge correlation (fleet layer — agentic-resources) export HELIX_SESSION_UID="claude:" kaizen-agentic metrics record tdd-workflow --success --time 120 --quality 0.9 kaizen-agentic metrics correlate claude: # needs HELIX_STORE_DB # Publish optimizer evidence to artifact-store (optional) export ARTIFACTSTORE_API_URL=http://127.0.0.1:8000 export ARTIFACTSTORE_API_TOKEN= kaizen-agentic metrics publish # Scaffold memory + metrics together kaizen-agentic memory init tdd-workflow kaizen-agentic memory init tdd-workflow --no-metrics # memory only ``` Session-close template: `docs/templates/session-close-protocol.md` ### Scheduled Agent Execution (ADR-005) ```bash # Opt this repo into fleet scheduling kaizen-agentic schedule init # coach + optimization weekly kaizen-agentic schedule init --timezone UTC # override timezone kaizen-agentic schedule init --engagement coulomb-loop \ --agents coach,optimization --bootstrap-cadence hourly kaizen-agentic schedule validate # schema + agent-name checks kaizen-agentic schedule list # enabled entries (--all incl. disabled) # Prepare orientation for a scheduled run (offline; no State Hub needed) kaizen-agentic schedule prepare coach # markdown bundle kaizen-agentic schedule prepare optimization --format json ``` activity-core fires the schedule and creates a task per (repo, agent); the task runs `schedule prepare`. kaizen-agentic does not run cron or invoke Claude. ### Information ```bash # List templates kaizen-agentic templates # Show help kaizen-agentic --help kaizen-agentic install --help # Command-specific help # Version kaizen-agentic --version ``` ## Common Workflows ### Setting Up New Python Web Project ```bash kaizen-agentic init my-web-app --template python-web cd my-web-app make setup-complete make test ``` ### Adding Agents to Existing Project ```bash cd existing-project kaizen-agentic install todo-keeper changelog-keeper kaizen-agentic status ``` ### Maintaining Agents ```bash # Weekly maintenance kaizen-agentic update kaizen-agentic validate # Check what's installed kaizen-agentic status ``` ### Team Onboarding ```bash git clone team-repo cd team-repo # Install CLI — see Installation section above kaizen-agentic status # See what agents are used cat CLAUDE.md # Read agent documentation ``` ## Agent Categories | Category | Example Agents | Use Cases | |----------|----------------|-----------| | `project-management` | todo-keeper, changelog-keeper | Task tracking, documentation | | `development-process` | tdd-workflow, requirements-engineering | Development methodology | | `code-quality` | code-refactoring, datamodel-optimization | Code improvement | | `infrastructure` | setup-repository, testing-efficiency | Project setup, tooling | | `testing` | test-maintenance, tdd-workflow | Test management | | `documentation` | claude-documentation, contributing-keeper | Documentation management | ## Templates | Template | Agents Included | Best For | |----------|----------------|----------| | `python-basic` | setup-repository, todo-keeper, changelog-keeper | Simple Python projects | | `python-web` | Basic + tdd-workflow, code-refactoring, contributing-keeper | Web applications | | `python-cli` | Basic + testing-efficiency, claude-documentation | Command-line tools | | `python-data` | Basic + datamodel-optimization, requirements-engineering | Data science | | `comprehensive` | All available agents | Complex projects | ## Integration Commands ### Without Makefile ```bash # Direct CLI usage when Makefile targets aren't available kaizen-agentic status # Instead of: make agents-list kaizen-agentic update # Instead of: make agents-update kaizen-agentic validate # Instead of: make agents-validate ``` ### With Build Tools **npm/package.json:** ```json { "scripts": { "agents:status": "kaizen-agentic status", "agents:update": "kaizen-agentic update" } } ``` **Make targets (auto-added):** ```bash make agents-list # List installed agents make agents-update # Update agents make agents-validate # Validate agents make agents-status # Show detailed status ``` ## Troubleshooting ### Common Issues ```bash # Command not found — reinstall (see Installation section) # No agents directory kaizen-agentic install todo-keeper # Validation errors kaizen-agentic validate kaizen-agentic remove problematic-agent kaizen-agentic install problematic-agent ``` ### Getting Help ```bash kaizen-agentic --help # General help kaizen-agentic COMMAND --help # Command help kaizen-agentic status # Check current state kaizen-agentic validate # Validate setup ``` ## Quick Examples **Start a data science project:** ```bash kaizen-agentic init ml-project --template python-data cd ml-project && make setup-complete ``` **Add testing workflow to existing project:** ```bash kaizen-agentic install tdd-workflow testing-efficiency ``` **Update all agents monthly:** ```bash kaizen-agentic update && kaizen-agentic validate ``` **Check what agents a project uses:** ```bash kaizen-agentic status cat CLAUDE.md # Detailed info ```