personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request 'Add path safeguards to prevent structural damage' (#21) from development into main

Browse Source 
Reviewed-on: bandit/support-claude-mktplace#21
This commit was merged in pull request #21.
This commit is contained in:
Leo Miranda
2025-12-12 05:15:04 +00:00
parent 628180b9d1 b53aa7cb23
commit 5cfe858b12
3 changed files with 193 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
CHANGELOG.md
View File

@@ -7,6 +7,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
## [Unreleased]
### Added
- `docs/CANONICAL-PATHS.md` - Single source of truth for all file paths
- Path verification rules in CLAUDE.md (mandatory pre-flight check)
- Recovery protocol for path issues
- Installation script (`scripts/setup.sh`) for new users
- Post-update script (`scripts/post-update.sh`) for updates
- Update documentation (`docs/UPDATING.md`)
@@ -19,9 +22,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
- `docs/workflows/` for workflow documentation
### Changed
- Replaced `docs/CORRECT-ARCHITECTURE.md` reference with `docs/CANONICAL-PATHS.md`
- Added mandatory path verification section to CLAUDE.md
- Reorganized documentation into `docs/references/`, `docs/architecture/`, `docs/workflows/`
- Updated CLAUDE.md with file creation governance
### Fixed
- Removed dead reference to non-existent `docs/CORRECT-ARCHITECTURE.md`
### Removed
- Organization/workspace GID variable (no longer needed)
- Deprecated `cmdb-assistant/` plugin

48
CLAUDE.md
View File

@@ -65,6 +65,50 @@ Before creating any file, verify:
**Violation of these rules creates technical debt and project chaos.**
## Path Verification (MANDATORY)
### Before Generating Any Prompt or Creating Any File
**This is non-negotiable. Failure to follow causes structural damage.**
1. **READ `docs/CANONICAL-PATHS.md` FIRST**
- This file is the single source of truth
- Never infer paths from memory or context
- Never assume paths based on conversation history
2. **List All Paths**
- Before generating a prompt, list every file path it will create/modify
- Show the list to the user
3. **Verify Each Path**
- Check each path against `docs/CANONICAL-PATHS.md`
- If a path is not in that file, STOP and ask
4. **Show Verification**
- Present a verification table to user:
```
| Path | Matches CANONICAL-PATHS.md? |
|------|----------------------------|
| plugins/projman/... | ✅ Yes |
```
5. **Get Confirmation**
- User must confirm paths are correct before proceeding
### Relative Path Rules
- Plugin to MCP server: `${CLAUDE_PLUGIN_ROOT}/../../mcp-servers/{server}`
- Marketplace to plugin: `./../../../plugins/{plugin-name}`
- **ALWAYS calculate from CANONICAL-PATHS.md, never from memory**
### Recovery Protocol
If you suspect paths are wrong:
1. Read `docs/CANONICAL-PATHS.md`
2. Compare actual structure against documented structure
3. Report discrepancies
4. Generate corrective prompt if needed
## Core Architecture
### Three-Agent Model
@@ -212,7 +256,7 @@ See [docs/reference-material/projman-implementation-plan.md](docs/reference-mate
### Repository Structure (DEFINITIVE)
⚠️ **See `docs/CORRECT-ARCHITECTURE.md` for the authoritative structure reference**
⚠️ **See `docs/CANONICAL-PATHS.md` for the authoritative path reference - THIS IS THE SINGLE SOURCE OF TRUTH**
```
bandit/support-claude-mktplace/
@@ -435,7 +479,7 @@ Test in real CuisineFlow repository with actual Gitea instance before distributi
This repository contains comprehensive planning documentation:
- **`docs/CORRECT-ARCHITECTURE.md`** - ⚠️ DEFINITIVE repository structure reference
- **`docs/CANONICAL-PATHS.md`** - ⚠️ SINGLE SOURCE OF TRUTH for all paths (MANDATORY reading before any file operations)
- **`docs/DOCUMENT-INDEX.md`** - Complete guide to all planning documents
- **`docs/projman-implementation-plan-updated.md`** - Full 12-phase implementation plan
- **`docs/projman-python-quickstart.md`** - Python-specific implementation guide

139
docs/CANONICAL-PATHS.md Normal file
View File

@@ -0,0 +1,139 @@
# 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 |