AI and agents
Agent skill dma — setup for Cursor and other assistants, workflow with check --format json.
LLM assistants write code fast, but often "improve" architecture using FSD-style patterns: inventing widgets/, entities/, barrel index.ts, pulling feature → feature. DMA relies on the graph and tooling, not model taste.
An agent skill is a compact instruction for the agent: placement algorithm, list of prohibitions, links to the spec. The skill does not replace dma check — it guides the agent before merge; the CLI remains the gate in CI.
What's inside the dma skill
Source in the repository: skills/dma.
| Section | Contents |
|---|---|
| Placement algorithm | Where to put a file — same steps as Where to put a file |
| Import cheat sheet | Dependency direction, */public/*, import type = edge |
| Agent workflow | Inspect → place/move → verify via CLI |
| Refuse / rewrite | Barrels, feature→feature, premature shared/, ports instead of promotion |
| Linter matrix | ESLint / Oxlint / Biome — file-scoped, not full graph |
| When to open more | spec, reference.md, examples, fixtures |
The normative SoT for the agent is spec/. The skill is a compressed checklist, not a replacement for the specification.
Installation
Via skills.sh (Cursor, Claude Code, and other hosts with skills support):
npx skills add mikhailmogilnikov/derived-modular-architecture --skill dmaList skills in the repository:
npx skills add mikhailmogilnikov/derived-modular-architecture --listManual setup
Copy or symlink the skills/dma folder into your editor's skills directory (for example ~/.cursor/skills/dma or .cursor/skills/dma at the project root). The SKILL.md file must be available to the agent as a skill.
Recommended agent workflow
- Read the tree — actual
src/{app\|pages\|routes,features,services?,shared}and imports; do not assume FSD layers. - Place / move using the algorithm; imports go through direct paths to
*/public/*. - Verify with CLI (if the package is installed in the project):
npx @derived-modular/cli check . --format json
npx @derived-modular/cli doctor . --format json| Exit code | Meaning |
|---|---|
0 | OK (for doctor — warnings may appear, CI is not broken) |
1 | check found violations — fix before merge |
2 | Environment: missing src/, tsconfig, invalid arguments |
- Do not "fix" barrels, deep imports, empty
services/, or ports to bypass legitimate promotion. - In CI still run
check— the agent may not have run the CLI or may have missed an edge case.
"The agent said the architecture is fine" is not an argument. The only hard gate is npx @derived-modular/cli check in CI (and locally before push).
JSON for automation
The --format json flag produces a stable report (version: 1) — convenient for CI, scripts, and agents:
npx @derived-modular/cli check . --format json
npx @derived-modular/cli doctor . --format jsonThe ruleId, severity, file, and message fields match the violation reference and doctor signals.
SARIF is for GitHub Code Scanning; see CI.
Skill + linter + CLI
Agent (skill) → where to put a file, what not to invent
Editor (lint) → four file-scoped rules on save
CI (dma check) → full graph, cycles, inbound predicatesThe skill and ESLint/Biome do not see no-cycle and feature-has-inbound — only the CLI does. See Tooling overview and Why CLI, not linters only.
AGENTS.md in your project
In your own repository you can duplicate key rules in AGENTS.md (check commands, barrel prohibition). The dma skill is a ready-made variant with the algorithm and refuse list; use the skill if you do not want to maintain your own file manually.
Minimum for a DMA project in any case:
{
"scripts": {
"dma-check": "npx @derived-modular/cli check ."
}
}And a line in CI — see CI.
What the skill does not do
| Not the skill | Why |
|---|---|
| CI gate | Only dma check with exit code |
| Domain cut choice | Conway — on the team; see What DMA does not decide |
| Import autofix | Manual refactor + re-run check |
| Spec replacement | Skill references spec; on conflict, tooling + spec win |