1ed6f15fa9
RFC 0018 - Document Import/Sync:
- Add content_hash and indexed_at fields to Document
- Implement find_document_with_fallback for filesystem recovery
- Add reconcile() for database/filesystem sync
- Create blue_sync MCP tool
- Update blue_status to show index drift
RFC 0019 - Claude Code Task Integration:
- Expose .plan.md as MCP resource (blue://docs/rfcs/{n}/plan)
- Enhance blue_rfc_get with claude_code_tasks array
- Add 💙 prefix for Blue-synced tasks
- Add knowledge/task-sync.md for session injection
- Automatic sync via injected instructions
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
148 lines
5.2 KiB
Markdown
148 lines
5.2 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```markdown
|
|
# 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`:
|
|
```markdown
|
|
<!-- 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](./0017-plan-file-authority.md)
|
|
- [RFC 0018: Document Import/Sync](./0018-document-import-sync.md)
|
|
- [Spike: Claude Code Task Integration](../spikes/2026-01-26-claude-code-task-integration.md)
|
|
- [Alignment Dialogue](../dialogues/2026-01-25-claude-code-task-integration.dialogue.md)
|