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 or OpenAI Codex (for testing skills)
• 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:

Claude Code:

# 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

OpenAI Codex:

# Link to Codex plugins directory, from WITHIN the cms-cultivator directory
mkdir -p ~/.codex/plugins
ln -s "$(pwd)" ~/.codex/plugins/cms-cultivator
# Then add ~/.agents/plugins/marketplace.json pointing to ~/.codex/plugins/cms-cultivator
# and restart Codex

Making Changes¶

Adding a New Skill¶

1. Create the skill directory and file¶

mkdir -p skills/my-new-skill
touch skills/my-new-skill/SKILL.md

2. Add frontmatter and content¶

---
name: my-new-skill
description: Automatically [action] when user [trigger phrase]. Invoke when user mentions "[term1]", "[term2]", or asks "[example question]".
---

Then write the skill content — workflow steps, examples, Drupal/WordPress-specific guidance.

3. Validate frontmatter¶

./scripts/validate-frontmatter.sh

4. Test the skill locally¶

Claude Code:

# Trigger via natural language
"[describe scenario that should activate the skill]"

# Or invoke explicitly
/my-new-skill

OpenAI Codex:

# Trigger via natural language — same as Claude Code
# Or invoke explicitly
@my-new-skill

5. Add to documentation¶

• Update docs/commands/overview.md with the new skill entry
• Update docs/agents-and-skills.md if the skill spawns agents

Updating Existing Skills¶

1. Modify the skill file in skills/skill-name/SKILL.md¶

2. Test thoroughly¶

• Trigger via natural language
• Try with both Drupal and WordPress projects
• Verify Kanopi tool integration if applicable

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¶

Skill Files (skills/<name>/SKILL.md)¶

• Use clear, descriptive headings
• Include code examples with proper syntax highlighting
• Provide both Drupal and WordPress examples where applicable
• Document trigger phrases 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¶

Skills (skills/*/SKILL.md): - name: Skill identifier in kebab-case (must match directory name) - description: When to invoke, trigger phrases, and use cases

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

Validating Frontmatter¶

Before committing changes to 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:

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(skills): add new skill 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! 🎉