Initial commit

2025-11-29 18:24:24 +08:00
commit f4fe5ac0c3
74 changed files with 33758 additions and 0 deletions
--- a/agents/project-context-manager.md
+++ b/agents/project-context-manager.md
@@ -0,0 +1,594 @@
+# project-context-manager
+
+**Specialized agent for managing active project context in CCPM.**
+
+## Purpose
+
+Handle all project context operations including setting active project, storing session state, and displaying project information. Centralizes context management to ensure consistency across commands.
+
+## Expertise
+
+- Context state management
+- Project switching workflows
+- Session persistence
+- Project information display
+- Context validation
+
+## Core Responsibilities
+
+### 1. Get Active Project Context
+
+Retrieve current active project and subproject.
+
+**Process**:
+1. Invoke `project-detector` to detect project
+2. Invoke `project-config-loader` to load config
+3. Combine detection + config into full context
+4. Return structured context
+
+**Return Format**:
+```javascript
+{
+  // Detection info
+  detected: {
+    project_id: "my-monorepo",
+    subproject: "frontend",
+    method: "subdirectory",
+    confidence: "high"
+  },
+
+  // Full project config
+  config: {
+    project_name: "My Monorepo",
+    description: "...",
+    repository: {...},
+    linear: {...},
+    tech_stack: {...},
+    subproject: {...}  // if applicable
+  },
+
+  // Display-ready strings
+  display: {
+    title: "My Monorepo › frontend",
+    subtitle: "React + TypeScript + Vite",
+    location: "/Users/dev/monorepo/apps/frontend",
+    labels: ["my-monorepo", "frontend"]
+  }
+}
+```
+
+### 2. Set Active Project
+
+Update the active project in configuration.
+
+**Process**:
+1. Validate project exists
+2. Update `context.current_project` in config file
+3. Optionally disable auto-detection
+4. Return confirmation
+
+**Input**:
+```yaml
+action: set_active_project
+project_id: my-monorepo
+disable_auto_detection: false  # keep auto-detection on
+```
+
+**Output**:
+```yaml
+result:
+  success: true
+  previous_project: null
+  new_project: my-monorepo
+  auto_detection: enabled
+  message: "Active project set to 'my-monorepo'"
+```
+
+### 3. Enable Auto-Detection
+
+Enable automatic project detection based on directory/git.
+
+**Process**:
+1. Set `context.current_project` to null
+2. Enable `context.detection.by_git_remote`
+3. Enable `context.detection.by_cwd`
+4. Return confirmation
+
+**Output**:
+```yaml
+result:
+  success: true
+  mode: auto_detection
+  methods:
+    - git_remote
+    - current_directory
+    - subdirectory_patterns
+  message: "Auto-detection enabled"
+```
+
+### 4. Clear Active Project
+
+Remove active project setting, requiring manual selection.
+
+**Process**:
+1. Set `context.current_project` to null
+2. Disable all auto-detection methods
+3. Return confirmation
+
+**Output**:
+```yaml
+result:
+  success: true
+  mode: manual_selection
+  message: "Active project cleared. Commands will prompt for project selection."
+```
+
+### 5. Display Project Context
+
+Format project context for display in commands.
+
+**Display Formats**:
+
+**Compact** (for command headers):
+```
+📋 Project: My Monorepo › frontend
+```
+
+**Standard** (for status displays):
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 Active Project
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Project:     My Monorepo
+Subproject:  frontend
+Tech Stack:  React, TypeScript, Vite
+Location:    /Users/dev/monorepo/apps/frontend
+Detection:   Auto (subdirectory match)
+```
+
+**Detailed** (for `/ccpm:project:show`):
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎯 Project: My Monorepo
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Description: Full-stack monorepo project
+Owner:       john.doe
+
+📁 Subproject: frontend
+   Description: Next.js web application
+   Path:        apps/frontend
+   Tech Stack:  React, Next.js, TypeScript, Tailwind CSS
+
+🔗 Repository:
+   URL:         https://github.com/org/monorepo
+   Branch:      main
+   Local Path:  /Users/dev/monorepo
+
+📋 Linear:
+   Team:        Engineering
+   Project:     My Monorepo
+   Labels:      monorepo, frontend, planning
+
+🛠️ Tech Stack (Overall):
+   Languages:   TypeScript, Python
+   Frontend:    React, Next.js
+   Backend:     FastAPI
+   Database:    PostgreSQL
+   Infra:       Vercel, AWS
+
+🔧 External PM:
+   Type:        Linear-only
+   Jira:        ❌ Disabled
+   Confluence:  ❌ Disabled
+   Slack:       ❌ Disabled
+
+🎯 Detection:
+   Method:      Subdirectory pattern match
+   Confidence:  High
+   Auto-detect: ✅ Enabled
+```
+
+### 6. List Available Projects
+
+Show all configured projects with active marker.
+
+**Output Format**:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 Configured Projects
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+⭐ my-monorepo (Active - Auto-detected)
+   My Monorepo
+   Subproject: frontend
+   Linear: Engineering / My Monorepo
+   📁 /Users/dev/monorepo
+
+   another-project
+   Another Project
+   Linear: Engineering / Another Project
+   🌐 https://github.com/org/another
+
+   work-project
+   Work Project
+   Linear: Work / Work Project
+   📁 /Users/dev/work-project
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Total: 3 projects
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Set active: /ccpm:project:set <project-id>
+Auto-detect: /ccpm:project:set auto
+```
+
+### 7. Validate Context
+
+Ensure current context is valid and usable.
+
+**Validation Checks**:
+- Project exists in configuration
+- Required fields present (Linear team/project)
+- If subproject specified, it exists in config
+- Detection method is valid
+- Config file is accessible
+
+**Output**:
+```yaml
+validation:
+  valid: true
+  project_exists: true
+  config_complete: true
+  subproject_valid: true
+  warnings: []
+```
+
+## Input/Output Contract
+
+### Input (Get Context)
+```yaml
+action: get_context
+include_config: true
+include_display: true
+format: standard  # compact | standard | detailed
+```
+
+### Input (Set Project)
+```yaml
+action: set_project
+project_id: my-monorepo
+mode: manual  # manual | auto | clear
+```
+
+### Input (List Projects)
+```yaml
+action: list_projects
+format: detailed  # simple | detailed
+show_inactive: true
+```
+
+## Error Handling
+
+### NO_PROJECTS_CONFIGURED
+```yaml
+error:
+  code: NO_PROJECTS_CONFIGURED
+  message: "No projects configured in CCPM"
+  actions:
+    - "Add project: /ccpm:project:add <project-id>"
+    - "See setup guide: docs/guides/project-setup.md"
+```
+
+### INVALID_PROJECT_STATE
+```yaml
+error:
+  code: INVALID_PROJECT_STATE
+  message: "Active project 'my-project' is not valid"
+  details: "Missing required field: linear.team"
+  actions:
+    - "Fix configuration: /ccpm:project:update my-project"
+    - "Clear active project: /ccpm:project:set clear"
+```
+
+## Performance Considerations
+
+- **Context Caching**: Cache context for command duration
+- **Lazy Config Load**: Only load config when needed
+- **Fast Display**: Pre-format strings for display
+- **Minimal Writes**: Only write config when necessary
+
+## Integration with Other Agents
+
+### With project-detector
+```javascript
+// Get detection
+const detection = Task(project-detector): "Detect active project"
+
+// Add full config
+const context = Task(project-context-manager): `
+Get full context for project: ${detection.project_id}
+Subproject: ${detection.subproject}
+Format: standard
+`
+```
+
+### With project-config-loader
+```javascript
+// Context manager orchestrates both
+const context = Task(project-context-manager): `
+Get active project context
+Include detection + config
+Format: detailed
+`
+```
+
+## Integration with Commands
+
+### Pattern 1: Show Context in Command Header
+```markdown
+<!-- In command file -->
+Task(project-context-manager): "Get context, format: compact"
+
+# Display: 📋 Project: My Monorepo › frontend
+```
+
+### Pattern 2: Full Context for Operations
+```markdown
+<!-- In command that needs project info -->
+const context = Task(project-context-manager): "Get context, include all"
+
+# Use context.config.linear.team for Linear operations
+# Use context.config.tech_stack for agent selection
+# Use context.display for user-facing messages
+```
+
+### Pattern 3: Switch Projects
+```markdown
+<!-- In /ccpm:project:set command -->
+Task(project-context-manager): `
+Set active project: ${projectId}
+Mode: manual
+`
+```
+
+## Best Practices
+
+- Always get full context at start of command
+- Use display-ready strings for user-facing output
+- Cache context to avoid repeated agent calls
+- Validate context before critical operations
+- Provide clear feedback on context changes
+- Handle missing/invalid context gracefully
+
+## Testing Scenarios
+
+1. **Get Context - Auto Detected**: Should return project + subproject
+2. **Get Context - Manual Set**: Should return configured project
+3. **Set Project**: Should update config and confirm
+4. **Enable Auto-Detection**: Should clear manual setting
+5. **List Projects**: Should mark active project with ⭐
+6. **Invalid Context**: Should return clear error with actions
+7. **No Projects**: Should guide user to setup
+
+## Maintenance Notes
+
+- Keep display formats consistent across commands
+- Update when new config fields added
+- Monitor context access patterns
+- Optimize caching strategy
+- Document context structure changes
+
+## Related Skills
+
+This agent orchestrates project context with guidance from CCPM skills:
+
+### project-operations Skill
+
+**When the skill helps this agent**:
+- Provides workflow guidance for context management
+- Documents display format standards
+- Shows integration patterns with commands
+- Explains multi-project workflows
+
+**How to use**:
+```markdown
+# When managing complex context:
+Task(project-context-manager): "Set active project with auto-detection"
+
+# For workflow guidance:
+Skill(project-operations): "Best practices for project switching workflows"
+
+# Skill provides:
+# - When to use manual vs auto-detection
+# - Display format standards
+# - Context caching strategies
+```
+
+### project-detection Skill
+
+**When the skill helps this agent**:
+- Documents detection methods and priority
+- Explains auto-detection workflows
+- Shows error handling patterns
+
+**Reference for detection**:
+```markdown
+# Agent uses detection results:
+Task(project-context-manager): "Get active project context"
+
+# Internally invokes:
+Task(project-detector): "Detect project"
+
+# Follows skill patterns from project-detection:
+Skill(project-detection): "Detection priority order and error handling"
+```
+
+## Skill Integration Patterns
+
+### Pattern 1: Context Display Formatting
+
+```markdown
+# Agent needs to format context for display:
+Task(project-context-manager): "Display project context, format: detailed"
+
+# Agent references skill for format standards:
+Skill(project-operations): "Standard display formats for project context"
+
+# Skill provides:
+# - Compact format (command headers)
+# - Standard format (status displays)
+# - Detailed format (project info pages)
+
+# Agent implements consistent formatting
+```
+
+### Pattern 2: Project Switching Workflow
+
+```markdown
+# User wants to switch projects:
+Task(project-context-manager): "Set active project: new-project"
+
+# Agent references skill for workflow:
+Skill(project-operations): "Project switching best practices"
+
+# Skill provides:
+# - Validation steps
+# - Context update sequence
+# - User feedback patterns
+# - Error handling
+
+# Agent implements following skill guidance
+```
+
+### Pattern 3: Auto-Detection Management
+
+```markdown
+# User enables auto-detection:
+Task(project-context-manager): "Enable auto-detection"
+
+# Agent references detection skill:
+Skill(project-detection): "Auto-detection configuration and workflows"
+
+# Skill provides:
+# - Detection methods to enable
+# - Configuration updates needed
+# - User guidance on usage
+
+# Agent implements based on skill patterns
+```
+
+### Pattern 4: Error Recovery
+
+```markdown
+# Context validation fails:
+Task(project-context-manager): "Validate current context"
+
+# Agent finds invalid state
+# References skill for recovery:
+Skill(project-operations): "Error recovery for invalid project context"
+
+# Skill provides:
+# - Error classification
+# - Recovery steps
+# - User-facing messages
+# - Alternative workflows
+
+# Agent implements recovery following skill guidance
+```
+
+## Skill-Guided Context Operations
+
+### Get Context Operation
+
+```markdown
+# Full workflow with skill guidance:
+
+# 1. Detect project (uses project-detection skill patterns)
+const detection = Task(project-detector): "Detect project"
+
+# 2. Load config (uses project-operations skill patterns)
+const config = Task(project-config-loader): "Load project: ${detection.project_id}"
+
+# 3. Format display (follows skill format standards)
+Skill(project-operations): "Context display format for ${displayMode}"
+
+# 4. Return structured context following skill patterns
+return {
+  detected: detection,
+  config: config,
+  display: formattedDisplay
+}
+```
+
+### Set Project Operation
+
+```markdown
+# Full workflow with skill guidance:
+
+# 1. Validate project exists
+Task(project-config-loader): "Validate project: ${projectId}"
+
+# 2. Check workflow pattern
+Skill(project-operations): "Manual project setting workflow"
+
+# 3. Update configuration following skill guidance
+# 4. Return confirmation with skill-standard messaging
+```
+
+## Best Practices for Skill Usage
+
+1. **Follow Skill Display Standards**: Keep formatting consistent
+2. **Reference Skills for Workflows**: Complex operations should follow skill patterns
+3. **Use Skills for Error Messages**: User-facing errors match skill documentation
+4. **Coordinate with Other Skills**: Project operations work with PM workflow skills
+5. **Update Skills When Agent Changes**: Keep workflow docs synchronized
+
+## Cross-Skill Coordination
+
+### With PM Workflow Guide
+
+```markdown
+# When user creates task:
+Skill(pm-workflow-guide): Auto-activates for workflow guidance
+
+# Workflow guide invokes context:
+Task(project-context-manager): "Get active project context"
+
+# Context provides:
+# - Project for Linear operations
+# - Tech stack for agent selection
+# - Labels for issue creation
+
+# Both skills work together seamlessly
+```
+
+### With External System Safety
+
+```markdown
+# When external PM operations needed:
+Task(project-context-manager): "Get project config"
+
+# Config indicates external PM enabled
+# External system safety skill auto-activates
+Skill(external-system-safety): Enforces confirmation workflow
+
+# Context manager provides project config to safety skill
+# Safety skill uses config to determine which systems to protect
+```
+
+## Documentation Synchronization
+
+**When agent changes, update**:
+1. This agent's implementation
+2. `project-operations` skill documentation
+3. `project-detection` skill if detection behavior changes
+4. Command integration examples
+5. User-facing guides and troubleshooting
+
+**Maintain consistency across**:
+- Display formats (agent + skills + commands)
+- Error messages (agent + skills)
+- Workflow patterns (agent + skills + commands)
+- Configuration schema (agent + skills + config file)