blue/.blue/docs/rfcs/0019-claude-code-task-integration.md

RFC 0019: Claude Code Task Integration

Status	Draft
Created	2026-01-25
Source	Spike: Claude Code Task Integration
Dialogue	12-expert alignment, 97% convergence (4 rounds)

---

Problem

Blue's RFC task tracking (via .plan.md files per RFC 0017) and Claude Code's built-in task management operate independently. Users cannot see Blue tasks in Claude Code's UI without manual effort.

Proposal

Integrate Blue plan files with Claude Code through automatic injection and sync - no skills, no explicit commands.

Design Principles

1. File Authority: .plan.md remains the single source of truth
2. Automatic Injection: Plan context appears when RFC is accessed
3. Automatic Sync: Task completion writes back without explicit command

Architecture

┌─────────────────┐                    ┌─────────────────┐
│   .plan.md      │◄───── MCP ────────│  blue_rfc_get   │
│   (authority)   │     Resource       │                 │
└────────┬────────┘                    └────────┬────────┘
         │                                      │
         │ auto-inject                          │ auto-creates
         │ as context                           │ Claude Code tasks
         ▼                                      ▼
┌─────────────────┐                    ┌─────────────────┐
│  Claude Code    │◄───────────────────│   TaskCreate    │
│    Context      │                    │   (automatic)   │
└────────┬────────┘                    └─────────────────┘
         │
         │ on task complete (hook)
         ▼
┌─────────────────┐
│ blue_rfc_task   │────────► Updates .plan.md
│    _complete    │          (automatic)
└─────────────────┘

Implementation

1. MCP Resource: Plan Files

Expose .plan.md files as MCP resources for context injection:

URI: blue://docs/rfcs/{number}/plan
Type: text/markdown

When Claude Code accesses an RFC, the plan resource is automatically available for context injection.

2. Tool Enhancement: Auto Task Creation

Modify blue_rfc_get to:

1. Return RFC content as normal
2. Include _plan_uri field pointing to plan resource
3. Automatically call TaskCreate for each plan task with metadata:

{
  "subject": "Task description from plan",
  "activeForm": "Working on RFC task...",
  "metadata": {
    "blue_rfc": "plan-file-authority",
    "blue_rfc_number": 17,
    "blue_task_index": 0
  }
}

3. Injected Sync Instruction

Via Blue's SessionStart hook, inject knowledge that instructs Claude to sync:

# knowledge/task-sync.md (injected at session start)

When you mark a task complete that has `blue_rfc` metadata,
call `blue_rfc_task_complete` with the RFC title and task index
to update the plan file automatically.

This works in any repo with Blue installed - no per-repo configuration needed.

4. Audit Trail

All syncs are logged:

• In blue status output
• As git-friendly comments in .plan.md:

  <!-- sync: 2026-01-25T10:30:42Z task-0 completed -->
  

What This Enables

Before	After
User runs /blue-plan skill	Tasks appear automatically
User calls blue_rfc_task_complete	Completion syncs via hook
No visibility in Claude Code UI	Full task progress in UI
Manual context switching	Seamless flow

What We Don't Build

Rejected	Reason
Skills	User preference: use injection
Explicit sync command	User preference: automatic
Bidirectional conflict resolution	First-time consent + hash validation sufficient

Security Considerations

Risk	Mitigation
Injection via metadata	Validate blue_rfc metadata exists in Blue
Hash conflicts	Content-hash validation before write
Audit gaps	All syncs logged with timestamps + git history

ADR Alignment

ADR	How Honored
ADR 5 (Single Source)	.plan.md is authoritative; Claude Code tasks are mirrors
ADR 8 (Honor)	Automatic sync is documented behavior; git provides audit
ADR 11 (Constraint)	Fully automatic flow removes all ceremony

Open Questions

1. Should auto-created tasks be marked with a visual indicator? Resolved: Yes, use 💙
2. How to handle task additions mid-session? Resolved: Poll on access - Re-read plan file on next blue_rfc_get, create missing tasks. Aligns with rebuild-on-read pattern from RFC 0017.

References

• RFC 0017: Plan File Authority
• RFC 0018: Document Import/Sync
• Spike: Claude Code Task Integration
• Alignment Dialogue