diff --git a/README.md b/README.md index 1c5867a..dfabcee 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,34 @@ # 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 -### [projman](./plugins/projman/README.md) +### [projman](./plugins/projman/README.md) v1.0.0 **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 -- Intelligent label suggestions from 44-label taxonomy -- Lessons learned capture to prevent repeated mistakes +- Intelligent label suggestions from 43-label taxonomy +- Lessons learned capture via Gitea Wiki +- Native issue dependencies with parallel execution +- Milestone management for sprint organization - Branch-aware security (development/staging/production) -**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) **NetBox CMDB Integration** @@ -35,41 +49,28 @@ Hook-based cleanup that runs after Claude completes work. - Deletes temp files (`*.tmp`, `*.bak`, `__pycache__`, etc.) - Warns about unexpected files in project root -- Identifies orphaned supporting files (`test_*`, `debug_*`, `*_backup.*`) -- Logs actions to `.dev/logs/` +- Identifies orphaned supporting files - Configurable via `.hygiene.json` -**Hook:** `task-completed` - ## 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) -Issue management, label operations, and repository tracking for Gitea. +### Gitea MCP Server (bundled in projman) -| Tool | Description | -|------|-------------| -| `list_issues` | Query issues with filters | -| `create_issue` | Create issue with labels | -| `get_labels` | Fetch org + repo labels | -| `suggest_labels` | Intelligent label suggestions | +Full Gitea API integration for project management. -**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) -Documentation management and lessons learned capture via GraphQL. +### NetBox MCP Server (bundled in cmdb-assistant) -| 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. | Module | Coverage | @@ -80,15 +81,13 @@ Comprehensive NetBox REST API integration for infrastructure management. | Virtualization | Clusters, VMs, Interfaces | | Extras | Tags, Custom Fields, Audit Log | -**Status:** Production Ready - ## Installation ### Prerequisites - Claude Code installed - Python 3.10+ -- Access to target services (Gitea, Wiki.js, NetBox as needed) +- Access to target services (Gitea, NetBox as needed) ### Quick Start @@ -100,35 +99,33 @@ Comprehensive NetBox REST API integration for infrastructure management. 2. **Install MCP server dependencies:** ```bash - # Gitea MCP - cd mcp-servers/gitea && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt + # Gitea MCP (for projman) + cd plugins/projman/mcp-servers/gitea + python3 -m venv .venv + source .venv/bin/activate + pip install -r requirements.txt + deactivate - # Wiki.js MCP - cd ../wikijs && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt - - # NetBox MCP - cd ../netbox && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt + # NetBox MCP (for cmdb-assistant) + cd ../../../cmdb-assistant/mcp-servers/netbox + python3 -m venv .venv + source .venv/bin/activate + pip install -r requirements.txt + deactivate ``` -3. **Configure credentials:** +3. **Configure system-level credentials:** ```bash mkdir -p ~/.config/claude - # Gitea + # Gitea credentials cat > ~/.config/claude/gitea.env << 'EOF' - GITEA_API_URL=https://gitea.example.com/api/v1 - GITEA_API_TOKEN=your_token - GITEA_OWNER=your_org + GITEA_URL=https://gitea.example.com + GITEA_TOKEN=your_token + GITEA_ORG=your_org EOF - # Wiki.js - 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 + # NetBox credentials cat > ~/.config/claude/netbox.env << 'EOF' NETBOX_API_URL=https://netbox.example.com/api NETBOX_API_TOKEN=your_token @@ -137,101 +134,85 @@ Comprehensive NetBox REST API integration for infrastructure management. chmod 600 ~/.config/claude/*.env ``` -4. **Add marketplace to Claude Code:** +4. **Configure project-level settings:** ```bash - claude plugin marketplace add /path/to/support-claude-mktplace - claude plugin install projman - claude plugin install cmdb-assistant - claude plugin install project-hygiene + # In your target project root + cat > .env << 'EOF' + GITEA_REPO=your-repository-name + EOF + ``` + +5. **Add marketplace to Claude Code:** + + Add to your project's `.claude/settings.json`: + ```json + { + "pluginMarketplace": "/path/to/support-claude-mktplace" + } ``` ## Repository Structure ``` support-claude-mktplace/ -├── plugins/ # All plugins -│ ├── projman/ # Sprint management plugin +├── .claude-plugin/ # Marketplace manifest +│ └── marketplace.json +├── plugins/ # All plugins (with bundled MCP servers) +│ ├── projman/ # Sprint management plugin │ │ ├── .claude-plugin/ +│ │ ├── .mcp.json +│ │ ├── mcp-servers/ # Bundled MCP server +│ │ │ └── gitea/ │ │ ├── commands/ │ │ ├── agents/ │ │ └── skills/ -│ ├── projman-pmo/ # PMO coordination plugin +│ ├── claude-config-maintainer/ # CLAUDE.md optimization plugin │ │ ├── .claude-plugin/ │ │ ├── commands/ │ │ └── agents/ -│ ├── project-hygiene/ # Cleanup automation plugin +│ ├── cmdb-assistant/ # NetBox CMDB integration │ │ ├── .claude-plugin/ -│ │ └── hooks/ -│ └── cmdb-assistant/ # NetBox CMDB integration -│ ├── .claude-plugin/ -│ ├── commands/ -│ └── agents/ -├── mcp-servers/ # Shared MCP servers -│ ├── gitea/ -│ ├── wikijs/ -│ └── netbox/ -├── .claude-plugin/ # Marketplace manifest (bandit-claude-marketplace) -│ └── marketplace.json -├── docs/ # Reference documentation +│ │ ├── .mcp.json +│ │ ├── mcp-servers/ # Bundled MCP server +│ │ │ └── netbox/ +│ │ ├── commands/ +│ │ └── agents/ +│ ├── projman-pmo/ # PMO coordination plugin (planned) +│ └── project-hygiene/ # Cleanup automation plugin +├── docs/ # Reference documentation +│ ├── CANONICAL-PATHS.md # Single source of truth for paths │ └── 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] : ` +- **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 -### 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 | |----------|-------------| +| [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 | -| [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 -- [x] **Phase 1-2**: MCP servers and commands (Complete) -- [ ] **Phase 3**: Agent system implementation -- [ ] **Phase 4**: Lessons learned integration -- [ ] **Phase 5-8**: Testing, documentation, production +- [x] **Phase 1-8**: projman v1.0.0 (Complete) - [ ] **Phase 9-11**: PMO plugin for multi-project coordination - [ ] **Phase 12**: Public marketplace distribution diff --git a/plugins/projman/README.md b/plugins/projman/README.md index 7ed1a66..8b80c0d 100644 --- a/plugins/projman/README.md +++ b/plugins/projman/README.md @@ -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 -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:** -- 🎯 **Sprint Planning** - AI-guided architecture analysis and issue creation -- 🏷️ **Smart Label Suggestions** - Intelligent label recommendations from 44-label taxonomy -- 📚 **Lessons Learned** - Systematic capture and search of sprint insights -- 🔒 **Branch-Aware Security** - Prevents accidental changes on production branches -- ⚙️ **Hybrid Configuration** - Simple setup with system + project-level config -- 🤖 **Three-Agent Model** - Planner, Orchestrator, and Executor agents +- **Sprint Planning** - AI-guided architecture analysis and issue creation +- **Smart Label Suggestions** - Intelligent label recommendations from 43-label taxonomy +- **Issue Dependencies** - Native Gitea dependencies with parallel execution batching +- **Milestones** - Sprint milestone management and tracking +- **Lessons Learned** - Systematic capture and search via Gitea Wiki +- **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 @@ -20,52 +22,38 @@ Projman transforms a proven 15-sprint workflow into a distributable Claude Code - Claude Code installed - Access to Gitea instance with API token -- Access to Wiki.js instance with API token - Python 3.10+ installed - 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 -# Navigate to MCP servers directory -cd ../mcp-servers/gitea -python -m venv .venv +cd plugins/projman/mcp-servers/gitea +python3 -m venv .venv source .venv/bin/activate # or .venv\Scripts\activate on Windows 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. ### 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 mkdir -p ~/.config/claude # Gitea configuration -cat > ~/.config/claude/gitea.env << EOF -GITEA_API_URL=https://gitea.example.com/api/v1 -GITEA_API_TOKEN=your_gitea_token_here -GITEA_OWNER=bandit +cat > ~/.config/claude/gitea.env << 'EOF' +GITEA_URL=https://gitea.example.com +GITEA_TOKEN=your_gitea_token_here +GITEA_ORG=your_organization EOF -# Wiki.js configuration -cat > ~/.config/claude/wikijs.env << EOF -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 +# Secure the file +chmod 600 ~/.config/claude/gitea.env ``` ### 4. Configure Project-Level Settings @@ -74,21 +62,15 @@ In your project root directory, create a `.env` file: ```bash # In your project directory -cat > .env << EOF +cat > .env << 'EOF' GITEA_REPO=your-repo-name -WIKIJS_PROJECT=projects/your-project-name EOF - -# Add to .gitignore -echo ".env" >> .gitignore ``` -### 5. Sync Label Taxonomy - -Fetch the label taxonomy from Gitea: +### 5. Run Initial Setup ```bash -/labels-sync +/initial-setup ``` ### 6. Start Planning! @@ -103,54 +85,54 @@ Fetch the label taxonomy from Gitea: Start sprint planning with the AI planner agent. **What it does:** +- Validates repository organization and label taxonomy - Asks clarifying questions about sprint goals - Searches relevant lessons learned from previous sprints - Performs architecture analysis - 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] : ` **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` Begin sprint execution with the orchestrator agent. **What it does:** -- Reviews open sprint issues -- Searches relevant lessons learned by tags -- Identifies next task based on priority and dependencies +- Reviews open sprint issues and dependencies +- Batches tasks by dependency graph for parallel execution - Generates lean execution prompts - 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:** -``` -/sprint-start -``` +**Branch Naming:** `feat/123-task-title`, `fix/456-bug-fix`, `debug/789-investigation` + +**When to use:** After planning, when ready to start implementation ### `/sprint-status` Check current sprint progress. **What it does:** - Lists all sprint issues by status (open, in progress, blocked, completed) -- Identifies blockers and priorities -- Shows completion percentage -- Highlights critical items needing attention +- Shows dependency analysis and blocked tasks +- Displays completion percentage +- Shows milestone progress **When to use:** Daily standup, progress check, deciding what to work on next -**Example:** -``` -/sprint-status -``` - ### `/sprint-close` Complete sprint and capture lessons learned. @@ -158,38 +140,39 @@ Complete sprint and capture lessons learned. - Reviews sprint completion - Captures lessons learned (what went wrong, what went right) - Tags lessons for discoverability -- Saves lessons to Wiki.js +- Saves lessons to Gitea Wiki +- Closes sprint milestone - Handles git operations (merge, tag, cleanup) **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. ### `/labels-sync` Synchronize label taxonomy from Gitea. **What it does:** +- Validates repository belongs to organization - Fetches current labels from Gitea (org + repo) +- Validates required label categories - Compares with local reference -- Detects changes (new, modified, removed labels) - Updates local taxonomy reference -- Updates suggestion logic **When to use:** - First-time setup - Monthly maintenance - When new labels are added to Gitea -- When label suggestions seem incorrect -**Example:** -``` -/labels-sync -``` +### `/initial-setup` +Run initial setup for a new project. + +**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 @@ -197,10 +180,12 @@ Synchronize label taxonomy from Gitea. **Personality:** Thoughtful, methodical, asks clarifying questions **Responsibilities:** +- Pre-planning validations (org, labels, folder structure) - Sprint planning and architecture analysis - Asking clarifying questions before making assumptions -- Searching relevant lessons learned +- Searching relevant lessons learned via Gitea Wiki - Creating well-structured Gitea issues +- Setting up issue dependencies - Suggesting appropriate labels based on context **Invoked by:** `/sprint-plan` @@ -209,11 +194,11 @@ Synchronize label taxonomy from Gitea. **Personality:** Concise, action-oriented, detail-focused **Responsibilities:** -- Coordinating sprint execution +- Coordinating sprint execution with parallel batching - Generating lean execution prompts (not full documents) - Tracking progress meticulously - Managing Git operations -- Handling task dependencies +- Handling task dependencies via `get_execution_order` - Capturing lessons learned at sprint close **Invoked by:** `/sprint-start`, `/sprint-close` @@ -225,14 +210,72 @@ Synchronize label taxonomy from Gitea. - Providing implementation guidance - Writing clean, tested code - 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 -**Usage:** Can be invoked by the orchestrator when implementation guidance is needed. +**MR Body Template:** +```markdown +## Summary +<1-3 bullet points> + +## Test plan + + +Closes # +``` + +## 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 -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:** - 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: **Development Branches** (`development`, `develop`, `feat/*`, `dev/*`): -- ✅ Full planning and execution capabilities -- ✅ Can create and modify issues -- ✅ Can capture lessons learned +- Full planning and execution capabilities +- Can create and modify issues +- Can capture lessons learned **Staging Branches** (`staging`, `stage/*`): -- ✅ Can create issues to document bugs -- ❌ Cannot modify code -- ⚠️ Warns when attempting changes +- Can create issues to document bugs +- Cannot modify code +- Warns when attempting changes **Production Branches** (`main`, `master`, `prod/*`): -- ✅ Read-only access -- ❌ Cannot create issues -- ❌ Cannot modify code -- 🛑 Blocks all planning and execution +- Read-only access +- Cannot create issues +- Blocks all planning and execution ## 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. **Workflow:** -1. **Sprint Close:** Orchestrator captures lessons (what went wrong, what went right, preventable mistakes) -2. **Wiki.js Storage:** Lessons saved to `/projects/{project}/lessons-learned/sprints/` +1. **Sprint Close:** Orchestrator captures lessons via Gitea Wiki tools +2. **Gitea Wiki Storage:** Lessons saved to repository wiki under `lessons-learned/sprints/` 3. **Sprint Start:** Planner searches relevant lessons by tags and keywords 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] ``` +## 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 See [CONFIGURATION.md](./CONFIGURATION.md) for detailed configuration instructions. **Quick summary:** -- **System-level:** `~/.config/claude/gitea.env` and `wikijs.env` (credentials) -- **Project-level:** `.env` in project root (repository and project paths) -- **MCP Servers:** Located at `../mcp-servers/` (shared by multiple plugins) +- **System-level:** `~/.config/claude/gitea.env` (credentials) +- **Project-level:** `.env` in project root (repository specification) ## Troubleshooting ### 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` - 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` - 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 - Run `/labels-sync` manually - 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` - 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 **Documentation:** - [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:** - Report bugs: Contact repository maintainer - Feature requests: Contact repository maintainer -- Documentation improvements: Submit PR ## License MIT License - See repository root for details -## Related Plugins - -- **projman-pmo** - Multi-project PMO coordination (build after projman is validated) - ## Version -**Current:** 0.1.0 (Phase 2 - Commands implemented) +**Current:** 1.0.0 -**Roadmap:** -- Phase 3: Agent system implementation -- Phase 4: Lessons learned integration -- Phase 5: Testing and validation -- Phase 6-8: Documentation, marketplace, production +**Changelog:** +- v1.0.0: Full Gitea integration with wiki, milestones, dependencies, parallel execution +- v0.1.0: Initial commands implementation --- **Built for:** Bandit Labs -**Status:** Phase 2 Complete - Commands ready for testing -**Next:** Implement agent system (Phase 3) +**Status:** Production Ready