Development Guide

Overview

Contributing to NikCLI helps build the future of AI-assisted development. Whether you’re fixing bugs, adding features, improving documentation, or creating agents, your contributions make a real difference for developers worldwide.

Getting Started

Set up your development environment and make your first contribution

Code Contributions

Guidelines for submitting high-quality code contributions

Agent Development

Create and contribute new AI agents to the ecosystem

Community

Join our vibrant community of contributors and maintainers

Development Setup

Prerequisites

System Requirements
Development Environment
Project Structure

# Required software
Node.js 18+ (LTS recommended)
npm 9+ or yarn 1.22+
Git 2.30+

# Recommended tools
VS Code with extensions:
- TypeScript and JavaScript Language Features
- ESLint
- Prettier
- Jest Runner
- GitLens

# System resources
RAM: 8GB minimum (16GB recommended)
Storage: 10GB free space for development
OS: macOS, Linux, or Windows with WSL2

# Clone the repository
git clone https://github.com/cadcamfun/nikcli.git
cd nikcli

# Install dependencies
npm install

# Set up development environment
cp .env.example .env.local
# Edit .env.local with your API keys and configuration

# Run initial setup
npm run setup:dev

# Start development server
npm run dev

# Run tests to verify setup
npm test

nikcli/
├── src/cli/                 # Main CLI source code
│   ├── index.ts            # CLI entry point
│   ├── automation/         # Agent system
│   ├── chat/              # Chat interface
│   ├── core/              # Core functionality
│   ├── services/          # Service layer
│   ├── tools/             # Tool implementations
│   └── utils/             # Utility functions
├── tests/                  # Test files
│   ├── unit/              # Unit tests
│   ├── integration/       # Integration tests
│   └── e2e/               # End-to-end tests
├── docs/                   # Documentation
├── scripts/               # Build and utility scripts
├── bin/                   # Binary entry points
└── dist/                  # Compiled output

Development Workflow

Branch Strategy

We use Git Flow with the following branch structure:

main: Production-ready code, tagged releases
develop: Integration branch for features
feature/*: Feature development branches
bugfix/*: Bug fix branches
hotfix/*: Critical fixes for production
release/*: Release preparation branches

# Start new feature
git checkout develop
git pull origin develop
git checkout -b feature/agent-improvements

# Work on feature, commit regularly
git add .
git commit -m "feat: improve agent response caching"

# Push and create PR when ready
git push origin feature/agent-improvements

Commit Convention

We follow Conventional Commits specification:

# Format: type(scope): description

# Types:
feat: new feature
fix: bug fix
docs: documentation changes
style: formatting, missing semicolons, etc
refactor: code change that neither fixes bug nor adds feature
perf: performance improvement
test: adding or updating tests
chore: updating build tasks, package manager configs, etc

# Examples:
git commit -m "feat(agents): add React testing specialist agent"
git commit -m "fix(chat): resolve message streaming timeout issue"
git commit -m "docs(api): update tool system documentation"
git commit -m "test(agents): add unit tests for agent orchestration"

Code Contribution Guidelines

Code Standards

TypeScript Guidelines
Error Handling
Testing Standards

// Use strict TypeScript configuration
// Always define explicit types for public APIs

interface AgentConfig {
  name: string;
  version: string;
  capabilities: AgentCapability[];
  tools: ToolDefinition[];
}

// Use generic types when appropriate
class AgentManager<T extends BaseAgent> {
  private agents = new Map<string, T>();
  
  register(agent: T): void {
    this.agents.set(agent.id, agent);
  }
  
  get(id: string): T | undefined {
    return this.agents.get(id);
  }
}

// Document complex functions with JSDoc
/**
 * Executes an agent task with retry logic and error handling
 * @param agentId - The ID of the agent to execute
 * @param task - The task to execute
 * @param options - Execution options including retry and timeout settings
 * @returns Promise that resolves to the task result
 */
async function executeAgentTask(
  agentId: string,
  task: AgentTask,
  options: ExecutionOptions = {}
): Promise<AgentResult> {
  // Implementation...
}

// Use custom error types for different scenarios
export class AgentExecutionError extends Error {
  constructor(
    message: string,
    public agentId: string,
    public taskId: string,
    public cause?: Error
  ) {
    super(message);
    this.name = 'AgentExecutionError';
  }
}

