---
id: kb-004
title: Project Alignment - Implementation Guide
scope:
  type: project
  id: 4sgm
purpose: alignment-implementation-guide
tags:
  - infrastructure
  - alignment
  - implementation-guide
topics:
  - engineering
  - devops
version: 1
created: 2025-11-26
updated: 2025-11-26
author: droid-agent
status: final
related_ids:
  - kb-002
  - kb-003
external_refs: []
---

# Project Alignment - Implementation Guide

This guide provides step-by-step instructions for aligning the infrastructure of `agentapi/atomsAgent` and `atoms-mcp-prod`.

## Phase 1: CRITICAL (Weeks 1-2)

### 1. Upgrade fastmcp (atomsAgent)
**Goal:** Align with atoms-mcp-prod's version (2.13.1+).

```bash
# Update pyproject.toml
uv add "fastmcp>=2.13.1"
```

### 2. Pin Python Version (atomsAgent)
**Goal:** Ensure consistent environment across local and CI.

```toml
# In pyproject.toml
[project]
requires-python = "==3.12.*"
```

### 3. Add Coverage Threshold (atomsAgent)
**Goal:** Maintain high code quality.

```toml
# In pyproject.toml
[tool.pytest.ini_options]
addopts = "--cov=src --cov-report=term-missing --cov-fail-under=95"
```

### 4. Add Test Artifact Uploads (atomsAgent)
**Goal:** Visibility into test failures in CI.

```yaml
# In .github/workflows/ci.yml
- name: Upload test results
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: pytest-results
    path: junit.xml
```

---

## Phase 2: TESTING (Weeks 2-3)

### 1. Enhanced Test Reporting
Copy `enhanced-testing.yml` from `atoms-mcp-prod` to `atomsAgent`.

### 2. Consolidate Pytest Markers
Standardize markers in `pyproject.toml`.

```toml
[tool.pytest.ini_options]
markers = [
    "unit: Quick unit tests",
    "integration: Integration tests",
    "e2e: End-to-end tests",
    "slow: Tests taking > 1s"
]
```

---

## Phase 3: QUALITY (Weeks 3-4)

### 1. Align Ruff Configuration
Merge explicit rules from `atomsAgent` with `atoms-mcp-prod`.

### 2. Align MyPy Configuration
Adopt comprehensive config from `atoms-mcp-prod`.

---

## Phase 4: ORGANIZATION (Weeks 3-4)

### 1. Create scripts/README.md
Document all utility scripts.

### 2. Create TESTING.md
Complete guide for running and writing tests.

---

## Phase 5: VERIFICATION (Week 4)

### 1. Run All Checks
```bash
uv run ruff check .
uv run mypy .
uv run pytest
```

### 2. Verify CI/CD
Ensure all workflows pass and artifacts are uploaded.
