34 Commits

Author SHA1 Message Date
337f40600a Merge pull request 'fix: remove Wiki.js references from architecture docs' (#35) from development into main
Reviewed-on: personal-projects/support-claude-mktplace#35
2026-01-20 16:24:53 +00:00
14425cfad1 fix: remove Wiki.js references from architecture docs
- Updated agent-workflow.spec.md to use Gitea Wiki instead of Wiki.js
- Updated component-map.spec.md to show Gitea (Issues + Wiki) as single service
- Changed GraphQL references to REST API (Gitea uses REST)
- Added Code Reviewer agent swimlane to agent-workflow diagram
- Added ARCHITECTURE NOTES sections to clarify current design

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-20 11:22:20 -05:00
c38404a98a Merge pull request 'development: small fixes in the changelog' (#34) from development into main
Reviewed-on: personal-projects/support-claude-mktplace#34
2026-01-20 16:17:13 +00:00
70d3933da4 docs: update CHANGELOG with complete version history and add maintenance rules
CHANGELOG.md updates:
- Added proper dates to all versions (2.1.0, 2.0.0, 1.0.0, 0.1.0)
- Added v2.0.0 section (was missing)
- Added v1.0.0 section with initial features
- Updated v2.2.0 with version consolidation changes
- Follows Keep a Changelog format

CLAUDE.md updates:
- Added "Changelog Maintenance (MANDATORY)" section
- Documented required steps when releasing new version
- Added Semantic Versioning reference
- Clarified version display rules

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-20 11:15:55 -05:00
cce2066d3b fix: consolidate version display to main README.md only
Version standardization:
- Move version to main README.md title: "Claude Code Marketplace - v2.2.0"
- Remove version from plugins/projman/README.md title
- Remove version from plugins/projman/CONFIGURATION.md title
- Remove version from plugin listings in README.md
- Remove "Key Features (v2.2.0)" -> "Key Features"
- Remove Version section from plugins/projman/README.md
- Remove version references from CLAUDE.md structure comments

Added versioning rule to CLAUDE.md:
- Version displayed ONLY in main README.md title
- Do NOT add versions to plugin docs or config guides
- Version history maintained in CHANGELOG.md only

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-20 11:12:44 -05:00
5d95e42eb5 Merge pull request 'development: final tuning adjustments' (#33) from development into main
Reviewed-on: personal-projects/support-claude-mktplace#33
2026-01-20 15:55:14 +00:00
f35706e621 chore: remove obsolete docs/references/ planning documents
Deleted (obsolete planning docs from pre-implementation phase):
- docs/references/MCP-GITEA.md - wrong MCP server location
- docs/references/MCP-WIKIJS.md - Wiki.js MCP never implemented
- docs/references/PLUGIN-PMO.md - projman-pmo not yet built
- docs/references/PLUGIN-PROJMAN.md - superseded by plugins/projman/README.md
- docs/references/PROJECT-SUMMARY.md - outdated architecture

Updated references in:
- CLAUDE.md - removed docs/references/ from documentation index
- docs/CANONICAL-PATHS.md - removed references directory from structure
- docs/UPDATING.md - updated to reference current documentation
- plugins/projman/mcp-servers/gitea/README.md - fixed related docs links
- plugins/projman/mcp-servers/gitea/TESTING.md - fixed resource links

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-20 10:52:35 -05:00
697031c526 docs: overhaul CLAUDE.md for v2.2.0 with maintainer best practices
Complete rewrite following claude-config-maintainer principles:
- Clear, concise, complete, current
- Scannable structure with tables
- Critical rules prominently placed
- Quick Start section added

Updates:
- Version: 2.2.0, Status: Production Ready
- Four-Agent Model (added Code Reviewer)
- New commands: /review, /test-check
- New file: validate-marketplace.sh
- Removed outdated "Next Steps" and stale dates
- Consolidated verbose sections into tables
- Added Version History table

Reduced from ~480 lines to ~195 lines while maintaining all essential information.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-20 10:34:13 -05:00
32797ce473 Merge pull request 'development: new version launched (v2.2.0)' (#32) from development into main
Reviewed-on: personal-projects/support-claude-mktplace#32
2026-01-20 15:23:12 +00:00
368f9a4c2e Merge feat/marketplace-compliance-and-review into development
Release v2.2.0 - Marketplace Compliance Updates & Feature Additions

New Features:
- /review command for pre-sprint-close code quality checks
- /test-check command for test verification before sprint close
- code-reviewer agent for structured code review
- Validation script (scripts/validate-marketplace.sh)

Compliance Fixes:
- Updated marketplace.json with required fields (metadata, author, homepage, repository)
- Updated all plugin manifests with required fields
- Fixed installation documentation to use official Claude Code methods
- Prioritized public HTTPS URL over Tailscale SSH URL

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-20 10:16:36 -05:00
cb0a5ddec5 chore: bump version to v2.2.0 and update documentation
Version updates:
- marketplace.json metadata.version: 2.0.0 → 2.2.0
- marketplace.json projman version: 2.0.0 → 2.2.0
- plugins/projman/plugin.json version: 2.0.0 → 2.2.0

Documentation updates:
- CHANGELOG.md: Changed [Unreleased] to [2.2.0] - 2026-01-20
- README.md: Updated projman version to v2.2.0
- README.md: Added /review and /test-check to commands list
- README.md: Added code-reviewer to agent list
- README.md: Updated Key Features section to v2.2.0
- README.md: Added validate-marketplace.sh to structure
- plugins/projman/README.md: Updated title to v2.2.0
- plugins/projman/README.md: Updated version changelog

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-20 10:09:01 -05:00
8da7117b89 docs: update projman readme with new commands
- Add /review command documentation
- Add /test-check command documentation
- Add Code Quality Commands section
- Add code-reviewer agent to Agents section
- Update architecture directory listing

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-20 10:00:37 -05:00
c322cf4b2f docs: update changelog with compliance and feature additions
- Document all compliance fixes (marketplace, plugins, README)
- Document new /review and /test-check commands
- Document code-reviewer agent addition
- Document validation script addition

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-20 09:59:43 -05:00
a6d3fe6c6c feat(projman): add /test-check command for test verification
- Add test-check.md command for pre-sprint-close test verification
- Automatic framework detection (pytest, jest, go test, cargo, etc.)
- Coverage reporting when available
- Sprint file analysis for untested changes
- Clear pass/fail summary with recommendations

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-20 09:59:16 -05:00
c62e0dbd2c feat(projman): add /review command for code quality checks
- Add review.md command for pre-sprint-close code quality review
- Add code-reviewer.md agent for structured review workflow
- Covers debug artifacts, code quality, security, error handling
- Integrates with projman sprint context when available
- Provides structured output with severity levels

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-20 09:58:35 -05:00
34c8f0bdb6 feat: add validation script for marketplace compliance
- Validates marketplace.json syntax and required fields
- Checks each plugin entry has required fields
- Validates individual plugin.json files
- Checks for recommended fields (author, homepage, repository)
- Returns non-zero exit code on errors

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-20 09:57:40 -05:00
72941c1fe1 docs: fix installation instructions for official methods
- Replace pluginMarketplace with extraKnownMarketplaces
- Add CLI command method (recommended)
- Add settings.json method for team distribution
- Add local development option
- Prioritize public HTTPS URL over Tailscale SSH URL
- Reorganize installation sections for clarity

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-20 09:56:41 -05:00
1adb434c58 fix: add required fields to plugin manifests
- Add author, homepage, repository to all plugin manifests
- Add license field where missing
- Add commands and agents directory references
- Update keywords for better discoverability

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-20 09:55:57 -05:00
76462d5d8c fix: update marketplace.json with required fields
- Add metadata wrapper for description and version
- Add author, homepage, and repository to all plugin entries
- Ensure owner.email field exists and is valid

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-20 09:55:13 -05:00
5b7c1f3fce Update plugins/projman/README.md 2026-01-20 13:55:26 +00:00
87b30cbb85 Update plugins/projman/README.md 2026-01-20 13:54:46 +00:00
67c057f9ee Merge pull request 'Update README.md' (#31) from development into main
Reviewed-on: personal-projects/support-claude-mktplace#31
2026-01-20 13:44:27 +00:00
c34fd22852 Update README.md 2026-01-20 13:42:39 +00:00
5fc18f28e9 Merge pull request 'feat: add plugin integration analysis to config-analyze command' (#30) from development into main
Reviewed-on: personal-projects/support-claude-mktplace#30
2026-01-19 23:27:15 +00:00
113839b0d8 feat: add plugin integration analysis to config-analyze command
Add automatic detection of active marketplace plugins and verification
that CLAUDE.md properly references them. This ensures projects using
marketplace plugins will have proper documentation to guide Claude Code
in using available tools.

Changes:
- Add claude-md-integration.md snippets to all 4 plugins (projman,
  cmdb-assistant, claude-config-maintainer, project-hygiene)
- Update marketplace.json with MCP server mappings for plugin detection
- Enhance /config-analyze to detect active plugins via MCP server names
- Update maintainer agent with plugin integration workflow
- Add plugin coverage percentage to analysis report
- User confirmation required before adding plugin references

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-19 18:24:29 -05:00
a12665c22d Merge pull request 'chore: rebrand for public release' (#28) from development into main
Reviewed-on: personal-projects/support-claude-mktplace#28
2026-01-19 22:54:29 +00:00
15e0654950 chore: rebrand for public release
- Move repository from bandit to personal-projects organization
- Remove all "Bandit Labs" references
- Update author to Leo Miranda
- Rename marketplace from bandit-claude-marketplace to claude-code-marketplace
- Add MIT LICENSE file
- Remove outdated root .mcp.json (MCP servers now bundled in plugins)
- Update all repository URLs to new location

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-19 17:49:40 -05:00
3c3b9329c5 Merge pull request 'development' (#27) from development into main
Reviewed-on: bandit/support-claude-mktplace#27
2026-01-19 22:23:28 +00:00
1e63de6679 Merge pull request 'refactor: bundle MCP servers inside plugins for cache compatibility' (#26) from development into main
Reviewed-on: bandit/support-claude-mktplace#26
2025-12-15 22:23:57 +00:00
6c77c264f6 Merge pull request 'fix: correct labels path in setup.sh' (#25) from development into main
Reviewed-on: bandit/support-claude-mktplace#25
2025-12-15 22:09:32 +00:00
b3a41f722c Merge pull request 'development' (#24) from development into main
Reviewed-on: bandit/support-claude-mktplace#24
2025-12-12 17:38:07 +00:00
97085021a9 Merge pull request 'fix: add missing plugin declarations and fix hardcoded paths' (#23) from development into main
Reviewed-on: bandit/support-claude-mktplace#23
2025-12-12 15:57:19 +00:00
eb2c184641 Merge pull request 'development' (#22) from development into main
Reviewed-on: bandit/support-claude-mktplace#22
2025-12-12 07:13:09 +00:00
5cfe858b12 Merge pull request 'Add path safeguards to prevent structural damage' (#21) from development into main
Reviewed-on: bandit/support-claude-mktplace#21
2025-12-12 05:15:04 +00:00
39 changed files with 1509 additions and 6689 deletions

View File

@@ -1,35 +1,79 @@
{ {
"name": "bandit-claude-marketplace", "name": "claude-code-marketplace",
"version": "2.0.0",
"description": "Project management plugins with Gitea and NetBox integrations",
"owner": { "owner": {
"name": "Bandit Labs", "name": "Leo Miranda",
"email": "dev@banditlabs.io" "email": "leobmiranda@gmail.com"
},
"metadata": {
"description": "Project management plugins with Gitea and NetBox integrations",
"version": "2.2.0"
}, },
"plugins": [ "plugins": [
{ {
"name": "projman", "name": "projman",
"version": "2.0.0", "version": "2.2.0",
"description": "Sprint planning and project management with Gitea integration", "description": "Sprint planning and project management with Gitea integration",
"source": "./plugins/projman" "source": "./plugins/projman",
"author": {
"name": "Leo Miranda",
"email": "leobmiranda@gmail.com"
},
"homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/projman/README.md",
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
"mcpServers": ["gitea"],
"integrationFile": "claude-md-integration.md"
}, },
{ {
"name": "project-hygiene", "name": "project-hygiene",
"version": "0.1.0", "version": "0.1.0",
"description": "Post-task cleanup hook that removes temp files and manages orphaned files", "description": "Post-task cleanup hook that removes temp files and manages orphaned files",
"source": "./plugins/project-hygiene" "source": "./plugins/project-hygiene",
"author": {
"name": "Leo Miranda",
"email": "leobmiranda@gmail.com"
},
"homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/project-hygiene/README.md",
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
"mcpServers": [],
"integrationFile": "claude-md-integration.md",
"hooks": ["PostToolUse"]
}, },
{ {
"name": "cmdb-assistant", "name": "cmdb-assistant",
"version": "1.0.0", "version": "1.0.0",
"description": "NetBox CMDB integration for infrastructure management", "description": "NetBox CMDB integration for infrastructure management",
"source": "./plugins/cmdb-assistant" "source": "./plugins/cmdb-assistant",
"author": {
"name": "Leo Miranda",
"email": "leobmiranda@gmail.com"
},
"homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/cmdb-assistant/README.md",
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
"mcpServers": ["netbox"],
"integrationFile": "claude-md-integration.md"
}, },
{ {
"name": "claude-config-maintainer", "name": "claude-config-maintainer",
"version": "1.0.0", "version": "1.0.0",
"description": "CLAUDE.md optimization and maintenance for Claude Code projects", "description": "CLAUDE.md optimization and maintenance for Claude Code projects",
"source": "./plugins/claude-config-maintainer" "source": "./plugins/claude-config-maintainer",
"author": {
"name": "Leo Miranda",
"email": "leobmiranda@gmail.com"
},
"homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/claude-config-maintainer/README.md",
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
"mcpServers": [],
"integrationFile": "claude-md-integration.md"
} }
] ],
"pluginDetection": {
"mcpServerMapping": {
"gitea": "projman",
"netbox": "cmdb-assistant"
},
"hookMapping": {
"PostToolUse:Write|Edit": "project-hygiene"
}
}
} }

View File

@@ -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"
}
}
}
}

View File

@@ -4,7 +4,37 @@ All notable changes to support-claude-mktplace will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
## [Unreleased] ## [2.2.0] - 2026-01-20
### Added
- `/review` command for pre-sprint-close code quality checks (projman)
- `/test-check` command for test verification before sprint close (projman)
- `code-reviewer` agent for structured code review workflow (projman)
- Validation script (`scripts/validate-marketplace.sh`) for marketplace compliance
- `homepage` and `repository` fields to all plugin entries in marketplace.json
- `metadata` wrapper for description/version in marketplace.json
- Keywords to all plugin manifests for better discoverability
- `commands` and `agents` directory references to plugin manifests
- Versioning rule: version displayed only in main README.md title
### Changed
- Updated marketplace.json with required fields per Claude Code spec
- Fixed installation documentation to use official Claude Code methods
- Prioritized public HTTPS URL over Tailscale SSH URL in documentation
- Updated all plugin manifests with author, homepage, repository, license fields
- Consolidated version display to main README.md title only
- Removed version numbers from plugin documentation titles
### Fixed
- Plugin manifests now include all required fields per Claude Code spec
- Installation section uses `extraKnownMarketplaces` instead of undocumented `pluginMarketplace`
### Removed
- `docs/references/` directory (obsolete planning documents)
- Version numbers from individual plugin README titles
- Version section from plugins/projman/README.md
## [2.1.0] - 2026-01-15
### Added ### Added
- `docs/CANONICAL-PATHS.md` - Single source of truth for all file paths - `docs/CANONICAL-PATHS.md` - Single source of truth for all file paths
@@ -15,16 +45,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
- Update documentation (`docs/UPDATING.md`) - Update documentation (`docs/UPDATING.md`)
- `/initial-setup` slash command - `/initial-setup` slash command
- File creation governance rules in CLAUDE.md - File creation governance rules in CLAUDE.md
- Architecture diagram specifications in `docs/architecture/`
- `.scratch/` directory for transient work - `.scratch/` directory for transient work
- `scripts/` directory for setup automation - `scripts/` directory for setup automation
- `docs/architecture/` for Draw.io diagrams
- `docs/workflows/` for workflow documentation
### Changed ### Changed
- Replaced `docs/CORRECT-ARCHITECTURE.md` reference with `docs/CANONICAL-PATHS.md` - Replaced `docs/CORRECT-ARCHITECTURE.md` reference with `docs/CANONICAL-PATHS.md`
- Added mandatory path verification section to CLAUDE.md - Added mandatory path verification section to CLAUDE.md
- Reorganized documentation into `docs/references/`, `docs/architecture/`, `docs/workflows/`
- Updated CLAUDE.md with file creation governance - Updated CLAUDE.md with file creation governance
### Fixed ### Fixed
@@ -32,21 +58,44 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
### Removed ### Removed
- Organization/workspace GID variable (no longer needed) - Organization/workspace GID variable (no longer needed)
- Deprecated `cmdb-assistant/` plugin
- Development output files (test scripts, status reports) - Development output files (test scripts, status reports)
- IDE-specific workspace files - IDE-specific workspace files
- Stray files from project root - Stray files from project root
## [0.1.0] - Initial Release ## [2.0.0] - 2026-01-06
### Added ### Added
- projman plugin for sprint management - Full Gitea integration with wiki, milestones, dependencies
- Parallel execution batching via dependency graph
- Wiki tools for lessons learned (`create_lesson`, `search_lessons`)
- Milestone tools (`list_milestones`, `create_milestone`, `update_milestone`)
- Dependency tools (`list_issue_dependencies`, `create_issue_dependency`, `get_execution_order`)
- Validation tools (`validate_repo_org`, `get_branch_protection`)
- MCP servers bundled inside plugins (not shared at root)
### Changed
- MCP server architecture: bundled in plugins instead of shared at root
- Configuration uses `${CLAUDE_PLUGIN_ROOT}/mcp-servers/` paths
## [1.0.0] - 2025-12-15
### Added
- projman plugin with basic sprint commands
- `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close` commands
- `/labels-sync` command for label taxonomy synchronization
- Three-agent model (planner, orchestrator, executor)
- Gitea MCP server with issue and label tools
- 43-label taxonomy system
- Hybrid configuration system (system + project level)
- Branch-aware security model
## [0.1.0] - 2025-12-01
### Added
- Initial repository structure
- projman plugin structure (planned)
- projman-pmo plugin structure (planned) - projman-pmo plugin structure (planned)
- project-hygiene plugin for cleanup automation - project-hygiene plugin for cleanup automation
- Gitea MCP server - claude-config-maintainer plugin structure
- Wiki.js MCP server - cmdb-assistant plugin structure
- 43-label taxonomy system - Basic marketplace manifest
- Lessons learned capture system
- Hybrid configuration system (system + project level)
- Three-agent model (planner, orchestrator, executor)
- Branch-aware security model

626
CLAUDE.md
View File

@@ -1,478 +1,216 @@
# CLAUDE.md # CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. This file provides guidance to Claude Code when working with code in this repository.
## Project Overview ## Project Overview
This repository contains Claude Code plugins for project management: **Repository:** support-claude-mktplace
**Version:** 2.2.0
**Status:** Production Ready
1. **`projman`** - Single-repository project management plugin with Gitea integration A Claude Code plugin marketplace containing:
2. **`projman-pmo`** - Multi-project PMO coordination plugin
3. **`claude-config-maintainer`** - CLAUDE.md optimization and maintenance plugin
4. **`cmdb-assistant`** - NetBox CMDB integration for infrastructure management
These plugins transform a proven 15-sprint workflow into reusable, distributable tools for managing software development with Claude Code, Gitea, and agile methodologies. | Plugin | Description | Version |
|--------|-------------|---------|
| `projman` | Sprint planning and project management with Gitea integration | 2.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: ## Repository Structure
- `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**
``` ```
bandit/support-claude-mktplace/ support-claude-mktplace/
├── .claude-plugin/ ├── .claude-plugin/
│ └── marketplace.json │ └── marketplace.json # Marketplace manifest
├── plugins/ # ← ALL PLUGINS (with bundled MCP servers) ├── plugins/
│ ├── projman/ # ← PROJECT PLUGIN │ ├── projman/ # Sprint management
│ │ ├── .claude-plugin/ │ │ ├── .claude-plugin/plugin.json
│ │ │ └── plugin.json
│ │ ├── .mcp.json # Points to ${CLAUDE_PLUGIN_ROOT}/mcp-servers/
│ │ ├── mcp-servers/ # ← MCP servers BUNDLED IN plugin
│ │ │ └── gitea/ # Gitea + Wiki tools
│ │ │ ├── .venv/
│ │ │ ├── requirements.txt
│ │ │ ├── mcp_server/
│ │ │ └── tests/
│ │ ├── commands/
│ │ │ ├── sprint-plan.md
│ │ │ ├── sprint-start.md
│ │ │ ├── sprint-status.md
│ │ │ ├── sprint-close.md
│ │ │ ├── labels-sync.md
│ │ │ └── initial-setup.md
│ │ ├── agents/
│ │ │ ├── planner.md
│ │ │ ├── orchestrator.md
│ │ │ └── executor.md
│ │ ├── skills/
│ │ │ └── label-taxonomy/
│ │ │ └── labels-reference.md
│ │ ├── README.md
│ │ └── CONFIGURATION.md
│ ├── projman-pmo/ # ← PMO PLUGIN
│ │ ├── .claude-plugin/
│ │ │ └── plugin.json
│ │ ├── .mcp.json │ │ ├── .mcp.json
│ │ ├── commands/ │ │ ├── mcp-servers/gitea/ # Bundled MCP server
│ │ ├── agents/ │ │ ├── commands/ # 8 commands
│ │ │ ── pmo-coordinator.md │ │ │ ── sprint-plan.md, sprint-start.md, sprint-status.md
│ │ ── README.md │ │ ── sprint-close.md, labels-sync.md, initial-setup.md
├── cmdb-assistant/ # ← CMDB PLUGIN └── review.md, test-check.md
│ │ ├── .claude-plugin/ │ │ ├── agents/ # 4 agents
│ │ │ ── plugin.json │ │ │ ── planner.md, orchestrator.md, executor.md
│ │ ├── .mcp.json # Points to ${CLAUDE_PLUGIN_ROOT}/mcp-servers/ │ │ │ └── code-reviewer.md
│ │ ── mcp-servers/ # ← MCP servers BUNDLED IN plugin │ │ ── skills/label-taxonomy/
│ │ └── netbox/ ├── claude-config-maintainer/
│ │ ├── .venv/ ├── cmdb-assistant/
│ │ ├── requirements.txt └── project-hygiene/
│ │ │ └── mcp_server/ ├── scripts/
│ ├── commands/ │ ├── setup.sh, post-update.sh
│ └── agents/ │ └── validate-marketplace.sh # Marketplace compliance validation
│ └── project-hygiene/ # ← CLEANUP PLUGIN
│ └── ...
├── scripts/ # Setup and maintenance scripts
│ ├── setup.sh
│ └── post-update.sh
└── docs/ └── docs/
├── CANONICAL-PATHS.md # Single source of truth for paths
└── references/
``` ```
### Key Design Decisions
**MCP Servers (Bundled in Plugins):**
- **Gitea MCP**: Issues, labels, wiki, milestones, dependencies (bundled in projman)
- **NetBox MCP**: Infrastructure management (bundled in cmdb-assistant)
- Servers are **bundled inside each plugin** that needs them
- This ensures plugins work when cached by Claude Code
**Python Implementation:**
- Python chosen over Node.js for MCP servers
- Better suited for configuration management and modular code
- Easier to maintain and extend
- Virtual environment (.venv) per MCP server
**Hybrid Configuration:**
- **System-level**: `~/.config/claude/gitea.env` (credentials)
- **Project-level**: `project-root/.env` (repository specification)
- Merge strategy: project overrides system
- Benefits: Single token per service, easy multi-project setup
**Skills as Knowledge, Not Orchestrators:**
- Skills provide supporting knowledge loaded when relevant
- Agents are the primary interface
- Reduces token usage
- Makes knowledge reusable across agents
**Branch Detection:**
- Two layers: CLAUDE.md (file access) + Plugin agents (tool usage)
- Defense in depth approach
- Plugin works with or without CLAUDE.md
## Multi-Project Context (PMO Plugin)
The `projman-pmo` plugin coordinates interdependent projects across an organization. Example use cases:
- Main product repository
- Marketing/documentation sites
- Extracted services
- Supporting tools
PMO plugin adds:
- Cross-project issue aggregation (all repos in organization)
- Dependency tracking and visualization
- Resource allocation across projects
- Deployment coordination
- Multi-project prioritization
- Company-wide lessons learned search
**Configuration Difference:**
- PMO operates at company level (no `GITEA_REPO`)
- Accesses all repositories in organization
- Aggregates issues and lessons across projects
Build PMO plugin AFTER projman is working and validated.
## Testing Approach
**Local Marketplace:**
Create local marketplace for plugin development:
```
~/projman-dev-marketplace/
├── .claude-plugin/
│ └── marketplace.json
└── projman/ # Symlink to plugin directory
```
**Integration Testing:**
Test in a real repository with actual Gitea instance before distribution.
**Success Metrics:**
- Sprint planning time reduced 40%
- Manual steps eliminated: 10+ per sprint
- Lessons learned capture rate: 100% (vs 0% before)
- Label accuracy on issues: 90%+
- User satisfaction: Better than current manual workflow
## Important Notes
- **Never modify docker-compose files with 'version' attribute** - It's obsolete
- **Focus on implementation, not over-engineering** - This system has been validated over 15 sprints
- **Lessons learned is critical** - Prevents repeated mistakes (e.g., Claude infinite loops)
- **Type/Refactor label** - Newly implemented at org level for architectural work
- **Branch detection must be 100% reliable** - Prevents production accidents
- **Python for MCP servers** - Use Python 3.8+ with virtual environments
- **CLI tools forbidden** - Use MCP tools exclusively, never CLI tools like `tea` or `gh`
## CRITICAL: Rules You MUST Follow ## CRITICAL: Rules You MUST Follow
### DO NOT MODIFY .gitignore Without Explicit Permission ### File Operations
- This is a **private repository** - credentials in `.env` files are intentional - **NEVER** create files in repository root unless listed in "Allowed Root Files"
- **NEVER** add `.env` or `.env.*` to .gitignore - **NEVER** modify `.gitignore` without explicit permission
- **NEVER** add venv patterns unless explicitly asked - **ALWAYS** use `.scratch/` for temporary/exploratory work
- If you think something should be ignored, ASK FIRST - **ALWAYS** verify paths against `docs/CANONICAL-PATHS.md` before creating files
### Plugin Structure Requirements ### Plugin Development
- **plugin.json MUST be in `.claude-plugin/` directory** - NOT in plugin root - **plugin.json MUST be in `.claude-plugin/` directory** (not plugin root)
- Every plugin in the repo MUST be listed in the marketplace.json - **Every plugin MUST be listed in marketplace.json**
- After creating/modifying a plugin, VERIFY it's in the marketplace - **MCP servers MUST use venv python path**: `${CLAUDE_PLUGIN_ROOT}/mcp-servers/{name}/.venv/bin/python`
- **CLI tools forbidden** - Use MCP tools exclusively (never `tea`, `gh`, etc.)
### Hooks Syntax (Claude Code Official) ### Hooks (Valid Events Only)
- **Valid events**: `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact` `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
- **INVALID events**: `task-completed`, `file-changed`, `git-commit-msg-needed` (these DO NOT exist)
- Hooks schema: **INVALID:** `task-completed`, `file-changed`, `git-commit-msg-needed`
```json
{ ### Allowed Root Files
"hooks": { `CLAUDE.md`, `README.md`, `LICENSE`, `CHANGELOG.md`, `.gitignore`, `.env.example`
"EventName": [
{ ### Allowed Root Directories
"matcher": "optional-pattern", `.claude/`, `.claude-plugin/`, `.claude-plugins/`, `.scratch/`, `docs/`, `hooks/`, `plugins/`, `scripts/`
"hooks": [
{ ## Architecture
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/path/to/script.sh" ### Four-Agent Model
}
] | Agent | Personality | Responsibilities |
} |-------|-------------|------------------|
] | **Planner** | Thoughtful, methodical | Sprint planning, architecture analysis, issue creation, lesson search |
} | **Orchestrator** | Concise, action-oriented | Sprint execution, parallel batching, Git operations, lesson capture |
} | **Executor** | Implementation-focused | Code implementation, branch management, MR creation |
| **Code Reviewer** | Thorough, practical | Pre-close quality review, security scan, test verification |
### MCP Server Tools (Gitea)
| Category | Tools |
|----------|-------|
| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment` |
| Labels | `get_labels`, `suggest_labels`, `create_label` |
| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone` |
| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `get_execution_order` |
| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `create_lesson`, `search_lessons` |
| Validation | `validate_repo_org`, `get_branch_protection` |
### Hybrid Configuration
| Level | Location | Purpose |
|-------|----------|---------|
| System | `~/.config/claude/gitea.env` | Credentials (GITEA_URL, GITEA_TOKEN, GITEA_ORG) |
| Project | `.env` in project root | Repository specification (GITEA_REPO) |
### Branch-Aware Security
| Branch Pattern | Mode | Capabilities |
|----------------|------|--------------|
| `development`, `feat/*` | Development | Full access |
| `staging` | Staging | Read-only code, can create issues |
| `main`, `master` | Production | Read-only, emergency only |
## Label Taxonomy
43 labels total: 27 organization + 16 repository
**Organization:** Agent/2, Complexity/3, Efforts/5, Priority/4, Risk/3, Source/4, Type/6
**Repository:** Component/9, Tech/7
Sync with `/labels-sync` command.
## Lessons Learned System
Stored in Gitea Wiki under `lessons-learned/sprints/`.
**Workflow:**
1. Orchestrator captures at sprint close via MCP tools
2. Planner searches at sprint start using `search_lessons`
3. Tags enable cross-project discovery
## Common Operations
### Adding a New Plugin
1. Create `plugins/{name}/.claude-plugin/plugin.json`
2. Add entry to `.claude-plugin/marketplace.json`
3. Create `README.md` and `claude-md-integration.md`
4. Run `./scripts/validate-marketplace.sh`
5. Update `CHANGELOG.md`
### Adding a Command to projman
1. Create `plugins/projman/commands/{name}.md`
2. Update `plugins/projman/README.md`
3. Update marketplace description if significant
### Validation
```bash
./scripts/validate-marketplace.sh # Validates all manifests
``` ```
### MCP Server Configuration ## Path Verification Protocol
- MCP servers MUST use venv python: `${CLAUDE_PLUGIN_ROOT}/../../mcp-servers/NAME/.venv/bin/python`
- NEVER use bare `python` command - always use venv path
- Test MCP servers after any config change
### Before Completing Any Plugin Work **Before creating any file:**
1. Verify plugin.json is in `.claude-plugin/` directory
2. Verify plugin is listed in marketplace.json 1. Read `docs/CANONICAL-PATHS.md`
3. Test MCP server configs load correctly 2. List all paths to be created/modified
4. Verify hooks use valid event types 3. Verify each against canonical paths
5. Check .gitignore wasn't modified inappropriately 4. If not in canonical paths, STOP and ask
## Documentation Index ## Documentation Index
This repository contains comprehensive planning documentation: | Document | Purpose |
|----------|---------|
| `docs/CANONICAL-PATHS.md` | **Single source of truth** for paths |
| `docs/UPDATING.md` | Update guide for the marketplace |
| `plugins/projman/CONFIGURATION.md` | Projman setup guide |
| `plugins/projman/README.md` | Projman full documentation |
- **`docs/CANONICAL-PATHS.md`** - ⚠️ SINGLE SOURCE OF TRUTH for all paths (MANDATORY reading before any file operations) ## Versioning and Changelog Rules
- **`docs/DOCUMENT-INDEX.md`** - Complete guide to all planning documents
- **`docs/projman-implementation-plan-updated.md`** - Full 12-phase implementation plan
- **`docs/projman-python-quickstart.md`** - Python-specific implementation guide
- **`docs/two-mcp-architecture-guide.md`** - Deep dive into two-MCP architecture
**Start with:** `docs/DOCUMENT-INDEX.md` for navigation guidance ### Version Display
**The marketplace version is displayed ONLY in the main `README.md` title.**
## Recent Updates (Updated: 2025-06-11) - Format: `# Claude Code Marketplace - vX.Y.Z`
- Do NOT add version numbers to individual plugin documentation titles
- Do NOT add version numbers to configuration guides
- Do NOT add version numbers to CLAUDE.md or other docs
### Planning Phase Complete ### Changelog Maintenance (MANDATORY)
- Comprehensive 12-phase implementation plan finalized **`CHANGELOG.md` is the authoritative source for version history.**
- Architecture decisions documented and validated
- Two-MCP-server approach confirmed (Gitea + Wiki.js)
- Python selected for MCP server implementation
- Hybrid configuration strategy defined (system + project level)
- Wiki.js structure planned with configurable base path
- Repository structure designed with shared MCP servers
### Key Architectural Decisions Made When releasing a new version:
1. **Shared MCP Servers**: Both plugins use the same MCP codebase at `mcp-servers/` 1. Update main `README.md` title with new version
2. **Mode Detection**: MCP servers detect project vs company-wide mode via environment variables 2. Update `CHANGELOG.md` with:
3. **Python Implementation**: MCP servers written in Python (not Node.js) for better configuration handling - Version number and date: `## [X.Y.Z] - YYYY-MM-DD`
4. **Wiki.js Integration**: Lessons learned and documentation moved to Wiki.js for better collaboration - **Added**: New features, commands, files
5. **Hybrid Config**: System-level credentials + project-level paths for flexibility - **Changed**: Modifications to existing functionality
- **Fixed**: Bug fixes
- **Removed**: Deleted features, files, deprecated items
3. Update `marketplace.json` metadata version
4. Update plugin `plugin.json` versions if plugin-specific changes
### Next Steps ### Version Format
- Begin Phase 1.1a: Gitea MCP Server implementation - Follow [Semantic Versioning](https://semver.org/): MAJOR.MINOR.PATCH
- Set up Python virtual environments - MAJOR: Breaking changes
- Create configuration loaders - MINOR: New features, backward compatible
- Implement core Gitea tools (issues, labels) - PATCH: Bug fixes, minor improvements
- Write integration tests
---
**Last Updated:** 2026-01-20

21
LICENSE Normal file
View 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.

144
README.md
View File

@@ -1,22 +1,23 @@
# Claude Code Marketplace - Bandit Labs # Claude Code Marketplace - v2.2.0
A collection of Claude Code plugins for project management, infrastructure automation, and development workflows. A collection of Claude Code plugins for project management, infrastructure automation, and development workflows.
## Plugins ## Plugins
### [projman](./plugins/projman/README.md) v2.0.0 ### [projman](./plugins/projman/README.md)
**Sprint Planning and Project Management** **Sprint Planning and Project Management**
AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sprint workflow into a distributable plugin. AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sprint workflow into a distributable plugin.
- Three-agent model: Planner, Orchestrator, Executor - Three-agent model: Planner, Orchestrator, Executor, Code Reviewer
- Intelligent label suggestions from 43-label taxonomy - Intelligent label suggestions from 43-label taxonomy
- Lessons learned capture via Gitea Wiki - Lessons learned capture via Gitea Wiki
- Native issue dependencies with parallel execution - Native issue dependencies with parallel execution
- Milestone management for sprint organization - Milestone management for sprint organization
- Branch-aware security (development/staging/production) - Branch-aware security (development/staging/production)
- Pre-sprint-close code quality review and test verification
**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup` **Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup`, `/review`, `/test-check`
### [claude-config-maintainer](./plugins/claude-config-maintainer/README.md) ### [claude-config-maintainer](./plugins/claude-config-maintainer/README.md)
**CLAUDE.md Optimization and Maintenance** **CLAUDE.md Optimization and Maintenance**
@@ -89,67 +90,92 @@ Comprehensive NetBox REST API integration for infrastructure management.
- Python 3.10+ - Python 3.10+
- Access to target services (Gitea, NetBox as needed) - Access to target services (Gitea, NetBox as needed)
### Quick Start ### Add Marketplace to Claude Code
1. **Clone the repository:** **Option 1 - CLI command (recommended):**
```bash ```bash
git clone ssh://git@hotserv.tailc9b278.ts.net:2222/bandit/support-claude-mktplace.git /plugin marketplace add https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git
cd support-claude-mktplace ```
```
2. **Install MCP server dependencies:** **Option 2 - Settings file (for team distribution):**
```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) Add to `.claude/settings.json` in your target project:
cd ../../../cmdb-assistant/mcp-servers/netbox ```json
python3 -m venv .venv {
source .venv/bin/activate "extraKnownMarketplaces": {
pip install -r requirements.txt "support-claude-mktplace": {
deactivate "source": {
``` "source": "git",
"url": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git"
}
}
}
}
```
3. **Configure system-level credentials:** **Option 3 - Local development:**
```bash ```bash
mkdir -p ~/.config/claude # Clone the repository first
git clone https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git
# Gitea credentials # Then add from local path
cat > ~/.config/claude/gitea.env << 'EOF' /plugin marketplace add /path/to/support-claude-mktplace
GITEA_URL=https://gitea.example.com ```
GITEA_TOKEN=your_token
GITEA_ORG=your_org
EOF
# NetBox credentials **Alternative SSH URL (for authenticated access):**
cat > ~/.config/claude/netbox.env << 'EOF' ```
NETBOX_API_URL=https://netbox.example.com/api ssh://git@hotserv.tailc9b278.ts.net:2222/personal-projects/support-claude-mktplace.git
NETBOX_API_TOKEN=your_token ```
EOF
chmod 600 ~/.config/claude/*.env ### Configure MCP Server Dependencies
```
4. **Configure project-level settings:** If using plugins with MCP servers (projman, cmdb-assistant), install dependencies:
```bash
# In your target project root
cat > .env << 'EOF'
GITEA_REPO=your-repository-name
EOF
```
5. **Add marketplace to Claude Code:** ```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
Add to your project's `.claude/settings.json`: # NetBox MCP (for cmdb-assistant)
```json cd ../../../cmdb-assistant/mcp-servers/netbox
{ python3 -m venv .venv
"pluginMarketplace": "/path/to/support-claude-mktplace" 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 ## Repository Structure
@@ -183,9 +209,10 @@ support-claude-mktplace/
│ ├── CANONICAL-PATHS.md # Single source of truth for paths │ ├── CANONICAL-PATHS.md # Single source of truth for paths
│ └── references/ │ └── references/
└── scripts/ # Setup and maintenance scripts └── scripts/ # Setup and maintenance scripts
└── validate-marketplace.sh # Marketplace compliance validation
``` ```
## Key Features (v2.0.0) ## Key Features
### Parallel Execution ### Parallel Execution
Tasks are batched by dependency graph for optimal parallel execution: Tasks are batched by dependency graph for optimal parallel execution:
@@ -212,9 +239,10 @@ All agents use MCP tools exclusively. CLI tools like `tea` or `gh` are forbidden
## License ## License
MIT License - Bandit Labs MIT License
## Support ## Support
- **Issues**: Contact repository maintainer - **Issues**: Contact repository maintainer
- **Repository**: `ssh://git@hotserv.tailc9b278.ts.net:2222/bandit/support-claude-mktplace.git` - **Repository**: `https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git`
- **SSH URL**: `ssh://git@hotserv.tailc9b278.ts.net:2222/personal-projects/support-claude-mktplace.git`

View File

@@ -2,7 +2,7 @@
**This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.** **This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.**
Last Updated: 2025-12-15 Last Updated: 2026-01-20
--- ---
@@ -11,12 +11,13 @@ Last Updated: 2025-12-15
``` ```
support-claude-mktplace/ support-claude-mktplace/
├── .claude/ # Claude Code local settings ├── .claude/ # Claude Code local settings
├── .claude-plugin/ # Marketplace manifest (bandit-claude-marketplace) ├── .claude-plugin/ # Marketplace manifest (claude-code-marketplace)
│ └── marketplace.json │ └── marketplace.json
├── .scratch/ # Transient work (auto-cleaned) ├── .scratch/ # Transient work (auto-cleaned)
├── docs/ # All documentation ├── docs/ # All documentation
│ ├── architecture/ # Draw.io diagrams and specs │ ├── architecture/ # Draw.io diagrams and specs
│ ├── references/ # Reference specifications │ ├── CANONICAL-PATHS.md # This file - single source of truth
│ ├── UPDATING.md # Update guide
│ └── workflows/ # Workflow documentation │ └── workflows/ # Workflow documentation
├── hooks/ # Shared hooks (if any) ├── hooks/ # Shared hooks (if any)
├── plugins/ # ALL plugins with bundled MCP servers ├── plugins/ # ALL plugins with bundled MCP servers
@@ -26,7 +27,8 @@ support-claude-mktplace/
│ │ │ └── gitea/ # Gitea + Wiki tools │ │ │ └── gitea/ # Gitea + Wiki tools
│ │ ├── commands/ │ │ ├── commands/
│ │ ├── agents/ │ │ ├── agents/
│ │ ── skills/ │ │ ── skills/
│ │ └── claude-md-integration.md # CLAUDE.md integration snippet
│ ├── projman-pmo/ │ ├── projman-pmo/
│ ├── project-hygiene/ │ ├── project-hygiene/
│ ├── cmdb-assistant/ │ ├── cmdb-assistant/
@@ -34,11 +36,17 @@ support-claude-mktplace/
│ │ ├── mcp-servers/ # MCP servers bundled IN plugin │ │ ├── mcp-servers/ # MCP servers bundled IN plugin
│ │ │ └── netbox/ │ │ │ └── netbox/
│ │ ├── commands/ │ │ ├── commands/
│ │ ── agents/ │ │ ── agents/
│ └── claude-config-maintainer/ │ └── claude-md-integration.md # CLAUDE.md integration snippet
│ ├── claude-config-maintainer/
│ │ ├── .claude-plugin/
│ │ ├── commands/
│ │ ├── agents/
│ │ └── claude-md-integration.md # CLAUDE.md integration snippet
│ └── project-hygiene/
│ ├── .claude-plugin/ │ ├── .claude-plugin/
│ ├── commands/ │ ├── hooks/
│ └── agents/ │ └── claude-md-integration.md # CLAUDE.md integration snippet
├── scripts/ # Setup and maintenance scripts ├── scripts/ # Setup and maintenance scripts
├── CLAUDE.md ├── CLAUDE.md
├── README.md ├── README.md
@@ -60,6 +68,7 @@ support-claude-mktplace/
| Plugin commands | `plugins/{plugin-name}/commands/` | `plugins/projman/commands/` | | Plugin commands | `plugins/{plugin-name}/commands/` | `plugins/projman/commands/` |
| Plugin agents | `plugins/{plugin-name}/agents/` | `plugins/projman/agents/` | | Plugin agents | `plugins/{plugin-name}/agents/` | `plugins/projman/agents/` |
| Plugin .mcp.json | `plugins/{plugin-name}/.mcp.json` | `plugins/projman/.mcp.json` | | Plugin .mcp.json | `plugins/{plugin-name}/.mcp.json` | `plugins/projman/.mcp.json` |
| Plugin integration snippet | `plugins/{plugin-name}/claude-md-integration.md` | `plugins/projman/claude-md-integration.md` |
### MCP Server Paths (Bundled in Plugins) ### MCP Server Paths (Bundled in Plugins)
@@ -82,10 +91,10 @@ MCP servers are now **bundled inside each plugin** to ensure they work when plug
| Type | Location | | Type | Location |
|------|----------| |------|----------|
| Reference specs | `docs/references/` |
| Architecture diagrams | `docs/architecture/` | | Architecture diagrams | `docs/architecture/` |
| Workflow docs | `docs/workflows/` | | Workflow docs | `docs/workflows/` |
| This file | `docs/CANONICAL-PATHS.md` | | This file | `docs/CANONICAL-PATHS.md` |
| Update guide | `docs/UPDATING.md` |
--- ---
@@ -149,5 +158,7 @@ MCP servers are bundled inside each plugin (not shared at root) because:
| Date | Change | By | | Date | Change | By |
|------|--------|-----| |------|--------|-----|
| 2026-01-20 | Removed docs/references/ (obsolete planning docs) | Claude Code |
| 2026-01-19 | Added claude-md-integration.md path pattern for plugin integration snippets | Claude Code |
| 2025-12-15 | Restructured: MCP servers now bundled in plugins | Claude Code | | 2025-12-15 | Restructured: MCP servers now bundled in plugins | Claude Code |
| 2025-12-12 | Initial creation | Claude Code | | 2025-12-12 | Initial creation | Claude Code |

View File

@@ -15,7 +15,7 @@ git pull origin main
## What the Post-Update Script Does ## What the Post-Update Script Does
1. **Updates Python dependencies** for Gitea and Wiki.js MCP servers 1. **Updates Python dependencies** for MCP servers
2. **Shows recent changelog entries** so you know what changed 2. **Shows recent changelog entries** so you know what changed
3. **Validates your configuration** is still compatible 3. **Validates your configuration** is still compatible
@@ -30,7 +30,6 @@ If the changelog mentions new environment variables:
1. Check the variable name and purpose in the changelog 1. Check the variable name and purpose in the changelog
2. Add it to the appropriate config file: 2. Add it to the appropriate config file:
- Gitea variables → `~/.config/claude/gitea.env` - Gitea variables → `~/.config/claude/gitea.env`
- Wiki.js variables → `~/.config/claude/wikijs.env`
- Project variables → `.env` in your project root - Project variables → `.env` in your project root
### New MCP Server Features ### New MCP Server Features
@@ -38,7 +37,7 @@ If the changelog mentions new environment variables:
If a new MCP server tool is added: If a new MCP server tool is added:
1. The post-update script handles dependency installation 1. The post-update script handles dependency installation
2. Check `docs/references/MCP-*.md` for usage documentation 2. Check `plugins/projman/README.md` for usage documentation
3. New tools are available immediately after update 3. New tools are available immediately after update
### Breaking Changes ### Breaking Changes
@@ -51,15 +50,7 @@ Breaking changes will be clearly marked in CHANGELOG.md with migration instructi
```bash ```bash
# Rebuild virtual environment # Rebuild virtual environment
cd mcp-servers/gitea cd plugins/projman/mcp-servers/gitea
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
deactivate
# Repeat for wikijs
cd ../wikijs
rm -rf .venv rm -rf .venv
python3 -m venv .venv python3 -m venv .venv
source .venv/bin/activate source .venv/bin/activate
@@ -76,7 +67,7 @@ deactivate
### MCP server won't start ### MCP server won't start
1. Check Python version: `python3 --version` (requires 3.10+) 1. Check Python version: `python3 --version` (requires 3.10+)
2. Verify venv exists: `ls mcp-servers/gitea/.venv` 2. Verify venv exists: `ls plugins/projman/mcp-servers/gitea/.venv`
3. Check logs for specific errors 3. Check logs for specific errors
## Version Pinning ## Version Pinning
@@ -88,7 +79,7 @@ To stay on a specific version:
git tag git tag
# Checkout specific version # Checkout specific version
git checkout v1.0.0 git checkout v2.2.0
# Run post-update # Run post-update
./scripts/post-update.sh ./scripts/post-update.sh
@@ -96,6 +87,7 @@ git checkout v1.0.0
## Getting Help ## Getting Help
- Check `docs/references/` for component documentation - Check `plugins/projman/README.md` for projman documentation
- Check `plugins/projman/CONFIGURATION.md` for setup guide
- Review CHANGELOG.md for recent changes - Review CHANGELOG.md for recent changes
- Search existing issues in Gitea - Search existing issues in Gitea

View File

@@ -2,7 +2,7 @@
**Target File:** `docs/architecture/agent-workflow.drawio` **Target File:** `docs/architecture/agent-workflow.drawio`
**Purpose:** Shows when Planner, Orchestrator, and Executor agents trigger during sprint lifecycle. **Purpose:** Shows when Planner, Orchestrator, Executor, and Code Reviewer agents trigger during sprint lifecycle.
**Diagram Type:** Swimlane / Sequence Diagram **Diagram Type:** Swimlane / Sequence Diagram
@@ -16,8 +16,8 @@
| planner-lane | Planner Agent | #4A90D9 | 2 | | planner-lane | Planner Agent | #4A90D9 | 2 |
| orchestrator-lane | Orchestrator Agent | #7CB342 | 3 | | orchestrator-lane | Orchestrator Agent | #7CB342 | 3 |
| executor-lane | Executor Agent | #FF9800 | 4 | | executor-lane | Executor Agent | #FF9800 | 4 |
| gitea-lane | Gitea | #9E9E9E | 5 | | reviewer-lane | Code Reviewer Agent | #9C27B0 | 5 |
| wikijs-lane | Wiki.js | #9E9E9E | 6 (rightmost) | | gitea-lane | Gitea (Issues + Wiki) | #9E9E9E | 6 (rightmost) |
--- ---
@@ -30,7 +30,7 @@
| p1-start | /sprint-plan | rounded-rect | user-lane | 1 | | p1-start | /sprint-plan | rounded-rect | user-lane | 1 |
| p1-activate | Planner Activates | rectangle | planner-lane | 2 | | p1-activate | Planner Activates | rectangle | planner-lane | 2 |
| p1-search-lessons | Search Lessons Learned | rectangle | planner-lane | 3 | | p1-search-lessons | Search Lessons Learned | rectangle | planner-lane | 3 |
| p1-wikijs-query | Query Past Lessons | rectangle | wikijs-lane | 4 | | p1-gitea-wiki-query | Query Past Lessons (Wiki) | rectangle | gitea-lane | 4 |
| p1-return-lessons | Return Relevant Lessons | rectangle | planner-lane | 5 | | p1-return-lessons | Return Relevant Lessons | rectangle | planner-lane | 5 |
| p1-clarify | Ask Clarifying Questions | diamond | planner-lane | 6 | | p1-clarify | Ask Clarifying Questions | diamond | planner-lane | 6 |
| p1-user-answers | Provide Answers | rectangle | user-lane | 7 | | p1-user-answers | Provide Answers | rectangle | user-lane | 7 |
@@ -44,8 +44,8 @@
|------|----|-------|-------| |------|----|-------|-------|
| p1-start | p1-activate | invokes | solid | | p1-start | p1-activate | invokes | solid |
| p1-activate | p1-search-lessons | | solid | | p1-activate | p1-search-lessons | | solid |
| p1-search-lessons | p1-wikijs-query | GraphQL search | solid | | p1-search-lessons | p1-gitea-wiki-query | REST API (search_lessons) | solid |
| p1-wikijs-query | p1-return-lessons | lessons data | dashed | | p1-gitea-wiki-query | p1-return-lessons | lessons data | dashed |
| p1-return-lessons | p1-clarify | | solid | | p1-return-lessons | p1-clarify | | solid |
| p1-clarify | p1-user-answers | questions | solid | | p1-clarify | p1-user-answers | questions | solid |
| p1-user-answers | p1-clarify | answers | dashed | | p1-user-answers | p1-clarify | answers | dashed |
@@ -65,7 +65,7 @@
| p2-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 12 | | p2-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 12 |
| p2-fetch-issues | Fetch Sprint Issues | rectangle | orchestrator-lane | 13 | | p2-fetch-issues | Fetch Sprint Issues | rectangle | orchestrator-lane | 13 |
| p2-gitea-list | List Open Issues | rectangle | gitea-lane | 14 | | p2-gitea-list | List Open Issues | rectangle | gitea-lane | 14 |
| p2-sequence | Sequence Work | rectangle | orchestrator-lane | 15 | | p2-sequence | Sequence Work (Dependencies) | rectangle | orchestrator-lane | 15 |
| p2-dispatch | Dispatch Task | rectangle | orchestrator-lane | 16 | | p2-dispatch | Dispatch Task | rectangle | orchestrator-lane | 16 |
| p2-exec-activate | Executor Activates | rectangle | executor-lane | 17 | | p2-exec-activate | Executor Activates | rectangle | executor-lane | 17 |
| p2-implement | Implement Task | rectangle | executor-lane | 18 | | p2-implement | Implement Task | rectangle | executor-lane | 18 |
@@ -83,7 +83,7 @@
| p2-orch-activate | p2-fetch-issues | | solid | | p2-orch-activate | p2-fetch-issues | | solid |
| p2-fetch-issues | p2-gitea-list | REST API | solid | | p2-fetch-issues | p2-gitea-list | REST API | solid |
| p2-gitea-list | p2-sequence | issues data | dashed | | p2-gitea-list | p2-sequence | issues data | dashed |
| p2-sequence | p2-dispatch | | solid | | p2-sequence | p2-dispatch | parallel batching | solid |
| p2-dispatch | p2-exec-activate | execution prompt | solid | | p2-dispatch | p2-exec-activate | execution prompt | solid |
| p2-exec-activate | p2-implement | | solid | | p2-exec-activate | p2-implement | | solid |
| p2-implement | p2-update-status | | solid | | p2-implement | p2-update-status | | solid |
@@ -95,23 +95,50 @@
--- ---
## PHASE 2.5: CODE REVIEW (Pre-Close)
### Nodes
| ID | Label | Type | Lane | Sequence |
|----|-------|------|------|----------|
| p25-start | /review | rounded-rect | user-lane | 24 |
| p25-reviewer-activate | Code Reviewer Activates | rectangle | reviewer-lane | 25 |
| p25-scan-changes | Scan Recent Changes | rectangle | reviewer-lane | 26 |
| p25-check-quality | Check Code Quality | rectangle | reviewer-lane | 27 |
| p25-security-scan | Security Scan | rectangle | reviewer-lane | 28 |
| p25-report | Generate Review Report | rectangle | reviewer-lane | 29 |
| p25-complete | Review Complete | rounded-rect | reviewer-lane | 30 |
### Edges
| From | To | Label | Style |
|------|----|-------|-------|
| p25-start | p25-reviewer-activate | invokes | solid |
| p25-reviewer-activate | p25-scan-changes | | solid |
| p25-scan-changes | p25-check-quality | | solid |
| p25-check-quality | p25-security-scan | | solid |
| p25-security-scan | p25-report | | solid |
| p25-report | p25-complete | | solid |
---
## PHASE 3: SPRINT CLOSE ## PHASE 3: SPRINT CLOSE
### Nodes ### Nodes
| ID | Label | Type | Lane | Sequence | | ID | Label | Type | Lane | Sequence |
|----|-------|------|------|----------| |----|-------|------|------|----------|
| p3-start | /sprint-close | rounded-rect | user-lane | 24 | | p3-start | /sprint-close | rounded-rect | user-lane | 31 |
| p3-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 25 | | p3-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 32 |
| p3-review | Review Sprint | rectangle | orchestrator-lane | 26 | | p3-review | Review Sprint | rectangle | orchestrator-lane | 33 |
| p3-gitea-status | Get Final Status | rectangle | gitea-lane | 27 | | p3-gitea-status | Get Final Status | rectangle | gitea-lane | 34 |
| p3-capture | Capture Lessons Learned | rectangle | orchestrator-lane | 28 | | p3-capture | Capture Lessons Learned | rectangle | orchestrator-lane | 35 |
| p3-user-input | Confirm Lessons | diamond | user-lane | 29 | | p3-user-input | Confirm Lessons | diamond | user-lane | 36 |
| p3-create-wiki | Create Wiki Pages | rectangle | orchestrator-lane | 30 | | p3-create-wiki | Create Wiki Pages | rectangle | orchestrator-lane | 37 |
| p3-wikijs-create | Store Lessons | rectangle | wikijs-lane | 31 | | p3-gitea-wiki-create | Store Lessons (Wiki) | rectangle | gitea-lane | 38 |
| p3-close-issues | Close Issues | rectangle | orchestrator-lane | 32 | | p3-close-issues | Close Issues | rectangle | orchestrator-lane | 39 |
| p3-gitea-close | Mark Closed | rectangle | gitea-lane | 33 | | p3-gitea-close | Mark Closed | rectangle | gitea-lane | 40 |
| p3-complete | Sprint Closed | rounded-rect | orchestrator-lane | 34 | | p3-complete | Sprint Closed | rounded-rect | orchestrator-lane | 41 |
### Edges ### Edges
@@ -123,8 +150,8 @@
| p3-gitea-status | p3-capture | status data | dashed | | p3-gitea-status | p3-capture | status data | dashed |
| p3-capture | p3-user-input | proposed lessons | solid | | p3-capture | p3-user-input | proposed lessons | solid |
| p3-user-input | p3-create-wiki | confirmed | solid | | p3-user-input | p3-create-wiki | confirmed | solid |
| p3-create-wiki | p3-wikijs-create | GraphQL mutation | solid | | p3-create-wiki | p3-gitea-wiki-create | REST API (create_lesson) | solid |
| p3-wikijs-create | p3-close-issues | confirm | dashed | | p3-gitea-wiki-create | p3-close-issues | confirm | dashed |
| p3-close-issues | p3-gitea-close | REST API | solid | | p3-close-issues | p3-gitea-close | REST API | solid |
| p3-gitea-close | p3-complete | confirm | dashed | | p3-gitea-close | p3-complete | confirm | dashed |
@@ -133,59 +160,71 @@
## LAYOUT NOTES ## LAYOUT NOTES
``` ```
+--------+------------+---------------+------------+--------+----------+ +--------+------------+---------------+------------+----------+------------------+
| User | Planner | Orchestrator | Executor | Gitea | Wiki.js | | User | Planner | Orchestrator | Executor | Reviewer | Gitea |
+--------+------------+---------------+------------+--------+----------+ | | | | | | (Issues + Wiki) |
| | | | | | | +--------+------------+---------------+------------+----------+------------------+
| PHASE 1: SPRINT PLANNING | | | | | | | |
|---------------------------------------------------------------------+ | PHASE 1: SPRINT PLANNING |
| O | | | | | | |-------------------------------------------------------------------------------|
| | | | | | | | | O | | | | | |
| +---->| O | | | | | | | | | | | | |
| | | | | | | | | +---->| O | | | | |
| | +----------|---------------|------------|------->| O | | | | | | | | |
| | |<---------|---------------|------------|--------+ | | | | +----------|---------------|------------|--------->| O (Wiki Query) |
| | | | | | | | | | |<---------|---------------|------------|----------+ | |
| | O<> | | | | | | | | | | | | |
| O<--->+ | | | | | | | | O<> | | | | |
| | | | | | | | | O<--->+ | | | | | |
| | +----------|---------------|----------->| O | | | | | | | | | |
| | O | | | | | | | +----------|---------------|------------|--------->| O (Issues) |
| | | | | | | | | O | | | | |
|---------------------------------------------------------------------+ | | | | | | |
| PHASE 2: SPRINT EXECUTION | |-------------------------------------------------------------------------------|
|---------------------------------------------------------------------+ | PHASE 2: SPRINT EXECUTION |
| O | | | | | | |-------------------------------------------------------------------------------|
| | | | | | | | | O | | | | | |
| +-----|----------->| O | | | | | | | | | | | |
| | | | | | | | | +-----|----------->| O | | | |
| | | +-------------|----------->| O | | | | | | | | | |
| | | |<------------|------------+ | | | | | | +-------------|------------|--------->| O (Issues) |
| | | | | | | | | | | |<------------|------------|----------+ | |
| | | +------------>| O | | | | | | | | | | |
| | | | | | | | | | | +------------>| O | | |
| | | | +--------->| O | | | | | | | | | |
| | | | |<---------+ | | | | | | | +----------|--------->| O (Issues) |
| | | O<------------+ | | | | | | | | |<---------|----------+ | |
| | | | | | | | | | | O<------------+ | | | |
| | | O (loop) | | | | | | | | | | | |
| | | | | | | | | | O (loop) | | | |
|---------------------------------------------------------------------+ | | | | | | |
| PHASE 3: SPRINT CLOSE | |-------------------------------------------------------------------------------|
|---------------------------------------------------------------------+ | PHASE 2.5: CODE REVIEW |
| O | | | | | | |-------------------------------------------------------------------------------|
| | | | | | | | | O | | | | | |
| +-----|----------->| O | | | | | | | | | | | |
| | | +-------------|----------->| O | | | +-----|------------|---------------|----------->| O | |
| | | |<------------|------------+ | | | | | | | | | | |
| | | | | | | | | | | | | O->O->O | |
| O<----|-----------<+ | | | | | | | | | | | | |
| +-----|----------->| | | | | | | | | | | O | |
| | | +-------------|------------|------->| O | | | | | | | |
| | | |<------------|------------|--------+ | | |-------------------------------------------------------------------------------|
| | | +-------------|----------->| O | | | PHASE 3: SPRINT CLOSE |
| | | O | | | | |-------------------------------------------------------------------------------|
+--------+------------+---------------+------------+--------+----------+ | O | | | | | |
| | | | | | | |
| +-----|----------->| O | | | |
| | | +-------------|------------|--------->| O (Issues) |
| | | |<------------|------------|----------+ | |
| | | | | | | |
| O<----|-----------<+ | | | | |
| +-----|----------->| | | | | |
| | | +-------------|------------|--------->| O (Wiki Create) |
| | | |<------------|------------|----------+ | |
| | | +-------------|------------|--------->| O (Issues Close) |
| | | O | | | |
+--------+------------+---------------+------------+----------+------------------+
``` ```
--- ---
@@ -198,7 +237,8 @@
| Blue | #4A90D9 | Planner Agent | | Blue | #4A90D9 | Planner Agent |
| Green | #7CB342 | Orchestrator Agent | | Green | #7CB342 | Orchestrator Agent |
| Orange | #FF9800 | Executor Agent | | Orange | #FF9800 | Executor Agent |
| Gray | #9E9E9E | External Services | | Purple | #9C27B0 | Code Reviewer Agent |
| Gray | #9E9E9E | External Services (Gitea) |
--- ---
@@ -219,3 +259,13 @@
|-------|---------| |-------|---------|
| Solid | Action/Request | | Solid | Action/Request |
| Dashed | Response/Data return | | Dashed | Response/Data return |
---
## ARCHITECTURE NOTES
- **Gitea provides BOTH issue tracking AND wiki** (no separate wiki service)
- All wiki operations use Gitea REST API via MCP tools
- Lessons learned stored in Gitea Wiki under `lessons-learned/sprints/`
- MCP tools: `search_lessons`, `create_lesson`, `list_wiki_pages`, `get_wiki_page`
- Four-agent model: Planner, Orchestrator, Executor, Code Reviewer

View File

@@ -13,22 +13,26 @@
| ID | Label | Type | Color | Position | | ID | Label | Type | Color | Position |
|----|-------|------|-------|----------| |----|-------|------|-------|----------|
| projman | projman | rectangle | #4A90D9 | top-center | | projman | projman | rectangle | #4A90D9 | top-center |
| projman-pmo | projman-pmo | rectangle | #4A90D9 | top-right | | projman-pmo | projman-pmo (planned) | rectangle | #4A90D9 | top-right |
| project-hygiene | project-hygiene | rectangle | #4A90D9 | top-left | | project-hygiene | project-hygiene | rectangle | #4A90D9 | top-left |
| claude-config | claude-config-maintainer | rectangle | #4A90D9 | bottom-left |
| cmdb-assistant | cmdb-assistant | rectangle | #4A90D9 | bottom-right |
### MCP Servers (Green - #7CB342) ### MCP Servers (Green - #7CB342)
| ID | Label | Type | Color | Position | MCP servers are **bundled inside each plugin** that needs them.
|----|-------|------|-------|----------|
| gitea-mcp | Gitea MCP Server | rectangle | #7CB342 | middle-left | | ID | Label | Type | Color | Position | Bundled In |
| wikijs-mcp | Wiki.js MCP Server | rectangle | #7CB342 | middle-right | |----|-------|------|-------|----------|------------|
| gitea-mcp | Gitea MCP Server | rectangle | #7CB342 | middle-left | projman |
| netbox-mcp | NetBox MCP Server | rectangle | #7CB342 | middle-right | cmdb-assistant |
### External Systems (Gray - #9E9E9E) ### External Systems (Gray - #9E9E9E)
| ID | Label | Type | Color | Position | | ID | Label | Type | Color | Position |
|----|-------|------|-------|----------| |----|-------|------|-------|----------|
| gitea-instance | Gitea\ngitea.hotserv.cloud | cylinder | #9E9E9E | bottom-left | | gitea-instance | Gitea\n(Issues + Wiki) | cylinder | #9E9E9E | bottom-left |
| wikijs-instance | Wiki.js\nwikijs.hotserv.cloud | cylinder | #9E9E9E | bottom-right | | netbox-instance | NetBox | cylinder | #9E9E9E | bottom-right |
### Configuration (Orange - #FF9800) ### Configuration (Orange - #FF9800)
@@ -45,10 +49,8 @@
| From | To | Label | Style | Arrow | | From | To | Label | Style | Arrow |
|------|----|-------|-------|-------| |------|----|-------|-------|-------|
| projman | gitea-mcp | uses | solid | forward | | projman | gitea-mcp | bundled | solid | bidirectional |
| projman | wikijs-mcp | uses | solid | forward | | cmdb-assistant | netbox-mcp | bundled | solid | bidirectional |
| projman-pmo | gitea-mcp | uses (company-wide) | solid | forward |
| projman-pmo | wikijs-mcp | uses (company-wide) | solid | forward |
### Plugin Dependencies ### Plugin Dependencies
@@ -61,16 +63,16 @@
| From | To | Label | Style | Arrow | | From | To | Label | Style | Arrow |
|------|----|-------|-------|-------| |------|----|-------|-------|-------|
| gitea-mcp | gitea-instance | REST API | solid | forward | | gitea-mcp | gitea-instance | REST API | solid | forward |
| wikijs-mcp | wikijs-instance | GraphQL | solid | forward | | netbox-mcp | netbox-instance | REST API | solid | forward |
### Configuration Connections ### Configuration Connections
| From | To | Label | Style | Arrow | | From | To | Label | Style | Arrow |
|------|----|-------|-------|-------| |------|----|-------|-------|-------|
| system-config | gitea-mcp | credentials | dashed | forward | | system-config | gitea-mcp | credentials | dashed | forward |
| system-config | wikijs-mcp | credentials | dashed | forward | | system-config | netbox-mcp | credentials | dashed | forward |
| project-config | gitea-mcp | repo context | dashed | forward | | project-config | gitea-mcp | repo context | dashed | forward |
| project-config | wikijs-mcp | project path | dashed | forward | | project-config | netbox-mcp | site context | dashed | forward |
--- ---
@@ -78,9 +80,8 @@
| ID | Label | Contains | Style | | ID | Label | Contains | Style |
|----|-------|----------|-------| |----|-------|----------|-------|
| plugins-group | Plugins | projman, projman-pmo, project-hygiene | light blue border | | plugins-group | Plugins | projman, projman-pmo, project-hygiene, claude-config, cmdb-assistant | light blue border |
| mcp-group | Shared MCP Servers | gitea-mcp, wikijs-mcp | light green border | | external-group | External Services | gitea-instance, netbox-instance | light gray border |
| external-group | External Services | gitea-instance, wikijs-instance | light gray border |
| config-group | Configuration | system-config, project-config | light orange border | | config-group | Configuration | system-config, project-config | light orange border |
--- ---
@@ -92,25 +93,21 @@
| PLUGINS GROUP | | PLUGINS GROUP |
| +----------------+ +----------------+ +-------------------+ | | +----------------+ +----------------+ +-------------------+ |
| | project- | | projman | | projman-pmo | | | | project- | | projman | | projman-pmo | |
| | hygiene | | | | | | | | hygiene | | [gitea-mcp] | | (planned) | |
| +----------------+ +-------+--------+ +--------+----------+ | | +----------------+ +-------+--------+ +-------------------+ |
| | | | | | |
| +----------------+ +-------------------+ |
| | claude-config | | cmdb-assistant | |
| | -maintainer | | [netbox-mcp] | |
| +----------------+ +--------+----------+ |
+------------------------------------------------------------------+ +------------------------------------------------------------------+
| | |
v v v
+------------------------------------------------------------------+
| MCP SERVERS GROUP |
| +-------------------+ +-------------------+ |
| | Gitea MCP Server | | Wiki.js MCP Server| |
| +--------+----------+ +---------+---------+ |
+------------------------------------------------------------------+
| |
v v
+------------------------------------------------------------------+ +------------------------------------------------------------------+
| EXTERNAL SERVICES GROUP | | EXTERNAL SERVICES GROUP |
| +-------------------+ +-------------------+ | | +-------------------+ +-------------------+ |
| | Gitea | | Wiki.js | | | | Gitea | | NetBox | |
| | gitea.hotserv.cloud | wikijs.hotserv.cloud | | | (Issues + Wiki) | | | |
| +-------------------+ +-------------------+ | | +-------------------+ +-------------------+ |
+------------------------------------------------------------------+ +------------------------------------------------------------------+
@@ -128,6 +125,15 @@ CONFIG GROUP (left side): CONFIG GROUP (right side):
| Color | Hex | Meaning | | Color | Hex | Meaning |
|-------|-----|---------| |-------|-----|---------|
| Blue | #4A90D9 | Plugins | | Blue | #4A90D9 | Plugins |
| Green | #7CB342 | MCP Servers | | Green | #7CB342 | MCP Servers (bundled in plugins) |
| Gray | #9E9E9E | External Systems | | Gray | #9E9E9E | External Systems |
| Orange | #FF9800 | Configuration | | Orange | #FF9800 | Configuration |
---
## ARCHITECTURE NOTES
- MCP servers are **bundled inside plugins** (not shared at root)
- Gitea provides both issue tracking AND wiki (lessons learned)
- No separate Wiki.js - all wiki functionality uses Gitea Wiki
- Each plugin is self-contained for Claude Code caching

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

View File

@@ -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! 🚀

View File

@@ -2,29 +2,21 @@
"name": "claude-config-maintainer", "name": "claude-config-maintainer",
"version": "1.0.0", "version": "1.0.0",
"description": "Maintains and optimizes CLAUDE.md configuration files for Claude Code projects", "description": "Maintains and optimizes CLAUDE.md configuration files for Claude Code projects",
"entryPoint": "agents/maintainer.md", "author": {
"commands": [ "name": "Leo Miranda",
{ "email": "leobmiranda@gmail.com"
"name": "config-analyze", },
"description": "Analyze CLAUDE.md for optimization opportunities", "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/claude-config-maintainer/README.md",
"entryPoint": "commands/analyze.md" "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
}, "license": "MIT",
{ "keywords": [
"name": "config-optimize", "claude-code",
"description": "Optimize CLAUDE.md structure and content", "configuration",
"entryPoint": "commands/optimize.md" "optimization",
}, "claude-md",
{ "developer-tools"
"name": "config-init",
"description": "Initialize a new CLAUDE.md file for a project",
"entryPoint": "commands/init.md"
}
], ],
"agents": [ "entryPoint": "agents/maintainer.md",
{ "commands": ["./commands/"],
"name": "maintainer", "agents": ["./agents/"]
"description": "CLAUDE.md optimization and maintenance agent",
"entryPoint": "agents/maintainer.md"
}
]
} }

View File

@@ -96,4 +96,4 @@ Target score: **70+** for effective Claude Code usage.
## Contributing ## Contributing
This plugin is part of the bandit/support-claude-mktplace repository. This plugin is part of the personal-projects/support-claude-mktplace repository.

View File

@@ -31,7 +31,11 @@ You are the **Maintainer Agent** - a specialist in creating and optimizing CLAUD
### 1. Analyze CLAUDE.md Files ### 1. Analyze CLAUDE.md Files
When analyzing a CLAUDE.md file, evaluate: When analyzing a CLAUDE.md file, perform two types of analysis:
#### A. Content Analysis
Evaluate:
**Structure:** **Structure:**
- Is the file well-organized? - Is the file well-organized?
@@ -57,6 +61,49 @@ When analyzing a CLAUDE.md file, evaluate:
- Are there verbose explanations that could be shortened? - Are there verbose explanations that could be shortened?
- Is the file too long for effective use? - Is the file too long for effective use?
#### B. Plugin Integration Analysis
After content analysis, check for marketplace plugin integration:
**Step 1: Detect Active Plugins**
Read `.claude/settings.local.json` and identify enabled MCP servers:
```json
{
"mcpServers": {
"gitea": { ... }, // → projman plugin
"netbox": { ... } // → cmdb-assistant plugin
}
}
```
Use this mapping to identify active plugins:
| MCP Server | Plugin |
|------------|--------|
| `gitea` | projman |
| `netbox` | cmdb-assistant |
Also check for hook-based plugins (project-hygiene uses `PostToolUse` hooks).
**Step 2: Check CLAUDE.md for Plugin References**
For each detected plugin, search CLAUDE.md for:
- Plugin name mention (e.g., "projman", "cmdb-assistant")
- Command references (e.g., `/sprint-plan`, `/cmdb-search`)
- MCP tool mentions (e.g., `list_issues`, `dcim_list_devices`)
**Step 3: Load Integration Snippets**
For plugins not referenced in CLAUDE.md, load their integration snippet from:
`plugins/{plugin-name}/claude-md-integration.md`
**Step 4: Report and Offer Integration**
Report plugin coverage percentage and offer to add missing integrations:
- Show which plugins are detected but not referenced
- Display the integration content that would be added
- Ask user for confirmation before modifying CLAUDE.md
### 2. Optimize CLAUDE.md Structure ### 2. Optimize CLAUDE.md Structure
**Recommended Structure:** **Recommended Structure:**
@@ -145,7 +192,42 @@ Suggested Actions:
Would you like me to implement these improvements? Would you like me to implement these improvements?
``` ```
### 5. Create New CLAUDE.md Files ### 5. Insert Plugin Integrations
When adding plugin integration content to CLAUDE.md:
**Placement:**
- Add plugin sections after the main project documentation
- Group all plugin integrations together under a clear header
- Use consistent formatting across all plugin sections
**Process:**
1. Read the plugin's `claude-md-integration.md` file
2. Show the content to the user for review
3. Ask for confirmation: "Add this plugin integration? [Y/n]"
4. If confirmed, insert at appropriate location in CLAUDE.md
5. Repeat for each missing plugin
**User Confirmation Flow:**
```
Plugin Integration: projman
--------------------------
[Show content from plugins/projman/claude-md-integration.md]
Add this integration to CLAUDE.md?
[1] Yes, add this integration
[2] Skip this plugin
[3] Add all remaining plugins
[4] Cancel
```
**Best Practices:**
- Never modify CLAUDE.md without user confirmation
- Show exactly what will be added before making changes
- Allow users to skip specific plugins they don't want documented
- Preserve existing CLAUDE.md structure and content
### 6. Create New CLAUDE.md Files
When creating a new CLAUDE.md: When creating a new CLAUDE.md:

View 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

View File

@@ -1,10 +1,10 @@
--- ---
description: Analyze CLAUDE.md for optimization opportunities description: Analyze CLAUDE.md for optimization opportunities and plugin integration
--- ---
# Analyze CLAUDE.md # Analyze CLAUDE.md
This command analyzes your project's CLAUDE.md file and provides a detailed report on optimization opportunities. This command analyzes your project's CLAUDE.md file and provides a detailed report on optimization opportunities and plugin integration status.
## What This Command Does ## What This Command Does
@@ -12,7 +12,9 @@ This command analyzes your project's CLAUDE.md file and provides a detailed repo
2. **Analyze Structure** - Evaluates organization, headers, and flow 2. **Analyze Structure** - Evaluates organization, headers, and flow
3. **Check Content** - Reviews clarity, completeness, and conciseness 3. **Check Content** - Reviews clarity, completeness, and conciseness
4. **Identify Issues** - Finds redundancy, verbosity, and missing sections 4. **Identify Issues** - Finds redundancy, verbosity, and missing sections
5. **Generate Report** - Provides scored assessment with recommendations 5. **Detect Active Plugins** - Identifies marketplace plugins enabled in the project
6. **Check Plugin Integration** - Verifies CLAUDE.md references active plugins
7. **Generate Report** - Provides scored assessment with recommendations
## Usage ## Usage
@@ -52,6 +54,29 @@ Analyze the CLAUDE.md file in this project
- Appropriate length for project size - Appropriate length for project size
- No generic filler content - No generic filler content
## Plugin Integration Analysis
After the content analysis, the command detects and analyzes marketplace plugin integration:
### Detection Method
1. **Read `.claude/settings.local.json`** - Check for enabled MCP servers
2. **Map MCP servers to plugins** - Use marketplace registry to identify active plugins:
- `gitea` → projman
- `netbox` → cmdb-assistant
3. **Check for hooks** - Identify hook-based plugins (project-hygiene)
4. **Scan CLAUDE.md** - Look for plugin integration content
### Plugin Coverage Scoring
For each detected plugin, verify CLAUDE.md contains:
- Plugin section header or mention
- Available commands documentation
- MCP tools reference (if applicable)
- Usage guidelines
Coverage is reported as percentage: `(plugins referenced / plugins detected) * 100`
## Expected Output ## Expected Output
``` ```
@@ -101,10 +126,37 @@ Recommendations:
Estimated improvement: 15-20 points after changes Estimated improvement: 15-20 points after changes
---
Plugin Integration Analysis
===========================
Detected Active Plugins:
✓ projman (via gitea MCP server)
✓ cmdb-assistant (via netbox MCP server)
✓ project-hygiene (via PostToolUse hook)
Plugin Coverage: 33% (1/3 plugins referenced)
✓ projman - Referenced in CLAUDE.md
✗ cmdb-assistant - NOT referenced
✗ project-hygiene - NOT referenced
Missing Integration Content:
1. cmdb-assistant
Add infrastructure management commands and NetBox MCP tools reference.
2. project-hygiene
Add cleanup hook documentation and configuration options.
---
Would you like me to: Would you like me to:
[1] Implement all recommended changes [1] Implement all content recommendations
[2] Show before/after for specific section [2] Add missing plugin integrations to CLAUDE.md
[3] Generate optimized version for review [3] Do both (recommended)
[4] Show preview of changes first
``` ```
## When to Use ## When to Use
@@ -115,6 +167,8 @@ Run `/config-analyze` when:
- Claude seems to miss instructions - Claude seems to miss instructions
- Before major project changes - Before major project changes
- Periodic maintenance (quarterly) - Periodic maintenance (quarterly)
- After installing new marketplace plugins
- When Claude doesn't seem to use available plugin tools
## Follow-Up Actions ## Follow-Up Actions

View File

@@ -3,10 +3,11 @@
"version": "1.0.0", "version": "1.0.0",
"description": "NetBox CMDB integration for infrastructure management - query, create, update, and manage network devices, IP addresses, sites, and more", "description": "NetBox CMDB integration for infrastructure management - query, create, update, and manage network devices, IP addresses, sites, and more",
"author": { "author": {
"name": "Bandit Labs", "name": "Leo Miranda",
"email": "dev@banditlabs.io" "email": "leobmiranda@gmail.com"
}, },
"homepage": "https://github.com/bandit-labs/cmdb-assistant", "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/cmdb-assistant/README.md",
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
"license": "MIT", "license": "MIT",
"keywords": [ "keywords": [
"netbox", "netbox",
@@ -15,5 +16,8 @@
"network", "network",
"ipam", "ipam",
"dcim" "dcim"
] ],
"commands": ["./commands/"],
"agents": ["./agents/"],
"mcpServers": "./.mcp.json"
} }

View File

@@ -167,4 +167,4 @@ The plugin uses the shared NetBox MCP server at `../mcp-servers/netbox/`.
## License ## License
MIT License - Part of the Bandit Labs plugin collection. MIT License - Part of the Claude Code Marketplace.

View 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

View File

@@ -294,4 +294,4 @@ logging.basicConfig(level=logging.DEBUG)
## License ## License
Part of the Bandit Labs Claude Code Plugins project (`support-claude-mktplace`). MIT License - Part of the Claude Code Marketplace (`support-claude-mktplace`).

View File

@@ -3,12 +3,19 @@
"version": "0.1.0", "version": "0.1.0",
"description": "Post-task cleanup hook that removes temp files, warns about unexpected root files, and manages orphaned supporting files", "description": "Post-task cleanup hook that removes temp files, warns about unexpected root files, and manages orphaned supporting files",
"author": { "author": {
"name": "Bandit Labs", "name": "Leo Miranda",
"email": "dev@banditlabs.io" "email": "leobmiranda@gmail.com"
}, },
"homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/project-hygiene/README.md",
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
"license": "MIT", "license": "MIT",
"keywords": ["cleanup", "hygiene", "automation", "hooks", "maintenance"], "keywords": [
"repository": "https://github.com/bandit-labs/project-hygiene", "cleanup",
"hygiene",
"automation",
"hooks",
"maintenance"
],
"hooks": { "hooks": {
"PostToolUse": [ "PostToolUse": [
{ {

View 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

View File

@@ -1,18 +1,21 @@
{ {
"name": "projman", "name": "projman",
"version": "2.0.0", "version": "2.2.0",
"description": "Sprint planning and project management with Gitea integration", "description": "Sprint planning and project management with Gitea integration",
"author": { "author": {
"name": "Bandit Labs", "name": "Leo Miranda",
"email": "dev@banditlabs.io" "email": "leobmiranda@gmail.com"
}, },
"homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/projman/README.md",
"repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
"license": "MIT", "license": "MIT",
"repository": "https://gitea.hotserv.cloud/bandit/support-claude-mktplace",
"keywords": [ "keywords": [
"project-management", "project-management",
"sprint-planning", "sprint-planning",
"gitea", "gitea",
"agile", "agile",
"lessons-learned" "lessons-learned"
] ],
"commands": ["./commands/"],
"agents": ["./agents/"]
} }

View File

@@ -1,4 +1,4 @@
# Configuration Guide - Projman Plugin v2.0.0 # Configuration Guide - Projman Plugin
Complete setup and configuration instructions for the Projman project management plugin. Complete setup and configuration instructions for the Projman project management plugin.

View File

@@ -1,4 +1,4 @@
# Projman v2.0.0 - Project Management for Claude Code # Projman - Project Management for Claude Code
Sprint planning and project management plugin with full Gitea integration. Sprint planning and project management plugin with full Gitea integration.
@@ -174,6 +174,43 @@ Run initial setup for a new project.
**When to use:** First time setting up projman for a project **When to use:** First time setting up projman for a project
### `/review`
Pre-sprint-close code quality review.
**What it does:**
- Scans recent changes for debug artifacts (TODO, console.log, commented code)
- Checks for code complexity issues (long functions, deep nesting)
- Performs lightweight security scan (hardcoded secrets, SQL injection risks)
- Identifies error handling gaps (bare except, swallowed exceptions)
**Output format:**
- Critical Issues (Block Sprint Close)
- Warnings (Should Address)
- Recommendations (Nice to Have)
**When to use:** Before closing a sprint to ensure code quality
### `/test-check`
Test verification before sprint close.
**What it does:**
- Automatically detects test framework (pytest, Jest, Go test, Cargo, etc.)
- Runs the test suite
- Reports pass/fail summary with details on failures
- Includes coverage report when available
- Identifies sprint files lacking test coverage
**Flags:**
- "run tests with coverage" - Include coverage report
- "run tests verbose" - Show full output
- "just check, don't run" - Report framework detection only
**When to use:** Before closing a sprint to ensure tests pass
## Code Quality Commands
The `/review` and `/test-check` commands complement the Executor agent by catching issues before work is marked complete. Run both commands before `/sprint-close` for a complete quality check.
## Agents ## Agents
### Planner Agent ### Planner Agent
@@ -203,6 +240,17 @@ Run initial setup for a new project.
**Invoked by:** `/sprint-start`, `/sprint-close` **Invoked by:** `/sprint-start`, `/sprint-close`
### Code Reviewer Agent
**Personality:** Thorough, practical, severity-focused
**Responsibilities:**
- Identifying code quality issues before sprint close
- Prioritizing findings (Critical > Warning > Recommendation)
- Providing actionable feedback with file:line references
- Respecting sprint scope (only reviewing changed files)
**Invoked by:** `/review`
### Executor Agent ### Executor Agent
**Personality:** Implementation-focused, follows specs precisely **Personality:** Implementation-focused, follows specs precisely
@@ -373,11 +421,14 @@ projman/
│ ├── sprint-status.md │ ├── sprint-status.md
│ ├── sprint-close.md │ ├── sprint-close.md
│ ├── labels-sync.md │ ├── labels-sync.md
── initial-setup.md ── initial-setup.md
│ ├── review.md
│ └── test-check.md
├── agents/ # Agent prompts ├── agents/ # Agent prompts
│ ├── planner.md │ ├── planner.md
│ ├── orchestrator.md │ ├── orchestrator.md
── executor.md ── executor.md
│ └── code-reviewer.md
├── skills/ # Supporting knowledge ├── skills/ # Supporting knowledge
│ └── label-taxonomy/ │ └── label-taxonomy/
│ └── labels-reference.md │ └── labels-reference.md
@@ -428,15 +479,6 @@ See [CONFIGURATION.md](./CONFIGURATION.md) for detailed configuration instructio
MIT License - See repository root for details MIT License - See repository root for details
## Version
**Current:** 2.0.0
**Changelog:**
- v2.0.0: Full Gitea integration with wiki, milestones, dependencies, parallel execution
- v1.0.0: Initial release with basic commands
--- ---
**Built for:** Bandit Labs
**Status:** Production Ready **Status:** Production Ready

View 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
```

View 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

View 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)

View 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

View File

@@ -389,25 +389,24 @@ def list_issues(self, state='open', labels=None, repo=None):
## License ## License
Part of the Bandit Labs Claude Code Plugins project. MIT License - Part of the Claude Code Marketplace project.
## Related Documentation ## Related Documentation
- **MCP Specification**: `docs/references/MCP-GITEA.md` - **Projman Documentation**: `plugins/projman/README.md`
- **Project Summary**: `docs/references/PROJECT-SUMMARY.md` - **Configuration Guide**: `plugins/projman/CONFIGURATION.md`
- **Implementation Plan**: `docs/reference-material/projman-implementation-plan.md`
- **Testing Guide**: `TESTING.md` - **Testing Guide**: `TESTING.md`
## Support ## Support
For issues or questions: For issues or questions:
1. Check [TESTING.md](./TESTING.md) troubleshooting section 1. Check [TESTING.md](./TESTING.md) troubleshooting section
2. Review [MCP-GITEA.md](../../docs/references/MCP-GITEA.md) specification 2. Review [plugins/projman/README.md](../../README.md) for plugin documentation
3. Create an issue in the project repository 3. Create an issue in the project repository
--- ---
**Built for**: Bandit Labs Project Management Plugins **Built for**: Claude Code Marketplace - Project Management Plugins
**Phase**: 1 (Complete) **Phase**: 1 (Complete)
**Status**: ✅ Production Ready **Status**: ✅ Production Ready
**Last Updated**: 2025-01-06 **Last Updated**: 2025-01-06

View File

@@ -574,8 +574,8 @@ After completing testing:
- **MCP Documentation**: https://docs.anthropic.com/claude/docs/mcp - **MCP Documentation**: https://docs.anthropic.com/claude/docs/mcp
- **Gitea API Documentation**: https://docs.gitea.io/en-us/api-usage/ - **Gitea API Documentation**: https://docs.gitea.io/en-us/api-usage/
- **Project Documentation**: `docs/references/MCP-GITEA.md` - **Projman Documentation**: `plugins/projman/README.md`
- **Implementation Plan**: `docs/references/PROJECT-SUMMARY.md` - **Configuration Guide**: `plugins/projman/CONFIGURATION.md`
--- ---

View File

@@ -45,7 +45,7 @@ class GiteaClient:
"""Parse owner/repo from input. Always requires 'owner/repo' format.""" """Parse owner/repo from input. Always requires 'owner/repo' format."""
target = repo or self.repo target = repo or self.repo
if not target or '/' not in target: if not target or '/' not in target:
raise ValueError("Use 'owner/repo' format (e.g. 'bandit/support-claude-mktplace')") raise ValueError("Use 'owner/repo' format (e.g. 'org/repo-name')")
parts = target.split('/', 1) parts = target.split('/', 1)
return parts[0], parts[1] return parts[0], parts[1]

View File

@@ -32,7 +32,7 @@ class LabelTools:
target_repo = repo or self.gitea.repo target_repo = repo or self.gitea.repo
if not target_repo or '/' not in target_repo: if not target_repo or '/' not in target_repo:
raise ValueError("Use 'owner/repo' format (e.g. 'bandit/support-claude-mktplace')") raise ValueError("Use 'owner/repo' format (e.g. 'org/repo-name')")
org = target_repo.split('/')[0] org = target_repo.split('/')[0]

View File

@@ -7,7 +7,7 @@ description: Dynamic reference for Gitea label taxonomy (organization + reposito
**Status:** ✅ Synced with Gitea **Status:** ✅ Synced with Gitea
**Last synced:** 2025-11-21 (via automated testing) **Last synced:** 2025-11-21 (via automated testing)
**Source:** Gitea (bandit/support-claude-mktplace) **Source:** Gitea (personal-projects/support-claude-mktplace)
## Overview ## Overview
@@ -17,7 +17,7 @@ This skill provides the current label taxonomy used for issue classification in
## Organization Labels (27) ## Organization Labels (27)
Organization-level labels are shared across all repositories in the `bandit` organization. Organization-level labels are shared across all repositories in your configured organization.
### Agent (2) ### Agent (2)
- `Agent/Human` (#0052cc) - Work performed by human developers - `Agent/Human` (#0052cc) - Work performed by human developers

139
scripts/validate-marketplace.sh Executable file
View 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 ==="