feat: project refactoring - folder cleanup, governance, and automation
Project Structure Cleanup: - Remove deprecated cmdb-assistant plugin - Remove development output files (test scripts, status reports) - Remove IDE-specific workspace files - Create scripts/ directory for automation - Create docs/architecture/ for Draw.io diagrams - Create docs/workflows/ for workflow documentation - Create .scratch/ directory for transient work Governance & Documentation: - Add File Creation Governance section to CLAUDE.md - Add architecture diagram specifications (component-map, agent-workflow) - Add docs/UPDATING.md with update workflow - Update CHANGELOG.md with all changes Installation Automation: - Add scripts/setup.sh for initial installation - Add scripts/post-update.sh for updates after git pull - Add /initial-setup slash command Maintenance: - Update .gitignore with scratch directory - Fix all project name references (use support-claude-mktplace) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -1,223 +0,0 @@
|
||||
# Quick Guide: Creating Label Taxonomy in Gitea
|
||||
|
||||
**Estimated Time:** 15-20 minutes
|
||||
**Required:** Admin access to bandit organization in Gitea
|
||||
|
||||
## Why This Is Needed
|
||||
|
||||
The Projman plugin depends on a 44-label taxonomy system for:
|
||||
- Issue categorization (Type, Priority, Component, Tech)
|
||||
- Intelligent label suggestions
|
||||
- Sprint planning and filtering
|
||||
- Progress tracking by category
|
||||
|
||||
**Currently:** Repository has 0 labels
|
||||
**Required:** 44 labels (28 organization + 16 repository)
|
||||
|
||||
## Step 1: Create Organization Labels (28 labels)
|
||||
|
||||
**Navigate to:** https://gitea.example.com/org/bandit/settings/labels
|
||||
|
||||
These labels will be available to ALL repositories in bandit organization.
|
||||
|
||||
### Agent (2 labels)
|
||||
| Name | Color | Description |
|
||||
|------|-------|-------------|
|
||||
| Agent/Human | `#0052CC` | Work performed by human developers |
|
||||
| Agent/Claude | `#6554C0` | Work performed by Claude Code or AI assistants |
|
||||
|
||||
### Complexity (3 labels)
|
||||
| Name | Color | Description |
|
||||
|------|-------|-------------|
|
||||
| Complexity/Simple | `#C2E0C6` | Straightforward tasks requiring minimal analysis |
|
||||
| Complexity/Medium | `#FFF4CE` | Moderate complexity with some architectural decisions |
|
||||
| Complexity/Complex | `#FFBDAD` | High complexity requiring significant planning |
|
||||
|
||||
### Efforts (5 labels)
|
||||
| Name | Color | Description |
|
||||
|------|-------|-------------|
|
||||
| Efforts/XS | `#C2E0C6` | Extra small effort (< 2 hours) |
|
||||
| Efforts/S | `#D4F1D4` | Small effort (2-4 hours) |
|
||||
| Efforts/M | `#FFF4CE` | Medium effort (4-8 hours / 1 day) |
|
||||
| Efforts/L | `#FFE0B2` | Large effort (1-3 days) |
|
||||
| Efforts/XL | `#FFBDAD` | Extra large effort (> 3 days) |
|
||||
|
||||
### Priority (4 labels)
|
||||
| Name | Color | Description |
|
||||
|------|-------|-------------|
|
||||
| Priority/Low | `#D4E157` | Nice to have, can wait |
|
||||
| Priority/Medium | `#FFEB3B` | Should be done this sprint |
|
||||
| Priority/High | `#FF9800` | Important, do soon |
|
||||
| Priority/Critical | `#F44336` | Urgent, blocking other work |
|
||||
|
||||
### Risk (3 labels)
|
||||
| Name | Color | Description |
|
||||
|------|-------|-------------|
|
||||
| Risk/Low | `#C2E0C6` | Low risk of issues or impact |
|
||||
| Risk/Medium | `#FFF4CE` | Moderate risk, proceed with caution |
|
||||
| Risk/High | `#FFBDAD` | High risk, needs careful planning and testing |
|
||||
|
||||
### Source (4 labels)
|
||||
| Name | Color | Description |
|
||||
|------|-------|-------------|
|
||||
| Source/Development | `#7CB342` | Issue discovered during development |
|
||||
| Source/Staging | `#FFB300` | Issue found in staging environment |
|
||||
| Source/Production | `#E53935` | Issue found in production |
|
||||
| Source/Customer | `#AB47BC` | Issue reported by customer |
|
||||
|
||||
### Type (6 labels)
|
||||
| Name | Color | Description |
|
||||
|------|-------|-------------|
|
||||
| Type/Bug | `#D73A4A` | Bug fixes and error corrections |
|
||||
| Type/Feature | `#0075CA` | New features and enhancements |
|
||||
| Type/Refactor | `#FBCA04` | Code restructuring and architectural changes |
|
||||
| Type/Documentation | `#0E8A16` | Documentation updates and improvements |
|
||||
| Type/Test | `#1D76DB` | Testing-related work (unit, integration, e2e) |
|
||||
| Type/Chore | `#FEF2C0` | Maintenance, tooling, dependencies, build tasks |
|
||||
|
||||
**Total Organization Labels: 28**
|
||||
|
||||
## Step 2: Create Repository Labels (16 labels)
|
||||
|
||||
**Navigate to:** https://gitea.example.com/bandit/support-claude-mktplace/labels
|
||||
|
||||
These labels are specific to the support-claude-mktplace repository.
|
||||
|
||||
### Component (9 labels)
|
||||
| Name | Color | Description |
|
||||
|------|-------|-------------|
|
||||
| Component/Backend | `#5319E7` | Backend service code and business logic |
|
||||
| Component/Frontend | `#1D76DB` | User interface and client-side code |
|
||||
| Component/API | `#0366D6` | API endpoints, contracts, and integration |
|
||||
| Component/Database | `#006B75` | Database schemas, migrations, queries |
|
||||
| Component/Auth | `#E99695` | Authentication and authorization |
|
||||
| Component/Deploy | `#BFD4F2` | Deployment, infrastructure, DevOps |
|
||||
| Component/Testing | `#F9D0C4` | Test infrastructure and frameworks |
|
||||
| Component/Docs | `#C5DEF5` | Documentation and guides |
|
||||
| Component/Infra | `#D4C5F9` | Infrastructure and system configuration |
|
||||
|
||||
### Tech (7 labels)
|
||||
| Name | Color | Description |
|
||||
|------|-------|-------------|
|
||||
| Tech/Python | `#3572A5` | Python language and libraries |
|
||||
| Tech/JavaScript | `#F1E05A` | JavaScript/Node.js code |
|
||||
| Tech/Docker | `#384D54` | Docker containers and compose |
|
||||
| Tech/PostgreSQL | `#336791` | PostgreSQL database |
|
||||
| Tech/Redis | `#DC382D` | Redis cache and pub/sub |
|
||||
| Tech/Vue | `#42B883` | Vue.js frontend framework |
|
||||
| Tech/FastAPI | `#009688` | FastAPI backend framework |
|
||||
|
||||
**Total Repository Labels: 16**
|
||||
|
||||
## Step 3: Verify Label Creation
|
||||
|
||||
After creating all labels, verify:
|
||||
|
||||
```bash
|
||||
# Count organization labels
|
||||
curl -s "https://gitea.example.com/api/v1/orgs/bandit/labels" \
|
||||
-H "Authorization: token YOUR_TOKEN" | python3 -c "import sys, json; print(len(json.load(sys.stdin)), 'org labels')"
|
||||
|
||||
# Count repository labels
|
||||
curl -s "https://gitea.example.com/api/v1/repos/bandit/support-claude-mktplace/labels" \
|
||||
-H "Authorization: token YOUR_TOKEN" | python3 -c "import sys, json; print(len(json.load(sys.stdin)), 'repo labels')"
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
28 org labels
|
||||
44 repo labels # (28 org + 16 repo)
|
||||
```
|
||||
|
||||
## Step 4: Sync Labels with Plugin
|
||||
|
||||
After creating all labels in Gitea:
|
||||
|
||||
```bash
|
||||
cd /home/lmiranda/Repositories/hhl/hhl-claude-agents
|
||||
/labels-sync
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
Fetching labels from Gitea...
|
||||
|
||||
Current Label Taxonomy:
|
||||
- Organization Labels: 28
|
||||
- Repository Labels: 16
|
||||
- Total: 44 labels
|
||||
|
||||
✅ Label taxonomy synchronized successfully!
|
||||
```
|
||||
|
||||
The plugin will update `projman/skills/label-taxonomy/labels-reference.md` with the current taxonomy.
|
||||
|
||||
## Alternative: Batch Creation Script
|
||||
|
||||
If you prefer to create labels programmatically:
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Batch create Gitea labels via API
|
||||
"""
|
||||
import requests
|
||||
|
||||
GITEA_URL = "https://gitea.example.com"
|
||||
TOKEN = "ae72c63cd7de02e40bd16f66d1e98059c187759b"
|
||||
ORG = "bandit"
|
||||
REPO = "support-claude-mktplace"
|
||||
|
||||
headers = {"Authorization": f"token {TOKEN}"}
|
||||
|
||||
# Organization labels
|
||||
org_labels = [
|
||||
{"name": "Agent/Human", "color": "#0052CC", "description": "Work performed by human developers"},
|
||||
{"name": "Agent/Claude", "color": "#6554C0", "description": "Work performed by Claude Code"},
|
||||
# ... (add all 28 org labels)
|
||||
]
|
||||
|
||||
# Repository labels
|
||||
repo_labels = [
|
||||
{"name": "Component/Backend", "color": "#5319E7", "description": "Backend service code"},
|
||||
# ... (add all 16 repo labels)
|
||||
]
|
||||
|
||||
# Create organization labels
|
||||
for label in org_labels:
|
||||
response = requests.post(
|
||||
f"{GITEA_URL}/api/v1/orgs/{ORG}/labels",
|
||||
headers=headers,
|
||||
json=label
|
||||
)
|
||||
print(f"Created org label: {label['name']} - {response.status_code}")
|
||||
|
||||
# Create repository labels
|
||||
for label in repo_labels:
|
||||
response = requests.post(
|
||||
f"{GITEA_URL}/api/v1/repos/{ORG}/{REPO}/labels",
|
||||
headers=headers,
|
||||
json=label
|
||||
)
|
||||
print(f"Created repo label: {label['name']} - {response.status_code}")
|
||||
|
||||
print("\n✅ Label creation complete!")
|
||||
```
|
||||
|
||||
## After Label Creation
|
||||
|
||||
Once labels are created, you can:
|
||||
|
||||
1. ✅ Run `/labels-sync` to update plugin
|
||||
2. ✅ Run `/sprint-plan` to create labeled issues
|
||||
3. ✅ Test label suggestions
|
||||
4. ✅ Use label-based filtering in `/sprint-status`
|
||||
5. ✅ Execute full workflow test
|
||||
|
||||
The plugin will now have full functionality!
|
||||
|
||||
---
|
||||
|
||||
**Total Time:** 15-20 minutes (manual) or 2-3 minutes (script)
|
||||
**Benefit:** Full plugin functionality unlocked
|
||||
**One-Time Task:** Labels persist and are reusable across all sprints
|
||||
@@ -1,149 +0,0 @@
|
||||
# Label Creation Complete ✅
|
||||
|
||||
**Date:** 2025-11-21
|
||||
**Status:** SUCCESS - All labels created in Gitea
|
||||
|
||||
## Summary
|
||||
|
||||
Successfully created **43 labels** in the bandit organization and support-claude-mktplace repository:
|
||||
|
||||
- ✅ **27 Organization Labels** (available to all bandit repositories)
|
||||
- ✅ **16 Repository Labels** (specific to support-claude-mktplace)
|
||||
- ✅ **Total: 43 Labels** (100% complete)
|
||||
|
||||
## Label Breakdown
|
||||
|
||||
### Organization Labels (27)
|
||||
|
||||
**Agent (2):**
|
||||
- Agent/Human
|
||||
- Agent/Claude
|
||||
|
||||
**Complexity (3):**
|
||||
- Complexity/Simple
|
||||
- Complexity/Medium
|
||||
- Complexity/Complex
|
||||
|
||||
**Efforts (5):**
|
||||
- Efforts/XS
|
||||
- Efforts/S
|
||||
- Efforts/M
|
||||
- Efforts/L
|
||||
- Efforts/XL
|
||||
|
||||
**Priority (4):**
|
||||
- Priority/Low
|
||||
- Priority/Medium
|
||||
- Priority/High
|
||||
- Priority/Critical
|
||||
|
||||
**Risk (3):**
|
||||
- Risk/Low
|
||||
- Risk/Medium
|
||||
- Risk/High
|
||||
|
||||
**Source (4):**
|
||||
- Source/Development
|
||||
- Source/Staging
|
||||
- Source/Production
|
||||
- Source/Customer
|
||||
|
||||
**Type (6):**
|
||||
- Type/Bug
|
||||
- Type/Feature
|
||||
- Type/Refactor
|
||||
- Type/Documentation
|
||||
- Type/Test
|
||||
- Type/Chore
|
||||
|
||||
### Repository Labels (16)
|
||||
|
||||
**Component (9):**
|
||||
- Component/Backend
|
||||
- Component/Frontend
|
||||
- Component/API
|
||||
- Component/Database
|
||||
- Component/Auth
|
||||
- Component/Deploy
|
||||
- Component/Testing
|
||||
- Component/Docs
|
||||
- Component/Infra
|
||||
|
||||
**Tech (7):**
|
||||
- Tech/Python
|
||||
- Tech/JavaScript
|
||||
- Tech/Docker
|
||||
- Tech/PostgreSQL
|
||||
- Tech/Redis
|
||||
- Tech/Vue
|
||||
- Tech/FastAPI
|
||||
|
||||
## API Verification
|
||||
|
||||
```bash
|
||||
# Organization labels
|
||||
$ curl -s "https://hotserv.tailc9b278.ts.net/api/v1/orgs/bandit/labels" \
|
||||
-H "Authorization: token ***" | jq 'length'
|
||||
27
|
||||
|
||||
# Repository labels (shows repo-specific only)
|
||||
$ curl -s "https://hotserv.tailc9b278.ts.net/api/v1/repos/bandit/support-claude-mktplace/labels" \
|
||||
-H "Authorization: token ***" | jq 'length'
|
||||
16
|
||||
```
|
||||
|
||||
**Note:** When querying the repository labels endpoint, Gitea returns only repository-specific labels. Organization labels are still available for use on issues, but don't appear in the repository endpoint query. The MCP server correctly fetches both by calling both endpoints.
|
||||
|
||||
## How Labels Are Accessed
|
||||
|
||||
The Projman plugin's MCP server fetches labels from **both endpoints**:
|
||||
|
||||
1. **Organization Labels:** `GET /api/v1/orgs/bandit/labels` → 27 labels
|
||||
2. **Repository Labels:** `GET /api/v1/repos/bandit/support-claude-mktplace/labels` → 16 labels
|
||||
3. **Total Available:** 43 labels for issue tagging
|
||||
|
||||
See `mcp-servers/gitea/mcp_server/tools/labels.py:29` for implementation.
|
||||
|
||||
## Documentation Correction
|
||||
|
||||
**Previous Documentation Error:**
|
||||
- Original guide stated "44 labels (28 org + 16 repo)"
|
||||
- Actual count: 43 labels (27 org + 16 repo)
|
||||
|
||||
**Root Cause:**
|
||||
- Documentation counted 28 org labels but only listed 27
|
||||
- Math: 2+3+5+4+3+4+6 = 27 org labels (correct)
|
||||
|
||||
This has been corrected in subsequent documentation.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that all labels are created:
|
||||
|
||||
1. ✅ **Labels Created** - All 43 labels exist in Gitea
|
||||
2. ⏭️ **Test /labels-sync** - Verify plugin can fetch all labels
|
||||
3. ⏭️ **Test /sprint-plan** - Verify label suggestions work
|
||||
4. ⏭️ **Test Label Assignment** - Create test issue with multiple labels
|
||||
5. ⏭️ **Full Workflow Test** - Complete sprint plan → start → close cycle
|
||||
|
||||
## Files Created
|
||||
|
||||
- `create_labels.py` - Label creation script (can be reused for other repos)
|
||||
- `docs/LABEL_CREATION_COMPLETE.md` - This document
|
||||
|
||||
## Gitea Configuration
|
||||
|
||||
**Organization:** bandit
|
||||
**Repository:** support-claude-mktplace
|
||||
**API URL:** https://hotserv.tailc9b278.ts.net/api/v1
|
||||
**Auth:** Token-based (configured in ~/.config/claude/gitea.env)
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- ✅ All 27 org labels created (0 errors)
|
||||
- ✅ All 16 repo labels created (0 errors)
|
||||
- ✅ Labels verified via API
|
||||
- ✅ MCP server configured to fetch both label sets
|
||||
- ✅ Label suggestion logic implemented in plugin
|
||||
|
||||
**Status:** Ready for plugin functional testing! 🎉
|
||||
@@ -1,345 +0,0 @@
|
||||
# Live API Testing Results - Projman Plugin
|
||||
|
||||
**Date:** 2025-11-18
|
||||
**Tester:** Claude Code (Live API Tests)
|
||||
**Environment:** hotport (Raspberry Pi 4, Tailscale network)
|
||||
**Branch:** feat/projman
|
||||
|
||||
## Executive Summary
|
||||
|
||||
✅ **Both APIs are LIVE and ACCESSIBLE**
|
||||
|
||||
Successfully connected to both Gitea and Wiki.js instances running on hotport. Authentication working, basic API operations confirmed.
|
||||
|
||||
⚠️ **CRITICAL FINDING: Repository has NO LABELS**
|
||||
|
||||
The `support-claude-mktplace` repository currently has **0 labels** defined. The plugin depends on a 44-label taxonomy system. Labels must be created before full plugin functionality can be tested.
|
||||
|
||||
## Test Results
|
||||
|
||||
### 1. Gitea API - ✅ WORKING
|
||||
|
||||
**Configuration:**
|
||||
```
|
||||
URL: https://gitea.example.com/api/v1
|
||||
Token: ae72c63cd7de02e40bd16f66d1e98059c187759b
|
||||
Owner: bandit (organization)
|
||||
Repo: support-claude-mktplace
|
||||
```
|
||||
|
||||
**Authentication Test:**
|
||||
```
|
||||
✅ Successfully authenticated as: lmiranda (admin user)
|
||||
✅ User ID: 1
|
||||
✅ Email: leobmiranda@gmail.com
|
||||
✅ Admin: true
|
||||
```
|
||||
|
||||
**Repository Access:**
|
||||
```
|
||||
✅ Found 4 repositories in bandit organization:
|
||||
- support-claude-mktplace ← Our test repo
|
||||
- serv-hotport-apps
|
||||
- serv-hhl-home-apps
|
||||
- serv-hhl
|
||||
```
|
||||
|
||||
**Issue Fetching:**
|
||||
```
|
||||
✅ Successfully fetched 2 issues from support-claude-mktplace:
|
||||
- Open: 0
|
||||
- Closed: 2
|
||||
|
||||
Recent issues:
|
||||
#2: feat/gitea
|
||||
#1: plan/documentation-review
|
||||
```
|
||||
|
||||
**Label Fetching:**
|
||||
```
|
||||
⚠️ CRITICAL: Found 0 labels in repository
|
||||
Expected: 44 labels (28 org-level + 16 repo-level)
|
||||
Actual: 0 labels
|
||||
|
||||
Label categories expected but missing:
|
||||
- Type/* (Bug, Feature, Refactor, Documentation, Test, Chore)
|
||||
- Priority/* (Low, Medium, High, Critical)
|
||||
- Complexity/* (Simple, Medium, Complex)
|
||||
- Efforts/* (XS, S, M, L, XL)
|
||||
- Component/* (Backend, Frontend, API, Database, Auth, etc.)
|
||||
- Tech/* (Python, JavaScript, Docker, PostgreSQL, Redis, Vue, FastAPI)
|
||||
```
|
||||
|
||||
### 2. Wiki.js API - ✅ WORKING
|
||||
|
||||
**Configuration:**
|
||||
```
|
||||
URL: http://localhost:7851/graphql
|
||||
Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... (JWT)
|
||||
Base Path: /hyper-hive-labs
|
||||
Project: projects/support-claude-mktplace
|
||||
```
|
||||
|
||||
**Connection Test:**
|
||||
```
|
||||
✅ Client initialized successfully
|
||||
✅ GraphQL endpoint accessible
|
||||
✅ Authentication valid
|
||||
```
|
||||
|
||||
**Note:** Full Wiki.js testing deferred - basic connectivity confirmed.
|
||||
|
||||
## Critical Issue: Missing Label Taxonomy
|
||||
|
||||
### Problem
|
||||
|
||||
The Projman plugin's core functionality depends on a dynamic 44-label taxonomy:
|
||||
- `/sprint-plan` uses labels to categorize issues
|
||||
- `/labels-sync` fetches and updates label reference
|
||||
- Planner agent uses `suggest_labels` tool
|
||||
- All issue creation includes label assignment
|
||||
|
||||
**Current State:** Repository has 0 labels defined.
|
||||
|
||||
### Impact
|
||||
|
||||
**Commands Affected:**
|
||||
- ❌ `/labels-sync` - Will sync 0 labels (not useful)
|
||||
- ❌ `/sprint-plan` - Cannot apply labels to issues
|
||||
- ⚠️ `/sprint-status` - Works but issues have no labels
|
||||
- ⚠️ `/sprint-start` - Works but cannot filter by labels
|
||||
- ⚠️ `/sprint-close` - Works for lesson capture
|
||||
|
||||
**Agent Functionality:**
|
||||
- ❌ Planner cannot suggest labels (no taxonomy to reference)
|
||||
- ⚠️ Orchestrator works but cannot use label-based filtering
|
||||
- ✅ Executor not affected (doesn't use labels directly)
|
||||
|
||||
### Options to Resolve
|
||||
|
||||
**Option 1: Create Labels in Gitea (RECOMMENDED)**
|
||||
|
||||
Create the 44-label taxonomy directly in Gitea:
|
||||
|
||||
**Organization-Level Labels (28):**
|
||||
```
|
||||
Agent/Human, Agent/Claude
|
||||
Complexity/Simple, Complexity/Medium, Complexity/Complex
|
||||
Efforts/XS, Efforts/S, Efforts/M, Efforts/L, Efforts/XL
|
||||
Priority/Low, Priority/Medium, Priority/High, Priority/Critical
|
||||
Risk/Low, Risk/Medium, Risk/High
|
||||
Source/Development, Source/Staging, Source/Production, Source/Customer
|
||||
Type/Bug, Type/Feature, Type/Refactor, Type/Documentation, Type/Test, Type/Chore
|
||||
```
|
||||
|
||||
**Repository-Level Labels (16):**
|
||||
```
|
||||
Component/Backend, Component/Frontend, Component/API, Component/Database
|
||||
Component/Auth, Component/Deploy, Component/Testing, Component/Docs, Component/Infra
|
||||
Tech/Python, Tech/JavaScript, Tech/Docker, Tech/PostgreSQL
|
||||
Tech/Redis, Tech/Vue, Tech/FastAPI
|
||||
```
|
||||
|
||||
**How to create:**
|
||||
1. Navigate to: https://gitea.example.com/org/bandit/settings/labels
|
||||
2. Create organization labels (available to all repos)
|
||||
3. Navigate to: https://gitea.example.com/bandit/support-claude-mktplace/labels
|
||||
4. Create repository-specific labels
|
||||
|
||||
**Option 2: Import from Existing Repo**
|
||||
|
||||
If labels exist in another repository (e.g., CuisineFlow):
|
||||
1. Export labels from existing repo
|
||||
2. Import to support-claude-mktplace
|
||||
3. Run `/labels-sync` to update plugin
|
||||
|
||||
**Option 3: Create Programmatically**
|
||||
|
||||
Use Gitea API to create labels via script:
|
||||
```python
|
||||
# Script to create labels via API
|
||||
# See: projman/skills/label-taxonomy/labels-reference.md for full list
|
||||
```
|
||||
|
||||
## Configuration Updates Made
|
||||
|
||||
### System-Level Configuration
|
||||
|
||||
**Before (Incorrect):**
|
||||
```bash
|
||||
GITEA_API_URL=http://gitea.hotport/ # DNS not resolving
|
||||
GITEA_OWNER=claude # Wrong - user instead of org
|
||||
```
|
||||
|
||||
**After (Correct):**
|
||||
```bash
|
||||
GITEA_API_URL=https://gitea.example.com/api/v1 # Public URL
|
||||
GITEA_OWNER=bandit # Correct organization
|
||||
GITEA_API_TOKEN=ae72c63cd7de02e40bd16f66d1e98059c187759b # New token with access
|
||||
```
|
||||
|
||||
**WikiJS (Already Correct):**
|
||||
```bash
|
||||
WIKIJS_API_URL=http://localhost:7851/graphql # Local access
|
||||
WIKIJS_BASE_PATH=/hyper-hive-labs
|
||||
```
|
||||
|
||||
### Project-Level Configuration
|
||||
|
||||
**File: `.env` (in project root)**
|
||||
```bash
|
||||
GITEA_REPO=support-claude-mktplace # ✅ Correct
|
||||
WIKIJS_PROJECT=projects/support-claude-mktplace # ✅ Correct
|
||||
```
|
||||
|
||||
## What Works Right Now
|
||||
|
||||
### ✅ Fully Functional (No Labels Required)
|
||||
|
||||
1. **Configuration System**
|
||||
- Hybrid config (system + project) loads correctly
|
||||
- Mode detection works (project mode vs company mode)
|
||||
- Environment variables properly isolated
|
||||
|
||||
2. **Gitea API Integration**
|
||||
- Issue fetching (`list_issues`, `get_issue`)
|
||||
- Issue creation (`create_issue` - but without labels)
|
||||
- Issue updates (`update_issue`, `add_comment`)
|
||||
|
||||
3. **Wiki.js API Integration**
|
||||
- Basic connectivity
|
||||
- GraphQL endpoint accessible
|
||||
- Authentication working
|
||||
|
||||
4. **Commands**
|
||||
- `/sprint-status` - Can list issues (just no label filtering)
|
||||
- `/sprint-close` - Can capture lessons learned to Wiki.js
|
||||
|
||||
### ⚠️ Partially Functional (Limited Without Labels)
|
||||
|
||||
1. **Commands**
|
||||
- `/labels-sync` - Works but syncs 0 labels
|
||||
- `/sprint-plan` - Can create issues but cannot apply labels
|
||||
- `/sprint-start` - Works but cannot use label-based prioritization
|
||||
|
||||
2. **Agents**
|
||||
- Planner - Works but label suggestions return empty
|
||||
- Orchestrator - Works but cannot filter by priority labels
|
||||
- Executor - Fully functional (doesn't depend on labels)
|
||||
|
||||
### ❌ Not Functional (Requires Labels)
|
||||
|
||||
1. **Label Suggestion System**
|
||||
- `suggest_labels` tool returns empty (no taxonomy to reference)
|
||||
- Smart label categorization unavailable
|
||||
- Issue categorization by type/priority/component not possible
|
||||
|
||||
## Test Execution Summary
|
||||
|
||||
| Test Category | Status | Details |
|
||||
|---------------|--------|---------|
|
||||
| Gitea Authentication | ✅ PASS | Authenticated as lmiranda (admin) |
|
||||
| Gitea Repository Access | ✅ PASS | Access to 4 repos in bandit |
|
||||
| Gitea Issue Fetching | ✅ PASS | Fetched 2 issues successfully |
|
||||
| Gitea Label Fetching | ⚠️ PASS | API works, but 0 labels found |
|
||||
| WikiJS Authentication | ✅ PASS | JWT token valid |
|
||||
| WikiJS Connection | ✅ PASS | GraphQL endpoint accessible |
|
||||
| Configuration Loading | ✅ PASS | Both system and project configs load |
|
||||
| Mode Detection | ✅ PASS | Correctly identifies project mode |
|
||||
|
||||
**Overall API Status:** ✅ **WORKING** (APIs functional, data setup incomplete)
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Immediate Actions (Before Full Testing)
|
||||
|
||||
1. **Create Label Taxonomy in Gitea** ⭐ CRITICAL
|
||||
- Create 28 organization-level labels
|
||||
- Create 16 repository-level labels
|
||||
- Document label colors and descriptions
|
||||
- Estimated time: 15-20 minutes
|
||||
|
||||
2. **Run `/labels-sync`**
|
||||
- Verify labels fetch correctly
|
||||
- Check `projman/skills/label-taxonomy/labels-reference.md` updates
|
||||
- Confirm 44 labels detected
|
||||
|
||||
3. **Test Label-Dependent Features**
|
||||
- Create test issue with `/sprint-plan`
|
||||
- Verify labels applied correctly
|
||||
- Test label suggestion accuracy
|
||||
|
||||
### Testing Sequence (After Labels Created)
|
||||
|
||||
**Phase 1: Label System (5 min)**
|
||||
```bash
|
||||
/labels-sync # Should now show 44 labels
|
||||
```
|
||||
|
||||
**Phase 2: Issue Management (10 min)**
|
||||
```bash
|
||||
/sprint-plan # Create test issue with labels
|
||||
/sprint-status # View issues with label filtering
|
||||
```
|
||||
|
||||
**Phase 3: Full Workflow (15 min)**
|
||||
```bash
|
||||
/sprint-start # Begin sprint with label-based prioritization
|
||||
# Work on task
|
||||
/sprint-close # Capture lessons
|
||||
```
|
||||
|
||||
**Phase 4: Validation (5 min)**
|
||||
- Check Gitea: Issues have correct labels
|
||||
- Check Wiki.js: Lessons saved correctly
|
||||
- Verify label suggestions intelligent
|
||||
|
||||
## Known Issues Found
|
||||
|
||||
### Issue 1: Label Suggestion Tool (Minor)
|
||||
**Description:** `suggest_labels` returns coroutine error when called synchronously
|
||||
**Impact:** Low - works in async context (MCP server uses async)
|
||||
**Status:** Cosmetic issue in test script, not a plugin bug
|
||||
**Fix Required:** No (test script issue only)
|
||||
|
||||
### Issue 2: WikiJS Client API Mismatch (Minor)
|
||||
**Description:** `list_pages(limit=10)` fails - parameter name mismatch
|
||||
**Impact:** Low - basic connectivity works, just API signature difference
|
||||
**Status:** Need to check WikiJS client implementation
|
||||
**Fix Required:** Review mcp-servers/wikijs/mcp_server/wikijs_client.py
|
||||
|
||||
## Next Steps
|
||||
|
||||
### For Developer Testing
|
||||
|
||||
1. ✅ API connectivity confirmed
|
||||
2. ⏳ **CREATE LABELS IN GITEA** (blocking full testing)
|
||||
3. ⏳ Run `/labels-sync` and verify
|
||||
4. ⏳ Execute full test plan (docs/TEST_01_PROJMAN.md)
|
||||
5. ⏳ Document results
|
||||
|
||||
### For Plugin Development
|
||||
|
||||
1. ✅ Phase 1 (MCP Servers) - Complete
|
||||
2. ✅ Phase 2 (Commands) - Complete
|
||||
3. ✅ Phase 3 (Agents) - Complete
|
||||
4. ⏳ Phase 4 (Integration Testing) - Blocked by missing labels
|
||||
5. ⏳ Phase 5 (Lessons Learned Enhancement) - Pending
|
||||
6. ⏳ Phase 6 (Documentation) - Pending
|
||||
|
||||
## Conclusion
|
||||
|
||||
**Plugin Status:** ✅ **STRUCTURALLY COMPLETE & APIs FUNCTIONAL**
|
||||
|
||||
**Blocking Issue:** Missing label taxonomy in Gitea repository
|
||||
|
||||
**Resolution:** Create 44 labels in Gitea (15-20 min task)
|
||||
|
||||
**After Resolution:** Plugin ready for full functional testing
|
||||
|
||||
---
|
||||
|
||||
**Test Completed:** 2025-11-18 03:15 UTC
|
||||
**APIs Tested:** Gitea (✅), Wiki.js (✅)
|
||||
**Blocking Issues:** 1 (Missing labels)
|
||||
**Ready for User Testing:** After labels created
|
||||
@@ -1,304 +0,0 @@
|
||||
# Projman Plugin Testing Report - Complete ✅
|
||||
|
||||
**Date:** 2025-11-21
|
||||
**Branch:** feat/projman
|
||||
**Status:** Testing Complete - All Core Features Functional
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Successfully completed comprehensive testing of the Projman plugin. All core features are functional and ready for production use:
|
||||
|
||||
- ✅ **MCP Servers:** Both Gitea and Wiki.js servers operational
|
||||
- ✅ **Label System:** All 43 labels created and synced
|
||||
- ✅ **Issue Creation:** Automatic label resolution working
|
||||
- ✅ **Label Suggestions:** Context-based suggestions accurate
|
||||
- ✅ **Configuration:** Hybrid system + project config functional
|
||||
|
||||
## Test Environment
|
||||
|
||||
**System:**
|
||||
- Host: hotport (Raspberry Pi 4B, 8GB RAM)
|
||||
- OS: Raspberry Pi OS (Linux 6.12.47+rpt-rpi-v8)
|
||||
- Network: Tailscale VPN (100.124.47.46)
|
||||
|
||||
**Services:**
|
||||
- Gitea: https://gitea.example.com (online, responsive)
|
||||
- Wiki.js: http://localhost:7851/graphql (online, responsive)
|
||||
|
||||
**Repository:**
|
||||
- Organization: bandit
|
||||
- Repository: support-claude-mktplace
|
||||
- Branch: feat/projman
|
||||
|
||||
## Tests Performed
|
||||
|
||||
### 1. Pre-Flight Checks ✅
|
||||
|
||||
**MCP Server Verification:**
|
||||
```bash
|
||||
✅ Gitea MCP Server
|
||||
- Location: mcp-servers/gitea/
|
||||
- Files: server.py, config.py, gitea_client.py, tools/
|
||||
- Virtual env: .venv (activated successfully)
|
||||
- Status: Fully functional
|
||||
|
||||
✅ Wiki.js MCP Server
|
||||
- Location: mcp-servers/wikijs/
|
||||
- Files: server.py, config.py, wikijs_client.py, tools/
|
||||
- Virtual env: .venv (activated successfully)
|
||||
- Status: Fully functional (files restored from git)
|
||||
```
|
||||
|
||||
**Configuration Verification:**
|
||||
```bash
|
||||
✅ System-level config: ~/.config/claude/gitea.env ✅
|
||||
✅ System-level config: ~/.config/claude/wikijs.env ✅
|
||||
✅ Project-level config: .env ✅
|
||||
✅ Plugin manifest: projman/.claude-plugin/plugin.json ✅
|
||||
✅ MCP config: projman/.mcp.json ✅
|
||||
```
|
||||
|
||||
### 2. Label Sync Testing ✅
|
||||
|
||||
**Test:** Fetch all labels from Gitea and update labels-reference.md
|
||||
|
||||
**Results:**
|
||||
```
|
||||
Organization Labels: 27/27 ✅
|
||||
Repository Labels: 16/16 ✅
|
||||
Total Labels: 43/43 ✅
|
||||
|
||||
Label Categories:
|
||||
- Agent (2)
|
||||
- Complexity (3)
|
||||
- Efforts (5)
|
||||
- Priority (4)
|
||||
- Risk (3)
|
||||
- Source (4)
|
||||
- Type (6)
|
||||
- Component (9)
|
||||
- Tech (7)
|
||||
|
||||
File Updated: projman/skills/label-taxonomy/labels-reference.md
|
||||
Status: ✅ Synced with Gitea
|
||||
Last Synced: 2025-11-21
|
||||
```
|
||||
|
||||
**Conclusion:** `/labels-sync` functionality working perfectly.
|
||||
|
||||
### 3. Label Suggestion Testing ✅
|
||||
|
||||
**Test 1:** "Fix critical bug in authentication service causing login failures"
|
||||
|
||||
**Expected Labels:**
|
||||
- Type/Bug, Priority/Critical, Complexity/Medium, Component/Auth, Component/Backend
|
||||
|
||||
**Actual Labels:**
|
||||
- Type/Bug, Priority/Critical, Complexity/Medium, Efforts/L, Component/Backend, Component/Auth
|
||||
|
||||
**Result:** ✅ PASS (6/6 relevant labels suggested)
|
||||
|
||||
---
|
||||
|
||||
**Test 2:** "Add new feature to export reports to PDF format"
|
||||
|
||||
**Expected Labels:**
|
||||
- Type/Feature, Priority/Medium, Component/Backend
|
||||
|
||||
**Actual Labels:**
|
||||
- Type/Feature, Priority/Medium, Complexity/Medium, Efforts/S
|
||||
|
||||
**Result:** ✅ PASS (4/4 relevant labels suggested)
|
||||
|
||||
---
|
||||
|
||||
**Test 3:** "Add comprehensive testing for MCP servers with Docker and Python"
|
||||
|
||||
**Expected Labels:**
|
||||
- Type/Feature, Component/Testing, Tech/Python, Tech/Docker
|
||||
|
||||
**Actual Labels:**
|
||||
- Type/Feature, Priority/Low, Complexity/Medium, Efforts/S, Component/Backend, Component/Deploy, Component/Testing, Component/Docs, Tech/Python, Tech/JavaScript, Tech/Docker
|
||||
|
||||
**Result:** ✅ PASS (11/11 labels, comprehensive and accurate)
|
||||
|
||||
**Conclusion:** Label suggestion logic is intelligent and context-aware.
|
||||
|
||||
### 4. Issue Creation Testing ✅
|
||||
|
||||
**Issue #4:** Manual test with direct API call
|
||||
- Title: "[TEST] Projman Plugin - Issue Creation Verification"
|
||||
- Labels: 4 labels (Type/Feature, Priority/Medium, Component/Testing, Tech/Python)
|
||||
- Method: Direct curl with label IDs
|
||||
- Result: ✅ PASS
|
||||
- URL: https://gitea.example.com/bandit/support-claude-mktplace/issues/4
|
||||
|
||||
**Issue #5:** Automated test via MCP server (with label resolution fix)
|
||||
- Title: "[TEST] Add Comprehensive Testing for Projman MCP Servers"
|
||||
- Labels: 11 labels (all automatically resolved from names to IDs)
|
||||
- Method: MCP server with automatic label name→ID resolution
|
||||
- Result: ✅ PASS
|
||||
- URL: https://gitea.example.com/bandit/support-claude-mktplace/issues/5
|
||||
|
||||
**Conclusion:** Issue creation with automatic label resolution working flawlessly.
|
||||
|
||||
### 5. Label ID Resolution Fix ✅
|
||||
|
||||
**Problem Discovered:**
|
||||
- Gitea API expects label IDs (integers), not label names (strings)
|
||||
- Original implementation passed names, causing 422 Unprocessable Entity errors
|
||||
|
||||
**Solution Implemented:**
|
||||
- Added `_resolve_label_ids()` method to `GiteaClient`
|
||||
- Automatically fetches all labels (org + repo)
|
||||
- Builds name→ID mapping
|
||||
- Converts label names to IDs before API call
|
||||
|
||||
**Testing:**
|
||||
```python
|
||||
Input: ['Type/Feature', 'Priority/Medium', 'Component/Testing', 'Tech/Python']
|
||||
Resolution: [291, 280, 302, 305]
|
||||
API Call: ✅ SUCCESS
|
||||
Labels Applied: ✅ All 4 labels correctly applied
|
||||
```
|
||||
|
||||
**Conclusion:** Label resolution fix is production-ready.
|
||||
|
||||
## Key Findings
|
||||
|
||||
### What Works ✅
|
||||
|
||||
1. **MCP Server Architecture**
|
||||
- Both Gitea and Wiki.js MCP servers fully functional
|
||||
- Configuration loading (system + project) working perfectly
|
||||
- Mode detection (project vs company-wide) accurate
|
||||
|
||||
2. **Label System**
|
||||
- All 43 labels created in Gitea (27 org + 16 repo)
|
||||
- Label taxonomy synced to plugin
|
||||
- Label suggestion logic intelligent and context-aware
|
||||
- Automatic label name→ID resolution working
|
||||
|
||||
3. **Issue Creation**
|
||||
- Can create issues via MCP server
|
||||
- Multiple labels applied correctly
|
||||
- Label resolution transparent to users
|
||||
|
||||
4. **Plugin Structure**
|
||||
- All 5 commands properly defined
|
||||
- All 3 agents properly defined
|
||||
- Label taxonomy skill properly defined
|
||||
- Plugin manifest valid
|
||||
|
||||
### Issues Fixed During Testing ✅
|
||||
|
||||
1. **Wiki.js MCP Server Missing Files**
|
||||
- **Issue:** Files existed in git but not in working tree
|
||||
- **Root Cause:** Files not properly checked out
|
||||
- **Resolution:** Restored from commit a686c3c
|
||||
- **Status:** ✅ FIXED
|
||||
|
||||
2. **Label ID Resolution**
|
||||
- **Issue:** Gitea expects label IDs, not names
|
||||
- **Error:** 422 Unprocessable Entity
|
||||
- **Resolution:** Added `_resolve_label_ids()` method
|
||||
- **Status:** ✅ FIXED
|
||||
|
||||
### Features Not Tested (Out of Scope)
|
||||
|
||||
The following features were not tested in this session as they require actual sprint workflows:
|
||||
|
||||
- ⏭️ `/sprint-plan` command (full workflow with planner agent)
|
||||
- ⏭️ `/sprint-start` command (with lessons learned search)
|
||||
- ⏭️ `/sprint-status` command (with issue querying)
|
||||
- ⏭️ `/sprint-close` command (with lesson capture to Wiki.js)
|
||||
- ⏭️ Planner agent (architecture analysis and planning)
|
||||
- ⏭️ Orchestrator agent (sprint coordination)
|
||||
- ⏭️ Executor agent (implementation guidance)
|
||||
|
||||
**Reason:** These features require actual sprint work and cannot be meaningfully tested without real issues and workflows.
|
||||
|
||||
## Test Artifacts Created
|
||||
|
||||
### Issues Created in Gitea
|
||||
1. **Issue #4:** Label ID test (manual)
|
||||
2. **Issue #5:** Comprehensive MCP server testing (automated)
|
||||
|
||||
Both issues can be closed after verification.
|
||||
|
||||
### Files Modified
|
||||
1. `mcp-servers/gitea/mcp_server/gitea_client.py` - Added label ID resolution
|
||||
2. `projman/skills/label-taxonomy/labels-reference.md` - Updated with current taxonomy
|
||||
|
||||
### Documentation Created
|
||||
1. `docs/LABEL_CREATION_COMPLETE.md` - Label creation verification
|
||||
2. `docs/STATUS_UPDATE_2025-11-21.md` - Comprehensive status update
|
||||
3. `docs/PROJMAN_TESTING_COMPLETE.md` - This document
|
||||
|
||||
## Commits Made
|
||||
|
||||
1. `73fb576` - feat: create all 43 labels in Gitea (27 org + 16 repo)
|
||||
2. `3e571f0` - test: verify MCP server fetches all 43 labels correctly
|
||||
3. `1245862` - docs: add comprehensive status update for label creation
|
||||
4. `66da25f` - fix: add label ID resolution to Gitea create_issue
|
||||
|
||||
All commits pushed to `origin/feat/projman`.
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Production Readiness
|
||||
|
||||
**Ready for Production:**
|
||||
- ✅ Label system (all 43 labels created and synced)
|
||||
- ✅ Issue creation with labels
|
||||
- ✅ Label suggestion logic
|
||||
- ✅ MCP server infrastructure
|
||||
|
||||
**Requires Real-World Testing:**
|
||||
- ⏭️ Full sprint workflows (plan → start → close)
|
||||
- ⏭️ Agent interactions
|
||||
- ⏭️ Lessons learned capture/search
|
||||
- ⏭️ Multi-issue sprint coordination
|
||||
|
||||
### Next Steps
|
||||
|
||||
1. **Immediate (Testing Complete):**
|
||||
- ✅ Close test issues #4 and #5 in Gitea
|
||||
- ✅ Merge feat/projman to development branch
|
||||
- ✅ Deploy to production for real sprint testing
|
||||
|
||||
2. **Short-term (Real Sprint Testing):**
|
||||
- Test `/sprint-plan` with actual sprint planning
|
||||
- Test planner agent with real architecture decisions
|
||||
- Test lessons learned capture with Wiki.js
|
||||
- Validate complete sprint cycle
|
||||
|
||||
3. **Long-term (Production Use):**
|
||||
- Gather user feedback on label suggestions
|
||||
- Refine agent personalities based on real usage
|
||||
- Expand label taxonomy as needed
|
||||
- Build PMO plugin (projman-pmo) for multi-project coordination
|
||||
|
||||
## Conclusion
|
||||
|
||||
**Status:** ✅ TESTING COMPLETE - PRODUCTION READY (Core Features)
|
||||
|
||||
The Projman plugin core infrastructure is fully functional and ready for production use:
|
||||
|
||||
- All MCP servers working
|
||||
- Label system complete and accurate
|
||||
- Issue creation with labels functional
|
||||
- Configuration system robust
|
||||
- Plugin structure valid
|
||||
|
||||
The plugin can be deployed to production for real-world sprint testing. Remaining features (agents, full workflows) will be validated during actual sprint work.
|
||||
|
||||
**Total Testing Time:** ~3 hours
|
||||
**Issues Found:** 2 (both fixed)
|
||||
**Test Coverage:** Core features (100%), Workflow features (pending real sprint)
|
||||
|
||||
---
|
||||
|
||||
**Test Engineer:** Claude Code (AI Assistant)
|
||||
**Review Status:** Ready for user verification
|
||||
**Deployment Recommendation:** APPROVED for production sprint testing
|
||||
@@ -1,164 +0,0 @@
|
||||
# Status Update: Projman Plugin - Label Creation Complete
|
||||
|
||||
**Date:** 2025-11-21
|
||||
**Branch:** feat/projman
|
||||
**Status:** ✅ Labels Created & Verified - Ready for Plugin Testing
|
||||
|
||||
## Summary
|
||||
|
||||
Successfully completed label creation for the Projman plugin! All 43 labels have been created in Gitea and verified working with the MCP server.
|
||||
|
||||
## What Was Accomplished
|
||||
|
||||
### 1. Label Creation ✅
|
||||
- **Created 27 organization labels** in bandit organization
|
||||
- **Created 16 repository labels** in support-claude-mktplace repository
|
||||
- **Total: 43 labels** (corrected from initial documentation of 44)
|
||||
- All labels created programmatically via Gitea API
|
||||
|
||||
### 2. MCP Server Verification ✅
|
||||
- Verified MCP server fetches all 27 organization labels
|
||||
- Verified MCP server fetches all 16 repository labels
|
||||
- Tested label suggestion logic - working correctly
|
||||
- Configuration loading from both system and project levels verified
|
||||
|
||||
### 3. Documentation ✅
|
||||
- Created `create_labels.py` - reusable label creation script
|
||||
- Created `LABEL_CREATION_COMPLETE.md` - detailed label documentation
|
||||
- Created `test_mcp_labels.py` - comprehensive label fetching test
|
||||
- Created this status update
|
||||
|
||||
## Label Breakdown
|
||||
|
||||
### Organization Labels (27)
|
||||
- **Agent:** 2 labels (Human, Claude)
|
||||
- **Complexity:** 3 labels (Simple, Medium, Complex)
|
||||
- **Efforts:** 5 labels (XS, S, M, L, XL)
|
||||
- **Priority:** 4 labels (Low, Medium, High, Critical)
|
||||
- **Risk:** 3 labels (Low, Medium, High)
|
||||
- **Source:** 4 labels (Development, Staging, Production, Customer)
|
||||
- **Type:** 6 labels (Bug, Feature, Refactor, Documentation, Test, Chore)
|
||||
|
||||
### Repository Labels (16)
|
||||
- **Component:** 9 labels (Backend, Frontend, API, Database, Auth, Deploy, Testing, Docs, Infra)
|
||||
- **Tech:** 7 labels (Python, JavaScript, Docker, PostgreSQL, Redis, Vue, FastAPI)
|
||||
|
||||
## Test Results
|
||||
|
||||
### MCP Server Label Fetching Test
|
||||
```
|
||||
✅ Organization labels: 27/27 (100%)
|
||||
✅ Repository labels: 16/16 (100%)
|
||||
✅ Total labels: 43/43 (100%)
|
||||
✅ Label suggestions working correctly
|
||||
```
|
||||
|
||||
### Label Suggestion Examples
|
||||
1. **"Fix critical bug in authentication service causing login failures"**
|
||||
- Suggested: Type/Bug, Priority/Critical, Complexity/Medium, Efforts/L, Component/Backend, Component/Auth
|
||||
|
||||
2. **"Add new feature to export reports to PDF format"**
|
||||
- Suggested: Type/Feature, Priority/Medium, Complexity/Medium, Efforts/S
|
||||
|
||||
3. **"Refactor backend API to extract authentication service"**
|
||||
- Suggested: Type/Refactor, Priority/Medium, Complexity/Medium, Component/Backend, Component/API, Component/Auth
|
||||
|
||||
All suggestions are accurate and appropriate! 🎉
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
**New Files:**
|
||||
- `create_labels.py` - Label creation script (381 lines)
|
||||
- `test_mcp_labels.py` - MCP server label test (136 lines)
|
||||
- `docs/LABEL_CREATION_COMPLETE.md` - Label documentation
|
||||
- `docs/STATUS_UPDATE_2025-11-21.md` - This document
|
||||
|
||||
**Commits:**
|
||||
1. `73fb576` - feat: create all 43 labels in Gitea (27 org + 16 repo)
|
||||
2. `3e571f0` - test: verify MCP server fetches all 43 labels correctly
|
||||
|
||||
## Documentation Correction
|
||||
|
||||
**Original Documentation:** 44 labels (28 org + 16 repo)
|
||||
**Actual Count:** 43 labels (27 org + 16 repo)
|
||||
|
||||
**Explanation:** The CREATE_LABELS_GUIDE.md stated 28 organization labels but only listed 27. The math confirms 27 is correct: 2+3+5+4+3+4+6 = 27.
|
||||
|
||||
## Configuration Details
|
||||
|
||||
**Gitea Configuration:**
|
||||
- API URL: `https://gitea.example.com/api/v1`
|
||||
- Organization: `bandit`
|
||||
- Repository: `support-claude-mktplace`
|
||||
- Token: Configured in `~/.config/claude/gitea.env`
|
||||
|
||||
**MCP Server:**
|
||||
- Location: `mcp-servers/gitea/`
|
||||
- Mode: Project mode (single-repo)
|
||||
- Config: Hybrid (system + project level)
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that labels are created and verified, we can proceed with full plugin testing:
|
||||
|
||||
### Immediate Next Steps:
|
||||
1. ⏭️ **Test `/sprint-plan` command** - Verify it can create issues with labels
|
||||
2. ⏭️ **Test `/labels-sync` command** - Verify it updates labels-reference.md
|
||||
3. ⏭️ **Create test issues** - Validate label assignment works in Gitea UI
|
||||
4. ⏭️ **Test label suggestions** - Try sprint planning with different contexts
|
||||
|
||||
### Full Workflow Testing (After Basic Tests):
|
||||
1. Complete sprint planning workflow
|
||||
2. Test sprint start and orchestration
|
||||
3. Verify sprint status reporting
|
||||
4. Test sprint close and lessons learned
|
||||
5. Execute complete end-to-end sprint cycle
|
||||
|
||||
### Before User Testing:
|
||||
- ✅ Phase 1: MCP Servers (Complete)
|
||||
- ✅ Phase 2: Commands (Complete)
|
||||
- ✅ Phase 3: Agents (Complete)
|
||||
- ✅ Labels Created (Complete)
|
||||
- ⏭️ Phase 4: Functional Testing (Next)
|
||||
|
||||
## Technical Notes
|
||||
|
||||
### Gitea API Behavior
|
||||
When querying `/repos/{owner}/{repo}/labels`, Gitea returns only repository-specific labels (16 labels). Organization labels don't appear in this endpoint but are still available for issue tagging.
|
||||
|
||||
The MCP server correctly handles this by:
|
||||
1. Fetching org labels via `/orgs/{owner}/labels` (27 labels)
|
||||
2. Fetching repo labels via `/repos/{owner}/{repo}/labels` (16 labels)
|
||||
3. Merging both sets for a total of 43 available labels
|
||||
|
||||
See `mcp-servers/gitea/mcp_server/tools/labels.py:29` for implementation.
|
||||
|
||||
### Label Suggestion Algorithm
|
||||
The label suggestion logic uses keyword matching and context analysis to recommend appropriate labels. It correctly:
|
||||
- Detects issue type from keywords (bug, feature, refactor, etc.)
|
||||
- Infers priority from urgency indicators
|
||||
- Identifies affected components from technical terms
|
||||
- Suggests tech stack labels based on mentioned technologies
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- ✅ All 43 labels created successfully (0 errors)
|
||||
- ✅ MCP server verified working (100% test pass rate)
|
||||
- ✅ Label suggestions tested and accurate
|
||||
- ✅ Configuration validated (system + project)
|
||||
- ✅ Documentation complete and accurate
|
||||
|
||||
## Conclusion
|
||||
|
||||
**The label taxonomy is complete and fully functional!** All 43 labels are created in Gitea, the MCP server can fetch them correctly, and the label suggestion system is working beautifully.
|
||||
|
||||
We're now ready to move forward with comprehensive plugin testing. The blocking issue from the previous testing session has been resolved.
|
||||
|
||||
**Status: Ready for Plugin Functional Testing** 🚀
|
||||
|
||||
---
|
||||
|
||||
**Previous Session Issue:** Repository had 0 labels
|
||||
**Resolution:** Created all 43 labels programmatically
|
||||
**Verification:** MCP server test passed 100%
|
||||
**Blocker Status:** ✅ RESOLVED
|
||||
@@ -1,630 +0,0 @@
|
||||
# Projman Plugin Testing Plan
|
||||
|
||||
**Status:** Phase 2 & 3 Complete - Ready for Testing
|
||||
**Date:** 2025-11-18
|
||||
**Plugin Version:** 0.1.0
|
||||
|
||||
## Overview
|
||||
|
||||
This document outlines the testing strategy for the Projman plugin, which has completed Phase 2 (Commands) and Phase 3 (Agents).
|
||||
|
||||
## What Was Built
|
||||
|
||||
### Phase 2: Commands (5 total)
|
||||
- ✅ `/sprint-plan` - AI-guided planning with planner agent
|
||||
- ✅ `/sprint-start` - Begin execution with orchestrator agent
|
||||
- ✅ `/sprint-status` - Quick progress check
|
||||
- ✅ `/sprint-close` - Capture lessons learned (critical!)
|
||||
- ✅ `/labels-sync` - Sync label taxonomy from Gitea
|
||||
|
||||
### Phase 3: Agents (3 total)
|
||||
- ✅ **Planner Agent** - Thoughtful, asks clarifying questions, searches lessons learned
|
||||
- ✅ **Orchestrator Agent** - Concise, action-oriented, tracks progress meticulously
|
||||
- ✅ **Executor Agent** - Implementation-focused, follows specs precisely
|
||||
|
||||
### Supporting Components
|
||||
- ✅ Plugin manifest (`plugin.json`) with valid schema
|
||||
- ✅ MCP configuration (`.mcp.json`) for Gitea + Wiki.js
|
||||
- ✅ Label taxonomy skill with suggestion logic
|
||||
- ✅ README.md with complete usage guide
|
||||
- ✅ CONFIGURATION.md with step-by-step setup
|
||||
|
||||
**Total:** 13 files, ~3,719 lines of documentation
|
||||
|
||||
## Testing Setup
|
||||
|
||||
### Prerequisites Completed
|
||||
|
||||
✅ **MCP Servers Installed:**
|
||||
- `mcp-servers/gitea/.venv/` - Gitea MCP Server
|
||||
- `mcp-servers/wikijs/.venv/` - Wiki.js MCP Server
|
||||
|
||||
✅ **System Configuration:**
|
||||
- `~/.config/claude/gitea.env` - Gitea credentials
|
||||
- `~/.config/claude/wikijs.env` - Wiki.js credentials
|
||||
|
||||
✅ **Project Configuration:**
|
||||
- `.env` - Project-specific settings (NOT committed)
|
||||
```bash
|
||||
GITEA_REPO=support-claude-mktplace
|
||||
WIKIJS_PROJECT=projects/support-claude-mktplace
|
||||
```
|
||||
|
||||
✅ **Local Marketplace:**
|
||||
- `.claude-plugins/projman-marketplace/marketplace.json`
|
||||
- Points to `../../projman` for local testing
|
||||
|
||||
### Repository Structure
|
||||
|
||||
```
|
||||
hhl-claude-agents/
|
||||
├── .env ✅ Project config (in .gitignore)
|
||||
├── .claude-plugins/
|
||||
│ └── projman-marketplace/
|
||||
│ └── marketplace.json ✅ Local marketplace
|
||||
├── projman/ ✅ Complete plugin
|
||||
│ ├── .claude-plugin/
|
||||
│ │ └── plugin.json
|
||||
│ ├── .mcp.json
|
||||
│ ├── 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/
|
||||
│ │ └── labels-reference.md
|
||||
│ ├── README.md
|
||||
│ └── CONFIGURATION.md
|
||||
└── mcp-servers/
|
||||
├── gitea/
|
||||
│ └── .venv/
|
||||
└── wikijs/
|
||||
└── .venv/
|
||||
```
|
||||
|
||||
## Pre-Flight Checks
|
||||
|
||||
### 1. Verify MCP Server Connectivity
|
||||
|
||||
**Test Gitea Connection:**
|
||||
```bash
|
||||
cd mcp-servers/gitea
|
||||
source .venv/bin/activate
|
||||
python -c "from mcp_server.config import load_config; config = load_config(); print(f'✅ Gitea: {config.api_url}')"
|
||||
```
|
||||
|
||||
**Expected output:**
|
||||
```
|
||||
✅ Gitea: http://gitea.hotport/api/v1
|
||||
```
|
||||
|
||||
**Test Wiki.js Connection:**
|
||||
```bash
|
||||
cd mcp-servers/wikijs
|
||||
source .venv/bin/activate
|
||||
python -c "from mcp_server.config import load_config; config = load_config(); print(f'✅ Wiki.js: {config.api_url}')"
|
||||
```
|
||||
|
||||
**Expected output:**
|
||||
```
|
||||
✅ Wiki.js: http://wikijs.hotport/graphql
|
||||
```
|
||||
|
||||
### 2. Verify Configuration Files
|
||||
|
||||
**Check System Config:**
|
||||
```bash
|
||||
ls -la ~/.config/claude/*.env
|
||||
# Should show:
|
||||
# -rw------- gitea.env
|
||||
# -rw------- wikijs.env
|
||||
```
|
||||
|
||||
**Check Project Config:**
|
||||
```bash
|
||||
cat .env
|
||||
# Should show:
|
||||
# GITEA_REPO=support-claude-mktplace
|
||||
# WIKIJS_PROJECT=projects/support-claude-mktplace
|
||||
```
|
||||
|
||||
**Verify .env is ignored:**
|
||||
```bash
|
||||
git check-ignore .env
|
||||
# Should output: .env
|
||||
```
|
||||
|
||||
### 3. Verify Plugin Structure
|
||||
|
||||
**Check plugin manifest:**
|
||||
```bash
|
||||
cat projman/.claude-plugin/plugin.json | python3 -m json.tool > /dev/null && echo "✅ Valid JSON"
|
||||
```
|
||||
|
||||
**Check MCP config:**
|
||||
```bash
|
||||
cat projman/.mcp.json | python3 -m json.tool > /dev/null && echo "✅ Valid JSON"
|
||||
```
|
||||
|
||||
**List all components:**
|
||||
```bash
|
||||
tree projman/ -L 2
|
||||
```
|
||||
|
||||
## Testing Phases
|
||||
|
||||
### Phase 1: Quick Validation (5-10 minutes)
|
||||
|
||||
**Goal:** Verify basic connectivity and command loading
|
||||
|
||||
**Test 1.1: Label Sync** (No agent, pure MCP test)
|
||||
```
|
||||
/labels-sync
|
||||
```
|
||||
|
||||
**Expected Behavior:**
|
||||
- ✅ Checks git branch first
|
||||
- ✅ Connects to Gitea MCP server
|
||||
- ✅ Fetches organization labels (28)
|
||||
- ✅ Fetches repository labels (16)
|
||||
- ✅ Shows total count (44 labels)
|
||||
- ✅ Updates `projman/skills/label-taxonomy/labels-reference.md`
|
||||
- ✅ Confirms successful sync
|
||||
|
||||
**Success Criteria:**
|
||||
- No connection errors
|
||||
- Label counts match Gitea
|
||||
- File updated with current timestamp
|
||||
- All label categories present (Agent, Complexity, Efforts, Priority, Risk, Source, Type, Component, Tech)
|
||||
|
||||
**Test 1.2: Sprint Status** (Read-only test)
|
||||
```
|
||||
/sprint-status
|
||||
```
|
||||
|
||||
**Expected Behavior:**
|
||||
- ✅ Checks git branch
|
||||
- ✅ Fetches open issues from Gitea
|
||||
- ✅ Fetches closed issues from Gitea
|
||||
- ✅ Categorizes by status (Open, In Progress, Blocked, Completed)
|
||||
- ✅ Shows completion percentage
|
||||
- ✅ Identifies priority alerts
|
||||
|
||||
**Success Criteria:**
|
||||
- Issues fetch successfully
|
||||
- Categorization works
|
||||
- No write operations attempted
|
||||
- Progress summary accurate
|
||||
|
||||
### Phase 2: Agent Validation (15-20 minutes)
|
||||
|
||||
**Goal:** Test agent personalities and MCP tool integration
|
||||
|
||||
**Test 2.1: Planner Agent** (via `/sprint-plan`)
|
||||
```
|
||||
/sprint-plan
|
||||
```
|
||||
|
||||
**Test Input:**
|
||||
> "Plan a small sprint to add usage examples to the projman README"
|
||||
|
||||
**Expected Planner Behavior:**
|
||||
1. ✅ Checks git branch (development)
|
||||
2. ✅ Asks clarifying questions:
|
||||
- What kind of examples?
|
||||
- How detailed should they be?
|
||||
- Any specific use cases?
|
||||
3. ✅ Searches lessons learned:
|
||||
- Uses `search_lessons` MCP tool
|
||||
- Searches by tags: "documentation", "readme"
|
||||
4. ✅ Performs architecture analysis:
|
||||
- Thinks through structure
|
||||
- Considers edge cases
|
||||
- References past lessons
|
||||
5. ✅ Creates Gitea issues:
|
||||
- Uses `suggest_labels` for each issue
|
||||
- Creates 2-3 well-structured issues
|
||||
- Includes acceptance criteria
|
||||
- References architectural decisions
|
||||
6. ✅ Generates planning document:
|
||||
- Summarizes sprint goals
|
||||
- Lists created issues
|
||||
- Documents assumptions
|
||||
|
||||
**Success Criteria:**
|
||||
- Planner personality evident (thoughtful, asks questions)
|
||||
- Lessons learned searched proactively
|
||||
- Labels suggested intelligently
|
||||
- Issues created in Gitea with proper structure
|
||||
- Architecture analysis thorough
|
||||
|
||||
**Test 2.2: Orchestrator Agent** (via `/sprint-start`)
|
||||
```
|
||||
/sprint-start
|
||||
```
|
||||
|
||||
**Expected Orchestrator Behavior:**
|
||||
1. ✅ Checks git branch
|
||||
2. ✅ Fetches sprint issues from Gitea
|
||||
3. ✅ Searches relevant lessons:
|
||||
- Uses `search_lessons` with tags
|
||||
- Presents relevant past experiences
|
||||
4. ✅ Identifies next task:
|
||||
- Highest priority
|
||||
- Unblocked by dependencies
|
||||
5. ✅ Generates lean execution prompt:
|
||||
- Concise (not verbose)
|
||||
- Actionable steps
|
||||
- References lessons
|
||||
- Clear acceptance criteria
|
||||
|
||||
**Success Criteria:**
|
||||
- Orchestrator personality evident (concise, action-oriented)
|
||||
- Lessons searched by relevant tags
|
||||
- Next task identified correctly
|
||||
- Execution prompt is lean (not planning document)
|
||||
- Dependencies checked
|
||||
|
||||
**Test 2.3: Executor Agent** (Manual invocation if needed)
|
||||
|
||||
**Note:** Executor typically invoked by orchestrator, but can be tested independently.
|
||||
|
||||
**Expected Executor Behavior:**
|
||||
1. ✅ Checks git branch
|
||||
2. ✅ Follows specifications precisely
|
||||
3. ✅ Writes clean, tested code
|
||||
4. ✅ Handles edge cases
|
||||
5. ✅ References lessons learned in code comments
|
||||
6. ✅ Generates completion report
|
||||
|
||||
**Success Criteria:**
|
||||
- Executor personality evident (implementation-focused)
|
||||
- Code follows specs exactly
|
||||
- Tests included
|
||||
- Edge cases covered
|
||||
- Lessons applied in implementation
|
||||
|
||||
### Phase 3: Full Workflow Test (30-45 minutes)
|
||||
|
||||
**Goal:** Complete sprint lifecycle end-to-end
|
||||
|
||||
**Scenario:** "Add comprehensive testing examples to projman documentation"
|
||||
|
||||
**Step 3.1: Planning** (`/sprint-plan`)
|
||||
```
|
||||
/sprint-plan
|
||||
|
||||
Input: "Add comprehensive testing examples to projman documentation,
|
||||
including command usage, agent behavior, and troubleshooting scenarios"
|
||||
```
|
||||
|
||||
**Expected Flow:**
|
||||
1. Planner asks clarifying questions
|
||||
2. Searches lessons about documentation
|
||||
3. Creates 3-4 issues in Gitea:
|
||||
- Add command usage examples
|
||||
- Add agent behavior examples
|
||||
- Add troubleshooting guide
|
||||
- Add quick start tutorial
|
||||
4. Suggests appropriate labels for each
|
||||
|
||||
**Validation:**
|
||||
- [ ] Check Gitea - issues created?
|
||||
- [ ] Check labels - appropriate categories?
|
||||
- [ ] Check issue bodies - acceptance criteria clear?
|
||||
|
||||
**Step 3.2: Execution** (`/sprint-start`)
|
||||
```
|
||||
/sprint-start
|
||||
```
|
||||
|
||||
**Expected Flow:**
|
||||
1. Orchestrator reviews issues
|
||||
2. Searches lessons about documentation
|
||||
3. Identifies first task
|
||||
4. Generates lean execution prompt
|
||||
|
||||
**Validation:**
|
||||
- [ ] Next task correctly identified?
|
||||
- [ ] Execution prompt concise?
|
||||
- [ ] Lessons referenced?
|
||||
|
||||
**Step 3.3: Work on Task**
|
||||
|
||||
Implement the first task (e.g., add command examples to README).
|
||||
|
||||
**Step 3.4: Close Sprint** (`/sprint-close`)
|
||||
```
|
||||
/sprint-close
|
||||
```
|
||||
|
||||
**Expected Flow:**
|
||||
1. Orchestrator reviews completion
|
||||
2. Asks questions about sprint:
|
||||
- What challenges faced?
|
||||
- What went well?
|
||||
- Preventable mistakes?
|
||||
3. Captures lessons learned:
|
||||
- Structures in proper format
|
||||
- Suggests appropriate tags
|
||||
4. Saves to Wiki.js:
|
||||
- Uses `create_lesson` MCP tool
|
||||
- Creates in `/projects/support-claude-mktplace/lessons-learned/sprints/`
|
||||
5. Offers git operations:
|
||||
- Commit changes
|
||||
- Merge branches
|
||||
- Tag sprint
|
||||
|
||||
**Validation:**
|
||||
- [ ] Lessons captured in proper format?
|
||||
- [ ] Saved to Wiki.js successfully?
|
||||
- [ ] Tags appropriate for discovery?
|
||||
- [ ] Check Wiki.js - lesson visible?
|
||||
|
||||
### Phase 4: Edge Case Testing (15-20 minutes)
|
||||
|
||||
**Goal:** Test branch detection and security
|
||||
|
||||
**Test 4.1: Production Branch Detection**
|
||||
|
||||
```bash
|
||||
git checkout main # Switch to production
|
||||
/sprint-plan
|
||||
```
|
||||
|
||||
**Expected Behavior:**
|
||||
- ❌ Command blocks immediately
|
||||
- ❌ Shows production branch warning
|
||||
- ❌ Instructs user to switch to development
|
||||
- ❌ Does NOT proceed with planning
|
||||
|
||||
**Test 4.2: Staging Branch Detection**
|
||||
|
||||
```bash
|
||||
git checkout -b staging # Create staging branch
|
||||
/sprint-start
|
||||
```
|
||||
|
||||
**Expected Behavior:**
|
||||
- ⚠️ Command warns about staging
|
||||
- ⚠️ Limited capabilities (can create issues, cannot modify code)
|
||||
- ⚠️ Instructs to switch to development for execution
|
||||
|
||||
**Test 4.3: Development Branch (Normal)**
|
||||
|
||||
```bash
|
||||
git checkout development # Back to development
|
||||
/sprint-plan
|
||||
```
|
||||
|
||||
**Expected Behavior:**
|
||||
- ✅ Full capabilities enabled
|
||||
- ✅ No warnings
|
||||
- ✅ Normal operation
|
||||
|
||||
**Validation:**
|
||||
- [ ] Production branch blocked?
|
||||
- [ ] Staging branch limited?
|
||||
- [ ] Development branch full access?
|
||||
|
||||
### Phase 5: Error Handling (10-15 minutes)
|
||||
|
||||
**Goal:** Test graceful error handling
|
||||
|
||||
**Test 5.1: Invalid Configuration**
|
||||
|
||||
Temporarily rename `.env`:
|
||||
```bash
|
||||
mv .env .env.bak
|
||||
/sprint-status
|
||||
```
|
||||
|
||||
**Expected Behavior:**
|
||||
- ❌ Clear error message about missing configuration
|
||||
- ❌ Instructions to create .env
|
||||
- ❌ No cryptic errors
|
||||
|
||||
**Test 5.2: Network Issues** (Simulate)
|
||||
|
||||
Stop Gitea or Wiki.js service temporarily:
|
||||
```
|
||||
/labels-sync
|
||||
```
|
||||
|
||||
**Expected Behavior:**
|
||||
- ❌ Connection error clearly stated
|
||||
- ❌ Helpful troubleshooting suggestions
|
||||
- ❌ No crashes or stack traces
|
||||
|
||||
**Test 5.3: Invalid Repository**
|
||||
|
||||
Edit `.env` with wrong repo name:
|
||||
```bash
|
||||
echo "GITEA_REPO=nonexistent-repo" > .env
|
||||
/sprint-status
|
||||
```
|
||||
|
||||
**Expected Behavior:**
|
||||
- ❌ Repository not found error
|
||||
- ❌ Suggestions to check .env configuration
|
||||
- ❌ No silent failures
|
||||
|
||||
**Cleanup:**
|
||||
```bash
|
||||
mv .env.bak .env # Restore configuration
|
||||
```
|
||||
|
||||
## Success Metrics
|
||||
|
||||
### Technical Metrics
|
||||
|
||||
- [ ] All MCP servers connect successfully
|
||||
- [ ] All 5 commands execute without errors
|
||||
- [ ] All 3 agents exhibit correct personalities
|
||||
- [ ] Branch detection works 100% accurately
|
||||
- [ ] Labels sync correctly from Gitea
|
||||
- [ ] Issues created with proper structure and labels
|
||||
- [ ] Lessons learned saved to Wiki.js successfully
|
||||
- [ ] No hardcoded secrets or absolute paths
|
||||
- [ ] Error messages clear and actionable
|
||||
|
||||
### User Experience Metrics
|
||||
|
||||
- [ ] Commands intuitive to use
|
||||
- [ ] Agent personalities distinct and helpful
|
||||
- [ ] Planner asks relevant questions
|
||||
- [ ] Orchestrator provides concise guidance
|
||||
- [ ] Executor follows specs precisely
|
||||
- [ ] Error messages helpful (not cryptic)
|
||||
- [ ] Documentation clear and accurate
|
||||
|
||||
### Quality Metrics
|
||||
|
||||
- [ ] No crashes or unhandled exceptions
|
||||
- [ ] Branch security enforced correctly
|
||||
- [ ] Configuration validation works
|
||||
- [ ] MCP tool integration seamless
|
||||
- [ ] Label suggestions intelligent
|
||||
- [ ] Lessons learned captured systematically
|
||||
|
||||
## Known Limitations (Phase 0.1.0)
|
||||
|
||||
1. **No Executor Integration** - Executor agent not yet invoked automatically by orchestrator (Phase 4)
|
||||
2. **No Milestone Support** - Sprint milestones not implemented (Phase 4)
|
||||
3. **No Dependencies Tracking** - Issue dependencies not automatically tracked (Phase 4)
|
||||
4. **No Progress Updates** - Orchestrator doesn't automatically update issue comments (Phase 4)
|
||||
5. **Manual Git Operations** - Git operations not automated yet (Phase 4)
|
||||
|
||||
These are expected at this stage and will be addressed in Phase 4 (Lessons Learned Integration).
|
||||
|
||||
## Troubleshooting Guide
|
||||
|
||||
### Issue: Commands not found
|
||||
|
||||
**Symptoms:** `/sprint-plan` returns "command not found"
|
||||
|
||||
**Solutions:**
|
||||
1. Check marketplace loaded: `ls .claude-plugins/projman-marketplace/`
|
||||
2. Verify plugin path in marketplace.json
|
||||
3. Restart Claude Code
|
||||
|
||||
### Issue: MCP connection errors
|
||||
|
||||
**Symptoms:** "Failed to connect to Gitea" or "Failed to connect to Wiki.js"
|
||||
|
||||
**Solutions:**
|
||||
1. Check system config exists: `ls ~/.config/claude/*.env`
|
||||
2. Verify API URLs correct in config files
|
||||
3. Test MCP servers manually (see Pre-Flight Checks)
|
||||
4. Check network connectivity to services
|
||||
|
||||
### Issue: Repository not found
|
||||
|
||||
**Symptoms:** "Repository 'X' not found in organization"
|
||||
|
||||
**Solutions:**
|
||||
1. Check `.env` file: `cat .env`
|
||||
2. Verify `GITEA_REPO` matches actual repository name
|
||||
3. Check Gitea organization matches `GITEA_OWNER` in system config
|
||||
4. Verify API token has access to repository
|
||||
|
||||
### Issue: Lessons not saving to Wiki.js
|
||||
|
||||
**Symptoms:** "Failed to create lesson" or permission errors
|
||||
|
||||
**Solutions:**
|
||||
1. Check Wiki.js API token has Pages (create) permission
|
||||
2. Verify `WIKIJS_BASE_PATH` exists in Wiki.js
|
||||
3. Check `WIKIJS_PROJECT` path is correct
|
||||
4. Test Wiki.js connection (see Pre-Flight Checks)
|
||||
|
||||
### Issue: Branch detection not working
|
||||
|
||||
**Symptoms:** Can create issues on production branch
|
||||
|
||||
**Solutions:**
|
||||
1. Verify git repository initialized: `git status`
|
||||
2. Check branch name: `git branch --show-current`
|
||||
3. Review agent prompts - branch check should be first operation
|
||||
4. This is a critical bug - report immediately
|
||||
|
||||
## Next Steps After Testing
|
||||
|
||||
### If All Tests Pass ✅
|
||||
|
||||
1. **Document Findings**
|
||||
- Create test report with results
|
||||
- Note any minor issues encountered
|
||||
- Capture user experience feedback
|
||||
|
||||
2. **Move to Phase 4: Lessons Learned Integration**
|
||||
- Implement automatic issue updates
|
||||
- Add milestone support
|
||||
- Implement dependency tracking
|
||||
- Automate git operations
|
||||
|
||||
3. **Prepare for Phase 5: Testing & Validation**
|
||||
- Write integration tests
|
||||
- Test with real sprint on a production project
|
||||
- Collect user feedback from team
|
||||
|
||||
### If Tests Fail ❌
|
||||
|
||||
1. **Document Failures**
|
||||
- Exact error messages
|
||||
- Steps to reproduce
|
||||
- Expected vs actual behavior
|
||||
|
||||
2. **Categorize Issues**
|
||||
- Critical: Blocks basic functionality
|
||||
- High: Major feature doesn't work
|
||||
- Medium: Feature works but has issues
|
||||
- Low: Minor UX improvements
|
||||
|
||||
3. **Fix and Retest**
|
||||
- Fix critical issues first
|
||||
- Retest after each fix
|
||||
- Update documentation if needed
|
||||
|
||||
## Test Execution Log
|
||||
|
||||
### Test Session 1: [Date]
|
||||
|
||||
**Tester:** [Name]
|
||||
**Duration:** [Time]
|
||||
**Environment:**
|
||||
- Branch: [branch name]
|
||||
- Claude Code Version: [version]
|
||||
- Plugin Version: 0.1.0
|
||||
|
||||
**Results:**
|
||||
|
||||
| Test | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| Pre-Flight: MCP Connectivity | [ ] Pass / [ ] Fail | |
|
||||
| Pre-Flight: Configuration | [ ] Pass / [ ] Fail | |
|
||||
| 1.1: Label Sync | [ ] Pass / [ ] Fail | |
|
||||
| 1.2: Sprint Status | [ ] Pass / [ ] Fail | |
|
||||
| 2.1: Planner Agent | [ ] Pass / [ ] Fail | |
|
||||
| 2.2: Orchestrator Agent | [ ] Pass / [ ] Fail | |
|
||||
| 2.3: Executor Agent | [ ] Pass / [ ] Fail | |
|
||||
| 3: Full Workflow | [ ] Pass / [ ] Fail | |
|
||||
| 4: Branch Detection | [ ] Pass / [ ] Fail | |
|
||||
| 5: Error Handling | [ ] Pass / [ ] Fail | |
|
||||
|
||||
**Overall Assessment:** [ ] Pass / [ ] Fail
|
||||
|
||||
**Critical Issues Found:** [Number]
|
||||
|
||||
**Recommendations:** [Next steps]
|
||||
|
||||
---
|
||||
|
||||
**Testing Status:** Ready to Begin
|
||||
**Next Step:** Execute Pre-Flight Checks and Phase 1 Quick Validation
|
||||
@@ -1,458 +0,0 @@
|
||||
# Projman Plugin - Test Execution Report
|
||||
|
||||
**Date:** 2025-11-18
|
||||
**Tester:** Claude Code (Automated)
|
||||
**Plugin Version:** 0.1.0
|
||||
**Branch:** feat/projman
|
||||
|
||||
## Executive Summary
|
||||
|
||||
✅ **VALIDATION STATUS: PASSED**
|
||||
|
||||
The Projman plugin has been validated for structural integrity, manifest compliance, security best practices, and documentation quality. All automated tests that could be run without live network access have **PASSED** (63/63 checks).
|
||||
|
||||
**Key Findings:**
|
||||
- ✅ Plugin structure correct and complete
|
||||
- ✅ All manifests valid JSON
|
||||
- ✅ All commands, agents, and skills present
|
||||
- ✅ Security practices followed (no hardcoded secrets, proper .gitignore)
|
||||
- ✅ Documentation comprehensive
|
||||
- ⚠️ Live API testing requires local network access (deferred to manual testing)
|
||||
|
||||
## Test Environment
|
||||
|
||||
**System:**
|
||||
- OS: Linux 6.12.47+rpt-rpi-v8 (Raspberry Pi)
|
||||
- Python: 3.11
|
||||
- Working Directory: `/home/lmiranda/Repositories/hhl/hhl-claude-agents`
|
||||
- Git Branch: `feat/projman`
|
||||
|
||||
**Configuration:**
|
||||
- System Config: `~/.config/claude/gitea.env`, `wikijs.env` (present ✅)
|
||||
- Project Config: `.env` (present ✅, properly ignored ✅)
|
||||
- MCP Servers: Installed in `mcp-servers/` (✅)
|
||||
|
||||
## Tests Executed
|
||||
|
||||
### Pre-Flight Checks: Configuration ✅ PASS
|
||||
|
||||
**Test 1.1: Gitea MCP Configuration Loading**
|
||||
```
|
||||
Status: ✅ PASS
|
||||
Details:
|
||||
- System config loads correctly from ~/.config/claude/gitea.env
|
||||
- Project config loads correctly from .env
|
||||
- Mode detection works (project mode)
|
||||
- Repository correctly identified: support-claude-mktplace
|
||||
- Owner correctly identified: claude
|
||||
```
|
||||
|
||||
**Test 1.2: Wiki.js MCP Configuration Loading**
|
||||
```
|
||||
Status: ✅ PASS
|
||||
Details:
|
||||
- System config loads correctly from ~/.config/claude/wikijs.env
|
||||
- Project config loads correctly from .env
|
||||
- Mode detection works (project mode)
|
||||
- Project correctly identified: projects/support-claude-mktplace
|
||||
- Base path correctly set: /hyper-hive-labs
|
||||
```
|
||||
|
||||
### Pre-Flight Checks: API Connectivity ⚠️ DEFERRED
|
||||
|
||||
**Test 2.1: Gitea API Connection**
|
||||
```
|
||||
Status: ⚠️ DEFERRED (Network limitation)
|
||||
Reason: Gitea instance at gitea.hotport not accessible from test environment
|
||||
Expected: Will work when run from local network/Tailscale
|
||||
Recommendation: Manual testing required
|
||||
```
|
||||
|
||||
**Test 2.2: Wiki.js API Connection**
|
||||
```
|
||||
Status: ⚠️ DEFERRED (Network limitation)
|
||||
Reason: Wiki.js instance at wikijs.hotport not accessible from test environment
|
||||
Expected: Will work when run from local network/Tailscale
|
||||
Recommendation: Manual testing required
|
||||
```
|
||||
|
||||
### Phase 1: Plugin Structure Validation ✅ PASS (63/63 checks)
|
||||
|
||||
**Test 3.1: Directory Structure**
|
||||
```
|
||||
Status: ✅ PASS (6/6 checks)
|
||||
✅ .claude-plugin/ exists
|
||||
✅ commands/ exists
|
||||
✅ agents/ exists
|
||||
✅ skills/ exists
|
||||
✅ skills/label-taxonomy/ exists
|
||||
✅ All required directories present
|
||||
```
|
||||
|
||||
**Test 3.2: Plugin Manifest (plugin.json)**
|
||||
```
|
||||
Status: ✅ PASS (15/15 checks)
|
||||
✅ Valid JSON syntax
|
||||
✅ Has 'name' field
|
||||
✅ Has 'version' field
|
||||
✅ Has 'displayName' field
|
||||
✅ Has 'description' field
|
||||
✅ Has 'author' field
|
||||
✅ Declares 5 commands
|
||||
✅ All command files exist:
|
||||
- commands/sprint-plan.md
|
||||
- commands/sprint-start.md
|
||||
- commands/sprint-status.md
|
||||
- commands/sprint-close.md
|
||||
- commands/labels-sync.md
|
||||
✅ Declares 3 agents
|
||||
✅ All agent files exist:
|
||||
- agents/planner.md
|
||||
- agents/orchestrator.md
|
||||
- agents/executor.md
|
||||
```
|
||||
|
||||
**Test 3.3: MCP Configuration (.mcp.json)**
|
||||
```
|
||||
Status: ✅ PASS (5/5 checks)
|
||||
✅ Valid JSON syntax
|
||||
✅ Declares 2 MCP servers
|
||||
✅ Gitea MCP server configured
|
||||
✅ Wiki.js MCP server configured
|
||||
✅ Uses ${CLAUDE_PLUGIN_ROOT} for path safety
|
||||
```
|
||||
|
||||
**Test 3.4: Command Files**
|
||||
```
|
||||
Status: ✅ PASS (15/15 checks)
|
||||
✅ Found 5 command files
|
||||
✅ All commands have frontmatter with name and description
|
||||
✅ Commands checked:
|
||||
- sprint-plan.md
|
||||
- sprint-start.md
|
||||
- sprint-status.md
|
||||
- sprint-close.md
|
||||
- labels-sync.md
|
||||
```
|
||||
|
||||
**Test 3.5: Agent Files**
|
||||
```
|
||||
Status: ✅ PASS (9/9 checks)
|
||||
✅ Found 3 agent files
|
||||
✅ All expected agents exist
|
||||
✅ All agents have frontmatter
|
||||
✅ All agents define personality:
|
||||
- planner.md (Thoughtful, methodical)
|
||||
- orchestrator.md (Concise, action-oriented)
|
||||
- executor.md (Implementation-focused)
|
||||
```
|
||||
|
||||
**Test 3.6: Skill Files**
|
||||
```
|
||||
Status: ✅ PASS (4/4 checks)
|
||||
✅ skills/label-taxonomy/ directory exists
|
||||
✅ labels-reference.md exists
|
||||
✅ Skill has frontmatter
|
||||
✅ Skill documents:
|
||||
- Organization labels
|
||||
- Repository labels
|
||||
- Suggestion logic
|
||||
```
|
||||
|
||||
**Test 3.7: Documentation**
|
||||
```
|
||||
Status: ✅ PASS (6/6 checks)
|
||||
✅ README.md exists
|
||||
✅ README has all key sections:
|
||||
- Overview
|
||||
- Quick Start
|
||||
- Commands
|
||||
- Configuration
|
||||
- Troubleshooting
|
||||
✅ CONFIGURATION.md exists with step-by-step setup
|
||||
```
|
||||
|
||||
**Test 3.8: Security Practices**
|
||||
```
|
||||
Status: ✅ PASS (3/3 checks)
|
||||
✅ .env in .gitignore (prevents credential commits)
|
||||
✅ No hardcoded secrets in plugin files
|
||||
✅ Uses ${CLAUDE_PLUGIN_ROOT} for path safety in .mcp.json
|
||||
⚠️ 2 warnings: Example tokens in CONFIGURATION.md (false positives - documentation only)
|
||||
```
|
||||
|
||||
### Phase 2: Command/Agent Integration ⚠️ DEFERRED
|
||||
|
||||
**Test 4.1: /labels-sync Command**
|
||||
```
|
||||
Status: ⚠️ DEFERRED (Requires live Gitea API)
|
||||
Manual Test Required:
|
||||
1. Run: /labels-sync
|
||||
2. Expected: Fetches labels from Gitea, updates labels-reference.md
|
||||
3. Verify: skills/label-taxonomy/labels-reference.md updated
|
||||
```
|
||||
|
||||
**Test 4.2: /sprint-status Command**
|
||||
```
|
||||
Status: ⚠️ DEFERRED (Requires live Gitea API)
|
||||
Manual Test Required:
|
||||
1. Run: /sprint-status
|
||||
2. Expected: Shows open/closed issues from Gitea
|
||||
3. Verify: Issue categorization works
|
||||
```
|
||||
|
||||
**Test 4.3: /sprint-plan Command + Planner Agent**
|
||||
```
|
||||
Status: ⚠️ DEFERRED (Requires live Gitea + Wiki.js APIs)
|
||||
Manual Test Required:
|
||||
1. Run: /sprint-plan with test task
|
||||
2. Expected: Planner asks questions, searches lessons, creates issues
|
||||
3. Verify: Issues created in Gitea with labels
|
||||
```
|
||||
|
||||
**Test 4.4: /sprint-start Command + Orchestrator Agent**
|
||||
```
|
||||
Status: ⚠️ DEFERRED (Requires live Gitea + Wiki.js APIs)
|
||||
Manual Test Required:
|
||||
1. Run: /sprint-start
|
||||
2. Expected: Orchestrator reviews issues, identifies next task
|
||||
3. Verify: Lean execution prompt generated
|
||||
```
|
||||
|
||||
**Test 4.5: /sprint-close Command + Lessons Learned**
|
||||
```
|
||||
Status: ⚠️ DEFERRED (Requires live Wiki.js API)
|
||||
Manual Test Required:
|
||||
1. Run: /sprint-close
|
||||
2. Expected: Orchestrator captures lessons, saves to Wiki.js
|
||||
3. Verify: Lesson visible in Wiki.js
|
||||
```
|
||||
|
||||
### Phase 3: Branch Detection ⚠️ DEFERRED
|
||||
|
||||
**Test 5.1: Production Branch Blocking**
|
||||
```
|
||||
Status: ⚠️ DEFERRED (Requires manual execution)
|
||||
Manual Test Required:
|
||||
1. git checkout main
|
||||
2. Run: /sprint-plan
|
||||
3. Expected: Command blocks with production warning
|
||||
4. Verify: No issues created
|
||||
```
|
||||
|
||||
**Test 5.2: Staging Branch Limitation**
|
||||
```
|
||||
Status: ⚠️ DEFERRED (Requires manual execution)
|
||||
Manual Test Required:
|
||||
1. git checkout -b staging
|
||||
2. Run: /sprint-start
|
||||
3. Expected: Warning about limited capabilities
|
||||
4. Verify: Cannot modify code
|
||||
```
|
||||
|
||||
**Test 5.3: Development Branch Full Access**
|
||||
```
|
||||
Status: ⚠️ DEFERRED (Requires manual execution)
|
||||
Manual Test Required:
|
||||
1. git checkout development
|
||||
2. Run: /sprint-plan
|
||||
3. Expected: Full capabilities, no warnings
|
||||
4. Verify: Normal operation
|
||||
```
|
||||
|
||||
## Test Results Summary
|
||||
|
||||
### Automated Tests
|
||||
|
||||
| Category | Tests | Passed | Failed | Deferred |
|
||||
|----------|-------|--------|--------|----------|
|
||||
| Configuration Loading | 2 | 2 | 0 | 0 |
|
||||
| API Connectivity | 2 | 0 | 0 | 2 |
|
||||
| Plugin Structure | 8 | 8 | 0 | 0 |
|
||||
| Detailed Validations | 63 | 63 | 0 | 0 |
|
||||
| **TOTAL** | **75** | **73** | **0** | **2** |
|
||||
|
||||
**Success Rate: 97% (73/75 tests, 2 deferred due to network)**
|
||||
|
||||
### Manual Tests Required
|
||||
|
||||
| Category | Tests | Priority |
|
||||
|----------|-------|----------|
|
||||
| Command Execution | 5 | High |
|
||||
| Agent Behavior | 3 | High |
|
||||
| Branch Detection | 3 | High |
|
||||
| Error Handling | 3 | Medium |
|
||||
| Full Workflow | 1 | High |
|
||||
| **TOTAL** | **15** | - |
|
||||
|
||||
## Issues Found
|
||||
|
||||
### Critical Issues
|
||||
**None** - All structural validations passed
|
||||
|
||||
### High Priority Issues
|
||||
**None** - Plugin structure is valid
|
||||
|
||||
### Medium Priority Issues
|
||||
**None** - Documentation and security practices are good
|
||||
|
||||
### Low Priority Issues / Warnings
|
||||
|
||||
1. **False Positive: Secret Detection in CONFIGURATION.md**
|
||||
- **Severity:** Low (False positive)
|
||||
- **Description:** Documentation includes example token strings
|
||||
- **Impact:** None - these are examples, not real secrets
|
||||
- **Recommendation:** No action needed
|
||||
|
||||
## Recommendations for Manual Testing
|
||||
|
||||
### Test Sequence
|
||||
|
||||
**Phase 1: Basic Connectivity (5 minutes)**
|
||||
1. Run `/labels-sync`
|
||||
- Verifies Gitea API connection
|
||||
- Tests MCP server communication
|
||||
- Updates label taxonomy
|
||||
|
||||
2. Run `/sprint-status`
|
||||
- Verifies issue fetching
|
||||
- Tests read-only operations
|
||||
|
||||
**Phase 2: Agent Testing (15 minutes)**
|
||||
3. Run `/sprint-plan` with simple task
|
||||
- Example: "Add examples to README"
|
||||
- Observe planner personality (asks questions)
|
||||
- Check issues created in Gitea
|
||||
- Verify labels applied correctly
|
||||
|
||||
4. Run `/sprint-start`
|
||||
- Observe orchestrator personality (concise)
|
||||
- Check next task identification
|
||||
- Verify execution prompt generated
|
||||
|
||||
5. Work on simple task (implement it)
|
||||
|
||||
6. Run `/sprint-close`
|
||||
- Capture a test lesson
|
||||
- Verify saved to Wiki.js
|
||||
|
||||
**Phase 3: Branch Detection (5 minutes)**
|
||||
7. Test on main branch (should block)
|
||||
8. Test on development branch (should work)
|
||||
|
||||
**Phase 4: Error Handling (5 minutes)**
|
||||
9. Test with invalid .env (expect clear error)
|
||||
10. Test with no .env (expect clear instructions)
|
||||
|
||||
### Success Criteria
|
||||
|
||||
✅ **Must Pass:**
|
||||
- /labels-sync fetches labels successfully
|
||||
- /sprint-plan creates issues with labels
|
||||
- /sprint-start identifies next task
|
||||
- /sprint-close saves lessons to Wiki.js
|
||||
- Production branch blocks operations
|
||||
- Development branch allows operations
|
||||
|
||||
⚠️ **Should Pass:**
|
||||
- Error messages are clear and actionable
|
||||
- Agent personalities are distinct
|
||||
- Lessons learned search works
|
||||
- Label suggestions are intelligent
|
||||
|
||||
## Known Limitations (Expected)
|
||||
|
||||
1. **No Executor Integration** - Executor agent not yet automatically invoked by orchestrator (Phase 4)
|
||||
2. **No Milestone Support** - Sprint milestones not implemented (Phase 4)
|
||||
3. **No Dependency Tracking** - Issue dependencies not automatically tracked (Phase 4)
|
||||
4. **No Progress Updates** - Orchestrator doesn't automatically update issue comments (Phase 4)
|
||||
5. **Manual Git Operations** - Git operations not automated yet (Phase 4)
|
||||
|
||||
These are expected for v0.1.0 (Phase 2 & 3 complete) and will be addressed in Phase 4.
|
||||
|
||||
## Files Modified/Created
|
||||
|
||||
### Plugin Files (15 new files)
|
||||
```
|
||||
projman/
|
||||
├── .claude-plugin/plugin.json (New)
|
||||
├── .mcp.json (New)
|
||||
├── commands/ (5 new files)
|
||||
│ ├── sprint-plan.md
|
||||
│ ├── sprint-start.md
|
||||
│ ├── sprint-status.md
|
||||
│ ├── sprint-close.md
|
||||
│ └── labels-sync.md
|
||||
├── agents/ (3 new files)
|
||||
│ ├── planner.md
|
||||
│ ├── orchestrator.md
|
||||
│ └── executor.md
|
||||
├── skills/label-taxonomy/ (1 new file)
|
||||
│ └── labels-reference.md
|
||||
├── README.md (New)
|
||||
└── CONFIGURATION.md (New)
|
||||
```
|
||||
|
||||
### Test Infrastructure
|
||||
```
|
||||
.claude-plugins/
|
||||
└── projman-marketplace/
|
||||
└── marketplace.json (New)
|
||||
|
||||
.env (New, not committed)
|
||||
|
||||
docs/
|
||||
├── TEST_01_PROJMAN.md (New)
|
||||
└── TEST_EXECUTION_REPORT.md (This file)
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Immediate: Manual Testing
|
||||
|
||||
1. **Start Local Test Session**
|
||||
```bash
|
||||
# Ensure on development branch
|
||||
git checkout development
|
||||
|
||||
# Verify configuration
|
||||
cat .env
|
||||
|
||||
# Test basic connectivity
|
||||
/labels-sync
|
||||
```
|
||||
|
||||
2. **Run Test Sequence** (Follow recommendations above)
|
||||
|
||||
3. **Document Results** in TEST_01_PROJMAN.md
|
||||
|
||||
### After Manual Testing
|
||||
|
||||
**If Tests Pass:**
|
||||
1. Create GitHub PR/Gitea PR for review
|
||||
2. Move to Phase 4: Lessons Learned Integration
|
||||
3. Plan integration testing with real sprint
|
||||
|
||||
**If Tests Fail:**
|
||||
1. Document exact failures and error messages
|
||||
2. Categorize by severity (Critical/High/Medium/Low)
|
||||
3. Fix critical issues first
|
||||
4. Retest and iterate
|
||||
|
||||
## Conclusion
|
||||
|
||||
✅ **Plugin Structure: PRODUCTION READY**
|
||||
|
||||
The Projman plugin has passed all automated structural validations. The plugin manifest, MCP configuration, commands, agents, skills, and documentation are all correctly structured and follow security best practices.
|
||||
|
||||
**Confidence Level:** High (97% of automated tests passed)
|
||||
|
||||
**Readiness:** Ready for manual functional testing
|
||||
|
||||
**Recommendation:** Proceed with manual testing sequence to validate live API integration and agent behavior.
|
||||
|
||||
---
|
||||
|
||||
**Report Generated:** 2025-11-18
|
||||
**Next Update:** After manual testing completion
|
||||
**Status:** ✅ AUTOMATED VALIDATION COMPLETE - READY FOR MANUAL TESTING
|
||||
101
docs/UPDATING.md
Normal file
101
docs/UPDATING.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# Updating support-claude-mktplace
|
||||
|
||||
This guide covers how to update your local installation when new versions are released.
|
||||
|
||||
## Quick Update
|
||||
|
||||
```bash
|
||||
# 1. Pull latest changes
|
||||
cd /path/to/support-claude-mktplace
|
||||
git pull origin main
|
||||
|
||||
# 2. Run post-update script
|
||||
./scripts/post-update.sh
|
||||
```
|
||||
|
||||
## What the Post-Update Script Does
|
||||
|
||||
1. **Updates Python dependencies** for Gitea and Wiki.js MCP servers
|
||||
2. **Shows recent changelog entries** so you know what changed
|
||||
3. **Validates your configuration** is still compatible
|
||||
|
||||
## Manual Steps After Update
|
||||
|
||||
Some updates may require manual configuration changes:
|
||||
|
||||
### New Environment Variables
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
3. New tools are available immediately after update
|
||||
|
||||
### Breaking Changes
|
||||
|
||||
Breaking changes will be clearly marked in CHANGELOG.md with migration instructions.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Dependencies fail to install
|
||||
|
||||
```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
|
||||
rm -rf .venv
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
deactivate
|
||||
```
|
||||
|
||||
### Configuration no longer works
|
||||
|
||||
1. Check CHANGELOG.md for breaking changes
|
||||
2. Compare your config files with updated `.env.example` (if provided)
|
||||
3. Run `./scripts/setup.sh` to validate configuration
|
||||
|
||||
### MCP server won't start
|
||||
|
||||
1. Check Python version: `python3 --version` (requires 3.10+)
|
||||
2. Verify venv exists: `ls mcp-servers/gitea/.venv`
|
||||
3. Check logs for specific errors
|
||||
|
||||
## Version Pinning
|
||||
|
||||
To stay on a specific version:
|
||||
|
||||
```bash
|
||||
# List available tags
|
||||
git tag
|
||||
|
||||
# Checkout specific version
|
||||
git checkout v1.0.0
|
||||
|
||||
# Run post-update
|
||||
./scripts/post-update.sh
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
- Check `docs/references/` for component documentation
|
||||
- Review CHANGELOG.md for recent changes
|
||||
- Search existing issues in Gitea
|
||||
221
docs/architecture/agent-workflow.spec.md
Normal file
221
docs/architecture/agent-workflow.spec.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# Agent Workflow - Draw.io Specification
|
||||
|
||||
**Target File:** `docs/architecture/agent-workflow.drawio`
|
||||
|
||||
**Purpose:** Shows when Planner, Orchestrator, and Executor agents trigger during sprint lifecycle.
|
||||
|
||||
**Diagram Type:** Swimlane / Sequence Diagram
|
||||
|
||||
---
|
||||
|
||||
## SWIMLANES
|
||||
|
||||
| ID | Label | Color | Position |
|
||||
|----|-------|-------|----------|
|
||||
| user-lane | User | #E3F2FD | 1 (leftmost) |
|
||||
| planner-lane | Planner Agent | #4A90D9 | 2 |
|
||||
| orchestrator-lane | Orchestrator Agent | #7CB342 | 3 |
|
||||
| executor-lane | Executor Agent | #FF9800 | 4 |
|
||||
| gitea-lane | Gitea | #9E9E9E | 5 |
|
||||
| wikijs-lane | Wiki.js | #9E9E9E | 6 (rightmost) |
|
||||
|
||||
---
|
||||
|
||||
## PHASE 1: SPRINT PLANNING
|
||||
|
||||
### Nodes
|
||||
|
||||
| ID | Label | Type | Lane | Sequence |
|
||||
|----|-------|------|------|----------|
|
||||
| p1-start | /sprint-plan | rounded-rect | user-lane | 1 |
|
||||
| p1-activate | Planner Activates | rectangle | planner-lane | 2 |
|
||||
| p1-search-lessons | Search Lessons Learned | rectangle | planner-lane | 3 |
|
||||
| p1-wikijs-query | Query Past Lessons | rectangle | wikijs-lane | 4 |
|
||||
| p1-return-lessons | Return Relevant Lessons | rectangle | planner-lane | 5 |
|
||||
| p1-clarify | Ask Clarifying Questions | diamond | planner-lane | 6 |
|
||||
| p1-user-answers | Provide Answers | rectangle | user-lane | 7 |
|
||||
| p1-create-issues | Create Issues with Labels | rectangle | planner-lane | 8 |
|
||||
| p1-gitea-create | Store Issues | rectangle | gitea-lane | 9 |
|
||||
| p1-plan-complete | Planning Complete | rounded-rect | planner-lane | 10 |
|
||||
|
||||
### Edges
|
||||
|
||||
| From | To | Label | Style |
|
||||
|------|----|-------|-------|
|
||||
| p1-start | p1-activate | invokes | solid |
|
||||
| p1-activate | p1-search-lessons | | solid |
|
||||
| p1-search-lessons | p1-wikijs-query | GraphQL search | solid |
|
||||
| p1-wikijs-query | p1-return-lessons | lessons data | dashed |
|
||||
| p1-return-lessons | p1-clarify | | solid |
|
||||
| p1-clarify | p1-user-answers | questions | solid |
|
||||
| p1-user-answers | p1-clarify | answers | dashed |
|
||||
| p1-clarify | p1-create-issues | | solid |
|
||||
| p1-create-issues | p1-gitea-create | REST API | solid |
|
||||
| p1-gitea-create | p1-plan-complete | confirm | dashed |
|
||||
|
||||
---
|
||||
|
||||
## PHASE 2: SPRINT EXECUTION
|
||||
|
||||
### Nodes
|
||||
|
||||
| ID | Label | Type | Lane | Sequence |
|
||||
|----|-------|------|------|----------|
|
||||
| p2-start | /sprint-start | rounded-rect | user-lane | 11 |
|
||||
| p2-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 12 |
|
||||
| p2-fetch-issues | Fetch Sprint Issues | rectangle | orchestrator-lane | 13 |
|
||||
| p2-gitea-list | List Open Issues | rectangle | gitea-lane | 14 |
|
||||
| p2-sequence | Sequence Work | rectangle | orchestrator-lane | 15 |
|
||||
| p2-dispatch | Dispatch Task | rectangle | orchestrator-lane | 16 |
|
||||
| p2-exec-activate | Executor Activates | rectangle | executor-lane | 17 |
|
||||
| p2-implement | Implement Task | rectangle | executor-lane | 18 |
|
||||
| p2-update-status | Update Issue Status | rectangle | executor-lane | 19 |
|
||||
| p2-gitea-update | Update Issue | rectangle | gitea-lane | 20 |
|
||||
| p2-report | Report Completion | rectangle | executor-lane | 21 |
|
||||
| p2-loop | More Tasks? | diamond | orchestrator-lane | 22 |
|
||||
| p2-exec-complete | Execution Complete | rounded-rect | orchestrator-lane | 23 |
|
||||
|
||||
### Edges
|
||||
|
||||
| From | To | Label | Style |
|
||||
|------|----|-------|-------|
|
||||
| p2-start | p2-orch-activate | invokes | solid |
|
||||
| p2-orch-activate | p2-fetch-issues | | solid |
|
||||
| p2-fetch-issues | p2-gitea-list | REST API | solid |
|
||||
| p2-gitea-list | p2-sequence | issues data | dashed |
|
||||
| p2-sequence | p2-dispatch | | solid |
|
||||
| p2-dispatch | p2-exec-activate | execution prompt | solid |
|
||||
| p2-exec-activate | p2-implement | | solid |
|
||||
| p2-implement | p2-update-status | | solid |
|
||||
| p2-update-status | p2-gitea-update | REST API | solid |
|
||||
| p2-gitea-update | p2-report | confirm | dashed |
|
||||
| p2-report | p2-loop | | solid |
|
||||
| p2-loop | p2-dispatch | yes | solid |
|
||||
| p2-loop | p2-exec-complete | no | solid |
|
||||
|
||||
---
|
||||
|
||||
## PHASE 3: SPRINT CLOSE
|
||||
|
||||
### Nodes
|
||||
|
||||
| ID | Label | Type | Lane | Sequence |
|
||||
|----|-------|------|------|----------|
|
||||
| p3-start | /sprint-close | rounded-rect | user-lane | 24 |
|
||||
| p3-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 25 |
|
||||
| p3-review | Review Sprint | rectangle | orchestrator-lane | 26 |
|
||||
| p3-gitea-status | Get Final Status | rectangle | gitea-lane | 27 |
|
||||
| p3-capture | Capture Lessons Learned | rectangle | orchestrator-lane | 28 |
|
||||
| p3-user-input | Confirm Lessons | diamond | user-lane | 29 |
|
||||
| p3-create-wiki | Create Wiki Pages | rectangle | orchestrator-lane | 30 |
|
||||
| p3-wikijs-create | Store Lessons | rectangle | wikijs-lane | 31 |
|
||||
| p3-close-issues | Close Issues | rectangle | orchestrator-lane | 32 |
|
||||
| p3-gitea-close | Mark Closed | rectangle | gitea-lane | 33 |
|
||||
| p3-complete | Sprint Closed | rounded-rect | orchestrator-lane | 34 |
|
||||
|
||||
### Edges
|
||||
|
||||
| From | To | Label | Style |
|
||||
|------|----|-------|-------|
|
||||
| p3-start | p3-orch-activate | invokes | solid |
|
||||
| p3-orch-activate | p3-review | | solid |
|
||||
| p3-review | p3-gitea-status | REST API | solid |
|
||||
| p3-gitea-status | p3-capture | status data | dashed |
|
||||
| p3-capture | p3-user-input | proposed lessons | solid |
|
||||
| p3-user-input | p3-create-wiki | confirmed | solid |
|
||||
| p3-create-wiki | p3-wikijs-create | GraphQL mutation | solid |
|
||||
| p3-wikijs-create | p3-close-issues | confirm | dashed |
|
||||
| p3-close-issues | p3-gitea-close | REST API | solid |
|
||||
| p3-gitea-close | p3-complete | confirm | dashed |
|
||||
|
||||
---
|
||||
|
||||
## LAYOUT NOTES
|
||||
|
||||
```
|
||||
+--------+------------+---------------+------------+--------+----------+
|
||||
| User | Planner | Orchestrator | Executor | Gitea | Wiki.js |
|
||||
+--------+------------+---------------+------------+--------+----------+
|
||||
| | | | | | |
|
||||
| PHASE 1: SPRINT PLANNING |
|
||||
|---------------------------------------------------------------------+
|
||||
| O | | | | | |
|
||||
| | | | | | | |
|
||||
| +---->| O | | | | |
|
||||
| | | | | | | |
|
||||
| | +----------|---------------|------------|------->| O |
|
||||
| | |<---------|---------------|------------|--------+ | |
|
||||
| | | | | | | |
|
||||
| | O<> | | | | |
|
||||
| O<--->+ | | | | | |
|
||||
| | | | | | | |
|
||||
| | +----------|---------------|----------->| O | |
|
||||
| | O | | | | |
|
||||
| | | | | | |
|
||||
|---------------------------------------------------------------------+
|
||||
| PHASE 2: SPRINT EXECUTION |
|
||||
|---------------------------------------------------------------------+
|
||||
| O | | | | | |
|
||||
| | | | | | | |
|
||||
| +-----|----------->| O | | | |
|
||||
| | | | | | | |
|
||||
| | | +-------------|----------->| O | |
|
||||
| | | |<------------|------------+ | | |
|
||||
| | | | | | | |
|
||||
| | | +------------>| O | | |
|
||||
| | | | | | | |
|
||||
| | | | +--------->| O | |
|
||||
| | | | |<---------+ | | |
|
||||
| | | O<------------+ | | | |
|
||||
| | | | | | | |
|
||||
| | | O (loop) | | | |
|
||||
| | | | | | |
|
||||
|---------------------------------------------------------------------+
|
||||
| PHASE 3: SPRINT CLOSE |
|
||||
|---------------------------------------------------------------------+
|
||||
| O | | | | | |
|
||||
| | | | | | | |
|
||||
| +-----|----------->| O | | | |
|
||||
| | | +-------------|----------->| O | |
|
||||
| | | |<------------|------------+ | | |
|
||||
| | | | | | | |
|
||||
| O<----|-----------<+ | | | | |
|
||||
| +-----|----------->| | | | | |
|
||||
| | | +-------------|------------|------->| O |
|
||||
| | | |<------------|------------|--------+ | |
|
||||
| | | +-------------|----------->| O | |
|
||||
| | | O | | | |
|
||||
+--------+------------+---------------+------------+--------+----------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## COLOR LEGEND
|
||||
|
||||
| Color | Hex | Meaning |
|
||||
|-------|-----|---------|
|
||||
| Light Blue | #E3F2FD | User actions |
|
||||
| Blue | #4A90D9 | Planner Agent |
|
||||
| Green | #7CB342 | Orchestrator Agent |
|
||||
| Orange | #FF9800 | Executor Agent |
|
||||
| Gray | #9E9E9E | External Services |
|
||||
|
||||
---
|
||||
|
||||
## SHAPE LEGEND
|
||||
|
||||
| Shape | Meaning |
|
||||
|-------|---------|
|
||||
| Rounded Rectangle | Start/End points (commands) |
|
||||
| Rectangle | Process/Action |
|
||||
| Diamond | Decision point |
|
||||
| Cylinder | Data store (in component map) |
|
||||
|
||||
---
|
||||
|
||||
## ARROW LEGEND
|
||||
|
||||
| Style | Meaning |
|
||||
|-------|---------|
|
||||
| Solid | Action/Request |
|
||||
| Dashed | Response/Data return |
|
||||
133
docs/architecture/component-map.spec.md
Normal file
133
docs/architecture/component-map.spec.md
Normal file
@@ -0,0 +1,133 @@
|
||||
# Component Map - Draw.io Specification
|
||||
|
||||
**Target File:** `docs/architecture/component-map.drawio`
|
||||
|
||||
**Purpose:** Shows all plugins, MCP servers, hooks and their relationships.
|
||||
|
||||
---
|
||||
|
||||
## NODES
|
||||
|
||||
### Plugins (Blue - #4A90D9)
|
||||
|
||||
| ID | Label | Type | Color | Position |
|
||||
|----|-------|------|-------|----------|
|
||||
| projman | projman | rectangle | #4A90D9 | top-center |
|
||||
| projman-pmo | projman-pmo | rectangle | #4A90D9 | top-right |
|
||||
| project-hygiene | project-hygiene | rectangle | #4A90D9 | top-left |
|
||||
|
||||
### MCP Servers (Green - #7CB342)
|
||||
|
||||
| ID | Label | Type | Color | Position |
|
||||
|----|-------|------|-------|----------|
|
||||
| gitea-mcp | Gitea MCP Server | rectangle | #7CB342 | middle-left |
|
||||
| wikijs-mcp | Wiki.js MCP Server | rectangle | #7CB342 | middle-right |
|
||||
|
||||
### External Systems (Gray - #9E9E9E)
|
||||
|
||||
| ID | Label | Type | Color | Position |
|
||||
|----|-------|------|-------|----------|
|
||||
| gitea-instance | Gitea\ngitea.hotserv.cloud | cylinder | #9E9E9E | bottom-left |
|
||||
| wikijs-instance | Wiki.js\nwikijs.hotserv.cloud | cylinder | #9E9E9E | bottom-right |
|
||||
|
||||
### Configuration (Orange - #FF9800)
|
||||
|
||||
| ID | Label | Type | Color | Position |
|
||||
|----|-------|------|-------|----------|
|
||||
| system-config | System Config\n~/.config/claude/ | rectangle | #FF9800 | far-left |
|
||||
| project-config | Project Config\n.env | rectangle | #FF9800 | far-right |
|
||||
|
||||
---
|
||||
|
||||
## EDGES
|
||||
|
||||
### Plugin to MCP Server Connections
|
||||
|
||||
| From | To | Label | Style | Arrow |
|
||||
|------|----|-------|-------|-------|
|
||||
| projman | gitea-mcp | uses | solid | forward |
|
||||
| projman | wikijs-mcp | uses | solid | forward |
|
||||
| projman-pmo | gitea-mcp | uses (company-wide) | solid | forward |
|
||||
| projman-pmo | wikijs-mcp | uses (company-wide) | solid | forward |
|
||||
|
||||
### Plugin Dependencies
|
||||
|
||||
| From | To | Label | Style | Arrow |
|
||||
|------|----|-------|-------|-------|
|
||||
| projman-pmo | projman | depends on | dashed | forward |
|
||||
|
||||
### MCP Server to External System Connections
|
||||
|
||||
| From | To | Label | Style | Arrow |
|
||||
|------|----|-------|-------|-------|
|
||||
| gitea-mcp | gitea-instance | REST API | solid | forward |
|
||||
| wikijs-mcp | wikijs-instance | GraphQL | solid | forward |
|
||||
|
||||
### Configuration Connections
|
||||
|
||||
| From | To | Label | Style | Arrow |
|
||||
|------|----|-------|-------|-------|
|
||||
| system-config | gitea-mcp | credentials | dashed | forward |
|
||||
| system-config | wikijs-mcp | credentials | dashed | forward |
|
||||
| project-config | gitea-mcp | repo context | dashed | forward |
|
||||
| project-config | wikijs-mcp | project path | dashed | forward |
|
||||
|
||||
---
|
||||
|
||||
## GROUPS
|
||||
|
||||
| ID | Label | Contains | Style |
|
||||
|----|-------|----------|-------|
|
||||
| plugins-group | Plugins | projman, projman-pmo, project-hygiene | light blue border |
|
||||
| mcp-group | Shared MCP Servers | gitea-mcp, wikijs-mcp | light green border |
|
||||
| external-group | External Services | gitea-instance, wikijs-instance | light gray border |
|
||||
| config-group | Configuration | system-config, project-config | light orange border |
|
||||
|
||||
---
|
||||
|
||||
## LAYOUT NOTES
|
||||
|
||||
```
|
||||
+------------------------------------------------------------------+
|
||||
| PLUGINS GROUP |
|
||||
| +----------------+ +----------------+ +-------------------+ |
|
||||
| | project- | | projman | | projman-pmo | |
|
||||
| | hygiene | | | | | |
|
||||
| +----------------+ +-------+--------+ +--------+----------+ |
|
||||
| | | |
|
||||
+------------------------------------------------------------------+
|
||||
| |
|
||||
v v
|
||||
+------------------------------------------------------------------+
|
||||
| MCP SERVERS GROUP |
|
||||
| +-------------------+ +-------------------+ |
|
||||
| | Gitea MCP Server | | Wiki.js MCP Server| |
|
||||
| +--------+----------+ +---------+---------+ |
|
||||
+------------------------------------------------------------------+
|
||||
| |
|
||||
v v
|
||||
+------------------------------------------------------------------+
|
||||
| EXTERNAL SERVICES GROUP |
|
||||
| +-------------------+ +-------------------+ |
|
||||
| | Gitea | | Wiki.js | |
|
||||
| | gitea.hotserv.cloud | wikijs.hotserv.cloud |
|
||||
| +-------------------+ +-------------------+ |
|
||||
+------------------------------------------------------------------+
|
||||
|
||||
CONFIG GROUP (left side): CONFIG GROUP (right side):
|
||||
+-------------------+ +-------------------+
|
||||
| System Config | | Project Config |
|
||||
| ~/.config/claude/ | | .env |
|
||||
+-------------------+ +-------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## COLOR LEGEND
|
||||
|
||||
| Color | Hex | Meaning |
|
||||
|-------|-----|---------|
|
||||
| Blue | #4A90D9 | Plugins |
|
||||
| Green | #7CB342 | MCP Servers |
|
||||
| Gray | #9E9E9E | External Systems |
|
||||
| Orange | #FF9800 | Configuration |
|
||||
Reference in New Issue
Block a user