lmiranda
b53aa7cb23
- Create docs/CANONICAL-PATHS.md as single source of truth - Add mandatory path verification rules to CLAUDE.md - Remove dead reference to CORRECT-ARCHITECTURE.md - Add recovery protocol for path issues 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
140 lines
4.5 KiB
Markdown
140 lines
4.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: 2025-12-12
|
|
|
|
---
|
|
|
|
## Repository Root Structure
|
|
|
|
```
|
|
support-claude-mktplace/
|
|
├── .claude/ # Claude Code skills
|
|
├── .claude-plugin/ # Root marketplace manifest (if any)
|
|
├── .claude-plugins/ # Local marketplace definitions
|
|
│ └── projman-marketplace/
|
|
│ └── .claude-plugin/
|
|
│ └── marketplace.json
|
|
├── .scratch/ # Transient work (auto-cleaned)
|
|
├── docs/ # All documentation
|
|
│ ├── architecture/ # Draw.io diagrams and specs
|
|
│ ├── references/ # Reference specifications
|
|
│ └── workflows/ # Workflow documentation
|
|
├── hooks/ # Shared hooks (if any)
|
|
├── mcp-servers/ # Shared MCP servers (AT ROOT)
|
|
│ ├── gitea/
|
|
│ ├── wikijs/
|
|
│ └── netbox/
|
|
├── plugins/ # ALL plugins (INSIDE plugins/)
|
|
│ ├── projman/
|
|
│ ├── projman-pmo/
|
|
│ ├── project-hygiene/
|
|
│ └── cmdb-assistant/
|
|
├── 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` |
|
|
|
|
### MCP Server Paths
|
|
|
|
| Context | Pattern | Example |
|
|
|---------|---------|---------|
|
|
| MCP server location | `mcp-servers/{server-name}/` | `mcp-servers/gitea/` |
|
|
| MCP server code | `mcp-servers/{server-name}/mcp_server/` | `mcp-servers/gitea/mcp_server/` |
|
|
| MCP venv | `mcp-servers/{server-name}/.venv/` | `mcp-servers/gitea/.venv/` |
|
|
|
|
### Relative Path Patterns (CRITICAL)
|
|
|
|
| From | To | Pattern |
|
|
|------|----|---------|
|
|
| Plugin .mcp.json | MCP server | `${CLAUDE_PLUGIN_ROOT}/../../mcp-servers/{server}` |
|
|
| marketplace.json | Plugin | `./../../../plugins/{plugin-name}` |
|
|
|
|
### Documentation Paths
|
|
|
|
| Type | Location |
|
|
|------|----------|
|
|
| Reference specs | `docs/references/` |
|
|
| Architecture diagrams | `docs/architecture/` |
|
|
| Workflow docs | `docs/workflows/` |
|
|
| This file | `docs/CANONICAL-PATHS.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 `mcp-servers/gitea/`:
|
|
```
|
|
plugins/projman/.mcp.json
|
|
↑ go up to plugins/projman/ (../)
|
|
↑ go up to plugins/ (../)
|
|
↑ go up to root/ (../)
|
|
→ go down to mcp-servers/gitea/ (mcp-servers/gitea/)
|
|
|
|
Result: ../../mcp-servers/gitea/
|
|
With variable: ${CLAUDE_PLUGIN_ROOT}/../../mcp-servers/gitea/
|
|
```
|
|
|
|
From `.claude-plugins/projman-marketplace/.claude-plugin/marketplace.json` to `plugins/projman/`:
|
|
```
|
|
.claude-plugins/projman-marketplace/.claude-plugin/marketplace.json
|
|
↑ go up to .claude-plugin/ (../)
|
|
↑ go up to projman-marketplace/ (../)
|
|
↑ go up to .claude-plugins/ (../)
|
|
↑ go up to root/ (../)
|
|
→ 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/` from plugin | Missing one level | `../../mcp-servers/` |
|
|
| `./projman` in marketplace | Wrong depth | `./../../../plugins/projman` |
|
|
| Creating `docs/CORRECT-ARCHITECTURE.md` | This file replaces it | Use `docs/CANONICAL-PATHS.md` |
|
|
|
|
---
|
|
|
|
## Change Log
|
|
|
|
| Date | Change | By |
|
|
|------|--------|-----|
|
|
| 2025-12-12 | Initial creation | Claude Code |
|