.claude-plugin/marketplace.json

@@ -6,12 +6,12 @@
   },
   "metadata": {
     "description": "Project management plugins with Gitea and NetBox integrations",
-    "version": "3.0.1"
+    "version": "3.1.0"
   },
   "plugins": [
     {
       "name": "projman",
-      "version": "3.0.0",
+      "version": "3.1.0",
       "description": "Sprint planning and project management with Gitea integration",
       "source": "./plugins/projman",
       "author": {

CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to the Leo Claude Marketplace will be documented in this fil
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [3.1.0] - 2026-01-21
+
+### Added
+
+#### Debug Workflow Commands (projman)
+- **`/debug-report`** - Run diagnostics in test projects, create structured issues in marketplace
+  - Runs 5 diagnostic MCP tool tests with explicit repo parameter
+  - Captures full project context (git remote, cwd, branch)
+  - Generates structured issue with hypothesis and investigation steps
+  - Creates issue in configured marketplace repository automatically
+
+- **`/debug-review`** - Investigate diagnostic issues with human approval gates
+  - Lists open diagnostic issues for triage
+  - Maps errors to relevant code files using error-to-file mapping
+  - MANDATORY: Reads relevant files before proposing any fix
+  - Three approval gates: investigation summary, fix approach, PR creation
+  - Creates feature branch, commits, and PR with proper linking
+
+#### MCP Server Improvements
+- Dynamic label format detection in `suggest_labels`
+  - Supports slash format (`Type/Bug`) and colon-space format (`Type: Bug`)
+  - Fetches actual labels from repo and matches suggestions to real format
+  - Handles Effort/Efforts singular/plural normalization
+
+### Changed
+- **`/labels-sync`** completely rewritten with explicit execution steps
+  - Step 1 now explicitly requires running `git remote get-url origin` via Bash
+  - All MCP tool calls show required `repo` parameter
+  - Added "DO NOT" section preventing common mistakes
+  - Removed confusing "Label Reference" section that caused file creation prompts
+
+### Fixed
+- MCP tools no longer fail with "Use 'owner/repo' format" error
+  - Root cause: MCP server is sandboxed and cannot auto-detect project directory
+  - Solution: Command documentation now instructs Claude to detect repo via Bash first
+
+---
+
 ## [3.0.1] - 2026-01-21
 
 ### Added

README.md

@@ -1,4 +1,4 @@
-# Leo Claude Marketplace - v3.0.1
+# Leo Claude Marketplace - v3.1.0
 
 A collection of Claude Code plugins for project management, infrastructure automation, and development workflows.
 

plugins/projman/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "projman",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Sprint planning and project management with Gitea integration",
   "author": {
     "name": "Leo Miranda",

plugins/projman/commands/debug-report.md

@@ -0,0 +1,262 @@
+---
+description: Run diagnostics and create structured issue in marketplace repository
+---
+
+# Debug Report
+
+Run diagnostic checks on projman MCP tools and create a structured issue in the marketplace repository for investigation.
+
+## Prerequisites
+
+Your project `.env` must have:
+
+```env
+PROJMAN_MARKETPLACE_REPO=personal-projects/leo-claude-mktplace
+```
+
+If not configured, ask the user for the marketplace repository path.
+
+## CRITICAL: Execution Steps
+
+You MUST follow these steps in order. Do NOT skip any step.
+
+### Step 1: Gather Project Context
+
+Run these Bash commands to capture project information:
+
+```bash
+# Get git remote URL
+git remote get-url origin
+
+# Get current branch
+git branch --show-current
+
+# Get working directory
+pwd
+```
+
+Parse the git remote to extract `REPO_NAME` in `owner/repo` format.
+
+Store all values:
+- `PROJECT_REPO`: The detected owner/repo
+- `GIT_REMOTE`: Full git remote URL
+- `CURRENT_BRANCH`: Current branch name
+- `WORKING_DIR`: Current working directory
+
+### Step 2: Read Marketplace Configuration
+
+```bash
+grep PROJMAN_MARKETPLACE_REPO .env
+```
+
+Store as `MARKETPLACE_REPO`. If not found, ask the user.
+
+### Step 3: Run Diagnostic Suite
+
+Run each MCP tool with explicit `repo` parameter. Record success/failure and full response.
+
+**Test 1: validate_repo_org**
+```
+mcp__plugin_projman_gitea__validate_repo_org(repo=PROJECT_REPO)
+```
+Expected: `{is_organization: true/false}`
+
+**Test 2: get_labels**
+```
+mcp__plugin_projman_gitea__get_labels(repo=PROJECT_REPO)
+```
+Expected: `{organization: [...], repository: [...], total_count: N}`
+
+**Test 3: list_issues**
+```
+mcp__plugin_projman_gitea__list_issues(repo=PROJECT_REPO, state="open")
+```
+Expected: Array of issues
+
+**Test 4: list_milestones**
+```
+mcp__plugin_projman_gitea__list_milestones(repo=PROJECT_REPO)
+```
+Expected: Array of milestones
+
+**Test 5: suggest_labels**
+```
+mcp__plugin_projman_gitea__suggest_labels(context="Test bug fix for authentication")
+```
+Expected: Array of label names matching repo's format
+
+For each test, record:
+- Tool name
+- Exact parameters used
+- Status: PASS or FAIL
+- Response or error message
+
+### Step 4: Analyze Results
+
+Count failures and categorize errors:
+
+| Category | Indicators |
+|----------|------------|
+| Parameter Format | "owner/repo format", "missing parameter" |
+| Authentication | "401", "403", "unauthorized" |
+| Not Found | "404", "not found" |
+| Network | "connection", "timeout", "ECONNREFUSED" |
+| Logic | Unexpected response format, wrong data |
+
+For each failure, write a hypothesis about the likely cause.
+
+### Step 5: Generate Issue Content
+
+Use this exact template:
+
+```markdown
+## Diagnostic Report
+
+**Generated**: [ISO timestamp]
+**Command Tested**: [What the user was trying to run, or "general diagnostic"]
+**Reporter**: Claude Code via /debug-report
+
+## Project Context
+
+| Field | Value |
+|-------|-------|
+| Repository | `[PROJECT_REPO]` |
+| Git Remote | `[GIT_REMOTE]` |
+| Working Directory | `[WORKING_DIR]` |
+| Current Branch | `[CURRENT_BRANCH]` |
+
+## Diagnostic Results
+
+### Test 1: validate_repo_org
+
+**Call**: `validate_repo_org(repo="[PROJECT_REPO]")`
+**Status**: [PASS/FAIL]
+**Response**:
+```json
+[full response or error]
+```
+
+### Test 2: get_labels
+
+**Call**: `get_labels(repo="[PROJECT_REPO]")`
+**Status**: [PASS/FAIL]
+**Response**:
+```json
+[full response or error - truncate if very long]
+```
+
+[... repeat for each test ...]
+
+## Summary
+
+- **Total Tests**: 5
+- **Passed**: [N]
+- **Failed**: [N]
+
+### Failed Tools
+
+[List each failed tool with its error]
+
+### Error Category
+
+[Check applicable categories]
+
+### Hypothesis
+
+[Your analysis of what's wrong and why]
+
+### Suggested Investigation
+
+1. [First file/function to check]
+2. [Second file/function to check]
+3. [etc.]
+
+## Reproduction Steps
+
+1. Navigate to `[WORKING_DIR]`
+2. Run `[command that was being tested]`
+3. Observe error at step [X]
+
+---
+
+*Generated by /debug-report - Labels: Type: Bug, Source: Diagnostic, Agent: Claude*
+```
+
+### Step 6: Create Issue in Marketplace
+
+```
+mcp__plugin_projman_gitea__create_issue(
+  repo=MARKETPLACE_REPO,
+  title="[Diagnostic] [summary of main failure]",
+  body=[generated content from Step 5],
+  labels=["Type: Bug", "Source: Diagnostic", "Agent: Claude"]
+)
+```
+
+If labels don't exist, create issue without labels.
+
+### Step 7: Report to User
+
+Display summary:
+
+```
+Debug Report Complete
+=====================
+
+Project: [PROJECT_REPO]
+Tests Run: 5
+Passed: [N]
+Failed: [N]
+
+Failed Tools:
+  - [tool1]: [brief error]
+  - [tool2]: [brief error]
+
+Issue Created: [issue URL]
+
+Next Steps:
+  1. Switch to marketplace repo: cd [marketplace path]
+  2. Run: /debug-review
+  3. Select issue #[N] to investigate
+```
+
+## DO NOT
+
+- **DO NOT** attempt to fix anything - only report
+- **DO NOT** create issues if all tests pass (just report success)
+- **DO NOT** skip any diagnostic test
+- **DO NOT** call MCP tools without the `repo` parameter
+- **DO NOT** ask user questions during execution - run autonomously
+
+## If All Tests Pass
+
+If all 5 tests pass, report success without creating an issue:
+
+```
+Debug Report Complete
+=====================
+
+Project: [PROJECT_REPO]
+Tests Run: 5
+Passed: 5
+Failed: 0
+
+All diagnostics passed. No issues to report.
+
+If you're experiencing a specific problem, please describe it
+and I can create a manual bug report.
+```
+
+## Troubleshooting
+
+**PROJMAN_MARKETPLACE_REPO not configured**
+- Ask user: "What is the marketplace repository? (e.g., personal-projects/leo-claude-mktplace)"
+- Store for this session and remind user to add to .env
+
+**Cannot detect project repository**
+- Check if in a git repository: `git rev-parse --git-dir`
+- If not a git repo, ask user for the repository path
+
+**MCP tools not available**
+- The projman plugin may not be properly installed
+- Check if .mcp.json exists and is configured

plugins/projman/commands/debug-review.md

@@ -0,0 +1,389 @@
+---
+description: Investigate diagnostic issues and propose fixes with human approval
+---
+
+# Debug Review
+
+Investigate diagnostic issues created by `/debug-report`, read relevant code, and propose fixes with human approval at each step.
+
+## CRITICAL: This Command Requires Human Approval
+
+This command has THREE mandatory approval gates. You MUST stop and wait for user confirmation at each gate before proceeding.
+
+## Execution Steps
+
+### Step 1: Detect Repository
+
+Run Bash to get the current repository:
+
+```bash
+git remote get-url origin
+```
+
+Parse to extract `REPO_NAME` in `owner/repo` format.
+
+### Step 2: Fetch Diagnostic Issues
+
+```
+mcp__plugin_projman_gitea__list_issues(
+  repo=REPO_NAME,
+  state="open",
+  labels=["Source: Diagnostic"]
+)
+```
+
+If no issues with that label, try without label filter and look for issues with "[Diagnostic]" in title.
+
+### Step 3: Display Issue List
+
+Show the user available issues:
+
+```
+Debug Review
+============
+
+Open Diagnostic Issues:
+
+  #80 - [Diagnostic] get_labels fails without repo parameter
+        Created: 2026-01-21 | Labels: Type: Bug, Source: Diagnostic
+
+  #77 - [Diagnostic] MCP tools require explicit repo parameter
+        Created: 2026-01-21 | Labels: Type: Bug, Source: Diagnostic
+
+No diagnostic issues? Showing recent bugs:
+
+  #75 - [Bug] Some other issue
+        Created: 2026-01-20
+```
+
+### Step 4: User Selects Issue
+
+Use AskUserQuestion:
+
+```
+Which issue would you like to investigate?
+Options: [List issue numbers]
+```
+
+Wait for user selection.
+
+### Step 5: Fetch Full Issue Details
+
+```
+mcp__plugin_projman_gitea__get_issue(repo=REPO_NAME, issue_number=SELECTED)
+```
+
+### Step 6: Parse Diagnostic Report
+
+Extract from the issue body:
+
+1. **Failed Tools**: Which MCP tools failed
+2. **Error Messages**: Exact error text
+3. **Hypothesis**: Reporter's analysis
+4. **Suggested Investigation**: Files to check
+5. **Project Context**: Repo, branch, cwd where error occurred
+
+If the issue doesn't follow the diagnostic template, extract what information is available.
+
+### Step 7: Map Errors to Code Files
+
+Use this mapping to identify relevant files:
+
+**By Tool Name:**
+| Tool | Primary Files |
+|------|---------------|
+| `validate_repo_org` | `mcp-servers/gitea/mcp_server/gitea_client.py` |
+| `get_labels` | `mcp-servers/gitea/mcp_server/tools/labels.py` |
+| `suggest_labels` | `mcp-servers/gitea/mcp_server/tools/labels.py` |
+| `list_issues` | `mcp-servers/gitea/mcp_server/tools/issues.py` |
+| `create_issue` | `mcp-servers/gitea/mcp_server/tools/issues.py` |
+| `list_milestones` | `mcp-servers/gitea/mcp_server/gitea_client.py` |
+
+**By Error Pattern:**
+| Error Contains | Check Files |
+|----------------|-------------|
+| "owner/repo format" | `config.py`, `gitea_client.py` |
+| "404" + "orgs" | `gitea_client.py` (is_org_repo method) |
+| "401", "403" | `config.py` (token loading) |
+| "No repository" | Command `.md` file (repo detection step) |
+
+**By Command:**
+| Command | Documentation File |
+|---------|-------------------|
+| `/labels-sync` | `plugins/projman/commands/labels-sync.md` |
+| `/sprint-plan` | `plugins/projman/commands/sprint-plan.md` |
+| `/sprint-start` | `plugins/projman/commands/sprint-start.md` |
+| `/debug-report` | `plugins/projman/commands/debug-report.md` |
+
+### Step 8: Read Relevant Files (MANDATORY)
+
+You MUST read the identified files before proposing any fix.
+
+For each relevant file:
+1. Read the file using the Read tool
+2. Find the specific function/method mentioned in the error
+3. Understand the code path that leads to the error
+4. Note any related code that might be affected
+
+Display snippets of relevant code to the user:
+
+```
+Reading relevant files...
+
+┌─ mcp-servers/gitea/mcp_server/tools/labels.py (lines 29-40) ────────┐
+│                                                                      │
+│ async def get_labels(self, repo: Optional[str] = None):              │
+│     target_repo = repo or self.gitea.repo                            │
+│     if not target_repo or '/' not in target_repo:                    │
+│         raise ValueError("Use 'owner/repo' format...")               │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+### Step 9: Present Investigation Summary
+
+Summarize what you found:
+
+```
+Investigation Summary
+=====================
+
+ISSUE: #80 - get_labels fails without repo parameter
+
+FAILED TOOLS:
+  • get_labels - "Use 'owner/repo' format"
+
+CODE ANALYSIS:
+
+1. labels.py:get_labels() requires repo parameter
+   - Line 30: `target_repo = repo or self.gitea.repo`
+   - Line 31-32: Raises ValueError if no repo
+
+2. labels-sync.md documents Step 1 for repo detection
+   - Lines 13-26: Instructs to run `git remote get-url origin`
+   - This step may not be followed by executing Claude
+
+ROOT CAUSE HYPOTHESIS:
+
+The command documentation (labels-sync.md) correctly instructs
+repo detection, but the executing Claude may be skipping Step 1
+and calling MCP tools directly.
+
+Evidence:
+  • Error indicates repo parameter was not passed
+  • labels-sync.md has correct instructions
+  • MCP server cannot auto-detect (sandboxed environment)
+
+LIKELY FIX:
+
+Option A: Make Step 1 more prominent in labels-sync.md
+Option B: Add validation that repo was detected before proceeding
+Option C: [Other based on analysis]
+```
+
+## APPROVAL GATE 1
+
+```
+Does this analysis match your understanding of the problem?
+
+[Y] Yes, proceed to propose fix
+[N] No, let me clarify
+[R] Read more files first
+```
+
+**STOP HERE AND WAIT FOR USER RESPONSE**
+
+Do NOT proceed until user approves.
+
+### Step 10: Propose Fix Approach
+
+Based on the analysis, propose a specific fix:
+
+```
+Proposed Fix
+============
+
+APPROACH: [A/B/C from above]
+
+CHANGES NEEDED:
+
+1. File: plugins/projman/commands/labels-sync.md
+   Change: Add warning box after Step 1 emphasizing repo must be detected
+
+2. File: [if applicable]
+   Change: [description]
+
+RATIONALE:
+
+[Explain why this fix addresses the root cause]
+
+RISKS:
+
+[Any potential issues with this approach]
+```
+
+## APPROVAL GATE 2
+
+```
+Proceed with this fix approach?
+
+[Y] Yes, implement it
+[N] No, try different approach
+[M] Modify the approach (tell me what to change)
+```
+
+**STOP HERE AND WAIT FOR USER RESPONSE**
+
+Do NOT implement until user approves.
+
+### Step 11: Implement Fix
+
+Only after user approves:
+
+1. Create feature branch:
+```bash
+git checkout -b fix/issue-[NUMBER]-[brief-description]
+```
+
+2. Make the code changes using Edit tool
+
+3. Run relevant tests if they exist:
+```bash
+cd mcp-servers/gitea && .venv/bin/python -m pytest tests/ -v
+```
+
+4. Show the changes to user:
+```bash
+git diff
+```
+
+### Step 12: Present Changes
+
+```
+Changes Implemented
+===================
+
+Branch: fix/issue-80-labels-sync-instructions
+
+Files Modified:
+  • plugins/projman/commands/labels-sync.md (+15, -3)
+
+Diff Summary:
+[Show git diff output]
+
+Test Results:
+  • 23 passed, 0 failed (or N/A if no tests)
+```
+
+## APPROVAL GATE 3
+
+```
+Create PR with these changes?
+
+[Y] Yes, create PR
+[N] No, I want to modify something
+[D] Discard changes
+```
+
+**STOP HERE AND WAIT FOR USER RESPONSE**
+
+Do NOT create PR until user approves.
+
+### Step 13: Create PR
+
+Only after user approves:
+
+1. Commit changes:
+```bash
+git add -A
+git commit -m "fix: [description]
+
+[Longer explanation]
+
+Fixes #[ISSUE_NUMBER]
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
+```
+
+2. Push branch:
+```bash
+git push -u origin fix/issue-[NUMBER]-[brief-description]
+```
+
+3. Create PR via API or MCP tools
+
+4. Add comment to original issue:
+```
+mcp__plugin_projman_gitea__add_comment(
+  repo=REPO_NAME,
+  issue_number=ISSUE_NUMBER,
+  comment="Fix proposed in PR #[PR_NUMBER]\n\nChanges:\n- [summary]\n\nPlease test after merge and report back."
+)
+```
+
+### Step 14: Report Completion
+
+```
+Debug Review Complete
+=====================
+
+Issue: #80 - get_labels fails without repo parameter
+Status: Fix Proposed
+
+PR Created: #81 - fix: improve labels-sync repo detection instructions
+URL: http://gitea.hotserv.cloud/.../pulls/81
+
+Next Steps:
+  1. Review and merge PR #81
+  2. In test project, pull latest plugin version
+  3. Run /debug-report to verify fix
+  4. If passing, close issue #80
+```
+
+## DO NOT
+
+- **DO NOT** skip reading relevant files - this is MANDATORY
+- **DO NOT** proceed past approval gates without user confirmation
+- **DO NOT** guess at fixes without evidence from code
+- **DO NOT** close issues - let user verify fix works first
+- **DO NOT** commit directly to development or main branches
+
+## If Investigation Finds No Bug
+
+Sometimes investigation reveals the issue is:
+- User error (didn't follow documented steps)
+- Configuration issue (missing .env vars)
+- Already fixed in a newer version
+
+In this case:
+
+```
+Investigation Summary
+=====================
+
+FINDING: This does not appear to be a code bug.
+
+ANALYSIS:
+[Explanation of what you found]
+
+RECOMMENDATION:
+[ ] Close issue as "not a bug" - user error
+[ ] Close issue as "duplicate" of #[X]
+[ ] Add documentation to prevent confusion
+[ ] Other: [specify]
+
+Would you like me to add a comment explaining this finding?
+```
+
+## Error-to-File Quick Reference
+
+```
+Error Message                    → File to Check
+─────────────────────────────────────────────────────────────────
+"Use 'owner/repo' format"        → config.py, gitea_client.py
+"404 Client Error.*orgs"         → gitea_client.py (_is_organization)
+"No repository specified"        → Command .md file (Step 1)
+"401 Unauthorized"               → config.py (token loading)
+"labels not found"               → labels.py, gitea_client.py
+"create local.*file"             → Command .md file (DO NOT section)
+```