docs: enhanced reference documentation with implementation details

Added comprehensive implementation guidance to reference docs: - MCP-GITEA.md: Token generation steps, Python requirements, server implementation, async wrappers, branch detection - MCP-WIKIJS.md: Token generation steps, Wiki.js structure setup script, initialization guide - PLUGIN-PMO.md & PLUGIN-PROJMAN.md: Updated plugin manifests and configuration details - PROJECT-SUMMARY.md: Consolidated project status and architecture decisions These updates prepare the reference materials for Phase 1 implementation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-06 14:53:46 -05:00
parent 588604351b
commit 4e25a6f9f5
5 changed files with 1293 additions and 42 deletions
--- a/docs/references/MCP-GITEA.md
+++ b/docs/references/MCP-GITEA.md
@@ -68,6 +68,21 @@ GITEA_API_TOKEN=your_gitea_token
 GITEA_OWNER=hyperhivelabs
 ```

+**Generating Gitea API Token:**
+
+1. Log into Gitea: https://gitea.hyperhivelabs.com
+2. Navigate to: **Settings** → **Applications** → **Manage Access Tokens**
+3. Click **Generate New Token**
+4. Token configuration:
+   - **Token Name:** `claude-code-mcp`
+   - **Required Permissions:**
+     - ✅ `repo` (all) - Read/write access to repositories, issues, labels
+     - ✅ `read:org` - Read organization information and labels
+     - ✅ `read:user` - Read user information
+5. Click **Generate Token**
+6. **Important:** Copy the token immediately (shown only once)
+7. Add to configuration file (see setup below)
+
 **Setup:**
 ```bash
 # Create config directory
@@ -76,12 +91,15 @@ mkdir -p ~/.config/claude
 # Create gitea.env
 cat > ~/.config/claude/gitea.env << EOF
 GITEA_API_URL=https://gitea.hyperhivelabs.com/api/v1
-GITEA_API_TOKEN=your_token
+GITEA_API_TOKEN=your_token_here
 GITEA_OWNER=hyperhivelabs
 EOF

-# Secure the file
+# Secure the file (important!)
 chmod 600 ~/.config/claude/gitea.env
+
+# Verify setup
+cat ~/.config/claude/gitea.env
 ```

 ### Project-Level Configuration
@@ -210,7 +228,7 @@ mcp-servers/gitea/
 **File:** `mcp-servers/gitea/requirements.txt`

 ```txt
-anthropic-sdk>=0.18.0    # MCP SDK
+mcp>=0.9.0               # MCP SDK from Anthropic
 python-dotenv>=1.0.0     # Environment variable loading
 requests>=2.31.0         # HTTP client for Gitea API
 pydantic>=2.5.0          # Data validation
@@ -218,6 +236,8 @@ pytest>=7.4.3            # Testing framework
 pytest-asyncio>=0.23.0   # Async testing support
 ```

+**Python Version:** 3.10+ required
+
 **Installation:**
 ```bash
 cd mcp-servers/gitea
@@ -433,22 +453,439 @@ class GiteaClient:

 ---

