fix(templates): replace Claude-only TodoWrite instruction with a generic todo list

[clay-good]

Status: Ready for review. CI green on all platforms; CodeRabbit reviewed with no actionable comments. Full suite: 2,027 passed; the only local failures are the 17 known environment-only ZshInstaller tests (#1321, fixed separately in #1400).

What was wrong

The generated openspec-propose and openspec-ff-change skills (and their /opsx:propose / /opsx:ff commands) instructed agents to "Use the TodoWrite tool to track progress through the artifacts." TodoWrite is a Claude Code-specific tool — the same templates generate commands for every supported tool, so Codex, Cursor, Gemini, Copilot, and the rest were told to use a tool they don't have. Reported in #643 (and TodoWrite is one of the unsupported references reported for Codex in #1103); the maintainer note on #643 already pointed the way: "this instruction probably needs to be generic anyways."

How it was fixed

The instruction is now runtime-neutral:

-   Use the **TodoWrite tool** to track progress through the artifacts.
+   Use a todo list to track progress through the artifacts.

Applied to all 4 template sites (propose + ff-change, skill and command variants), with the static skills/ copies regenerated via npm run generate:skills and the golden hashes in skill-templates-parity.test.ts updated. Tools with a native todo mechanism (Claude Code) still use it; tools without one track progress however they normally would. No behavior, CLI, or schema changes.

Proof

End-to-end from the built CLI (init --tools claude,codex,cursor, plus a custom-profile run that installs the ff workflow), then inspecting every generated asset:

$ grep -rn "TodoWrite" <project>          # → no matches
$ grep -c "Use a todo list to track progress through the artifacts" ...
.claude/commands/opsx/ff.md:1
.claude/skills/openspec-ff-change/SKILL.md:1
.codex/skills/openspec-ff-change/SKILL.md:1
.cursor/commands/opsx-ff.md:1
.cursor/skills/openspec-ff-change/SKILL.md:1

(Same result for the propose assets across all three tools.)

• grep -rn "TodoWrite" src/ skills/ test/ docs/ → no matches after the change.
• test/core/templates/ (parity + skills.sh parity + generator guards): 20/20 pass.
• Full suite: 2,027 passed (only the pre-existing ZshInstaller tests fail on machines with a real Oh My Zsh install (17/50 failures) #1321 environment failures remain).

Notes

• Scoped strictly to what fast forward command instructs to use TodoWrite tool but claude no longer has it #643 reports. The AskUserQuestion references in the same templates are the subject of Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools #1103/fix(codex): rewrite unsupported tool references #1133 (Codex adapter-level rewriting) and are deliberately not touched here — no conflict with that PR, which doesn't modify these template files.

Fixes #643

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Updated workflow guidance to use a tool-neutral todo list for tracking progress.
  • Removed references to a Claude-specific task-tracking tool from proposal and fast-forward instructions.
• Documentation
  • Aligned generated skill and command instructions with the updated progress-tracking guidance.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 3a2a51e6-fab4-44c2-ba7b-a41cc8b1e223

📥 Commits

Reviewing files that changed from the base of the PR and between d7be4fa and 55ff3ca.

📒 Files selected for processing (6)

• .changeset/generic-todo-tracking.md
• skills/openspec-ff-change/SKILL.md
• skills/openspec-propose/SKILL.md
• src/core/templates/workflows/ff-change.ts
• src/core/templates/workflows/propose.ts
• test/core/templates/skill-templates-parity.test.ts

🚧 Files skipped from review as they are similar to previous changes (3)

• src/core/templates/workflows/propose.ts
• src/core/templates/workflows/ff-change.ts
• test/core/templates/skill-templates-parity.test.ts

---

📝 Walkthrough

Walkthrough

Propose and fast-forward workflow instructions now use generic todo lists instead of the Claude-specific TodoWrite tool. Corresponding generated skill content, parity hashes, and the package patch changeset were updated.

Changes

Runtime-neutral todo tracking

Layer / File(s)	Summary
Update propose and fast-forward instructions src/core/templates/workflows/*, skills/openspec-*-change/SKILL.md, skills/openspec-propose/SKILL.md	Replaces TodoWrite references with generic todo-list progress tracking in propose and fast-forward templates and skills.
Refresh parity checks and release metadata test/core/templates/skill-templates-parity.test.ts, .changeset/generic-todo-tracking.md	Updates template and generated-skill hash baselines and adds a patch changeset describing the wording changes.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• Fission-AI/OpenSpec#1368: Modifies the same workflow templates and parity hash baselines.

Suggested reviewers: tabishb, alfred-openspec

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main template change.
Linked Issues check	✅ Passed	The PR replaces the TodoWrite instruction with a generic todo-list instruction as required by issue #643.
Out of Scope Changes check	✅ Passed	The changes stay within the template, static skill copy, and hash update scope needed for the TodoWrite wording change.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/generic-todo-tracking

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[alfred-openspec]

All four generated workflow variants now use runtime-neutral todo guidance, the checked-in skills regenerate cleanly, and no TodoWrite references remain. Exact-head build, 20 template/parity tests, CodeRabbit, and the full cross-platform matrix passed.

[alfred-openspec]

The rebase preserves the runtime-neutral todo guidance across all four propose and fast-forward variants. Exact-head build, clean skill regeneration, a zero-result TodoWrite scan, 37 focused generation/parity tests, and the full CI/CodeQL matrix pass.