Quick Decision Guide (Full Details)

CLAUDE_REFERENCE.md

Extended reference documentation for Claude Copilot framework components.

Quick Decision Guide (Full Details)

Feature Comparison

Protocol Flow System

The /protocol command uses intent detection to route work through the appropriate agent chain. There are four flows:

Flow A: Experience-First (DEFAULT)

• Triggers: Building features, adding functionality, creating UI, or no strong keywords
• Chain: sd → uxd → uids → ta → me
• Checkpoints: After sd, uxd, uids (user approves each stage)
• Philosophy: Design before code, think about user journey first

Flow B: Defect

• Triggers: Keywords like bug, broken, fix, error, not working, crash
• Chain: qa → me → qa
• Checkpoints: After qa diagnosis, after me fix
• Philosophy: Diagnose thoroughly, fix with tests, verify resolution

Flow C: Technical-Only

• Triggers: Keywords like refactor, optimize, architecture, performance, or --technical flag
• Chain: ta → me
• Checkpoints: After ta planning
• Philosophy: Plan architecture first, then implement cleanly

Flow D: Clarification

• Triggers: Ambiguous keywords like improve, enhance, update, change
• Behavior: Ask user to clarify intent (experience/technical/defect) before routing
• Philosophy: Never assume - get explicit direction when unclear

Escape Hatches:

• Use --technical, --defect, or --experience flags to force a specific flow
• Use --skip-sd, --skip-uxd, --skip-uids to bypass design stages
• Use --no-checkpoints to run full chain without pausing
• Use --verbose or --minimal to control checkpoint verbosity

Agent Selection Matrix

Extension Type Guide

Memory vs Skills vs Extensions

The Five Pillars (Detailed)

1. Memory Copilot (Full Details)

MCP server providing persistent memory across sessions.

Location: mcp-servers/copilot-memory/

Two-Tier Resume System:

• Lean mode (default): Returns ~150 tokens - status, currentFocus, nextAction only
• Full mode: Returns ~370 tokens - includes decisions, lessons, keyFiles

Configuration:

Important: By default, each project gets a unique database based on its path hash. Set WORKSPACE_ID explicitly to preserve memories when renaming/moving projects. See mcp-servers/copilot-memory/README.md for details.

2. Agents (Full Details)

14 specialized agents for complex development tasks using the lean agent model.

Location: .claude/agents/

Lean Agent Model:

Agents are 60-120 lines each. Shared boilerplate (skill loading, Task Copilot pattern, iteration loop, return format, context compaction, knowledge pull-based, specification workflow, multi-agent handoff, protocol integration) is extracted to the "Agent Shared Behaviors" section in CLAUDE.md. Individual agent files contain only domain-specific logic, core behaviors, output format, and routing tables.

Required Agent Tools/Commands:

3. Skills (Full Details)

Skills can be loaded via native @include directive or Skills Copilot MCP server.

Native @include (Recommended for Local Skills)

Load local skills directly without MCP overhead:

## Context
When working with Laravel:
@include ~/.claude/skills/laravel/SKILL.md

When writing tests:
@include .claude/skills/testing/SKILL.md

Benefits:

• Zero MCP overhead (~500 tokens saved per skill)
• Instant loading, no network/database
• Simpler setup (no MCP configuration)
• Full control over skill content

Use for:

• Project-specific skills (.claude/skills/)
• User-level skills (~/.claude/skills/)
• Simple, direct loading

Auto-Detection with skill_evaluate

Agents use skill_evaluate to automatically detect relevant skills based on file patterns and keywords:

const skills = await skill_evaluate({
  files: ['src/Button.test.tsx'],     // Match against trigger_files
  text: 'Help with React testing',    // Match against trigger_keywords
  threshold: 0.5                      // Minimum confidence (0-1)
});
// Returns ranked list: { skillName, confidence, path }

See Skill Evaluation Quick Reference for details.

Skills Copilot MCP (OPTIONAL)

