mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-05 01:50:27 +08:00

Files

catlog22 7e3d9007cd Remove remote installation script (install-remote.sh) due to deprecation and transition to new installation methods.

2026-01-04 12:04:13 +08:00

14 KiB

Raw Blame History

🤝 Contributing to Claude Code Workflow

Thank you for your interest in contributing to Claude Code Workflow (CCW)! This document provides guidelines and instructions for contributing to the project.

📜 Code of Conduct

Our Pledge

We are committed to providing a welcoming and inclusive environment for all contributors, regardless of:

Experience level
Background
Identity
Perspective

Our Standards

Positive behaviors:

Using welcoming and inclusive language
Being respectful of differing viewpoints
Gracefully accepting constructive criticism
Focusing on what is best for the community
Showing empathy towards other community members

Unacceptable behaviors:

Trolling, insulting/derogatory comments, and personal attacks
Public or private harassment
Publishing others' private information without permission
Other conduct which could reasonably be considered inappropriate

🚀 Getting Started

Prerequisites

Before contributing, ensure you have:

Claude Code - The latest version installed (Installation Guide)
Git - For version control
Text Editor - VS Code, Vim, or your preferred editor
Basic Knowledge:
- Bash scripting
- Markdown formatting
- JSON structure
- Git workflow

Understanding the Codebase

Start by reading:

README.md - Project overview
ARCHITECTURE.md - System architecture
GETTING_STARTED.md - Basic usage
COMMAND_SPEC.md - Command specifications

💻 Development Setup

1. Fork and Clone

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/Claude-Code-Workflow.git
cd Claude-Code-Workflow

2. Set Up Upstream Remote

git remote add upstream https://github.com/catlog22/Claude-Code-Workflow.git
git fetch upstream

3. Create Development Branch

# Update your main branch
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/your-feature-name

4. Install CCW for Testing

# Install dependencies
npm install

# Link your development version globally
npm link

# Verify installation
ccw --version

🛠️ How to Contribute

Types of Contributions

1. Bug Fixes

Report bugs via GitHub Issues
Include reproduction steps
Provide system information (OS, Claude Code version)
Submit PR with fix

2. New Features

Discuss in GitHub Discussions
Create feature proposal issue
Get community feedback
Implement after approval

3. Documentation

Fix typos or clarify existing docs
Add missing documentation
Improve examples
Translate to other languages

4. New Commands

Follow command template structure
Include comprehensive documentation
Add tests for command execution
Update COMMAND_REFERENCE.md

5. New Agents

Define agent role clearly
Specify tools required
Provide usage examples
Document in ARCHITECTURE.md

📏 Coding Standards

General Principles

Follow the project's core beliefs (from CLAUDE.md):

Pursue good taste - Eliminate edge cases for natural, elegant code
Embrace extreme simplicity - Avoid unnecessary complexity
Be pragmatic - Solve real-world problems
Data structures first - Focus on data design
Never break backward compatibility - Existing functionality is sacred
Incremental progress - Small changes that compile and pass tests
Learn from existing code - Study patterns before implementing
Clear intent over clever code - Be boring and obvious

Bash Script Standards

#!/usr/bin/env bash
# Command: /workflow:example
# Description: Brief description of what this command does

set -euo pipefail  # Exit on error, undefined vars, pipe failures

# Function definitions
function example_function() {
    local param1="$1"
    local param2="${2:-default}"

    # Implementation
}

# Main execution
function main() {
    # Validate inputs
    # Execute logic
    # Handle errors
}

# Run main if executed directly
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
    main "$@"
fi

JSON Standards

{
  "id": "IMPL-1",
  "title": "Task title",
  "status": "pending",
  "meta": {
    "type": "feature",
    "agent": "code-developer",
    "priority": "high"
  },
  "context": {
    "requirements": ["Requirement 1", "Requirement 2"],
    "focus_paths": ["src/module/"],
    "acceptance": ["Criterion 1", "Criterion 2"]
  }
}

Rules:

Use 2-space indentation
Always validate JSON syntax
Include all required fields
Use clear, descriptive values

Markdown Standards

# Main Title (H1) - One per document

## Section Title (H2)

### Subsection (H3)

- Use bullet points for lists
- Use `code blocks` for commands
- Use **bold** for emphasis
- Use *italics* for technical terms

```bash
# Code blocks with language specification
command --flag value

Use blockquotes for important notes


### File Organization

.claude/ ├── agents/ # Agent definitions │ ├── agent-name.md ├── commands/ # Slash commands │ └── workflow/ │ ├── workflow-plan.md ├── skills/ # Agent skills │ └── skill-name/ │ ├── SKILL.md └── workflows/ # Workflow docs ├── workflow-architecture.md


---

## 🧪 Testing Guidelines

### Manual Testing

Before submitting PR:

1. **Test the Happy Path**
   ```bash
   # Test basic functionality
   /your:new:command "basic input"

Test Error Handling

# Test with invalid input
/your:new:command ""
/your:new:command --invalid-flag

Test Edge Cases

# Test with special characters
/your:new:command "input with 'quotes'"

# Test with long input
/your:new:command "very long input string..."

Integration Testing

Test how your changes interact with existing commands:

# Example workflow test
/workflow:session:start "Test Feature"
/your:new:command "test input"
/workflow:status
/workflow:session:complete

Testing Checklist

Command executes without errors
Error messages are clear and helpful
Session state is preserved correctly
JSON files are created with correct structure
Memory system updates work correctly
Works on both Linux and Windows
Documentation is accurate

📚 Documentation Guidelines

Command Documentation

Every new command must include:

1. Inline Documentation (in command file)

