Skip to content

docs: correct module/plugin naming convention in skills#142

Merged
markshust merged 1 commit into
developfrom
feature/module-naming-convention-skills
Jun 26, 2026
Merged

docs: correct module/plugin naming convention in skills#142
markshust merged 1 commit into
developfrom
feature/module-naming-convention-skills

Conversation

@markshust

Copy link
Copy Markdown
Collaborator

Summary

Corrects the module/plugin naming convention in the create-module and create-plugin skills, verified against core framework code.

The skills previously had the directory-casing model backwards for app/ (showed a capitalized app/{Module}/) and were missing the modules/ distributable tier. create-plugin also re-derived the vendor from the project directory name, producing the wrong namespace for app-local modules.

The correct model (confirmed against core)

  • Directory + Composer name → always lowercase; PHP namespace → always StudlyCase. Core derives the namespace solely from composer.json psr-4 (ModuleAutoloader), never from directory casing — so lowercase directories are correct, not a bug.
  • Three host-project tiers (ProjectPaths + ModuleDiscovery):
    • app/{name}/ — one level deep, single segment, vendor is the literal app → namespace App\{Name}
    • modules/{vendor}/{name}/ — recursive/any depth, two-segment distributable → namespace {Vendor}\{Name}
    • packages/{name}/ — framework monorepo only → namespace Marko\{Name}
  • vendor/ is ephemeral and never authored into; modules/ is its manual-install mirror.

Changes

create-module

  • Add an explicit "ask for the name if not provided" step
  • Replace capitalized app/{Module}/ with lowercase app/{name}/
  • Add the modules/{vendor}/{name}/ distributable tier
  • Tier-scope the vendor-derivation rule (app-local has no vendor)
  • Make the lowercase-dir / StudlyCase-namespace rule explicit

create-plugin

  • Inherit {{Vendor}}\{{Name}} from the host module's psr-4 verbatim instead of re-deriving vendor from the project directory name

Verification

Cross-checked against packages/core/src/Module/ModuleDiscovery.php, packages/core/src/Path/ProjectPaths.php, and packages/core/src/Module/ModuleAutoloader.php. Discovery depths, the three directory names, and psr-4-driven (casing-agnostic) namespace registration all match the documented convention. Docs-only change to skill markdown — no code or tests affected.

🤖 Generated with Claude Code

Align create-module and create-plugin skills with framework behavior
verified against core (ModuleDiscovery, ProjectPaths, ModuleAutoloader):

- Directory and Composer-name segments are always lowercase; only the
  PHP namespace is StudlyCase (core derives namespace solely from
  composer.json psr-4, never from directory casing).
- Three host-project tiers: app/{name}/ (single segment, vendor is
  literal "app"), modules/{vendor}/{name}/ (distributable, two-segment),
  packages/{name}/ (monorepo only). vendor/ is never authored into.
- create-module: add explicit name-elicitation step; replace the
  capitalized app/{Module}/ with lowercase app/{name}/; add the
  modules/ tier; tier-scope the vendor-derivation rule.
- create-plugin: inherit namespace from the host module's psr-4 verbatim
  instead of re-deriving vendor from the project directory name (which
  produced the wrong vendor for app-local modules).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@markshust markshust merged commit 122d01c into develop Jun 26, 2026
1 check passed
@markshust markshust deleted the feature/module-naming-convention-skills branch June 26, 2026 14:05
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Jun 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant