| name | system-supervisor |
| category | architecture |
| version | 1.0.0 |
| priority | P1 |
| auto_load | true |
| triggers | ["new_file_creation","new_abstraction","new_dependency","schema_addition","api_route_addition","component_creation","refactor","architecture_discussion"] |
| description | Apply this skill before creating new files, new abstractions, new dependencies, new
API routes, new database tables, or new components. Detects architectural drift,
complexity accumulation, and pattern violations before they get committed.
Also applies when reviewing existing code for structural issues.
P1 auto-load โ always active when the system structure changes.
|
| context | fork |
System Supervisor
The Default Being Overridden
Left unchecked, LLMs default to:
- Parallel creation: Adding a new file/function/abstraction that duplicates one already existing, because the existing one wasn't checked for
- Complexity ratchet: Each session adds complexity; no session removes it; over time the codebase drifts from its design patterns
- Premature abstraction: Creating helper utilities, shared functions, and wrappers for single-use operations
- Unchecked dependency growth: Adding packages without considering their cost (bundle size, maintenance burden, conflict risk)
- Pattern amnesia: Implementing a pattern differently from how it's already done elsewhere in the same codebase
- Silent accumulation: File counts, function counts, and dependency counts grow without any awareness or concern
This skill overrides those defaults with a structural awareness layer.
Pre-Creation Check (Run Before Creating Anything New)
Before creating a new file, function, component, hook, utility, or API route:
Pre-creation check for: [thing being created]
โก Does something serving this purpose already exist?
โ Search: grep for the function name, class name, or similar purpose
โ If found: extend or reuse it โ do not create a parallel
โก Is this abstraction used in more than one place?
โ If NO: inline it โ don't extract a helper for a single caller
โ If YES: extract to the appropriate shared location
โก Does this follow the existing pattern for its category?
โ Check: how are other [API routes / components / hooks / services] in this codebase structured?
โ Mirror the structure โ do not invent a new convention
โก What is the dependency cost?
โ New package: check bundle size impact, update frequency, alternatives
โ Built-in alternative: prefer native APIs over packages when they're sufficient
If any check fails, resolve it before proceeding.
Drift Detection Signals
These are signals that architectural drift is occurring. Flag them when spotted:
Signal 1: Naming inconsistency
The same concept has multiple names in different parts of the codebase (e.g., founderId, founder_id, userId, createdBy all referring to the same auth.uid()).
Action: Standardise the name. Pick the convention used in the database schema and propagate it.
Signal 2: Pattern divergence
Two API routes that do similar things but are structured differently (e.g., one uses Zod validation, one uses manual type guards; one returns , another returns the object directly).
