How to Report a Bug in Ruflo: A Complete Guide to GitHub Issues and Verification

To report a bug in Ruflo, open a GitHub Issue using the rollback-incident template, run the verify-appliance.sh script for diagnostics, and attach debug logs captured with the --debug flag.

When you need to report a bug in Ruflo, the open-source AI orchestration framework for multi-agent swarms, following the project's structured GitHub Issues workflow ensures maintainers can reproduce and resolve issues efficiently. This guide walks through the exact steps to submit a high-quality bug report using the repository's built-in validation tools and issue templates stored in ruvnet/ruflo.

Using the GitHub Issue Template

Every bug report starts with the Bug issue template located at .github/ISSUE_TEMPLATE/rollback-incident.md. This template enforces a consistent format that captures all critical diagnostic information required by maintainers.

When you open a new issue, the template prompts you to provide:

• A concise title and clear description of the problem
• Step-by-step reproduction instructions
• Expected behavior versus actual behavior
• Environment details including Node version, OS, and Ruflo version
• Relevant logs, screenshots, or error traces

The template automatically applies the bug label to your issue. If the defect blocks production work, manually add the high-priority or needs-triage labels to expedite review.

Running the Verification Script

Before submitting your report, execute the scripts/verify-appliance.sh script to validate your local environment and generate a baseline diagnostic report. According to the source code, this script performs sanity checks on CLI invocation, MCP server startup, and basic swarm task execution.

bash ./scripts/verify-appliance.sh

The script outputs a concise pass/fail report that you should paste directly into your GitHub issue. Running this verification helps distinguish between environmental configuration issues and actual code defects in the core engine.

Capturing Debug Logs and Reproduction Cases

The most actionable bug reports include a minimal reproducible test case and comprehensive debug logs. To capture detailed output during a failure, use the --debug flag with the Ruflo CLI entry point at bin/cli.js.

npx ruflo@latest swarm start \
  --objective "Buggy task" \
  --strategy development \
  --debug > bug-report.log 2>&1

Ruflo writes detailed logs to ~/.ruflo/logs or the logs/ directory under the project root. If the bug involves swarm coordination failures or agent claim handling—common issues in v3/src/coordination/application/SwarmCoordinator.ts—include excerpts from these logs. For MCP communication errors defined in v3/mcp/types.ts, include relevant RPC contract details in your report.

You can also reference the integration test suite in tests/rvf-integration.test.ts to see if your issue matches existing Vitest scenarios or to structure your reproduction case using established test patterns.

CI Pipeline and Issue Triage

Once submitted, maintainers triage your issue and attempt reproduction against the CI pipeline defined in .github/workflows/ci.yml. This workflow runs the full Vitest suite on every pull request, ensuring that verified bug fixes pass all integration tests before merging. The maintainers use the same CLI flags (--debug, --wizard) available in bin/cli.js to reproduce reported issues in a clean environment.

Summary

• Open GitHub Issues using the template at .github/ISSUE_TEMPLATE/rollback-incident.md to ensure consistent formatting and automatic bug labeling.
• Run scripts/verify-appliance.sh to generate environment diagnostics before submitting your report.
• Capture debug logs using npx ruflo@latest --debug and check ~/.ruflo/logs for detailed error traces.
• Include environment details (Node version, OS, Ruflo version) and minimal reproduction steps for the fastest resolution.
• Reference core source files like v3/src/coordination/application/SwarmCoordinator.ts when reporting swarm coordination issues or v3/mcp/types.ts for MCP-related bugs.

Frequently Asked Questions

Where does Ruflo store debug logs?

Ruflo writes debug logs to ~/.ruflo/logs by default, or to the logs/ folder under the project root when running from a local clone. You can also redirect debug output to a file using the --debug flag with the CLI: npx ruflo@latest --debug > bug-report.log 2>&1.

What does the verify-appliance.sh script check?

The script at scripts/verify-appliance.sh validates CLI invocation, MCP server startup, and basic swarm execution to ensure your local environment is functional. It prints a concise pass/fail report that helps distinguish between configuration errors and actual code defects in the core orchestration logic.

How should I label urgent bugs?

While the issue template automatically applies the bug label, you should manually add high-priority if the defect blocks production work or needs-triage if you are uncertain about the severity. These labels alert maintainers to time-sensitive issues that require immediate attention.

How do maintainers confirm that a bug is fixed?

The maintainers reproduce reported issues against the CI pipeline defined in .github/workflows/ci.yml, which runs the full Vitest test suite on every pull request. Once a fix is submitted, the integration tests in tests/rvf-integration.test.ts must pass before the fix is merged, ensuring the bug is resolved.

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