Compare commits
29 Commits
v2.0.0
...
5d95e42eb5
| Author | SHA1 | Date | |
|---|---|---|---|
| 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,79 @@
|
||||
{
|
||||
"name": "bandit-claude-marketplace",
|
||||
"version": "2.0.0",
|
||||
"description": "Project management plugins with Gitea and NetBox integrations",
|
||||
"name": "claude-code-marketplace",
|
||||
"owner": {
|
||||
"name": "Bandit Labs",
|
||||
"email": "dev@banditlabs.io"
|
||||
"name": "Leo Miranda",
|
||||
"email": "leobmiranda@gmail.com"
|
||||
},
|
||||
"metadata": {
|
||||
"description": "Project management plugins with Gitea and NetBox integrations",
|
||||
"version": "2.2.0"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "projman",
|
||||
"version": "2.0.0",
|
||||
"version": "2.2.0",
|
||||
"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": "project-hygiene",
|
||||
"version": "0.1.0",
|
||||
"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",
|
||||
"version": "1.0.0",
|
||||
"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",
|
||||
"version": "1.0.0",
|
||||
"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"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
24
CHANGELOG.md
24
CHANGELOG.md
@@ -4,7 +4,29 @@ 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/).
|
||||
|
||||
## [Unreleased]
|
||||
## [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
|
||||
|
||||
### 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
|
||||
|
||||
### Fixed
|
||||
- Plugin manifests now include all required fields per Claude Code spec
|
||||
- Installation section uses `extraKnownMarketplaces` instead of undocumented `pluginMarketplace`
|
||||
|
||||
## [2.1.0] - Previous Release
|
||||
|
||||
### Added
|
||||
- `docs/CANONICAL-PATHS.md` - Single source of truth for all file paths
|
||||
|
||||
609
CLAUDE.md
609
CLAUDE.md
@@ -1,478 +1,195 @@
|
||||
# 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
|
||||
|
||||
This repository contains Claude Code plugins for project management:
|
||||
**Repository:** support-claude-mktplace
|
||||
**Version:** 2.2.0
|
||||
**Status:** Production Ready
|
||||
|
||||
1. **`projman`** - Single-repository project management plugin with Gitea integration
|
||||
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
|
||||
A Claude Code plugin marketplace containing:
|
||||
|
||||
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.2.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
|
||||
/sprint-status # Check progress
|
||||
/review # Pre-close code quality review
|
||||
/test-check # Verify tests before close
|
||||
/sprint-close # Complete sprint
|
||||
```
|
||||
|
||||
Only these files may exist at the repository root:
|
||||
|
||||
- `CLAUDE.md` - This file
|
||||
- `README.md` - Repository overview
|
||||
- `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**
|
||||
- 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**
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
bandit/support-claude-mktplace/
|
||||
support-claude-mktplace/
|
||||
├── .claude-plugin/
|
||||
│ └── marketplace.json
|
||||
├── plugins/ # ← ALL PLUGINS (with bundled MCP servers)
|
||||
│ ├── projman/ # ← PROJECT PLUGIN
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ │ └── 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
|
||||
│ └── marketplace.json # Marketplace manifest
|
||||
├── plugins/
|
||||
│ ├── projman/ # Sprint management (v2.2.0)
|
||||
│ │ ├── .claude-plugin/plugin.json
|
||||
│ │ ├── .mcp.json
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ │ └── pmo-coordinator.md
|
||||
│ │ └── README.md
|
||||
│ ├── cmdb-assistant/ # ← CMDB PLUGIN
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ │ └── plugin.json
|
||||
│ │ ├── .mcp.json # Points to ${CLAUDE_PLUGIN_ROOT}/mcp-servers/
|
||||
│ │ ├── mcp-servers/ # ← MCP servers BUNDLED IN plugin
|
||||
│ │ │ └── netbox/
|
||||
│ │ │ ├── .venv/
|
||||
│ │ │ ├── requirements.txt
|
||||
│ │ │ └── mcp_server/
|
||||
│ │ ├── commands/
|
||||
│ │ └── agents/
|
||||
│ └── project-hygiene/ # ← CLEANUP PLUGIN
|
||||
│ └── ...
|
||||
├── scripts/ # Setup and maintenance scripts
|
||||
│ ├── setup.sh
|
||||
│ └── post-update.sh
|
||||
│ │ ├── mcp-servers/gitea/ # Bundled MCP server
|
||||
│ │ ├── commands/ # 8 commands
|
||||
│ │ │ ├── sprint-plan.md, sprint-start.md, sprint-status.md
|
||||
│ │ │ ├── sprint-close.md, labels-sync.md, initial-setup.md
|
||||
│ │ │ ├── review.md, test-check.md # NEW in v2.2.0
|
||||
│ │ ├── agents/ # 4 agents
|
||||
│ │ │ ├── planner.md, orchestrator.md, executor.md
|
||||
│ │ │ └── code-reviewer.md # NEW in v2.2.0
|
||||
│ │ └── skills/label-taxonomy/
|
||||
│ ├── claude-config-maintainer/
|
||||
│ ├── cmdb-assistant/
|
||||
│ └── project-hygiene/
|
||||
├── scripts/
|
||||
│ ├── setup.sh, post-update.sh
|
||||
│ └── validate-marketplace.sh # NEW in v2.2.0
|
||||
└── 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
|
||||
|
||||
### DO NOT MODIFY .gitignore Without Explicit Permission
|
||||
- This is a **private repository** - credentials in `.env` files are intentional
|
||||
- **NEVER** add `.env` or `.env.*` to .gitignore
|
||||
- **NEVER** add venv patterns unless explicitly asked
|
||||
- If you think something should be ignored, ASK FIRST
|
||||
### File Operations
|
||||
- **NEVER** create files in repository root unless listed in "Allowed Root Files"
|
||||
- **NEVER** modify `.gitignore` without explicit permission
|
||||
- **ALWAYS** use `.scratch/` for temporary/exploratory work
|
||||
- **ALWAYS** verify paths against `docs/CANONICAL-PATHS.md` before creating files
|
||||
|
||||
### Plugin Structure Requirements
|
||||
- **plugin.json MUST be in `.claude-plugin/` directory** - NOT in plugin root
|
||||
- Every plugin in the repo MUST be listed in the marketplace.json
|
||||
- After creating/modifying a plugin, VERIFY it's in the marketplace
|
||||
### Plugin Development
|
||||
- **plugin.json MUST be in `.claude-plugin/` directory** (not plugin root)
|
||||
- **Every plugin MUST be listed in marketplace.json**
|
||||
- **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)
|
||||
- **Valid events**: `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:
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"EventName": [
|
||||
{
|
||||
"matcher": "optional-pattern",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/path/to/script.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
### Hooks (Valid Events Only)
|
||||
`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
|
||||
|
||||
**INVALID:** `task-completed`, `file-changed`, `git-commit-msg-needed`
|
||||
|
||||
### Allowed Root Files
|
||||
`CLAUDE.md`, `README.md`, `LICENSE`, `CHANGELOG.md`, `.gitignore`, `.env.example`
|
||||
|
||||
### Allowed Root Directories
|
||||
`.claude/`, `.claude-plugin/`, `.claude-plugins/`, `.scratch/`, `docs/`, `hooks/`, `plugins/`, `scripts/`
|
||||
|
||||
## Architecture
|
||||
|
||||
### Four-Agent Model (projman v2.2.0)
|
||||
|
||||
| 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
|
||||
- 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
|
||||
## Path Verification Protocol
|
||||
|
||||
### Before Completing Any Plugin Work
|
||||
1. Verify plugin.json is in `.claude-plugin/` directory
|
||||
2. Verify plugin is listed in marketplace.json
|
||||
3. Test MCP server configs load correctly
|
||||
4. Verify hooks use valid event types
|
||||
5. Check .gitignore wasn't modified inappropriately
|
||||
**Before creating any file:**
|
||||
|
||||
1. Read `docs/CANONICAL-PATHS.md`
|
||||
2. List all paths to be created/modified
|
||||
3. Verify each against canonical paths
|
||||
4. If not in canonical paths, STOP and ask
|
||||
|
||||
## 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)
|
||||
- **`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
|
||||
## Version History
|
||||
|
||||
**Start with:** `docs/DOCUMENT-INDEX.md` for navigation guidance
|
||||
| Version | Date | Highlights |
|
||||
|---------|------|------------|
|
||||
| 2.2.0 | 2026-01-20 | `/review`, `/test-check` commands, code-reviewer agent, validation script, marketplace compliance |
|
||||
| 2.1.0 | Previous | Canonical paths, initial-setup command, documentation improvements |
|
||||
| 2.0.0 | Previous | Full Gitea integration, wiki, milestones, dependencies, parallel execution |
|
||||
| 0.1.0 | Initial | Basic plugin structure |
|
||||
|
||||
## Recent Updates (Updated: 2025-06-11)
|
||||
---
|
||||
|
||||
### Planning Phase Complete
|
||||
- Comprehensive 12-phase implementation plan finalized
|
||||
- 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
|
||||
1. **Shared MCP Servers**: Both plugins use the same MCP codebase at `mcp-servers/`
|
||||
2. **Mode Detection**: MCP servers detect project vs company-wide mode via environment variables
|
||||
3. **Python Implementation**: MCP servers written in Python (not Node.js) for better configuration handling
|
||||
4. **Wiki.js Integration**: Lessons learned and documentation moved to Wiki.js for better collaboration
|
||||
5. **Hybrid Config**: System-level credentials + project-level paths for flexibility
|
||||
|
||||
### Next Steps
|
||||
- Begin Phase 1.1a: Gitea MCP Server implementation
|
||||
- Set up Python virtual environments
|
||||
- Create configuration loaders
|
||||
- Implement core Gitea tools (issues, labels)
|
||||
- Write integration tests
|
||||
**Last Updated:** 2026-01-20 | **Current Version:** 2.2.0
|
||||
|
||||
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.
|
||||
156
README.md
156
README.md
@@ -1,22 +1,23 @@
|
||||
# Claude Code Marketplace - Bandit Labs
|
||||
# Claude Code Marketplace
|
||||
|
||||
A collection of Claude Code plugins for project management, infrastructure automation, and development workflows.
|
||||
|
||||
## Plugins
|
||||
|
||||
### [projman](./plugins/projman/README.md) v2.0.0
|
||||
### [projman](./plugins/projman/README.md) v2.2.0
|
||||
**Sprint Planning and Project Management**
|
||||
|
||||
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
|
||||
- Lessons learned capture via Gitea Wiki
|
||||
- Native issue dependencies with parallel execution
|
||||
- Milestone management for sprint organization
|
||||
- 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`
|
||||
|
||||
### [claude-config-maintainer](./plugins/claude-config-maintainer/README.md)
|
||||
**CLAUDE.md Optimization and Maintenance**
|
||||
@@ -89,67 +90,92 @@ Comprehensive NetBox REST API integration for infrastructure management.
|
||||
- Python 3.10+
|
||||
- Access to target services (Gitea, NetBox as needed)
|
||||
|
||||
### Quick Start
|
||||
### Add Marketplace to Claude Code
|
||||
|
||||
1. **Clone the repository:**
|
||||
```bash
|
||||
git clone ssh://git@hotserv.tailc9b278.ts.net:2222/bandit/support-claude-mktplace.git
|
||||
cd support-claude-mktplace
|
||||
```
|
||||
**Option 1 - CLI command (recommended):**
|
||||
```bash
|
||||
/plugin marketplace add https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git
|
||||
```
|
||||
|
||||
2. **Install MCP server dependencies:**
|
||||
```bash
|
||||
# Gitea MCP (for projman)
|
||||
cd plugins/projman/mcp-servers/gitea
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
deactivate
|
||||
**Option 2 - Settings file (for team distribution):**
|
||||
|
||||
# NetBox MCP (for cmdb-assistant)
|
||||
cd ../../../cmdb-assistant/mcp-servers/netbox
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
deactivate
|
||||
```
|
||||
|
||||
3. **Configure system-level credentials:**
|
||||
```bash
|
||||
mkdir -p ~/.config/claude
|
||||
|
||||
# Gitea credentials
|
||||
cat > ~/.config/claude/gitea.env << 'EOF'
|
||||
GITEA_URL=https://gitea.example.com
|
||||
GITEA_TOKEN=your_token
|
||||
GITEA_ORG=your_org
|
||||
EOF
|
||||
|
||||
# NetBox credentials
|
||||
cat > ~/.config/claude/netbox.env << 'EOF'
|
||||
NETBOX_API_URL=https://netbox.example.com/api
|
||||
NETBOX_API_TOKEN=your_token
|
||||
EOF
|
||||
|
||||
chmod 600 ~/.config/claude/*.env
|
||||
```
|
||||
|
||||
4. **Configure project-level settings:**
|
||||
```bash
|
||||
# In your target project root
|
||||
cat > .env << 'EOF'
|
||||
GITEA_REPO=your-repository-name
|
||||
EOF
|
||||
```
|
||||
|
||||
5. **Add marketplace to Claude Code:**
|
||||
|
||||
Add to your project's `.claude/settings.json`:
|
||||
```json
|
||||
{
|
||||
"pluginMarketplace": "/path/to/support-claude-mktplace"
|
||||
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
|
||||
# Gitea MCP (for projman)
|
||||
cd plugins/projman/mcp-servers/gitea
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
deactivate
|
||||
|
||||
# NetBox MCP (for cmdb-assistant)
|
||||
cd ../../../cmdb-assistant/mcp-servers/netbox
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
deactivate
|
||||
```
|
||||
|
||||
### Configure Credentials
|
||||
|
||||
**System-level credentials:**
|
||||
```bash
|
||||
mkdir -p ~/.config/claude
|
||||
|
||||
# Gitea credentials
|
||||
cat > ~/.config/claude/gitea.env << 'EOF'
|
||||
GITEA_URL=https://gitea.example.com
|
||||
GITEA_TOKEN=your_token
|
||||
GITEA_ORG=your_org
|
||||
EOF
|
||||
|
||||
# NetBox credentials
|
||||
cat > ~/.config/claude/netbox.env << 'EOF'
|
||||
NETBOX_API_URL=https://netbox.example.com/api
|
||||
NETBOX_API_TOKEN=your_token
|
||||
EOF
|
||||
|
||||
chmod 600 ~/.config/claude/*.env
|
||||
```
|
||||
|
||||
**Project-level settings:**
|
||||
```bash
|
||||
# In your target project root
|
||||
cat > .env << 'EOF'
|
||||
GITEA_REPO=your-repository-name
|
||||
EOF
|
||||
```
|
||||
|
||||
## Repository Structure
|
||||
|
||||
@@ -183,9 +209,10 @@ support-claude-mktplace/
|
||||
│ ├── CANONICAL-PATHS.md # Single source of truth for paths
|
||||
│ └── references/
|
||||
└── scripts/ # Setup and maintenance scripts
|
||||
└── validate-marketplace.sh # Marketplace compliance validation
|
||||
```
|
||||
|
||||
## Key Features (v2.0.0)
|
||||
## Key Features (v2.2.0)
|
||||
|
||||
### Parallel Execution
|
||||
Tasks are batched by dependency graph for optimal parallel execution:
|
||||
@@ -212,9 +239,10 @@ All agents use MCP tools exclusively. CLI tools like `tea` or `gh` are forbidden
|
||||
|
||||
## License
|
||||
|
||||
MIT License - Bandit Labs
|
||||
MIT License
|
||||
|
||||
## Support
|
||||
|
||||
- **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.**
|
||||
|
||||
Last Updated: 2025-12-15
|
||||
Last Updated: 2026-01-20
|
||||
|
||||
---
|
||||
|
||||
@@ -11,12 +11,13 @@ Last Updated: 2025-12-15
|
||||
```
|
||||
support-claude-mktplace/
|
||||
├── .claude/ # Claude Code local settings
|
||||
├── .claude-plugin/ # Marketplace manifest (bandit-claude-marketplace)
|
||||
├── .claude-plugin/ # Marketplace manifest (claude-code-marketplace)
|
||||
│ └── marketplace.json
|
||||
├── .scratch/ # Transient work (auto-cleaned)
|
||||
├── docs/ # All documentation
|
||||
│ ├── 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
|
||||
├── hooks/ # Shared hooks (if any)
|
||||
├── plugins/ # ALL plugins with bundled MCP servers
|
||||
@@ -26,7 +27,8 @@ support-claude-mktplace/
|
||||
│ │ │ └── gitea/ # Gitea + Wiki tools
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ └── skills/
|
||||
│ │ ├── skills/
|
||||
│ │ └── claude-md-integration.md # CLAUDE.md integration snippet
|
||||
│ ├── projman-pmo/
|
||||
│ ├── project-hygiene/
|
||||
│ ├── cmdb-assistant/
|
||||
@@ -34,11 +36,17 @@ support-claude-mktplace/
|
||||
│ │ ├── mcp-servers/ # MCP servers bundled IN plugin
|
||||
│ │ │ └── netbox/
|
||||
│ │ ├── commands/
|
||||
│ │ └── agents/
|
||||
│ └── claude-config-maintainer/
|
||||
│ │ ├── agents/
|
||||
│ │ └── claude-md-integration.md # CLAUDE.md integration snippet
|
||||
│ ├── claude-config-maintainer/
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ └── claude-md-integration.md # CLAUDE.md integration snippet
|
||||
│ └── project-hygiene/
|
||||
│ ├── .claude-plugin/
|
||||
│ ├── commands/
|
||||
│ └── agents/
|
||||
│ ├── hooks/
|
||||
│ └── claude-md-integration.md # CLAUDE.md integration snippet
|
||||
├── scripts/ # Setup and maintenance scripts
|
||||
├── CLAUDE.md
|
||||
├── README.md
|
||||
@@ -60,6 +68,7 @@ support-claude-mktplace/
|
||||
| Plugin commands | `plugins/{plugin-name}/commands/` | `plugins/projman/commands/` |
|
||||
| Plugin agents | `plugins/{plugin-name}/agents/` | `plugins/projman/agents/` |
|
||||
| Plugin .mcp.json | `plugins/{plugin-name}/.mcp.json` | `plugins/projman/.mcp.json` |
|
||||
| Plugin integration snippet | `plugins/{plugin-name}/claude-md-integration.md` | `plugins/projman/claude-md-integration.md` |
|
||||
|
||||
### MCP Server Paths (Bundled in Plugins)
|
||||
|
||||
@@ -82,10 +91,10 @@ MCP servers are now **bundled inside each plugin** to ensure they work when plug
|
||||
|
||||
| Type | Location |
|
||||
|------|----------|
|
||||
| Reference specs | `docs/references/` |
|
||||
| Architecture diagrams | `docs/architecture/` |
|
||||
| Workflow docs | `docs/workflows/` |
|
||||
| This file | `docs/CANONICAL-PATHS.md` |
|
||||
| Update guide | `docs/UPDATING.md` |
|
||||
|
||||
---
|
||||
|
||||
@@ -149,5 +158,7 @@ MCP servers are bundled inside each plugin (not shared at root) because:
|
||||
|
||||
| Date | Change | By |
|
||||
|------|--------|-----|
|
||||
| 2026-01-20 | Removed docs/references/ (obsolete planning docs) | Claude Code |
|
||||
| 2026-01-19 | Added claude-md-integration.md path pattern for plugin integration snippets | Claude Code |
|
||||
| 2025-12-15 | Restructured: MCP servers now bundled in plugins | Claude Code |
|
||||
| 2025-12-12 | Initial creation | Claude Code |
|
||||
|
||||
@@ -15,7 +15,7 @@ git pull origin main
|
||||
|
||||
## 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
|
||||
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
|
||||
2. Add it to the appropriate config file:
|
||||
- Gitea variables → `~/.config/claude/gitea.env`
|
||||
- Wiki.js variables → `~/.config/claude/wikijs.env`
|
||||
- Project variables → `.env` in your project root
|
||||
|
||||
### New MCP Server Features
|
||||
@@ -38,7 +37,7 @@ If the changelog mentions new environment variables:
|
||||
If a new MCP server tool is added:
|
||||
|
||||
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
|
||||
|
||||
### Breaking Changes
|
||||
@@ -51,15 +50,7 @@ Breaking changes will be clearly marked in CHANGELOG.md with migration instructi
|
||||
|
||||
```bash
|
||||
# Rebuild virtual environment
|
||||
cd 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
|
||||
cd plugins/projman/mcp-servers/gitea
|
||||
rm -rf .venv
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
@@ -76,7 +67,7 @@ deactivate
|
||||
### MCP server won't start
|
||||
|
||||
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
|
||||
|
||||
## Version Pinning
|
||||
@@ -88,7 +79,7 @@ To stay on a specific version:
|
||||
git tag
|
||||
|
||||
# Checkout specific version
|
||||
git checkout v1.0.0
|
||||
git checkout v2.2.0
|
||||
|
||||
# Run post-update
|
||||
./scripts/post-update.sh
|
||||
@@ -96,6 +87,7 @@ git checkout v1.0.0
|
||||
|
||||
## 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
|
||||
- Search existing issues in Gitea
|
||||
|
||||
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",
|
||||
"version": "1.0.0",
|
||||
"description": "Maintains and optimizes CLAUDE.md configuration files for Claude Code projects",
|
||||
"entryPoint": "agents/maintainer.md",
|
||||
"commands": [
|
||||
{
|
||||
"name": "config-analyze",
|
||||
"description": "Analyze CLAUDE.md for optimization opportunities",
|
||||
"entryPoint": "commands/analyze.md"
|
||||
"author": {
|
||||
"name": "Leo Miranda",
|
||||
"email": "leobmiranda@gmail.com"
|
||||
},
|
||||
{
|
||||
"name": "config-optimize",
|
||||
"description": "Optimize CLAUDE.md structure and content",
|
||||
"entryPoint": "commands/optimize.md"
|
||||
},
|
||||
{
|
||||
"name": "config-init",
|
||||
"description": "Initialize a new CLAUDE.md file for a project",
|
||||
"entryPoint": "commands/init.md"
|
||||
}
|
||||
"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",
|
||||
"license": "MIT",
|
||||
"keywords": [
|
||||
"claude-code",
|
||||
"configuration",
|
||||
"optimization",
|
||||
"claude-md",
|
||||
"developer-tools"
|
||||
],
|
||||
"agents": [
|
||||
{
|
||||
"name": "maintainer",
|
||||
"description": "CLAUDE.md optimization and maintenance agent",
|
||||
"entryPoint": "agents/maintainer.md"
|
||||
}
|
||||
]
|
||||
"entryPoint": "agents/maintainer.md",
|
||||
"commands": ["./commands/"],
|
||||
"agents": ["./agents/"]
|
||||
}
|
||||
|
||||
@@ -96,4 +96,4 @@ Target score: **70+** for effective Claude Code usage.
|
||||
|
||||
## 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
|
||||
|
||||
When analyzing a CLAUDE.md file, evaluate:
|
||||
When analyzing a CLAUDE.md file, perform two types of analysis:
|
||||
|
||||
#### A. Content Analysis
|
||||
|
||||
Evaluate:
|
||||
|
||||
**Structure:**
|
||||
- Is the file well-organized?
|
||||
@@ -57,6 +61,49 @@ When analyzing a CLAUDE.md file, evaluate:
|
||||
- Are there verbose explanations that could be shortened?
|
||||
- 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
|
||||
|
||||
**Recommended Structure:**
|
||||
@@ -145,7 +192,42 @@ Suggested Actions:
|
||||
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:
|
||||
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
@@ -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
|
||||
3. **Check Content** - Reviews clarity, completeness, and conciseness
|
||||
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
|
||||
|
||||
@@ -52,6 +54,29 @@ Analyze the CLAUDE.md file in this project
|
||||
- Appropriate length for project size
|
||||
- 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
|
||||
|
||||
```
|
||||
@@ -101,10 +126,37 @@ Recommendations:
|
||||
|
||||
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:
|
||||
[1] Implement all recommended changes
|
||||
[2] Show before/after for specific section
|
||||
[3] Generate optimized version for review
|
||||
[1] Implement all content recommendations
|
||||
[2] Add missing plugin integrations to CLAUDE.md
|
||||
[3] Do both (recommended)
|
||||
[4] Show preview of changes first
|
||||
```
|
||||
|
||||
## When to Use
|
||||
@@ -115,6 +167,8 @@ Run `/config-analyze` when:
|
||||
- Claude seems to miss instructions
|
||||
- Before major project changes
|
||||
- Periodic maintenance (quarterly)
|
||||
- After installing new marketplace plugins
|
||||
- When Claude doesn't seem to use available plugin tools
|
||||
|
||||
## Follow-Up Actions
|
||||
|
||||
|
||||
@@ -3,10 +3,11 @@
|
||||
"version": "1.0.0",
|
||||
"description": "NetBox CMDB integration for infrastructure management - query, create, update, and manage network devices, IP addresses, sites, and more",
|
||||
"author": {
|
||||
"name": "Bandit Labs",
|
||||
"email": "dev@banditlabs.io"
|
||||
"name": "Leo Miranda",
|
||||
"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",
|
||||
"keywords": [
|
||||
"netbox",
|
||||
@@ -15,5 +16,8 @@
|
||||
"network",
|
||||
"ipam",
|
||||
"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
|
||||
|
||||
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
|
||||
|
||||
Part of the Bandit Labs Claude Code Plugins project (`support-claude-mktplace`).
|
||||
MIT License - Part of the Claude Code Marketplace (`support-claude-mktplace`).
|
||||
|
||||
@@ -3,12 +3,19 @@
|
||||
"version": "0.1.0",
|
||||
"description": "Post-task cleanup hook that removes temp files, warns about unexpected root files, and manages orphaned supporting files",
|
||||
"author": {
|
||||
"name": "Bandit Labs",
|
||||
"email": "dev@banditlabs.io"
|
||||
"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",
|
||||
"license": "MIT",
|
||||
"keywords": ["cleanup", "hygiene", "automation", "hooks", "maintenance"],
|
||||
"repository": "https://github.com/bandit-labs/project-hygiene",
|
||||
"keywords": [
|
||||
"cleanup",
|
||||
"hygiene",
|
||||
"automation",
|
||||
"hooks",
|
||||
"maintenance"
|
||||
],
|
||||
"hooks": {
|
||||
"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",
|
||||
"version": "2.0.0",
|
||||
"version": "2.2.0",
|
||||
"description": "Sprint planning and project management with Gitea integration",
|
||||
"author": {
|
||||
"name": "Bandit Labs",
|
||||
"email": "dev@banditlabs.io"
|
||||
"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",
|
||||
"license": "MIT",
|
||||
"repository": "https://gitea.hotserv.cloud/bandit/support-claude-mktplace",
|
||||
"keywords": [
|
||||
"project-management",
|
||||
"sprint-planning",
|
||||
"gitea",
|
||||
"agile",
|
||||
"lessons-learned"
|
||||
]
|
||||
],
|
||||
"commands": ["./commands/"],
|
||||
"agents": ["./agents/"]
|
||||
}
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Projman v2.0.0 - Project Management for Claude Code
|
||||
# Projman v2.2.0 - Project Management for Claude Code
|
||||
|
||||
Sprint planning and project management plugin with full Gitea integration.
|
||||
|
||||
@@ -174,6 +174,43 @@ Run initial setup for a new 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
|
||||
|
||||
## 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
|
||||
|
||||
### Planner Agent
|
||||
@@ -203,6 +240,17 @@ Run initial setup for a new project.
|
||||
|
||||
**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
|
||||
**Personality:** Implementation-focused, follows specs precisely
|
||||
|
||||
@@ -373,11 +421,14 @@ projman/
|
||||
│ ├── sprint-status.md
|
||||
│ ├── sprint-close.md
|
||||
│ ├── labels-sync.md
|
||||
│ └── initial-setup.md
|
||||
│ ├── initial-setup.md
|
||||
│ ├── review.md
|
||||
│ └── test-check.md
|
||||
├── agents/ # Agent prompts
|
||||
│ ├── planner.md
|
||||
│ ├── orchestrator.md
|
||||
│ └── executor.md
|
||||
│ ├── executor.md
|
||||
│ └── code-reviewer.md
|
||||
├── skills/ # Supporting knowledge
|
||||
│ └── label-taxonomy/
|
||||
│ └── labels-reference.md
|
||||
@@ -430,13 +481,14 @@ MIT License - See repository root for details
|
||||
|
||||
## Version
|
||||
|
||||
**Current:** 2.0.0
|
||||
**Current:** 2.2.0
|
||||
|
||||
**Changelog:**
|
||||
- v2.2.0: Added `/review` and `/test-check` commands, code-reviewer agent, marketplace compliance updates
|
||||
- v2.1.0: Documentation improvements, canonical paths, initial-setup command
|
||||
- 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
|
||||
|
||||
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
|
||||
@@ -389,25 +389,24 @@ def list_issues(self, state='open', labels=None, repo=None):
|
||||
|
||||
## License
|
||||
|
||||
Part of the Bandit Labs Claude Code Plugins project.
|
||||
MIT License - Part of the Claude Code Marketplace project.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **MCP Specification**: `docs/references/MCP-GITEA.md`
|
||||
- **Project Summary**: `docs/references/PROJECT-SUMMARY.md`
|
||||
- **Implementation Plan**: `docs/reference-material/projman-implementation-plan.md`
|
||||
- **Projman Documentation**: `plugins/projman/README.md`
|
||||
- **Configuration Guide**: `plugins/projman/CONFIGURATION.md`
|
||||
- **Testing Guide**: `TESTING.md`
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
**Built for**: Bandit Labs Project Management Plugins
|
||||
**Built for**: Claude Code Marketplace - Project Management Plugins
|
||||
**Phase**: 1 (Complete)
|
||||
**Status**: ✅ Production Ready
|
||||
**Last Updated**: 2025-01-06
|
||||
|
||||
@@ -574,8 +574,8 @@ After completing testing:
|
||||
|
||||
- **MCP Documentation**: https://docs.anthropic.com/claude/docs/mcp
|
||||
- **Gitea API Documentation**: https://docs.gitea.io/en-us/api-usage/
|
||||
- **Project Documentation**: `docs/references/MCP-GITEA.md`
|
||||
- **Implementation Plan**: `docs/references/PROJECT-SUMMARY.md`
|
||||
- **Projman Documentation**: `plugins/projman/README.md`
|
||||
- **Configuration Guide**: `plugins/projman/CONFIGURATION.md`
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -45,7 +45,7 @@ class GiteaClient:
|
||||
"""Parse owner/repo from input. Always requires 'owner/repo' format."""
|
||||
target = repo or self.repo
|
||||
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)
|
||||
return parts[0], parts[1]
|
||||
|
||||
|
||||
@@ -32,7 +32,7 @@ class LabelTools:
|
||||
|
||||
target_repo = repo or self.gitea.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]
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ description: Dynamic reference for Gitea label taxonomy (organization + reposito
|
||||
|
||||
**Status:** ✅ Synced with Gitea
|
||||
**Last synced:** 2025-11-21 (via automated testing)
|
||||
**Source:** Gitea (bandit/support-claude-mktplace)
|
||||
**Source:** Gitea (personal-projects/support-claude-mktplace)
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -17,7 +17,7 @@ This skill provides the current label taxonomy used for issue classification in
|
||||
|
||||
## 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/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