MCP server for advanced skill management and marketplace access.

Location: mcp-servers/skills-copilot/

Skill Tools:

Knowledge Tools:

Use when you need:

• SkillsMP marketplace access (25K+ public skills)
• Private skill storage in Postgres database
• Cross-source skill search (DB + marketplace + local)
• Usage analytics and caching
• Knowledge repository extensions

Knowledge is searched in two-tier resolution: project-level first (KNOWLEDGE_REPO_PATH), then machine-level (~/.claude/knowledge).

4. Task Copilot (Full Details)

CLI tool for ephemeral PRD, task, and work product storage. Task Copilot operations use the tc CLI tool (installed at tools/tc/). Agents call tc commands via Bash instead of MCP tool calls.

Location: tools/tc/

Purpose: Agents store detailed work products here instead of returning them to the main session, reducing context bloat by ~94% on average (up to 96% for single-agent tasks, 85%+ for session resume, 92%+ for multi-agent collaboration).

Core Commands:

Stream Management:

Note: Stream conflict checking, unarchiving, and bulk archival have been removed. Use git diff for conflict detection between streams.

Agent Collaboration (Hierarchical Handoffs):

Configuration:

Work Product Types:

Key Features:

• Hierarchical Handoffs: Multi-agent chains pass context between agents via tc handoff; only final agent returns to main (~100 tokens vs ~900)
• Token Efficiency: Agents store detailed output via tc wp store instead of returning to session context
• Independent Streams: Parallel work streams with dependency management (foundation → parallel → integration); use git diff for conflict detection
• Progress Visibility: Compact progress overview via tc progress --json
• Specification Workflow: Domain agents (sd, uxd, uids, cw, cco) create specifications → @agent-ta reviews and creates tasks with traceability

5. Protocol (Full Details)

Commands enforcing battle-tested workflows.

Location: .claude/commands/

Quick Start Examples:

/protocol fix login authentication bug        → Auto-routes to @agent-qa
/protocol add dark mode to dashboard          → Auto-routes to @agent-sd
/continue Stream-B                            → Resume parallel stream work
/pause switching to urgent bug                → Create checkpoint with reason
/map                                          → Generate project structure map
/orchestrate generate                         → Create PRD + stream tasks via @agent-ta
/orchestrate start                            → Set up worktrees, print launch instructions
/orchestrate status                           → Check progress of all streams
/orchestrate merge                            → Merge completed worktrees back to main

OMC Features

Five productivity enhancements inspired by Oh My Claude Code:

1. Ecomode - Smart Model Routing

Automatically routes tasks to appropriate Claude model (haiku/sonnet/opus) based on complexity scoring.

Usage in task titles (BREAKING CHANGE v2.8.0):

eco: Fix the login bug                    → Auto-selects model, low effort
fast: Refactor authentication module      → Auto-selects model, medium effort ⚠️ BREAKING
max: Design microservices architecture    → Auto-selects model, max effort ✨ NEW
opus: Update README typo                  → Forces Opus (effort from complexity)
sonnet: Implement feature                 → Forces Sonnet (effort from complexity)
haiku: Fix typo                           → Forces Haiku (effort from complexity)

How it works:

• Analyzes task title, description, file count, and agent type
• Calculates complexity score (0.0 to 1.0)
• Routes model: < 0.3 = haiku, 0.3-0.7 = sonnet, > 0.7 = opus
• Determines effort: < 0.3 = low, 0.3-0.7 = high, > 0.7 = max
• Keywords can override model (opus:, sonnet:, haiku:) or effort (eco:, fast:, max:)

Benefits:

• Cost optimization for simple tasks
• Performance boost with haiku for quick fixes
• Automatic scaling to opus for complex work

2. Magic Keywords - Quick Action Routing

Action keywords at message start suggest agent routing and task type.

Supported keywords:

