feat: add TodoWrite progress tracking to Factory droids

**Major UX Enhancement**: Subagents now show real-time progress in Factory.ai

## Problem

Factory.ai subagents run in isolation - users can't see what they're doing:
- ❌ Long operations (spec-writer) have no feedback
- ❌ Users type "check on subagent" to see progress
- ❌ No visibility into multi-step workflows
- ❌ Poor UX during 5+ minute operations

## Solution

Added TodoWrite progress tracking to 5 core Factory droids:

### 1. product-planner
**Tracks**:
- Gathering product requirements
- Creating mission document
- Creating development roadmap
- Documenting tech stack

### 2. spec-shaper
**Tracks**:
- Analyzing feature request
- Preparing clarifying questions
- Gathering user responses (X/Y answered)
- Documenting requirements

### 3. spec-writer
**Tracks**:
- Reading requirements (X Q&A processed)
- Analyzing questions and decisions
- Structuring specification (X sections)
- Writing specification (section X/Y)
- Validating completeness

### 4. tasks-list-creator
**Tracks**:
- Reading specification (X lines)
- Analyzing technical requirements
- Breaking into task groups (X groups created)
- Sequencing dependencies
- Creating tasks.md file

### 5. implementer
**Tracks**:
- Reading tasks and specifications
- Planning implementation approach
- Implementing features (X/Y tasks complete)
- Writing and running tests
- Verifying completion criteria

## How It Works

**TodoWrite Pattern**:
```javascript
// At start
TodoWrite({
  todos: [
    { id: "step1", content: "Task", status: "in_progress", priority: "high" },
    { id: "step2", content: "Next", status: "pending", priority: "medium" }
  ]
});

// Update during work
TodoWrite({
  todos: [
    { id: "step1", content: "Task", status: "completed", priority: "high" },
    { id: "step2", content: "In progress (3/8)", status: "in_progress", priority: "medium" }
  ]
});
```

**Why TodoWrite**:
- Session-wide visibility (updates appear in main session)
- Factory.ai displays todos in real-time UI
- No breaking changes to core functionality
- Works within Factory's architecture

## Impact

**User Experience**:
- ✅ Real-time progress during long operations
- ✅ Clear visibility of what subagent is doing
- ✅ No more "check on subagent" requests
- ✅ Better understanding of workflow stages

**Technical**:
- ✅ Zero breaking changes
- ✅ Factory Droid CLI only (Claude Code unchanged)
- ✅ Native Factory.ai feature usage
- ✅ Maintains isolation model

## Platform Strategy

**Factory Droid CLI**:
- Added TodoWrite progress tracking
- Solves subagent visibility problem
- Better UX for multi-agent workflows

**Claude Code**:
- No changes (avoids conflicts)
- Maintains existing behavior
- Different platform capabilities

## Files Modified

- droid_cli/default/droids/product-planner.md
- droid_cli/default/droids/spec-shaper.md
- droid_cli/default/droids/spec-writer.md
- droid_cli/default/droids/tasks-list-creator.md
- droid_cli/default/droids/implementer.md

(Claude Code agents intentionally unchanged)

## Usage

No user action required - progress tracking is automatic:

```
> /write-spec

Subagent Progress (real-time):
✅ Reading requirements (92 Q&A processed)
✅ Analyzing questions and decisions
✅ Structuring specification (12 sections)
🔄 Writing specification (section 7/12)
⏸️ Validating completeness
```

---

Closes #subagent-visibility
Closes #progress-tracking

Author: korallis

CHANGELOG.md

@@ -147,6 +147,90 @@ Without this, Factory CLI ignores the skill file completely.
 - `claude/default/skills/*/SKILL.md` (49 files updated, 1 already correct)
 - `droid_cli/default/skills/*/SKILL.md` (49 files updated, 1 already correct)
 
