initial project setup

.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

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

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.