Contributing to Claude Code Extended Framework

Thank you for your interest in contributing! This document provides guidelines for contributing to this project.

Code of Conduct
Getting Started
Development Workflow
SPARC Methodology
Code Style Guidelines
File Organization
Testing Requirements
Pull Request Process
Agent Coordination
Adding New Features

Code of Conduct

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

Getting Started

Prerequisites

Claude Code CLI installed
Git configured with your name and email
Bash shell environment (Linux, macOS, or WSL on Windows)
Basic understanding of shell scripting

Development Setup

Fork and clone the repository:

git fork https://github.com/kvnloo/evolve.git
git clone https://github.com/kvnloo/evolve.git
cd evolve

Create a feature branch:

git checkout -b feature/your-feature-name

Set up MCP servers (recommended):

claude mcp add claude-flow npx claude-flow@alpha mcp start
claude mcp add ruv-swarm npx ruv-swarm mcp start  # Optional

Review the project structure:

cat CLAUDE.md  # Main configuration
ls -la .claude/  # Configuration directory
cat docs/github-setup-plan.md  # Development roadmap

Development Workflow

SPARC Methodology

This project follows the SPARC methodology for systematic development:

Specification: Define requirements clearly
- Write PRD if adding major feature
- Create GitHub issue with detailed description
- Identify success criteria
Pseudocode: Design before implementation
- Outline algorithm/logic in comments
- Plan function signatures and data structures
- Review with maintainers if complex
Architecture: Document system design
- Update architecture diagrams if needed
- Document integration points
- Explain design decisions
Refinement: Test-Driven Development
- Write tests BEFORE implementation
- Ensure tests fail initially
- Implement until tests pass
- Refactor while keeping tests green
Completion: Validate integration
- Run full test suite
- Update documentation
- Verify no regressions

Feature Branch Workflow

# Always work on feature branches, never on main
git checkout -b feature/descriptive-name

# Make incremental commits
git add .
git commit -m "feat: add user authentication helper"

# Keep branch updated with main
git fetch origin
git rebase origin/main

# Push when ready
git push origin feature/descriptive-name

Code Style Guidelines

Shell Scripts

Follow these conventions for all .sh files:

#!/usr/bin/env bash
set -euo pipefail  # Exit on error, undefined vars, pipe failures

# Use descriptive variable names
readonly PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
readonly CONFIG_DIR="${PROJECT_ROOT}/.claude"

# Add comments for complex logic
# Validates that the repository is not the CCPM template
validate_repository() {
  local remote_url
  remote_url=$(git remote get-url origin 2>/dev/null || echo "")

  if [[ "$remote_url" == *"automazeio/ccpm"* ]]; then
    echo "❌ ERROR: Cannot sync with template repository" >&2
    return 1
  fi
}

# Use functions for reusability
main() {
  validate_repository || exit 1
  # Implementation...
}

main "$@"

Style Requirements:

Use #!/usr/bin/env bash shebang
Set strict mode: set -euo pipefail
Use readonly for constants
Quote all variables: "${variable}"
Use local for function variables
Add descriptive comments
Use meaningful function names
Return early on errors
Use >&2 for error messages

Configuration Files

For .md files in .claude/commands/:

---
name: command-name
description: Brief description of what this command does
category: category-name
---

# Command Implementation

Detailed documentation and implementation...

For rule files in .claude/rules/:

# Rule Title

Clear, actionable rules with examples.

## Section

✅ Correct examples
❌ Incorrect examples

File Organization

Critical Rule: NEVER save working files to the root folder

Use these directories:

.claude/
├── commands/        # Slash command definitions
├── rules/           # Coordination and operation rules
├── helpers/         # Reusable shell scripts
├── prds/            # Product requirement documents
├── context/         # Project context files
└── statusline/      # Status line configuration

docs/                # Documentation and analysis
scripts/             # Utility scripts
.github/             # GitHub workflows and templates

Path Standards

Follow .claude/rules/path-standards.md:

Use relative paths for project files: internal/auth/server.go
No absolute paths with usernames: ❌ /Users/username/project/...
Cross-project references: ../project-name/file.go

Testing Requirements

Shell Script Testing

