Project Detection Skill

This skill ensures every CCPM command has the correct project context. It auto-activates to provide seamless project detection without user intervention.

Instructions

Automatic Activation

This skill activates automatically:

At command start: Before any CCPM command executes
Context validation: When project context is needed
Error recovery: When project detection fails

Core Detection Flow

mermaid

graph TD
    A[Command Starts] --> B{Manual Project Set?}
    B -->|Yes| C[Use Manual Setting]
    B -->|No| D{Auto-Detection Enabled?}
    D -->|Yes| E[Invoke project-detector]
    D -->|No| F[Prompt User for Project]
    E --> G{Project Detected?}
    G -->|Yes| H[Load Full Config]
    G -->|No| F
    H --> I[Cache Context]
    I --> J[Command Proceeds]
    C --> H
    F --> J

Detection Priority Order

Manual Setting (Highest Priority)
- User explicitly set: /ccpm:project:set my-project
- Stored in context.current_project
- Overrides all auto-detection
Git Remote URL Match
- Match current git remote against projects.*.repository.url
- Normalizes git@ and https:// URLs
- Works in any subdirectory of repo
Subdirectory Pattern Match (NEW)
- Check if CWD is in project's local_path
- Match against context.detection.subdirectories patterns
- Returns project + active subproject
- Supports glob patterns
Local Path Match
- Match CWD against projects.*.repository.local_path
- Uses longest-match-wins
- No subproject info
Custom Patterns
- Match against context.detection.patterns
- User-defined glob patterns
- Flexible for non-standard setups

Agent Integration

Always use the project-detector agent:

javascript

// At the start of every command
const detection = Task(project-detector): `
Detect active project

Environment:
- Current directory: ${cwd}
- Git remote: ${gitRemote}
- Config: ~/.claude/ccpm-config.yaml
`

if (detection.error) {
  // Handle no project detected
  console.error(detection.error.message)
  detection.error.suggestions.forEach(s => console.log(s))
  return
}

// Cache for command duration
const PROJECT_CONTEXT = {
  id: detection.project_id,
  name: detection.project_name,
  subproject: detection.subproject,
  method: detection.detection_method
}

Monorepo Detection

For monorepos with multiple sub-projects:

Configuration

yaml

projects:
  my-monorepo:
    repository:
      url: https://github.com/org/monorepo
      local_path: /Users/dev/monorepo

    context:
      detection:
        subdirectories:
          - subproject: web-app
            match_pattern: "*/apps/web/*"
            priority: 10

          - subproject: mobile-app
            match_pattern: "*/apps/mobile/*"
            priority: 10

          - subproject: api-server
            match_pattern: "*/services/api/*"
            priority: 10

    code_repository:
      subprojects:
        - name: web-app
          path: apps/web
          tech_stack:
            frontend: [react, nextjs]

        - name: mobile-app
          path: apps/mobile
          tech_stack:
            frontend: [react-native, expo]

Detection Examples

Example 1: Web App Directory

bash

$ cd /Users/dev/monorepo/apps/web/src/components
$ /ccpm:plan "Add dark mode"

# Detection flow:
# 1. Git remote → matches "my-monorepo" ✓
# 2. Subdirectory → CWD matches "*/apps/web/*" ✓
# 3. Result: project="my-monorepo", subproject="web-app"

# Display:
📋 Project: My Monorepo › web-app
🛠️ Tech Stack: React, Next.js

# Linear labels: [my-monorepo, web-app, planning]

Example 2: Mobile App Directory

bash

$ cd /Users/dev/monorepo/apps/mobile
$ /ccpm:work WORK-123

# Detection:
# → project="my-monorepo", subproject="mobile-app"

# Display:
📋 Project: My Monorepo › mobile-app
🛠️ Tech Stack: React Native, Expo

Example 3: Repository Root

bash

$ cd /Users/dev/monorepo
$ /ccpm:project:list

# Detection:
# 1. Git remote → matches "my-monorepo" ✓
# 2. Subdirectory → CWD at root, no pattern match
# 3. Result: project="my-monorepo", subproject=null

# Display:
📋 Project: My Monorepo
⭐ Active (Git remote match)

Pattern Matching Logic

Glob Patterns Supported:

yaml

# Match any path containing /frontend/
"*/frontend/*"

# Match specific nesting
"apps/web/src/*"

# Match multiple levels
"**/services/**"

# Match alternatives (requires extension)
"apps/{web,mobile}/*"

Priority Handling:

When multiple patterns match, higher priority wins:

yaml

subdirectories:
  # Specific pattern (high priority)
  - subproject: admin-panel
    match_pattern: "*/apps/web/admin/*"
    priority: 20

  # General pattern (lower priority)
  - subproject: web-app
    match_pattern: "*/apps/web/*"
    priority: 10

# Working in: /apps/web/admin/users
# Both patterns match, but "admin-panel" wins (priority 20 > 10)

Context Display

In Command Headers:

📋 Project: My Monorepo › frontend

In Status Displays:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 Active Project
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Project:     My Monorepo
Subproject:  frontend
Tech Stack:  React, TypeScript, Vite
Location:    /Users/dev/monorepo/apps/frontend
Detection:   Auto (subdirectory match)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Error Handling

Scenario 1: No Project Detected

Situation: User runs command outside any configured project

Detection Result:

javascript

{
  error: {
    code: "NO_PROJECT_DETECTED",
    message: "Could not detect active project",
    suggestions: [
      "Set active project: /ccpm:project:set <project-id>",
      "Enable auto-detection: /ccpm:project:set auto",
      "Check current directory is within a configured project",
      "List projects: /ccpm:project:list"
    ]
  }
}

Command Response:

❌ Could not detect active project

You are currently in: /Users/dev/random-project

