Compare commits
43 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| 1c694b6469 | |||
| c1e9382031 | |||
| b6c632b75f | |||
| a8ea1fcc25 | |||
| ebb950d39c | |||
| b508d4bcce | |||
| 23537158bc | |||
| 870ed26510 | |||
| 395daecda8 | |||
| 337f40600a | |||
| 14425cfad1 | |||
| c38404a98a | |||
| 70d3933da4 | |||
| cce2066d3b | |||
| 5d95e42eb5 | |||
| f35706e621 | |||
| 697031c526 | |||
| 32797ce473 | |||
| 368f9a4c2e | |||
| cb0a5ddec5 | |||
| 8da7117b89 | |||
| c322cf4b2f | |||
| a6d3fe6c6c | |||
| c62e0dbd2c | |||
| 34c8f0bdb6 | |||
| 72941c1fe1 | |||
| 1adb434c58 | |||
| 76462d5d8c | |||
| 5b7c1f3fce | |||
| 87b30cbb85 | |||
| 67c057f9ee | |||
| c34fd22852 | |||
| 5fc18f28e9 | |||
| 113839b0d8 | |||
| a12665c22d | |||
| 15e0654950 | |||
| 3c3b9329c5 | |||
| 1e63de6679 | |||
| 6c77c264f6 | |||
| b3a41f722c | |||
| 97085021a9 | |||
| eb2c184641 | |||
| 5cfe858b12 |
@@ -1,35 +1,111 @@
|
|||||||
{
|
{
|
||||||
"name": "bandit-claude-marketplace",
|
"name": "claude-code-marketplace",
|
||||||
"version": "2.0.0",
|
|
||||||
"description": "Project management plugins with Gitea and NetBox integrations",
|
|
||||||
"owner": {
|
"owner": {
|
||||||
"name": "Bandit Labs",
|
"name": "Leo Miranda",
|
||||||
"email": "dev@banditlabs.io"
|
"email": "leobmiranda@gmail.com"
|
||||||
|
},
|
||||||
|
"metadata": {
|
||||||
|
"description": "Project management plugins with Gitea and NetBox integrations",
|
||||||
|
"version": "2.3.0"
|
||||||
},
|
},
|
||||||
"plugins": [
|
"plugins": [
|
||||||
{
|
{
|
||||||
"name": "projman",
|
"name": "projman",
|
||||||
"version": "2.0.0",
|
"version": "2.3.0",
|
||||||
"description": "Sprint planning and project management with Gitea integration",
|
"description": "Sprint planning and project management with Gitea integration",
|
||||||
"source": "./plugins/projman"
|
"source": "./plugins/projman",
|
||||||
|
"author": {
|
||||||
|
"name": "Leo Miranda",
|
||||||
|
"email": "leobmiranda@gmail.com"
|
||||||
|
},
|
||||||
|
"homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/projman/README.md",
|
||||||
|
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
|
||||||
|
"mcpServers": ["gitea"],
|
||||||
|
"integrationFile": "claude-md-integration.md"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "doc-guardian",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"description": "Automatic documentation drift detection and synchronization",
|
||||||
|
"source": "./plugins/doc-guardian",
|
||||||
|
"author": {
|
||||||
|
"name": "Leo Miranda",
|
||||||
|
"email": "leobmiranda@gmail.com"
|
||||||
|
},
|
||||||
|
"homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/doc-guardian/README.md",
|
||||||
|
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
|
||||||
|
"mcpServers": [],
|
||||||
|
"integrationFile": "claude-md-integration.md",
|
||||||
|
"hooks": ["PostToolUse", "Stop"]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "code-sentinel",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"description": "Security scanning and code refactoring tools",
|
||||||
|
"source": "./plugins/code-sentinel",
|
||||||
|
"author": {
|
||||||
|
"name": "Leo Miranda",
|
||||||
|
"email": "leobmiranda@gmail.com"
|
||||||
|
},
|
||||||
|
"homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/code-sentinel/README.md",
|
||||||
|
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
|
||||||
|
"mcpServers": [],
|
||||||
|
"integrationFile": "claude-md-integration.md",
|
||||||
|
"hooks": ["PreToolUse"]
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "project-hygiene",
|
"name": "project-hygiene",
|
||||||
"version": "0.1.0",
|
"version": "0.1.0",
|
||||||
"description": "Post-task cleanup hook that removes temp files and manages orphaned files",
|
"description": "Post-task cleanup hook that removes temp files and manages orphaned files",
|
||||||
"source": "./plugins/project-hygiene"
|
"source": "./plugins/project-hygiene",
|
||||||
|
"author": {
|
||||||
|
"name": "Leo Miranda",
|
||||||
|
"email": "leobmiranda@gmail.com"
|
||||||
|
},
|
||||||
|
"homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/project-hygiene/README.md",
|
||||||
|
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
|
||||||
|
"mcpServers": [],
|
||||||
|
"integrationFile": "claude-md-integration.md",
|
||||||
|
"hooks": ["PostToolUse"]
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "cmdb-assistant",
|
"name": "cmdb-assistant",
|
||||||
"version": "1.0.0",
|
"version": "1.0.0",
|
||||||
"description": "NetBox CMDB integration for infrastructure management",
|
"description": "NetBox CMDB integration for infrastructure management",
|
||||||
"source": "./plugins/cmdb-assistant"
|
"source": "./plugins/cmdb-assistant",
|
||||||
|
"author": {
|
||||||
|
"name": "Leo Miranda",
|
||||||
|
"email": "leobmiranda@gmail.com"
|
||||||
|
},
|
||||||
|
"homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/cmdb-assistant/README.md",
|
||||||
|
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
|
||||||
|
"mcpServers": ["netbox"],
|
||||||
|
"integrationFile": "claude-md-integration.md"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "claude-config-maintainer",
|
"name": "claude-config-maintainer",
|
||||||
"version": "1.0.0",
|
"version": "1.0.0",
|
||||||
"description": "CLAUDE.md optimization and maintenance for Claude Code projects",
|
"description": "CLAUDE.md optimization and maintenance for Claude Code projects",
|
||||||
"source": "./plugins/claude-config-maintainer"
|
"source": "./plugins/claude-config-maintainer",
|
||||||
|
"author": {
|
||||||
|
"name": "Leo Miranda",
|
||||||
|
"email": "leobmiranda@gmail.com"
|
||||||
|
},
|
||||||
|
"homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/claude-config-maintainer/README.md",
|
||||||
|
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
|
||||||
|
"mcpServers": [],
|
||||||
|
"integrationFile": "claude-md-integration.md"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"pluginDetection": {
|
||||||
|
"mcpServerMapping": {
|
||||||
|
"gitea": "projman",
|
||||||
|
"netbox": "cmdb-assistant"
|
||||||
|
},
|
||||||
|
"hookMapping": {
|
||||||
|
"PostToolUse:Write|Edit": "project-hygiene",
|
||||||
|
"PostToolUse:Write|Edit|MultiEdit": "doc-guardian",
|
||||||
|
"PreToolUse:Write|Edit|MultiEdit": "code-sentinel"
|
||||||
|
}
|
||||||
}
|
}
|
||||||
]
|
|
||||||
}
|
}
|
||||||
|
|||||||
28
.mcp.json
28
.mcp.json
@@ -1,28 +0,0 @@
|
|||||||
{
|
|
||||||
"mcpServers": {
|
|
||||||
"gitea": {
|
|
||||||
"command": "/home/lmiranda/repos/bandit/support-claude-mktplace/mcp-servers/gitea/.venv/bin/python",
|
|
||||||
"args": ["-m", "mcp_server.server"],
|
|
||||||
"cwd": "/home/lmiranda/repos/bandit/support-claude-mktplace/mcp-servers/gitea",
|
|
||||||
"env": {
|
|
||||||
"PYTHONPATH": "/home/lmiranda/repos/bandit/support-claude-mktplace/mcp-servers/gitea"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"wikijs": {
|
|
||||||
"command": "/home/lmiranda/repos/bandit/support-claude-mktplace/mcp-servers/wikijs/.venv/bin/python",
|
|
||||||
"args": ["-m", "mcp_server.server"],
|
|
||||||
"cwd": "/home/lmiranda/repos/bandit/support-claude-mktplace/mcp-servers/wikijs",
|
|
||||||
"env": {
|
|
||||||
"PYTHONPATH": "/home/lmiranda/repos/bandit/support-claude-mktplace/mcp-servers/wikijs"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"netbox": {
|
|
||||||
"command": "/home/lmiranda/repos/bandit/support-claude-mktplace/mcp-servers/netbox/.venv/bin/python",
|
|
||||||
"args": ["-m", "mcp_server.server"],
|
|
||||||
"cwd": "/home/lmiranda/repos/bandit/support-claude-mktplace/mcp-servers/netbox",
|
|
||||||
"env": {
|
|
||||||
"PYTHONPATH": "/home/lmiranda/repos/bandit/support-claude-mktplace/mcp-servers/netbox"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
108
CHANGELOG.md
108
CHANGELOG.md
@@ -4,7 +4,66 @@ All notable changes to support-claude-mktplace will be documented in this file.
|
|||||||
|
|
||||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
||||||
|
|
||||||
## [Unreleased]
|
## [2.3.0] - 2026-01-20
|
||||||
|
|
||||||
|
### Added
|
||||||
|
|
||||||
|
#### New Plugins
|
||||||
|
- **doc-guardian** v1.0.0 - Documentation lifecycle management
|
||||||
|
- `/doc-audit` command for full project documentation drift analysis
|
||||||
|
- `/doc-sync` command to batch apply pending documentation updates
|
||||||
|
- PostToolUse hook for automatic drift detection
|
||||||
|
- Stop hook reminder for pending updates
|
||||||
|
- doc-analyzer agent for cross-reference analysis
|
||||||
|
- doc-patterns skill for documentation structure knowledge
|
||||||
|
|
||||||
|
- **code-sentinel** v1.0.0 - Security scanning and refactoring
|
||||||
|
- `/security-scan` command for comprehensive security audit
|
||||||
|
- `/refactor` command to apply refactoring patterns
|
||||||
|
- `/refactor-dry` command to preview refactoring opportunities
|
||||||
|
- PreToolUse hook for real-time security scanning
|
||||||
|
- security-reviewer agent for vulnerability analysis
|
||||||
|
- refactor-advisor agent for code structure improvements
|
||||||
|
- security-patterns skill for vulnerability detection rules
|
||||||
|
|
||||||
|
#### projman Enhancements
|
||||||
|
- `/test-gen` command - Generate unit, integration, and e2e tests for specified code
|
||||||
|
|
||||||
|
### Changed
|
||||||
|
- Marketplace version bumped to 2.3.0
|
||||||
|
- projman version bumped to 2.3.0
|
||||||
|
|
||||||
|
## [2.2.0] - 2026-01-20
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- `/review` command for pre-sprint-close code quality checks (projman)
|
||||||
|
- `/test-check` command for test verification before sprint close (projman)
|
||||||
|
- `code-reviewer` agent for structured code review workflow (projman)
|
||||||
|
- Validation script (`scripts/validate-marketplace.sh`) for marketplace compliance
|
||||||
|
- `homepage` and `repository` fields to all plugin entries in marketplace.json
|
||||||
|
- `metadata` wrapper for description/version in marketplace.json
|
||||||
|
- Keywords to all plugin manifests for better discoverability
|
||||||
|
- `commands` and `agents` directory references to plugin manifests
|
||||||
|
- Versioning rule: version displayed only in main README.md title
|
||||||
|
|
||||||
|
### Changed
|
||||||
|
- Updated marketplace.json with required fields per Claude Code spec
|
||||||
|
- Fixed installation documentation to use official Claude Code methods
|
||||||
|
- Prioritized public HTTPS URL over Tailscale SSH URL in documentation
|
||||||
|
- Updated all plugin manifests with author, homepage, repository, license fields
|
||||||
|
- Consolidated version display to main README.md title only
|
||||||
|
- Removed version numbers from plugin documentation titles
|
||||||
|
|
||||||
|
### Fixed
|
||||||
|
- Plugin manifests now include all required fields per Claude Code spec
|
||||||
|
- Installation section uses `extraKnownMarketplaces` instead of undocumented `pluginMarketplace`
|
||||||
|
|
||||||
|
### Removed
|
||||||
|
- `docs/references/` directory (obsolete planning documents)
|
||||||
|
- Version numbers from individual plugin README titles
|
||||||
|
- Version section from plugins/projman/README.md
|
||||||
|
|
||||||
|
## [2.1.0] - 2026-01-15
|
||||||
|
|
||||||
### Added
|
### Added
|
||||||
- `docs/CANONICAL-PATHS.md` - Single source of truth for all file paths
|
- `docs/CANONICAL-PATHS.md` - Single source of truth for all file paths
|
||||||
@@ -15,16 +74,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
|||||||
- Update documentation (`docs/UPDATING.md`)
|
- Update documentation (`docs/UPDATING.md`)
|
||||||
- `/initial-setup` slash command
|
- `/initial-setup` slash command
|
||||||
- File creation governance rules in CLAUDE.md
|
- File creation governance rules in CLAUDE.md
|
||||||
- Architecture diagram specifications in `docs/architecture/`
|
|
||||||
- `.scratch/` directory for transient work
|
- `.scratch/` directory for transient work
|
||||||
- `scripts/` directory for setup automation
|
- `scripts/` directory for setup automation
|
||||||
- `docs/architecture/` for Draw.io diagrams
|
|
||||||
- `docs/workflows/` for workflow documentation
|
|
||||||
|
|
||||||
### Changed
|
### Changed
|
||||||
- Replaced `docs/CORRECT-ARCHITECTURE.md` reference with `docs/CANONICAL-PATHS.md`
|
- Replaced `docs/CORRECT-ARCHITECTURE.md` reference with `docs/CANONICAL-PATHS.md`
|
||||||
- Added mandatory path verification section to CLAUDE.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
|
- Updated CLAUDE.md with file creation governance
|
||||||
|
|
||||||
### Fixed
|
### Fixed
|
||||||
@@ -32,21 +87,44 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
|||||||
|
|
||||||
### Removed
|
### Removed
|
||||||
- Organization/workspace GID variable (no longer needed)
|
- Organization/workspace GID variable (no longer needed)
|
||||||
- Deprecated `cmdb-assistant/` plugin
|
|
||||||
- Development output files (test scripts, status reports)
|
- Development output files (test scripts, status reports)
|
||||||
- IDE-specific workspace files
|
- IDE-specific workspace files
|
||||||
- Stray files from project root
|
- Stray files from project root
|
||||||
|
|
||||||
## [0.1.0] - Initial Release
|
## [2.0.0] - 2026-01-06
|
||||||
|
|
||||||
### Added
|
### Added
|
||||||
- projman plugin for sprint management
|
- Full Gitea integration with wiki, milestones, dependencies
|
||||||
|
- Parallel execution batching via dependency graph
|
||||||
|
- Wiki tools for lessons learned (`create_lesson`, `search_lessons`)
|
||||||
|
- Milestone tools (`list_milestones`, `create_milestone`, `update_milestone`)
|
||||||
|
- Dependency tools (`list_issue_dependencies`, `create_issue_dependency`, `get_execution_order`)
|
||||||
|
- Validation tools (`validate_repo_org`, `get_branch_protection`)
|
||||||
|
- MCP servers bundled inside plugins (not shared at root)
|
||||||
|
|
||||||
|
### Changed
|
||||||
|
- MCP server architecture: bundled in plugins instead of shared at root
|
||||||
|
- Configuration uses `${CLAUDE_PLUGIN_ROOT}/mcp-servers/` paths
|
||||||
|
|
||||||
|
## [1.0.0] - 2025-12-15
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- projman plugin with basic sprint commands
|
||||||
|
- `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close` commands
|
||||||
|
- `/labels-sync` command for label taxonomy synchronization
|
||||||
|
- Three-agent model (planner, orchestrator, executor)
|
||||||
|
- Gitea MCP server with issue and label tools
|
||||||
|
- 43-label taxonomy system
|
||||||
|
- Hybrid configuration system (system + project level)
|
||||||
|
- Branch-aware security model
|
||||||
|
|
||||||
|
## [0.1.0] - 2025-12-01
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- Initial repository structure
|
||||||
|
- projman plugin structure (planned)
|
||||||
- projman-pmo plugin structure (planned)
|
- projman-pmo plugin structure (planned)
|
||||||
- project-hygiene plugin for cleanup automation
|
- project-hygiene plugin for cleanup automation
|
||||||
- Gitea MCP server
|
- claude-config-maintainer plugin structure
|
||||||
- Wiki.js MCP server
|
- cmdb-assistant plugin structure
|
||||||
- 43-label taxonomy system
|
- Basic marketplace manifest
|
||||||
- Lessons learned capture system
|
|
||||||
- Hybrid configuration system (system + project level)
|
|
||||||
- Three-agent model (planner, orchestrator, executor)
|
|
||||||
- Branch-aware security model
|
|
||||||
|
|||||||
638
CLAUDE.md
638
CLAUDE.md
@@ -1,478 +1,230 @@
|
|||||||
# CLAUDE.md
|
# CLAUDE.md
|
||||||
|
|
||||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
This file provides guidance to Claude Code when working with code in this repository.
|
||||||
|
|
||||||
## Project Overview
|
## Project Overview
|
||||||
|
|
||||||
This repository contains Claude Code plugins for project management:
|
**Repository:** support-claude-mktplace
|
||||||
|
**Version:** 2.3.0
|
||||||
|
**Status:** Production Ready
|
||||||
|
|
||||||
1. **`projman`** - Single-repository project management plugin with Gitea integration
|
A Claude Code plugin marketplace containing:
|
||||||
2. **`projman-pmo`** - Multi-project PMO coordination plugin
|
|
||||||
3. **`claude-config-maintainer`** - CLAUDE.md optimization and maintenance plugin
|
|
||||||
4. **`cmdb-assistant`** - NetBox CMDB integration for infrastructure management
|
|
||||||
|
|
||||||
These plugins transform a proven 15-sprint workflow into reusable, distributable tools for managing software development with Claude Code, Gitea, and agile methodologies.
|
| Plugin | Description | Version |
|
||||||
|
|--------|-------------|---------|
|
||||||
|
| `projman` | Sprint planning and project management with Gitea integration | 2.3.0 |
|
||||||
|
| `doc-guardian` | Automatic documentation drift detection and synchronization | 1.0.0 |
|
||||||
|
| `code-sentinel` | Security scanning and code refactoring tools | 1.0.0 |
|
||||||
|
| `claude-config-maintainer` | CLAUDE.md optimization and maintenance | 1.0.0 |
|
||||||
|
| `cmdb-assistant` | NetBox CMDB integration for infrastructure management | 1.0.0 |
|
||||||
|
| `project-hygiene` | Post-task cleanup automation via hooks | 0.1.0 |
|
||||||
|
|
||||||
**Status:** projman v1.0.0 complete with full Gitea integration
|
## Quick Start
|
||||||
|
|
||||||
## File Creation Governance
|
```bash
|
||||||
|
# Validate marketplace compliance
|
||||||
|
./scripts/validate-marketplace.sh
|
||||||
|
|
||||||
### Allowed Root Files
|
# Run projman commands (in a target project with plugin installed)
|
||||||
|
/sprint-plan # Start sprint planning
|
||||||
Only these files may exist at the repository root:
|
/sprint-status # Check progress
|
||||||
|
/review # Pre-close code quality review
|
||||||
- `CLAUDE.md` - This file
|
/test-check # Verify tests before close
|
||||||
- `README.md` - Repository overview
|
/sprint-close # Complete sprint
|
||||||
- `LICENSE` - License file
|
|
||||||
- `CHANGELOG.md` - Version history
|
|
||||||
- `.gitignore` - Git ignore rules
|
|
||||||
- `.env.example` - Environment template (if needed)
|
|
||||||
|
|
||||||
### Allowed Root Directories
|
|
||||||
|
|
||||||
Only these directories may exist at the repository root:
|
|
||||||
|
|
||||||
| Directory | Purpose |
|
|
||||||
|-----------|---------|
|
|
||||||
| `.claude/` | Claude Code local settings |
|
|
||||||
| `.claude-plugin/` | Marketplace manifest |
|
|
||||||
| `.claude-plugins/` | Local marketplace definitions |
|
|
||||||
| `.scratch/` | Transient work (auto-cleaned) |
|
|
||||||
| `docs/` | Documentation |
|
|
||||||
| `hooks/` | Shared hooks (if any) |
|
|
||||||
| `plugins/` | All plugins (projman, projman-pmo, project-hygiene, cmdb-assistant, claude-config-maintainer) |
|
|
||||||
| `scripts/` | Setup and maintenance scripts |
|
|
||||||
|
|
||||||
### File Creation Rules
|
|
||||||
|
|
||||||
1. **No new root files** - Do not create files directly in the repository root unless listed above
|
|
||||||
2. **No new root directories** - Do not create top-level directories without explicit approval
|
|
||||||
3. **Transient work goes in `.scratch/`** - Any temporary files, test outputs, or exploratory work must be created in `.scratch/`
|
|
||||||
4. **Clean up after tasks** - Delete files in `.scratch/` when the task is complete
|
|
||||||
5. **Documentation location** - All documentation goes in `docs/` with appropriate subdirectory:
|
|
||||||
- `docs/references/` - Reference specifications and summaries
|
|
||||||
- `docs/architecture/` - Architecture diagrams (Draw.io files)
|
|
||||||
- `docs/workflows/` - Workflow documentation
|
|
||||||
6. **No output files** - Do not leave generated output, logs, or test results outside designated directories
|
|
||||||
|
|
||||||
### Enforcement
|
|
||||||
|
|
||||||
Before creating any file, verify:
|
|
||||||
|
|
||||||
1. Is this file type allowed in the target location?
|
|
||||||
2. If temporary, am I using `.scratch/`?
|
|
||||||
3. If documentation, am I using the correct `docs/` subdirectory?
|
|
||||||
4. Will this file be cleaned up after the task?
|
|
||||||
|
|
||||||
**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**
|
## Repository Structure
|
||||||
- User must confirm paths are correct before proceeding
|
|
||||||
|
|
||||||
### Relative Path Rules
|
|
||||||
|
|
||||||
- Plugin to bundled 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
|
|
||||||
|
|
||||||
The plugins implement a three-agent architecture that mirrors the proven workflow:
|
|
||||||
|
|
||||||
**Planner Agent** (`agents/planner.md`)
|
|
||||||
- Performs architecture analysis and sprint planning
|
|
||||||
- Creates detailed planning documents
|
|
||||||
- Makes architectural decisions
|
|
||||||
- Creates Gitea issues with appropriate labels
|
|
||||||
- Personality: Asks clarifying questions, thinks through edge cases, never rushes
|
|
||||||
|
|
||||||
**Orchestrator Agent** (`agents/orchestrator.md`)
|
|
||||||
- Coordinates sprint execution
|
|
||||||
- Generates lean execution prompts (not full docs)
|
|
||||||
- Tracks progress and updates documentation
|
|
||||||
- Handles Git operations (commit, merge, cleanup)
|
|
||||||
- Manages task dependencies
|
|
||||||
- Personality: Concise, action-oriented, tracks details meticulously
|
|
||||||
|
|
||||||
**Executor Agent** (`agents/executor.md`)
|
|
||||||
- Implements features according to execution prompts
|
|
||||||
- Writes clean, tested code
|
|
||||||
- Follows architectural decisions from planning
|
|
||||||
- Generates completion reports
|
|
||||||
- Personality: Implementation-focused, follows specs precisely
|
|
||||||
|
|
||||||
### MCP Server Integration
|
|
||||||
|
|
||||||
**Gitea MCP Server** (Python) - bundled in projman plugin
|
|
||||||
|
|
||||||
**Issue Tools:**
|
|
||||||
- `list_issues` - Query issues with filters
|
|
||||||
- `get_issue` - Fetch single issue details
|
|
||||||
- `create_issue` - Create new issue with labels
|
|
||||||
- `update_issue` - Modify existing issue
|
|
||||||
- `add_comment` - Add comments to issues
|
|
||||||
- `get_labels` - Fetch org + repo label taxonomy
|
|
||||||
- `suggest_labels` - Analyze context and suggest appropriate labels
|
|
||||||
|
|
||||||
**Milestone Tools:**
|
|
||||||
- `list_milestones` - List sprint milestones
|
|
||||||
- `get_milestone` - Get milestone details
|
|
||||||
- `create_milestone` - Create sprint milestone
|
|
||||||
- `update_milestone` - Update/close milestone
|
|
||||||
|
|
||||||
**Dependency Tools:**
|
|
||||||
- `list_issue_dependencies` - Get issue dependencies
|
|
||||||
- `create_issue_dependency` - Create dependency between issues
|
|
||||||
- `get_execution_order` - Get parallel execution batches
|
|
||||||
|
|
||||||
**Wiki Tools (Gitea Wiki):**
|
|
||||||
- `list_wiki_pages` - List wiki pages
|
|
||||||
- `get_wiki_page` - Fetch specific page content
|
|
||||||
- `create_wiki_page` - Create new wiki page
|
|
||||||
- `create_lesson` - Create lessons learned document
|
|
||||||
- `search_lessons` - Search past lessons by tags
|
|
||||||
|
|
||||||
**Validation Tools:**
|
|
||||||
- `validate_repo_org` - Check repo belongs to organization
|
|
||||||
- `get_branch_protection` - Check branch protection rules
|
|
||||||
- `create_label` - Create missing required labels
|
|
||||||
|
|
||||||
**Key Architecture Points:**
|
|
||||||
- MCP servers are **bundled inside each plugin** at `plugins/{plugin}/mcp-servers/`
|
|
||||||
- This ensures plugins work when cached by Claude Code (only plugin directory is cached)
|
|
||||||
- Configuration uses hybrid approach (system-level + project-level)
|
|
||||||
- All plugins reference `${CLAUDE_PLUGIN_ROOT}/mcp-servers/` in their `.mcp.json` files
|
|
||||||
|
|
||||||
## Branch-Aware Security Model
|
|
||||||
|
|
||||||
Plugin behavior adapts to the current Git branch to prevent accidental changes:
|
|
||||||
|
|
||||||
**Development Mode** (`development`, `feat/*`)
|
|
||||||
- Full access to all operations
|
|
||||||
- Can create Gitea issues
|
|
||||||
- Can modify all files
|
|
||||||
|
|
||||||
**Staging Mode** (`staging`)
|
|
||||||
- Read-only for application code
|
|
||||||
- Can modify `.env` files
|
|
||||||
- Can create issues to document needed fixes
|
|
||||||
- Warns on attempted code changes
|
|
||||||
|
|
||||||
**Production Mode** (`main`)
|
|
||||||
- Read-only for application code
|
|
||||||
- Emergency-only `.env` modifications
|
|
||||||
- Can create incident issues
|
|
||||||
- Blocks code changes
|
|
||||||
|
|
||||||
This behavior is implemented in both CLAUDE.md (file-level) and plugin agents (tool-level).
|
|
||||||
|
|
||||||
## Label Taxonomy System
|
|
||||||
|
|
||||||
The project uses a sophisticated 43-label taxonomy at organization level:
|
|
||||||
|
|
||||||
**Organization Labels (27):**
|
|
||||||
- Agent/2, Complexity/3, Efforts/5, Priority/4, Risk/3, Source/4, Type/6
|
|
||||||
|
|
||||||
**Repository Labels (16):**
|
|
||||||
- Component/9, Tech/7
|
|
||||||
|
|
||||||
**Important Labels:**
|
|
||||||
- `Type/Refactor` - For architectural changes and code restructuring (exclusive Type label)
|
|
||||||
- Used for service extraction, architecture modifications, technical debt
|
|
||||||
|
|
||||||
The label system includes:
|
|
||||||
- `skills/label-taxonomy/labels-reference.md` - Local reference synced from Gitea
|
|
||||||
- Label suggestion logic that detects appropriate labels from context
|
|
||||||
- `/labels-sync` command to review and sync changes from Gitea
|
|
||||||
|
|
||||||
## Lessons Learned System
|
|
||||||
|
|
||||||
**Critical Feature:** After 15 sprints without lesson capture, repeated mistakes occurred (e.g., Claude Code infinite loops on similar issues 2-3 times).
|
|
||||||
|
|
||||||
**Gitea Wiki Structure:**
|
|
||||||
Lessons learned are stored in the Gitea repository's built-in wiki under `lessons-learned/sprints/`.
|
|
||||||
|
|
||||||
**Workflow:**
|
|
||||||
- Orchestrator captures lessons at sprint close via Gitea Wiki MCP tools
|
|
||||||
- Planner searches relevant lessons at sprint start using `search_lessons`
|
|
||||||
- Tags enable cross-project lesson discovery
|
|
||||||
- Focus on preventable repetitions, not every detail
|
|
||||||
- Web interface available through Gitea Wiki
|
|
||||||
|
|
||||||
## Development Workflow
|
|
||||||
|
|
||||||
### Build Order
|
|
||||||
|
|
||||||
1. **Phase 1-8:** Build `projman` plugin first (single-repo)
|
|
||||||
2. **Phase 9-11:** Build `pmo` plugin second (multi-project)
|
|
||||||
3. **Phase 12:** Production deployment
|
|
||||||
|
|
||||||
See [docs/reference-material/projman-implementation-plan.md](docs/reference-material/projman-implementation-plan.md) for the complete 12-phase implementation plan.
|
|
||||||
|
|
||||||
### Repository Structure (DEFINITIVE)
|
|
||||||
|
|
||||||
⚠️ **See `docs/CANONICAL-PATHS.md` for the authoritative path reference - THIS IS THE SINGLE SOURCE OF TRUTH**
|
|
||||||
|
|
||||||
```
|
```
|
||||||
bandit/support-claude-mktplace/
|
support-claude-mktplace/
|
||||||
├── .claude-plugin/
|
├── .claude-plugin/
|
||||||
│ └── marketplace.json
|
│ └── marketplace.json # Marketplace manifest
|
||||||
├── plugins/ # ← ALL PLUGINS (with bundled MCP servers)
|
├── plugins/
|
||||||
│ ├── projman/ # ← PROJECT PLUGIN
|
│ ├── projman/ # Sprint management
|
||||||
│ │ ├── .claude-plugin/
|
│ │ ├── .claude-plugin/plugin.json
|
||||||
│ │ │ └── plugin.json
|
|
||||||
│ │ ├── .mcp.json # Points to ${CLAUDE_PLUGIN_ROOT}/mcp-servers/
|
|
||||||
│ │ ├── mcp-servers/ # ← MCP servers BUNDLED IN plugin
|
|
||||||
│ │ │ └── gitea/ # Gitea + Wiki tools
|
|
||||||
│ │ │ ├── .venv/
|
|
||||||
│ │ │ ├── requirements.txt
|
|
||||||
│ │ │ ├── mcp_server/
|
|
||||||
│ │ │ └── tests/
|
|
||||||
│ │ ├── commands/
|
|
||||||
│ │ │ ├── sprint-plan.md
|
|
||||||
│ │ │ ├── sprint-start.md
|
|
||||||
│ │ │ ├── sprint-status.md
|
|
||||||
│ │ │ ├── sprint-close.md
|
|
||||||
│ │ │ ├── labels-sync.md
|
|
||||||
│ │ │ └── initial-setup.md
|
|
||||||
│ │ ├── agents/
|
|
||||||
│ │ │ ├── planner.md
|
|
||||||
│ │ │ ├── orchestrator.md
|
|
||||||
│ │ │ └── executor.md
|
|
||||||
│ │ ├── skills/
|
|
||||||
│ │ │ └── label-taxonomy/
|
|
||||||
│ │ │ └── labels-reference.md
|
|
||||||
│ │ ├── README.md
|
|
||||||
│ │ └── CONFIGURATION.md
|
|
||||||
│ ├── projman-pmo/ # ← PMO PLUGIN
|
|
||||||
│ │ ├── .claude-plugin/
|
|
||||||
│ │ │ └── plugin.json
|
|
||||||
│ │ ├── .mcp.json
|
│ │ ├── .mcp.json
|
||||||
│ │ ├── commands/
|
│ │ ├── mcp-servers/gitea/ # Bundled MCP server
|
||||||
│ │ ├── agents/
|
│ │ ├── commands/ # 9 commands
|
||||||
│ │ │ └── pmo-coordinator.md
|
│ │ │ ├── sprint-plan.md, sprint-start.md, sprint-status.md
|
||||||
│ │ └── README.md
|
│ │ │ ├── sprint-close.md, labels-sync.md, initial-setup.md
|
||||||
│ ├── cmdb-assistant/ # ← CMDB PLUGIN
|
│ │ │ └── review.md, test-check.md, test-gen.md
|
||||||
│ │ ├── .claude-plugin/
|
│ │ ├── agents/ # 4 agents
|
||||||
│ │ │ └── plugin.json
|
│ │ │ ├── planner.md, orchestrator.md, executor.md
|
||||||
│ │ ├── .mcp.json # Points to ${CLAUDE_PLUGIN_ROOT}/mcp-servers/
|
│ │ │ └── code-reviewer.md
|
||||||
│ │ ├── mcp-servers/ # ← MCP servers BUNDLED IN plugin
|
│ │ └── skills/label-taxonomy/
|
||||||
│ │ │ └── netbox/
|
│ ├── doc-guardian/ # Documentation drift detection
|
||||||
│ │ │ ├── .venv/
|
│ │ ├── .claude-plugin/plugin.json
|
||||||
│ │ │ ├── requirements.txt
|
│ │ ├── hooks/hooks.json # PostToolUse, Stop hooks
|
||||||
│ │ │ └── mcp_server/
|
│ │ ├── commands/ # doc-audit.md, doc-sync.md
|
||||||
│ │ ├── commands/
|
│ │ ├── agents/ # doc-analyzer.md
|
||||||
│ │ └── agents/
|
│ │ └── skills/doc-patterns/
|
||||||
│ └── project-hygiene/ # ← CLEANUP PLUGIN
|
│ ├── code-sentinel/ # Security scanning & refactoring
|
||||||
│ └── ...
|
│ │ ├── .claude-plugin/plugin.json
|
||||||
├── scripts/ # Setup and maintenance scripts
|
│ │ ├── hooks/hooks.json # PreToolUse hook
|
||||||
│ ├── setup.sh
|
│ │ ├── commands/ # security-scan.md, refactor.md, refactor-dry.md
|
||||||
│ └── post-update.sh
|
│ │ ├── agents/ # security-reviewer.md, refactor-advisor.md
|
||||||
|
│ │ └── skills/security-patterns/
|
||||||
|
│ ├── claude-config-maintainer/
|
||||||
|
│ ├── cmdb-assistant/
|
||||||
|
│ └── project-hygiene/
|
||||||
|
├── scripts/
|
||||||
|
│ ├── setup.sh, post-update.sh
|
||||||
|
│ └── validate-marketplace.sh # Marketplace compliance validation
|
||||||
└── docs/
|
└── docs/
|
||||||
|
├── CANONICAL-PATHS.md # Single source of truth for paths
|
||||||
|
└── references/
|
||||||
```
|
```
|
||||||
|
|
||||||
### Key Design Decisions
|
|
||||||
|
|
||||||
**MCP Servers (Bundled in Plugins):**
|
|
||||||
- **Gitea MCP**: Issues, labels, wiki, milestones, dependencies (bundled in projman)
|
|
||||||
- **NetBox MCP**: Infrastructure management (bundled in cmdb-assistant)
|
|
||||||
- Servers are **bundled inside each plugin** that needs them
|
|
||||||
- This ensures plugins work when cached by Claude Code
|
|
||||||
|
|
||||||
**Python Implementation:**
|
|
||||||
- Python chosen over Node.js for MCP servers
|
|
||||||
- Better suited for configuration management and modular code
|
|
||||||
- Easier to maintain and extend
|
|
||||||
- Virtual environment (.venv) per MCP server
|
|
||||||
|
|
||||||
**Hybrid Configuration:**
|
|
||||||
- **System-level**: `~/.config/claude/gitea.env` (credentials)
|
|
||||||
- **Project-level**: `project-root/.env` (repository specification)
|
|
||||||
- Merge strategy: project overrides system
|
|
||||||
- Benefits: Single token per service, easy multi-project setup
|
|
||||||
|
|
||||||
**Skills as Knowledge, Not Orchestrators:**
|
|
||||||
- Skills provide supporting knowledge loaded when relevant
|
|
||||||
- Agents are the primary interface
|
|
||||||
- Reduces token usage
|
|
||||||
- Makes knowledge reusable across agents
|
|
||||||
|
|
||||||
**Branch Detection:**
|
|
||||||
- Two layers: CLAUDE.md (file access) + Plugin agents (tool usage)
|
|
||||||
- Defense in depth approach
|
|
||||||
- Plugin works with or without CLAUDE.md
|
|
||||||
|
|
||||||
## Multi-Project Context (PMO Plugin)
|
|
||||||
|
|
||||||
The `projman-pmo` plugin coordinates interdependent projects across an organization. Example use cases:
|
|
||||||
- Main product repository
|
|
||||||
- Marketing/documentation sites
|
|
||||||
- Extracted services
|
|
||||||
- Supporting tools
|
|
||||||
|
|
||||||
PMO plugin adds:
|
|
||||||
- Cross-project issue aggregation (all repos in organization)
|
|
||||||
- Dependency tracking and visualization
|
|
||||||
- Resource allocation across projects
|
|
||||||
- Deployment coordination
|
|
||||||
- Multi-project prioritization
|
|
||||||
- Company-wide lessons learned search
|
|
||||||
|
|
||||||
**Configuration Difference:**
|
|
||||||
- PMO operates at company level (no `GITEA_REPO`)
|
|
||||||
- Accesses all repositories in organization
|
|
||||||
- Aggregates issues and lessons across projects
|
|
||||||
|
|
||||||
Build PMO plugin AFTER projman is working and validated.
|
|
||||||
|
|
||||||
## Testing Approach
|
|
||||||
|
|
||||||
**Local Marketplace:**
|
|
||||||
Create local marketplace for plugin development:
|
|
||||||
```
|
|
||||||
~/projman-dev-marketplace/
|
|
||||||
├── .claude-plugin/
|
|
||||||
│ └── marketplace.json
|
|
||||||
└── projman/ # Symlink to plugin directory
|
|
||||||
```
|
|
||||||
|
|
||||||
**Integration Testing:**
|
|
||||||
Test in a real repository with actual Gitea instance before distribution.
|
|
||||||
|
|
||||||
**Success Metrics:**
|
|
||||||
- Sprint planning time reduced 40%
|
|
||||||
- Manual steps eliminated: 10+ per sprint
|
|
||||||
- Lessons learned capture rate: 100% (vs 0% before)
|
|
||||||
- Label accuracy on issues: 90%+
|
|
||||||
- User satisfaction: Better than current manual workflow
|
|
||||||
|
|
||||||
## Important Notes
|
|
||||||
|
|
||||||
- **Never modify docker-compose files with 'version' attribute** - It's obsolete
|
|
||||||
- **Focus on implementation, not over-engineering** - This system has been validated over 15 sprints
|
|
||||||
- **Lessons learned is critical** - Prevents repeated mistakes (e.g., Claude infinite loops)
|
|
||||||
- **Type/Refactor label** - Newly implemented at org level for architectural work
|
|
||||||
- **Branch detection must be 100% reliable** - Prevents production accidents
|
|
||||||
- **Python for MCP servers** - Use Python 3.8+ with virtual environments
|
|
||||||
- **CLI tools forbidden** - Use MCP tools exclusively, never CLI tools like `tea` or `gh`
|
|
||||||
|
|
||||||
## CRITICAL: Rules You MUST Follow
|
## CRITICAL: Rules You MUST Follow
|
||||||
|
|
||||||
### DO NOT MODIFY .gitignore Without Explicit Permission
|
### File Operations
|
||||||
- This is a **private repository** - credentials in `.env` files are intentional
|
- **NEVER** create files in repository root unless listed in "Allowed Root Files"
|
||||||
- **NEVER** add `.env` or `.env.*` to .gitignore
|
- **NEVER** modify `.gitignore` without explicit permission
|
||||||
- **NEVER** add venv patterns unless explicitly asked
|
- **ALWAYS** use `.scratch/` for temporary/exploratory work
|
||||||
- If you think something should be ignored, ASK FIRST
|
- **ALWAYS** verify paths against `docs/CANONICAL-PATHS.md` before creating files
|
||||||
|
|
||||||
### Plugin Structure Requirements
|
### Plugin Development
|
||||||
- **plugin.json MUST be in `.claude-plugin/` directory** - NOT in plugin root
|
- **plugin.json MUST be in `.claude-plugin/` directory** (not plugin root)
|
||||||
- Every plugin in the repo MUST be listed in the marketplace.json
|
- **Every plugin MUST be listed in marketplace.json**
|
||||||
- After creating/modifying a plugin, VERIFY it's in the marketplace
|
- **MCP servers MUST use venv python path**: `${CLAUDE_PLUGIN_ROOT}/mcp-servers/{name}/.venv/bin/python`
|
||||||
|
- **CLI tools forbidden** - Use MCP tools exclusively (never `tea`, `gh`, etc.)
|
||||||
|
|
||||||
### Hooks Syntax (Claude Code Official)
|
### Hooks (Valid Events Only)
|
||||||
- **Valid events**: `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
|
`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
|
||||||
- **INVALID events**: `task-completed`, `file-changed`, `git-commit-msg-needed` (these DO NOT exist)
|
|
||||||
- Hooks schema:
|
**INVALID:** `task-completed`, `file-changed`, `git-commit-msg-needed`
|
||||||
```json
|
|
||||||
{
|
### Allowed Root Files
|
||||||
"hooks": {
|
`CLAUDE.md`, `README.md`, `LICENSE`, `CHANGELOG.md`, `.gitignore`, `.env.example`
|
||||||
"EventName": [
|
|
||||||
{
|
### Allowed Root Directories
|
||||||
"matcher": "optional-pattern",
|
`.claude/`, `.claude-plugin/`, `.claude-plugins/`, `.scratch/`, `docs/`, `hooks/`, `plugins/`, `scripts/`
|
||||||
"hooks": [
|
|
||||||
{
|
## Architecture
|
||||||
"type": "command",
|
|
||||||
"command": "${CLAUDE_PLUGIN_ROOT}/path/to/script.sh"
|
### Four-Agent Model
|
||||||
}
|
|
||||||
]
|
| Agent | Personality | Responsibilities |
|
||||||
}
|
|-------|-------------|------------------|
|
||||||
]
|
| **Planner** | Thoughtful, methodical | Sprint planning, architecture analysis, issue creation, lesson search |
|
||||||
}
|
| **Orchestrator** | Concise, action-oriented | Sprint execution, parallel batching, Git operations, lesson capture |
|
||||||
}
|
| **Executor** | Implementation-focused | Code implementation, branch management, MR creation |
|
||||||
|
| **Code Reviewer** | Thorough, practical | Pre-close quality review, security scan, test verification |
|
||||||
|
|
||||||
|
### MCP Server Tools (Gitea)
|
||||||
|
|
||||||
|
| Category | Tools |
|
||||||
|
|----------|-------|
|
||||||
|
| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment` |
|
||||||
|
| Labels | `get_labels`, `suggest_labels`, `create_label` |
|
||||||
|
| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone` |
|
||||||
|
| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `get_execution_order` |
|
||||||
|
| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `create_lesson`, `search_lessons` |
|
||||||
|
| Validation | `validate_repo_org`, `get_branch_protection` |
|
||||||
|
|
||||||
|
### Hybrid Configuration
|
||||||
|
|
||||||
|
| Level | Location | Purpose |
|
||||||
|
|-------|----------|---------|
|
||||||
|
| System | `~/.config/claude/gitea.env` | Credentials (GITEA_URL, GITEA_TOKEN, GITEA_ORG) |
|
||||||
|
| Project | `.env` in project root | Repository specification (GITEA_REPO) |
|
||||||
|
|
||||||
|
### Branch-Aware Security
|
||||||
|
|
||||||
|
| Branch Pattern | Mode | Capabilities |
|
||||||
|
|----------------|------|--------------|
|
||||||
|
| `development`, `feat/*` | Development | Full access |
|
||||||
|
| `staging` | Staging | Read-only code, can create issues |
|
||||||
|
| `main`, `master` | Production | Read-only, emergency only |
|
||||||
|
|
||||||
|
## Label Taxonomy
|
||||||
|
|
||||||
|
43 labels total: 27 organization + 16 repository
|
||||||
|
|
||||||
|
**Organization:** Agent/2, Complexity/3, Efforts/5, Priority/4, Risk/3, Source/4, Type/6
|
||||||
|
**Repository:** Component/9, Tech/7
|
||||||
|
|
||||||
|
Sync with `/labels-sync` command.
|
||||||
|
|
||||||
|
## Lessons Learned System
|
||||||
|
|
||||||
|
Stored in Gitea Wiki under `lessons-learned/sprints/`.
|
||||||
|
|
||||||
|
**Workflow:**
|
||||||
|
1. Orchestrator captures at sprint close via MCP tools
|
||||||
|
2. Planner searches at sprint start using `search_lessons`
|
||||||
|
3. Tags enable cross-project discovery
|
||||||
|
|
||||||
|
## Common Operations
|
||||||
|
|
||||||
|
### Adding a New Plugin
|
||||||
|
|
||||||
|
1. Create `plugins/{name}/.claude-plugin/plugin.json`
|
||||||
|
2. Add entry to `.claude-plugin/marketplace.json`
|
||||||
|
3. Create `README.md` and `claude-md-integration.md`
|
||||||
|
4. Run `./scripts/validate-marketplace.sh`
|
||||||
|
5. Update `CHANGELOG.md`
|
||||||
|
|
||||||
|
### Adding a Command to projman
|
||||||
|
|
||||||
|
1. Create `plugins/projman/commands/{name}.md`
|
||||||
|
2. Update `plugins/projman/README.md`
|
||||||
|
3. Update marketplace description if significant
|
||||||
|
|
||||||
|
### Validation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./scripts/validate-marketplace.sh # Validates all manifests
|
||||||
```
|
```
|
||||||
|
|
||||||
### MCP Server Configuration
|
## Path Verification Protocol
|
||||||
- MCP servers MUST use venv python: `${CLAUDE_PLUGIN_ROOT}/../../mcp-servers/NAME/.venv/bin/python`
|
|
||||||
- NEVER use bare `python` command - always use venv path
|
|
||||||
- Test MCP servers after any config change
|
|
||||||
|
|
||||||
### Before Completing Any Plugin Work
|
**Before creating any file:**
|
||||||
1. Verify plugin.json is in `.claude-plugin/` directory
|
|
||||||
2. Verify plugin is listed in marketplace.json
|
1. Read `docs/CANONICAL-PATHS.md`
|
||||||
3. Test MCP server configs load correctly
|
2. List all paths to be created/modified
|
||||||
4. Verify hooks use valid event types
|
3. Verify each against canonical paths
|
||||||
5. Check .gitignore wasn't modified inappropriately
|
4. If not in canonical paths, STOP and ask
|
||||||
|
|
||||||
## Documentation Index
|
## Documentation Index
|
||||||
|
|
||||||
This repository contains comprehensive planning documentation:
|
| Document | Purpose |
|
||||||
|
|----------|---------|
|
||||||
|
| `docs/CANONICAL-PATHS.md` | **Single source of truth** for paths |
|
||||||
|
| `docs/UPDATING.md` | Update guide for the marketplace |
|
||||||
|
| `plugins/projman/CONFIGURATION.md` | Projman setup guide |
|
||||||
|
| `plugins/projman/README.md` | Projman full documentation |
|
||||||
|
|
||||||
- **`docs/CANONICAL-PATHS.md`** - ⚠️ SINGLE SOURCE OF TRUTH for all paths (MANDATORY reading before any file operations)
|
## Versioning and Changelog Rules
|
||||||
- **`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
|
|
||||||
- **`docs/two-mcp-architecture-guide.md`** - Deep dive into two-MCP architecture
|
|
||||||
|
|
||||||
**Start with:** `docs/DOCUMENT-INDEX.md` for navigation guidance
|
### Version Display
|
||||||
|
**The marketplace version is displayed ONLY in the main `README.md` title.**
|
||||||
|
|
||||||
## Recent Updates (Updated: 2025-06-11)
|
- Format: `# Claude Code Marketplace - vX.Y.Z`
|
||||||
|
- Do NOT add version numbers to individual plugin documentation titles
|
||||||
|
- Do NOT add version numbers to configuration guides
|
||||||
|
- Do NOT add version numbers to CLAUDE.md or other docs
|
||||||
|
|
||||||
### Planning Phase Complete
|
### Changelog Maintenance (MANDATORY)
|
||||||
- Comprehensive 12-phase implementation plan finalized
|
**`CHANGELOG.md` is the authoritative source for version history.**
|
||||||
- Architecture decisions documented and validated
|
|
||||||
- Two-MCP-server approach confirmed (Gitea + Wiki.js)
|
|
||||||
- Python selected for MCP server implementation
|
|
||||||
- Hybrid configuration strategy defined (system + project level)
|
|
||||||
- Wiki.js structure planned with configurable base path
|
|
||||||
- Repository structure designed with shared MCP servers
|
|
||||||
|
|
||||||
### Key Architectural Decisions Made
|
When releasing a new version:
|
||||||
1. **Shared MCP Servers**: Both plugins use the same MCP codebase at `mcp-servers/`
|
1. Update main `README.md` title with new version
|
||||||
2. **Mode Detection**: MCP servers detect project vs company-wide mode via environment variables
|
2. Update `CHANGELOG.md` with:
|
||||||
3. **Python Implementation**: MCP servers written in Python (not Node.js) for better configuration handling
|
- Version number and date: `## [X.Y.Z] - YYYY-MM-DD`
|
||||||
4. **Wiki.js Integration**: Lessons learned and documentation moved to Wiki.js for better collaboration
|
- **Added**: New features, commands, files
|
||||||
5. **Hybrid Config**: System-level credentials + project-level paths for flexibility
|
- **Changed**: Modifications to existing functionality
|
||||||
|
- **Fixed**: Bug fixes
|
||||||
|
- **Removed**: Deleted features, files, deprecated items
|
||||||
|
3. Update `marketplace.json` metadata version
|
||||||
|
4. Update plugin `plugin.json` versions if plugin-specific changes
|
||||||
|
|
||||||
### Next Steps
|
### Version Format
|
||||||
- Begin Phase 1.1a: Gitea MCP Server implementation
|
- Follow [Semantic Versioning](https://semver.org/): MAJOR.MINOR.PATCH
|
||||||
- Set up Python virtual environments
|
- MAJOR: Breaking changes
|
||||||
- Create configuration loaders
|
- MINOR: New features, backward compatible
|
||||||
- Implement core Gitea tools (issues, labels)
|
- PATCH: Bug fixes, minor improvements
|
||||||
- Write integration tests
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Last Updated:** 2026-01-20
|
||||||
|
|||||||
21
LICENSE
Normal file
21
LICENSE
Normal file
@@ -0,0 +1,21 @@
|
|||||||
|
MIT License
|
||||||
|
|
||||||
|
Copyright (c) 2025 Leo Miranda
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
100
README.md
100
README.md
@@ -1,22 +1,23 @@
|
|||||||
# Claude Code Marketplace - Bandit Labs
|
# Claude Code Marketplace - v2.3.0
|
||||||
|
|
||||||
A collection of Claude Code plugins for project management, infrastructure automation, and development workflows.
|
A collection of Claude Code plugins for project management, infrastructure automation, and development workflows.
|
||||||
|
|
||||||
## Plugins
|
## Plugins
|
||||||
|
|
||||||
### [projman](./plugins/projman/README.md) v2.0.0
|
### [projman](./plugins/projman/README.md)
|
||||||
**Sprint Planning and Project Management**
|
**Sprint Planning and Project Management**
|
||||||
|
|
||||||
AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sprint workflow into a distributable plugin.
|
AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sprint workflow into a distributable plugin.
|
||||||
|
|
||||||
- Three-agent model: Planner, Orchestrator, Executor
|
- Three-agent model: Planner, Orchestrator, Executor, Code Reviewer
|
||||||
- Intelligent label suggestions from 43-label taxonomy
|
- Intelligent label suggestions from 43-label taxonomy
|
||||||
- Lessons learned capture via Gitea Wiki
|
- Lessons learned capture via Gitea Wiki
|
||||||
- Native issue dependencies with parallel execution
|
- Native issue dependencies with parallel execution
|
||||||
- Milestone management for sprint organization
|
- Milestone management for sprint organization
|
||||||
- Branch-aware security (development/staging/production)
|
- Branch-aware security (development/staging/production)
|
||||||
|
- Pre-sprint-close code quality review and test verification
|
||||||
|
|
||||||
**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup`
|
**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup`, `/review`, `/test-check`, `/test-gen`
|
||||||
|
|
||||||
### [claude-config-maintainer](./plugins/claude-config-maintainer/README.md)
|
### [claude-config-maintainer](./plugins/claude-config-maintainer/README.md)
|
||||||
**CLAUDE.md Optimization and Maintenance**
|
**CLAUDE.md Optimization and Maintenance**
|
||||||
@@ -52,6 +53,28 @@ Hook-based cleanup that runs after Claude completes work.
|
|||||||
- Identifies orphaned supporting files
|
- Identifies orphaned supporting files
|
||||||
- Configurable via `.hygiene.json`
|
- Configurable via `.hygiene.json`
|
||||||
|
|
||||||
|
### [doc-guardian](./plugins/doc-guardian/README.md)
|
||||||
|
**Documentation Lifecycle Management**
|
||||||
|
|
||||||
|
Automatic documentation drift detection and synchronization. Eliminates manual doc update cycles.
|
||||||
|
|
||||||
|
- PostToolUse hook detects when code changes affect documentation
|
||||||
|
- Stop hook reminds of pending updates before session ends
|
||||||
|
- Batched updates in single commit
|
||||||
|
|
||||||
|
**Commands:** `/doc-audit`, `/doc-sync`
|
||||||
|
|
||||||
|
### [code-sentinel](./plugins/code-sentinel/README.md)
|
||||||
|
**Security Scanning & Refactoring**
|
||||||
|
|
||||||
|
Security vulnerability detection and code refactoring tools.
|
||||||
|
|
||||||
|
- PreToolUse hook catches security issues before code is written
|
||||||
|
- Pattern library: SQL injection, XSS, command injection, hardcoded secrets
|
||||||
|
- Refactoring patterns: extract method, simplify conditional, modernize syntax
|
||||||
|
|
||||||
|
**Commands:** `/security-scan`, `/refactor`, `/refactor-dry`
|
||||||
|
|
||||||
## MCP Servers
|
## MCP Servers
|
||||||
|
|
||||||
MCP servers are **bundled inside each plugin** that needs them. This ensures plugins work when cached by Claude Code.
|
MCP servers are **bundled inside each plugin** that needs them. This ensures plugins work when cached by Claude Code.
|
||||||
@@ -89,15 +112,47 @@ Comprehensive NetBox REST API integration for infrastructure management.
|
|||||||
- Python 3.10+
|
- Python 3.10+
|
||||||
- Access to target services (Gitea, NetBox as needed)
|
- Access to target services (Gitea, NetBox as needed)
|
||||||
|
|
||||||
### Quick Start
|
### Add Marketplace to Claude Code
|
||||||
|
|
||||||
1. **Clone the repository:**
|
**Option 1 - CLI command (recommended):**
|
||||||
```bash
|
```bash
|
||||||
git clone ssh://git@hotserv.tailc9b278.ts.net:2222/bandit/support-claude-mktplace.git
|
/plugin marketplace add https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git
|
||||||
cd support-claude-mktplace
|
|
||||||
```
|
```
|
||||||
|
|
||||||
2. **Install MCP server dependencies:**
|
**Option 2 - Settings file (for team distribution):**
|
||||||
|
|
||||||
|
Add to `.claude/settings.json` in your target project:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"extraKnownMarketplaces": {
|
||||||
|
"support-claude-mktplace": {
|
||||||
|
"source": {
|
||||||
|
"source": "git",
|
||||||
|
"url": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Option 3 - Local development:**
|
||||||
|
```bash
|
||||||
|
# Clone the repository first
|
||||||
|
git clone https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git
|
||||||
|
|
||||||
|
# Then add from local path
|
||||||
|
/plugin marketplace add /path/to/support-claude-mktplace
|
||||||
|
```
|
||||||
|
|
||||||
|
**Alternative SSH URL (for authenticated access):**
|
||||||
|
```
|
||||||
|
ssh://git@hotserv.tailc9b278.ts.net:2222/personal-projects/support-claude-mktplace.git
|
||||||
|
```
|
||||||
|
|
||||||
|
### Configure MCP Server Dependencies
|
||||||
|
|
||||||
|
If using plugins with MCP servers (projman, cmdb-assistant), install dependencies:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Gitea MCP (for projman)
|
# Gitea MCP (for projman)
|
||||||
cd plugins/projman/mcp-servers/gitea
|
cd plugins/projman/mcp-servers/gitea
|
||||||
@@ -114,7 +169,9 @@ Comprehensive NetBox REST API integration for infrastructure management.
|
|||||||
deactivate
|
deactivate
|
||||||
```
|
```
|
||||||
|
|
||||||
3. **Configure system-level credentials:**
|
### Configure Credentials
|
||||||
|
|
||||||
|
**System-level credentials:**
|
||||||
```bash
|
```bash
|
||||||
mkdir -p ~/.config/claude
|
mkdir -p ~/.config/claude
|
||||||
|
|
||||||
@@ -134,7 +191,7 @@ Comprehensive NetBox REST API integration for infrastructure management.
|
|||||||
chmod 600 ~/.config/claude/*.env
|
chmod 600 ~/.config/claude/*.env
|
||||||
```
|
```
|
||||||
|
|
||||||
4. **Configure project-level settings:**
|
**Project-level settings:**
|
||||||
```bash
|
```bash
|
||||||
# In your target project root
|
# In your target project root
|
||||||
cat > .env << 'EOF'
|
cat > .env << 'EOF'
|
||||||
@@ -142,15 +199,6 @@ Comprehensive NetBox REST API integration for infrastructure management.
|
|||||||
EOF
|
EOF
|
||||||
```
|
```
|
||||||
|
|
||||||
5. **Add marketplace to Claude Code:**
|
|
||||||
|
|
||||||
Add to your project's `.claude/settings.json`:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"pluginMarketplace": "/path/to/support-claude-mktplace"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Repository Structure
|
## Repository Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
@@ -178,14 +226,17 @@ support-claude-mktplace/
|
|||||||
│ │ ├── commands/
|
│ │ ├── commands/
|
||||||
│ │ └── agents/
|
│ │ └── agents/
|
||||||
│ ├── projman-pmo/ # PMO coordination plugin (planned)
|
│ ├── projman-pmo/ # PMO coordination plugin (planned)
|
||||||
│ └── project-hygiene/ # Cleanup automation plugin
|
│ ├── project-hygiene/ # Cleanup automation plugin
|
||||||
|
│ ├── doc-guardian/ # Documentation drift detection
|
||||||
|
│ └── code-sentinel/ # Security scanning & refactoring
|
||||||
├── docs/ # Reference documentation
|
├── docs/ # Reference documentation
|
||||||
│ ├── CANONICAL-PATHS.md # Single source of truth for paths
|
│ ├── CANONICAL-PATHS.md # Single source of truth for paths
|
||||||
│ └── references/
|
│ └── references/
|
||||||
└── scripts/ # Setup and maintenance scripts
|
└── scripts/ # Setup and maintenance scripts
|
||||||
|
└── validate-marketplace.sh # Marketplace compliance validation
|
||||||
```
|
```
|
||||||
|
|
||||||
## Key Features (v2.0.0)
|
## Key Features
|
||||||
|
|
||||||
### Parallel Execution
|
### Parallel Execution
|
||||||
Tasks are batched by dependency graph for optimal parallel execution:
|
Tasks are batched by dependency graph for optimal parallel execution:
|
||||||
@@ -212,9 +263,10 @@ All agents use MCP tools exclusively. CLI tools like `tea` or `gh` are forbidden
|
|||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
MIT License - Bandit Labs
|
MIT License
|
||||||
|
|
||||||
## Support
|
## Support
|
||||||
|
|
||||||
- **Issues**: Contact repository maintainer
|
- **Issues**: Contact repository maintainer
|
||||||
- **Repository**: `ssh://git@hotserv.tailc9b278.ts.net:2222/bandit/support-claude-mktplace.git`
|
- **Repository**: `https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git`
|
||||||
|
- **SSH URL**: `ssh://git@hotserv.tailc9b278.ts.net:2222/personal-projects/support-claude-mktplace.git`
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
**This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.**
|
**This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.**
|
||||||
|
|
||||||
Last Updated: 2025-12-15
|
Last Updated: 2026-01-20
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -11,12 +11,13 @@ Last Updated: 2025-12-15
|
|||||||
```
|
```
|
||||||
support-claude-mktplace/
|
support-claude-mktplace/
|
||||||
├── .claude/ # Claude Code local settings
|
├── .claude/ # Claude Code local settings
|
||||||
├── .claude-plugin/ # Marketplace manifest (bandit-claude-marketplace)
|
├── .claude-plugin/ # Marketplace manifest (claude-code-marketplace)
|
||||||
│ └── marketplace.json
|
│ └── marketplace.json
|
||||||
├── .scratch/ # Transient work (auto-cleaned)
|
├── .scratch/ # Transient work (auto-cleaned)
|
||||||
├── docs/ # All documentation
|
├── docs/ # All documentation
|
||||||
│ ├── architecture/ # Draw.io diagrams and specs
|
│ ├── architecture/ # Draw.io diagrams and specs
|
||||||
│ ├── references/ # Reference specifications
|
│ ├── CANONICAL-PATHS.md # This file - single source of truth
|
||||||
|
│ ├── UPDATING.md # Update guide
|
||||||
│ └── workflows/ # Workflow documentation
|
│ └── workflows/ # Workflow documentation
|
||||||
├── hooks/ # Shared hooks (if any)
|
├── hooks/ # Shared hooks (if any)
|
||||||
├── plugins/ # ALL plugins with bundled MCP servers
|
├── plugins/ # ALL plugins with bundled MCP servers
|
||||||
@@ -26,19 +27,39 @@ support-claude-mktplace/
|
|||||||
│ │ │ └── gitea/ # Gitea + Wiki tools
|
│ │ │ └── gitea/ # Gitea + Wiki tools
|
||||||
│ │ ├── commands/
|
│ │ ├── commands/
|
||||||
│ │ ├── agents/
|
│ │ ├── agents/
|
||||||
│ │ └── skills/
|
│ │ ├── 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/
|
│ ├── projman-pmo/
|
||||||
│ ├── project-hygiene/
|
|
||||||
│ ├── cmdb-assistant/
|
│ ├── cmdb-assistant/
|
||||||
│ │ ├── .claude-plugin/
|
│ │ ├── .claude-plugin/
|
||||||
│ │ ├── mcp-servers/ # MCP servers bundled IN plugin
|
│ │ ├── mcp-servers/ # MCP servers bundled IN plugin
|
||||||
│ │ │ └── netbox/
|
│ │ │ └── netbox/
|
||||||
│ │ ├── commands/
|
│ │ ├── commands/
|
||||||
│ │ └── agents/
|
│ │ ├── agents/
|
||||||
│ └── claude-config-maintainer/
|
│ │ └── 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/
|
│ ├── .claude-plugin/
|
||||||
│ ├── commands/
|
│ ├── hooks/
|
||||||
│ └── agents/
|
│ └── claude-md-integration.md # CLAUDE.md integration snippet
|
||||||
├── scripts/ # Setup and maintenance scripts
|
├── scripts/ # Setup and maintenance scripts
|
||||||
├── CLAUDE.md
|
├── CLAUDE.md
|
||||||
├── README.md
|
├── README.md
|
||||||
@@ -60,6 +81,7 @@ support-claude-mktplace/
|
|||||||
| Plugin commands | `plugins/{plugin-name}/commands/` | `plugins/projman/commands/` |
|
| Plugin commands | `plugins/{plugin-name}/commands/` | `plugins/projman/commands/` |
|
||||||
| Plugin agents | `plugins/{plugin-name}/agents/` | `plugins/projman/agents/` |
|
| Plugin agents | `plugins/{plugin-name}/agents/` | `plugins/projman/agents/` |
|
||||||
| Plugin .mcp.json | `plugins/{plugin-name}/.mcp.json` | `plugins/projman/.mcp.json` |
|
| 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 Server Paths (Bundled in Plugins)
|
||||||
|
|
||||||
@@ -82,10 +104,10 @@ MCP servers are now **bundled inside each plugin** to ensure they work when plug
|
|||||||
|
|
||||||
| Type | Location |
|
| Type | Location |
|
||||||
|------|----------|
|
|------|----------|
|
||||||
| Reference specs | `docs/references/` |
|
|
||||||
| Architecture diagrams | `docs/architecture/` |
|
| Architecture diagrams | `docs/architecture/` |
|
||||||
| Workflow docs | `docs/workflows/` |
|
| Workflow docs | `docs/workflows/` |
|
||||||
| This file | `docs/CANONICAL-PATHS.md` |
|
| This file | `docs/CANONICAL-PATHS.md` |
|
||||||
|
| Update guide | `docs/UPDATING.md` |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -149,5 +171,7 @@ MCP servers are bundled inside each plugin (not shared at root) because:
|
|||||||
|
|
||||||
| Date | Change | By |
|
| 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-15 | Restructured: MCP servers now bundled in plugins | Claude Code |
|
||||||
| 2025-12-12 | Initial creation | Claude Code |
|
| 2025-12-12 | Initial creation | Claude Code |
|
||||||
|
|||||||
@@ -15,7 +15,7 @@ git pull origin main
|
|||||||
|
|
||||||
## What the Post-Update Script Does
|
## What the Post-Update Script Does
|
||||||
|
|
||||||
1. **Updates Python dependencies** for Gitea and Wiki.js MCP servers
|
1. **Updates Python dependencies** for MCP servers
|
||||||
2. **Shows recent changelog entries** so you know what changed
|
2. **Shows recent changelog entries** so you know what changed
|
||||||
3. **Validates your configuration** is still compatible
|
3. **Validates your configuration** is still compatible
|
||||||
|
|
||||||
@@ -30,7 +30,6 @@ If the changelog mentions new environment variables:
|
|||||||
1. Check the variable name and purpose in the changelog
|
1. Check the variable name and purpose in the changelog
|
||||||
2. Add it to the appropriate config file:
|
2. Add it to the appropriate config file:
|
||||||
- Gitea variables → `~/.config/claude/gitea.env`
|
- Gitea variables → `~/.config/claude/gitea.env`
|
||||||
- Wiki.js variables → `~/.config/claude/wikijs.env`
|
|
||||||
- Project variables → `.env` in your project root
|
- Project variables → `.env` in your project root
|
||||||
|
|
||||||
### New MCP Server Features
|
### New MCP Server Features
|
||||||
@@ -38,7 +37,7 @@ If the changelog mentions new environment variables:
|
|||||||
If a new MCP server tool is added:
|
If a new MCP server tool is added:
|
||||||
|
|
||||||
1. The post-update script handles dependency installation
|
1. The post-update script handles dependency installation
|
||||||
2. Check `docs/references/MCP-*.md` for usage documentation
|
2. Check `plugins/projman/README.md` for usage documentation
|
||||||
3. New tools are available immediately after update
|
3. New tools are available immediately after update
|
||||||
|
|
||||||
### Breaking Changes
|
### Breaking Changes
|
||||||
@@ -51,15 +50,7 @@ Breaking changes will be clearly marked in CHANGELOG.md with migration instructi
|
|||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Rebuild virtual environment
|
# Rebuild virtual environment
|
||||||
cd mcp-servers/gitea
|
cd plugins/projman/mcp-servers/gitea
|
||||||
rm -rf .venv
|
|
||||||
python3 -m venv .venv
|
|
||||||
source .venv/bin/activate
|
|
||||||
pip install -r requirements.txt
|
|
||||||
deactivate
|
|
||||||
|
|
||||||
# Repeat for wikijs
|
|
||||||
cd ../wikijs
|
|
||||||
rm -rf .venv
|
rm -rf .venv
|
||||||
python3 -m venv .venv
|
python3 -m venv .venv
|
||||||
source .venv/bin/activate
|
source .venv/bin/activate
|
||||||
@@ -76,7 +67,7 @@ deactivate
|
|||||||
### MCP server won't start
|
### MCP server won't start
|
||||||
|
|
||||||
1. Check Python version: `python3 --version` (requires 3.10+)
|
1. Check Python version: `python3 --version` (requires 3.10+)
|
||||||
2. Verify venv exists: `ls mcp-servers/gitea/.venv`
|
2. Verify venv exists: `ls plugins/projman/mcp-servers/gitea/.venv`
|
||||||
3. Check logs for specific errors
|
3. Check logs for specific errors
|
||||||
|
|
||||||
## Version Pinning
|
## Version Pinning
|
||||||
@@ -88,7 +79,7 @@ To stay on a specific version:
|
|||||||
git tag
|
git tag
|
||||||
|
|
||||||
# Checkout specific version
|
# Checkout specific version
|
||||||
git checkout v1.0.0
|
git checkout v2.2.0
|
||||||
|
|
||||||
# Run post-update
|
# Run post-update
|
||||||
./scripts/post-update.sh
|
./scripts/post-update.sh
|
||||||
@@ -96,6 +87,7 @@ git checkout v1.0.0
|
|||||||
|
|
||||||
## Getting Help
|
## Getting Help
|
||||||
|
|
||||||
- Check `docs/references/` for component documentation
|
- Check `plugins/projman/README.md` for projman documentation
|
||||||
|
- Check `plugins/projman/CONFIGURATION.md` for setup guide
|
||||||
- Review CHANGELOG.md for recent changes
|
- Review CHANGELOG.md for recent changes
|
||||||
- Search existing issues in Gitea
|
- Search existing issues in Gitea
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
**Target File:** `docs/architecture/agent-workflow.drawio`
|
**Target File:** `docs/architecture/agent-workflow.drawio`
|
||||||
|
|
||||||
**Purpose:** Shows when Planner, Orchestrator, and Executor agents trigger during sprint lifecycle.
|
**Purpose:** Shows when Planner, Orchestrator, Executor, and Code Reviewer agents trigger during sprint lifecycle.
|
||||||
|
|
||||||
**Diagram Type:** Swimlane / Sequence Diagram
|
**Diagram Type:** Swimlane / Sequence Diagram
|
||||||
|
|
||||||
@@ -16,8 +16,8 @@
|
|||||||
| planner-lane | Planner Agent | #4A90D9 | 2 |
|
| planner-lane | Planner Agent | #4A90D9 | 2 |
|
||||||
| orchestrator-lane | Orchestrator Agent | #7CB342 | 3 |
|
| orchestrator-lane | Orchestrator Agent | #7CB342 | 3 |
|
||||||
| executor-lane | Executor Agent | #FF9800 | 4 |
|
| executor-lane | Executor Agent | #FF9800 | 4 |
|
||||||
| gitea-lane | Gitea | #9E9E9E | 5 |
|
| reviewer-lane | Code Reviewer Agent | #9C27B0 | 5 |
|
||||||
| wikijs-lane | Wiki.js | #9E9E9E | 6 (rightmost) |
|
| gitea-lane | Gitea (Issues + Wiki) | #9E9E9E | 6 (rightmost) |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -30,7 +30,7 @@
|
|||||||
| p1-start | /sprint-plan | rounded-rect | user-lane | 1 |
|
| p1-start | /sprint-plan | rounded-rect | user-lane | 1 |
|
||||||
| p1-activate | Planner Activates | rectangle | planner-lane | 2 |
|
| p1-activate | Planner Activates | rectangle | planner-lane | 2 |
|
||||||
| p1-search-lessons | Search Lessons Learned | rectangle | planner-lane | 3 |
|
| p1-search-lessons | Search Lessons Learned | rectangle | planner-lane | 3 |
|
||||||
| p1-wikijs-query | Query Past Lessons | rectangle | wikijs-lane | 4 |
|
| p1-gitea-wiki-query | Query Past Lessons (Wiki) | rectangle | gitea-lane | 4 |
|
||||||
| p1-return-lessons | Return Relevant Lessons | rectangle | planner-lane | 5 |
|
| p1-return-lessons | Return Relevant Lessons | rectangle | planner-lane | 5 |
|
||||||
| p1-clarify | Ask Clarifying Questions | diamond | planner-lane | 6 |
|
| p1-clarify | Ask Clarifying Questions | diamond | planner-lane | 6 |
|
||||||
| p1-user-answers | Provide Answers | rectangle | user-lane | 7 |
|
| p1-user-answers | Provide Answers | rectangle | user-lane | 7 |
|
||||||
@@ -44,8 +44,8 @@
|
|||||||
|------|----|-------|-------|
|
|------|----|-------|-------|
|
||||||
| p1-start | p1-activate | invokes | solid |
|
| p1-start | p1-activate | invokes | solid |
|
||||||
| p1-activate | p1-search-lessons | | solid |
|
| p1-activate | p1-search-lessons | | solid |
|
||||||
| p1-search-lessons | p1-wikijs-query | GraphQL search | solid |
|
| p1-search-lessons | p1-gitea-wiki-query | REST API (search_lessons) | solid |
|
||||||
| p1-wikijs-query | p1-return-lessons | lessons data | dashed |
|
| p1-gitea-wiki-query | p1-return-lessons | lessons data | dashed |
|
||||||
| p1-return-lessons | p1-clarify | | solid |
|
| p1-return-lessons | p1-clarify | | solid |
|
||||||
| p1-clarify | p1-user-answers | questions | solid |
|
| p1-clarify | p1-user-answers | questions | solid |
|
||||||
| p1-user-answers | p1-clarify | answers | dashed |
|
| p1-user-answers | p1-clarify | answers | dashed |
|
||||||
@@ -65,7 +65,7 @@
|
|||||||
| p2-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 12 |
|
| p2-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 12 |
|
||||||
| p2-fetch-issues | Fetch Sprint Issues | rectangle | orchestrator-lane | 13 |
|
| p2-fetch-issues | Fetch Sprint Issues | rectangle | orchestrator-lane | 13 |
|
||||||
| p2-gitea-list | List Open Issues | rectangle | gitea-lane | 14 |
|
| p2-gitea-list | List Open Issues | rectangle | gitea-lane | 14 |
|
||||||
| p2-sequence | Sequence Work | rectangle | orchestrator-lane | 15 |
|
| p2-sequence | Sequence Work (Dependencies) | rectangle | orchestrator-lane | 15 |
|
||||||
| p2-dispatch | Dispatch Task | rectangle | orchestrator-lane | 16 |
|
| p2-dispatch | Dispatch Task | rectangle | orchestrator-lane | 16 |
|
||||||
| p2-exec-activate | Executor Activates | rectangle | executor-lane | 17 |
|
| p2-exec-activate | Executor Activates | rectangle | executor-lane | 17 |
|
||||||
| p2-implement | Implement Task | rectangle | executor-lane | 18 |
|
| p2-implement | Implement Task | rectangle | executor-lane | 18 |
|
||||||
@@ -83,7 +83,7 @@
|
|||||||
| p2-orch-activate | p2-fetch-issues | | solid |
|
| p2-orch-activate | p2-fetch-issues | | solid |
|
||||||
| p2-fetch-issues | p2-gitea-list | REST API | solid |
|
| p2-fetch-issues | p2-gitea-list | REST API | solid |
|
||||||
| p2-gitea-list | p2-sequence | issues data | dashed |
|
| p2-gitea-list | p2-sequence | issues data | dashed |
|
||||||
| p2-sequence | p2-dispatch | | solid |
|
| p2-sequence | p2-dispatch | parallel batching | solid |
|
||||||
| p2-dispatch | p2-exec-activate | execution prompt | solid |
|
| p2-dispatch | p2-exec-activate | execution prompt | solid |
|
||||||
| p2-exec-activate | p2-implement | | solid |
|
| p2-exec-activate | p2-implement | | solid |
|
||||||
| p2-implement | p2-update-status | | solid |
|
| p2-implement | p2-update-status | | solid |
|
||||||
@@ -95,23 +95,50 @@
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## PHASE 2.5: CODE REVIEW (Pre-Close)
|
||||||
|
|
||||||
|
### Nodes
|
||||||
|
|
||||||
|
| ID | Label | Type | Lane | Sequence |
|
||||||
|
|----|-------|------|------|----------|
|
||||||
|
| p25-start | /review | rounded-rect | user-lane | 24 |
|
||||||
|
| p25-reviewer-activate | Code Reviewer Activates | rectangle | reviewer-lane | 25 |
|
||||||
|
| p25-scan-changes | Scan Recent Changes | rectangle | reviewer-lane | 26 |
|
||||||
|
| p25-check-quality | Check Code Quality | rectangle | reviewer-lane | 27 |
|
||||||
|
| p25-security-scan | Security Scan | rectangle | reviewer-lane | 28 |
|
||||||
|
| p25-report | Generate Review Report | rectangle | reviewer-lane | 29 |
|
||||||
|
| p25-complete | Review Complete | rounded-rect | reviewer-lane | 30 |
|
||||||
|
|
||||||
|
### Edges
|
||||||
|
|
||||||
|
| From | To | Label | Style |
|
||||||
|
|------|----|-------|-------|
|
||||||
|
| p25-start | p25-reviewer-activate | invokes | solid |
|
||||||
|
| p25-reviewer-activate | p25-scan-changes | | solid |
|
||||||
|
| p25-scan-changes | p25-check-quality | | solid |
|
||||||
|
| p25-check-quality | p25-security-scan | | solid |
|
||||||
|
| p25-security-scan | p25-report | | solid |
|
||||||
|
| p25-report | p25-complete | | solid |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## PHASE 3: SPRINT CLOSE
|
## PHASE 3: SPRINT CLOSE
|
||||||
|
|
||||||
### Nodes
|
### Nodes
|
||||||
|
|
||||||
| ID | Label | Type | Lane | Sequence |
|
| ID | Label | Type | Lane | Sequence |
|
||||||
|----|-------|------|------|----------|
|
|----|-------|------|------|----------|
|
||||||
| p3-start | /sprint-close | rounded-rect | user-lane | 24 |
|
| p3-start | /sprint-close | rounded-rect | user-lane | 31 |
|
||||||
| p3-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 25 |
|
| p3-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 32 |
|
||||||
| p3-review | Review Sprint | rectangle | orchestrator-lane | 26 |
|
| p3-review | Review Sprint | rectangle | orchestrator-lane | 33 |
|
||||||
| p3-gitea-status | Get Final Status | rectangle | gitea-lane | 27 |
|
| p3-gitea-status | Get Final Status | rectangle | gitea-lane | 34 |
|
||||||
| p3-capture | Capture Lessons Learned | rectangle | orchestrator-lane | 28 |
|
| p3-capture | Capture Lessons Learned | rectangle | orchestrator-lane | 35 |
|
||||||
| p3-user-input | Confirm Lessons | diamond | user-lane | 29 |
|
| p3-user-input | Confirm Lessons | diamond | user-lane | 36 |
|
||||||
| p3-create-wiki | Create Wiki Pages | rectangle | orchestrator-lane | 30 |
|
| p3-create-wiki | Create Wiki Pages | rectangle | orchestrator-lane | 37 |
|
||||||
| p3-wikijs-create | Store Lessons | rectangle | wikijs-lane | 31 |
|
| p3-gitea-wiki-create | Store Lessons (Wiki) | rectangle | gitea-lane | 38 |
|
||||||
| p3-close-issues | Close Issues | rectangle | orchestrator-lane | 32 |
|
| p3-close-issues | Close Issues | rectangle | orchestrator-lane | 39 |
|
||||||
| p3-gitea-close | Mark Closed | rectangle | gitea-lane | 33 |
|
| p3-gitea-close | Mark Closed | rectangle | gitea-lane | 40 |
|
||||||
| p3-complete | Sprint Closed | rounded-rect | orchestrator-lane | 34 |
|
| p3-complete | Sprint Closed | rounded-rect | orchestrator-lane | 41 |
|
||||||
|
|
||||||
### Edges
|
### Edges
|
||||||
|
|
||||||
@@ -123,8 +150,8 @@
|
|||||||
| p3-gitea-status | p3-capture | status data | dashed |
|
| p3-gitea-status | p3-capture | status data | dashed |
|
||||||
| p3-capture | p3-user-input | proposed lessons | solid |
|
| p3-capture | p3-user-input | proposed lessons | solid |
|
||||||
| p3-user-input | p3-create-wiki | confirmed | solid |
|
| p3-user-input | p3-create-wiki | confirmed | solid |
|
||||||
| p3-create-wiki | p3-wikijs-create | GraphQL mutation | solid |
|
| p3-create-wiki | p3-gitea-wiki-create | REST API (create_lesson) | solid |
|
||||||
| p3-wikijs-create | p3-close-issues | confirm | dashed |
|
| p3-gitea-wiki-create | p3-close-issues | confirm | dashed |
|
||||||
| p3-close-issues | p3-gitea-close | REST API | solid |
|
| p3-close-issues | p3-gitea-close | REST API | solid |
|
||||||
| p3-gitea-close | p3-complete | confirm | dashed |
|
| p3-gitea-close | p3-complete | confirm | dashed |
|
||||||
|
|
||||||
@@ -133,59 +160,71 @@
|
|||||||
## LAYOUT NOTES
|
## LAYOUT NOTES
|
||||||
|
|
||||||
```
|
```
|
||||||
+--------+------------+---------------+------------+--------+----------+
|
+--------+------------+---------------+------------+----------+------------------+
|
||||||
| User | Planner | Orchestrator | Executor | Gitea | Wiki.js |
|
| User | Planner | Orchestrator | Executor | Reviewer | Gitea |
|
||||||
+--------+------------+---------------+------------+--------+----------+
|
| | | | | | (Issues + Wiki) |
|
||||||
|
+--------+------------+---------------+------------+----------+------------------+
|
||||||
| | | | | | |
|
| | | | | | |
|
||||||
| PHASE 1: SPRINT PLANNING |
|
| PHASE 1: SPRINT PLANNING |
|
||||||
|---------------------------------------------------------------------+
|
|-------------------------------------------------------------------------------|
|
||||||
| O | | | | | |
|
| O | | | | | |
|
||||||
| | | | | | | |
|
| | | | | | | |
|
||||||
| +---->| O | | | | |
|
| +---->| O | | | | |
|
||||||
| | | | | | | |
|
| | | | | | | |
|
||||||
| | +----------|---------------|------------|------->| O |
|
| | +----------|---------------|------------|--------->| O (Wiki Query) |
|
||||||
| | |<---------|---------------|------------|--------+ | |
|
| | |<---------|---------------|------------|----------+ | |
|
||||||
| | | | | | | |
|
| | | | | | | |
|
||||||
| | O<> | | | | |
|
| | O<> | | | | |
|
||||||
| O<--->+ | | | | | |
|
| O<--->+ | | | | | |
|
||||||
| | | | | | | |
|
| | | | | | | |
|
||||||
| | +----------|---------------|----------->| O | |
|
| | +----------|---------------|------------|--------->| O (Issues) |
|
||||||
| | O | | | | |
|
| | O | | | | |
|
||||||
| | | | | | |
|
| | | | | | |
|
||||||
|---------------------------------------------------------------------+
|
|-------------------------------------------------------------------------------|
|
||||||
| PHASE 2: SPRINT EXECUTION |
|
| PHASE 2: SPRINT EXECUTION |
|
||||||
|---------------------------------------------------------------------+
|
|-------------------------------------------------------------------------------|
|
||||||
| O | | | | | |
|
| O | | | | | |
|
||||||
| | | | | | | |
|
| | | | | | | |
|
||||||
| +-----|----------->| O | | | |
|
| +-----|----------->| O | | | |
|
||||||
| | | | | | | |
|
| | | | | | | |
|
||||||
| | | +-------------|----------->| O | |
|
| | | +-------------|------------|--------->| O (Issues) |
|
||||||
| | | |<------------|------------+ | | |
|
| | | |<------------|------------|----------+ | |
|
||||||
| | | | | | | |
|
| | | | | | | |
|
||||||
| | | +------------>| O | | |
|
| | | +------------>| O | | |
|
||||||
| | | | | | | |
|
| | | | | | | |
|
||||||
| | | | +--------->| O | |
|
| | | | +----------|--------->| O (Issues) |
|
||||||
| | | | |<---------+ | | |
|
| | | | |<---------|----------+ | |
|
||||||
| | | O<------------+ | | | |
|
| | | O<------------+ | | | |
|
||||||
| | | | | | | |
|
| | | | | | | |
|
||||||
| | | O (loop) | | | |
|
| | | O (loop) | | | |
|
||||||
| | | | | | |
|
| | | | | | |
|
||||||
|---------------------------------------------------------------------+
|
|-------------------------------------------------------------------------------|
|
||||||
|
| PHASE 2.5: CODE REVIEW |
|
||||||
|
|-------------------------------------------------------------------------------|
|
||||||
|
| O | | | | | |
|
||||||
|
| | | | | | | |
|
||||||
|
| +-----|------------|---------------|----------->| O | |
|
||||||
|
| | | | | | | |
|
||||||
|
| | | | | O->O->O | |
|
||||||
|
| | | | | | | |
|
||||||
|
| | | | | O | |
|
||||||
|
| | | | | | |
|
||||||
|
|-------------------------------------------------------------------------------|
|
||||||
| PHASE 3: SPRINT CLOSE |
|
| PHASE 3: SPRINT CLOSE |
|
||||||
|---------------------------------------------------------------------+
|
|-------------------------------------------------------------------------------|
|
||||||
| O | | | | | |
|
| O | | | | | |
|
||||||
| | | | | | | |
|
| | | | | | | |
|
||||||
| +-----|----------->| O | | | |
|
| +-----|----------->| O | | | |
|
||||||
| | | +-------------|----------->| O | |
|
| | | +-------------|------------|--------->| O (Issues) |
|
||||||
| | | |<------------|------------+ | | |
|
| | | |<------------|------------|----------+ | |
|
||||||
| | | | | | | |
|
| | | | | | | |
|
||||||
| O<----|-----------<+ | | | | |
|
| O<----|-----------<+ | | | | |
|
||||||
| +-----|----------->| | | | | |
|
| +-----|----------->| | | | | |
|
||||||
| | | +-------------|------------|------->| O |
|
| | | +-------------|------------|--------->| O (Wiki Create) |
|
||||||
| | | |<------------|------------|--------+ | |
|
| | | |<------------|------------|----------+ | |
|
||||||
| | | +-------------|----------->| O | |
|
| | | +-------------|------------|--------->| O (Issues Close) |
|
||||||
| | | O | | | |
|
| | | O | | | |
|
||||||
+--------+------------+---------------+------------+--------+----------+
|
+--------+------------+---------------+------------+----------+------------------+
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
@@ -198,7 +237,8 @@
|
|||||||
| Blue | #4A90D9 | Planner Agent |
|
| Blue | #4A90D9 | Planner Agent |
|
||||||
| Green | #7CB342 | Orchestrator Agent |
|
| Green | #7CB342 | Orchestrator Agent |
|
||||||
| Orange | #FF9800 | Executor Agent |
|
| Orange | #FF9800 | Executor Agent |
|
||||||
| Gray | #9E9E9E | External Services |
|
| Purple | #9C27B0 | Code Reviewer Agent |
|
||||||
|
| Gray | #9E9E9E | External Services (Gitea) |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -219,3 +259,13 @@
|
|||||||
|-------|---------|
|
|-------|---------|
|
||||||
| Solid | Action/Request |
|
| Solid | Action/Request |
|
||||||
| Dashed | Response/Data return |
|
| Dashed | Response/Data return |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ARCHITECTURE NOTES
|
||||||
|
|
||||||
|
- **Gitea provides BOTH issue tracking AND wiki** (no separate wiki service)
|
||||||
|
- All wiki operations use Gitea REST API via MCP tools
|
||||||
|
- Lessons learned stored in Gitea Wiki under `lessons-learned/sprints/`
|
||||||
|
- MCP tools: `search_lessons`, `create_lesson`, `list_wiki_pages`, `get_wiki_page`
|
||||||
|
- Four-agent model: Planner, Orchestrator, Executor, Code Reviewer
|
||||||
|
|||||||
@@ -13,22 +13,26 @@
|
|||||||
| ID | Label | Type | Color | Position |
|
| ID | Label | Type | Color | Position |
|
||||||
|----|-------|------|-------|----------|
|
|----|-------|------|-------|----------|
|
||||||
| projman | projman | rectangle | #4A90D9 | top-center |
|
| projman | projman | rectangle | #4A90D9 | top-center |
|
||||||
| projman-pmo | projman-pmo | rectangle | #4A90D9 | top-right |
|
| projman-pmo | projman-pmo (planned) | rectangle | #4A90D9 | top-right |
|
||||||
| project-hygiene | project-hygiene | rectangle | #4A90D9 | top-left |
|
| project-hygiene | project-hygiene | rectangle | #4A90D9 | top-left |
|
||||||
|
| claude-config | claude-config-maintainer | rectangle | #4A90D9 | bottom-left |
|
||||||
|
| cmdb-assistant | cmdb-assistant | rectangle | #4A90D9 | bottom-right |
|
||||||
|
|
||||||
### MCP Servers (Green - #7CB342)
|
### MCP Servers (Green - #7CB342)
|
||||||
|
|
||||||
| ID | Label | Type | Color | Position |
|
MCP servers are **bundled inside each plugin** that needs them.
|
||||||
|----|-------|------|-------|----------|
|
|
||||||
| gitea-mcp | Gitea MCP Server | rectangle | #7CB342 | middle-left |
|
| ID | Label | Type | Color | Position | Bundled In |
|
||||||
| wikijs-mcp | Wiki.js MCP Server | rectangle | #7CB342 | middle-right |
|
|----|-------|------|-------|----------|------------|
|
||||||
|
| gitea-mcp | Gitea MCP Server | rectangle | #7CB342 | middle-left | projman |
|
||||||
|
| netbox-mcp | NetBox MCP Server | rectangle | #7CB342 | middle-right | cmdb-assistant |
|
||||||
|
|
||||||
### External Systems (Gray - #9E9E9E)
|
### External Systems (Gray - #9E9E9E)
|
||||||
|
|
||||||
| ID | Label | Type | Color | Position |
|
| ID | Label | Type | Color | Position |
|
||||||
|----|-------|------|-------|----------|
|
|----|-------|------|-------|----------|
|
||||||
| gitea-instance | Gitea\ngitea.hotserv.cloud | cylinder | #9E9E9E | bottom-left |
|
| gitea-instance | Gitea\n(Issues + Wiki) | cylinder | #9E9E9E | bottom-left |
|
||||||
| wikijs-instance | Wiki.js\nwikijs.hotserv.cloud | cylinder | #9E9E9E | bottom-right |
|
| netbox-instance | NetBox | cylinder | #9E9E9E | bottom-right |
|
||||||
|
|
||||||
### Configuration (Orange - #FF9800)
|
### Configuration (Orange - #FF9800)
|
||||||
|
|
||||||
@@ -45,10 +49,8 @@
|
|||||||
|
|
||||||
| From | To | Label | Style | Arrow |
|
| From | To | Label | Style | Arrow |
|
||||||
|------|----|-------|-------|-------|
|
|------|----|-------|-------|-------|
|
||||||
| projman | gitea-mcp | uses | solid | forward |
|
| projman | gitea-mcp | bundled | solid | bidirectional |
|
||||||
| projman | wikijs-mcp | uses | solid | forward |
|
| cmdb-assistant | netbox-mcp | bundled | solid | bidirectional |
|
||||||
| projman-pmo | gitea-mcp | uses (company-wide) | solid | forward |
|
|
||||||
| projman-pmo | wikijs-mcp | uses (company-wide) | solid | forward |
|
|
||||||
|
|
||||||
### Plugin Dependencies
|
### Plugin Dependencies
|
||||||
|
|
||||||
@@ -61,16 +63,16 @@
|
|||||||
| From | To | Label | Style | Arrow |
|
| From | To | Label | Style | Arrow |
|
||||||
|------|----|-------|-------|-------|
|
|------|----|-------|-------|-------|
|
||||||
| gitea-mcp | gitea-instance | REST API | solid | forward |
|
| gitea-mcp | gitea-instance | REST API | solid | forward |
|
||||||
| wikijs-mcp | wikijs-instance | GraphQL | solid | forward |
|
| netbox-mcp | netbox-instance | REST API | solid | forward |
|
||||||
|
|
||||||
### Configuration Connections
|
### Configuration Connections
|
||||||
|
|
||||||
| From | To | Label | Style | Arrow |
|
| From | To | Label | Style | Arrow |
|
||||||
|------|----|-------|-------|-------|
|
|------|----|-------|-------|-------|
|
||||||
| system-config | gitea-mcp | credentials | dashed | forward |
|
| system-config | gitea-mcp | credentials | dashed | forward |
|
||||||
| system-config | wikijs-mcp | credentials | dashed | forward |
|
| system-config | netbox-mcp | credentials | dashed | forward |
|
||||||
| project-config | gitea-mcp | repo context | dashed | forward |
|
| project-config | gitea-mcp | repo context | dashed | forward |
|
||||||
| project-config | wikijs-mcp | project path | dashed | forward |
|
| project-config | netbox-mcp | site context | dashed | forward |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -78,9 +80,8 @@
|
|||||||
|
|
||||||
| ID | Label | Contains | Style |
|
| ID | Label | Contains | Style |
|
||||||
|----|-------|----------|-------|
|
|----|-------|----------|-------|
|
||||||
| plugins-group | Plugins | projman, projman-pmo, project-hygiene | light blue border |
|
| plugins-group | Plugins | projman, projman-pmo, project-hygiene, claude-config, cmdb-assistant | light blue border |
|
||||||
| mcp-group | Shared MCP Servers | gitea-mcp, wikijs-mcp | light green border |
|
| external-group | External Services | gitea-instance, netbox-instance | light gray border |
|
||||||
| external-group | External Services | gitea-instance, wikijs-instance | light gray border |
|
|
||||||
| config-group | Configuration | system-config, project-config | light orange border |
|
| config-group | Configuration | system-config, project-config | light orange border |
|
||||||
|
|
||||||
---
|
---
|
||||||
@@ -92,25 +93,21 @@
|
|||||||
| PLUGINS GROUP |
|
| PLUGINS GROUP |
|
||||||
| +----------------+ +----------------+ +-------------------+ |
|
| +----------------+ +----------------+ +-------------------+ |
|
||||||
| | project- | | projman | | projman-pmo | |
|
| | project- | | projman | | projman-pmo | |
|
||||||
| | hygiene | | | | | |
|
| | hygiene | | [gitea-mcp] | | (planned) | |
|
||||||
| +----------------+ +-------+--------+ +--------+----------+ |
|
| +----------------+ +-------+--------+ +-------------------+ |
|
||||||
| | | |
|
| | |
|
||||||
|
| +----------------+ +-------------------+ |
|
||||||
|
| | claude-config | | cmdb-assistant | |
|
||||||
|
| | -maintainer | | [netbox-mcp] | |
|
||||||
|
| +----------------+ +--------+----------+ |
|
||||||
+------------------------------------------------------------------+
|
+------------------------------------------------------------------+
|
||||||
| |
|
|
|
||||||
v v
|
v
|
||||||
+------------------------------------------------------------------+
|
|
||||||
| MCP SERVERS GROUP |
|
|
||||||
| +-------------------+ +-------------------+ |
|
|
||||||
| | Gitea MCP Server | | Wiki.js MCP Server| |
|
|
||||||
| +--------+----------+ +---------+---------+ |
|
|
||||||
+------------------------------------------------------------------+
|
|
||||||
| |
|
|
||||||
v v
|
|
||||||
+------------------------------------------------------------------+
|
+------------------------------------------------------------------+
|
||||||
| EXTERNAL SERVICES GROUP |
|
| EXTERNAL SERVICES GROUP |
|
||||||
| +-------------------+ +-------------------+ |
|
| +-------------------+ +-------------------+ |
|
||||||
| | Gitea | | Wiki.js | |
|
| | Gitea | | NetBox | |
|
||||||
| | gitea.hotserv.cloud | wikijs.hotserv.cloud |
|
| | (Issues + Wiki) | | | |
|
||||||
| +-------------------+ +-------------------+ |
|
| +-------------------+ +-------------------+ |
|
||||||
+------------------------------------------------------------------+
|
+------------------------------------------------------------------+
|
||||||
|
|
||||||
@@ -128,6 +125,15 @@ CONFIG GROUP (left side): CONFIG GROUP (right side):
|
|||||||
| Color | Hex | Meaning |
|
| Color | Hex | Meaning |
|
||||||
|-------|-----|---------|
|
|-------|-----|---------|
|
||||||
| Blue | #4A90D9 | Plugins |
|
| Blue | #4A90D9 | Plugins |
|
||||||
| Green | #7CB342 | MCP Servers |
|
| Green | #7CB342 | MCP Servers (bundled in plugins) |
|
||||||
| Gray | #9E9E9E | External Systems |
|
| Gray | #9E9E9E | External Systems |
|
||||||
| Orange | #FF9800 | Configuration |
|
| Orange | #FF9800 | Configuration |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ARCHITECTURE NOTES
|
||||||
|
|
||||||
|
- MCP servers are **bundled inside plugins** (not shared at root)
|
||||||
|
- Gitea provides both issue tracking AND wiki (lessons learned)
|
||||||
|
- No separate Wiki.js - all wiki functionality uses Gitea Wiki
|
||||||
|
- Each plugin is self-contained for Claude Code caching
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -1,692 +0,0 @@
|
|||||||
# Project Management Plugins - Project Summary
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
This project builds two Claude Code plugins that transform a proven 15-sprint workflow into reusable, distributable tools for managing software development with Gitea, Wiki.js, and agile methodologies.
|
|
||||||
|
|
||||||
**Status:** Planning phase complete, ready for implementation
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## The Two Plugins
|
|
||||||
|
|
||||||
### 1. projman (Single-Repository)
|
|
||||||
|
|
||||||
**Purpose:** Project management for individual repositories
|
|
||||||
**Users:** Developers, Team Leads
|
|
||||||
**Build Order:** Build FIRST
|
|
||||||
|
|
||||||
**Key Features:**
|
|
||||||
- Sprint planning with AI agents
|
|
||||||
- Issue creation with 43-label taxonomy
|
|
||||||
- Lessons learned capture in Wiki.js
|
|
||||||
- Branch-aware security model
|
|
||||||
- Hybrid configuration system
|
|
||||||
|
|
||||||
**Reference:** [PLUGIN-PROJMAN.md](./PLUGIN-PROJMAN.md)
|
|
||||||
|
|
||||||
### 2. projman-pmo (Multi-Project)
|
|
||||||
|
|
||||||
**Purpose:** PMO coordination across organization
|
|
||||||
**Users:** PMO Coordinators, Engineering Managers, CTOs
|
|
||||||
**Build Order:** Build SECOND (after projman validated)
|
|
||||||
|
|
||||||
**Key Features:**
|
|
||||||
- Cross-project status aggregation
|
|
||||||
- Dependency tracking and visualization
|
|
||||||
- Resource conflict detection
|
|
||||||
- Release coordination
|
|
||||||
- Company-wide lessons learned search
|
|
||||||
|
|
||||||
**Reference:** [PLUGIN-PMO.md](./PLUGIN-PMO.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Core Architecture
|
|
||||||
|
|
||||||
### Shared MCP Servers
|
|
||||||
|
|
||||||
Both plugins share the same MCP server codebase at repository root (`mcp-servers/`):
|
|
||||||
|
|
||||||
**1. Gitea MCP Server**
|
|
||||||
- Issue management (CRUD operations)
|
|
||||||
- Label taxonomy system (43 labels)
|
|
||||||
- Mode detection (project vs company-wide)
|
|
||||||
|
|
||||||
**Reference:** [MCP-GITEA.md](./MCP-GITEA.md)
|
|
||||||
|
|
||||||
**2. Wiki.js MCP Server**
|
|
||||||
- Documentation management
|
|
||||||
- Lessons learned capture and search
|
|
||||||
- GraphQL API integration
|
|
||||||
- Company-wide knowledge base
|
|
||||||
|
|
||||||
**Reference:** [MCP-WIKIJS.md](./MCP-WIKIJS.md)
|
|
||||||
|
|
||||||
### Mode Detection
|
|
||||||
|
|
||||||
The MCP servers detect their operating mode based on environment variables:
|
|
||||||
|
|
||||||
**Project Mode (projman):**
|
|
||||||
- `GITEA_REPO` present → operates on single repository
|
|
||||||
- `WIKIJS_PROJECT` present → operates on single project path
|
|
||||||
|
|
||||||
**Company Mode (pmo):**
|
|
||||||
- No `GITEA_REPO` → operates on all repositories
|
|
||||||
- No `WIKIJS_PROJECT` → operates on entire company namespace
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Repository Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
bandit/support-claude-mktplace/
|
|
||||||
├── mcp-servers/ # ← SHARED BY BOTH PLUGINS
|
|
||||||
│ ├── gitea/ # Gitea MCP Server
|
|
||||||
│ │ ├── .venv/
|
|
||||||
│ │ ├── requirements.txt
|
|
||||||
│ │ ├── mcp_server/
|
|
||||||
│ │ └── tests/
|
|
||||||
│ └── wikijs/ # Wiki.js MCP Server
|
|
||||||
│ ├── .venv/
|
|
||||||
│ ├── requirements.txt
|
|
||||||
│ ├── mcp_server/
|
|
||||||
│ └── tests/
|
|
||||||
├── projman/ # ← PROJECT PLUGIN
|
|
||||||
│ ├── .claude-plugin/
|
|
||||||
│ │ └── plugin.json
|
|
||||||
│ ├── .mcp.json # Points to ../mcp-servers/
|
|
||||||
│ ├── commands/
|
|
||||||
│ │ ├── sprint-plan.md
|
|
||||||
│ │ ├── sprint-start.md
|
|
||||||
│ │ ├── sprint-status.md
|
|
||||||
│ │ ├── sprint-close.md
|
|
||||||
│ │ └── labels-sync.md
|
|
||||||
│ ├── agents/
|
|
||||||
│ │ ├── planner.md
|
|
||||||
│ │ ├── orchestrator.md
|
|
||||||
│ │ └── executor.md
|
|
||||||
│ ├── skills/
|
|
||||||
│ │ └── label-taxonomy/
|
|
||||||
│ ├── README.md
|
|
||||||
│ └── CONFIGURATION.md
|
|
||||||
└── projman-pmo/ # ← PMO PLUGIN
|
|
||||||
├── .claude-plugin/
|
|
||||||
│ └── plugin.json
|
|
||||||
├── .mcp.json # Points to ../mcp-servers/
|
|
||||||
├── commands/
|
|
||||||
│ ├── pmo-status.md
|
|
||||||
│ ├── pmo-priorities.md
|
|
||||||
│ ├── pmo-dependencies.md
|
|
||||||
│ └── pmo-schedule.md
|
|
||||||
├── agents/
|
|
||||||
│ └── pmo-coordinator.md
|
|
||||||
└── README.md
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Configuration Architecture
|
|
||||||
|
|
||||||
### Hybrid Configuration System
|
|
||||||
|
|
||||||
The plugins use a hybrid configuration approach that balances security and flexibility:
|
|
||||||
|
|
||||||
**System-Level (Once per machine):**
|
|
||||||
- `~/.config/claude/gitea.env` - Gitea credentials
|
|
||||||
- `~/.config/claude/wikijs.env` - Wiki.js credentials
|
|
||||||
|
|
||||||
**Project-Level (Per repository):**
|
|
||||||
- `project-root/.env` - Repository and project paths
|
|
||||||
|
|
||||||
**Benefits:**
|
|
||||||
- Single token per service (update once)
|
|
||||||
- Project isolation
|
|
||||||
- Security (tokens never committed)
|
|
||||||
- Easy multi-project setup
|
|
||||||
|
|
||||||
### Configuration Example
|
|
||||||
|
|
||||||
**System-Level:**
|
|
||||||
```bash
|
|
||||||
# ~/.config/claude/gitea.env
|
|
||||||
GITEA_API_URL=https://gitea.example.com/api/v1
|
|
||||||
GITEA_API_TOKEN=your_token
|
|
||||||
GITEA_OWNER=bandit
|
|
||||||
|
|
||||||
# ~/.config/claude/wikijs.env
|
|
||||||
WIKIJS_API_URL=https://wiki.your-company.com/graphql
|
|
||||||
WIKIJS_API_TOKEN=your_token
|
|
||||||
WIKIJS_BASE_PATH=/your-org
|
|
||||||
```
|
|
||||||
|
|
||||||
**Project-Level:**
|
|
||||||
```bash
|
|
||||||
# project-root/.env (for projman)
|
|
||||||
GITEA_REPO=cuisineflow
|
|
||||||
WIKIJS_PROJECT=projects/cuisineflow
|
|
||||||
|
|
||||||
# No .env needed for pmo (company-wide mode)
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Key Architectural Decisions
|
|
||||||
|
|
||||||
### 1. Two MCP Servers (Shared)
|
|
||||||
|
|
||||||
**Decision:** Separate Gitea and Wiki.js servers at repository root
|
|
||||||
**Why:**
|
|
||||||
- Clear separation of concerns
|
|
||||||
- Independent configuration
|
|
||||||
- Better maintainability
|
|
||||||
- Professional architecture
|
|
||||||
|
|
||||||
### 2. Python Implementation
|
|
||||||
|
|
||||||
**Decision:** Python 3.10+ for MCP servers
|
|
||||||
**Why:**
|
|
||||||
- Modern async/await improvements
|
|
||||||
- Better type hints support
|
|
||||||
- Good balance of compatibility vs features
|
|
||||||
- Widely available (released Oct 2021)
|
|
||||||
- Most production servers have 3.10+ by now
|
|
||||||
|
|
||||||
### 3. Wiki.js for Lessons Learned
|
|
||||||
|
|
||||||
**Decision:** Use Wiki.js instead of Git-based Wiki
|
|
||||||
**Why:**
|
|
||||||
- Rich editor and search
|
|
||||||
- Built-in tag system
|
|
||||||
- Version history
|
|
||||||
- Web-based collaboration
|
|
||||||
- GraphQL API
|
|
||||||
- Company-wide accessibility
|
|
||||||
|
|
||||||
### 4. Hybrid Configuration
|
|
||||||
|
|
||||||
**Decision:** System-level + project-level configuration
|
|
||||||
**Why:**
|
|
||||||
- Single token per service (security)
|
|
||||||
- Per-project customization (flexibility)
|
|
||||||
- Easy multi-project setup
|
|
||||||
- Never commit tokens to git
|
|
||||||
|
|
||||||
### 5. Mode Detection in MCP Servers
|
|
||||||
|
|
||||||
**Decision:** Detect mode based on environment variables
|
|
||||||
**Why:**
|
|
||||||
- Same codebase for both plugins
|
|
||||||
- No code duplication
|
|
||||||
- Fix bugs once, both benefit
|
|
||||||
- Clear separation of concerns
|
|
||||||
|
|
||||||
### 6. Build Order: projman First
|
|
||||||
|
|
||||||
**Decision:** Build projman completely before starting pmo
|
|
||||||
**Why:**
|
|
||||||
- Validate core functionality
|
|
||||||
- Establish patterns
|
|
||||||
- Reduce risk
|
|
||||||
- PMO builds on projman foundation
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## The Three-Agent Model
|
|
||||||
|
|
||||||
### Projman Agents
|
|
||||||
|
|
||||||
**Planner Agent:**
|
|
||||||
- Sprint planning and architecture analysis
|
|
||||||
- Asks clarifying questions
|
|
||||||
- Suggests appropriate labels
|
|
||||||
- Creates Gitea issues
|
|
||||||
- Searches relevant lessons learned
|
|
||||||
|
|
||||||
**Orchestrator Agent:**
|
|
||||||
- Sprint progress monitoring
|
|
||||||
- Task coordination
|
|
||||||
- Blocker identification
|
|
||||||
- Git operations
|
|
||||||
- Generates lean execution prompts
|
|
||||||
|
|
||||||
**Executor Agent:**
|
|
||||||
- Implementation guidance
|
|
||||||
- Code review suggestions
|
|
||||||
- Testing strategy
|
|
||||||
- Quality standards enforcement
|
|
||||||
- Documentation
|
|
||||||
|
|
||||||
### PMO Agent
|
|
||||||
|
|
||||||
**PMO Coordinator:**
|
|
||||||
- Strategic view across all projects
|
|
||||||
- Cross-project dependency tracking
|
|
||||||
- Resource conflict detection
|
|
||||||
- Release coordination
|
|
||||||
- Delegates to projman agents for details
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Wiki.js Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
Wiki.js: https://wiki.your-company.com
|
|
||||||
└── /your-org/
|
|
||||||
├── projects/ # Project-specific
|
|
||||||
│ ├── project-a/
|
|
||||||
│ │ ├── lessons-learned/
|
|
||||||
│ │ │ ├── sprints/
|
|
||||||
│ │ │ ├── patterns/
|
|
||||||
│ │ │ └── INDEX.md
|
|
||||||
│ │ └── documentation/
|
|
||||||
│ ├── project-b/
|
|
||||||
│ ├── project-c/
|
|
||||||
│ └── company-site/
|
|
||||||
├── company/ # Company-wide
|
|
||||||
│ ├── processes/
|
|
||||||
│ ├── standards/
|
|
||||||
│ └── tools/
|
|
||||||
└── shared/ # Cross-project
|
|
||||||
├── architecture-patterns/
|
|
||||||
├── best-practices/
|
|
||||||
└── tech-stack/
|
|
||||||
```
|
|
||||||
|
|
||||||
**Reference:** [MCP-WIKIJS.md](./MCP-WIKIJS.md#wiki-js-structure)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Label Taxonomy System
|
|
||||||
|
|
||||||
### Dynamic Label System (44 labels currently)
|
|
||||||
|
|
||||||
Labels are **fetched dynamically from Gitea** at runtime via the `/labels-sync` command:
|
|
||||||
|
|
||||||
**Organization Labels (28):**
|
|
||||||
- Agent/2
|
|
||||||
- Complexity/3
|
|
||||||
- Efforts/5
|
|
||||||
- Priority/4
|
|
||||||
- Risk/3
|
|
||||||
- Source/4
|
|
||||||
- Type/6 (Bug, Feature, Refactor, Documentation, Test, Chore)
|
|
||||||
|
|
||||||
**Repository Labels (16):**
|
|
||||||
- Component/9 (Backend, Frontend, API, Database, Auth, Deploy, Testing, Docs, Infra)
|
|
||||||
- Tech/7 (Python, JavaScript, Docker, PostgreSQL, Redis, Vue, FastAPI)
|
|
||||||
|
|
||||||
### Type/Refactor Label
|
|
||||||
|
|
||||||
**Organization-level label** for architectural work:
|
|
||||||
- Service extraction
|
|
||||||
- Architecture modifications
|
|
||||||
- Code restructuring
|
|
||||||
- Technical debt reduction
|
|
||||||
|
|
||||||
**Note:** Label count may change. Always sync from Gitea using `/labels-sync` command. When new labels are detected, the command will explain changes and update suggestion logic.
|
|
||||||
|
|
||||||
**Reference:** [PLUGIN-PROJMAN.md](./PLUGIN-PROJMAN.md#label-taxonomy-system)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Build Order & Phases
|
|
||||||
|
|
||||||
### Build projman First (Phases 1-8)
|
|
||||||
|
|
||||||
**Phase 1:** Core Infrastructure (MCP servers)
|
|
||||||
**Phase 2:** Sprint Planning Commands
|
|
||||||
**Phase 3:** Agent System
|
|
||||||
**Phase 4:** Lessons Learned System
|
|
||||||
**Phase 5:** Testing & Validation
|
|
||||||
**Phase 6:** Documentation & Refinement
|
|
||||||
**Phase 7:** Marketplace Preparation
|
|
||||||
**Phase 8:** Production Hardening
|
|
||||||
|
|
||||||
**Reference:** [PLUGIN-PROJMAN.md](./PLUGIN-PROJMAN.md#implementation-phases)
|
|
||||||
|
|
||||||
### Build pmo Second (Phases 9-12)
|
|
||||||
|
|
||||||
**Phase 9:** PMO Plugin Foundation
|
|
||||||
**Phase 10:** PMO Commands & Workflows
|
|
||||||
**Phase 11:** PMO Testing & Integration
|
|
||||||
**Phase 12:** Production Deployment
|
|
||||||
|
|
||||||
**Reference:** [PLUGIN-PMO.md](./PLUGIN-PMO.md#implementation-phases)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Quick Start Guide
|
|
||||||
|
|
||||||
### 1. System Configuration
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Create config directory
|
|
||||||
mkdir -p ~/.config/claude
|
|
||||||
|
|
||||||
# Gitea config
|
|
||||||
cat > ~/.config/claude/gitea.env << EOF
|
|
||||||
GITEA_API_URL=https://gitea.example.com/api/v1
|
|
||||||
GITEA_API_TOKEN=your_gitea_token
|
|
||||||
GITEA_OWNER=bandit
|
|
||||||
EOF
|
|
||||||
|
|
||||||
# Wiki.js config
|
|
||||||
cat > ~/.config/claude/wikijs.env << EOF
|
|
||||||
WIKIJS_API_URL=https://wiki.your-company.com/graphql
|
|
||||||
WIKIJS_API_TOKEN=your_wikijs_token
|
|
||||||
WIKIJS_BASE_PATH=/your-org
|
|
||||||
EOF
|
|
||||||
|
|
||||||
# Secure files
|
|
||||||
chmod 600 ~/.config/claude/*.env
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Project Configuration
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# In each project root (for projman)
|
|
||||||
cat > .env << EOF
|
|
||||||
GITEA_REPO=cuisineflow
|
|
||||||
WIKIJS_PROJECT=projects/cuisineflow
|
|
||||||
EOF
|
|
||||||
|
|
||||||
# Add to .gitignore
|
|
||||||
echo ".env" >> .gitignore
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. MCP Server Setup
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Gitea MCP Server
|
|
||||||
cd mcp-servers/gitea
|
|
||||||
python -m venv .venv
|
|
||||||
source .venv/bin/activate
|
|
||||||
pip install -r requirements.txt
|
|
||||||
|
|
||||||
# Wiki.js MCP Server
|
|
||||||
cd mcp-servers/wikijs
|
|
||||||
python -m venv .venv
|
|
||||||
source .venv/bin/activate
|
|
||||||
pip install -r requirements.txt
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. Validate Setup
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Test MCP servers
|
|
||||||
python -m mcp_server.server --test # In each MCP directory
|
|
||||||
|
|
||||||
# Test plugin loading
|
|
||||||
claude plugin test projman
|
|
||||||
claude plugin test projman-pmo
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Document Organization
|
|
||||||
|
|
||||||
This documentation is organized into 4 focused files plus this summary:
|
|
||||||
|
|
||||||
### 1. Gitea MCP Server Reference
|
|
||||||
|
|
||||||
**File:** [MCP-GITEA.md](./MCP-GITEA.md)
|
|
||||||
|
|
||||||
**Contains:**
|
|
||||||
- Configuration setup
|
|
||||||
- Python implementation
|
|
||||||
- API client code
|
|
||||||
- Issue and label tools
|
|
||||||
- Testing strategies
|
|
||||||
- Mode detection
|
|
||||||
- Performance optimization
|
|
||||||
|
|
||||||
**Use when:** Implementing or troubleshooting Gitea integration
|
|
||||||
|
|
||||||
### 2. Wiki.js MCP Server Reference
|
|
||||||
|
|
||||||
**File:** [MCP-WIKIJS.md](./MCP-WIKIJS.md)
|
|
||||||
|
|
||||||
**Contains:**
|
|
||||||
- Configuration setup
|
|
||||||
- GraphQL client implementation
|
|
||||||
- Wiki.js structure
|
|
||||||
- Lessons learned system
|
|
||||||
- Documentation tools
|
|
||||||
- Company-wide patterns
|
|
||||||
- PMO multi-project methods
|
|
||||||
|
|
||||||
**Use when:** Implementing or troubleshooting Wiki.js integration
|
|
||||||
|
|
||||||
### 3. Projman Plugin Reference
|
|
||||||
|
|
||||||
**File:** [PLUGIN-PROJMAN.md](./PLUGIN-PROJMAN.md)
|
|
||||||
|
|
||||||
**Contains:**
|
|
||||||
- Plugin structure
|
|
||||||
- Commands (sprint-plan, sprint-start, sprint-status, sprint-close, labels-sync)
|
|
||||||
- Three agents (planner, orchestrator, executor)
|
|
||||||
- Sprint workflow
|
|
||||||
- Label taxonomy
|
|
||||||
- Branch-aware security
|
|
||||||
- Implementation phases 1-8
|
|
||||||
|
|
||||||
**Use when:** Building or using the projman plugin
|
|
||||||
|
|
||||||
### 4. PMO Plugin Reference
|
|
||||||
|
|
||||||
**File:** [PLUGIN-PMO.md](./PLUGIN-PMO.md)
|
|
||||||
|
|
||||||
**Contains:**
|
|
||||||
- PMO plugin structure
|
|
||||||
- Multi-project commands
|
|
||||||
- PMO coordinator agent
|
|
||||||
- Cross-project coordination
|
|
||||||
- Dependency tracking
|
|
||||||
- Resource conflict detection
|
|
||||||
- Implementation phases 9-12
|
|
||||||
|
|
||||||
**Use when:** Building or using the projman-pmo plugin
|
|
||||||
|
|
||||||
### 5. This Summary
|
|
||||||
|
|
||||||
**File:** PROJECT-SUMMARY.md (this document)
|
|
||||||
|
|
||||||
**Contains:**
|
|
||||||
- Project overview
|
|
||||||
- Architecture decisions
|
|
||||||
- Configuration approach
|
|
||||||
- Quick start guide
|
|
||||||
- References to detailed docs
|
|
||||||
|
|
||||||
**Use when:** Getting started or need high-level overview
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Key Success Metrics
|
|
||||||
|
|
||||||
### Technical Metrics
|
|
||||||
|
|
||||||
- Sprint planning time reduced by 40%
|
|
||||||
- Manual steps eliminated: 10+ per sprint
|
|
||||||
- Lessons learned capture rate: 100% (vs 0% before)
|
|
||||||
- Label accuracy on issues: 90%+
|
|
||||||
- Configuration setup time: < 5 minutes
|
|
||||||
|
|
||||||
### User Metrics
|
|
||||||
|
|
||||||
- User satisfaction: Better than current manual workflow
|
|
||||||
- Learning curve: < 1 hour to basic proficiency
|
|
||||||
- Error rate: < 5% incorrect operations
|
|
||||||
- Adoption rate: 100% team adoption within 1 month
|
|
||||||
|
|
||||||
### PMO Metrics
|
|
||||||
|
|
||||||
- Cross-project visibility: 100% (vs fragmented before)
|
|
||||||
- Dependency detection: Automated (vs manual tracking)
|
|
||||||
- Resource conflict identification: Proactive (vs reactive)
|
|
||||||
- Release coordination: Streamlined (vs ad-hoc)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Critical Lessons from 15 Sprints
|
|
||||||
|
|
||||||
### Why Lessons Learned Is Critical
|
|
||||||
|
|
||||||
After 15 sprints without systematic lesson capture, repeated mistakes occurred:
|
|
||||||
- Claude Code infinite loops on similar issues: 2-3 times
|
|
||||||
- Same architectural mistakes: Multiple occurrences
|
|
||||||
- Forgotten optimizations: Re-discovered each time
|
|
||||||
|
|
||||||
**Solution:** Mandatory lessons learned capture at sprint close, searchable at sprint start
|
|
||||||
|
|
||||||
### Branch Detection Must Be 100% Reliable
|
|
||||||
|
|
||||||
Production accidents are unacceptable. Branch-aware security prevents:
|
|
||||||
- Accidental code changes on production branch
|
|
||||||
- Sprint planning on wrong branch
|
|
||||||
- Deployment mistakes
|
|
||||||
|
|
||||||
**Implementation:** Two layers - CLAUDE.md (file-level) + Plugin agents (tool-level)
|
|
||||||
|
|
||||||
### Configuration Complexity Is a Blocker
|
|
||||||
|
|
||||||
Previous attempts failed due to:
|
|
||||||
- Complex per-project setup
|
|
||||||
- Token management overhead
|
|
||||||
- Multiple configuration files
|
|
||||||
|
|
||||||
**Solution:** Hybrid approach - system-level tokens + simple project-level paths
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Next Steps
|
|
||||||
|
|
||||||
### Immediate Actions
|
|
||||||
|
|
||||||
1. **Set up system configuration** (Gitea + Wiki.js tokens)
|
|
||||||
2. **Create Wiki.js base structure** at `/your-org`
|
|
||||||
3. **Begin Phase 1.1a** - Gitea MCP Server implementation
|
|
||||||
4. **Begin Phase 1.1b** - Wiki.js MCP Server implementation
|
|
||||||
|
|
||||||
### Phase Execution
|
|
||||||
|
|
||||||
1. **Phases 1-4:** Build core projman functionality
|
|
||||||
2. **Phase 5:** Validate with real sprint (e.g., Intuit Engine extraction)
|
|
||||||
3. **Phases 6-8:** Polish, document, and harden projman
|
|
||||||
4. **Phases 9-12:** Build and validate pmo plugin
|
|
||||||
|
|
||||||
### Validation Points
|
|
||||||
|
|
||||||
- **After Phase 1:** MCP servers working and tested
|
|
||||||
- **After Phase 4:** Complete projman workflow end-to-end
|
|
||||||
- **After Phase 5:** Real sprint successfully managed
|
|
||||||
- **After Phase 8:** Production-ready projman
|
|
||||||
- **After Phase 11:** Multi-project coordination validated
|
|
||||||
- **After Phase 12:** Complete system operational
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Implementation Decisions (Pre-Development)
|
|
||||||
|
|
||||||
These decisions were finalized before development:
|
|
||||||
|
|
||||||
### 1. Python Version: 3.10+
|
|
||||||
- **Rationale:** Balance of modern features and wide availability
|
|
||||||
- **Benefits:** Modern async, good type hints, widely deployed
|
|
||||||
- **Minimum:** Python 3.10.0
|
|
||||||
|
|
||||||
### 2. Wiki.js Base Structure: Needs Creation
|
|
||||||
- **Status:** `/your-org` structure does NOT exist yet
|
|
||||||
- **Action:** Run `setup_wiki_structure.py` during Phase 1.1b
|
|
||||||
- **Script:** See MCP-WIKIJS.md for complete setup script
|
|
||||||
- **Post-setup:** Verify at https://wiki.your-company.com/your-org
|
|
||||||
|
|
||||||
### 3. Testing Strategy: Both Mocks and Real APIs
|
|
||||||
- **Unit tests:** Use mocks for fast feedback during development
|
|
||||||
- **Integration tests:** Use real Gitea/Wiki.js APIs for validation
|
|
||||||
- **CI/CD:** Run both test suites
|
|
||||||
- **Developers:** Can skip integration tests locally if needed
|
|
||||||
- **Markers:** Use pytest markers (`@pytest.mark.integration`)
|
|
||||||
|
|
||||||
### 4. Token Permissions: Confirmed
|
|
||||||
- **Gitea token:**
|
|
||||||
- `repo` (all) - Read/write repositories, issues, labels
|
|
||||||
- `read:org` - Organization information and labels
|
|
||||||
- `read:user` - User information
|
|
||||||
- **Wiki.js token:**
|
|
||||||
- Read/create/update pages
|
|
||||||
- Manage tags
|
|
||||||
- Search access
|
|
||||||
|
|
||||||
### 5. Label System: Dynamic (44 labels)
|
|
||||||
- **Current count:** 44 labels (28 org + 16 repo)
|
|
||||||
- **Approach:** Fetch dynamically via API, never hardcode
|
|
||||||
- **Sync:** `/labels-sync` command updates local reference and suggestion logic
|
|
||||||
- **New labels:** Command explains changes and asks for confirmation
|
|
||||||
|
|
||||||
### 6. Branch Detection: Defense in Depth
|
|
||||||
- **Layer 1:** MCP tools check branch and block operations
|
|
||||||
- **Layer 2:** Agent prompts check branch and warn users
|
|
||||||
- **Layer 3:** CLAUDE.md provides context (third layer)
|
|
||||||
- **Rationale:** Multiple layers prevent production accidents
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Important Reminders
|
|
||||||
|
|
||||||
1. **Build projman FIRST** - Don't start pmo until projman is validated
|
|
||||||
2. **MCP servers are SHARED** - Located at `mcp-servers/`, not inside plugins
|
|
||||||
3. **Lessons learned is critical** - Prevents repeated mistakes
|
|
||||||
4. **Test with real work** - Validate with actual sprints, not just unit tests
|
|
||||||
5. **Security first** - Branch detection must be 100% reliable
|
|
||||||
6. **Keep it simple** - Avoid over-engineering, focus on proven workflow
|
|
||||||
7. **Python 3.10+** - Minimum version requirement
|
|
||||||
8. **Wiki.js setup** - Must run setup script before projman works
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Getting Help
|
|
||||||
|
|
||||||
### Documentation Structure
|
|
||||||
|
|
||||||
**Need details on:**
|
|
||||||
- Gitea integration → [MCP-GITEA.md](./MCP-GITEA.md)
|
|
||||||
- Wiki.js integration → [MCP-WIKIJS.md](./MCP-WIKIJS.md)
|
|
||||||
- Projman usage → [PLUGIN-PROJMAN.md](./PLUGIN-PROJMAN.md)
|
|
||||||
- PMO usage → [PLUGIN-PMO.md](./PLUGIN-PMO.md)
|
|
||||||
- Overview → This document
|
|
||||||
|
|
||||||
### Quick Reference
|
|
||||||
|
|
||||||
| Question | Reference |
|
|
||||||
|----------|-----------|
|
|
||||||
| How do I set up configuration? | This document, "Quick Start Guide" |
|
|
||||||
| What's the repository structure? | This document, "Repository Structure" |
|
|
||||||
| How do Gitea tools work? | [MCP-GITEA.md](./MCP-GITEA.md) |
|
|
||||||
| How do Wiki.js tools work? | [MCP-WIKIJS.md](./MCP-WIKIJS.md) |
|
|
||||||
| How do I use sprint commands? | [PLUGIN-PROJMAN.md](./PLUGIN-PROJMAN.md#commands) |
|
|
||||||
| How do agents work? | [PLUGIN-PROJMAN.md](./PLUGIN-PROJMAN.md#three-agent-model) |
|
|
||||||
| How do I coordinate multiple projects? | [PLUGIN-PMO.md](./PLUGIN-PMO.md) |
|
|
||||||
| What's the build order? | This document, "Build Order & Phases" |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Project Timeline
|
|
||||||
|
|
||||||
**Planning:** Complete ✅
|
|
||||||
**Phase 1-8 (projman):** 6-8 weeks estimated
|
|
||||||
**Phase 9-12 (pmo):** 2-4 weeks estimated
|
|
||||||
**Total:** 8-12 weeks from start to production
|
|
||||||
|
|
||||||
**Note:** No fixed deadlines - work at sustainable pace and validate thoroughly
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## You're Ready!
|
|
||||||
|
|
||||||
You have everything you need to build the projman and projman-pmo plugins. All architectural decisions are finalized and documented.
|
|
||||||
|
|
||||||
**Start here:** [MCP-GITEA.md](./MCP-GITEA.md) - Set up Gitea MCP Server
|
|
||||||
|
|
||||||
Good luck with the build! 🚀
|
|
||||||
@@ -2,29 +2,21 @@
|
|||||||
"name": "claude-config-maintainer",
|
"name": "claude-config-maintainer",
|
||||||
"version": "1.0.0",
|
"version": "1.0.0",
|
||||||
"description": "Maintains and optimizes CLAUDE.md configuration files for Claude Code projects",
|
"description": "Maintains and optimizes CLAUDE.md configuration files for Claude Code projects",
|
||||||
"entryPoint": "agents/maintainer.md",
|
"author": {
|
||||||
"commands": [
|
"name": "Leo Miranda",
|
||||||
{
|
"email": "leobmiranda@gmail.com"
|
||||||
"name": "config-analyze",
|
|
||||||
"description": "Analyze CLAUDE.md for optimization opportunities",
|
|
||||||
"entryPoint": "commands/analyze.md"
|
|
||||||
},
|
},
|
||||||
{
|
"homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/claude-config-maintainer/README.md",
|
||||||
"name": "config-optimize",
|
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
|
||||||
"description": "Optimize CLAUDE.md structure and content",
|
"license": "MIT",
|
||||||
"entryPoint": "commands/optimize.md"
|
"keywords": [
|
||||||
},
|
"claude-code",
|
||||||
{
|
"configuration",
|
||||||
"name": "config-init",
|
"optimization",
|
||||||
"description": "Initialize a new CLAUDE.md file for a project",
|
"claude-md",
|
||||||
"entryPoint": "commands/init.md"
|
"developer-tools"
|
||||||
}
|
|
||||||
],
|
],
|
||||||
"agents": [
|
"entryPoint": "agents/maintainer.md",
|
||||||
{
|
"commands": ["./commands/"],
|
||||||
"name": "maintainer",
|
"agents": ["./agents/"]
|
||||||
"description": "CLAUDE.md optimization and maintenance agent",
|
|
||||||
"entryPoint": "agents/maintainer.md"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -96,4 +96,4 @@ Target score: **70+** for effective Claude Code usage.
|
|||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
This plugin is part of the bandit/support-claude-mktplace repository.
|
This plugin is part of the personal-projects/support-claude-mktplace repository.
|
||||||
|
|||||||
@@ -31,7 +31,11 @@ You are the **Maintainer Agent** - a specialist in creating and optimizing CLAUD
|
|||||||
|
|
||||||
### 1. Analyze CLAUDE.md Files
|
### 1. Analyze CLAUDE.md Files
|
||||||
|
|
||||||
When analyzing a CLAUDE.md file, evaluate:
|
When analyzing a CLAUDE.md file, perform two types of analysis:
|
||||||
|
|
||||||
|
#### A. Content Analysis
|
||||||
|
|
||||||
|
Evaluate:
|
||||||
|
|
||||||
**Structure:**
|
**Structure:**
|
||||||
- Is the file well-organized?
|
- Is the file well-organized?
|
||||||
@@ -57,6 +61,49 @@ When analyzing a CLAUDE.md file, evaluate:
|
|||||||
- Are there verbose explanations that could be shortened?
|
- Are there verbose explanations that could be shortened?
|
||||||
- Is the file too long for effective use?
|
- Is the file too long for effective use?
|
||||||
|
|
||||||
|
#### B. Plugin Integration Analysis
|
||||||
|
|
||||||
|
After content analysis, check for marketplace plugin integration:
|
||||||
|
|
||||||
|
**Step 1: Detect Active Plugins**
|
||||||
|
|
||||||
|
Read `.claude/settings.local.json` and identify enabled MCP servers:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"gitea": { ... }, // → projman plugin
|
||||||
|
"netbox": { ... } // → cmdb-assistant plugin
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Use this mapping to identify active plugins:
|
||||||
|
| MCP Server | Plugin |
|
||||||
|
|------------|--------|
|
||||||
|
| `gitea` | projman |
|
||||||
|
| `netbox` | cmdb-assistant |
|
||||||
|
|
||||||
|
Also check for hook-based plugins (project-hygiene uses `PostToolUse` hooks).
|
||||||
|
|
||||||
|
**Step 2: Check CLAUDE.md for Plugin References**
|
||||||
|
|
||||||
|
For each detected plugin, search CLAUDE.md for:
|
||||||
|
- Plugin name mention (e.g., "projman", "cmdb-assistant")
|
||||||
|
- Command references (e.g., `/sprint-plan`, `/cmdb-search`)
|
||||||
|
- MCP tool mentions (e.g., `list_issues`, `dcim_list_devices`)
|
||||||
|
|
||||||
|
**Step 3: Load Integration Snippets**
|
||||||
|
|
||||||
|
For plugins not referenced in CLAUDE.md, load their integration snippet from:
|
||||||
|
`plugins/{plugin-name}/claude-md-integration.md`
|
||||||
|
|
||||||
|
**Step 4: Report and Offer Integration**
|
||||||
|
|
||||||
|
Report plugin coverage percentage and offer to add missing integrations:
|
||||||
|
- Show which plugins are detected but not referenced
|
||||||
|
- Display the integration content that would be added
|
||||||
|
- Ask user for confirmation before modifying CLAUDE.md
|
||||||
|
|
||||||
### 2. Optimize CLAUDE.md Structure
|
### 2. Optimize CLAUDE.md Structure
|
||||||
|
|
||||||
**Recommended Structure:**
|
**Recommended Structure:**
|
||||||
@@ -145,7 +192,42 @@ Suggested Actions:
|
|||||||
Would you like me to implement these improvements?
|
Would you like me to implement these improvements?
|
||||||
```
|
```
|
||||||
|
|
||||||
### 5. Create New CLAUDE.md Files
|
### 5. Insert Plugin Integrations
|
||||||
|
|
||||||
|
When adding plugin integration content to CLAUDE.md:
|
||||||
|
|
||||||
|
**Placement:**
|
||||||
|
- Add plugin sections after the main project documentation
|
||||||
|
- Group all plugin integrations together under a clear header
|
||||||
|
- Use consistent formatting across all plugin sections
|
||||||
|
|
||||||
|
**Process:**
|
||||||
|
1. Read the plugin's `claude-md-integration.md` file
|
||||||
|
2. Show the content to the user for review
|
||||||
|
3. Ask for confirmation: "Add this plugin integration? [Y/n]"
|
||||||
|
4. If confirmed, insert at appropriate location in CLAUDE.md
|
||||||
|
5. Repeat for each missing plugin
|
||||||
|
|
||||||
|
**User Confirmation Flow:**
|
||||||
|
```
|
||||||
|
Plugin Integration: projman
|
||||||
|
--------------------------
|
||||||
|
[Show content from plugins/projman/claude-md-integration.md]
|
||||||
|
|
||||||
|
Add this integration to CLAUDE.md?
|
||||||
|
[1] Yes, add this integration
|
||||||
|
[2] Skip this plugin
|
||||||
|
[3] Add all remaining plugins
|
||||||
|
[4] Cancel
|
||||||
|
```
|
||||||
|
|
||||||
|
**Best Practices:**
|
||||||
|
- Never modify CLAUDE.md without user confirmation
|
||||||
|
- Show exactly what will be added before making changes
|
||||||
|
- Allow users to skip specific plugins they don't want documented
|
||||||
|
- Preserve existing CLAUDE.md structure and content
|
||||||
|
|
||||||
|
### 6. Create New CLAUDE.md Files
|
||||||
|
|
||||||
When creating a new CLAUDE.md:
|
When creating a new CLAUDE.md:
|
||||||
|
|
||||||
|
|||||||
30
plugins/claude-config-maintainer/claude-md-integration.md
Normal file
30
plugins/claude-config-maintainer/claude-md-integration.md
Normal file
@@ -0,0 +1,30 @@
|
|||||||
|
## CLAUDE.md Maintenance (claude-config-maintainer)
|
||||||
|
|
||||||
|
This project uses the **claude-config-maintainer** plugin to analyze and optimize CLAUDE.md configuration files.
|
||||||
|
|
||||||
|
### Available Commands
|
||||||
|
|
||||||
|
| Command | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `/config-analyze` | Analyze CLAUDE.md for optimization opportunities with 100-point scoring |
|
||||||
|
| `/config-optimize` | Automatically optimize CLAUDE.md structure and content |
|
||||||
|
| `/config-init` | Initialize a new CLAUDE.md file for a project |
|
||||||
|
|
||||||
|
### Scoring System
|
||||||
|
|
||||||
|
The analysis uses a 100-point scoring system across four categories:
|
||||||
|
|
||||||
|
| Category | Points | What It Measures |
|
||||||
|
|----------|--------|------------------|
|
||||||
|
| Structure | 25 | Organization, headers, navigation, grouping |
|
||||||
|
| Clarity | 25 | Instructions, examples, language, detail level |
|
||||||
|
| Completeness | 25 | Overview, quick start, critical rules, workflows |
|
||||||
|
| Conciseness | 25 | Efficiency, no repetition, appropriate length |
|
||||||
|
|
||||||
|
### Usage Guidelines
|
||||||
|
|
||||||
|
- Run `/config-analyze` periodically to assess CLAUDE.md quality
|
||||||
|
- Target a score of **70+/100** for effective Claude Code operation
|
||||||
|
- Address HIGH priority issues first when optimizing
|
||||||
|
- Use `/config-init` when setting up new projects to start with best practices
|
||||||
|
- Re-analyze after making changes to verify improvements
|
||||||
@@ -1,10 +1,10 @@
|
|||||||
---
|
---
|
||||||
description: Analyze CLAUDE.md for optimization opportunities
|
description: Analyze CLAUDE.md for optimization opportunities and plugin integration
|
||||||
---
|
---
|
||||||
|
|
||||||
# Analyze CLAUDE.md
|
# Analyze CLAUDE.md
|
||||||
|
|
||||||
This command analyzes your project's CLAUDE.md file and provides a detailed report on optimization opportunities.
|
This command analyzes your project's CLAUDE.md file and provides a detailed report on optimization opportunities and plugin integration status.
|
||||||
|
|
||||||
## What This Command Does
|
## What This Command Does
|
||||||
|
|
||||||
@@ -12,7 +12,9 @@ This command analyzes your project's CLAUDE.md file and provides a detailed repo
|
|||||||
2. **Analyze Structure** - Evaluates organization, headers, and flow
|
2. **Analyze Structure** - Evaluates organization, headers, and flow
|
||||||
3. **Check Content** - Reviews clarity, completeness, and conciseness
|
3. **Check Content** - Reviews clarity, completeness, and conciseness
|
||||||
4. **Identify Issues** - Finds redundancy, verbosity, and missing sections
|
4. **Identify Issues** - Finds redundancy, verbosity, and missing sections
|
||||||
5. **Generate Report** - Provides scored assessment with recommendations
|
5. **Detect Active Plugins** - Identifies marketplace plugins enabled in the project
|
||||||
|
6. **Check Plugin Integration** - Verifies CLAUDE.md references active plugins
|
||||||
|
7. **Generate Report** - Provides scored assessment with recommendations
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
@@ -52,6 +54,29 @@ Analyze the CLAUDE.md file in this project
|
|||||||
- Appropriate length for project size
|
- Appropriate length for project size
|
||||||
- No generic filler content
|
- No generic filler content
|
||||||
|
|
||||||
|
## Plugin Integration Analysis
|
||||||
|
|
||||||
|
After the content analysis, the command detects and analyzes marketplace plugin integration:
|
||||||
|
|
||||||
|
### Detection Method
|
||||||
|
|
||||||
|
1. **Read `.claude/settings.local.json`** - Check for enabled MCP servers
|
||||||
|
2. **Map MCP servers to plugins** - Use marketplace registry to identify active plugins:
|
||||||
|
- `gitea` → projman
|
||||||
|
- `netbox` → cmdb-assistant
|
||||||
|
3. **Check for hooks** - Identify hook-based plugins (project-hygiene)
|
||||||
|
4. **Scan CLAUDE.md** - Look for plugin integration content
|
||||||
|
|
||||||
|
### Plugin Coverage Scoring
|
||||||
|
|
||||||
|
For each detected plugin, verify CLAUDE.md contains:
|
||||||
|
- Plugin section header or mention
|
||||||
|
- Available commands documentation
|
||||||
|
- MCP tools reference (if applicable)
|
||||||
|
- Usage guidelines
|
||||||
|
|
||||||
|
Coverage is reported as percentage: `(plugins referenced / plugins detected) * 100`
|
||||||
|
|
||||||
## Expected Output
|
## Expected Output
|
||||||
|
|
||||||
```
|
```
|
||||||
@@ -101,10 +126,37 @@ Recommendations:
|
|||||||
|
|
||||||
Estimated improvement: 15-20 points after changes
|
Estimated improvement: 15-20 points after changes
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Plugin Integration Analysis
|
||||||
|
===========================
|
||||||
|
|
||||||
|
Detected Active Plugins:
|
||||||
|
✓ projman (via gitea MCP server)
|
||||||
|
✓ cmdb-assistant (via netbox MCP server)
|
||||||
|
✓ project-hygiene (via PostToolUse hook)
|
||||||
|
|
||||||
|
Plugin Coverage: 33% (1/3 plugins referenced)
|
||||||
|
|
||||||
|
✓ projman - Referenced in CLAUDE.md
|
||||||
|
✗ cmdb-assistant - NOT referenced
|
||||||
|
✗ project-hygiene - NOT referenced
|
||||||
|
|
||||||
|
Missing Integration Content:
|
||||||
|
|
||||||
|
1. cmdb-assistant
|
||||||
|
Add infrastructure management commands and NetBox MCP tools reference.
|
||||||
|
|
||||||
|
2. project-hygiene
|
||||||
|
Add cleanup hook documentation and configuration options.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
Would you like me to:
|
Would you like me to:
|
||||||
[1] Implement all recommended changes
|
[1] Implement all content recommendations
|
||||||
[2] Show before/after for specific section
|
[2] Add missing plugin integrations to CLAUDE.md
|
||||||
[3] Generate optimized version for review
|
[3] Do both (recommended)
|
||||||
|
[4] Show preview of changes first
|
||||||
```
|
```
|
||||||
|
|
||||||
## When to Use
|
## When to Use
|
||||||
@@ -115,6 +167,8 @@ Run `/config-analyze` when:
|
|||||||
- Claude seems to miss instructions
|
- Claude seems to miss instructions
|
||||||
- Before major project changes
|
- Before major project changes
|
||||||
- Periodic maintenance (quarterly)
|
- Periodic maintenance (quarterly)
|
||||||
|
- After installing new marketplace plugins
|
||||||
|
- When Claude doesn't seem to use available plugin tools
|
||||||
|
|
||||||
## Follow-Up Actions
|
## Follow-Up Actions
|
||||||
|
|
||||||
|
|||||||
@@ -3,10 +3,11 @@
|
|||||||
"version": "1.0.0",
|
"version": "1.0.0",
|
||||||
"description": "NetBox CMDB integration for infrastructure management - query, create, update, and manage network devices, IP addresses, sites, and more",
|
"description": "NetBox CMDB integration for infrastructure management - query, create, update, and manage network devices, IP addresses, sites, and more",
|
||||||
"author": {
|
"author": {
|
||||||
"name": "Bandit Labs",
|
"name": "Leo Miranda",
|
||||||
"email": "dev@banditlabs.io"
|
"email": "leobmiranda@gmail.com"
|
||||||
},
|
},
|
||||||
"homepage": "https://github.com/bandit-labs/cmdb-assistant",
|
"homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/cmdb-assistant/README.md",
|
||||||
|
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
|
||||||
"license": "MIT",
|
"license": "MIT",
|
||||||
"keywords": [
|
"keywords": [
|
||||||
"netbox",
|
"netbox",
|
||||||
@@ -15,5 +16,8 @@
|
|||||||
"network",
|
"network",
|
||||||
"ipam",
|
"ipam",
|
||||||
"dcim"
|
"dcim"
|
||||||
]
|
],
|
||||||
|
"commands": ["./commands/"],
|
||||||
|
"agents": ["./agents/"],
|
||||||
|
"mcpServers": "./.mcp.json"
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -167,4 +167,4 @@ The plugin uses the shared NetBox MCP server at `../mcp-servers/netbox/`.
|
|||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
MIT License - Part of the Bandit Labs plugin collection.
|
MIT License - Part of the Claude Code Marketplace.
|
||||||
|
|||||||
58
plugins/cmdb-assistant/claude-md-integration.md
Normal file
58
plugins/cmdb-assistant/claude-md-integration.md
Normal file
@@ -0,0 +1,58 @@
|
|||||||
|
## Infrastructure Management (cmdb-assistant)
|
||||||
|
|
||||||
|
This project uses the **cmdb-assistant** plugin for NetBox CMDB integration to manage network infrastructure.
|
||||||
|
|
||||||
|
### Available Commands
|
||||||
|
|
||||||
|
| Command | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `/cmdb-search` | Search across all NetBox objects |
|
||||||
|
| `/cmdb-device` | Manage devices (create, update, list) |
|
||||||
|
| `/cmdb-ip` | Manage IP addresses and prefixes |
|
||||||
|
| `/cmdb-site` | Manage sites and locations |
|
||||||
|
|
||||||
|
### MCP Tools Available
|
||||||
|
|
||||||
|
The following NetBox MCP tools are available for infrastructure management:
|
||||||
|
|
||||||
|
**DCIM (Data Center Infrastructure Management):**
|
||||||
|
- `dcim_list_devices`, `dcim_get_device`, `dcim_create_device`, `dcim_update_device` - Device management
|
||||||
|
- `dcim_list_sites`, `dcim_get_site`, `dcim_create_site` - Site management
|
||||||
|
- `dcim_list_racks`, `dcim_get_rack`, `dcim_create_rack` - Rack management
|
||||||
|
- `dcim_list_interfaces`, `dcim_create_interface` - Interface management
|
||||||
|
- `dcim_list_cables`, `dcim_create_cable` - Cable management
|
||||||
|
- `dcim_list_device_types`, `dcim_list_device_roles`, `dcim_list_manufacturers` - Reference data
|
||||||
|
- `dcim_list_regions`, `dcim_list_locations` - Location hierarchy
|
||||||
|
|
||||||
|
**IPAM (IP Address Management):**
|
||||||
|
- `ipam_list_ip_addresses`, `ipam_create_ip_address`, `ipam_get_ip_address` - IP address management
|
||||||
|
- `ipam_list_prefixes`, `ipam_create_prefix`, `ipam_list_available_prefixes` - Prefix management
|
||||||
|
- `ipam_list_vlans`, `ipam_create_vlan` - VLAN management
|
||||||
|
- `ipam_list_vrfs`, `ipam_create_vrf` - VRF management
|
||||||
|
- `ipam_list_available_ips`, `ipam_create_available_ip` - IP allocation
|
||||||
|
|
||||||
|
**Virtualization:**
|
||||||
|
- `virtualization_list_virtual_machines`, `virtualization_create_virtual_machine` - VM management
|
||||||
|
- `virtualization_list_clusters`, `virtualization_create_cluster` - Cluster management
|
||||||
|
- `virtualization_list_vm_interfaces` - VM interface management
|
||||||
|
|
||||||
|
**Circuits:**
|
||||||
|
- `circuits_list_circuits`, `circuits_create_circuit` - Circuit management
|
||||||
|
- `circuits_list_providers`, `circuits_create_provider` - Provider management
|
||||||
|
|
||||||
|
**Tenancy:**
|
||||||
|
- `tenancy_list_tenants`, `tenancy_create_tenant` - Tenant management
|
||||||
|
- `tenancy_list_contacts`, `tenancy_create_contact` - Contact management
|
||||||
|
|
||||||
|
**Extras:**
|
||||||
|
- `extras_list_tags`, `extras_create_tag` - Tag management
|
||||||
|
- `extras_list_journal_entries`, `extras_create_journal_entry` - Audit journal
|
||||||
|
- `extras_list_object_changes` - Change tracking
|
||||||
|
|
||||||
|
### Usage Guidelines
|
||||||
|
|
||||||
|
- Use NetBox MCP tools for all infrastructure queries and modifications
|
||||||
|
- Always verify device/IP existence before creating duplicates
|
||||||
|
- Use tags for categorization and filtering
|
||||||
|
- Create journal entries for significant changes to maintain audit trail
|
||||||
|
- Check available IPs in a prefix before manual allocation
|
||||||
@@ -294,4 +294,4 @@ logging.basicConfig(level=logging.DEBUG)
|
|||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
Part of the Bandit Labs Claude Code Plugins project (`support-claude-mktplace`).
|
MIT License - Part of the Claude Code Marketplace (`support-claude-mktplace`).
|
||||||
|
|||||||
13
plugins/code-sentinel/.claude-plugin/plugin.json
Normal file
13
plugins/code-sentinel/.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,13 @@
|
|||||||
|
{
|
||||||
|
"name": "code-sentinel",
|
||||||
|
"description": "Security scanning and code refactoring tools",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"author": {
|
||||||
|
"name": "Leo Miranda",
|
||||||
|
"email": "leobmiranda@gmail.com"
|
||||||
|
},
|
||||||
|
"homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/code-sentinel/README.md",
|
||||||
|
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
|
||||||
|
"license": "MIT",
|
||||||
|
"keywords": ["security", "refactoring", "code-quality", "static-analysis", "hooks"]
|
||||||
|
}
|
||||||
47
plugins/code-sentinel/README.md
Normal file
47
plugins/code-sentinel/README.md
Normal file
@@ -0,0 +1,47 @@
|
|||||||
|
# code-sentinel
|
||||||
|
|
||||||
|
Security scanning and code refactoring tools for Claude Code projects.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
### Security Scanning
|
||||||
|
- **PreToolUse Hook**: Catches vulnerabilities BEFORE code is written
|
||||||
|
- **Full Audit**: `/security-scan` for comprehensive project review
|
||||||
|
- **Pattern Detection**: SQL injection, XSS, command injection, secrets, and more
|
||||||
|
|
||||||
|
### Refactoring
|
||||||
|
- **Pattern Library**: Extract method, simplify conditionals, modernize syntax
|
||||||
|
- **Safe Transforms**: Preview changes before applying
|
||||||
|
- **Reference Updates**: Automatically updates all call sites
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
|
||||||
|
| Command | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `/security-scan` | Full project security audit |
|
||||||
|
| `/refactor <target>` | Apply refactoring with pattern |
|
||||||
|
| `/refactor-dry <target>` | Preview opportunities without changes |
|
||||||
|
|
||||||
|
## Hooks
|
||||||
|
|
||||||
|
- **PreToolUse (Write\|Edit)**: Scans code for security patterns before writing
|
||||||
|
|
||||||
|
## Security Patterns Detected
|
||||||
|
|
||||||
|
| Category | Examples |
|
||||||
|
|----------|----------|
|
||||||
|
| Injection | SQL, Command, Code (eval), XSS |
|
||||||
|
| Secrets | Hardcoded API keys, passwords |
|
||||||
|
| Deserialization | Pickle, unsafe YAML |
|
||||||
|
| Path Traversal | Unsanitized file paths |
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/plugin marketplace add https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git
|
||||||
|
/plugin install code-sentinel
|
||||||
|
```
|
||||||
|
|
||||||
|
## Integration
|
||||||
|
|
||||||
|
See claude-md-integration.md for CLAUDE.md additions.
|
||||||
48
plugins/code-sentinel/agents/refactor-advisor.md
Normal file
48
plugins/code-sentinel/agents/refactor-advisor.md
Normal file
@@ -0,0 +1,48 @@
|
|||||||
|
---
|
||||||
|
description: Code structure and refactoring specialist
|
||||||
|
---
|
||||||
|
|
||||||
|
# Refactor Advisor Agent
|
||||||
|
|
||||||
|
You are a software architect specializing in code quality, design patterns, and refactoring.
|
||||||
|
|
||||||
|
## Expertise
|
||||||
|
|
||||||
|
- Martin Fowler's refactoring catalog
|
||||||
|
- SOLID principles
|
||||||
|
- Design patterns (GoF, enterprise, functional)
|
||||||
|
- Code smells detection
|
||||||
|
- Cyclomatic complexity analysis
|
||||||
|
- Technical debt assessment
|
||||||
|
|
||||||
|
## Analysis Approach
|
||||||
|
|
||||||
|
When analyzing code:
|
||||||
|
|
||||||
|
1. **Identify Code Smells**
|
||||||
|
- Long methods (>20 lines)
|
||||||
|
- Large classes (>200 lines)
|
||||||
|
- Long parameter lists (>3 params)
|
||||||
|
- Duplicate code
|
||||||
|
- Feature envy
|
||||||
|
- Data clumps
|
||||||
|
|
||||||
|
2. **Assess Structure**
|
||||||
|
- Single responsibility adherence
|
||||||
|
- Coupling between modules
|
||||||
|
- Cohesion within modules
|
||||||
|
- Abstraction levels
|
||||||
|
|
||||||
|
3. **Recommend Refactorings**
|
||||||
|
- Match smells to appropriate refactorings
|
||||||
|
- Consider dependencies and side effects
|
||||||
|
- Prioritize by impact and risk
|
||||||
|
- Provide step-by-step approach
|
||||||
|
|
||||||
|
## Output Style
|
||||||
|
|
||||||
|
Be practical:
|
||||||
|
- Focus on high-impact improvements
|
||||||
|
- Explain the "why" behind recommendations
|
||||||
|
- Provide concrete before/after examples
|
||||||
|
- Consider testing implications
|
||||||
50
plugins/code-sentinel/agents/security-reviewer.md
Normal file
50
plugins/code-sentinel/agents/security-reviewer.md
Normal file
@@ -0,0 +1,50 @@
|
|||||||
|
---
|
||||||
|
description: Security-focused code review agent
|
||||||
|
---
|
||||||
|
|
||||||
|
# Security Reviewer Agent
|
||||||
|
|
||||||
|
You are a security engineer specializing in application security and secure coding practices.
|
||||||
|
|
||||||
|
## Expertise
|
||||||
|
|
||||||
|
- OWASP Top 10 vulnerabilities
|
||||||
|
- Language-specific security pitfalls (Python, JavaScript, Go, etc.)
|
||||||
|
- Authentication and authorization flaws
|
||||||
|
- Cryptographic misuse
|
||||||
|
- Input validation and output encoding
|
||||||
|
- Secure configuration
|
||||||
|
|
||||||
|
## Review Approach
|
||||||
|
|
||||||
|
When reviewing code:
|
||||||
|
|
||||||
|
1. **Identify Trust Boundaries**
|
||||||
|
- Where does user input enter?
|
||||||
|
- Where does data leave the system?
|
||||||
|
- What operations are privileged?
|
||||||
|
|
||||||
|
2. **Trace Data Flow**
|
||||||
|
- Follow user input through the code
|
||||||
|
- Check for sanitization at each boundary
|
||||||
|
- Verify output encoding
|
||||||
|
|
||||||
|
3. **Check Security Controls**
|
||||||
|
- Authentication present where needed?
|
||||||
|
- Authorization checked before actions?
|
||||||
|
- Secrets properly managed?
|
||||||
|
- Errors handled without leaking info?
|
||||||
|
|
||||||
|
4. **Language-Specific Checks**
|
||||||
|
Python: eval, pickle, yaml.load, subprocess
|
||||||
|
JavaScript: innerHTML, eval, prototype pollution
|
||||||
|
SQL: parameterized queries, ORM usage
|
||||||
|
Shell: quoting, input validation
|
||||||
|
|
||||||
|
## Output Style
|
||||||
|
|
||||||
|
Be specific and actionable:
|
||||||
|
- Quote the vulnerable line
|
||||||
|
- Explain the attack vector
|
||||||
|
- Provide the secure alternative
|
||||||
|
- Rate severity (Critical/High/Medium/Low)
|
||||||
26
plugins/code-sentinel/claude-md-integration.md
Normal file
26
plugins/code-sentinel/claude-md-integration.md
Normal file
@@ -0,0 +1,26 @@
|
|||||||
|
# Code Sentinel Integration
|
||||||
|
|
||||||
|
Add to your project's CLAUDE.md:
|
||||||
|
|
||||||
|
## Security & Code Quality
|
||||||
|
|
||||||
|
This project uses code-sentinel for security scanning and refactoring.
|
||||||
|
|
||||||
|
### Automatic Security Checks
|
||||||
|
PreToolUse hooks scan all code changes for:
|
||||||
|
- SQL/Command/Code injection
|
||||||
|
- XSS vulnerabilities
|
||||||
|
- Hardcoded secrets
|
||||||
|
- Unsafe deserialization
|
||||||
|
|
||||||
|
Critical issues are blocked. Warnings are noted but allowed.
|
||||||
|
|
||||||
|
### Commands
|
||||||
|
- `/security-scan` - Full project security audit
|
||||||
|
- `/refactor <target>` - Apply refactoring pattern
|
||||||
|
- `/refactor-dry <target>` - Preview refactoring opportunities
|
||||||
|
|
||||||
|
### Severity Levels
|
||||||
|
- 🔴 Critical: Must fix immediately
|
||||||
|
- 🟠 High: Fix before release
|
||||||
|
- 🟡 Medium: Improve when possible
|
||||||
57
plugins/code-sentinel/commands/refactor-dry.md
Normal file
57
plugins/code-sentinel/commands/refactor-dry.md
Normal file
@@ -0,0 +1,57 @@
|
|||||||
|
---
|
||||||
|
description: Preview refactoring changes without applying them
|
||||||
|
---
|
||||||
|
|
||||||
|
# Refactor Dry Run
|
||||||
|
|
||||||
|
Analyze and preview refactoring opportunities without making changes.
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
```
|
||||||
|
/refactor-dry <target> [--all]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Target:** File path, function name, or "." for current file
|
||||||
|
**--all:** Show all opportunities, not just recommended
|
||||||
|
|
||||||
|
## Process
|
||||||
|
|
||||||
|
1. **Scan Target**
|
||||||
|
Analyze code for refactoring opportunities.
|
||||||
|
|
||||||
|
2. **Score Opportunities**
|
||||||
|
Each opportunity rated by:
|
||||||
|
- Impact (how much it improves code)
|
||||||
|
- Risk (likelihood of breaking something)
|
||||||
|
- Effort (complexity of the refactoring)
|
||||||
|
|
||||||
|
3. **Output**
|
||||||
|
```
|
||||||
|
## Refactoring Opportunities: src/handlers.py
|
||||||
|
|
||||||
|
### Recommended (High Impact, Low Risk)
|
||||||
|
|
||||||
|
1. **extract-method** at lines 45-67
|
||||||
|
- Extract order validation logic
|
||||||
|
- Impact: High (reduces complexity from 12 to 4)
|
||||||
|
- Risk: Low (pure function, no side effects)
|
||||||
|
- Run: `/refactor src/handlers.py:45 --pattern=extract-method`
|
||||||
|
|
||||||
|
2. **use-dataclass** for OrderInput class
|
||||||
|
- Convert to dataclass with validation
|
||||||
|
- Impact: Medium (reduces boilerplate)
|
||||||
|
- Risk: Low
|
||||||
|
- Run: `/refactor src/models.py:OrderInput --pattern=use-dataclass`
|
||||||
|
|
||||||
|
### Optional (Consider Later)
|
||||||
|
|
||||||
|
3. **use-fstring** at 12 locations
|
||||||
|
- Modernize string formatting
|
||||||
|
- Impact: Low (readability only)
|
||||||
|
- Risk: None
|
||||||
|
|
||||||
|
### Summary
|
||||||
|
- 2 recommended refactorings
|
||||||
|
- 1 optional improvement
|
||||||
|
- Estimated complexity reduction: 35%
|
||||||
|
```
|
||||||
81
plugins/code-sentinel/commands/refactor.md
Normal file
81
plugins/code-sentinel/commands/refactor.md
Normal file
@@ -0,0 +1,81 @@
|
|||||||
|
---
|
||||||
|
description: Apply refactoring patterns to improve code structure and maintainability
|
||||||
|
---
|
||||||
|
|
||||||
|
# Refactor
|
||||||
|
|
||||||
|
Apply refactoring transformations to specified code.
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
```
|
||||||
|
/refactor <target> [--pattern=<pattern>]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Target:** File path, function name, or "." for current context
|
||||||
|
**Pattern:** Specific refactoring pattern (optional)
|
||||||
|
|
||||||
|
## Available Patterns
|
||||||
|
|
||||||
|
### Structure
|
||||||
|
| Pattern | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `extract-method` | Extract code block into named function |
|
||||||
|
| `extract-class` | Move related methods to new class |
|
||||||
|
| `inline` | Inline trivial function/variable |
|
||||||
|
| `rename` | Rename with all references updated |
|
||||||
|
| `move` | Move function/class to different module |
|
||||||
|
|
||||||
|
### Simplification
|
||||||
|
| Pattern | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `simplify-conditional` | Flatten nested if/else |
|
||||||
|
| `remove-dead-code` | Delete unreachable code |
|
||||||
|
| `consolidate-duplicate` | Merge duplicate code blocks |
|
||||||
|
| `decompose-conditional` | Break complex conditions into named parts |
|
||||||
|
|
||||||
|
### Modernization
|
||||||
|
| Pattern | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `use-comprehension` | Convert loops to list/dict comprehensions |
|
||||||
|
| `use-pathlib` | Replace os.path with pathlib |
|
||||||
|
| `use-fstring` | Convert .format() to f-strings |
|
||||||
|
| `use-typing` | Add type hints |
|
||||||
|
| `use-dataclass` | Convert class to dataclass |
|
||||||
|
|
||||||
|
## Process
|
||||||
|
|
||||||
|
1. **Analyze Target**
|
||||||
|
- Parse code structure
|
||||||
|
- Identify refactoring opportunities
|
||||||
|
- Check for side effects and dependencies
|
||||||
|
|
||||||
|
2. **Propose Changes**
|
||||||
|
- Show before/after diff
|
||||||
|
- Explain the improvement
|
||||||
|
- List affected files/references
|
||||||
|
|
||||||
|
3. **Apply (with confirmation)**
|
||||||
|
- Make changes
|
||||||
|
- Update all references
|
||||||
|
- Run existing tests if available
|
||||||
|
|
||||||
|
4. **Output**
|
||||||
|
```
|
||||||
|
## Refactoring: extract-method
|
||||||
|
|
||||||
|
### Target
|
||||||
|
src/handlers.py:create_order (lines 45-89)
|
||||||
|
|
||||||
|
### Changes
|
||||||
|
- Extracted validation logic → validate_order_input()
|
||||||
|
- Extracted pricing logic → calculate_order_total()
|
||||||
|
- Original function now 15 lines (was 44)
|
||||||
|
|
||||||
|
### Files Modified
|
||||||
|
- src/handlers.py
|
||||||
|
- tests/test_handlers.py (updated calls)
|
||||||
|
|
||||||
|
### Metrics
|
||||||
|
- Cyclomatic complexity: 12 → 4
|
||||||
|
- Function length: 44 → 15 lines
|
||||||
|
```
|
||||||
64
plugins/code-sentinel/commands/security-scan.md
Normal file
64
plugins/code-sentinel/commands/security-scan.md
Normal file
@@ -0,0 +1,64 @@
|
|||||||
|
---
|
||||||
|
description: Full security audit of codebase - scans all files for vulnerability patterns
|
||||||
|
---
|
||||||
|
|
||||||
|
# Security Scan
|
||||||
|
|
||||||
|
Comprehensive security audit of the project.
|
||||||
|
|
||||||
|
## Process
|
||||||
|
|
||||||
|
1. **File Discovery**
|
||||||
|
Scan all code files: .py, .js, .ts, .jsx, .tsx, .go, .rs, .java, .rb, .php, .sh
|
||||||
|
|
||||||
|
2. **Pattern Detection**
|
||||||
|
|
||||||
|
### Critical Vulnerabilities
|
||||||
|
| Pattern | Risk | Detection |
|
||||||
|
|---------|------|-----------|
|
||||||
|
| SQL Injection | High | String concat in SQL queries |
|
||||||
|
| Command Injection | High | shell=True, os.system with vars |
|
||||||
|
| XSS | High | innerHTML with user input |
|
||||||
|
| Code Injection | Critical | eval/exec with external input |
|
||||||
|
| Deserialization | Critical | pickle.loads, yaml.load unsafe |
|
||||||
|
| Path Traversal | High | File ops without sanitization |
|
||||||
|
| Hardcoded Secrets | High | API keys, passwords in code |
|
||||||
|
| SSRF | Medium | URL from user input in requests |
|
||||||
|
|
||||||
|
### Code Quality Issues
|
||||||
|
| Pattern | Risk | Detection |
|
||||||
|
|---------|------|-----------|
|
||||||
|
| Broad Exceptions | Low | `except:` or `except Exception:` |
|
||||||
|
| Debug Statements | Low | print/console.log with data |
|
||||||
|
| TODO/FIXME Security | Medium | Comments mentioning security |
|
||||||
|
| Deprecated Functions | Medium | Known insecure functions |
|
||||||
|
|
||||||
|
3. **Output Format**
|
||||||
|
```
|
||||||
|
## Security Scan Report
|
||||||
|
|
||||||
|
### Critical (Immediate Action Required)
|
||||||
|
🔴 src/db.py:45 - SQL Injection
|
||||||
|
Code: `f"SELECT * FROM users WHERE id = {user_id}"`
|
||||||
|
Fix: Use parameterized query: `cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))`
|
||||||
|
|
||||||
|
### High
|
||||||
|
🟠 config.py:12 - Hardcoded Secret
|
||||||
|
Code: `API_KEY = "sk-1234..."`
|
||||||
|
Fix: Use environment variable: `API_KEY = os.environ.get("API_KEY")`
|
||||||
|
|
||||||
|
### Medium
|
||||||
|
🟡 utils.py:78 - Broad Exception
|
||||||
|
Code: `except:`
|
||||||
|
Fix: Catch specific exceptions
|
||||||
|
|
||||||
|
### Summary
|
||||||
|
- Critical: X (must fix before deploy)
|
||||||
|
- High: X (fix soon)
|
||||||
|
- Medium: X (improve when possible)
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Exit Code Guidance**
|
||||||
|
- Critical findings: Recommend blocking merge/deploy
|
||||||
|
- High findings: Recommend fixing before release
|
||||||
|
- Medium/Low: Informational
|
||||||
15
plugins/code-sentinel/hooks/hooks.json
Normal file
15
plugins/code-sentinel/hooks/hooks.json
Normal file
@@ -0,0 +1,15 @@
|
|||||||
|
{
|
||||||
|
"hooks": {
|
||||||
|
"PreToolUse": [
|
||||||
|
{
|
||||||
|
"matcher": "Write|Edit|MultiEdit",
|
||||||
|
"hooks": [
|
||||||
|
{
|
||||||
|
"type": "prompt",
|
||||||
|
"prompt": "SECURITY CHECK - Before writing this code, scan for these patterns:\n\n**Critical (BLOCK if found):**\n- eval(), exec() with user input\n- SQL string concatenation (SQL injection)\n- shell=True with user input (command injection)\n- Hardcoded secrets (API keys, passwords, tokens)\n- Pickle/marshal deserialization of untrusted data\n- innerHTML/dangerouslySetInnerHTML with user content (XSS)\n\n**Warning (WARN but allow):**\n- subprocess without input validation\n- File operations without path sanitization\n- HTTP requests without timeout\n- Broad exception catches (except:)\n- Debug/print statements with sensitive data\n\n**Response:**\n- If CRITICAL found: STOP, explain the issue, suggest safe alternative\n- If WARNING found: Note it briefly, proceed with suggestion\n- If clean: Proceed silently (say nothing)\n\nDo NOT announce clean scans. Only speak if issues found."
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
111
plugins/code-sentinel/skills/security-patterns/SKILL.md
Normal file
111
plugins/code-sentinel/skills/security-patterns/SKILL.md
Normal file
@@ -0,0 +1,111 @@
|
|||||||
|
---
|
||||||
|
description: Security vulnerability patterns and detection rules
|
||||||
|
---
|
||||||
|
|
||||||
|
# Security Patterns Skill
|
||||||
|
|
||||||
|
## Critical Patterns (Always Block)
|
||||||
|
|
||||||
|
### SQL Injection
|
||||||
|
```python
|
||||||
|
# VULNERABLE
|
||||||
|
query = f"SELECT * FROM users WHERE id = {user_id}"
|
||||||
|
query = "SELECT * FROM users WHERE id = " + user_id
|
||||||
|
|
||||||
|
# SAFE
|
||||||
|
cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))
|
||||||
|
User.objects.filter(id=user_id)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Command Injection
|
||||||
|
```python
|
||||||
|
# VULNERABLE
|
||||||
|
os.system(f"convert {filename} output.png")
|
||||||
|
subprocess.run(cmd, shell=True)
|
||||||
|
|
||||||
|
# SAFE
|
||||||
|
subprocess.run(["convert", filename, "output.png"], shell=False)
|
||||||
|
shlex.quote(filename)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Code Injection
|
||||||
|
```python
|
||||||
|
# VULNERABLE
|
||||||
|
eval(user_input)
|
||||||
|
exec(user_code)
|
||||||
|
|
||||||
|
# SAFE
|
||||||
|
ast.literal_eval(user_input) # Only for literals
|
||||||
|
# Use sandboxed execution environment
|
||||||
|
```
|
||||||
|
|
||||||
|
### XSS
|
||||||
|
```javascript
|
||||||
|
// VULNERABLE
|
||||||
|
element.innerHTML = userContent;
|
||||||
|
dangerouslySetInnerHTML={{__html: userData}}
|
||||||
|
|
||||||
|
// SAFE
|
||||||
|
element.textContent = userContent;
|
||||||
|
DOMPurify.sanitize(userContent)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Hardcoded Secrets
|
||||||
|
```python
|
||||||
|
# VULNERABLE
|
||||||
|
API_KEY = "sk-1234567890abcdef"
|
||||||
|
password = "admin123"
|
||||||
|
|
||||||
|
# SAFE
|
||||||
|
API_KEY = os.environ.get("API_KEY")
|
||||||
|
password = get_secret("db_password")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Unsafe Deserialization
|
||||||
|
```python
|
||||||
|
# VULNERABLE
|
||||||
|
data = pickle.loads(user_data)
|
||||||
|
config = yaml.load(file) # yaml.load without Loader
|
||||||
|
|
||||||
|
# SAFE
|
||||||
|
data = json.loads(user_data)
|
||||||
|
config = yaml.safe_load(file)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Warning Patterns (Flag but Allow)
|
||||||
|
|
||||||
|
### Broad Exception Handling
|
||||||
|
```python
|
||||||
|
# WARNING
|
||||||
|
try:
|
||||||
|
risky_operation()
|
||||||
|
except:
|
||||||
|
pass
|
||||||
|
|
||||||
|
# BETTER
|
||||||
|
try:
|
||||||
|
risky_operation()
|
||||||
|
except SpecificError as e:
|
||||||
|
logger.error(f"Operation failed: {e}")
|
||||||
|
raise
|
||||||
|
```
|
||||||
|
|
||||||
|
### Missing Timeout
|
||||||
|
```python
|
||||||
|
# WARNING
|
||||||
|
response = requests.get(url)
|
||||||
|
|
||||||
|
# BETTER
|
||||||
|
response = requests.get(url, timeout=30)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Path Traversal Risk
|
||||||
|
```python
|
||||||
|
# WARNING
|
||||||
|
file_path = os.path.join(base_dir, user_filename)
|
||||||
|
|
||||||
|
# BETTER
|
||||||
|
file_path = os.path.join(base_dir, os.path.basename(user_filename))
|
||||||
|
if not file_path.startswith(os.path.abspath(base_dir)):
|
||||||
|
raise ValueError("Invalid path")
|
||||||
|
```
|
||||||
13
plugins/doc-guardian/.claude-plugin/plugin.json
Normal file
13
plugins/doc-guardian/.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,13 @@
|
|||||||
|
{
|
||||||
|
"name": "doc-guardian",
|
||||||
|
"description": "Automatic documentation drift detection and synchronization",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"author": {
|
||||||
|
"name": "Leo Miranda",
|
||||||
|
"email": "leobmiranda@gmail.com"
|
||||||
|
},
|
||||||
|
"homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/doc-guardian/README.md",
|
||||||
|
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
|
||||||
|
"license": "MIT",
|
||||||
|
"keywords": ["documentation", "sync", "drift-detection", "automation", "hooks"]
|
||||||
|
}
|
||||||
49
plugins/doc-guardian/README.md
Normal file
49
plugins/doc-guardian/README.md
Normal file
@@ -0,0 +1,49 @@
|
|||||||
|
# doc-guardian
|
||||||
|
|
||||||
|
Automatic documentation drift detection and synchronization for Claude Code projects.
|
||||||
|
|
||||||
|
## Problem Solved
|
||||||
|
|
||||||
|
Documentation gets outdated. Functions get renamed, configs change, versions bump—but docs lag behind. This creates:
|
||||||
|
- Multiple review cycles finding stale references
|
||||||
|
- Unnecessary commits fixing docs piecemeal
|
||||||
|
- User confusion from outdated instructions
|
||||||
|
|
||||||
|
## Solution
|
||||||
|
|
||||||
|
doc-guardian watches your code changes and automatically:
|
||||||
|
1. Detects when changes affect documentation
|
||||||
|
2. Queues updates silently (doesn't interrupt your flow)
|
||||||
|
3. Syncs all doc changes in a single commit when ready
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
|
||||||
|
| Command | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `/doc-audit` | Full project scan - reports all drift without changing anything |
|
||||||
|
| `/doc-sync` | Apply all pending documentation updates in one commit |
|
||||||
|
|
||||||
|
## Hooks
|
||||||
|
|
||||||
|
- **PostToolUse (Write\|Edit)**: Silently checks if code changes affect docs
|
||||||
|
- **Stop**: Reminds you of pending doc updates before session ends
|
||||||
|
|
||||||
|
## What It Detects
|
||||||
|
|
||||||
|
- **Broken References**: Function/class renamed but docs still use old name
|
||||||
|
- **Version Drift**: Python 3.9 in docs but 3.11 in pyproject.toml
|
||||||
|
- **Missing Docs**: Public functions without docstrings
|
||||||
|
- **Stale Examples**: CLI examples that no longer work
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
This plugin is part of the claude-code-marketplace.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/plugin marketplace add https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git
|
||||||
|
/plugin install doc-guardian
|
||||||
|
```
|
||||||
|
|
||||||
|
## Integration
|
||||||
|
|
||||||
|
See claude-md-integration.md for CLAUDE.md additions.
|
||||||
41
plugins/doc-guardian/agents/doc-analyzer.md
Normal file
41
plugins/doc-guardian/agents/doc-analyzer.md
Normal file
@@ -0,0 +1,41 @@
|
|||||||
|
---
|
||||||
|
description: Specialized agent for documentation analysis and drift detection
|
||||||
|
---
|
||||||
|
|
||||||
|
# Documentation Analyzer Agent
|
||||||
|
|
||||||
|
You are an expert technical writer and documentation analyst. Your role is to detect discrepancies between code and documentation.
|
||||||
|
|
||||||
|
## Capabilities
|
||||||
|
|
||||||
|
1. **Pattern Recognition**
|
||||||
|
- Identify documentation references to code elements
|
||||||
|
- Parse docstrings, markdown, and inline comments
|
||||||
|
- Understand common documentation structures (README, API docs, man pages)
|
||||||
|
|
||||||
|
2. **Cross-Reference Analysis**
|
||||||
|
- Map documentation claims to actual code
|
||||||
|
- Detect renamed, moved, or deleted code still referenced in docs
|
||||||
|
- Identify undocumented public interfaces
|
||||||
|
|
||||||
|
3. **Semantic Understanding**
|
||||||
|
- Recognize when documentation meaning is correct but wording is outdated
|
||||||
|
- Distinguish between cosmetic issues and functional inaccuracies
|
||||||
|
- Prioritize user-facing documentation over internal notes
|
||||||
|
|
||||||
|
## Analysis Approach
|
||||||
|
|
||||||
|
When analyzing drift:
|
||||||
|
1. Parse the changed file to understand what was modified
|
||||||
|
2. Search for documentation files that might reference the changed code
|
||||||
|
3. Extract specific references (function names, class names, config keys)
|
||||||
|
4. Verify each reference against current code state
|
||||||
|
5. Categorize findings by severity (broken, stale, missing)
|
||||||
|
|
||||||
|
## Output Style
|
||||||
|
|
||||||
|
Be precise and actionable:
|
||||||
|
- Quote the exact line in documentation
|
||||||
|
- Show the exact discrepancy
|
||||||
|
- Suggest the specific fix
|
||||||
|
- Never report vague or uncertain findings
|
||||||
22
plugins/doc-guardian/claude-md-integration.md
Normal file
22
plugins/doc-guardian/claude-md-integration.md
Normal file
@@ -0,0 +1,22 @@
|
|||||||
|
# Doc Guardian Integration
|
||||||
|
|
||||||
|
Add to your project's CLAUDE.md:
|
||||||
|
|
||||||
|
## Documentation Management
|
||||||
|
|
||||||
|
This project uses doc-guardian for automatic documentation synchronization.
|
||||||
|
|
||||||
|
### Behavior
|
||||||
|
- Documentation drift is detected automatically when files change
|
||||||
|
- Pending updates are queued silently during work
|
||||||
|
- Run `/doc-sync` to apply all pending documentation updates
|
||||||
|
- Run `/doc-audit` for a full project documentation review
|
||||||
|
|
||||||
|
### Documentation Files Tracked
|
||||||
|
- README.md (root and subdirectories)
|
||||||
|
- CLAUDE.md
|
||||||
|
- API documentation in docs/
|
||||||
|
- Docstrings in Python/TypeScript files
|
||||||
|
|
||||||
|
### Commit Convention
|
||||||
|
Documentation sync commits use: `docs: sync documentation with code changes`
|
||||||
50
plugins/doc-guardian/commands/doc-audit.md
Normal file
50
plugins/doc-guardian/commands/doc-audit.md
Normal file
@@ -0,0 +1,50 @@
|
|||||||
|
---
|
||||||
|
description: Full documentation audit - scans entire project for doc drift without making changes
|
||||||
|
---
|
||||||
|
|
||||||
|
# Documentation Audit
|
||||||
|
|
||||||
|
Perform a comprehensive documentation drift analysis.
|
||||||
|
|
||||||
|
## Process
|
||||||
|
|
||||||
|
1. **Inventory Documentation Files**
|
||||||
|
- README.md (root and subdirectories)
|
||||||
|
- CLAUDE.md
|
||||||
|
- API documentation
|
||||||
|
- Docstrings in code files
|
||||||
|
- Configuration references
|
||||||
|
|
||||||
|
2. **Cross-Reference Analysis**
|
||||||
|
For each documentation file:
|
||||||
|
- Extract referenced functions, classes, endpoints, configs
|
||||||
|
- Verify each reference exists in codebase
|
||||||
|
- Check signatures/types match documentation
|
||||||
|
- Flag deprecated or renamed items still in docs
|
||||||
|
|
||||||
|
3. **Completeness Check**
|
||||||
|
- Public functions without docstrings
|
||||||
|
- Exported modules without README coverage
|
||||||
|
- Environment variables used but not documented
|
||||||
|
- CLI commands not in help text
|
||||||
|
|
||||||
|
4. **Output Format**
|
||||||
|
```
|
||||||
|
## Documentation Drift Report
|
||||||
|
|
||||||
|
### Critical (Broken References)
|
||||||
|
- [ ] README.md:45 references `calculate_total()` - function renamed to `compute_total()`
|
||||||
|
|
||||||
|
### Stale (Outdated Info)
|
||||||
|
- [ ] CLAUDE.md:23 lists Python 3.9 - project uses 3.11
|
||||||
|
|
||||||
|
### Missing (Undocumented)
|
||||||
|
- [ ] api/handlers.py:`create_order()` - no docstring
|
||||||
|
|
||||||
|
### Summary
|
||||||
|
- Critical: X items
|
||||||
|
- Stale: X items
|
||||||
|
- Missing: X items
|
||||||
|
```
|
||||||
|
|
||||||
|
5. **Do NOT make changes** - audit only, report findings
|
||||||
58
plugins/doc-guardian/commands/doc-sync.md
Normal file
58
plugins/doc-guardian/commands/doc-sync.md
Normal file
@@ -0,0 +1,58 @@
|
|||||||
|
---
|
||||||
|
description: Synchronize all pending documentation updates in a single commit
|
||||||
|
---
|
||||||
|
|
||||||
|
# Documentation Sync
|
||||||
|
|
||||||
|
Apply all pending documentation updates detected by doc-guardian hooks.
|
||||||
|
|
||||||
|
## Process
|
||||||
|
|
||||||
|
1. **Review Pending Queue**
|
||||||
|
List all documentation drift detected during this session.
|
||||||
|
|
||||||
|
2. **Batch Updates**
|
||||||
|
For each pending item:
|
||||||
|
- Show the specific change needed
|
||||||
|
- Apply the update
|
||||||
|
- Track in change list
|
||||||
|
|
||||||
|
3. **Update Types**
|
||||||
|
|
||||||
|
**Reference Fixes:**
|
||||||
|
- Renamed function/class → update all doc references
|
||||||
|
- Changed signature → update parameter documentation
|
||||||
|
- Removed item → remove or mark deprecated in docs
|
||||||
|
|
||||||
|
**Content Sync:**
|
||||||
|
- Version numbers (Python, Node, dependencies)
|
||||||
|
- Configuration keys/values
|
||||||
|
- File paths and directory structures
|
||||||
|
- Command examples and outputs
|
||||||
|
|
||||||
|
**Structural:**
|
||||||
|
- Add missing sections for new features
|
||||||
|
- Remove sections for deleted features
|
||||||
|
- Reorder to match current code organization
|
||||||
|
|
||||||
|
4. **Commit Strategy**
|
||||||
|
- Stage all doc changes together
|
||||||
|
- Single commit: `docs: sync documentation with code changes`
|
||||||
|
- Include summary of what was updated in commit body
|
||||||
|
|
||||||
|
5. **Output**
|
||||||
|
```
|
||||||
|
## Documentation Sync Complete
|
||||||
|
|
||||||
|
### Files Updated
|
||||||
|
- README.md (3 changes)
|
||||||
|
- CLAUDE.md (1 change)
|
||||||
|
- src/api/README.md (2 changes)
|
||||||
|
|
||||||
|
### Changes Applied
|
||||||
|
- Updated function reference: calculate_total → compute_total
|
||||||
|
- Updated Python version: 3.9 → 3.11
|
||||||
|
- Added docstring to create_order()
|
||||||
|
|
||||||
|
Committed: abc123f
|
||||||
|
```
|
||||||
26
plugins/doc-guardian/hooks/hooks.json
Normal file
26
plugins/doc-guardian/hooks/hooks.json
Normal file
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"hooks": {
|
||||||
|
"PostToolUse": [
|
||||||
|
{
|
||||||
|
"matcher": "Write|Edit|MultiEdit",
|
||||||
|
"hooks": [
|
||||||
|
{
|
||||||
|
"type": "prompt",
|
||||||
|
"prompt": "A file was just modified. Silently check if this change affects any documentation:\n\n1. If a code file changed: check if README, CLAUDE.md, docstrings, or API docs reference the modified functions/classes/configs\n2. If drift detected: add to internal queue (do NOT interrupt user flow)\n3. At natural breakpoints or when user runs /doc-sync: report pending doc updates\n\nDo NOT announce this check unless drift is found. Work silently."
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"Stop": [
|
||||||
|
{
|
||||||
|
"matcher": ".*",
|
||||||
|
"hooks": [
|
||||||
|
{
|
||||||
|
"type": "prompt",
|
||||||
|
"prompt": "Before ending, check if there are pending documentation updates queued by doc-guardian. If yes, ask user: 'I detected documentation drift in X files. Run /doc-sync to update, or skip for now?'"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
39
plugins/doc-guardian/skills/doc-patterns/SKILL.md
Normal file
39
plugins/doc-guardian/skills/doc-patterns/SKILL.md
Normal file
@@ -0,0 +1,39 @@
|
|||||||
|
---
|
||||||
|
description: Knowledge of documentation patterns and structures for drift detection
|
||||||
|
---
|
||||||
|
|
||||||
|
# Documentation Patterns Skill
|
||||||
|
|
||||||
|
## Common Documentation Structures
|
||||||
|
|
||||||
|
### README.md Patterns
|
||||||
|
- Installation section: version requirements, dependencies
|
||||||
|
- Usage section: function calls, CLI commands
|
||||||
|
- Configuration section: env vars, config files
|
||||||
|
- API section: endpoint references
|
||||||
|
|
||||||
|
### CLAUDE.md Patterns
|
||||||
|
- Project context: tech stack versions
|
||||||
|
- File structure: directory layout
|
||||||
|
- Commands: available operations
|
||||||
|
- Workflows: process descriptions
|
||||||
|
|
||||||
|
### Code Documentation
|
||||||
|
- Docstrings: function signatures, parameters, returns
|
||||||
|
- Type hints: should match docstring types
|
||||||
|
- Comments: inline references to other code
|
||||||
|
|
||||||
|
## Drift Detection Rules
|
||||||
|
|
||||||
|
1. **Version Mismatch**: Any hardcoded version in docs must match package.json, pyproject.toml, requirements.txt
|
||||||
|
2. **Function References**: Function names in docs must exist in codebase with matching signatures
|
||||||
|
3. **Path References**: File paths in docs must exist in current directory structure
|
||||||
|
4. **Config Keys**: Environment variables and config keys in docs must be used in code
|
||||||
|
5. **Command Examples**: CLI examples in docs should be valid commands
|
||||||
|
|
||||||
|
## Priority Levels
|
||||||
|
|
||||||
|
- **P0 (Critical)**: Broken references that would cause user errors
|
||||||
|
- **P1 (High)**: Outdated information that misleads users
|
||||||
|
- **P2 (Medium)**: Missing documentation for public interfaces
|
||||||
|
- **P3 (Low)**: Style inconsistencies, minor wording issues
|
||||||
@@ -3,12 +3,19 @@
|
|||||||
"version": "0.1.0",
|
"version": "0.1.0",
|
||||||
"description": "Post-task cleanup hook that removes temp files, warns about unexpected root files, and manages orphaned supporting files",
|
"description": "Post-task cleanup hook that removes temp files, warns about unexpected root files, and manages orphaned supporting files",
|
||||||
"author": {
|
"author": {
|
||||||
"name": "Bandit Labs",
|
"name": "Leo Miranda",
|
||||||
"email": "dev@banditlabs.io"
|
"email": "leobmiranda@gmail.com"
|
||||||
},
|
},
|
||||||
|
"homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/project-hygiene/README.md",
|
||||||
|
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
|
||||||
"license": "MIT",
|
"license": "MIT",
|
||||||
"keywords": ["cleanup", "hygiene", "automation", "hooks", "maintenance"],
|
"keywords": [
|
||||||
"repository": "https://github.com/bandit-labs/project-hygiene",
|
"cleanup",
|
||||||
|
"hygiene",
|
||||||
|
"automation",
|
||||||
|
"hooks",
|
||||||
|
"maintenance"
|
||||||
|
],
|
||||||
"hooks": {
|
"hooks": {
|
||||||
"PostToolUse": [
|
"PostToolUse": [
|
||||||
{
|
{
|
||||||
|
|||||||
36
plugins/project-hygiene/claude-md-integration.md
Normal file
36
plugins/project-hygiene/claude-md-integration.md
Normal file
@@ -0,0 +1,36 @@
|
|||||||
|
## Project Cleanup (project-hygiene)
|
||||||
|
|
||||||
|
This project uses the **project-hygiene** plugin for automated post-task cleanup.
|
||||||
|
|
||||||
|
### How It Works
|
||||||
|
|
||||||
|
The plugin automatically runs after file Write or Edit operations to:
|
||||||
|
|
||||||
|
1. **Delete temporary files** - Removes `*.tmp`, `*.bak`, `__pycache__/`, `.pytest_cache/`, etc.
|
||||||
|
2. **Warn about unexpected root files** - Alerts when files are created outside expected locations
|
||||||
|
3. **Identify orphaned files** - Detects supporting files that may no longer be needed
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
The plugin can be configured via `.hygiene.json` in the project root:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"temp_patterns": ["*.tmp", "*.bak", "*.swp"],
|
||||||
|
"ignore_dirs": ["node_modules", ".git", ".venv"],
|
||||||
|
"allowed_root_files": ["CLAUDE.md", "README.md", "LICENSE"],
|
||||||
|
"warn_on_root_files": true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Hook Events
|
||||||
|
|
||||||
|
The plugin registers on the following events:
|
||||||
|
- `PostToolUse` (matcher: `Write|Edit`) - Runs cleanup after file modifications
|
||||||
|
|
||||||
|
### Usage Guidelines
|
||||||
|
|
||||||
|
- Let the hook run automatically - no manual intervention needed
|
||||||
|
- Review warnings about unexpected root files
|
||||||
|
- Configure `.hygiene.json` to customize cleanup behavior for your project
|
||||||
|
- Check cleanup output if files seem to disappear unexpectedly
|
||||||
@@ -1,18 +1,21 @@
|
|||||||
{
|
{
|
||||||
"name": "projman",
|
"name": "projman",
|
||||||
"version": "2.0.0",
|
"version": "2.3.0",
|
||||||
"description": "Sprint planning and project management with Gitea integration",
|
"description": "Sprint planning and project management with Gitea integration",
|
||||||
"author": {
|
"author": {
|
||||||
"name": "Bandit Labs",
|
"name": "Leo Miranda",
|
||||||
"email": "dev@banditlabs.io"
|
"email": "leobmiranda@gmail.com"
|
||||||
},
|
},
|
||||||
|
"homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/projman/README.md",
|
||||||
|
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
|
||||||
"license": "MIT",
|
"license": "MIT",
|
||||||
"repository": "https://gitea.hotserv.cloud/bandit/support-claude-mktplace",
|
|
||||||
"keywords": [
|
"keywords": [
|
||||||
"project-management",
|
"project-management",
|
||||||
"sprint-planning",
|
"sprint-planning",
|
||||||
"gitea",
|
"gitea",
|
||||||
"agile",
|
"agile",
|
||||||
"lessons-learned"
|
"lessons-learned"
|
||||||
]
|
],
|
||||||
|
"commands": ["./commands/"],
|
||||||
|
"agents": ["./agents/"]
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,4 +1,4 @@
|
|||||||
# Configuration Guide - Projman Plugin v2.0.0
|
# Configuration Guide - Projman Plugin
|
||||||
|
|
||||||
Complete setup and configuration instructions for the Projman project management plugin.
|
Complete setup and configuration instructions for the Projman project management plugin.
|
||||||
|
|
||||||
|
|||||||
@@ -1,4 +1,4 @@
|
|||||||
# Projman v2.0.0 - Project Management for Claude Code
|
# Projman - Project Management for Claude Code
|
||||||
|
|
||||||
Sprint planning and project management plugin with full Gitea integration.
|
Sprint planning and project management plugin with full Gitea integration.
|
||||||
|
|
||||||
@@ -174,6 +174,62 @@ Run initial setup for a new project.
|
|||||||
|
|
||||||
**When to use:** First time setting up projman for a project
|
**When to use:** First time setting up projman for a project
|
||||||
|
|
||||||
|
### `/review`
|
||||||
|
Pre-sprint-close code quality review.
|
||||||
|
|
||||||
|
**What it does:**
|
||||||
|
- Scans recent changes for debug artifacts (TODO, console.log, commented code)
|
||||||
|
- Checks for code complexity issues (long functions, deep nesting)
|
||||||
|
- Performs lightweight security scan (hardcoded secrets, SQL injection risks)
|
||||||
|
- Identifies error handling gaps (bare except, swallowed exceptions)
|
||||||
|
|
||||||
|
**Output format:**
|
||||||
|
- Critical Issues (Block Sprint Close)
|
||||||
|
- Warnings (Should Address)
|
||||||
|
- Recommendations (Nice to Have)
|
||||||
|
|
||||||
|
**When to use:** Before closing a sprint to ensure code quality
|
||||||
|
|
||||||
|
### `/test-check`
|
||||||
|
Test verification before sprint close.
|
||||||
|
|
||||||
|
**What it does:**
|
||||||
|
- Automatically detects test framework (pytest, Jest, Go test, Cargo, etc.)
|
||||||
|
- Runs the test suite
|
||||||
|
- Reports pass/fail summary with details on failures
|
||||||
|
- Includes coverage report when available
|
||||||
|
- Identifies sprint files lacking test coverage
|
||||||
|
|
||||||
|
**Flags:**
|
||||||
|
- "run tests with coverage" - Include coverage report
|
||||||
|
- "run tests verbose" - Show full output
|
||||||
|
- "just check, don't run" - Report framework detection only
|
||||||
|
|
||||||
|
**When to use:** Before closing a sprint to ensure tests pass
|
||||||
|
|
||||||
|
### `/test-gen`
|
||||||
|
Generate tests for specified code.
|
||||||
|
|
||||||
|
**What it does:**
|
||||||
|
- Analyzes target code (function, class, or module)
|
||||||
|
- Auto-detects test framework (pytest, Jest, vitest, Go test, Cargo, etc.)
|
||||||
|
- Generates comprehensive tests: happy path, edge cases, error cases
|
||||||
|
- Supports unit, integration, e2e, and snapshot test types
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
```
|
||||||
|
/test-gen <target> [--type=<type>] [--framework=<framework>]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Target:** File path, function name, class name, or module
|
||||||
|
**Type:** unit (default), integration, e2e, snapshot
|
||||||
|
|
||||||
|
**When to use:** When adding new code that needs test coverage
|
||||||
|
|
||||||
|
## Code Quality Commands
|
||||||
|
|
||||||
|
The `/review` and `/test-check` commands complement the Executor agent by catching issues before work is marked complete. Run both commands before `/sprint-close` for a complete quality check.
|
||||||
|
|
||||||
## Agents
|
## Agents
|
||||||
|
|
||||||
### Planner Agent
|
### Planner Agent
|
||||||
@@ -203,6 +259,17 @@ Run initial setup for a new project.
|
|||||||
|
|
||||||
**Invoked by:** `/sprint-start`, `/sprint-close`
|
**Invoked by:** `/sprint-start`, `/sprint-close`
|
||||||
|
|
||||||
|
### Code Reviewer Agent
|
||||||
|
**Personality:** Thorough, practical, severity-focused
|
||||||
|
|
||||||
|
**Responsibilities:**
|
||||||
|
- Identifying code quality issues before sprint close
|
||||||
|
- Prioritizing findings (Critical > Warning > Recommendation)
|
||||||
|
- Providing actionable feedback with file:line references
|
||||||
|
- Respecting sprint scope (only reviewing changed files)
|
||||||
|
|
||||||
|
**Invoked by:** `/review`
|
||||||
|
|
||||||
### Executor Agent
|
### Executor Agent
|
||||||
**Personality:** Implementation-focused, follows specs precisely
|
**Personality:** Implementation-focused, follows specs precisely
|
||||||
|
|
||||||
@@ -373,11 +440,15 @@ projman/
|
|||||||
│ ├── sprint-status.md
|
│ ├── sprint-status.md
|
||||||
│ ├── sprint-close.md
|
│ ├── sprint-close.md
|
||||||
│ ├── labels-sync.md
|
│ ├── labels-sync.md
|
||||||
│ └── initial-setup.md
|
│ ├── initial-setup.md
|
||||||
|
│ ├── review.md
|
||||||
|
│ ├── test-check.md
|
||||||
|
│ └── test-gen.md
|
||||||
├── agents/ # Agent prompts
|
├── agents/ # Agent prompts
|
||||||
│ ├── planner.md
|
│ ├── planner.md
|
||||||
│ ├── orchestrator.md
|
│ ├── orchestrator.md
|
||||||
│ └── executor.md
|
│ ├── executor.md
|
||||||
|
│ └── code-reviewer.md
|
||||||
├── skills/ # Supporting knowledge
|
├── skills/ # Supporting knowledge
|
||||||
│ └── label-taxonomy/
|
│ └── label-taxonomy/
|
||||||
│ └── labels-reference.md
|
│ └── labels-reference.md
|
||||||
@@ -428,15 +499,6 @@ See [CONFIGURATION.md](./CONFIGURATION.md) for detailed configuration instructio
|
|||||||
|
|
||||||
MIT License - See repository root for details
|
MIT License - See repository root for details
|
||||||
|
|
||||||
## Version
|
|
||||||
|
|
||||||
**Current:** 2.0.0
|
|
||||||
|
|
||||||
**Changelog:**
|
|
||||||
- v2.0.0: Full Gitea integration with wiki, milestones, dependencies, parallel execution
|
|
||||||
- v1.0.0: Initial release with basic commands
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Built for:** Bandit Labs
|
|
||||||
**Status:** Production Ready
|
**Status:** Production Ready
|
||||||
|
|||||||
90
plugins/projman/agents/code-reviewer.md
Normal file
90
plugins/projman/agents/code-reviewer.md
Normal file
@@ -0,0 +1,90 @@
|
|||||||
|
---
|
||||||
|
name: code-reviewer
|
||||||
|
description: Specialized agent for pre-sprint code quality review
|
||||||
|
---
|
||||||
|
|
||||||
|
# Code Reviewer Agent
|
||||||
|
|
||||||
|
You are a code quality reviewer focused on catching issues before sprint close.
|
||||||
|
|
||||||
|
## Your Role
|
||||||
|
|
||||||
|
- Identify issues that should be fixed before work is marked complete
|
||||||
|
- Prioritize findings by severity (Critical > Warning > Recommendation)
|
||||||
|
- Be concise—developers need actionable feedback, not lectures
|
||||||
|
- Respect sprint scope—don't expand review beyond changed files
|
||||||
|
|
||||||
|
## Review Philosophy
|
||||||
|
|
||||||
|
**Critical**: Security issues, broken functionality, data loss risks
|
||||||
|
- Hardcoded credentials or API keys
|
||||||
|
- SQL injection vulnerabilities
|
||||||
|
- Missing authentication/authorization checks
|
||||||
|
- Unhandled errors that could crash the application
|
||||||
|
|
||||||
|
**Warning**: Technical debt that will cause problems soon
|
||||||
|
- TODO/FIXME comments left unresolved
|
||||||
|
- Debug statements (console.log, print) in production code
|
||||||
|
- Functions over 50 lines (complexity smell)
|
||||||
|
- Deeply nested conditionals (>3 levels)
|
||||||
|
- Bare except/catch blocks
|
||||||
|
|
||||||
|
**Recommendation**: Improvements that can wait for a future sprint
|
||||||
|
- Missing docstrings on public functions
|
||||||
|
- Minor code duplication
|
||||||
|
- Commented-out code blocks
|
||||||
|
|
||||||
|
## What You Don't Do
|
||||||
|
|
||||||
|
- Bikeshed on style (assume formatters handle this)
|
||||||
|
- Suggest architectural rewrites mid-sprint
|
||||||
|
- Flag issues in unchanged code (unless directly impacted)
|
||||||
|
- Automatically fix code without explicit approval
|
||||||
|
|
||||||
|
## Integration with Projman
|
||||||
|
|
||||||
|
When sprint context is available, you can:
|
||||||
|
- Reference the sprint's issue list
|
||||||
|
- Create follow-up issues for non-critical findings via Gitea MCP
|
||||||
|
- Tag findings with appropriate labels from the 43-label taxonomy
|
||||||
|
|
||||||
|
## Review Patterns by Language
|
||||||
|
|
||||||
|
### Python
|
||||||
|
- Look for: bare `except:`, `print()` statements, `# TODO`, missing type hints on public APIs
|
||||||
|
- Security: `eval()`, `exec()`, SQL string formatting, `verify=False`
|
||||||
|
|
||||||
|
### JavaScript/TypeScript
|
||||||
|
- Look for: `console.log`, `// TODO`, `any` type abuse, missing error boundaries
|
||||||
|
- Security: `eval()`, `innerHTML`, unescaped user input
|
||||||
|
|
||||||
|
### Go
|
||||||
|
- Look for: `// TODO`, ignored errors (`_`), missing error returns
|
||||||
|
- Security: SQL concatenation, missing input validation
|
||||||
|
|
||||||
|
### Rust
|
||||||
|
- Look for: `// TODO`, `unwrap()` chains, `unsafe` blocks without justification
|
||||||
|
- Security: unchecked `unwrap()` on user input
|
||||||
|
|
||||||
|
## Output Template
|
||||||
|
|
||||||
|
```
|
||||||
|
## Code Review Summary
|
||||||
|
|
||||||
|
**Scope**: [X files from sprint/last N commits]
|
||||||
|
**Verdict**: [READY FOR CLOSE / NEEDS ATTENTION / BLOCKED]
|
||||||
|
|
||||||
|
### Critical (Must Fix)
|
||||||
|
- `src/auth.py:45` - Hardcoded API key in source code
|
||||||
|
|
||||||
|
### Warnings (Should Fix)
|
||||||
|
- `src/utils.js:123` - console.log left in production code
|
||||||
|
- `src/handler.py:67` - Bare except block swallows all errors
|
||||||
|
|
||||||
|
### Recommendations (Future Sprint)
|
||||||
|
- `src/api.ts:89` - Function exceeds 50 lines, consider splitting
|
||||||
|
|
||||||
|
### Clean Files
|
||||||
|
- src/models.py
|
||||||
|
- src/tests/test_auth.py
|
||||||
|
```
|
||||||
56
plugins/projman/claude-md-integration.md
Normal file
56
plugins/projman/claude-md-integration.md
Normal file
@@ -0,0 +1,56 @@
|
|||||||
|
## Sprint Management (projman)
|
||||||
|
|
||||||
|
This project uses the **projman** plugin for sprint planning and project management with Gitea integration.
|
||||||
|
|
||||||
|
### Available Commands
|
||||||
|
|
||||||
|
| Command | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `/sprint-plan` | Start sprint planning with AI-guided architecture analysis |
|
||||||
|
| `/sprint-start` | Begin sprint execution with relevant lessons learned |
|
||||||
|
| `/sprint-status` | Check current sprint progress and identify blockers |
|
||||||
|
| `/sprint-close` | Complete sprint and capture lessons learned to Gitea Wiki |
|
||||||
|
| `/labels-sync` | Synchronize label taxonomy from Gitea |
|
||||||
|
| `/initial-setup` | Run initial setup for projman plugin |
|
||||||
|
|
||||||
|
### MCP Tools Available
|
||||||
|
|
||||||
|
The following Gitea MCP tools are available for issue and project management:
|
||||||
|
|
||||||
|
**Issue Management:**
|
||||||
|
- `list_issues` - Query issues with filters (state, labels)
|
||||||
|
- `get_issue` - Fetch single issue details
|
||||||
|
- `create_issue` - Create new issue with labels
|
||||||
|
- `update_issue` - Modify existing issue
|
||||||
|
- `add_comment` - Add comments to issues
|
||||||
|
|
||||||
|
**Labels:**
|
||||||
|
- `get_labels` - Fetch org + repo label taxonomy
|
||||||
|
- `suggest_labels` - Analyze context and suggest appropriate labels
|
||||||
|
- `create_label` - Create missing required labels
|
||||||
|
|
||||||
|
**Milestones:**
|
||||||
|
- `list_milestones` - List sprint milestones
|
||||||
|
- `get_milestone` - Get milestone details
|
||||||
|
- `create_milestone` - Create sprint milestone
|
||||||
|
- `update_milestone` - Update/close milestone
|
||||||
|
|
||||||
|
**Dependencies:**
|
||||||
|
- `list_issue_dependencies` - Get issue dependencies
|
||||||
|
- `create_issue_dependency` - Create dependency between issues
|
||||||
|
- `get_execution_order` - Get parallel execution batches
|
||||||
|
|
||||||
|
**Wiki (Lessons Learned):**
|
||||||
|
- `list_wiki_pages` - List wiki pages
|
||||||
|
- `get_wiki_page` - Fetch specific page content
|
||||||
|
- `create_wiki_page` - Create new wiki page
|
||||||
|
- `create_lesson` - Create lessons learned document
|
||||||
|
- `search_lessons` - Search past lessons by tags
|
||||||
|
|
||||||
|
### Usage Guidelines
|
||||||
|
|
||||||
|
- **Always use `/sprint-plan`** when starting new development work
|
||||||
|
- **Check `/sprint-status`** regularly during active sprints
|
||||||
|
- **Run `/sprint-close`** at the end of each sprint to capture lessons learned
|
||||||
|
- Use `suggest_labels` when creating issues to ensure proper categorization
|
||||||
|
- Search lessons learned with `search_lessons` before implementing features to avoid repeated mistakes
|
||||||
82
plugins/projman/commands/review.md
Normal file
82
plugins/projman/commands/review.md
Normal file
@@ -0,0 +1,82 @@
|
|||||||
|
---
|
||||||
|
name: review
|
||||||
|
description: Pre-sprint-close code quality review
|
||||||
|
---
|
||||||
|
|
||||||
|
# Code Review for Sprint Close
|
||||||
|
|
||||||
|
Review the recent code changes for quality issues before closing the sprint.
|
||||||
|
|
||||||
|
## Review Checklist
|
||||||
|
|
||||||
|
Analyze the changes and report on:
|
||||||
|
|
||||||
|
### 1. Debug Artifacts
|
||||||
|
- [ ] TODO/FIXME comments that should be resolved or converted to issues
|
||||||
|
- [ ] Console.log, print(), debug statements left in code
|
||||||
|
- [ ] Commented-out code blocks
|
||||||
|
|
||||||
|
### 2. Code Quality
|
||||||
|
- [ ] Functions exceeding 50 lines (complexity smell)
|
||||||
|
- [ ] Deeply nested conditionals (>3 levels)
|
||||||
|
- [ ] Duplicate code patterns
|
||||||
|
- [ ] Missing docstrings/comments on public functions
|
||||||
|
|
||||||
|
### 3. Security Scan (Lightweight)
|
||||||
|
- [ ] Hardcoded strings that look like secrets (API keys, passwords, tokens)
|
||||||
|
- [ ] SQL strings with concatenation (injection risk)
|
||||||
|
- [ ] Disabled SSL verification
|
||||||
|
- [ ] Overly permissive file permissions in code
|
||||||
|
|
||||||
|
### 4. Error Handling
|
||||||
|
- [ ] Bare except/catch blocks
|
||||||
|
- [ ] Swallowed exceptions (catch with pass/empty block)
|
||||||
|
- [ ] Missing null/undefined checks on external data
|
||||||
|
|
||||||
|
## Output Format
|
||||||
|
|
||||||
|
Provide a structured report:
|
||||||
|
|
||||||
|
```
|
||||||
|
## Sprint Review Summary
|
||||||
|
|
||||||
|
### Critical Issues (Block Sprint Close)
|
||||||
|
- [file:line] Description
|
||||||
|
|
||||||
|
### Warnings (Should Address)
|
||||||
|
- [file:line] Description
|
||||||
|
|
||||||
|
### Recommendations (Nice to Have)
|
||||||
|
- [file:line] Description
|
||||||
|
|
||||||
|
### Clean Files
|
||||||
|
- List of files with no issues found
|
||||||
|
```
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
If sprint context is available from projman, limit review to files touched in current sprint.
|
||||||
|
Otherwise, review staged changes or changes in the last 5 commits.
|
||||||
|
|
||||||
|
## How to Determine Scope
|
||||||
|
|
||||||
|
1. **Check for sprint context**: Look for `.projman/current-sprint.json` or similar
|
||||||
|
2. **Fall back to git changes**: Use `git diff --name-only HEAD~5` or staged files
|
||||||
|
3. **Filter by file type**: Focus on code files (.py, .js, .ts, .go, .rs, etc.)
|
||||||
|
|
||||||
|
## Execution Steps
|
||||||
|
|
||||||
|
1. Determine scope (sprint files or recent commits)
|
||||||
|
2. For each file in scope:
|
||||||
|
- Read the file content
|
||||||
|
- Scan for patterns in each category
|
||||||
|
- Record findings with file:line references
|
||||||
|
3. Compile findings into the structured report
|
||||||
|
4. Provide recommendation: READY / NEEDS ATTENTION / BLOCK
|
||||||
|
|
||||||
|
## Do NOT
|
||||||
|
|
||||||
|
- Rewrite or refactor code automatically
|
||||||
|
- Make changes without explicit approval
|
||||||
|
- Review files outside the sprint/change scope
|
||||||
|
- Spend excessive time on style issues (assume formatters handle this)
|
||||||
163
plugins/projman/commands/test-check.md
Normal file
163
plugins/projman/commands/test-check.md
Normal file
@@ -0,0 +1,163 @@
|
|||||||
|
---
|
||||||
|
name: test-check
|
||||||
|
description: Run tests and verify coverage before sprint close
|
||||||
|
---
|
||||||
|
|
||||||
|
# Test Check for Sprint Close
|
||||||
|
|
||||||
|
Verify test status and coverage before closing the sprint.
|
||||||
|
|
||||||
|
## Framework Detection
|
||||||
|
|
||||||
|
Detect the test framework by checking for:
|
||||||
|
|
||||||
|
| Indicator | Framework | Command |
|
||||||
|
|-----------|-----------|---------|
|
||||||
|
| `pytest.ini`, `pyproject.toml` with pytest, `tests/` with `test_*.py` | pytest | `pytest` |
|
||||||
|
| `package.json` with jest | Jest | `npm test` or `npx jest` |
|
||||||
|
| `package.json` with mocha | Mocha | `npm test` or `npx mocha` |
|
||||||
|
| `package.json` with vitest | Vitest | `npm test` or `npx vitest` |
|
||||||
|
| `go.mod` with `*_test.go` files | Go test | `go test ./...` |
|
||||||
|
| `Cargo.toml` with `tests/` or `#[test]` | Cargo test | `cargo test` |
|
||||||
|
| `Makefile` with test target | Make | `make test` |
|
||||||
|
| `tox.ini` | tox | `tox` |
|
||||||
|
| `setup.py` with test command | setuptools | `python setup.py test` |
|
||||||
|
|
||||||
|
## Execution Steps
|
||||||
|
|
||||||
|
### 1. Detect Framework
|
||||||
|
|
||||||
|
1. Check for framework indicators in project root
|
||||||
|
2. If multiple found, list them and ask which to run
|
||||||
|
3. If none found, report "No test framework detected"
|
||||||
|
|
||||||
|
### 2. Run Tests
|
||||||
|
|
||||||
|
1. Execute the appropriate test command
|
||||||
|
2. Capture stdout/stderr
|
||||||
|
3. Parse results for pass/fail counts
|
||||||
|
4. Note: Some frameworks may require dependencies to be installed first
|
||||||
|
|
||||||
|
### 3. Coverage Check (if available)
|
||||||
|
|
||||||
|
Coverage tools by framework:
|
||||||
|
- **Python**: `pytest --cov` or `coverage run`
|
||||||
|
- **JavaScript**: Jest has built-in coverage (`--coverage`)
|
||||||
|
- **Go**: `go test -cover`
|
||||||
|
- **Rust**: `cargo tarpaulin` or `cargo llvm-cov`
|
||||||
|
|
||||||
|
If coverage is configured:
|
||||||
|
- Report overall coverage percentage
|
||||||
|
- List files with 0% coverage that were changed in sprint
|
||||||
|
|
||||||
|
### 4. Sprint File Analysis
|
||||||
|
|
||||||
|
If sprint context is available:
|
||||||
|
- Identify which sprint files have tests
|
||||||
|
- Flag sprint files with no corresponding test coverage
|
||||||
|
|
||||||
|
## Output Format
|
||||||
|
|
||||||
|
```
|
||||||
|
## Test Check Summary
|
||||||
|
|
||||||
|
### Test Results
|
||||||
|
- Framework: {detected framework}
|
||||||
|
- Status: {PASS/FAIL}
|
||||||
|
- Passed: {n} | Failed: {n} | Skipped: {n}
|
||||||
|
- Duration: {time}
|
||||||
|
|
||||||
|
### Failed Tests
|
||||||
|
- test_name: error message (file:line)
|
||||||
|
|
||||||
|
### Coverage (if available)
|
||||||
|
- Overall: {n}%
|
||||||
|
- Sprint files coverage:
|
||||||
|
- file.py: {n}%
|
||||||
|
- file.py: NO TESTS
|
||||||
|
|
||||||
|
### Recommendation
|
||||||
|
{READY FOR CLOSE / TESTS MUST PASS / COVERAGE GAPS TO ADDRESS}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Behavior Flags
|
||||||
|
|
||||||
|
The command accepts optional flags via natural language:
|
||||||
|
|
||||||
|
| Request | Behavior |
|
||||||
|
|---------|----------|
|
||||||
|
| "run tests with coverage" | Include coverage report |
|
||||||
|
| "run tests verbose" | Show full output |
|
||||||
|
| "just check, don't run" | Report framework detection only |
|
||||||
|
| "run specific tests for X" | Run tests matching pattern |
|
||||||
|
|
||||||
|
## Framework-Specific Notes
|
||||||
|
|
||||||
|
### Python (pytest)
|
||||||
|
```bash
|
||||||
|
# Basic run
|
||||||
|
pytest
|
||||||
|
|
||||||
|
# With coverage
|
||||||
|
pytest --cov=src --cov-report=term-missing
|
||||||
|
|
||||||
|
# Verbose
|
||||||
|
pytest -v
|
||||||
|
|
||||||
|
# Specific tests
|
||||||
|
pytest tests/test_specific.py -k "test_function_name"
|
||||||
|
```
|
||||||
|
|
||||||
|
### JavaScript (Jest/Vitest)
|
||||||
|
```bash
|
||||||
|
# Basic run
|
||||||
|
npm test
|
||||||
|
|
||||||
|
# With coverage
|
||||||
|
npm test -- --coverage
|
||||||
|
|
||||||
|
# Specific tests
|
||||||
|
npm test -- --testPathPattern="specific"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Go
|
||||||
|
```bash
|
||||||
|
# Basic run
|
||||||
|
go test ./...
|
||||||
|
|
||||||
|
# With coverage
|
||||||
|
go test -cover ./...
|
||||||
|
|
||||||
|
# Verbose
|
||||||
|
go test -v ./...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Rust
|
||||||
|
```bash
|
||||||
|
# Basic run
|
||||||
|
cargo test
|
||||||
|
|
||||||
|
# Verbose
|
||||||
|
cargo test -- --nocapture
|
||||||
|
```
|
||||||
|
|
||||||
|
## Do NOT
|
||||||
|
|
||||||
|
- Modify test files
|
||||||
|
- Skip failing tests to make the run pass
|
||||||
|
- Run tests in production environments (check for .env indicators)
|
||||||
|
- Install dependencies without asking first
|
||||||
|
- Run tests that require external services without confirmation
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
If tests fail:
|
||||||
|
1. Report the failure clearly
|
||||||
|
2. List failed test names and error summaries
|
||||||
|
3. Recommend: "TESTS MUST PASS before sprint close"
|
||||||
|
4. Offer to help debug specific failures
|
||||||
|
|
||||||
|
If framework not detected:
|
||||||
|
1. List what was checked
|
||||||
|
2. Ask user to specify the test command
|
||||||
|
3. Offer common suggestions based on file types found
|
||||||
118
plugins/projman/commands/test-gen.md
Normal file
118
plugins/projman/commands/test-gen.md
Normal file
@@ -0,0 +1,118 @@
|
|||||||
|
---
|
||||||
|
description: Generate tests for specified code - creates unit, integration, or e2e tests
|
||||||
|
---
|
||||||
|
|
||||||
|
# Test Generation
|
||||||
|
|
||||||
|
Generate comprehensive tests for specified code.
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
```
|
||||||
|
/test-gen <target> [--type=<type>] [--framework=<framework>]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Target:** File path, function name, class name, or module
|
||||||
|
**Type:** unit (default), integration, e2e, snapshot
|
||||||
|
**Framework:** Auto-detected or specify (pytest, jest, vitest, go test, etc.)
|
||||||
|
|
||||||
|
## Process
|
||||||
|
|
||||||
|
1. **Analyze Target Code**
|
||||||
|
- Parse function/class signatures
|
||||||
|
- Identify dependencies and side effects
|
||||||
|
- Map input types and return types
|
||||||
|
- Find edge cases from logic branches
|
||||||
|
|
||||||
|
2. **Determine Test Strategy**
|
||||||
|
|
||||||
|
| Code Pattern | Test Approach |
|
||||||
|
|--------------|---------------|
|
||||||
|
| Pure function | Unit tests with varied inputs |
|
||||||
|
| Class with state | Setup/teardown, state transitions |
|
||||||
|
| External calls | Mocks/stubs for dependencies |
|
||||||
|
| Database ops | Integration tests with fixtures |
|
||||||
|
| API endpoints | Request/response tests |
|
||||||
|
| UI components | Snapshot + interaction tests |
|
||||||
|
|
||||||
|
3. **Generate Tests**
|
||||||
|
|
||||||
|
For each target function/method:
|
||||||
|
- Happy path test (expected inputs → expected output)
|
||||||
|
- Edge cases (empty, null, boundary values)
|
||||||
|
- Error cases (invalid inputs → expected errors)
|
||||||
|
- Type variations (if dynamic typing)
|
||||||
|
|
||||||
|
4. **Test Structure**
|
||||||
|
```python
|
||||||
|
# Example output for Python/pytest
|
||||||
|
|
||||||
|
import pytest
|
||||||
|
from module import target_function
|
||||||
|
|
||||||
|
class TestTargetFunction:
|
||||||
|
"""Tests for target_function."""
|
||||||
|
|
||||||
|
def test_happy_path(self):
|
||||||
|
"""Standard input produces expected output."""
|
||||||
|
result = target_function(valid_input)
|
||||||
|
assert result == expected_output
|
||||||
|
|
||||||
|
def test_empty_input(self):
|
||||||
|
"""Empty input handled gracefully."""
|
||||||
|
result = target_function("")
|
||||||
|
assert result == default_value
|
||||||
|
|
||||||
|
def test_invalid_input_raises(self):
|
||||||
|
"""Invalid input raises ValueError."""
|
||||||
|
with pytest.raises(ValueError):
|
||||||
|
target_function(invalid_input)
|
||||||
|
|
||||||
|
@pytest.mark.parametrize("input,expected", [
|
||||||
|
(case1_in, case1_out),
|
||||||
|
(case2_in, case2_out),
|
||||||
|
])
|
||||||
|
def test_variations(self, input, expected):
|
||||||
|
"""Multiple input variations."""
|
||||||
|
assert target_function(input) == expected
|
||||||
|
```
|
||||||
|
|
||||||
|
5. **Output**
|
||||||
|
```
|
||||||
|
## Tests Generated
|
||||||
|
|
||||||
|
### Target: src/orders.py:calculate_total
|
||||||
|
|
||||||
|
### File Created: tests/test_orders.py
|
||||||
|
|
||||||
|
### Tests (6 total)
|
||||||
|
- test_calculate_total_happy_path
|
||||||
|
- test_calculate_total_empty_items
|
||||||
|
- test_calculate_total_negative_price_raises
|
||||||
|
- test_calculate_total_with_discount
|
||||||
|
- test_calculate_total_with_tax
|
||||||
|
- test_calculate_total_parametrized_cases
|
||||||
|
|
||||||
|
### Coverage Estimate
|
||||||
|
- Line coverage: ~85%
|
||||||
|
- Branch coverage: ~70%
|
||||||
|
|
||||||
|
### Run Tests
|
||||||
|
pytest tests/test_orders.py -v
|
||||||
|
```
|
||||||
|
|
||||||
|
## Framework Detection
|
||||||
|
|
||||||
|
| Files Present | Framework Used |
|
||||||
|
|---------------|----------------|
|
||||||
|
| pytest.ini, conftest.py | pytest |
|
||||||
|
| jest.config.* | jest |
|
||||||
|
| vitest.config.* | vitest |
|
||||||
|
| *_test.go | go test |
|
||||||
|
| Cargo.toml | cargo test |
|
||||||
|
| mix.exs | ExUnit |
|
||||||
|
|
||||||
|
## Integration with /test-check
|
||||||
|
|
||||||
|
- `/test-gen` creates new tests
|
||||||
|
- `/test-check` verifies tests pass
|
||||||
|
- Typical flow: `/test-gen src/new_module.py` → `/test-check`
|
||||||
@@ -389,25 +389,24 @@ def list_issues(self, state='open', labels=None, repo=None):
|
|||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
Part of the Bandit Labs Claude Code Plugins project.
|
MIT License - Part of the Claude Code Marketplace project.
|
||||||
|
|
||||||
## Related Documentation
|
## Related Documentation
|
||||||
|
|
||||||
- **MCP Specification**: `docs/references/MCP-GITEA.md`
|
- **Projman Documentation**: `plugins/projman/README.md`
|
||||||
- **Project Summary**: `docs/references/PROJECT-SUMMARY.md`
|
- **Configuration Guide**: `plugins/projman/CONFIGURATION.md`
|
||||||
- **Implementation Plan**: `docs/reference-material/projman-implementation-plan.md`
|
|
||||||
- **Testing Guide**: `TESTING.md`
|
- **Testing Guide**: `TESTING.md`
|
||||||
|
|
||||||
## Support
|
## Support
|
||||||
|
|
||||||
For issues or questions:
|
For issues or questions:
|
||||||
1. Check [TESTING.md](./TESTING.md) troubleshooting section
|
1. Check [TESTING.md](./TESTING.md) troubleshooting section
|
||||||
2. Review [MCP-GITEA.md](../../docs/references/MCP-GITEA.md) specification
|
2. Review [plugins/projman/README.md](../../README.md) for plugin documentation
|
||||||
3. Create an issue in the project repository
|
3. Create an issue in the project repository
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Built for**: Bandit Labs Project Management Plugins
|
**Built for**: Claude Code Marketplace - Project Management Plugins
|
||||||
**Phase**: 1 (Complete)
|
**Phase**: 1 (Complete)
|
||||||
**Status**: ✅ Production Ready
|
**Status**: ✅ Production Ready
|
||||||
**Last Updated**: 2025-01-06
|
**Last Updated**: 2025-01-06
|
||||||
|
|||||||
@@ -574,8 +574,8 @@ After completing testing:
|
|||||||
|
|
||||||
- **MCP Documentation**: https://docs.anthropic.com/claude/docs/mcp
|
- **MCP Documentation**: https://docs.anthropic.com/claude/docs/mcp
|
||||||
- **Gitea API Documentation**: https://docs.gitea.io/en-us/api-usage/
|
- **Gitea API Documentation**: https://docs.gitea.io/en-us/api-usage/
|
||||||
- **Project Documentation**: `docs/references/MCP-GITEA.md`
|
- **Projman Documentation**: `plugins/projman/README.md`
|
||||||
- **Implementation Plan**: `docs/references/PROJECT-SUMMARY.md`
|
- **Configuration Guide**: `plugins/projman/CONFIGURATION.md`
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -45,7 +45,7 @@ class GiteaClient:
|
|||||||
"""Parse owner/repo from input. Always requires 'owner/repo' format."""
|
"""Parse owner/repo from input. Always requires 'owner/repo' format."""
|
||||||
target = repo or self.repo
|
target = repo or self.repo
|
||||||
if not target or '/' not in target:
|
if not target or '/' not in target:
|
||||||
raise ValueError("Use 'owner/repo' format (e.g. 'bandit/support-claude-mktplace')")
|
raise ValueError("Use 'owner/repo' format (e.g. 'org/repo-name')")
|
||||||
parts = target.split('/', 1)
|
parts = target.split('/', 1)
|
||||||
return parts[0], parts[1]
|
return parts[0], parts[1]
|
||||||
|
|
||||||
|
|||||||
@@ -32,7 +32,7 @@ class LabelTools:
|
|||||||
|
|
||||||
target_repo = repo or self.gitea.repo
|
target_repo = repo or self.gitea.repo
|
||||||
if not target_repo or '/' not in target_repo:
|
if not target_repo or '/' not in target_repo:
|
||||||
raise ValueError("Use 'owner/repo' format (e.g. 'bandit/support-claude-mktplace')")
|
raise ValueError("Use 'owner/repo' format (e.g. 'org/repo-name')")
|
||||||
|
|
||||||
org = target_repo.split('/')[0]
|
org = target_repo.split('/')[0]
|
||||||
|
|
||||||
|
|||||||
@@ -7,7 +7,7 @@ description: Dynamic reference for Gitea label taxonomy (organization + reposito
|
|||||||
|
|
||||||
**Status:** ✅ Synced with Gitea
|
**Status:** ✅ Synced with Gitea
|
||||||
**Last synced:** 2025-11-21 (via automated testing)
|
**Last synced:** 2025-11-21 (via automated testing)
|
||||||
**Source:** Gitea (bandit/support-claude-mktplace)
|
**Source:** Gitea (personal-projects/support-claude-mktplace)
|
||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|
||||||
@@ -17,7 +17,7 @@ This skill provides the current label taxonomy used for issue classification in
|
|||||||
|
|
||||||
## Organization Labels (27)
|
## Organization Labels (27)
|
||||||
|
|
||||||
Organization-level labels are shared across all repositories in the `bandit` organization.
|
Organization-level labels are shared across all repositories in your configured organization.
|
||||||
|
|
||||||
### Agent (2)
|
### Agent (2)
|
||||||
- `Agent/Human` (#0052cc) - Work performed by human developers
|
- `Agent/Human` (#0052cc) - Work performed by human developers
|
||||||
|
|||||||
139
scripts/validate-marketplace.sh
Executable file
139
scripts/validate-marketplace.sh
Executable file
@@ -0,0 +1,139 @@
|
|||||||
|
#!/usr/bin/env bash
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||||
|
ROOT_DIR="$(dirname "$SCRIPT_DIR")"
|
||||||
|
|
||||||
|
echo "=== Validating Marketplace ==="
|
||||||
|
|
||||||
|
# Check marketplace.json exists and is valid JSON
|
||||||
|
MARKETPLACE_JSON="$ROOT_DIR/.claude-plugin/marketplace.json"
|
||||||
|
if [[ ! -f "$MARKETPLACE_JSON" ]]; then
|
||||||
|
echo "ERROR: Missing $MARKETPLACE_JSON"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
if ! jq empty "$MARKETPLACE_JSON" 2>/dev/null; then
|
||||||
|
echo "ERROR: Invalid JSON in marketplace.json"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
echo "✓ marketplace.json is valid JSON"
|
||||||
|
|
||||||
|
# Check required fields
|
||||||
|
if ! jq -e '.name' "$MARKETPLACE_JSON" >/dev/null; then
|
||||||
|
echo "ERROR: Missing 'name' field in marketplace.json"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
if ! jq -e '.owner.name' "$MARKETPLACE_JSON" >/dev/null; then
|
||||||
|
echo "ERROR: Missing 'owner.name' field in marketplace.json"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
if ! jq -e '.owner.email' "$MARKETPLACE_JSON" >/dev/null; then
|
||||||
|
echo "ERROR: Missing 'owner.email' field in marketplace.json"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
echo "✓ Required marketplace fields present"
|
||||||
|
|
||||||
|
# Check plugins array exists
|
||||||
|
if ! jq -e '.plugins | type == "array"' "$MARKETPLACE_JSON" >/dev/null; then
|
||||||
|
echo "ERROR: Missing or invalid 'plugins' array in marketplace.json"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Check each plugin entry in marketplace.json
|
||||||
|
PLUGIN_COUNT=$(jq '.plugins | length' "$MARKETPLACE_JSON")
|
||||||
|
echo "Found $PLUGIN_COUNT plugins in marketplace.json"
|
||||||
|
|
||||||
|
for i in $(seq 0 $((PLUGIN_COUNT - 1))); do
|
||||||
|
PLUGIN_NAME=$(jq -r ".plugins[$i].name" "$MARKETPLACE_JSON")
|
||||||
|
echo "--- Checking marketplace entry: $PLUGIN_NAME ---"
|
||||||
|
|
||||||
|
# Check required fields in marketplace entry
|
||||||
|
for field in name source description version; do
|
||||||
|
if ! jq -e ".plugins[$i].$field" "$MARKETPLACE_JSON" >/dev/null; then
|
||||||
|
echo "ERROR: Missing '$field' in marketplace entry for $PLUGIN_NAME"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
# Check author field
|
||||||
|
if ! jq -e ".plugins[$i].author.name" "$MARKETPLACE_JSON" >/dev/null; then
|
||||||
|
echo "ERROR: Missing 'author.name' in marketplace entry for $PLUGIN_NAME"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Check homepage and repository
|
||||||
|
if ! jq -e ".plugins[$i].homepage" "$MARKETPLACE_JSON" >/dev/null; then
|
||||||
|
echo "WARNING: Missing 'homepage' in marketplace entry for $PLUGIN_NAME"
|
||||||
|
fi
|
||||||
|
|
||||||
|
if ! jq -e ".plugins[$i].repository" "$MARKETPLACE_JSON" >/dev/null; then
|
||||||
|
echo "WARNING: Missing 'repository' in marketplace entry for $PLUGIN_NAME"
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo "✓ Marketplace entry $PLUGIN_NAME valid"
|
||||||
|
done
|
||||||
|
|
||||||
|
# Validate each plugin directory
|
||||||
|
PLUGINS_DIR="$ROOT_DIR/plugins"
|
||||||
|
echo ""
|
||||||
|
echo "=== Validating Plugin Directories ==="
|
||||||
|
|
||||||
|
for plugin_dir in "$PLUGINS_DIR"/*/; do
|
||||||
|
plugin_name=$(basename "$plugin_dir")
|
||||||
|
echo "--- Checking plugin directory: $plugin_name ---"
|
||||||
|
|
||||||
|
# Check plugin.json exists
|
||||||
|
plugin_json="$plugin_dir.claude-plugin/plugin.json"
|
||||||
|
if [[ ! -f "$plugin_json" ]]; then
|
||||||
|
echo "WARNING: Missing plugin.json in $plugin_name/.claude-plugin/"
|
||||||
|
continue
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Validate JSON syntax
|
||||||
|
if ! jq empty "$plugin_json" 2>/dev/null; then
|
||||||
|
echo "ERROR: Invalid JSON in $plugin_name/plugin.json"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Check required plugin fields
|
||||||
|
for field in name description version; do
|
||||||
|
if ! jq -e ".$field" "$plugin_json" >/dev/null; then
|
||||||
|
echo "ERROR: Missing '$field' in $plugin_name/plugin.json"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
# Check recommended fields
|
||||||
|
if ! jq -e '.author.name' "$plugin_json" >/dev/null; then
|
||||||
|
echo "WARNING: Missing 'author.name' in $plugin_name/plugin.json"
|
||||||
|
fi
|
||||||
|
|
||||||
|
if ! jq -e '.homepage' "$plugin_json" >/dev/null; then
|
||||||
|
echo "WARNING: Missing 'homepage' in $plugin_name/plugin.json"
|
||||||
|
fi
|
||||||
|
|
||||||
|
if ! jq -e '.repository' "$plugin_json" >/dev/null; then
|
||||||
|
echo "WARNING: Missing 'repository' in $plugin_name/plugin.json"
|
||||||
|
fi
|
||||||
|
|
||||||
|
if ! jq -e '.license' "$plugin_json" >/dev/null; then
|
||||||
|
echo "WARNING: Missing 'license' in $plugin_name/plugin.json"
|
||||||
|
fi
|
||||||
|
|
||||||
|
if ! jq -e '.keywords | type == "array"' "$plugin_json" >/dev/null; then
|
||||||
|
echo "WARNING: Missing 'keywords' array in $plugin_name/plugin.json"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Check README exists
|
||||||
|
if [[ ! -f "$plugin_dir/README.md" ]]; then
|
||||||
|
echo "WARNING: Missing README.md in $plugin_name/"
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo "✓ $plugin_name valid"
|
||||||
|
done
|
||||||
|
|
||||||
|
echo ""
|
||||||
|
echo "=== All validations passed ==="
|
||||||
Reference in New Issue
Block a user