Contributing to Smart Ralph

Contributing to Smart Ralph

*"I'm learnding!"* - You, after reading this guide

First off, thanks for wanting to contribute! This project welcomes contributors of all experience levels. Whether you're fixing a typo or adding a whole new agent, your help is appreciated.

Table of Contents

• Code of Conduct
• Ways to Contribute
• Development Setup
• Making Changes
• Pull Request Process
• Style Guide
• Getting Help

Code of Conduct

Be kind. Be respectful. Remember that behind every GitHub handle is a real person. We're all here to build something useful together.

Ways to Contribute

Not all contributions require code:

• Report bugs - Found something broken? Open an issue
• Suggest features - Have an idea? We want to hear it
• Improve docs - Typos, unclear explanations, missing examples
• Answer questions - Help others in issues and discussions
• Write code - Bug fixes, new features, refactoring

Good First Issues

Look for issues labeled `good first issue` or `help wanted`. These are specifically chosen for newer contributors.

Development Setup

Prerequisites

• Claude Code installed
• Git
• A project to test with

Local Development

# Clone the repo
git clone https://github.com/tzachbon/smart-ralph.git
cd smart-ralph

# Test the plugin locally
claude --plugin-dir ./plugins/ralph-specum

# Make changes, restart Claude Code to reload

Project Structure

smart-ralph/
├── plugins/
│   └── ralph-specum/
│       ├── .claude-plugin/
│       │   └── plugin.json      # Plugin manifest
│       ├── agents/              # Sub-agent definitions
│       ├── commands/            # Slash command implementations
│       ├── hooks/               # Stop watcher (logging only)
│       ├── templates/           # Spec file templates
│       └── schemas/             # JSON schemas for validation
└── README.md

Testing Changes

1. Make your changes
2. Restart Claude Code with --plugin-dir pointing to your local copy
3. Run through the workflow: /ralph-specum:start test-feature Some test goal
4. Verify each phase works as expected

Making Changes

Branch Naming

feature/description    # New features
fix/description        # Bug fixes
docs/description       # Documentation only
refactor/description   # Code refactoring

Commit Messages

Keep them short and descriptive:

Good:
- Add retry logic to spec-executor
- Fix state cleanup on cancel
- Update installation docs

Bad:
- Fixed stuff
- WIP
- asdfasdf

Pull Request Process

1. Fork the repo and create your branch from main
2. Make your changes
3. Test locally with Claude Code
4. Update documentation if needed
5. Submit PR with clear description of changes

PR Description Template

## What

Brief description