// Implement proper error handling with recovery
async function executeWithRetry<T>(
  operation: () => Promise<T>,
  maxRetries: number = 3,
  delay: number = 1000
): Promise<T> {
  let lastError: Error;
  
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error) {
      lastError = error as Error;
      
      if (attempt === maxRetries) {
        throw new AgentExecutionError(
          `Operation failed after ${maxRetries} attempts`,
          'unknown',
          'unknown',
          lastError
        );
      }
      
      await new Promise(resolve => setTimeout(resolve, delay * attempt));
    }
  }
  
  throw lastError!;
}

// Unit test example
import { describe, it, expect, beforeEach, jest } from '@jest/globals';
import { AgentManager } from '../agent-manager';
import { MockAgent } from '../../test-utils/mock-agent';

describe('AgentManager', () => {
  let agentManager: AgentManager;
  let mockAgent: MockAgent;
  
  beforeEach(() => {
    agentManager = new AgentManager();
    mockAgent = new MockAgent('test-agent');
  });
  
  describe('register', () => {
    it('should register an agent successfully', () => {
      agentManager.register(mockAgent);
      
      expect(agentManager.get('test-agent')).toBe(mockAgent);
    });
    
    it('should throw error when registering duplicate agent', () => {
      agentManager.register(mockAgent);
      
      expect(() => agentManager.register(mockAgent))
        .toThrow('Agent test-agent is already registered');
    });
  });
  
  describe('execute', () => {
    it('should execute agent task successfully', async () => {
      const task = { id: 'task-1', description: 'Test task' };
      const expectedResult = { success: true, output: 'Task completed' };
      
      mockAgent.execute.mockResolvedValue(expectedResult);
      agentManager.register(mockAgent);
      
      const result = await agentManager.execute('test-agent', task);
      
      expect(result).toEqual(expectedResult);
      expect(mockAgent.execute).toHaveBeenCalledWith(task);
    });
  });
});

Performance Guidelines

Memory Management

// Implement proper cleanup in long-running processes
export class StreamingManager {
  private streams = new Map<string, NodeJS.ReadableStream>();
  private cleanupTimer?: NodeJS.Timeout;
  
  constructor() {
    // Set up automatic cleanup
    this.cleanupTimer = setInterval(() => {
      this.cleanupInactiveStreams();
    }, 60000); // Every minute
  }
  
  addStream(id: string, stream: NodeJS.ReadableStream): void {
    // Clean up existing stream if any
    this.removeStream(id);
    
    this.streams.set(id, stream);
    
    // Set up stream cleanup on end
    stream.on('end', () => this.removeStream(id));
    stream.on('error', () => this.removeStream(id));
  }
  
  removeStream(id: string): void {
    const stream = this.streams.get(id);
    if (stream) {
      stream.destroy();
      this.streams.delete(id);
    }
  }
  
  destroy(): void {
    if (this.cleanupTimer) {
      clearInterval(this.cleanupTimer);
    }
    
    // Clean up all streams
    for (const [id] of this.streams) {
      this.removeStream(id);
    }
  }
}

Caching Strategies

// Implement intelligent caching with TTL and LRU eviction
export class IntelligentCache<T> {
  private cache = new Map<string, CacheEntry<T>>();
  private accessOrder: string[] = [];
  
  constructor(
    private maxSize: number = 1000,
    private defaultTtl: number = 300000 // 5 minutes
  ) {}
  
  set(key: string, value: T, ttl?: number): void {
    const expiry = Date.now() + (ttl ?? this.defaultTtl);
    
    // Remove if already exists to update access order
    if (this.cache.has(key)) {
      this.remove(key);
    }
    
    // Evict if at capacity
    if (this.cache.size >= this.maxSize) {
      this.evictLRU();
    }
    
    this.cache.set(key, { value, expiry });
    this.accessOrder.push(key);
  }
  
  get(key: string): T | undefined {
    const entry = this.cache.get(key);
    
    if (!entry) {
      return undefined;
    }
    
    if (Date.now() > entry.expiry) {
      this.remove(key);
      return undefined;
    }
    
    // Update access order
    this.updateAccessOrder(key);
    
    return entry.value;
  }
  
  private evictLRU(): void {
    const oldestKey = this.accessOrder.shift();
    if (oldestKey) {
      this.cache.delete(oldestKey);
    }
  }
}

Feature Development Process

Planning and Design

Feature Proposal
Implementation
Review Process