# Run shellcheck on all scripts
shellcheck scripts/*.sh .claude/helpers/*.sh

# Test scripts in isolated environment
bash -n script.sh  # Syntax check
bash -x script.sh  # Debug mode

Integration Testing

Before submitting PR:

# Test slash command execution
# (requires Claude Code CLI)

# Test helper scripts
./scripts/checkpoint.sh
./scripts/migrate-agents.sh --dry-run

# Verify GitHub workflows syntax
# (use GitHub Actions workflow validator)

Pull Request Process

Before Submitting

Follow SPARC methodology (all 5 phases)
Tests written and passing
Shell scripts pass shellcheck
Documentation updated
Commit messages follow convention (see below)
No hardcoded paths or secrets
Files organized in correct directories

Commit Message Convention

<type>(<scope>): <subject>

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation only
style: Code style changes (formatting)
refactor: Code refactoring
test: Adding/updating tests
chore: Maintenance tasks

Examples:

git commit -m "feat(commands): add /sc:benchmark command for performance testing"
git commit -m "fix(helpers): resolve path resolution in checkpoint.sh"
git commit -m "docs(contributing): add shell script style guidelines"

PR Template Checklist

When you open a PR, complete the template checklist:

## SPARC Methodology Checklist
- [ ] Specification: Requirements clearly defined
- [ ] Pseudocode: Algorithm/logic designed before implementation
- [ ] Architecture: System design documented
- [ ] Refinement: TDD approach - tests written first
- [ ] Completion: Integration validated

## Code Quality
- [ ] Shell scripts pass shellcheck
- [ ] No new warnings introduced
- [ ] Files under 500 lines (per style guide)
- [ ] Code follows project style guide

## Security
- [ ] No hardcoded secrets or credentials
- [ ] No absolute paths with usernames
- [ ] Input validation implemented

Agent Coordination

Multi-Agent Development

If using git worktrees for parallel development:

Follow .claude/rules/agent-coordination.md:

Only modify files in your assigned work stream
Make atomic commits (single purpose)
Update progress files regularly
Never force push
Communicate through commit messages

Example workflow:

# Create worktree for epic
git worktree add ../epic-auth-system epic/auth-system

# Check work assignment
cat .claude/epics/epic-name/issue-123-analysis.md

# Update progress
echo "✅ Completed database schema" >> stream-A.md
git add stream-A.md
git commit -m "Progress: Stream A - schema complete"

Adding New Features

Adding a Slash Command

Create command file in .claude/commands/:

# .claude/commands/sc/my-command.md
---
name: my-command
description: Brief description
category: utilities
---

# Implementation
Your command logic here...

Document usage in README or docs/
Add tests if applicable
Submit PR with example usage

Adding a Helper Script

Create script in .claude/helpers/:

#!/usr/bin/env bash
set -euo pipefail

# .claude/helpers/my-helper.sh
# Description: What this helper does

main() {
  # Implementation
}

main "$@"

Make executable: chmod +x .claude/helpers/my-helper.sh
Run shellcheck: shellcheck .claude/helpers/my-helper.sh
Document in README or docs/
Add usage examples

Adding Documentation

Add files to docs/ directory:
- Guides: docs/guide-name.md
- Analysis: docs/analysis-name.md
- Reference: docs/reference-name.md
Link from README.md if appropriate
Use relative paths for links
Include table of contents for long docs

Modifying GitHub Workflows

Test syntax with GitHub Actions validator
Test in fork before submitting PR
Document any new environment variables needed
Explain workflow purpose in PR description

Questions?

General questions: Open a Discussion
Bug reports: Open an Issue
Feature requests: Open an Issue with [FEATURE] prefix
Security issues: See SECURITY.md

Recognition

Contributors are recognized in:

Git commit history
Release notes
Project documentation

Thank you for contributing to make this project better! 🎉

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Contributing to Claude Code Extended Framework

Table of Contents

Code of Conduct

Getting Started

Prerequisites

Development Setup

Development Workflow

SPARC Methodology

Feature Branch Workflow

Code Style Guidelines

Shell Scripts

Configuration Files

File Organization

Path Standards

Testing Requirements

Shell Script Testing

Integration Testing

Pull Request Process

Before Submitting

Commit Message Convention

PR Template Checklist

Agent Coordination

Multi-Agent Development

Adding New Features

Adding a Slash Command

Adding a Helper Script

Adding Documentation

Modifying GitHub Workflows

Questions?

Recognition

Uh oh!

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to Claude Code Extended Framework

Table of Contents

Code of Conduct

Getting Started

Prerequisites

Development Setup

Development Workflow

SPARC Methodology

Feature Branch Workflow

Code Style Guidelines

Shell Scripts

Configuration Files

File Organization

Path Standards

Testing Requirements

Shell Script Testing

Integration Testing

Pull Request Process

Before Submitting

Commit Message Convention

PR Template Checklist

Agent Coordination

Multi-Agent Development

Adding New Features

Adding a Slash Command

Adding a Helper Script

Adding Documentation

Modifying GitHub Workflows

Questions?

Recognition