<div style="display: none;" hidden="true" aria-hidden="true">Are you an LLM? You can read better optimized documentation at /guides/claude/developer-overrides.md for this page in Markdown format</div>

Per-Developer Overrides

See also: System Overview | Agent Catalog | Repo Flexibility | Usage Guide

How to customize Claude Code configuration for your local workflow without affecting the team's shared setup.

---

Quick Start

1. Install the team plugins (one-time) — see Required Plugins (First-Run Install). The agents, skills, slash commands, and the repo-detector hook all ship from the ecommercen-platform plugin, not this repo.
2. (Optional) Open .claude/settings.local.json (gitignored) and add your preferred permissions.
3. Start a session — the repo-detector hook (from the ecommercen-core plugin) runs automatically.

Step 1 is the only required step; everything below it is optional customization.

---

Required Plugins (First-Run Install)

Do this once after cloning. The agents, skills, and slash commands you use every day are not in this repo — they ship from the ecommercen-platform plugin marketplace (Advisable-com/ecommercen-claude). The committed .claude/settings.json declares the marketplace and enables five default-on slices, but committed settings do not install plugins.

Why a manual step is needed

.claude/settings.json carries two plugin keys, and neither installs anything:

Key	What it does	What it does not do
extraKnownMarketplaces	Registers the ecommercen-platform marketplace so it is discoverable	Does not download or install any plugin
enabledPlugins	Auto-enables the five slices once they are installed in your plugin cache	Does not fetch or install missing ones

