blue/.blue/docs/dialogues/2026-01-25-claude-code-task-integration.dialogue.md

# Alignment Dialogue: Claude Code Task Integration

| | |
|---|---|
| **Topic** | RFC for integrating Blue plan files with Claude Code's task management |
| **Source** | Spike: Claude Code Task Integration (2026-01-26) |
| **Experts** | 12 |
| **Target** | 95% convergence |
| **Status** | In Progress |

---

## Round 1: Initial Perspectives

### Scoreboard

| Expert | Role | Wisdom | Consistency | Truth | Relationships | Total |
|--------|------|--------|-------------|-------|---------------|-------|
| 1 | Systems Architect | 9 | 9 | 9 | 8 | 35 |
| 2 | Developer Experience | 8 | 9 | 8 | 9 | 34 |
| 3 | File System Philosopher | 10 | 10 | 10 | 7 | 37 |
| 4 | MCP Protocol Expert | 9 | 10 | 9 | 8 | 36 |
| 5 | Workflow Automation | 8 | 8 | 8 | 8 | 32 |
| 6 | Data Sync Expert | 8 | 9 | 9 | 7 | 33 |
| 7 | UI Designer | 9 | 8 | 9 | 9 | 35 |
| 8 | Reliability Engineer | 9 | 9 | 9 | 7 | 34 |
| 9 | Simplicity Advocate | 10 | 9 | 10 | 8 | 37 |
| 10 | Security Analyst | 8 | 9 | 9 | 7 | 33 |
| 11 | Integration Architect | 9 | 8 | 8 | 8 | 33 |
| 12 | Blue ADR Guardian | 9 | 10 | 10 | 9 | 38 |

### Convergence Points (100%)

1. **File Authority**: `.plan.md` files are the single source of truth (ADR 5)
2. **Ephemeral Tasks**: Claude Code tasks are session-local mirrors, not persistent state
3. **Skill Orchestration**: Skills mediate between Blue MCP and Claude Code tasks
4. **No MCP Push**: MCP's request-response nature means Blue cannot initiate sync

### Key Perspectives

**Expert 3 (File System Philosopher):**
> "The file must win, always. When divergence is detected, the file's state is ground truth; the database state is an error to be corrected."

**Expert 9 (Simplicity Advocate):**
> "The integration isn't worth the complexity... Strip this down to read-only exposure. If a user wants to update the Blue plan after completing a Claude Code task, they run `blue_rfc_task_complete` explicitly."

**Expert 4 (MCP Protocol Expert):**
> "Pure skill orchestration is sufficient. The MCP server stays pure—it only answers queries about its documents, never tries to manage external task state."

**Expert 7 (UI Designer):**
> "Make task state transitions (not progress updates) the trigger for filesystem writes."

### Tensions

| Tension | Position A | Position B | Experts |
|---------|-----------|-----------|---------|
| Integration Scope | Full bidirectional sync | Read-only context only | 1,2,5,6,7,8,11 vs 9 |
| New Blue Tools | Add `blue_task_context` | Pure skill orchestration | 11 vs 4,9 |
| Sync Timing | Automatic on completion | Explicit user command | 2,7 vs 5,6,9 |

### Round 1 Convergence: ~75%

Strong agreement on principles, divergence on implementation scope.

---

## Round 2: Resolving Tensions

### Votes

| Expert | Tension 1 | Tension 2 | Tension 3 |
|--------|-----------|-----------|-----------|
| 1 | - | - | - |
| 2 | B | B | B |
| 3 | A | B | B |
| 4 | B | B | B |
| 5 | B | B | B |
| 6 | B | B | B |
| 7 | B | B | B |
| 8 | B | B | B |
| 9 | B | B | B |
| 10 | B | B | B |
| 11 | B | B | B |
| 12 | B | B | B |

### Results

| Tension | Position A | Position B | Winner |
|---------|-----------|-----------|--------|
| 1. Integration Scope | 1 (9%) | 10 (91%) | **B: Read-only context injection** |
| 2. New Blue Tools | 0 (0%) | 11 (100%) | **B: Pure skill orchestration** |
| 3. Sync Timing | 0 (0%) | 11 (100%) | **B: Explicit sync command** |

### Round 2 Convergence: 97%

Target of 95% achieved.

---

## Consensus

The 12 experts converged on the following RFC specification:

### Core Principles

1. **File Authority**: `.plan.md` files are the single source of truth for RFC task state
2. **Ephemeral Mirror**: Claude Code tasks are session-local projections, not persistent state
3. **Skill Orchestration**: A `/blue-plan` skill mediates using existing tools only
4. **Explicit Sync**: Users invoke `blue_rfc_task_complete` manually to persist changes

### Architecture

```
┌─────────────────┐     read      ┌─────────────────┐
│   .plan.md      │◄──────────────│  /blue-plan     │
│   (authority)   │               │    skill        │
└─────────────────┘               └────────┬────────┘
        ▲                                  │
        │                                  │ create
        │ explicit                         ▼
        │ blue_rfc_task_complete   ┌─────────────────┐
        │                          │  Claude Code    │
        └──────────────────────────│    Tasks        │
              user invokes         │  (ephemeral)    │
                                   └─────────────────┘
```

### What the Skill Does

1. On `/blue-plan <rfc-title>`:
   - Calls `blue_rfc_get` to fetch RFC with plan tasks
   - Creates Claude Code tasks via `TaskCreate` for each plan task
   - Stores mapping in task metadata: `{ blue_rfc: "title", blue_task_index: N }`

2. During work:
   - User works normally, Claude marks tasks in_progress/completed
   - Claude Code UI shows progress

3. On task completion:
   - User (or skill prompt) calls `blue_rfc_task_complete` explicitly
   - Plan file updated, becomes source of truth for next session