+## MCP Server Implementation
+
+### Overview
+
+The MCP (Model Context Protocol) server exposes Gitea tools to Claude Code via JSON-RPC 2.0 over stdio.
+
+**Communication Flow:**
+```
+Claude Code <--> stdio <--> MCP Server <--> Gitea API
+```
+
+### Server Entry Point
+
+**File:** `mcp-servers/gitea/mcp_server/server.py`
+
+```python
+"""
+MCP Server entry point for Gitea integration.
+"""
+import asyncio
+import logging
+import json
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+from .config import GiteaConfig
+from .gitea_client import GiteaClient
+from .tools.issues import IssueTools
+from .tools.labels import LabelTools
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class GiteaMCPServer:
+    """MCP Server for Gitea integration"""
+
+    def __init__(self):
+        self.server = Server("gitea-mcp")
+        self.config = None
+        self.client = None
+        self.issue_tools = None
+        self.label_tools = None
+
+    async def initialize(self):
+        """Initialize server and load configuration"""
+        try:
+            config_loader = GiteaConfig()
+            self.config = config_loader.load()
+
+            self.client = GiteaClient()
+            self.issue_tools = IssueTools(self.client)
+            self.label_tools = LabelTools(self.client)
+
+            logger.info(f"Gitea MCP Server initialized in {self.config['mode']} mode")
+        except Exception as e:
+            logger.error(f"Failed to initialize: {e}")
+            raise
+
+    def setup_tools(self):
+        """Register all available tools with the MCP server"""
+
+        @self.server.list_tools()
+        async def list_tools() -> list[Tool]:
+            """Return list of available tools"""
+            return [
+                Tool(
+                    name="list_issues",
+                    description="List issues from Gitea repository",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "state": {
+                                "type": "string",
+                                "enum": ["open", "closed", "all"],
+                                "default": "open"
+                            },
+                            "labels": {
+                                "type": "array",
+                                "items": {"type": "string"}
+                            },
+                            "repo": {"type": "string"}
+                        }
+                    }
+                ),
+                Tool(
+                    name="get_issue",
+                    description="Get specific issue details",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "issue_number": {"type": "integer"},
+                            "repo": {"type": "string"}
+                        },
+                        "required": ["issue_number"]
+                    }
+                ),
+                Tool(
+                    name="create_issue",
+                    description="Create a new issue in Gitea",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "title": {"type": "string"},
+                            "body": {"type": "string"},
+                            "labels": {
+                                "type": "array",
+                                "items": {"type": "string"}
+                            },
+                            "repo": {"type": "string"}
+                        },
+                        "required": ["title", "body"]
+                    }
+                ),
+                Tool(
+                    name="update_issue",
+                    description="Update existing issue",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "issue_number": {"type": "integer"},
+                            "title": {"type": "string"},
+                            "body": {"type": "string"},
+                            "state": {
+                                "type": "string",
+                                "enum": ["open", "closed"]
+                            },
+                            "labels": {
+                                "type": "array",
+                                "items": {"type": "string"}
+                            },
+                            "repo": {"type": "string"}
+                        },
+                        "required": ["issue_number"]
+                    }
+                ),
+                Tool(
+                    name="add_comment",
+                    description="Add comment to issue",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "issue_number": {"type": "integer"},
+                            "comment": {"type": "string"},
+                            "repo": {"type": "string"}
+                        },
+                        "required": ["issue_number", "comment"]
+                    }
+                ),
+                Tool(
+                    name="get_labels",
+                    description="Get all available labels (org + repo)",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "repo": {"type": "string"}
+                        }
+                    }
+                ),
+                Tool(
+                    name="suggest_labels",
+                    description="Analyze context and suggest appropriate labels",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "context": {"type": "string"}
+                        },
+                        "required": ["context"]
+                    }
+                ),
+                Tool(
+                    name="aggregate_issues",
+                    description="Fetch issues across all repositories (PMO mode)",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "state": {
+                                "type": "string",
+                                "enum": ["open", "closed", "all"],
+                                "default": "open"
+                            },
+                            "labels": {
+                                "type": "array",
+                                "items": {"type": "string"}
+                            }
+                        }
+                    }
+                )
+            ]
+
+        @self.server.call_tool()
+        async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+            """Handle tool invocation"""
+            try:
+                # Route to appropriate tool handler
+                if name == "list_issues":
+                    result = await self.issue_tools.list_issues(**arguments)
+                elif name == "get_issue":
+                    result = await self.issue_tools.get_issue(**arguments)
+                elif name == "create_issue":
+                    result = await self.issue_tools.create_issue(**arguments)
+                elif name == "update_issue":
+                    result = await self.issue_tools.update_issue(**arguments)
+                elif name == "add_comment":
+                    result = await self.issue_tools.add_comment(**arguments)
+                elif name == "get_labels":
+                    result = await self.label_tools.get_labels(**arguments)
+                elif name == "suggest_labels":
+                    result = await self.label_tools.suggest_labels(**arguments)
+                elif name == "aggregate_issues":
+                    result = await self.issue_tools.aggregate_issues(**arguments)
+                else:
+                    raise ValueError(f"Unknown tool: {name}")
+
+                return [TextContent(
+                    type="text",
+                    text=json.dumps(result, indent=2)
+                )]
+
+            except Exception as e:
+                logger.error(f"Tool {name} failed: {e}")
+                return [TextContent(
+                    type="text",
+                    text=f"Error: {str(e)}"
+                )]
+
+    async def run(self):
+        """Run the MCP server"""
+        await self.initialize()
+        self.setup_tools()
+
+        async with stdio_server() as (read_stream, write_stream):
+            await self.server.run(
+                read_stream,
+                write_stream,
+                self.server.create_initialization_options()
+            )
+
+
+async def main():
+    """Main entry point"""
+    server = GiteaMCPServer()
+    await server.run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Tool Implementation with Async Wrappers
+
+Since the Gitea client uses `requests` (synchronous), but MCP tools must be async:
+
+```python
+# mcp-servers/gitea/mcp_server/tools/issues.py
+import asyncio
+
+class IssueTools:
+    def __init__(self, gitea_client):
+        self.gitea = gitea_client
+
+    async def list_issues(self, state='open', labels=None, repo=None):
+        """
+        List issues from repository.
+
+        Wraps sync Gitea client method in executor for async compatibility.
+        """
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None,
+            self.gitea.list_issues,
+            state,
+            labels,
+            repo
+        )
+
+    async def create_issue(self, title, body, labels=None, repo=None):
+        """Create new issue"""
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None,
+            self.gitea.create_issue,
+            title,
+            body,
+            labels,
+            repo
+        )
+
+    # Other methods follow same pattern
+```
+
+### Branch Detection in MCP Tools
+
+Implement branch-aware security at the MCP level:
+
+```python
+# mcp-servers/gitea/mcp_server/tools/issues.py
+import subprocess
+
+class IssueTools:
+    def _get_current_branch(self) -> str:
+        """Get current git branch"""
+        try:
+            result = subprocess.run(
+                ['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
+                capture_output=True,
+                text=True,
+                check=True
+            )
+            return result.stdout.strip()
+        except subprocess.CalledProcessError:
+            return "unknown"
+
+    def _check_branch_permissions(self, operation: str) -> bool:
+        """Check if operation is allowed on current branch"""
+        branch = self._get_current_branch()
+
+        # Production branches (read-only except incidents)
+        if branch in ['main', 'master'] or branch.startswith('prod/'):
+            return operation in ['list_issues', 'get_issue', 'get_labels']
+
+        # Staging branches (read-only for code)
+        if branch == 'staging' or branch.startswith('stage/'):
+            return operation in ['list_issues', 'get_issue', 'get_labels', 'create_issue']
+
+        # Development branches (full access)
+        if branch in ['development', 'develop'] or branch.startswith(('feat/', 'feature/', 'dev/')):
+            return True
+
+        # Unknown branch - be restrictive
+        return False
+
+    async def create_issue(self, title, body, labels=None, repo=None):
+        """Create issue with branch check"""
+        if not self._check_branch_permissions('create_issue'):
+            branch = self._get_current_branch()
+            raise PermissionError(
+                f"Cannot create issues on branch '{branch}'. "
+                f"Switch to a development branch to create issues."
+            )
+
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None,
+            self.gitea.create_issue,
+            title,
+            body,
+            labels,
+            repo
+        )
+```
+
+### Testing the MCP Server
+
+**Manual testing:**
+```bash
+cd mcp-servers/gitea
+source .venv/bin/activate
+python -m mcp_server.server
+```
+
+**Unit tests with mocks:**
+```python
+# tests/test_server.py
+import pytest
+from unittest.mock import Mock, patch
+
+@pytest.mark.asyncio
+async def test_server_initialization():
+    """Test server initializes correctly"""
+    from mcp_server.server import GiteaMCPServer
+
+    with patch('mcp_server.server.GiteaClient'):
+        server = GiteaMCPServer()
+        await server.initialize()
+
+        assert server.client is not None
+        assert server.config is not None
+```
+
+**Integration tests with real API:**
+```python
+# tests/test_integration.py
+import pytest
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_list_issues_real_api():
+    """Test against real Gitea instance"""
+    from mcp_server.server import GiteaMCPServer
+
+    server = GiteaMCPServer()
+    await server.initialize()
+
+    result = await server.issue_tools.list_issues(state='open')
+    assert isinstance(result, list)
+```
+
+**Run tests:**
+```bash
+# Unit tests only (with mocks)
+pytest tests/ -m "not integration"
+
+# Integration tests (requires Gitea access)
+pytest tests/ -m integration
+
+# All tests
+pytest tests/
+```
+
+---
+
 ## Label Taxonomy System

-### 43-Label System
+### Dynamic Label System

-**Organization Labels (27):**
+The label taxonomy is **fetched dynamically from Gitea** at runtime. The current system has 44 labels:
+
+**Organization Labels (28):**
 - Agent/2
 - Complexity/3
 - Efforts/5
 - Priority/4
 - Risk/3
 - Source/4
- Type/6 (includes Type/Refactor)
+- Type/6 (includes Type/Bug, Type/Feature, Type/Refactor, Type/Documentation, Type/Test, Type/Chore)

 **Repository Labels (16):**
- Component/9
- Tech/7
+- Component/9 (Backend, Frontend, API, Database, Auth, Deploy, Testing, Docs, Infra)
+- Tech/7 (Python, JavaScript, Docker, PostgreSQL, Redis, Vue, FastAPI)
+
+**Note:** Label count and composition may change. The `/labels-sync` command fetches the latest labels from Gitea and updates suggestion logic accordingly.

 ### Label Suggestion Logic

--- a/docs/references/MCP-WIKIJS.md
+++ b/docs/references/MCP-WIKIJS.md
@@ -144,6 +144,25 @@ WIKIJS_API_TOKEN=your_wikijs_token
 WIKIJS_BASE_PATH=/hyper-hive-labs
 ```

