jaymd96-pants-clawthor 0.1.3
Pants plugin for compiling Clawthor Claude Code plugins
License: MIT
Requires Python: >=3.9
Keywords: claude, clawthor, dsl, pants, plugin

# Pants Clawthor Plugin

Optional Pants backend that compiles Clawthor plugins as part of your build.

**Use this when**: You define plugins in `BUILD` files and want automatic compilation via Pants.

**Don't use if**: You just want to compile manually with `clawthor compile` (use the gem directly instead).

## Installation

### 1. Install clawthor gem

```bash
gem install clawthor
which clawthor    # Verify it's available
```

### 2. Add to pants.toml

```toml
[GLOBAL]
plugins = [
    "jaymd96-pants-clawthor==0.1.0",
]
```

### Requirements

- **Pants** 2.18+
- **Python** 3.9+
- **Ruby** 3.0+
- **clawthor gem** 0.3.0+

## Quick Start

### 1. Create a BUILD file

```python
# plugins/my_plugin/BUILD
claude_plugin(
    name="my_plugin",
    definition="definition.rb",
)
```

### 2. Create definition.rb

```ruby
# plugins/my_plugin/definition.rb
workspace :my_plugin do
  version "1.0.0"
  author "My Team"
end

skill :example do
  description "Example skill"
end

command :hello do
  description "Say hello"
  template { prompt "Say hello" }
end
```

### 3. Build

```bash
pants build //plugins/my_plugin:my_plugin
```

That's it! Generated plugin is in `plugins/my_plugin/output/`.

## Target Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `definition` | string | required | Path to `definition.rb` |
| `output_dir` | string | `output` | Where to generate files |
| `marketplace` | bool | `false` | Use marketplace layout? |

## Examples

### Basic plugin

```python
# plugins/docs/BUILD
claude_plugin(
    name="docs",
    definition="definition.rb",
)
```

### With modules

```python
# plugins/dev/BUILD
claude_plugin(
    name="dev",
    definition="definition.rb",
    output_dir="plugin",
)
```

```ruby
# plugins/dev/definition.rb
workspace :dev_tools do
  version "1.0.0"
end

require_relative './modules/planning'
use :planning
```

### Marketplace layout

```python
claude_plugin(
    name="release",
    definition="definition.rb",
    marketplace=True,
)
```

## Reusing Claudo modules

Copy Claudo modules into your project:

```bash
cp ../baseline/modules/planning.rb plugins/my_plugin/
```

Then use them:

```ruby
require_relative './modules/planning'

workspace :my_plugin do
  use :planning
end
```

## Troubleshooting

### "clawthor command not found"

1. Install: `gem install clawthor`
2. Verify: `which clawthor`
3. If using rbenv/rvm, check Ruby version: `ruby --version`

### Compilation fails

Check definition file manually:
```bash
cd plugins/my_plugin
clawthor compile definition.rb output/
```

### Path issues

Make sure `definition` is relative to the BUILD file:

```python
claude_plugin(
    name="my_plugin",
    definition="definition.rb",  # Same dir as BUILD
)
```

## Development

### Setup

```bash
cd pants-plugin
hatch env create
hatch run test
```

### Test your backend

```bash
hatch run test
```

### Format code

```bash
hatch run fmt
```

## How It Works

This backend:
1. Takes a `definition.rb` file
2. Runs `clawthor compile` automatically
3. Generates plugin files
4. Makes them available to Pants

That's all—it's a simple bridge between Pants and Clawthor.

## Related

- [Clawthor Gem](../clawthor/README.md) — The DSL compiler
- [Baseline Plugin](../baseline/README.md) — Reference & modules
- [Clawthor Monorepo](../README.md) — Overview
- [Pants Docs](https://www.pantsbuild.org/) — Build system

## License

MIT — See [../clawthor/LICENSE](../clawthor/LICENSE)