playbook/outfitter-agents/plugins/outfitter/skills/claude-commands/references/namespacing.md

Command Namespacing Reference

Complete guide to organizing slash commands with directories and namespaces.

Overview

Commands can be organized in subdirectories to group related functionality. The directory structure becomes the namespace.

.claude/commands/
+-- frontend/
|   +-- component.md    # /component (project:frontend)
|   +-- styling.md      # /styling (project:frontend)
+-- backend/
|   +-- api.md          # /api (project:backend)
+-- review.md           # /review (project)

---

How Namespacing Works

Display in /help

Commands show their namespace in parentheses:

Available commands:
  /component    Create React component (project:frontend)
  /styling      Check styling guidelines (project:frontend)
  /api          Create API endpoint (project:backend)
  /review       Review code changes (project)

Invocation

Commands can be invoked with or without namespace:

# Direct (command name only)
/component Button

# With namespace
/frontend/component Button

Both work. Use direct for brevity, namespace for clarity when names overlap.

---

Directory Structure

Single Level

.claude/commands/
+-- git/
|   +-- commit.md       # /commit (project:git)
|   +-- branch.md       # /branch (project:git)
|   +-- sync.md         # /sync (project:git)

Multiple Namespaces

.claude/commands/
+-- frontend/
|   +-- component.md
|   +-- test.md
+-- backend/
|   +-- endpoint.md
|   +-- test.md         # Different from frontend/test.md
+-- deploy/
|   +-- staging.md
|   +-- production.md

Mixed (Root + Namespaced)

.claude/commands/
+-- review.md           # Root level: /review
+-- commit.md           # Root level: /commit
+-- git/
|   +-- sync.md         # Namespaced: /sync (project:git)
+-- test/
|   +-- unit.md         # Namespaced: /unit (project:test)
|   +-- e2e.md          # Namespaced: /e2e (project:test)

---

Naming Collisions

Same Name in Different Namespaces

When multiple commands have the same name:

.claude/commands/
+-- frontend/
|   +-- build.md        # /build (project:frontend)
+-- backend/
|   +-- build.md        # /build (project:backend)

Invocation:

• /build - Ambiguous, may prompt for clarification
• /frontend/build - Explicit
• /backend/build - Explicit

Resolution Priority

1. Root commands (.claude/commands/name.md)
2. First alphabetically by namespace
3. User prompted if ambiguous

Best practice: Use unique names or explicit namespaces to avoid ambiguity.

---

Organizational Patterns

By Domain

Group by functional area:

.claude/commands/
+-- auth/
|   +-- login.md
|   +-- session.md
|   +-- permissions.md
+-- data/
|   +-- migrate.md
|   +-- seed.md
|   +-- backup.md
+-- api/
|   +-- endpoint.md
|   +-- client.md

By Workflow

Group by development stage:

.claude/commands/
+-- setup/
|   +-- init.md
|   +-- config.md
+-- develop/
|   +-- feature.md
|   +-- fix.md
+-- review/
|   +-- pr.md
|   +-- security.md
+-- deploy/
|   +-- staging.md
|   +-- production.md

By Team

Group by team ownership:

.claude/commands/
+-- platform/
|   +-- infra.md
|   +-- deploy.md
+-- frontend/
|   +-- component.md
|   +-- story.md
+-- backend/
|   +-- api.md
|   +-- migration.md

By Command Type

Group by command category:

.claude/commands/
+-- tools/
|   +-- lint.md
|   +-- format.md
|   +-- test.md
+-- workflows/
|   +-- feature.md
|   +-- release.md
+-- analysis/
|   +-- review.md
|   +-- audit.md

---

Scope Interaction

Project Namespaces

Project commands (.claude/commands/) show:

/command (project:namespace)

Personal Namespaces

Personal commands (~/.claude/commands/) show:

/command (user:namespace)

Plugin Namespaces

Plugin commands show:

/command (plugin-name:namespace)

Priority

When same-named commands exist:

1. Plugin commands
2. Project commands (override personal)
3. Personal commands (fallback)

---

Best Practices

1. Consistent Structure

Choose one organizational pattern and stick with it:

# Good: Consistent by domain
frontend/
backend/
deploy/

# Bad: Mixed patterns
frontend/
deploy-staging/
api-commands/

2. Shallow Nesting

Keep to one level of directories:

# Good
.claude/commands/frontend/component.md

# Avoid
.claude/commands/frontend/react/components/button.md

3. Descriptive Names

Make namespaces self-explanatory:

# Good
git/
test/
deploy/

# Avoid
g/
t/
d/

4. README in Directories

Document namespace purpose:

.claude/commands/
+-- frontend/
|   +-- README.md       # Explains frontend commands
|   +-- component.md
|   +-- styling.md

5. Group Related Commands

Keep tightly related commands together:

# Good: Git operations together
git/
  +-- commit.md
  +-- branch.md
  +-- sync.md

# Avoid: Scattered
commands/
  +-- git-commit.md
  +-- git-branch.md
  +-- other-stuff.md
  +-- git-sync.md

---

Examples

Monorepo Structure

.claude/commands/
+-- packages/
|   +-- core/
|   |   +-- build.md
|   |   +-- test.md
|   +-- web/
|   |   +-- build.md
|   |   +-- dev.md
|   +-- api/
|       +-- build.md
|       +-- deploy.md
+-- shared/
    +-- lint.md
    +-- format.md

Full-Stack App

.claude/commands/
+-- client/
|   +-- component.md
|   +-- page.md
|   +-- story.md
+-- server/
|   +-- endpoint.md
|   +-- middleware.md
|   +-- migration.md
+-- ops/
|   +-- deploy.md
|   +-- rollback.md
|   +-- monitor.md
+-- review.md
+-- test.md

Open Source Project

.claude/commands/
+-- contribute/
|   +-- setup.md
|   +-- pr.md
|   +-- issue.md
+-- maintain/
|   +-- release.md
|   +-- changelog.md
+-- docs/
|   +-- api.md
|   +-- readme.md