Eric Garcia 9759f0e3db feat: implement plan file authority (RFC 0017)

Plan files (.plan.md) are now the authoritative source for RFC task
tracking, with SQLite as a derived cache rebuilt on read.

Changes:
- Add plan.rs with PlanFile parsing/generation
- Add schema v7 migration for plan_cache table
- Modify handle_rfc_plan to write .plan.md files
- Modify handle_rfc_task_complete to update .plan.md
- Implement rebuild-on-read for stale cache detection
- Add RFC header validation (table vs inline format)
- Extend blue_lint with headers check and --fix support

Also includes spike investigating Claude Code task integration.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-25 20:10:05 -05:00

2.7 KiB

Raw Blame History

Spike: Claude Code Task Integration


Status	In Progress
Date	2026-01-26
Time Box	2 hours

Question

How can Blue integrate with Claude Code's built-in task management (TaskCreate/TaskUpdate/TaskList) to provide bidirectional sync between Blue's RFC tasks and Claude Code's UI?

Investigation

What Claude Code Provides

Claude Code has built-in task management tools:

TaskCreate - Create tasks with subject, description, activeForm
TaskUpdate - Update status (pending → in_progress → completed)
TaskList - List all tasks with status
TaskGet - Get full task details

These render in Claude Code's UI with a progress tracker showing task status.

Integration Approaches

Approach 1: MCP Server Push (Not Viable)

MCP servers can only respond to requests - they cannot initiate calls to Claude Code's task system.

Approach 2: Claude Code Skill (Recommended)

Create a /blue-plan skill that orchestrates both systems:

User: /blue-plan rfc-17
Skill:
  1. Call blue_rfc_get to fetch RFC tasks
  2. For each task, call TaskCreate with:
     - subject: task description
     - metadata: { blue_rfc: 17, blue_task_index: 0 }
  3. As work progresses, TaskUpdate syncs status
  4. On completion, call blue_rfc_task_complete

Pros: Clean separation, skill handles orchestration Cons: Manual invocation required

Approach 3: .plan.md as Shared Interface

The .plan.md file (RFC 0017) becomes the bridge:

Blue writes/reads plan files
A watcher process syncs changes to Claude Code tasks
Task checkbox state is the single source of truth

Pros: File-based, works offline Cons: Requires external sync process

Approach 4: Hybrid - Skill + Plan File

/blue-plan skill reads .plan.md and creates Claude Code tasks
User works, marking tasks complete in Claude Code
On session end, skill writes back to .plan.md
Blue picks up changes on next read (rebuild-on-read from RFC 0017)

Recommended Path

Phase 1: Implement RFC 0017 (plan file authority) - gives us the file format Phase 2: Create /blue-plan skill that syncs plan → Claude Code tasks Phase 3: Add completion writeback to skill

Key Insight

The .plan.md format is already compatible with Claude Code's task model:

- [ ] Task maps to TaskCreate with status=pending
- [x] Task maps to status=completed

The skill just needs to translate between formats.

Conclusion

Integration is viable via a Claude Code skill that reads .plan.md files and creates corresponding Claude Code tasks. This preserves Blue's file-first philosophy while enabling Claude Code's task UI.

Next: Create RFC for skill implementation after RFC 0017 is complete.

2.7 KiB Raw Blame History