# Canonical Paths - SINGLE SOURCE OF TRUTH

**This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.**

Last Updated: 2026-01-20

---

## Repository Root Structure

```
support-claude-mktplace/
├── .claude/                    # Claude Code local settings
├── .claude-plugin/             # Marketplace manifest (claude-code-marketplace)
│   └── marketplace.json
├── .scratch/                   # Transient work (auto-cleaned)
├── docs/                       # All documentation
│   ├── architecture/           # Draw.io diagrams and specs
│   ├── CANONICAL-PATHS.md      # This file - single source of truth
│   ├── UPDATING.md             # Update guide
│   └── workflows/              # Workflow documentation
├── hooks/                      # Shared hooks (if any)
├── plugins/                    # ALL plugins with bundled MCP servers
│   ├── projman/
│   │   ├── .claude-plugin/
│   │   ├── mcp-servers/        # MCP servers bundled IN plugin
│   │   │   └── gitea/          # Gitea + Wiki tools
│   │   ├── commands/
│   │   ├── agents/
│   │   ├── skills/
│   │   └── claude-md-integration.md  # CLAUDE.md integration snippet
│   ├── doc-guardian/           # Documentation drift detection
│   │   ├── .claude-plugin/
│   │   ├── hooks/              # PostToolUse, Stop hooks
│   │   ├── commands/
│   │   ├── agents/
│   │   ├── skills/
│   │   └── claude-md-integration.md
│   ├── code-sentinel/          # Security scanning & refactoring
│   │   ├── .claude-plugin/
│   │   ├── hooks/              # PreToolUse hook
│   │   ├── commands/
│   │   ├── agents/
│   │   ├── skills/
│   │   └── claude-md-integration.md
│   ├── projman-pmo/
│   ├── cmdb-assistant/
│   │   ├── .claude-plugin/
│   │   ├── mcp-servers/        # MCP servers bundled IN plugin
│   │   │   └── netbox/
│   │   ├── commands/
│   │   ├── agents/
│   │   └── claude-md-integration.md  # CLAUDE.md integration snippet
│   ├── claude-config-maintainer/
│   │   ├── .claude-plugin/
│   │   ├── commands/
│   │   ├── agents/
│   │   └── claude-md-integration.md  # CLAUDE.md integration snippet
│   └── project-hygiene/
│       ├── .claude-plugin/
│       ├── hooks/
│       └── claude-md-integration.md  # CLAUDE.md integration snippet
├── scripts/                    # Setup and maintenance scripts
├── CLAUDE.md
├── README.md
├── LICENSE
├── CHANGELOG.md
└── .gitignore
```

---

## Path Patterns (MANDATORY)

### Plugin Paths

| Context | Pattern | Example |
|---------|---------|---------|
| Plugin location | `plugins/{plugin-name}/` | `plugins/projman/` |
| Plugin manifest | `plugins/{plugin-name}/.claude-plugin/plugin.json` | `plugins/projman/.claude-plugin/plugin.json` |
| Plugin commands | `plugins/{plugin-name}/commands/` | `plugins/projman/commands/` |
| Plugin agents | `plugins/{plugin-name}/agents/` | `plugins/projman/agents/` |
| Plugin .mcp.json | `plugins/{plugin-name}/.mcp.json` | `plugins/projman/.mcp.json` |
| Plugin integration snippet | `plugins/{plugin-name}/claude-md-integration.md` | `plugins/projman/claude-md-integration.md` |

### MCP Server Paths (Bundled in Plugins)

MCP servers are now **bundled inside each plugin** to ensure they work when plugins are cached.

| Context | Pattern | Example |
|---------|---------|---------|
| MCP server location | `plugins/{plugin}/mcp-servers/{server}/` | `plugins/projman/mcp-servers/gitea/` |
| MCP server code | `plugins/{plugin}/mcp-servers/{server}/mcp_server/` | `plugins/projman/mcp-servers/gitea/mcp_server/` |
| MCP venv | `plugins/{plugin}/mcp-servers/{server}/.venv/` | `plugins/projman/mcp-servers/gitea/.venv/` |

### Relative Path Patterns (CRITICAL)

| From | To | Pattern |
|------|----|---------|
| Plugin .mcp.json | Bundled MCP server | `${CLAUDE_PLUGIN_ROOT}/mcp-servers/{server}` |
| marketplace.json | Plugin | `./plugins/{plugin-name}` |

### Documentation Paths

| Type | Location |
|------|----------|
| Architecture diagrams | `docs/architecture/` |
| Workflow docs | `docs/workflows/` |
| This file | `docs/CANONICAL-PATHS.md` |
| Update guide | `docs/UPDATING.md` |

---

## Validation Rules

### Before Creating Any File

1. Check this file for the correct path pattern
2. Verify the parent directory exists in the structure above
3. If path not listed here, **STOP AND ASK**

### Before Generating Any Prompt

1. List all file paths the prompt will create/modify
2. Verify each path against patterns in this file
3. Show verification to user before proceeding

### Relative Path Calculation

From `plugins/projman/.mcp.json` to bundled `mcp-servers/gitea/`:
```
plugins/projman/.mcp.json
  → MCP servers are IN the plugin at mcp-servers/

Result: mcp-servers/gitea/
With variable: ${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/
```

From `.claude-plugin/marketplace.json` to `plugins/projman/`:
```
.claude-plugin/marketplace.json
  ↑ marketplace.json is at repo root level
  → go down to plugins/projman/           (./plugins/projman/)

Result: ./plugins/projman
```

---

## Anti-Patterns (NEVER DO THIS)

| Wrong | Why | Correct |
|-------|-----|---------|
| `projman/` at root | Plugins go in `plugins/` | `plugins/projman/` |
| `mcp-servers/` at root | MCP servers are bundled in plugins | `plugins/{plugin}/mcp-servers/` |
| `../../mcp-servers/` from plugin | Old pattern, doesn't work with caching | `${CLAUDE_PLUGIN_ROOT}/mcp-servers/` |
| `./../../../plugins/projman` in marketplace | Wrong (old nested structure) | `./plugins/projman` |

---

## Architecture Note

MCP servers are bundled inside each plugin (not shared at root) because:
- Claude Code caches only the plugin directory when installed
- Relative paths to parent directories break in the cache
- Each plugin must be self-contained to work properly

---

## Change Log

| Date | Change | By |
|------|--------|-----|
| 2026-01-20 | Removed docs/references/ (obsolete planning docs) | Claude Code |
| 2026-01-19 | Added claude-md-integration.md path pattern for plugin integration snippets | Claude Code |
| 2025-12-15 | Restructured: MCP servers now bundled in plugins | Claude Code |
| 2025-12-12 | Initial creation | Claude Code |