From 8fcaf6d974df551bba25756a5d7f4e64c8078c63 Mon Sep 17 00:00:00 2001 From: l3ocho Date: Wed, 5 Nov 2025 12:22:02 -0500 Subject: [PATCH] initial project setup --- .claude-plugins/marketplace.json | 0 .gitignore | 124 ++++ CLAUDE.md | 226 ++++++ README.md | 0 docs/projman-implementation-plan.md | 1022 +++++++++++++++++++++++++++ docs/projman-plugin-analysis.md | 636 +++++++++++++++++ 6 files changed, 2008 insertions(+) create mode 100644 .claude-plugins/marketplace.json create mode 100644 .gitignore create mode 100644 CLAUDE.md create mode 100644 README.md create mode 100644 docs/projman-implementation-plan.md create mode 100644 docs/projman-plugin-analysis.md diff --git a/.claude-plugins/marketplace.json b/.claude-plugins/marketplace.json new file mode 100644 index 0000000..e69de29 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2e74085 --- /dev/null +++ b/.gitignore @@ -0,0 +1,124 @@ +# Python +*.py[cod] +*$py.class +*.so +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +pip-wheel-metadata/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# Virtual Environments +venv/ +ENV/ +env/ +.venv +.ENV +.env.local + +# PyCharm +.idea/ + +# VS Code +.vscode/ +*.code-workspace + +# Jupyter Notebook +.ipynb_checkpoints + +# pyenv +.python-version + +# Pytest +.pytest_cache/ +.coverage +htmlcov/ + +# Node.js (for MCP servers) +node_modules/ +npm-debug.log* +yarn-debug.log* +yarn-error.log* +package-lock.json +.npm +.yarn/ + +# TypeScript +*.tsbuildinfo +dist/ +build/ + +# Environment variables (IMPORTANT: Contains Gitea credentials) +.env +.env.local +.env.*.local + +# OS +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db +Thumbs.db +*~ + +# Claude Code +.claude/settings.local.json +.claude/history/ + +# Logs +logs/ +*.log + +# Temporary files +tmp/ +temp/ +*.tmp +*.bak +*.swp +*.swo + +# Build artifacts +*.wasm +*.exe +*.dll +*.so +*.dylib + +# Testing +.tox/ +.coverage +.coverage.* +coverage.xml +*.cover +.hypothesis/ + +# Documentation builds +docs/_build/ +site/ + +# Database +*.db +*.sqlite +*.sqlite3 + +# Secrets and credentials +*credentials* +*secret* +*token* +!.gitkeep diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..c2adb0c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,226 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +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) + +These plugins transform a proven 15-sprint workflow into reusable, distributable tools for managing software development with Claude Code, Gitea, and agile methodologies. + +## Core Architecture + +### Three-Agent Model + +The plugins implement a three-agent architecture that mirrors the proven workflow: + +**Planner Agent** (`agents/planner.md`) +- Performs architecture analysis and sprint planning +- Creates detailed planning documents +- Makes architectural decisions +- Creates Gitea issues with appropriate labels +- Personality: Asks clarifying questions, thinks through edge cases, never rushes + +**Orchestrator Agent** (`agents/orchestrator.md`) +- Coordinates sprint execution +- Generates lean execution prompts (not full docs) +- Tracks progress and updates documentation +- Handles Git operations (commit, merge, cleanup) +- Manages task dependencies +- Personality: Concise, action-oriented, tracks details meticulously + +**Executor Agent** (`agents/executor.md`) +- Implements features according to execution prompts +- Writes clean, tested code +- Follows architectural decisions from planning +- Generates completion reports +- Personality: Implementation-focused, follows specs precisely + +### MCP Server Integration + +Both plugins use a Gitea MCP server (`mcp-server/`) to expose Gitea API as tools: + +**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 + +Configuration lives in `.mcp.json` and uses environment variables for Gitea credentials. + +## Branch-Aware Security Model + +Plugin behavior adapts to the current Git branch to prevent accidental changes: + +**Development Mode** (`development`, `feat/*`) +- Full access to all operations +- Can create Gitea issues +- Can modify all files + +**Staging Mode** (`staging`) +- Read-only for application code +- Can modify `.env` files +- Can create issues to document needed fixes +- Warns on attempted code changes + +**Production Mode** (`main`) +- Read-only for application code +- Emergency-only `.env` modifications +- Can create incident issues +- Blocks code changes + +This behavior is implemented in both CLAUDE.md (file-level) and plugin agents (tool-level). + +## Label Taxonomy System + +The project uses a sophisticated 43-label taxonomy at organization level: + +**Organization Labels (27):** +- Agent/2, Complexity/3, Efforts/5, Priority/4, Risk/3, Source/4, Type/6 + +**Repository Labels (16):** +- Component/9, Tech/7 + +**Important Labels:** +- `Type/Refactor` - For architectural changes and code restructuring (exclusive Type label) +- Used for service extraction, architecture modifications, technical debt + +The label system includes: +- `skills/label-taxonomy/labels-reference.md` - Local reference synced from Gitea +- Label suggestion logic that detects appropriate labels from context +- `/labels-sync` command to review and sync changes from Gitea + +## Lessons Learned System + +**Critical Feature:** After 15 sprints without lesson capture, repeated mistakes occurred (e.g., Claude Code infinite loops on similar issues 2-3 times). + +**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 +``` + +**Workflow:** +- Orchestrator captures lessons at sprint close +- Planner searches relevant lessons at sprint start +- INDEX.md maintained automatically +- Focus on preventable repetitions, not every detail + +## Development Workflow + +### Build Order + +1. **Phase 1-8:** Build `projman` plugin first (single-repo) +2. **Phase 9-11:** Build `pmo` plugin second (multi-project) +3. **Phase 12:** Production deployment + +See [docs/reference-material/projman-implementation-plan.md](docs/reference-material/projman-implementation-plan.md) for the complete 12-phase implementation plan. + +### Plugin Structure + +``` +projman/ +├── .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 +``` + +### 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 + +**Skills as Knowledge, Not Orchestrators:** +- Skills provide supporting knowledge loaded when relevant +- Agents are the primary interface +- Reduces token usage +- Makes knowledge reusable across agents + +**Branch Detection:** +- Two layers: CLAUDE.md (file access) + Plugin agents (tool usage) +- Defense in depth approach +- Plugin works with or without CLAUDE.md + +## Multi-Project Context (PMO Plugin) + +The `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 +- Dependency tracking and visualization +- Resource allocation across projects +- Deployment coordination +- Multi-project prioritization + +Build PMO plugin AFTER projman is working and validated. + +## Testing Approach + +**Local Marketplace:** +Create local marketplace for plugin development: +``` +~/projman-dev-marketplace/ +├── .claude-plugin/ +│ └── marketplace.json +└── projman/ # Symlink to plugin directory +``` + +**Integration Testing:** +Test in real CuisineFlow repository with actual Gitea instance before distribution. + +**Success 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: Better than current manual workflow + +## Important Notes + +- **Never modify docker-compose files with 'version' attribute** - It's obsolete +- **Focus on implementation, not over-engineering** - This system has been validated over 15 sprints +- **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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/projman-implementation-plan.md b/docs/projman-implementation-plan.md new file mode 100644 index 0000000..756743f --- /dev/null +++ b/docs/projman-implementation-plan.md @@ -0,0 +1,1022 @@ +# 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 new file mode 100644 index 0000000..7cc066e --- /dev/null +++ b/docs/projman-plugin-analysis.md @@ -0,0 +1,636 @@ +# 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.