So a fresh clone leaves the marketplace known and the slices "enabled" in config, but nothing actually installed. The usual symptom: you end up with only ecommercen-core (or whatever you installed by hand) and the generator / QA / docs / legacy agents silently missing. (Tracked upstream as ecommercen-claude#35.)

Install the five default-on slices

Option A — accept the prompt. The first time you trust this repo's folder, Claude Code offers to install the declared marketplace and plugins. Accept it. (If you trusted the folder before the plugin config landed, the prompt will not re-appear — use Option B.)

Option B — install manually (reliable, idempotent):

for p in core generators qa docs legacy; do
  claude plugin install ecommercen-$p@ecommercen-platform
done

If the marketplace is not known yet, add it first:

claude plugin marketplace add Advisable-com/ecommercen-claude

Then reload (or restart the session):

/reload-plugins

Verify

Run /plugin (or claude plugin list) — you should see all five enabled:

Slice	Provides
ecommercen-core	conventions skill, repo-detector hook, issue + coordinator commands
ecommercen-generators	domain / REST / migration / job / feed / test scaffolding + domain-developer
ecommercen-qa	code-reviewer, commit-message, REST-changelog merge-guard hook
ecommercen-docs	doc-ba flow-doc pipeline + docs-updater
ecommercen-legacy	legacy-developer for CodeIgniter 3 / HMVC code

If only ecommercen-core shows up, the others did not install — re-run the Option B loop.

Client repos additionally need the client-only slice: claude plugin install ecommercen-client-merge@ecommercen-platform.

---

Override Hierarchy

Settings (settings.json) precedence

Permission / hook / env settings resolve from highest to lowest priority. Higher layers override lower ones (permissions are the exception — they merge, see below).

Priority	Source	Scope	Committed?
1	CLI flags (--allowedTools, --agents)	Session only	No
2	.claude/settings.local.json	Per-developer	No (gitignored)
3	.claude/settings.json	Team-shared	Yes
4	~/.claude/settings.json	User-level (all projects)	No

Where each component comes from — and how to override it

Most of the agent system is provided by the ecommercen-platform plugin, not committed in this repo's .claude/. That changes how you override each piece:

Component	Default source	Personal override	Merge vs. override
Permissions	.claude/settings.json	.claude/settings.local.json, ~/.claude/settings.json	Merge across all scopes; deny wins at any layer
Agents	plugin	Same-name file ~/.claude/agents/<name>.md (or project .claude/agents/<name>.md) shadows the plugin agent	Precedence: CLI --agents › project .claude/agents/ › user ~/.claude/agents/ › plugin. You must shadow the whole agent file, not just its frontmatter
Skills	plugin (namespaced plugin:skill)	None	Cannot be shadowed; disable the plugin to remove
Slash commands	plugin	None (no per-command shadow)	Disable the plugin to remove
Hooks	plugin (ecommercen-core repo-detector) + any in .claude/settings.json	Add your own in ~/.claude/settings.json	Merge — all scopes' hooks fire. No per-hook disable (only disableAllHooks, or disable the plugin)
Rules	plugin — shipped as on-demand references inside the ecommercen-conventions skill; they do not auto-load on file open	~/.claude/rules/*.md (auto-load, all projects) or a local .claude/rules/*.md	Local rule files auto-load + merge; to auto-load the team rules, copy them into a local .claude/rules/
CLAUDE.md	./CLAUDE.md (repo)	~/.claude/CLAUDE.md; exclude with claudeMdExcludes	All files load together
MCP servers	.mcp.json (repo)	~/.claude.json (per-project)	Merge

Why "shadow the whole agent"? Dropping a same-name file at ~/.claude/agents/<name>.md replaces the plugin agent entirely — there is no documented way to override only its model/frontmatter. Copy the full agent (instructions, tools, model) from the plugin cache or the ecommercen-claude repo, then edit.

---

Common Recipes

1. Auto-Allow Common Commands

Add to .claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "Bash(vendor/bin/phpunit:*)",
      "Bash(php:*)",
      "Bash(git add:*)",
      "Bash(git push:*)",
      "Bash(npm run:*)",
      "Bash(composer:*)",
      "Skill(code-reviewer)"
    ]
  }
}

2. Stop Using Specific Agents

To keep an agent out of your sessions, deny the Task tool for that agent type in settings.local.json:

{
  "permissions": {
    "deny": [
      "Agent(feed-writer)",
      "Agent(patcher-writer)"
    ]
  }
}

To remove an agent's definition (not just gate invocation), shadow it with a same-name file under ~/.claude/agents/, or disable the providing slice with /plugin disable <slice>@ecommercen-platform.

3. Add Personal MCP Servers

MCP servers are configured per-project in ~/.claude.json (user-level):

{
  "projects": {
    "/path/to/adveshop4": {
      "mcpServers": {
        "my-db-tool": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://..."]
        }
      }
    }
  }
}

Team-shared MCP servers go in .mcp.json at the project root.

4. Add Personal Rules

Create rules in ~/.claude/rules/ that apply to all your projects and auto-load when you open matching files:

<!-- ~/.claude/rules/my-preferences.md -->
---
paths:
  - "**"
---
When generating PHP code, always add a blank line before return statements.

The team's path-specific conventions are not auto-loading .claude/rules/ files anymore — they ship as on-demand references inside the ecommercen-conventions skill (the ecommercen-core plugin), which agents load when relevant. Plugin rules do not auto-load on file open. To restore the old auto-load-on-edit behaviour, copy the references into a local .claude/rules/ (committed if you want them shared, or keep them personal under ~/.claude/rules/).

5. Personal CLAUDE.md Preferences

Create ~/.claude/CLAUDE.md for instructions that apply across all projects:

# Personal Preferences
- Always explain architectural decisions before implementing
- Use verbose git commit messages
- Prefer explicit type hints in PHP

6. Override an Agent's Model

Agents come from the plugin, and a user-level file wins over a plugin agent (precedence: CLI › project .claude/agents/ › user ~/.claude/agents/ › plugin). So to run an agent on a different model, shadow it with a same-name file at ~/.claude/agents/<name>.md:

<!-- ~/.claude/agents/schema-analyzer.md -->
---
model: haiku
---
(paste the FULL agent body — instructions, tools, everything — from the plugin)

Important: shadowing replaces the entire agent, so you must copy its full content, not just set the frontmatter. Get the source from the plugin cache (~/.claude/plugins/cache/ecommercen-platform/<slice>/<version>/agents/<name>.md) or the ecommercen-claude repo. Trade-off: your copy won't track upstream agent updates — revisit it after plugin bumps.

7. Exclude Specific CLAUDE.md Files

If a directory-level CLAUDE.md conflicts with your workflow:

{
  "claudeMdExcludes": ["path/to/specific/CLAUDE.md"]
}

Add this to .claude/settings.local.json.

8. Add Personal Hooks

Add hooks in ~/.claude/settings.json (user-level) — they fire alongside project and plugin hooks (all matching hooks run):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'File written: $TOOL_INPUT_FILE_PATH'"
          }
        ]
      }
    ]
  }
}

---

Clean settings.local.json Template

Starting point for new developers:

{
  "permissions": {
    "allow": [
      "Bash(vendor/bin/phpunit:*)",
      "Bash(php:*)",
      "Bash(git add:*)",
      "Bash(git push:*)",
      "Skill(code-reviewer)"
    ]
  }
}

---

Client Repo Notes

The same override mechanisms work identically in client repos:

• .claude/settings.local.json — per-developer permissions
• ~/.claude/agents/ — personal agent overrides (shadow a plugin agent)
• ~/.claude/rules/ — personal rules
• ~/.claude.json — personal MCP servers

Client repos enable the same five default-on slices plus the client-only ecommercen-client-merge slice (claude plugin install ecommercen-client-merge@ecommercen-platform). The repo-detector hook (from ecommercen-core) auto-detects the repo type, and agents automatically switch to client mode (writing to custom/ and application/ instead of src/ and ecommercen/).

---

What NOT to Override

These are critical shared infrastructure — overriding them will break agent behavior:

Item	Why
Plugin skills (ecommercen-platform)	Knowledge bases agents depend on. Namespaced (plugin:skill) — no user-level shadow exists; disabling the plugin removes them wholesale.
Repo-detector hook (ecommercen-core)	Repo detection is critical for all agents. Plugin hooks merge — you can't remove a single one (only disableAllHooks, or disable the plugin).
CLAUDE.md core conventions	Agent delegation rules, namespace patterns, file structure. Wrong overrides cause bad code generation.
Agent workflow logic	Encodes correct generation pipelines. Changing an agent's model is fine; changing its logic risks broken output.

---

File Reference

File	Location	Committed?	Purpose
.claude/settings.json	Project	Yes	Declares the ecommercen-platform marketplace + enabled plugins (the agent system)
.claude/settings.local.json	Project	No	Per-developer permissions / hooks
CLAUDE.md	Project root	Yes	Core project instructions
.mcp.json	Project root	Yes	Team MCP servers
ecommercen-platform plugins	~/.claude/plugins/cache/	No (installed per-dev)	Agents, skills, slash commands, hooks — the shared agent system
~/.claude/settings.json	User home	No	User-level settings / hooks
~/.claude/agents/*.md	User home	No	Personal agent overrides (shadow a plugin agent)
~/.claude/rules/*.md	User home	No	Personal rules (auto-load)
~/.claude/CLAUDE.md	User home	No	Personal instructions
~/.claude.json	User home	No	Personal MCP servers

The repo intentionally has no .claude/agents/, .claude/skills/, or .claude/rules/ directories — those are provided by the ecommercen-platform plugin. Only .claude/settings.json (plus your gitignored settings.local.json) lives in the repo.