fix: Authentication not working           → Routes to @agent-qa
add: Dark mode to dashboard              → Routes to @agent-me
refactor: Database connection pool       → Routes to @agent-ta
optimize: API response time              → Routes to @agent-ta
test: Login flow edge cases              → Routes to @agent-qa
doc: API endpoints                       → Routes to @agent-doc
deploy: Production environment           → Routes to @agent-do

Combine with modifiers:

eco: fix: login bug                      → QA agent + auto-model + low effort
fast: doc: quick API reference           → Doc agent + auto-model + medium effort
max: add: complex feature                → Engineer + auto-model + max effort
opus: refactor: auth module              → Engineer + opus + complexity-based effort

Rules:

• Keywords must be at message start
• Case-insensitive matching
• Max 1 modifier + 1 action keyword
• False positive prevention (e.g., "economics:" ignored)

3. Progress HUD - Live Status Display

Real-time statusline showing task progress, model in use, and token estimates.

Format:

[Stream-A] ▶ 50% | sonnet | ~1.2k tokens
[Stream-B] ✓ 100% | haiku | ~500 tokens

Components:

• Stream/task identifier
• Progress indicator with unicode symbols (⏸ ▶ ⚠ ✓)
• Model indicator with color coding
• Token usage estimate
• Optional: Active file tracking

Usage:

const hud = createStatusline('TASK-123', 'Fix auth bug', 'Stream-A');
hud.updateState({ status: 'in_progress', progressPercent: 50 });
hud.updateModel('sonnet');
const rendered = hud.render(); // → "[Stream-A] ▶ 50% | sonnet | ~1.2k"

4. Skill Extraction - Auto-Detect Patterns

Automatically detects repeated patterns in work and suggests skill extractions.

Detection:

• File patterns (e.g., "always use X pattern in src/auth/**/*.ts")
• Keyword patterns (e.g., "error handling", "validation", "testing")
• Workflow patterns (e.g., "run tests before commit")
• Best practices (e.g., "use async/await, not callbacks")

Workflow:

1. Pattern detection runs after task completion
2. Suggests skill creation with confidence score
3. Review and approve via /skills-approve command
4. Auto-generates skill file with:
   • Pattern description
   • Usage examples
   • Trigger conditions (files/keywords)
   • Quality checklist

Benefits:

• Builds team knowledge automatically
• Reduces repetitive explanations
• Improves consistency across sessions

5. Zero-Config Install - One Command Setup

Simple installer with automatic dependency checking and fixing.

Primary method:

# Install globally with auto-fix
npx claude-copilot install --global --auto-fix

# Install to project
npx claude-copilot install --project .

Features:

• Auto-detects missing dependencies (Node.js, Git, build tools)
• Platform-specific fixes (Homebrew on macOS, apt/dnf/pacman on Linux)
• Validates installation after completion
• Clear error messages with recovery instructions

Commands:

npx claude-copilot check         # Check dependencies
npx claude-copilot validate      # Validate installation
npx claude-copilot install       # Install with options

What it replaces:

• Manual dependency installation
• Manual MCP server builds
• Manual directory creation
• Manual configuration setup

See packages/installer/README.md for full documentation.

Extension System (Full Details)

This framework supports extensions via knowledge repositories. Extensions allow company-specific methodologies to override or enhance base agents.

Two-Tier Resolution

Extensions are resolved in priority order:

Key benefit: Set up your company knowledge once in ~/.claude/knowledge and it's automatically available in every project.

Extension Types

Setting Up Global Knowledge Repository

Create a knowledge repository at ~/.claude/knowledge/:

~/.claude/knowledge/
├── knowledge-manifest.json    # Required
└── .claude/
    └── extensions/
        ├── sd.override.md     # Your agent extensions
        └── uxd.extension.md

Minimal manifest:

{
  "version": "1.0",
  "name": "my-company",
  "description": "Company-specific agent extensions"
}

No .mcp.json changes needed - global repository is auto-detected.

Project-Specific Overrides (Optional)