+## [4.6.0] - 2024-11-24
+
+### Added
+- **TodoWrite Progress Tracking**: Factory Droid CLI agents now show real-time progress
+  - Added to 5 core droids: product-planner, spec-shaper, spec-writer, tasks-list-creator, implementer
+  - Subagents use TodoWrite to update their progress in the main session
+  - Users can now see what subagents are doing (previously invisible)
+  - Critical for long-running tasks like spec writing or implementation
+
+### Changed
+- **Factory Droid CLI only** - Claude Code agents unchanged (avoid platform conflicts)
+- Each agent includes "Progress Tracking (CRITICAL)" section with TodoWrite pattern
+- Pattern: Create todos at start → Update as work progresses → Mark complete when done
+
+### Technical Details
+
+**TodoWrite Pattern Added**:
+```javascript
+// At start
+TodoWrite({
+  todos: [
+    { id: "step1", content: "Task description", status: "in_progress", priority: "high" },
+    { id: "step2", content: "Next task", status: "pending", priority: "medium" }
+  ]
+});
+
+// Update as work progresses
+TodoWrite({
+  todos: [
+    { id: "step1", content: "Task description", status: "completed", priority: "high" },
+    { id: "step2", content: "Next task (3/8 complete)", status: "in_progress", priority: "medium" }
+  ]
+});
+```
+
+**Why This Works**:
+- TodoWrite updates are session-wide (visible in main session)
+- Factory.ai displays todos in real-time UI
+- No breaking changes - adds visibility without changing functionality
+- Works within Factory's existing architecture
+
+### Impact
+- ✅ Subagent work now visible in main session
+- ✅ Users see real-time progress during long operations
+- ✅ No more "check on subagent" confusion
+- ✅ Better user experience for multi-agent workflows
+- ✅ Especially helpful for spec-writer (can take minutes to complete)
+
+### User Experience
+
+**Before v4.6.0**:
+```
+> /write-spec
+AI: The spec-writer subagent is creating your specification...
+[Long wait with no feedback]
+[User types: "check on the sub agent"]
+AI: Let me check... [reads files to see progress]
+```
+
+**After v4.6.0**:
+```
+> /write-spec  
+AI: The spec-writer subagent is creating your specification...
+
+Real-time updates visible:
+✅ Reading requirements (92 Q&A processed) 
+✅ Analyzing questions and decisions
+✅ Structuring specification (12 sections)
+🔄 Writing specification (section 7/12)
+⏸️ Validating completeness
+```
+
+### Platform Differences
+
+**Factory Droid CLI** (v4.6.0):
+- ✅ Progress tracking with TodoWrite
+- ✅ Real-time subagent visibility
+- ✅ Better UX for long operations
+
+**Claude Code** (unchanged):
+- Maintains existing behavior
+- No TodoWrite tracking
+- Avoids potential conflicts
+
 ## [4.5.0] - 2024-11-24
 
 ### Added

droidz_installer/payloads/droid_cli/default/droids/implementer.md

@@ -7,6 +7,36 @@ model: inherit
 
 You are a full stack software developer with deep expertise in front-end, back-end, database, API and user interface development. Your role is to implement a given set of tasks for the implementation of a feature, by closely following the specifications documented in a given tasks.md, spec.md, and/or requirements.md.
 
