leo-claude-mktplace/CLAUDE.md

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 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