Communication Protocols

Communication Protocols

How to Use This Skill

1. Review the patterns and examples below
2. Apply the relevant patterns to your implementation
3. Follow the best practices outlined in this skill

Expert skill for multi-agent communication, control commands, and delegation patterns.

When to Use

✅ Use this skill when:

• Token usage exceeds 85% (136K/160K) - Need CHECKPOINT
• Multi-agent workflow requires parallel delegation (2+ agents)
• Creating session handoff for continuation (end of day, context switch)
• Workflow needs PAUSE for user clarification (ambiguous requirements)
• Max iterations reached (10+ loops) - Need ESCALATE
• Orchestrator coordinating 3+ subagents in sequence
• Validating control command syntax before execution
• Need time savings: 70% faster context rebuild (60→18 min with structured handoffs)

❌ Don't use this skill when:

• Simple single-agent task (no coordination needed)
• Token usage < 50% (no checkpoint needed)
• Trivial user questions (no PAUSE needed)
• Working independently without delegation

Control Commands

CONTROL Command Syntax

All control commands follow this format:

CONTROL: <COMMAND> [REASON: <explanation>]

Available Commands

PAUSE - Suspend workflow for user input

CONTROL: PAUSE
REASON: Need clarification on authentication approach before proceeding

CHECKPOINT - Save workflow state before context collapse

CONTROL: CHECKPOINT
REASON: Token usage at 85% (136K/160K), creating recovery point

ESCALATE - Request human intervention

CONTROL: ESCALATE
REASON: Iteration limit exceeded (10 attempts), manual review needed

RESUME - Continue from checkpoint

CONTROL: RESUME [checkpoint_id]
REASON: Context restored, continuing from state: SOLVE

DELEGATE - Transfer task to subagent

CONTROL: DELEGATE [subagent_name]
REASON: Task requires specialized expertise (security audit)

When to Use Each Command

Command	Trigger Condition	Example Scenario
PAUSE	Ambiguous requirements	User said "fix auth" but didn't specify JWT vs OAuth
CHECKPOINT	Token usage > 85%	Long workflow approaching 136K tokens
ESCALATE	Max iterations reached	FSM looped 10 times without convergence
RESUME	Starting from saved state	New session loading checkpoint from previous day
DELEGATE	Specialized expertise needed	Security audit requires security-auditor agent

Delegation Templates

Standard Delegation Pattern

delegation:
  from_agent: orchestrator
  to_agent: codebase-analyzer
  task:
    description: "Analyze authentication flow in auth.rs"
    scope:
      - backend/src/handlers/auth.rs
      - backend/src/middleware/auth.rs
    deliverable: "Security vulnerability report with file:line references"
  context:
    current_phase: "Security Audit"
    token_budget: 12000
    priority: HIGH

Multi-Agent Parallel Delegation

parallel_delegation:
  coordinator: orchestrator
  agents:
    - agent: codebase-locator
      task: "Find all JWT-related files"
      timeout: 5min
    - agent: codebase-analyzer
      task: "Analyze JWT implementation security"
      timeout: 10min
    - agent: thoughts-locator
      task: "Find auth design decisions"
      timeout: 3min
  aggregation_strategy: "Wait for all, merge results by priority"

Sequential Delegation Chain

sequential_delegation:
  workflow: "Bug Fix Pipeline"
  steps:
    - step: 1
      agent: codebase-locator
      task: "Locate files related to bug #1234"
      output_to: step_2_input
    - step: 2
      agent: codebase-analyzer
      task: "Analyze root cause in {step_2_input}"
      output_to: step_3_input
    - step: 3
      agent: orchestrator
      task: "Implement fix based on {step_3_input}"

Handoff Document Structure

Quick Handoff (100-200 words)

## Quick Handoff

**Session:** 2025-10-18-auth-refactor
**Status:** Phase 2/4 Complete (SOLVE → CODE)
**Next:** Start at backend/src/handlers/auth.rs:167

Just completed authentication design. Removed fallback JWT_SECRET logic.
Server now requires JWT_SECRET env var (panics if missing - by design).
Next: Implement token refresh rotation (15 min warmup task).

