CRITICAL: Main Session Guardrails

CLAUDE.md

This file provides guidance to Claude Code when working with the Claude Copilot framework.

CRITICAL: Main Session Guardrails

These rules exist to prevent context bloat. Violating them wastes tokens and defeats the framework's purpose.

What You MUST NEVER Do

What You Should AVOID

Self-Check Before Every Response

Ask yourself:

1. Am I about to read many files (>8)? → CONSIDER delegating to agent.
2. Am I about to write code? → STOP. Delegate to @agent-me.
3. Am I about to create a plan? → STOP. Delegate to @agent-ta.
4. Am I using a generic agent? → STOP. Switch to framework agent.
5. Is my response going to be long? → CONSIDER storing details in Task Copilot.

Framework Agents vs Generic Agents

ONLY use framework agents - they integrate with Task Copilot:

NEVER use generic agents - they bypass Task Copilot:

Expected Token Usage Per Task

If you're hitting compact frequently, consider delegating more to framework agents.

Overview

Claude Copilot is a complete AI-enabled development framework solving five challenges:

Quick Decision Guide

Note: For comprehensive details see CLAUDE_REFERENCE.md or docs/10-architecture/03-decision-guide.md.

Command Selection Matrix

Use Case Mapping

The Five Pillars

1. Memory Copilot

Persistent memory across sessions with semantic search.

Essential Tools: initiative_get, initiative_start, initiative_update, initiative_complete, memory_store, memory_search

Location: mcp-servers/copilot-memory/

2. Agents

14 specialized agents using lean agent model (~60-120 lines each).

Agents: me, ta, qa, sec, doc, do, sd, uxd, uids, uid, cw, cco, kc

Location: .claude/agents/

3. Skills

Load via native @include (recommended) or Skills Copilot MCP server (optional).

Native: @include .claude/skills/NAME/SKILL.md

MCP Tools: skill_get, skill_search, skill_list, skill_evaluate, knowledge_search, knowledge_get

Location: mcp-servers/skills-copilot/

4. Task Copilot

Ephemeral PRD, task, and work product storage. Reduces context bloat by ~94%.

Note: Task Copilot operations use the tc CLI tool (installed at tools/tc/). Agents call tc commands via Bash instead of MCP tool calls. Memory Copilot and Skills Copilot still use their MCP servers.

Core Commands: tc prd create, tc prd get, tc task create, tc task update, tc task get, tc wp store, tc wp get, tc progress, initiative_link (Memory Copilot MCP)

Stream Commands: tc stream list, tc stream get

Other Commands: tc handoff, tc log --task <id>

Location: tools/tc/

5. Protocol

Battle-tested workflow commands.

Commands: /setup, /setup-project, /update-project, /update-copilot, /knowledge-copilot, /protocol [task], /continue [stream], /pause [reason], /map, /memory, /orchestrate

Location: .claude/commands/

Agent Routing

Agents route to each other based on expertise:

Specification Workflow

Domain agents (sd, uxd, uids, cw, cco) MUST NOT create tasks directly. Instead, they create specifications that @agent-ta reviews and decomposes into tasks.

Why Specifications?

Workflow

1. Domain agent completes work (journey map, wireframes, design tokens, copy, creative direction)
2. Store as specification work product (type: 'specification')
3. Route to @agent-ta
4. TA discovers specifications for PRD
5. TA reviews all domain specifications
6. TA creates tasks with specification traceability

Specification Structure

All specifications include:

Task Creation with Traceability

When TA creates tasks from specifications, metadata includes:

metadata: {
  sourceSpecifications: ['WP-xxx', 'WP-yyy', 'WP-zzz'],
  // Links back to all domain specifications
}

Task descriptions consolidate requirements from all specifications, ensuring implementation aligns with all domain input.

Example Flow

1. User creates PRD-001: "Build user dashboard"
2. @agent-sd creates WP-001: Service Design Specification (journey stages)
3. @agent-uxd creates WP-002: UX Design Specification (interactions, states)
4. @agent-uids creates WP-003: UI Design Specification (design tokens, components)
5. @agent-cw creates WP-004: Copy Specification (headlines, errors, empty states)
6. @agent-ta discovers WP-001 through WP-004
7. @agent-ta creates tasks with consolidated requirements and sourceSpecifications metadata

Installation

Quick Setup:

1. Machine setup (once): cd ~/.claude/copilot && claude then run /setup
2. Project setup (per project): Run /setup-project
3. Update projects: Run /update-project in each project
4. Knowledge (optional): Run /knowledge-copilot

See SETUP.md for details.

Extension System

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

Resolution order: Project ($KNOWLEDGE_REPO_PATH) → Global (~/.claude/knowledge) → Base framework

