# cl-preset

A Python package for managing Claude Code configuration presets and strategies.

## Overview

`cl-preset` allows you to package your Claude Code strategies and install them with different scopes (global, user, or project). This makes it easy to share and distribute custom configurations across projects and teams.

## Features

- **Package Management**: Create, install, and uninstall preset packages
- **Multiple Scopes**: Install presets globally, per-user, or per-project
- **CLI Interface**: Simple command-line interface for all operations
- **Rich Output**: Beautiful terminal output with formatted tables
- **Validation**: Built-in metadata validation for preset packages
- **Git Strategy Management**: Built-in git workflow strategies with validation

## Installation

```bash
pip install cl-preset
```

Or using uv:

```bash
uv pip install cl-preset
```

## Quick Start

### Interactive Mode (Recommended)

The easiest way to get started is the interactive mode:

```bash
cl-preset
```

This will launch an interactive selector that guides you through:
1. **Welcome Screen** - Beautiful introduction to cl-preset
2. **Strategy Selection** - Browse and select from available strategies (presets and git strategies)
3. **Scope Selection** - Choose installation scope (global, user, or project)
4. **Installation** - Automatic installation with progress feedback

Available strategies include:
- **web-development-strategy** - Preset for web development with FastAPI and React
- **dual-repo-git-strategy** - Dev/Release repository separation workflow
- **github-flow-git-strategy** - Simple branch-based workflow
- **git-flow-git-strategy** - Feature/release/hotfix branching model

### Create a New Preset

```bash
# Initialize a new preset scaffold
cl-preset init my-strategy

# This creates a directory structure:
# my-strategy/
#   ├── agents/       # Agent definitions
#   ├── skills/       # Skill definitions
#   ├── commands/     # Command definitions
#   └── examples/     # Usage examples
```

### Install a Preset

```bash
# Install from a local directory
cl-preset install ./my-strategy --name my-strategy --description "My custom strategy"

# Install with specific scope
cl-preset install ./my-strategy --name my-strategy --description "My custom strategy" --scope global
```

### List Installed Presets

```bash
# List all installed presets
cl-preset list

# List presets by scope
cl-preset list --scope user
cl-preset list --scope project
cl-preset list --scope global

# Output as JSON
cl-preset list --json
```

### Get Preset Information

```bash
cl-preset info my-strategy
```

### Uninstall a Preset

```bash
cl-preset uninstall my-strategy

# Uninstall from specific scope
cl-preset uninstall my-strategy --scope user
```

## Command Reference

### `init`

Initialize a new preset scaffold.

```bash
cl-preset init NAME [OPTIONS]
```

**Options:**
- `--output, -o`: Output path for preset metadata (default: ./preset.json)

### `install`

Install a preset from a source directory.

```bash
cl-preset install SOURCE_PATH [OPTIONS]
```

**Options:**
- `--name, -n`: Unique name for the preset (required)
- `--version, -v`: Version (default: 1.0.0)
- `--description, -d`: Description of the preset (required)
- `--author, -a`: Author name
- `--type, -t`: Type of preset (agent|skill|command|strategy)
- `--scope, -s`: Installation scope (global|user|project)

### `list`

List installed presets.

```bash
cl-preset list [OPTIONS]
```

**Options:**
- `--scope, -s`: Filter by scope
- `--json`: Output as JSON

### `info`

Show detailed information about an installed preset.

```bash
cl-preset info NAME
```

### `uninstall`

Uninstall a preset by name.

```bash
cl-preset uninstall NAME [OPTIONS]
```

**Options:**
- `--scope, -s`: Filter by scope

## Git Strategy Management

`cl-preset` includes built-in git workflow strategies that you can apply to your projects. These strategies define branching patterns, merge rules, and branch protection configurations.

### Available Strategies

#### dual-repo
Dev/Release repository separation workflow.
- **Dev repository**: Active development, feature branches, experimental work
- **Release repository**: Production-ready code, stable releases, published documentation
- **Promotion workflow**: Create release branch, review, merge to release repository

