Sets up a dual-layer tracking system: CRAFT workflow state (the source of truth) and TodoWrite widget (the visual rendering layer)
Tracks multi-step CRAFT workflows visually using Cowork’s native TodoWrite widget for real-time progress display, while maintaining CRAFT’s structured workflow state for handoff serialization. Extends the Core Progress Tracker by bridging CRAFT progress semantics to Cowork’s built-in UI.
Cowork Progress Tracker with TodoWrite Bridge
Tags: Introduced in Beta, Progress, Tracker, TodoWrite, Bridge, Workflow, Evidence, Handoff, Cowork
TL;DR
What It Does
Tracks multi-step CRAFT workflows visually using Cowork’s native TodoWrite widget for real-time progress display, while maintaining CRAFT’s structured workflow state for handoff serialization. Extends the Core Progress Tracker by bridging CRAFT progress semantics to Cowork’s built-in UI.
How It Works
The AI maintains a dual-layer tracking system: CRAFT workflow state (the source of truth) and TodoWrite widget (the visual rendering layer). When you initialize a workflow, the recipe creates both layers. As steps complete, both update in sync. The recipe requires evidence grounding for completion claims — at least one of: git commit hash, file diff, tool output, or user confirmation. Unverified claims are tagged and flagged during handoff creation.
What To Expect
A real-time progress widget showing your workflow steps with completion percentages. Step descriptions appear in imperative form (“Run tests”), and the active step shows present continuous (“Running tests”) in the spinner. When all steps complete, the recipe prompts for a summary or new workflow.
Best Results When You
Initialize workflows at the start of multi-step tasks with clear, concise step descriptions. Let auto mode detect progress from your conversation, or use explicit update mode when auto-detection misses a completion signal.
Typical Time
Under 1 minute per update. Initialization takes slightly longer depending on the number of steps.
Difficulty
Medium — you provide step lists and confirm completions. The AI handles state management, TodoWrite synchronization, evidence tracking, and handoff serialization.
How To Start
The progress tracker operates in five modes: initialize, update, auto, status, and sync. Most of the time, auto mode detects progress from your conversation automatically.
STEP 1Initialize or Interact with a Workflow
Tell the AI which workflow to track and what mode to use, or let auto mode handle it.
Available parameters
-
task_name
· string · required
Name of the workflow being tracked. -
mode
· string · optional · default: “auto”
Tracking mode. Options: “auto,” “status,” “initialize,” “update,” “sync.” -
steps_list
· list · optional
Step descriptions for a new workflow. Used with “initialize” mode. -
completed_step
· string · optional
Step to mark complete. Used with “update” mode.
Invocations
Initialize a Workflow
#H->AI::Directive: (Track progress for SP10 Recipe Build-Out — Cowork mode with mode=initialize, steps_list=[Read source, Author content, Evaluate, Build HTML, Review])
Mark a Step Complete
#H->AI::Directive: (Track progress for SP10 Recipe Build-Out — Cowork mode with mode=update, completed_step=Author content)
Check Status
#H->AI::Directive: (Track progress for SP10 Recipe Build-Out — Cowork mode with mode=status)
Usage Examples
Three scenarios — initializing a workflow, auto-detecting progress, and re-syncing after drift.
Example 1 · Initializing a recipe build workflow
User:
Track our progress on the CWK-010 recipe build.
AI:
Initializing workflow: CWK-010 Recipe Build. 5 steps created. TodoWrite widget active — real-time progress display.
Example 2 · Auto-detecting progress
User:
[completes authoring the content file]
AI:
Auto-detected progress — “Author content” marked complete. Evidence: file_diff (authored content file created). Progress: 40% — 2/5 steps complete.
Example 3 · Re-syncing after context compaction
User:
The progress widget seems off — can you re-sync it?
AI:
TodoWrite out of sync — re-syncing from CRAFT state. 3 of 5 steps confirmed complete. TodoWrite re-synced.
How AI Reads This Recipe
When this recipe is triggered, the AI maintains a dual-layer progress tracking system with evidence-grounded completion claims. The AI should:
- MAINTAIN two synchronized layers: CRAFT workflow state (source of truth, persisted via handoff) and TodoWrite widget (visual rendering layer). Map CRAFT states: pending to pending, active to in_progress, completed to completed, blocked to in_progress with a blocker note.
- IN INITIALIZE MODE: create a CRAFT state object with workflow name, steps, timestamps, and blockers. Emit a full TodoWrite list. Derive active forms from step descriptions (imperative to present continuous). Mark the first step as in_progress.
- IN UPDATE MODE: mark the specified step as completed. Require at least one evidence type: git commit hash, file diff, tool output, or user confirmation. Tag steps without evidence as UNVERIFIED. Advance to the next pending step. Update TodoWrite. Report completion percentage.
- IN AUTO MODE: scan the conversation for completion signals — “completed,” “finished,” successful tool executions, explicit confirmations, recipe completions. Update both layers for each detected completion.
- IN STATUS MODE: report workflow name, progress percentage, current step, blockers, and next step. Verify TodoWrite matches CRAFT state; if drift is detected, trigger sync mode.
- IN SYNC MODE: rebuild TodoWrite entirely from CRAFT state. Handles drift from manual edits or context compaction.
- FOR HANDOFF: serialize active workflow state including progress percentage, completed steps, current step, blockers, next action, and evidence summary. CWK-002 should warn if any steps are unverified.
CRAFT state is always the source of truth — never derive state from TodoWrite. If the TodoWrite tool is unavailable, fall back to Core text-based progress display. Evidence grounding is not optional — unverified claims must be tagged and flagged during handoff.
When to Use This Recipe
Use this recipe when you:
- Are running a multi-step CRAFT workflow and want visual progress tracking in the Cowork sidebar.
- Need evidence-grounded completion tracking that carries through to handoff creation.
- Want automatic progress detection from your conversation without manually marking each step.
- Need to recover from TodoWrite drift after context compaction.
Do not use this recipe when:
You have a single-step task that completes in one exchange. Progress tracking adds overhead without value for trivial tasks. Use this recipe when workflows have 3 or more steps and span multiple exchanges.
Recipe FAQ
Q.What is the relationship between CRAFT state and TodoWrite?
CRAFT state is the source of truth — it holds the canonical workflow data including evidence records and blocker information. TodoWrite is the visual rendering layer that displays progress in the Cowork sidebar. The recipe keeps them synchronized, but if they drift, CRAFT state wins.
Q.What evidence types are accepted for completion claims?
Four types: git commit hash (proving a change was committed), file diff (observable file change), tool output (tool execution confirming a result), or user confirmation (explicit “yes” from the user in chat). At least one is required. If none is available, the step is tagged UNVERIFIED.
Q.What happens to UNVERIFIED steps during handoff?
CWK-002 (handoff creation) checks the evidence summary. If any steps are unverified, the handoff includes them marked as UNVERIFIED with a warning note. This is not a blocking error — it flags claims that the next session should verify.
Q.How does active form derivation work?
The recipe converts imperative step descriptions to present continuous for the TodoWrite spinner: “Run tests” becomes “Running tests,” “Implement CWK-010” becomes “Implementing CWK-010,” “Push to GitHub” becomes “Pushing to GitHub.” The pattern: first word gets the -ing suffix, rest unchanged.
Q.What triggers sync mode?
Status mode automatically triggers sync if it detects that TodoWrite does not match CRAFT state. You can also trigger sync manually when the widget looks wrong — for example, after context compaction that lost the widget state.
Q.What if TodoWrite is unavailable?
The recipe falls back to Core text-based progress display. CRAFT state continues to track progress normally; only the visual rendering layer is affected.
Version History
Changes to this recipe over time. Most recent first.
v1.01a
2026-03-15
Added evidence grounding requirement for completion claims (R-9, QA Phase A). Four evidence types: git_commit, file_diff, tool_output, user_confirm. Steps without evidence are tagged UNVERIFIED and flagged during handoff. Added evidence_summary block to handoff serialization. Added sync mode for TodoWrite drift recovery.
v1.00a
2026-02-28
Initial release. Extends Core Progress Tracker with TodoWrite bridge: dual-layer tracking, five modes (initialize, update, auto, status, sync), active form derivation, handoff serialization for cross-session state persistence. TodoWrite fallback to text-based display when widget unavailable.
Get this recipe with CRAFT for Claude Cowork
Cowork recipes ship bundled with CRAFT for Claude Cowork — there’s no separate download. Clone the framework once, and your AI runs every recipe automatically when invoked.
Pull anytime to stay on the latest version — free to clone, no login or email required.
Then start your session
Once CRAFT is in your project folder, open a new Cowork session and ask Claude to initialize. For example:
You
Please initialize my CRAFT session.
Claude
CRAFT session ready. Your project is loaded, your persona is active, and your recipes are available. What would you like to work on?
Not familiar with Git? Download as a ZIP
No command line needed. Just download, move, and unzip:
- Open the CRAFT framework repo on GitHub.
- Click the green Code button, then choose Download ZIP.
- Move the downloaded ZIP into your Claude Cowork project folder.
- Unzip it: double-click on Mac, or right-click → Extract All on Windows.
