Merge pull request 'development: final tuning adjustments' (#33) from development into main
Reviewed-on: personal-projects/support-claude-mktplace#33
This commit was merged in pull request #33.
This commit is contained in:
609
CLAUDE.md
609
CLAUDE.md
@@ -1,478 +1,195 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
This file provides guidance to Claude Code when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
This repository contains Claude Code plugins for project management:
|
||||
**Repository:** support-claude-mktplace
|
||||
**Version:** 2.2.0
|
||||
**Status:** Production Ready
|
||||
|
||||
1. **`projman`** - Single-repository project management plugin with Gitea integration
|
||||
2. **`projman-pmo`** - Multi-project PMO coordination plugin
|
||||
3. **`claude-config-maintainer`** - CLAUDE.md optimization and maintenance plugin
|
||||
4. **`cmdb-assistant`** - NetBox CMDB integration for infrastructure management
|
||||
A Claude Code plugin marketplace containing:
|
||||
|
||||
These plugins transform a proven 15-sprint workflow into reusable, distributable tools for managing software development with Claude Code, Gitea, and agile methodologies.
|
||||
| Plugin | Description | Version |
|
||||
|--------|-------------|---------|
|
||||
| `projman` | Sprint planning and project management with Gitea integration | 2.2.0 |
|
||||
| `claude-config-maintainer` | CLAUDE.md optimization and maintenance | 1.0.0 |
|
||||
| `cmdb-assistant` | NetBox CMDB integration for infrastructure management | 1.0.0 |
|
||||
| `project-hygiene` | Post-task cleanup automation via hooks | 0.1.0 |
|
||||
|
||||
**Status:** projman v1.0.0 complete with full Gitea integration
|
||||
## Quick Start
|
||||
|
||||
## File Creation Governance
|
||||
```bash
|
||||
# Validate marketplace compliance
|
||||
./scripts/validate-marketplace.sh
|
||||
|
||||
### Allowed Root Files
|
||||
# Run projman commands (in a target project with plugin installed)
|
||||
/sprint-plan # Start sprint planning
|
||||
/sprint-status # Check progress
|
||||
/review # Pre-close code quality review
|
||||
/test-check # Verify tests before close
|
||||
/sprint-close # Complete sprint
|
||||
```
|
||||
|
||||
Only these files may exist at the repository root:
|
||||
|
||||
- `CLAUDE.md` - This file
|
||||
- `README.md` - Repository overview
|
||||
- `LICENSE` - License file
|
||||
- `CHANGELOG.md` - Version history
|
||||
- `.gitignore` - Git ignore rules
|
||||
- `.env.example` - Environment template (if needed)
|
||||
|
||||
### Allowed Root Directories
|
||||
|
||||
Only these directories may exist at the repository root:
|
||||
|
||||
| Directory | Purpose |
|
||||
|-----------|---------|
|
||||
| `.claude/` | Claude Code local settings |
|
||||
| `.claude-plugin/` | Marketplace manifest |
|
||||
| `.claude-plugins/` | Local marketplace definitions |
|
||||
| `.scratch/` | Transient work (auto-cleaned) |
|
||||
| `docs/` | Documentation |
|
||||
| `hooks/` | Shared hooks (if any) |
|
||||
| `plugins/` | All plugins (projman, projman-pmo, project-hygiene, cmdb-assistant, claude-config-maintainer) |
|
||||
| `scripts/` | Setup and maintenance scripts |
|
||||
|
||||
### File Creation Rules
|
||||
|
||||
1. **No new root files** - Do not create files directly in the repository root unless listed above
|
||||
2. **No new root directories** - Do not create top-level directories without explicit approval
|
||||
3. **Transient work goes in `.scratch/`** - Any temporary files, test outputs, or exploratory work must be created in `.scratch/`
|
||||
4. **Clean up after tasks** - Delete files in `.scratch/` when the task is complete
|
||||
5. **Documentation location** - All documentation goes in `docs/` with appropriate subdirectory:
|
||||
- `docs/references/` - Reference specifications and summaries
|
||||
- `docs/architecture/` - Architecture diagrams (Draw.io files)
|
||||
- `docs/workflows/` - Workflow documentation
|
||||
6. **No output files** - Do not leave generated output, logs, or test results outside designated directories
|
||||
|
||||
### Enforcement
|
||||
|
||||
Before creating any file, verify:
|
||||
|
||||
1. Is this file type allowed in the target location?
|
||||
2. If temporary, am I using `.scratch/`?
|
||||
3. If documentation, am I using the correct `docs/` subdirectory?
|
||||
4. Will this file be cleaned up after the task?
|
||||
|
||||
**Violation of these rules creates technical debt and project chaos.**
|
||||
|
||||
## Path Verification (MANDATORY)
|
||||
|
||||
### Before Generating Any Prompt or Creating Any File
|
||||
|
||||
**This is non-negotiable. Failure to follow causes structural damage.**
|
||||
|
||||
1. **READ `docs/CANONICAL-PATHS.md` FIRST**
|
||||
- This file is the single source of truth
|
||||
- Never infer paths from memory or context
|
||||
- Never assume paths based on conversation history
|
||||
|
||||
2. **List All Paths**
|
||||
- Before generating a prompt, list every file path it will create/modify
|
||||
- Show the list to the user
|
||||
|
||||
3. **Verify Each Path**
|
||||
- Check each path against `docs/CANONICAL-PATHS.md`
|
||||
- If a path is not in that file, STOP and ask
|
||||
|
||||
4. **Show Verification**
|
||||
- Present a verification table to user:
|
||||
```
|
||||
| Path | Matches CANONICAL-PATHS.md? |
|
||||
|------|----------------------------|
|
||||
| plugins/projman/... | ✅ Yes |
|
||||
```
|
||||
|
||||
5. **Get Confirmation**
|
||||
- User must confirm paths are correct before proceeding
|
||||
|
||||
### Relative Path Rules
|
||||
|
||||
- Plugin to bundled MCP server: `${CLAUDE_PLUGIN_ROOT}/mcp-servers/{server}`
|
||||
- Marketplace to plugin: `./../../../plugins/{plugin-name}`
|
||||
- **ALWAYS calculate from CANONICAL-PATHS.md, never from memory**
|
||||
|
||||
### Recovery Protocol
|
||||
|
||||
If you suspect paths are wrong:
|
||||
1. Read `docs/CANONICAL-PATHS.md`
|
||||
2. Compare actual structure against documented structure
|
||||
3. Report discrepancies
|
||||
4. Generate corrective prompt if needed
|
||||
|
||||
## Core Architecture
|
||||
|
||||
### Three-Agent Model
|
||||
|
||||
The plugins implement a three-agent architecture that mirrors the proven workflow:
|
||||
|
||||
**Planner Agent** (`agents/planner.md`)
|
||||
- Performs architecture analysis and sprint planning
|
||||
- Creates detailed planning documents
|
||||
- Makes architectural decisions
|
||||
- Creates Gitea issues with appropriate labels
|
||||
- Personality: Asks clarifying questions, thinks through edge cases, never rushes
|
||||
|
||||
**Orchestrator Agent** (`agents/orchestrator.md`)
|
||||
- Coordinates sprint execution
|
||||
- Generates lean execution prompts (not full docs)
|
||||
- Tracks progress and updates documentation
|
||||
- Handles Git operations (commit, merge, cleanup)
|
||||
- Manages task dependencies
|
||||
- Personality: Concise, action-oriented, tracks details meticulously
|
||||
|
||||
**Executor Agent** (`agents/executor.md`)
|
||||
- Implements features according to execution prompts
|
||||
- Writes clean, tested code
|
||||
- Follows architectural decisions from planning
|
||||
- Generates completion reports
|
||||
- Personality: Implementation-focused, follows specs precisely
|
||||
|
||||
### MCP Server Integration
|
||||
|
||||
**Gitea MCP Server** (Python) - bundled in projman plugin
|
||||
|
||||
**Issue Tools:**
|
||||
- `list_issues` - Query issues with filters
|
||||
- `get_issue` - Fetch single issue details
|
||||
- `create_issue` - Create new issue with labels
|
||||
- `update_issue` - Modify existing issue
|
||||
- `add_comment` - Add comments to issues
|
||||
- `get_labels` - Fetch org + repo label taxonomy
|
||||
- `suggest_labels` - Analyze context and suggest appropriate labels
|
||||
|
||||
**Milestone Tools:**
|
||||
- `list_milestones` - List sprint milestones
|
||||
- `get_milestone` - Get milestone details
|
||||
- `create_milestone` - Create sprint milestone
|
||||
- `update_milestone` - Update/close milestone
|
||||
|
||||
**Dependency Tools:**
|
||||
- `list_issue_dependencies` - Get issue dependencies
|
||||
- `create_issue_dependency` - Create dependency between issues
|
||||
- `get_execution_order` - Get parallel execution batches
|
||||
|
||||
**Wiki Tools (Gitea Wiki):**
|
||||
- `list_wiki_pages` - List wiki pages
|
||||
- `get_wiki_page` - Fetch specific page content
|
||||
- `create_wiki_page` - Create new wiki page
|
||||
- `create_lesson` - Create lessons learned document
|
||||
- `search_lessons` - Search past lessons by tags
|
||||
|
||||
**Validation Tools:**
|
||||
- `validate_repo_org` - Check repo belongs to organization
|
||||
- `get_branch_protection` - Check branch protection rules
|
||||
- `create_label` - Create missing required labels
|
||||
|
||||
**Key Architecture Points:**
|
||||
- MCP servers are **bundled inside each plugin** at `plugins/{plugin}/mcp-servers/`
|
||||
- This ensures plugins work when cached by Claude Code (only plugin directory is cached)
|
||||
- Configuration uses hybrid approach (system-level + project-level)
|
||||
- All plugins reference `${CLAUDE_PLUGIN_ROOT}/mcp-servers/` in their `.mcp.json` files
|
||||
|
||||
## Branch-Aware Security Model
|
||||
|
||||
Plugin behavior adapts to the current Git branch to prevent accidental changes:
|
||||
|
||||
**Development Mode** (`development`, `feat/*`)
|
||||
- Full access to all operations
|
||||
- Can create Gitea issues
|
||||
- Can modify all files
|
||||
|
||||
**Staging Mode** (`staging`)
|
||||
- Read-only for application code
|
||||
- Can modify `.env` files
|
||||
- Can create issues to document needed fixes
|
||||
- Warns on attempted code changes
|
||||
|
||||
**Production Mode** (`main`)
|
||||
- Read-only for application code
|
||||
- Emergency-only `.env` modifications
|
||||
- Can create incident issues
|
||||
- Blocks code changes
|
||||
|
||||
This behavior is implemented in both CLAUDE.md (file-level) and plugin agents (tool-level).
|
||||
|
||||
## Label Taxonomy System
|
||||
|
||||
The project uses a sophisticated 43-label taxonomy at organization level:
|
||||
|
||||
**Organization Labels (27):**
|
||||
- Agent/2, Complexity/3, Efforts/5, Priority/4, Risk/3, Source/4, Type/6
|
||||
|
||||
**Repository Labels (16):**
|
||||
- Component/9, Tech/7
|
||||
|
||||
**Important Labels:**
|
||||
- `Type/Refactor` - For architectural changes and code restructuring (exclusive Type label)
|
||||
- Used for service extraction, architecture modifications, technical debt
|
||||
|
||||
The label system includes:
|
||||
- `skills/label-taxonomy/labels-reference.md` - Local reference synced from Gitea
|
||||
- Label suggestion logic that detects appropriate labels from context
|
||||
- `/labels-sync` command to review and sync changes from Gitea
|
||||
|
||||
## Lessons Learned System
|
||||
|
||||
**Critical Feature:** After 15 sprints without lesson capture, repeated mistakes occurred (e.g., Claude Code infinite loops on similar issues 2-3 times).
|
||||
|
||||
**Gitea Wiki Structure:**
|
||||
Lessons learned are stored in the Gitea repository's built-in wiki under `lessons-learned/sprints/`.
|
||||
|
||||
**Workflow:**
|
||||
- Orchestrator captures lessons at sprint close via Gitea Wiki MCP tools
|
||||
- Planner searches relevant lessons at sprint start using `search_lessons`
|
||||
- Tags enable cross-project lesson discovery
|
||||
- Focus on preventable repetitions, not every detail
|
||||
- Web interface available through Gitea Wiki
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Build Order
|
||||
|
||||
1. **Phase 1-8:** Build `projman` plugin first (single-repo)
|
||||
2. **Phase 9-11:** Build `pmo` plugin second (multi-project)
|
||||
3. **Phase 12:** Production deployment
|
||||
|
||||
See [docs/reference-material/projman-implementation-plan.md](docs/reference-material/projman-implementation-plan.md) for the complete 12-phase implementation plan.
|
||||
|
||||
### Repository Structure (DEFINITIVE)
|
||||
|
||||
⚠️ **See `docs/CANONICAL-PATHS.md` for the authoritative path reference - THIS IS THE SINGLE SOURCE OF TRUTH**
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
personal-projects/support-claude-mktplace/
|
||||
support-claude-mktplace/
|
||||
├── .claude-plugin/
|
||||
│ └── marketplace.json
|
||||
├── plugins/ # ← ALL PLUGINS (with bundled MCP servers)
|
||||
│ ├── projman/ # ← PROJECT PLUGIN
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ │ └── plugin.json
|
||||
│ │ ├── .mcp.json # Points to ${CLAUDE_PLUGIN_ROOT}/mcp-servers/
|
||||
│ │ ├── mcp-servers/ # ← MCP servers BUNDLED IN plugin
|
||||
│ │ │ └── gitea/ # Gitea + Wiki tools
|
||||
│ │ │ ├── .venv/
|
||||
│ │ │ ├── requirements.txt
|
||||
│ │ │ ├── mcp_server/
|
||||
│ │ │ └── tests/
|
||||
│ │ ├── commands/
|
||||
│ │ │ ├── sprint-plan.md
|
||||
│ │ │ ├── sprint-start.md
|
||||
│ │ │ ├── sprint-status.md
|
||||
│ │ │ ├── sprint-close.md
|
||||
│ │ │ ├── labels-sync.md
|
||||
│ │ │ └── initial-setup.md
|
||||
│ │ ├── agents/
|
||||
│ │ │ ├── planner.md
|
||||
│ │ │ ├── orchestrator.md
|
||||
│ │ │ └── executor.md
|
||||
│ │ ├── skills/
|
||||
│ │ │ └── label-taxonomy/
|
||||
│ │ │ └── labels-reference.md
|
||||
│ │ ├── README.md
|
||||
│ │ └── CONFIGURATION.md
|
||||
│ ├── projman-pmo/ # ← PMO PLUGIN
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ │ └── plugin.json
|
||||
│ └── marketplace.json # Marketplace manifest
|
||||
├── plugins/
|
||||
│ ├── projman/ # Sprint management (v2.2.0)
|
||||
│ │ ├── .claude-plugin/plugin.json
|
||||
│ │ ├── .mcp.json
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ │ └── pmo-coordinator.md
|
||||
│ │ └── README.md
|
||||
│ ├── cmdb-assistant/ # ← CMDB PLUGIN
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ │ └── plugin.json
|
||||
│ │ ├── .mcp.json # Points to ${CLAUDE_PLUGIN_ROOT}/mcp-servers/
|
||||
│ │ ├── mcp-servers/ # ← MCP servers BUNDLED IN plugin
|
||||
│ │ │ └── netbox/
|
||||
│ │ │ ├── .venv/
|
||||
│ │ │ ├── requirements.txt
|
||||
│ │ │ └── mcp_server/
|
||||
│ │ ├── commands/
|
||||
│ │ └── agents/
|
||||
│ └── project-hygiene/ # ← CLEANUP PLUGIN
|
||||
│ └── ...
|
||||
├── scripts/ # Setup and maintenance scripts
|
||||
│ ├── setup.sh
|
||||
│ └── post-update.sh
|
||||
│ │ ├── mcp-servers/gitea/ # Bundled MCP server
|
||||
│ │ ├── commands/ # 8 commands
|
||||
│ │ │ ├── sprint-plan.md, sprint-start.md, sprint-status.md
|
||||
│ │ │ ├── sprint-close.md, labels-sync.md, initial-setup.md
|
||||
│ │ │ ├── review.md, test-check.md # NEW in v2.2.0
|
||||
│ │ ├── agents/ # 4 agents
|
||||
│ │ │ ├── planner.md, orchestrator.md, executor.md
|
||||
│ │ │ └── code-reviewer.md # NEW in v2.2.0
|
||||
│ │ └── skills/label-taxonomy/
|
||||
│ ├── claude-config-maintainer/
|
||||
│ ├── cmdb-assistant/
|
||||
│ └── project-hygiene/
|
||||
├── scripts/
|
||||
│ ├── setup.sh, post-update.sh
|
||||
│ └── validate-marketplace.sh # NEW in v2.2.0
|
||||
└── docs/
|
||||
├── CANONICAL-PATHS.md # Single source of truth for paths
|
||||
└── references/
|
||||
```
|
||||
|
||||
### Key Design Decisions
|
||||
|
||||
**MCP Servers (Bundled in Plugins):**
|
||||
- **Gitea MCP**: Issues, labels, wiki, milestones, dependencies (bundled in projman)
|
||||
- **NetBox MCP**: Infrastructure management (bundled in cmdb-assistant)
|
||||
- Servers are **bundled inside each plugin** that needs them
|
||||
- This ensures plugins work when cached by Claude Code
|
||||
|
||||
**Python Implementation:**
|
||||
- Python chosen over Node.js for MCP servers
|
||||
- Better suited for configuration management and modular code
|
||||
- Easier to maintain and extend
|
||||
- Virtual environment (.venv) per MCP server
|
||||
|
||||
**Hybrid Configuration:**
|
||||
- **System-level**: `~/.config/claude/gitea.env` (credentials)
|
||||
- **Project-level**: `project-root/.env` (repository specification)
|
||||
- Merge strategy: project overrides system
|
||||
- Benefits: Single token per service, easy multi-project setup
|
||||
|
||||
**Skills as Knowledge, Not Orchestrators:**
|
||||
- Skills provide supporting knowledge loaded when relevant
|
||||
- Agents are the primary interface
|
||||
- Reduces token usage
|
||||
- Makes knowledge reusable across agents
|
||||
|
||||
**Branch Detection:**
|
||||
- Two layers: CLAUDE.md (file access) + Plugin agents (tool usage)
|
||||
- Defense in depth approach
|
||||
- Plugin works with or without CLAUDE.md
|
||||
|
||||
## Multi-Project Context (PMO Plugin)
|
||||
|
||||
The `projman-pmo` plugin coordinates interdependent projects across an organization. Example use cases:
|
||||
- Main product repository
|
||||
- Marketing/documentation sites
|
||||
- Extracted services
|
||||
- Supporting tools
|
||||
|
||||
PMO plugin adds:
|
||||
- Cross-project issue aggregation (all repos in organization)
|
||||
- Dependency tracking and visualization
|
||||
- Resource allocation across projects
|
||||
- Deployment coordination
|
||||
- Multi-project prioritization
|
||||
- Company-wide lessons learned search
|
||||
|
||||
**Configuration Difference:**
|
||||
- PMO operates at company level (no `GITEA_REPO`)
|
||||
- Accesses all repositories in organization
|
||||
- Aggregates issues and lessons across projects
|
||||
|
||||
Build PMO plugin AFTER projman is working and validated.
|
||||
|
||||
## Testing Approach
|
||||
|
||||
**Local Marketplace:**
|
||||
Create local marketplace for plugin development:
|
||||
```
|
||||
~/projman-dev-marketplace/
|
||||
├── .claude-plugin/
|
||||
│ └── marketplace.json
|
||||
└── projman/ # Symlink to plugin directory
|
||||
```
|
||||
|
||||
**Integration Testing:**
|
||||
Test in a real repository with actual Gitea instance before distribution.
|
||||
|
||||
**Success Metrics:**
|
||||
- Sprint planning time reduced 40%
|
||||
- Manual steps eliminated: 10+ per sprint
|
||||
- Lessons learned capture rate: 100% (vs 0% before)
|
||||
- Label accuracy on issues: 90%+
|
||||
- User satisfaction: Better than current manual workflow
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **Never modify docker-compose files with 'version' attribute** - It's obsolete
|
||||
- **Focus on implementation, not over-engineering** - This system has been validated over 15 sprints
|
||||
- **Lessons learned is critical** - Prevents repeated mistakes (e.g., Claude infinite loops)
|
||||
- **Type/Refactor label** - Newly implemented at org level for architectural work
|
||||
- **Branch detection must be 100% reliable** - Prevents production accidents
|
||||
- **Python for MCP servers** - Use Python 3.8+ with virtual environments
|
||||
- **CLI tools forbidden** - Use MCP tools exclusively, never CLI tools like `tea` or `gh`
|
||||
|
||||
## CRITICAL: Rules You MUST Follow
|
||||
|
||||
### DO NOT MODIFY .gitignore Without Explicit Permission
|
||||
- This is a **private repository** - credentials in `.env` files are intentional
|
||||
- **NEVER** add `.env` or `.env.*` to .gitignore
|
||||
- **NEVER** add venv patterns unless explicitly asked
|
||||
- If you think something should be ignored, ASK FIRST
|
||||
### File Operations
|
||||
- **NEVER** create files in repository root unless listed in "Allowed Root Files"
|
||||
- **NEVER** modify `.gitignore` without explicit permission
|
||||
- **ALWAYS** use `.scratch/` for temporary/exploratory work
|
||||
- **ALWAYS** verify paths against `docs/CANONICAL-PATHS.md` before creating files
|
||||
|
||||
### Plugin Structure Requirements
|
||||
- **plugin.json MUST be in `.claude-plugin/` directory** - NOT in plugin root
|
||||
- Every plugin in the repo MUST be listed in the marketplace.json
|
||||
- After creating/modifying a plugin, VERIFY it's in the marketplace
|
||||
### Plugin Development
|
||||
- **plugin.json MUST be in `.claude-plugin/` directory** (not plugin root)
|
||||
- **Every plugin MUST be listed in marketplace.json**
|
||||
- **MCP servers MUST use venv python path**: `${CLAUDE_PLUGIN_ROOT}/mcp-servers/{name}/.venv/bin/python`
|
||||
- **CLI tools forbidden** - Use MCP tools exclusively (never `tea`, `gh`, etc.)
|
||||
|
||||
### Hooks Syntax (Claude Code Official)
|
||||
- **Valid events**: `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
|
||||
- **INVALID events**: `task-completed`, `file-changed`, `git-commit-msg-needed` (these DO NOT exist)
|
||||
- Hooks schema:
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"EventName": [
|
||||
{
|
||||
"matcher": "optional-pattern",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/path/to/script.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
### Hooks (Valid Events Only)
|
||||
`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
|
||||
|
||||
**INVALID:** `task-completed`, `file-changed`, `git-commit-msg-needed`
|
||||
|
||||
### Allowed Root Files
|
||||
`CLAUDE.md`, `README.md`, `LICENSE`, `CHANGELOG.md`, `.gitignore`, `.env.example`
|
||||
|
||||
### Allowed Root Directories
|
||||
`.claude/`, `.claude-plugin/`, `.claude-plugins/`, `.scratch/`, `docs/`, `hooks/`, `plugins/`, `scripts/`
|
||||
|
||||
## Architecture
|
||||
|
||||
### Four-Agent Model (projman v2.2.0)
|
||||
|
||||
| Agent | Personality | Responsibilities |
|
||||
|-------|-------------|------------------|
|
||||
| **Planner** | Thoughtful, methodical | Sprint planning, architecture analysis, issue creation, lesson search |
|
||||
| **Orchestrator** | Concise, action-oriented | Sprint execution, parallel batching, Git operations, lesson capture |
|
||||
| **Executor** | Implementation-focused | Code implementation, branch management, MR creation |
|
||||
| **Code Reviewer** | Thorough, practical | Pre-close quality review, security scan, test verification |
|
||||
|
||||
### MCP Server Tools (Gitea)
|
||||
|
||||
| Category | Tools |
|
||||
|----------|-------|
|
||||
| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment` |
|
||||
| Labels | `get_labels`, `suggest_labels`, `create_label` |
|
||||
| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone` |
|
||||
| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `get_execution_order` |
|
||||
| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `create_lesson`, `search_lessons` |
|
||||
| Validation | `validate_repo_org`, `get_branch_protection` |
|
||||
|
||||
### Hybrid Configuration
|
||||
|
||||
| Level | Location | Purpose |
|
||||
|-------|----------|---------|
|
||||
| System | `~/.config/claude/gitea.env` | Credentials (GITEA_URL, GITEA_TOKEN, GITEA_ORG) |
|
||||
| Project | `.env` in project root | Repository specification (GITEA_REPO) |
|
||||
|
||||
### Branch-Aware Security
|
||||
|
||||
| Branch Pattern | Mode | Capabilities |
|
||||
|----------------|------|--------------|
|
||||
| `development`, `feat/*` | Development | Full access |
|
||||
| `staging` | Staging | Read-only code, can create issues |
|
||||
| `main`, `master` | Production | Read-only, emergency only |
|
||||
|
||||
## Label Taxonomy
|
||||
|
||||
43 labels total: 27 organization + 16 repository
|
||||
|
||||
**Organization:** Agent/2, Complexity/3, Efforts/5, Priority/4, Risk/3, Source/4, Type/6
|
||||
**Repository:** Component/9, Tech/7
|
||||
|
||||
Sync with `/labels-sync` command.
|
||||
|
||||
## Lessons Learned System
|
||||
|
||||
Stored in Gitea Wiki under `lessons-learned/sprints/`.
|
||||
|
||||
**Workflow:**
|
||||
1. Orchestrator captures at sprint close via MCP tools
|
||||
2. Planner searches at sprint start using `search_lessons`
|
||||
3. Tags enable cross-project discovery
|
||||
|
||||
## Common Operations
|
||||
|
||||
### Adding a New Plugin
|
||||
|
||||
1. Create `plugins/{name}/.claude-plugin/plugin.json`
|
||||
2. Add entry to `.claude-plugin/marketplace.json`
|
||||
3. Create `README.md` and `claude-md-integration.md`
|
||||
4. Run `./scripts/validate-marketplace.sh`
|
||||
5. Update `CHANGELOG.md`
|
||||
|
||||
### Adding a Command to projman
|
||||
|
||||
1. Create `plugins/projman/commands/{name}.md`
|
||||
2. Update `plugins/projman/README.md`
|
||||
3. Update marketplace description if significant
|
||||
|
||||
### Validation
|
||||
|
||||
```bash
|
||||
./scripts/validate-marketplace.sh # Validates all manifests
|
||||
```
|
||||
|
||||
### MCP Server Configuration
|
||||
- MCP servers MUST use venv python: `${CLAUDE_PLUGIN_ROOT}/../../mcp-servers/NAME/.venv/bin/python`
|
||||
- NEVER use bare `python` command - always use venv path
|
||||
- Test MCP servers after any config change
|
||||
## Path Verification Protocol
|
||||
|
||||
### Before Completing Any Plugin Work
|
||||
1. Verify plugin.json is in `.claude-plugin/` directory
|
||||
2. Verify plugin is listed in marketplace.json
|
||||
3. Test MCP server configs load correctly
|
||||
4. Verify hooks use valid event types
|
||||
5. Check .gitignore wasn't modified inappropriately
|
||||
**Before creating any file:**
|
||||
|
||||
1. Read `docs/CANONICAL-PATHS.md`
|
||||
2. List all paths to be created/modified
|
||||
3. Verify each against canonical paths
|
||||
4. If not in canonical paths, STOP and ask
|
||||
|
||||
## Documentation Index
|
||||
|
||||
This repository contains comprehensive planning documentation:
|
||||
| Document | Purpose |
|
||||
|----------|---------|
|
||||
| `docs/CANONICAL-PATHS.md` | **Single source of truth** for paths |
|
||||
| `docs/UPDATING.md` | Update guide for the marketplace |
|
||||
| `plugins/projman/CONFIGURATION.md` | Projman setup guide |
|
||||
| `plugins/projman/README.md` | Projman full documentation |
|
||||
|
||||
- **`docs/CANONICAL-PATHS.md`** - ⚠️ SINGLE SOURCE OF TRUTH for all paths (MANDATORY reading before any file operations)
|
||||
- **`docs/DOCUMENT-INDEX.md`** - Complete guide to all planning documents
|
||||
- **`docs/projman-implementation-plan-updated.md`** - Full 12-phase implementation plan
|
||||
- **`docs/projman-python-quickstart.md`** - Python-specific implementation guide
|
||||
- **`docs/two-mcp-architecture-guide.md`** - Deep dive into two-MCP architecture
|
||||
## Version History
|
||||
|
||||
**Start with:** `docs/DOCUMENT-INDEX.md` for navigation guidance
|
||||
| Version | Date | Highlights |
|
||||
|---------|------|------------|
|
||||
| 2.2.0 | 2026-01-20 | `/review`, `/test-check` commands, code-reviewer agent, validation script, marketplace compliance |
|
||||
| 2.1.0 | Previous | Canonical paths, initial-setup command, documentation improvements |
|
||||
| 2.0.0 | Previous | Full Gitea integration, wiki, milestones, dependencies, parallel execution |
|
||||
| 0.1.0 | Initial | Basic plugin structure |
|
||||
|
||||
## Recent Updates (Updated: 2025-06-11)
|
||||
---
|
||||
|
||||
### Planning Phase Complete
|
||||
- Comprehensive 12-phase implementation plan finalized
|
||||
- Architecture decisions documented and validated
|
||||
- Two-MCP-server approach confirmed (Gitea + Wiki.js)
|
||||
- Python selected for MCP server implementation
|
||||
- Hybrid configuration strategy defined (system + project level)
|
||||
- Wiki.js structure planned with configurable base path
|
||||
- Repository structure designed with shared MCP servers
|
||||
|
||||
### Key Architectural Decisions Made
|
||||
1. **Shared MCP Servers**: Both plugins use the same MCP codebase at `mcp-servers/`
|
||||
2. **Mode Detection**: MCP servers detect project vs company-wide mode via environment variables
|
||||
3. **Python Implementation**: MCP servers written in Python (not Node.js) for better configuration handling
|
||||
4. **Wiki.js Integration**: Lessons learned and documentation moved to Wiki.js for better collaboration
|
||||
5. **Hybrid Config**: System-level credentials + project-level paths for flexibility
|
||||
|
||||
### Next Steps
|
||||
- Begin Phase 1.1a: Gitea MCP Server implementation
|
||||
- Set up Python virtual environments
|
||||
- Create configuration loaders
|
||||
- Implement core Gitea tools (issues, labels)
|
||||
- Write integration tests
|
||||
**Last Updated:** 2026-01-20 | **Current Version:** 2.2.0
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
**This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.**
|
||||
|
||||
Last Updated: 2025-12-15
|
||||
Last Updated: 2026-01-20
|
||||
|
||||
---
|
||||
|
||||
@@ -16,7 +16,8 @@ support-claude-mktplace/
|
||||
├── .scratch/ # Transient work (auto-cleaned)
|
||||
├── docs/ # All documentation
|
||||
│ ├── architecture/ # Draw.io diagrams and specs
|
||||
│ ├── references/ # Reference specifications
|
||||
│ ├── CANONICAL-PATHS.md # This file - single source of truth
|
||||
│ ├── UPDATING.md # Update guide
|
||||
│ └── workflows/ # Workflow documentation
|
||||
├── hooks/ # Shared hooks (if any)
|
||||
├── plugins/ # ALL plugins with bundled MCP servers
|
||||
@@ -90,10 +91,10 @@ MCP servers are now **bundled inside each plugin** to ensure they work when plug
|
||||
|
||||
| Type | Location |
|
||||
|------|----------|
|
||||
| Reference specs | `docs/references/` |
|
||||
| Architecture diagrams | `docs/architecture/` |
|
||||
| Workflow docs | `docs/workflows/` |
|
||||
| This file | `docs/CANONICAL-PATHS.md` |
|
||||
| Update guide | `docs/UPDATING.md` |
|
||||
|
||||
---
|
||||
|
||||
@@ -157,6 +158,7 @@ MCP servers are bundled inside each plugin (not shared at root) because:
|
||||
|
||||
| Date | Change | By |
|
||||
|------|--------|-----|
|
||||
| 2026-01-20 | Removed docs/references/ (obsolete planning docs) | Claude Code |
|
||||
| 2026-01-19 | Added claude-md-integration.md path pattern for plugin integration snippets | Claude Code |
|
||||
| 2025-12-15 | Restructured: MCP servers now bundled in plugins | Claude Code |
|
||||
| 2025-12-12 | Initial creation | Claude Code |
|
||||
|
||||
@@ -15,7 +15,7 @@ git pull origin main
|
||||
|
||||
## What the Post-Update Script Does
|
||||
|
||||
1. **Updates Python dependencies** for Gitea and Wiki.js MCP servers
|
||||
1. **Updates Python dependencies** for MCP servers
|
||||
2. **Shows recent changelog entries** so you know what changed
|
||||
3. **Validates your configuration** is still compatible
|
||||
|
||||
@@ -30,7 +30,6 @@ If the changelog mentions new environment variables:
|
||||
1. Check the variable name and purpose in the changelog
|
||||
2. Add it to the appropriate config file:
|
||||
- Gitea variables → `~/.config/claude/gitea.env`
|
||||
- Wiki.js variables → `~/.config/claude/wikijs.env`
|
||||
- Project variables → `.env` in your project root
|
||||
|
||||
### New MCP Server Features
|
||||
@@ -38,7 +37,7 @@ If the changelog mentions new environment variables:
|
||||
If a new MCP server tool is added:
|
||||
|
||||
1. The post-update script handles dependency installation
|
||||
2. Check `docs/references/MCP-*.md` for usage documentation
|
||||
2. Check `plugins/projman/README.md` for usage documentation
|
||||
3. New tools are available immediately after update
|
||||
|
||||
### Breaking Changes
|
||||
@@ -51,15 +50,7 @@ Breaking changes will be clearly marked in CHANGELOG.md with migration instructi
|
||||
|
||||
```bash
|
||||
# Rebuild virtual environment
|
||||
cd mcp-servers/gitea
|
||||
rm -rf .venv
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
deactivate
|
||||
|
||||
# Repeat for wikijs
|
||||
cd ../wikijs
|
||||
cd plugins/projman/mcp-servers/gitea
|
||||
rm -rf .venv
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
@@ -76,7 +67,7 @@ deactivate
|
||||
### MCP server won't start
|
||||
|
||||
1. Check Python version: `python3 --version` (requires 3.10+)
|
||||
2. Verify venv exists: `ls mcp-servers/gitea/.venv`
|
||||
2. Verify venv exists: `ls plugins/projman/mcp-servers/gitea/.venv`
|
||||
3. Check logs for specific errors
|
||||
|
||||
## Version Pinning
|
||||
@@ -88,7 +79,7 @@ To stay on a specific version:
|
||||
git tag
|
||||
|
||||
# Checkout specific version
|
||||
git checkout v1.0.0
|
||||
git checkout v2.2.0
|
||||
|
||||
# Run post-update
|
||||
./scripts/post-update.sh
|
||||
@@ -96,6 +87,7 @@ git checkout v1.0.0
|
||||
|
||||
## Getting Help
|
||||
|
||||
- Check `docs/references/` for component documentation
|
||||
- Check `plugins/projman/README.md` for projman documentation
|
||||
- Check `plugins/projman/CONFIGURATION.md` for setup guide
|
||||
- Review CHANGELOG.md for recent changes
|
||||
- Search existing issues in Gitea
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -1,692 +0,0 @@
|
||||
# Project Management Plugins - Project Summary
|
||||
|
||||
## Overview
|
||||
|
||||
This project builds two Claude Code plugins that transform a proven 15-sprint workflow into reusable, distributable tools for managing software development with Gitea, Wiki.js, and agile methodologies.
|
||||
|
||||
**Status:** Planning phase complete, ready for implementation
|
||||
|
||||
---
|
||||
|
||||
## The Two Plugins
|
||||
|
||||
### 1. projman (Single-Repository)
|
||||
|
||||
**Purpose:** Project management for individual repositories
|
||||
**Users:** Developers, Team Leads
|
||||
**Build Order:** Build FIRST
|
||||
|
||||
**Key Features:**
|
||||
- Sprint planning with AI agents
|
||||
- Issue creation with 43-label taxonomy
|
||||
- Lessons learned capture in Wiki.js
|
||||
- Branch-aware security model
|
||||
- Hybrid configuration system
|
||||
|
||||
**Reference:** [PLUGIN-PROJMAN.md](./PLUGIN-PROJMAN.md)
|
||||
|
||||
### 2. projman-pmo (Multi-Project)
|
||||
|
||||
**Purpose:** PMO coordination across organization
|
||||
**Users:** PMO Coordinators, Engineering Managers, CTOs
|
||||
**Build Order:** Build SECOND (after projman validated)
|
||||
|
||||
**Key Features:**
|
||||
- Cross-project status aggregation
|
||||
- Dependency tracking and visualization
|
||||
- Resource conflict detection
|
||||
- Release coordination
|
||||
- Company-wide lessons learned search
|
||||
|
||||
**Reference:** [PLUGIN-PMO.md](./PLUGIN-PMO.md)
|
||||
|
||||
---
|
||||
|
||||
## Core Architecture
|
||||
|
||||
### Shared MCP Servers
|
||||
|
||||
Both plugins share the same MCP server codebase at repository root (`mcp-servers/`):
|
||||
|
||||
**1. Gitea MCP Server**
|
||||
- Issue management (CRUD operations)
|
||||
- Label taxonomy system (43 labels)
|
||||
- Mode detection (project vs company-wide)
|
||||
|
||||
**Reference:** [MCP-GITEA.md](./MCP-GITEA.md)
|
||||
|
||||
**2. Wiki.js MCP Server**
|
||||
- Documentation management
|
||||
- Lessons learned capture and search
|
||||
- GraphQL API integration
|
||||
- Company-wide knowledge base
|
||||
|
||||
**Reference:** [MCP-WIKIJS.md](./MCP-WIKIJS.md)
|
||||
|
||||
### Mode Detection
|
||||
|
||||
The MCP servers detect their operating mode based on environment variables:
|
||||
|
||||
**Project Mode (projman):**
|
||||
- `GITEA_REPO` present → operates on single repository
|
||||
- `WIKIJS_PROJECT` present → operates on single project path
|
||||
|
||||
**Company Mode (pmo):**
|
||||
- No `GITEA_REPO` → operates on all repositories
|
||||
- No `WIKIJS_PROJECT` → operates on entire company namespace
|
||||
|
||||
---
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
personal-projects/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! 🚀
|
||||
@@ -393,16 +393,15 @@ MIT License - Part of the Claude Code Marketplace project.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **MCP Specification**: `docs/references/MCP-GITEA.md`
|
||||
- **Project Summary**: `docs/references/PROJECT-SUMMARY.md`
|
||||
- **Implementation Plan**: `docs/reference-material/projman-implementation-plan.md`
|
||||
- **Projman Documentation**: `plugins/projman/README.md`
|
||||
- **Configuration Guide**: `plugins/projman/CONFIGURATION.md`
|
||||
- **Testing Guide**: `TESTING.md`
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
1. Check [TESTING.md](./TESTING.md) troubleshooting section
|
||||
2. Review [MCP-GITEA.md](../../docs/references/MCP-GITEA.md) specification
|
||||
2. Review [plugins/projman/README.md](../../README.md) for plugin documentation
|
||||
3. Create an issue in the project repository
|
||||
|
||||
---
|
||||
|
||||
@@ -574,8 +574,8 @@ After completing testing:
|
||||
|
||||
- **MCP Documentation**: https://docs.anthropic.com/claude/docs/mcp
|
||||
- **Gitea API Documentation**: https://docs.gitea.io/en-us/api-usage/
|
||||
- **Project Documentation**: `docs/references/MCP-GITEA.md`
|
||||
- **Implementation Plan**: `docs/references/PROJECT-SUMMARY.md`
|
||||
- **Projman Documentation**: `plugins/projman/README.md`
|
||||
- **Configuration Guide**: `plugins/projman/CONFIGURATION.md`
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user