+**Generating Wiki.js API Token:**
+
+1. Log into Wiki.js: https://wiki.hyperhivelabs.com
+2. Navigate to: **User Menu (top-right)** → **Administration**
+3. In the sidebar, go to: **API Access**
+4. Click **Create New Token**
+5. Token configuration:
+   - **Name:** `claude-code-mcp`
+   - **Expiration:** Never (or set appropriate expiration)
+   - **Required Permissions:**
+     - ✅ Read pages
+     - ✅ Create pages
+     - ✅ Update pages
+     - ✅ Manage tags
+     - ✅ Search
+6. Click **Generate**
+7. **Important:** Copy the token immediately (shown only once)
+8. Add to configuration file (see setup below)
+
 **Setup:**
 ```bash
 # Create config directory
@@ -152,12 +171,15 @@ mkdir -p ~/.config/claude
 # Create wikijs.env
 cat > ~/.config/claude/wikijs.env << EOF
 WIKIJS_API_URL=https://wiki.hyperhivelabs.com/graphql
-WIKIJS_API_TOKEN=your_token
+WIKIJS_API_TOKEN=your_token_here
 WIKIJS_BASE_PATH=/hyper-hive-labs
 EOF

-# Secure the file
+# Secure the file (important!)
 chmod 600 ~/.config/claude/wikijs.env
+
+# Verify setup
+cat ~/.config/claude/wikijs.env
 ```

 ### Project-Level Configuration
@@ -294,7 +316,7 @@ mcp-servers/wikijs/
 **File:** `mcp-servers/wikijs/requirements.txt`

 ```txt
-anthropic-sdk>=0.18.0    # MCP SDK
+mcp>=0.9.0               # MCP SDK from Anthropic
 python-dotenv>=1.0.0     # Environment variable loading
 gql>=3.4.0               # GraphQL client for Wiki.js
 aiohttp>=3.9.0           # Async HTTP
@@ -303,6 +325,8 @@ pytest>=7.4.3            # Testing framework
 pytest-asyncio>=0.23.0   # Async testing support
 ```

+**Python Version:** 3.10+ required
+
 **Installation:**
 ```bash
 cd mcp-servers/wikijs
@@ -1092,54 +1116,242 @@ pytest tests/test_config.py::test_project_config_path_composition

 ### Initial Structure Creation

+**Status:** Base structure `/hyper-hive-labs` **does not exist** and needs to be created during Phase 1.1b.
+
+**Setup Script:** Run this script during Phase 1.1b to create the base structure:
+
+**File:** `mcp-servers/wikijs/setup_wiki_structure.py`
+
 ```python
-# setup_wiki_structure.py
+#!/usr/bin/env python3
+"""
+One-time setup script to create base Wiki.js structure.
+Run during Phase 1.1b implementation.
+"""
 import asyncio
+import sys
 from mcp_server.wikijs_client import WikiJSClient

-async def initialize_wiki_structure():
-    """One-time setup script to create base Wiki.js structure"""
-    client = WikiJSClient()