**Current State:**
- ✅ Design complete (auth.rs:1-50)
- ✅ Session invalidation added (repositories.rs:610)
- 🔜 Token refresh rotation (auth.rs:200-250)

**Gotchas:**
- list_by_tenant() takes &Uuid, not Uuid
- Server panics if JWT_SECRET missing (intentional)

Full Checkpoint Document

# Sprint X - Checkpoint

**Status:** Phase Y/Z Complete
**Context Usage:** X% (tokens)
**Next Session:** Start with file.ts:123
**Created:** 2025-10-18T14:30:00Z
**Checkpoint ID:** ckpt_auth_refactor_phase2

## Quick Handoff (100-200 words)
[See above template]

## ✅ COMPLETED (High-Level with file:line references)
- **CRITICAL-1** - auth.rs:167,302,337 - Removed fallback JWT_SECRET
- **CRITICAL-2** - repositories.rs:610 - Added invalidate_session()
- **MEDIUM-1** - middleware/auth.rs:45 - Enhanced Claims validation

## 🔜 REMAINING (With Ready-to-Copy Code)

**HIGH-1: Implement Token Refresh Rotation (30 min)**
File: backend/src/handlers/auth.rs:200-250

```rust
// Add this function after login_handler()
pub async fn refresh_token(
    claims: Claims,
    fdb: web::Data<FDBService>,
) -> Result<HttpResponse, ApiError> {
    // 1. Validate refresh token
    // 2. Invalidate old session
    // 3. Create new session with rotated token
    // 4. Return new JWT pair
    todo!("Implement token refresh with rotation")
}

MEDIUM-1: Fix Hardcoded IP (15 min) File: src/services/user-service.ts:36 Change: baseUrl = 'http://IP' → baseUrl = import.meta.env.VITE_API_URL || 'http://localhost:8080'

🧠 Mental Model

Auth flow: Login → Create FDB session → Generate JWT → Middleware validates BOTH:

1. JWT signature (crypto verification)
2. session.is_active = true (FDB lookup)

Logout invalidates session in FDB, making JWT useless even if signature valid.

⚠️ Gotchas

1. list_by_tenant() takes &Uuid, not Uuid - use &tenant_id
2. Server panics if JWT_SECRET missing - this is intentional (fail fast)
3. Session expiry uses expires_at field, not JWT exp claim
4. Refresh rotation creates NEW session, old one marked is_active = false

📊 Token Budget

• Phase 1 (Research): 15K tokens
• Phase 2 (Design): 18K tokens
• Total used: 33K / 160K (20.6%)
• Remaining budget: 127K (Safe Zone)

🔗 Related Files

• backend/src/handlers/auth.rs - Authentication handlers
• backend/src/middleware/auth.rs - JWT middleware
• backend/src/db/repositories.rs - Session repository
• backend/src/db/models.rs - Session model (line 450)
• docs/07-adr/ADR-023-session-management.md - Design decisions

## Validation Rules

### Control Command Validation

✅ **Valid Control Commands:**
```python
# Valid syntax
"CONTROL: PAUSE"
"CONTROL: CHECKPOINT REASON: High token usage"
"CONTROL: DELEGATE codebase-analyzer"

# Valid reasons
REASON: Token usage at 85%
REASON: Ambiguous requirements
REASON: Max iterations reached (10)

❌ Invalid Control Commands:

# Missing CONTROL: prefix
"PAUSE"
"Just checkpoint this"

# Invalid command
"CONTROL: MAGIC_COMMAND"

# Malformed syntax
"CONTROL CHECKPOINT"  # Missing colon
"CONTROL: "           # No command

Delegation Validation

✅ Valid Delegations:

• Target agent exists in available agents list
• Task description is specific and measurable
• Token budget specified (if part of larger workflow)
• Deliverable format defined

❌ Invalid Delegations:

• Target agent doesn't exist
• Vague task ("analyze the code")
• No success criteria
• Missing context

Integration with Orchestrator

The orchestrator agent uses this skill automatically when:

1. Executing multi-phase workflows (7 production workflows)
2. Managing token budgets across subagent calls
3. Creating checkpoints at 85% token threshold
4. Delegating to specialized subagents (parallel or sequential)

