asset-library-organization-planner

name	asset-library-organization-planner
description	Plan an internal asset library structure (folders, naming, metadata, license tracking, version control) so future recipes find and reuse assets reliably.

asset-library-organization-planner

Purpose

Set up a maintainable internal asset library so future recipes can:

• find existing assets quickly,
• avoid re-licensing the same source,
• reuse PBR materials and HDRIs,
• track versions and revisions.

Quick start

• pin folder structure (kebab-case, by category)
• pin naming convention (asset name + version + license slug)
• pin metadata schema (license, source, date, version, hash)
• pin version control rules (LFS for large binaries, plain text for metadata)
• emit a library-init plan

When to use

• starting a new BlendOps repo with multiple recipes
• existing library is disorganized; recipes can't find assets
• before scaling to 50+ assets

When not to use

• single-recipe repo with < 5 assets
• pure planning before any asset is sourced
• as a substitute for license check (use asset-license-checker)

Trigger phrases

• "organize the assets"
• "asset library structure"
• "where should assets go"
• "name our assets"

Prerequisites / readiness

• baseline asset count + categories known
• version control system known (git + LFS / Perforce / DAM)
• internal team conventions (if any)

Input schema

Required inputs

Input	Why it is required
Asset categories	Drives folder structure
Version control system	Drives binary storage rules
Existing convention (if any)	Maintain consistency

Optional inputs

Input	Use
Team size	Affects review process
Cloud storage / DAM	Alternative storage path

Assumptions to confirm

• The library is shared across future recipes.
• License metadata must be queryable.
• Versioning is discrete (not "latest" symlinks; pinned versions).

Output schema

Primary output

A library plan: folder tree, naming convention, metadata schema, version control rules, license tracking strategy.

Secondary output

• migration steps if existing assets need re-organizing
• review process for adding new assets
• evidence label

Evidence / caveat output

Runtime status: Not Run | Attempted | Produced | Verified | Failed | Blocked / Not Run
Artifact status: Not Run | Not Produced | Produced | Verified | Failed
Evidence used: <links, paths, logs, or "none">
Limitations: <known gaps>

Required laws

• ../../laws/evidence-before-done.md
• ../../laws/non-blender-user-language.md
• ../../laws/no-arbitrary-python-interface.md
• ../../laws/official-runtime-only.md

Official runtime boundary

Planning skill — does not move files, does not run Blender, does not configure version control. Outputs a structure spec.

Operating procedure

1. Read asset categories.
2. Pin folder structure (see references/folder-structure-rules.md).
3. Pin naming convention (see references/naming-rules.md).
4. Pin metadata schema (see references/metadata-schema.md).
5. Pin version control rules (LFS thresholds, branching).
6. Pin license tracking (one license file per asset folder).
7. Recommend a review process for new asset additions.
8. Emit library-init plan + migration steps.

Decision tree

< 50 total assets?
  → Simple flat structure may suffice
50-500 assets?
  → Categorical folders + subfolders
500+ assets?
  → DAM (Digital Asset Management) tool recommended
Mostly small files (< 50MB each)?
  → Plain git OK
Mixed sizes including > 50MB?
  → Git LFS or external storage
> 1GB total?
  → External DAM strongly recommended

Playbooks

Playbook A: Small repo (< 50 assets)

Flat folders by category: assets/models/, assets/textures/, assets/hdris/, assets/fonts/. One README + LICENSES.md per folder.

Playbook B: Medium repo (50-500 assets)

Nested by category + sub-category: assets/models/products/, assets/models/characters/, assets/textures/pbr/, etc. Per-asset LICENSE.txt + metadata.json.

Playbook C: Large repo (500+)

External DAM (e.g. Tractor, Razuna, custom) + git pointer files. Library plan focuses on naming + metadata schema; storage is offloaded.

Mode handling

Text-only mode

Library plan only.

Runtime-ready mode

Plan + recommended directory creation steps (operator runs them; this skill does not).

Blocked runtime mode

Plan only.

Validation checklist

• Folder structure pinned
• Naming convention pinned
• Metadata schema pinned
• Version control rules pinned
• License tracking strategy pinned
• Review process for new assets
• Migration steps (if existing library)

Pass / Warn / Fail rubric

Verdict	Criteria
Pass	All sections pinned + migration plan if needed + review process.
Warn	One section soft (e.g. metadata schema partial).
Fail	"Just dump in a folder" advice; no naming convention; no license tracking.

Failure handling

• Existing library cannot be reorganized → plan a parallel new library + gradual migration.
• VCS not in place → recommend git or alternative before any asset commit.
• Team lacks process discipline → recommend lightweight review checklist (1-page).

Troubleshooting

Problem	Response
Asset duplicates across folders	Add a hash check; deduplicate before re-organizing.
Lost license info on old assets	Mark as Quarantine; do not use until re-licensed.
Naming inconsistency	Apply convention to new only; rename old in batches with care.

Best practices

• One library, one source of truth.
• License lives next to the asset, always.
• Naming convention is unforgiving; enforce in code review.
• Avoid deeply-nested folders (> 4 levels gets confusing).

Good examples

• "assets/models/products/sneaker-v01-cc0.glb + assets/models/products/sneaker-v01-cc0.metadata.json + assets/models/products/sneaker-v01-cc0.LICENSE.txt"

Bad examples

• "Just use a Drive folder." — no version, no license tracking.

User-facing response template

Library size estimate: <N assets>
VCS: <git / git+lfs / DAM>

Folder structure:
  <tree>

Naming convention: <pattern + examples>

Metadata schema (per asset):
  <fields>

Version control:
  <rules>

License tracking: <strategy>

Review process: <1-page checklist>

Migration steps (if applicable): <list>
Limitations: <gaps>
Next: implement plan; future recipes use this library

Anti-patterns

• "Just a folder."
• No license file.
• Mutable "latest" pointers.
• Mixing assets and recipes in the same folders.

Cross-skill handoff

• Asset discovery → ../blender-asset-discovery-planner/SKILL.md
• License → ../asset-license-checker/SKILL.md
• Style → ../asset-style-consistency-checker/SKILL.md
• Fallback → ../asset-fallback-strategy/SKILL.md

Non-goals

• Move files.
• Configure git / DAM.
• Run Blender.
• Buy assets.

References

• references/folder-structure-rules.md
• references/naming-rules.md
• references/metadata-schema.md
• ../../docs/skill-system.md