Development Guide

Tier 2 Hub | Load for development tasks Contributing: CONTRIBUTING.md

Quick Navigation

Quick Start

# Clone repository
git clone https://github.com/williamzujkowski/nexus-agents.git
cd nexus-agents

# Install dependencies
pnpm install

# Run tests
pnpm test

# Start development
pnpm dev

Development Workflow

1. Create Issue

gh issue create --title "feat: description" --label "enhancement"

2. Create Branch

git checkout -b feat/<issue>-short-description

3. Implement with TDD

# Write test first
pnpm test --watch

# Implement until tests pass

4. Run Quality Gates

pnpm lint          # Zero errors
pnpm typecheck     # Zero errors
pnpm test          # All pass

5. Create PR

git push -u origin HEAD
gh pr create --title "feat: description" --body "Closes #<issue>"

Quality Gates

Pre-Commit (Must Pass)

• pnpm lint - Zero errors, zero warnings
• pnpm typecheck - Zero errors
• pnpm test - All tests pass
• No file > 400 lines
• No function > 50 lines

Pre-Merge

• All pre-commit gates
• Coverage ≥ 80%
• Security audit clean

Code Standards Summary

TypeScript

// Use Result<T,E> for fallible operations
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };

// Use unknown over any
function parse(input: unknown): Result<Data, ParseError> {}

// Use Zod for validation
const Schema = z.object({ name: z.string() });

Naming

File Structure

// 1. Imports (external, then internal)
// 2. Types/Interfaces
// 3. Constants
// 4. Main export
// 5. Helper functions

Common Tasks

Adding a New Expert

// 1. Define expert config
const config: ExpertConfig = {
  type: 'my-expert',
  prompt: 'You are an expert in...',
  tier: 'balanced',
};

// 2. Add to BUILT_IN_EXPERTS in expert-config.ts
// ExpertFactory.create('my-expert') will then find it

Adding an MCP Tool

server.tool(
  'tool_name',
  {
    param: z.string().describe('What this does'),
  },
  async (args) => {
    // Implementation
    return { content: [{ type: 'text', text: result }] };
  }
);

Adding a Consensus Protocol

class MyProtocol implements ICollaborationProtocol {
  readonly pattern = 'my-pattern';

  async execute(config, agents) {
    // Implementation
  }
}

Testing

Unit Tests

import { describe, it, expect } from 'vitest';

describe('MyComponent', () => {
  it('should do something', () => {
    expect(result).toBe(expected);
  });
});

Integration Tests

import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';

const [client, server] = InMemoryTransport.createLinkedPair();

Run Specific Tests

pnpm test path/to/file.test.ts
pnpm test --grep "pattern"

Debugging

Enable Debug Logging

export NEXUS_LOG_LEVEL=debug
pnpm dev

Routing Debug

nexus-agents routing-audit "task" --verbose

See Also

• DEBUGGING_OBSERVABILITY.md
• TROUBLESHOOTING.md

Related Documents

• Architecture: architecture/README.md
• Full Standards: CODING_STANDARDS.md
• API Reference: ENTRYPOINTS.md
• Research: RESEARCH_INDEX.md