initial project setup

2025-11-05 12:22:02 -05:00
commit 8fcaf6d974
6 changed files with 2008 additions and 0 deletions
--- a/docs/projman-implementation-plan.md
+++ b/docs/projman-implementation-plan.md
--- a/docs/projman-plugin-analysis.md
+++ 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.