Skip to content

AGENTS.md

Latest commit

 

History

History
214 lines (150 loc) · 5.49 KB

AGENTS.md

File metadata and controls

214 lines (150 loc) · 5.49 KB

AGENTS.md — Nexus Development Standards

This repository is being built iteratively with the assistance of coding agents (e.g. Claude Code). All contributors (human or agent) MUST follow these standards.

1. Golden Rules

  1. Work milestone-by-milestone

    • Implement ONLY the requested milestone scope.
    • Do not start future milestones early.

  2. No broken builds

    • All changes must build and run locally.
    • All tests must pass before considering work complete.

  3. No undocumented behaviour

    • If you add or change functionality, update the relevant docs.

  4. No silent complexity

    • Prefer simple, explicit code over clever abstractions.
    • Leave clear comments where logic is non-obvious.

  5. Capture workflow instructions in AGENTS.md

    • When the user provides instructions about approaches, processes, or ways of working, add them to this file.

2. Tech Stack

Component Dev Prod
Language Python 3.11+ Python 3.11+
LLM gpt-oss-20b (Ollama) GPT-5.2 (OpenAI API)
Embeddings Nomic Embed Text V2 (Ollama) Nomic Embed Text V2
Vector Store ChromaDB ChromaDB
CLI Framework Typer Typer
Config Pydantic Settings Pydantic Settings
Logging structlog (JSON) structlog (JSON)
Runtime Docker Compose Docker Compose

3. Testing Requirements (Mandatory)

Every milestone MUST include automated tests.

3.1 Test Layers

  1. Unit tests — Pure logic (chunker, context builder, citation validator)
  2. Integration tests — Component interactions (embedder + ChromaDB, LLM client)
  3. Smoke tests — Full pipeline works end-to-end

3.2 Minimum Standards

  • All new logic must have corresponding tests.
  • Critical functions (citation validation, guardrails) require high coverage.
  • CI checks must pass: pytest, ruff check, mypy.

3.3 Manual Verification (Required)

Before considering work complete:

  1. Rebuild containers — docker compose build
  2. Start services — docker compose up -d
  3. Verify manually — Run CLI commands against real services
  4. Test edge cases — Empty repos, large files, unsupported questions

4. Developer Commands

# Start development environment
docker compose up -d

# Run tests
pytest

# Run linting
ruff check .

# Run type checking
mypy .

# Run all CI checks
pytest && ruff check . && mypy .

# Build Docker image
docker compose build

# View logs
docker compose logs -f nexus

5. Documentation Requirements

5.1 Evergreen Docs

  • README.md — Quickstart, usage, architecture overview
  • docs/DECISIONS.md — Architecture decision records
  • docs/plans/ — Design documents per milestone

5.2 Changelog Discipline

Update README.md or create CHANGELOG.md with:

  • What was added/changed
  • How to verify locally
  • Tests added

6. Code Standards

6.1 Docstrings

All public functions must include docstrings:

def retrieve_chunks(query: str, top_k: int = 8) -> list[Chunk]:
    """Retrieve relevant chunks for a query.

    Args:
        query: The natural language question.
        top_k: Maximum number of chunks to return.

    Returns:
        List of Chunk objects with metadata and similarity scores.

    Raises:
        RetrievalError: If ChromaDB connection fails.
    """

6.2 Inline Comments

Add comments for:

  • Complex regex patterns (citation extraction)
  • Security-sensitive logic (input validation)
  • Non-obvious algorithmic choices (chunking overlap)

6.3 Type Hints

All functions must have complete type hints. No Any unless unavoidable.

7. Current Scope

Milestone 0 (Complete)

  • Repository scaffold
  • Dependencies pinned
  • CLI entrypoints scaffolded
  • Docker Compose files
  • Configuration setup

Milestone 1 (Complete)

  • Ingestion pipeline (walker, chunker, embedder, index)
  • nexus ingest <repo> functional

Milestone 2 (Complete)

  • Semantic search (top-k, threshold, diversity)
  • Context builder (prompt assembly)
  • LLM answer generation
  • nexus ask "<question>" functional

Milestone 3 (Complete)

  • Post-hoc citation validation with full rejection
  • Structured logging (structlog, JSON/console)
  • Bracketed inline citation format

Milestone 4 (Complete)

  • Eval harness with hit-rate reporting
  • README finalised with all spec sections
  • Docker packaging verified

Out of Scope

  • Web UI
  • Authentication
  • Multi-tenancy
  • Distributed indexing

8. Milestone Completion Checklist

Before declaring a milestone complete:

  • Summary of changes provided
  • Verification steps documented
  • Tests added/updated
  • CI passes locally
  • Docs updated
  • User has validated manually

9. Pre-Commit Validation (Mandatory)

Before committing milestone work:

  1. Rebuild — docker compose build
  2. Run tests — pytest
  3. Run lints — ruff check . && mypy .
  4. Ask for validation — Provide specific steps
  5. Wait for approval — Only commit after user confirms

10. Embedding Instruction Prefixes

Nomic Embed Text V2 requires instruction prefixes:

  • Documents: search_document: <content>
  • Queries: search_query: <question>

Omitting these prefixes significantly degrades retrieval quality.

11. Citation Format

All answers must include citations in this format:

relative/path/to/file.ext:start_line-end_line

Examples:

  • src/auth/login.py:45-92
  • README.md:1-25

Invalid citations (files not in retrieved context) must be rejected.