SkinbaseNova/.copilot/inctructions.md

Copilot Instructions – Artworks Module (SkinBase)

This file defines HOW Copilot must generate code. It is a strict instruction set. If there is a conflict between generated code and these rules, these rules override everything.

---

1. Global Rules (MANDATORY)

Copilot MUST:

• Target Laravel 12
• Use PHP 8.3+ syntax
• Follow Eloquent best practices
• Respect SoftDeletes
• Respect FK relationships
• Generate clean, readable, maintainable code

Copilot MUST NOT:

• Reference legacy tables (wallz, old categories, old views)
• Generate MyISAM tables
• Generate hard deletes for user content
• Put counters on hot tables
• Use IDs in URLs
• Mix responsibilities across models

---

2. Authoritative Schema Reference

The canonical schema for artworks is defined in:

.copilot/artworks.md

Copilot MUST:

• Read this file before generating any code
• Match table names, columns, relations exactly
• Never invent fields or tables unless explicitly allowed

---

3. Models Generation Rules

When generating Eloquent models:

Required models

Copilot MUST generate:

• App\Models\Artwork
• App\Models\ArtworkTranslation
• App\Models\ArtworkStats
• App\Models\ArtworkComment
• App\Models\ArtworkDownload

Model requirements

Each model MUST:

• Declare $fillable
• Define all relationships
• Use SoftDeletes only when allowed
• Include PHPDoc blocks for relations
• Use type-hinted return values

Forbidden

Copilot MUST NOT:

• Add business logic into models
• Perform stat mutations in models
• Use observers unless explicitly requested

---

4. Relationships (STRICT)

Copilot MUST implement these exact relations:

Artwork

belongsTo(User::class)
hasMany(ArtworkTranslation::class)
hasOne(ArtworkStats::class)
belongsToMany(Category::class)
hasMany(ArtworkComment::class)
hasMany(ArtworkDownload::class)

ArtworkTranslation

belongsTo(Artwork::class)

ArtworkStats

belongsTo(Artwork::class)

ArtworkComment

belongsTo(Artwork::class)
belongsTo(User::class)

ArtworkDownload

belongsTo(Artwork::class)

---

5. Query & Scope Rules

Copilot MUST define these scopes on Artwork:

scopePublic($query)
scopeApproved($query)
scopePublished($query)

Public queries MUST always include:

deleted_at IS NULL
is_public = true
is_approved = true

Copilot MUST NOT:

• Eager-load stats in list views
• Use offset pagination for feeds
• Load unnecessary relations by default

---

6. Controller Generation Rules

When generating controllers:

Copilot MUST:

• Use thin controllers
• Delegate logic to services/actions if needed
• Validate input using Form Requests
• Use route-model binding with slug
• Handle soft-deleted content properly

Copilot MUST NOT:

• Query raw DB tables directly
• Bypass scopes
• Return unfiltered content

---

7. Routing Rules

Routes MUST:

• Use slug-based routing
• Never expose numeric IDs
• Respect category hierarchy
• Be SEO-friendly

Example (valid):

/photography/abstract/dark/night-city

Invalid:

/artwork/123

---

8. Soft Delete Rules

Copilot MUST:

• Use delete() (soft delete) for user content
• Use restore() for recovery
• Use forceDelete() only when explicitly requested

When content is soft-deleted:

• It must disappear from public browsing
• It must remain accessible to admins

---

9. Stats & High-Load Rules

Copilot MUST:

• Treat stats as derived data
• Update stats via jobs / services
• Never increment counters inline in controllers
• Assume Redis may be present

Copilot MUST NOT:

• Store counters on artworks
• Use increment() directly on hot rows

---

10. Search Rules

Copilot MAY:

• Use MySQL FULLTEXT
• Use external search engines (if requested)

Copilot MUST NOT:

• Search file paths
• Search binary metadata
• Assume Elasticsearch exists unless specified

---

11. Forbidden Patterns (NEVER GENERATE)

❌ Hard deletes on artworks ❌ Legacy column names ❌ Polymorphic abuse ❌ Fat controllers ❌ Magic numbers ❌ Inline SQL in controllers ❌ Business logic in migrations

---

12. Extension Rules

Copilot MAY generate new features ONLY if:

• They do not modify core tables
• They follow the same architectural principles
• They are isolated in new tables/services

Allowed examples:

• tags
• EXIF metadata
• versioning
• reporting/flagging
• API resources

---

13. Error Handling

Copilot MUST:

• Throw meaningful exceptions
• Return proper HTTP codes
• Use 404 for missing public content
• Use 410 or 301 for deleted content (if requested)

---

14. Final Instruction (ABSOLUTE)

Copilot must treat this file and artworks.md as non-negotiable contracts.

If unsure:

• ask for clarification
• do NOT guess
• do NOT invent schema

---

✅ End of Copilot Instructions