checkmate-cli 0.4.1

# Claude Plugin

Checkmate includes a Claude Code plugin for AI-assisted testing.

## Overview

The plugin:
- Injects project context at session start
- Provides test spec creation guidance
- Enables seamless AI-driven API testing

## Installation

### 1. Locate Plugin

The plugin is at `claude-plugin/` in the Checkmate repository:

```
claude-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── init.md
│   └── test.md
└── skills/
    └── create-spec.md
```

### 2. Install Plugin

Copy or symlink to your Claude plugins directory:

```bash
# Option 1: Symlink
ln -s /path/to/checkmate/claude-plugin ~/.claude/plugins/checkmate

# Option 2: Copy
cp -r /path/to/checkmate/claude-plugin ~/.claude/plugins/checkmate
```

### 3. Verify Installation

Start a new Claude Code session in a Checkmate project. You should see context about available tests.

## Plugin Features

### SessionStart Hook

On session start, the plugin runs `cm prime` to inject:

```markdown
# Checkmate API Testing Context

**Project**: /path/to/project
**Base URL**: http://localhost:8080

## Test Specs (3):
- **User API Tests** (5 tests)
- **Order Tests** (3 tests)
- **Health Check** (1 test)

## Recent Runs:
✓ cm-run-a3f 2024-01-15 9/9 passed @ abc1234

## Quick Reference:
cm test run              # Run all tests
cm test run <name>       # Run specific spec
...
```

### PreCompact Hook

Context is re-injected before conversation compaction to preserve test awareness.

### Commands

The plugin provides command documentation:

- `/checkmate init` - Initialize project
- `/checkmate test` - Run tests

### Skills

- `create-spec` - Guide for creating test specifications

## plugin.json

```json
{
  "name": "checkmate",
  "description": "AI-native API testing framework",
  "version": "0.2.0",
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "cm prime 2>/dev/null || true"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "cm prime 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}
```

## cm prime Command

The `cm prime` command outputs project context:

```bash
cm prime
```

Output is markdown formatted for AI consumption:
- Project location
- Configuration
- Available test specs
- Recent run history
- Quick reference commands

If no `.checkmate/` is found, exits silently.

## Using with Claude

### Creating Tests

Ask Claude to create test specs:

> "Create a test spec for the /api/users endpoint that tests CRUD operations"

Claude will use the `create-spec` skill and project context.

### Running Tests

> "Run the user tests and explain any failures"

Claude will run `cm test run users -v` and analyze results.

### Debugging Failures

> "Why are the order tests failing?"

Claude will:
1. Run tests with verbose output
2. Check recent history
3. Analyze assertion failures

## Customization

### Add Project-Specific Commands

Create `.checkmate/claude/commands/`:

```markdown
---
description: Run tests with coverage
---

# Run with Coverage

\`\`\`bash
cm test run --coverage
\`\`\`
```

### Add Custom Skills

Create `.checkmate/claude/skills/`:

```markdown
---
description: Performance testing guide
---

# Performance Testing

Guide for performance-focused test specs...
```

## Troubleshooting

### Context Not Appearing

1. Verify plugin is installed
2. Check `cm prime` works: `cm prime`
3. Ensure `.checkmate/` exists in project

### Wrong Project Context

Claude uses current working directory. Ensure you're in the correct project.

### Plugin Not Loading

Check Claude plugin directory structure:
```
~/.claude/plugins/checkmate/
└── .claude-plugin/
    └── plugin.json
```

---

## See Also

- [Agent Guide](AGENT_GUIDE.md) - AI agent best practices
- [Quick Start](QUICKSTART.md) - Getting started