Contributing

Contributing

How to contribute to Ruflo.

---

Development Setup

# Clone the repository
git clone https://github.com/ruvnet/ruflo.git
cd ruflo

# Install dependencies
npm install

# Start daemon
npx ruflo@latest daemon start

# Run tests
npm test

---

Code Style

• TypeScript — Strict mode, no any
• Formatting — Prettier (auto-run on commit)
• Linting — ESLint + TypeScript strict
• Testing — Jest (London school TDD preferred)

---

Git Workflow

1. Create a branch from main:

   git checkout -b feat/my-feature

2. Test your changes:

   npm test
   npm run build
   npx ruflo@latest doctor

3. Commit with message (no --no-verify):

   git commit -m "feat: add my feature"

   Commit message format:

   • feat: — New feature
   • fix: — Bug fix
   • refactor: — Code improvement
   • docs: — Documentation
   • test: — Test-related

4. Push and open PR against main:

   git push origin feat/my-feature

---

Three-Package Publishing

When publishing (maintainers only), ALL THREE packages must be updated together:

# STEP 1: Publish @claude-flow/cli
cd v3/@claude-flow/cli
npm version patch  # or minor/major
npm run build
npm publish

# STEP 2: Publish claude-flow (umbrella)
cd /Users/cohen/Projects/ruflo
npm version patch
npm publish

# STEP 3: Publish ruflo (CLI wrapper — CRITICAL)
cd ruflo
npm version patch
npm publish

All three packages must have the same version number and be published within the same CI run.

---

Test Baseline

Ruflo maintains a test baseline of 1,999 passing tests:

npm test -- --coverage

If you add features:

• Add tests (TDD first)
• Maintain or improve coverage (>80%)
• Don't skip tests (even flaky ones — fix them)

---

Hook Authorization

When committing via Git, you'll see hooks ask for permissions. Allow them:

• pre-commit — Format and lint check
• commit-msg — Message validation
• post-commit — Update ADR index if needed

Never use --no-verify to skip hooks.

---

Performance Benchmarks

Before claiming performance improvements, run the benchmark suite:

npx ruflo@latest performance benchmark --suite all

Document baseline and new metrics in your PR.

---

Documentation

When you add a feature:

1. Update README.md if it's user-facing
2. Update docs/USERGUIDE.md for CLI/MCP changes
3. Add ADR if it's an architectural decision (ADR-130+)
4. Update this wiki (see deployment below)

---

Common Tasks

Add a New CLI Command

1. Create v3/@claude-flow/cli/src/commands/my-command.ts
2. Export from v3/@claude-flow/cli/src/index.ts
3. Add tests in v3/@claude-flow/cli/src/__tests__/
4. Document in CLI-Reference wiki page

Add a New MCP Tool

1. Create v3/@claude-flow/cli/src/mcp-tools/my-tool.ts
2. Export from v3/@claude-flow/cli/src/mcp-tools/index.ts
3. Register in v3/@claude-flow/cli/src/mcp-server.ts
4. Add tests

Add a Plugin

1. Create plugins/ruflo-my-plugin/
2. Include plugin.json (metadata)
3. Implement commands, skills, agents
4. Publish to npm with ruflo- prefix
5. Submit PR to add to registry

---

Pull Request Checklist

Before submitting:

• Branch is up-to-date with main
• All tests pass: npm test
• Build succeeds: npm run build
• No new warnings: npx ruflo@latest doctor
• Commit messages are clear
• No --no-verify used
• Tests added for new code
• Documentation updated (if needed)
• No API key / secret commits

---

PR Merging (Maintainers)

Three-package lockstep:

1. Merge PR to main
2. Update all three package.json versions
3. Publish all three to npm in sequence
4. Tag release: git tag v<version>
5. Push tags: git push --tags
6. Create GitHub release with notes

---

ADR Process

For architectural decisions:

1. Create v3/docs/adr/ADR-XXX-my-decision.md
2. Use template: Title, Status, Context, Decision, Consequences
3. Link to related ADRs (supersedes, amends, depends-on)
4. Submit PR for discussion
5. Once accepted, run npx ruflo@latest adr index to update causal graph

---

Code Review

We look for:

• Correctness — Does it work?
• Testing — Is it tested?
• Performance — Is it fast?
• Security — Are inputs validated?
• Documentation — Is it clear?

---

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Maintainers: @ruvnet and team

---

Ruflo v3.10.1 · GitHub · Contributing Guidelines