-    # Base structure
+async def initialize_wiki_structure():
+    """Create base Wiki.js structure for Hyper Hive Labs"""
+
+    print("Initializing Wiki.js base structure...")
+    print("=" * 60)
+
+    try:
+        client = WikiJSClient()
+        print(f"✅ Connected to Wiki.js at {client.api_url}")
+        print(f"   Base path: {client.base_path}")
+        print()
+
+    except Exception as e:
+        print(f"❌ Failed to connect to Wiki.js: {e}")
+        print("   Check your ~/.config/claude/wikijs.env configuration")
+        sys.exit(1)
+
+    # Base structure to create
    base_pages = [
        {
-            'path': '/hyper-hive-labs',
+            'path': 'hyper-hive-labs',
            'title': 'Hyper Hive Labs',
-            'content': '# Hyper Hive Labs Documentation\n\nCompany-wide knowledge base.',
-            'tags': ['company']
+            'content': '''# Hyper Hive Labs Documentation
+
+Welcome to the Hyper Hive Labs knowledge base.
+
+## Organization
+
+- **[Projects](hyper-hive-labs/projects)** - Project-specific documentation and lessons learned
+- **[Company](hyper-hive-labs/company)** - Company-wide processes, standards, and tools
+- **[Shared](hyper-hive-labs/shared)** - Cross-project architecture patterns and best practices
+
+## Purpose
+
+This knowledge base captures:
+- Lessons learned from sprints
+- Architecture patterns and decisions
+- Company processes and standards
+- Best practices and technical guides
+
+All content is searchable and tagged for easy discovery across projects.
+''',
+            'tags': ['company', 'index'],
+            'description': 'Hyper Hive Labs company knowledge base'
        },
        {
-            'path': '/hyper-hive-labs/projects',
+            'path': 'hyper-hive-labs/projects',
            'title': 'Projects',
-            'content': '# Project Documentation\n\nProject-specific documentation and lessons learned.',
-            'tags': ['projects']
+            'content': '''# Project Documentation
+
+Project-specific documentation and lessons learned.
+
+## Active Projects
+
+- **[CuisineFlow](hyper-hive-labs/projects/cuisineflow)** - Main product
+- **[CuisineFlow-Site](hyper-hive-labs/projects/cuisineflow-site)** - Demo and customer gateway
+- **[Intuit-Engine](hyper-hive-labs/projects/intuit-engine)** - API aggregator service
+- **[HHL-Site](hyper-hive-labs/projects/hhl-site)** - Company website
+
+Each project maintains:
+- Lessons learned from sprints
+- Project-specific documentation
+- Architecture decisions
+''',
+            'tags': ['projects', 'index'],
+            'description': 'Index of all project documentation'
        },
        {
-            'path': '/hyper-hive-labs/company',
+            'path': 'hyper-hive-labs/company',
            'title': 'Company',
-            'content': '# Company Documentation\n\nProcesses, standards, and tools.',
-            'tags': ['company', 'processes']
+            'content': '''# Company Documentation
+
+Company-wide processes, standards, and tools.
+
+## Sections
+
+- **[Processes](hyper-hive-labs/company/processes)** - Development workflows, onboarding, deployment
+- **[Standards](hyper-hive-labs/company/standards)** - Code style, API design, security practices
+- **[Tools](hyper-hive-labs/company/tools)** - Gitea, Wiki.js, Claude Code plugin guides
+
+These standards apply to all projects and team members.
+''',
+            'tags': ['company', 'processes', 'index'],
+            'description': 'Company processes and standards'
        },
        {
-            'path': '/hyper-hive-labs/shared',
+            'path': 'hyper-hive-labs/shared',
            'title': 'Shared Resources',
-            'content': '# Shared Resources\n\nArchitecture patterns, best practices, tech stack.',
-            'tags': ['shared', 'resources']
+            'content': '''# Shared Resources
+
+Cross-project architecture patterns, best practices, and technical knowledge.
+
+## Sections
+
+- **[Architecture Patterns](hyper-hive-labs/shared/architecture-patterns)** - Microservices, service extraction, API design
+- **[Best Practices](hyper-hive-labs/shared/best-practices)** - Error handling, logging, testing strategies
+- **[Tech Stack](hyper-hive-labs/shared/tech-stack)** - Python ecosystem, Docker, CI/CD pipelines
+
+These patterns are distilled from lessons learned across all projects.
+''',
+            'tags': ['shared', 'resources', 'index'],
+            'description': 'Cross-project architecture patterns and best practices'
+        },
+        # Project placeholders
+        {
+            'path': 'hyper-hive-labs/projects/cuisineflow',
+            'title': 'CuisineFlow',
+            'content': '''# CuisineFlow
+
+Main product - recipe management and meal planning platform.
+
+## Documentation
+
+- **[Lessons Learned](hyper-hive-labs/projects/cuisineflow/lessons-learned)** - Sprint retrospectives and insights
+- **[Architecture](hyper-hive-labs/projects/cuisineflow/documentation/architecture)** - System architecture
+- **[API](hyper-hive-labs/projects/cuisineflow/documentation/api)** - API documentation
+
+Sprint lessons will be automatically captured here by the projman plugin.
+''',
+            'tags': ['project', 'cuisineflow'],
+            'description': 'CuisineFlow project documentation'
+        },
+        {
+            'path': 'hyper-hive-labs/projects/cuisineflow/lessons-learned',
+            'title': 'CuisineFlow - Lessons Learned',
+            'content': '''# CuisineFlow - Lessons Learned
+
+Sprint retrospectives and insights from CuisineFlow development.
+
+## Organization
+
+- **[Sprints](hyper-hive-labs/projects/cuisineflow/lessons-learned/sprints)** - Sprint-specific lessons
+- **[Patterns](hyper-hive-labs/projects/cuisineflow/lessons-learned/patterns)** - Recurring patterns and solutions
+- **[INDEX](hyper-hive-labs/projects/cuisineflow/lessons-learned/INDEX)** - Complete index with tags
+
+Lessons are automatically captured during sprint close via `/sprint-close` command.
+''',
+            'tags': ['lessons-learned', 'cuisineflow'],
+            'description': 'CuisineFlow lessons learned index'
        }
    ]

+    # Create pages
+    created_count = 0
+    failed_count = 0
+
    for page_data in base_pages:
        try:
+            print(f"Creating: /{page_data['path']}")
            result = await client.create_page(**page_data)
-            print(f"Created: {page_data['path']}")
+
+            if result.get('responseResult', {}).get('succeeded'):
+                print(f"   ✅ Created successfully")
+                created_count += 1
+            else:
+                error_msg = result.get('responseResult', {}).get('message', 'Unknown error')
+                print(f"   ⚠️  Warning: {error_msg}")
+                failed_count += 1
+
        except Exception as e:
