# Contributing to CmdForge Registry

Thank you for contributing to the CmdForge ecosystem!

## Publishing a Tool

### Prerequisites

1. Install CmdForge: `pip install cmdforge`
2. Create an account at the registry website
3. Generate an API token from your dashboard
4. Configure your token: `cmdforge config set-token YOUR_TOKEN`

### Tool Structure

Your tool directory should contain:

```
my-tool/
├── config.yaml    # Required: Tool definition
└── README.md      # Recommended: Documentation
```

### config.yaml Format

```yaml
name: my-tool
version: "1.0.0"
description: A brief description of what your tool does
category: text-processing  # See categories below
tags:
  - ai
  - productivity

arguments:
  - flag: --max-length
    variable: max_length
    default: "500"
    description: Maximum output length

steps:
  - type: prompt
    prompt: |
      Summarize the following text in {max_length} characters or less:

      {input}
    provider: claude
    output_var: response

output: "{response}"
```

### Categories

Choose one of these categories:

- `text-processing` - Text manipulation and analysis
- `code` - Code review, generation, analysis
- `data` - Data transformation and analysis
- `media` - Image, audio, video processing
- `productivity` - General productivity tools
- `writing` - Writing assistance and editing
- `translation` - Language translation
- `research` - Research and information gathering

### Publishing

```bash
cd my-tool/
cmdforge registry publish
```

Use `--dry-run` to validate without publishing:
```bash
cmdforge registry publish --dry-run
```

## Guidelines

### Do's

- Write clear, concise descriptions
- Include usage examples in your README
- Use semantic versioning (MAJOR.MINOR.PATCH)
- Test your tool before publishing
- Choose an appropriate category

### Don'ts

- Don't include secrets or API keys in prompts
- Don't publish tools that duplicate existing official tools
- Don't use misleading names or descriptions
- Don't publish empty or non-functional tools

## Versioning

Once a version is published, it cannot be modified. To make changes:

1. Update your tool locally
2. Bump the version in config.yaml
3. Run `cmdforge registry publish`

## Deprecation

To deprecate a tool version, add to your config.yaml:

```yaml
deprecated: true
deprecated_message: "Use v2.0.0 instead - security fix"
replacement: "username/toolname@2.0.0"
```

## Questions?

Open an issue on the [CmdForge repository](https://gitea.brrd.tech/rob/CmdForge/issues).