lmiranda
c1e9382031
Updates missed in initial implementation: - projman/README.md: add /test-gen command documentation and update architecture - CLAUDE.md: bump to v2.3.0, add doc-guardian and code-sentinel to plugin table, update projman version, update command count to 9, update repository structure - docs/CANONICAL-PATHS.md: add doc-guardian and code-sentinel plugin paths Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
178 lines
6.5 KiB
Markdown
178 lines
6.5 KiB
Markdown
# 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 |
|