GitHub Copilot - Nomarr Architecture Enforcer

Enforces architectural rules, tool usage hierarchy, and quality standards for the Nomarr pre-alpha codebase. Ensures proper layer separation, dependency injection patterns, and MCP tool usage.

Core Requirements

1. Read Layer Skills Before Editing (MANDATORY)

**Never edit code without first reading the relevant layer skill file.**

Before modifying any file, identify its layer and read the corresponding skill:

| Path Pattern | Skill File to Read |

|--------------|-------------------|

| `nomarr/interfaces/` | `.github/skills/layer-interfaces/SKILL.md` |

| `nomarr/services/` | `.github/skills/layer-services/SKILL.md` |

| `nomarr/workflows/` | `.github/skills/layer-workflows/SKILL.md` |

| `nomarr/components/` | `.github/skills/layer-components/SKILL.md` |

| `nomarr/persistence/` | `.github/skills/layer-persistence/SKILL.md` |

| `nomarr/helpers/` | `.github/skills/layer-helpers/SKILL.md` |

| `frontend/` | `.github/skills/layer-frontend/SKILL.md` |

Skills contain authoritative guidance on naming, boundaries, imports, and validation requirements.

2. Use MCP API Discovery Before Modifications (MANDATORY)

**Never guess at module APIs — discover them first.**

Before editing any Python module, run:

```bash

mcp_nomarrdev_discover_api("module.path.here")

```

Use discovered signatures as source of truth. Do not proceed without verifying existing API shapes.

3. Run Layer Validation Scripts (MANDATORY)

After making changes, run the layer's validation script:

```powershell

Services layer

python .github/skills/layer-services/scripts/check_naming.py

Persistence layer

python .github/skills/layer-persistence/scripts/check_naming.py

Interfaces layer

python .github/skills/layer-interfaces/scripts/check_naming.py

```

Run additional checks (lint, mypy, build) if specified by the layer skill.

Tool Usage Hierarchy (Enforce Strictly)

Priority 1: Python Code Navigation (Nomarr-Specific)

**Always use these tools first for Python exploration:**

`mcp_nomarrdev_discover_api(module_name)` — See exported classes/functions/signatures

`mcp_nomarrdev_locate_symbol(symbol_name)` — Find where symbols are defined

`mcp_nomarrdev_get_source(qualified_name)` — Get exact function/class source with line numbers

`mcp_nomarrdev_trace_endpoint(endpoint)` — Trace FastAPI routes through DI layers

`mcp_nomarrdev_trace_calls(function)` — Follow call chains from entry points

`mcp_nomarrdev_check_api_coverage()` — See which endpoints are used by frontend

These tools understand FastAPI dependency injection and Nomarr's layered architecture.

Priority 2: General Code Navigation

**For file exploration and symbol finding:**

`mcp_oraios_serena_get_symbols_overview(relative_path)` — View file structure before reading

`mcp_oraios_serena_find_symbol(name_path_pattern, relative_path)` — Find and get symbol bodies

`mcp_oraios_serena_search_for_pattern(substring_pattern)` — Regex search with context

`mcp_oraios_serena_find_referencing_symbols(name_path, relative_path)` — See who calls what

Priority 3: Library Documentation

**Before guessing external library APIs:**

`mcp_context7_resolve_library_id(libraryName)` → `get_library_docs(context7CompatibleLibraryID)`

Get authoritative documentation instead of making assumptions.

Priority 4: Memory & Knowledge Persistence

**Check memories at task start, update at task end:**

`mcp_oraios_serena_list_memories()` — List available memories

`mcp_oraios_serena_read_memory(memory_file_name)` — Read relevant architectural context

`mcp_oraios_serena_write_memory(memory_file_name, content)` — Persist discoveries and patterns

Priority 5: Standard Tools (Last Resort Only)

**Only use when MCP tools cannot accomplish the task:**

`read_file` — Only when Serena/nomarrdev cannot access content

`grep_search` — Only for non-code files or when pattern search fails

`semantic_search` — Only when symbol-based navigation is insufficient

Architectural Rules (Enforce Strictly)

Dependency Direction

```

interfaces → services → workflows → components → (persistence / helpers)

```

**Interfaces** call services only

**Services** own wiring, call workflows

**Workflows** implement use cases, call components

**Components** contain heavy logic, call persistence/helpers

**Persistence/helpers** never import higher layers

Import-linter enforces these boundaries.

Hard Prohibitions

**Never:**

Import `essentia` anywhere except `components/ml/ml_backend_essentia_comp.py`

Read config or environment variables at module import time

Create or mutate global state

Rename `_id` or `_key` (ArangoDB-native identifiers)

Let workflows import services or interfaces

Let helpers import any `nomarr.*` modules

**Always:**

Use dependency injection (receive db, config, backends as parameters)

Write fully type-annotated code

Run API discovery before calling unfamiliar modules

Verify virtual environment is active before running Python commands

Pre-Alpha Policy

Nomarr is pre-alpha. Breaking changes are acceptable. No migrations, legacy shims, or compatibility layers. Prioritize clean architecture over preserving old data.

Quality Assurance

Discovery Scripts

```bash

Discover module API before calling it

python scripts/discover_api.py nomarr.components.ml

Run all quality control checks

python scripts/run_qc.py

Find complexity/violations in specific file

python scripts/detect_slop.py nomarr/workflows/some_wf.py

```

For detailed tool usage, see `.github/skills/quality-analysis/` and `.github/skills/code-discovery/`.

Workflow

1. **Identify layer** from file path

2. **Read corresponding skill** from `.github/skills/layer-*/SKILL.md`

3. **Use MCP tools** to discover existing APIs and symbols

4. **Check memories** for relevant architectural context

5. **Make changes** following layer conventions

6. **Run validation scripts** for the modified layer

7. **Update memories** if new patterns or decisions were made

8. **Verify dependency direction** with import-linter if needed

Constraints

This skill enforces Nomarr-specific architecture patterns

MCP tool usage is mandatory, not optional

Layer skills are authoritative — do not deviate without explicit approval

Breaking changes are acceptable in pre-alpha; clean architecture is the priority

GitHub Copilot - Nomarr Architecture Enforcer

GitHub Copilot - Nomarr Architecture Enforcer

Core Requirements

1. Read Layer Skills Before Editing (MANDATORY)

2. Use MCP API Discovery Before Modifications (MANDATORY)

3. Run Layer Validation Scripts (MANDATORY)

Services layer

Persistence layer

Interfaces layer

Tool Usage Hierarchy (Enforce Strictly)

Priority 1: Python Code Navigation (Nomarr-Specific)

Priority 2: General Code Navigation

Priority 3: Library Documentation

Priority 4: Memory & Knowledge Persistence

Priority 5: Standard Tools (Last Resort Only)

Architectural Rules (Enforce Strictly)

Dependency Direction

Hard Prohibitions

Pre-Alpha Policy

Quality Assurance

Discovery Scripts

Discover module API before calling it

Run all quality control checks

Find complexity/violations in specific file

Workflow

Constraints

Reviews (0)