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

docs: update README files for v1.0.0 release

Browse Source 
- Update main README with new structure (MCP servers bundled in plugins)
- Remove Wiki.js references (replaced by Gitea Wiki)
- Add claude-config-maintainer plugin documentation
- Update projman README with new tools and features
- Update installation instructions for bundled MCP servers

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2026-01-19 17:16:16 -05:00
parent 74b28170fa
commit 657b7a7a6f
2 changed files with 292 additions and 308 deletions
Download Patch File Download Diff File Expand all files Collapse all files

229
README.md
View File

@@ -1,20 +1,34 @@
# Claude Code Marketplace - Bandit Labs # Claude Code Marketplace - Bandit Labs
A collection of Claude Code plugins and MCP servers 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) ### [projman](./plugins/projman/README.md) v1.0.0
**Sprint Planning and Project Management** **Sprint Planning and Project Management**
AI-guided sprint planning with Gitea and Wiki.js 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
- Intelligent label suggestions from 44-label taxonomy - Intelligent label suggestions from 43-label taxonomy
- Lessons learned capture to prevent repeated mistakes - Lessons learned capture via Gitea Wiki
- Native issue dependencies with parallel execution
- Milestone management for sprint organization
- Branch-aware security (development/staging/production) - Branch-aware security (development/staging/production)
**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync` **Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup`
### [claude-config-maintainer](./plugins/claude-config-maintainer/README.md)
**CLAUDE.md Optimization and Maintenance**
Analyze, optimize, and create CLAUDE.md configuration files for Claude Code projects.
- Structure and clarity scoring (100-point system)
- Automatic optimization with preview and backup
- Project-aware initialization with stack detection
- Best practices enforcement
**Commands:** `/config-analyze`, `/config-optimize`, `/config-init`
### [cmdb-assistant](./plugins/cmdb-assistant/README.md) ### [cmdb-assistant](./plugins/cmdb-assistant/README.md)
**NetBox CMDB Integration** **NetBox CMDB Integration**
@@ -35,41 +49,28 @@ Hook-based cleanup that runs after Claude completes work.
- Deletes temp files (`*.tmp`, `*.bak`, `__pycache__`, etc.) - Deletes temp files (`*.tmp`, `*.bak`, `__pycache__`, etc.)
- Warns about unexpected files in project root - Warns about unexpected files in project root
- Identifies orphaned supporting files (`test_*`, `debug_*`, `*_backup.*`) - Identifies orphaned supporting files
- Logs actions to `.dev/logs/`
- Configurable via `.hygiene.json` - Configurable via `.hygiene.json`
**Hook:** `task-completed`
## MCP Servers ## MCP Servers
Shared Model Context Protocol servers that provide plugins with external service access. MCP servers are **bundled inside each plugin** that needs them. This ensures plugins work when cached by Claude Code.
### [Gitea MCP Server](./mcp-servers/gitea/README.md) ### Gitea MCP Server (bundled in projman)
Issue management, label operations, and repository tracking for Gitea.
| Tool | Description | Full Gitea API integration for project management.
|------|-------------|
| `list_issues` | Query issues with filters |
| `create_issue` | Create issue with labels |
| `get_labels` | Fetch org + repo labels |
| `suggest_labels` | Intelligent label suggestions |
**Status:** Production Ready | Category | Tools |
|----------|-------|
| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment` |
| Labels | `get_labels`, `suggest_labels`, `create_label` |
| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `create_lesson`, `search_lessons` |
| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone` |
| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `get_execution_order` |
| Validation | `validate_repo_org`, `get_branch_protection` |
### [Wiki.js MCP Server](./mcp-servers/wikijs/README.md) ### NetBox MCP Server (bundled in cmdb-assistant)
Documentation management and lessons learned capture via GraphQL.
| Tool | Description |
|------|-------------|
| `search_pages` | Search by keywords/tags |
| `create_page` | Create markdown pages |
| `create_lesson` | Capture sprint lessons |
| `search_lessons` | Find relevant insights |
**Status:** Production Ready
### [NetBox MCP Server](./mcp-servers/netbox/README.md)
Comprehensive NetBox REST API integration for infrastructure management. Comprehensive NetBox REST API integration for infrastructure management.
| Module | Coverage | | Module | Coverage |
@@ -80,15 +81,13 @@ Comprehensive NetBox REST API integration for infrastructure management.
| Virtualization | Clusters, VMs, Interfaces | | Virtualization | Clusters, VMs, Interfaces |
| Extras | Tags, Custom Fields, Audit Log | | Extras | Tags, Custom Fields, Audit Log |
**Status:** Production Ready
## Installation ## Installation
### Prerequisites ### Prerequisites
- Claude Code installed - Claude Code installed
- Python 3.10+ - Python 3.10+
- Access to target services (Gitea, Wiki.js, NetBox as needed) - Access to target services (Gitea, NetBox as needed)
### Quick Start ### Quick Start
@@ -100,35 +99,33 @@ Comprehensive NetBox REST API integration for infrastructure management.
2. **Install MCP server dependencies:** 2. **Install MCP server dependencies:**
```bash ```bash
# Gitea MCP # Gitea MCP (for projman)
cd mcp-servers/gitea && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt cd plugins/projman/mcp-servers/gitea
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
deactivate
# Wiki.js MCP # NetBox MCP (for cmdb-assistant)
cd ../wikijs && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt cd ../../../cmdb-assistant/mcp-servers/netbox
python3 -m venv .venv
# NetBox MCP source .venv/bin/activate
cd ../netbox && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt pip install -r requirements.txt
deactivate
``` ```
3. **Configure credentials:** 3. **Configure system-level credentials:**
```bash ```bash
mkdir -p ~/.config/claude mkdir -p ~/.config/claude
# Gitea # Gitea credentials
cat > ~/.config/claude/gitea.env << 'EOF' cat > ~/.config/claude/gitea.env << 'EOF'
GITEA_API_URL=https://gitea.example.com/api/v1 GITEA_URL=https://gitea.example.com
GITEA_API_TOKEN=your_token GITEA_TOKEN=your_token
GITEA_OWNER=your_org GITEA_ORG=your_org
EOF EOF
# Wiki.js # NetBox credentials
cat > ~/.config/claude/wikijs.env << 'EOF'
WIKIJS_API_URL=https://wiki.example.com/graphql
WIKIJS_API_TOKEN=your_token
WIKIJS_BASE_PATH=/your-namespace
EOF
# NetBox
cat > ~/.config/claude/netbox.env << 'EOF' cat > ~/.config/claude/netbox.env << 'EOF'
NETBOX_API_URL=https://netbox.example.com/api NETBOX_API_URL=https://netbox.example.com/api
NETBOX_API_TOKEN=your_token NETBOX_API_TOKEN=your_token
@@ -137,101 +134,85 @@ Comprehensive NetBox REST API integration for infrastructure management.
chmod 600 ~/.config/claude/*.env chmod 600 ~/.config/claude/*.env
``` ```
4. **Add marketplace to Claude Code:** 4. **Configure project-level settings:**
```bash ```bash
claude plugin marketplace add /path/to/support-claude-mktplace # In your target project root
claude plugin install projman cat > .env << 'EOF'
claude plugin install cmdb-assistant GITEA_REPO=your-repository-name
claude plugin install project-hygiene EOF
```
5. **Add marketplace to Claude Code:**
Add to your project's `.claude/settings.json`:
```json
{
"pluginMarketplace": "/path/to/support-claude-mktplace"
}
``` ```
## Repository Structure ## Repository Structure
``` ```
support-claude-mktplace/ support-claude-mktplace/
├── plugins/ # All plugins ├── .claude-plugin/ # Marketplace manifest
│ ├── projman/ # Sprint management plugin │ └── marketplace.json
├── plugins/ # All plugins (with bundled MCP servers)
│ ├── projman/ # Sprint management plugin
│ │ ├── .claude-plugin/ │ │ ├── .claude-plugin/
│ │ ├── .mcp.json
│ │ ├── mcp-servers/ # Bundled MCP server
│ │ │ └── gitea/
│ │ ├── commands/ │ │ ├── commands/
│ │ ├── agents/ │ │ ├── agents/
│ │ └── skills/ │ │ └── skills/
│ ├── projman-pmo/ # PMO coordination plugin │ ├── claude-config-maintainer/ # CLAUDE.md optimization plugin
│ │ ├── .claude-plugin/ │ │ ├── .claude-plugin/
│ │ ├── commands/ │ │ ├── commands/
│ │ └── agents/ │ │ └── agents/
│ ├── project-hygiene/ # Cleanup automation plugin │ ├── cmdb-assistant/ # NetBox CMDB integration
│ │ ├── .claude-plugin/ │ │ ├── .claude-plugin/
│ │ └── hooks/ │ │ ├── .mcp.json
│ └── cmdb-assistant/ # NetBox CMDB integration │ │ ├── mcp-servers/ # Bundled MCP server
│ ├── .claude-plugin/ │ │ │ └── netbox/
│ ├── commands/ │ │ ├── commands/
│ └── agents/ │ │ └── agents/
├── mcp-servers/ # Shared MCP servers │ ├── projman-pmo/ # PMO coordination plugin (planned)
│ ├── gitea/ │ └── project-hygiene/ # Cleanup automation plugin
│ ├── wikijs/ ├── docs/ # Reference documentation
│ └── netbox/ │ ├── CANONICAL-PATHS.md # Single source of truth for paths
├── .claude-plugin/ # Marketplace manifest (bandit-claude-marketplace)
│ └── marketplace.json
├── docs/ # Reference documentation
│ └── references/ │ └── references/
└── .claude/ # Claude Code local settings └── scripts/ # Setup and maintenance scripts
``` ```
## Key Features (v1.0.0)
### Parallel Execution
Tasks are batched by dependency graph for optimal parallel execution:
```
Batch 1 (parallel): Task A, Task B, Task C
Batch 2 (parallel): Task D, Task E (depend on Batch 1)
Batch 3 (sequential): Task F (depends on Batch 2)
```
### Naming Conventions
- **Tasks:** `[Sprint XX] <type>: <description>`
- **Branches:** `feat/`, `fix/`, `debug/` prefixes with issue numbers
### CLI Tools Blocked
All agents use MCP tools exclusively. CLI tools like `tea` or `gh` are forbidden to ensure consistent, auditable operations.
## Documentation ## Documentation
### Reference Material
| Document | Description |
|----------|-------------|
| [PROJECT-SUMMARY.md](./docs/references/PROJECT-SUMMARY.md) | Architecture overview and design decisions |
| [PLUGIN-PROJMAN.md](./docs/references/PLUGIN-PROJMAN.md) | Detailed projman plugin specification |
| [PLUGIN-PMO.md](./docs/references/PLUGIN-PMO.md) | Multi-project PMO plugin specification |
| [MCP-GITEA.md](./docs/references/MCP-GITEA.md) | Gitea MCP server API reference |
| [MCP-WIKIJS.md](./docs/references/MCP-WIKIJS.md) | Wiki.js MCP server API reference |
### Testing & Validation
| Document | Description |
|----------|-------------|
| [PROJMAN_TESTING_COMPLETE.md](./docs/PROJMAN_TESTING_COMPLETE.md) | Test results and validation |
| [LIVE_API_TEST_RESULTS.md](./docs/LIVE_API_TEST_RESULTS.md) | Live API integration tests |
| [TEST_EXECUTION_REPORT.md](./docs/TEST_EXECUTION_REPORT.md) | Full test execution report |
### Configuration Guides
| Document | Description | | Document | Description |
|----------|-------------| |----------|-------------|
| [CLAUDE.md](./CLAUDE.md) | Main project instructions |
| [CANONICAL-PATHS.md](./docs/CANONICAL-PATHS.md) | Authoritative path reference |
| [projman/CONFIGURATION.md](./plugins/projman/CONFIGURATION.md) | Projman setup guide | | [projman/CONFIGURATION.md](./plugins/projman/CONFIGURATION.md) | Projman setup guide |
| [CREATE_LABELS_GUIDE.md](./docs/CREATE_LABELS_GUIDE.md) | Gitea label taxonomy setup |
## Development
### Adding New Plugins
1. Create plugin directory in `plugins/` with `.claude-plugin/plugin.json`
2. Add commands, agents, or hooks as needed
3. Reference shared MCP servers via `.mcp.json` (use `../../mcp-servers/`)
4. Add to marketplace in `.claude-plugin/marketplace.json`
5. Document in plugin `README.md`
### Testing
```bash
# MCP server unit tests
cd mcp-servers/gitea && pytest -v
cd mcp-servers/wikijs && pytest -v
# Plugin validation
claude plugin list
claude --debug
```
## Roadmap ## Roadmap
- [x] **Phase 1-2**: MCP servers and commands (Complete) - [x] **Phase 1-8**: projman v1.0.0 (Complete)
- [ ] **Phase 3**: Agent system implementation
- [ ] **Phase 4**: Lessons learned integration
- [ ] **Phase 5-8**: Testing, documentation, production
- [ ] **Phase 9-11**: PMO plugin for multi-project coordination - [ ] **Phase 9-11**: PMO plugin for multi-project coordination
- [ ] **Phase 12**: Public marketplace distribution - [ ] **Phase 12**: Public marketplace distribution

371
plugins/projman/README.md
View File

@@ -1,18 +1,20 @@
# Projman - Project Management for Claude Code # Projman v1.0.0 - Project Management for Claude Code
Sprint planning and project management plugin with Gitea and Wiki.js integration. Sprint planning and project management plugin with full Gitea integration.
## Overview ## Overview
Projman transforms a proven 15-sprint workflow into a distributable Claude Code plugin. It provides AI-guided sprint planning, intelligent issue creation with label taxonomy, and systematic lessons learned capture to prevent repeated mistakes. Projman transforms a proven 15-sprint workflow into a distributable Claude Code plugin. It provides AI-guided sprint planning, intelligent issue creation with label taxonomy, native issue dependencies, parallel task execution, and systematic lessons learned capture via Gitea Wiki.
**Key Features:** **Key Features:**
- 🎯 **Sprint Planning** - AI-guided architecture analysis and issue creation - **Sprint Planning** - AI-guided architecture analysis and issue creation
- 🏷️ **Smart Label Suggestions** - Intelligent label recommendations from 44-label taxonomy - **Smart Label Suggestions** - Intelligent label recommendations from 43-label taxonomy
- 📚 **Lessons Learned** - Systematic capture and search of sprint insights - **Issue Dependencies** - Native Gitea dependencies with parallel execution batching
- 🔒 **Branch-Aware Security** - Prevents accidental changes on production branches - **Milestones** - Sprint milestone management and tracking
- ⚙️ **Hybrid Configuration** - Simple setup with system + project-level config - **Lessons Learned** - Systematic capture and search via Gitea Wiki
- 🤖 **Three-Agent Model** - Planner, Orchestrator, and Executor agents - **Branch-Aware Security** - Prevents accidental changes on production branches
- **Three-Agent Model** - Planner, Orchestrator, and Executor agents
- **CLI Tools Blocked** - All operations via MCP tools only (no `tea` or `gh`)
## Quick Start ## Quick Start
@@ -20,52 +22,38 @@ Projman transforms a proven 15-sprint workflow into a distributable Claude Code
- Claude Code installed - Claude Code installed
- Access to Gitea instance with API token - Access to Gitea instance with API token
- Access to Wiki.js instance with API token
- Python 3.10+ installed - Python 3.10+ installed
- Git repository initialized - Git repository initialized
### 2. Install MCP Servers ### 2. Install MCP Server
The plugin requires two shared MCP servers: The plugin bundles the Gitea MCP server:
```bash ```bash
# Navigate to MCP servers directory cd plugins/projman/mcp-servers/gitea
cd ../mcp-servers/gitea python3 -m venv .venv
python -m venv .venv
source .venv/bin/activate # or .venv\Scripts\activate on Windows source .venv/bin/activate # or .venv\Scripts\activate on Windows
pip install -r requirements.txt pip install -r requirements.txt
cd ../wikijs
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
``` ```
See [CONFIGURATION.md](./CONFIGURATION.md) for detailed setup instructions. See [CONFIGURATION.md](./CONFIGURATION.md) for detailed setup instructions.
### 3. Configure System-Level Settings ### 3. Configure System-Level Settings
Create system-wide configuration with your Gitea and Wiki.js credentials: Create system-wide configuration with your Gitea credentials:
```bash ```bash
mkdir -p ~/.config/claude mkdir -p ~/.config/claude
# Gitea configuration # Gitea configuration
cat > ~/.config/claude/gitea.env << EOF cat > ~/.config/claude/gitea.env << 'EOF'
GITEA_API_URL=https://gitea.example.com/api/v1 GITEA_URL=https://gitea.example.com
GITEA_API_TOKEN=your_gitea_token_here GITEA_TOKEN=your_gitea_token_here
GITEA_OWNER=bandit GITEA_ORG=your_organization
EOF EOF
# Wiki.js configuration # Secure the file
cat > ~/.config/claude/wikijs.env << EOF chmod 600 ~/.config/claude/gitea.env
WIKIJS_API_URL=https://wiki.your-company.com/graphql
WIKIJS_API_TOKEN=your_wikijs_token_here
WIKIJS_BASE_PATH=/your-org
EOF
# Secure the files
chmod 600 ~/.config/claude/*.env
``` ```
### 4. Configure Project-Level Settings ### 4. Configure Project-Level Settings
@@ -74,21 +62,15 @@ In your project root directory, create a `.env` file:
```bash ```bash
# In your project directory # In your project directory
cat > .env << EOF cat > .env << 'EOF'
GITEA_REPO=your-repo-name GITEA_REPO=your-repo-name
WIKIJS_PROJECT=projects/your-project-name
EOF EOF
# Add to .gitignore
echo ".env" >> .gitignore
``` ```
### 5. Sync Label Taxonomy ### 5. Run Initial Setup
Fetch the label taxonomy from Gitea:
```bash ```bash
/labels-sync /initial-setup
``` ```
### 6. Start Planning! ### 6. Start Planning!
@@ -103,54 +85,54 @@ Fetch the label taxonomy from Gitea:
Start sprint planning with the AI planner agent. Start sprint planning with the AI planner agent.
**What it does:** **What it does:**
- Validates repository organization and label taxonomy
- Asks clarifying questions about sprint goals - Asks clarifying questions about sprint goals
- Searches relevant lessons learned from previous sprints - Searches relevant lessons learned from previous sprints
- Performs architecture analysis - Performs architecture analysis
- Creates Gitea issues with intelligent label suggestions - Creates Gitea issues with intelligent label suggestions
- Generates planning document - Sets up issue dependencies for parallel execution
- Creates sprint milestone
**Pre-Planning Validations:**
1. Repository belongs to configured organization
2. Required label categories exist
3. `docs/changes/` folder exists in repository
**Task Naming:** `[Sprint XX] <type>: <description>`
**When to use:** Beginning of a new sprint or when planning a major feature **When to use:** Beginning of a new sprint or when planning a major feature
**Example:**
```
/sprint-plan
> "I want to plan a sprint for user authentication"
```
### `/sprint-start` ### `/sprint-start`
Begin sprint execution with the orchestrator agent. Begin sprint execution with the orchestrator agent.
**What it does:** **What it does:**
- Reviews open sprint issues - Reviews open sprint issues and dependencies
- Searches relevant lessons learned by tags - Batches tasks by dependency graph for parallel execution
- Identifies next task based on priority and dependencies
- Generates lean execution prompts - Generates lean execution prompts
- Tracks progress - Tracks progress
**When to use:** After planning, when ready to start implementation **Parallel Execution:**
```
Batch 1 (parallel): Task A, Task B, Task C
Batch 2 (parallel): Task D, Task E (depend on Batch 1)
Batch 3 (sequential): Task F (depends on Batch 2)
```
**Example:** **Branch Naming:** `feat/123-task-title`, `fix/456-bug-fix`, `debug/789-investigation`
```
/sprint-start **When to use:** After planning, when ready to start implementation
```
### `/sprint-status` ### `/sprint-status`
Check current sprint progress. Check current sprint progress.
**What it does:** **What it does:**
- Lists all sprint issues by status (open, in progress, blocked, completed) - Lists all sprint issues by status (open, in progress, blocked, completed)
- Identifies blockers and priorities - Shows dependency analysis and blocked tasks
- Shows completion percentage - Displays completion percentage
- Highlights critical items needing attention - Shows milestone progress
**When to use:** Daily standup, progress check, deciding what to work on next **When to use:** Daily standup, progress check, deciding what to work on next
**Example:**
```
/sprint-status
```
### `/sprint-close` ### `/sprint-close`
Complete sprint and capture lessons learned. Complete sprint and capture lessons learned.
@@ -158,38 +140,39 @@ Complete sprint and capture lessons learned.
- Reviews sprint completion - Reviews sprint completion
- Captures lessons learned (what went wrong, what went right) - Captures lessons learned (what went wrong, what went right)
- Tags lessons for discoverability - Tags lessons for discoverability
- Saves lessons to Wiki.js - Saves lessons to Gitea Wiki
- Closes sprint milestone
- Handles git operations (merge, tag, cleanup) - Handles git operations (merge, tag, cleanup)
**When to use:** End of sprint, before starting the next one **When to use:** End of sprint, before starting the next one
**Example:**
```
/sprint-close
```
**CRITICAL:** Don't skip this! After 15 sprints without lesson capture, teams repeat the same mistakes. **CRITICAL:** Don't skip this! After 15 sprints without lesson capture, teams repeat the same mistakes.
### `/labels-sync` ### `/labels-sync`
Synchronize label taxonomy from Gitea. Synchronize label taxonomy from Gitea.
**What it does:** **What it does:**
- Validates repository belongs to organization
- Fetches current labels from Gitea (org + repo) - Fetches current labels from Gitea (org + repo)
- Validates required label categories
- Compares with local reference - Compares with local reference
- Detects changes (new, modified, removed labels)
- Updates local taxonomy reference - Updates local taxonomy reference
- Updates suggestion logic
**When to use:** **When to use:**
- First-time setup - First-time setup
- Monthly maintenance - Monthly maintenance
- When new labels are added to Gitea - When new labels are added to Gitea
- When label suggestions seem incorrect
**Example:** ### `/initial-setup`
``` Run initial setup for a new project.
/labels-sync
``` **What it does:**
- Validates Gitea MCP server connection
- Tests credential configuration
- Syncs label taxonomy
- Creates required directory structure
**When to use:** First time setting up projman for a project
## Agents ## Agents
@@ -197,10 +180,12 @@ Synchronize label taxonomy from Gitea.
**Personality:** Thoughtful, methodical, asks clarifying questions **Personality:** Thoughtful, methodical, asks clarifying questions
**Responsibilities:** **Responsibilities:**
- Pre-planning validations (org, labels, folder structure)
- Sprint planning and architecture analysis - Sprint planning and architecture analysis
- Asking clarifying questions before making assumptions - Asking clarifying questions before making assumptions
- Searching relevant lessons learned - Searching relevant lessons learned via Gitea Wiki
- Creating well-structured Gitea issues - Creating well-structured Gitea issues
- Setting up issue dependencies
- Suggesting appropriate labels based on context - Suggesting appropriate labels based on context
**Invoked by:** `/sprint-plan` **Invoked by:** `/sprint-plan`
@@ -209,11 +194,11 @@ Synchronize label taxonomy from Gitea.
**Personality:** Concise, action-oriented, detail-focused **Personality:** Concise, action-oriented, detail-focused
**Responsibilities:** **Responsibilities:**
- Coordinating sprint execution - Coordinating sprint execution with parallel batching
- Generating lean execution prompts (not full documents) - Generating lean execution prompts (not full documents)
- Tracking progress meticulously - Tracking progress meticulously
- Managing Git operations - Managing Git operations
- Handling task dependencies - Handling task dependencies via `get_execution_order`
- Capturing lessons learned at sprint close - Capturing lessons learned at sprint close
**Invoked by:** `/sprint-start`, `/sprint-close` **Invoked by:** `/sprint-start`, `/sprint-close`
@@ -225,14 +210,72 @@ Synchronize label taxonomy from Gitea.
- Providing implementation guidance - Providing implementation guidance
- Writing clean, tested code - Writing clean, tested code
- Following architectural decisions from planning - Following architectural decisions from planning
- Generating completion reports - Creating branches with proper naming (`feat/`, `fix/`, `debug/`)
- Generating MR body template
- Code review and quality standards - Code review and quality standards
**Usage:** Can be invoked by the orchestrator when implementation guidance is needed. **MR Body Template:**
```markdown
## Summary
<1-3 bullet points>
## Test plan
<Testing approach>
Closes #<issue-number>
```
## MCP Tools
### Issue Tools
| Tool | Description |
|------|-------------|
| `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 |
### Label Tools
| Tool | Description |
|------|-------------|
| `get_labels` | Fetch org + repo label taxonomy |
| `suggest_labels` | Analyze context and suggest appropriate labels |
| `create_label` | Create missing required labels |
### Milestone Tools
| Tool | Description |
|------|-------------|
| `list_milestones` | List sprint milestones |
| `get_milestone` | Get milestone details |
| `create_milestone` | Create sprint milestone |
| `update_milestone` | Update/close milestone |
### Dependency Tools
| Tool | Description |
|------|-------------|
| `list_issue_dependencies` | Get issue dependencies |
| `create_issue_dependency` | Create dependency between issues |
| `get_execution_order` | Get parallel execution batches |
### Wiki Tools (Gitea Wiki)
| Tool | Description |
|------|-------------|
| `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
| Tool | Description |
|------|-------------|
| `validate_repo_org` | Check repo belongs to organization |
| `get_branch_protection` | Check branch protection rules |
## Label Taxonomy ## Label Taxonomy
The plugin uses a dynamic 44-label taxonomy (28 organization + 16 repository): The plugin uses a dynamic 43-label taxonomy (27 organization + 16 repository):
**Organization Labels:** **Organization Labels:**
- Agent/* (2): Human, Claude - Agent/* (2): Human, Claude
@@ -254,20 +297,19 @@ Labels are fetched dynamically from Gitea using `/labels-sync`.
The plugin implements defense-in-depth branch detection to prevent accidental changes on production: The plugin implements defense-in-depth branch detection to prevent accidental changes on production:
**Development Branches** (`development`, `develop`, `feat/*`, `dev/*`): **Development Branches** (`development`, `develop`, `feat/*`, `dev/*`):
- ✅ Full planning and execution capabilities - Full planning and execution capabilities
- ✅ Can create and modify issues - Can create and modify issues
- ✅ Can capture lessons learned - Can capture lessons learned
**Staging Branches** (`staging`, `stage/*`): **Staging Branches** (`staging`, `stage/*`):
- ✅ Can create issues to document bugs - Can create issues to document bugs
- ❌ Cannot modify code - Cannot modify code
- ⚠️ Warns when attempting changes - Warns when attempting changes
**Production Branches** (`main`, `master`, `prod/*`): **Production Branches** (`main`, `master`, `prod/*`):
- ✅ Read-only access - Read-only access
- ❌ Cannot create issues - Cannot create issues
- ❌ Cannot modify code - Blocks all planning and execution
- 🛑 Blocks all planning and execution
## Lessons Learned System ## Lessons Learned System
@@ -279,8 +321,8 @@ The plugin implements defense-in-depth branch detection to prevent accidental ch
**Solution:** Mandatory lessons learned capture at sprint close, searchable at sprint start. **Solution:** Mandatory lessons learned capture at sprint close, searchable at sprint start.
**Workflow:** **Workflow:**
1. **Sprint Close:** Orchestrator captures lessons (what went wrong, what went right, preventable mistakes) 1. **Sprint Close:** Orchestrator captures lessons via Gitea Wiki tools
2. **Wiki.js Storage:** Lessons saved to `/projects/{project}/lessons-learned/sprints/` 2. **Gitea Wiki Storage:** Lessons saved to repository wiki under `lessons-learned/sprints/`
3. **Sprint Start:** Planner searches relevant lessons by tags and keywords 3. **Sprint Start:** Planner searches relevant lessons by tags and keywords
4. **Prevention:** Apply learned insights to avoid repeating mistakes 4. **Prevention:** Apply learned insights to avoid repeating mistakes
@@ -304,19 +346,57 @@ The plugin implements defense-in-depth branch detection to prevent accidental ch
[technology, component, type] [technology, component, type]
``` ```
## Architecture
```
projman/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest
├── .mcp.json # MCP server configuration
├── mcp-servers/ # Bundled MCP server
│ └── gitea/
│ ├── .venv/
│ ├── requirements.txt
│ ├── mcp_server/
│ │ ├── server.py
│ │ ├── gitea_client.py
│ │ └── tools/
│ │ ├── issues.py
│ │ ├── labels.py
│ │ ├── wiki.py
│ │ ├── milestones.py
│ │ └── dependencies.py
│ └── tests/
├── commands/ # Slash commands
│ ├── sprint-plan.md
│ ├── sprint-start.md
│ ├── sprint-status.md
│ ├── sprint-close.md
│ ├── labels-sync.md
│ └── initial-setup.md
├── agents/ # Agent prompts
│ ├── planner.md
│ ├── orchestrator.md
│ └── executor.md
├── skills/ # Supporting knowledge
│ └── label-taxonomy/
│ └── labels-reference.md
├── README.md # This file
└── CONFIGURATION.md # Setup guide
```
## Configuration ## Configuration
See [CONFIGURATION.md](./CONFIGURATION.md) for detailed configuration instructions. See [CONFIGURATION.md](./CONFIGURATION.md) for detailed configuration instructions.
**Quick summary:** **Quick summary:**
- **System-level:** `~/.config/claude/gitea.env` and `wikijs.env` (credentials) - **System-level:** `~/.config/claude/gitea.env` (credentials)
- **Project-level:** `.env` in project root (repository and project paths) - **Project-level:** `.env` in project root (repository specification)
- **MCP Servers:** Located at `../mcp-servers/` (shared by multiple plugins)
## Troubleshooting ## Troubleshooting
### Plugin not loading ### Plugin not loading
- Check that MCP servers are installed: `ls ../mcp-servers/gitea/.venv` - Check that MCP server is installed: `ls mcp-servers/gitea/.venv`
- Verify plugin manifest: `cat .claude-plugin/plugin.json | jq` - Verify plugin manifest: `cat .claude-plugin/plugin.json | jq`
- Check Claude Code logs for errors - Check Claude Code logs for errors
@@ -325,11 +405,6 @@ See [CONFIGURATION.md](./CONFIGURATION.md) for detailed configuration instructio
- Test token: `curl -H "Authorization: token YOUR_TOKEN" https://gitea.example.com/api/v1/user` - Test token: `curl -H "Authorization: token YOUR_TOKEN" https://gitea.example.com/api/v1/user`
- Check network connectivity - Check network connectivity
### Cannot connect to Wiki.js
- Verify `~/.config/claude/wikijs.env` exists and has correct URL and token
- Check Wiki.js GraphQL endpoint: `https://wiki.your-company.com/graphql`
- Verify API token has pages read/write permissions
### Labels not syncing ### Labels not syncing
- Run `/labels-sync` manually - Run `/labels-sync` manually
- Check Gitea API token has `read:org` and `repo` permissions - Check Gitea API token has `read:org` and `repo` permissions
@@ -340,100 +415,28 @@ See [CONFIGURATION.md](./CONFIGURATION.md) for detailed configuration instructio
- Check current branch: `git branch --show-current` - Check current branch: `git branch --show-current`
- If on wrong branch, switch: `git checkout development` - If on wrong branch, switch: `git checkout development`
## Architecture
```
projman/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest
├── .mcp.json # MCP server configuration
├── commands/ # Slash commands
│ ├── sprint-plan.md
│ ├── sprint-start.md
│ ├── sprint-status.md
│ ├── sprint-close.md
│ └── labels-sync.md
├── agents/ # Agent prompts (Phase 3)
│ ├── planner.md
│ ├── orchestrator.md
│ └── executor.md
├── skills/ # Supporting knowledge
│ └── label-taxonomy/
│ └── labels-reference.md
├── README.md # This file
└── CONFIGURATION.md # Setup guide
```
**MCP Servers (shared):**
```
../mcp-servers/
├── gitea/ # Gitea MCP server
│ ├── .venv/
│ ├── mcp_server/
│ └── tests/
└── wikijs/ # Wiki.js MCP server
├── .venv/
├── mcp_server/
└── tests/
```
## Workflow Example
**Complete Sprint Lifecycle:**
```bash
# 1. Plan the sprint
/sprint-plan
> "Extract Intuit Engine service from monolith"
[Planner asks questions, searches lessons, creates issues]
# 2. Start execution
/sprint-start
[Orchestrator reviews issues, finds relevant lessons, identifies next task]
# 3. Check progress daily
/sprint-status
[See completion percentage, blockers, priorities]
# 4. Close sprint and capture lessons
/sprint-close
[Orchestrator captures lessons learned, saves to Wiki.js]
# Next sprint uses those lessons automatically!
```
## Support ## Support
**Documentation:** **Documentation:**
- [CONFIGURATION.md](./CONFIGURATION.md) - Setup and configuration - [CONFIGURATION.md](./CONFIGURATION.md) - Setup and configuration
- [Gitea MCP Server](../mcp-servers/gitea/README.md) - Gitea integration details
- [Wiki.js MCP Server](../mcp-servers/wikijs/README.md) - Wiki.js integration details
**Issues:** **Issues:**
- Report bugs: Contact repository maintainer - Report bugs: Contact repository maintainer
- Feature requests: Contact repository maintainer - Feature requests: Contact repository maintainer
- Documentation improvements: Submit PR
## License ## License
MIT License - See repository root for details MIT License - See repository root for details
## Related Plugins
- **projman-pmo** - Multi-project PMO coordination (build after projman is validated)
## Version ## Version
**Current:** 0.1.0 (Phase 2 - Commands implemented) **Current:** 1.0.0
**Roadmap:** **Changelog:**
- Phase 3: Agent system implementation - v1.0.0: Full Gitea integration with wiki, milestones, dependencies, parallel execution
- Phase 4: Lessons learned integration - v0.1.0: Initial commands implementation
- Phase 5: Testing and validation
- Phase 6-8: Documentation, marketplace, production
--- ---
**Built for:** Bandit Labs **Built for:** Bandit Labs
**Status:** Phase 2 Complete - Commands ready for testing **Status:** Production Ready
**Next:** Implement agent system (Phase 3)