initial project setup

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