From c3df0f95e6d6cf2afc4c3ebb5f922976c619aea2 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Wed, 21 Jan 2026 17:44:54 -0500 Subject: [PATCH] feat: add debug workflow commands and bump to v3.1.0 New commands for structured debugging workflow: /debug-report (for test projects): - Runs 5 diagnostic MCP tool tests - Captures full project context (git remote, cwd, branch) - Generates structured issue with hypothesis - Creates issue in marketplace repo automatically /debug-review (for marketplace repo): - Lists open diagnostic issues for triage - Maps errors to relevant code files - MANDATORY: Reads files before proposing fixes - Three human approval gates - Creates feature branch, commits, PR with linking Also includes: - Dynamic label format detection in suggest_labels - Rewritten labels-sync.md with explicit execution steps - Version bump to 3.1.0 Co-Authored-By: Claude Opus 4.5 --- .claude-plugin/marketplace.json | 4 +- CHANGELOG.md | 38 ++ README.md | 2 +- plugins/projman/.claude-plugin/plugin.json | 2 +- plugins/projman/commands/debug-report.md | 262 ++++++++++++++ plugins/projman/commands/debug-review.md | 389 +++++++++++++++++++++ 6 files changed, 693 insertions(+), 4 deletions(-) create mode 100644 plugins/projman/commands/debug-report.md create mode 100644 plugins/projman/commands/debug-review.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 3970ae6..23a5079 100644 --- a/.claude-plugin/marketplace.json +++ b/.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": { diff --git a/CHANGELOG.md b/CHANGELOG.md index 9206ff0..812b50b 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 3ac2e34..479eeb9 100644 --- a/README.md +++ b/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. diff --git a/plugins/projman/.claude-plugin/plugin.json b/plugins/projman/.claude-plugin/plugin.json index c6a5590..97f6517 100644 --- a/plugins/projman/.claude-plugin/plugin.json +++ b/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", diff --git a/plugins/projman/commands/debug-report.md b/plugins/projman/commands/debug-report.md new file mode 100644 index 0000000..d8d4e99 --- /dev/null +++ b/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 diff --git a/plugins/projman/commands/debug-review.md b/plugins/projman/commands/debug-review.md new file mode 100644 index 0000000..f93316f --- /dev/null +++ b/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 " +``` + +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) +``` -- 2.49.1