Contributing

Contributing

Guide for contributing to the Agentwise project and helping improve multi-agent orchestration.

Overview

We welcome contributions to Agentwise! Whether you're fixing bugs, adding features, improving documentation, or creating new agents, your contributions help make Agentwise better for everyone.

Getting Started

Prerequisites

Before contributing, ensure you have:

• Node.js 18+ and npm 9+
• Git 2.30+
• Docker (for agent development)
• Claude Code CLI installed
• Basic understanding of multi-agent systems

Development Environment Setup

# Clone the repository
git clone https://github.com/VibeCodingWithPhil/agentwise.git
cd agentwise

# Install dependencies
npm install

# Set up development environment
cp .env.example .env.development
npm run dev:setup

# Start development server
npm run dev

# Verify installation
npm run test
npm run agent:test

Project Structure

agentwise/
├── src/
│   ├── orchestrator/          # Core orchestration engine
│   ├── agents/               # Built-in agent implementations
│   ├── api/                  # REST API and WebSocket servers
│   ├── cli/                  # Command-line interface
│   ├── config/               # Configuration management
│   ├── utils/                # Shared utilities
│   └── types/                # TypeScript type definitions
├── agents/                   # Agent definitions and templates
├── templates/                # Project templates
├── docs/                     # Documentation
├── tests/                    # Test suites
├── scripts/                  # Build and deployment scripts
└── examples/                 # Example projects and usage

Types of Contributions

1. Bug Reports

Help us identify and fix issues:

Before Reporting

• Search existing issues to avoid duplicates
• Test with the latest version
• Gather relevant system information

Bug Report Template

**Bug Description**
A clear description of the bug.

**Steps to Reproduce**
1. Run command `agentwise create web-app`
2. Select React + TypeScript
3. Execute build process
4. Error occurs during compilation

**Expected Behavior**
Project should build successfully.

**Actual Behavior**
Build fails with TypeScript compilation errors.

**Environment**
- Agentwise version: 1.0.0
- Node.js version: 18.17.0
- Operating System: macOS 14.1
- Claude Code version: 1.2.3

**Additional Context**
- Configuration files
- Error logs
- Screenshots if applicable

2. Feature Requests

Propose new functionality:

Feature Request Template

**Feature Summary**
Brief description of the proposed feature.

**Problem Statement**
What problem does this feature solve?

**Proposed Solution**
Detailed description of how the feature should work.

**Alternative Solutions**
Other approaches you've considered.

**Use Cases**
Real-world scenarios where this feature would be valuable.

**Implementation Notes**
Technical considerations or suggestions.

3. Code Contributions

Development Workflow

# Create feature branch
git checkout -b feature/agent-mobile-specialist

# Make your changes
# ... develop and test ...

# Run tests
npm run test
npm run lint
npm run type-check

# Commit changes (conventional commits)
git commit -m "feat(agents): add mobile specialist agent

- Add React Native and Flutter capabilities
- Include iOS/Android specific optimizations
- Add mobile UI/UX pattern recognition
- Update agent discovery system

Closes #123"

# Push branch
git push origin feature/agent-mobile-specialist

# Create Pull Request

4. Agent Development

Creating new specialized agents:

Agent Template

// agents/specialist-template.js
export class SpecialistAgent extends BaseAgent {
  constructor() {
    super({
      id: 'my-specialist',
      name: 'My Specialist Agent',
      description: 'Expert in specific domain',
      capabilities: [
        'domain-specific-task-1',
        'domain-specific-task-2'
      ],
      tools: [
        'tool-name-1',
        'tool-name-2'
      ],
      priority: 'medium',
      maxConcurrentTasks: 2
    });
  }

  async processTask(task, context) {
    // Implement task processing logic
    try {
      const result = await this.executeTask(task, context);
      return this.formatResponse(result);
    } catch (error) {
      throw new AgentError(`Task processing failed: ${error.message}`);
    }
  }

  async executeTask(task, context) {
    // Core task execution logic
    switch (task.type) {
      case 'domain-specific-task-1':
        return await this.handleTask1(task, context);
      case 'domain-specific-task-2':
        return await this.handleTask2(task, context);
      default:
        throw new Error(`Unsupported task type: ${task.type}`);
    }
  }

