build-loop:architecture-rules

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->

# Architecture Rules / Violation Check

Run NavGator's rules engine to detect architectural violations using the `mcp__plugin_navgator__rules` MCP tool. Classifies findings as blocking (circular dependency, layer violation, database isolation breach, frontend-direct-DB at error level) vs warning (hotspot, high-fan-out, orphan, shallow-module).

> **Divergence note**: NavGator has no discrete SKILL.md for rules. The canonical wrapper is `commands/test.md`, which orchestrates `navgator rules` + `navgator dead` + pipeline traces. This skill extracts the rules-only workflow.

## When to Activate

- Phase 4 Review-D Fact-Check: when code changed in this build, run rules to detect new violations
- Phase 1 Assess: optionally run as a baseline so Review-D can diff
- User asks "any architecture violations", "is this safe to merge", "what did I break"

## Pre-flight

1. If `.navgator/architecture/index.json` does not exist → no-op with `NavGator: no architecture snapshot found — skipping rules check`. Recommend `build-loop:architecture-scan`.
2. Check `index.json` `generated_at` timestamp. If >24 hours old, warn: "Architecture data is N hours old — consider running `build-loop:architecture-scan` first for accurate results."

## Rules Workflow

1. Run `mcp__plugin_navgator__rules` (or `navgator rules --json`)
2. Classify each finding:

| Severity | Categories |
|----------|-----------|
| **Blocking** | `circular-dependency`, `layer-violation`, `database-isolation`, `frontend-direct-db` (error level) |
| **Warning** | `hotspot`, `high-fan-out`, `orphan`, `shallow-module` (thin pass-through: high fan-out, low fan-in — advisory design guidance, never blocks) |

3. Diff against the Phase 1 baseline if present in `.build-loop/state.json.architecture.rules.baseline`
4. Flag recurrences against `.navgator/lessons/lessons.json` (lessons with matching `signature`)
5. Write the result to `.build-loop/state.json.architecture.rules` with `{blocking_count, warning_count, new_violations[], recurrences[]}`

## Decision

- **Blocking findings** → route back to Phase 5 Iterate with the violation as a fresh criterion
- **Warning findings** → log to `.build-loop/issues/` and surface in Review-F Report
- **No new violations** → continue Review pipeline; report "No new architectural violations introduced"

## Report Format

```
ARCHITECTURE RULES
==================
Blocking: N (N new this build)
Warnings: N (N new this build)
Recurrences against lessons: N

[BLOCKING] Layer violation: ComponentA (frontend) → ComponentB (database)
  File: src/pages/users.tsx:45
  Recurrence: matches lesson 'frontend-direct-db' (last seen 2026-03-15)
```

If no findings: report "No connection-integrity issues found" — do not omit the section.

## Sibling Skills

- `build-loop:architecture-scan` — refresh data first
- `build-loop:architecture-impact` — pre-flight blast-radius for any blocking finding's affected component
- `build-loop:architecture-dead` — orphan-only scan (warnings flagged here too)
- `build-loop:architecture-review` — runs rules as part of a 5-phase integrity review

*Source: NavGator `commands/test.md` (the orchestrator that calls `navgator rules`). The canonical rules engine is the MCP tool. Drift-checked by `build-loop:sync-skills`.*

From tyroneross/build-loop, Apache-2.0.

More from tyroneross/build-loop