Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
138 lines (95 loc) · 4.04 KB

CONTRIBUTING.md

File metadata and controls

138 lines (95 loc) · 4.04 KB

Contributing to Agent NERO

Thank you for your interest in contributing to Agent NERO. This document provides guidelines and information for contributors.

Getting Started

  1. Fork the repository
  2. Clone your fork: git clone https://github.com/YOUR-USERNAME/agent-nero.git
  3. Install dependencies: npm install
  4. Create a feature branch: git checkout -b feature/your-feature-name

Development Setup

Prerequisites

  • Node.js >= 20.0.0
  • npm >= 10.0.0
  • An Anthropic API key (for integration testing)

Running from Source

# Direct execution
npx tsx src/index.ts

# With file watching (auto-restart on changes)
npm run dev

Type Checking

npm run typecheck

All code must pass TypeScript strict mode with zero errors before submission.

Code Standards

TypeScript

  • Strict mode enabled ("strict": true)
  • ES2022 target with ESNext modules
  • All exports must have explicit types
  • Use const by default, let when mutation is required
  • Prefer async/await over raw promises
  • Error handling: catch specific error types, never swallow errors silently

Project Conventions

  • File naming: kebab-case.ts (e.g., memory-bus.ts, agent-pool.ts)
  • Class naming: PascalCase (e.g., NeroAgent, MemoryBus)
  • Tool naming: snake_case with nero_ prefix for MCP tools (e.g., nero_spawn)
  • Internal tools: snake_case without prefix (e.g., read_file, run_command)

Formatting

  • 2-space indentation
  • LF line endings
  • UTF-8 encoding
  • Trailing newline on all files
  • No trailing whitespace (except in Markdown)

See .editorconfig for the full specification.

Making Changes

Adding a New MCP Tool

  1. Create src/tools/your-tool.ts following the pattern in existing tools
  2. Define a registerYourTool() function that takes McpServer and required dependencies
  3. Use Zod schemas for input validation
  4. Register the tool in src/index.ts
  5. Update the tool count comment in src/index.ts
  6. Document the tool in docs/API.md
  7. Add to the MCP permissions list in the README

Adding a New Agent Internal Tool

  1. Add the tool definition to getToolDefinitions() in src/agent-tools.ts
  2. Add the executor to createToolExecutors() in the same file
  3. Include path sanitization for any file system operations
  4. Respect the TOOL_TIMEOUT_MS and MAX_OUTPUT_CHARS limits
  5. Document in docs/API.md

Modifying Core Components

  • agent.ts — The tool-use loop is critical. Changes must preserve the Anthropic API contract.
  • memory-bus.ts — Thread safety matters if future async patterns are introduced.
  • agent-pool.ts — Agent lifecycle management. Ensure no memory leaks on kill/reset.

Commit Messages

Use clear, descriptive commit messages:

feat: add nero_memory_dump tool for disk export
fix: prevent history pruning from violating user-first constraint
docs: add architecture diagram to README
refactor: extract tool executor factory from agent class

Prefixes: feat, fix, docs, refactor, test, chore, perf

Pull Requests

  1. Ensure npm run typecheck passes with zero errors
  2. Test your changes with an actual Claude Code session if possible
  3. Update documentation for any user-facing changes
  4. Update CHANGELOG.md with your changes
  5. Keep PRs focused — one feature or fix per PR
  6. Fill out the PR template completely

Reporting Bugs

Use the bug report template. Include:

  • Node.js version
  • Claude Code version
  • Steps to reproduce
  • Expected vs actual behavior
  • Relevant logs (stderr output from [NERO] prefix)

Feature Requests

Use the feature request template. Describe:

  • The problem your feature solves
  • Your proposed solution
  • Alternatives you've considered

Security

If you discover a security vulnerability, do not open a public issue. See SECURITY.md for responsible disclosure instructions.

License

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