SuperClaude/.github/workflows/README.md

GitHub Actions Workflows

This directory contains CI/CD workflows for SuperClaude Framework.

Workflows

1. test.yml - Comprehensive Test Suite

Triggers: Push/PR to master or integration, manual dispatch Jobs:

• test: Run tests on Python 3.10, 3.11, 3.12
  • Install UV and dependencies
  • Run full test suite
  • Generate coverage report (Python 3.10 only)
  • Upload to Codecov
• lint: Run ruff linter and format checker
• plugin-check: Verify pytest plugin loads correctly
• doctor-check: Run superclaude doctor health check
• test-summary: Aggregate results from all jobs

Status Badge:

[![Tests](https://github.com/SuperClaude-Org/SuperClaude_Framework/actions/workflows/test.yml/badge.svg)](https://github.com/SuperClaude-Org/SuperClaude_Framework/actions/workflows/test.yml)

2. quick-check.yml - Fast PR Feedback

Triggers: Pull requests to master or integration Jobs:

• quick-test: Fast check on Python 3.10 only
  • Run unit tests only (faster)
  • Run linter
  • Check formatting
  • Verify plugin loads
  • 10 minute timeout

Purpose: Provide rapid feedback on PRs before running full test matrix.

3. publish-pypi.yml (Existing)

Triggers: Manual or release tags Purpose: Publish package to PyPI

4. readme-quality-check.yml (Existing)

Triggers: Push/PR affecting README files Purpose: Validate README quality and consistency

Local Testing

Before pushing, run these commands locally:

# Run full test suite
uv run pytest -v

# Run with coverage
uv run pytest --cov=superclaude --cov-report=term

# Run linter
uv run ruff check src/ tests/

# Check formatting
uv run ruff format --check src/ tests/

# Auto-fix formatting
uv run ruff format src/ tests/

# Verify plugin loads
uv run pytest --trace-config | grep superclaude

# Run doctor check
uv run superclaude doctor --verbose

CI/CD Pipeline

┌─────────────────────┐
│   Push/PR Created   │
└──────────┬──────────┘
           │
           ├─────────────────────────┐
           │                         │
    ┌──────▼──────┐         ┌───────▼────────┐
    │ Quick Check │         │  Full Test     │
    │  (PR only)  │         │   Matrix       │
    │             │         │                │
    │ • Unit tests│         │ • Python 3.10  │
    │ • Lint      │         │ • Python 3.11  │
    │ • Format    │         │ • Python 3.12  │
    │             │         │ • Coverage     │
    │ ~2-3 min    │         │ • Lint         │
    └─────────────┘         │ • Plugin check │
                            │ • Doctor check │
                            │                │
                            │ ~5-8 min       │
                            └────────────────┘

Coverage Reporting

Coverage reports are generated for Python 3.10 and uploaded to Codecov.

To view coverage locally:

uv run pytest --cov=superclaude --cov-report=html
open htmlcov/index.html

Troubleshooting

Workflow fails with "UV not found"

• UV is installed in each job via curl -LsSf https://astral.sh/uv/install.sh | sh
• If installation fails, check UV's status page

Tests fail locally but pass in CI (or vice versa)

• Check Python version: python --version
• Reinstall dependencies: uv pip install -e ".[dev]"
• Clear caches: rm -rf .pytest_cache .venv

Plugin not loading in CI

• Verify entry point in pyproject.toml: [project.entry-points.pytest11]
• Check plugin is installed: uv run pytest --trace-config

Coverage upload fails

• This is non-blocking (fail_ci_if_error: false)
• Check Codecov token in repository secrets

Maintenance

Adding a New Workflow

1. Create new .yml file in this directory
2. Follow existing structure (checkout, setup-python, install UV)
3. Add status badge to README.md if needed
4. Document in this file

Updating Python Versions

1. Edit matrix.python-version in test.yml
2. Update pyproject.toml classifiers
3. Test locally with new version first

Modifying Test Strategy

• quick-check.yml: For fast PR feedback (unit tests only)
• test.yml: For comprehensive validation (full matrix)

Best Practices

1. Keep workflows fast: Use caching, parallel jobs
2. Fail fast: Use -x flag in pytest for quick-check
3. Clear names: Job and step names should be descriptive
4. Version pinning: Pin action versions (@v4, @v5)
5. Matrix testing: Test on multiple Python versions
6. Non-blocking coverage: Don't fail on coverage upload errors
7. Manual triggers: Add workflow_dispatch for debugging

Resources

• GitHub Actions Documentation
• UV Documentation
• Pytest Documentation
• SuperClaude Testing Guide