zCode-CLI-X/CONTRIBUTING.md

Contributing to zCode CLI X

Thank you for your interest in contributing to zCode CLI X! This document provides guidelines and instructions for contributing.

🌟 How to Contribute

Types of Contributions

We welcome many types of contributions:

• Bug Reports — Found a bug? Let us know!
• Feature Requests — Have an idea? Share it!
• Code Changes — Fix bugs, add features, improve performance
• Documentation — Improve README, add examples, fix typos
• Tests — Add test coverage for new features
• Community Support — Help others in issues and discussions

---

🚀 Quick Start for Contributors

1. Fork & Clone

# Fork the repo on GitHub, then clone:
git clone https://github.rommark.dev/admin/zCode-CLI-X.git
cd zCode-CLI-X

2. Install Dependencies

npm install

3. Run Smoke Tests

# Verify everything works
node test-ruflo-smoke.mjs

# Should show: 53/53 tests passing

4. Make Changes

Follow the guidelines below, then:

# Test your changes
npm test

# Commit with descriptive message
git commit -m "feat: add new feature"

5. Push & Create PR

git push origin main

# Create pull request on GitHub

---

📝 Development Guidelines

Code Style

• JavaScript — Use ES modules (import/export)
• Naming — camelCase for variables/functions, PascalCase for classes
• Comments — JSDoc for public APIs, inline comments for complex logic
• Error handling — Always handle errors, never ignore them

Commit Messages

Follow Conventional Commits:

feat: add new feature
fix: bug fix
docs: documentation changes
style: formatting, missing semicolons (no code change)
refactor: code refactoring
test: adding or updating tests
chore: maintenance tasks (not user-facing)

Examples:

feat: add multi-agent swarm support
fix: resolve memory backend eviction bug
docs: update installation instructions
refactor: simplify plugin loading logic
test: add smoke tests for hook system

Branch Naming

feat/new-feature
fix/bug-fix
docs/update-readme
refactor/code-improvement
test/add-tests

---

🏗️ Architecture Guidelines

Plugin System

When adding new plugins:

1. Define extension point in src/plugins/ExtensionPoints.js
2. Implement plugin extending BasePlugin in src/plugins/Plugin.js
3. Register in PluginManager — Add to extension point routing
4. Document — Add to CREDITS.md or docs

Example:

// src/plugins/MyPlugin.js
import { BasePlugin } from './Plugin.js';

export class MyPlugin extends BasePlugin {
  name = 'my-plugin';
  
  async initialize() {
    console.log('MyPlugin initialized');
  }
  
  async shutdown() {
    console.log('MyPlugin shut down');
  }
}

Hook System

When adding new hooks:

1. Define hook type in src/bot/hooks.js
2. Register hook with priority order
3. Document — Add to README.md

Example:

// src/bot/hooks.js
export const HOOK_TYPES = {
  TOOL_PRE: 'tool.pre',
  TOOL_POST: 'tool.post',
  AI_PRE: 'ai.pre',
  AI_POST: 'ai.post',
  // Add your custom hooks here
  MY_CUSTOM_HOOK: 'my.custom.hook'
};

Agent System

When adding new agent roles:

1. Add to agents/index.js — Define agent type
2. Update system prompt — Add agent description
3. Document — Add to README.md feature comparison table

Example:

// src/agents/index.js
export const AGENT_TYPES = {
  coder: {
    id: 'coder',
    name: 'Coder',
    description: 'Implementation, debugging, refactoring'
  },
  // Add your new agent here
  analyst: {
    id: 'analyst',
    name: 'Data Analyst',
    description: 'Data analysis, visualization, insights'
  }
};

---

🧪 Testing

Run Smoke Tests

node test-ruflo-smoke.mjs

Coverage:

• ✅ PluginSystem: 10 tests
• ✅ HookSystem: 4 tests
• ✅ AgentSystem: 9 tests
• ✅ SwarmCoordinator: 12 tests
• ✅ AgentOrchestrator: 4 tests
• ✅ MemoryBackend: 14 tests
• Total: 53 tests

Add New Tests

When adding new features, add tests:

// test-my-feature.mjs
import { test } from 'node:test';
import assert from 'node:assert';

test('my feature works', async () => {
  const result = await myFunction();
  assert.strictEqual(result, expected);
});

---

📚 Documentation

README.md

Update README when:

