Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
200 lines (149 loc) · 5.61 KB

CONTRIBUTING.md

File metadata and controls

200 lines (149 loc) · 5.61 KB

Contributing to Spec Kit Partner

Thank you for your interest in contributing to the Spec Kit Partner plugin! This document provides guidelines and information about our development workflows.

Development Setup

  1. Clone the repository

    git clone https://github.com/jcmrs/claude-code-spec-kit-subagent-plugin.git
cd claude-code-spec-kit-subagent-plugin

  2. Install Python dependencies

    pip install flake8 pylint pytest

  3. Install Node.js tools (for Markdown linting)

    npm install -g markdownlint-cli

Automated Workflows

This repository uses GitHub Actions to automatically validate all contributions. The following workflows run on every push and pull request:

1. Python Linting (python-lint.yml)

Purpose: Ensures Python code in spec-kit-partner/src/ follows syntax and style guidelines.

Tools:

  • flake8 - Checks for syntax errors and undefined names (fails on errors)
  • pylint - Additional code quality checks (warnings only)

Run locally:

flake8 spec-kit-partner/src --count --select=E9,F63,F7,F82 --show-source --statistics
flake8 spec-kit-partner/src --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
pylint spec-kit-partner/src --exit-zero --max-line-length=127

2. JSON Manifest Validation (validate-manifests.yml)

Purpose: Validates that plugin manifests exist, are valid JSON, and contain all required fields.

Checks:

  • .claude-plugin/plugin.json exists and is valid JSON
  • .claude-plugin/marketplace.json exists and is valid JSON
  • Required fields are present in both files

Required fields in plugin.json:

  • name, version, description, author, license

Required fields in marketplace.json:

  • display_name, summary, description, categories, icon, publisher, license, version

Run locally:

python3 -m json.tool .claude-plugin/plugin.json > /dev/null
python3 -m json.tool .claude-plugin/marketplace.json > /dev/null

3. Asset Validation (validate-assets.yml)

Purpose: Ensures all assets referenced in manifests actually exist in the repository.

Checks:

  • Icon file exists (assets/icon.png)
  • README file exists (README.md)
  • Screenshot files exist (as listed in marketplace.json)

Run locally:

# Check if referenced assets exist
test -f assets/icon.png && echo "✓ Icon found"
test -f README.md && echo "✓ README found"
test -f assets/screenshot1.png && echo "✓ Screenshot 1 found"
test -f assets/screenshot2.png && echo "✓ Screenshot 2 found"

4. Markdown and Mermaid Linting (lint-markdown-mermaid.yml)

Purpose: Validates Markdown syntax and Mermaid diagram syntax (not content completeness).

Tools:

  • markdownlint-cli - Checks Markdown formatting (warnings only)
  • Python validator - Basic Mermaid syntax validation

Run locally:

# Lint Markdown
markdownlint '**/*.md' --ignore node_modules

# Validate Mermaid diagrams
find . -name "*.mermaid" -o -name "*.mmd"

5. Python Tests (python-tests.yml)

Purpose: Runs automated tests to verify Python code functionality.

Current tests:

  • Module import validation
  • Constants and class existence checks
  • Basic functionality tests

Run locally:

python tests/test_basic.py
pytest tests/ -v

Pull Request Process

  1. Fork and create a branch

    git checkout -b feature/your-feature-name

  2. Make your changes

    • Follow existing code style
    • Keep changes minimal and focused
    • Update documentation as needed

  3. Test locally

    # Run linting
flake8 spec-kit-partner/src

# Run tests
python tests/test_basic.py

# Validate JSON
python3 -m json.tool .claude-plugin/plugin.json > /dev/null

  4. Commit and push

    git add .
git commit -m "Description of your changes"
git push origin feature/your-feature-name

  5. Create Pull Request

    • All workflows must pass before merging
    • Request review from maintainers
    • Address any feedback

Code Style Guidelines

Python

  • Maximum line length: 127 characters
  • Use PEP 8 style guide
  • Add docstrings to functions and classes
  • Keep complexity reasonable (max-complexity=10)

Markdown

  • Use consistent heading levels
  • Include blank lines around code blocks and lists
  • Keep line length reasonable (no strict limit)

JSON

  • Use 2-space indentation
  • No trailing commas
  • No comments (JSON doesn't support them)

File Structure

claude-code-spec-kit-subagent-plugin/
├── .github/workflows/       # GitHub Actions workflows
├── .claude-plugin/          # Plugin manifests
├── agents/                  # Agent documentation
├── assets/                  # Images and static files
├── spec-kit-partner/
│   ├── src/                # Python source code
│   ├── project-data/       # Runtime data files
│   ├── diagrams/           # Mermaid diagrams
│   └── spec/              # Specification files
└── tests/                  # Test files

Adding New Workflows

If you need to add a new workflow:

  1. Create a new YAML file in .github/workflows/
  2. Follow the existing workflow structure
  3. Test locally before committing
  4. Document the workflow in this file

Questions?

License

By contributing, you agree that your contributions will be licensed under the MIT License.