Contributing¶

Thank you for your interest in contributing to CMS Cultivator! This document provides guidelines for contributing to the project.

Getting Started¶

Prerequisites¶

• Git
• Python 3.x (for Zensical documentation)
• Claude Code CLI (for testing commands)
• Basic knowledge of Markdown

Setting Up Development Environment¶

1. Fork the repository on GitHub

2. Clone your fork:

   git clone https://github.com/YOUR-USERNAME/cms-cultivator.git
   cd cms-cultivator
   

3. Install Zensical (for documentation):

   pip install zensical
   

4. Test the plugin locally:

   # Link to Claude Code plugins directory, from WITHIN the cms-cultivator directory
   mkdir -p ~/.config/claude/plugins
   ln -s "$(pwd)" ~/.config/claude/plugins/
   claude plugins enable cms-cultivator
   

Making Changes¶

Adding a New Command¶

1. Create command file in /commands/¶

touch commands/my-new-command.md

2. Add frontmatter at the top¶

---
description: Brief description of what the command does
argument-hint: [optional-arg]
allowed-tools: Bash(git:*), Read, Glob, Grep, Write
---

3. Write command documentation¶

• Clear usage instructions
• Example outputs
• Drupal/WordPress-specific considerations
• Integration with Kanopi tools (if applicable)

4. Test the command¶

# In Claude Code
/my-new-command

5. Add to documentation¶

• Update docs/commands/overview.md
• Add detailed guide if needed

Updating Existing Commands¶

1. Modify command file in /commands/¶

2. Test thoroughly¶

• Try different arguments
• Test with both Drupal and WordPress projects
• Verify Kanopi tool integration

3. Update documentation if behavior changed¶

Improving Documentation¶

1. Edit files in /docs/¶

2. Preview locally¶

zensical serve
# Visit http://localhost:8000

3. Build to verify¶

zensical build --clean

Coding Standards¶

Command Files (.md)¶

• Use clear, descriptive headings
• Include code examples with proper syntax highlighting
• Provide both Drupal and WordPress examples where applicable
• Document all arguments and focus options
• Include expected output examples

Documentation¶

• Write in clear, concise language
• Use proper Markdown formatting
• Include code examples with syntax highlighting
• Add admonitions for warnings/tips:

  !!! warning
      Important warning text
  
  !!! tip
      Helpful tip text
  

Frontmatter¶

• description: Brief one-line description
• argument-hint: Show optional arguments in square brackets
• allowed-tools: List all tools the command can use

Validating Frontmatter¶

Before committing changes to commands, agents, or skills, validate that all frontmatter is properly formatted.

Run the validation script¶

./scripts/validate-frontmatter.sh

This script checks:

• Frontmatter presence - All files have valid YAML frontmatter
• Required fields - All mandatory fields exist for each file type
• YAML syntax - Frontmatter can be parsed without errors
• Non-empty values - All required fields have content
• Name consistency - Agent and skill names match directory names

Common frontmatter issues¶

Unquoted square brackets - Always quote argument-hint values containing brackets:

# ❌ Wrong
argument-hint: [operation] [args]

# ✅ Correct
argument-hint: "[operation] [args]"

Missing required fields - Each file type has required fields:

Commands (commands/*.md): - description - Brief one-line description - allowed-tools - Tools the command can use - argument-hint - Optional argument syntax (recommended)

Agents (agents/*/AGENT.md): - name - Agent name (must match directory) - description - When/how to invoke this agent - tools - Available tools

Skills (skills/*/SKILL.md): - name - Skill name (must match directory) - description - Trigger terms and use cases

Add validation to CI/CD¶

Consider adding the validation script to your pre-commit hook or CI/CD pipeline:

# .git/hooks/pre-commit
#!/bin/bash
./scripts/validate-frontmatter.sh || exit 1

Pull Request Process¶

1. Create a branch from main¶

git checkout -b feature/my-new-feature

2. Make your changes¶

• Follow coding standards
• Add/update documentation
• Test thoroughly

3. Commit your changes¶

git add .
git commit -m "feat: add new command for X"

Use Conventional Commits:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• refactor: - Code refactoring
• test: - Adding tests
• chore: - Maintenance

4. Push to your fork¶

git push origin feature/my-new-feature

5. Create Pull Request on GitHub¶

• Provide clear description
• Reference any issues
• Add screenshots if relevant

6. Address review feedback¶

• Make requested changes
• Push updates to same branch

Testing Guidelines¶

Manual Testing¶

1. Install plugin locally¶

claude plugins enable cms-cultivator

2. Test command variations¶

• Without arguments
• With different focus options
• In Drupal project
• In WordPress project

3. Verify Kanopi integration¶

• Test with ddev composer commands
• Verify ddev custom commands work

Documentation Testing¶

# Build docs locally
zensical build --clean

# Serve docs locally
zensical serve

Code of Conduct¶

Our Pledge¶

We are committed to providing a welcoming and inclusive environment for all contributors.

Expected Behavior¶

• Be respectful and considerate
• Provide constructive feedback
• Focus on what is best for the community
• Show empathy towards others

Unacceptable Behavior¶

• Harassment or discriminatory language
• Personal attacks
• Publishing others' private information
• Other unethical or unprofessional conduct

Getting Help¶

• GitHub Issues: Report bugs or request features
• GitHub Discussions: Ask questions or share ideas
• Documentation: Read the full docs

Recognition¶

Contributors will be recognized in: - CHANGELOG.md for significant contributions - GitHub contributors page - Project documentation (where applicable)

License¶

By contributing to CMS Cultivator, you agree that your contributions will be licensed under the GPL-2.0-or-later license.

Thank you for contributing to CMS Cultivator! 🎉