-            print(f"Error creating {page_data['path']}: {e}")
+            print(f"   ❌ Error: {e}")
+            failed_count += 1
+
+        print()
+
+    # Summary
+    print("=" * 60)
+    print(f"Setup complete!")
+    print(f"   Created: {created_count} pages")
+    if failed_count > 0:
+        print(f"   Failed: {failed_count} pages")
+        print(f"\n⚠️  Some pages failed. Check errors above.")
+        sys.exit(1)
+    else:
+        print(f"\n✅ All pages created successfully!")
+        print(f"\nView at: https://wiki.hyperhivelabs.com/hyper-hive-labs")
+

 if __name__ == '__main__':
    asyncio.run(initialize_wiki_structure())
 ```

+**Running the setup:**
+```bash
+cd mcp-servers/wikijs
+source .venv/bin/activate
+python setup_wiki_structure.py
+```
+
+**Expected output:**
+```
+Initializing Wiki.js base structure...
+============================================================
+✅ Connected to Wiki.js at https://wiki.hyperhivelabs.com/graphql
+   Base path: /hyper-hive-labs
+
+Creating: /hyper-hive-labs
+   ✅ Created successfully
+
+Creating: /hyper-hive-labs/projects
+   ✅ Created successfully
+
+...
+
+============================================================
+Setup complete!
+   Created: 6 pages
+
+✅ All pages created successfully!
+
+View at: https://wiki.hyperhivelabs.com/hyper-hive-labs
+```
+
+**Post-Setup:**
+After running the script:
+1. Visit https://wiki.hyperhivelabs.com/hyper-hive-labs to verify structure
+2. Add additional project directories as needed
+3. The structure is now ready for projman plugin to use
+
 ---

 ## Migration from Git-based Wiki
--- a/docs/references/PLUGIN-PMO.md
+++ b/docs/references/PLUGIN-PMO.md
@@ -38,6 +38,128 @@ projman-pmo/

 ---

+## Plugin Manifest
+
+**File:** `projman-pmo/.claude-plugin/plugin.json`
+
+```json
+{
+  "name": "projman-pmo",
+  "version": "0.1.0",
+  "displayName": "Projman PMO - Multi-Project Coordination",
+  "description": "PMO coordination with cross-project visibility, dependency tracking, and resource management",
+  "author": "Hyper Hive Labs",
+  "homepage": "https://gitea.hyperhivelabs.com/hyperhivelabs/claude-plugins/projman-pmo",
+  "repository": {
+    "type": "git",
+    "url": "https://gitea.hyperhivelabs.com/hyperhivelabs/claude-plugins.git"
+  },
+  "license": "MIT",
+  "keywords": [
+    "pmo",
+    "multi-project",
+    "coordination",
+    "dependencies",
+    "resource-management"
+  ],
+  "minimumClaudeVersion": "1.0.0",
+  "main": "commands/",
+  "dependencies": {
+    "projman": ">=0.1.0"
+  },
+  "contributes": {
+    "commands": [
+      {
+        "name": "pmo-status",
+        "title": "PMO Status",
+        "description": "Multi-project status overview",
+        "file": "commands/pmo-status.md"
+      },
+      {
+        "name": "pmo-priorities",
+        "title": "PMO Priorities",
+        "description": "Cross-project priority analysis",
+        "file": "commands/pmo-priorities.md"
+      },
+      {
+        "name": "pmo-dependencies",
+        "title": "PMO Dependencies",
+        "description": "Project dependency visualization",
+        "file": "commands/pmo-dependencies.md"
+      },
+      {
+        "name": "pmo-conflicts",
+        "title": "PMO Resource Conflicts",
+        "description": "Resource conflict detection and resolution",
+        "file": "commands/pmo-conflicts.md"
+      },
+      {
+        "name": "pmo-schedule",
+        "title": "PMO Schedule",
+        "description": "Multi-project deployment scheduling",
+        "file": "commands/pmo-schedule.md"
+      }
+    ],
+    "agents": [
+      {
+        "name": "pmo-coordinator",
+        "title": "PMO Coordinator",
+        "description": "Strategic multi-project coordination and dependency management",
+        "file": "agents/pmo-coordinator.md"
+      }
+    ]
+  },
+  "configuration": {
+    "required": [
+      "GITEA_API_URL",
+      "GITEA_API_TOKEN",
+      "GITEA_OWNER",
+      "WIKIJS_API_URL",
+      "WIKIJS_API_TOKEN",
+      "WIKIJS_BASE_PATH"
+    ],
+    "properties": {
+      "GITEA_API_URL": {
+        "type": "string",
+        "description": "Gitea API base URL (e.g., https://gitea.example.com/api/v1)"
+      },
+      "GITEA_API_TOKEN": {
+        "type": "string",
+        "description": "Gitea API token with organization-level access",
+        "secret": true
+      },
+      "GITEA_OWNER": {
+        "type": "string",
+        "description": "Gitea organization name"
+      },
+      "WIKIJS_API_URL": {
+        "type": "string",
+        "description": "Wiki.js GraphQL API URL (e.g., https://wiki.example.com/graphql)"
+      },
+      "WIKIJS_API_TOKEN": {
+        "type": "string",
+        "description": "Wiki.js API token with company-wide read access",
+        "secret": true
+      },
+      "WIKIJS_BASE_PATH": {
+        "type": "string",
+        "description": "Base path in Wiki.js (e.g., /company-name)"
+      }
+    },
+    "notes": {
+      "company_mode": "PMO plugin operates in company-wide mode. Do NOT set GITEA_REPO or WIKIJS_PROJECT environment variables."
+    }
+  }
+}
+```
+
+**Key Differences from projman:**
+- `dependencies`: Declares dependency on projman plugin
+- No `GITEA_REPO` or `WIKIJS_PROJECT` in configuration (company-wide mode)
+- Focused on coordination, not individual project management
+
+---
+
 ## Configuration

 ### Plugin .mcp.json
--- a/docs/references/PLUGIN-PROJMAN.md
+++ b/docs/references/PLUGIN-PROJMAN.md
@@ -37,13 +37,440 @@ projman/
 │   └── executor.md               # Implementation guidance agent
 ├── skills/
 │   └── label-taxonomy/
-│       └── labels-reference.md   # 43-label system reference
+│       └── labels-reference.md   # Dynamic label reference
 ├── README.md                      # Installation and usage guide
 └── CONFIGURATION.md               # Configuration setup guide
 ```

 ---

