| name | project-operations |
| description | Provides intelligent project setup and management with agent-based architecture to minimize token usage. Auto-activates when user mentions project setup, "add project", "configure project", "monorepo", "subdirectories", "switch project", or "project info". Uses three specialized agents internally: project-detector (detect active), project-config-loader (load settings with validation), project-context-manager (manage active project). Guides through four workflows: Add New Project (setup + templates), Configure Monorepo (pattern matching + subdirectories), Switch Between Projects (auto or manual), View Project Information. Provides templates for common architectures (fullstack-with-jira, fullstack-linear-only, mobile-app, monorepo). Validates configuration and suggests fixes for errors. Handles context-aware error handling with specific fix suggestions. |
Project Operations Skill
This skill handles all project-related operations in CCPM, including setup, configuration, detection, and multi-project management. It automatically invokes specialized agents to optimize performance and reduce token usage.
Instructions
Automatic Activation
This skill activates when user mentions:
- Project setup or configuration
- Adding/updating/deleting projects
- Multi-project management
- Monorepo or subdirectory configuration
- Project switching or detection
- Active project context
Core Principles
- Agent-First Approach: Always use specialized agents for project operations
- Minimal Token Usage: Agents handle heavy logic, skills provide guidance
- Context-Aware: Detect project context before operations
- User-Friendly: Clear errors and actionable suggestions
Agent Usage Patterns
Pattern 1: Detect Project Context
When: Command needs to know active project
Implementation:
const detection = Task(project-detector): `
Detect active project for current environment
Current directory: ${cwd}
Git remote: ${gitRemote}
`
const context = Task(project-context-manager): `
Get full context for detected project
Project ID: ${detection.project_id}
Subproject: ${detection.subproject}
Include config: true
Format: standard
`
console.log(`๐ Project: ${context.display.title}`)
Benefits:
- Consistent detection logic
- Reduces token usage (agent handles logic)
- Structured output ready for use
Pattern 2: Load Project Configuration
When: Command needs project settings (Linear, Jira, tech stack)
Implementation:
const config = Task(project-config-loader): `
Load configuration for project: ${projectId}
Include subproject: ${subprojectName}
Validate: true
`
if (!config.validation.valid) {
console.error("Configuration errors:", config.validation.errors)
return
}
const linearTeam = config.linear.team
const techStack = config.tech_stack.languages
Benefits:
- Validation built-in
- Structured, type-safe output
- Errors with actionable messages
Pattern 3: Manage Project Context
When: Setting active project, enabling auto-detection
Implementation:
const result = Task(project-context-manager): `
Set active project: ${projectId}
Mode: manual
Disable auto-detection: false
`
console.log(`โ
${result.message}`)
const result = Task(project-context-manager): `
Enable auto-detection
`
console.log(`โ
Auto-detection enabled`)
console.log(`Methods: ${result.methods.join(', ')}`)
Project Setup Workflows
Workflow 1: Add New Project
Trigger phrases:
- "add a new project"
- "configure new project"
- "set up project"
Command: /ccpm:project:add <project-id> [--template TEMPLATE]
Guidance:
Let's set up your new project!
Quick templates available:
1. fullstack-with-jira - Full-stack app with Jira integration
2. fullstack-linear-only - Full-stack app, Linear-only
3. mobile-app - React Native / Expo mobile app
4. monorepo - Multi-project repository with subdirectories
Or create custom configuration interactively.
Example:
/ccpm:project:add my-app --template fullstack-with-jira
Workflow 2: Configure Monorepo with Subdirectories
Trigger phrases:
- "monorepo setup"
- "subdirectories"
- "multiple projects in one repo"
Guidance:
For monorepos with subdirectories (like Nx, Turborepo):
1. Add the project:
/ccpm:project:add my-monorepo
2. Configure subdirectory detection:
Edit ~/.claude/ccpm-config.yaml:
```yaml
my-monorepo:
repository:
local_path: /Users/dev/monorepo
context:
detection:
subdirectories:
- subproject: frontend
match_pattern: "*/apps/frontend/*"
priority: 10
- subproject: backend
match_pattern: "*/apps/backend/*"
priority: 10
code_repository:
subprojects:
- name: frontend
path: apps/frontend
tech_stack:
languages: [typescript]
frameworks:
frontend: [react, nextjs]
-
Enable auto-detection:
/ccpm:project:set auto
-
Test detection:
cd /Users/dev/monorepo/apps/frontend
/ccpm:project:list # Should show "frontend" subproject active
#### Workflow 3: Switch Between Projects
**Trigger phrases**:
- "switch project"
- "change active project"
- "work on different project"
**Commands**:
- `/ccpm:project:set <project-id>` - Set specific project
- `/ccpm:project:set auto` - Enable auto-detection
- `/ccpm:project:list` - See all projects with active marker
**Agent usage**:
```javascript
// Commands internally use:
Task(project-context-manager): `
Set active project: ${projectId}
Mode: manual
`
// Then display with:
Task(project-context-manager): `
Get context
Format: standard
`
Workflow 4: View Project Information
Trigger phrases:
- "show project details"
- "what's my current project"
- "project info"
Commands:
/ccpm:project:show <project-id> - Detailed project info/ccpm:project:list - List all projects/ccpm:work <issue-id> - Task with project context
Agent usage:
Task(project-context-manager): `
Get context for project: ${projectId}
Format: detailed
Include all sections: true
`
Monorepo Support
CCPM provides first-class monorepo support with automatic subdirectory detection, pattern-based matching, and intelligent context switching.
What is Monorepo Support?
Monorepos contain multiple projects/packages in a single repository (e.g., Nx, Turborepo, Lerna). CCPM automatically detects which subproject you're working in and applies the correct configuration.
Key Features:
- Auto-detection based on working directory
- Pattern-based matching with glob patterns
- Priority weighting for conflict resolution
- Per-subproject tech stack and configuration
- Seamless context switching on
cd
- Performance: <100ms auto-detect, 0ms manual mode
How Subdirectory Detection Works
Priority-Based Resolution (highest to lowest):
- Manual Setting: User explicitly set project with
/ccpm:project:set
- Git Remote Match: Matches repository URL to project config
- Subdirectory Pattern Match: Matches current directory against glob patterns
- Local Path Match: Falls back to project root directory match
- Custom Patterns: User-defined patterns with priority weighting
Detection Flow Example:
Working in: /Users/dev/repeat/jarvis/src
Detection flow:
1. Check manual override โ None set
2. Check git remote โ matches "repeat" project โ
3. Check subdirectory patterns:
- "*/xygaming_symfony/*" (priority: 10) โ โ
- "*/jarvis/*" (priority: 10) โ โ
Match!
4. Return: project="repeat", subproject="jarvis"
Result:
๐ Project: Repeat โบ jarvis
๐ ๏ธ Tech Stack: TypeScript, Next.js, NestJS
Performance:
- Auto-detection: <100ms (cached for session)
- Manual mode: 0ms (no detection overhead)
- Session cache: Detection runs once per command
Subdirectory Configuration Commands
Use these commands to manage subdirectories in monorepos:
Add Subdirectory
/ccpm:project:subdir:add <project-id> <subproject-name> <path> [--pattern <pattern>] [--priority <priority>]
Example:
/ccpm:project:subdir:add my-monorepo frontend apps/frontend \
--pattern "*/apps/frontend/*" \
--priority 10
/ccpm:project:subdir:add my-monorepo backend apps/backend \
--pattern "*/apps/backend/*" \
--priority 15
List Subdirectories
/ccpm:project:subdir:list <project-id>
Shows all configured subdirectories with patterns and priorities.
Update Subdirectory
/ccpm:project:subdir:update <project-id> <subproject-name> [--field <field>]
Examples:
/ccpm:project:subdir:update my-monorepo frontend --field pattern="*/web/*"
/ccpm:project:subdir:update my-monorepo backend --field priority=20
/ccpm:project:subdir:update my-monorepo mobile --field tech_stack.languages=["typescript", "swift"]
Remove Subdirectory
/ccpm:project:subdir:remove <project-id> <subproject-name>
Pattern-Based Detection
Glob Pattern Syntax:
* - Matches any characters within a directory level** - Matches any number of directory levels? - Matches single character[abc] - Matches any character in set
Pattern Examples:
match_pattern: "*/apps/frontend/*"
match_pattern: "**/packages/ui/**"
- match_pattern: "*/apps/web/*"
priority: 10
- match_pattern: "*/web/*"
priority: 5
Priority Weighting:
- Higher number = higher priority
- Use priorities to resolve conflicts
- Recommended: 10 for standard, 15-20 for specific, 5 for fallback
Conflict Resolution Example:
subdirectories:
- subproject: admin-frontend
match_pattern: "*/apps/admin/*"
priority: 15
- subproject: frontend
match_pattern: "*/apps/*"
priority: 5
Project Context Switching
Auto-Detection Mode (recommended for monorepos):
/ccpm:project:set auto
cd /Users/dev/monorepo/apps/frontend
cd /Users/dev/monorepo/apps/backend
Manual Mode (stable across sessions):
/ccpm:project:set my-monorepo
cd /Users/dev/other-repo
When to Use Each:
- Auto-detection: Daily development, switching between subprojects frequently
- Manual mode: Working on one subproject for extended period, avoiding auto-switch
Monorepo Configuration Format
projects:
my-monorepo:
repository:
local_path: /Users/dev/monorepo
git_remote: github.com/org/monorepo
context:
detection:
subdirectories:
- subproject: frontend
match_pattern: "*/apps/frontend/*"
priority: 10
- subproject: backend
match_pattern: "*/apps/backend/*"
priority: 10
- subproject: mobile
match_pattern: "*/apps/mobile/*"
priority: 10
code_repository:
subprojects:
- name: frontend
path: apps/frontend
description: Next.js web application
tech_stack:
languages: [typescript]
frameworks:
frontend: [react, nextjs, tailwindcss]
- name: backend
path: apps/backend
description: NestJS API server
tech_stack:
languages: [typescript]
frameworks:
backend: [nestjs, prisma]
- name: mobile
path: apps/mobile
description: React Native mobile app
tech_stack:
languages: [typescript]
frameworks:
mobile: [react-native, expo]
Monorepo Examples
Example 1: Simple Frontend/Backend Monorepo
my-monorepo:
repository:
local_path: /Users/dev/monorepo
context:
detection:
subdirectories:
- subproject: web
match_pattern: "*/apps/web/*"
priority: 10
- subproject: api
match_pattern: "*/apps/api/*"
priority: 10
- subproject: shared
match_pattern: "*/packages/shared/*"
priority: 5
code_repository:
subprojects:
- name: web
path: apps/web
tech_stack:
languages: [typescript]
frameworks:
frontend: [react, nextjs]
- name: api
path: apps/api
tech_stack:
languages: [typescript]
frameworks:
backend: [express, prisma]
Example 2: Complex Package-Based Monorepo
my-packages:
repository:
local_path: /Users/dev/packages
context:
detection:
subdirectories:
- subproject: ui
match_pattern: "**/packages/ui/**"
priority: 10
- subproject: api-client
match_pattern: "**/packages/api-client/**"
priority: 10
- subproject: utils
match_pattern: "**/packages/utils/**"
priority: 8
- subproject: core
match_pattern: "**/packages/**"
priority: 3
code_repository:
subprojects:
- name: ui
path: packages/ui
tech_stack:
languages: [typescript]
frameworks:
frontend: [react, tailwindcss]
- name: api-client
path: packages/api-client
tech_stack:
languages: [typescript]
Example 3: Multi-Team Enterprise Monorepo
enterprise:
repository:
local_path: /Users/dev/enterprise
context:
detection:
subdirectories:
- subproject: commerce-web
match_pattern: "*/teams/commerce/web/*"
priority: 15
- subproject: commerce-api
match_pattern: "*/teams/commerce/api/*"
priority: 15
- subproject: marketing-landing
match_pattern: "*/teams/marketing/landing/*"
priority: 15
- subproject: marketing-cms
match_pattern: "*/teams/marketing/cms/*"
priority: 15
- subproject: commerce
match_pattern: "*/teams/commerce/*"
priority: 8
- subproject: marketing
match_pattern: "*/teams/marketing/*"
priority: 8
code_repository:
subprojects:
- name: commerce-web
path: teams/commerce/web
tech_stack:
languages: [typescript]
frameworks:
frontend: [react, nextjs]
- name: commerce-api
path: teams/commerce/api
tech_stack:
languages: [typescript]
frameworks:
backend: [nestjs, graphql]
Monorepo Best Practices
1. Pattern Design
DO:
- Use specific patterns with high priority for primary subprojects
- Add fallback patterns with lower priority for misc directories
- Test patterns match expected directories
- Document pattern logic in config comments
DON'T:
- Use overly broad patterns (e.g.,
*/*)
- Set all patterns to same priority (ambiguous)
- Forget to update patterns when restructuring
2. Priority Assignment
Recommended Priority Scheme:
- 20-25: Very specific (exact team/product match)
- 10-15: Standard subprojects (apps, packages)
- 5-9: Fallback patterns (general matches)
- 1-4: Catch-all (rarely used)
Example:
- match_pattern: "*/apps/admin/dashboard/*"
priority: 20
- match_pattern: "*/apps/admin/*"
priority: 15
- match_pattern: "*/apps/*"
priority: 5
3. Organization Conventions
Naming:
- Use kebab-case for subproject names:
commerce-web, marketing-api
- Match subproject name to directory when possible
- Use team prefixes for multi-team repos:
team-commerce, team-marketing
Structure:
- Group related subprojects in config
- Order by priority (highest first) for readability
- Add comments explaining complex patterns
4. Performance Optimization
Cache Friendly:
- Enable auto-detection mode (detection cached per session)
- Avoid excessive pattern matching (max ~10 patterns per project)
- Use manual mode for long-running sessions on one subproject
Detection Speed:
subdirectories:
- subproject: frontend
match_pattern: "*/apps/web/*"
priority: 10
- subproject: backend
match_pattern: "*/apps/api/*"
priority: 10
- subproject: shared
match_pattern: "*/packages/*"
priority: 5
subdirectories:
- subproject: web
match_pattern: "*/apps/web/*"
priority: 10
- subproject: web
match_pattern: "*/web/*"
priority: 9
- subproject: web
match_pattern: "**/web/**"
priority: 8
5. Tech Stack Configuration
Per-Subproject Stacks:
subprojects:
- name: web
tech_stack:
languages: [typescript]
frameworks:
frontend: [react, nextjs]
tools: [tailwindcss, vitest]
- name: api
tech_stack:
languages: [typescript]
frameworks:
backend: [nestjs, prisma]
tools: [jest, swagger]
Benefits:
- Agent selection uses subproject stack
- Commands show relevant tech context
- Better tool recommendations
6. Testing Configuration
Verify Detection:
cd /path/to/monorepo/apps/frontend
/ccpm:project:list
cd /path/to/monorepo/apps/backend
/ccpm:project:list
Test Pattern Conflicts:
cd /path/to/ambiguous/directory
/ccpm:project:list
7. Migration from Single Project
Steps:
- Start with existing single project config
- Add subdirectory detection rules
- Define subproject metadata
- Test auto-detection in each directory
- Enable auto-detection mode
- Update team documentation
Before (single project):
my-app:
repository:
local_path: /Users/dev/my-app
After (monorepo):
my-app:
repository:
local_path: /Users/dev/my-app
context:
detection:
subdirectories:
- subproject: web
match_pattern: "*/apps/web/*"
priority: 10
- subproject: api
match_pattern: "*/apps/api/*"
priority: 10
code_repository:
subprojects:
- name: web
path: apps/web
- name: api
path: apps/api
Error Handling
No Project Detected
Error:
โ Could not detect active project
Suggestions:
- Set active project: /ccpm:project:set <project-id>
- Enable auto-detection: /ccpm:project:set auto
- Check you're in a configured project directory
Solution with agents:
const detection = Task(project-detector): "Detect active project"
if (detection.error) {
console.log(detection.error.message)
console.log("\nSuggestions:")
detection.error.suggestions.forEach(s => console.log(`- ${s}`))
}
Configuration Error
Error:
โ Project configuration invalid
Project 'my-app' missing required field: linear.team
Fix with: /ccpm:project:update my-app --field linear.team
Solution with agents:
const config = Task(project-config-loader): `
Load project: ${projectId}
Validate: true
`
if (!config.validation.valid) {
config.validation.errors.forEach(err => {
console.error(`โ ${err.message}`)
err.actions?.forEach(action => console.log(` Fix: ${action}`))
})
}
Best Practices
- Always Detect First: Start commands with project detection
- Use Agents for Logic: Don't reimplement detection/loading
- Cache Context: Detect once, use throughout command
- Display Context: Show users which project is active
- Handle Errors Gracefully: Provide actionable error messages
- Support Auto-Detection: Let users work naturally
Command Integration Examples
Example 1: Planning Command with Project Context
# In /ccpm:plan
Task(project-context-manager): `
Get active project context
Include: detection + config
Format: compact
`
# Display: ๐ Project: My Monorepo โบ frontend
# Use context for Linear:
linear_create_issue({
team: context.config.linear.team,
project: context.config.linear.project,
labels: context.display.labels
})
Example 2: Implementation Command with Subproject Info
# In /ccpm:work
const context = Task(project-context-manager): "Get context"
console.log(`
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
๐ Starting Implementation
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Project: ${context.config.project_name}
Subproject: ${context.config.subproject?.name || 'N/A'}
Tech Stack: ${context.display.subtitle}
Location: ${context.display.location}
`)
# Agent selection uses tech stack:
const agents = selectAgents(context.config.subproject?.tech_stack || context.config.tech_stack)
Performance Optimizations
- Agent Caching: Agents handle caching internally
- Lazy Loading: Only load config when needed
- Parallel Ops: Detect and load in parallel when possible
- Session State: Cache detection result for command duration
Testing
Test with these scenarios:
- Simple Project: Single repo, no subdirectories
- Monorepo: Multiple subdirectories with patterns
- Manual Override: User sets specific project
- Auto-Detection: Switch directories, auto-detect
- No Config: Fresh install, guide user to setup
- Invalid Config: Missing fields, show validation errors
Related Commands
Project Management:
/ccpm:project:add - Add new project/ccpm:project:list - List all projects/ccpm:project:show - Show project details/ccpm:project:set - Set active project/ccpm:project:update - Update project config/ccpm:project:delete - Delete project
Monorepo Subdirectories:
/ccpm:project:subdir:add - Add subdirectory to project/ccpm:project:subdir:list - List project subdirectories/ccpm:project:subdir:update - Update subdirectory config/ccpm:project:subdir:remove - Remove subdirectory
Maintenance
When to update this skill:
- New project config fields added
- New detection methods implemented
- Agent interfaces change
- New project templates added
Update locations:
- This skill (guidance and examples)
- Project agents (implementation)
- Command files (integration)
- Documentation (user-facing guides)
