kaizen-agentic/docs/CLI_CHEAT_SHEET.md

Kaizen Agentic CLI Cheat Sheet

Quick reference for the kaizen-agentic command-line tool.

Installation

From Forgejo PyPI (see PACKAGE_RELEASE.md):

pip install kaizen-agentic \
  --extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/

Core Commands

Project Initialization

# 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

# 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)

# Scaffold a new schema-valid agent (agents/agent-<name>.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)

# 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:<native-id>"
kaizen-agentic metrics record tdd-workflow --success --time 120 --quality 0.9
kaizen-agentic metrics correlate claude:<native-id>   # 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=<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)

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

Forward-deployed engagements (WP-0009 / DEC-FDA-001)

# List / inspect pilot engagements under engagements/pilots/
kaizen-agentic engagement list
kaizen-agentic engagement show eng-coulomb-railiance01-ho-001
kaizen-agentic engagement validate eng-coulomb-railiance01-ho-001

# Checklists (ramp-up / ramp-down)
kaizen-agentic engagement checklist eng-coulomb-railiance01-ho-001
kaizen-agentic engagement checklist eng-… --mark RU-01=done

# Phase transitions (staffing → ramp_up → operating → ramp_down → closed)
kaizen-agentic engagement phase eng-… --to ramp_up
kaizen-agentic engagement phase eng-… --to operating --force   # override graph

# Session orientation bundle (agent + vault + protocols + access plan)
kaizen-agentic engagement prepare eng-coulomb-railiance01-ho-001
kaizen-agentic engagement prepare eng-… --format json

# Session close — vault log + metrics + Kai ledger + report (no secrets)
kaizen-agentic engagement close-session eng-coulomb-railiance01-ho-001 \
  --success --duty standard_review \
  --summary "daily health: watch-level disk, load OK" \
  --time 120 --quality 0.85
# Flags: --no-metrics --no-ledger --no-report --kai-amount N --access-class host_observe

# Staff a new pilot from a Role package
kaizen-agentic engagement staff \
  --id eng-example-001 --role host-operator \
  --client coulomb --target railiance01

# Kai quote, scrub before lesson export, handoff pack
kaizen-agentic engagement quote eng-coulomb-railiance01-ho-001
kaizen-agentic engagement scrub eng-…
kaizen-agentic engagement export-handoff eng-…

Does not invoke LLMs or touch production hosts. Spec: docs/forward-deployed-engagement-architecture.md.

Information

# 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

kaizen-agentic init my-web-app --template python-web
cd my-web-app
make setup-complete
make test

Adding Agents to Existing Project

cd existing-project
kaizen-agentic install todo-keeper changelog-keeper
kaizen-agentic status

Maintaining Agents

# Weekly maintenance
kaizen-agentic update
kaizen-agentic validate

# Check what's installed
kaizen-agentic status

Team Onboarding

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

# 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:

{
  "scripts": {
    "agents:status": "kaizen-agentic status",
    "agents:update": "kaizen-agentic update"
  }
}

Make targets (auto-added):

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

# 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

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:

kaizen-agentic init ml-project --template python-data
cd ml-project && make setup-complete

Add testing workflow to existing project:

kaizen-agentic install tdd-workflow testing-efficiency

Update all agents monthly:

kaizen-agentic update && kaizen-agentic validate

Check what agents a project uses:

kaizen-agentic status
cat CLAUDE.md  # Detailed info