kaizen-agentic/docs/CLI_CHEAT_SHEET.md

# Kaizen Agentic CLI Cheat Sheet

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

## Installation
```bash
pip install kaizen-agentic
```

## 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 agent installation
```

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

### 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
pip install kaizen-agentic
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
pip install kaizen-agentic

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