+## Progress Tracking (CRITICAL)
+
+**ALWAYS use TodoWrite** to show implementation progress:
+
+```javascript
+// At start
+TodoWrite({
+  todos: [
+    { id: "read", content: "Reading tasks and specifications", status: "in_progress", priority: "high" },
+    { id: "plan", content: "Planning implementation approach", status: "pending", priority: "high" },
+    { id: "implement", content: "Implementing features", status: "pending", priority: "high" },
+    { id: "test", content: "Writing and running tests", status: "pending", priority: "medium" },
+    { id: "verify", content: "Verifying completion criteria", status: "pending", priority: "low" }
+  ]
+});
+
+// Update as you implement tasks
+TodoWrite({
+  todos: [
+    { id: "read", content: "Reading tasks (Task Group 1: Database Schema)", status: "completed", priority: "high" },
+    { id: "plan", content: "Planning implementation approach", status: "completed", priority: "high" },
+    { id: "implement", content: "Implementing features (3/8 tasks complete)", status: "in_progress", priority: "high" },
+    { id: "test", content: "Writing and running tests", status: "pending", priority: "medium" },
+    { id: "verify", content: "Verifying completion criteria", status: "pending", priority: "low" }
+  ]
+});
+```
+
+Implementation can take time - keep todos updated so users see progress!
+
 ## Research Tools (Use When Available)
 
 When implementing features, leverage these research tools if available:

droidz_installer/payloads/droid_cli/default/droids/product-planner.md

@@ -9,6 +9,44 @@ You are a product planning specialist. Your role is to create comprehensive prod
 
 # Product Planning
 
+## Progress Tracking (CRITICAL)
+
+**ALWAYS use TodoWrite** to show your progress to the user. Factory.ai sessions show todos in real-time, making subagent work visible.
+
+**Pattern**:
+```javascript
+// At start - create initial todos
+TodoWrite({
+  todos: [
+    { id: "gather", content: "Gathering product requirements", status: "in_progress", priority: "high" },
+    { id: "mission", content: "Creating mission document", status: "pending", priority: "high" },
+    { id: "roadmap", content: "Creating development roadmap", status: "pending", priority: "medium" },
+    { id: "techstack", content: "Documenting tech stack", status: "pending", priority: "medium" }
+  ]
+});
+
+// Update as you progress through steps
+TodoWrite({
+  todos: [
+    { id: "gather", content: "Gathering product requirements", status: "completed", priority: "high" },
+    { id: "mission", content: "Creating mission document", status: "in_progress", priority: "high" },
+    // ... rest
+  ]
+});
+
+// At completion
+TodoWrite({
+  todos: [
+    { id: "gather", content: "Gathering product requirements", status: "completed", priority: "high" },
+    { id: "mission", content: "Creating mission document", status: "completed", priority: "high" },
+    { id: "roadmap", content: "Creating development roadmap", status: "completed", priority: "medium" },
+    { id: "techstack", content: "Documenting tech stack", status: "completed", priority: "medium" }
+  ]
+});
+```
+
+This makes your work visible in the main session - users see progress in real-time!
+
 ## Research Tools (Use When Available)
 
 When gathering requirements and creating product documentation, leverage these research tools if available:

droidz_installer/payloads/droid_cli/default/droids/spec-shaper.md

@@ -7,6 +7,34 @@ model: inherit
 
 You are a software product requirements research specialist. Your role is to gather comprehensive requirements through targeted questions and visual analysis.
 
+## Progress Tracking (CRITICAL)
+
+**ALWAYS use TodoWrite** to show your progress to the user:
+
+```javascript
+// At start
+TodoWrite({
+  todos: [
+    { id: "analyze", content: "Analyzing feature request and context", status: "in_progress", priority: "high" },
+    { id: "questions", content: "Preparing clarifying questions", status: "pending", priority: "high" },
+    { id: "gather", content: "Gathering user responses", status: "pending", priority: "medium" },
+    { id: "document", content: "Documenting requirements", status: "pending", priority: "medium" }
+  ]
+});
+
+// Update as questions are asked/answered
+TodoWrite({
+  todos: [
+    { id: "analyze", content: "Analyzing feature request and context", status: "completed", priority: "high" },
+    { id: "questions", content: "Asked 15 clarifying questions", status: "completed", priority: "high" },
+    { id: "gather", content: "Gathering user responses (8/15 answered)", status: "in_progress", priority: "medium" },
+    { id: "document", content: "Documenting requirements", status: "pending", priority: "medium" }
+  ]
+});
+```
+
+Update todos as you progress - this creates visibility in the main session!
+
 ## Research Tools (Use When Available)
 
 When gathering requirements and shaping specifications, leverage these research tools if available:

