# 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

```bash
# 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

```bash
npm install
```

### 3. Run Smoke Tests

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

# Should show: 53/53 tests passing
```

### 4. Make Changes

Follow the guidelines below, then:

```bash
# Test your changes
npm test

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

### 5. Push & Create PR

```bash
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](https://www.conventionalcommits.org/):

```bash
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**:
```bash
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

```bash
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**:
```javascript
// 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**:
```javascript
// 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**:
```javascript
// 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

```bash
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:

```javascript
// 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**:
```bash
# Use environment variables
ZAI_API_KEY=${ZAI_API_KEY}
TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
```

**DON'T**:
```bash
# Hardcoded secrets in code
const API_KEY = 'abc123'; // NEVER DO THIS
```

### Validate User Input

Always validate and sanitize user input:
```javascript
// 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

```markdown
## 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](https://github.rommark.dev/admin/zCode-CLI-X/issues)
- **Discussions**: [GitHub Discussions](https://github.rommark.dev/admin/zCode-CLI-X/discussions)
- **Telegram**: [@zcode_bot](https://t.me/zcode_bot) (ask questions)

### FAQ

**Q: How do I set up the development environment?**  
A: Follow [INSTALLATION.md](./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](./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!

---

<div align="center">

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

</div>