Contribution Guide

Overview

This guide provides detailed contribution workflows for nexus-agents. For quick setup, see CONTRIBUTING.md.

Development Setup

Script test prerequisites

Install Python 3 (python3) and jq on your PATH before running the repository script tests. The governor approval tests execute the real jq filters; the native-approval snapshot tests execute isolated Python. Check both tools locally:

python3 --version
jq --version

If either command is missing, install it using your operating system’s package manager before running pnpm test:scripts. A missing executable is a setup failure, not a passing or skipped governance check. Use the pnpm version pinned by packageManager in the root package.json.

After installing repository dependencies, run the focused checks with:

pnpm test:scripts scripts/governor-human-approval.test.ts scripts/native-approval-canary-imports.test.ts

These local tests do not dispatch the approval experiment. Its separate review, owner ratification and live-read prerequisites remain in the native approval canary runbook.

Installation

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

# Install dependencies
pnpm install

# Verify installation
pnpm test

Workflow: Feature Implementation

Step 1: Research and Plan

Before implementing:

1. Check existing issues - Avoid duplicate work
2. Research registry - Check docs/research/registry/techniques.yaml
3. Define interface - Write interface before implementation

# Search for related issues
gh issue list --search "keyword"

# Check research registry
grep -i "keyword" docs/research/registry/techniques.yaml

Step 2: Create GitHub Issue

gh issue create \
  --title "feat: brief description" \
  --body "## Description

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Related Research
- Link to paper or technique" \
  --label "enhancement"

Step 3: Create Branch

git checkout main
git pull origin main
git checkout -b feat/<issue>-short-description

Step 4: Implement with TDD

# Write failing test first
pnpm test --watch packages/nexus-agents/src/path/to/feature.test.ts

# Implement until tests pass
# Keep functions < 50 lines, files < 400 lines

Step 5: Run Quality Gates

pnpm lint          # Zero errors, zero warnings
pnpm typecheck     # Zero type errors
pnpm test          # All tests pass

Step 6: Commit with Conventional Format

git add .
git commit -m "$(cat <<'EOF'
feat(scope): brief description

- Implementation detail 1
- Implementation detail 2

Closes #<issue>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"

Step 7: Create Pull Request

git push -u origin HEAD
gh pr create \
  --title "feat(scope): description" \
  --body "## Summary
- Implements #<issue>

## Changes
- Change 1
- Change 2

## Testing
- Test approach

## Checklist
- [ ] Tests pass
- [ ] Lint clean
- [ ] Types clean"

Workflow: Bug Fix

Step 1: Reproduce

# Create minimal reproduction
pnpm test:watch packages/nexus-agents/src/path/to/failing.test.ts

Step 2: Write Failing Test

it('should not have the bug', () => {
  const result = buggyFunction(input);
  expect(result).toBe(expected);
});

Step 3: Fix and Verify

# Implement fix until test passes
# Check for similar bugs elsewhere
grep -r "similar-pattern" packages/

Step 4: Create PR with Bug Fix Format

git commit -m "$(cat <<'EOF'
fix(scope): brief description of fix

Fixes regression where X caused Y.

Closes #<issue>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"

Workflow: Documentation

When to Update Documentation

• Adding new features or tools
• Changing public APIs
• Modifying configuration options
• Fixing incorrect documentation

Documentation Checklist

• ☐Not done: JSDoc for public functions
• ☐Not done: Update relevant docs/*.md files
• ☐Not done: Update CHANGELOG.md for user-facing changes
• ☐Not done: Verify links work: pnpm lint:links

PR Review Process

CLI-Based Review (Required)

# Run review with auto-selected CLI
pnpm review <PR-number>

# Use specific model
pnpm review <PR#> --model=claude    # Security, architecture
pnpm review <PR#> --model=gemini    # Large files (1M context)
pnpm review <PR#> --model=codex     # Code quality

# Dry run (preview without posting)
pnpm review <PR#> --dry-run

Review Focus Areas

Commit Message Reference

Types

Scopes

Issue Labels Reference

Quality Gates Reference

Pre-Commit

• pnpm lint - Zero errors, zero warnings
• pnpm typecheck - Zero type errors
• pnpm test - All tests pass
• Files ≤ 400 lines
• Functions ≤ 50 lines

Pre-Merge

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

Pre-Release

• All pre-merge gates
• E2E tests pass
• Documentation complete
• CHANGELOG updated

Related Documents

• Quick Start: CONTRIBUTING.md
• Coding Standards: CODING_STANDARDS.md
• Architecture: architecture/README.md
• Research: RESEARCH_INDEX.md