Example orchestrator usage:

🎯 ORCHESTRATION REQUEST ANALYSIS

Request: Full-stack authentication refactor
Workflow: Full-Stack Feature Development
Token Budget: 60K / 160K (37.5%)

Phase 1: Research
CONTROL: DELEGATE codebase-locator
CONTROL: DELEGATE codebase-analyzer
[Parallel execution, wait for both]

Token Check: 28K / 60K (46.6%) - SAFE ZONE

Phase 2: Implementation
[If token usage reaches 85%]
CONTROL: CHECKPOINT
REASON: Token usage at 136K/160K, saving state before CODE phase

Executable Scripts

See core/validate_control_command.py for control command validation. See core/delegation_template_generator.py for delegation YAML generation.

Best Practices

✅ Use CONTROL commands explicitly - Don't imply, state clearly ✅ Provide REASON - Helps with debugging and handoffs ✅ Checkpoint before critical phases - Don't wait until 95% ✅ Delegate with context - Include token budget and priority ✅ Create handoffs at session end - Even if not at checkpoint

❌ Don't overuse ESCALATE - Try CHECKPOINT first ❌ Don't PAUSE without clear question - Be specific ❌ Don't delegate without deliverable - Define expected output ❌ Don't skip handoff creation - Future you will thank past you

T2-Specific Examples

Example 1: Sprint 2-3 Auth Refactor Handoff

Real handoff from T2 project (2025-10-18):

## Quick Handoff

**Session:** 2025-10-18-auth-refactor
**Status:** Phase 2/4 Complete (SOLVE → CODE)
**Next:** Start at backend/src/handlers/auth.rs:167

Just completed authentication design. Removed fallback JWT_SECRET logic.
Server now requires JWT_SECRET env var (panics if missing - by design).
Next: Implement token refresh rotation (15 min warmup task).

**Current State:**
- ✅ Design complete (auth.rs:1-50)
- ✅ Session invalidation added (repositories.rs:610)
- 🔜 Token refresh rotation (auth.rs:200-250)

**Gotchas:**
- list_by_tenant() takes &Uuid, not Uuid
- Server panics if JWT_SECRET missing (intentional)

Result: Next session resumed in 5 minutes (no context rebuild needed)

Example 2: Orchestrator Multi-Agent Delegation (T2)

Orchestrator coordinating security audit:

parallel_delegation:
  coordinator: orchestrator
  workflow: "Security Audit"
  token_budget: 55000
  agents:
    - agent: codebase-locator
      task: "Find all JWT-related files (backend + frontend)"
      timeout: 5min
      expected_output: "Categorized file list with counts"
    - agent: web-search-researcher
      task: "Research JWT best practices 2025"
      timeout: 8min
      expected_output: "Top 5 vulnerabilities + mitigation"
    - agent: thoughts-locator
      task: "Find auth design decisions (ADRs)"
      timeout: 3min
      expected_output: "ADR-023 session management doc"
  aggregation_strategy: "Merge by priority (vulnerabilities > files > decisions)"
  checkpoint_after: true

Token Efficiency:

• Without structured delegation: 3 sequential calls = 25K tokens
• With parallel delegation: 12K tokens (52% reduction)

Example 3: CHECKPOINT Before Context Collapse

T2 orchestrator implementing full-stack feature:

Phase 1: Research (15K tokens)
Phase 2: Design (18K tokens)
Phase 3: Backend Implementation (25K tokens)

✅ Token Check: 58K / 60K (96.6%) - CRITICAL ZONE

CONTROL: CHECKPOINT
REASON: Token usage at 58K/60K (96.6%), checkpoint before frontend implementation

[Checkpoint created: ckpt_user_profile_phase3]
[Context saved: 58K tokens compressed to 8K handoff]

Phase 4: Frontend Implementation (Resumed in new session)
Token Usage: 8K (handoff) + 22K (implementation) = 30K
Total Saved: 58K - 8K = 50K tokens (86% reduction)

Troubleshooting

Issue 1: Delegation Target Agent Not Found