Create GitHub Issue
- Use feature request template
- Describe the problem and proposed solution
- Include user stories and acceptance criteria
- Add relevant labels and milestones
Design Discussion
- Participate in design discussions
- Consider backwards compatibility
- Review impact on existing features
- Get maintainer approval before starting
Technical Design
- Create technical design document if complex
- Consider architecture implications
- Plan testing strategy
- Identify potential risks and mitigations

# Development workflow

1. Create feature branch
git checkout -b feature/new-agent-capability

2. Implement feature with tests
# Write failing tests first (TDD approach)
# Implement minimum viable feature
# Refactor and optimize
# Add comprehensive tests

3. Update documentation
# Update relevant documentation
# Add examples and usage guides
# Update CHANGELOG.md

4. Test thoroughly
npm run test:unit
npm run test:integration
npm run test:e2e

5. Submit pull request
# Follow PR template
# Request reviews from relevant maintainers
# Address feedback promptly

Quality Assurance

Testing Requirements

# Test coverage requirements
- Unit tests: 90% statement coverage minimum
- Integration tests: All service interactions
- End-to-end tests: Critical user workflows
- Performance tests: Response time benchmarks

# Running different test suites
npm run test:unit              # Fast unit tests
npm run test:integration       # Service integration tests  
npm run test:e2e              # End-to-end browser tests
npm run test:performance      # Performance benchmarks
npm run test:security         # Security vulnerability tests

# Test in different environments
npm run test:node-18          # Test on Node.js 18
npm run test:node-20          # Test on Node.js 20
npm run test:windows          # Windows-specific tests
npm run test:linux            # Linux-specific tests
npm run test:macos            # macOS-specific tests

Performance Testing

// Performance test example
import { performance } from 'perf_hooks';

describe('Agent Performance', () => {
  it('should respond within acceptable time limits', async () => {
    const agent = new UniversalAgent();
    const startTime = performance.now();
    
    const result = await agent.execute({
      task: 'Create a simple React component',
      context: { files: [], workspace: '/test' }
    });
    
    const duration = performance.now() - startTime;
    
    expect(result).toBeDefined();
    expect(duration).toBeLessThan(30000); // 30 seconds max
  });
  
  it('should handle concurrent requests efficiently', async () => {
    const agent = new UniversalAgent();
    const concurrentRequests = 10;
    
    const startTime = performance.now();
    
    const promises = Array.from({ length: concurrentRequests }, () =>
      agent.execute({
        task: 'Simple task',
        context: { files: [], workspace: '/test' }
      })
    );
    
    const results = await Promise.all(promises);
    const duration = performance.now() - startTime;
    
    expect(results).toHaveLength(concurrentRequests);
    expect(duration).toBeLessThan(60000); // Should complete within 1 minute
  });
});

Agent Development

Creating New Agents

Agent Structure
Agent Registration
Agent Testing

// src/cli/automation/agents/my-custom-agent.ts
import { BaseAgent, AgentCapability, AgentResult } from './base-agent';
import { ToolRegistry } from '../tools/tool-registry';

export class MyCustomAgent extends BaseAgent {
  constructor() {
    super({
      id: 'my-custom-agent',
      name: 'My Custom Agent',
      description: 'Specialized agent for custom tasks',
      version: '1.6.0',
      capabilities: [
        AgentCapability.CODE_GENERATION,
        AgentCapability.CODE_REVIEW,
        AgentCapability.TESTING
      ],
      specializations: ['custom-framework', 'domain-specific'],
      tools: [
        'file_operations',
        'code_analysis', 
        'custom_validator'
      ]
    });
  }
  
  async execute(task: AgentTask): Promise<AgentResult> {
    try {
      // Validate task requirements
      this.validateTask(task);
      
      // Process task with domain expertise
      const result = await this.processCustomTask(task);
      
      // Validate result quality
      await this.validateResult(result);
      
      return {
        success: true,
        result: result,
        confidence: this.calculateConfidence(result),
        suggestions: this.generateSuggestions(result)
      };
    } catch (error) {
      return this.handleError(error, task);
    }
  }
  
  private async processCustomTask(task: AgentTask): Promise<any> {
    // Custom processing logic
    const context = await this.analyzeContext(task.context);
    const solution = await this.generateSolution(task.description, context);
    return await this.refineSolution(solution, task.requirements);
  }
  
  protected getSystemPrompt(): string {
    return `
    You are a specialized agent expert in custom framework development.
    You have deep knowledge of:
    - Custom framework patterns and best practices
    - Domain-specific architecture patterns  
    - Performance optimization techniques
    - Testing strategies for custom frameworks
    
    Always provide:
    - Clean, maintainable code
    - Comprehensive documentation
    - Appropriate test coverage
    - Performance considerations
    `;
  }
}