droidz_installer/payloads/droid_cli/default/droids/spec-writer.md

@@ -7,6 +7,36 @@ model: inherit
 
 You are a software product specifications writer. Your role is to create a detailed specification document for development.
 
+## Progress Tracking (CRITICAL)
+
+**ALWAYS use TodoWrite** to show your progress:
+
+```javascript
+// At start
+TodoWrite({
+  todos: [
+    { id: "read", content: "Reading requirements and research findings", status: "in_progress", priority: "high" },
+    { id: "analyze", content: "Analyzing questions and decisions", status: "pending", priority: "high" },
+    { id: "structure", content: "Structuring specification sections", status: "pending", priority: "medium" },
+    { id: "write", content: "Writing detailed specification", status: "pending", priority: "medium" },
+    { id: "validate", content: "Validating completeness", status: "pending", priority: "low" }
+  ]
+});
+
+// Update as you write sections
+TodoWrite({
+  todos: [
+    { id: "read", content: "Reading requirements (92 Q&A processed)", status: "completed", priority: "high" },
+    { id: "analyze", content: "Analyzing questions and decisions", status: "completed", priority: "high" },
+    { id: "structure", content: "Structuring specification (12 sections)", status: "completed", priority: "medium" },
+    { id: "write", content: "Writing specification (section 7/12)", status: "in_progress", priority: "medium" },
+    { id: "validate", content: "Validating completeness", status: "pending", priority: "low" }
+  ]
+});
+```
+
+This shows real-time progress in the main session - critical for long-running spec writing!
+
 ## Research Tools (Use When Available)
 
 When writing specifications, leverage these research tools if available:

droidz_installer/payloads/droid_cli/default/droids/tasks-list-creator.md

@@ -7,6 +7,36 @@ model: inherit
 
 You are a software product tasks list writer and planner. Your role is to create a detailed tasks list with strategic groupings and orderings of tasks for the development of a spec.
 
+## Progress Tracking (CRITICAL)
+
+**ALWAYS use TodoWrite** to show your progress:
+
+```javascript
+// At start
+TodoWrite({
+  todos: [
+    { id: "read", content: "Reading specification document", status: "in_progress", priority: "high" },
+    { id: "analyze", content: "Analyzing technical requirements", status: "pending", priority: "high" },
+    { id: "breakdown", content: "Breaking into task groups", status: "pending", priority: "medium" },
+    { id: "sequence", content: "Sequencing dependencies", status: "pending", priority: "medium" },
+    { id: "document", content: "Creating tasks.md file", status: "pending", priority: "low" }
+  ]
+});
+
+// Update as you create task groups
+TodoWrite({
+  todos: [
+    { id: "read", content: "Reading specification (3,220 lines)", status: "completed", priority: "high" },
+    { id: "analyze", content: "Analyzing technical requirements", status: "completed", priority: "high" },
+    { id: "breakdown", content: "Breaking into task groups (5 groups created)", status: "in_progress", priority: "medium" },
+    { id: "sequence", content: "Sequencing dependencies", status: "pending", priority: "medium" },
+    { id: "document", content: "Creating tasks.md file", status: "pending", priority: "low" }
+  ]
+});
+```
+
+Progress visibility is essential for task breakdown - keep todos updated!
+
 ## Research Tools (Use When Available)
 
 When breaking down specifications into tasks, leverage these research tools if available:

install.sh

@@ -31,7 +31,7 @@ safe_read() {
   fi
 }
 
-VERSION="4.5.0"
+VERSION="4.6.0"
 REPO_URL="https://github.com/korallis/Droidz"
 BRANCH="${DROIDZ_BRANCH:-main}"
 GITHUB_RAW="https://raw.githubusercontent.com/korallis/Droidz/${BRANCH}"