+## Plugin Manifest
+
+**File:** `projman/.claude-plugin/plugin.json`
+
+```json
+{
+  "name": "projman",
+  "version": "0.1.0",
+  "displayName": "Projman - Single-Repository Project Management",
+  "description": "Sprint planning and project management with Gitea and Wiki.js integration",
+  "author": "Hyper Hive Labs",
+  "homepage": "https://gitea.hyperhivelabs.com/hyperhivelabs/claude-plugins/projman",
+  "repository": {
+    "type": "git",
+    "url": "https://gitea.hyperhivelabs.com/hyperhivelabs/claude-plugins.git"
+  },
+  "license": "MIT",
+  "keywords": [
+    "project-management",
+    "sprint-planning",
+    "gitea",
+    "wikijs",
+    "agile"
+  ],
+  "minimumClaudeVersion": "1.0.0",
+  "main": "commands/",
+  "contributes": {
+    "commands": [
+      {
+        "name": "sprint-plan",
+        "title": "Plan Sprint",
+        "description": "Start sprint planning with AI guidance",
+        "file": "commands/sprint-plan.md"
+      },
+      {
+        "name": "sprint-start",
+        "title": "Start Sprint",
+        "description": "Begin sprint execution with relevant lessons",
+        "file": "commands/sprint-start.md"
+      },
+      {
+        "name": "sprint-status",
+        "title": "Sprint Status",
+        "description": "Check current sprint progress",
+        "file": "commands/sprint-status.md"
+      },
+      {
+        "name": "sprint-close",
+        "title": "Close Sprint",
+        "description": "Complete sprint and capture lessons learned",
+        "file": "commands/sprint-close.md"
+      },
+      {
+        "name": "labels-sync",
+        "title": "Sync Labels",
+        "description": "Synchronize label taxonomy from Gitea",
+        "file": "commands/labels-sync.md"
+      }
+    ],
+    "agents": [
+      {
+        "name": "planner",
+        "title": "Sprint Planner",
+        "description": "Sprint planning and architecture analysis",
+        "file": "agents/planner.md"
+      },
+      {
+        "name": "orchestrator",
+        "title": "Sprint Orchestrator",
+        "description": "Sprint coordination and progress tracking",
+        "file": "agents/orchestrator.md"
+      },
+      {
+        "name": "executor",
+        "title": "Sprint Executor",
+        "description": "Implementation guidance and code review",
+        "file": "agents/executor.md"
+      }
+    ],
+    "skills": [
+      {
+        "name": "label-taxonomy",
+        "title": "Label Taxonomy Reference",
+        "description": "Gitea label system reference",
+        "file": "skills/label-taxonomy/labels-reference.md"
+      }
+    ]
+  },
+  "configuration": {
+    "required": [
+      "GITEA_API_URL",
+      "GITEA_API_TOKEN",
+      "GITEA_OWNER",
+      "GITEA_REPO",
+      "WIKIJS_API_URL",
+      "WIKIJS_API_TOKEN",
+      "WIKIJS_BASE_PATH",
+      "WIKIJS_PROJECT"
+    ],
+    "properties": {
+      "GITEA_API_URL": {
+        "type": "string",
+        "description": "Gitea API base URL (e.g., https://gitea.example.com/api/v1)"
+      },
+      "GITEA_API_TOKEN": {
+        "type": "string",
+        "description": "Gitea API token with repo and org read access",
+        "secret": true
+      },
+      "GITEA_OWNER": {
+        "type": "string",
+        "description": "Gitea organization or user name"
+      },
+      "GITEA_REPO": {
+        "type": "string",
+        "description": "Repository name for project-scoped operations"
+      },
+      "WIKIJS_API_URL": {
+        "type": "string",
+        "description": "Wiki.js GraphQL API URL (e.g., https://wiki.example.com/graphql)"
+      },
+      "WIKIJS_API_TOKEN": {
+        "type": "string",
+        "description": "Wiki.js API token with page management permissions",
+        "secret": true
+      },
+      "WIKIJS_BASE_PATH": {
+        "type": "string",
+        "description": "Base path in Wiki.js (e.g., /company-name)"
+      },
+      "WIKIJS_PROJECT": {
+        "type": "string",
+        "description": "Project path relative to base (e.g., projects/my-project)"
+      }
+    }
+  }
+}
+```
+
+---
+
+## How Commands Work
+
+Commands are **markdown files** that expand when invoked. When a user types `/sprint-plan`, Claude Code:
+
+1. Loads the markdown file from `commands/sprint-plan.md`
+2. Injects the content into the conversation context
+3. Claude follows the instructions in the markdown
+
+**Example:** `commands/sprint-plan.md`
+
+```markdown
+# Sprint Planning Command
+
+You are assisting with sprint planning for a software project.
+
+## Your Role
+
+Guide the user through sprint planning by:
+1. Asking what feature/fix/refactor is planned
+2. Searching lessons learned for similar past work
+3. Asking clarifying questions about architecture and scope
+4. Suggesting appropriate Gitea labels based on context
+5. Creating a Gitea issue if the user confirms
+6. Generating a structured sprint planning document
+
+## Available Tools
+
+You have access to these MCP tools (invoke by describing what you need):
+- **search_lessons**: Search past lessons learned for relevant context
+- **list_issues**: Check existing issues for related work
+- **suggest_labels**: Get label suggestions based on context
+- **create_issue**: Create Gitea issue with labels
+- **get_labels**: Fetch available label taxonomy
+
+## Branch Awareness
+
+Before creating issues, check the current Git branch:
+- **Development branches** (development, feat/*): Full access
+- **Staging/Production**: Warn user and suggest switching to development branch
+
+## Workflow
+
+1. Ask: "What are you building in this sprint?"
+2. Use **search_lessons** tool with relevant keywords
+3. Present any relevant past lessons found
+4. Ask clarifying questions:
+   - Which components are affected?
+   - What's the architectural approach?
+   - Any known risks or dependencies?
+5. Use **suggest_labels** tool with the context
+6. Present suggested labels and ask for confirmation
+7. Use **create_issue** tool if user confirms
+8. Generate sprint planning document with:
+   - Sprint goal
+   - Architecture decisions
+   - Task breakdown
+   - Risks and mitigation
+   - References to relevant lessons
+
+## Personality
+
+Be thorough but not overwhelming. Ask targeted questions. Think through edge cases.
+```
+
+**Key Points:**
+- Commands are **prompts**, not code
+- Tools are invoked by **describing needs** in natural language
+- Claude Code handles tool execution automatically
+- Commands can invoke agents, use tools, or both
+
+---
+
+## How Agents Work
+
+Agents are also **markdown files** with specialized prompts. They can be invoked by:
+- Commands (e.g., sprint-plan command uses planner agent)
+- Slash commands (e.g., `/agent planner`)
+- Other agents (delegation)
+
+**Example:** `agents/planner.md`
+
+```markdown
+# Sprint Planner Agent
+
+You are the Sprint Planner for Hyper Hive Labs.
+
+## Your Identity
+
+**Role:** Sprint planning and architecture analysis
+**Personality:** Thorough, architecture-aware, asks clarifying questions
+**Focus:** Planning before execution
+
+## Responsibilities
+
+1. **Sprint Planning:**
+   - Guide users through sprint planning process
+   - Ask targeted questions about scope and architecture
+   - Break down work into manageable tasks
+
+2. **Architecture Analysis:**
+   - Identify architectural implications
+   - Detect when work is a refactor vs feature
+   - Consider cross-project impacts
+
+3. **Label Selection:**
+   - Analyze context to suggest appropriate labels
+   - Ensure Type labels are accurate (Bug/Feature/Refactor)
+   - Suggest Component and Priority labels
+
+4. **Lessons Integration:**
+   - Search past lessons before planning
+   - Reference relevant experiences
+   - Apply learned patterns
+
+5. **Issue Creation:**
+   - Create well-structured Gitea issues
+   - Include detailed descriptions
+   - Apply suggested labels
+
+## Available MCP Tools
+
+Invoke these tools by describing what you need in natural language:
+
+- **search_lessons(query, tags)**: Search Wiki.js for past lessons
+- **list_issues(state, labels, repo)**: List Gitea issues
+- **get_issue(issue_number, repo)**: Get specific issue
+- **create_issue(title, body, labels, repo)**: Create new issue
+- **suggest_labels(context)**: Get label suggestions
+- **get_labels(repo)**: Fetch all available labels
+
+## Tool Invocation Examples
+
+Instead of calling tools programmatically, describe what you need:
+
+**Good:**
+- "Let me search past lessons for service extraction experiences"
+- "I'll check if there are any existing issues related to authentication"
+- "I need to suggest labels based on this context: [context]"
+
+**Claude Code will:**
+1. Understand your intent
+2. Map it to the appropriate MCP tool
+3. Execute the tool
+4. Provide results back to you
+
+## Branch-Aware Security
+
+Check branch before creating issues:
+
+**Development branches:** Create issues freely
+**Staging branches:** Warn and suggest switching branches
+**Production branches:** Block issue creation, suggest incidents only
+
+**How to check:**
+- Git branch info is available in environment context
+- If unsure, ask user what branch they're on
+- Provide appropriate warnings
+
+## Planning Workflow
+
+1. **Understand the work:**
+   - "What are you building?"
+   - Listen for keywords: "bug", "feature", "refactor", "extract"
+
+2. **Search lessons:**
+   - Extract keywords from user's description
+   - Search: "Let me search for lessons about [keywords]"
+   - Present relevant findings
+
+3. **Ask clarifying questions:**
+   - Architecture approach?
+   - Components affected?
+   - Dependencies or risks?
+   - Timeline expectations?
+
+4. **Suggest labels:**
+   - Combine work type + user answers into context
+   - "I'll suggest appropriate labels for this work"
+   - Present suggestions with explanations
+
+5. **Confirm and create:**
+   - Show proposed issue structure
+   - Ask for user confirmation
+   - Create issue: "I'll create this issue in Gitea"
+   - Confirm creation with issue number
+
+6. **Generate plan:**
+   - Sprint goal
+   - Architecture decisions
+   - Task breakdown
+   - Risk mitigation
+   - Lesson references
+
+## Communication Style
+
+- **Thorough but concise:** Don't overwhelm with details
+- **Question-driven:** Ask targeted questions
+- **Context-aware:** Reference past lessons naturally
+- **Clear labeling:** Explain label choices
+- **Architecture-focused:** Think through implications
+
+## Example Interaction
+
+```
+User: I need to extract the Intuit engine into a separate service
+
+Planner: Let me search for lessons about service extraction...
+
+[Tool executes: search_lessons("service extraction")]
+
+I found two relevant lessons from past work:
+- Sprint 08: Service boundary issues with shared DB
+- Sprint 12: API versioning during extraction
+
+Before we proceed, a few questions:
+1. Have you defined the service boundaries at the data model level?
+2. What's your approach to API versioning?
+3. Which components will be affected?
+
+[User answers]
+
+Planner: Based on your answers, this is a Type/Refactor with:
+- Component/Backend
+- Component/API
+- Component/Database
+- Priority/High
+- Risk/Medium
+
+Should I create a Gitea issue with these labels?
+
+[User confirms]
+
+Planner: I'll create the issue...
+
+[Tool executes: create_issue(...)]
+
+Created issue #47: "Extract Intuit Engine Service"
+View at: https://gitea.hyperhivelabs.com/org/repo/issues/47
+
+Now let me generate a detailed sprint plan...
+```
+
+## Important Notes
+
+- **Never rush planning:** Take time to understand the work
+- **Always search lessons:** Past experience prevents mistakes
+- **Explain label choices:** Don't just apply labels, explain why
+- **Think architecturally:** Consider broader implications
+- **Branch safety:** Verify branch before creating issues
+
+## Delegation
+
+You focus on planning. For execution monitoring or implementation:
+- **Orchestrator agent:** Sprint progress and coordination
+- **Executor agent:** Implementation guidance and code review
+
+Stay in your lane. Planning is your expertise.
+```
+
+**Key Points:**
+- Agents describe their role and personality
+- Tools are invoked via **natural language**, not function calls
+- Claude Code maps natural language to MCP tool calls automatically
+- Agents can reference other agents for delegation
+
+---
+
+## How Tool Invocation Works
+
+**You don't call tools programmatically.** Instead, agents/commands describe what they need in natural language, and Claude Code handles the execution.
+
+**Example flow:**
+
+1. **Agent says:** "Let me search for lessons about authentication"
+2. **Claude Code:**
+   - Parses the intent
+   - Maps to MCP tool: `search_lessons(query="authentication")`
+   - Executes the tool
+   - Returns results
+3. **Agent receives:** List of matching lessons
+4. **Agent continues:** "I found 3 lessons about authentication..."
+
+This natural language interface makes agents more maintainable and readable
+
+---
+
 ## Configuration

 ### Plugin .mcp.json
