Inconsistent resource design within API

How to fix

1. Align route naming and response shape with adjacent resources.
2. Document intentional exceptions in the API style ADR.
3. Update clients and contracts together.

What the rule validates

Related API endpoints appear to model resources inconsistently.

Why it matters

Consistent resource design improves client ergonomics and contract review.

Common causes

• Endpoints were added by different teams without a shared convention.
• A resource was renamed in code but not in the contract.
• Action-style routes mix with resource-style routes unnecessarily.

Typical violation example

The API mixes /teams/:id/system, /systemTeams, and /assign-system for the same relationship.

Typical compliant example

Relationship operations use one documented resource naming pattern.

Related rules

Adjacent categories

Related files/config

• contracts/openapi.yaml
• apps/api/src

Related CLI commands

• archpilot validate
• archpilot validate --ci