How to Contribute to the Ruflo Project: A Complete Developer Guide

To contribute to the Ruflo project, fork the ruvnet/ruflo repository, configure the Node.js/TypeScript environment using ./scripts/install.sh, implement your changes following the architectural patterns in v3/src/, and submit a pull request that passes the automated CI verification pipeline.

Learning how to contribute to the Ruflo project opens the door to improving this open-source workflow orchestration platform built on TypeScript and Node.js. Whether you want to extend the core engine, build plugins, or improve documentation, the repository at ruvnet/ruflo provides a structured development environment with comprehensive testing and automated CI pipelines to ensure code quality.

Fork and Clone the Repository

The first step in contributing to Ruflo is creating your own copy of the codebase and setting it up locally.

Fork the Repository on GitHub

Navigate to the main repository at ruvnet/ruflo and click the Fork button in the top-right corner. This creates a copy under your GitHub account where you can freely experiment with changes.

Clone Your Fork Locally

Once forked, clone the repository to your local machine and enter the project directory:

git clone https://github.com/<your-username>/ruflo.git
cd ruflo

Set Up the Development Environment

Ruflo uses a standard Node.js and TypeScript stack. The project includes automated scripts to streamline environment configuration.

Install Dependencies

Run the installation script to set up the workspace, install Node packages, and link internal tools:

./scripts/install.sh

This script handles the initial setup, including workspace linking and dependency resolution across the monorepo structure.

Build the TypeScript Source

Compile the source code for both the v2 and v3 architectures:

npm run build

Alternatively, you can run the TypeScript compiler directly with npx tsc. The build process compiles source files located in v3/src/ and v2/.

Run the Test Suite

Execute all unit and integration tests to verify your environment:

npm test

Or use Vitest directly:

npx vitest

Tests are located in the tests/ directory and cover both the core engine and plugin functionality.

Lint and Format Code

Ensure your code follows the project's ESLint and Prettier configuration:

npm run lint

Choose Your Contribution Area

Ruflo is organized into several sub-projects. Select the area that aligns with your expertise and interests.

Core Engine (v3)

The core workflow engine resides in v3/src/. Contributions here include new task types, agent implementations, and workflow orchestration improvements. Study existing agent patterns and the async/await architecture before modifying core logic.

Plugins

Extend Ruflo's functionality by contributing to v3/plugins/. The repository includes examples like prime-radiant and agentic-qe that demonstrate plugin architecture. Plugins integrate with the core engine through well-defined interfaces.

CLI and MCP Tools

Improve the command-line interface located in v3/@claude-flow/cli/. This includes adding new commands, enhancing the transfer-store workflow, or improving the Model Context Protocol (MCP) integrations. The contribute command alias is implemented in v3/@claude-flow/cli/src/commands/transfer-store.ts.

Documentation and Tests

Contribute to v3/docs/ or v2/docs/ to improve architecture documentation, write tutorials, or update Architectural Decision Records (ADRs). Add test coverage in tests/ for new features or fix flaky existing tests.

Implement Your Changes

Follow the project's coding standards and workflow when developing your contribution.

Create a Feature Branch

Create a descriptive branch for your changes:

git checkout -b feature/<short-description>

Use clear, concise names that describe the feature or fix.

Follow Coding Standards

Write TypeScript code using strict typing, async/await patterns, and functional programming principles where appropriate. Reference similar implementations for guidance, such as v3/plugins/agentic-qe/src/tools/defect-intelligence/predict-defects.ts.

Use the memory and MCP abstractions when implementing persistence or inter-agent communication, as documented in v3/@claude-flow/memory/README.md.

Add Tests and Documentation

Place tests in tests/ following the naming convention of existing suites (e.g., rvf-integration.test.ts). Update documentation in the appropriate docs/ directory if your changes affect public APIs or CLI commands.

Run the full test suite before submitting:

npm test
npm run lint

Submit a Pull Request

Submit your changes through GitHub's pull request workflow.

Create the Pull Request

Push your branch to your fork:

git push origin feature/<short-description>

Open a pull request against ruvnet/ruflo:main. Fill out the PR template that appears automatically, describing the problem, your solution, and any required migrations.

If you added a plugin, reference the transfer-store command (ruflo transfer store publish) and note the plugin's purpose. Link to related ADRs in v3/implementation/adrs/v3-adrs.md if your changes affect architecture.

CI Pipeline Verification

The CI pipelines defined in .github/workflows/ run automatically on your PR:

• Verification pipeline (ci.yml): Runs lint, build, and tests.
• V3 CI (v3-ci.yml): Ensures compatibility with the latest Claude-Flow runtime.

Monitor the status checks and address any failures by pushing additional commits to your branch.

Publish Community Plugins

Ruflo supports a decentralized plugin registry. After your plugin is merged into the main repository, publish it to the community marketplace:

npx ruflo transfer store publish --plugin ./v3/plugins/<your-plugin>

This command, defined in v3/@claude-flow/cli/src/plugins/store/publish.ts, registers your plugin in the community marketplace (.claude-plugin/marketplace.json). For discovery mechanisms, refer to v3/@claude-flow/cli/src/plugins/store/discovery.ts.

Summary

• Fork and clone the ruvnet/ruflo repository to begin your contribution.
• Set up the environment using ./scripts/install.sh and verify with npm test and npm run lint.
• Choose your focus area: core engine (v3/src/), plugins (v3/plugins/), CLI tools (v3/@claude-flow/cli/), or documentation.
• Follow coding standards: TypeScript with strict typing, async/await patterns, and comprehensive test coverage in tests/.
• Submit via PR against main, ensuring CI pipelines (.github/workflows/ci.yml and v3-ci.yml) pass.
• Publish plugins using npx ruflo transfer store publish after merge.

Frequently Asked Questions

What programming languages and technologies does Ruflo use?

Ruflo is built primarily with TypeScript and Node.js. The project uses Vitest for testing, ESLint and Prettier for code quality, and follows strict async/await patterns throughout the codebase. The core engine resides in v3/src/ while plugins extend functionality in v3/plugins/.

How do I run tests before submitting a pull request?

Execute the full test suite using npm test or npx vitest from the repository root. This runs all unit and integration tests located in the tests/ directory. Additionally, run npm run lint to ensure your code follows the project's ESLint and Prettier configuration before creating your PR.

Where should I add new plugins to the Ruflo project?

Create new plugins in the v3/plugins/ directory, following the structure of existing examples like prime-radiant or agentic-qe. Each plugin should include its own src/ directory, tests, and documentation. After merging, publish your plugin using the CLI command npx ruflo transfer store publish --plugin ./v3/plugins/<your-plugin>.

What CI checks run when I submit a pull request?

Pull requests trigger two main workflows defined in .github/workflows/: the verification pipeline (ci.yml) which runs lint, build, and tests, and the V3 CI (v3-ci.yml) which ensures compatibility with the latest Claude-Flow runtime. All checks must pass before maintainers can merge your contribution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}