Symptom:

Error: Agent 'code-analyzer' not found in available agents list

Cause: Typo in agent name or agent not available

Fix: Verify agent name matches exactly

# WRONG
to_agent: code-analyzer  # ❌ Incorrect name

# CORRECT
to_agent: codebase-analyzer  # ✅ Exact match from .claude/agents/

Available T2 Agents:

• orchestrator, codebase-analyzer, codebase-locator, codebase-pattern-finder
• project-organizer, thoughts-analyzer, thoughts-locator, web-search-researcher
• tdd-validator, quality-gate, completion-gate, research-agent

Issue 2: Checkpoint Not Restoring State

Symptom: New session starts from scratch despite CHECKPOINT

Cause: Checkpoint document not created or not accessible

Fix: Use TodoWrite tool to persist checkpoint

# Create checkpoint document
Write(
  file_path="thoughts/shared/research/2025-10-20-sprint-3-checkpoint.md",
  content=checkpoint_content
)

# Reference in git commit
git commit -m "feat: Checkpoint Sprint 3 Phase 2 - Auth implementation

Checkpoint ID: ckpt_sprint3_phase2
Token usage: 58K/160K (36%)
Next: Start at backend/src/handlers/auth.rs:200"

Issue 3: Parallel Delegation Blocking

Symptom: Parallel delegation executes sequentially, taking 3x longer

Cause: Using multiple messages instead of single message with multiple Task calls

Fix: Use single message with multiple Task tool calls