Extension types: override (replace agent), extension (add to sections), skills (inject skills)

See extension-spec.md and CLAUDE_REFERENCE.md for full details.

File Locations

Session Management

Starting Fresh Work

Use /protocol to activate the Agent-First Protocol.

Resuming Previous Work

Use /continue to load context from Memory Copilot.

End of Session

Call initiative_update with:

Development Guidelines

No Time Estimates Policy

ALL outputs from agents and direct responses MUST NEVER include:

• Time-based estimates (hours, days, weeks, months, quarters, sprints)
• Completion dates or deadlines
• Duration predictions or timelines
• Phase durations (e.g., "Phase 1 (Weeks 1-2)")

Acceptable alternatives:

Sequencing without time:

• Use dependency chains: "After X completes" not "Week 2"
• Use phases: "Phase 1 → Phase 2" not "Weeks 1-3"
• Use priority: "P0 (critical), P1 (high), P2 (medium)" not "This week"
• Use complexity: "Low / Medium / High / Very High" not "X days"

Why: Time estimates are consistently inaccurate, create false expectations, and shift focus from quality to arbitrary deadlines. With parallel agents, traditional time-based planning is meaningless.

When Modifying Agents

• Keep base agents generic (no company-specific content)
• Use industry-standard methodologies
• Include routing to other agents
• Document decision authority

Required Agent Sections

Every agent must include:

1. Frontmatter - name, description, tools, model (YAML block between --- markers)
2. Opening description - Role and mission (paragraph after frontmatter)
3. Core Behaviors - Always do / Never do lists
4. Output format - Example output or deliverable templates
5. Route To Other Agent - When to hand off to specialists
6. Task Copilot Integration - How to store work products

Agent Shared Behaviors

All agents inherit these behaviors. Individual agent files should NOT repeat them.

Skill Loading: Call skill_evaluate({ files, text, threshold: 0.5 }) at start. Load top matching skills via @include skills[0].path.

Task Copilot Pattern (all agents):

1. tc task get <taskId> --json (via Bash)
2. Verify task exists and is assigned
3. skill_evaluate({ files, text }) (if available - Skills MCP unchanged)
4. Do domain work
5. tc wp store --task <taskId> --type <type> --title "..." --content "..." --json (via Bash)
6. tc task update <taskId> --status completed --json (via Bash)

Iteration Loop (agents with iteration enabled):

1. Agent self-manages iteration count (max from frontmatter config)
2. FOR EACH iteration: make changes → validate against frontmatter rules
   - All rules pass → store work product via tc wp store, mark complete via tc task update
   - Blocked → store findings via tc wp store, emit <promise>BLOCKED</promise>
   - Else → iterate with refined approach

Return Format: Return ONLY ~100 tokens to main session. Store all details via tc wp store. Never return full designs, plans, code, or analysis.

Context Compaction: If response exceeds 14K tokens (55K chars), store full content as work product and return compact summary only.

Knowledge (Pull-Based): When working on user-facing features, check knowledge_search() for voice/brand/product context. If not configured and relevant, note recommendation in work product (not main response). Never block work for missing knowledge.

Specification Workflow (domain agents: sd, uxd, uids, cw, cco): Store completed work as type: 'specification', then route to @agent-ta. Domain agents MUST NOT create tasks directly.

Multi-Agent Handoff: If not final agent in chain: store work product, call tc handoff --from <agent> --to <agent> --task <id> --context "..." --json (200-char context), route to next agent, do NOT return to main session. If final agent: call tc log --task <id> --json, return consolidated summary.

Protocol Integration: When invoked via /protocol with checkpoints, output stage-complete summary with: Task/WP IDs, key deliverables, key decisions (2-3), handoff context (200-char max).

Operations Documentation

Standards and guides in docs/30-operations/:

Extended Reference

For detailed information on the following topics, see CLAUDE_REFERENCE.md:

• Full Quick Decision Guide: Protocol flow system, agent selection matrix, extension types, memory vs skills vs extensions comparison
• The Five Pillars (Detailed): Complete tool descriptions, configuration tables, work product types, key features
• OMC Features: Ecomode, magic keywords, progress HUD, skill extraction, zero-config install
• Extension System (Full): Two-tier resolution, setup instructions, extension tools
• Session Boundary Protocol: Preflight checks, decision matrix, agent-specific guidance, example usage
• Lifecycle Hooks: Hook types, security rules, API examples
• Skill Evaluation: Evaluation methods, confidence levels, usage examples
• Correction Detection: Detection patterns, tools, /reflect command

To include the extended reference:

@include CLAUDE_REFERENCE.md