#!/usr/bin/env bash
# Command: /workflow:example
# Description: One-line description
# Usage: /workflow:example [options] <arg>
#
# Options:
#   --option1    Description of option1
#   --option2    Description of option2
#
# Examples:
#   /workflow:example "basic usage"
#   /workflow:example --option1 value "advanced usage"

2. COMMAND_REFERENCE.md Entry

Add entry to the appropriate section:

| `/workflow:example` | Brief description of the command. |

3. COMMAND_SPEC.md Entry

Add detailed specification:

### `/workflow:example`

**Purpose**: Detailed description of what this command does and when to use it.

**Parameters**:
- `arg` (required): Description of argument
- `--option1` (optional): Description of option

**Workflow**:
1. Step 1
2. Step 2
3. Step 3

**Output**:
- Creates: Files created
- Updates: Files updated
- Returns: Return value

**Examples**:
```bash
/workflow:example "example input"

Related Commands:

/related:command1 - Description
/related:command2 - Description


### Agent Documentation

Every new agent must include:

```markdown
# Agent Name

## Role
Clear description of agent's responsibility and purpose.

## Specialization
What makes this agent unique and when to use it.

## Tools Available
- Tool 1: Usage
- Tool 2: Usage
- Tool 3: Usage

## Invocation
How the agent is typically invoked (manually or by workflow).

## Context Requirements
What context the agent needs to function effectively.

## Output
What the agent produces.

## Examples
Real usage examples.

## Prompt
The actual agent instructions...

📤 Submitting Changes

Commit Message Guidelines

Follow the Conventional Commits specification:

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

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Examples:

feat(workflow): add workflow:example command

Add new workflow command for example functionality.
Includes:
- Command implementation
- Documentation updates
- Test cases

Closes #123

fix(memory): resolve memory update race condition

Fix race condition when multiple agents update memory
simultaneously by adding file locking mechanism.

Fixes #456

docs(readme): update installation instructions

Clarify Windows installation steps and add troubleshooting
section for common issues.

Pull Request Process

Update your branch

git fetch upstream
git rebase upstream/main

Push to your fork

git push origin feature/your-feature-name

Create Pull Request
- Go to GitHub and create PR
- Fill out PR template
- Link related issues
- Add screenshots/examples if applicable

PR Title Format

feat: Add workflow:example command
fix: Resolve memory update issue
docs: Update contributing guide

PR Description Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Refactoring

## Related Issues
Closes #123

## Testing
- [ ] Tested on Linux
- [ ] Tested on Windows
- [ ] Added/updated documentation

## Screenshots (if applicable)

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No breaking changes (or documented)

Address Review Comments
- Respond to all comments
- Make requested changes
- Push updates to same branch
- Re-request review when ready

🎯 Development Workflow

Feature Development

# 1. Create branch
git checkout -b feat/new-command

# 2. Implement feature
# - Write code
# - Add documentation
# - Test thoroughly

# 3. Commit changes
git add .
git commit -m "feat(workflow): add new command"

# 4. Push and create PR
git push origin feat/new-command

Bug Fix

# 1. Create branch
git checkout -b fix/issue-123

# 2. Fix bug
# - Identify root cause
# - Implement fix
# - Add regression test

# 3. Commit fix
git commit -m "fix: resolve issue #123"

# 4. Push and create PR
git push origin fix/issue-123

🔄 Release Process

Version Numbering

CCW follows Semantic Versioning:

MAJOR: Breaking changes
MINOR: New features (backward compatible)
PATCH: Bug fixes (backward compatible)

Example: v5.8.1

5: Major version
8: Minor version
1: Patch version

Release Checklist

Maintainers will:

Update version in:
- README.md
- README_CN.md
- All documentation headers

Update CHANGELOG.md:

## [v5.9.0] - 2025-11-20

### Added
- New feature 1
- New feature 2

### Fixed
- Bug fix 1
- Bug fix 2

### Changed
- Change 1

Create release tag:

git tag -a v5.9.0 -m "Release v5.9.0"
git push origin v5.9.0

Create GitHub Release with:
- Release notes from CHANGELOG.md
- Installation scripts
- Migration guide (if breaking changes)

💡 Tips for Contributors

Best Practices

Start Small
- Fix documentation typos
- Add examples
- Improve error messages
- Then move to larger features
Ask Questions
- Use GitHub Discussions for questions
- Ask before starting major work
- Clarify requirements early
Follow Existing Patterns
- Study similar commands before creating new ones
- Maintain consistency with existing code
- Reuse existing utilities
Test Thoroughly
- Test on both Linux and Windows if possible
- Test with different input types
- Test integration with existing workflows
Document Everything
- Clear commit messages
- Comprehensive PR descriptions
- Updated documentation
- Code comments where necessary

Common Pitfalls to Avoid

❌ Don't:

Break backward compatibility without discussion
Add features without documentation
Submit large PRs without prior discussion
Ignore failing tests
Copy code without attribution

✅ Do:

Keep PRs focused and small
Update documentation with code changes
Add tests for new features
Follow project coding standards
Be responsive to review comments

📞 Getting Help

Resources

Documentation: Read all docs in repository
Discussions: GitHub Discussions
Issues: GitHub Issues
Command Guide: Use CCW-help within Claude Code

Contact

Bug Reports: GitHub Issues
Feature Requests: GitHub Discussions
Questions: GitHub Discussions
Security Issues: Create private security advisory

🙏 Recognition

Contributors will be:

Listed in CHANGELOG.md for their contributions
Mentioned in release notes
Credited in commit history
Appreciated by the community!

📄 License

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

Thank you for contributing to Claude Code Workflow! 🎉

Your contributions help make AI-assisted development better for everyone.

Last Updated: 2025-11-20 Version: 5.8.1

14 KiB Raw Blame History