  getCapabilityScore(task) {
    // Return 0-1 score for task capability
    const taskTechnology = task.requirements?.technology;
    if (this.capabilities.includes(taskTechnology)) {
      return 0.9;
    }
    return 0.0;
  }
}

Agent Registration

// Register agent with the system
import { AgentRegistry } from '../src/orchestrator/AgentRegistry.js';
import { MySpecialistAgent } from './my-specialist-agent.js';

AgentRegistry.register(new MySpecialistAgent());

5. Documentation

Improve project documentation:

• API documentation updates
• Tutorial improvements
• Example projects
• Architecture diagrams
• Performance guides

Development Guidelines

Code Style

We use ESLint and Prettier for consistent code formatting:

// .eslintrc.js
module.exports = {
  extends: [
    'eslint:recommended',
    '@typescript-eslint/recommended',
    'prettier'
  ],
  rules: {
    'no-console': 'warn',
    'no-unused-vars': 'error',
    '@typescript-eslint/no-explicit-any': 'warn',
    'prefer-const': 'error'
  }
};

Commit Convention

We follow Conventional Commits:

# Format: type(scope): description
feat(agents): add mobile specialist agent
fix(orchestrator): resolve memory leak in context sharing
docs(readme): update installation instructions
test(api): add integration tests for task API
refactor(core): simplify agent assignment logic
perf(optimization): improve token compression algorithm

Commit Types

• feat: New features
• fix: Bug fixes
• docs: Documentation updates
• style: Code style changes
• refactor: Code refactoring
• test: Adding tests
• chore: Build/tooling changes
• perf: Performance improvements

Testing Requirements

All contributions must include appropriate tests:

Unit Tests

// tests/agents/specialist-agent.test.js
import { SpecialistAgent } from '../../src/agents/SpecialistAgent.js';
import { mockTask, mockContext } from '../helpers/mocks.js';

describe('SpecialistAgent', () => {
  let agent;

  beforeEach(() => {
    agent = new SpecialistAgent();
  });

  test('should process valid task successfully', async () => {
    const task = mockTask({
      type: 'domain-specific-task',
      requirements: { technology: 'my-tech' }
    });

    const result = await agent.processTask(task, mockContext);
    
    expect(result).toBeDefined();
    expect(result.status).toBe('success');
  });

  test('should reject unsupported task types', async () => {
    const task = mockTask({ type: 'unsupported-task' });
    
    await expect(agent.processTask(task, mockContext))
      .rejects.toThrow('Unsupported task type');
  });
});

Integration Tests

// tests/integration/agent-orchestration.test.js
import { OrchestrationEngine } from '../../src/orchestrator/OrchestrationEngine.js';
import { testProject } from '../fixtures/projects.js';

describe('Agent Orchestration Integration', () => {
  let orchestrator;

  beforeAll(async () => {
    orchestrator = new OrchestrationEngine();
    await orchestrator.initialize();
  });

  test('should complete full project workflow', async () => {
    const result = await orchestrator.processProject(testProject);
    
    expect(result.status).toBe('completed');
    expect(result.tasks.every(t => t.status === 'completed')).toBe(true);
    expect(result.artifacts).toHaveLength(testProject.expectedArtifacts.length);
  });
});

Performance Considerations

Ensure your contributions maintain system performance:

Benchmarking

// tests/benchmarks/agent-performance.bench.js
import { benchmark } from '../helpers/benchmark.js';
import { MySpecialistAgent } from '../../src/agents/MySpecialistAgent.js';

benchmark('MySpecialistAgent Performance', {
  'simple task processing': async () => {
    const agent = new MySpecialistAgent();
    const task = createSimpleTask();
    await agent.processTask(task, mockContext);
  },
  
  'complex task processing': async () => {
    const agent = new MySpecialistAgent();
    const task = createComplexTask();
    await agent.processTask(task, mockContext);
  }
}, {
  iterations: 100,
  timeout: 30000
});

Pull Request Process

PR Checklist

Before submitting a pull request:

• Code follows project style guidelines
• All tests pass locally
• New tests cover new functionality
• Documentation updated if needed
• Performance benchmarks run if applicable
• Security considerations reviewed
• Breaking changes documented
• Conventional commit messages used