• Adding new features
• Changing configuration options
• Updating installation steps
• Adding new agents/tools

Architecture.md

Update ARCHITECTURE.md when:

• Changing system architecture
• Adding new components
• Modifying message flows

CREDITS.md

Update CREDITS.md when:

• Adding new dependencies
• Acknowledging new contributors
• Updating third-party licenses

---

🔒 Security Guidelines

Never Commit Secrets

DO:

# Use environment variables
ZAI_API_KEY=${ZAI_API_KEY}
TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}

DON'T:

# Hardcoded secrets in code
const API_KEY = 'abc123'; // NEVER DO THIS

Validate User Input

Always validate and sanitize user input:

// Validate Telegram user ID
if (!/^\d+$/.validate(userId)) {
  throw new Error('Invalid user ID');
}

Protect Sensitive Files

Never modify these files via self-evolve:

• SelfEvolveTool.js — The safety system itself
• stt.py — Voice recognition bridge
• .env — Environment variables
• package.json — Dependencies

---

🐛 Bug Reports

When reporting a bug:

1. Search existing issues — Make sure it's not already reported
2. Provide reproduction steps — How to trigger the bug
3. Include logs — journalctl --user -u zcode -f
4. Specify environment — Node version, OS, configuration
5. Expected vs actual behavior — What should happen vs what does

Example:

**Bug**: Bot crashes on voice message

**Steps to reproduce**:
1. Send voice message to bot
2. Bot crashes with error

**Expected**: Bot transcribes voice and responds
**Actual**: Bot crashes with "Vosk model not found"

**Environment**:
- Node.js: v20.10.0
- OS: Ubuntu 24.04
- Vosk model: ~/vosk-models/vosk-model-small-0.15

---

💡 Feature Requests

When requesting a feature:

1. Describe the use case — Why do you need this?
2. Provide examples — How would you use it?
3. Consider alternatives — What existing features could work?
4. Estimate impact — How many users would benefit?

Example:

**Feature**: Add support for custom AI models

**Use case**: I want to use my own fine-tuned model
**Example**: `/model use my-custom-model-v2`
**Alternatives**: Currently using Z.AI GLM-5.1
**Impact**: Would help users with specific model requirements

---

📄 Pull Request Process

Before Submitting

1. ✅ Run all tests — npm test should pass
2. ✅ Update documentation — README, ARCHITECTURE, CREDITS
3. ✅ Add tests for new features — Test coverage > 80%
4. ✅ Follow code style — Consistent formatting
5. ✅ Write descriptive commit messages — Conventional Commits

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Refactoring
- [ ] Test addition

## Testing
- [ ] Tests added/updated
- [ ] Smoke tests passing
- [ ] Manual testing done

## Checklist
- [ ] Code follows project style
- [ ] Documentation updated
- [ ] No breaking changes
- [ ] Self-review done

---

🎯 Code Review

Reviewers Will Check

• Functionality — Does it work as expected?
• Security — Any vulnerabilities?
• Performance — Any bottlenecks?
• Testing — Adequate test coverage?
• Documentation — Is it documented?
• Style — Follows project conventions?

Review Process

1. Automated checks (tests, linting)
2. Core team review (1-2 reviewers)
3. Address feedback
4. Merge to main

---

🌍 Community Guidelines

Be Respectful

• Treat everyone with respect
• Provide constructive feedback
• Accept constructive criticism
• Focus on ideas, not people

Be Helpful

• Help new contributors
• Share knowledge
• Answer questions
• Document well

Be Patient

• Code review takes time
• Feedback is for improvement
• Iteration is normal
• Quality over speed

---

📞 Getting Help

Channels

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Telegram: @zcode_bot (ask questions)

FAQ

Q: How do I set up the development environment?
A: Follow INSTALLATION.md

Q: What's the best way to start contributing?
A: Look for "good first issue" labels on GitHub

Q: How long does code review take?
A: Usually 1-3 days, depending on complexity

Q: Can I work on an existing issue?
A: Yes! Comment "I'm working on this" to claim it

---

📜 License

By contributing, you agree that your contributions will be licensed under the MIT License.

---

🙏 Thank You!

Thank you for contributing to zCode CLI X! Your contributions make this project better for everyone.

Questions? Open an issue or start a discussion!

---

Contributions welcome! 🚀
Let's build the ultimate agentic coding assistant together