gh-duongdev-ccpm/agents/project-context-manager.md

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:

{
  // 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:

action: set_active_project
project_id: my-monorepo
disable_auto_detection: false  # keep auto-detection on

Output:

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:

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:

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:

validation:
  valid: true
  project_exists: true
  config_complete: true
  subproject_valid: true
  warnings: []

Input/Output Contract

Input (Get Context)

action: get_context
include_config: true
include_display: true
format: standard  # compact | standard | detailed

Input (Set Project)

action: set_project
project_id: my-monorepo
mode: manual  # manual | auto | clear

Input (List Projects)

action: list_projects
format: detailed  # simple | detailed
show_inactive: true

Error Handling

NO_PROJECTS_CONFIGURED

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

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

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

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

<!-- In command file -->
Task(project-context-manager): "Get context, format: compact"

# Display: 📋 Project: My Monorepo › frontend

Pattern 2: Full Context for Operations

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

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

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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