PR Template

## Description
Brief description of changes and motivation.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Breaking change

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing performed
- [ ] Performance testing done

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-reviewed the code
- [ ] Documentation updated
- [ ] No breaking changes (or documented)
- [ ] Tests pass locally

## Screenshots (if applicable)
Include screenshots for UI changes.

## Related Issues
Closes #123
Relates to #456

Review Process

1. Automated Checks: CI/CD pipeline runs tests and linting
2. Peer Review: At least one maintainer reviews the code
3. Testing: Changes tested in development environment
4. Documentation: Ensure documentation is updated
5. Merge: Approved PRs merged to main branch

Community Guidelines

Code of Conduct

We follow the Contributor Covenant:

• Be respectful and inclusive
• Welcome newcomers and help them succeed
• Focus on constructive feedback
• Respect different viewpoints and experiences
• Accept responsibility for mistakes

Communication Channels

• GitHub Issues: Bug reports and feature requests
• GitHub Discussions: General questions and ideas
• Discord: Real-time chat (@vibecodingwithphil)
• Email: Direct contact for sensitive issues

Recognition

Contributors are recognized through:

• GitHub contributor graphs
• Release notes acknowledgments
• Hall of Fame in documentation
• Special badges for significant contributions

Advanced Contributions

MCP Server Development

Creating new MCP servers for Agentwise:

// Example MCP server for custom integration
import { MCPServer } from '@modelcontextprotocol/sdk';

class CustomIntegrationServer extends MCPServer {
  constructor() {
    super({
      name: 'custom-integration',
      version: '1.0.0',
      description: 'Custom integration for Agentwise'
    });
  }

  async initialize() {
    this.registerTool('custom-action', {
      description: 'Perform custom action',
      parameters: {
        type: 'object',
        properties: {
          action: { type: 'string' },
          parameters: { type: 'object' }
        }
      }
    });
  }

  async handleToolCall(name, parameters) {
    switch (name) {
      case 'custom-action':
        return await this.performCustomAction(parameters);
      default:
        throw new Error(`Unknown tool: ${name}`);
    }
  }
}

Template Development

Creating project templates:

{
  "name": "microservices-template",
  "description": "Microservices architecture template",
  "agents": ["backend", "database", "devops", "testing"],
  "structure": {
    "services/": {
      "user-service/": "User management microservice",
      "product-service/": "Product catalog microservice",
      "order-service/": "Order processing microservice"
    },
    "infrastructure/": {
      "docker-compose.yml": "Local development setup",
      "k8s/": "Kubernetes deployment configurations"
    },
    "docs/": {
      "api/": "API documentation",
      "architecture.md": "System architecture overview"
    }
  },
  "dependencies": {
    "runtime": ["docker", "kubernetes"],
    "development": ["node", "npm", "git"]
  }
}

Release Process

For maintainers and core contributors:

Version Management

We use semantic versioning (SemVer):

• MAJOR: Breaking changes
• MINOR: New features (backwards compatible)
• PATCH: Bug fixes

Release Workflow

# Prepare release
npm run release:prepare

# Update version
npm version minor  # or major/patch

# Generate changelog
npm run changelog:generate

# Create release PR
git checkout -b release/v1.1.0
git push origin release/v1.1.0

# After PR approval and merge
git tag v1.1.0
git push origin v1.1.0

# Publish to npm (if applicable)
npm publish

# Create GitHub release
gh release create v1.1.0 --generate-notes

Resources for Contributors

Learning Resources

• Multi-Agent Systems Guide
• Claude Code Documentation
• MCP Protocol Specification
• JavaScript/TypeScript Best Practices

Development Tools

• IDE Setup: VS Code with recommended extensions
• Debugging: Chrome DevTools integration
• Profiling: Node.js profiler for performance analysis
• Monitoring: Grafana dashboard for metrics

Getting Help

If you need help contributing:

1. Check the FAQ for common questions
2. Search existing GitHub issues and discussions
3. Join our Discord community
4. Reach out to maintainers directly

---

Thank you for contributing to Agentwise! Together, we're building the future of multi-agent software development.