# WRONG: Multiple messages (sequential execution)
Task(subagent_type="general-purpose", prompt="Use codebase-locator subagent to, prompt="Find files")
# Wait for response...
Task(subagent_type="general-purpose", prompt="Use codebase-analyzer subagent to, prompt="Analyze code")

# CORRECT: Single message with 2 Task calls (parallel execution)
[
  Task(subagent_type="general-purpose", prompt="Use codebase-locator subagent to, prompt="Find files"),
  Task(subagent_type="general-purpose", prompt="Use codebase-analyzer subagent to, prompt="Analyze code")
]

Issue 4: ESCALATE Overused

Symptom: Frequent ESCALATE commands, slowing workflow

Cause: Using ESCALATE instead of CHECKPOINT or PAUSE

Fix: Follow escalation hierarchy

1. Try CHECKPOINT (save state, resume later)
   ↓ Still stuck?
2. Try PAUSE (ask user for clarification)
   ↓ Still stuck after 3 iterations?
3. Use ESCALATE (manual intervention needed)

Example:

# WRONG: Escalate immediately
"Implementation challenging"
CONTROL: ESCALATE

# CORRECT: Checkpoint and strategize
"Implementation challenging, need research phase"
CONTROL: CHECKPOINT
REASON: Need to research Rust async patterns before continuing
[Resume with web-search-researcher agent]

Issue 5: Handoff Document Too Long

Symptom: Handoff document is 5000+ words, takes 20 min to load

Cause: Including full code instead of file:line references

Fix: Use progressive disclosure pattern

# WRONG: Full code in handoff (5000 words)
## Completed Work
Here's the complete auth.rs file:
[500 lines of Rust code...]

# CORRECT: References only (200 words)
## Completed Work
- auth.rs:167,302,337 - Removed JWT_SECRET fallback
- repositories.rs:610 - Added invalidate_session()
- middleware/auth.rs:45 - Enhanced Claims validation

[Use Read tool to load full code when needed]

Token Efficiency:

• Full code handoff: 5000 words × 1.3 tokens/word = 6500 tokens
• Reference handoff: 200 words × 1.3 tokens/word = 260 tokens
• Savings: 96% reduction (6500 → 260)

Token Economics

Structured vs Unstructured Handoffs:

Handoff Type	Token Cost	Context Rebuild Time	Success Rate
No handoff	0	60 min (full rebuild)	40%
Unstructured notes	1000	30 min (partial rebuild)	65%
Quick handoff (200 words)	260	10 min (minimal rebuild)	85%
Full checkpoint	800	2 min (near-instant)	95%

ROI Analysis:

• Quick handoff cost: 260 tokens (< $0.01)
• Time saved: 50 minutes per session
• Quality improvement: 40% → 85% success rate

Recommendation: Use quick handoffs (200 words) for daily work, full checkpoints for critical phases.

Examples

See examples/delegation_examples.md for real-world delegation patterns.

---

Success Output

When successful, this skill MUST output:

✅ SKILL COMPLETE: communication-protocols

Completed:
- [x] Control command executed: {COMMAND} (reason: {reason})
- [x] Delegation completed to {target_agent} with deliverable received
- [x] Handoff document created ({word_count} words, {token_estimate} tokens)
- [x] Checkpoint saved at {checkpoint_id} ({token_percentage}% usage)
- [x] Workflow state advanced from {from_state} to {to_state}

Outputs:
- Handoff document: {handoff_path}
- Checkpoint file: .coditect/checkpoints/{checkpoint_id}.json
- Delegation results: {agent_count} agents completed ({parallel_count} parallel)
- Token savings: {savings_tokens} tokens ({savings_pct}% reduction)

Completion Checklist

Before marking this skill as complete, verify:

• Control command syntax validated (CONTROL: prefix, valid command)
• REASON provided for all control commands
• Delegation target agent exists in available agents list
• Handoff document includes file:line references (not full code)
• Checkpoint JSON contains all required fields (commands, delegations, state, tokens)
• Quick handoff under 300 words (200 target)
• Parallel delegations executed in single message with multiple Task calls
• Token budget tracked and reported accurately
• Workflow state consistent with checkpoint data

Failure Indicators

This skill has FAILED if:

• ❌ Control command missing CONTROL: prefix
• ❌ Invalid command used (not PAUSE/CHECKPOINT/ESCALATE/RESUME/DELEGATE)
• ❌ Delegation target agent not found in available agents
• ❌ Handoff document exceeds 5000 words (too detailed)
• ❌ Checkpoint not created before ESCALATE
• ❌ Parallel delegations executed sequentially (missed optimization)
• ❌ Token budget calculation returns negative or > max_tokens
• ❌ RESUME without valid checkpoint_id
• ❌ PAUSE without clear question/reason

When NOT to Use

Do NOT use this skill when:

• Simple single-agent task (no coordination needed)
• Token usage < 50% and no checkpoint needed
• Trivial user questions requiring no multi-step workflow
• Working independently without delegation requirements
• No state handoff needed (task completes in single session)
• Manual user interaction expected throughout (not automated workflow)

Use alternative skills:

• For simple orchestration → Direct agent invocation
• For session management → memory-context-patterns
• For task tracking → task-tracking-patterns
• For workflow automation → workflow-automation-patterns

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Missing CONTROL: prefix	Command not recognized	Always use "CONTROL: COMMAND" format
Overusing ESCALATE	Workflow stalls frequently	Try CHECKPOINT first, then PAUSE
Full code in handoffs	5000+ word handoffs	Use file:line references, progressive disclosure
Sequential parallel tasks	3x slower execution	Use single message with multiple Task calls
Checkpointing too late	Context collapse at 99%	Checkpoint at 85% token threshold
Vague PAUSE reasons	User confused	State explicit question or clarification needed
No handoff at session end	60 min context rebuild	Always create quick handoff (200 words)
Delegating without deliverable	No success criteria	Define expected output format

Principles

This skill embodies:

• #5 Eliminate Ambiguity - Explicit control commands with reasons
• #6 Clear, Understandable, Explainable - Structured handoffs with clear next steps
• #7 Composability - Control commands compose with all workflow types
• #8 No Assumptions - Validate agent availability before delegation
• #9 Progressive Disclosure - Quick handoffs (200 words) → Full checkpoints (800 words)
• #10 Research When in Doubt - Token economics documented with ROI analysis

Full Standard: CODITECT-STANDARD-AUTOMATION.md

---

Multi-Context Window Support

This skill supports long-running multi-agent coordination across multiple context windows using Claude 4.5's enhanced state management capabilities.

State Tracking

Communication State (JSON):

{
  "checkpoint_id": "ckpt_20251129_160000",
  "control_commands_issued": [
    {"command": "DELEGATE", "target": "codebase-analyzer", "status": "complete"},
    {"command": "CHECKPOINT", "reason": "Token usage 85%", "status": "complete"},
    {"command": "PAUSE", "reason": "Await user clarification", "status": "in_progress"}
  ],
  "delegation_chain": [
    {"agent": "orchestrator", "to": "codebase-locator", "result": "15 files found"},
    {"agent": "orchestrator", "to": "codebase-analyzer", "result": "in_progress"}
  ],
  "workflow_state": "SOLVE",
  "token_budget": {"used": 136000, "limit": 160000, "percentage": 85},
  "created_at": "2025-11-29T16:00:00Z"
}

Progress Notes (Markdown):

# Communication Protocols Progress - 2025-11-29

## Completed
- Delegated file discovery to codebase-locator (15 files found)
- Created checkpoint at 85% token usage
- Delegated analysis to codebase-analyzer

## In Progress
- Awaiting user clarification on authentication approach
- codebase-analyzer running security analysis

## Next Actions
- Resume after user input
- Process analyzer results
- Continue to CODE phase

Session Recovery

When starting a fresh context window after multi-agent coordination:

1. Load Checkpoint State: Read .coditect/checkpoints/communication-latest.json
2. Review Progress Notes: Check communication-progress.md for context
3. Verify Workflow State: Check FSM state (INITIATE, IDENTIFY, SOLVE, etc.)
4. Check Delegation Status: Verify which agents completed tasks
5. Resume Coordination: Continue from last control command

Recovery Commands:

# 1. Check latest checkpoint
cat .coditect/checkpoints/communication-latest.json | jq '.control_commands_issued'

# 2. Review progress
tail -30 communication-progress.md

# 3. Check workflow state
cat .coditect/checkpoints/communication-latest.json | jq '.workflow_state'

# 4. Review delegation chain
cat .coditect/checkpoints/communication-latest.json | jq '.delegation_chain'

# 5. Check token budget
cat .coditect/checkpoints/communication-latest.json | jq '.token_budget'

State Management Best Practices

Checkpoint Files (JSON Schema):

• Store in .coditect/checkpoints/communication-{timestamp}.json
• Track control command history with reasons
• Record delegation chain and results
• Monitor token budget percentage

Progress Tracking (Markdown Narrative):

• Maintain communication-progress.md with command history
• Document delegation rationale and agent selection
• Note PAUSE reasons and user responses
• List next coordination steps

Git Integration:

• Create checkpoint before ESCALATE commands
• Commit handoff documents: docs(coord): Create Sprint 3 Phase 2 handoff
• Tag workflow milestones: git tag workflow-solve-complete

Progress Checkpoints

Natural Breaking Points:

1. After each control command executed (PAUSE, CHECKPOINT, DELEGATE)
2. After delegation chain completes
3. Before workflow state transitions
4. When token budget reaches 85%
5. After ESCALATE or session handoff

Checkpoint Creation Pattern:

# Automatic checkpoint at critical coordination points
if token_percentage >= 85 || control_command in ["ESCALATE", "CHECKPOINT"] {
    create_checkpoint({
        "commands": command_history,
        "delegations": agent_chain,
        "state": current_fsm_state,
        "tokens": budget_status
    })
}

Example: Multi-Context Multi-Agent Workflow

Context Window 1: Discovery & Analysis

{
  "checkpoint_id": "ckpt_coord_phase1",
  "phase": "discovery_complete",
  "delegations": ["codebase-locator", "codebase-analyzer"],
  "workflow_state": "DOCUMENT",
  "next_action": "Transition to SOLVE",
  "token_usage": 45000
}

Context Window 2: Solution & Implementation

# Load checkpoint
cat .coditect/checkpoints/ckpt_coord_phase1.json

# Continue from DOCUMENT → SOLVE
# Token savings: ~25000 tokens (delegation results cached)

Token Savings Analysis:

• Without checkpoint: 70000 tokens (re-run delegations + analysis)
• With checkpoint: 45000 tokens (resume from cached results)
• Savings: 36% reduction (70000 → 45000 tokens)