brownfield-drift

Name: brownfield-drift
Author: wednesday-solutions

161stars19forks

How to install brownfield-drift?

wednesday-solutions/ai-agent-skills/brownfield-drift

$npx -y skills add wednesday-solutions/ai-agent-skills --skill brownfield-drift

Installs into the current project.

Summary

Enforces architecture boundaries defined in PLAN.md. Use when a PR crosses module/service boundaries, when the dev asks "are we following the architecture?", or as a scheduled architecture health check. Not for querying what a module does — use brownfield-chat for that.

Files · 1

View on GitHub

SKILL.md

1	## When to use
2	- Dev asks "are we following the architecture?" or "is this a valid change?"
3	- PR touches files near module boundaries or service interfaces
4	- Weekly architecture health check
5	- Any cross-service import was just added
6
7	## When NOT to use
8	- "What does module X do?" → use brownfield-chat
9	- "What breaks if I change X?" → use brownfield-chat
10	- Graph coverage is low on a file → use brownfield-fix (it fills gaps before editing)
11	- No PLAN.md exists — drift requires machine-readable boundaries in PLAN.md
12
13	## What to do
14	1. Run `wednesday-skills drift` via Bash tool
15	2. Report violations with:
16	- The specific edge that violates the rule
17	- The commit that introduced it (when available)
18	- The suggested fix per PLAN.md intent
19	3. For PR reviews: run `wednesday-skills drift --since <base-commit>` to only report new violations
20	4. For a single rule: `wednesday-skills drift --rule <rule-name>`
21
22	## Adding constraints to PLAN.md
23	If the project has no constraints block, add one to PLAN.md:
24
25	```json
26	{
27	"boundaries": [
28	{
29	"rule": "frontend-never-imports-db",
30	"description": "Frontend components must never import DB layer directly",
31	"from": "src/app/**",
32	"to": "src/lib/db/**",
33	"type": "forbidden"
34	},
35	{
36	"rule": "no-circular-deps",
37	"description": "No circular dependencies anywhere",
38	"scope": "**",
39	"type": "no-cycle"
40	}
41	]
42	}
43	```
44
45	## Violation types
46	\| Type \| What it catches \|
47	\|------\|----------------\|
48	\| `forbidden` \| Import from A → B that should never exist \|
49	\| `ownership` \| Logic pattern appearing outside its designated owner \|
50	\| `no-direct-import` \| Direct import between services that should use API \|
51	\| `no-cycle` \| Circular dependency between modules \|
52
53	## Never
54	- Auto-fix boundary violations — always ask the dev first
55	- Flag existing violations on a PR that did not introduce them (use `--since`)
56	- Run on projects without machine-readable PLAN.md constraints
57	- Report the same violation twice in one review session
58
59	## CLI reference
60	```bash
61	wednesday-skills drift # full check
62	wednesday-skills drift --rule frontend-never-imports-db # single rule
63	wednesday-skills drift --since abc1234 # new drift only (for PR review)
64	```

People who liked this also viewed

6 picks

Type

brownfield-drift

161stars19forks

View on GitHub

How to install brownfield-drift?

wednesday-solutions/ai-agent-skills/brownfield-drift

$npx -y skills add wednesday-solutions/ai-agent-skills --skill brownfield-drift

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	## When to use
2	- Dev asks "are we following the architecture?" or "is this a valid change?"
3	- PR touches files near module boundaries or service interfaces
4	- Weekly architecture health check
5	- Any cross-service import was just added
6
7	## When NOT to use
8	- "What does module X do?" → use brownfield-chat
9	- "What breaks if I change X?" → use brownfield-chat
10	- Graph coverage is low on a file → use brownfield-fix (it fills gaps before editing)
11	- No PLAN.md exists — drift requires machine-readable boundaries in PLAN.md
12
13	## What to do
14	1. Run `wednesday-skills drift` via Bash tool
15	2. Report violations with:
16	- The specific edge that violates the rule
17	- The commit that introduced it (when available)
18	- The suggested fix per PLAN.md intent
19	3. For PR reviews: run `wednesday-skills drift --since <base-commit>` to only report new violations
20	4. For a single rule: `wednesday-skills drift --rule <rule-name>`
21
22	## Adding constraints to PLAN.md
23	If the project has no constraints block, add one to PLAN.md:
24
25	```json
26	{
27	"boundaries": [
28	{
29	"rule": "frontend-never-imports-db",
30	"description": "Frontend components must never import DB layer directly",
31	"from": "src/app/**",
32	"to": "src/lib/db/**",
33	"type": "forbidden"
34	},
35	{
36	"rule": "no-circular-deps",
37	"description": "No circular dependencies anywhere",
38	"scope": "**",
39	"type": "no-cycle"
40	}
41	]
42	}
43	```
44
45	## Violation types
46	\| Type \| What it catches \|
47	\|------\|----------------\|
48	\| `forbidden` \| Import from A → B that should never exist \|
49	\| `ownership` \| Logic pattern appearing outside its designated owner \|
50	\| `no-direct-import` \| Direct import between services that should use API \|
51	\| `no-cycle` \| Circular dependency between modules \|
52
53	## Never
54	- Auto-fix boundary violations — always ask the dev first
55	- Flag existing violations on a PR that did not introduce them (use `--since`)
56	- Run on projects without machine-readable PLAN.md constraints
57	- Report the same violation twice in one review session
58
59	## CLI reference
60	```bash
61	wednesday-skills drift # full check
62	wednesday-skills drift --rule frontend-never-imports-db # single rule
63	wednesday-skills drift --since abc1234 # new drift only (for PR review)
64	```

People who liked this also viewed

6 picks

Type