Customizing the Plugin

When the framework evolves, the plugin needs to follow. This page is for maintainers who need to update the skills, the templates, or the convention rules.

Where everything lives

Inside the bjsm monorepo:

packages/claude-plugin-arcade-ecs/
├── .claude-plugin/
│   └── plugin.json                # name, version, description (manifest)
├── README.md
└── skills/
    ├── ecs-api/
    │   └── SKILL.md               # API reference + anti-pattern table
    └── scaffold-ecs/
        ├── SKILL.md               # scaffolding workflow
        └── templates/
            ├── component.ts.tmpl  # Component + System + Events
            └── test.ts.tmpl       # Vitest skeleton

When the framework adds a hook or method

Edit skills/ecs-api/SKILL.md — find the relevant class table (Component, System, World, etc.) and add the new method with its real signature. The skill is supposed to be derived from source, so cite the file:line where the new method is defined.

If the new method makes an old approach obsolete, add the deprecated method to the anti-pattern table with the correct replacement.

When the framework deprecates an API

Two edits:

1. skills/ecs-api/SKILL.md — move the deprecated method from the "real API" tables down to the anti-pattern table, with a note about what to use instead.
2. skills/scaffold-ecs/templates/*.tmpl — if any template emits the deprecated call, fix it. Re-render against a sample name to verify the new output compiles.

Bump the plugin's version field in .claude-plugin/plugin.json. Users running claude plugin add get the new version automatically.

When you want a new template

Add skills/scaffold-ecs/templates/{name}.tmpl, then reference it from the workflow section of scaffold-ecs/SKILL.md. The skill's "Workflow" section is the source of truth for which templates fire when.

If the new template needs token substitutions beyond the existing __NAME__, __SLUG__, __LOWER__, document them at the top of the template as a comment so future maintainers know.

Testing changes locally

claude --plugin-dir packages/claude-plugin-arcade-ecs

Edit SKILL.md or a template. In Claude Code:

/reload-plugins

The change is live without restarting the session.

To validate a template renders to syntactically-valid TypeScript:

# Substitute tokens and pipe through tsc as a smoke check
sed 's/__NAME__/Cooldown/g; s/__SLUG__/cooldown/g; s/__LOWER__/cooldown/g' \
  packages/claude-plugin-arcade-ecs/skills/scaffold-ecs/templates/component.ts.tmpl \
  > /tmp/Cooldown.ts
npx tsc --noEmit --target ES2022 --moduleResolution bundler /tmp/Cooldown.ts

The rule that's load-bearing

Conventions live in the plugin, not in each consuming project. When a consumer wants to deviate, the right answer is almost always to update the plugin rather than fork the convention in one project. Forks drift; the plugin keeps everyone aligned.

If a convention genuinely needs to differ between projects, that's a sign the plugin should expose a configuration knob — not a sign that the consumer should hand-roll its own conventions.