// src/cli/register-agents.ts
import { AgentRegistry } from './core/agent-registry';
import { MyCustomAgent } from './automation/agents/my-custom-agent';

export function registerAllAgents(): void {
  const registry = AgentRegistry.getInstance();
  
  // Register existing agents...
  
  // Register new custom agent
  registry.register(new MyCustomAgent());
  
  // Agent is now available via:
  // /agent my-custom-agent "task description"
  // /agents (will list the new agent)
}

// tests/unit/agents/my-custom-agent.test.ts
import { MyCustomAgent } from '../../../src/cli/automation/agents/my-custom-agent';
import { AgentTask } from '../../../src/cli/types/agent';

describe('MyCustomAgent', () => {
  let agent: MyCustomAgent;
  
  beforeEach(() => {
    agent = new MyCustomAgent();
  });
  
  describe('execute', () => {
    it('should handle custom framework tasks', async () => {
      const task: AgentTask = {
        id: 'test-task',
        description: 'Create custom framework component',
        context: {
          workspace: '/test/project',
          files: ['src/framework/base.ts']
        }
      };
      
      const result = await agent.execute(task);
      
      expect(result.success).toBe(true);
      expect(result.result).toBeDefined();
      expect(result.confidence).toBeGreaterThan(0.8);
    });
    
    it('should provide helpful suggestions', async () => {
      const task: AgentTask = {
        id: 'test-task-2', 
        description: 'Optimize framework performance',
        context: { workspace: '/test', files: [] }
      };
      
      const result = await agent.execute(task);
      
      expect(result.suggestions).toBeDefined();
      expect(result.suggestions.length).toBeGreaterThan(0);
    });
  });
});

Agent Best Practices

Design Principles

Single Responsibility: Each agent should have a clear, focused purpose

// Good: Focused agent
export class ReactTestingAgent extends BaseAgent {
  // Specialized in React component testing only
}

// Avoid: Overly broad agent
export class FullStackEverythingAgent extends BaseAgent {
  // Tries to do too many different things
}

Domain Expertise: Agents should have deep knowledge in their domain

protected getSystemPrompt(): string {
  return `
  You are a React testing expert with deep knowledge of:
  - Jest and React Testing Library best practices
  - Component testing strategies (unit, integration)  
  - Mock strategies for complex components
  - Testing hooks and context providers
  - Accessibility testing with jest-axe
  - Visual regression testing approaches
  `;
}

Error Handling

async execute(task: AgentTask): Promise<AgentResult> {
  try {
    // Validate inputs
    if (!this.canHandleTask(task)) {
      return {
        success: false,
        error: 'This agent cannot handle the requested task type',
        suggestions: ['Try the universal-agent or a more appropriate specialist']
      };
    }
    
    // Execute with timeout protection
    const result = await Promise.race([
      this.processTask(task),
      this.timeoutPromise(30000) // 30 second timeout
    ]);
    
    return result;
  } catch (error) {
    // Log error for debugging but don't expose internal details
    this.logger.error('Agent execution failed', { 
      agentId: this.id, 
      taskId: task.id, 
      error 
    });
    
    return {
      success: false,
      error: 'An unexpected error occurred while processing the task',
      suggestions: [
        'Try rephrasing the request',
        'Check if all required context is provided',
        'Consider breaking the task into smaller parts'
      ]
    };
  }
}

Documentation Contributions

Writing Guidelines

Documentation Standards
API Documentation

Structure: Follow established patterns and organization

---
title: 'Clear, Descriptive Title'
description: 'Concise description of the content'
icon: 'relevant-icon'
---

## Overview
Brief introduction with key benefits/features

<CardGroup cols={2}>
  <!-- Feature highlights -->
</CardGroup>

## Main Content Sections

### Subsection
<Tabs>
  <Tab title="Basic Usage">
    <!-- Simple examples first -->
  </Tab>
  
  <Tab title="Advanced Usage">
    <!-- Complex examples after -->
  </Tab>
</Tabs>

## Next Steps
<CardGroup cols={2}>
  <!-- Related documentation links -->
</CardGroup>

Code Examples: Always include working, tested examples

# Always show the actual command
/agent react-expert "create a login component with validation"

