---
name: Brownfield Drift
slug: brownfield-drift
category: Quality
description: Brownfield Drift checks code against PLAN.md boundaries to find architecture drift, cross-service imports, and circular dependencies. Use it in PR reviews or scheduled health checks when you need to verify a change follows the defined architecture.
github: "https://github.com/wednesday-solutions/ai-agent-skills/tree/main/skills/brownfield-drift"
language: JavaScript
stars: 168
forks: 21
install: "npx degit https://github.com/wednesday-solutions/ai-agent-skills/tree/main/skills/brownfield-drift ~/.claude/skills/brownfield-drift"
installs_to: ~/.claude/skills/brownfield-drift
source_path: skills/brownfield-drift/SKILL.md
collection_size: 10
category_size: 1897
collection_url: "https://dirskills.com/collections/wednesday-solutions/ai-agent-skills"
added: 2026-09-08T05:34:06.301Z
last_synced: 2026-09-08T05:34:06.301Z
canonical_url: "https://dirskills.com/skills/brownfield-drift"
---

# Brownfield Drift

Brownfield Drift checks code against PLAN.md boundaries to find architecture drift, cross-service imports, and circular dependencies. Use it in PR reviews or scheduled health checks when you need to verify a change follows the defined architecture.

**Install:**

```bash
npx degit https://github.com/wednesday-solutions/ai-agent-skills/tree/main/skills/brownfield-drift ~/.claude/skills/brownfield-drift
```

## README

## When to use
- Dev asks "are we following the architecture?" or "is this a valid change?"
- PR touches files near module boundaries or service interfaces
- Weekly architecture health check
- Any cross-service import was just added

## When NOT to use
- "What does module X do?" → use **brownfield-chat**
- "What breaks if I change X?" → use **brownfield-chat**
- Graph coverage is low on a file → use **brownfield-fix (it fills gaps before editing)**
- No PLAN.md exists — drift requires machine-readable boundaries in PLAN.md

## What to do
1. Run `wednesday-skills drift` via Bash tool
2. Report violations with:
   - The specific edge that violates the rule
   - The commit that introduced it (when available)
   - The suggested fix per PLAN.md intent
3. For PR reviews: run `wednesday-skills drift --since <base-commit>` to only report new violations
4. For a single rule: `wednesday-skills drift --rule <rule-name>`

## Adding constraints to PLAN.md
If the project has no constraints block, add one to PLAN.md:

```json
{
  "boundaries": [
    {
      "rule": "frontend-never-imports-db",
      "description": "Frontend components must never import DB layer directly",
      "from": "src/app/**",
      "to": "src/lib/db/**",
      "type": "forbidden"
    },
    {
      "rule": "no-circular-deps",
      "description": "No circular dependencies anywhere",
      "scope": "**",
      "type": "no-cycle"
    }
  ]
}
```

## Violation types
| Type | What it catches |
|------|----------------|
| `forbidden` | Import from A → B that should never exist |
| `ownership` | Logic pattern appearing outside its designated owner |
| `no-direct-import` | Direct import between services that should use API |
| `no-cycle` | Circular dependency between modules |

## Never
- Auto-fix boundary violations — always ask the dev first
- Flag existing violations on a PR that did not introduce them (use `--since`)
- Run on projects without machine-readable PLAN.md constraints
- Report the same violation twice in one review session

## CLI reference
```bash
wednesday-skills drift                              # full check
wednesday-skills drift --rule frontend-never-imports-db  # single rule
wednesday-skills drift --since abc1234              # new drift only (for PR review)
```