Contributing to ADEPT

Contributing to ADEPT

Thank you for your interest in contributing to ADEPT. This guide covers the development workflow, conventions, and submission process.

---

Development Workflow

ADEPT follows a 10-phase feature development lifecycle documented in docs/development/FEATURE_DEVELOPMENT_WORKFLOW.md.

Phases

#	Phase	Gate
0	Orient	Read CLAUDE.md + workflow docs
1	Plan	Implementation plan doc exists
2	Discover	3+ analogous patterns found
3	Branch	Branch pushed to origin
4	Implement	Tasks from plan complete
5	Test	Required test tiers pass
6	Document	Session report + tracking docs
7	Commit	Conventional Commit format
8	Audit	Code hygiene checklist passes
9	Close	PR created, review addressed

---

Branch Naming

<type>-<scope>-<quarter>-<description>

Examples:
  feature-mcp-server-FY26Q4-genomics-tools
  bugfix-auth-FY26Q4-jwt-expiry
  refactor-orchestration-FY26Q4-simplify-routing

---

Commit Format

Conventional Commits with documentation references:

type(scope): concise description

Body: what changed and why.

Related documentation (this commit):
- docs/implementation-reports/SESSION_N_TITLE.md

Related documentation (past 5 commits):
- docs/implementation-reports/SESSION_N-1_TITLE.md

Types: feat, fix, refactor, docs, test, chore, perf, ci

---

Testing Requirements

Tests are determined by what files changed:

Changed Files	Required Tiers
src/	Unit tests mandatory
Cross-package	Integration required
API routes / gateway	E2E required
Connectors / UI	All 4 tiers
Docs only	No tests needed
IaC	Dry-run validation

Running Tests

# All tests use Docker containers (never host pytest)
make validate                  # Full E2E suite
make validate-unit-all         # All unit tests
make validate-service-health   # Service health

# Specific areas
make validate-response-api-tool-calls
make validate-multi-agent
make validate-mcp-tools-discovery

---

Code Style

• Formatter: Black (line-length 88)
• Import sorting: isort (profile: black)
• Linter: ruff (target: py311)
• Type checker: mypy

All run via Docker containers for consistency:

docker run --rm -v "$(pwd)/src":/app/src:ro -w /tmp \
  agentic-framework-deps-base /bin/bash -c "
    python3 -m venv /tmp/lint_venv && \
    /tmp/lint_venv/bin/pip install -q black ruff && \
    /tmp/lint_venv/bin/black --check /app/src/ --line-length 88 && \
    /tmp/lint_venv/bin/ruff check /app/src/ --target-version py311
  "

---

MCP Tool Development

To add a new scientific tool:

1. Choose the appropriate server (mcp_server/, hpc_mcp_server/, or new)
2. Create tool module in tools/ directory
3. Follow the register(mcp) + Pydantic input model pattern
4. Add unit tests, integration tests, registration verification
5. Tools are auto-discovered by the orchestration service

See examples/mcp_server_template/ for the canonical template.

---

Pull Request Checklist

Before submitting:

• Implementation plan doc in docs/implementation-plans/
• All required test tiers pass (timestamped evidence in logs/)
• Code formatted with Black + isort
• No linting errors from ruff
• Conventional Commit message with doc references
• Session report in docs/implementation-reports/
• CHANGELOG updated (if user-facing change)

---

CI Pipeline

PRs automatically trigger:

1. Lint and Test -- Black, ruff, mypy, pytest
2. Infrastructure Linting -- Helm lint, Terraform validate
3. ASOPB Pre-Release Scan -- Security analysis (Phase 1 blocking, Phase 2 advisory)

---

Getting Help

• Issues: github.com/pnnl/adept-agentic/issues
• Wiki: github.com/pnnl/adept-agentic/wiki
• Claude Code: Use /start-feature to get guided through the full workflow