### What We Don't Build

- No automatic writeback from Claude Code to plan files
- No new Blue MCP tools (existing tools sufficient)
- No bidirectional sync machinery
- No watcher processes or polling

### ADR Alignment

| ADR | Alignment |
|-----|-----------|
| ADR 5 (Single Source) | `.plan.md` is sole authority |
| ADR 8 (Honor) | Explicit sync = say what you do |
| ADR 10 (No Dead Code) | No new tools needed |
| ADR 11 (Constraint) | Simple one-way flow |

---

## Status

~~CONVERGED at 97%~~ - User rejected skills and explicit sync.

---

## Round 3: User Constraints

**User Requirements:**
1. No explicit sync - automatic/implicit instead
2. No skills - don't add Claude Code skills
3. Use injection - context appears automatically

### New Consensus

| Expert | Position | Key Insight |
|--------|----------|-------------|
| 1 | MCP Resources | Expose `.plan.md` as resource, inject on RFC access |
| 2 | Seamless UX | Zero onboarding, tasks appear naturally |
| 3 | Visible Sync | Automatic OK if auditable (git commits) |
| 4 | Tool-Triggered | `blue_rfc_get` returns `_plan_uri` for injection |
| 5 | Lazy Injection | Inject on-demand when RFC referenced |
| 6 | Hash Versioning | Content-hash with three-way merge on conflict |
| 7 | Audit Trail | Sync events logged, visible in status |
| 8 | Confirmation | Three-phase handshake for reliability |
| 9 | File Watcher | Session-scoped injection + file watcher |
| 10 | **DISSENT** | Automatic file writes are security risk |
| 11 | Hooks | Option B+C: tool injection + hook writeback |
| 12 | Observable | Automatic sync honors ADR 8 if transparent |

### Convergence: ~92%

Expert 10 dissents on automatic writeback security.

### Proposed Architecture

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

### Implementation Approach

1. **MCP Resource**: Expose `.plan.md` files via `blue://docs/rfcs/{id}/plan`
2. **Tool Enhancement**: `blue_rfc_get` includes `_plan_uri` and auto-creates Claude Code tasks
3. **Hook Integration**: Claude Code hook watches task state → calls `blue_rfc_task_complete`
4. **Audit Trail**: All syncs logged with timestamps, visible in `blue status`

### Security Mitigation (for Expert 10's concern)

- Writeback only for tasks with valid `blue_rfc` metadata
- Content-hash validation before write (detect external changes)
- Audit log in `.plan.md` comments for forensics
- Rate limiting on automatic writes

---

## Round 4: Security Resolution

**Question**: How to address Expert 10's security concern about automatic file writes?

| Option | Description |
|--------|-------------|
| A | Accept risk with mitigations only |
| B | First-time confirmation per RFC |
| C | Opt-in via config (disabled by default) |

### Votes

| Expert | Vote | Justification |
|--------|------|---------------|
| 1 | B | Confirmation friction only hits once per RFC |
| 2 | B | Builds confidence after first sync |
| 3 | B | Establishes implicit consent to manage companion file |
| 9 | B | Sweet spot: informed consent without ongoing friction |
| 10 | B | Hash validation + first confirmation = informed consent |
| 12 | B | ADR 8 requires transparency; confirmation makes behavior knowable |

### Result: **Option B Unanimous (100%)**

First-time confirmation per RFC satisfies security concern while preserving seamless UX.

---

## Final Consensus

**Convergence: 97%** - Target achieved.

### 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 triggers
         ▼
┌─────────────────────────────────────────────────────────┐
│  First time for this RFC?                               │
│  ├─ YES → Confirm: "Enable auto-sync for RFC X?" [Y/n] │
│  └─ NO  → Automatic writeback                          │
└─────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────┐
│ blue_rfc_task   │────────► Updates .plan.md
│    _complete    │
└─────────────────┘
```

### Key Decisions

| Decision | Rationale |
|----------|-----------|
| MCP Resource injection | Context appears automatically, no skills |
| Tool-triggered task creation | `blue_rfc_get` auto-populates Claude Code tasks |
| Hook-based writeback | Task completion triggers `blue_rfc_task_complete` |
| First-time confirmation | Balances security with seamlessness |
| Audit trail | All syncs logged, visible in git |

### ADR Alignment

| ADR | How Honored |
|-----|-------------|
| ADR 5 (Single Source) | `.plan.md` remains authoritative |
| ADR 8 (Honor) | First-time confirmation = explicit consent |
| ADR 11 (Constraint) | Automatic flow with minimal friction |

---

## Round 5: User Override

**User Decision**: Remove first-time confirmation. It adds friction for a low-risk operation.

Rationale:
- User is already in their own project
- Writes are just checkbox updates in `.plan.md`
- Git provides full audit trail and rollback
- The "security risk" is overstated for this context

**Final Architecture**: Fully automatic. No prompts, no confirmation.

---

---

## Round 6: Open Questions

### Q1: Visual indicator for auto-created tasks?
**User Decision**: Yes, use 💙

### Q2: Mid-session task additions?

| Expert | Vote | Rationale |
|--------|------|-----------|
| 1 | B | Honors file authority, syncs at natural interaction points |
| 2 | B | Predictable - sync at interaction, not background |
| 3 | B | File is truth, re-read ensures current state |
| 9 | B | Rebuild-on-read already exists, no new complexity |
| 11 | B | Lazy re-read aligns with `is_cache_stale()` pattern |
| 12 | B | ADR 5 requires trusting `.plan.md` as authority |

**Result: B (Poll on access) - Unanimous**

Re-read plan file on next `blue_rfc_get`, create missing tasks.

---

## Status

**CONVERGED** - All open questions resolved. RFC 0019 ready.