#### github-flow
Simple branch-based workflow.
- Feature branches from main
- Pull requests for review
- Direct merge to main after approval
- No release/develop branches

#### git-flow
Feature/release/hotfix branching model.
- **master**: Production-ready code
- **develop**: Integration branch for features
- **feature/**: Feature development branches
- **release/**: Release preparation branches
- **hotfix/**: Emergency fixes for production

### Git Commands

#### `git list`

List available git strategies.

```bash
cl-preset git list
cl-preset git list --no-builtin  # Only custom strategies
```

#### `git info`

Show detailed information about a git strategy.

```bash
cl-preset git info dual-repo
cl-preset git info github-flow
```

#### `git export`

Export a git strategy to a YAML file.

```bash
cl-preset git export dual-repo
cl-preset git export dual-repo -o ./my-strategy.yaml
```

#### `git apply`

Apply a git strategy to the current project.

```bash
# Apply a strategy
cl-preset git apply github-flow

# Dry run to see what would be configured
cl-preset git apply github-flow --dry-run
```

This creates a `.moai/config/sections/git-strategy.yaml` file with the strategy configuration.

#### `git validate`

Validate current git setup against a strategy.

```bash
cl-preset git validate github-flow
```

This checks:
- Current branch matches strategy expectations
- Required branches exist (main, develop, etc.)
- Required remotes are configured
- Repository state matches the strategy

### Creating Custom Strategies

You can create custom git strategies by exporting a built-in strategy and modifying it:

```bash
# Export a built-in strategy as a starting point
cl-preset git export github-flow -o ./my-custom-strategy.yaml

# Edit the YAML file to customize
# Then use it as a reference for your project
```

Strategy configuration format:

```yaml
name: my-custom-strategy
strategy_type: custom
description: "A custom git workflow"

main_branch: main
develop_branch: develop

branch_patterns:
  feature: "feature/*"
  bugfix: "bugfix/*"
  release: "release/*"
  hotfix: "hotfix/*"

merge_rules:
  require_pr: true
  require_approval: true
  allow_squash: true
  allow_merge_commit: false
  allow_rebase: false

protection_rules:
  main:
    enabled: true
    require_status_checks: true
    required_check_names: ["ci", "tests"]
    allow_force_pushes: false
    allow_deletions: false
```

### Git Strategy Integration with MoAI

When you apply a git strategy using `cl-preset git apply`, it:

1. Creates `.moai/config/sections/git-strategy.yaml`
2. Configures branch naming patterns
3. Sets up merge rule recommendations
4. Defines branch protection rules

This integrates with MoAI's git workflow commands and ensures consistent branching patterns across your team.

## Scopes

Presets can be installed at three different scopes:

| Scope | Path | Description |
|-------|------|-------------|
| `global` | `/usr/local/share/cl-preset/{name}` | Available to all users on the system |
| `user` | `~/.claude/presets/{name}` | Available only to the current user (default) |
| `project` | `.claude/presets/{name}` | Available only in the current project |

## Preset Structure

A valid preset directory contains:

```
my-preset/
├── agents/           # Agent definition files
├── skills/           # Skill definition files
├── commands/         # Command definition files
├── examples/         # Usage examples
└── preset.json       # Preset metadata (generated during install)
```

## Metadata

Each preset has metadata defined in `preset.json`:

```json
{
  "name": "my-preset",
  "version": "1.0.0",
  "description": "My custom Claude Code strategy",
  "author": "Your Name",
  "license": "MIT",
  "preset_type": "strategy",
  "tags": ["web", "api", "fastapi"]
}
```

## Development

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/yarang/cl-preset
cd cl-preset

# Install with dev dependencies
uv sync --dev
```

### Run Tests

```bash
uv run pytest
```

### Code Quality

```bash
# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Type check
uv run mypy src/
```

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## Author

William Jung - [@yarang](https://github.com/yarang)

## Links

- [GitHub Repository](https://github.com/yarang/cl-preset)
- [Issue Tracker](https://github.com/yarang/cl-preset/issues)
