Docs › Contributing

Contributing

NightShift is AGPL-3.0. Contributions are welcome across code, AR patterns, KB consolidation, agent archetypes, and documentation. Here's how to get started without breaking anything.

ⓘ

Before you write a line of code, read Architecture and run the test suite locally. NightShift has 665 tests. All must pass before a PR is merged.

Development Setup

terminal
# Clone the repo git clone https://github.com/geopard-studio/nightshift.git cd nightshift # Create a virtual environment python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate # Install with dev dependencies pip install -e ".[dev]" # Verify: all tests should pass pytest -x -q 665 passed in 12.4s # Set your API key (needed for integration tests) export ANTHROPIC_API_KEY="sk-ant-..."

Contribution Areas

Pick based on what you know. Each area is well-isolated.

AR Patterns — Team configurations

If you've run NightShift on a real problem and found a team composition that worked well, contribute it as an AR pattern. No deep code knowledge required — just a YAML block and evidence it works.

  • File: nightshift/ar/seed_patterns.yaml
  • Each pattern needs: name, description, nodes list, use_case
  • Include a real example run in the PR description — quality score, cost, problem type
Agent Archetypes — New agent roles

The Coordinator can invent archetypes on the fly, but seed archetypes give it better starting points. If you build a reliable agent for a specific task type, add it.

  • File: nightshift/agents/archetypes/
  • Each archetype is a Python class implementing BaseAgent
  • Required: system prompt, run() method, unit tests in tests/agents/
  • Archetypes must be deterministic enough to test: provide mock LLM fixtures
KB Consolidation — Smarter memory compression

The Librarian consolidation is one of the highest-leverage areas. Better consolidation = more signal, less noise, faster KB queries, better learning.

  • File: nightshift/kb/librarian.py
  • The Librarian takes a list of KB entries and outputs a reduced, consolidated list
  • Benchmark: run tests/kb/test_librarian_quality.py with your changes
  • Target: higher consolidation ratio without dropping actionable insights
Evaluator — Better quality scoring

The Evaluator is what keeps the system honest. Improvements here improve the signal that feeds UCB1 scoring and the learning loop.

  • File: nightshift/evaluator/evaluator.py
  • Sub-evaluators are in nightshift/evaluator/sub_evaluators/
  • New sub-evaluator types (e.g. "security review", "test coverage check") are welcome
  • All evaluator changes must pass tests/evaluator/ and include new tests

PR Workflow

  1. Branch from main — use a descriptive name: feat/archetype-security-scanner, fix/kb-consolidation-dedup, docs/monitoring-page
  2. Write tests first — every non-trivial change needs a test. NightShift has a strong test suite; keep it strong.
  3. Run the full suite before opening a PR: pytest -x
  4. One concern per PR — a PR that adds an archetype AND refactors the engine will be asked to split.
  5. Write a clear description — what changed, why, and how to verify. For AR patterns, include a real run result.
⚠

Never hardcode agent names, thresholds, or task-type gates. The architecture explicitly forbids this (see Principle 1 in Architecture). PRs that add hardcoded branching will be rejected.

Testing Guide

Unit tests (no API key needed)

terminal
# Run all unit tests pytest tests/unit/ -q # Run a specific module pytest tests/unit/test_kb.py -v # Run with coverage pytest tests/unit/ --cov=nightshift --cov-report=term-missing

Integration tests (API key required, costs ~$0.10)

terminal
# Integration tests hit the real API pytest tests/integration/ -v --timeout=120 # Run a single integration test pytest tests/integration/test_full_run.py::test_simple_problem -v

Writing good tests

NightShift uses deterministic mocking for all LLM calls in unit tests. The mock fixtures are in tests/fixtures/. When adding a new agent or archetype:

  1. Add realistic mock responses to tests/fixtures/responses/
  2. Test the happy path, the failure path, and the retry path
  3. Test that KB reads happen before the agent acts, and KB writes happen after

AGPL-3.0 and Contributions

NightShift is AGPL-3.0. By contributing, you agree that your contribution will be licensed under the same terms.

Key implication: if you deploy a modified version of NightShift as a network service, you must release your modifications under AGPL-3.0. Running it locally for personal use has no such requirement.

✨

The AGPL license is intentional. It ensures that improvements to NightShift stay in the commons. If your company needs different terms (e.g. for a proprietary deployment), reach out to discuss a commercial license.

Community Standards

NightShift is a small project. We don't have a formal CoC document yet, but the standard applies: be direct, be honest, don't be a jerk. Technical disagreements are fine and healthy. Personal attacks are not.

The best way to influence direction is to show up with working code and real results. "I ran this on 20 problems and it improved quality by 0.3 points on average" is more persuasive than a 2,000-word design doc.

← Previous Monitoring Back to Docs Home