--- a/docs/references/PROJECT-SUMMARY.md
+++ b/docs/references/PROJECT-SUMMARY.md
@@ -184,12 +184,13 @@ WIKIJS_PROJECT=projects/cuisineflow

 ### 2. Python Implementation

-**Decision:** Python 3.11+ for MCP servers
+**Decision:** Python 3.10+ for MCP servers
 **Why:**
- Better suited for configuration management
- Modular code structure
- Easier to maintain and extend
- Good async support
+- Modern async/await improvements
+- Better type hints support
+- Good balance of compatibility vs features
+- Widely available (released Oct 2021)
+- Most production servers have 3.10+ by now

 ### 3. Wiki.js for Lessons Learned

@@ -298,29 +299,33 @@ Wiki.js: https://wiki.hyperhivelabs.com

 ## Label Taxonomy System

-### 43-Label System
+### Dynamic Label System (44 labels currently)

-**Organization Labels (27):**
+Labels are **fetched dynamically from Gitea** at runtime via the `/labels-sync` command:
+
+**Organization Labels (28):**
 - Agent/2
 - Complexity/3
 - Efforts/5
 - Priority/4
 - Risk/3
 - Source/4
- Type/6 (includes Type/Refactor)
+- Type/6 (Bug, Feature, Refactor, Documentation, Test, Chore)

 **Repository Labels (16):**