CCPM couldn't match this to any configured project.

Options:
1. Set a specific project:
   /ccpm:project:set <project-id>

2. Enable auto-detection and cd to a configured project:
   /ccpm:project:set auto
   cd ~/my-project

3. Add this project to CCPM:
   /ccpm:project:add new-project

4. See all configured projects:
   /ccpm:project:list

Scenario 2: Ambiguous Detection

Situation: Multiple projects match (rare, but possible)

Detection Result:

javascript

{
  error: {
    code: "AMBIGUOUS_PROJECT",
    message: "Multiple projects match current context",
    candidates: [
      { project: "my-monorepo", reason: "Git remote matches" },
      { project: "local-clone", reason: "Working directory matches" }
    ]
  }
}

Command Response:

⚠️  Multiple projects match your current location

Candidates:
1. my-monorepo (Git remote: github.com/org/monorepo)
2. local-clone (Local path: /Users/dev/monorepo)

Please specify which project:
/ccpm:project:set my-monorepo

Or disable one detection method in config.

Scenario 3: Configuration Error

Situation: Project detected but config invalid

Command Response:

❌ Project configuration error

Project 'my-project' detected but has errors:
- Missing required field: linear.team
- Missing required field: linear.project

Fix with:
/ccpm:project:update my-project --field linear.team

Or edit config manually:
~/.claude/ccpm-config.yaml

Auto-Detection vs Manual Setting

Manual Setting (Stable)

Use When:

Working exclusively on one project
Want consistent context across sessions
Terminal multiplexing (tmux, iTerm tabs)

How:

bash

/ccpm:project:set my-project

# Now ALL commands use my-project, regardless of directory

Pros:

Consistent everywhere
No surprises
Fast (no detection needed)

Cons:

Must manually switch projects
Not ideal for monorepo workflows

Auto-Detection (Flexible)

Use When:

Working on multiple projects
Monorepo with subdirectories
Frequent project switching

How:

bash

/ccpm:project:set auto

# Now commands detect based on directory/git
cd ~/monorepo/apps/frontend  # → project: monorepo, sub: frontend
cd ~/other-project           # → project: other-project

Pros:

Seamless project switching
Natural workflow (cd = switch)
Ideal for monorepos

Cons:

Small detection overhead
Must be in correct directory

Performance Considerations

Detection Speed:

Manual setting: 0ms (instant lookup)
Auto-detection: <100ms (cached after first)

Caching:

javascript

// Detect once per command
if (!CACHED_CONTEXT) {
  CACHED_CONTEXT = Task(project-detector): "Detect project"
}

// Reuse for entire command
const project = CACHED_CONTEXT.project_id

Optimization:

Config file read once, cached
Git operations cached per session
Pattern matching is fast (string ops)

Integration with Commands

Every CCPM command should start with:

markdown

## Step 1: Detect Project Context

Skill(project-detection): This auto-activates

Task(project-detector): `
Detect active project
`

If detection succeeds → proceed
If detection fails → show error and exit

Then load full config:

markdown

## Step 2: Load Project Configuration

Task(project-config-loader): `
Load configuration for project: ${PROJECT_ID}
Include subproject: ${SUBPROJECT}
Validate: true
`

Testing Scenarios

Git Remote Match: In repo with matching remote
Subdirectory Match: In monorepo subdir
Manual Override: Manual setting overrides auto
No Match: Outside any project
Nested Subdirs: In deeply nested subdir
Priority Conflict: Multiple patterns match

Troubleshooting Guide

Problem: "No project detected" but I'm in a project

Solution:

bash

# Check config file exists
ls -la ~/.claude/ccpm-config.yaml

# Check git remote matches
git remote get-url origin
# Compare with config: projects.*.repository.url

# Check local path if set
pwd
# Compare with config: projects.*.repository.local_path

# Try manual setting
/ccpm:project:set <project-id>

Problem: "Wrong subproject detected"

Solution:

bash

# Check subdirectory patterns in config
cat ~/.claude/ccpm-config.yaml | grep -A 20 "subdirectories:"

# Verify pattern matches current path
pwd
# Should match one of the patterns

# Adjust pattern or priority if needed
/ccpm:project:update <project-id> --field context.detection.subdirectories

Problem: "Detection is slow"

Solution:

Switch to manual setting: /ccpm:project:set <project-id>
Reduce number of detection patterns
Disable unused detection methods in config

Best Practices

Enable Auto-Detection: Best for natural workflow
Configure Subdirectories: Essential for monorepos
Set Priorities: More specific patterns = higher priority
Validate Patterns: Test after configuration changes
Cache Context: Detect once, use throughout command
Handle Errors: Always provide actionable suggestions

Related Skills & Agents

Skills:

project-operations - Overall project management guidance
pm-workflow-guide - Workflow guidance with project context

Agents:

project-detector - Detection implementation
project-config-loader - Config loading
project-context-manager - Context management

Maintenance

When to update:

New detection methods added
Pattern matching logic changes
New project templates
Performance optimizations

Update locations:

This skill (guidance)
project-detector agent (implementation)
Command templates (integration)
Documentation (user guides)

Search AI Tools

project-detection

Install this agent skill to your Project

SKILL.md

Project Detection Skill

Instructions

Automatic Activation

Core Detection Flow

Detection Priority Order

Agent Integration

Monorepo Detection

Configuration

Detection Examples

Pattern Matching Logic

Context Display

Error Handling

Scenario 1: No Project Detected

Scenario 2: Ambiguous Detection

Scenario 3: Configuration Error

Auto-Detection vs Manual Setting

Manual Setting (Stable)

Auto-Detection (Flexible)

Performance Considerations

Integration with Commands

Testing Scenarios

Troubleshooting Guide

Best Practices

Related Skills & Agents

Maintenance