Contributing to ruflo / claude-flow — read this first

Pin this so new contributors see it.
Full guide: docs/AGENT_CONTRIBUTOR.md

The one rule

File an issue before opening a PR. Even 3 lines. We collaborate on the shape of the change before you sink a weekend into it.

issue → discussion → agreed approach → PR → review → merge
   ↑
   not optional

Exceptions: typo fixes, dep bumps, CVE security patches. Everything else — new feature, refactor, plugin, behavior change — starts with an issue.

If you open a PR cold, we'll politely ask you to file the missing issue first. Not punitive, structural: we can't reason about a change without the why.

Where contributions go

Reference plugins to model after: @claude-flow/plugin-agent-federation, @claude-flow/plugin-iot-cognitum, @claude-flow/aidefence.

Standards (the short list)

• ESM with explicit .js extensions in TypeScript imports (vitest tolerates bare, Node doesn't)
• No stubs. Real behavior or a loud throw new Error('not implemented') — never silent fake success
• Contrastive testing for detection code — paired positive + negative-control corpora, both with explicit assertions
• CI smoke for every new contract that crosses a process or package boundary (pattern: scripts/smoke-<name>.mjs, wired into .github/workflows/v3-ci.yml)
• Files under 500 lines. TypeScript strict mode. DDD layout for Tier 2/3.
• Cross-OS — macOS, Linux, Windows. Test path separators on Windows early.

Writing a good issue

Concrete repro, expected behavior, env (node version, OS, alpha vs stable), what you ruled out, optional proposed fix. The fastest-triaged issues look like #2024 and #2034. Use the templates under .github/ISSUE_TEMPLATE/.

Writing a good PR

## Summary
- 1-3 bullets

## Issue / motivation
Closes #NNNN.

## Approach
Design choice in 1 paragraph. Cite ADR if Tier 3.

## Test plan
- [x] Unit tests
- [x] CI smoke (when applicable)
- [x] Manual repro

## Risks / open questions
Anything you're unsure about.

Smaller is better. A PR that does 3 things is harder to review than 3 PRs that each do 1.

AI agent contributors

Same conventions apply. No agent-special exceptions. A few specifics:

• Memory-as-bus, not subagent-to-subagent SendMessage. See #2028 for why.
• Cite your trajectory. If a verdict from agentdb_pattern-search or hooks_explain drove the work, mention it.
• Don't fabricate. Uncertain? File an issue with what you've ruled out. Plausible-looking-but-wrong is worse than honest "I don't know yet."
• Validate before claiming done. Run the tests. Run the smoke. The codex review of @claude-flow/codex@3.0.0-alpha.9 caught a function returning success: true without doing the work. Don't be that function.

Where to ask

• Quick stuff → comment on your issue, ping @ruvnet
• Architecture → ADR draft in v3/docs/adr/
• Sensitive → ruv@ruv.net

Full guide with reference plugins, publishing procedure, lockstep rules, and contrastive testing pattern: docs/AGENT_CONTRIBUTOR.md.

Looking forward to your contribution.

— @ruvnet