============
Contributing
============

This guide covers how to contribute to the ``llm-workflow`` project.

Development Setup
-----------------

1. Clone the repository:

   .. code-block:: bash

      git clone https://github.com/yourusername/llm-workflow.git
      cd llm-workflow

2. Install documentation dependencies:

   .. code-block:: bash

      pip install sphinx sphinx-book-theme myst-parser

3. Build the documentation locally:

   .. code-block:: bash

      cd docs
      make html

   The built docs will be in ``docs/build/html/``.

Adding a New Skill
------------------

1. **Create the skill directory**

   .. code-block:: bash

      mkdir plugin/skills/my-new-skill

2. **Write SKILL.md**

   Create ``plugin/skills/my-new-skill/SKILL.md`` with:

   - YAML frontmatter (``name`` and ``description``)
   - Markdown instructions for the skill

   .. code-block:: markdown

      ---
      name: my-new-skill
      description: Brief description of what this skill does and when to use it.
      ---

      # My New Skill

      Instructions for using the skill...

   The plugin system auto-discovers skills from ``plugin/skills/``. No
   manifest update is needed — just create the directory and SKILL.md.

3. **Bump the version**

   Update the version in both ``plugin/.claude-plugin/plugin.json`` and
   ``plugin/.claude-plugin/marketplace.json``, then clear the plugin cache
   (see the memory notes or run ``bump2version``).

4. **Document the skill**

   Create ``docs/source/skills/my-new-skill.rst`` with:

   - Description
   - Triggers
   - Workflow
   - Output format
   - Examples

5. **Update the skills index**

   Add the new skill to ``docs/source/skills/index.rst``.

Versioning
----------

The project uses `bump2version <https://github.com/c4urself/bump2version>`_
for version management.

**Patch release** (bug fixes):

.. code-block:: bash

   bump2version patch

**Minor release** (new features):

.. code-block:: bash

   bump2version minor

**Major release** (breaking changes):

.. code-block:: bash

   bump2version major

**Pre-release versions**:

.. code-block:: bash

   bump2version release  # b0 -> rc0
   bump2version build    # rc0 -> rc1

Code Style
----------

- Follow the existing patterns in the codebase
- Keep SKILL.md files concise and focused
- Use clear, imperative language in skill instructions
- Include examples for complex workflows

Submitting Changes
------------------

1. Create a feature branch:

   .. code-block:: bash

      git checkout -b feature/my-new-skill

2. Make your changes and commit:

   .. code-block:: bash

      git add .
      git commit -m "Add my-new-skill for X workflow"

3. Push and create a pull request:

   .. code-block:: bash

      git push origin feature/my-new-skill