- Component/9
- Tech/7
+- Component/9 (Backend, Frontend, API, Database, Auth, Deploy, Testing, Docs, Infra)
+- Tech/7 (Python, JavaScript, Docker, PostgreSQL, Redis, Vue, FastAPI)

 ### Type/Refactor Label

-**New organization-level label** for architectural work:
+**Organization-level label** for architectural work:
 - Service extraction
 - Architecture modifications
 - Code restructuring
 - Technical debt reduction

+**Note:** Label count may change. Always sync from Gitea using `/labels-sync` command. When new labels are detected, the command will explain changes and update suggestion logic.
+
 **Reference:** [PLUGIN-PROJMAN.md](./PLUGIN-PROJMAN.md#label-taxonomy-system)

 ---
@@ -582,6 +587,52 @@ Previous attempts failed due to:

 ---

+## Implementation Decisions (Pre-Development)
+
+These decisions were finalized before development:
+
+### 1. Python Version: 3.10+
+- **Rationale:** Balance of modern features and wide availability
+- **Benefits:** Modern async, good type hints, widely deployed
+- **Minimum:** Python 3.10.0
+
+### 2. Wiki.js Base Structure: Needs Creation
+- **Status:** `/hyper-hive-labs` structure does NOT exist yet
+- **Action:** Run `setup_wiki_structure.py` during Phase 1.1b
+- **Script:** See MCP-WIKIJS.md for complete setup script
+- **Post-setup:** Verify at https://wiki.hyperhivelabs.com/hyper-hive-labs
+
+### 3. Testing Strategy: Both Mocks and Real APIs
+- **Unit tests:** Use mocks for fast feedback during development
+- **Integration tests:** Use real Gitea/Wiki.js APIs for validation
+- **CI/CD:** Run both test suites
+- **Developers:** Can skip integration tests locally if needed
+- **Markers:** Use pytest markers (`@pytest.mark.integration`)
+
+### 4. Token Permissions: Confirmed
+- **Gitea token:**
+  - `repo` (all) - Read/write repositories, issues, labels
+  - `read:org` - Organization information and labels
+  - `read:user` - User information
+- **Wiki.js token:**
+  - Read/create/update pages
+  - Manage tags
+  - Search access
+
+### 5. Label System: Dynamic (44 labels)
+- **Current count:** 44 labels (28 org + 16 repo)
+- **Approach:** Fetch dynamically via API, never hardcode
+- **Sync:** `/labels-sync` command updates local reference and suggestion logic
+- **New labels:** Command explains changes and asks for confirmation
+
+### 6. Branch Detection: Defense in Depth
+- **Layer 1:** MCP tools check branch and block operations
+- **Layer 2:** Agent prompts check branch and warn users
+- **Layer 3:** CLAUDE.md provides context (third layer)
+- **Rationale:** Multiple layers prevent production accidents
+
+---
+
 ## Important Reminders

 1. **Build projman FIRST** - Don't start pmo until projman is validated
@@ -590,6 +641,8 @@ Previous attempts failed due to:
 4. **Test with real work** - Validate with actual sprints, not just unit tests
 5. **Security first** - Branch detection must be 100% reliable
 6. **Keep it simple** - Avoid over-engineering, focus on proven workflow
+7. **Python 3.10+** - Minimum version requirement
+8. **Wiki.js setup** - Must run setup script before projman works

 ---