From eebfd0e2f90f386967552f8f7a89b0403646a19c Mon Sep 17 00:00:00 2001 From: l3ocho Date: Thu, 6 Nov 2025 08:29:41 -0500 Subject: [PATCH] initial setup: planning documents updated --- CLAUDE.md | 226 +- docs/projman-implementation-plan.md | 1022 -------- docs/projman-plugin-analysis.md | 636 ----- .../projman-pmo/CORRECT-ARCHITECTURE.md | 325 +++ docs/references/projman-pmo/DOCUMENT-INDEX.md | 241 ++ .../projman-implementation-plan-updated.md | 2086 +++++++++++++++++ .../projman-pmo/projman-python-quickstart.md | 729 ++++++ .../projman-pmo/two-mcp-architecture-guide.md | 944 ++++++++ 8 files changed, 4500 insertions(+), 1709 deletions(-) delete mode 100644 docs/projman-implementation-plan.md delete mode 100644 docs/projman-plugin-analysis.md create mode 100644 docs/references/projman-pmo/CORRECT-ARCHITECTURE.md create mode 100644 docs/references/projman-pmo/DOCUMENT-INDEX.md create mode 100644 docs/references/projman-pmo/projman-implementation-plan-updated.md create mode 100644 docs/references/projman-pmo/projman-python-quickstart.md create mode 100644 docs/references/projman-pmo/two-mcp-architecture-guide.md diff --git a/CLAUDE.md b/CLAUDE.md index 6d198f7..867bf4d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,9 +7,11 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co This repository contains development of two Claude Code plugins for project management: 1. **`projman`** - Single-repository project management plugin (build first) -2. **`pmo`** - Multi-project PMO coordination plugin (build second) +2. **`projman-pmo`** - Multi-project PMO coordination plugin (build second) -These plugins transform a proven 15-sprint workflow into reusable, distributable tools for managing software development with Claude Code, Gitea, and agile methodologies. +These plugins transform a proven 15-sprint workflow into reusable, distributable tools for managing software development with Claude Code, Gitea, Wiki.js, and agile methodologies. + +**Status:** Planning phase complete, ready for implementation (Phase 1) ## Core Architecture @@ -41,9 +43,9 @@ The plugins implement a three-agent architecture that mirrors the proven workflo ### MCP Server Integration -Both plugins use a Gitea MCP server (`mcp-server/`) to expose Gitea API as tools: +Both plugins use **two shared MCP servers** at repository root level (`mcp-servers/`): -**Core Tools:** +**1. Gitea MCP Server** (Python) - `list_issues` - Query issues with filters - `get_issue` - Fetch single issue details - `create_issue` - Create new issue with labels @@ -52,7 +54,21 @@ Both plugins use a Gitea MCP server (`mcp-server/`) to expose Gitea API as tools - `get_labels` - Fetch org + repo label taxonomy - `suggest_labels` - Analyze context and suggest appropriate labels -Configuration lives in `.mcp.json` and uses environment variables for Gitea credentials. +**2. Wiki.js MCP Server** (Python, GraphQL) +- `search_pages` - Search Wiki.js pages by keywords/tags +- `get_page` - Fetch specific page content +- `create_page` - Create new Wiki page +- `update_page` - Modify existing page +- `list_pages` - List pages in a path +- `create_lesson` - Create lessons learned document +- `search_lessons` - Search past lessons by tags +- `tag_lesson` - Add tags to lessons learned + +**Key Architecture Points:** +- MCP servers are **shared** by both plugins at `mcp-servers/gitea` and `mcp-servers/wikijs` +- Each MCP server detects its mode (project-scoped vs company-wide) based on environment variables +- Configuration uses hybrid approach (system-level + project-level) +- Both plugins reference `../mcp-servers/` in their `.mcp.json` files ## Branch-Aware Security Model @@ -100,20 +116,37 @@ The label system includes: **Critical Feature:** After 15 sprints without lesson capture, repeated mistakes occurred (e.g., Claude Code infinite loops on similar issues 2-3 times). -**Structure:** +**Wiki.js Structure:** ``` -docs/lessons-learned/ -├── INDEX.md # Master index with searchable tags -├── sprints/ # Per-sprint lessons -├── patterns/ # Recurring patterns (deployment, architecture, Claude issues) -└── templates/ # Lesson template +Wiki.js: https://wiki.hyperhivelabs.com +└── /hyper-hive-labs/ + ├── projects/ # Project-specific documentation + │ ├── cuisineflow/ + │ │ ├── lessons-learned/ + │ │ │ ├── sprints/ + │ │ │ ├── patterns/ + │ │ │ └── INDEX.md + │ │ └── documentation/ + │ ├── cuisineflow-site/ + │ ├── intuit-engine/ + │ └── hhl-site/ + ├── company/ # Company-wide documentation + │ ├── processes/ + │ ├── standards/ + │ └── tools/ + └── shared/ # Cross-project resources + ├── architecture-patterns/ + ├── best-practices/ + └── tech-stack/ ``` **Workflow:** -- Orchestrator captures lessons at sprint close -- Planner searches relevant lessons at sprint start -- INDEX.md maintained automatically +- Orchestrator captures lessons at sprint close via Wiki.js MCP +- Planner searches relevant lessons at sprint start using GraphQL search +- INDEX.md maintained automatically via Wiki.js API +- Tags enable cross-project lesson discovery - Focus on preventable repetitions, not every detail +- Web interface for team review and editing ## Development Workflow @@ -125,48 +158,93 @@ docs/lessons-learned/ See [docs/reference-material/projman-implementation-plan.md](docs/reference-material/projman-implementation-plan.md) for the complete 12-phase implementation plan. -### Plugin Structure +### Repository Structure (DEFINITIVE) + +⚠️ **See `docs/CORRECT-ARCHITECTURE.md` for the authoritative structure reference** ``` -projman/ +hyperhivelabs/claude-plugins/ ├── .claude-plugin/ -│ └── plugin.json # Plugin manifest -├── commands/ # Slash commands (user entry points) -│ ├── sprint-plan.md -│ ├── sprint-start.md -│ ├── sprint-status.md -│ ├── sprint-close.md -│ ├── issue-create.md -│ ├── issue-list.md -│ ├── labels-sync.md -│ └── deploy-check.md -├── agents/ # Agent personalities and workflows -│ ├── planner.md -│ ├── orchestrator.md -│ └── executor.md -├── skills/ # Supporting knowledge (not orchestrators) -│ ├── gitea-api/ -│ ├── label-taxonomy/ -│ ├── lessons-learned/ -│ ├── agile-pm/ -│ └── branch-strategy/ -├── hooks/ # Automation (post-task sync, staging guards) -│ └── hooks.json -├── .mcp.json # MCP server configuration -├── mcp-server/ # Gitea API integration -│ ├── package.json -│ ├── tsconfig.json -│ └── src/ -└── README.md +│ └── marketplace.json +├── mcp-servers/ # ← SHARED BY BOTH PLUGINS +│ ├── gitea/ +│ │ ├── .venv/ +│ │ ├── requirements.txt # Python dependencies +│ │ ├── mcp_server/ +│ │ │ ├── __init__.py +│ │ │ ├── server.py +│ │ │ ├── config.py # Mode detection (project/company) +│ │ │ ├── gitea_client.py +│ │ │ └── tools/ +│ │ │ ├── issues.py +│ │ │ └── labels.py +│ │ └── tests/ +│ └── wikijs/ +│ ├── .venv/ +│ ├── requirements.txt # Python + GraphQL dependencies +│ ├── mcp_server/ +│ │ ├── __init__.py +│ │ ├── server.py +│ │ ├── config.py # Mode detection (project/company) +│ │ ├── wikijs_client.py # GraphQL client +│ │ └── tools/ +│ │ ├── pages.py +│ │ ├── lessons_learned.py +│ │ └── documentation.py +│ └── tests/ +├── projman/ # ← PROJECT PLUGIN +│ ├── .claude-plugin/ +│ │ └── plugin.json +│ ├── .mcp.json # Points to ../mcp-servers/ +│ ├── commands/ +│ │ ├── sprint-plan.md +│ │ ├── sprint-start.md +│ │ ├── sprint-status.md +│ │ ├── sprint-close.md +│ │ └── labels-sync.md +│ ├── agents/ +│ │ ├── planner.md +│ │ ├── orchestrator.md +│ │ └── executor.md +│ ├── skills/ +│ │ └── label-taxonomy/ +│ │ └── labels-reference.md +│ ├── README.md +│ └── CONFIGURATION.md +└── projman-pmo/ # ← PMO PLUGIN + ├── .claude-plugin/ + │ └── plugin.json + ├── .mcp.json # Points to ../mcp-servers/ + ├── commands/ + │ ├── pmo-status.md + │ ├── pmo-priorities.md + │ ├── pmo-dependencies.md + │ └── pmo-schedule.md + ├── agents/ + │ └── pmo-coordinator.md + └── README.md ``` ### Key Design Decisions -**MCP vs Direct API:** -- Use MCP Server for Gitea integration -- Allows agents to use tools naturally in conversation -- Easier to test independently -- Future-proof for additional integrations +**Two MCP Servers (Shared Architecture):** +- **Gitea MCP**: Issues, labels, repository management +- **Wiki.js MCP**: Documentation, lessons learned, knowledge base +- Servers are **shared** between both plugins at repository root +- Mode detection based on environment variables (project vs company-wide) +- Benefits: Single source of truth, fix bugs once, professional architecture + +**Python Implementation:** +- Python chosen over Node.js for MCP servers +- Better suited for configuration management and modular code +- Easier to maintain and extend +- Virtual environment (.venv) per MCP server + +**Hybrid Configuration:** +- **System-level**: `~/.config/claude/gitea.env` and `wikijs.env` (credentials) +- **Project-level**: `project-root/.env` (repository and path specification) +- Merge strategy: project overrides system +- Benefits: Single token per service, easy multi-project setup **Skills as Knowledge, Not Orchestrators:** - Skills provide supporting knowledge loaded when relevant @@ -188,18 +266,24 @@ projman/ ## Multi-Project Context (PMO Plugin) -The `pmo` plugin will coordinate interdependent projects: +The `projman-pmo` plugin will coordinate interdependent projects: - **CuisineFlow** - Main product - **CuisineFlow-Site** - Demo sync + customer gateway - **Intuit Engine Service** - API aggregator extraction (imminent) - **HHL-Site** - Company presence PMO plugin adds: -- Cross-project issue aggregation +- Cross-project issue aggregation (all repos in organization) - Dependency tracking and visualization - Resource allocation across projects - Deployment coordination - Multi-project prioritization +- Company-wide lessons learned search + +**Configuration Difference:** +- PMO operates at company level (no `GITEA_REPO` or `WIKIJS_PROJECT`) +- Accesses entire `/hyper-hive-labs` Wiki.js namespace +- Queries all repositories in organization Build PMO plugin AFTER projman is working and validated. @@ -231,3 +315,43 @@ Test in real CuisineFlow repository with actual Gitea instance before distributi - **Lessons learned is critical** - Prevents repeated mistakes (e.g., Claude infinite loops) - **Type/Refactor label** - Newly implemented at org level for architectural work - **Branch detection must be 100% reliable** - Prevents production accidents +- **Python for MCP servers** - Use Python 3.8+ with virtual environments +- **Wiki.js structure** - All HHL content under `/hyper-hive-labs` namespace + +## Documentation Index + +This repository contains comprehensive planning documentation: + +- **`docs/CORRECT-ARCHITECTURE.md`** - ⚠️ DEFINITIVE repository structure reference +- **`docs/DOCUMENT-INDEX.md`** - Complete guide to all planning documents +- **`docs/projman-implementation-plan-updated.md`** - Full 12-phase implementation plan +- **`docs/projman-python-quickstart.md`** - Python-specific implementation guide +- **`docs/two-mcp-architecture-guide.md`** - Deep dive into two-MCP architecture + +**Start with:** `docs/DOCUMENT-INDEX.md` for navigation guidance + +## Recent Updates (Updated: 2025-06-11) + +### Planning Phase Complete +- Comprehensive 12-phase implementation plan finalized +- Architecture decisions documented and validated +- Two-MCP-server approach confirmed (Gitea + Wiki.js) +- Python selected for MCP server implementation +- Hybrid configuration strategy defined (system + project level) +- Wiki.js structure planned at `/hyper-hive-labs` +- Repository structure designed with shared MCP servers +- `claude-plugin-developer` skill added to project + +### Key Architectural Decisions Made +1. **Shared MCP Servers**: Both plugins use the same MCP codebase at `mcp-servers/` +2. **Mode Detection**: MCP servers detect project vs company-wide mode via environment variables +3. **Python Implementation**: MCP servers written in Python (not Node.js) for better configuration handling +4. **Wiki.js Integration**: Lessons learned and documentation moved to Wiki.js for better collaboration +5. **Hybrid Config**: System-level credentials + project-level paths for flexibility + +### Next Steps +- Begin Phase 1.1a: Gitea MCP Server implementation +- Set up Python virtual environments +- Create configuration loaders +- Implement core Gitea tools (issues, labels) +- Write integration tests diff --git a/docs/projman-implementation-plan.md b/docs/projman-implementation-plan.md deleted file mode 100644 index 756743f..0000000 --- a/docs/projman-implementation-plan.md +++ /dev/null @@ -1,1022 +0,0 @@ -# ProjMan Plugin Suite - Implementation Plan - -**Plugins:** `projman` (single-repo) + `projman-pmo` (multi-project) -**Build Order:** projman first, then projman-pmo -**Label System:** Type/Refactor now implemented at organization level - ---- - -## Phase 1: Core Infrastructure (projman) - -### 1.1 MCP Server Foundation - -**Deliverable:** Working Gitea MCP server with all required tools - -**Tasks:** -- Set up Node.js/TypeScript project structure -- Implement authentication with Gitea API -- Create 7 core tools: - - `list_issues` - Query issues with filters - - `get_issue` - Fetch single issue details - - `create_issue` - Create new issue with labels - - `update_issue` - Modify existing issue - - `add_comment` - Add comments to issues - - `get_labels` - Fetch org + repo label taxonomy - - `suggest_labels` - Analyze context and suggest appropriate labels -- Write integration tests against actual Gitea instance -- Create `.mcp.json` configuration template - -**Success Criteria:** -- All tools pass integration tests -- Label suggestion correctly identifies Type/Refactor for architectural changes -- Error handling for network failures and API rate limits -- Environment variable configuration works - -### 1.2 Label Taxonomy System - -**Deliverable:** Label reference with sync capability - -**Tasks:** -- Create `skills/label-taxonomy/` directory structure -- Port `gitea-labels-reference.md` to plugin -- Document exclusive vs non-exclusive label rules -- Build label suggestion logic: - - Type detection (Bug, Feature, Refactor, etc.) - - Component inference from file paths - - Tech stack detection from extensions - - Source/Priority/Risk heuristics -- Implement `/labels-sync` command -- Create agent workflow for reviewing label changes - -**Success Criteria:** -- Local reference matches current Gitea state -- Suggestion engine correctly identifies Type/Refactor for architecture work -- Sync command shows clear diffs -- Agent discusses impact of label changes before applying - -**Label Categories (43 total):** -- Organization (27): Agent/2, Complexity/3, Efforts/5, Priority/4, Risk/3, Source/4, Type/6 (includes Refactor) -- Repository (16): Component/9, Tech/7 (includes Tech/AI) - -### 1.3 Plugin Structure - -**Deliverable:** Complete plugin directory with manifest - -**Tasks:** -- Create `.claude-plugin/plugin.json` with metadata -- Set up all required directories -- Configure plugin dependencies -- Write README with installation instructions -- Create example `.env` template -- Add LICENSE and CHANGELOG - -**Directory Structure:** -``` -projman/ -├── .claude-plugin/ -│ └── plugin.json -├── commands/ -│ ├── sprint-plan.md -│ ├── sprint-start.md -│ ├── sprint-status.md -│ ├── sprint-close.md -│ ├── issue-create.md -│ ├── issue-list.md -│ ├── labels-sync.md -│ └── deploy-check.md -├── agents/ -│ ├── planner.md -│ ├── orchestrator.md -│ └── executor.md -├── skills/ -│ ├── gitea-api/ -│ │ └── SKILL.md -│ ├── label-taxonomy/ -│ │ ├── SKILL.md -│ │ └── labels-reference.md -│ ├── lessons-learned/ -│ │ └── SKILL.md -│ ├── agile-pm/ -│ │ └── SKILL.md -│ └── branch-strategy/ -│ └── SKILL.md -├── hooks/ -│ └── hooks.json -├── .mcp.json -├── mcp-server/ -│ ├── package.json -│ ├── tsconfig.json -│ ├── src/ -│ │ ├── gitea-server.ts -│ │ ├── label-suggester.ts -│ │ ├── types.ts -│ │ └── utils.ts -│ └── tests/ -│ └── integration.test.ts -├── README.md -├── LICENSE -└── CHANGELOG.md -``` - -**Success Criteria:** -- Plugin manifest valid -- All directories in place -- Documentation complete -- Installable via local marketplace - ---- - -## Phase 2: Agent Development (projman) - -### 2.1 Planner Agent - -**Deliverable:** Planning agent for architecture and sprint setup - -**Tasks:** -- Port `sprint-workflow.md` logic to agent prompt -- Integrate branch detection (Development vs Development-Claude modes) -- Add label suggestion workflow -- Implement sprint document generation -- Connect to `gitea.create_issue` tool -- Add Gitea issue export for Development-Claude mode -- Implement lessons learned search at planning start - -**Agent Personality:** -- Asks clarifying questions upfront -- Thinks through edge cases and risks -- Documents architectural decisions -- Never rushes to implementation -- References past lessons learned - -**Tools Used:** -- `gitea.create_issue` (Development mode only) -- `gitea.get_labels` (for validation) -- `gitea.suggest_labels` (for new issues) -- `gitea.list_issues` (to check for duplicates) - -**Success Criteria:** -- Generates complete sprint planning documents -- Creates properly labeled Gitea issues -- Exports issue data in Development-Claude mode -- Finds and references relevant past lessons -- Suggests appropriate labels (including Type/Refactor when applicable) - -### 2.2 Orchestrator Agent - -**Deliverable:** Sprint execution coordinator - -**Tasks:** -- Port `sprint-orchestrator.md` logic to agent prompt -- Implement progress tracking -- Create execution prompt generation -- Add Git operation handling (commit, merge, cleanup) -- Build dependency coordination logic -- Integrate with lessons learned capture - -**Agent Personality:** -- Concise and action-oriented -- Tracks details meticulously -- Signals next steps clearly -- Never writes application code -- Coordinates between tasks - -**Tools Used:** -- `gitea.get_issue` (read sprint details) -- `gitea.update_issue` (update progress) -- `gitea.add_comment` (log milestones) - -**Success Criteria:** -- Generates lean execution prompts (not full docs) -- Tracks sprint progress accurately -- Manages branch operations safely -- Coordinates task dependencies -- Signals clear next steps - -### 2.3 Executor Agent - -**Deliverable:** Implementation specialist - -**Tasks:** -- Port `sprint-executor.md` logic to agent prompt -- Implement feature development workflow -- Add completion report generation -- Integrate with orchestrator handoff - -**Agent Personality:** -- Implementation-focused -- Follows specifications precisely -- Tests as builds -- Reports blockers immediately -- Generates detailed completion reports - -**Tools Used:** -- Standard Claude Code tools (no Gitea access) - -**Success Criteria:** -- Implements features according to prompts -- Writes clean, tested code -- Follows architectural decisions from planning -- Generates useful completion reports -- Surfaces blockers early - ---- - -## Phase 3: Commands (projman) - -### 3.1 Sprint Lifecycle Commands - -**Deliverable:** Core sprint management commands - -**Tasks:** -- `/sprint-plan` - Invokes planner agent -- `/sprint-start` - Invokes orchestrator agent -- `/sprint-status` - Shows current progress -- `/sprint-close` - Captures lessons learned - -**Command Behaviors:** -- Detect current branch and adjust permissions -- Pass context to appropriate agents -- Handle mode restrictions (Development vs Development-Claude) -- Provide clear user feedback - -**Success Criteria:** -- Commands invoke correct agents -- Branch detection works reliably -- User workflow feels natural -- Mode restrictions enforced - -### 3.2 Issue Management Commands - -**Deliverable:** Gitea issue interaction commands - -**Tasks:** -- `/issue-create` - Quick issue creation with label suggestions -- `/issue-list` - Filter and display issues -- `/labels-sync` - Sync label taxonomy from Gitea - -**Success Criteria:** -- Quick issue creation with smart defaults -- Filtering works for sprint planning -- Label sync includes impact discussion -- Type/Refactor appears in suggestions for architecture work - -### 3.3 Deployment Commands - -**Deliverable:** Environment validation commands - -**Tasks:** -- `/deploy-check` - Validate staging/production environment -- Branch-aware behavior for deployment contexts - -**Success Criteria:** -- Detects configuration issues -- Creates issues on code problems (staging/prod modes) -- Handles .env modifications appropriately - ---- - -## Phase 4: Lessons Learned System (projman) - -### 4.1 Wiki Structure - -**Deliverable:** Markdown-based lessons learned repository - -**Tasks:** -- Create `docs/lessons-learned/` directory structure -- Build sprint lesson template -- Create pattern-based categorization -- Implement searchable index - -**Directory Structure:** -``` -docs/lessons-learned/ -├── INDEX.md # Master index with tags -├── sprints/ -│ ├── sprint-01-auth-refactor.md -│ ├── sprint-02-deployment.md -│ └── sprint-N-[name].md -├── patterns/ -│ ├── claude-infinite-loops.md # Recurring Claude Code issues -│ ├── deployment-gotchas.md # Deployment problems -│ ├── architecture-mistakes.md # Architecture decisions -│ └── integration-issues.md # Third-party API problems -└── templates/ - └── lesson-template.md -``` - -**Lesson Template:** -```markdown -# Lesson: [Short Title] - -**Sprint:** [Sprint number/name] -**Date:** [YYYY-MM-DD] -**Category:** [Architecture/Deployment/Claude/Integration/etc.] -**Impact:** [High/Medium/Low] - -## What Happened -[Describe the issue/situation] - -## Root Cause -[Why it happened] - -## What We Did -[How it was resolved] - -## Prevention -[How to avoid this in the future] - -## Keywords -[Tags for searchability: deployment, auth, infinite-loop, etc.] -``` - -**Success Criteria:** -- Easy to create new lessons -- Searchable by keyword/category -- Git tracked and versioned -- Referenced by planner agent - -### 4.2 Agent Integration - -**Deliverable:** Automated lesson capture and retrieval - -**Tasks:** -- Orchestrator prompts for lessons at sprint close -- Planner searches lessons at sprint start -- INDEX.md maintained automatically -- Pattern categorization suggests categories - -**Sprint Close Flow:** -``` -Orchestrator: "Sprint completed ✅ - -Let's capture lessons learned: - -1. What went wrong that we should avoid next time? -2. What decisions worked really well? -3. Were there any Claude Code issues that caused loops/blocks? -4. Any architectural insights for similar future work? - -[User provides answers] - -I'll create: -- docs/lessons-learned/sprints/sprint-16-intuit-refactor.md -- Update INDEX.md with searchable tags -- File under patterns/architecture-mistakes.md if applicable -" -``` - -**Sprint Start Flow:** -``` -Planner: "Let me search past lessons learned..." - -[Searches INDEX.md for keywords: 'intuit', 'api', 'service', 'refactor'] - -📚 Found 3 relevant lessons: -- sprint-08: Service boundary decisions (Type/Refactor) -- sprint-12: Claude Code loop on validation logic -- sprint-14: API rate limiting with third-party services - -I'll reference these in the planning document. -``` - -**Success Criteria:** -- Lessons captured at every sprint close -- Relevant lessons surfaced at sprint start -- INDEX stays current -- Patterns emerge and get documented - -### 4.3 Retroactive Lesson Capture - -**Deliverable:** Document past 15 sprints' lessons - -**Tasks:** -- Create command `/lessons-backfill` for guided retrospective -- Agent interviews user about past sprints -- Focuses on repeated issues (Claude infinite loops, etc.) -- Prioritizes high-impact lessons - -**Interview Process:** -``` -Orchestrator: "Let's capture lessons from past sprints. - -I'll focus on patterns that repeated across sprints. - -You mentioned Claude Code infinite loops on similar issues 2-3 times. -Can you describe: -1. What type of code triggered the loops? -2. What was Claude trying to do? -3. How did you eventually resolve it? -4. Which sprints did this happen in? - -[Captures pattern lesson, not individual sprint lessons] -" -``` - -**Success Criteria:** -- Most impactful past lessons documented -- Patterns identified and categorized -- No need to document every sprint detail -- Focus on preventable repetitions - ---- - -## Phase 5: Hooks and Automation (projman) - -### 5.1 Documentation Sync Hook - -**Deliverable:** Automatic doc updates after task completion - -**Tasks:** -- Port `post-task-doc-sync.md` logic to hook -- Trigger on task completion -- Update sprint documentation -- Maintain change logs - -**Hook Configuration:** -```json -{ - "name": "post-task-sync", - "event": "task_completed", - "action": "run_command", - "command": "update-sprint-docs", - "description": "Sync sprint documentation after task completion" -} -``` - -**Success Criteria:** -- Docs stay current automatically -- No manual sync needed -- Change history preserved - -### 5.2 Staging/Production Guards - -**Deliverable:** Prevent accidental code changes on protected branches - -**Tasks:** -- Detect file changes on staging/main branches -- Warn if attempting code modifications -- Suggest creating issue instead - -**Hook Configuration:** -```json -{ - "name": "staging-code-guard", - "event": "file_changed", - "filter": { - "branch": "staging", - "paths": ["src/**/*.py", "src/**/*.js", "backend/**/*", "frontend/**/*"] - }, - "action": "warn", - "message": "⚠️ Code changes on staging branch. Use /issue-create to document needed fixes." -}, -{ - "name": "production-code-guard", - "event": "file_changed", - "filter": { - "branch": "main", - "paths": ["src/**/*.py", "src/**/*.js", "backend/**/*", "frontend/**/*"] - }, - "action": "block", - "message": "🚫 Code changes blocked on production. Use /issue-create for incidents." -} -``` - -**Success Criteria:** -- Prevents accidental code changes -- Guides user to correct workflow -- Allows .env modifications as needed - -### 5.3 Issue Status Automation - -**Deliverable:** Auto-update issues on branch merge - -**Tasks:** -- Detect sprint branch merges -- Update corresponding Gitea issue status -- Add completion comment with branch info - -**Success Criteria:** -- Issues auto-close on merge -- Audit trail maintained -- Manual override available - ---- - -## Phase 6: Local Testing (projman) - -### 6.1 Local Marketplace Setup - -**Deliverable:** Test marketplace for plugin development - -**Tasks:** -- Create local marketplace directory structure -- Write marketplace.json manifest -- Configure plugin source path -- Add marketplace to Claude Code - -**Structure:** -``` -~/projman-dev-marketplace/ -├── .claude-plugin/ -│ └── marketplace.json -└── projman/ # Symlink to plugin directory - └── [plugin contents] -``` - -**Success Criteria:** -- Plugin installs locally -- Can iterate and reinstall -- Changes reflect immediately - -### 6.2 Integration Testing - -**Deliverable:** Validated plugin in CuisineFlow repo - -**Tasks:** -- Install plugin in CuisineFlow project -- Test all commands with real Gitea instance -- Run through complete sprint cycle -- Validate branch detection on all branch types -- Test label suggestions with Type/Refactor -- Capture and review lessons learned - -**Test Scenarios:** -- Plan sprint with `/sprint-plan` on development branch -- Create issue with Type/Refactor label -- Start sprint with `/sprint-start` -- Execute tasks in separate chat -- Close sprint with `/sprint-close` and capture lessons -- Sync labels with `/labels-sync` -- Test staging mode restrictions -- Test production incident reporting - -**Success Criteria:** -- All commands work as expected -- Branch detection reliable -- Label suggestions accurate (including Refactor) -- Lessons learned capture works -- No major regressions vs current system - -### 6.3 Real-World Validation - -**Deliverable:** Plugin used in actual sprint (Intuit refactor) - -**Tasks:** -- Use plugin for Intuit engine extraction sprint -- Document friction points -- Collect improvement ideas -- Measure workflow efficiency vs current system - -**Metrics to Track:** -- Time to create sprint (planning to issue creation) -- Number of manual steps eliminated -- Lessons learned capture rate -- Label accuracy on created issues - -**Success Criteria:** -- Plugin performs equal or better than current workflow -- User finds it helpful, not hindering -- Captures lessons that would have been missed -- Identifies areas for improvement - ---- - -## Phase 7: Skills Refinement (projman) - -### 7.1 Extract Supporting Knowledge - -**Deliverable:** Clean, reusable skills - -**Tasks:** -- Extract Gitea API patterns → `skills/gitea-api/SKILL.md` -- Extract PM best practices → `skills/agile-pm/SKILL.md` -- Extract Git workflows → `skills/branch-strategy/SKILL.md` -- Extract label taxonomy usage → `skills/label-taxonomy/SKILL.md` -- Extract lessons learned patterns → `skills/lessons-learned/SKILL.md` - -**Each Skill Contains:** -- When to use this knowledge -- Common patterns and anti-patterns -- Examples from past sprints -- Tool usage guidelines -- Reference to full documentation - -**Success Criteria:** -- Skills are concise (< 200 lines) -- Agents reference skills appropriately -- Knowledge is reusable across agents -- Reduced token usage per interaction - -### 7.2 Agent Prompt Optimization - -**Deliverable:** Lean agent prompts that reference skills - -**Tasks:** -- Remove duplicated knowledge from agent prompts -- Add skill references where appropriate -- Optimize for token efficiency -- Maintain agent personality clarity - -**Example Before:** -```markdown -# Planner Agent -[500 lines including all label rules, Git workflow, PM practices] -``` - -**Example After:** -```markdown -# Planner Agent - -**Skills:** label-taxonomy, agile-pm, branch-strategy, gitea-api - -**Core Personality:** -- Ask clarifying questions upfront -- Think through edge cases -- Document risks explicitly -[150 lines focused on agent-specific behavior] -``` - -**Success Criteria:** -- Agent prompts < 300 lines each -- Skills invoked automatically when relevant -- Token usage reduced 30-40% -- No loss in agent effectiveness - ---- - -## Phase 8: Documentation and Distribution (projman) - -### 8.1 User Documentation - -**Deliverable:** Complete usage guide - -**Tasks:** -- Write README with: - - Installation instructions - - Configuration guide (Gitea credentials, .env setup) - - Command reference with examples - - Agent personality descriptions - - Branch-aware behavior explanation - - Label taxonomy overview - - Lessons learned workflow -- Create CONTRIBUTING.md for future enhancements -- Write troubleshooting guide -- Add FAQ section - -**Success Criteria:** -- New user can install and configure in < 15 minutes -- All commands documented with examples -- Common issues covered -- Clear explanation of Type/Refactor and other labels - -### 8.2 Plugin Marketplace Publication - -**Deliverable:** Public plugin in marketplace - -**Tasks:** -- Clean up code and documentation -- Add comprehensive testing -- Create example configurations -- Write clear changelog -- Publish to plugin marketplace -- Announce in community - -**Success Criteria:** -- Plugin discoverable in marketplace -- Installation is one command -- Example .env template provided -- Positive feedback from early adopters - ---- - -## Phase 9: PMO Plugin Foundation (projman-pmo) - -### 9.1 Multi-Project Requirements Analysis - -**Deliverable:** Specification for PMO plugin - -**Tasks:** -- Document current cross-project coordination workflow -- Map project dependencies: - - CuisineFlow → CuisineFlow-Site (demo sync) - - CuisineFlow → Intuit Engine Service (API aggregation) - - Customer VPS deployments (IP restrictions) -- Identify coordination pain points -- Define success metrics for PMO plugin - -**Research Questions:** -- How do you currently track CuisineFlow-Site demo sync? -- What triggers Intuit engine updates? -- How do you coordinate customer VPS deployments? -- Where do multi-project conflicts happen? -- What decisions require cross-project visibility? - -**Success Criteria:** -- Clear understanding of multi-project workflows -- Pain points documented -- PMO plugin scope defined -- Not duplicating single-repo functionality - -### 9.2 MCP Server Extension - -**Deliverable:** Multi-repo query capabilities - -**Tasks:** -- Extend Gitea MCP server for multi-repo operations -- Add tools: - - `list_repos` - Get all organization repos - - `aggregate_issues` - Fetch issues across repos - - `check_dependencies` - Analyze cross-repo dependencies - - `get_deployment_status` - Check deployment states -- Build dependency graph visualization data - -**Success Criteria:** -- Can query multiple repos efficiently -- Dependency analysis works -- Aggregated views make sense -- Performance acceptable for 3-5 repos - -### 9.3 PMO Agent Design - -**Deliverable:** Multi-project coordinator agent - -**Tasks:** -- Define PMO agent personality -- Design cross-project prioritization logic -- Create resource allocation algorithms -- Build conflict detection rules -- Design dependency tracking system - -**PMO Agent Personality:** -- Strategic thinker across projects -- Identifies bottlenecks and conflicts -- Balances competing priorities -- Maintains company-wide view -- Delegates to project-level agents - -**Success Criteria:** -- Clear separation from projman agents -- Valuable for multi-project scenarios -- Doesn't micromanage single projects -- Integrates with projman seamlessly - ---- - -## Phase 10: PMO Plugin Development (projman-pmo) - -### 10.1 Cross-Project Commands - -**Deliverable:** PMO-specific commands - -**Tasks:** -- `/pmo-status` - View all projects status -- `/pmo-priorities` - Review and adjust priorities -- `/pmo-dependencies` - Visualize cross-project dependencies -- `/pmo-resources` - Track resource allocation -- `/pmo-sync` - Coordinate dependent deployments - -**Success Criteria:** -- Commands provide multi-project insight -- Integration with projman plugins -- Don't duplicate single-project functionality -- Actually useful for coordination - -### 10.2 Dependency Management - -**Deliverable:** Track and visualize project dependencies - -**Tasks:** -- Build dependency declaration format -- Create dependency graph visualization -- Implement impact analysis (what breaks if X changes) -- Add deployment coordination logic -- Handle version pinning across projects - -**Example Dependencies:** -```yaml -# In CuisineFlow-Site -dependencies: - - repo: cuisineflow - type: demo-sync - constraint: "same-version" - trigger: "on-release" - - - repo: intuit-engine - type: api-provider - constraint: "stable-api" - trigger: "on-breaking-change" -``` - -**Success Criteria:** -- Dependencies clearly documented -- Impact analysis accurate -- Deployment coordination works -- Version conflicts detected early - -### 10.3 Resource Tracking - -**Deliverable:** Cross-project resource visibility - -**Tasks:** -- Track which projects are active -- Identify resource conflicts -- Suggest priority adjustments -- Maintain project roadmaps -- Coordinate customer deployment schedules - -**Success Criteria:** -- Clear view of where effort is going -- Conflicts surfaced early -- Priorities aligned with company strategy -- Customer deployment schedule respected - ---- - -## Phase 11: PMO Plugin Testing (projman-pmo) - -### 11.1 Multi-Project Scenario Testing - -**Deliverable:** Validated PMO plugin - -**Tasks:** -- Test with CuisineFlow + CuisineFlow-Site + Intuit Engine -- Simulate deployment coordination scenarios -- Test priority conflict resolution -- Validate dependency tracking -- Test customer deployment scheduling - -**Test Scenarios:** -- CuisineFlow release triggers Site demo update -- Intuit engine breaking change impacts CuisineFlow -- Competing priorities across projects -- Customer VPS deployment window coordination -- Resource constraint identification - -**Success Criteria:** -- All scenarios handled correctly -- Dependencies respected -- Conflicts detected and surfaced -- Coordination reduces manual overhead - -### 11.2 Integration with projman - -**Deliverable:** Seamless plugin interoperability - -**Tasks:** -- Ensure PMO agent delegates to projman agents -- Test command interoperability -- Validate shared MCP server usage -- Check lessons learned sharing across projects - -**Success Criteria:** -- PMO doesn't interfere with single-project work -- Delegation works smoothly -- Shared infrastructure stable -- Cross-project lessons accessible - ---- - -## Phase 12: Production Deployment - -### 12.1 Multi-Environment Rollout - -**Deliverable:** Plugins deployed across all environments - -**Tasks:** -- Deploy to laptop (development) -- Deploy to staging VPS -- Deploy to production VPS -- Configure branch-aware permissions per environment -- Test network connectivity and API access - -**Environment Matrix:** -``` -| Environment | Branch | projman | projman-pmo | Permissions | -|-------------|--------|---------|-------------|-------------| -| Laptop | dev/* | ✅ | ✅ | Full access | -| Laptop | staging| ✅ | ✅ | Read + issues | -| Laptop | main | ✅ | ✅ | Read + incidents | -| VPS Staging | staging| ✅ | ✅ | Read + config | -| VPS Prod | main | ✅ | ✅ | Read + emergency config | -``` - -**Success Criteria:** -- All environments configured correctly -- Branch detection works everywhere -- API credentials secured properly -- Network access validated - -### 12.2 Team Onboarding - -**Deliverable:** Plugin adoption by team/future collaborators - -**Tasks:** -- Create onboarding documentation -- Record walkthrough videos -- Provide example workflows -- Document common pitfalls -- Set up support channel - -**Success Criteria:** -- New team member can use plugin in < 30 minutes -- Common questions documented -- Positive user feedback -- Adoption rate high - ---- - -## Success Metrics - -### Technical Metrics -- ✅ All integration tests passing -- ✅ Branch detection 100% reliable -- ✅ Label suggestions 85%+ accurate -- ✅ Zero data loss in Gitea operations -- ✅ Performance: Commands respond < 2 seconds - -### User Experience Metrics -- ✅ Sprint planning time reduced 40% -- ✅ Manual steps eliminated: 10+ per sprint -- ✅ Lessons learned capture rate: 100% (vs 0% before) -- ✅ Label accuracy on issues: 90%+ -- ✅ User satisfaction: "Definitely better than current system" - -### Workflow Metrics -- ✅ Complete sprint cycle uses plugin end-to-end -- ✅ No fallback to manual scripts -- ✅ Agent personalities clear and helpful -- ✅ Cross-project coordination improved (PMO plugin) - ---- - -## Critical Path Items - -These must be completed in order: - -1. **MCP Server** - Nothing works without Gitea integration -2. **Label System** - Required for issue creation -3. **Planner Agent** - Entry point for sprint workflow -4. **Lessons Learned** - Addresses immediate pain -5. **Testing in Real Sprint** - Validates everything -6. **PMO Foundation** - Can't build multi-project without single-project working - ---- - -## Rollback Plan - -If plugin causes more problems than it solves: - -**Immediate Fallback:** -- Keep existing skills and scripts functional -- Plugin is opt-in, not replacement -- Document issues and iterate - -**Criteria for Rollback:** -- Plugin slower than current workflow -- Frequent errors or data loss -- User frustration increases -- Blocks urgent work (like Intuit refactor) - -**Progressive Enhancement:** -- Build plugin alongside current system -- Migrate piece by piece -- Keep escape hatches -- Only deprecate scripts when plugin proven - ---- - -## Notes on Type/Refactor Label - -**Label Details:** -- **Name:** `Type/Refactor` -- **Level:** Organization (available to all repos) -- **Category:** Type/ (Exclusive - only one Type per issue) -- **Color:** #0052cc (matches other Type labels) -- **Description:** Architectural changes and code restructuring - -**Usage in Plugin:** -- Planner agent suggests Type/Refactor for: - - Service extraction (like Intuit engine) - - Architecture modifications - - Code restructuring without feature changes - - Performance optimizations requiring significant changes -- Label suggestion engine detects refactor keywords: - - "extract", "refactor", "restructure", "optimize architecture" - - "service boundary", "microservice", "decouple" - - "technical debt", "code quality" -- Shows in label sync diffs when fetching from Gitea -- Documented in label taxonomy skill - -**Integration Points:** -- MCP server includes Type/Refactor in label enumeration -- Suggestion engine trained on architectural patterns -- Sprint planning templates include refactor considerations -- Lessons learned can tag architectural mistakes for future refactors - ---- - -## End of Implementation Plan - -This plan builds two plugins systematically, starting with single-repo project management and expanding to multi-project coordination. Each phase builds on previous phases, with testing and validation throughout. - -The plan is execution-ready but flexible - adjust based on real-world feedback and discovered requirements. diff --git a/docs/projman-plugin-analysis.md b/docs/projman-plugin-analysis.md deleted file mode 100644 index 7cc066e..0000000 --- a/docs/projman-plugin-analysis.md +++ /dev/null @@ -1,636 +0,0 @@ -# ProjMan Plugin: Analysis & Design - -## Executive Summary - -Leo has built a sophisticated, working project management system over 15 sprints using: -- **Skills** for behavioral guidance -- **Python scripts** for Gitea API interaction -- **CLAUDE.md** for branch-aware permission control - -**Goal:** Transform this proven system into a reusable, distributable plugin called `projman`. - -## Current System Analysis - -### What's Working Well - -**1. Three-Chat Architecture** -- **Chat 0** (Claude Web): Planning & architecture → generates sprint documents -- **Chat 1** (Claude Code): Orchestration → manages branches, generates prompts, tracks progress -- **Chat 2+** (Claude Code): Execution → implements features according to prompts - -**2. Branch-Aware Security** -``` -development → Full access -feat/* → Full access -staging → Read-only code, can modify .env, creates issues -main → Read-only code, emergency .env only, creates issues -``` - -**3. Gitea Integration** -- Two Python scripts: `create_gitea_issue.py` and `list_gitea_issues.py` -- Proper API authentication via environment variables -- Structured issue creation with labels, priority, affected files - -**4. Skills System** -- `sprint-workflow.md` - Planning phase (Chat 0) -- `sprint-orchestrator.md` - Coordination phase (Chat 1) -- `sprint-executor.md` - Implementation phase (Chat 2+) -- `post-task-doc-sync.md` - Documentation updates -- `incident-reporter.md` - Issue creation from staging/prod - -### What Feels Messy - -Leo identified these friction points: - -**1. Skills vs Agents Confusion** -> "I don't think skill would be the best way of handling an Agent" - -Current state: Using skills to guide behavior that should be agent personalities - -**2. Manual Script Invocation** -Scripts exist but require manual execution: -```bash -python ops/scripts/create_gitea_issue.py --title "..." --problem "..." ... -python ops/scripts/list_gitea_issues.py -``` - -**3. Mode Detection Redundancy** -Branch detection logic is duplicated across: -- CLAUDE.md -- Each skill file -- Manual checks in workflows - -**4. Context Switching Overhead** -User must manually: -- Switch between chats -- Remember which skill to load where -- Copy/paste completion reports between chats - -## Plugin Architecture Design - -### Core Insight: The 3-Agent Model - -Transform the three chats into three distinct agents: - -``` -projman/ -├── agents/ -│ ├── planner.md # Chat 0 → Planning Agent -│ ├── orchestrator.md # Chat 1 → PM Agent -│ └── executor.md # Chat 2+ → Implementation Agent -``` - -### Component Breakdown - -#### 1. MCP Server: `gitea-mcp` - -**Purpose:** Provide Gitea API access as tools that agents can use - -**Tools to expose:** -```typescript -{ - "list_issues": { - state: "open" | "closed" | "all", - labels: string[], - assignee: string - }, - "create_issue": { - title: string, - body: string, - labels: string[], - assignee: string, - priority: "critical" | "high" | "medium" | "low" - }, - "update_issue": { - number: number, - state: "open" | "closed", - body: string, - labels: string[] - }, - "get_issue": { - number: number - }, - "add_comment": { - number: number, - body: string - }, - "get_labels": { - // Fetches all org + repo labels with metadata - include_org: boolean, - include_repo: boolean - }, - "suggest_labels": { - // Analyzes context and suggests appropriate labels - issue_body: string, - context: { - branch: string, - files_changed: string[], - is_bug: boolean, - components: string[] - } - } -} -``` - -**Configuration:** `.mcp.json` -```json -{ - "mcpServers": { - "gitea": { - "command": "node", - "args": ["mcp-server/gitea-server.js"], - "env": { - "GITEA_URL": "${GITEA_URL}", - "GITEA_OWNER": "${GITEA_OWNER}", - "GITEA_REPO": "${GITEA_REPO}", - "GITEA_API_TOKEN": "${GITEA_API_TOKEN}" - } - } - } -} -``` - -#### 2. Slash Commands - -**Primary commands for user interaction:** - -```markdown -commands/ -├── sprint-plan.md # /sprint-plan - Start planning a new sprint -├── sprint-start.md # /sprint-start - Begin sprint execution -├── sprint-status.md # /sprint-status - Check current sprint progress -├── sprint-close.md # /sprint-close - Complete sprint, capture lessons learned -├── issue-create.md # /issue-create - Quick issue creation -├── issue-list.md # /issue-list - List issues with filters -├── labels-sync.md # /labels-sync - Sync label taxonomy from Gitea -└── deploy-check.md # /deploy-check - Staging/prod environment validation -``` - -**Example: `/labels-sync`** -```markdown ---- -name: labels-sync -description: Sync label taxonomy from Gitea and review changes -agent: planner ---- - -You are updating the plugin's label reference from Gitea. - -**Workflow:** -1. Fetch current labels from Gitea (org + repo) -2. Compare with local reference (skills/label-taxonomy/labels-reference.md) -3. Show user a diff of changes: - - New labels added - - Labels removed - - Description/color changes -4. Discuss impact: "The new Type/Refactor label means we should update suggestion logic for architectural changes" -5. After approval, update local reference -6. Update label suggestion rules if needed - -This ensures the plugin stays in sync with your evolving label system. -``` - -#### 3. Agents - -**Agent: `planner.md`** -```markdown ---- -name: planner -description: Architecture analysis and sprint planning expert ---- - -You are the Planning Agent for project management. - -**Your Role:** -- Analyze business requirements -- Make architectural decisions -- Break work into implementation steps -- Generate sprint planning documents -- Create Gitea issues for approved plans - -**Your Personality:** -- Ask clarifying questions upfront -- Think through edge cases -- Consider architectural fit -- Document risks explicitly -- Never rush to implementation - -**Your Tools:** -- gitea.create_issue - Create issues after approval -- gitea.list_issues - Check for similar existing issues - -**Branch Awareness:** -${BRANCH_DETECTION_LOGIC} - -**Workflow:** -[... rest of sprint-workflow.md content ...] -``` - -**Agent: `orchestrator.md`** -```markdown ---- -name: orchestrator -description: Sprint execution coordinator and progress tracker ---- - -You are the Orchestrator Agent for project management. - -**Your Role:** -- Manage sprint execution -- Generate lean execution prompts -- Track progress and update documentation -- Handle Git operations (commit, merge, cleanup) -- Coordinate task dependencies - -**Your Personality:** -- Concise and action-oriented -- Track details meticulously -- Signal next steps clearly -- Never write application code yourself - -**Your Tools:** -- gitea.get_issue - Read issue details -- gitea.update_issue - Update issue status -- gitea.add_comment - Add progress notes - -**Branch Awareness:** -${BRANCH_DETECTION_LOGIC} - -**Workflow:** -[... rest of sprint-orchestrator.md content ...] -``` - -**Agent: `executor.md`** -```markdown ---- -name: executor -description: Feature implementation and code execution specialist ---- - -You are the Executor Agent for project management. - -**Your Role:** -- Implement features according to execution prompts -- Write clean, tested code -- Follow architectural decisions from planning -- Generate completion reports for orchestrator - -**Your Personality:** -- Implementation-focused -- Follow specs precisely -- Test as you build -- Report blockers immediately - -**Your Tools:** -- None (uses standard code tools) - -**Branch Awareness:** -${BRANCH_DETECTION_LOGIC} - -**Workflow:** -[... rest of sprint-executor.md content ...] -``` - -#### 4. Skills - -Skills become **supporting knowledge** rather than primary orchestrators: - -```markdown -skills/ -├── gitea-api/ -│ └── SKILL.md # How to use Gitea MCP server effectively -├── agile-pm/ -│ └── SKILL.md # Agile/PMP best practices -└── branch-strategy/ - └── SKILL.MD # Git branching workflow -``` - -#### 5. Hooks - -Automate repetitive actions: - -```json -{ - "hooks": [ - { - "name": "post-task-sync", - "event": "task_completed", - "action": "run_command", - "command": "update-docs", - "description": "Sync documentation after task completion" - }, - { - "name": "staging-incident", - "event": "file_changed", - "filter": { - "branch": "staging", - "paths": ["src/**/*.py", "src/**/*.js"] - }, - "action": "warn", - "message": "⚠️ Code changes on staging branch. Consider creating issue instead." - } - ] -} -``` - -### Environment-Aware Behavior - -**Key Design Decision:** Plugin behavior adapts to Git branch - -```typescript -// Branch detection in plugin -const CURRENT_BRANCH = getCurrentBranch(); -const MODE = detectMode(CURRENT_BRANCH); - -// Modify agent permissions based on mode -switch (MODE) { - case 'DEVELOPMENT': - // Full access - agents.planner.allowGiteaAPI = true; - agents.orchestrator.allowFileWrite = true; - break; - - case 'STAGING': - // Read-only code, can modify .env, can create issues - agents.planner.allowGiteaAPI = true; - agents.orchestrator.allowFileWrite = false; - agents.orchestrator.allowEnvWrite = true; - break; - - case 'PRODUCTION': - // Emergency mode only - agents.planner.allowGiteaAPI = true; // Create incidents - agents.orchestrator.allowFileWrite = false; - agents.orchestrator.allowEnvWrite = true; // Emergency only - break; -} -``` - -## Migration Strategy - -### Phase 1: MCP Server (Week 1) - -**Goal:** Replace Python scripts with MCP server - -**Tasks:** -1. Build `gitea-mcp` server in Node.js/TypeScript -2. Implement 5 core tools (list, create, update, get, comment) -3. Test with environment variables from CuisineFlow -4. Verify equivalent functionality to existing scripts - -**Success Criteria:** -- MCP server can create issues identical to `create_gitea_issue.py` -- MCP server can list issues identical to `list_gitea_issues.py` -- No regression in functionality - -### Phase 2: Agents (Week 2) - -**Goal:** Convert skills to agents - -**Tasks:** -1. Create `agents/planner.md` from `sprint-workflow.md` -2. Create `agents/orchestrator.md` from `sprint-orchestrator.md` -3. Create `agents/executor.md` from `sprint-executor.md` -4. Add agent-specific tool permissions -5. Test agent invocation via commands - -**Success Criteria:** -- `/sprint-plan` invokes planner agent correctly -- `/sprint-start` invokes orchestrator agent correctly -- Agents have distinct personalities and tool access - -### Phase 3: Commands (Week 2-3) - -**Goal:** Create user-facing slash commands - -**Tasks:** -1. Build 6 core commands (plan, start, status, issue-create, issue-list, deploy-check) -2. Connect commands to agents -3. Add branch detection to command behavior -4. Test command flow end-to-end - -**Success Criteria:** -- Commands invoke correct agents -- Branch restrictions work automatically -- User workflow feels natural - -### Phase 4: Hooks (Week 3) - -**Goal:** Automate repetitive tasks - -**Tasks:** -1. Implement post-task documentation sync -2. Add staging/production code change warnings -3. Auto-update issue status on merge -4. Test hook reliability - -**Success Criteria:** -- Hooks trigger at correct moments -- No false positives -- Improve workflow efficiency - -### Phase 5: Skills Refactor (Week 4) - -**Goal:** Convert orchestration skills to supporting knowledge - -**Tasks:** -1. Extract Gitea API patterns → `skills/gitea-api/SKILL.md` -2. Extract PM best practices → `skills/agile-pm/SKILL.md` -3. Extract Git workflows → `skills/branch-strategy/SKILL.md` -4. Remove duplication from agent prompts - -**Success Criteria:** -- Skills are referenced by agents, not primary orchestrators -- Less token usage per interaction -- Knowledge is reusable across agents - -### Phase 6: Local Testing (Week 4) - -**Goal:** Validate entire plugin in CuisineFlow - -**Tasks:** -1. Create local marketplace for testing -2. Install plugin in CuisineFlow project -3. Run through complete sprint cycle -4. Compare to current workflow -5. Fix issues and iterate - -**Success Criteria:** -- Plugin performs equivalently to current system -- Workflow feels smoother, not worse -- No major regressions - -### Phase 7: Distribution (Week 5) - -**Goal:** Package for others to use - -**Tasks:** -1. Write comprehensive README -2. Add installation instructions -3. Document configuration requirements -4. Create example `.env` template -5. Publish to plugin marketplace - -**Success Criteria:** -- Someone else can install and use it -- Clear documentation -- Configuration is straightforward - -## Directory Structure - -``` -projman/ -├── .claude-plugin/ -│ └── plugin.json -├── commands/ -│ ├── sprint-plan.md -│ ├── sprint-start.md -│ ├── sprint-status.md -│ ├── issue-create.md -│ ├── issue-list.md -│ └── deploy-check.md -├── agents/ -│ ├── planner.md -│ ├── orchestrator.md -│ └── executor.md -├── skills/ -│ ├── gitea-api/ -│ │ └── SKILL.md -│ ├── agile-pm/ -│ │ └── SKILL.md -│ └── branch-strategy/ -│ └── SKILL.md -├── hooks/ -│ └── hooks.json -├── .mcp.json -├── mcp-server/ -│ ├── package.json -│ ├── tsconfig.json -│ ├── gitea-server.ts -│ └── types.ts -├── README.md -├── LICENSE -└── CHANGELOG.md -``` - -## Key Decisions - -### Decision 1: MCP vs Direct API Calls in Commands - -**Choice:** Use MCP Server - -**Rationale:** -- Agents can use tools naturally in conversation -- Easier to test MCP server independently -- Future-proof for adding more integrations (Asana, Linear) -- Follows Claude Code best practices - -### Decision 2: Three Agents vs One Agent with Modes - -**Choice:** Three Distinct Agents - -**Rationale:** -- Clear separation of concerns matches Leo's three-chat workflow -- Each agent has distinct personality and tool access -- User knows exactly which agent they're talking to -- Prevents mode confusion - -### Decision 3: Branch Detection in Plugin vs CLAUDE.md - -**Choice:** Both - -**Rationale:** -- CLAUDE.md provides base-level permissions (file access) -- Plugin agents adapt behavior based on branch (tool usage) -- Defense in depth - two layers of protection -- Plugin works with or without CLAUDE.md - -### Decision 4: Skills as Orchestrators vs Knowledge - -**Choice:** Skills as Supporting Knowledge - -**Rationale:** -- Agents are the primary interface -- Skills reduce token usage (loaded only when relevant) -- Skills can be shared across agents -- Follows Anthropic's Agent Skills spec - -## Validated Requirements from Leo - -**Q1: Asana Integration** -- ✅ Build Gitea-only first, add Asana as separate MCP server later - -**Q2: Agent Invocation** -- ✅ Via commands only (`/sprint-plan` → planner agent) - -**Q3: Multi-Project Support** -- ✅ Two plugins needed: - - `projman`: Single-repo project management (build first) - - `projman-pmo`: Multi-project orchestration (build second) -- **Context:** Leo manages interdependent projects: - - CuisineFlow (main product) - - CuisineFlow-Site (demo sync + customer gateway) - - Intuit Engine Service (API aggregator extraction - imminent) - - HHL-Site (company presence) -- These have real deployment dependencies and require coordination - -**Q4: Deployment Environment** -- ✅ Same plugin on laptop + VPS servers, branch-aware behavior handles differences - -**Q5: Label System** -- ✅ Leo has sophisticated 43-label taxonomy at org level (enforced consistency) -- ✅ Include label suggestion in v1 -- ✅ Plugin maintains local reference, syncs from Gitea with agent review - -**Q6: Lessons Learned** -- ✅ Wiki-based implementation in v1 (NOT v2) -- **Critical pain point:** 15 sprints with no lesson capture causing repeated mistakes -- **Real example:** Claude Code infinite loops on same issues 2-3 times -- Must capture at sprint close, reference at sprint start - -## Success Metrics - -**Technical:** -- ✅ MCP server passes all integration tests -- ✅ Agents invoke correctly via commands -- ✅ Branch detection works 100% reliably -- ✅ No token usage increase vs current system - -**User Experience:** -- ✅ Leo completes sprint cycle faster than before -- ✅ Less context switching between chats -- ✅ Fewer manual script invocations -- ✅ Clearer agent personalities - -**Distribution:** -- ✅ Another PM can install and use it -- ✅ Documentation is clear enough -- ✅ Configuration takes <10 minutes - -## Next Steps - -**Immediate (Today):** -1. Leo reviews this analysis -2. Answer open questions (Q1-Q4) -3. Decide: build MCP server first or start with agents? - -**Short-term (This Week):** -1. Begin Phase 1 (MCP server) OR Phase 2 (agents) -2. Set up local marketplace for testing -3. Create `plugin.json` manifest - -**Medium-term (Next 2 Weeks):** -1. Complete Phases 1-4 (MCP, agents, commands, hooks) -2. Test in real CuisineFlow sprint -3. Iterate based on friction points - -## Anti-Over-Engineering Checklist - -Before building anything, verify: -- [ ] Have we done this manually 3+ times? ✅ (15 sprints) -- [ ] Is current system actually broken? ✅ (messy, but Leo identified pain points) -- [ ] Will plugin reduce friction? ✅ (fewer manual steps, clearer roles) -- [ ] Can we build incrementally? ✅ (7-phase plan) -- [ ] Is scope contained? ✅ (Gitea only, not all possible features) - -**Verdict:** This plugin is justified. Proceed with confidence. diff --git a/docs/references/projman-pmo/CORRECT-ARCHITECTURE.md b/docs/references/projman-pmo/CORRECT-ARCHITECTURE.md new file mode 100644 index 0000000..8bbb98e --- /dev/null +++ b/docs/references/projman-pmo/CORRECT-ARCHITECTURE.md @@ -0,0 +1,325 @@ +# DEFINITIVE ARCHITECTURE - FINAL CORRECT VERSION + +## ⚠️ THIS IS THE ONLY CORRECT STRUCTURE ⚠️ + +If you see ANY other structure in ANY other document, **THIS ONE IS CORRECT**. + +--- + +## Repository Structure (FINAL) + +``` +your-gitea/hyperhivelabs/claude-plugins/ +├── .claude-plugin/ +│ └── marketplace.json +├── mcp-servers/ # ← SHARED BY BOTH PLUGINS +│ ├── gitea/ +│ │ ├── .venv/ +│ │ ├── requirements.txt +│ │ ├── mcp_server/ +│ │ │ ├── __init__.py +│ │ │ ├── server.py +│ │ │ ├── config.py +│ │ │ ├── gitea_client.py +│ │ │ └── tools/ +│ │ │ ├── __init__.py +│ │ │ ├── issues.py +│ │ │ └── labels.py +│ │ └── tests/ +│ │ ├── test_config.py +│ │ ├── test_gitea_client.py +│ │ └── test_tools.py +│ └── wikijs/ +│ ├── .venv/ +│ ├── requirements.txt +│ ├── mcp_server/ +│ │ ├── __init__.py +│ │ ├── server.py +│ │ ├── config.py +│ │ ├── wikijs_client.py +│ │ └── tools/ +│ │ ├── __init__.py +│ │ ├── pages.py +│ │ ├── lessons_learned.py +│ │ └── documentation.py +│ └── tests/ +│ ├── test_config.py +│ ├── test_wikijs_client.py +│ └── test_tools.py +├── projman/ # ← PROJECT PLUGIN +│ ├── .claude-plugin/ +│ │ └── plugin.json +│ ├── .mcp.json # Points to ../mcp-servers/ +│ ├── commands/ +│ │ ├── sprint-plan.md +│ │ ├── sprint-start.md +│ │ ├── sprint-status.md +│ │ ├── sprint-close.md +│ │ └── labels-sync.md +│ ├── agents/ +│ │ ├── planner.md +│ │ ├── orchestrator.md +│ │ └── executor.md +│ ├── skills/ +│ │ └── label-taxonomy/ +│ │ └── labels-reference.md +│ ├── README.md +│ └── CONFIGURATION.md +└── projman-pmo/ # ← PMO PLUGIN + ├── .claude-plugin/ + │ └── plugin.json + ├── .mcp.json # Points to ../mcp-servers/ + ├── commands/ + │ ├── pmo-status.md + │ ├── pmo-priorities.md + │ ├── pmo-dependencies.md + │ └── pmo-schedule.md + ├── agents/ + │ └── pmo-coordinator.md + └── README.md +``` + +--- + +## Key Points + +### 1. MCP Servers Are SHARED +- Location: `mcp-servers/` at repository root +- NOT inside `projman/` or `projman-pmo/` +- Built ONCE, used by BOTH plugins + +### 2. Plugins Reference MCP Servers +- Both plugins use `.mcp.json` to point to `../mcp-servers/` +- No MCP code inside plugin directories +- Only commands, agents, and skills in plugin directories + +### 3. Mode Detection +- MCP servers detect mode based on environment variables +- Project mode: When `GITEA_REPO` and `WIKIJS_PROJECT` present +- Company mode: When those variables absent (PMO) + +--- + +## Configuration Files + +### projman/.mcp.json + +```json +{ + "mcpServers": { + "gitea-projman": { + "command": "python", + "args": ["-m", "mcp_server.server"], + "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea", + "env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea", + "GITEA_API_URL": "${GITEA_API_URL}", + "GITEA_API_TOKEN": "${GITEA_API_TOKEN}", + "GITEA_OWNER": "${GITEA_OWNER}", + "GITEA_REPO": "${GITEA_REPO}" + } + }, + "wikijs-projman": { + "command": "python", + "args": ["-m", "mcp_server.server"], + "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs", + "env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs", + "WIKIJS_API_URL": "${WIKIJS_API_URL}", + "WIKIJS_API_TOKEN": "${WIKIJS_API_TOKEN}", + "WIKIJS_BASE_PATH": "${WIKIJS_BASE_PATH}", + "WIKIJS_PROJECT": "${WIKIJS_PROJECT}" + } + } + } +} +``` + +### projman-pmo/.mcp.json + +```json +{ + "mcpServers": { + "gitea-pmo": { + "command": "python", + "args": ["-m", "mcp_server.server"], + "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea", + "env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea", + "GITEA_API_URL": "${GITEA_API_URL}", + "GITEA_API_TOKEN": "${GITEA_API_TOKEN}", + "GITEA_OWNER": "${GITEA_OWNER}" + } + }, + "wikijs-pmo": { + "command": "python", + "args": ["-m", "mcp_server.server"], + "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs", + "env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs", + "WIKIJS_API_URL": "${WIKIJS_API_URL}", + "WIKIJS_API_TOKEN": "${WIKIJS_API_TOKEN}", + "WIKIJS_BASE_PATH": "${WIKIJS_BASE_PATH}" + } + } + } +} +``` + +**Critical:** Both plugins point to `../mcp-servers/` using relative paths. + +--- + +## Setup Instructions + +### 1. System Configuration + +```bash +# Create config directory +mkdir -p ~/.config/claude + +# Gitea config +cat > ~/.config/claude/gitea.env << EOF +GITEA_API_URL=https://gitea.hyperhivelabs.com/api/v1 +GITEA_API_TOKEN=your_token +GITEA_OWNER=hyperhivelabs +EOF + +# Wiki.js config +cat > ~/.config/claude/wikijs.env << EOF +WIKIJS_API_URL=https://wiki.hyperhivelabs.com/graphql +WIKIJS_API_TOKEN=your_token +WIKIJS_BASE_PATH=/hyper-hive-labs +EOF + +# Secure files +chmod 600 ~/.config/claude/*.env +``` + +### 2. Project Configuration + +```bash +# In each project root +cat > .env << EOF +GITEA_REPO=cuisineflow +WIKIJS_PROJECT=projects/cuisineflow +EOF + +# Add to .gitignore +echo ".env" >> .gitignore +``` + +### 3. Install MCP Servers (ONE TIME) + +```bash +# Gitea MCP Server +cd /path/to/claude-plugins/mcp-servers/gitea +python -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt + +# Wiki.js MCP Server +cd /path/to/claude-plugins/mcp-servers/wikijs +python -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +``` + +--- + +## What Makes This Work + +### Mode Detection in config.py + +```python +# mcp-servers/gitea/mcp_server/config.py +def load(self): + # ... load configs ... + + self.repo = os.getenv('GITEA_REPO') # Optional + + if self.repo: + self.mode = 'project' + logger.info(f"Running in project mode: {self.repo}") + else: + self.mode = 'company' + logger.info("Running in company-wide mode (PMO)") + + return { + 'api_url': self.api_url, + 'api_token': self.api_token, + 'owner': self.owner, + 'repo': self.repo, + 'mode': self.mode + } +``` + +### Same MCP Code, Different Behavior + +The SAME MCP server code runs differently based on environment variables: + +**When projman calls it:** +- Has `GITEA_REPO` → operates on single repository +- Has `WIKIJS_PROJECT` → operates on single project path + +**When projman-pmo calls it:** +- No `GITEA_REPO` → operates on all repositories +- No `WIKIJS_PROJECT` → operates on entire company namespace + +--- + +## Visual Path Flow + +### projman Plugin Flow +``` +projman/.mcp.json + ↓ (cwd: ../mcp-servers/gitea) +mcp-servers/gitea/mcp_server/server.py + ↓ (loads config) +mcp-servers/gitea/mcp_server/config.py + ↓ (detects GITEA_REPO present) + → PROJECT MODE +``` + +### projman-pmo Plugin Flow +``` +projman-pmo/.mcp.json + ↓ (cwd: ../mcp-servers/gitea) +mcp-servers/gitea/mcp_server/server.py + ↓ (loads config) +mcp-servers/gitea/mcp_server/config.py + ↓ (detects NO GITEA_REPO) + → COMPANY MODE +``` + +--- + +## File Paths Quick Reference + +### Gitea MCP Server Files +- Config loader: `mcp-servers/gitea/mcp_server/config.py` +- API client: `mcp-servers/gitea/mcp_server/gitea_client.py` +- Server entry: `mcp-servers/gitea/mcp_server/server.py` +- Issue tools: `mcp-servers/gitea/mcp_server/tools/issues.py` +- Label tools: `mcp-servers/gitea/mcp_server/tools/labels.py` + +### Wiki.js MCP Server Files +- Config loader: `mcp-servers/wikijs/mcp_server/config.py` +- API client: `mcp-servers/wikijs/mcp_server/wikijs_client.py` +- Server entry: `mcp-servers/wikijs/mcp_server/server.py` +- Page tools: `mcp-servers/wikijs/mcp_server/tools/pages.py` +- Lessons tools: `mcp-servers/wikijs/mcp_server/tools/lessons_learned.py` + +### Plugin Files +- projman config: `projman/.mcp.json` +- projman-pmo config: `projman-pmo/.mcp.json` + +--- + +## This Is The Truth + +**If ANY other document shows MCP servers inside plugin directories, that document is WRONG.** + +**THIS document shows the CORRECT, FINAL architecture.** + +Use this as your reference. Period. \ No newline at end of file diff --git a/docs/references/projman-pmo/DOCUMENT-INDEX.md b/docs/references/projman-pmo/DOCUMENT-INDEX.md new file mode 100644 index 0000000..3765078 --- /dev/null +++ b/docs/references/projman-pmo/DOCUMENT-INDEX.md @@ -0,0 +1,241 @@ +# ProjMan Implementation - Document Index + +All documentation for building the projman and projman-pmo plugins. + +--- + +## ⚠️ START HERE - CORRECT ARCHITECTURE + +### [CORRECT-ARCHITECTURE.md](./CORRECT-ARCHITECTURE.md) +**⚠️ THIS IS THE DEFINITIVE REFERENCE ⚠️** +**Use when:** You need to verify the correct repository structure +**Contains:** +- THE ONLY CORRECT repository structure +- MCP servers are SHARED at root level (`mcp-servers/` directory) +- Configuration file examples +- Setup instructions +- Path references +- Mode detection implementation + +**If any other document conflicts with this, THIS ONE IS CORRECT.** + +--- + +## 📚 Core Implementation Documents + +### [projman-implementation-plan-updated.md](./projman-implementation-plan-updated.md) +**Purpose:** Complete, detailed implementation plan +**Use when:** Actually building the plugins (your main reference) +**Contains:** +- 12 detailed implementation phases +- Configuration architecture +- Complete code examples +- Success criteria per phase +- Testing strategies +- No timelines - work at your pace +- **Length:** Comprehensive (2000+ lines) + +--- + +## 🐍 Python-Specific Guides + +### [projman-python-quickstart.md](./projman-python-quickstart.md) +**Purpose:** Python-specific implementation guide +**Use when:** Setting up Python environment, writing code +**Contains:** +- Python project structure +- Virtual environment setup +- Requirements.txt examples +- Configuration loader code +- Modular code patterns +- Testing with pytest +- Debugging tips + +--- + +## 🏗️ Architecture Documentation + +### [two-mcp-architecture-guide.md](./two-mcp-architecture-guide.md) +**Purpose:** Deep dive into two-MCP-server architecture +**Use when:** Understanding the MCP server design +**Contains:** +- Wiki.js structure at `/hyper-hive-labs` +- Complete Gitea MCP server code +- Complete Wiki.js MCP server code (GraphQL) +- Configuration examples +- Mode detection implementation +- Setup instructions +- Migration guidance + +--- + +## 🎯 How to Use These Documents + +### Phase 1: Planning & Setup +1. Read **CORRECT-ARCHITECTURE.md** to understand the definitive repository structure +2. Review **projman-implementation-plan-updated.md** Phase 1 for setup overview +3. Set up your Gitea and Wiki.js instances +4. Create system-level configuration files + +### Phase 2: Starting Implementation +1. Open **projman-implementation-plan-updated.md** (your main reference for all 12 phases) +2. Start with Phase 1.1a (Gitea MCP Server) +3. Reference **projman-python-quickstart.md** for Python patterns and virtual environment setup +4. Reference **two-mcp-architecture-guide.md** for detailed MCP server code examples + +### Phase 3: During Development +1. **Main reference:** projman-implementation-plan-updated.md (follow phase by phase) +2. **Structure reference:** CORRECT-ARCHITECTURE.md (when in doubt about paths) +3. **Code patterns:** projman-python-quickstart.md +4. **Architecture deep dive:** two-mcp-architecture-guide.md + +### Phase 4: Troubleshooting +1. Check **CORRECT-ARCHITECTURE.md** for definitive path references +2. Review configuration examples in **two-mcp-architecture-guide.md** +3. Check Python-specific debugging in **projman-python-quickstart.md** +4. Verify setup instructions in **projman-implementation-plan-updated.md** Phase 1.3 + +--- + +## 📖 Document Relationships + +``` +CORRECT-ARCHITECTURE.md (definitive structure) + ↓ (referenced by) + ├── projman-implementation-plan-updated.md (main implementation guide) + │ ↓ (uses Python patterns from) + │ ├── projman-python-quickstart.md + │ ↓ (references architecture from) + │ └── two-mcp-architecture-guide.md + └── DOCUMENT-INDEX.md (this file - navigation) +``` + +--- + +## 🎨 Quick Reference by Topic + +### Repository Structure +- **Definitive reference:** CORRECT-ARCHITECTURE.md (lines 9-80) +- **Key point:** MCP servers are SHARED at `mcp-servers/` directory (not inside plugins) + +### Configuration +- **Setup instructions:** CORRECT-ARCHITECTURE.md (lines 172-229) +- **Implementation details:** projman-implementation-plan-updated.md (Phase 1.3) +- **Python code examples:** projman-python-quickstart.md (lines 140-214) +- **Config loader:** two-mcp-architecture-guide.md (lines 281-358) + +### MCP Servers +- **Architecture overview:** CORRECT-ARCHITECTURE.md (Key Points section) +- **Gitea MCP:** projman-implementation-plan-updated.md (Phase 1.1a) +- **Wiki.js MCP:** projman-implementation-plan-updated.md (Phase 1.1b) +- **Complete implementation:** two-mcp-architecture-guide.md (lines 277-680) + +### Wiki.js Structure +- **Full structure:** two-mcp-architecture-guide.md (lines 13-70) +- **Path resolution:** projman-implementation-plan-updated.md (lines 110-115) +- **Integration:** projman-implementation-plan-updated.md (Phase 4.1) + +### Python Patterns +- **Setup & dependencies:** projman-python-quickstart.md (lines 15-111) +- **Modular code structure:** projman-python-quickstart.md (lines 511-575) +- **Virtual environment:** projman-python-quickstart.md (lines 579-616) + +### Sprint Workflow +- **Commands:** projman-implementation-plan-updated.md (Phase 2) +- **Agents:** projman-implementation-plan-updated.md (Phase 3) +- **Lessons Learned:** projman-implementation-plan-updated.md (Phase 4) + +### PMO Plugin +- **Requirements:** projman-implementation-plan-updated.md (Phase 9) +- **Implementation:** projman-implementation-plan-updated.md (Phase 10-11) +- **Multi-project methods:** two-mcp-architecture-guide.md (lines 639-679) + +--- + +## 🚀 Suggested Reading Order + +### First Time (Understanding the Project) +1. **CORRECT-ARCHITECTURE.md** (15 minutes) + - Understand the definitive repository structure + - See MCP server placement (shared at root) + - Review configuration approach + +2. **projman-python-quickstart.md** (30 minutes) + - Understand Python setup + - See code patterns + - Virtual environment setup + +3. **projman-implementation-plan-updated.md** (2-3 hours) + - Read Phase 1 in detail + - Skim Phases 2-12 to understand the flow + - This is your main implementation guide + +4. **two-mcp-architecture-guide.md** (1 hour) + - Deep dive into MCP server architecture + - Complete code examples + - Wiki.js structure and integration + +### During Implementation +- Keep **projman-implementation-plan-updated.md** open (your main reference) +- Reference **CORRECT-ARCHITECTURE.md** when unsure about paths +- Use **projman-python-quickstart.md** for Python-specific code +- Use **two-mcp-architecture-guide.md** for detailed MCP implementation + +### When You Need Quick Answers +- **"What's the correct repository structure?"** → CORRECT-ARCHITECTURE.md +- **"How do I set up Python?"** → projman-python-quickstart.md +- **"How does configuration work?"** → CORRECT-ARCHITECTURE.md or two-mcp-architecture-guide.md +- **"What's the full MCP server code?"** → two-mcp-architecture-guide.md +- **"What do I build in Phase X?"** → projman-implementation-plan-updated.md + +--- + +## 📊 Document Statistics + +| Document | Lines | Focus | Primary Use | +|----------|-------|-------|-------------| +| CORRECT-ARCHITECTURE.md | 325 | Definitive Structure | Reference (paths, config) | +| projman-implementation-plan-updated.md | 2081 | Complete Implementation | Main guide (building) | +| projman-python-quickstart.md | 727 | Python Patterns | Code patterns & setup | +| two-mcp-architecture-guide.md | 941 | Architecture Deep Dive | MCP implementation | + +**Total:** ~4,074 lines of comprehensive documentation + +--- + +## ✅ Pre-Implementation Checklist + +Before starting Phase 1, verify you have: +- [ ] Read CORRECT-ARCHITECTURE.md (understand structure) +- [ ] Understand the two-MCP-server architecture (Gitea + Wiki.js) +- [ ] Understand shared MCP codebase at `mcp-servers/` (not in plugin dirs) +- [ ] Understand Wiki.js structure at `/hyper-hive-labs` +- [ ] Understand hybrid configuration (system + project levels) +- [ ] Python 3.11+ installed +- [ ] Access to Gitea instance +- [ ] Access to Wiki.js instance +- [ ] API tokens for both services + +--- + +## 🎯 Key Architectural Decisions + +These are the final decisions documented across all files: + +1. **Two MCP Servers** - Separate Gitea and Wiki.js servers for better maintainability +2. **Shared MCP Codebase** - Located at `mcp-servers/` (root level), used by both plugins +3. **Python Implementation** - MCP servers written in Python 3.11+ +4. **Hybrid Configuration** - System-level tokens + project-level paths +5. **Wiki.js for Lessons** - Superior to Git-based Wiki for documentation and search +6. **Mode Detection** - MCP servers detect project vs company-wide mode via environment variables +7. **Build Order** - projman first (Phases 1-8), then projman-pmo (Phases 9-12) + +--- + +## 🎉 You're Ready! + +You have everything you need to build the projman and projman-pmo plugins. All architectural decisions are finalized and documented. + +**Start here:** [projman-implementation-plan-updated.md](./projman-implementation-plan-updated.md) - Phase 1.1a + +Good luck with the build! \ No newline at end of file diff --git a/docs/references/projman-pmo/projman-implementation-plan-updated.md b/docs/references/projman-pmo/projman-implementation-plan-updated.md new file mode 100644 index 0000000..c16d77e --- /dev/null +++ b/docs/references/projman-pmo/projman-implementation-plan-updated.md @@ -0,0 +1,2086 @@ +# ProjMan Plugin Suite - Implementation Plan + +**Plugins:** `projman` (single-repo) + `projman-pmo` (multi-project) +**Build Order:** projman first, then projman-pmo +**Label System:** Type/Refactor now implemented at organization level +**Configuration:** Hybrid approach (system + project level) +**Technology Stack:** Python (MCP server), Markdown (commands/agents) + +> **⚠️ IMPORTANT:** For the definitive, authoritative repository structure, always refer to [CORRECT-ARCHITECTURE.md](./CORRECT-ARCHITECTURE.md). If this document conflicts with CORRECT-ARCHITECTURE.md, CORRECT-ARCHITECTURE.md is correct. + +--- + +## Configuration Architecture + +### Two MCP Server Design (Shared Codebase) + +**Architecture Decision:** +Both plugins (projman and projman-pmo) **share the same MCP server codebase**. The MCP servers detect their mode (project-scoped vs company-wide) based on environment variables. + +**Separation of Concerns:** +- **Gitea MCP Server**: Issues, labels, repository data +- **Wiki.js MCP Server**: Documentation, lessons learned, knowledge base + +**Repository Structure:** +``` +hyperhivelabs/claude-plugins/ +├── mcp-servers/ # Shared by both plugins +│ ├── gitea/ +│ └── wikijs/ +├── projman/ # Project plugin +└── projman-pmo/ # PMO plugin +``` + +**Benefits:** +✅ Single source of truth - fix bugs once, both plugins benefit +✅ Less code duplication and maintenance +✅ MCP servers already handle both modes +✅ Independent service configuration (Gitea vs Wiki.js) +✅ Can enable/disable each service independently +✅ Wiki.js shared across entire company (not just projects) +✅ Easier to maintain and debug +✅ Professional architecture + +### System-Level Configuration (Shared) + +**Gitea Configuration:** +**Location:** `~/.config/claude/gitea.env` + +```bash +GITEA_API_URL=https://gitea.hyperhivelabs.com/api/v1 +GITEA_API_TOKEN=your_gitea_token +GITEA_OWNER=hyperhivelabs +``` + +**Wiki.js Configuration:** +**Location:** `~/.config/claude/wikijs.env` + +```bash +WIKIJS_API_URL=https://wiki.hyperhivelabs.com/graphql +WIKIJS_API_TOKEN=your_wikijs_token +WIKIJS_BASE_PATH=/hyper-hive-labs +``` + +**Used by:** Both projman and pmo plugins + +### Project-Level Configuration + +**Location:** `project-root/.env` + +**Contains:** +```bash +# Gitea repository name +GITEA_REPO=cuisineflow + +# Wiki.js project path (relative to /hyper-hive-labs) +WIKIJS_PROJECT=projects/cuisineflow +``` + +**Used by:** projman plugin only (pmo operates across all repos/projects) + +### Wiki.js Structure + +``` +Wiki.js +└── hyper-hive-labs/ + ├── projects/ # Project-specific documentation + │ ├── cuisineflow/ + │ │ ├── lessons-learned/ + │ │ │ ├── sprints/ + │ │ │ └── INDEX.md + │ │ └── documentation/ + │ │ ├── architecture/ + │ │ └── api/ + │ ├── cuisineflow-site/ + │ │ ├── lessons-learned/ + │ │ └── documentation/ + │ ├── intuit-engine/ + │ │ ├── lessons-learned/ + │ │ └── documentation/ + │ └── hhl-site/ + │ ├── lessons-learned/ + │ └── documentation/ + ├── company/ # Company-wide documentation + │ ├── processes/ + │ ├── onboarding/ + │ ├── standards/ + │ └── tools/ + └── shared/ # Cross-project resources + ├── architecture-patterns/ + ├── best-practices/ + └── tech-stack/ +``` + +**Path Resolution:** +- **projman**: `{WIKIJS_BASE_PATH}/{WIKIJS_PROJECT}` → `/hyper-hive-labs/projects/cuisineflow` +- **projman-pmo**: `{WIKIJS_BASE_PATH}` → `/hyper-hive-labs` (entire company namespace) + +### Benefits + +✅ Single token per service - update once +✅ Project isolation - each repo declares its paths +✅ Company-wide documentation accessible +✅ PMO can see all projects +✅ Shared resources available to all +✅ Security - tokens never committed +✅ Portability - same system config for all projects +✅ Scalable - easy to add new projects + +--- + +## Phase 1: Core Infrastructure (projman) + +### 1.1 MCP Server Foundation (Shared Infrastructure) + +**Deliverable:** Two working MCP servers (Gitea and Wiki.js) with hybrid configuration, shared by both projman and projman-pmo plugins + +**Important:** These MCP servers are built ONCE and shared by both plugins. They detect their operating mode (project-scoped vs company-wide) based on environment variables. + +--- + +#### 1.1a Gitea MCP Server + +**Tasks:** + +**Configuration Setup:** +- Design environment variable loading strategy: + - System-level: `~/.config/claude/gitea.env` + - Project-level: `project-root/.env` + - Merge strategy: project overrides system +- Create `.env.example` template +- Document configuration precedence rules +- Add validation for required variables + +**MCP Server Implementation:** +- Set up Python project structure +- Create virtual environment (.venv) +- Install dependencies: + ``` + # requirements.txt + anthropic-sdk>=0.18.0 + python-dotenv>=1.0.0 + requests>=2.31.0 + pydantic>=2.5.0 + pytest>=7.4.3 + ``` +- Implement Gitea API authentication +- Create environment variable loader: + ```python + # config.py + from pathlib import Path + from dotenv import load_dotenv + import os + + def load_config(): + """Load configuration from system and project levels""" + # Load system config + system_config = Path.home() / '.config' / 'claude' / 'gitea.env' + if system_config.exists(): + load_dotenv(system_config) + + # Load project config (overrides system) + project_config = Path.cwd() / '.env' + if project_config.exists(): + load_dotenv(project_config, override=True) + + # Validate required variables + required = ['GITEA_API_URL', 'GITEA_API_TOKEN', 'GITEA_OWNER'] + missing = [var for var in required if not os.getenv(var)] + if missing: + raise ValueError(f"Missing config: {', '.join(missing)}") + + return { + 'api_url': os.getenv('GITEA_API_URL'), + 'api_token': os.getenv('GITEA_API_TOKEN'), + 'owner': os.getenv('GITEA_OWNER'), + 'repo': os.getenv('GITEA_REPO') # Optional for PMO + } + ``` +- Validate all required variables present +- Create 7 core tools: + - `list_issues` - Query issues with filters + - `get_issue` - Fetch single issue details + - `create_issue` - Create new issue with labels + - `update_issue` - Modify existing issue + - `add_comment` - Add comments to issues + - `get_labels` - Fetch org + repo label taxonomy + - `suggest_labels` - Analyze context and suggest appropriate labels + +**Testing:** +- Write integration tests against actual Gitea instance +- Test configuration loading from both levels +- Test missing configuration error handling +- Test API authentication with loaded credentials + +**Success Criteria:** +- Configuration loads from both system and project levels +- Missing variables produce clear error messages +- All tools pass integration tests +- Label suggestion correctly identifies Type/Refactor +- Error handling for network failures and API rate limits + +--- + +#### 1.1b Wiki.js MCP Server + +**Tasks:** + +**Configuration Setup:** +- Design environment variable loading strategy: + - System-level: `~/.config/claude/wikijs.env` + - Project-level: `project-root/.env` + - Path composition: `{BASE_PATH}/{PROJECT_PATH}` +- Create `.env.example` template +- Document path resolution rules +- Add validation for required variables + +**MCP Server Implementation:** +- Set up Python project structure (separate from Gitea MCP) +- Create virtual environment (.venv) +- Install dependencies: + ``` + # requirements.txt + anthropic-sdk>=0.18.0 + python-dotenv>=1.0.0 + gql>=3.4.0 # GraphQL client for Wiki.js + aiohttp>=3.9.0 # Async HTTP + pydantic>=2.5.0 + pytest>=7.4.3 + pytest-asyncio>=0.23.0 + ``` +- Implement Wiki.js GraphQL authentication +- Create environment variable loader: + ```python + # config.py + from pathlib import Path + from dotenv import load_dotenv + import os + + def load_config(): + """Load Wiki.js configuration from system and project levels""" + # Load system config + system_config = Path.home() / '.config' / 'claude' / 'wikijs.env' + if system_config.exists(): + load_dotenv(system_config) + + # Load project config (overrides system) + project_config = Path.cwd() / '.env' + if project_config.exists(): + load_dotenv(project_config, override=True) + + # Validate required variables + required = ['WIKIJS_API_URL', 'WIKIJS_API_TOKEN', 'WIKIJS_BASE_PATH'] + missing = [var for var in required if not os.getenv(var)] + if missing: + raise ValueError(f"Missing config: {', '.join(missing)}") + + # Compose full path + base_path = os.getenv('WIKIJS_BASE_PATH') # /hyper-hive-labs + project_path = os.getenv('WIKIJS_PROJECT') # projects/cuisineflow + + full_path = f"{base_path}/{project_path}" if project_path else base_path + + return { + 'api_url': os.getenv('WIKIJS_API_URL'), + 'api_token': os.getenv('WIKIJS_API_TOKEN'), + 'base_path': base_path, + 'project_path': project_path, + 'full_path': full_path + } + ``` +- Validate all required variables present +- Create 8 core tools: + - `search_pages` - Search Wiki.js pages by keywords/tags + - `get_page` - Fetch specific page content + - `create_page` - Create new Wiki page + - `update_page` - Modify existing page + - `list_pages` - List pages in a path + - `create_lesson` - Create lessons learned document + - `search_lessons` - Search past lessons by tags + - `tag_lesson` - Add tags to lessons learned + +**GraphQL Client Example:** +```python +# wikijs_client.py +from gql import gql, Client +from gql.transport.aiohttp import AIOHTTPTransport + +class WikiJSClient: + def __init__(self, api_url: str, api_token: str): + transport = AIOHTTPTransport( + url=api_url, + headers={'Authorization': f'Bearer {api_token}'} + ) + self.client = Client(transport=transport, fetch_schema_from_transport=True) + + async def search_pages(self, query: str, path: str = None): + """Search pages in Wiki.js""" + gql_query = gql(""" + query SearchPages($query: String!, $path: String) { + pages { + search(query: $query, path: $path) { + results { + id + path + title + description + tags + } + } + } + } + """) + + result = await self.client.execute( + gql_query, + variable_values={'query': query, 'path': path} + ) + return result['pages']['search']['results'] + + async def create_page(self, path: str, title: str, content: str, tags: list): + """Create a new page in Wiki.js""" + gql_mutation = gql(""" + mutation CreatePage($path: String!, $title: String!, $content: String!, $tags: [String]!) { + pages { + create( + path: $path + title: $title + content: $content + tags: $tags + ) { + responseResult { + succeeded + errorCode + message + } + page { + id + path + } + } + } + } + """) + + result = await self.client.execute( + gql_mutation, + variable_values={ + 'path': path, + 'title': title, + 'content': content, + 'tags': tags + } + ) + return result['pages']['create'] +``` + +**Testing:** +- Write integration tests against actual Wiki.js instance +- Test configuration loading from both levels +- Test path composition and resolution +- Test GraphQL queries and mutations +- Test authentication with Wiki.js + +**Success Criteria:** +- Configuration loads from both system and project levels +- Path composition works correctly +- Missing variables produce clear error messages +- All tools pass integration tests +- GraphQL queries execute successfully +- Error handling for network failures and API rate limits +- Lessons learned can be created and searched + +### 1.2 Label Taxonomy System + +**Deliverable:** Label reference with sync capability + +**Tasks:** +- Create `skills/label-taxonomy/` directory structure +- Port `gitea-labels-reference.md` to plugin +- Document exclusive vs non-exclusive label rules +- Build label suggestion logic: + - Type detection (Bug, Feature, Refactor, etc.) + - Component identification from context + - Priority inference from keywords + - Source detection based on branch +- Create `/labels-sync` command +- Implement diff viewer for label changes +- Build interactive review workflow + +**Label Sync Workflow:** +``` +User: /labels-sync +Agent: Fetching labels from Gitea... + Found 1 new label: Type/Documentation + Found 2 modified descriptions + + New: Type/Documentation + - For documentation-only changes + - Should update suggestion logic to detect "docs", "readme" + + Modified: Priority/High + - Description clarified: "Blocks sprint completion" + + Shall I update the local reference and suggestion rules? +User: Yes +Agent: Updated ✅ + - labels-reference.md updated + - Suggestion logic updated + - 43 labels now in taxonomy +``` + +**Success Criteria:** +- Complete 43-label taxonomy documented +- Sync command fetches live data from Gitea +- Diff detection works correctly +- Agent provides meaningful impact analysis +- Local reference stays synchronized + +### 1.3 Plugin Manifest & Structure + +**Deliverable:** Complete projman plugin structure + +**Tasks:** +- Create `.claude-plugin/plugin.json` +- Set up repository structure: + ``` + hyperhivelabs/claude-plugins/ + ├── mcp-servers/ # Shared by both plugins + │ ├── gitea/ + │ │ ├── .venv/ + │ │ ├── requirements.txt + │ │ ├── .env.example + │ │ ├── mcp_server/ + │ │ │ ├── __init__.py + │ │ │ ├── server.py + │ │ │ ├── config.py # Detects project/company mode + │ │ │ └── gitea_client.py + │ │ └── tests/ + │ └── wikijs/ + │ ├── .venv/ + │ ├── requirements.txt + │ ├── .env.example + │ ├── mcp_server/ + │ │ ├── __init__.py + │ │ ├── server.py + │ │ ├── config.py # Detects project/company mode + │ │ └── wikijs_client.py + │ └── tests/ + ├── projman/ # Project plugin + │ ├── .claude-plugin/ + │ │ └── plugin.json + │ ├── .mcp.json # References ../mcp-servers/ + │ ├── commands/ + │ │ └── (will add in Phase 2) + │ ├── agents/ + │ │ └── (will add in Phase 3) + │ ├── skills/ + │ │ └── label-taxonomy/ + │ │ └── labels-reference.md + │ ├── README.md + │ └── CONFIGURATION.md + └── projman-pmo/ # PMO plugin + ├── .claude-plugin/ + │ └── plugin.json + ├── .mcp.json # References ../mcp-servers/ + ├── commands/ + │ └── (will add in Phase 10) + ├── agents/ + │ └── (will add in Phase 9) + └── README.md + ``` +- Write README with installation instructions +- Create CONFIGURATION.md with hybrid config setup for both services +- Document setup steps: + 1. Create system configs (Gitea + Wiki.js) + 2. Create project .env + 3. Create virtual environments for both MCP servers (once, in mcp-servers/) + 4. Install dependencies with pip + 5. Test connections + +**Mode Detection in MCP Servers:** +```python +# mcp-servers/gitea/mcp_server/config.py +class GiteaConfig: + def load(self): + # ... load configs ... + + self.repo = os.getenv('GITEA_REPO') # Optional + + if self.repo: + self.mode = 'project' + logger.info(f"Running in project mode: {self.repo}") + else: + self.mode = 'company' + logger.info("Running in company-wide mode (PMO)") + + return { + 'api_url': self.api_url, + 'api_token': self.api_token, + 'owner': self.owner, + 'repo': self.repo, + 'mode': self.mode + } +``` + +**Configuration Files:** + +**projman/.mcp.json:** +```json +{ + "mcpServers": { + "gitea-projman": { + "command": "python", + "args": ["-m", "mcp_server.server"], + "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea", + "env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea", + "GITEA_API_URL": "${GITEA_API_URL}", + "GITEA_API_TOKEN": "${GITEA_API_TOKEN}", + "GITEA_OWNER": "${GITEA_OWNER}", + "GITEA_REPO": "${GITEA_REPO}" + } + }, + "wikijs-projman": { + "command": "python", + "args": ["-m", "mcp_server.server"], + "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs", + "env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs", + "WIKIJS_API_URL": "${WIKIJS_API_URL}", + "WIKIJS_API_TOKEN": "${WIKIJS_API_TOKEN}", + "WIKIJS_BASE_PATH": "${WIKIJS_BASE_PATH}", + "WIKIJS_PROJECT": "${WIKIJS_PROJECT}" + } + } + } +} +``` + +**projman-pmo/.mcp.json:** +```json +{ + "mcpServers": { + "gitea-pmo": { + "command": "python", + "args": ["-m", "mcp_server.server"], + "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea", + "env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea", + "GITEA_API_URL": "${GITEA_API_URL}", + "GITEA_API_TOKEN": "${GITEA_API_TOKEN}", + "GITEA_OWNER": "${GITEA_OWNER}" + } + }, + "wikijs-pmo": { + "command": "python", + "args": ["-m", "mcp_server.server"], + "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs", + "env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs", + "WIKIJS_API_URL": "${WIKIJS_API_URL}", + "WIKIJS_API_TOKEN": "${WIKIJS_API_TOKEN}", + "WIKIJS_BASE_PATH": "${WIKIJS_BASE_PATH}" + } + } + } +} +``` + +**Note:** Both plugins reference `../mcp-servers/` (shared location). The MCP servers detect their mode based on which environment variables are present. + +**Configuration Documentation:** + +**CONFIGURATION.md structure:** +```markdown +# Configuration Setup + +## System-Level (Required for all projects) + +### Gitea Configuration + +1. Create config directory: + mkdir -p ~/.config/claude + +2. Create gitea.env: + cat > ~/.config/claude/gitea.env << EOF + GITEA_API_URL=https://gitea.hyperhivelabs.com/api/v1 + GITEA_API_TOKEN=your_gitea_token + GITEA_OWNER=hyperhivelabs + EOF + +3. Secure the file: + chmod 600 ~/.config/claude/gitea.env + +### Wiki.js Configuration + +1. Create wikijs.env: + cat > ~/.config/claude/wikijs.env << EOF + WIKIJS_API_URL=https://wiki.hyperhivelabs.com/graphql + WIKIJS_API_TOKEN=your_wikijs_token + WIKIJS_BASE_PATH=/hyper-hive-labs + EOF + +2. Secure the file: + chmod 600 ~/.config/claude/wikijs.env + +## Project-Level (Per repository) + +1. Create .env in project root: + cat > .env << EOF + GITEA_REPO=cuisineflow + WIKIJS_PROJECT=projects/cuisineflow + EOF + +2. Add to .gitignore: + echo ".env" >> .gitignore + +## MCP Server Setup (One-Time, Shared by Both Plugins) + +### Gitea MCP Server + +1. Navigate to shared MCP directory: + cd /path/to/claude-plugins/mcp-servers/gitea + +2. Create virtual environment: + python -m venv .venv + +3. Activate virtual environment: + source .venv/bin/activate # Linux/Mac + .venv\Scripts\activate # Windows + +4. Install dependencies: + pip install -r requirements.txt + +### Wiki.js MCP Server + +1. Navigate to Wiki.js MCP directory: + cd /path/to/claude-plugins/mcp-servers/wikijs + +2. Create virtual environment: + python -m venv .venv + +3. Activate virtual environment: + source .venv/bin/activate # Linux/Mac + .venv\Scripts\activate # Windows + +4. Install dependencies: + pip install -r requirements.txt + +## Wiki.js Structure + +Your Wiki.js should have this structure: + +/hyper-hive-labs/ +├── projects/ +│ ├── cuisineflow/ +│ │ ├── lessons-learned/ +│ │ │ ├── sprints/ +│ │ │ └── INDEX.md +│ │ └── documentation/ +│ ├── intuit-engine/ +│ └── hhl-site/ +├── company/ +│ ├── processes/ +│ └── standards/ +└── shared/ + └── architecture-patterns/ + +Create the base structure in Wiki.js before using the plugin. + +## Architecture Note + +Both plugins (projman and projman-pmo) share the same MCP servers. +The MCP servers detect their operating mode based on environment variables: +- Project mode: When GITEA_REPO and WIKIJS_PROJECT are present +- Company mode: When these variables are absent (PMO plugin) + +## Validation + +Test Gitea MCP: +python -m mcp_gitea.server --test + +Test Wiki.js MCP: +python -m mcp_wikijs.server --test + +Test projman plugin: +claude plugin test projman + +Test projman-pmo plugin: +claude plugin test projman-pmo +``` + +**Success Criteria:** +- Plugin loads successfully +- MCP server starts without errors +- Documentation is clear and complete +- Configuration templates provided +- Setup can be completed in < 5 minutes + +--- + +## Phase 2: Sprint Planning Commands (projman) + +### 2.1 Sprint Plan Command + +**Deliverable:** `/sprint-plan` command with planner agent integration + +**Tasks:** +- Create `commands/sprint-plan.md` +- Design command parameters: + - Sprint name/number + - Feature description + - Architecture considerations +- Invoke planner agent +- Handle branch detection (only create issues in development) +- Generate sprint planning document + +**Command Flow:** +``` +User: /sprint-plan +Agent: Let me help you plan this sprint. + + What are you building? +User: Extract Intuit engine into separate service +Agent: I detected architectural changes - this is Type/Refactor. + + Which components are affected? + - Component/Backend + - Component/API + - Component/Database + + Should we create a Gitea issue for tracking? +User: Yes +Agent: Created issue #47 with labels: + - Type/Refactor + - Component/Backend + - Component/API + - Priority/High + - Source/Development + + Generating sprint plan... + [Sprint document generated] +``` + +**Success Criteria:** +- Command invokes planner agent +- Agent asks relevant clarifying questions +- Issue created with correct labels +- Sprint document generated +- Only creates issues in development branch + +### 2.2 Sprint Start Command + +**Deliverable:** `/sprint-start` command + +**Tasks:** +- Create `commands/sprint-start.md` +- Search lessons learned Wiki +- Surface relevant past issues +- Set up sprint tracking +- Initialize issue tracking + +**Command Flow:** +``` +User: /sprint-start +Agent: Starting sprint... + + Searching lessons learned for "service extraction"... + 📚 Found 2 relevant lessons: + - Sprint 08: Service boundary issues with shared DB + - Sprint 12: API versioning during extraction + + These might be helpful for Intuit engine extraction. + + Ready to begin. Sprint issue: #47 +``` + +**Success Criteria:** +- Searches lessons learned Wiki +- Surfaces relevant past experiences +- Links to sprint issue +- Provides helpful context + +### 2.3 Sprint Status Command + +**Deliverable:** `/sprint-status` command + +**Tasks:** +- Create `commands/sprint-status.md` +- Query current sprint issue +- Show progress indicators +- List blockers +- Surface next actions + +**Success Criteria:** +- Clear status overview +- Identifies blockers +- Actionable next steps +- Links to relevant issues + +### 2.4 Sprint Close Command + +**Deliverable:** `/sprint-close` command with lessons learned capture + +**Tasks:** +- Create `commands/sprint-close.md` +- Guide retrospective questions: + - What went wrong? + - What worked well? + - Any Claude Code issues? + - Architecture insights? +- Create lessons learned document +- Update Wiki INDEX.md +- Add searchable tags +- Close sprint issue + +**Retrospective Template:** +```markdown +# Sprint [Number]: [Name] - Lessons Learned + +**Date:** [Date] +**Issue:** #[number] + +## What Went Wrong +- [Item 1] +- [Item 2] + +## What Worked Well +- [Item 1] +- [Item 2] + +## Claude Code Issues +- [Item 1] +- [Item 2] + +## Architecture Insights +- [Item 1] +- [Item 2] + +## Tags +#service-extraction #api #refactoring #claude-code-loops +``` + +**Success Criteria:** +- Interactive retrospective guide +- Document created in Wiki +- INDEX.md updated with tags +- Sprint issue closed +- Lessons searchable for future sprints + +--- + +## Phase 3: Agent System (projman) + +### 3.1 Planner Agent + +**Deliverable:** Sprint planning agent + +**Tasks:** +- Create `agents/planner.md` +- Define agent personality: + - Asks clarifying questions + - Analyzes architecture impact + - Suggests appropriate labels + - Generates structured plans +- Design interaction patterns +- Integrate with MCP tools +- Test with various scenarios + +**Agent Personality:** +```markdown +You are the Sprint Planner for Hyper Hive Labs. + +Your role: +- Guide users through sprint planning +- Ask targeted questions about scope and architecture +- Detect issue types (Bug, Feature, Refactor) +- Suggest appropriate labels based on context +- Generate comprehensive sprint documents +- Consider lessons learned from past sprints + +You are: +- Thorough but not overwhelming +- Architecture-aware +- Label-conscious (use Type/Refactor for architectural changes) +- Process-oriented + +You always: +- Reference relevant past lessons +- Consider technical debt +- Identify cross-project impacts +- Suggest realistic scope +``` + +**Success Criteria:** +- Agent provides valuable planning guidance +- Questions are relevant and targeted +- Label suggestions accurate +- Sprint documents well-structured +- Integrates lessons learned effectively + +### 3.2 Orchestrator Agent + +**Deliverable:** Sprint coordination agent + +**Tasks:** +- Create `agents/orchestrator.md` +- Define orchestration responsibilities: + - Track sprint progress + - Identify blockers + - Coordinate sub-tasks + - Surface relevant context +- Design status monitoring +- Build blocker detection logic + +**Agent Personality:** +```markdown +You are the Sprint Orchestrator for Hyper Hive Labs. + +Your role: +- Monitor sprint progress +- Track issue status +- Identify and surface blockers +- Coordinate between tasks +- Keep sprint on track + +You are: +- Progress-focused +- Blocker-aware +- Context-provider +- Coordination-minded + +You always: +- Check issue status +- Identify dependencies +- Surface relevant documentation +- Keep things moving +``` + +**Success Criteria:** +- Tracks progress accurately +- Identifies blockers early +- Provides useful coordination +- Reduces manual overhead + +### 3.3 Executor Agent + +**Deliverable:** Implementation guidance agent + +**Tasks:** +- Create `agents/executor.md` +- Define implementation support: + - Technical guidance + - Code review + - Testing strategy + - Documentation +- Integrate with label taxonomy +- Reference architecture patterns + +**Agent Personality:** +```markdown +You are the Sprint Executor for Hyper Hive Labs. + +Your role: +- Provide implementation guidance +- Suggest code patterns +- Review technical decisions +- Ensure quality standards +- Reference best practices + +You are: +- Technically detailed +- Quality-focused +- Pattern-aware +- Standards-conscious + +You always: +- Follow modular architecture principles +- Suggest discrete methods/functions +- Consider testability +- Document decisions +``` + +**Success Criteria:** +- Provides valuable technical guidance +- Maintains quality standards +- References appropriate patterns +- Supports implementation effectively + +--- + +## Phase 4: Lessons Learned System (projman) + +### 4.1 Wiki.js Integration + +**Deliverable:** Lessons learned structure in Wiki.js + +**Tasks:** +- Design Wiki.js page structure within project path: + ``` + /hyper-hive-labs/projects/cuisineflow/ + ├── lessons-learned/ + │ ├── INDEX.md # Searchable index + │ ├── sprints/ + │ │ ├── sprint-01-auth.md + │ │ ├── sprint-02-api.md + │ │ └── ... + │ └── patterns/ + │ ├── service-extraction.md + │ └── database-migration.md + └── documentation/ + ├── architecture/ + └── api/ + ``` +- Create INDEX.md template +- Define tagging system using Wiki.js tags +- Build search integration using Wiki.js MCP tools + +**INDEX.md Structure:** +```markdown +# CuisineFlow - Lessons Learned Index + +## By Sprint +- [Sprint 01: Auth System](sprints/sprint-01-auth) #authentication #oauth #security +- [Sprint 02: API Gateway](sprints/sprint-02-api) #api #gateway #routing + +## By Pattern +- [Service Extraction](patterns/service-extraction) #microservices #refactoring + +## By Technology +- Authentication: Sprint 01, Sprint 08 +- API Design: Sprint 02, Sprint 12 +- Database: Sprint 03, Sprint 15 + +## By Problem +- Claude Code Loops: Sprint 04, Sprint 12, Sprint 14 +- Deployment Issues: Sprint 08, Sprint 13 + +## Tags +#authentication #api #database #deployment #refactoring #claude-code-loops +``` + +**Wiki.js Advantages:** +- Rich markdown editor +- Built-in search +- Tag system +- Version history +- Access control +- Web UI for review + +**Success Criteria:** +- Clear Wiki.js page structure +- Searchable index page +- Tagging system works with Wiki.js tags +- Easy to navigate via web interface +- Integrates with Git (Wiki.js can sync to Git) + +### 4.2 Search Integration + +**Deliverable:** Lessons learned search using Wiki.js MCP + +**Tasks:** +- Use Wiki.js MCP server tools for search: + - `search_pages` - Search by keywords/tags in project path + - `get_page` - Fetch specific lesson document + - `create_page` - Create new lesson + - `update_page` - Update INDEX.md + - `list_pages` - List all lessons in path +- Implement tag-based search using Wiki.js tags +- Build keyword matching using Wiki.js search API +- Integrate with agents + +**Search Example:** +```python +# Using Wiki.js MCP tools +from mcp_wikijs import WikiJSClient + +client = WikiJSClient() + +# Search for service extraction lessons +results = await client.search_pages( + query="service extraction", + path="/hyper-hive-labs/projects/cuisineflow/lessons-learned" +) + +# Filter by tags +lessons_with_tag = await client.search_pages( + query="#refactoring", + path="/hyper-hive-labs/projects/cuisineflow/lessons-learned" +) +``` + +**Success Criteria:** +- Fast search using Wiki.js search API +- Tag-based filtering works +- Relevant results surfaced +- Integrates with planning process +- Can search across all projects (for PMO) + +### 4.3 Capture Workflow + +**Deliverable:** Lessons learned capture during sprint close + +**Tasks:** +- Integrate into `/sprint-close` command +- Guide retrospective discussion +- Generate structured markdown document +- Auto-tag based on content using Wiki.js tags +- Create page in Wiki.js via MCP +- Update INDEX.md automatically +- Use Wiki.js version control for history + +**Capture Flow:** +``` +User: /sprint-close +Agent: Let's capture lessons learned... + + What went wrong that we should avoid next time? +User: [Response] + +Agent: What decisions worked really well? +User: [Response] + +Agent: Were there any Claude Code issues that caused loops/blocks? +User: [Response] + +Agent: Any architectural insights for similar future work? +User: [Response] + +Agent: I'll create a lesson in Wiki.js: + Path: /hyper-hive-labs/projects/cuisineflow/lessons-learned/sprints/sprint-16-intuit-engine + + Tags detected: + #service-extraction #api #refactoring #claude-code-loops + + Creating page in Wiki.js... ✅ + Updating INDEX.md... ✅ + + View at: https://wiki.hyperhivelabs.com/hyper-hive-labs/projects/cuisineflow/lessons-learned/sprints/sprint-16-intuit-engine +``` + +**Wiki.js Page Creation:** +```python +# Using Wiki.js MCP create_page tool +await wikijs_client.create_page( + path="/hyper-hive-labs/projects/cuisineflow/lessons-learned/sprints/sprint-16-intuit-engine", + title="Sprint 16: Intuit Engine Extraction", + content=lesson_markdown, + tags=["service-extraction", "api", "refactoring", "claude-code-loops"] +) +``` + +**Success Criteria:** +- Guided retrospective questions +- Document created in Wiki.js +- Tags added via Wiki.js tag system +- INDEX.md updated automatically +- Viewable in Wiki.js web interface +- Version history tracked +- Searchable immediately + +--- + +## Phase 5: Testing & Validation (projman) + +### 5.1 Integration Testing + +**Deliverable:** Comprehensive test suite + +**Tasks:** +- Test MCP server tools: + - Issue CRUD operations + - Label operations + - Wiki operations + - Configuration loading +- Test command workflows: + - Complete sprint lifecycle + - Label sync + - Lessons learned capture +- Test agent interactions: + - Planner workflow + - Orchestrator monitoring + - Executor guidance +- Test configuration: + - System-level loading + - Project-level loading + - Hybrid merge behavior + - Missing config handling + +**Test Matrix:** +``` +| Component | Test Coverage | Status | +|------------------|---------------|--------| +| MCP Tools | All 10 tools | ✅ | +| Commands | All 5 cmds | ✅ | +| Agents | All 3 agents | ✅ | +| Configuration | All scenarios | ✅ | +| Wiki Integration | Full flow | ✅ | +| Label System | All labels | ✅ | +``` + +**Success Criteria:** +- All tests pass +- Edge cases handled +- Error messages clear +- Configuration validation works +- Performance acceptable + +### 5.2 Real Sprint Testing + +**Deliverable:** Plugin validated with actual sprint + +**Tasks:** +- Use plugin for Intuit engine extraction sprint +- Monitor for issues +- Collect user feedback +- Identify pain points +- Document improvements needed + +**Test Sprint Checklist:** +- [ ] Sprint planning with planner agent +- [ ] Issue created with correct labels +- [ ] Lessons learned searched at start +- [ ] Status monitoring during sprint +- [ ] Blocker identification +- [ ] Sprint close with retrospective +- [ ] Wiki updated with lessons + +**Success Criteria:** +- Plugin handles real sprint +- No critical bugs +- Workflow feels natural +- Saves time vs manual process +- Lessons learned captured + +### 5.3 Configuration Testing + +**Deliverable:** Validated hybrid configuration + +**Tasks:** +- Test system config creation +- Test project config creation +- Test configuration loading order +- Test missing config scenarios: + - No system config + - No project config + - Invalid credentials + - Network issues +- Test multi-project scenarios: + - Different repos with same system config + - Switching between projects + - Config changes propagation + +**Test Scenarios:** +``` +Scenario 1: Fresh install +- No configs exist +- Plugin guides user through setup +- All configs created correctly + +Scenario 2: System config exists +- User adds new project +- Only needs project .env +- System config reused + +Scenario 3: Invalid credentials +- Clear error message +- Suggests checking config +- Points to CONFIGURATION.md + +Scenario 4: Multi-project +- cuisineflow project +- Switch to intuit-engine project +- Each uses correct GITEA_REPO +- Same system credentials +``` + +**Success Criteria:** +- Configuration works in all scenarios +- Error messages are helpful +- Setup is intuitive +- Multi-project switching seamless +- Documentation matches reality + +--- + +## Phase 6: Documentation & Refinement (projman) + +### 6.1 User Documentation + +**Deliverable:** Complete user guide + +**Tasks:** +- Write README.md: + - Installation instructions + - Configuration setup (hybrid approach) + - Command reference + - Agent descriptions + - Troubleshooting +- Write CONFIGURATION.md: + - System-level setup + - Project-level setup + - Validation steps + - Common issues +- Create ARCHITECTURE.md: + - Plugin structure + - MCP server design + - Configuration flow + - Agent system +- Write CONTRIBUTING.md: + - Development setup + - Testing guidelines + - Label taxonomy updates + - Wiki maintenance + +**Success Criteria:** +- Complete documentation +- Clear setup instructions +- Configuration well-explained +- Examples provided +- Troubleshooting guide + +### 6.2 Iteration Based on Feedback + +**Deliverable:** Refined plugin based on real use + +**Tasks:** +- Address issues from test sprint +- Improve agent prompts +- Refine command flows +- Enhance error messages +- Optimize performance +- Update configuration docs if needed + +**Feedback Categories:** +- Usability issues +- Missing features +- Confusing workflows +- Error handling gaps +- Documentation unclear +- Configuration complexity + +**Success Criteria:** +- Major issues resolved +- Workflows improved +- Documentation updated +- Performance acceptable +- Ready for team use + +--- + +## Phase 7: Marketplace Preparation (projman) + +### 7.1 Gitea Marketplace Setup + +**Deliverable:** projman available in Gitea marketplace + +**Tasks:** +- Create marketplace repository in Gitea: + - `hyperhivelabs/claude-plugins` +- Add projman plugin to repository +- Create `.claude-plugin/marketplace.json`: + ```json + { + "plugins": [ + { + "name": "projman", + "displayName": "Project Manager", + "description": "Single-repo project management with Gitea", + "version": "1.0.0", + "author": "Hyper Hive Labs", + "repository": "hyperhivelabs/claude-plugins", + "path": "projman" + } + ] + } + ``` +- Test marketplace loading +- Document installation for team + +**Installation Command:** +```bash +# Add marketplace +/plugin marketplace add https://your-gitea.com/hyperhivelabs/claude-plugins + +# Install plugin +/plugin install projman +``` + +**Success Criteria:** +- Marketplace repository created +- Plugin available for installation +- Installation works smoothly +- Team can access plugin +- Documentation clear + +### 7.2 Team Onboarding + +**Deliverable:** Team trained on projman usage + +**Tasks:** +- Create onboarding guide +- Walk through configuration setup: + - System config creation + - Project config per repo +- Demonstrate sprint workflow +- Show lessons learned capture +- Explain label system +- Share best practices + +**Onboarding Checklist:** +- [ ] Configuration setup completed +- [ ] Test sprint planned +- [ ] Issue created successfully +- [ ] Labels used correctly +- [ ] Lessons learned captured +- [ ] Wiki searched successfully + +**Success Criteria:** +- Team understands configuration +- Can run full sprint workflow +- Uses labels correctly +- Captures lessons learned +- Comfortable with plugin + +--- + +## Phase 8: Production Hardening (projman) + +### 8.1 Error Handling & Resilience + +**Deliverable:** Production-ready error handling + +**Tasks:** +- Implement comprehensive error handling: + - Network failures + - API rate limits + - Authentication errors + - Invalid configurations + - Missing Wiki + - Git conflicts +- Add retry logic for transient failures +- Improve error messages +- Add logging for debugging +- Create health check command + +**Success Criteria:** +- Graceful failure handling +- Clear error messages +- Automatic retries where appropriate +- Logging helps debugging +- Users not blocked by errors + +### 8.2 Performance Optimization + +**Deliverable:** Optimized plugin performance + +**Tasks:** +- Profile MCP server operations using cProfile +- Optimize API calls: + - Batch requests where possible + - Cache label data using lru_cache + - Minimize Wiki searches +- Reduce startup time +- Optimize configuration loading +- Test with large repositories +- Use async/await for concurrent operations where beneficial + +**Success Criteria:** +- Fast command execution +- Low latency for API calls +- Efficient caching +- Handles large repos +- Startup time < 2 seconds + +### 8.3 Security Audit + +**Deliverable:** Security-hardened plugin + +**Tasks:** +- Review credential handling: + - System config permissions + - Token storage security + - Environment variable safety +- Validate input sanitization +- Check for injection vulnerabilities +- Review error message information leakage +- Audit logging for sensitive data +- Test access controls + +**Security Checklist:** +- [ ] Credentials never logged +- [ ] Config files have correct permissions +- [ ] Input validation on all user input +- [ ] No SQL/command injection vectors +- [ ] Error messages don't leak tokens +- [ ] API calls use TLS +- [ ] Token rotation supported + +**Success Criteria:** +- No security vulnerabilities +- Credentials protected +- Safe input handling +- Audit clean +- Best practices followed + +--- + +## Phase 9: PMO Plugin Foundation (projman-pmo) + +### 9.1 Requirements Analysis + +**Deliverable:** PMO plugin requirements document + +**Tasks:** +- Analyze multi-project workflows: + - CuisineFlow → CuisineFlow-Site sync + - Intuit Engine → CuisineFlow integration + - HHL-Site updates + - Customer VPS deployments +- Identify cross-project dependencies +- Define coordination pain points +- Design PMO plugin scope +- Determine what belongs in PMO vs projman + +**Key Questions:** +- What triggers demo site updates? +- What triggers Intuit engine updates? +- How do you coordinate customer VPS deployments? +- Where do multi-project conflicts happen? +- What decisions require cross-project visibility? + +**Success Criteria:** +- Clear understanding of multi-project workflows +- Pain points documented +- PMO plugin scope defined +- Not duplicating single-repo functionality + +### 9.2 MCP Server Extension + +**Deliverable:** Multi-repo query capabilities + +**Tasks:** +- Extend Gitea MCP server for multi-repo operations +- Add tools: + - `list_repos` - Get all organization repos + - `aggregate_issues` - Fetch issues across repos + - `check_dependencies` - Analyze cross-repo dependencies + - `get_deployment_status` - Check deployment states +- Build dependency graph visualization data +- Implement cross-repo search + +**Configuration for PMO:** + +**pmo/.mcp.json:** +```json +{ + "mcpServers": { + "gitea-pmo": { + "command": "python", + "args": ["-m", "mcp_server.server"], + "cwd": "${CLAUDE_PLUGIN_ROOT}/mcp-server", + "env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/mcp-server", + "GITEA_API_URL": "${GITEA_API_URL}", + "GITEA_API_TOKEN": "${GITEA_API_TOKEN}", + "GITEA_OWNER": "${GITEA_OWNER}" + } + } + } +} +``` + +**Note:** PMO only uses system-level config (no GITEA_REPO). + +**Success Criteria:** +- Can query multiple repos efficiently +- Dependency analysis works +- Aggregated views make sense +- Performance acceptable for 3-5 repos +- System-level config sufficient + +### 9.3 PMO Agent Design + +**Deliverable:** Multi-project coordinator agent + +**Tasks:** +- Define PMO agent personality +- Design cross-project prioritization logic +- Create resource allocation algorithms +- Build conflict detection rules +- Design dependency tracking system + +**PMO Agent Personality:** +```markdown +You are the PMO Coordinator for Hyper Hive Labs. + +Your role: +- Maintain strategic view across all projects +- Identify cross-project dependencies +- Detect resource conflicts +- Balance competing priorities +- Coordinate release timing +- Track customer deployment schedules + +You are: +- Strategic thinker +- Dependency-aware +- Conflict detector +- Priority balancer +- Team coordinator + +You delegate to project-level agents: +- Don't micromanage single projects +- Focus on cross-project issues +- Surface conflicts early +- Facilitate coordination +``` + +**Success Criteria:** +- Clear separation from projman agents +- Valuable for multi-project scenarios +- Doesn't micromanage single projects +- Integrates with projman seamlessly + +--- + +## Phase 10: PMO Plugin Development (projman-pmo) + +### 10.1 Cross-Project Commands + +**Deliverable:** PMO-specific commands + +**Tasks:** +- `/pmo-status` - View all projects status +- `/pmo-priorities` - Review and adjust priorities across projects +- `/pmo-dependencies` - Visualize project dependencies +- `/pmo-conflicts` - Identify resource conflicts +- `/pmo-schedule` - View deployment schedule + +**Command Examples:** + +**`/pmo-status`:** +``` +Projects Overview: + +CuisineFlow (main) +├── Sprint: Intuit Engine Extraction +├── Status: In Progress (60%) +├── Blockers: None +└── Next: API testing + +CuisineFlow-Site (demo) +├── Sprint: Dashboard Updates +├── Status: Waiting on CuisineFlow API +├── Blockers: Depends on #cuisineflow-47 +└── Next: Deploy when API ready + +Intuit-Engine (service) +├── Sprint: Initial Setup +├── Status: Planning +├── Blockers: Architecture decisions needed +└── Next: Service boundary definition + +HHL-Site (marketing) +├── Sprint: Content Updates +├── Status: Complete +├── Blockers: None +└── Next: Deploy to production +``` + +**`/pmo-dependencies`:** +``` +Project Dependencies: + +CuisineFlow → Intuit-Engine + ├── Must complete before v2.0 launch + └── API contracts defined + +CuisineFlow → CuisineFlow-Site + ├── Demo must sync with main features + └── Deploy together for consistency + +Deployment Order: +1. Intuit-Engine (backend service) +2. CuisineFlow (main app) +3. CuisineFlow-Site (demo sync) +4. Customer VPS deployments +``` + +**Success Criteria:** +- Commands provide valuable cross-project insights +- Dependencies clearly visualized +- Conflicts easily identified +- Priorities make sense +- Schedule coordination works + +### 10.2 Coordination Workflows + +**Deliverable:** Multi-project coordination automation + +**Tasks:** +- Implement dependency tracking +- Build conflict detection: + - Resource conflicts + - Timeline conflicts + - Priority conflicts +- Create notification system for cross-project impacts +- Design release coordination workflow + +**Conflict Detection Examples:** + +**Resource Conflict:** +``` +⚠️ Resource Conflict Detected + +Leo is assigned to: +- CuisineFlow: Intuit Engine extraction (Priority: Critical) +- CuisineFlow-Site: Dashboard redesign (Priority: High) +- HHL-Site: Content update (Priority: Medium) + +Recommendation: +- Focus on Intuit Engine (blocks launch) +- Defer dashboard redesign to next sprint +- Delegate content update to marketing +``` + +**Timeline Conflict:** +``` +⚠️ Timeline Conflict Detected + +CuisineFlow v2.0 launch: Nov 15 +├── Depends on: Intuit Engine completion +└── Current status: Behind schedule + +Impact: +- Demo site deployment delayed +- Customer VPS updates postponed +- Marketing announcements on hold + +Action needed: Re-evaluate scope or push date +``` + +**Success Criteria:** +- Conflicts detected automatically +- Clear recommendations provided +- Dependencies tracked accurately +- Timeline visibility maintained + +### 10.3 Dashboard & Reporting + +**Deliverable:** Multi-project dashboard + +**Tasks:** +- Create consolidated view: + - All active sprints + - Cross-project dependencies + - Resource allocation + - Timeline status + - Blockers across projects +- Build reporting commands: + - `/pmo-report daily` - Daily standup report + - `/pmo-report weekly` - Weekly progress + - `/pmo-report release` - Release readiness +- Generate stakeholder updates + +**Success Criteria:** +- Dashboard provides clear overview +- Reports are actionable +- Stakeholder communication improved +- Decision-making supported + +--- + +## Phase 11: PMO Testing & Integration (projman-pmo) + +### 11.1 Multi-Project Testing + +**Deliverable:** Validated PMO plugin + +**Tasks:** +- Test with CuisineFlow + CuisineFlow-Site + Intuit Engine +- Simulate deployment coordination scenarios +- Test priority conflict resolution +- Validate dependency tracking +- Test customer deployment scheduling + +**Test Scenarios:** + +**Scenario 1: Dependent Deploy** +``` +Given: CuisineFlow has API changes +And: CuisineFlow-Site depends on those changes +When: CuisineFlow sprint completes +Then: PMO should alert about Site sync needed +And: Suggest coordinated deployment +``` + +**Scenario 2: Resource Conflict** +``` +Given: Multiple critical priorities +And: Single developer (Leo) +When: PMO analyzes priorities +Then: Should detect conflict +And: Recommend prioritization +``` + +**Scenario 3: Release Coordination** +``` +Given: Intuit Engine must deploy first +And: CuisineFlow depends on it +And: Demo site must sync +When: Release planned +Then: PMO generates deployment order +And: Validates dependencies satisfied +``` + +**Success Criteria:** +- All scenarios handled correctly +- Dependencies respected +- Conflicts detected and surfaced +- Coordination reduces manual overhead + +### 11.2 Integration with projman + +**Deliverable:** Seamless plugin interoperability + +**Tasks:** +- Ensure PMO agent delegates to projman agents +- Test command interoperability +- Validate shared MCP server usage (if applicable) +- Check lessons learned sharing across projects +- Test configuration isolation (PMO system-only vs projman hybrid) + +**Integration Points:** +``` +PMO Plugin projman Plugin + ├─────────────────────┤ + │ Delegates │ + │ single-project │ + │ details │ + │ │ + ├─ Aggregates ────────┤ + │ cross-project │ + │ status │ + │ │ + └─ Coordinates ───────┘ + dependencies +``` + +**Success Criteria:** +- PMO doesn't interfere with single-project work +- Delegation works smoothly +- Shared infrastructure stable (if any) +- Cross-project lessons accessible +- Configuration doesn't conflict + +--- + +## Phase 12: Production Deployment + +### 12.1 Multi-Environment Rollout + +**Deliverable:** Plugins deployed across all environments + +**Tasks:** +- Deploy to laptop (development) +- Deploy to staging VPS +- Deploy to production VPS +- Configure branch-aware permissions per environment +- Test network connectivity and API access +- Validate configuration in each environment + +**Environment Configuration:** + +**Laptop (Development):** +```bash +# System config (~/.config/claude/gitea.env) +GITEA_API_URL=https://gitea.hyperhivelabs.com/api/v1 +GITEA_API_TOKEN=dev_token +GITEA_OWNER=hyperhivelabs + +# Project configs (per repo .env) +# cuisineflow/.env +GITEA_REPO=cuisineflow + +# intuit-engine/.env +GITEA_REPO=intuit-engine +``` + +**VPS Environments:** +- Same system config copied to VPS +- Each project repo has its own .env +- MCP server runs in production mode +- Network access validated + +**Success Criteria:** +- Plugins work in all environments +- Configuration portable across systems +- Network connectivity stable +- Production ready + +### 12.2 Backup & Recovery + +**Deliverable:** Backup and recovery procedures + +**Tasks:** +- Document configuration backup: + - System config backup + - Project configs tracked in git +- Create Wiki backup strategy +- Document recovery procedures +- Test configuration restoration +- Automate backups where possible + +**Backup Strategy:** +```bash +# System config backup +cp ~/.config/claude/gitea.env ~/.config/claude/gitea.env.backup + +# Wiki is already in git +cd wiki +git push origin main + +# Project configs are in .gitignore (not backed up, easily recreated) +``` + +**Success Criteria:** +- Configuration backup documented +- Wiki backed up regularly +- Recovery procedures tested +- Data loss risk minimized + +### 12.3 Monitoring & Maintenance + +**Deliverable:** Ongoing monitoring and maintenance plan + +**Tasks:** +- Set up error monitoring +- Create maintenance schedule: + - Label taxonomy updates + - Wiki cleanup + - Configuration audits + - Security updates +- Document troubleshooting procedures +- Establish update process for MCP server + +**Maintenance Checklist:** +- [ ] Weekly: Review error logs +- [ ] Monthly: Update Python dependencies (pip list --outdated) +- [ ] Quarterly: Security audit (pip-audit) +- [ ] As-needed: Label taxonomy sync +- [ ] As-needed: Wiki organization +- [ ] As-needed: Recreate virtual environment for major updates + +**Success Criteria:** +- Monitoring in place +- Maintenance plan documented +- Update process defined +- Team knows how to maintain + +--- + +## Rollback Plan + +If plugins cause more problems than they solve: + +**Immediate Fallback:** +- Keep existing skills and scripts functional +- Plugins are opt-in, not replacement +- Document issues and iterate +- Can disable plugins without losing work + +**Criteria for Rollback:** +- Plugin slower than current workflow +- Frequent errors or data loss +- User frustration increases +- Blocks urgent work (like sprint deadlines) + +**Progressive Enhancement:** +- Build plugins alongside current system +- Migrate piece by piece +- Keep escape hatches +- Only deprecate scripts when plugin proven + +--- + +## Configuration Quick Reference + +### System-Level Setup (Once per machine) + +```bash +# Create config directory +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_here +GITEA_OWNER=hyperhivelabs +EOF + +# Set permissions +chmod 600 ~/.config/claude/gitea.env +``` + +### Project-Level Setup (Per repository) + +```bash +# In project root +echo "GITEA_REPO=cuisineflow" > .env + +# Add to .gitignore +echo ".env" >> .gitignore +``` + +### Validation + +```bash +# Test projman configuration +cd your-project +claude plugin test projman + +# Test pmo configuration (no project needed) +claude plugin test projman-pmo +``` + +--- + +## Notes on Type/Refactor Label + +**Label Details:** +- **Name:** `Type/Refactor` +- **Level:** Organization (available to all repos) +- **Category:** Type/ (Exclusive - only one Type per issue) +- **Color:** #0052cc (matches other Type labels) +- **Description:** Architectural changes and code restructuring + +**Usage in Plugins:** +- Planner agent suggests Type/Refactor for: + - Service extraction (like Intuit engine) + - Architecture modifications + - Code restructuring without feature changes + - Performance optimizations requiring significant changes +- Label suggestion engine detects refactor keywords: + - "extract", "refactor", "restructure", "optimize architecture" + - "service boundary", "microservice", "decouple" + - "technical debt", "code quality" +- Shows in label sync diffs when fetching from Gitea +- Documented in label taxonomy skill + +**Integration Points:** +- MCP server includes Type/Refactor in label enumeration +- Suggestion engine trained on architectural patterns +- Sprint planning templates include refactor considerations +- Lessons learned can tag architectural mistakes for future refactors + +--- + +## End of Implementation Plan + +This plan builds two plugins systematically, starting with single-repo project management (projman) and expanding to multi-project coordination (projman-pmo). Each phase builds on previous phases, with testing and validation throughout. + +The hybrid configuration approach provides the right balance of simplicity (single token location) and flexibility (per-project repository specification). + +The plan is execution-ready but flexible - adjust based on real-world feedback and discovered requirements. \ No newline at end of file diff --git a/docs/references/projman-pmo/projman-python-quickstart.md b/docs/references/projman-pmo/projman-python-quickstart.md new file mode 100644 index 0000000..c63c00a --- /dev/null +++ b/docs/references/projman-pmo/projman-python-quickstart.md @@ -0,0 +1,729 @@ +# ProjMan Plugins - Python Quick Start + +This guide provides Python-specific setup and development information for the projman and projman-pmo plugins. + +> **⚠️ IMPORTANT:** For the definitive repository structure, refer to [CORRECT-ARCHITECTURE.md](./CORRECT-ARCHITECTURE.md). This guide shows Python-specific patterns and setup. + +--- + +## Technology Stack + +- **MCP Server:** Python 3.11+ +- **Commands:** Markdown files +- **Agents:** Markdown files +- **Dependencies:** pip with requirements.txt +- **Virtual Environment:** .venv (per plugin) + +--- + +## Initial Setup + +### 1. System Requirements + +```bash +# Python 3.11 or higher +python --version + +# pip (latest) +pip --version + +# git +git --version +``` + +### 2. System-Level Configuration + +```bash +# Create config directory +mkdir -p ~/.config/claude + +# Create gitea.env with your credentials +cat > ~/.config/claude/gitea.env << EOF +GITEA_API_URL=https://gitea.hyperhivelabs.com/api/v1 +GITEA_API_TOKEN=your_token_here +GITEA_OWNER=hyperhivelabs +EOF + +# Secure the file +chmod 600 ~/.config/claude/gitea.env +``` + +### 3. Project-Level Configuration + +```bash +# In each repository root +echo "GITEA_REPO=cuisineflow" > .env + +# Add to .gitignore +echo ".env" >> .gitignore +``` + +--- + +## MCP Server Structure + +``` +hyperhivelabs/claude-plugins/ +├── mcp-servers/ # SHARED by both plugins +│ ├── gitea/ +│ │ ├── .venv/ +│ │ ├── requirements.txt +│ │ ├── mcp_server/ +│ │ │ ├── __init__.py +│ │ │ ├── server.py +│ │ │ ├── config.py +│ │ │ ├── gitea_client.py +│ │ │ └── tools/ +│ │ └── tests/ +│ └── wikijs/ +│ ├── .venv/ +│ ├── requirements.txt +│ ├── mcp_server/ +│ │ ├── __init__.py +│ │ ├── server.py +│ │ ├── config.py +│ │ └── wikijs_client.py +│ └── tests/ +├── projman/ +│ ├── .mcp.json # Points to ../mcp-servers/ +│ ├── commands/ +│ └── agents/ +└── projman-pmo/ + ├── .mcp.json # Points to ../mcp-servers/ + └── commands/ +``` + +--- + +## Dependencies (requirements.txt) + +```txt +# anthropic-sdk==0.18.0 # MCP SDK +anthropic-sdk>=0.18.0 +# python-dotenv==1.0.0 # Environment variable loading +python-dotenv>=1.0.0 +# requests==2.31.0 # HTTP client for Gitea API +requests>=2.31.0 +# pydantic==2.5.0 # Data validation +pydantic>=2.5.0 +# pytest==7.4.3 # Testing framework +pytest>=7.4.3 +# pytest-asyncio==0.23.0 # Async testing support +pytest-asyncio>=0.23.0 +``` + +**Note:** Following your coding preferences, library versions are specified with comments showing the exact version being used. + +--- + +## Development Workflow + +### Initial MCP Server Setup + +```bash +# Navigate to MCP servers directory +cd /path/to/claude-plugins/mcp-servers/gitea + +# Create virtual environment +python -m venv .venv + +# Activate virtual environment +source .venv/bin/activate # Linux/Mac +# or +.venv\Scripts\activate # Windows + +# Install dependencies +pip install -r requirements.txt + +# Verify installation +python -c "import anthropic; print('SDK installed')" +``` + +### Configuration Loader (config.py) + +```python +# mcp-servers/gitea/mcp_server/config.py +from pathlib import Path +from dotenv import load_dotenv +import os +from typing import Dict, Optional + +class Config: + """Hybrid configuration loader for projman plugins""" + + def __init__(self): + self.api_url: Optional[str] = None + self.api_token: Optional[str] = None + self.owner: Optional[str] = None + self.repo: Optional[str] = None + + def load(self) -> Dict[str, str]: + """ + Load configuration from system and project levels. + Project-level configuration overrides system-level. + """ + # Load system config + system_config = Path.home() / '.config' / 'claude' / 'gitea.env' + if system_config.exists(): + load_dotenv(system_config) + else: + raise FileNotFoundError( + f"System config not found: {system_config}\n" + "Create it with: mkdir -p ~/.config/claude && " + "cat > ~/.config/claude/gitea.env" + ) + + # Load project config (overrides system) + project_config = Path.cwd() / '.env' + if project_config.exists(): + load_dotenv(project_config, override=True) + + # Extract values + self.api_url = os.getenv('GITEA_API_URL') + self.api_token = os.getenv('GITEA_API_TOKEN') + self.owner = os.getenv('GITEA_OWNER') + self.repo = os.getenv('GITEA_REPO') # Optional for PMO + + # Validate required variables + self._validate() + + return { + 'api_url': self.api_url, + 'api_token': self.api_token, + 'owner': self.owner, + 'repo': self.repo + } + + def _validate(self) -> None: + """Validate that required configuration is present""" + required = { + 'GITEA_API_URL': self.api_url, + 'GITEA_API_TOKEN': self.api_token, + 'GITEA_OWNER': self.owner + } + + missing = [key for key, value in required.items() if not value] + + if missing: + raise ValueError( + f"Missing required configuration: {', '.join(missing)}\n" + "Check your ~/.config/claude/gitea.env file" + ) + +# Usage +config = Config() +config_dict = config.load() +``` + +### Gitea API Client (gitea_client.py) + +```python +# mcp-servers/gitea/mcp_server/gitea_client.py +import requests +from typing import List, Dict, Optional +from .config import Config + +class GiteaClient: + """Client for interacting with Gitea API""" + + def __init__(self): + config = Config() + config_dict = config.load() + + self.base_url = config_dict['api_url'] + self.token = config_dict['api_token'] + self.owner = config_dict['owner'] + self.repo = config_dict.get('repo') # Optional + + self.session = requests.Session() + self.session.headers.update({ + 'Authorization': f'token {self.token}', + 'Content-Type': 'application/json' + }) + + def list_issues( + self, + state: str = 'open', + labels: Optional[List[str]] = None, + repo: Optional[str] = None + ) -> List[Dict]: + """ + List issues from Gitea repository. + + Args: + state: Issue state (open, closed, all) + labels: Filter by labels + repo: Override configured repo (for PMO multi-repo) + """ + target_repo = repo or self.repo + if not target_repo: + raise ValueError("Repository not specified") + + url = f"{self.base_url}/repos/{self.owner}/{target_repo}/issues" + params = {'state': state} + + if labels: + params['labels'] = ','.join(labels) + + response = self.session.get(url, params=params) + response.raise_for_status() + return response.json() + + def create_issue( + self, + title: str, + body: str, + labels: Optional[List[str]] = None, + repo: Optional[str] = None + ) -> Dict: + """Create a new issue in Gitea""" + target_repo = repo or self.repo + if not target_repo: + raise ValueError("Repository not specified") + + url = f"{self.base_url}/repos/{self.owner}/{target_repo}/issues" + data = { + 'title': title, + 'body': body + } + + if labels: + data['labels'] = labels + + response = self.session.post(url, json=data) + response.raise_for_status() + return response.json() + + def get_labels( + self, + repo: Optional[str] = None + ) -> List[Dict]: + """Get all labels from repository""" + target_repo = repo or self.repo + if not target_repo: + raise ValueError("Repository not specified") + + url = f"{self.base_url}/repos/{self.owner}/{target_repo}/labels" + response = self.session.get(url) + response.raise_for_status() + return response.json() +``` + +### MCP Server Entry Point (server.py) + +```python +# mcp-servers/gitea/mcp_server/server.py +from anthropic import Anthropic +from .gitea_client import GiteaClient +from .tools import IssueTools, LabelTools, WikiTools + +class ProjManMCPServer: + """Main MCP server for projman plugin""" + + def __init__(self): + self.gitea = GiteaClient() + self.issue_tools = IssueTools(self.gitea) + self.label_tools = LabelTools(self.gitea) + self.wiki_tools = WikiTools(self.gitea) + + def register_tools(self): + """Register all available MCP tools""" + return [ + # Issue tools + self.issue_tools.list_issues, + self.issue_tools.get_issue, + self.issue_tools.create_issue, + self.issue_tools.update_issue, + self.issue_tools.add_comment, + + # Label tools + self.label_tools.get_labels, + self.label_tools.suggest_labels, + + # Wiki tools + self.wiki_tools.search_wiki, + self.wiki_tools.get_wiki_page, + self.wiki_tools.create_wiki_page + ] + +if __name__ == '__main__': + server = ProjManMCPServer() + # MCP server startup logic here +``` + +--- + +## Testing + +### Unit Tests + +```python +# tests/test_config.py +import pytest +from pathlib import Path +from mcp_server.config import Config + +def test_load_system_config(tmp_path): + """Test loading system-level configuration""" + # Create mock system config + config_dir = tmp_path / '.config' / 'claude' + config_dir.mkdir(parents=True) + + config_file = config_dir / 'gitea.env' + config_file.write_text( + "GITEA_API_URL=https://test.com/api/v1\n" + "GITEA_API_TOKEN=test_token\n" + "GITEA_OWNER=test_owner\n" + ) + + # Test config loading + config = Config() + # ... test assertions + +def test_project_config_override(tmp_path): + """Test that project config overrides system config""" + # ... test implementation + +def test_missing_required_config(): + """Test error handling for missing configuration""" + with pytest.raises(ValueError): + config = Config() + config.load() +``` + +### Integration Tests + +```python +# tests/test_gitea_client.py +import pytest +from mcp_server.gitea_client import GiteaClient + +@pytest.fixture +def gitea_client(): + """Fixture providing configured Gitea client""" + return GiteaClient() + +def test_list_issues(gitea_client): + """Test listing issues from Gitea""" + issues = gitea_client.list_issues(state='open') + assert isinstance(issues, list) + +def test_create_issue(gitea_client): + """Test creating an issue in Gitea""" + issue = gitea_client.create_issue( + title="Test Issue", + body="Test body", + labels=["Type/Bug"] + ) + assert issue['title'] == "Test Issue" + assert "Type/Bug" in [label['name'] for label in issue['labels']] +``` + +### Running Tests + +```bash +# Activate virtual environment +source .venv/bin/activate + +# Run all tests +pytest + +# Run with coverage +pytest --cov=mcp_server --cov-report=html + +# Run specific test file +pytest tests/test_config.py + +# Run with verbose output +pytest -v +``` + +--- + +## .mcp.json Configuration + +### projman (Repository-Specific) + +```json +{ + "mcpServers": { + "gitea-projman": { + "command": "python", + "args": ["-m", "mcp_server.server"], + "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea", + "env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea", + "GITEA_API_URL": "${GITEA_API_URL}", + "GITEA_API_TOKEN": "${GITEA_API_TOKEN}", + "GITEA_OWNER": "${GITEA_OWNER}", + "GITEA_REPO": "${GITEA_REPO}" + } + }, + "wikijs-projman": { + "command": "python", + "args": ["-m", "mcp_server.server"], + "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs", + "env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs", + "WIKIJS_API_URL": "${WIKIJS_API_URL}", + "WIKIJS_API_TOKEN": "${WIKIJS_API_TOKEN}", + "WIKIJS_BASE_PATH": "${WIKIJS_BASE_PATH}", + "WIKIJS_PROJECT": "${WIKIJS_PROJECT}" + } + } + } +} +``` + +### projman-pmo (Multi-Project) + +```json +{ + "mcpServers": { + "gitea-pmo": { + "command": "python", + "args": ["-m", "mcp_server.server"], + "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea", + "env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea", + "GITEA_API_URL": "${GITEA_API_URL}", + "GITEA_API_TOKEN": "${GITEA_API_TOKEN}", + "GITEA_OWNER": "${GITEA_OWNER}" + } + }, + "wikijs-pmo": { + "command": "python", + "args": ["-m", "mcp_server.server"], + "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs", + "env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs", + "WIKIJS_API_URL": "${WIKIJS_API_URL}", + "WIKIJS_API_TOKEN": "${WIKIJS_API_TOKEN}", + "WIKIJS_BASE_PATH": "${WIKIJS_BASE_PATH}" + } + } + } +} +``` + +**Note:** Both plugins reference `../mcp-servers/` (shared location). PMO doesn't use `GITEA_REPO` since it operates across all repositories. + +--- + +## Modular Code Structure (Following Your Preferences) + +### Single Responsibility Functions + +```python +def validate_configuration(config: Dict[str, str]) -> None: + """ + Validate that all required configuration values are present. + Raises ValueError if any required values are missing. + """ + required_keys = ['api_url', 'api_token', 'owner'] + missing = [key for key in required_keys if not config.get(key)] + + if missing: + raise ValueError(f"Missing configuration: {', '.join(missing)}") + +def load_system_config() -> Dict[str, str]: + """ + Load configuration from system-level gitea.env file. + Returns dictionary of configuration values. + """ + config_path = Path.home() / '.config' / 'claude' / 'gitea.env' + + if not config_path.exists(): + raise FileNotFoundError(f"System config not found: {config_path}") + + load_dotenv(config_path) + + return { + 'api_url': os.getenv('GITEA_API_URL'), + 'api_token': os.getenv('GITEA_API_TOKEN'), + 'owner': os.getenv('GITEA_OWNER') + } + +def load_project_config() -> Dict[str, Optional[str]]: + """ + Load project-specific configuration from local .env file. + Returns dictionary with 'repo' key, value may be None if not configured. + """ + project_env = Path.cwd() / '.env' + + if project_env.exists(): + load_dotenv(project_env, override=True) + + return { + 'repo': os.getenv('GITEA_REPO') + } + +def merge_configurations(system: Dict, project: Dict) -> Dict[str, str]: + """ + Merge system and project configurations. + Project values override system values where present. + """ + merged = system.copy() + merged.update({k: v for k, v in project.items() if v is not None}) + return merged + +def main(): + """Main entry point that orchestrates configuration loading""" + system_config = load_system_config() + project_config = load_project_config() + final_config = merge_configurations(system_config, project_config) + validate_configuration(final_config) + return final_config +``` + +--- + +## Virtual Environment Management + +### Creation + +```bash +# In plugin mcp-server directory +python -m venv .venv +``` + +### Activation + +```bash +# Linux/Mac +source .venv/bin/activate + +# Windows +.venv\Scripts\activate +``` + +### Deactivation + +```bash +deactivate +``` + +### Cleanup & Rebuild + +```bash +# Remove old virtual environment +rm -rf .venv + +# Create fresh virtual environment +python -m venv .venv + +# Activate and reinstall +source .venv/bin/activate +pip install -r requirements.txt +``` + +--- + +## Debugging + +### Enable Debug Logging + +```python +# Add to server.py +import logging + +logging.basicConfig( + level=logging.DEBUG, + format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' +) + +logger = logging.getLogger(__name__) +``` + +### Common Issues + +**Issue:** Module not found +```bash +# Solution: Ensure PYTHONPATH is set in .mcp.json +"env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/mcp-server" +} +``` + +**Issue:** Configuration not loading +```bash +# Solution: Check file permissions +chmod 600 ~/.config/claude/gitea.env + +# Verify file exists +cat ~/.config/claude/gitea.env +``` + +**Issue:** API authentication failing +```bash +# Solution: Test token manually +curl -H "Authorization: token YOUR_TOKEN" \ + https://your-gitea.com/api/v1/user +``` + +--- + +## Performance Optimization + +### Caching with functools + +```python +from functools import lru_cache + +@lru_cache(maxsize=128) +def get_labels_cached(repo: str) -> List[Dict]: + """Cached label retrieval to reduce API calls""" + return self.gitea.get_labels(repo) +``` + +### Async Operations + +```python +import asyncio +import aiohttp + +async def fetch_multiple_repos(repos: List[str]) -> List[Dict]: + """Fetch data from multiple repositories concurrently""" + async with aiohttp.ClientSession() as session: + tasks = [fetch_repo_data(session, repo) for repo in repos] + return await asyncio.gather(*tasks) +``` + +--- + +## Next Steps + +1. **Set up system configuration** as shown above +2. **Create project configuration** in your first repository +3. **Navigate to Phase 1.1** of the implementation plan +4. **Build the MCP server** following the structure above +5. **Write tests** as you implement each component +6. **Test with real Gitea instance** early and often + +--- + +## Key Differences from Node.js Approach + +| Aspect | Node.js | Python (Your Choice) | +|--------|---------|---------------------| +| Dependencies | package.json | requirements.txt | +| Package Manager | npm/yarn | pip | +| Isolation | node_modules | .venv | +| Module System | ES6 imports | Python imports | +| Async | async/await | async/await | +| Type Checking | TypeScript | Type hints + Pydantic | +| Testing | Jest | pytest | + +--- + +## Resources + +- **Anthropic MCP SDK (Python):** https://github.com/anthropics/anthropic-sdk-python +- **Python Requests:** https://docs.python-requests.org/ +- **Pydantic:** https://docs.pydantic.dev/ +- **pytest:** https://docs.pytest.org/ +- **Gitea API Docs:** https://docs.gitea.com/api/ + +--- + +Ready to build! 🚀 \ No newline at end of file diff --git a/docs/references/projman-pmo/two-mcp-architecture-guide.md b/docs/references/projman-pmo/two-mcp-architecture-guide.md new file mode 100644 index 0000000..f7cb263 --- /dev/null +++ b/docs/references/projman-pmo/two-mcp-architecture-guide.md @@ -0,0 +1,944 @@ +# Two MCP Server Architecture - Implementation Guide + +## Overview + +The projman plugin now uses **two separate MCP servers**: +1. **Gitea MCP Server** - Issues, labels, repository management +2. **Wiki.js MCP Server** - Documentation, lessons learned, knowledge base + +This separation provides better maintainability, independent configuration, and leverages Wiki.js's superior documentation features. + +> **⚠️ IMPORTANT:** For the definitive repository structure and configuration paths, refer to [CORRECT-ARCHITECTURE.md](./CORRECT-ARCHITECTURE.md). This guide provides detailed implementation examples and architectural deep-dive. + +--- + +## Wiki.js Structure at Hyper Hive Labs + +### Company-Wide Organization + +``` +Wiki.js Instance: https://wiki.hyperhivelabs.com +└── /hyper-hive-labs/ # Base path for all HHL content + ├── projects/ # Project-specific documentation + │ ├── cuisineflow/ + │ │ ├── lessons-learned/ + │ │ │ ├── sprints/ + │ │ │ │ ├── sprint-01-auth.md + │ │ │ │ ├── sprint-02-api.md + │ │ │ │ └── ... + │ │ │ ├── patterns/ + │ │ │ │ ├── service-extraction.md + │ │ │ │ └── database-migration.md + │ │ │ └── INDEX.md + │ │ └── documentation/ + │ │ ├── architecture/ + │ │ ├── api/ + │ │ └── deployment/ + │ ├── cuisineflow-site/ + │ │ ├── lessons-learned/ + │ │ └── documentation/ + │ ├── intuit-engine/ + │ │ ├── lessons-learned/ + │ │ └── documentation/ + │ └── hhl-site/ + │ ├── lessons-learned/ + │ └── documentation/ + ├── company/ # Company-wide documentation + │ ├── processes/ + │ │ ├── onboarding.md + │ │ ├── deployment.md + │ │ └── code-review.md + │ ├── standards/ + │ │ ├── python-style-guide.md + │ │ ├── api-design.md + │ │ └── security.md + │ └── tools/ + │ ├── gitea-guide.md + │ ├── wikijs-guide.md + │ └── claude-plugins.md + └── shared/ # Cross-project resources + ├── architecture-patterns/ + │ ├── microservices.md + │ ├── api-gateway.md + │ └── database-per-service.md + ├── best-practices/ + │ ├── error-handling.md + │ ├── logging.md + │ └── testing.md + └── tech-stack/ + ├── python-ecosystem.md + ├── docker.md + └── ci-cd.md +``` + +--- + +## Configuration Architecture + +### System-Level Configuration + +**File: `~/.config/claude/gitea.env`** +```bash +GITEA_API_URL=https://gitea.hyperhivelabs.com/api/v1 +GITEA_API_TOKEN=your_gitea_token_here +GITEA_OWNER=hyperhivelabs +``` + +**File: `~/.config/claude/wikijs.env`** +```bash +WIKIJS_API_URL=https://wiki.hyperhivelabs.com/graphql +WIKIJS_API_TOKEN=your_wikijs_token_here +WIKIJS_BASE_PATH=/hyper-hive-labs +``` + +**Why separate files?** +- Different services, different authentication +- Can update one without affecting the other +- Clear separation of concerns +- Easier to revoke/rotate tokens per service + +### Project-Level Configuration + +**File: `project-root/.env`** +```bash +# Gitea repository name +GITEA_REPO=cuisineflow + +# Wiki.js project path (relative to /hyper-hive-labs) +WIKIJS_PROJECT=projects/cuisineflow +``` + +**Path Resolution:** +- Full Wiki.js path = `{WIKIJS_BASE_PATH}/{WIKIJS_PROJECT}` +- For cuisineflow: `/hyper-hive-labs/projects/cuisineflow` +- For intuit-engine: `/hyper-hive-labs/projects/intuit-engine` + +### PMO Configuration (No Project Scope) + +**PMO operates at company level:** +- **Gitea**: No `GITEA_REPO` → accesses all repos +- **Wiki.js**: No `WIKIJS_PROJECT` → accesses entire `/hyper-hive-labs` namespace + +--- + +## Plugin Structure + +### Repository Structure (CORRECT) + +``` +hyperhivelabs/claude-plugins/ +├── mcp-servers/ # SHARED by both plugins +│ ├── gitea/ +│ │ ├── .venv/ +│ │ ├── requirements.txt +│ │ │ # anthropic-sdk>=0.18.0 +│ │ │ # python-dotenv>=1.0.0 +│ │ │ # requests>=2.31.0 +│ │ │ # pydantic>=2.5.0 +│ │ ├── .env.example +│ │ ├── mcp_server/ +│ │ │ ├── __init__.py +│ │ │ ├── server.py +│ │ │ ├── config.py +│ │ │ ├── gitea_client.py +│ │ │ └── tools/ +│ │ │ ├── issues.py +│ │ │ └── labels.py +│ │ └── tests/ +│ │ ├── test_config.py +│ │ ├── test_gitea_client.py +│ │ └── test_tools.py +│ └── wikijs/ +│ ├── .venv/ +│ ├── requirements.txt +│ │ # anthropic-sdk>=0.18.0 +│ │ # python-dotenv>=1.0.0 +│ │ # gql>=3.4.0 +│ │ # aiohttp>=3.9.0 +│ │ # pydantic>=2.5.0 +│ ├── .env.example +│ ├── mcp_server/ +│ │ ├── __init__.py +│ │ ├── server.py +│ │ ├── config.py +│ │ ├── wikijs_client.py +│ │ └── tools/ +│ │ ├── pages.py +│ │ ├── lessons_learned.py +│ │ └── documentation.py +│ └── tests/ +│ ├── test_config.py +│ ├── test_wikijs_client.py +│ └── test_tools.py +├── projman/ # Project plugin +│ ├── .claude-plugin/ +│ │ └── plugin.json +│ ├── .mcp.json # Points to ../mcp-servers/ +│ ├── commands/ +│ │ ├── sprint-plan.md +│ │ ├── sprint-start.md +│ │ ├── sprint-status.md +│ │ ├── sprint-close.md +│ │ └── labels-sync.md +│ ├── agents/ +│ │ ├── planner.md +│ │ ├── orchestrator.md +│ │ └── executor.md +│ ├── skills/ +│ │ └── label-taxonomy/ +│ │ └── labels-reference.md +│ ├── README.md +│ └── CONFIGURATION.md +└── projman-pmo/ # PMO plugin + ├── .claude-plugin/ + │ └── plugin.json + ├── .mcp.json # Points to ../mcp-servers/ + ├── commands/ + │ ├── pmo-status.md + │ ├── pmo-priorities.md + │ ├── pmo-dependencies.md + │ └── pmo-schedule.md + ├── agents/ + │ └── pmo-coordinator.md + └── README.md +``` + +--- + +## MCP Configuration Files + +### projman .mcp.json (Project-Scoped) + +```json +{ + "mcpServers": { + "gitea-projman": { + "command": "python", + "args": ["-m", "mcp_server.server"], + "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea", + "env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea", + "GITEA_API_URL": "${GITEA_API_URL}", + "GITEA_API_TOKEN": "${GITEA_API_TOKEN}", + "GITEA_OWNER": "${GITEA_OWNER}", + "GITEA_REPO": "${GITEA_REPO}" + } + }, + "wikijs-projman": { + "command": "python", + "args": ["-m", "mcp_server.server"], + "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs", + "env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs", + "WIKIJS_API_URL": "${WIKIJS_API_URL}", + "WIKIJS_API_TOKEN": "${WIKIJS_API_TOKEN}", + "WIKIJS_BASE_PATH": "${WIKIJS_BASE_PATH}", + "WIKIJS_PROJECT": "${WIKIJS_PROJECT}" + } + } + } +} +``` + +### projman-pmo .mcp.json (Company-Wide) + +```json +{ + "mcpServers": { + "gitea-pmo": { + "command": "python", + "args": ["-m", "mcp_server.server"], + "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea", + "env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea", + "GITEA_API_URL": "${GITEA_API_URL}", + "GITEA_API_TOKEN": "${GITEA_API_TOKEN}", + "GITEA_OWNER": "${GITEA_OWNER}" + } + }, + "wikijs-pmo": { + "command": "python", + "args": ["-m", "mcp_server.server"], + "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs", + "env": { + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs", + "WIKIJS_API_URL": "${WIKIJS_API_URL}", + "WIKIJS_API_TOKEN": "${WIKIJS_API_TOKEN}", + "WIKIJS_BASE_PATH": "${WIKIJS_BASE_PATH}" + } + } + } +} +``` + +**Critical Notes:** +- Both plugins reference `../mcp-servers/` (shared location at repository root) +- **projman**: Includes `GITEA_REPO` and `WIKIJS_PROJECT` for project-scoped operations +- **projman-pmo**: Omits project-specific variables for company-wide operations + +--- + +## Wiki.js MCP Server Implementation + +### Configuration Loader + +```python +# mcp-wikijs/mcp_server/config.py +from pathlib import Path +from dotenv import load_dotenv +import os +from typing import Dict, Optional + +class WikiJSConfig: + """Hybrid configuration loader for Wiki.js""" + + def __init__(self): + self.api_url: Optional[str] = None + self.api_token: Optional[str] = None + self.base_path: Optional[str] = None + self.project_path: Optional[str] = None + self.full_path: Optional[str] = None + + def load(self) -> Dict[str, str]: + """ + Load Wiki.js configuration from system and project levels. + Composes full path from base_path + project_path. + """ + # Load system config + system_config = Path.home() / '.config' / 'claude' / 'wikijs.env' + if system_config.exists(): + load_dotenv(system_config) + else: + raise FileNotFoundError( + f"System config not found: {system_config}\n" + "Create it with: cat > ~/.config/claude/wikijs.env" + ) + + # Load project config (if exists, optional for PMO) + project_config = Path.cwd() / '.env' + if project_config.exists(): + load_dotenv(project_config, override=True) + + # Extract values + self.api_url = os.getenv('WIKIJS_API_URL') + self.api_token = os.getenv('WIKIJS_API_TOKEN') + self.base_path = os.getenv('WIKIJS_BASE_PATH') # /hyper-hive-labs + self.project_path = os.getenv('WIKIJS_PROJECT') # projects/cuisineflow (optional) + + # Compose full path + if self.project_path: + self.full_path = f"{self.base_path}/{self.project_path}" + else: + # PMO mode - entire company namespace + self.full_path = self.base_path + + # Validate required variables + self._validate() + + return { + 'api_url': self.api_url, + 'api_token': self.api_token, + 'base_path': self.base_path, + 'project_path': self.project_path, + 'full_path': self.full_path + } + + def _validate(self) -> None: + """Validate that required configuration is present""" + required = { + 'WIKIJS_API_URL': self.api_url, + 'WIKIJS_API_TOKEN': self.api_token, + 'WIKIJS_BASE_PATH': self.base_path + } + + missing = [key for key, value in required.items() if not value] + + if missing: + raise ValueError( + f"Missing required configuration: {', '.join(missing)}\n" + "Check your ~/.config/claude/wikijs.env file" + ) +``` + +### GraphQL Client + +```python +# mcp-wikijs/mcp_server/wikijs_client.py +from gql import gql, Client +from gql.transport.aiohttp import AIOHTTPTransport +from typing import List, Dict, Optional +from .config import WikiJSConfig + +class WikiJSClient: + """Client for interacting with Wiki.js GraphQL API""" + + def __init__(self): + config = WikiJSConfig() + config_dict = config.load() + + self.api_url = config_dict['api_url'] + self.api_token = config_dict['api_token'] + self.base_path = config_dict['base_path'] + self.project_path = config_dict.get('project_path') + self.full_path = config_dict['full_path'] + + # Set up GraphQL client + transport = AIOHTTPTransport( + url=self.api_url, + headers={'Authorization': f'Bearer {self.api_token}'} + ) + self.client = Client( + transport=transport, + fetch_schema_from_transport=True + ) + + async def search_pages( + self, + query: str, + path: Optional[str] = None, + tags: Optional[List[str]] = None + ) -> List[Dict]: + """ + Search pages in Wiki.js within a specific path. + + Args: + query: Search query string + path: Optional path to search within (defaults to full_path) + tags: Optional list of tags to filter by + """ + search_path = path or self.full_path + + gql_query = gql(""" + query SearchPages($query: String!, $path: String) { + pages { + search(query: $query, path: $path) { + results { + id + path + title + description + tags + updatedAt + } + } + } + } + """) + + result = await self.client.execute( + gql_query, + variable_values={'query': query, 'path': search_path} + ) + + pages = result['pages']['search']['results'] + + # Filter by tags if specified + if tags: + pages = [ + p for p in pages + if any(tag in p['tags'] for tag in tags) + ] + + return pages + + async def get_page(self, path: str) -> Dict: + """Fetch a specific page by path""" + gql_query = gql(""" + query GetPage($path: String!) { + pages { + single(path: $path) { + id + path + title + description + content + tags + createdAt + updatedAt + } + } + } + """) + + result = await self.client.execute( + gql_query, + variable_values={'path': path} + ) + return result['pages']['single'] + + async def create_page( + self, + path: str, + title: str, + content: str, + tags: List[str], + description: str = "" + ) -> Dict: + """ + Create a new page in Wiki.js. + + Args: + path: Full path for the page (e.g., /hyper-hive-labs/projects/cuisineflow/lessons-learned/sprints/sprint-01) + title: Page title + content: Page content (markdown) + tags: List of tags + description: Optional description + """ + gql_mutation = gql(""" + mutation CreatePage( + $path: String!, + $title: String!, + $content: String!, + $tags: [String]!, + $description: String + ) { + pages { + create( + path: $path, + title: $title, + content: $content, + tags: $tags, + description: $description, + isPublished: true, + editor: "markdown" + ) { + responseResult { + succeeded + errorCode + message + } + page { + id + path + title + } + } + } + } + """) + + result = await self.client.execute( + gql_mutation, + variable_values={ + 'path': path, + 'title': title, + 'content': content, + 'tags': tags, + 'description': description + } + ) + return result['pages']['create'] + + async def update_page( + self, + page_id: int, + content: str, + tags: Optional[List[str]] = None + ) -> Dict: + """Update existing page""" + variables = { + 'id': page_id, + 'content': content + } + + if tags is not None: + variables['tags'] = tags + + gql_mutation = gql(""" + mutation UpdatePage( + $id: Int!, + $content: String!, + $tags: [String] + ) { + pages { + update( + id: $id, + content: $content, + tags: $tags + ) { + responseResult { + succeeded + errorCode + message + } + } + } + } + """) + + result = await self.client.execute(gql_mutation, variable_values=variables) + return result['pages']['update'] + + async def list_pages(self, path: str) -> List[Dict]: + """List all pages within a path""" + gql_query = gql(""" + query ListPages($path: String!) { + pages { + list(path: $path, orderBy: TITLE) { + id + path + title + description + tags + updatedAt + } + } + } + """) + + result = await self.client.execute( + gql_query, + variable_values={'path': path} + ) + return result['pages']['list'] + + # Lessons Learned Specific Methods + + async def create_lesson( + self, + sprint_name: str, + lesson_content: str, + tags: List[str] + ) -> Dict: + """ + Create a lessons learned document for a sprint. + + Args: + sprint_name: Sprint identifier (e.g., "sprint-16-intuit-engine") + lesson_content: Full lesson markdown content + tags: Tags for categorization + """ + # Compose path within project's lessons-learned/sprints/ + lesson_path = f"{self.full_path}/lessons-learned/sprints/{sprint_name}" + title = f"Sprint {sprint_name.split('-')[1]}: {' '.join(sprint_name.split('-')[2:]).title()}" + + return await self.create_page( + path=lesson_path, + title=title, + content=lesson_content, + tags=tags, + description=f"Lessons learned from {sprint_name}" + ) + + async def search_lessons( + self, + query: str, + tags: Optional[List[str]] = None + ) -> List[Dict]: + """ + Search lessons learned within the current project. + + Args: + query: Search keywords + tags: Optional tags to filter by + """ + lessons_path = f"{self.full_path}/lessons-learned" + return await self.search_pages( + query=query, + path=lessons_path, + tags=tags + ) + + # PMO Multi-Project Methods + + async def search_all_projects( + self, + query: str, + tags: Optional[List[str]] = None + ) -> Dict[str, List[Dict]]: + """ + Search lessons across all projects (PMO mode). + Returns results grouped by project. + """ + all_projects_path = f"{self.base_path}/projects" + results = await self.search_pages( + query=query, + path=all_projects_path, + tags=tags + ) + + # Group by project + by_project = {} + for result in results: + # Extract project name from path + # e.g., "/hyper-hive-labs/projects/cuisineflow/..." -> "cuisineflow" + path_parts = result['path'].split('/') + if len(path_parts) >= 4: + project = path_parts[3] + if project not in by_project: + by_project[project] = [] + by_project[project].append(result) + + return by_project + + async def get_shared_docs(self, category: str) -> List[Dict]: + """ + Access company-wide shared documentation. + + Args: + category: Category within shared/ (e.g., "architecture-patterns", "best-practices") + """ + shared_path = f"{self.base_path}/shared/{category}" + return await self.list_pages(path=shared_path) +``` + +--- + +## MCP Tools Structure + +### Gitea MCP Tools + +```python +# mcp-gitea/mcp_server/tools/issues.py +class IssueTools: + def __init__(self, gitea_client): + self.gitea = gitea_client + + async def list_issues(self, state='open', labels=None): + """List issues in current repository""" + return await self.gitea.list_issues(state=state, labels=labels) + + async def get_issue(self, issue_number): + """Get specific issue details""" + return await self.gitea.get_issue(issue_number) + + async def create_issue(self, title, body, labels=None): + """Create new issue""" + return await self.gitea.create_issue(title, body, labels) + + # ... other issue tools + +# mcp-gitea/mcp_server/tools/labels.py +class LabelTools: + def __init__(self, gitea_client): + self.gitea = gitea_client + + async def get_labels(self): + """Get all labels from repository""" + return await self.gitea.get_labels() + + async def suggest_labels(self, context): + """Suggest appropriate labels based on context""" + # Label suggestion logic using taxonomy + pass +``` + +### Wiki.js MCP Tools + +```python +# mcp-wikijs/mcp_server/tools/pages.py +class PageTools: + def __init__(self, wikijs_client): + self.wikijs = wikijs_client + + async def search_pages(self, query, path=None, tags=None): + """Search Wiki.js pages""" + return await self.wikijs.search_pages(query, path, tags) + + async def get_page(self, path): + """Get specific page""" + return await self.wikijs.get_page(path) + + async def create_page(self, path, title, content, tags): + """Create new page""" + return await self.wikijs.create_page(path, title, content, tags) + + # ... other page tools + +# mcp-wikijs/mcp_server/tools/lessons_learned.py +class LessonsLearnedTools: + def __init__(self, wikijs_client): + self.wikijs = wikijs_client + + async def create_lesson(self, sprint_name, content, tags): + """Create lessons learned document""" + return await self.wikijs.create_lesson(sprint_name, content, tags) + + async def search_lessons(self, query, tags=None): + """Search past lessons""" + return await self.wikijs.search_lessons(query, tags) + + async def search_all_projects(self, query, tags=None): + """Search lessons across all projects (PMO)""" + return await self.wikijs.search_all_projects(query, tags) +``` + +--- + +## Setup Instructions + +### 1. System Configuration + +```bash +# Create config directory +mkdir -p ~/.config/claude + +# Create Gitea config +cat > ~/.config/claude/gitea.env << EOF +GITEA_API_URL=https://gitea.hyperhivelabs.com/api/v1 +GITEA_API_TOKEN=your_gitea_token +GITEA_OWNER=hyperhivelabs +EOF + +# Create Wiki.js config +cat > ~/.config/claude/wikijs.env << EOF +WIKIJS_API_URL=https://wiki.hyperhivelabs.com/graphql +WIKIJS_API_TOKEN=your_wikijs_token +WIKIJS_BASE_PATH=/hyper-hive-labs +EOF + +# Secure config files +chmod 600 ~/.config/claude/*.env +``` + +### 2. Project Configuration + +```bash +# In each project root +cat > .env << EOF +GITEA_REPO=cuisineflow +WIKIJS_PROJECT=projects/cuisineflow +EOF + +# Add to .gitignore +echo ".env" >> .gitignore +``` + +### 3. Install MCP Servers + +```bash +# Gitea MCP Server +cd /path/to/claude-plugins/mcp-servers/gitea +python -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt + +# Wiki.js MCP Server +cd /path/to/claude-plugins/mcp-servers/wikijs +python -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +``` + +### 4. Initialize Wiki.js Structure + +Create the base structure in Wiki.js web interface: +1. Navigate to https://wiki.hyperhivelabs.com +2. Create `/hyper-hive-labs` page +3. Create `/hyper-hive-labs/projects` page +4. Create `/hyper-hive-labs/company` page +5. Create `/hyper-hive-labs/shared` page + +Or use the Wiki.js API: +```python +# One-time setup script +import asyncio +from wikijs_client import WikiJSClient + +async def initialize_wiki_structure(): + client = WikiJSClient() + + # Create base pages + await client.create_page( + path="/hyper-hive-labs", + title="Hyper Hive Labs", + content="# Hyper Hive Labs Documentation", + tags=["company"] + ) + + await client.create_page( + path="/hyper-hive-labs/projects", + title="Projects", + content="# Project Documentation", + tags=["projects"] + ) + + # ... create other base pages + +asyncio.run(initialize_wiki_structure()) +``` + +--- + +## Benefits of This Architecture + +### 1. Separation of Concerns +- **Gitea MCP**: Project tracking, issues, labels +- **Wiki.js MCP**: Knowledge management, documentation + +### 2. Independent Configuration +- Update Gitea credentials without affecting Wiki.js +- Different token expiration policies +- Independent service availability + +### 3. Better Documentation Features +- Wiki.js rich editor +- Built-in search and indexing +- Tag system +- Version history +- Access control +- Web-based review and editing + +### 4. Company-Wide Knowledge Base +- Shared documentation accessible to all projects +- Cross-project lesson learning +- Best practices repository +- Onboarding materials +- Technical standards + +### 5. Scalability +- Add new projects easily +- Grow company documentation organically +- PMO has visibility across everything +- Individual projects stay focused + +--- + +## Migration from Single MCP + +If you have existing Wiki content in Git: + +```python +# Migration script +import asyncio +from wikijs_client import WikiJSClient +from pathlib import Path + +async def migrate_lessons_to_wikijs(): + """Migrate existing lessons learned from Git to Wiki.js""" + client = WikiJSClient() + + # Read existing markdown files + lessons_dir = Path("wiki/lessons-learned/sprints") + + for lesson_file in lessons_dir.glob("*.md"): + content = lesson_file.read_text() + sprint_name = lesson_file.stem + + # Extract tags from content (e.g., from frontmatter or hashtags) + tags = extract_tags(content) + + # Create in Wiki.js + await client.create_lesson( + sprint_name=sprint_name, + lesson_content=content, + tags=tags + ) + + print(f"Migrated: {sprint_name}") + +asyncio.run(migrate_lessons_to_wikijs()) +``` + +--- + +## Next Steps + +1. **Set up Wiki.js instance** if not already done +2. **Create base structure** in Wiki.js +3. **Implement both MCP servers** (Phase 1.1a and 1.1b) +4. **Test configuration** with both services +5. **Migrate existing lessons** (if applicable) +6. **Start using with next sprint** + +The two-MCP-server architecture provides a solid foundation for both project-level and company-wide knowledge management! \ No newline at end of file