Only needed when a project requires different extensions than global:

{
  "mcpServers": {
    "skills-copilot": {
      "env": {
        "KNOWLEDGE_REPO_PATH": "/path/to/project-specific/knowledge"
      }
    }
  }
}

Extension Tools

Documentation

See extension-spec.md for full documentation on:

• Creating knowledge repositories
• Extension file formats
• Fallback behaviors
• Required skills validation

Session Boundary Protocol

The Session Boundary Protocol ensures agents start work in a healthy environment by running preflight checks before substantive work.

Overview

Agents should verify the task exists via tc task get <id> --json and check git/environment state before beginning implementation, planning, or testing to surface environment issues early and prevent wasted work.

When to Use

Preflight Check

Verify the task exists and review its current state:

tc task get TASK-123 --json

Additionally, check git and environment health:

git status --short
git diff --stat

Decision Matrix

Agent-Specific Guidance

@agent-me:

• Must verify environment before implementation
• Git dirty with unrelated changes: warn but can continue if acknowledged
• Environment issues: STOP and fix (missing deps, config errors)
• Blocked dependencies: wait for prerequisites

@agent-ta:

• Check before creating PRDs/tasks
• Git dirty: note current work, ensure new plan doesn't conflict
• Many blocked tasks: identify patterns, address in plan
• Use git diff to check for file conflicts across parallel work streams

@agent-qa:

• Check before running tests
• Environment issues: fix before test execution to prevent false failures
• Git dirty with failing tests: determine if failures from current changes
• Missing test dependencies: install before proceeding

Benefits

• Early issue detection: Surface problems before wasted work
• Context awareness: Understand current state before planning
• Better decisions: Know git state, blockers, environment status
• Prevent false failures: Ensure healthy environment for tests
• Stream coordination: Use git diff to avoid file conflicts in parallel work

Example Usage

# @agent-me starting implementation

# 1. Verify the task exists
tc task get TASK-123 --json

# 2. Check git state
git status --short

# 3. If working directory is dirty with unrelated changes:
#    Warn user and suggest: git stash or git commit

# 4. If environment issues (missing deps, etc.):
#    STOP and fix before proceeding

# 5. Proceed with implementation

Lifecycle Hooks Quick Reference

Note: Lifecycle hooks (hook_register, hook_clear, hook_evaluate, hook_list) have been removed from Task Copilot. The security rules below are maintained by the development environment directly.

Security Rules (Built-in)

Full documentation: docs/50-features/lifecycle-hooks.md

Skill Evaluation Quick Reference

Automatically detect relevant skills from file patterns and text keywords.

Evaluation Methods

skill_evaluate Tool

// Evaluate context for relevant skills
const result = await skill_evaluate({
  files: ['src/Button.test.tsx'],     // File patterns to match
  text: 'Help with React testing',    // Keywords to detect
  recentActivity: ['testing'],        // Boost matching skills
  threshold: 0.3,                     // Min confidence (0-1)
  limit: 5                            // Max results
});

// Returns ranked skills:
// { skillName: 'react-testing', confidence: 0.78, level: 'high', reason: '...' }

Confidence Levels

Full documentation: docs/50-features/skill-evaluation.md

Correction Detection Quick Reference

Auto-capture user corrections for continuous agent/skill improvement.

Detection Patterns

Correction Tools

/reflect Command

Review and manage pending corrections:

/reflect                    # Review all pending
/reflect --agent me         # Filter by agent
/reflect --status approved  # Filter by status

Example Detection

import { detectCorrections } from 'copilot-memory/tools/correction-tools';

const result = detectCorrections({
  userMessage: 'Actually, use async/await instead of callbacks',
  previousAgentOutput: '...',
  agentId: 'me',
  threshold: 0.5
}, 'project-id');

// result.detected: true
// result.maxConfidence: 0.85
// result.suggestedAction: 'auto_capture'

Full documentation: docs/50-features/correction-detection.md