# Show expected output or results when helpful
# ✓ Component created: src/components/LoginForm.tsx
# ✓ Tests created: src/components/__tests__/LoginForm.test.tsx
# ✓ Storybook story: src/stories/LoginForm.stories.tsx

/**
 * Executes an agent task with comprehensive error handling and validation
 * 
 * @param agentId - Unique identifier for the agent to execute
 * @param task - Task object containing description and context
 * @param options - Optional execution parameters
 * @returns Promise resolving to the agent execution result
 * 
 * @example
 * ```typescript
 * const result = await executeAgent('react-expert', {
 *   description: 'Create a modal component',
 *   context: { workspace: './src', files: ['types.ts'] }
 * });
 * 
 * if (result.success) {
 *   console.log('Task completed:', result.output);
 * }
 * ```
 * 
 * @throws {AgentNotFoundError} When the specified agent doesn't exist
 * @throws {InvalidTaskError} When the task is malformed or incomplete
 */
export async function executeAgent(
  agentId: string,
  task: AgentTask,
  options?: ExecutionOptions
): Promise<AgentResult>;

Documentation Review Process

Review Checklist

Content Quality:

Information is accurate and up-to-date
Examples are working and tested
Writing is clear and concise
Technical terms are explained
Prerequisites are clearly stated

Structure:

Follows documentation template
Proper heading hierarchy
Code examples are syntax highlighted
Links work and point to correct pages
Images have alt text and load correctly

User Experience:

Information is organized logically
Examples progress from simple to complex
Cross-references help navigation
Search keywords are appropriate

Community Guidelines

Code of Conduct

We are committed to fostering an inclusive and welcoming community. All contributors must adhere to our Code of Conduct. Key Principles:

Be respectful: Treat all community members with respect and kindness
Be collaborative: Work together constructively and share knowledge
Be inclusive: Welcome contributors from all backgrounds and experience levels
Be patient: Help newcomers learn and grow
Focus on what’s best for the community: Make decisions that benefit everyone

Getting Help

Discord Community

Join our active Discord for real-time discussions

General discussion and questions
Development help and code review
Feature planning and feedback
Community events and updates

GitHub Discussions

Participate in structured discussions

Feature requests and proposals
Architecture discussions
Best practices sharing
Q&A and troubleshooting

Office Hours

Join weekly maintainer office hours

Every Tuesday 2PM EST / 7PM GMT
Open forum for questions and discussion
Feature demos and roadmap updates
New contributor onboarding

Mentorship Program

Get paired with experienced contributors

1-on-1 guidance for new contributors
Code review and feedback
Career development support
Open source best practices

Recognition

We believe in recognizing and celebrating our contributors:

Contributor Hall of Fame: Featured on our documentation site
Annual Awards: Recognition for outstanding contributions
Speaking Opportunities: Conference and meetup speaking invitations
Swag and Rewards: Exclusive contributor merchandise
Resume Support: LinkedIn recommendations and references

Next Steps

Architecture Deep Dive

Understand NikCLI’s architecture and design decisions

Extending NikCLI

Learn advanced techniques for extending NikCLI

GitHub Repository

Visit our repository to start contributing

Discord Community

Join our development community discussions

Start small with documentation fixes or bug reports, then gradually work up to feature contributions. Don’t hesitate to ask questions in Discord or GitHub Discussions - our community is here to help!

Getting Started

CLI Reference

Agent System

Planning System

Context & RAG

Architecture

Troubleshooting

​Overview

Getting Started

Code Contributions

Agent Development

Community

​Development Setup

​Prerequisites

​Development Workflow

​Code Contribution Guidelines

​Code Standards

​Performance Guidelines

​Feature Development Process

​Planning and Design

​Quality Assurance

​Agent Development

​Creating New Agents

​Agent Best Practices

​Documentation Contributions

​Writing Guidelines

​Documentation Review Process

​Community Guidelines

​Code of Conduct

​Getting Help

Discord Community

GitHub Discussions

Office Hours

Mentorship Program

​Recognition

​Next Steps

Architecture Deep Dive

Extending NikCLI

GitHub Repository

Discord Community

Overview

Development Setup

Prerequisites

Development Workflow

Code Contribution Guidelines

Code Standards

Performance Guidelines

Feature Development Process

Planning and Design

Quality Assurance

Agent Development

Creating New Agents

Agent Best Practices

Documentation Contributions

Writing Guidelines

Documentation Review Process

Community Guidelines

Code of Conduct

Getting Help

Recognition

Next Steps